# OpenMed > Local-first OpenMed documentation for clinical NLP, de-identification, model discovery, and on-device or self-hosted healthcare workflows. OpenMed is a local-first healthcare NLP toolkit for clinical entity extraction, de-identification, model discovery, and on-device or self-hosted integrations. # Getting started # OpenMed Documentation OpenMed bundles curated biomedical models, advanced de-identification, multimodal intake, structured health-data utilities, and one-call orchestration so you can ship clinical NLP workflows without wrangling infrastructure. This documentation keeps copied snippets and workflows close at hand: each section is Markdown-first, searchable, and optimized for quick scanning or copy/paste into notebooks. The OpenMed `3.2.0` candidate adds multilingual privacy patterns, native calendars and surrogates, synthetic clinical dataset tooling, and optional local GLiFormer, GLiNER2.5, GLiClass and decision-server backends. These new runtime and data-generation capabilities are primarily Python APIs; existing Swift, Kotlin/Android, JavaScript and service contracts retain their documented platform coverage. Review the [3.1-to-3.2 migration guide](https://openmed.life/docs/migration/3.1-to-3.2/index.md) for the Python 3.11 minimum, rendering requirements and decision schema compatibility. Low-resource cohort languages remain experimental until their independent review and graduation gates pass. New-model training and checkpoint publication are optional research, not feature or SDK-release prerequisites. The candidate combines policy-aware de-identification, expanded clinical and structured-data workflows, broad multilingual PII coverage, and fail-closed release evidence: - **Policy-aware de-identification** with signed audit reports, reproducibility hashes, review bundles, redaction previews, and release gates. - **Multimodal and structured inputs** across OCR, images, PDFs, DOCX, email, EPUB, vCard/iCalendar, DICOM, CSV/TSV, JSONL chat logs, HL7 v2, CDA/C-CDA, FHIR operations, and FHIR Bulk NDJSON. - **Python, Swift, Kotlin/Android, REST, gRPC, React Native, TypeScript, and browser paths** including OpenMedKit, typed REST clients, ONNX/WebGPU, and Transformers.js export bundles. - **42 supported PII language codes: am, ar, as, bn, cs, da, de, el, en, es, fa, fr, gu, he, hi, id, it, ja, kn, ko, ml, mr, nl, no, or, pa, pl, pt, ro, ru, sv, sw, ta, te, th, tr, uk, ur, vi, xh, zh, and zu**, with Russian using a documented multilingual default-model placeholder and Bengali, Chinese, and Tamil using dedicated registry entries, plus locale-aware validation and surrogate generation. A user-configured Indic NER adapter can also serve Assamese, Bengali, Gujarati, Hindi, Kannada, Malayalam, Marathi, Odia, Punjabi, Tamil, and Telugu. Additional validator-backed national-ID coverage remains available for ID-only locales. - **Release evidence** for leakage heatmaps, model scorecards, threshold sweeps, k-anonymity/l-diversity/t-closeness, utility loss, SBOMs, signed images, SLSA provenance, secret scanning, and reproducible dependency locks. ## What you get - **Curated registries** – discoverable Hugging Face models with metadata (domain, size, device guidance). - **One-line orchestration** – `analyze_text` wraps validation, inference, and formatting for scripts, notebooks, or services. - **PII detection & de-identification** – HIPAA-aware smart entity merging, policy profiles, signed audit reports, and deployment-oriented de-identification workflows. - **Apple Silicon and mobile acceleration** – MLX-backed Python inference plus Swift-native and Android/Kotlin app integration through OpenMedKit. - **REST service** – FastAPI endpoints for `/livez`, `/readyz`, `/analyze`, `/pii/extract`, `/pii/deidentify`, warm pools, batching, metrics, and typed Python/TypeScript clients. - **Browser and React Native export** – ONNX/WebGPU bundles for Transformers.js token classification in browser runtimes plus a React Native bridge for mobile apps. - **Advanced NER post-processing** – score-aware grouping, PHI-friendly filtering, and CSV/JSON/HTML export helpers. - **Composable config** – `OpenMedConfig` reads YAML/ENV so deployments stay reproducible across laptops and clusters. Copy-friendly defaults Every page in this site exposes code fences with copy buttons and callouts so teammates (or AI copilots) can lift the exact snippet they need. Use the search shortcut (`/` or `cmd/ctrl + K`) to jump straight to an entity, API call, or API surface. LLM-ready documentation Use the curated [llms.txt](https://openmed.life/docs/llms.txt) index to discover the quickstarts, APIs, and agent tool surfaces, or load [llms-full.txt](https://openmed.life/docs/llms-full.txt) when you need their full rendered content in one file. Both feeds are regenerated by the documentation build. ## First look ```python from openmed import analyze_text result = analyze_text( "Patient started on imatinib for chronic myeloid leukemia.", model_name="disease_detection_superclinical", confidence_threshold=0.55, ) for entity in result.entities: print(entity.label, entity.text, entity.confidence) ``` ```bash uv pip install "openmed[hf]" uv run python examples/pii_model_comparison.py ``` The rest of the docs expand on this snippet—head to **Quick Start** for the end-to-end setup, then explore the guides for configuration, zero-shot GLiNER workflows, and advanced processing helpers. ## Latest release highlights - [OpenMed 3.2.0 Release Notes](https://openmed.life/docs/release/v3.2.0/index.md) – candidate scope, intended post-publication coordinates and validation requirements. See the [feature map](https://openmed.life/docs/feature-map/index.md) for capability and platform coverage. - [OpenMed 3.2.0 Migration Guide](https://openmed.life/docs/migration/3.1-to-3.2/index.md) – interpreter requirements, rendering changes and retained decision contracts. - [OpenMed 2.5.0 Release Notes](https://openmed.life/docs/release/v2.5.0/index.md) – historical coverage and installation coordinates for the previous stable release. - [OpenMed 2.0.0 Release Notes](https://openmed.life/docs/release/v2.0.0/index.md) – historical major-version contract and v2 baseline. - [OpenMed 1.9.1 Release Notes](https://openmed.life/docs/release/v1.9.1/index.md) – historical Swift packaging, Android release hardening, and dependency-security fixes for the final 1.9 patch. - [OpenMed 1.8.0 Release Notes](https://openmed.life/docs/release/v1.8.0/index.md) – historical cross-platform runtime and service release inventory. - [OpenMed v1.6-v1.7 Feature Coverage](https://openmed.life/docs/release/v1.6-v1.7-feature-coverage/index.md) – historical coverage checklist across examples, docs, website, and source modules. - [Examples & Copy/Paste Recipes](https://openmed.life/docs/examples/index.md) – release-friendly snippets for Python, PII, batch jobs, Apple runtimes, browser export, multimodal inputs, and FHIR/HL7. - [ONNX and WebGPU Export](https://openmed.life/docs/export-onnx-webgpu/index.md) – export, manifest, runtime-loading, and publication guidance for ONNX browser artifacts. - [Transformers.js Export](https://openmed.life/docs/export-transformersjs/index.md) – browser/WebGPU packaging for token classification bundles. - [FHIR Interop Helpers](https://openmed.life/docs/fhir-interop/index.md), [FHIR-to-OMOP round-trip conformance](https://openmed.life/docs/interop/fhir-omop-matrix/index.md), [HL7 v2 De-identification](https://openmed.life/docs/hl7v2-deidentification/index.md), and [OMOP/lakehouse integrations](https://openmed.life/docs/integrations/lakehouse-redaction/index.md) – structured health-data workflows. - [MLX Backend](https://openmed.life/docs/mlx-backend/index.md), [OpenMedKit](https://openmed.life/docs/swift-openmedkit/index.md), [Android Span Parity](https://openmed.life/docs/android-parity/index.md), and [CoreML Packaging](https://openmed.life/docs/coreml-export/index.md) – local mobile/runtime paths. ## How these docs are structured 1. [Quick Start](https://openmed.life/docs/getting-started/index.md) – fastest path to a working environment plus a copy/paste script. 1. [Feature Map](https://openmed.life/docs/feature-map/index.md) – see how every capability maps back to the code. 1. [OpenMed 3.2.0 Migration Guide](https://openmed.life/docs/migration/3.1-to-3.2/index.md) – review contract changes and validation requirements before upgrading. 1. Core guides: - [Analyze Text Helper](https://openmed.life/docs/analyze-text/index.md) for single-call inference. - [REST Service (MVP)](https://openmed.life/docs/rest-service/index.md) for Dockerized HTTP endpoints. - [PII Detection & Smart Merging](https://openmed.life/docs/pii-smart-merging/index.md) for PHI de-identification workflows (v0.5.0). - [Batch Processing](https://openmed.life/docs/batch-processing/index.md) for multi-text/file processing. - [ModelLoader & Pipelines](https://openmed.life/docs/model-loader/index.md) for long-running jobs. - [Model Registry](https://openmed.life/docs/model-registry/index.md) to pick the right checkpoint. - [Configuration Profiles](https://openmed.life/docs/profiles/index.md) for dev/prod/test switching. - [Advanced NER & Output Formatting](https://openmed.life/docs/output-formatting/index.md) to polish spans. - [Medical-Aware Tokenizer](https://openmed.life/docs/medical-tokenizer/index.md) for better clinical token boundaries. - [Configuration & Validation](https://openmed.life/docs/configuration/index.md) to keep deployments reproducible. - [Zero-shot Toolkit](https://openmed.life/docs/zero-shot-ner/index.md) when you need GLiNER workflows. - [Performance Profiling](https://openmed.life/docs/profiling/index.md) for timing and optimization. - [Examples](https://openmed.life/docs/examples/index.md) and [Testing & QA](https://openmed.life/docs/testing/index.md) for day-to-day operations. 1. Project operations: - [Contributing & Releases](https://openmed.life/docs/contributing/index.md) – how we cut releases, publish docs, and keep CI green. - [Release Streams & Channels](https://openmed.life/docs/release/semver-and-channels/index.md) – model artifact and library release policy. - [Generative Model Policy](https://openmed.life/docs/generative-model-policy/index.md) – approved and prohibited model-assisted workflows. Need something that is not here yet? Drop an issue on GitHub and mention the missing recipe. Every addition is just a Markdown file away. # Quick Start This guide gets you from a blank workstation to copying results from the docs within minutes. It uses [uv](https://github.com/astral-sh/uv) for dependency management, but any Python 3.11+ environment works. Working with intermittent connectivity, offline clinics, OpenMRS, or DHIS2? Use the [African developer onboarding guide](https://openmed.life/docs/africa-onboarding/index.md) for a low-bandwidth model setup, local-only inference, privacy-profile pointers, and FHIR-based integration recipes. ## 1. Bootstrap the environment ```bash curl -LsSf https://astral.sh/uv/install.sh | sh # install uv (skip if already installed) uv venv --python 3.11 # create a dedicated virtualenv source .venv/bin/activate # or use `uv python` directly # install OpenMed with Hugging Face extras and doc tooling uv pip install ".[hf]" ``` ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" uv venv --python 3.11 .venv\Scripts\Activate.ps1 # install OpenMed with Hugging Face extras and doc tooling uv pip install ".[hf]" ``` Need the zero-shot GLiNER stack or dev tools? Stack extras as needed: ```bash uv pip install ".[hf,gliner]" # add GLiNER + transformers uv pip install ".[dev]" # pytest + coverage + linting ``` Installing behind an institutional proxy or package mirror, or preparing for a metered/offline deployment? Follow the [low-bandwidth, mirror, and proxy installation guide](https://openmed.life/docs/low-bandwidth-install/index.md) to configure pip, `HF_ENDPOINT`, the shared model cache, and diagnostics. For scanned images and document OCR, install the multimodal extra plus the system Tesseract binary: ```bash uv pip install ".[multimodal]" brew install tesseract # macOS sudo apt-get install tesseract-ocr # Debian/Ubuntu ``` PaddleOCR is available as a heavier opt-in OCR backend: ```bash uv pip install ".[ocr-paddle]" ``` CDA/C-CDA XML de-identification is available in the core install. It redacts structured header PHI, sweeps CDA section narrative text, keeps XML parseable, and only routes `.xml` files that look like CDA documents: ```python from openmed.interop.cda import redact_cda redacted_xml = redact_cda("synthetic_ccda.xml", date_shift_days=30) ``` C-CDA default header rules cover patient, guardian, next-of-kin and informant names/addresses/telecom values, plus birthplace addresses. Those known values also seed the narrative surface sweep. Pass `coverage_report={}` to `redact_cda` to collect `unmapped_elements` (controlled element paths and counts) and `unmapped_counts` for person names, addresses and telecoms. Reports never include values, attributes or custom element names. Unmapped structures still require local profile review; these defaults are not a guarantee of complete de-identification or a conformance validation. The optional inventory refuses documents deeper than 64 levels or containing more than 10,000 elements with `CDA coverage limit exceeded`, before updating the output mapping. This bounds controlled paths and avoids partial reports. To measure residual PHI against seeded C-CDA documents with element-level truth, see [Synthetic C-CDA documents](https://openmed.life/docs/training/synthetic/cda-documents/index.md). On an Apple Silicon Mac, you can start directly on the new MLX path: ```bash uv pip install ".[mlx]" # Python MLX runtime + tokenizer/artifact deps uv run python -c "from openmed.core.backends import get_backend; print(type(get_backend()).__name__)" ``` If you want the full launch surface on one machine, combine them: ```bash uv pip install ".[hf,mlx,docs]" ``` ## 2. Run `analyze_text` ```python from openmed import analyze_text text = "Metastatic breast cancer treated with paclitaxel and trastuzumab." resp = analyze_text(text, model_name="disease_detection_superclinical") print(resp.entities[0]) # Want ready-to-embed HTML instead? Ask for the "html" output format: html = analyze_text(text, model_name="disease_detection_superclinical", output_format="html") print(html) # ready for dashboards or docs ``` Prefer a quick script entrypoint? Run a one-file smoke script: ```bash uv run python examples/pii_model_comparison.py ``` ## 3. De-identify PII ```python from openmed import deidentify result = deidentify("Patient John Doe, DOB 01/15/1970", method="mask") print(result.deidentified_text) # Patient [first_name] [last_name], DOB [date] ``` `deidentify()` supports five methods (`mask`, `remove`, `replace`, `hash`, `shift_dates`) — see the [Anonymization quickstart](https://openmed.life/docs/anonymization/#quickstart-choosing-a-method) for a runnable example of each, plus how to reverse one with `reidentify()`. ## 4. Pull a model reliably for offline use Use the model pull command to warm the Hugging Face cache before working offline. Downloads resume after interrupted transfers, retry transient network failures, and verify every file against Hub metadata: ```bash openmed models pull disease_detection_superclinical ``` On a metered or unstable connection, pin the revision, limit transfer speed, and tune the retry count explicitly: ```bash openmed models pull disease_detection_superclinical \ --revision main \ --max-bandwidth 524288 \ --retries 5 ``` Progress contains only repository filenames and byte/file totals. After the pull completes, set `OPENMED_OFFLINE=1`; the same command then performs a cache-only lookup and never attempts a network connection. ### Scriptable CLI output and shell completion Add `--json` to a leaf command when a pipeline needs one stable JSON document on stdout instead of human-readable formatting: ```bash openmed analyze --text "synthetic clinical note" --json ``` The result uses the command's typed `to_dict()` payload inside a stable `ok`/`command`/`data` envelope. Errors use the matching `ok`/`command`/`error` envelope and a non-zero exit code; diagnostics and progress stay off the JSON stdout stream. Generate completion definitions for the shell in use: ```bash # Bash eval "$(openmed completion bash)" # Zsh source <(openmed completion zsh) # Fish openmed completion fish | source ``` ## 5. Copy code snippets from the docs All code blocks ship with Material for MkDocs copy buttons. Invoking the command palette (`/` or `cmd/ctrl + K`) lets you search for “GLiNER,” “OpenMedConfig,” or “token classification,” then copy the snippet that appears in the preview pane. If you rely on AI copilots (ChatGPT, Copilot, etc.), point them at the published docs URL so they crawl the same structured Markdown and surface canonical answers. ## 6. Optional: pin configuration ```python from openmed.core import OpenMedConfig, ModelLoader config = OpenMedConfig.from_env_fallback( cache_dir="~/.cache/openmed", device="cuda", default_org="OpenMed", ) loader = ModelLoader(config=config) ner = loader.create_pipeline("disease_detection_superclinical") entities = ner("Hydroxyurea dose reduced after platelet drop.") ``` Continue to the **Configuration** section for the full YAML/ENV schema, PHI-aware validation helpers, and logging setup. # Persona Quickstarts The [Quick Start](https://openmed.life/docs/getting-started/index.md) walks through installation in one linear path. This page splits that path into three short, copy-paste tracks so you land on the right first command for your role, then hands you off to the deeper guide. Pick the track that matches how you'll use OpenMed: | Persona | Goal | Jump to | | ----------------- | ------------------------------------------------ | ------------------------------- | | **Researcher** | De-identify a corpus and measure PHI leakage | [Researcher](#researcher) | | **App developer** | Call de-identification from a service or agent | [App developer](#app-developer) | | **Data engineer** | Redact files, directories, and datasets at scale | [Data engineer](#data-engineer) | To generate the matching config, offline defaults, README, and starter script instead of assembling them by hand, use the [`openmed init` project scaffold](https://openmed.life/docs/cli/openmed-init/index.md). Not a medical device OpenMed is a research and engineering toolkit for text de-identification and named-entity recognition. It is **not** a medical device and does not provide clinical decisions, diagnosis, or treatment advice. De-identification is probabilistic: review residual-risk output and validate against your own compliance requirements before releasing data. Every example below uses **synthetic, non-PHI** text. All tracks assume a working install. The minimal setup is: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh # install uv (skip if present) uv venv --python 3.11 source .venv/bin/activate uv pip install "openmed[hf]" # core + Hugging Face models ``` ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" uv venv --python 3.11 .venv\Scripts\Activate.ps1 uv pip install "openmed[hf]" # core + Hugging Face models ``` The first model-backed call may download model artifacts. Clinical text is still processed locally; after warming the cache, use [local-only offline mode](https://openmed.life/docs/configuration/#local-only-offline-mode) to block outbound connections during inference. ______________________________________________________________________ ## Researcher **Goal:** run entity extraction and de-identification over clinical notes, then quantify how much PHI leaked through. ### 1. Extract entities from a synthetic note `extract_pii()` returns a `PredictionResult` whose `entities` carry the detected text, canonical label, confidence, and character offsets. ```python from openmed import extract_pii note = "Patient Casey Example (MRN 00123) called from 555-0100 on 01/15/2020." result = extract_pii(note) for entity in result.entities: print(f"{entity.label:>10} {entity.text!r} [{entity.start}:{entity.end}]") ``` Reach for `analyze_text()` when you want the clinical NER models (diseases, medications, findings) instead of PII labels: ```python from openmed import analyze_text clinical = analyze_text( "Metastatic breast cancer treated with paclitaxel and trastuzumab.", model_name="disease_detection_superclinical", ) print(clinical.entities[0]) ``` ### 2. De-identify the note ```python from openmed import deidentify redacted = deidentify(note, method="mask") print(redacted.deidentified_text) # Detected spans are replaced with labels such as [first_name] and [phone_number]. ``` ### 3. Measure PHI leakage For a de-identification study, compare your gold PHI spans against the spans the model predicted. `compute_leakage_rate()` reports the character-weighted fraction of gold PHI not covered by a same-label prediction — the lower the better. ```python from openmed.eval import compute_leakage_rate gold = [ {"start": 8, "end": 21, "label": "NAME"}, # "Casey Example" {"start": 46, "end": 54, "label": "PHONE"}, # "555-0100" ] predicted = [ {"start": 8, "end": 21, "label": "NAME"}, # phone missed on purpose ] metrics = compute_leakage_rate(gold, predicted, source_text=note) print(f"Overall PHI leakage: {metrics.overall:.1%}") print(f"Missed phone leakage: {metrics.by_label['PHONE']:.1%}") ``` **Next steps:** the full method matrix (`mask`, `remove`, `replace`, `hash`, `shift_dates`), reversible mappings, and longitudinal patient-keyed date shifting live in [PII Anonymization](https://openmed.life/docs/anonymization/#quickstart-choosing-a-method). For the metric bundle and release gates, see [Eval Harness & Metrics](https://openmed.life/docs/eval-harness/index.md). ______________________________________________________________________ ## App developer **Goal:** de-identify text from an application or agent without embedding the models in your own request path. ### Option A — call the library directly If your service is already Python, one call is enough: ```python from openmed import deidentify redacted = deidentify("Contact Jordan Sample at jordan.sample@example.org.") print(redacted.deidentified_text) # Contact [first_name] [last_name] at [email]. ``` ### Option B — run the REST service Install the service extra and start the API: ```bash uv pip install "openmed[hf,service]" python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` Call `POST /pii/deidentify` with any HTTP client: ```bash curl -s http://127.0.0.1:8080/pii/deidentify \ -H "Content-Type: application/json" \ -d '{"text": "Contact Jordan Sample at jordan.sample@example.org.", "method": "mask"}' ``` Or use the typed Python client bundled with the `service` extra: ```python from openmed.service.client import OpenMedClient with OpenMedClient("http://127.0.0.1:8080", timeout=300.0) as client: redacted = client.deidentify( "Contact Jordan Sample at jordan.sample@example.org.", method="mask", ) print(redacted["deidentified_text"]) ``` ### Option C — expose OpenMed to an AI agent over MCP Install the MCP extra and start the Model Context Protocol server. It exposes an `openmed_deidentify` tool (plus `openmed_extract_pii` and `openmed_analyze_text`) over stdio, so agent frameworks can redact PHI as a tool call: ```bash uv pip install "openmed[hf,mcp]" python -m openmed.mcp.server # stdio transport (default) ``` For a local agent runtime that connects over HTTP, keep the server on loopback: ```bash python -m openmed.mcp.server --transport streamable-http --host 127.0.0.1 --port 8081 ``` These service examples deliberately bind to loopback. Do not expose them to an untrusted network without an authenticated, TLS-terminating boundary. **Next steps:** health checks, model warm-pool controls, request batching, the privacy gateway, and the full endpoint reference are in [REST Service](https://openmed.life/docs/rest-service/index.md). ______________________________________________________________________ ## Data engineer **Goal:** de-identify many files or dataset rows with progress reporting and PHI-free aggregate summaries — no per-record boilerplate. ### 1. Process a directory of notes `BatchProcessor` reuses one warmed model across the batch and keeps going when a single record fails. It returns de-identified text in memory and does not overwrite the source files: ```python from pathlib import Path from tempfile import TemporaryDirectory from openmed import BatchProcessor processor = BatchProcessor( operation="deidentify", model_name="pii_detection", method="mask", batch_size=16, confidence_threshold=0.7, continue_on_error=True, ) with TemporaryDirectory() as temp_dir: notes_dir = Path(temp_dir) (notes_dir / "note-1.txt").write_text( "Patient Casey Example called from 555-0100.", encoding="utf-8" ) (notes_dir / "note-2.txt").write_text( "Email Jordan Sample at jordan.sample@example.org.", encoding="utf-8" ) result = processor.process_directory( notes_dir, pattern="*.txt", recursive=True ) redacted_texts = [ item.result.deidentified_text for item in result.get_successful_results() ] print(f"Processed {len(redacted_texts)}/{result.total_items} files") print(f"Failures: {result.failed_items}") ``` ### 2. Redact specific columns of a dataset For CSV or JSONL input, `redact_dataset()` de-identifies only the free-text columns you name and returns an aggregate, PHI-free audit summary. Parquet uses the same API after installing the `columnar` extra with `uv pip install "openmed[hf,columnar]"`: ```python from openmed import redact_dataset result = redact_dataset( "notes.csv", text_columns=["note", "comment"], output_path="notes.redacted.csv", policy="strict_no_leak", ) # Aggregate counts only — total spans, per-label counts, residual-leakage estimate. print(result.summary.to_dict()) ``` The source dataset is never overwritten: `output_path` receives the redacted rows, while the summary remains in memory unless you explicitly persist it. The same path is available from the console entry point: ```bash openmed redact-dataset notes.csv \ --text-columns note,comment \ --policy strict_no_leak \ --output notes.redacted.csv ``` **Next steps:** streaming iteration, progress callbacks, batch PII extraction, and result export are covered in [Batch Processing](https://openmed.life/docs/batch-processing/index.md). # APIs and de-identification # Analyze Text Helper `openmed.analyze_text` is the top-level orchestrator that most users start with. It validates input, loads a token-classification or native span model, segments sentences, and normalizes the output so you can copy dict/JSON/HTML/CSV payloads straight into downstream systems. ## GLiFormer and GLiNER2 (v3.2) OpenMed 3.1's token-classification pipeline cannot load GLiFormer. Starting in v3.2, native GLiNER, GLiFormer, and GLiNER2 / GLiNER2.5 checkpoints share the same `analyze_text` result and formatting interface. Install the matching extra: ```bash pip install "openmed[gliformer]" # GLiFormer 0.1.3 pip install "openmed[gliner2]" # gliner2[local] 2.1+, including GLiNER2.5 ``` ```python from openmed import OpenMedConfig, analyze_text text = "No asthma. A synthetic note documents diabetes and asthma." result = analyze_text( text, model_id="OpenMed/GLiFormer-BioNER-Disease-Base-v1", threshold=0.7, config=OpenMedConfig(device="cpu"), assert_context=True, ) for entity in result.entities: assert text[entity.start:entity.end] == entity.text print(entity.text, entity.label, entity.confidence) ``` This registered checkpoint defaults to `labels=["disease"]`. Extraction uses the model's native labels; returned OpenMed entities normalize `disease` to `DISEASE`. Disease mentions remain mentions even when negated: the optional context stage adds assertion metadata, and does not establish a diagnosis. Use explicit labels for general-purpose models: ```python result = analyze_text( "A synthetic note documents asthma.", model_id="fastino/gliner2.5-base-v1", labels=["disease"], threshold=0.7, config=OpenMedConfig(device="cpu"), ) ``` Recognized family names and local checkpoint configurations select the native loader without a generated index or a Hub metadata request. For a custom Hub ID whose name does not identify its architecture, pass `family="gliformer"`, `family="gliner2"`, or `family="gliner"`. Local exports with renamed directories are detected from `gliner_config.json` / `config.json`; supply `labels=["disease"]` when the exported directory no longer identifies the registered disease model. `threshold` controls native extraction (default 0.5); `confidence_threshold` is a separate final output filter. Sentence chunking and absolute offsets, `output_format`, clinical context, and in-memory result caching still apply. Native pipelines accept a string or a list of strings and process chunks in order; `num_workers` must be zero. `aggregation_strategy` and fast-tokenizer selection apply to Transformers models. Native loading accepts `revision`, `cache_dir`, `token`, `device`, and `local_files_only`; unsupported loading options raise an error rather than being silently ignored. `max_length` controls the high-level chunk-size hint, while each native runtime owns token limits. Weights are downloaded on first use and kept in the configured local cache. For offline use, pre-download the checkpoint and any required tokenizer assets, then use a local directory or `OpenMedConfig(local_only=True, device="cpu")`. An uncached dependency fails offline; inference always uses the local model. See the [zero-shot toolkit](https://openmed.life/docs/zero-shot-ner/index.md) for the lower-level API and [upstream GLiFormer usage](https://docs.knowledgator.com/docs/frameworks/gliformer/usage/). ## Quick reference ```python from openmed import analyze_text result = analyze_text( text="Patient started on imatinib for chronic myeloid leukemia.", model_name="disease_detection_superclinical", aggregation_strategy="simple", output_format="dict", include_confidence=True, confidence_threshold=0.55, group_entities=True, metadata={"source": "clinic-note-42"}, ) print(result.model) print(result.entities[:3]) payload = result.to_dict() ``` ### Key arguments - `model_name`: registry alias, full Hugging Face id, or local model directory. Use `openmed.list_models()` if you need auto-discovery. - `model_id`: alias for `model_name`, supported for API-style callers that use model-id terminology. - `aggregation_strategy`: forwarded to the HF pipeline. `simple` (default) yields grouped tokens; `None` keeps raw tokens. - `output_format`: `"dict"` (default, returns `AnalyzeResult`), `"json"`, `"html"`, or `"csv"`. - `include_confidence` & `confidence_threshold`: control the final payload; defaults keep all scores. - `group_entities`: merge adjacent spans of the same label after formatting. - `formatter_kwargs`: forwarded to `openmed.processing.format_predictions`. - `assert_context`: opt in to deterministic clinical assertion labels. Each entity receives `negation`, `uncertainty`, `experiencer`, and `temporality` under `entity.metadata["clinical_context"]`. - Sentence options (`sentence_detection`, `sentence_language`, `sentence_clean`, `sentence_segmenter`, `sentence_backend`) wrap the sentence engine so each prediction carries the sentence span; disable them if latency matters more than helper metadata. The context stage is disabled by default. Enable it for clinical entities that will flow into grounding, FHIR export, or problem-list review: ```python result = analyze_text( "No evidence of pneumonia.", assert_context=True, ) print(result.entities[0].metadata["clinical_context"]) ``` ## Optional YASBD sentence backend The default `sentence_backend="auto"` path is unchanged: OpenMed uses its built-in Indic and Chinese segmenters where appropriate and pySBD elsewhere. YASBD is neither installed nor imported by a core OpenMed installation. Install the experimental backend explicitly when you want to benchmark it on your own workload: ```bash pip install "openmed[yasbd]" ``` Then select it for either the low-level sentence API or `analyze_text`: ```python from openmed import analyze_text from openmed.processing.sentences import segment_text spans = segment_text( "Patient is stable. Follow up tomorrow.", language="en", backend="yasbd", ) result = analyze_text( "Patient is stable. Follow up tomorrow.", sentence_backend="yasbd", ) ``` The adapter preserves OpenMed's exact, contiguous source offsets and assigns inter-sentence whitespace to the preceding span, matching the existing span contract. YASBD remains an explicit opt-in because sentence boundaries can differ between engines; validate representative clinical and multilingual inputs before adopting it in production. If the extra is missing, explicitly selecting `"yasbd"` raises an installation error instead of silently changing behavior. ## Chunking & truncation ```python result = analyze_text( text=long_report, model_name="pharma_detection_superclinical", aggregation_strategy=None, # work with raw tokens max_length=512, # forwarded to HF pipeline truncation=True, # enforce length (default) sentence_detection=False, # skip sentence detection to save ~2ms per note sentence_backend="auto", # "auto" (default) or "yasbd" (experimental, faster) ) ``` When you need full-control over tokenizer behaviour: - Pass `max_length`/`truncation` via `pipeline_kwargs`. If you skip truncation, the helper sets the tokenizer max length to unlimited (0) so HF pipelines accept longer inputs. - Provide `batch_size` or `num_workers` in `pipeline_kwargs` and they will be forwarded to the pipeline call but not to the constructor. - Enable medical token remapping with `OpenMedConfig(use_medical_tokenizer=True)` to group outputs onto clinical-friendly tokens without changing the model tokenizer. ## Loading from a local path Pass an existing model directory to `model_name` or `model_id` when the model files are already present on disk: ```python import os from openmed import OpenMedConfig, analyze_text local_path = os.path.abspath("./models/OpenMed-NER-DiseaseDetect-SuperClinical-434M") config = OpenMedConfig(device="cpu") result = analyze_text( "Patient presents with chronic myeloid leukemia and Type 2 diabetes.", model_id=local_path, config=config, ) for entity in result.entities: print(entity.text, entity.label) legacy_payload = result.to_dict() print(legacy_payload["model_name"]) ``` When the identifier points to an existing local path, OpenMed asks Transformers to load with `local_files_only=True` by default. That keeps air-gapped deployments from validating or downloading the model from the Hugging Face Hub. If any required tokenizer, config, or weight file is missing, loading fails locally with the underlying Transformers error. ## Streaming multiple texts `analyze_text` is optimized for single inputs. For batch jobs, keep a `ModelLoader` instance around and reuse its pipelines: ```python from openmed import ModelLoader, format_predictions loader = ModelLoader() pipeline = loader.create_pipeline("disease_detection_superclinical") for note in notes: raw = pipeline(note, batch_size=16) formatted = format_predictions(raw, note, model_name="Disease Detection") print(formatted.entities[:3]) ``` See [ModelLoader & Pipelines](https://openmed.life/docs/model-loader/index.md) for details on caching, GPU selection, and tokenizer reuse. ## HTML/CSV rendering ```python html = analyze_text( text, model_name="oncology_detection_superclinical", output_format="html", formatter_kwargs={ "html_class": "openmed-highlights", "tag_colors": {"CANCER": "#d97706"}, }, ) csv_rows = analyze_text( text, model_name="pharma_detection_superclinical", output_format="csv", ) ``` The HTML formatter emits a ready-to-embed snippet for dashboards; CSV mode writes row strings (header + body). Both respect `confidence_threshold` and `group_entities`. ## Validation behaviours Behind the scenes `analyze_text` calls: - `validate_input` — trims whitespace and enforces max lengths. - `validate_model_name` — normalizes registry aliases. - Sentence detection (`openmed.processing.sentences`) — optional segmentation with language hints and a selectable backend. - `OutputFormatter` — see [Advanced NER & Output Formatting](https://openmed.life/docs/output-formatting/index.md) for available kwargs. If you need custom validation or logging, inject your own `OpenMedConfig` or reuse a configured `ModelLoader`. # API Reference ## extract_pii Extract PII entities from text with intelligent entity merging. Uses token classification models to detect personally identifiable information including names, emails, phone numbers, addresses, and other HIPAA-protected identifiers. The smart merging feature uses regex patterns to identify semantic units (dates, SSN, phone numbers, etc.) and merges fragmented model predictions into complete entities with dominant label selection. Parameters: | Name | Type | Description | Default | | ---------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | | `text` | \`str | bytes | bytearray | | `model_name` | `str` | PII detection model (registry key or HuggingFace ID). When the default is used and lang is not "en", the language-appropriate default model is selected automatically. | `_DEFAULT_EN_MODEL` | | `confidence_threshold` | `float` | Minimum confidence score (0-1) | `0.5` | | `config` | `Optional[OpenMedConfig]` | Optional configuration override | `None` | | `use_smart_merging` | `bool` | Enable regex-based semantic unit merging (recommended) | `True` | | `lang` | `str` | ISO 639-1 language code (en, fr, de, it, es, nl, hi, te, pt, ar, ja, tr). Controls which default model and regex patterns are used. Mixed Latin/Devanagari or Latin/Telugu notes automatically use script-aware India clinical routing for hi and te. | `'en'` | | `normalize_accents` | `Optional[bool]` | Strip diacritical marks before model inference so that models trained on accent-free text still detect accented names. Entity spans in the result reference the original (accented) text. None (default) auto-enables for languages in \_ACCENT_NORMALIZE_LANGS (currently Spanish). | `None` | | `preserve_whitespace` | `bool` | Preserve leading and trailing source whitespace so returned entity offsets refer to the exact input string. | `False` | | `loader` | `Optional['ModelLoader']` | Optional shared model loader to reuse warmed pipelines. | `None` | | `batch_size` | `Optional[int]` | Optional backend inference batch size. | `None` | | `num_workers` | `Optional[int]` | Optional backend inference worker count. | `None` | | `custom_recognizer` | `Any` | Optional deny-list/allow-list recognizer config, CustomRecognizer instance, or JSON/YAML config path. Deny-list matches are added with custom:deny provenance; allow-list matches suppress overlapping spans from any detector. | `None` | | `abdm` | `Optional[bool]` | Enable the India ABDM identifier bundle. None auto-enables it for Hindi/Telugu and India locales; False explicitly disables that automatic activation. | `None` | | `code_mixed` | `bool` | Enable the explicit English/Hinglish route. This preserves English model detection while adding Roman-Hindi context patterns. | `False` | | `token_language_tags` | `Optional[Sequence[Any]]` | Required with code_mixed=True. Ordered, non-overlapping records with start, end, and label (en, hi, ne, univ, or other). Tags are consumed as offsets/labels only and are never copied with raw token surfaces. When omitted in code-mixed mode, the deterministic token-LID fallback derives them from the input. | `None` | | `lid_model` | `Optional['TokenLIDHook']` | Optional user-supplied token language-ID hook used only when code_mixed=True and token_language_tags is omitted. | `None` | | `transliterated_name_config` | `Any` | Optional configuration for the conservative Latin-script Indian given/family-name allow/deny bridge. | `None` | | `cache_results` | `bool` | Whether to cache this result in the in-process LRU cache. Cached results may contain PHI, but are never saved to disk. | `False` | | `max_cache_entries` | `int` | Maximum number of cached results. | `128` | | `budget` | `Optional[RequestBudget]` | Optional per-request wall-time and input-character budget. None means unlimited. Deadline checks are cooperative, and an over-length input is rejected before model inference. | `None` | Returns: | Type | Description | | ------------------ | ------------------------------------------- | | `PredictionResult` | PredictionResult with detected PII entities | Raises: | Type | Description | | --------------------- | --------------------------------------------------------- | | `InputError` | If text or request options are malformed or unsupported. | | `CapabilityError` | If the selected model or optional runtime is unavailable. | | `BudgetExceededError` | If the request exceeds its configured budget. | | `InternalError` | If inference violates a result or span invariant. | Example > > > from unittest.mock import patch from openmed.core.pii import extract_pii from openmed.processing.outputs import EntityPrediction, PredictionResult fake_result = PredictionResult( ... text="Patient Casey Example called.", ... entities=[ ... EntityPrediction( ... text="Casey Example", ... label="NAME", ... confidence=0.98, ... start=8, ... end=21, ... ) ... ], ... model_name="fixture-pii-model", ... timestamp="2026-01-01T00:00:00", ... ) with patch("openmed.analyze_text", return_value=fake_result): ... result = extract_pii( ... "Patient Casey Example called.", ... model_name="fixture-pii-model", ... use_smart_merging=False, ... ) next((entity.text, entity.label) for entity in result.entities) ('Casey Example', 'NAME') ## deidentify De-identify text by detecting and redacting PII with intelligent merging. Implements multiple de-identification strategies for HIPAA compliance: - **mask**: Replace with placeholders like [NAME], [EMAIL], etc. - **aadhaar_mask**: Render valid Aadhaar values as `XXXX XXXX NNNN`; use ordinary placeholders for every other entity - **remove**: Remove PII text entirely (empty string) - **replace**: Replace with fake but realistic data - **hash**: Replace with consistent hashed values for entity linking - **format_preserve**: Replace structured identifiers with synthetic values that keep shape and separators, masking unsupported labels - **shift_dates**: Shift dates by random offset while preserving intervals Smart merging uses regex patterns to merge fragmented entities (e.g., dates split into '01' and '/15/1970' are merged into complete '01/15/1970'). Code-mixed mode is explicit and offset driven. With `code_mixed=True` and per-token language tags, the English NER path remains active while a separate Roman-script Hindi pattern bank detects cues such as `naam`, `umar`, `pata`, `mobile`, and `janm`. The combined spans pass through the normal entity merger and final safety sweep before redaction. Parameters: | Name | Type | Description | Default | | ----------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | \`str | bytes | bytearray | | `method` | `DeidentificationMethod` | De-identification method (mask, aadhaar_mask, remove, replace, hash, shift_dates, format_preserve) | `'mask'` | | `model_name` | `str` | PII detection model | `_DEFAULT_EN_MODEL` | | `confidence_threshold` | `float` | Minimum confidence for redaction (default 0.7 for safety) | `0.7` | | `keep_year` | `bool` | For dates, keep the year unchanged | `False` | | `shift_dates` | `Optional[bool]` | Deprecated alias for method="shift_dates". | `None` | | `date_shift_days` | `Optional[int]` | Specific number of days to shift when patient_key is omitted. When patient_key is supplied, this is treated as a legacy maximum absolute offset bound unless date_shift_max_days is also supplied. | `None` | | `patient_key` | \`Optional\[str | bytes\]\` | Optional stable patient identifier used only to derive a deterministic HMAC date-shift offset. Raw keys are not logged, persisted, or returned. | | `date_shift_max_days` | `Optional[int]` | Maximum absolute offset for random, seeded, or patient-keyed date shifting. Defaults to 365 when patient_key or seed is supplied and neither this nor date_shift_days is set. | `None` | | `date_shift_secret` | \`Optional\[str | bytes\]\` | Required HMAC key material for patient-keyed offsets. Reuse the same value across sessions to keep offsets stable. | | `keep_mapping` | `bool` | Keep mapping for re-identification | `False` | | `config` | `Optional[OpenMedConfig]` | Optional configuration override | `None` | | `use_smart_merging` | `bool` | Enable regex-based semantic unit merging (recommended) | `True` | | `use_safety_sweep` | `bool` | Run a deterministic structured-identifier sweep after model detection and before redaction. | `True` | | `lang` | `str` | ISO 639-1 language code (en, fr, de, it, es, nl, hi, te, pt, ar, ja, tr). Controls model selection, regex patterns, and fake data for replacement. Mixed Latin/Devanagari or Latin/Telugu notes automatically use the script-aware India clinical route for hi and te. | `'en'` | | `normalize_accents` | `Optional[bool]` | Strip diacritical marks before model inference. None (default) auto-enables for Spanish. | `None` | | `loader` | `Optional['ModelLoader']` | Optional shared model loader to reuse warmed pipelines. | `None` | | `consistent` | `bool` | When method="replace" or method="format_preserve", generate stable surrogates (same input -> same surrogate within the call). Lets repeated mentions of the same name resolve to one fake identity instead of a different one each time. | `False` | | `seed` | `Optional[int]` | Optional request-scoped integer seed for cross-run reproducibility of replacements and automatic date shifting. Implies consistent=True for replacement methods. Explicit date_shift_days and patient-keyed offsets still take precedence for method="shift_dates". | `None` | | `locale` | `Optional[str]` | Faker locale override (pt_BR, en_GB, ...) for method="replace" and method="format_preserve". When None, derived from lang. | `None` | | `surrogate_vault` | `Optional['SurrogateVault']` | Optional cross-document surrogate vault. When provided with method="replace", OpenMed stores only HMAC source hashes. Indian names in Devanagari, Tamil, or opted-in Romanization use one HMAC of an in-memory phonetic fold and render the reused identity in the input script; the fold itself is never persisted or audited. | `None` | | `policy` | `Optional[str]` | Optional policy profile name controlling arbitration, action selection, mandatory safety sweep behavior, and reversible mapping. | `None` | | `calibration_thresholds_path` | \`Optional\[str | Path\]\` | Optional thresholds.json artifact path or artifact directory. When provided, per-label calibrated thresholds filter model detections and appear in audit output. | | `custom_recognizer` | `Any` | Optional deny-list/allow-list recognizer config, CustomRecognizer instance, or JSON/YAML config path. Deny-list matches are redacted with custom:deny provenance; allow-list matches suppress overlapping spans from any detector. | `None` | | `abdm` | `Optional[bool]` | Enable the India ABDM recognizer bundle. None auto-enables it for policy="india_dpdp_act", Hindi/Telugu, or an India locale. Pass False to opt out of automatic activation. | `None` | | `code_mixed` | `bool` | Enable the explicit English/Hinglish de-identification path. | `False` | | `token_language_tags` | `Optional[Sequence[Any]]` | Required with code_mixed=True. Ordered token records with exact start/end offsets and an en, hi, ne, univ, or other label. A pure-English tag stream does not activate Roman-Hindi patterns. When omitted in code-mixed mode, the deterministic token-LID fallback derives the tags. | `None` | | `lid_model` | `Optional['TokenLIDHook']` | Optional user-supplied token language-ID hook used only when code-mixed tags are inferred. | `None` | | `transliterated_name_config` | `Any` | Optional configuration for the Latin-script Indian name allow/deny bridge. The default bridge is conservative and can be replaced or extended by configuration. | `None` | | `audit` | `bool` | Return an AuditReport instead of the DeidentificationResult. Fresh calls use separate private HMAC keys. For stable hashes across runs, use a Pipeline with an explicit private hmac_secret. | `False` | | `cache_results` | `bool` | Whether to cache this result in the in-process LRU cache. Cached results may contain PHI, but are never saved to disk. | `False` | | `max_cache_entries` | `int` | Maximum number of cached results. | `128` | | `budget` | `Optional[RequestBudget]` | Optional per-request wall-time and input-character budget. None means unlimited. Deadline checks are cooperative, and an over-length input is rejected before model inference. | `None` | Returns: | Type | Description | | ------------------------ | --------------- | | \`DeidentificationResult | 'AuditReport'\` | | \`DeidentificationResult | 'AuditReport'\` | Raises: | Type | Description | | --------------------- | ------------------------------------------------------------------------------- | | `InputError` | If text or de-identification options are malformed. | | `PolicyError` | If the selected privacy policy is invalid or disallows the requested operation. | | `CapabilityError` | If the selected model or optional runtime is unavailable. | | `BudgetExceededError` | If the request exceeds its configured budget. | | `InternalError` | If inference or redaction violates an internal invariant. | Example > > > from datetime import datetime from types import SimpleNamespace from unittest.mock import patch from openmed.core.pii import ( ... DeidentificationResult, ... PIIEntity, ... deidentify, ... ) fixture = DeidentificationResult( ... original_text="Patient Casey Example", ... deidentified_text="Patient [NAME]", ... pii_entities=\[ ... PIIEntity( ... text="Casey Example", ... label="NAME", ... start=8, ... end=21, ... confidence=0.98, ... redacted_text="[NAME]", ... ) ... \], ... method="mask", ... timestamp=datetime(2026, 1, 1, 0, 0, 0), ... mapping={"[NAME]": "Casey Example"}, ... ) with patch("openmed.core.pipeline.Pipeline") as pipeline_cls: ... pipeline_cls.return_value.run.return_value = SimpleNamespace( ... deidentification_result=fixture ... ) ... result = deidentify( ... "Patient Casey Example", ... method="mask", ... keep_mapping=True, ... ) result.deidentified_text 'Patient [NAME]' result.mapping ## reidentify Re-identify text using stored mapping. Restores original PII from de-identified text using the mapping created during de-identification. Only works if keep_mapping=True was used. Parameters: | Name | Type | Description | Default | | ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `deidentified_text` | `str` | De-identified text | *required* | | `mapping` | `Mapping[str, str]` | Mapping from redacted to original text, optionally including occurrence-aware entries emitted for colliding replacement values. | *required* | Returns: | Type | Description | | ----- | --------------------------------------------- | | `str` | Re-identified text with original PII restored | Raises: | Type | Description | | ------------ | ---------------------------------------------------------------- | | `InputError` | If the text or mapping does not use the documented string types. | Example > > > from openmed.core.pii import reidentify reidentify( ... "Patient [NAME] has record [ID]", ... {"[NAME]": "Casey Example", "[ID]": "MRN-0001"}, ... ) 'Patient Casey Example has record MRN-0001' Note Only works if keep_mapping=True was used during de-identification. Requires proper authorization and audit logging in production. ## Structured errors The complete hierarchy, compatibility guarantees, and REST/MCP mappings are documented in [Structured public errors](https://openmed.life/docs/api/errors/index.md). ### OpenMedError Bases: `Exception` Base class for expected failures on the OpenMed public API. Parameters: | Name | Type | Description | Default | | --------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- | | `message` | `str` | Actionable, PHI-free explanation of the failure. | *required* | | `code` | `Optional[str]` | Optional stable leaf code owned by OpenMed. Callers should not invent codes; this hook supports existing specialized errors. | `None` | | `details` | `Optional[Mapping[str, Any]]` | Optional PHI-free structured context. | `None` | Attributes: | Name | Type | Description | | --------- | ---------------- | -------------------------------------------- | | `code` | `str` | Stable machine-readable error code. | | `message` | | Actionable, PHI-free human-readable message. | | `details` | `dict[str, Any]` | PHI-free structured context. | ## `__str__()` Return the PHI-free human-readable message. ## `to_dict(*, include_details=True)` Return a JSON-ready error object. Parameters: | Name | Type | Description | Default | | ----------------- | ------ | -------------------------------------------------------------------------------------------- | ------- | | `include_details` | `bool` | Include the structured details mapping. Service adapters use False for server-side failures. | `True` | Returns: | Type | Description | | ---------------- | --------------------------------------------------------- | | `dict[str, Any]` | A mapping with stable code and actionable message fields. | ### InputError Bases: `OpenMedError`, `ValueError`, `TypeError` Caller input is malformed, conflicting, or unsupported. `ValueError` and `TypeError` remain bases so existing handlers keep catching value and type validation failures after adopting the taxonomy. ### ConfigurationError Bases: `OpenMedError`, `ValueError`, `TypeError`, `KeyError` Configuration is missing, unknown, or inconsistent. The legacy `ValueError`, `TypeError`, and `KeyError` bases preserve compatibility with configuration registries and validators. ### CapabilityError Bases: `OpenMedError`, `ImportError` A requested runtime, model, or optional capability is unavailable. ### MissingExtraError Bases: `CapabilityError` An optional package or OpenMed extra is not installed. Parameters: | Name | Type | Description | Default | | --------- | ----------------------------- | ---------------------------------------------------------- | ---------- | | `message` | `str` | Actionable message containing an installation instruction. | *required* | | `package` | `Optional[str]` | Missing distribution name, if known. | `None` | | `feature` | `Optional[str]` | Feature that requires the package, if known. | `None` | | `extra` | `Optional[str]` | OpenMed extra that provides the package, if known. | `None` | | `details` | `Optional[Mapping[str, Any]]` | Additional PHI-free structured context. | `None` | ### ModelLoadError Bases: `CapabilityError`, `ValueError` A model, tokenizer, or inference backend could not be loaded. `ValueError` is retained in addition to `ImportError` because older model-loading paths used both builtin families. Parameters: | Name | Type | Description | Default | | ------------ | ----------------------------- | ------------------------------------------------------- | ---------- | | `message` | `str` | Actionable, PHI-free load failure message. | *required* | | `model_name` | `Optional[str]` | Non-sensitive model identifier or local path, if known. | `None` | | `details` | `Optional[Mapping[str, Any]]` | Additional PHI-free structured context. | `None` | ### PolicyError Bases: `OpenMedError`, `ValueError`, `TypeError` A request violates or misconfigures a privacy policy constraint. ### BudgetExceededError Bases: `OpenMedError`, `RuntimeError` A request exceeded a configured size, time, or resource budget. This class accepts both the generic taxonomy constructor and the historical request-budget fields used by :mod:`openmed.core.budget`. Parameters: | Name | Type | Description | Default | | ------------ | ----------------------------- | --------------------------------------------------------------------------------------------------- | ------- | | `message` | `Optional[str]` | Optional actionable message. When omitted, one is built from kind, limit, observed, and checkpoint. | `None` | | `kind` | `Optional[str]` | Budget dimension such as "wall_time" or "input_chars". | `None` | | `limit` | `Optional[float]` | Configured limit. | `None` | | `observed` | `Optional[float]` | Observed value that exceeded the limit. | `None` | | `checkpoint` | `Optional[str]` | Safe pipeline checkpoint where the limit was observed. | `None` | | `details` | `Optional[Mapping[str, Any]]` | Additional PHI-free structured context. | `None` | ### InternalError Bases: `OpenMedError`, `RuntimeError` An internal invariant failed and the request cannot safely continue. ### InferenceError Bases: `InternalError` A model or backend returned a structurally invalid inference result. ### redact_detail Return a stable descriptor for untrusted text without exposing it. Parameters: | Name | Type | Description | Default | | ------- | ----- | ---------------------------------------------------------------------------------------------------------------------- | ---------- | | `value` | `Any` | Value to describe. It is converted to text only for hashing and is never included verbatim in the returned descriptor. | *required* | Returns: | Type | Description | | ----- | ---------------------------------------------------------------------- | | `str` | A descriptor containing only the UTF-8 byte length and SHA-256 digest. | ## analyze_text Run token-classification or native span NER and format the predictions. Parameters: | Name | Type | Description | Default | | ---------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `text` | `str` | Clinical or biomedical text to analyse. | *required* | | `model_name` | `str` | Registry key, fully-qualified Hugging Face model id, or local model path. | `'disease_detection_superclinical'` | | `model_id` | `Optional[str]` | Alias for model_name. Useful for APIs and examples that name model identifiers as model_id. | `None` | | `family` | `Optional[str]` | Explicit gliner, gliner2, or gliformer family for an ambiguously named checkpoint. Recognized IDs and local configs select their family automatically. | `None` | | `labels` | `Optional[List[str]]` | Entity types for a native span model; the registered disease checkpoint defaults to ["disease"]. | `None` | | `threshold` | `Optional[float]` | Native extraction threshold, defaulting to 0.5. The final confidence_threshold filter applies independently afterwards. | `None` | | `config` | `Optional[OpenMedConfig]` | Optional :class:~openmed.core.config.OpenMedConfig instance. | `None` | | `loader` | `Optional[ModelLoader]` | Reuse an existing :class:~openmed.core.models.ModelLoader. | `None` | | `aggregation_strategy` | `Optional[str]` | Hugging Face aggregation strategy ("simple" by default). Set to None to work with raw token outputs. | `'simple'` | | `output_format` | `str` | "dict" (default), "json", "html" or "csv". | `'dict'` | | `include_confidence` | `bool` | Whether to include confidence scores in formatted output. | `True` | | `confidence_threshold` | `Optional[float]` | Minimum confidence for entities. None keeps all. | `0.0` | | `group_entities` | `bool` | Merge adjacent entities of the same label in the formatted output. | `False` | | `formatter_kwargs` | `Optional[Dict[str, Any]]` | Extra keyword arguments forwarded to :func:openmed.processing.format_predictions. | `None` | | `metadata` | `Optional[Dict[str, Any]]` | Optional metadata to attach to the result. | `None` | | `use_fast_tokenizer` | `bool` | Prefer fast tokenizers when available. | `True` | | `sentence_detection` | `bool` | Enable sentence detection (default: True). The engine is selected by sentence_backend. | `True` | | `sentence_language` | `str` | Language hint for the sentence detector. | `'en'` | | `sentence_clean` | `bool` | Whether to enable the sentence detector's cleaning heuristics. | `False` | | `sentence_segmenter` | `Optional[Any]` | Optional preconstructed segmenter object to reuse. It cannot be combined with sentence_backend="yasbd". | `None` | | `sentence_backend` | `Literal['auto', 'yasbd']` | Sentence segmentation engine to use. It can be "auto" (default, unchanged routing) or "yasbd" (experimental opt-in; requires openmed[yasbd]). | `'auto'` | | `assert_context` | `bool` | Attach deterministic negation, uncertainty, experiencer, and temporality labels to each entity under metadata["clinical_context"]. Disabled by default. | `False` | | `cache_results` | `bool` | Whether to cache this result in the in-process LRU cache. Cached results may contain PHI, but are never saved to disk. | `False` | | `max_cache_entries` | `int` | Maximum number of cached results. | `128` | | `**pipeline_kwargs` | `Any` | Additional arguments passed to :meth:openmed.core.models.ModelLoader.create_pipeline. | `{}` | Returns: | Type | Description | | ------------------------------------------------- | ------------------------------------------------------------------ | | `Union[AnalyzeResult, str, List[Dict[str, Any]]]` | Analyze result for "dict" output, otherwise the requested rendered | | `Union[AnalyzeResult, str, List[Dict[str, Any]]]` | format. | Example > > > class FixtureLoader: ... config = None ... ... def create_pipeline(self, model_name, **kwargs): ... def pipeline(text,** call_kwargs): ... return [ ... { ... "entity_group": "CONDITION", ... "score": 0.99, ... "start": 11, ... "end": 17, ... "word": "asthma", ... } ... ] ... ... return pipeline ... ... def get_max_sequence_length(self, model_name, tokenizer=None): ... return 128 result = analyze_text( ... "History of asthma.", ... model_name="fixture-ner-model", ... loader=FixtureLoader(), ... sentence_detection=False, ... ) next((entity.text, entity.label) for entity in result.entities) ('asthma', 'CONDITION') ## list_models Return available OpenMed model identifiers. Parameters: | Name | Type | Description | Default | | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | ------- | | `include_registry` | `bool` | Include entries from the bundled registry in addition to entries in the committed manifest. | `True` | | `include_remote` | `bool` | Retained for compatibility; no live discovery is performed. | `True` | | `config` | `Optional[OpenMedConfig]` | Optional custom configuration for model discovery. | `None` | ## BatchProcessor Process multiple texts efficiently with progress tracking. Example usage > > > from openmed import BatchProcessor, OpenMedConfig processor = BatchProcessor(model_name="disease_detection_superclinical") texts = ["Patient has diabetes.", "No significant findings."] result = processor.process_texts(texts) print(result.summary()) ## `__init__(model_name='disease_detection_superclinical', operation='analyze_text', batch_size=8, config=None, loader=None, aggregation_strategy='simple', confidence_threshold=None, group_entities=False, continue_on_error=True, checkpoint_interval=_DEFAULT_CHECKPOINT_INTERVAL, _atomic_write_hook=None, budget=None, **analyze_kwargs)` Initialize batch processor. Parameters: | Name | Type | Description | Default | | ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `model_name` | `str` | Model registry key or HuggingFace identifier. | `'disease_detection_superclinical'` | | `operation` | `BatchOperation` | Which function to call per item: "analyze_text" (default), "extract_pii" or "deidentify". Extra kwargs passed via \*\*analyze_kwargs are passed to the selected function. | `'analyze_text'` | | `batch_size` | `int` | Number of documents to process together per batch. | `8` | | `config` | `Optional[Any]` | Optional OpenMedConfig instance. | `None` | | `loader` | `Optional[Any]` | Optional ModelLoader instance to reuse. | `None` | | `aggregation_strategy` | `Optional[str]` | HuggingFace aggregation strategy (analyze_text operation only). | `'simple'` | | `confidence_threshold` | `Optional[float]` | Minimum confidence for entities. When not provided, defaults match the selected operation: 0.0 for analyze_text, 0.5 for extract_pii, and 0.7 for deidentify. | `None` | | `group_entities` | `bool` | Whether to group adjacent entities (analyze_text operation only). | `False` | | `continue_on_error` | `bool` | Continue processing on individual item errors. | `True` | | `checkpoint_interval` | `int` | Maximum number of items processed between durable checkpoints. | `_DEFAULT_CHECKPOINT_INTERVAL` | | `budget` | `Optional[Any]` | Optional per-request resource budget applied independently to each extract_pii or deidentify item. None means unlimited. The analyze_text operation ignores this value. | `None` | | `**analyze_kwargs` | `Any` | Additional arguments passed to the selected function. | `{}` | ## `iter_process(texts, ids=None, *, on_progress=None)` Process texts as an iterator, yielding results one at a time. This is useful for streaming results or processing very large batches where you don't want to hold all results in memory. Parameters: | Name | Type | Description | Default | | ------------- | --------------------------------- | ------------------------------------------------------------------------------------------ | ---------- | | `texts` | `Sequence[str]` | Sequence of texts to analyze. | *required* | | `ids` | `Optional[Sequence[str]]` | Optional identifiers for each text. | `None` | | `on_progress` | `Optional[BatchProgressCallback]` | Optional PHI-safe callback that receives a BatchProgress record after each completed item. | `None` | Yields: | Type | Description | | ----------------- | ---------------------------------------- | | `BatchItemResult` | BatchItemResult for each processed text. | ## `process_directory(directory, pattern='*.txt', recursive=False, encoding='utf-8', progress_callback=None, *, on_progress=None, output_path=None, checkpoint_path=None, resume_from_checkpoint=False, checkpoint_interval=None, output_format='json')` Process all matching files in a directory. Parameters: | Name | Type | Description | Default | | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------ | ---------- | | `directory` | `Union[str, Path]` | Directory path. | *required* | | `pattern` | `str` | Glob pattern for file matching. | `'*.txt'` | | `recursive` | `bool` | Whether to search recursively. | `False` | | `encoding` | `str` | File encoding. | `'utf-8'` | | `progress_callback` | `Optional[ProgressCallback]` | Optional callback for progress updates. | `None` | | `on_progress` | `Optional[BatchProgressCallback]` | Optional PHI-safe callback that receives a BatchProgress record after each completed item. | `None` | | `output_path` | `Optional[Union[str, Path]]` | Optional atomically written final result file. | `None` | | `checkpoint_path` | `Optional[Union[str, Path]]` | Optional PHI-free durable checkpoint file. | `None` | | `resume_from_checkpoint` | `bool` | Resume the committed result prefix. | `False` | | `checkpoint_interval` | `Optional[int]` | Per-run override for checkpoint frequency. | `None` | | `output_format` | `str` | "json" or "summary" for output_path. | `'json'` | Returns: | Type | Description | | ------------- | ---------------------------------------- | | `BatchResult` | BatchResult with all processing results. | ## `process_files(file_paths, encoding='utf-8', progress_callback=None, *, on_progress=None, output_path=None, checkpoint_path=None, resume_from_checkpoint=False, checkpoint_interval=None, output_format='json')` Process multiple files. Parameters: | Name | Type | Description | Default | | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------ | ---------- | | `file_paths` | `Sequence[Union[str, Path]]` | Paths to text files. | *required* | | `encoding` | `str` | File encoding. | `'utf-8'` | | `progress_callback` | `Optional[ProgressCallback]` | Optional callback for progress updates. | `None` | | `on_progress` | `Optional[BatchProgressCallback]` | Optional PHI-safe callback that receives a BatchProgress record after each completed item. | `None` | | `output_path` | `Optional[Union[str, Path]]` | Optional atomically written final result file. | `None` | | `checkpoint_path` | `Optional[Union[str, Path]]` | Optional PHI-free durable checkpoint file. | `None` | | `resume_from_checkpoint` | `bool` | Resume the committed result prefix. | `False` | | `checkpoint_interval` | `Optional[int]` | Per-run override for checkpoint frequency. | `None` | | `output_format` | `str` | "json" or "summary" for output_path. | `'json'` | Returns: | Type | Description | | ------------- | ---------------------------------------- | | `BatchResult` | BatchResult with all processing results. | Filesystem and decoding failures become failed items when `continue_on_error` is enabled; strict mode propagates the exception. Decoding-error reports contain only the exception type. ## `process_files_to_directory(file_paths, *, input_root, output_dir, encoding='utf-8', checkpoint_path=None, resume_from_checkpoint=False, checkpoint_interval=None, progress_callback=None, on_progress=None)` De-identify files into an atomic, checkpointed output directory. Output paths preserve each input's location relative to `input_root`. Committed files are hashed in the PHI-free checkpoint and verified before a resumed run skips them. Filesystem and decoding failures use the same per-file policy as `process_files`. Decoding-error reports omit native decoder details. ## `process_items(items, progress_callback=None, *, on_progress=None, output_path=None, checkpoint_path=None, resume_from_checkpoint=False, checkpoint_interval=None, output_format='json')` Process a sequence of BatchItem objects. Parameters: | Name | Type | Description | Default | | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------ | ---------- | | `items` | `Sequence[BatchItem]` | Sequence of BatchItem objects. | *required* | | `progress_callback` | `Optional[ProgressCallback]` | Optional callback for progress updates. | `None` | | `on_progress` | `Optional[BatchProgressCallback]` | Optional PHI-safe callback that receives a BatchProgress record after each completed item. | `None` | | `output_path` | `Optional[Union[str, Path]]` | Optional atomically written final result file. | `None` | | `checkpoint_path` | `Optional[Union[str, Path]]` | Optional PHI-free durable checkpoint file. | `None` | | `resume_from_checkpoint` | `bool` | Resume the committed result prefix. | `False` | | `checkpoint_interval` | `Optional[int]` | Per-run override for checkpoint frequency. | `None` | | `output_format` | `str` | "json" or "summary" for output_path. | `'json'` | Returns: | Type | Description | | ------------- | ---------------------------------------- | | `BatchResult` | BatchResult with all processing results. | ## `process_texts(texts, ids=None, progress_callback=None, *, on_progress=None, output_path=None, checkpoint_path=None, resume_from_checkpoint=False, checkpoint_interval=None, output_format='json')` Process multiple texts. Parameters: | Name | Type | Description | Default | | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------- | ---------- | | `texts` | `Sequence[str]` | Sequence of texts to analyze. | *required* | | `ids` | `Optional[Sequence[str]]` | Optional identifiers for each text. | `None` | | `progress_callback` | `Optional[ProgressCallback]` | Optional callback for progress updates. Signature: callback(completed_count, total_count, result) | `None` | | `on_progress` | `Optional[BatchProgressCallback]` | Optional PHI-safe callback that receives a BatchProgress record after each completed item. | `None` | | `output_path` | `Optional[Union[str, Path]]` | Optional atomically written final result file. | `None` | | `checkpoint_path` | `Optional[Union[str, Path]]` | Optional PHI-free durable checkpoint file. | `None` | | `resume_from_checkpoint` | `bool` | Resume the committed result prefix instead of starting a new checkpoint. | `False` | | `checkpoint_interval` | `Optional[int]` | Per-run override for checkpoint frequency. | `None` | | `output_format` | `str` | "json" or "summary" for output_path. | `'json'` | Returns: | Type | Description | | ------------- | ---------------------------------------- | | `BatchResult` | BatchResult with all processing results. | ## `resume_from_checkpoint(items, *, checkpoint_path, output_path=None, progress_callback=None, on_progress=None, output_format='json')` Resume `items` from a previously committed batch checkpoint. ## PIIEntity Bases: `EntityPrediction` Extended Entity with PII-specific metadata. Attributes: | Name | Type | Description | | --------------- | --------------- | ------------------------------------------- | | `text` | `str` | The entity text span | | `label` | `str` | PII category (NAME, EMAIL, PHONE, etc.) | | `start` | `Optional[int]` | Character start position | | `end` | `Optional[int]` | Character end position | | `confidence` | `float` | Model confidence score (0-1) | | `entity_type` | `str` | PII category (same as label) | | `redacted_text` | `Optional[str]` | Replacement text after de-identification | | `original_text` | `Optional[str]` | Original text before redaction | | `hash_value` | `Optional[str]` | Consistent hash for entity linking | | `reversible_id` | `Optional[str]` | Optional reversible pseudonymization handle | ## `__post_init__()` Initialize entity_type from label if not set. ## DeidentificationResult Result of de-identification operation. Attributes: | Name | Type | Description | | ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `original_text` | `str` | Input text before de-identification | | `deidentified_text` | `str` | Output text with PII redacted | | `pii_entities` | `list[PIIEntity]` | List of detected and redacted PII entities | | `method` | `str` | De-identification method used | | `timestamp` | `datetime` | When de-identification was performed | | `mapping` | `Optional[dict[str, str]]` | Optional mapping for re-identification. Colliding replacement surfaces use private occurrence keys so separate source spellings remain reversible without changing the de-identified text. | ## `to_dataframe()` Convert detected PII entities to a pandas DataFrame. Returns: | Type | Description | | ----- | --------------------------------------------------------------- | | `Any` | A pandas DataFrame with one row per detected entity and columns | | `Any` | text, label, entity_type, start, end, | | `Any` | confidence, action, and result_id. | Raises: | Type | Description | | ------------------- | --------------------------------------------------------------------------------- | | `MissingExtraError` | If pandas is not installed. This remains an :class:ImportError for compatibility. | ## `to_dict()` Convert result to dictionary format. Returns: | Type | Description | | ------ | ---------------------------------------------- | | `dict` | Dictionary with all result fields and metadata | ## PDF redaction and fidelity Render and verify a clean redacted PDF from projected rectangles. Parameters: | Name | Type | Description | Default | | ------------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `source` | \`str | Path\` | Source digital PDF. Processing is local and never uses a network. | | `output` | \`str | Path\` | Destination PDF. It is published atomically only after every mandatory verification passes. | | `regions` | `Iterable[Any]` | Iterable of (page, bbox) tuples, mappings/objects with page and bbox, or ProjectedRectangle instances. Bboxes use pdfplumber's top-origin (x0, top, x1, bottom) coordinates. | *required* | | `render_dpi` | `int` | Resolution used to burn each source page into safe pixels. | `_DEFAULT_RENDER_DPI` | | `fidelity_dpi` | \`int | None\` | Resolution used by the independent regression check. Defaults to render_dpi. | | `pixel_tolerance` | `int` | Maximum per-channel 0-255 difference treated as stable. | `_DEFAULT_PIXEL_TOLERANCE` | | `max_outside_changed_fraction` | `float` | Maximum fraction of pixels outside all redaction boxes that may differ. | `_DEFAULT_MAX_OUTSIDE_CHANGED_FRACTION` | | `max_pages` | `int` | Maximum number of source pages accepted for one render. | `_DEFAULT_MAX_PAGES` | | `max_page_pixels` | `int` | Maximum rendered pixels accepted for any page. | `_DEFAULT_MAX_PAGE_PIXELS` | | `max_total_pixels` | `int` | Maximum rendered pixels accepted across all pages. | `_DEFAULT_MAX_TOTAL_PIXELS` | | `max_regions` | `int` | Maximum number of distinct redaction rectangles. | `_DEFAULT_MAX_REGIONS` | | `overwrite` | `bool` | Permit atomically replacing an existing output file. | `False` | | `code_detector` | \`CodeRegionDetector | None\` | Local code provider, or optional ZXing by default. | | `code_detection_policy` | `CodeDetectionPolicy` | Fail closed or record unavailable code coverage. | `'coverage_incomplete'` | | `annotation_detector` | `Any` | Optional callable that detects PHI offsets in the annotation Contents/appearance text. Omit to remove all annotations. Unmappable appearances fail closed; matched spans redact the full annotation extent. No annotation objects survive in either mode. | `None` | Returns: | Name | Type | Description | | ---- | -------------------- | ------------------------------------------------------------------- | | `A` | `PdfRedactionResult` | class:PdfRedactionResult containing PHI-safe verification evidence. | Raises: | Type | Description | | ---------------------------- | ------------------------------------------------------------ | | `ValueError` | If regions, thresholds, page indexes, or bboxes are invalid. | | `FileExistsError` | If output exists and overwrite is false. | | `PdfRenderVerificationError` | If text removal, boxes, or layout fail. | | `MissingDependencyError` | If the multimodal PDF stack is unavailable. | Verify that `redacted` scrubbed the PHI `spans` present in `original`. `spans` describes what was redacted. Each item may be: - a `(page, bbox)` region (a mapping/object with `page` and `bbox`, or a :class:`~openmed.multimodal.documents_pdf.ProjectedRectangle`), or - a character span into `original`'s extracted text (a `(start, end)` tuple, or a mapping/object with `start`/`end`) that is projected to a page rectangle using `original`. For each region the verifier asserts (a) no selectable word in `redacted` remains under the region and (b) an opaque redaction box covers the region. When a raster backend is available (or `rasterizer` is supplied) the region is also rendered to pixels in both documents and required to differ. Returns a :class:`PdfFidelityReport`. Pass `strict=True` to raise :class:`RedactionFidelityError` on any residual leakage instead. Verify that every selected source-word occurrence was removed. Unlike :func:`verify_redacted_pdf`, which checks the output text layer at each projected rectangle, this helper accounts for selected word occurrences across the complete extracted text of both PDFs. It therefore catches source words that were moved, reordered, separated, split, merged, or duplicated during re-rendering while allowing unrelated identical words to remain. Reports contain only geometry, counts, and SHA-256 digests; source and residual plaintext are never stored. A region with no extractable source text fails closed because this helper cannot prove removal. Scanned/image-only PDFs require the separate OCR path. Pass `strict=True` to raise :class:`RedactedTextRemovalError` on failure. Measure page geometry and pixels outside redaction rectangles. The comparison is deterministic for a fixed local PDF stack. Pixels inside each requested rectangle, plus a one-point antialiasing margin, are masked out. The remaining pixels form an enforceable regression gate. No OCR or page text is included in the returned report. ## PipelineTelemetry Opt-in OpenTelemetry spans and metrics for core pipeline stages. Parameters: | Name | Type | Description | Default | | --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- | ------- | | `enabled` | `bool` | Explicit opt-in. The default is False. | `False` | | `tracer` | `Any` | Optional caller-owned OpenTelemetry tracer. When omitted after opt-in, the global API tracer is used if OpenTelemetry is installed. | `None` | | `meter` | `Any` | Optional caller-owned OpenTelemetry meter. When omitted after opt-in, the global API meter is used if OpenTelemetry is installed. | `None` | OpenMed never configures the providers behind these objects and therefore never creates an exporter or network destination. ## `disabled()` Return an explicitly disabled no-op runtime. ## `from_env(*, tracer=None, meter=None)` Build telemetry from the explicit environment opt-in. ## `stage_span(index, name)` Create one fixed-name, no-PHI span for a pipeline stage. ## StageTelemetry No-PHI recorder for one pipeline stage. Instances are created by :meth:`PipelineTelemetry.stage_span`. Setters accept only aggregate values and route every span attribute through :func:`safe_stage_attributes`. ## `active` Return whether this recorder has a trace or metric sink. ## `finish(duration_ms)` Finish the stage and record its duration and aggregate metrics. ## `mark_failed()` Mark a failed stage without recording an exception or message. ## `set_entity_count(count)` Record how many entities this stage produced. ## `set_input_length(length)` Record a stage input character count. ## `set_labels(labels)` Record a set of canonical category labels, never entity text. ## `set_offset_range(start, end)` Record aggregate output bounds without storing a detected surface. ## `set_redacted_length(length)` Record the emitted redacted character count. ## `set_span_count(count)` Record how many canonical spans this stage produced. # De-identification API The `deidentify()` helper returns a typed `DeidentificationResult` with the redacted text, detected `PIIEntity` spans, result metadata, and a `to_dict()` representation for JSON-style workflows. ## Entity Table Export Use `DeidentificationResult.to_dataframe()` when you want to inspect the entities detected in a single de-identification result as a table: ```python from openmed import deidentify result = deidentify("Patient John Doe called 555-1234", method="mask") entities = result.to_dataframe() ``` The method imports pandas lazily, so importing `openmed` or `openmed.core.pii` does not import pandas. If pandas is not installed, calling `to_dataframe()` raises an actionable `MissingExtraError` with code `missing_extra` and the install command. It remains an `ImportError` for backward compatibility. See [Structured public errors](https://openmed.life/docs/api/errors/index.md). The returned DataFrame has one row per detected entity and always uses this column order: | Column | Description | | ------------- | ---------------------------------------------------------------------- | | `text` | Entity text span captured by the detector. | | `label` | Detector label for the span. | | `entity_type` | Normalized PII entity type stored on the result entity. | | `start` | Character start offset in the original text. | | `end` | Character end offset in the original text. | | `confidence` | Detector confidence score. | | `action` | De-identification policy action applied to the entity, when available. | | `result_id` | Stable hash-derived identifier shared by every row from the result. | When no PII entities are present, `to_dataframe()` returns an empty DataFrame with the same columns. ## India ABDM and ABHA identifiers Enable the ABDM recognizer bundle for Indian clinical records to detect and replace ABHA numbers and addresses, Aadhaar numbers, PAN values, and contextual HPR/HFR registry identifiers: ```python from openmed import deidentify result = deidentify( note, method="replace", lang="en", locale="en_IN", abdm=True, ) ``` The bundle also activates automatically for Hindi or Telugu, an India locale, or the `india_dpdp_act` policy profile. Pass `abdm=False` to opt out explicitly. It is inactive for other languages and locales by default. Recognized source labels (`ABHA_NUMBER`, `ABHA_ADDRESS`, `AADHAAR`, `PAN`, `ABDM_HPR_ID`, and `ABDM_HFR_ID`) normalize to `ID_NUM` and the `DIRECT_IDENTIFIER` policy class. Replacement mode produces synthetic values only; it does not call ABDM, verify an identifier, or store or resolve a real ABHA number. ABHA numbers are validated by their publicly documented 14-digit shape; the public NHA materials do not specify an offline checksum algorithm. ABHA-linked record sharing requires the individual's informed consent. This mode de-identifies recognized identifiers, but it does not collect or record consent and does not decide whether a disclosure is permitted. Applications must enforce their own consent and disclosure workflow before sharing records. See the [official ABDM FAQ](https://abdm.gov.in/FAQ) for the ABHA identity and consent model. # Advanced NER & Output Formatting Post-processing matters as much as the base model. OpenMed codifies the heuristics from the public demos so you can go from noisy token output to high-quality, copy-pasteable spans in a few lines. ## Advanced NER processor `openmed.processing.advanced_ner.AdvancedNERProcessor` applies the same filtering stack used in the OpenMed Gradio app: - Confidence filtering with a configurable threshold (`min_confidence`). - Punctuation-only and short-span removal. - Regex-based exclusions for common false positives. - Optional edge stripping and gap-aware merging of adjacent entities. - Smart BIO grouping fixes overlapping spans when `aggregation_strategy=None`. ```python from openmed.processing.advanced_ner import create_advanced_processor processor = create_advanced_processor( min_confidence=0.65, merge_adjacent=True, max_merge_gap=8, ) raw = pipeline(text) # HF token-classification output entities = processor.process_pipeline_output(text, raw) for span in entities: print(span.label, span.text, span.score) ``` Use it when you need deterministic filtering outside of `analyze_text` or when you operate on raw tokens. ## Medication-focused candidates PharmaDetect checkpoints expose the label defined by their training data: `CHEM`. That label covers chemical mentions and is not proof that every span is a prescribed medication. OpenMed therefore preserves `CHEM` instead of silently relabeling it as `MEDICATION`. For a precision-oriented medication candidate list, compose `analyze_text` with the clinical postprocessor: ```python from openmed import analyze_text from openmed.clinical import filter_medication_candidates text = "Diabetic with PP 202mg/dL. On metformin.\nCyclopalm\nOndam" result = analyze_text( text, model_name="OpenMed/OpenMed-NER-PharmaDetect-SuperClinical-434M-mlx", confidence_threshold=0.0, ) medications = filter_medication_candidates(text, result.entities) print([(item.source_label, item.text) for item in medications]) # [('CHEM', 'metformin'), ('CHEM', 'Cyclopalm'), ('CHEM', 'Ondam')] ``` The built-in preset uses a `0.75` threshold and rejects short uppercase spans when their immediate same-line context is an observation-like measurement (for example, `PP 202mg/dL`). It does not use a network service, mutate the input entities, or require a terminology dependency. The threshold is a precision-oriented starting point for this model, not a universal calibration. Applications can pass a custom `MedicationCandidatePreset`. They can also supply a caller-owned local formulary or `RxNormLinker.link` as `grounder`; successful grounding overrides the observation heuristic. Strict grounding is opt-in because RxNorm is US-centric and can omit regional brand names. ## OutputFormatter & PredictionResult `openmed.processing.OutputFormatter` normalizes predictions into dictionaries, JSON strings, HTML snippets, or CSV rows. The dataclasses in `openmed/processing/outputs.py` ensure the payload stays type-safe and ready for logging. ```python from openmed.processing import format_predictions formatted = format_predictions( raw_predictions, original_text, model_name="Disease Detection", include_confidence=True, confidence_threshold=0.6, group_entities=True, ) print(formatted.entities[0].to_dict()) print(formatted.to_dict()) ``` ### HTML output ```python from openmed.processing.outputs import OutputFormatter formatter = OutputFormatter(group_entities=True) result = formatter.format_predictions(raw_predictions, text, model_name="Oncology") html = formatter.to_html(result, tag_colors={"Cancer": "#f97316"}) ``` The HTML helper wraps highlighted spans with semantic tags (`data-entity="Cancer"`) so your dashboards can apply custom styles or tooltips. ### CSV output ```python csv_lines = formatter.to_csv(result) print("\n".join(csv_lines[:5])) ``` CSV export is handy when you need to feed BI tools or spreadsheets without additional ETL code. ## Sentence spans & metadata - `analyze_text` attaches sentence spans (using the default routing or the experimental YASBD backend) and forwards `metadata` objects so each entity can carry extra context (e.g., the originating service, clinical section, or ontological hints). - Aggregated entities are split at detected sentence boundaries and hard line breaks, so adjacent list items such as `Cyclopalm` and `Ondam` remain separate even when the model emits one BIO chain. - The formatter ensures `confidence`, `start`, and `end` offsets are normalized to built-in `float`/`int` so serializing to JSON never fails due to NumPy/PyTorch dtypes. ## Guardrails Pair the formatter with validation helpers from `openmed.utils.validation`: ```python from openmed.utils.validation import ( validate_confidence_threshold, validate_output_format, validate_batch_size, ) ``` These guardrails keep API endpoints resilient against out-of-range parameters and malformed payloads. ## CLI JSON output contract Every `openmed` subcommand accepts a uniform `--json` flag for scripting and agent use. When set, the command writes a single machine-readable document to stdout with stable top-level keys; without it, the command keeps its human-readable output. ### Success envelope ```json { "ok": true, "command": "models list", "data": { "count": 12, "models": [ /* command-specific payload */ ] } } ``` - `ok` — always `true` on success. - `command` — the space-joined subcommand path. - `data` — the command-specific payload with stable keys (documented per command in `--help`). ### Error envelope On failure the command writes the error envelope (to stdout in `--json` mode so an agent can parse a single stream) and exits non-zero: ```json { "ok": false, "command": "audit verify", "error": { "code": "input_not_found", "message": "Input file not found: report.json" } } ``` Without `--json`, the same failure prints the message to stderr. Either way the process exit code follows the table below. ### Exit codes | Code | Meaning | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | success | | `1` | failure: runtime error (I/O, model load), or a gate/verification negative result — e.g. `--strict` / `--fail-on-*` violations, matching the repository's release-gate convention | | `2` | usage / validation error (also argparse's own parse-error code) | Scriptability: no `openmed` subcommand blocks on interactive input, so every command is safe to run non-interactively in a pipeline. This is enforced by `tests/unit/cli/test_cli_json_output.py`. ## Tool schema registry & drift guard The agent-facing tool schemas (used by the MCP server and the framework adapters) are defined once in `openmed.mcp.tool_registry.TOOL_REGISTRY`. A static bundle is published at `openmed/interop/tools.json` for offline consumers, generated from `render_tool_registry_document()`. `tests/unit/interop/test_tool_schema_sync.py` guards against drift: it asserts the registry, the MCP server's registered tools, every framework adapter's rendered definitions, and the committed `tools.json` bundle all agree on tool names and input/output schemas. Regenerate the bundle whenever the registry changes: ```python import json from openmed.mcp.tool_registry import render_tool_registry_document with open("openmed/interop/tools.json", "w", encoding="utf-8") as fh: json.dump(render_tool_registry_document(), fh, indent=2, sort_keys=True) fh.write("\n") ``` # Agents and tool surfaces # Build with OpenMed from an agent Use this guide when a coding agent is building an application that imports OpenMed. The repository `AGENTS.md` explains how to contribute to OpenMed; this page explains how to consume its public APIs safely. For permissioned clinical workflows, start with the [governed-agent lifecycle](https://openmed.life/docs/agent/index.md) and its authority, approval, evidence and recovery contracts. The application must compose those checks around its dispatch boundary; using a coding agent does not authorize clinical actions. All examples below use synthetic values. Model inference runs locally after the first model download. ## Install Install the core library and the local model runtime: ```bash python -m pip install "openmed[hf]" ``` Add optional surfaces only when the application needs them: ```bash python -m pip install "openmed[hf,mcp,service]" ``` ## Three primary calls ### Analyze clinical text Use `analyze_text` for clinical or biomedical named-entity recognition. ```python from openmed import analyze_text result = analyze_text( "Synthetic assessment: type 2 diabetes treated with metformin.", model_name="disease_detection_superclinical", confidence_threshold=0.5, ) for entity in result.entities: print(entity.label, entity.text, entity.start, entity.end) ``` The result is a typed `AnalyzeResult`. Its `entities` expose text, label, confidence, and character offsets; `result.to_dict()` produces a JSON-ready mapping. ### Extract PII without changing the text Use `extract_pii` when the application needs identifier spans and offsets. ```python from openmed import extract_pii synthetic_note = ( "Synthetic patient Taylor Example, record SYNTH-0007, called " "212-555-0198." ) result = extract_pii( synthetic_note, lang="en", confidence_threshold=0.5, ) for entity in result.entities: print(entity.label, entity.start, entity.end, entity.confidence) ``` Do not print `entity.text` for real records. Keep raw surfaces inside the trusted process and use labels, offsets, hashes, and confidence values for diagnostics. ### De-identify text Use `deidentify` to mask, remove, replace, hash, or consistently shift detected identifiers. ```python from openmed import deidentify synthetic_note = ( "Synthetic patient Taylor Example can be reached at " "demo.patient@example.test." ) result = deidentify( synthetic_note, method="mask", lang="en", confidence_threshold=0.5, ) print(result.deidentified_text) print(result.num_entities_redacted) ``` `DeidentificationResult` also carries detected entities, metadata, an optional audit report, and an optional reversible mapping. Do not log or return `original_text`, entity surfaces, or mappings across an untrusted boundary. ## Public API map | Task | Public surface | Result or purpose | | --------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | | Clinical NER | `openmed.analyze_text` | `AnalyzeResult` with typed entity spans | | PII detection | `openmed.extract_pii` | PII predictions without rewriting text | | De-identification | `openmed.deidentify` | `DeidentificationResult` and rewritten text | | Re-identification | `openmed.reidentify` | Restore only from an explicitly retained mapping | | Batch text processing | `openmed.BatchProcessor`, `openmed.process_batch` | Reuse model state across many inputs | | Dataset redaction | `openmed.redact_dataset` | Separate CSV, JSONL, or Parquet output plus aggregate summary | | Model discovery | `openmed.get_model_info`, `openmed.get_models_by_category`, `openmed.get_pii_models_by_language` | Offline registry metadata | | Model loading | `openmed.ModelLoader`, `openmed.load_model` | Explicit model lifecycle and cache reuse | | FHIR export | `openmed.clinical.exporters.fhir` | Deterministic FHIR R4 helpers | | Evaluation | `openmed.eval` | Recall, leakage, calibration, and release gates | | Agent tools | `openmed.mcp.tool_registry` | Typed tool definitions and validation | | Local service | `openmed.service.app:app` | REST endpoints for self-hosted use | | Command line | `openmed` | Analyze, PII, dataset, model, and benchmark commands | Use the [API reference](https://openmed.life/docs/api-reference/index.md) for signatures and the [feature map](https://openmed.life/docs/feature-map/index.md) for the source module behind each capability. ## Privacy invariants An agent that builds with OpenMed must preserve these rules: 1. Keep inference local. A first run may download model artifacts; steady-state inference must not require uploading text or enabling telemetry. 1. Use offline mode after approved models are cached: ```python from openmed import OpenMedConfig, extract_pii config = OpenMedConfig(local_only=True) result = extract_pii( "Synthetic contact: sample.user@example.test.", config=config, ) ``` 1. Never place raw PHI in logs, traces, cache keys, temporary filenames, exception messages, analytics, or audit artifacts. 1. Keep audit evidence PHI-free: store offsets, canonical labels, thresholds, provenance, counts, and keyed hashes rather than identifier text. 1. Use synthetic data in examples and committed fixtures. Never commit DUA-gated corpora or restricted terminology assets. 1. Validate direct-identifier recall, critical leakage, span integrity, and quantized-model deltas. Aggregate F1 alone is not a privacy gate. 1. Treat de-identification as a technical control, not a compliance guarantee or an automated clinical decision. 1. Keep reversible mappings encrypted and separate, or leave `keep_mapping=False`. See [No-Raw-PHI Logging](https://openmed.life/docs/security/no-raw-phi-logging/index.md), [No-Telemetry Guarantee](https://openmed.life/docs/security/no-telemetry/index.md), and the [redactor threat model](https://openmed.life/docs/security/threat-model/index.md) for the full controls. ## MCP server and tool registry Install and launch the local stdio server: ```bash python -m pip install "openmed[mcp]" openmed-mcp --transport stdio ``` The server exposes `openmed_analyze_text`, `openmed_extract_pii`, `openmed_deidentify`, model discovery and lifecycle tools, and a PHI-safe workflow runner. The source of truth for their input and output schemas is `openmed/mcp/tool_registry.py`. Use the [MCP client guide](https://openmed.life/docs/mcp-clients/index.md) for client configuration and authenticated remote deployment. Prefer stdio or loopback. Do not bind an unauthenticated server to a public interface. Applications that need tool definitions without running an MCP transport can import the registry directly: ```python from openmed.mcp.tool_registry import TOOL_REGISTRY for tool in TOOL_REGISTRY.latest_specs(): print(tool.name) ``` ## Command-line interface Discover models without sending clinical text anywhere: ```bash openmed models list openmed models info disease_detection_superclinical ``` Run the three primary paths: ```bash openmed analyze \ --text "Synthetic assessment: asthma treated with albuterol." openmed pii extract \ --text "Synthetic contact: 212-555-0198." openmed pii deidentify \ --text "Synthetic contact: demo.patient@example.test." \ --method mask ``` For files and datasets, prefer `--input-file`, `openmed deid`, or `openmed redact-dataset` so shell history does not capture sensitive values. See [Batch Processing](https://openmed.life/docs/batch-processing/index.md) for streaming and aggregate PHI-free progress reporting. ## Repository skills The repository-root `skills/` directory contains portable procedures an agent can load directly. Start with these task recipes: - `skills/deidentify-a-dataset/SKILL.md` - `skills/extract-clinical-entities-to-fhir/SKILL.md` - `skills/pick-a-pii-model/SKILL.md` - `skills/benchmark-pii-recall/SKILL.md` Each skill includes a synthetic runnable snippet and points to a checked-in repository example. # Connect MCP clients to OpenMed OpenMed exposes its clinical NLP, PII extraction, and de-identification tools through the Model Context Protocol (MCP). Use the `openmed-mcp` command for local stdio clients or the Streamable HTTP transport for clients that connect to a URL. All examples on this page use synthetic text. Only send real PHI to an OpenMed runtime that you operate and trust. ## Install and verify Install OpenMed with the optional MCP dependency: ```bash python -m pip install "openmed[mcp]" openmed-mcp --version ``` For a checkout managed with `uv`: ```bash uv sync --extra mcp uv run openmed-mcp --version ``` ## Run in a container Build the dedicated MCP image from a checkout: ```bash docker build -f Dockerfile.mcp -t openmed-mcp:local . ``` The image defaults to stdio. Keep stdin attached with `-i` and do not allocate a TTY, because MCP protocol messages use stdin and stdout: ```bash docker run -i --rm \ -v openmed-hf-cache:/root/.cache/huggingface \ openmed-mcp:local ``` A command-map client can launch that container directly: ```json { "mcpServers": { "openmed-container": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "openmed-hf-cache:/root/.cache/huggingface", "openmed-mcp:local" ] } } } ``` For a local Streamable HTTP endpoint, override the image's default command. The server must listen on all container interfaces, while the published port remains limited to host loopback: ```bash docker run --rm \ -p 127.0.0.1:8081:8081 \ -v openmed-hf-cache:/root/.cache/huggingface \ openmed-mcp:local \ --transport streamable-http \ --host 0.0.0.0 \ --port 8081 \ --streamable-http-path /mcp ``` The equivalent Compose service includes the same loopback port binding, a listener health check, and a persistent model cache: ```bash docker compose up --build mcp ``` Connect remote-style local clients to `http://127.0.0.1:8081/mcp`. Set `OPENMED_MCP_PORT` before starting Compose to select a different host port; the container endpoint remains on port `8081`. ## Local stdio connections Stdio is the recommended transport when the MCP client and OpenMed run on the same machine. The client launches the server as a child process, so no TCP port is exposed. ### JSON command-map clients Use this shape for desktop and IDE clients that accept an `mcpServers` command map: ```json { "mcpServers": { "openmed": { "command": "uvx", "args": [ "--from", "openmed[mcp]", "openmed-mcp", "--transport", "stdio" ] } } } ``` If OpenMed is already installed in a virtual environment, set `command` to the absolute path of that environment's `openmed-mcp` executable and omit the `uvx`, `--from`, and package arguments. ### TOML server-table clients Terminal coding clients commonly use a TOML server table: ```toml [mcp_servers.openmed] command = "uvx" args = ["--from", "openmed[mcp]", "openmed-mcp", "--transport", "stdio"] ``` ### Typed local blocks Clients that distinguish local and remote servers with a `type` field usually accept the equivalent typed block: ```json { "name": "openmed", "type": "stdio", "command": "uvx", "args": ["--from", "openmed[mcp]", "openmed-mcp", "--transport", "stdio"] } ``` Client field names vary, but the command and argument sequence is the same. ## Streamable HTTP connections Start a loopback-only server for a local URL-based client: ```bash openmed-mcp \ --transport streamable-http \ --host 127.0.0.1 \ --port 8081 \ --streamable-http-path /mcp ``` The MCP endpoint is `http://127.0.0.1:8081/mcp`. A typed remote configuration typically looks like this: ```json { "name": "openmed", "type": "http", "url": "http://127.0.0.1:8081/mcp" } ``` Hosted-assistant developer connectors use the same URL. They cannot reach a loopback address on your workstation; deploy through a private network or an authenticated HTTPS gateway instead of exposing the OpenMed process directly. ## Journey workflow tools and generated clients Six fixed-resource, read-only tools expose journey, cohort, dataset, registry, measure, and trial-review workflows. Their schemas are derived from the same versioned Journey page contract used by REST, GraphQL, and read-only SQL: - `openmed_read_journey` - `openmed_read_cohort` - `openmed_read_dataset` - `openmed_read_registry` - `openmed_read_measure` - `openmed_read_trial_review` Every result carries evidence identifiers, schema and immutable snapshot versions, the access-policy decision, controlled warnings, and explicit review metadata. The result contract excludes raw source text. All six tools advertise `readOnlyHint=true`, `destructiveHint=false`, and closed-world execution. The machine-readable generation contract is available at `openmed://journey-workflows`. Regenerate the Python and TypeScript client surfaces after changing a Journey workflow schema: ```bash python scripts/generate_journey_workflow_clients.py python scripts/generate_journey_workflow_clients.py --check ``` Python clients expose `journey()`, `cohort()`, `dataset()`, `registry()`, `measure()`, and `trial_review()`. The TypeScript client exposes the same names, with `trialReview()` using normal TypeScript casing. The registry document marks every tool as either state-changing or read-only. State-changing tools continue through the signed, single-use consent-receipt verification path; the read-only Journey tools never accept a receipt as a substitute for access policy. ## Governed workflow observations and review Four tools reference an action already held by a caller-injected local `GovernedMCPService`. They are registered from the canonical tool registry: | Tool | Behavior | Read-only | Destructive | | --------------------------------- | ------------------------------------------------------------------------------ | --------- | ----------- | | `openmed_workflow_preflight` | Observe capability-grant, purpose-ticket and minimum-data projection decisions | Yes | No | | `openmed_workflow_preview` | Inspect proposed effect counts without clinical values or targets | Yes | No | | `openmed_workflow_status` | Poll run phase and action-bound receipt-verification observations | Yes | No | | `openmed_workflow_request_review` | Create a human reviewer handoff after server-held consent | No | No | Each tool accepts only `request`, an object with exactly these five fields: ```json { "schema_version": "openmed.mcp.governance_request.v1", "run_id": "run_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "workflow_id": "workflow:org.example/synthetic@1.0.0", "action_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expected_state_digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ``` The three read tools may use `null` for `expected_state_digest`. Review requests require the exact current state digest. Run IDs must be opaque, and workflow IDs must be developer-owned names; neither may encode patient information. The service resolves the existing action, policy and purpose from its own custody. MCP callers cannot upload a grant, purpose ticket, approval token, consent receipt, reviewer identity, role claim or credential. Unknown fields, including inline authority, return `invalid_arguments` without echoing their values. Canonical workflow identifiers use the existing 512-character bound. Raw handler operation selection is fixed when the tool is registered; caller arguments cannot select another service method. Public errors discard foreign diagnostic fields and private exception contexts. Results use `openmed.mcp.governance_result.v1` and contain only bound run/workflow references, action/state digests, phase/outcome codes, closed decisions for `grant`, `purpose_ticket` and `projection`, bounded proposed/committed effect counts, a receipt observation, and an optional review-request digest. Receipt observations are `absent`, `unverified`, `verified`, `expired` or `conflict`; a `verified` observation reports the service's durable check for this action and does not enable execution. The three authority decisions are `allowed`, `denied` or `unavailable`. No decision field transmits authority. Configure `create_mcp_server(governance_service=...)` with trusted local custody. No governance adapter is loaded from environment variables or downloaded; an unconfigured tool returns `governance_unavailable`. Review requests additionally need `governance_consent_policy` (a receipt-required `ConsentReceiptPolicy`) and `governance_consent_receipt_provider`, a trusted local callback retrieving a human-issued, single-use consent receipt bound to the exact review tool and request. These are server configuration, not MCP arguments. The default policy has no keys and requires a receipt, so review is denied by default. A permissive legacy policy cannot weaken this boundary. Registration rejects missing or disabled governance consent enforcement, incorrect behavioral annotations and substituted governance schema versions or contracts. A review request first checks the run/action/state and terminal or denied outcomes, then verifies human-channel consent, then delegates one atomic handoff creation. The service must repeat the state comparison at dispatch. Its `ReviewerHandoffPacket` must bind the same run/workflow and contain an evidence reference with schema `openmed.agent.action.v1` and the exact action SHA-256. MCP returns only the packet digest. No tool approves, resumes, cancels or executes an action, or mutates a FHIR/OMOP target. The service retains the packet for the human channel; clinical values, receipt signatures and reviewer identities never enter an MCP result. Stale state or mismatched run/action responses return `governance_conflict`; refused state returns `governance_denied`. Missing consent returns `consent_required`, failed verification returns the existing consent error, untyped/malformed acknowledgements return `governance_invalid_result`, and unexpected adapter failures return `governance_failed`. Diagnostic messages are fixed. Adapter standard output/error is suppressed, but adapters are trusted code and must keep their own logging value-free; this is not a sandbox. A failed, expired or malformed acknowledgement after handoff creation can have unknown commit state. Reconcile with status and service custody; never retry automatically or treat the failure as proof that nothing was created. Consent is consumed before handoff dispatch. Services own durable idempotency and action authority checks, independently of MCP transport authentication. The [offline authorization matrix](https://openmed.life/docs/security/mcp-authorization-matrix/index.md) includes these tools. Synthetic real SDK sessions verify preflight, preview, review and polling without network access. The default adversarial corpus attempts inline instructions, hostile tool results, catalog substitution, delegation scope amplification and other forbidden fields through the actual dispatcher, under both strict and allow injection-guard modes; malformed authority still fails schema validation in allow mode. Its benign proposal is registered in service custody and referenced only by digest. These bounded controls do not establish universal prompt-injection resistance or clinical validation. ## Fixed-option decisions `openmed_decide` scores bounded caller-supplied options, preserves caller ordering, applies the selected calibration profile, and returns typed abstention, denial, conflict, unsupported, timeout, and failure states. It is a read-only, non-destructive, idempotent, closed-world tool. It also accepts a `question_set` of named questions over one input and reports each question's state separately. The result always requires human review and never authorizes a clinical action. Its request and result schemas are identical to the Python and REST contracts described in [Fixed-option decision API](https://openmed.life/docs/api/fixed-option-decisions/index.md). ## Canonical clinical agent workflow MCP clients can discover the `openmed-clinical-workflow` prompt, the `openmed://clinical-workflow` guidance resource, and the `openmed://clinical-workflow/golden-agent-run` synthetic fixture through the standard MCP prompt and resource listings. The `openmed://tool-registry` document also publishes a `workflows` entry with the prompt, resources, tool names, stage order, and registered artifact schema identifiers, so clients do not need to hardcode the workflow contract. The workflow de-identifies first, then executes the canonical pipeline order: `detect`, `context`, `sections`, `relations`, `ground`, `export`, and `risk`. Each stage produces a registered artifact: | Artifact | Contents allowed after the de-identification boundary | | ------------ | ------------------------------------------------------ | | `deidentify` | De-identified text and a source-text hash | | `detect` | Canonical text-free spans, model identifier, and count | | `context` | Canonical spans with clinical context metadata | | `sections` | Canonical spans and surface-free section offsets | | `relations` | Canonical spans and surface-free relation endpoints | | `ground` | Terminology codes, scores, hashes, and provenance | | `export` | Identifier-free FHIR Bundle | | `risk` | Aggregate residual-risk summary | Execution is local and has zero network egress by default. Keep source text, direct identifiers, entity surfaces, and reversible mappings inside the trusted local runtime. Anything after the de-identification boundary may carry only de-identified text, offsets, hashes, canonical spans, terminology provenance, identifier-free FHIR resources, and aggregate risk values. Do not write source text or identifiers to logs or agent traces. External-LLM-capable stages remain disabled unless an operator explicitly opts in, and they must route through the OpenMed privacy gateway. Raw source text must never cross that boundary. Grounded codes and exported resources require human review and must not automatically trigger clinical, treatment, billing, or medical-device decisions. ## Remote authentication and protocol headers The built-in MCP server does not validate API keys or bearer tokens. Never bind it to a public interface without a TLS-terminating reverse proxy or gateway that authenticates every request. Configure the client to send the gateway's bearer token, for example: ```json { "name": "openmed", "type": "http", "url": "https://openmed.example.org/mcp", "headers": { "Authorization": "Bearer ${OPENMED_MCP_TOKEN}" } } ``` Keep the token in the client's secret or environment-variable store rather than committing it to a configuration file. Streamable HTTP clients also send the `MCP-Protocol-Version` header on requests after initialization. SDK-based clients set it automatically to the version negotiated during the `initialize` exchange. If a gateway allowlists headers, forward `MCP-Protocol-Version`, `Mcp-Session-Id`, `Content-Type`, `Accept`, and `Authorization`; do not replace the negotiated protocol version with a fixed value at the proxy. ## Structured tool errors Expected OpenMed failures return structured content with `is_error: true` and the same stable code exposed by the Python API and REST service: ```json { "error": { "code": "input_error", "message": "The request input is malformed. Correct the documented field and retry.", "details": {"argument": "text"} }, "is_error": true } ``` Branch on `error.code`, not the human-readable message. Error payloads never echo tool arguments, clinical text, mappings, credentials, or upstream exception text. Security, authorization, consent, and tool-schema errors retain their existing specialized codes. See [Structured public errors](https://openmed.life/docs/api/errors/index.md) for the complete Python/REST/MCP mapping. ## Environment-variable defaults The command-line flags can also be configured with environment variables: | Variable | Default | Purpose | | ----------------------- | ----------- | ----------------------------- | | `OPENMED_MCP_TRANSPORT` | `stdio` | `stdio` or `streamable-http` | | `OPENMED_MCP_HOST` | `127.0.0.1` | HTTP bind address | | `OPENMED_MCP_PORT` | `8081` | HTTP port | | `OPENMED_MCP_PATH` | `/mcp` | Streamable HTTP endpoint path | Command-line flags override these values. Keep `OPENMED_MCP_HOST=127.0.0.1` unless an authenticated network boundary is already in place. ## Troubleshooting - **Command not found:** install the `mcp` extra and ensure the selected Python environment's executable directory is on `PATH`. - **Client starts and immediately disconnects:** keep stdio reserved for MCP protocol messages; avoid wrapper scripts that print banners to stdout. - **HTTP client receives 404:** confirm the URL includes the configured `--streamable-http-path`, which defaults to `/mcp`. - **Remote client cannot connect:** loopback is intentionally local-only. Use a private route or authenticated HTTPS gateway rather than changing the bind address without access controls. # REST Service OpenMed's FastAPI service provides shared model reuse, explicit model unloading, streaming PII extraction, asynchronous jobs, privacy-gateway egress, and SMART Backend Services ingestion. The generated OpenAPI document is the source of truth for exact request and response schemas. Its current public operations are: - `GET /health` - `GET /livez` - `GET /readyz` - `GET /models/loaded` - `GET /v1/journey/resources` - `POST /models/unload` - `POST /analyze` - `POST /ground` - `POST /brief` - `POST /profile` - `POST /pii/extract` - `POST /pii/extract/stream` - `POST /pii/deidentify` - `POST /pii/deidentify/stream` - `POST /fhir/smart-backend/ingestions` - `GET /fhir/smart-backend/ingestions/{job_id}` - `GET /fhir/smart-backend/ingestions/{job_id}/summary` - `POST /jobs` - `GET /jobs/{job_id}` - `POST /privacy-gateway/complete` - `POST /v1/decisions` - `POST /v1/systemone` - `POST /omop/load` - `POST /cohort/resolve` - `POST /v1/workflows/preflight` - `POST /v1/workflows/preview` - `POST /v1/workflows/status` - `POST /v1/workflows/review-receipts` - `POST /v1/workflows/cancel` The opt-in `GET /metrics` route is intentionally excluded from the generated schema and returns `404` unless metrics are enabled. The service includes stricter request validation, shared model/pipeline reuse, optional startup preload, bounded warm-pool residency, model keep-alive controls, optional no-PHI OpenTelemetry tracing, and a consistent application error envelope. For ready-to-run `curl` and Python `requests` snippets covering the common calls, see the task-oriented [REST API Recipes](https://openmed.life/docs/rest-recipes/index.md) page. For versioned, policy-scoped Journey resource pagination, see the [Journey Resources API](https://openmed.life/docs/api/journey-resources/index.md) guide. For large de-identification batches that should not hold a client connection open, use [Async REST Jobs & Webhooks](https://openmed.life/docs/serving/async-jobs/index.md). ## Run Locally Install the service dependencies: ```bash uv pip install -e ".[hf,service]" ``` Start the API server: ```bash python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` Keep this loopback bind for local use. Before exposing the service on a network, configure [authentication](https://openmed.life/docs/serving/authentication/index.md), TLS at the ingress or reverse proxy, and an exact trusted-host allowlist. ## Experimental multimodal preflight The single-asset `POST /experimental/multimodal/preflight` route is absent from both routing and runtime OpenAPI unless explicitly enabled. Opt in locally: ```bash OPENMED_SERVICE_EXPERIMENTAL_MULTIMODAL_PREFLIGHT=1 \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` An embedding host can instead call `create_app(experimental_multimodal_preflight=True)`; explicit `False` overrides the environment. Unset, `0`, or `false` disables the route; `1` or `true` enables it. Other flag values fail configuration without echoing their contents. The committed [OpenAPI catalog](https://openmed.life/docs/api/openapi.json) lists this opt-in operation under `x-openmed-experimental-paths`, with `x-experimental: true` and `x-enabled-by-default: false`. Its main `paths` map describes the default service for existing clients. An enabled running app includes the route in its normal OpenAPI `paths`; the default running app omits it. Send raw bytes as `Content-Type: application/octet-stream`. Supply exactly one `X-OpenMed-Manifest` header containing a strict [asset manifest](https://openmed.life/docs/multimodal/asset-manifests/index.md) JSON object, at most 8192 UTF-8 bytes. Unknown fields, duplicate JSON keys, duplicate headers, paths, free-text metadata and malformed values are rejected. Use a caller-generated opaque `asset_id`, never a filename or patient identifier. This transport avoids multipart upload spooling and requires no upload dependency. For example, this caller builds a manifest for a synthetic PNG prefix in memory: ```python import hashlib import json import requests payload = b"\x89PNG\r\n\x1a\n" + b"synthetic" manifest = { "asset_id": "synthetic-asset-1", "media_type": "image/png", "sha256": hashlib.sha256(payload).hexdigest(), "byte_size": len(payload), "width": 8, "height": 8, } response = requests.post( "http://127.0.0.1:8080/experimental/multimodal/preflight", headers={ "Content-Type": "application/octet-stream", "X-OpenMed-Manifest": json.dumps(manifest), }, data=payload, timeout=30, ) response.raise_for_status() assert response.json()["status"] == "accept" ``` A successful transport returns HTTP 200 with the exact bytes from `preflight_asset(manifest, payload).to_json()`, using the core desktop-v1 limit profile. This includes ordinary `abstain` reports: HTTP 200 does not mean asset acceptance. In particular, the current PDF manifest cannot express raster pixel budgets, so PDF can abstain with `insufficient_metadata`; REST preserves that result. Preflight checks declarations, a bounded media signature and integrity; it does not decode, redact, validate clinical content or qualify a provider. Errors use the existing `{"error":{"code":...,"message":...,"details":...}}` envelope, without input or exception details: | HTTP | Code | Trigger | | ---- | ------------------------ | -------------------------------------------------------------- | | 413 | `request_size_exceeded` | Global `OPENMED_SERVICE_MAX_REQUEST_BYTES` ceiling | | 413 | `payload_too_large` | Route body ceiling (`max_request_body_bytes` factory override) | | 400 | `request_size_invalid` | Invalid declared request length | | 415 | `unsupported_media_type` | Transport is not raw octet-stream | | 422 | `malformed_manifest` | Missing, duplicate, oversized or invalid manifest header | | 422 | `byte_count_mismatch` | Declared byte count differs from received source | | 422 | `sha256_mismatch` | Source digest differs from the manifest | Both body ceilings apply before preflight, including chunked bodies and bodies with incorrect `Content-Length`. The smaller ceiling wins. Source bytes remain in memory for the request; the adapter writes no temporary files, caches or artifacts. It loads no models, calls no providers and adds no network calls. The route follows existing service authentication settings and requires `pii:read` when authentication is enabled. Its service access logs contain only the fixed route, outcome and controlled reason codes, in both JSON and plain formats. Caller request IDs are replaced with generated IDs for this route, so failure responses and logs cannot echo identifier-bearing header values. Configure ingress/client logging separately to avoid recording headers or bodies. This experimental adapter is REST-only. Batch preflight, inference, SDK changes, authentication policy changes and autonomous clinical action are outside this surface. The report is non-diagnostic; any later consequential workflow must obtain explicit reviewer confirmation before acting on its outputs. The reference launcher configures `StructuredJsonLogFormatter` for `openmed.service.access` and disables `uvicorn.access`. It emits exactly one structured record per request (method, route template, status, duration, request id), with no raw target/query string or client address. `OPENMED_SERVICE_LOG_LEVEL=off` suppresses those records too. Custom ASGI launchers must disable raw access logs (Uvicorn: `--no-access-log`) and configure the structured logger explicitly; otherwise rejected URLs may expose PHI. Request-ID validation is separate: do not put sensitive values into `X-Request-ID`, and have a trusted ingress replace caller-provided request ids with opaque values before exposing this launch configuration publicly. ### Served-model policy Set `OPENMED_SERVICE_SERVED_MODELS` to the comma-separated model ids or registry keys that network clients may select. Requests cannot select filesystem paths, home-relative names or undeclared Hub ids. Rejection occurs before loader/path inspection and returns `422 model_not_served` without echoing the value. REST, GraphQL, gRPC, async jobs, bulk/SMART and the privacy gateway use this shared runtime policy; Python-library and CLI model selection remain unchanged. Without an explicit set, the served ids are the documented defaults `disease_detection_superclinical` and `OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1`, configured public preload ids, and the profile's public PII model id. `/models/loaded` includes `served_models` and a value-free `model_policy` self-check input. Production without an explicit set reports `served_models_not_explicit`; declare the intended set before deployment. This selection boundary does not authorize model acquisition: operators must separately provision the approved models and network policy. ## Postman Collection A ready-to-import [Postman collection](https://openmed.life/docs/api/openmed.postman_collection.json) (`docs/api/openmed.postman_collection.json`) ships with one example request per endpoint group so you can exercise the API without writing any client code. Import it into Postman (or any tool that reads the Postman v2.1 schema), then set the `base_url` collection variable to your server (it defaults to `http://127.0.0.1:8080`, matching the Python client's safe loopback default). Use an `https://` base URL for every non-loopback deployment; never send credentials or clinical data over plaintext HTTP. For an authenticated deployment, configure collection-level authorization in Postman or add either an `X-API-Key` header or an `Authorization: Bearer ` header. The collection intentionally stores no credentials. Every example body uses synthetic clinical text only — no real PHI. Keep those bodies synthetic because real patient text can persist in Postman history, console output, shared workspaces, exports, or screenshots. Before polling, copy the identifier returned by the async-job or SMART-ingestion POST request into `job_id`. The SMART request leaves `{{smart_private_key_pem}}` unresolved on purpose. Define it only in a secure local-client environment; in Postman, the secure variable can be backed by Local Vault. Escape PEM newlines as `\n` for the JSON body, and never replace the reference with a real key in a saved or exported collection. ## Python Client The service extra includes the typed sync client and its `httpx` dependency: ```bash uv pip install -e ".[hf,service]" ``` Use `OpenMedClient` against a running service: All patient-like content in the examples below is synthetic. Do not paste real patient text, reversible mappings, or credentials into documentation, issues, logs, or screenshots. ```python from openmed.service.client import OpenMedAPIError, OpenMedClient with OpenMedClient("http://127.0.0.1:8080", timeout=300.0) as client: result = client.analyze( "Patient started imatinib for CML.", model_name="disease_detection_superclinical", ) pii = client.extract_pii("Paciente: Maria Garcia", lang="es") redacted = client.deidentify( "Paciente: Maria Garcia", method="mask", ) llm = client.privacy_gateway( "Patient Maria Garcia called 555-0100.", confidence_threshold=0.9, ) loaded = client.loaded_models() ``` The client also exposes `ground()`, `profile()` and `resolve_cohort()` using the committed REST request fields. Grounding stays offline by default; the operator must provision the selected vocabulary snapshots. Profiling and cohort resolution send supplied JSONL content, never a server-side filename. ```python from openmed.service.client import ConceptAncestorRequest, OpenMedClient def review_synthetic_batch(records_jsonl, reviewed_phenotype): # The caller supplies a validated phenotype mapping and synthetic JSONL. with OpenMedClient("http://127.0.0.1:8080") as client: grounded = client.ground( "type 2 diabetes", systems=["icd10cm"], top_k=3, offline=True ) quality = client.profile( records_jsonl, completeness_floor=0.9, required_fields=["condition"] ) cohort = client.resolve_cohort( reviewed_phenotype, records_jsonl, concept_ancestors=[ConceptAncestorRequest(201826, 443238)], required_fields=["condition"], ) return grounded, quality, cohort ``` All three calls accept an opaque `request_id` and use the same `OpenMedAPIError` handling as the existing methods. The request dataclasses `GroundRequest`, `ProfileRequest`, `CohortResolveRequest` and `ConceptAncestorRequest` describe their typed wire payloads. Treat returned grounded content as protected and cohort matches as review aids, not clinical actions; do not log patient text or records. Python OpenAPI coverage is explicit: every committed path must have a method or an entry in `CLIENT_OPENAPI_EXCLUSIONS`. The deliberately excluded paths are: - `/health`, `/livez`, `/readyz`: operator-owned deployment probes. - `/omop/load`: explicit direct REST bulk-loading workflow. - `/pii/deidentify/stream`: no sync de-identification-stream wrapper yet. - `/jobs`, `/jobs/{job_id}`: no sync asynchronous-job lifecycle wrapper yet. - `/fhir/smart-backend/ingestions`, `/fhir/smart-backend/ingestions/{job_id}` and `/fhir/smart-backend/ingestions/{job_id}/summary`: operator-managed SMART ingestion workflows. The coverage test rejects a newly added OpenAPI path until it is implemented or deliberately documented in this list and the exclusion map. Non-2xx responses raise `OpenMedAPIError` with the service error `code`, `message`, optional `details`, HTTP status, and any `X-Request-ID` returned by the service or proxy: ```python try: client.unload_model("disease_detection_superclinical") except OpenMedAPIError as exc: print(exc.status_code, exc.code, exc.message, exc.request_id) ``` ## Static OpenAPI Spec The committed OpenAPI document lives at `docs/api/openapi.json`. Regenerate it after changing REST routes, request schemas, response schemas, or service metadata: ```bash .venv/bin/python scripts/export_openapi.py ``` The export command imports `openmed.service.app.create_app()`, calls `app.openapi()`, stamps `info.version` from `openmed.__version__`, and writes deterministic JSON with sorted keys. The unit test suite includes a drift guard that compares the committed artifact byte-for-byte against a fresh in-memory export. Optional profile selection (defaults to `prod`): ```bash OPENMED_PROFILE=dev python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` ## Browser and Host Allowlists The service is strict by default: - CORS is off unless `OPENMED_SERVICE_CORS_ORIGINS` is set. Cross-origin browser requests are not granted `Access-Control-Allow-Origin` by default. - Trusted host checking is always on. `OPENMED_SERVICE_TRUSTED_HOSTS` defaults to `localhost,127.0.0.1,[::1]`, so loopback clients pass and unexpected Host headers are rejected with the standard error envelope. Both variables accept comma-separated allowlists. CORS origins must be exact scheme/host/port origins and cannot use wildcards. Setting `OPENMED_SERVICE_TRUSTED_HOSTS` replaces the loopback default, so include every host the service should accept. Example browser front-end configuration: ```bash OPENMED_SERVICE_CORS_ORIGINS=http://localhost:5173 \ OPENMED_SERVICE_TRUSTED_HOSTS=127.0.0.1,localhost \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` For a reverse proxy in front of the service, configure the public browser origin and the host header forwarded to Uvicorn: ```bash OPENMED_SERVICE_CORS_ORIGINS=https://clinic-ui.example.com \ OPENMED_SERVICE_TRUSTED_HOSTS=api.example.com \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` Optional shared model preload at startup: ```bash OPENMED_SERVICE_PRELOAD_MODELS=disease_detection_superclinical,OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1 \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` `OPENMED_SERVICE_PRELOAD_MODELS` is a comma-separated list of registry aliases or full Hugging Face ids. Empty entries are ignored and duplicates are removed. Optional warm-pool resident model limit: ```bash OPENMED_SERVICE_PRELOAD_MODELS=disease_detection_superclinical \ OPENMED_SERVICE_MAX_RESIDENT_MODELS=2 \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` `OPENMED_SERVICE_MAX_RESIDENT_MODELS` bounds how many models remain resident in the shared warm-pool. When the limit is exceeded, the least-recently-used idle model is unloaded. Omit it for unbounded resident model caching. Optional default model keep-alive: ```bash OPENMED_SERVICE_KEEP_ALIVE=10m python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` `OPENMED_SERVICE_KEEP_ALIVE` accepts seconds as a number or duration strings such as `30s`, `5m`, `1h30m`, or `1d`. Omit it for indefinite caching, use `0` for unload-after-request behavior, or use request-level `keep_alive` to override the default for one call. Optional request text cap: ```bash OPENMED_SERVICE_MAX_TEXT_LENGTH=250000 python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` `OPENMED_SERVICE_MAX_TEXT_LENGTH` caps the `text` field accepted by `/analyze`, `/ground`, `/pii/extract`, `/pii/extract/stream`, `/pii/deidentify`, `/pii/deidentify/stream`, `/jobs`, and `/privacy-gateway/complete`. The default is `1,000,000` characters. Oversized requests return the standard `422` validation envelope; split larger documents client-side or route them through batch processing. Optional privacy-gateway egress endpoint: ```bash OPENMED_SERVICE_PRIVACY_GATEWAY_ENDPOINT=https://llm-proxy.example.com/complete \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` `POST /privacy-gateway/complete` refuses to call an external LLM unless `OPENMED_SERVICE_PRIVACY_GATEWAY_ENDPOINT` is configured by the operator or the FastAPI app is given an explicit `app.state.privacy_gateway_transport` callable. The request body never accepts an arbitrary URL. The gateway redacts locally, forwards only the redacted prompt, keeps the placeholder map in process memory for that request, runs an independent outbound tripwire scan, and records only PHI-free audit metadata. Optional dynamic request batching: ```bash OPENMED_SERVICE_BATCHING_ENABLED=true \ OPENMED_SERVICE_BATCH_MAX_SIZE=8 \ OPENMED_SERVICE_BATCH_MAX_WAIT_MS=25 \ OPENMED_SERVICE_BATCH_HIGH_WATERMARK=256 \ OPENMED_SERVICE_BATCH_LOW_WATERMARK=128 \ OPENMED_SERVICE_BATCH_MAX_QUEUE_WAIT_MS=1000 \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` Dynamic batching is off by default. When enabled, `/pii/extract` groups compatible requests and dispatches them through the PII batch helper; models with true batch backends get one backend batch, while model families whose batch helper falls back to per-text analysis still preserve per-request results. `/analyze` uses one backend pipeline call for compatible requests with `sentence_detection=false`; requests that need sentence segmentation or other non-batch-compatible settings are still coalesced but executed independently. `OPENMED_SERVICE_BATCH_MAX_SIZE` must be a positive integer. `OPENMED_SERVICE_BATCH_MAX_WAIT_MS` is a non-negative wait window in milliseconds. Bounded admission, high/low-watermark hysteresis, maximum queue waits, `503` responses with `Retry-After`, and aggregate metrics are described in [`Serving Backpressure`](https://openmed.life/docs/serving/backpressure/index.md). Optional request coalescing: ```bash OPENMED_SERVICE_COALESCING_ENABLED=true \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` Request coalescing is off by default. When enabled, identical concurrent `/analyze`, `/pii/extract`, and `/pii/deidentify` requests share one in-flight model computation keyed by endpoint, normalized text, and request options. The single result, or the leader error, is fanned out to all joined waiters. This is not a persistent response cache; entries are evicted shortly after completion. Optional model resilience controls: ```bash OPENMED_SERVICE_RETRY_MAX_ATTEMPTS=3 \ OPENMED_SERVICE_RETRY_BACKOFF_INITIAL_SECONDS=0.05 \ OPENMED_SERVICE_CIRCUIT_BREAKER_FAILURE_THRESHOLD=3 \ OPENMED_SERVICE_CIRCUIT_BREAKER_RECOVERY_TIMEOUT_SECONDS=30 \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` Model load and inference work is retried with bounded exponential backoff and jitter, then counted against an in-process circuit breaker keyed by resolved model/backend. While a breaker is open, model-backed endpoints return `503` with error code `circuit_breaker_open` and a `Retry-After` header. See [`Serving Resilience`](https://openmed.life/docs/serving/resilience/index.md) for the full set of knobs. Optional graceful-shutdown drain timeout: ```bash OPENMED_SERVICE_SHUTDOWN_DRAIN_SECONDS=30 python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` `OPENMED_SERVICE_SHUTDOWN_DRAIN_SECONDS` is a non-negative number of seconds. During shutdown, readiness is flipped off, new model-backed work is rejected, and the service waits up to this timeout for in-flight `/analyze`, `/pii/extract`, `/pii/deidentify`, `/pii/deidentify/stream`, and `/privacy-gateway/complete` requests to finish. The default is `30`. Optional pull-only Prometheus metrics endpoint: ```bash OPENMED_SERVICE_METRICS_ENABLED=true python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` `GET /metrics` is disabled by default and returns `404` unless `OPENMED_SERVICE_METRICS_ENABLED` is set to a truthy value such as `true` or `1` before the app starts. When enabled, the endpoint renders Prometheus 0.0.4 text exposition for aggregate request counts, request duration histograms, in-flight request count, warm-pool model load/eviction counters, and aggregate circuit-breaker state gauges. Metrics are pull-only: OpenMed does not push them to any remote service. Scrape it from a locally scoped Prometheus or sidecar, and avoid exposing it directly to untrusted networks. Metric labels are limited to static route templates and HTTP status codes; text, model outputs, entities, client identity, document content, and PHI are never used as label values. Timeouts end the client wait, not the underlying threadpool work. REST inference calls using request timeouts, GraphQL resolver calls, and batch submissions retain any concurrency permits and their shutdown-drain tokens until work finishes or fails. Drain-token and orphaned-work accounting also apply when neither a concurrency limit nor a rate limit is configured. While that work occupies a configured concurrency bound, new work returns `503 service_busy`. Parallel GraphQL resolvers require separate model slots under the same bound. The existing REST `504 timeout` response is unchanged. `openmed_service_orphaned_work` counts admitted requests with outstanding work after their HTTP wait ends, without labels or input values; it returns to zero when that work settles. Timing out does not forcibly terminate model threads. Optional MLX-LM paged KV-cache budget for long-note generation: ```bash OPENMED_SERVICE_MLX_PAGED_KV_CACHE_BUDGET=512MiB \ OPENMED_SERVICE_MLX_PAGED_KV_CACHE_PAGE_TOKENS=128 \ OPENMED_SERVICE_MLX_PAGED_KV_CACHE_CHUNK_TOKENS=512 \ OPENMED_SERVICE_MLX_PAGED_KV_CACHE_BYTES_PER_TOKEN=65536 \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` `OPENMED_SERVICE_MLX_PAGED_KV_CACHE_BUDGET` is disabled when unset. It accepts raw bytes or size suffixes such as `MiB` and `GiB`. The exact dense-equivalent context is `floor(budget / (page_tokens * bytes_per_token)) * page_tokens`. If `OPENMED_SERVICE_MLX_PAGED_KV_CACHE_WINDOW_TOKENS` is lower than that capacity, the lower window is used. Longer prompts remain bounded to the configured resident window and surface aggregate occupancy/eviction counters through `/metrics`: - `openmed_service_mlx_paged_kv_cache_occupancy_pages` - `openmed_service_mlx_paged_kv_cache_capacity_pages` - `openmed_service_mlx_paged_kv_cache_peak_pages` - `openmed_service_mlx_paged_kv_cache_eviction_total` - `openmed_service_mlx_paged_kv_cache_budget_bytes` Optional OpenTelemetry tracing: ```bash OPENMED_SERVICE_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces \ python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` Tracing is disabled by default and the OTLP exporter is created only when `OPENMED_SERVICE_TRACING_ENABLED=true` or `OPENMED_SERVICE_OTLP_ENDPOINT` is set. Request spans honor incoming W3C `traceparent` headers and include only no-PHI attributes such as route templates, status codes, request IDs, stage names, counts, labels, lengths, and durations. See [REST Tracing](https://openmed.life/docs/serving/tracing/index.md) for the full configuration contract. ## Reliability Changes - Requests now run against one shared service runtime per process, including a shared `OpenMedConfig` and bounded warm-pool loader. - Blocking inference is executed off the event loop and guarded by the active profile timeout (`prod=300s`, `test=60s`, etc.). - Streaming de-identification advances the blocking core iterator in the threadpool and applies the same active-profile timeout to the complete stream. - Text-bearing inference requests are capped before model execution to bound memory use. - Loaded model pipelines can be released manually with `POST /models/unload`. - `/privacy-gateway/complete` redacts PHI before the configured external LLM egress and re-identifies only after validating returned placeholders. - `OPENMED_SERVICE_MAX_RESIDENT_MODELS` evicts the least-recently-used idle model when mixed-model traffic exceeds the configured resident limit. - Inference requests accept `keep_alive` to schedule model unloading after the model becomes idle. - Dynamic request batching can be enabled for compatible `/analyze` and `/pii/extract` traffic with `OPENMED_SERVICE_BATCHING_ENABLED=true`. - CORS remains disabled unless exact origins are listed, and Host headers are checked against the configured trusted-host allowlist. - Identical in-flight inference requests can be coalesced with `OPENMED_SERVICE_COALESCING_ENABLED=true`. - Model load and inference work uses bounded retry and an in-process circuit breaker. Open breakers fail fast with `503` and `Retry-After`. - `/livez` reports process liveness, `/readyz` reports startup readiness, and `/health` remains the backward-compatible health alias. - Graceful shutdown rejects new model-backed requests and drains in-flight model-backed requests for up to `OPENMED_SERVICE_SHUTDOWN_DRAIN_SECONDS`. - `/metrics` is opt-in, pull-only, and exposes aggregate counts, gauges, and latency histograms without PHI-derived labels. - OpenTelemetry tracing is opt-in, honors incoming trace context, and exports only no-PHI span attributes when configured. - Application endpoint errors and invalid Host headers use one JSON envelope across validation, bad-request, timeout, and internal errors. A CORS preflight rejected by Starlette's middleware can instead use its native plain-text response. - `/pii/deidentify` still accepts the legacy `shift_dates` boolean, but it is now a deprecated alias for `method="shift_dates"`. ## Endpoints ### Governed workflows Five versioned `POST` routes inspect service-custodied actions and record review or cancellation metadata. Opaque references stay in JSON bodies rather than URLs. None of these routes dispatches, replays or compensates an effect. | Route | Required scope | Behavior | | ------------------------------- | ----------------- | --------------------------------------------- | | `/v1/workflows/preflight` | `workflow:read` | Read permission and policy findings | | `/v1/workflows/preview` | `workflow:read` | Inspect the content-free effect plan | | `/v1/workflows/status` | `workflow:read` | Read lifecycle and effect evidence | | `/v1/workflows/review-receipts` | `workflow:review` | Submit a previously consumed approval receipt | | `/v1/workflows/cancel` | `workflow:cancel` | Record cancellation intent | The routes are disabled by default. A host application must configure [existing authentication](https://openmed.life/docs/serving/authentication/index.md), inject a synchronous local `WorkflowGovernanceService`, and opt in with `WorkflowHTTPPolicy`. Passing a service alone does not enable the routes. Review submissions and cancellation have separate opt-ins. Every route requires an authenticated principal and its fixed scope, even if global route exemptions or scope overrides are configured. Disabling global authentication cannot make a workflow route public. ```python from openmed.service.app import create_app from openmed.service.governed_workflows import WorkflowHTTPPolicy # custody_service is your trusted local governance implementation. app = create_app( workflow_service=custody_service, workflow_policy=WorkflowHTTPPolicy( enabled=True, allow_review_submissions=True, allow_cancellation=True, timeout_seconds=5.0, ), ) ``` All requests require exactly these six reference fields. The identifiers below are synthetic. Inspection may set `expected_state_digest` and `request_id` to `null`; mutations require both a state digest and a fresh random request ID. ```json { "schema_version": "openmed.service.workflow_request.v1", "run_id": "run_11111111111111111111111111111111", "workflow_id": "workflow:test.example/review@1.0.0", "action_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expected_state_digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "request_id": "req_22222222222222222222222222222222" } ``` Receipt submission additionally requires `receipt`, serialized with the existing `ApprovalReceipt.to_dict()` contract. The service must verify it against its trusted custody and recheck reviewer authority, run/caller isolation, purpose/projection policy, exact action/state binding, expiry and durable idempotency atomically at commit. The v2 receipt contains only action/token digests, an `approved` code and its schema version; reviewer roles and timestamps remain private service custody. A caller-supplied digest or well-formed receipt is insufficient authority. The adapter does not issue or consume approval tokens. It binds the receipt and supplies fresh trusted clocks for verification and submission; the service owns expiry checks and the final atomic authority check. The response uses `openmed.service.workflow_response.v1`, the existing `ActionPhase`, `WorkflowOutcome` and `EffectRecord` wire vocabularies, opaque identifiers, digests and effect counts. It contains no clinical payload, credential or protected preview text. `cancellation_requested: true` acknowledges recorded intent; it does not claim an in-flight operation has stopped or undo a committed effect. Production effect execution belongs to the host's separately enabled, permission-gated dispatcher. The trusted service owns compare-and-set state and durable duplicate handling. Identical repeated mutations must return the original acknowledgement; reuse of a request ID for different content must fail. The HTTP adapter has no mutation cache or automatic retry. A timeout or unexpected service exception during a mutation returns `workflow_mutation_unknown` because its worker may continue. Inspect status through the custody service before deciding whether to repeat the exact request with the same ID. Do not interpret a transport failure as proof that a mutation was rolled back. Requests require `application/json`, no query parameters, a body at most 64 KiB, at most 256 parsed nodes and depth eight. Duplicate keys, nonfinite numbers, unknown fields and unsupported versions are refused. Responses contain at most 128 effect records and 256 KiB of serialized metadata. A service call deadline must be greater than zero and at most 30 seconds. Request bodies, receipts and responses never become access-log fields; arbitrary `X-Request-ID` values are replaced with random UUIDs before shared logging. Use opaque request IDs only. Successful workflow responses and adapter errors carry `Cache-Control: no-store`. The OpenAPI export derives exact fields, identifier grammars and enum/reason vocabularies from governance types. Native Python checks also enforce cross-field bindings, effect ordering, counts and custody, which JSON Schema cannot prove. Workflow errors use the existing `error` envelope with fixed messages and codes: | Status | Workflow codes | | ------ | --------------------------------------------------------------------------------------------------- | | 401 | `workflow_authentication_required` | | 403 | `workflow_forbidden`, `workflow_receipt_unverified` | | 409 | `workflow_conflict`, `workflow_receipt_expired`, `workflow_receipt_future`, `workflow_terminal` | | 413 | `workflow_request_too_large` | | 422 | `workflow_invalid_input` | | 502 | `workflow_invalid_result` | | 503 | `workflow_disabled`, `workflow_unavailable`, `workflow_service_failed`, `workflow_mutation_unknown` | Existing authentication middleware may return its own controlled authentication codes before the adapter runs. These offline adapter tests use synthetic custody and establish HTTP behavior, not clinical validation or a production database's durability guarantee. #### Typed workflow clients Python and TypeScript clients strictly parse the declared metadata responses, recompute preview and run-bound effect commitments, and preserve schema version, action digest, phase, outcome, receipt digest and cancellation intent. Unknown versions, extra fields, duplicate JSON keys, malformed successful responses and binding mismatches fail with fixed `WorkflowClientError` diagnostics. Errors retain controlled code/status and a validated opaque correlation ID; they do not retain server messages, details, response bodies or transport exceptions. A parsed snapshot is evidence to inspect, not clinical execution authority. ```python import threading from openmed.agent.correlation import RunId from openmed.agent.identifiers import WorkflowId from openmed.service.client import ( OpenMedClient, WorkflowClientError, WorkflowPollPolicy, WorkflowReference, ) reference = WorkflowReference( RunId.parse("run_" + "1" * 32), WorkflowId.parse("workflow:test.example/review@1.0.0"), "sha256:" + "2" * 64, ) stop = threading.Event() with OpenMedClient("http://127.0.0.1:8080") as client: try: view = client.poll_workflow( reference, policy=WorkflowPollPolicy(max_requests=20, timeout_seconds=60), stop_event=stop, ) print(view.phase.value, view.to_dict()["committed_effect_count"]) except WorkflowClientError as error: print(error.code) ``` `workflow_preflight`, `workflow_preview` and `workflow_status` make one request by default. Explicit `WorkflowReadOptions(max_attempts=3)` permits up to three inspection attempts only for transport or declared temporary service failures. `poll_workflow` makes at most 100 status requests within a five-minute deadline; it returns on `waiting-review`, `completed` or `aborted`, without accepting a receipt or requesting cancellation. A timeout/cancellation error preserves the last strictly validated view when one exists. Per-request timeouts are at most 30 seconds. Python `stop_event` is cooperative between requests, response chunks and interruptible waits; a synchronous HTTP read already in flight can run until its bounded HTTPX I/O timeout. The deadline is rechecked after each chunk and request. Custom synchronous transports must enforce their own I/O timeout. State changes require separate `workflow_submit_receipt(reference, receipt)` or `workflow_cancel(reference)` calls with both a fresh expected-state digest and random `req_` idempotency ID. They make one attempt. `mutation_outcome` is `not_attempted` before dispatch, `refused` for declared refusals, and `unknown` for transport, timeout, malformed success or ambiguous service failures. Inspect status before deciding on another explicit call after an unknown result. A locally cancelled HTTP request cannot revoke a receipt already recorded. Server cancellation records intent and does not undo committed effects. TypeScript provides the equivalent `WorkflowSnapshot`, `WorkflowReadOptions`, `WorkflowMutationOptions`, `WorkflowPollOptions` and `WorkflowClientError`, using `AbortSignal` and millisecond bounds. `workflowSubmitReceipt` preserves exact v2 receipt metadata and rejects role or timestamp fields; the client cannot infer authority from serialized metadata. A successful receipt response must acknowledge the submitted receipt digest. A successful cancellation response must report a cancellation request or an aborted phase. Transport exceptions cannot declare a mutation refused; only a validated server refusal can. Otherwise the mutation result stays unknown, and inspection must reconcile it before further action. Diagnostic metadata uses only closed codes, bounded status and correlation identifiers, and a validated last snapshot. See the [TypeScript client](https://github.com/maziyarpanahi/openmed/blob/master/clients/typescript/README.md) for runnable usage and the shared offline wire tests. Responses are bounded by 256 KiB, depth eight, 4,096 values and 128 effects; requests by 64 KiB. No client validates human custody, issues approval, executes effects or follows redirects. ### `POST /v1/systemone` The [opt-in System One privacy route](https://openmed.life/docs/api/fixed-option-decisions/#de-identifying-system-one-requests) masks state and question text before scoring. The caller needs both `pii:write` and `decisions:write`. Configure authentication, positive rate limits and local-only inference before enabling it. ### `POST /v1/decisions` Evaluates a bounded caller-supplied choice, ordering, multi-label, boolean, or scalar request and returns calibrated confidence, backend identity, typed abstention and failure states, and mandatory review metadata. The default backend is local and deterministic; operators can inject a permissively licensed encoder, cross-encoder, or small specialist backend. See the [fixed-option decision API](https://openmed.life/docs/api/fixed-option-decisions/index.md) for the canonical schemas, limits, and client examples. ### `GET /health` Health response: ```json { "status": "ok", "service": "openmed-rest", "version": "", "profile": "prod" } ``` `GET /health` remains the backward-compatible health alias. ### `GET /livez` Liveness response: ```json { "status": "ok", "service": "openmed-rest" } ``` ### `GET /readyz` Readiness response after startup preload completes: ```json { "status": "ready", "service": "openmed-rest" } ``` Before startup readiness, `/readyz` returns `503` with `error.code` set to `not_ready`. ### `GET /models/loaded` Returns currently cached model resources and idle-unload status: ```json { "default_keep_alive_seconds": 600.0, "max_resident_models": 2, "warm_models": ["disease_detection_superclinical"], "models": { "OpenMed/OpenMed-NER-DiseaseDetect-SuperClinical-434M": { "models": 0, "tokenizers": 0, "pipelines": 1, "active_requests": 0, "keep_alive_seconds_remaining": 287.4, "resident": true } } } ``` ### `POST /models/unload` Unload one inactive model: ```json { "model_name": "disease_detection_superclinical" } ``` Unload all inactive models: ```json { "all": true } ``` If a model has active requests, the service leaves it loaded and reports the active request count. ### `POST /analyze` Request body: ```json { "text": "Patient started imatinib for CML.", "model_name": "disease_detection_superclinical", "confidence_threshold": 0.0, "group_entities": false, "aggregation_strategy": "simple", "keep_alive": "5m" } ``` Returns the same shape as OpenMed `analyze_text(..., output_format="dict")`. ### `POST /brief` Build a local guarded brief with `text`, `model` (local alias), `profile` and an optional opaque `review_id`. Configure the trusted application review provider as described in [Clinical brief](https://openmed.life/docs/clinical/clinical-brief/index.md). Missing review or local model configuration fails closed. The response contains protected summary text plus value-free citations, metrics and review metadata; never log it. ### `POST /ground` Ground synthetic text or pre-extracted entity objects against caller-provisioned local terminology snapshots: ```json { "text": "Aspirin 81 mg daily", "systems": ["rxnorm"], "lang": "en", "top_k": 5, "offline": true } ``` For example: ```bash curl --fail-with-body --max-time 30 \ -X POST "http://127.0.0.1:8080/ground" \ -H "Content-Type: application/json" \ -d '{"text":"Aspirin 81 mg daily","systems":["rxnorm"],"lang":"en","top_k":5,"offline":true}' ``` `source_language` remains accepted as a compatibility alias for `lang`. Unsupported terminology systems return the standard `422` validation envelope. The route is covered by the service request-body and throttle middleware, so an oversized body returns `413` and a rate-limited request returns `429`. The route is offline by default. Restricted terminologies such as UMLS and SNOMED CT require an explicitly configured, user-licensed terminology source; OpenMed never bundles those vocabularies. ### `POST /pii/extract` Request body: ```json { "text": "Paciente: Maria Garcia, DNI: 12345678Z", "lang": "es", "use_smart_merging": true, "keep_alive": "10m" } ``` Returns the same shape as `extract_pii(...).to_dict()`. ### `POST /pii/deidentify` Request body: ```json { "text": "Paciente: Maria Garcia, DNI: 12345678Z", "method": "mask", "lang": "es", "keep_mapping": true, "keep_alive": "10m" } ``` Date shifting: ```json { "text": "Paciente: Maria Garcia, fecha: 15/01/2020", "method": "shift_dates", "date_shift_days": 30, "lang": "es" } ``` The deprecated `shift_dates: true` boolean is still accepted as an alias for `method: "shift_dates"`. Returns `deidentify(...).to_dict()`. When `keep_mapping=true` and mapping data exists, a `mapping` field is included. ### `POST /pii/deidentify/stream` Use the streaming endpoint when a client should receive safe redacted output before a long de-identification request finishes. It accepts every `/pii/deidentify` request field plus an optional `chunk_size` from `1` to `32768` characters (default `1024`): ```json { "text": "Patient Maria Garcia called 555-0100 before discharge.", "method": "mask", "lang": "en", "chunk_size": 16 } ``` The response media type is `application/x-ndjson`. Each line is one complete JSON object. Redacted output records arrive in order: ```json {"type":"chunk","index":0,"redacted_text":"Patient [NAME] called "} {"type":"chunk","index":1,"redacted_text":"[PHONE] before discharge."} {"type":"final","audit":{"span_count":2,"spans":[{"start":8,"end":20,"canonical_label":"PERSON","text_hash":"hmac-sha256:..."}],"stream":{"chunks":4,"max_buffer":4096,"max_observed_buffer":55}},"spans":[{"start":8,"end":20,"canonical_label":"PERSON","text_hash":"hmac-sha256:..."}]} ``` Concatenate `redacted_text` from records whose `type` is `chunk` to reconstruct the complete redacted document. The core carry-over buffer holds unsafe tails, so an identifier split across input chunks is not emitted partially. The final record contains global-offset spans and the aggregate audit record; these carry offsets, labels, and HMAC hashes rather than source surfaces. When `keep_mapping=true` (or the selected policy requires reversible mapping), the final record also contains the same opt-in `mapping` shape as the single-shot endpoint. Treat that mapping as PHI and do not log or persist it without the same controls used for the source document. Mapping-enabled streams use one full-document core window so placeholder numbering remains identical to the single-shot result; omit `keep_mapping` when early incremental output is the priority. Python clients can consume the response without buffering the NDJSON body: ```python import json import requests with requests.post( "http://127.0.0.1:8080/pii/deidentify/stream", json={"text": "Patient Maria Garcia called 555-0100.", "chunk_size": 16}, stream=True, timeout=310, ) as response: response.raise_for_status() for line in response.iter_lines(): if line: event = json.loads(line) if event["type"] == "chunk": consume_redacted_text(event["redacted_text"]) ``` If the configured service timeout is reached after the response has started, the last line has `type: "error"` and the standard `timeout` error fields. A client disconnect stops iteration and releases the model request. Streamed source text is never written to service logs. ### `POST /privacy-gateway/complete` Request body: ```json { "text": "Patient Maria Garcia called 555-0100.", "confidence_threshold": 0.9, "detector_confidence_floor": 0.0, "policy": "strict", "disallowed_entity_categories": [], "lang": "en", "keep_alive": "10m" } ``` The service detects PHI locally, replaces spans with `OPENMED_PHI` placeholder tokens, runs an independent outbound tripwire scan, sends only the redacted prompt to the operator-configured transport, and substitutes known placeholders back into the external response. Unknown or mangled placeholders fail closed. Successful response shape: ```json { "request_id": "4e22b0c3-4b56-4d2f-9c0d-9f2c9d331c21", "redacted_prompt": "Patient <> called <>.", "external_response": "Echo Patient <> called <>.", "reidentified_text": "Echo Patient Maria Garcia called 555-0100.", "entity_counts": { "NAME": 1, "PHONE": 1 }, "placeholder_hashes": ["..."], "audit": { "record_hash": "...", "verified": true } } ``` ### `POST /omop/load` Loads newline-delimited grounded note records into an in-memory OMOP CDM v5.4 build over the existing `openmed.interop.omop` loader and returns a PHI-free summary. `records_jsonl` carries the grounded results as a JSONL string; `validate_constraints` optionally reports CDM constraint violations. The request body carries clinical text and must be treated as PHI, but the response contains only counts, hashed note identifiers, and span offsets. Request body: ```json { "records_jsonl": "{\"document_id\": \"note-1\", \"person_id\": \"patient-1\", \"note_text\": \"Patient reports diabetes.\", \"entities\": [{\"text\": \"diabetes\", \"domain_id\": \"Condition\", \"start\": 16, \"end\": 24, \"concept_id\": 201820, \"vocabulary_id\": \"SNOMED\"}]}\n", "vocabulary_version": "SNOMED-2026", "validate_constraints": true } ``` Successful response shape: ```json { "row_counts": { "note": 1, "note_nlp": 1, "condition_occurrence": 1 }, "rejection_counts": {}, "rejected_spans": [], "source_note_hashes": ["..."], "constraint_violations": { "count": 0, "by_reason": {} } } ``` ## Error Envelope Application endpoint errors and invalid Host headers use this shape: A CORS preflight is handled before the endpoint. If Starlette rejects its origin, method, or requested headers, the response can be plain text rather than this JSON envelope. Clients should check the status and content type before decoding an error body. ```json { "error": { "code": "", "message": "human-readable summary", "details": null } } ``` Validation example: ```json { "error": { "code": "validation_error", "message": "Request validation failed", "details": [ { "field": "body.text", "message": "Text must not be blank", "type": "value_error" } ] } } ``` Failures raised by the public Python taxonomy keep their stable class code in this envelope. Input, configuration, and policy errors use HTTP 400; capability and budget errors use HTTP 503; and internal or inference errors use HTTP 500 with `details` set to `null`. See [Structured public errors](https://openmed.life/docs/api/errors/index.md) for the complete mapping and compatibility guarantees. Request-schema failures continue to use HTTP 422 and `validation_error` as shown above. Timeout example: ```json { "error": { "code": "timeout", "message": "Request exceeded configured timeout of 300 seconds", "details": { "timeout_seconds": 300 } } } ``` ## Docker Build: ```bash docker build -t openmed:local . ``` Run: ```bash docker run --rm -p 127.0.0.1:8080:8080 \ -e OPENMED_PROFILE=prod \ -e OPENMED_SERVICE_KEEP_ALIVE=10m \ -e OPENMED_SERVICE_PRELOAD_MODELS=disease_detection_superclinical \ -e OPENMED_SERVICE_MAX_RESIDENT_MODELS=2 \ -e OPENMED_SERVICE_CORS_ORIGINS=http://localhost:5173 \ -e OPENMED_SERVICE_TRUSTED_HOSTS=127.0.0.1,localhost \ openmed:local ``` ### Docker Compose Use the provided `docker-compose.yml` to build and start the service with a single command. The Compose setup publishes host port **8080**, sets `OPENMED_PROFILE=prod`, and persists the standard Hugging Face cache directory in a named volume so downloads placed in that cache are reused across restarts. `OPENMED_CACHE_DIR` is also passed through for data and deployment workflows that explicitly read it; it is not a generic `OpenMedConfig.cache_dir` override. The checked-in Compose port mapping listens on the host's interfaces. Treat it as network exposure: for local-only troubleshooting, change the mapping to `127.0.0.1:8080:8080`. Before intentional network exposure, configure authentication, TLS, and the trusted-host allowlist. ```bash docker compose up -d ``` Verify the service started correctly: ```bash docker compose ps # The STATUS column should show "(healthy)" ``` Stop the container: ```bash docker compose down ``` To remove the persisted model cache too, delete the named volume: ```bash docker compose down --volumes ``` Smoke check: ```bash curl http://127.0.0.1:8080/health ``` Optional values such as `HF_TOKEN`, `OPENMED_PROFILE`, `OPENMED_CACHE_DIR`, `OPENMED_SERVICE_PRELOAD_MODELS`, and `OPENMED_SERVICE_MAX_RESIDENT_MODELS`, `OPENMED_SERVICE_CORS_ORIGINS`, and `OPENMED_SERVICE_TRUSTED_HOSTS` can be supplied from a local `.env` file. Keep `.env` ignored and never commit secrets to version control. # REST API Recipes Copy-paste recipes for the OpenMed REST service. Each primary request below is a ready-to-run `curl` command paired with an equivalent Python [`requests`](https://requests.readthedocs.io/) snippet. Additional variants may be shown in one form; the real response shapes let callers wire up parsing and error handling in one pass. This page is the task-oriented companion to the endpoint reference in [REST Service](https://openmed.life/docs/rest-service/index.md). Use the reference for the full field-by-field contract and configuration knobs; use this page to make a successful call fast. All examples use **synthetic data only**. Never paste real patient text into a shared terminal, shell history, or issue tracker. Model-backed responses can echo the request text and detected entity text. Treat request and response payloads as PHI in real deployments: do not put them in application logs, telemetry, caches, or unencrypted artifacts. The examples print fields only because every value shown here is synthetic. ## Start the service Install the service extra and start Uvicorn: ```bash uv pip install -e ".[hf,service]" python -m openmed.service.logging --host 127.0.0.1 --port 8080 ``` The standalone Python snippets below use `requests`, which is intentionally not a server dependency. Install it explicitly in the client environment: ```bash uv pip install requests ``` The first model-backed request downloads model weights unless they are already cached. After download, inference stays local. For an air-gapped deployment, pre-seed the cache and follow the [local-only offline configuration](https://openmed.life/docs/configuration/#local-only-offline-mode). Or run the packaged container with Docker Compose (maps port `8080`, persists the Hugging Face cache in a named volume). See [REST Service — Docker Compose](https://openmed.life/docs/rest-service/#docker-compose) for the full setup: ```bash docker compose up -d ``` The checked-in Compose mapping publishes port `8080` on every host interface. For local-only use, prefer the loopback-bound Uvicorn command above or restrict the published port to loopback with the host firewall or a Compose override. Before allowing remote access, terminate TLS at a reverse proxy, enable [REST authentication](https://openmed.life/docs/serving/authentication/index.md), and restrict the trusted-host allowlist. CORS is a browser policy, not authentication or transport security. The examples below assume the service is reachable at `http://127.0.0.1:8080`. Export it once so the `curl` snippets stay short: ```bash export OPENMED_URL="http://127.0.0.1:8080" ``` The Python snippets share one base URL: ```python import requests BASE_URL = "http://127.0.0.1:8080" ``` By default the service only trusts loopback `Host` headers (`localhost,127.0.0.1,[::1]`) and CORS is off. If you call it from another host configure `OPENMED_SERVICE_TRUSTED_HOSTS`; for a browser front-end, also configure `OPENMED_SERVICE_CORS_ORIGINS` — see [Browser and Host Allowlists](https://openmed.life/docs/rest-service/#browser-and-host-allowlists). These allowlists do not encrypt or authenticate traffic; remote deployments still need HTTPS and authentication. ## Health check — `GET /health` The cheapest call to confirm the service is up. It never loads a model. ```bash curl --max-time 10 "$OPENMED_URL/health" ``` ```python response = requests.get(f"{BASE_URL}/health", timeout=10) response.raise_for_status() print(response.json()) ``` Response: ```json { "status": "ok", "service": "openmed-rest", "version": "3.2.0", "profile": "prod" } ``` `GET /health` is the backward-compatible health alias. For orchestrators, use `GET /livez` (process liveness) and `GET /readyz` (startup readiness). Before startup completes, `/readyz` returns `503` with `error.code` set to `not_ready`. ## Analyze clinical text — `POST /analyze` Run a medical NER model over free text. `model_name` defaults to `disease_detection_superclinical`; `confidence_threshold` defaults to `0.0`. ```bash curl -sS --max-time 310 -X POST "$OPENMED_URL/analyze" \ -H "Content-Type: application/json" \ -d '{ "text": "Patient started imatinib for CML.", "model_name": "disease_detection_superclinical", "confidence_threshold": 0.5 }' ``` ```python payload = { "text": "Patient started imatinib for CML.", "model_name": "disease_detection_superclinical", "confidence_threshold": 0.5, } response = requests.post(f"{BASE_URL}/analyze", json=payload, timeout=310) response.raise_for_status() result = response.json() for entity in result["entities"]: print(entity["label"], entity["text"], round(entity["confidence"], 3)) ``` Representative response (same shape as `analyze_text(..., output_format="dict")`; scores and timings vary by hardware): ```json { "text": "Patient started imatinib for CML.", "entities": [ { "text": "CML", "label": "DISEASE", "confidence": 0.957, "start": 29, "end": 32, "metadata": { "sentence_index": 0, "sentence_text": "Patient started imatinib for CML.", "sentence_start": 0, "sentence_end": 33, "span_valid": true } } ], "model_name": "disease_detection_superclinical", "timestamp": "2026-07-11T16:58:55.987165", "processing_time": 1.527, "metadata": { "sentence_detection": true, "sentence_count": 1, "sentence_language": "en", "medical_tokenizer": true, "max_length": 512 } } ``` ## Extract PII — `POST /pii/extract` Detect personally identifiable information. Unless `model_name` is set, OpenMed selects the recommended PII model for `lang`. The 42 supported PII language codes: `am`, `ar`, `as`, `bn`, `cs`, `da`, `de`, `el`, `en`, `es`, `fa`, `fr`, `gu`, `he`, `hi`, `id`, `it`, `ja`, `kn`, `ko`, `ml`, `mr`, `nl`, `no`, `or`, `pa`, `pl`, `pt`, `ro`, `ru`, `sv`, `sw`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`, `xh`, `zh`, and `zu`. Russian currently uses a documented multilingual default-model placeholder. An optional Indic NER adapter can be configured with `OPENMED_INDIC_NER_MODEL` or an explicit model; Assamese, Bengali, Gujarati, Hindi, Kannada, Malayalam, Marathi, Odia, Punjabi, Tamil, and Telugu can use it. `confidence_threshold` defaults to `0.5`. ```bash curl -sS --max-time 310 -X POST "$OPENMED_URL/pii/extract" \ -H "Content-Type: application/json" \ -d '{ "text": "Patient Jordan Ramirez, MRN 4482910, called from 555-0147.", "lang": "en", "use_smart_merging": true }' ``` ```python payload = { "text": "Patient Jordan Ramirez, MRN 4482910, called from 555-0147.", "lang": "en", "use_smart_merging": True, } response = requests.post(f"{BASE_URL}/pii/extract", json=payload, timeout=310) response.raise_for_status() for entity in response.json()["entities"]: print(entity["label"], entity["start"], entity["end"], entity["text"]) ``` Representative response (same shape as `extract_pii(...).to_dict()`; scores and timings vary by hardware): ```json { "text": "Patient Jordan Ramirez, MRN 4482910, called from 555-0147.", "entities": [ { "text": "Jordan", "label": "first_name", "confidence": 0.999, "start": 8, "end": 14, "metadata": {"span_valid": true} }, { "text": "Ramirez", "label": "last_name", "confidence": 0.999, "start": 15, "end": 22, "metadata": {"span_valid": true} }, { "text": "MRN 4482910", "label": "medical_record_number", "confidence": 0.708, "start": 24, "end": 35, "metadata": {"span_valid": true} }, { "text": "555-0147", "label": "phone_number", "confidence": 0.992, "start": 49, "end": 57, "metadata": {"span_valid": true} } ], "model_name": "OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1", "timestamp": "2026-07-11T16:58:02.718948", "processing_time": 1.772, "metadata": { "sentence_detection": true, "sentence_count": 1, "sentence_language": "en", "medical_tokenizer": true, "max_length": 512, "clinical_protection": { "source": "openmed/core/data/clinical_protect_terms.txt", "version": "clinical-protect-terms-v1", "protected_term_count": 71, "checked_spans": 2, "suppressed_spans": 0, "enabled": true } } } ``` ## De-identify text — `POST /pii/deidentify` Redact detected PII. `method` is one of `mask`, `remove`, `replace`, `hash`, or `shift_dates` (default `mask`). `keep_mapping` defaults to `false` and is intentionally omitted here. Enabling it returns original identifiers in a placeholder-to-original mapping and should be reserved for controlled, reversible workflows. `confidence_threshold` defaults to `0.7`. ```bash curl -sS --max-time 310 -X POST "$OPENMED_URL/pii/deidentify" \ -H "Content-Type: application/json" \ -d '{ "text": "Call 555-0147 to confirm the appointment.", "method": "mask", "lang": "en" }' ``` ```python payload = { "text": "Call 555-0147 to confirm the appointment.", "method": "mask", "lang": "en", } response = requests.post(f"{BASE_URL}/pii/deidentify", json=payload, timeout=310) response.raise_for_status() result = response.json() print(result["deidentified_text"]) print("redacted:", result["num_entities_redacted"]) ``` Representative abridged response (`deidentify(...).to_dict()`; scores, timings, and nested provenance metadata vary by runtime): ```json { "original_text": "Call 555-0147 to confirm the appointment.", "deidentified_text": "Call [phone_number] to confirm the appointment.", "pii_entities": [ { "text": "555-0147", "label": "phone_number", "entity_type": "phone_number", "start": 5, "end": 13, "confidence": 0.986, "redacted_text": "[phone_number]", "canonical_label": "PHONE", "sources": ["ml"], "evidence": { "raw_label": "phone_number", "language": "en", "model_id": "OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1" }, "threshold": 0.7, "action": "mask", "surrogate": "[phone_number]", "metadata": {"span_valid": true} } ], "method": "mask", "timestamp": "2026-07-11T16:58:43.445519", "num_entities_redacted": 1, "metadata": { "sentence_detection": true, "sentence_count": 1, "sentence_language": "en", "medical_tokenizer": true, "max_length": 512, "safety_sweep": { "source": "safety_sweep", "patterns_version": "safety-sweep-v1", "spans_added": 0 } }, "audit_report": null } ``` To shift dates instead of masking, use `method: "shift_dates"` with an optional `date_shift_days`: ```bash curl -sS --max-time 310 -X POST "$OPENMED_URL/pii/deidentify" \ -H "Content-Type: application/json" \ -d '{ "text": "Patient Jordan Ramirez was admitted on 2026-01-02.", "method": "shift_dates", "date_shift_days": 30, "lang": "en" }' ``` The deprecated `shift_dates: true` boolean is still accepted as an alias for `method: "shift_dates"`. ## Inspect loaded models — `GET /models/loaded` Report the warm-pool cache, resident models, and idle-unload countdown. No model is loaded by this call. ```bash curl --max-time 10 "$OPENMED_URL/models/loaded" ``` ```python response = requests.get(f"{BASE_URL}/models/loaded", timeout=10) response.raise_for_status() state = response.json() print("warm:", state["warm_models"]) print("resident cap:", state["max_resident_models"]) ``` Response immediately after an unconfigured local service starts: ```json { "default_keep_alive_seconds": null, "max_resident_models": null, "memory_budget_bytes": null, "resident_memory_bytes": 0, "pending_memory_bytes": 0, "memory_admission_wait_seconds": 0.05, "warm_models": [], "models": {} } ``` After a model-backed request, `models` contains one entry per resolved model and reports its cached resources, active requests, residency, idle-unload countdown, and memory footprint. `warm_models` lists only the configured preload set. `default_keep_alive_seconds`, `max_resident_models`, and `memory_budget_bytes` are `null` when their optional env vars are unset. ## Unload a model — `POST /models/unload` Free one inactive model, or all of them. If a model still has active requests, the service leaves it loaded and reports the count. Unload one model: ```bash curl -sS --max-time 30 -X POST "$OPENMED_URL/models/unload" \ -H "Content-Type: application/json" \ -d '{"model_name": "disease_detection_superclinical"}' ``` ```python payload = {"model_name": "disease_detection_superclinical"} response = requests.post(f"{BASE_URL}/models/unload", json=payload, timeout=30) response.raise_for_status() print(response.json()) ``` Representative response after the analyze recipe has loaded the default disease model (released resource counts vary by backend): ```json { "unloaded": true, "model_name": "OpenMed/OpenMed-NER-DiseaseDetect-SuperClinical-434M", "active_requests": 0, "loading": false, "released": {"models": 0, "tokenizers": 0, "pipelines": 1} } ``` Unload every inactive model: ```bash curl -sS --max-time 30 -X POST "$OPENMED_URL/models/unload" \ -H "Content-Type: application/json" \ -d '{"all": true}' ``` ```python response = requests.post( f"{BASE_URL}/models/unload", json={"all": True}, timeout=30 ) response.raise_for_status() print(response.json()) ``` Representative response after both an analysis pipeline and a PII pipeline were cached (released resource counts vary by backend): ```json { "unloaded": true, "released": {"models": 0, "tokenizers": 0, "pipelines": 2}, "active_models": {} } ``` Send `model_name` to unload one model or `all: true` to unload all inactive models. Sending neither returns the validation error envelope described below. Do not send both: the current schema treats `all: true` as the all-model operation when both fields are present. ## Handling errors After a request passes the configured host and CORS middleware, application endpoint errors use one JSON envelope, so a single handler covers validation, bad-request, timeout, and internal errors: ```json { "error": { "code": "validation_error", "message": "Request validation failed", "details": [ { "field": "body.text", "message": "Value error, Text must not be blank", "type": "value_error" } ], "request_id": "recipe-validation-error" } } ``` Common `error.code` values include `validation_error`, `bad_request`, `timeout`, `not_ready`, `rate_limited`, `backpressure`, `service_busy`, `circuit_breaker_open`, and `internal_error`. Authentication and privacy-gateway features add their own documented codes. `details` may be a list (validation errors), an object (for example `{"timeout_seconds": 300}`), or `null`. Every HTTP response carries an `X-Request-ID` header. Application-generated error envelopes also echo it as `error.request_id` for correlating logs; middleware rejections may provide only the response header. Reproduce the validation envelope with a blank `text`: ```bash curl -sS --max-time 60 -X POST "$OPENMED_URL/analyze" \ -H "Content-Type: application/json" \ -H "X-Request-ID: recipe-validation-error" \ -d '{"text": " "}' ``` ```python def analyze(text: str) -> dict: response = requests.post( f"{BASE_URL}/analyze", json={"text": text}, headers={"X-Request-ID": "recipe-validation-error"}, timeout=60, ) if response.status_code >= 400: error = response.json()["error"] request_id = response.headers.get("X-Request-ID") raise RuntimeError( f"{response.status_code} {error['code']}: {error['message']} " f"(request_id={request_id})" ) return response.json() analyze(" ") # raises RuntimeError with code "validation_error" ``` ## Typed Python client The `service` extra ships a typed synchronous client, `openmed.service.client.OpenMedClient`, built on `httpx`. It maps the analysis, PII, privacy-gateway, and model-cache endpoints to methods and raises `OpenMedAPIError` on any non-2xx response, so you skip the manual status checks above: ```python from openmed.service.client import OpenMedAPIError, OpenMedClient with OpenMedClient("http://127.0.0.1:8080", timeout=310.0) as client: analysis = client.analyze( "Patient started imatinib for CML.", model_name="disease_detection_superclinical", confidence_threshold=0.5, ) pii = client.extract_pii( "Patient Jordan Ramirez, MRN 4482910, called from 555-0147.", lang="en", ) redacted = client.deidentify( "Patient Jordan Ramirez was admitted on 2026-01-02.", method="mask", ) loaded = client.loaded_models() try: client.unload_model("disease_detection_superclinical") except OpenMedAPIError as exc: print(exc.status_code, exc.code, exc.message, exc.request_id) ``` `OpenMedAPIError` exposes the service error `code`, `message`, optional `details`, HTTP `status_code`, and the `request_id` from the response header (or the outgoing client request ID when the response has none). Use `client.unload_all_models()` to drop every inactive model in one call. The `310`-second model-call timeout is intentionally just above the production profile's default `300`-second service deadline, so the client can receive the service's structured timeout envelope. Raise both values together if your deployment uses a longer server deadline. ## Related pages - [REST Service](https://openmed.life/docs/rest-service/index.md) — full endpoint reference, configuration env vars, allowlists, and the Docker/Compose run path. - [REST Authentication](https://openmed.life/docs/serving/authentication/index.md) — optional API-key and bearer-token enforcement in front of these endpoints. - [Async REST Jobs & Webhooks](https://openmed.life/docs/serving/async-jobs/index.md) — for large de-identification batches that should not hold a client connection open. # Extension plugin SDK stability policy OpenMed's extension SDK lets a separately installed Python distribution provide recognizers, anonymizer providers, exporters, interop adapters, and language packs without a core-code change. The public SDK lives in `openmed.plugins` and uses canonical `OpenMedSpan` records at every span-producing boundary. Importing `openmed` does not import `openmed.plugins`, enumerate entry points, or import plugin dependencies. Discovery is local, lazy, and process-scoped. Installing a plugin is a user decision; discovery never downloads or installs packages. ## Package and entry-point contract Plugin distributions publish one or more components through the stable `openmed.plugins` entry-point group: ```toml [project.entry-points."openmed.plugins"] example = "example_openmed_plugin:plugin_components" ``` The referenced object may be one component, a zero-argument factory, or an iterable of components. Each component exposes static `metadata` as a `PluginComponentMetadata` instance or mapping. A minimal recognizer factory is: ```python from openmed.core.schemas.span import OpenMedSpan class ExampleRecognizer: metadata = { "plugin_id": "example-openmed-plugin", "component_id": "example-recognizer", "kind": "recognizer", "sdk_version": "1.0.0", "license": "Apache-2.0", "network_egress": False, "labels": ("PERSON",), "languages": ("en",), "metadata": {"stage": "fast_pii"}, } def recognize(self, text: str, **kwargs) -> tuple[OpenMedSpan, ...]: return () def plugin_components() -> tuple[ExampleRecognizer, ...]: return (ExampleRecognizer(),) ``` ### Stable metadata | Field | Contract | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `plugin_id` | Non-empty stable distribution identifier. It must not contain `:`. | | `component_id` | Non-empty identifier unique within the plugin. It must not contain `:`. | | `kind` | One supported component kind from the table below. | | `sdk_version` | Semantic version of the SDK contract targeted by the component. | | `license` | SPDX-like license expression. Unknown or restricted expressions require opt-in. | | `network_egress` | Boolean declaring whether the component may make network calls. | | `labels` | Canonical OpenMed labels emitted or handled by the component. Recognizers and anonymizer providers must declare at least one. | | `languages` | Normalized language tags supported by the component, or `*`. | | `name` and `description` | Optional human-readable component information. | | `metadata` | Optional static, non-PHI mapping. Recognizers may select `deterministic`, `fast_pii`, or `clinical_phi` with `stage`. | The stable qualified identifier is `plugin_id:component_id`. Registry reports, detector provenance, interop registrations, and MCP tool documents retain this identifier without including input text. ## Component protocols The versioned protocols are defined in `openmed.plugins.protocols`. | Kind | Required public behavior | | --------------------- | ------------------------------------------------------------------------------------------------------------------ | | `recognizer` | `recognize(text, **kwargs)` returns canonical `OpenMedSpan` values with offsets into `text`. | | `anonymizer_provider` | `replacement_for(span, surface, **kwargs)` returns replacement text without retaining or logging `surface`. | | `exporter` | `export(spans, **kwargs)` returns text, bytes, or structured records without adding source surfaces. | | `interop_adapter` | `to_openmed_spans(payload, **kwargs)` and `from_openmed_spans(spans, **kwargs)` translate through canonical spans. | | `language_pack` | `language_code()` and `canonical_labels()` declare routing and span capabilities. | Recognizer and interop outputs must use valid character offsets, canonical labels, finite scores, and privacy-safe evidence and metadata. Components must not persist the source text or raw PHI. OpenMed rewrites document identity, text hashes, and recognizer provenance before pipeline arbitration. ### Anonymizer provider example An anonymizer provider is routed by its declared canonical labels and languages. It receives the source span and surface only while replacement is running. The configured Faker instance and resolved locale are available in keyword arguments, so seeded anonymizers remain deterministic: ```toml [project.entry-points."openmed.plugins"] example = "example_openmed_plugin:plugin_components" ``` ```python class ExampleIdProvider: metadata = { "plugin_id": "example-openmed-plugin", "component_id": "example-id-provider", "kind": "anonymizer_provider", "sdk_version": "1.0.0", "license": "Apache-2.0", "network_egress": False, "labels": ("ID_NUM",), "languages": ("en",), } def replacement_for(self, span, surface, **kwargs): faker = kwargs["faker"] return f"SYN-{faker.random_int(min=100000, max=999999)}" def plugin_components(): return (ExampleIdProvider(),) ``` The replacement must be a non-empty string and must not contain the source surface. Exceptions and invalid replacements produce a PHI-safe warning and fall back to the built-in generator. When multiple accepted providers cover the same label and locale, the lowest qualified component id wins. ### Provider registrar compatibility Provider-only packages may use the original `openmed.providers` entry-point group when they already integrate through the public anonymizer registration APIs. The target is either a zero-argument registrar or a Faker `BaseProvider` subclass: ```toml [project.entry-points."openmed.providers"] acme_ids = "acme_openmed_provider:register" ``` ```python from faker.providers import BaseProvider from openmed.core.anonymizer import ( register_clinical_provider, register_label_generator, ) class AcmeIdProvider(BaseProvider): def acme_id(self) -> str: return self.generator.numerify("ACME-#####") def generate_acme_id(faker, original: str, *, locale: str) -> str: del original, locale return faker.acme_id() def register() -> None: register_clinical_provider(AcmeIdProvider) register_label_generator("ID_NUM", generate_acme_id) ``` This compatibility group is discovered lazily and once per process before the first anonymizer generator lookup. A failing registrar emits a warning with only its entry-point name and exception type, then built-in anonymization continues. New packages should prefer `openmed.plugins`: its metadata, protocol-version, label, license, and network-policy checks run before a component reaches the anonymizer runtime. ## Discovery, quarantine, and policy opt-in Call `openmed.plugins.discover_plugins()` to receive a `PluginDiscoveryResult`. Accepted components appear as `PluginRegistration` records. A broken or incompatible component is isolated as a `PluginQuarantineRecord`; it does not crash discovery or prevent other plugins from loading. Quarantine records expose a stable `reason`, a safe `message`, entry-point and component identifiers when available, and detached static metadata. Reasons include invalid metadata or labels, unknown component kinds, duplicate ids, load failures, SDK-major mismatches, and local-first policy rejections. The default policy auto-loads only components that declare no network egress and whose complete license expression is permissive. Opt-in is explicit and local to the call: ```python from openmed.plugins import discover_plugins result = discover_plugins( opt_in_plugins=("example-openmed-plugin:remote-exporter",), ) ``` Callers may instead use `allow_network_egress=True` or `allow_non_permissive_licenses=True` when they intentionally accept every plugin in that policy class. These flags do not change the safe process default. ## Runtime integration Validated recognizers are adapted into `DetectorSpec` records on the first detector lookup. Their spans run in the declared pipeline stage and participate in the same arbitration, provenance rewriting, and privacy-safe metadata filtering as first-party spans. Validated anonymizer providers are adapted into the label-generator registry on the first `Anonymizer.surrogate()` lookup. Discovery is process-scoped and idempotent. A caller that intentionally enables a policy-restricted provider can wire it before first use: ```python from openmed import discover_anonymizer_provider_plugins discover_anonymizer_provider_plugins( opt_in_plugins=("example-openmed-plugin:example-id-provider",), ) ``` Validated exporters and interop adapters are registered lazily with: ```python from openmed.interop import available_adapters, get_adapter names = available_adapters(include_plugins=True) exporter = get_adapter("example-openmed-plugin:example-exporter") ``` A component may also expose `openmed_tools` declarations built from `openmed.mcp.tool_registry.PluginTool`. Valid plugin tools appear beside first-party tools on the MCP registry's first lookup, retain plugin provenance in rendered tool documents, and route through the registered handler. The older `openmed.detectors` / `DetectorSpec` entry point remains a supported compatibility surface for detector-only packages. New multi-component packages should use `openmed.plugins` so SDK-version, label, license, and network policy validation happens before runtime registration. ## Local-first requirements Every plugin must preserve OpenMed's privacy defaults: - no telemetry or background network calls by default; - no automatic model, package, or dataset download during import or discovery; - no raw PHI in logs, exceptions, caches, temporary files, traces, or exports; - remote services remain disabled until the caller explicitly opts in; - credentials and restricted datasets remain user-supplied and are not bundled; - optional dependencies fail clearly only when their component is selected. Plugin code executes in the OpenMed process after installation and opt-in. The registry validates compatibility and policy declarations; it is not a sandbox for untrusted code. ## Conformance kit and example package `examples/openmed-plugin-example` is a copyable Apache-2.0 distribution with a deterministic toy recognizer, a privacy-safe exporter, installed entry-point metadata, and synthetic self-certification tests. Run its conformance gate offline from the repository root: ```bash PYTHONPATH="examples/openmed-plugin-example/src${PYTHONPATH:+:${PYTHONPATH}}" \ python -m openmed.plugins.conformance \ openmed_example_plugin:plugin_components PYTHONPATH="examples/openmed-plugin-example/src${PYTHONPATH:+:${PYTHONPATH}}" \ python -m pytest \ examples/openmed-plugin-example/tests/test_conformance.py -q ``` The example's malformed synthetic fixture fails with the stable reason `invalid_metadata` and message `network_egress must be a boolean`. The conformance kit exercises each component protocol with synthetic values and does not enumerate installed packages, open sockets, or persist source text. ## Semantic-versioning policy `PLUGIN_SDK_VERSION` follows Semantic Versioning. The registry accepts valid plugin SDK versions with the supported major version and quarantines a different major as `protocol_version_mismatch`. The following changes require an SDK major-version increment unless a prior deprecation path preserves compatibility: - renaming or removing the `openmed.plugins` entry-point group; - removing or renaming a stable metadata field or component kind; - making an optional field required or changing its accepted value shape; - changing a required component method, arguments, or return contract; - changing `OpenMedSpan` offset or canonical-label semantics; - rejecting a component shape or policy declaration that was previously valid; - removing stable quarantine reason codes or plugin provenance fields; - weakening local-first, no-telemetry, or no-raw-PHI defaults. Additive component kinds, optional fields with compatible defaults, canonical labels, safe return conveniences, and runtime bridges may ship in an SDK minor release. Documentation corrections and stricter rejection of inputs that were already invalid may ship in a patch release. Deprecated fields remain available for at least two minor releases, emit a `DeprecationWarning`, identify their replacement, and appear in the changelog before removal. Before widening an OpenMed dependency range, plugin authors should run the conformance kit against the oldest and newest supported OpenMed releases, test installed entry-point discovery, cover positive, negative, overlap, Unicode, and invalid-span inputs, and confirm that offline execution emits no source surface in logs or artifacts.