From 65bcda5b81e9c06b149b43ec8bf6088b9a804e84 Mon Sep 17 00:00:00 2001 From: Venkata Nainala Date: Wed, 15 Jul 2026 09:01:41 +0100 Subject: [PATCH 1/2] feat(docs): replace Swagger UI with Scalar API reference Migrate interactive API documentation to Scalar while keeping existing /latest/docs and /v1/docs URLs. Disable default Swagger/ReDoc routes on versioned mounts and remove fastapi-versioning noop doc handlers that blocked proper OpenAPI serving. --- README.md | 2 +- app/core/scalar_docs.py | 57 +++++++++++++++++++++++++++++++++++++++++ app/main.py | 4 +++ app/routers/predict.py | 8 +++--- requirements.txt | 1 + 5 files changed, 67 insertions(+), 5 deletions(-) create mode 100644 app/core/scalar_docs.py diff --git a/README.md b/README.md index 2bbe7e6..615cc91 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Key Features: ๐Ÿ”„ Format Conversion: Effortlessly convert NMR data between various file formats. ๐Ÿ”— Explore the documentation and get started: https://nfdi4chem.github.io/nmrkit -Swagger Endpoint - https://dev.nmrkit.nmrxiv.org/latest/docs +API Reference - https://dev.nmrkit.nmrxiv.org/latest/docs ๐Ÿ“ข Found a bug or have a feature request? We'd love to hear from you! Please open an issue: [https://github.com/NFDI4Chem/nmrkit/issues] Happy NMR exploring! ๐Ÿงช๐ŸŒŸ" diff --git a/app/core/scalar_docs.py b/app/core/scalar_docs.py new file mode 100644 index 0000000..a5c735f --- /dev/null +++ b/app/core/scalar_docs.py @@ -0,0 +1,57 @@ +from fastapi import FastAPI +from fastapi.routing import APIRoute +from scalar_fastapi import get_scalar_api_reference +from starlette.routing import Mount + + +def _remove_doc_routes(fastapi_app: FastAPI) -> None: + fastapi_app.router.routes = [ + route + for route in fastapi_app.router.routes + if not ( + isinstance(route, APIRoute) + and route.path in ("/docs", "/redoc") + ) + ] + fastapi_app.docs_url = None + fastapi_app.redoc_url = None + + +def _remove_versioning_noop_routes(parent_app: FastAPI) -> None: + parent_app.router.routes = [ + route + for route in parent_app.router.routes + if not ( + isinstance(route, APIRoute) + and route.path.endswith(("/docs", "/openapi.json")) + and route.endpoint.__name__ == "noop" + ) + ] + + +def _add_scalar_docs(fastapi_app: FastAPI, openapi_url: str, title: str) -> None: + _remove_doc_routes(fastapi_app) + + @fastapi_app.get("/docs", include_in_schema=False) + async def scalar_html(): + return get_scalar_api_reference( + openapi_url=openapi_url, + title=title, + ) + + +def configure_scalar_docs(parent_app: FastAPI) -> None: + """Replace default Swagger UI with Scalar on all versioned API mounts.""" + _remove_versioning_noop_routes(parent_app) + + for route in parent_app.routes: + if not isinstance(route, Mount) or not isinstance(route.app, FastAPI): + continue + + prefix = route.path.rstrip("/") + mounted_app = route.app + _add_scalar_docs( + mounted_app, + openapi_url=f"{prefix}/openapi.json", + title=mounted_app.title, + ) diff --git a/app/main.py b/app/main.py index b9fdb6f..56f7c32 100644 --- a/app/main.py +++ b/app/main.py @@ -9,6 +9,7 @@ from fastapi.middleware.cors import CORSMiddleware from app.core import config, tasks +from app.core.scalar_docs import configure_scalar_docs from prometheus_fastapi_instrumentator import Instrumentator from app.schemas import HealthCheck @@ -96,6 +97,8 @@ version_format="{major}", prefix_format="/v{major}", enable_latest=True, + docs_url=None, + redoc_url=None, description=DESCRIPTION, terms_of_service="https://nfdi4chem.github.io/nmrkit", contact={ @@ -109,6 +112,7 @@ }, openapi_tags=tags_metadata, ) +configure_scalar_docs(app) Instrumentator().instrument(app).expose(app) diff --git a/app/routers/predict.py b/app/routers/predict.py index cf7fa56..262da0d 100644 --- a/app/routers/predict.py +++ b/app/routers/predict.py @@ -483,7 +483,7 @@ def get_health() -> HealthCheck: "| **nmrshift** | proton, carbon | ~5-10s |\n" "| **nmrdb.org** | proton, carbon, cosy, hsqc, hmbc | ~30-60s |\n\n" "> **Note:** nmrdb.org predictions can take 30-60 seconds. " - "Consider using curl or Postman instead of the Swagger UI for long-running requests." + "Consider using curl or Postman instead of the API docs for long-running requests." ), response_description="Predicted spectra in NMRium-compatible JSON format", status_code=status.HTTP_200_OK, @@ -499,7 +499,7 @@ async def predict_from_structure(request: PredictRequest): """ ## Predict NMR spectra from a MOL string - **Note:** nmrdb.org predictions take 30-60s. Use curl/Postman, not Swagger. + **Note:** nmrdb.org predictions take 30-60s. Use curl/Postman, not the API docs. ### Engines @@ -564,7 +564,7 @@ async def predict_from_structure(request: PredictRequest): "| **nmrshift** | proton, carbon | ~5-10s |\n" "| **nmrdb.org** | proton, carbon, cosy, hsqc, hmbc | ~30-60s |\n\n" "> **Note:** nmrdb.org predictions can take 30-60 seconds. " - "Consider using curl or Postman instead of the Swagger UI for long-running requests." + "Consider using curl or Postman instead of the API docs for long-running requests." ), response_description="Predicted spectra in NMRium-compatible JSON format", status_code=status.HTTP_200_OK, @@ -597,7 +597,7 @@ async def predict_from_file( Upload a MOL file and pass engine options as a JSON string in the `request` field. - > **Note:** nmrdb.org predictions take 30-60s. Use curl/Postman, not Swagger. + > **Note:** nmrdb.org predictions take 30-60s. Use curl/Postman, not the API docs. ### nmrshift example `request` field ```json diff --git a/requirements.txt b/requirements.txt index 9e5b55e..12e8910 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,5 @@ fastapi +scalar-fastapi uvicorn pydantic rdkit-pypi>=2022.09.4 From 550b6025f9f6f8f2c841cd5ece903096064bb808 Mon Sep 17 00:00:00 2001 From: Venkata Nainala Date: Wed, 15 Jul 2026 10:22:55 +0100 Subject: [PATCH 2/2] docs: complete documentation update for #111 Migrate API docs to Scalar and fill in architecture, deployment, module, and service documentation covering nmr-cli and nmr-respredict. --- README.md | 2 +- app/main.py | 1 + docs/.vitepress/config.ts | 27 +++-- docs/src/deployment/docker.md | 94 ++++++++++++++-- docs/src/deployment/overview.md | 75 +++++++++++++ docs/src/development/installation.md | 20 +++- docs/src/getting-started/api-reference.md | 51 +++++++++ docs/src/getting-started/architecture.md | 86 ++++++++++++++- docs/src/getting-started/versions.md | 39 ++++++- docs/src/introduction.md | 45 ++++++-- docs/src/modules/chemistry.md | 59 ++++++++++ docs/src/modules/converter.md | 35 ++++++ docs/src/modules/prediction.md | 124 +++++++++++++++++++++- docs/src/modules/registration.md | 93 +++++++++++++++- docs/src/modules/search.md | 28 ++++- docs/src/modules/spectra.md | 119 ++++++++++++++++++++- docs/src/modules/training.md | 20 +++- docs/src/modules/validation.md | 18 +++- docs/src/services/nmr-cli.md | 69 ++++++++++++ docs/src/services/nmr-respredict.md | 47 ++++++++ 20 files changed, 1012 insertions(+), 40 deletions(-) create mode 100644 docs/src/deployment/overview.md create mode 100644 docs/src/getting-started/api-reference.md create mode 100644 docs/src/modules/chemistry.md create mode 100644 docs/src/modules/converter.md create mode 100644 docs/src/services/nmr-cli.md create mode 100644 docs/src/services/nmr-respredict.md diff --git a/README.md b/README.md index 615cc91..80a5b7a 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Key Features: ๐Ÿ”„ Format Conversion: Effortlessly convert NMR data between various file formats. ๐Ÿ”— Explore the documentation and get started: https://nfdi4chem.github.io/nmrkit -API Reference - https://dev.nmrkit.nmrxiv.org/latest/docs +API Reference (Scalar) - https://dev.nmrkit.nmrxiv.org/latest/docs ๐Ÿ“ข Found a bug or have a feature request? We'd love to hear from you! Please open an issue: [https://github.com/NFDI4Chem/nmrkit/issues] Happy NMR exploring! ๐Ÿงช๐ŸŒŸ" diff --git a/app/main.py b/app/main.py index 56f7c32..a1f3490 100644 --- a/app/main.py +++ b/app/main.py @@ -33,6 +33,7 @@ ### Links * [Documentation](https://nfdi4chem.github.io/nmrkit) +* [API Reference (Scalar)](https://dev.nmrkit.nmrxiv.org/latest/docs) * [Source Code](https://github.com/NFDI4Chem/nmrkit) """ diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index bc35ca0..a21d0c5 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -16,7 +16,8 @@ export default defineConfigWithTheme({ }, nav: [ { text: 'Home', link: '/nmrkit/introduction' }, - { text: 'API', link: 'https://dev.nmrkit.nmrxiv.org/latest/docs' }, + { text: 'API Reference', link: '/getting-started/api-reference' }, + { text: 'Scalar (dev)', link: 'https://dev.nmrkit.nmrxiv.org/latest/docs' }, { text: 'GitHub', link: 'https://github.com/NFDI4Chem/nmrkit' } ], sidebar: [ @@ -24,27 +25,37 @@ export default defineConfigWithTheme({ text: 'Getting Started', items: [ { text: 'Introduction', link: '/introduction' }, - { text: 'Versions', link: '/getting-started/versions' }, + { text: 'API Reference', link: '/getting-started/api-reference' }, { text: 'Architecture', link: '/getting-started/architecture' }, + { text: 'Versions', link: '/getting-started/versions' }, ] }, { text: 'Deployment', items: [ - //{ text: 'Public API', link: '/public-api' }, + { text: 'Overview', link: '/deployment/overview' }, { text: 'Docker', link: '/deployment/docker' }, { text: 'Cluster Deployment (K8S)', link: '/deployment/cluster-deployment' } ] }, + { + text: 'Services', + items: [ + { text: 'nmr-cli', link: '/services/nmr-cli' }, + { text: 'nmr-respredict', link: '/services/nmr-respredict' }, + ] + }, { text: 'Modules', items: [ - { text: 'Registration', link: '/modules/registration' }, - { text: 'Search', link: '/modules/search' }, - { text: 'Prediction', link: '/modules/prediction' }, + { text: 'Chemistry', link: '/modules/chemistry' }, { text: 'Spectra', link: '/modules/spectra' }, - { text: 'Training', link: '/modules/training' }, - { text: 'Validation', link: 'modules/validation' }, + { text: 'Converter', link: '/modules/converter' }, + { text: 'Prediction', link: '/modules/prediction' }, + { text: 'Registration', link: '/modules/registration' }, + { text: 'Search (planned)', link: '/modules/search' }, + { text: 'Training (planned)', link: '/modules/training' }, + { text: 'Validation (planned)', link: '/modules/validation' }, ] }, { diff --git a/docs/src/deployment/docker.md b/docs/src/deployment/docker.md index a826156..89b7d08 100644 --- a/docs/src/deployment/docker.md +++ b/docs/src/deployment/docker.md @@ -1,25 +1,99 @@ # Docker -NMRKit is containerized using Docker and is distributed publicly via the [Docker Hub](https://hub.docker.com/r/nfdi4chem/nmrkit), a cloud-based registry provided by Docker that allows developers to store, share, and distribute Docker images. -To use this image: +NMRKit is containerized using Docker and distributed via +[Docker Hub](https://hub.docker.com/r/nfdi4chem/nmrkit). -* Make sure you have [Docker](https://docs.docker.com/get-docker/) installed and configured on your target deployment environment. -* Pull the NMRKit image by providing the appropiate tag. +## Pull the image ```bash -docker pull nfdi4chem/nmrkit:[tag] +docker pull nfdi4chem/nmrkit:latest # production +docker pull nfdi4chem/nmrkit:dev-latest # development +``` + +## Docker Compose (recommended) + +The root `docker-compose.yml` starts the full stack: +```bash +cp env.template .env +docker compose up -d ``` -* NMRKit uses [rdkit-cartridge-debian](https://hub.docker.com/r/informaticsmatters/rdkit-cartridge-debian) Postgres. Run the below command to spin up the image. + +| Service | Container | Port | Purpose | +|---------|-----------|------|---------| +| `web` | `nmrkit-api` | 8080โ†’80 | FastAPI application | +| `nmr-load-save` | `nmr-converter` | โ€” | nmr-cli spectra parsing & prediction | +| `nmr-respredict` | `nmr-respredict` | โ€” | Residual NMR prediction (future) | +| `pgsql` | โ€” | 5433โ†’5432 | PostgreSQL + RDKit cartridge | +| `redis` | โ€” | 6380โ†’6379 | Cache | +| `minio` | โ€” | 9002, 8901 | Object storage | +| `prometheus` | `nmrkit_prometheus` | 9090 | Metrics | +| `grafana` | `nmrkit_grafana` | 3000 | Dashboards | + +Open http://localhost:8080/latest/docs for the Scalar API reference. + +### Volumes + +- `./app` is mounted into the API container for live code reload during development +- `/var/run/docker.sock` allows the API to `docker exec` into `nmr-converter` +- `shared-data` passes files between API, nmr-cli, and nmr-respredict containers + +## Standalone container + +For a minimal deployment with an external PostgreSQL instance: ```bash -docker run -d --name postgres -e POSTGRES_PASSWORD=password -e POSTGRES_USER=nmrkit -p 5432:5432 informaticsmatters/rdkit-cartridge-debian:latest +# Start PostgreSQL with RDKit cartridge +docker run -d --name postgres \ + -e POSTGRES_PASSWORD=password \ + -e POSTGRES_USER=nmrkit \ + -p 5432:5432 \ + informaticsmatters/rdkit-cartridge-debian:latest +# Start NMRKit API +docker run -d -p 8080:80 --name nmrkit \ + -e POSTGRES_PASSWORD=password \ + -e POSTGRES_USER=nmrkit \ + -e POSTGRES_SERVER=postgres \ + -e POSTGRES_DB=nmr_predict \ + --link postgres:postgres \ + nfdi4chem/nmrkit:latest ``` -* After the Postgres container is prepared to receive connections, initiate the NMRKit container by executing the following command and providing the Postgres credentials. +::: warning +Standalone mode does not include `nmr-converter`. Spectra parsing and prediction +endpoints require the nmr-cli container โ€” use Docker Compose instead. +::: + +## Server deployments (Traefik) + +For hosted dev/prod environments, use the ops compose files: ```bash -docker run -d -p 8080:80 --name nmrkit -e POSTGRES_PASSWORD=password -e POSTGRES_USER=nmrkit -e POSTGRES_SERVER=postgres -e POSTGRES_DB=nmr_predict nfdi4chem/nmrkit:[tag] +# Development +docker compose -f ops/docker-compose-dev.yml up -d + +# Production +docker compose -f ops/docker-compose-prod.yml up -d +``` + +These configurations use [Traefik](https://traefik.io/) as a reverse proxy: + +| Environment | Host | Image tag | +|-------------|------|-----------| +| Development | `dev.nmrkit.nmrxiv.org` | `nfdi4chem/nmrkit:dev-latest` | +| Production | `nmrkit.nmrxiv.org` | `nfdi4chem/nmrkit:latest` | + +## Health checks + +Docker Compose health checks hit the registration module: + +``` +GET http://localhost:80/latest/registration/health +``` + +## See also -``` \ No newline at end of file +- [Deployment Overview](./overview) โ€” all deployment options +- [nmr-cli service](../services/nmr-cli) โ€” companion container details +- [Local Installation](../development/installation) โ€” development setup diff --git a/docs/src/deployment/overview.md b/docs/src/deployment/overview.md new file mode 100644 index 0000000..b70a3a6 --- /dev/null +++ b/docs/src/deployment/overview.md @@ -0,0 +1,75 @@ +# Deployment Overview + +NMRKit supports three deployment modes: + +| Mode | Use case | Documentation | +|------|----------|---------------| +| **Docker Compose (local)** | Development and testing | [Local Installation](../development/installation#docker) | +| **Docker Compose (ops)** | Dev / prod servers with Traefik | [Docker](./docker) | +| **Kubernetes (Helm)** | Cluster deployments | [Cluster Deployment](./cluster-deployment) | + +## Public instances + +| Environment | API docs | Host | +|-------------|----------|------| +| Development | [dev.nmrkit.nmrxiv.org/latest/docs](https://dev.nmrkit.nmrxiv.org/latest/docs) | `dev.nmrkit.nmrxiv.org` | +| Production | [nmrkit.nmrxiv.org/latest/docs](https://nmrkit.nmrxiv.org/latest/docs) | `nmrkit.nmrxiv.org` | + +## Compose files + +| File | Purpose | +|------|---------| +| `docker-compose.yml` | Full local stack (API, nmr-cli, nmr-respredict, DB, Redis, MinIO, monitoring) | +| `ops/docker-compose-dev.yml` | Dev server with Traefik reverse proxy | +| `ops/docker-compose-prod.yml` | Production server with Traefik | + +## Required services + +At minimum, the following containers must be running for full API functionality: + +| Service | Required for | +|---------|-------------| +| `nmrkit-api` | All API endpoints | +| `nmr-converter` | Spectra, converter, and predict modules | +| `pgsql` | Registration module | +| `nmr-respredict` | Future respredict integration (optional today) | + +## Environment configuration + +Copy `env.template` to `.env` and set database credentials: + +```bash +cp env.template .env +``` + +| Variable | Description | +|----------|-------------| +| `POSTGRES_USER` | PostgreSQL username | +| `POSTGRES_PASSWORD` | PostgreSQL password | +| `POSTGRES_SERVER` | Database host (`pgsql` in Compose) | +| `POSTGRES_PORT` | Database port (default `5432`) | +| `POSTGRES_DB` | Database name (`nmr_predict`) | +| `MINIO_ROOT_USER` | MinIO access key | +| `MINIO_ROOT_PASSWORD` | MinIO secret key | + +## CI/CD + +Docker images are built and published via GitHub Actions: + +- `dev-build.yml` โ€” builds `nfdi4chem/nmrkit:dev-latest` on pushes to `development` +- `prod-build.yml` โ€” builds `nfdi4chem/nmrkit:latest` on releases +- `doc-deploy.yml` โ€” deploys this documentation site to GitHub Pages + +See [#95 โ€” Update CI/CD and deployment script](https://github.com/NFDI4Chem/nmrkit/issues/95) +for ongoing improvements to the deployment pipeline. + +## Quick start (local) + +```bash +git clone https://github.com/NFDI4Chem/nmrkit.git +cd nmrkit +cp env.template .env +docker compose up -d +``` + +API docs: http://localhost:8080/latest/docs diff --git a/docs/src/development/installation.md b/docs/src/development/installation.md index aa9c077..db64bc9 100644 --- a/docs/src/development/installation.md +++ b/docs/src/development/installation.md @@ -135,13 +135,27 @@ networks: name: nmrkit_vpc ``` -4. Run Docker Compose: Execute the command ```docker-compose up -d``` to start the containers defined in the Compose file. +4. Run Docker Compose: Execute the command `docker compose up -d` to start the containers. 5. Wait for the containers to start: Docker Compose will start the containers and display their logs in the terminal or command prompt. -Unicorn will start the app and display the server address (usually `http://localhost:80`) and Grafana dashboard can be accessed at `http://localhost:3000` +The API will be available at http://localhost:8080 and the Scalar API reference at http://localhost:8080/latest/docs. Grafana dashboard can be accessed at http://localhost:3000. -You may update the docker-compose file to disable or add additional services but by default, the docker-compose file shipped with the project has the web (nmrkit FAST API app), [rdkit-cartridge-debian](https://hub.docker.com/r/informaticsmatters/rdkit-cartridge-debian), [Prometheus](https://prometheus.io/img/introduction/overview/) and [Grafana](https://prometheus.io/img/introduction/overview/) (logging and visualisation of metrics), [Minio](https://min.io/img/minio/linux/index.html), [Redis](https://redis.io/img/) services. +### Services started by Docker Compose + +| Service | Container | Purpose | +|---------|-----------|---------| +| `web` | `nmrkit-api` | FastAPI application | +| `nmr-load-save` | `nmr-converter` | nmr-cli for spectra parsing and prediction | +| `nmr-respredict` | `nmr-respredict` | Residual NMR prediction (future integration) | +| `pgsql` | โ€” | PostgreSQL with RDKit cartridge | +| `redis` | โ€” | Cache | +| `minio` | โ€” | Object storage | +| `prometheus` / `grafana` | โ€” | Metrics and dashboards | + +Copy `env.template` to `.env` and adjust database credentials before starting. + +See the [Deployment Overview](/deployment/overview) and [nmr-cli service](/services/nmr-cli) documentation for details. ## Standalone diff --git a/docs/src/getting-started/api-reference.md b/docs/src/getting-started/api-reference.md new file mode 100644 index 0000000..8082873 --- /dev/null +++ b/docs/src/getting-started/api-reference.md @@ -0,0 +1,51 @@ +# API Reference + +NMRKit exposes an OpenAPI-documented REST API. Interactive documentation is +rendered with [Scalar](https://scalar.com/) (replacing the previous Swagger UI). + +## Endpoints + +| Environment | Scalar docs | OpenAPI JSON | +|-------------|-------------|--------------| +| Development | [dev.nmrkit.nmrxiv.org/latest/docs](https://dev.nmrkit.nmrxiv.org/latest/docs) | [/latest/openapi.json](https://dev.nmrkit.nmrxiv.org/latest/openapi.json) | +| Production | [nmrkit.nmrxiv.org/latest/docs](https://nmrkit.nmrxiv.org/latest/docs) | [/latest/openapi.json](https://nmrkit.nmrxiv.org/latest/openapi.json) | + +Versioned docs are also available at `/v1/docs` and `/v1/openapi.json`. + +## Using Scalar + +Scalar provides: + +- Browsable endpoint groups (chem, spectra, converter, predict, registration) +- Request/response schemas with examples +- A **Test Request** panel for trying endpoints directly in the browser + +### Tips for long-running requests + +Some endpoints can take 30โ€“60 seconds (notably `nmrdb.org` predictions and +large spectra parsing). For these, prefer `curl` or Postman over the browser UI: + +```bash +curl -X POST "https://dev.nmrkit.nmrxiv.org/latest/predict/" \ + -H "Content-Type: application/json" \ + -d '{ + "engine": "nmrshift", + "structure": "\n Mrv...\nM END", + "spectra": ["proton"], + "options": { "frequency": 400 } + }' +``` + +## Health checks + +| Endpoint | Purpose | +|----------|---------| +| `GET /health` | Global API health | +| `GET /latest/registration/health` | Used by Docker Compose health checks | + +## Further reading + +- [Architecture](./architecture) โ€” system components and data flow +- [Spectra module](../modules/spectra) โ€” parsing and conversion routines +- [Prediction module](../modules/prediction) โ€” prediction engines +- [nmr-cli service](../services/nmr-cli) โ€” underlying CLI tool diff --git a/docs/src/getting-started/architecture.md b/docs/src/getting-started/architecture.md index f2569bf..2040d1f 100644 --- a/docs/src/getting-started/architecture.md +++ b/docs/src/getting-started/architecture.md @@ -1 +1,85 @@ -# Architecture \ No newline at end of file +# Architecture + +NMRKit is a FastAPI application that exposes a versioned REST API for NMR data +processing, conversion, prediction, and molecule registration. Heavy lifting for +spectra parsing and prediction is delegated to companion Docker containers that +run the **nmr-cli** and **nmr-respredict** toolchains. + +## System overview + +```mermaid +flowchart TB + Client[Client / NMRium / nmrxiv] + API[NMRKit API
FastAPI] + CLI[nmr-cli container
nmr-converter] + RP[nmr-respredict container] + PG[(PostgreSQL
RDKit cartridge)] + Redis[(Redis)] + Minio[(MinIO)] + + Client -->|HTTP| API + API -->|docker exec| CLI + API -->|docker exec| RP + API --> PG + API --> Redis + API --> Minio +``` + +## Components + +| Component | Container name | Purpose | +|-----------|----------------|---------| +| **NMRKit API** | `nmrkit-api` | FastAPI gateway, versioning, health checks, Prometheus metrics | +| **nmr-cli** | `nmr-converter` | Parse spectra, convert formats, predict shifts via nmrdb.org / nmrshift | +| **nmr-respredict** | `nmr-respredict` | Residual-based NMR prediction (planned integration) | +| **PostgreSQL** | `pgsql` | Molecule registration (lwreg) and RDKit cartridge queries | +| **Redis** | `redis` | Caching and background task support | +| **MinIO** | `minio` | Object storage for uploaded files | +| **Prometheus** | `nmrkit_prometheus` | Metrics collection | +| **Grafana** | `nmrkit_grafana` | Metrics dashboards | + +## API modules + +All endpoints are mounted under a version prefix (for example `/latest/` or `/v1/`). + +| Module | Prefix | Description | +|--------|--------|-------------| +| **Chemistry** | `/chem` | HOSE code generation (CDK / RDKit) | +| **Spectra** | `/spectra` | Parse NMR data from files, URLs, publication strings, or peak lists | +| **Converter** | `/convert` | Convert raw NMR data to NMRium JSON | +| **Predict** | `/predict` | Predict NMR spectra from molecular structures | +| **Registration** | `/registration` | Register, query, and retrieve molecules via lwreg | + +See the [interactive API reference](https://dev.nmrkit.nmrxiv.org/latest/docs) (Scalar) +or the module pages in this documentation for endpoint details. + +## How nmr-cli is invoked + +The API container mounts the Docker socket and executes commands inside the +`nmr-converter` container: + +```bash +docker exec nmr-converter nmr-cli parse-spectra -u +docker exec nmr-converter nmr-cli predict -s "" --engine nmrshift ... +``` + +A shared volume (`/shared`) is used to pass files between containers when +uploading MOL files for prediction. + +## API versioning + +NMRKit uses [fastapi-versioning](https://github.com/one-thd/fastapi-versioning): + +- `/latest/` โ€” always points to the newest API version +- `/v1/` โ€” stable version 1 endpoints +- `/latest/openapi.json` โ€” OpenAPI schema used by Scalar + +## Interactive documentation + +API documentation is served by [Scalar](https://scalar.com/) at `/latest/docs` +and `/v1/docs`. The root URL (`/`) redirects to the docs by default. + +Public instances: + +- **Development:** https://dev.nmrkit.nmrxiv.org/latest/docs +- **Production:** https://nmrkit.nmrxiv.org/latest/docs diff --git a/docs/src/getting-started/versions.md b/docs/src/getting-started/versions.md index 465c8c7..22de0ba 100644 --- a/docs/src/getting-started/versions.md +++ b/docs/src/getting-started/versions.md @@ -1 +1,38 @@ -# Versions \ No newline at end of file +# Versions + +## API versioning + +NMRKit uses URL-based versioning via `fastapi-versioning`: + +| Prefix | Description | +|--------|-------------| +| `/latest/` | Alias for the current API version (recommended for development) | +| `/v1/` | Stable version 1 | + +All module paths are appended to the version prefix. For example: + +``` +GET /latest/chem/hosecode?smiles=CCO +POST /latest/spectra/parse/url +POST /latest/predict/ +``` + +## Docker image tags + +Images are published to [Docker Hub](https://hub.docker.com/r/nfdi4chem/nmrkit): + +| Tag | Environment | +|-----|-------------| +| `dev-latest` | Development deployments (`dev.nmrkit.nmrxiv.org`) | +| `latest` | Production deployments (`nmrkit.nmrxiv.org`) | + +Companion images: + +| Image | Dev tag | Prod tag | +|-------|---------|----------| +| `nfdi4chem/nmr-cli` | `dev-latest` | `latest` | +| `nfdi4chem/nmr-respredict` | `dev-latest` | `latest` | + +## Changelog + +Release history is tracked in the repository [CHANGELOG.md](https://github.com/NFDI4Chem/nmrkit/blob/main/CHANGELOG.md). diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 4ab3194..671022d 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,18 +1,43 @@ -# Welcome to NMRKit ๐Ÿš€ +# Welcome to NMRKit -NMRKit, features a collection of powerful microservices designed to simplify your NMR data processing and analysis. Whether you're a seasoned researcher or a curious chemist, our suite of tools offers NMR Prediction, Validation, and Depiction via the nmrium library, along with seamless Format Conversion using the nmr-load-save package. With our robust API, functionalities, and developer-friendly documentation, exploring and interpreting NMR spectra has never been easier. +NMRKit is a collection of microservices for NMR data processing, conversion, +prediction, and molecule registration. It provides a versioned REST API backed +by FastAPI, with interactive documentation powered by Scalar. -Key Features: +## Key capabilities -๐Ÿ”ฎ NMR Prediction: Obtain accurate NMR spectra predictions for your molecular structures. +| Capability | Module | Description | +|------------|--------|-------------| +| Spectra parsing | [Spectra](./modules/spectra) | Parse Bruker, JCAMP-DX, and zipped archives into NMRium JSON | +| Peak list conversion | [Spectra](./modules/spectra) | Generate spectra from peak lists or publication strings | +| Format conversion | [Converter](./modules/converter) | Convert raw NMR data to NMRium format | +| NMR prediction | [Prediction](./modules/prediction) | Predict spectra via nmrdb.org or nmrshift engines | +| HOSE codes | [Chemistry](./modules/chemistry) | Generate HOSE codes for shift prediction | +| Molecule registration | [Registration](./modules/registration) | Register and query molecules via lwreg | -๐Ÿ” Validation: Verify and ensure the quality and consistency of your experimental NMR data assignments. +## Services -๐Ÿ“Š Depiction via nmrium: Visualize NMR spectra and offer interactivity. +NMRKit runs as a Docker Compose stack. Besides the API itself, two companion +containers provide specialised NMR processing: -๐Ÿ”„ Format Conversion: Effortlessly convert NMR data between various file formats. +- **[nmr-cli](./services/nmr-cli)** โ€” spectra parsing, conversion, and prediction +- **[nmr-respredict](./services/nmr-respredict)** โ€” residual-based prediction (integration in progress) -๐Ÿ”— Explore the documentation and get started: https://nfdi4chem.github.io/nmrkit -๐Ÿ“ข Found a bug or have a feature request? We'd love to hear from you! Please open an issue: [https://github.com/NFDI4Chem/nmrkit/issues] +See [Architecture](./getting-started/architecture) for a full system diagram. -Happy NMR exploring! ๐Ÿงช๐ŸŒŸ" \ No newline at end of file +## Quick links + +- **Documentation:** https://nfdi4chem.github.io/nmrkit +- **API reference (dev):** https://dev.nmrkit.nmrxiv.org/latest/docs +- **API reference (prod):** https://nmrkit.nmrxiv.org/latest/docs +- **Source code:** https://github.com/NFDI4Chem/nmrkit +- **Issues:** https://github.com/NFDI4Chem/nmrkit/issues +- **Help desk:** https://helpdesk.nfdi4chem.de/ + +## Getting started + +1. [Local Installation](./development/installation) โ€” run NMRKit with Docker Compose +2. [API Reference](./getting-started/api-reference) โ€” explore endpoints with Scalar +3. [Deployment](./deployment/overview) โ€” deploy to dev, prod, or Kubernetes + +Found a bug or have a feature request? Please [open an issue](https://github.com/NFDI4Chem/nmrkit/issues). diff --git a/docs/src/modules/chemistry.md b/docs/src/modules/chemistry.md new file mode 100644 index 0000000..ffa0736 --- /dev/null +++ b/docs/src/modules/chemistry.md @@ -0,0 +1,59 @@ +# Chemistry Module + +The chemistry module provides cheminformatics utilities for NMR workflows, +including HOSE (Hierarchically Ordered Spherical Environment) code generation. + +**Base path:** `/latest/chem` + +## Endpoints + +### `GET /hosecode` + +Generate HOSE codes for every atom in a molecule. + +**Query parameters:** + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `smiles` | required | SMILES string (e.g. `CCCC1CC1`) | +| `framework` | `cdk` | `cdk` or `rdkit` | +| `spheres` | `3` | Number of bond spheres (1โ€“10) | +| `usestereo` | `false` | Include stereochemistry (CDK only) | + +**Response:** Array of HOSE code strings, one per atom. + +```bash +curl "https://dev.nmrkit.nmrxiv.org/latest/chem/hosecode?smiles=CCO&framework=cdk&spheres=3" +``` + +**Example response:** + +```json +[ + "C(CC,CC,&)", + "C(CC,C&,&)", + "C(CC,CC,&)" +] +``` + +## Frameworks + +| Framework | Library | Stereo support | +|-----------|---------|----------------| +| `cdk` | Chemistry Development Kit | Yes (`usestereo`) | +| `rdkit` | RDKit | No | + +HOSE codes encode the local chemical environment around each atom and are +widely used in NMR chemical shift prediction and database lookup. + +## Error codes + +| Status | Meaning | +|--------|---------| +| `409` | Molecule already exists (unique constraint) | +| `422` | Invalid SMILES or parse error | + +## See also + +- [Prediction module](./prediction) โ€” structure-based spectrum prediction +- [nmr-respredict service](../services/nmr-respredict) โ€” HOSE-based residual prediction diff --git a/docs/src/modules/converter.md b/docs/src/modules/converter.md new file mode 100644 index 0000000..cad0667 --- /dev/null +++ b/docs/src/modules/converter.md @@ -0,0 +1,35 @@ +# Converter Module + +The converter module provides a lightweight endpoint to convert NMR raw data from +a remote URL into [NMRium](https://www.nmrium.org/)-compatible JSON. + +**Base path:** `/latest/convert` + +::: info +For full parsing options (auto-processing, detection, snapshots), use the +[Spectra module](./spectra) instead. +::: + +## Endpoints + +### `GET /spectra` + +Fetch NMR data from a URL and convert it to NMRium JSON. + +**Query parameter:** `url` โ€” publicly accessible URL to NMR data + +```bash +curl "https://dev.nmrkit.nmrxiv.org/latest/convert/spectra?url=https://example.com/data.zip" +``` + +**Response:** NMRium-compatible JSON. + +## Supported formats + +Any format recognized by [nmr-load-save](https://github.com/cheminfo/nmr-load-save) +and **nmr-cli**, including Bruker archives and JCAMP-DX files. + +## See also + +- [Spectra module](./spectra) โ€” full parsing with processing options +- [nmr-cli service](../services/nmr-cli) diff --git a/docs/src/modules/prediction.md b/docs/src/modules/prediction.md index e45bec0..f4fdb47 100644 --- a/docs/src/modules/prediction.md +++ b/docs/src/modules/prediction.md @@ -1 +1,123 @@ -# Prediction Module \ No newline at end of file +# Prediction Module + +The prediction module generates NMR spectra from molecular structures. Predictions +are executed by **nmr-cli** inside the `nmr-converter` container using one of two +supported engines. + +**Base path:** `/latest/predict` + +## Engines + +| Engine | Spectra types | Typical time | Notes | +|--------|--------------|--------------|-------| +| `nmrshift` | proton, carbon | 5โ€“10 s | Fast, local shift prediction | +| `nmrdb.org` | proton, carbon, cosy, hsqc, hmbc | 30โ€“60 s | Remote API, supports 2D spectra | + +::: tip +Use `curl` or Postman for `nmrdb.org` requests โ€” browser-based Scalar tests may +time out on long predictions. +::: + +## Endpoints + +### `POST /` + +Predict spectra from a MOL block string. + +**Request body (nmrshift example):** + +```json +{ + "engine": "nmrshift", + "structure": "\n Mrv2311...\nM END", + "spectra": ["proton"], + "options": { + "solvent": "Chloroform-D1 (CDCl3)", + "frequency": 400, + "nbPoints": 1024, + "lineWidth": 1, + "peakShape": "lorentzian" + } +} +``` + +**Request body (nmrdb.org example):** + +```json +{ + "engine": "nmrdb.org", + "structure": "\n Mrv2311...\nM END", + "spectra": ["proton", "carbon"], + "options": { + "name": "Benzene", + "frequency": 400, + "1d": { + "proton": { "from": -1, "to": 12 }, + "carbon": { "from": -5, "to": 220 }, + "nbPoints": 131072, + "lineWidth": 1 + }, + "autoExtendRange": true + } +} +``` + +### `POST /file` + +Predict from an uploaded MOL file (`multipart/form-data`). + +| Form field | Description | +|------------|-------------| +| `file` | MOL file with molecular structure | +| `request` | JSON string with `engine`, `spectra`, and `options` (same schema as `POST /`) | + +## nmrshift options + +| Option | Default | Description | +|--------|---------|-------------| +| `solvent` | DMSO | NMR solvent (see API enum for full list) | +| `frequency` | 400 | Spectrometer frequency (MHz) | +| `from` / `to` | โ€” | Spectrum range in ppm | +| `nbPoints` | 1024 | Number of data points | +| `lineWidth` | 1 | Peak linewidth | +| `peakShape` | `lorentzian` | `gaussian` or `lorentzian` | +| `tolerance` | 0.001 | Peak grouping tolerance | + +## nmrdb.org options + +| Option | Default | Description | +|--------|---------|-------------| +| `name` | `""` | Compound name | +| `frequency` | 400 | Spectrometer frequency (MHz) | +| `1d.proton` | -1 to 12 ppm | 1H range | +| `1d.carbon` | -5 to 220 ppm | 13C range | +| `1d.nbPoints` | 131072 | 1D data points | +| `2d.nbPoints` | 1024ร—1024 | 2D data points | +| `autoExtendRange` | `true` | Extend range if signals fall outside | + +## Error codes + +| Status | Meaning | +|--------|---------| +| `408` | Prediction timed out (nmrdb.org: 300 s, nmrshift: 120 s) | +| `422` | Invalid structure or CLI error | +| `500` | Docker or container unavailable | + +## Example + +```bash +curl -X POST "https://dev.nmrkit.nmrxiv.org/latest/predict/" \ + -H "Content-Type: application/json" \ + -d '{ + "engine": "nmrshift", + "structure": "\n CDK 09012310592D\n\n 6 6 0 0 0 0 0 0 0 0999 V2000\n 0.0000 0.0000 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0\nM END", + "spectra": ["proton"], + "options": { "frequency": 400 } + }' +``` + +## See also + +- [nmr-cli service](../services/nmr-cli) +- [nmr-respredict service](../services/nmr-respredict) โ€” planned additional engine +- [Chemistry module](./chemistry) โ€” HOSE codes used in shift prediction diff --git a/docs/src/modules/registration.md b/docs/src/modules/registration.md index efdef7b..ecb354d 100644 --- a/docs/src/modules/registration.md +++ b/docs/src/modules/registration.md @@ -1 +1,92 @@ -# Registration Module \ No newline at end of file +# Registration Module + +The registration module provides molecule registration, lookup, and retrieval +using [lwreg](https://github.com/rdkit/lwreg) backed by PostgreSQL with the +RDKit cartridge. + +**Base path:** `/latest/registration` + +## Endpoints + +### `POST /init` + +Initialize (or re-initialize) the registration database. + +::: danger +This destroys all existing registration data. Set `confirm` to `true` to proceed. +::: + +```json +{ "confirm": true } +``` + +### `POST /register` + +Register one or more molecules. Send **plain text** (not JSON): + +**SMILES input** (one per line): + +``` +CCCC +CCCCO +c1ccccc1 +``` + +**SDF block** (with `$$$$` delimiters) is also accepted. + +**Response:** Array of registry numbers or status strings: + +```json +[1, "DUPLICATE", 3] +``` + +| Value | Meaning | +|-------|---------| +| integer | New molregno for a registered molecule | +| `"DUPLICATE"` | Molecule already exists | +| `"PARSE_FAILURE"` | Could not parse the structure | + +### `GET /query` + +Check if a molecule is registered. + +**Query parameter:** `smi` โ€” SMILES string + +**Response:** Array of matching molregnos (empty if not found). + +```bash +curl "https://dev.nmrkit.nmrxiv.org/latest/registration/query?smi=CCO" +``` + +### `POST /retrieve` + +Retrieve molecules by registry ID. + +**Request body:** + +```json +[1, 2, 3] +``` + +**Response:** Array of `[molregno, data, format]` tuples. + +### `GET /health` + +Health check used by Docker Compose deployments. + +## Configuration + +Registration requires PostgreSQL environment variables (see +[Local Installation](../development/installation#docker)): + +| Variable | Description | +|----------|-------------| +| `POSTGRES_USER` | Database user | +| `POSTGRES_PASSWORD` | Database password | +| `POSTGRES_SERVER` | Hostname (`pgsql` in Docker Compose) | +| `POSTGRES_DB` | Database name (default: `nmr_predict`) | +| `STANDARDIZATION` | lwreg standardization mode (default: `tautomer`) | + +## See also + +- [Architecture](../getting-started/architecture) โ€” PostgreSQL component diff --git a/docs/src/modules/search.md b/docs/src/modules/search.md index 504c8f8..9737fbb 100644 --- a/docs/src/modules/search.md +++ b/docs/src/modules/search.md @@ -1 +1,27 @@ -# Search Module \ No newline at end of file +# Search Module + +::: warning Planned feature +The search module is not yet exposed via the REST API. This page describes the +planned functionality tracked in +[#66 โ€” Expose correlation package functionality](https://github.com/NFDI4Chem/nmrkit/issues/66). +::: + +## Planned scope + +Expose [nmr-correlation](https://github.com/cheminfo/nmr-correlation) as a +standalone routine: + +**Input:** + +- URL to a spectra ZIP archive +- Molecular formula +- Optional C/H tolerance overrides + +**Output:** + +- Correlation object linking experimental peaks to predicted assignments + +## Current workaround + +Use the [Spectra](./spectra) and [Prediction](./prediction) modules separately, +then correlate results in your client application. diff --git a/docs/src/modules/spectra.md b/docs/src/modules/spectra.md index 3979fb2..1e5201f 100644 --- a/docs/src/modules/spectra.md +++ b/docs/src/modules/spectra.md @@ -1 +1,118 @@ -# Spectra Module \ No newline at end of file +# Spectra Module + +The spectra module parses experimental NMR data into +[NMRium](https://www.nmrium.org/)-compatible JSON. All operations delegate to +the **nmr-cli** `parse-spectra` toolchain running in the `nmr-converter` +container. + +**Base path:** `/latest/spectra` + +## Endpoints + +### `POST /parse/url` + +Parse spectra from a remote URL. + +**Request body (JSON):** + +```json +{ + "url": "https://example.com/spectra/sample.zip", + "capture_snapshot": false, + "auto_processing": true, + "auto_detection": true, + "raw_data": false +} +``` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `url` | URL | required | Link to NMR data (JCAMP-DX, Bruker zip, etc.) | +| `capture_snapshot` | bool | `false` | Generate a PNG snapshot of the spectrum | +| `auto_processing` | bool | `false` | Process FID โ†’ FT spectra automatically | +| `auto_detection` | bool | `false` | Detect ranges and zones automatically | +| `raw_data` | bool | `false` | Embed raw data in the output | + +**Response:** NMRium-compatible JSON (`application/json`). + +### `POST /parse/file` + +Parse an uploaded spectra file (`multipart/form-data`). + +| Form field | Type | Default | Description | +|------------|------|---------|-------------| +| `file` | file | required | JCAMP-DX, Bruker zip, or other supported format | +| `capture_snapshot` | bool | `false` | Generate snapshot image | +| `auto_processing` | bool | `false` | FID โ†’ FT processing | +| `auto_detection` | bool | `false` | Range/zone detection | +| `raw_data` | bool | `false` | Include raw data | + +### `POST /parse/publication-string` + +Reconstruct a spectrum from an ACS-style NMR publication string. Send the string +as **plain text** (not JSON). + +**Example body:** + +``` +1H NMR (400 MHz, CDCl3) ฮด 7.26 (s, 1H), 2.10 (s, 3H) +``` + +### `POST /parse/peaks` + +Convert a peak list into a simulated 1D spectrum. + +**Request body (JSON):** + +```json +{ + "peaks": [ + { "x": 7.26, "y": 1, "width": 1 }, + { "x": 2.10, "y": 1, "width": 1 } + ], + "options": { + "nucleus": "1H", + "frequency": 400, + "nbPoints": 131072, + "from": 0, + "to": 12 + } +} +``` + +| Peak field | Required | Description | +|------------|----------|-------------| +| `x` | yes | Chemical shift (ppm) | +| `y` | no | Intensity (default `1.0`) | +| `width` | no | Peak width in Hz (default `1.0`) | + +## Supported input formats + +- JCAMP-DX (`.jdx`, `.dx`) +- Bruker directories (zipped) +- Other formats supported by [nmr-load-save](https://github.com/cheminfo/nmr-load-save) + +## Error codes + +| Status | Meaning | +|--------|---------| +| `408` | Processing exceeded 120 s timeout | +| `422` | Parse error or invalid input | +| `500` | Docker or `nmr-converter` container unavailable | + +## Example + +```bash +curl -X POST "https://dev.nmrkit.nmrxiv.org/latest/spectra/parse/url" \ + -H "Content-Type: application/json" \ + -d '{ + "url": "https://cheminfo.github.io/bruker-data-test/data/zipped/aspirin-1h.zip", + "auto_processing": true + }' \ + -o spectrum.json +``` + +## See also + +- [nmr-cli service](../services/nmr-cli) +- [Converter module](./converter) โ€” legacy URL conversion endpoint diff --git a/docs/src/modules/training.md b/docs/src/modules/training.md index 147f419..20fa1f9 100644 --- a/docs/src/modules/training.md +++ b/docs/src/modules/training.md @@ -1 +1,19 @@ -# Training Module \ No newline at end of file +# Training Module + +::: warning Planned feature +The training module is not yet exposed via the REST API. Model training +capabilities are tracked in +[#13 โ€” Add training model](https://github.com/NFDI4Chem/nmrkit/issues/13). +::: + +## Planned scope + +- Train prediction models on spectral database tables +- Store trained models in a configurable location +- Benchmarking routines with cross-validation + +## Related modules + +- [Prediction](./prediction) โ€” current inference engines +- [Chemistry](./chemistry) โ€” HOSE code generation for feature extraction +- [nmr-respredict service](../services/nmr-respredict) โ€” residual prediction backend diff --git a/docs/src/modules/validation.md b/docs/src/modules/validation.md index 14b835f..6a83869 100644 --- a/docs/src/modules/validation.md +++ b/docs/src/modules/validation.md @@ -1 +1,17 @@ -# Validation Module \ No newline at end of file +# Validation Module + +::: warning Planned feature +The validation module is not yet exposed via the REST API. Spectral assignment +validation is tracked in +[#15 โ€” Validation module](https://github.com/NFDI4Chem/nmrkit/issues/15). +::: + +## Planned scope + +Implement validation scores for spectral assignments, verifying the quality and +consistency of experimental NMR data against predicted or reference values. + +## Related modules + +- [Prediction](./prediction) โ€” generate reference spectra for comparison +- [Spectra](./spectra) โ€” parse experimental data for validation input diff --git a/docs/src/services/nmr-cli.md b/docs/src/services/nmr-cli.md new file mode 100644 index 0000000..a662130 --- /dev/null +++ b/docs/src/services/nmr-cli.md @@ -0,0 +1,69 @@ +# nmr-cli Service + +The **nmr-cli** container (`nmr-converter`) packages the +[nmr-load-save](https://github.com/cheminfo/nmr-load-save) toolchain and related +NMR processing utilities. NMRKit invokes it via `docker exec` for spectra +parsing, format conversion, and structure-based prediction. + +## Docker image + +| Registry | Image | Tags | +|----------|-------|------| +| Docker Hub | `nfdi4chem/nmr-cli` | `dev-latest`, `latest` | + +In `docker-compose.yml` the service is named `nmr-load-save` with container +name `nmr-converter`. + +## Commands used by NMRKit + +| nmr-cli command | API endpoint | Description | +|-----------------|--------------|-------------| +| `parse-spectra` | `POST /spectra/parse/url`, `POST /spectra/parse/file` | Parse Bruker, JCAMP-DX, zipped archives into NMRium JSON | +| `parse-publication-string` | `POST /spectra/parse/publication-string` | Reconstruct spectrum from ACS publication string | +| `peaks-to-nmrium` | `POST /spectra/parse/peaks` | Generate spectrum from a peak list | +| `predict` | `POST /predict/`, `POST /predict/file` | Predict spectra via nmrdb.org or nmrshift | +| `-u ` | `GET /convert/spectra` | Legacy URL-based conversion | + +### parse-spectra flags + +| Flag | API parameter | Description | +|------|---------------|-------------| +| `-u` | `url` | Remote URL to spectra file | +| `-p` | `file` / `auto_processing` | File path or enable FID โ†’ FT processing | +| `-s` | `capture_snapshot` | Capture spectra image snapshot | +| `-d` | `auto_detection` | Automatic range/zone detection | +| `-r` | `raw_data` | Include raw data in output | + +## Manual testing + +Build and run the container locally: + +```bash +docker pull nfdi4chem/nmr-cli:dev-latest +docker run -it --name nmr-converter nfdi4chem/nmr-cli:dev-latest bash +``` + +Inside the container: + +```bash +nmr-cli parse-spectra -u https://cheminfo.github.io/bruker-data-test/data/zipped/aspirin-1h.zip +nmr-cli predict -s "" --engine nmrshift --spectra proton +``` + +## Shared volume + +The `/shared` volume is mounted in both `nmrkit-api` and `nmr-converter` so +uploaded MOL files can be passed to `nmr-cli predict` without `docker cp`. + +## Timeouts + +| Operation | Timeout | +|-----------|---------| +| Spectra parsing | 120 s | +| nmrshift prediction | 120 s | +| nmrdb.org prediction | 300 s | + +## Related issues + +- [#56](https://github.com/NFDI4Chem/nmrkit/issues/56) โ€” NodeJS Docker image with nmr-load-save +- [#57](https://github.com/NFDI4Chem/nmrkit/issues/57) โ€” Docker connection between nmrkit and nmr-load-save diff --git a/docs/src/services/nmr-respredict.md b/docs/src/services/nmr-respredict.md new file mode 100644 index 0000000..2d00edc --- /dev/null +++ b/docs/src/services/nmr-respredict.md @@ -0,0 +1,47 @@ +# nmr-respredict Service + +The **nmr-respredict** container provides residual-based NMR chemical shift +prediction. It is distributed as a separate Docker image and is included in the +NMRKit Docker Compose stack for future integration. + +## Docker image + +| Registry | Image | Tags | +|----------|-------|------| +| Docker Hub | `nfdi4chem/nmr-respredict` | `dev-latest`, `latest` | + +Source: [stefhk3/nmr-respredict-docker](https://github.com/stefhk3/nmr-respredict-docker) + +## Role in NMRKit + +In the current deployment, `nmr-respredict` runs alongside the API and shares +the `/shared` volume. The FastAPI application does not yet expose a dedicated +REST endpoint for this engine โ€” prediction is currently routed through +**nmr-cli** using the `nmrdb.org` and `nmrshift` engines. + +Planned integration is tracked in +[#62 โ€” Integrate nmr-respredict Docker image](https://github.com/NFDI4Chem/nmrkit/issues/62). + +## Compose configuration + +```yaml +nmr-respredict: + image: nfdi4chem/nmr-respredict:dev-latest + container_name: nmr-respredict + entrypoint: /bin/sh + stdin_open: true + tty: true + volumes: + - shared-data:/shared +``` + +## Requirements + +- The container must be running for future respredict endpoints to work +- MOL/SDF structure files are passed via the shared volume at `/shared` +- PostgreSQL with RDKit cartridge is required for HOSE-code-based lookup + +## Related documentation + +- [Prediction module](../modules/prediction) โ€” currently available engines +- [Architecture](../getting-started/architecture) โ€” system overview