building-with-openmed

Building with OpenMed

OpenMed is an Apache-2.0, local-first Python library for clinical and biomedical NLP. Models download once from the Hugging Face Hub and then run fully on-device — no network calls, no telemetry, no raw PHI in logs, caches, or temp files. This skill is the map: it tells you what OpenMed can do and which focused skill (or API) to reach for next.

When to use this skill

Use it to scope a task and pick an entry point. For the actual work, hand off to the focused OpenMed skills (each is grounded in the real API):

Install

pip install openmed                 # core: NER + de-identification
pip install "openmed[hf]"           # add Hugging Face model downloads
pip install "openmed[mcp]"          # Model Context Protocol server
pip install "openmed[service]"      # FastAPI REST service
pip install "openmed[mlx]"          # Apple Silicon acceleration
pip install "openmed[presidio]"     # Microsoft Presidio bridge

Extras map to capabilities: cli, mcp, service, presidio, spacy, langchain, gliner (zero-shot), multimodal/ocr-paddle (document intake), mlx/coreml/onnx (on-device backends), hf (model hub), dev (tests/lint).

The three core calls

import openmed

# 1) Named-entity recognition (token classification)
result = openmed.analyze_text(
    "Patient prescribed 500 mg metformin for type 2 diabetes.",
    model_name="disease_detection_superclinical",  # registry key, HF id, or local path
    output_format="dict",                           # dict | json | html | csv
)

# 2) De-identify PHI (mask | remove | replace | hash | shift_dates)
deid = openmed.deidentify(
    "John Doe (MRN 12345) seen on 2024-03-02.",
    method="replace",
    policy="hipaa_safe_harbor",   # bundled policy profile
)
print(deid.deidentified_text)     # PHI removed; deid.pii_entities lists the spans

# 3) Detect PHI spans without changing the text
pii = openmed.extract_pii("Call Dr. Smith at 617-555-0123.")  # PredictionResult
spans = pii.entities                                          # the PHI spans

analyze_text and deidentify are the workhorses. Everything else (multilingual, audit, policies, FHIR, eval) layers on top of these.

Discover what is available at runtime

Never hardcode model lists or language counts — query them:

import openmed
openmed.list_model_categories()          # e.g. Privacy, Disease, Oncology, Genomics ...
openmed.get_models_by_category("Disease")
openmed.get_pii_models_by_language("es")
from openmed.core.pii_i18n import SUPPORTED_LANGUAGES   # de-id language set

CLI equivalents: openmed models list, openmed models info <key>, openmed analyze --text "<text>" --model <key> --format json. MCP/REST expose the same surface as tools (openmed_analyze_text, openmed_deidentify, openmed_list_models, …).

Non-negotiable rules when building with OpenMed

• Local-first. Do not add cloud calls to PHI workflows. Models run on-device after a one-time download.
• No raw PHI in artifacts. Logs, caches, audit reports, and error messages must use offsets, hashes, and labels — never plaintext identifiers. Use audit=True for tamper-evident, no-PHI audit output.
• Permissive licensing only. Do not bundle UMLS, SNOMED CT, CPT, MIMIC, i2b2, or n2c2 assets. Call restricted terminologies out-of-process with the user's own credentials.
• De-identification is verified, not assumed. Gate on leakage with openmed.eval, not on F1 alone (see evaluating-with-leakage-gates).
• Clinical safety. OpenMed assists; it does not make autonomous clinical decisions. Surface disclaimers for any borderline medical-device behavior.

A typical pipeline

ingest (HL7v2 / FHIR / C-CDA / OCR)
   → de-identify (openmed.deidentify, policy=…)
   → extract entities (openmed.analyze_text)
   → ground to terminology (out-of-process: RxNorm / LOINC / SNOMED)
   → assemble FHIR (openmed.interop)
   → evaluate (openmed.eval leakage gates)

Each stage has a companion skill in this directory. Start here, then jump to the stage you need.