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.

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:

python -m pip install "openmed[hf]"

Add optional surfaces only when the application needs them:

python -m pip install "openmed[hf,mcp,service]"

Three primary calls¶

Analyze clinical text¶

Use analyze_text for clinical or biomedical named-entity recognition.

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.

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.

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¶

Use the API reference for signatures and the feature map 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.
2. Use offline mode after approved models are cached:

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.
2. Keep audit evidence PHI-free: store offsets, canonical labels, thresholds, provenance, counts, and keyed hashes rather than identifier text.
3. Use synthetic data in examples and committed fixtures. Never commit DUA-gated corpora or restricted terminology assets.
4. Validate direct-identifier recall, critical leakage, span integrity, and quantized-model deltas. Aggregate F1 alone is not a privacy gate.
5. Treat de-identification as a technical control, not a compliance guarantee or an automated clinical decision.
6. Keep reversible mappings encrypted and separate, or leave keep_mapping=False.

See No-Raw-PHI Logging, No-Telemetry Guarantee, and the redactor threat model for the full controls.

MCP server and tool registry¶

Install and launch the local stdio server:

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

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:

openmed models list
openmed models info disease_detection_superclinical

Run the three primary paths:

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 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.