Quick Start¶

This guide gets you from a blank workstation to copying results from the docs within minutes. It uses uv for dependency management, but any Python 3.11+ environment works.

1. Bootstrap the environment¶

macOS/LinuxWindows PowerShell

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

uv pip install ".[hf,gliner]"      # add GLiNER + transformers
uv pip install ".[dev]"            # pytest + coverage + linting

For scanned images and document OCR, install the multimodal extra plus the system Tesseract binary:

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:

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:

from openmed.interop.cda import redact_cda

redacted_xml = redact_cda("synthetic_ccda.xml", date_shift_days=30)

On an Apple Silicon Mac, you can start directly on the new MLX path:

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:

uv pip install ".[hf,mlx,docs]"

2. Run `analyze_text`¶

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:

uv run python examples/pii_model_comparison.py

3. De-identify PII¶

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 for a runnable example of each, plus how to reverse one with reidentify().

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

5. Optional: pin configuration¶

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.