Skip to content

agent-usage.md

Latest commit

 

History

History
222 lines (166 loc) · 7.21 KB

agent-usage.md

File metadata and controls

222 lines (166 loc) · 7.21 KB
Raw

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

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

  3. Never place raw PHI in logs, traces, cache keys, temporary filenames, exception messages, analytics, or audit artifacts.

  4. Keep audit evidence PHI-free: store offsets, canonical labels, thresholds, provenance, counts, and keyed hashes rather than identifier text.

  5. Use synthetic data in examples and committed fixtures. Never commit DUA-gated corpora or restricted terminology assets.

  6. Validate direct-identifier recall, critical leakage, span integrity, and quantized-model deltas. Aggregate F1 alone is not a privacy gate.

  7. Treat de-identification as a technical control, not a compliance guarantee or an automated clinical decision.

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