/building-with-openmed

name: building-with-openmed
description: "Orient and bootstrap any project that uses OpenMed, the on-device clinical and biomedical NLP library, for named-entity recognition, PHI de-identification, FHIR export, and evaluation. Use when the user mentions OpenMed, wants to install it, asks which OpenMed capability or model fits a task, or is starting to build a clinical/medical text pipeline and needs the right entry point."
license: Apache-2.0
metadata:
  project: OpenMed
  category: openmed-core
  pairs: adjacent
  version: "1.0"

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):

| Task | Skill / API | | --- | --- | | Find and load a model | `loading-openmed-models`, `choosing-openmed-models` | | Run clinical/biomedical NER | `extracting-clinical-entities` (`openmed.analyze_text`) | | Zero-shot NER (no fine-tune) | `running-zeroshot-ner` (`openmed zero`) | | Remove / mask PHI | `deidentifying-clinical-text` (`openmed.deidentify`) | | Detect PHI spans only | `extracting-pii-entities` (`openmed.extract_pii`) | | Restore masked PHI | `reidentifying-text` (`openmed.reidentify`) | | Pick a privacy policy | `configuring-privacy-policies` (7 bundled profiles) | | Non-English PHI | `deidentifying-multilingual-text` | | Signed, no-PHI audit | `auditing-deidentification-runs` (`audit=True`) | | Negation / temporality | `resolving-clinical-context` (`openmed.clinical`) | | Evaluate with leakage gates | `evaluating-with-leakage-gates` (`openmed.eval`) | | FHIR R4 export | `exporting-to-fhir` (`openmed.interop`) | | Serve REST / MCP | `serving-openmed-rest-api`, `deploying-openmed-mcp` | | Run on Apple Silicon / edge | `running-openmed-ondevice` (MLX / CoreML / ONNX) |

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.