Skip to content
Back to search

openmed-skills

MarketplaceWorks with Claude CodeGitHub

Local-first healthcare AI: clinical NER and HIPAA PII de-identification on hardware you control. 2,200+ medical models, 35 model-backed PII languages, and Python, MLX, Android and browser runtimes. Apache-2.0 SDK.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/maziyarpanahi/openmed with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/maziyarpanahi/openmed'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/maziyarpanahi--openmed/badge.svg)](/listings/maziyarpanahi--openmed)

HTML

<a href="/listings/maziyarpanahi--openmed"><img src="/api/listings/maziyarpanahi--openmed/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Core + Hugging Face runtime (Linux, macOS, Windows; CPU or CUDA)
pip install --upgrade "openmed[hf]"

# Add the REST service
pip install --upgrade "openmed[hf,service]"

# Apple Silicon acceleration (MLX)
pip install --upgrade "openmed[mlx]"

Expected result:

Successfully installed openmed-...

<table> <tr> <td width="33%" valign="top">

**Python API**

from openmed import analyze_text

result = analyze_text(
  "Patient received 75mg "
  "clopidogrel for NSTEMI.",
  model_name=
  "pharma_detection_superclinical",
)
print([(e.label, e.text) for e in result.entities])

Example output:

[('DRUG', 'clopidogrel'), ('CONDITION', 'NSTEMI')]

</td> <td width="33%" valign="top">

**REST service**

python -m openmed.service.logging \
  --host 0.0.0.0 --port 8080

Example output:

INFO:     Uvicorn running on http://0.0.0.0:8080
GET /health -> 200 OK

`GET /health` `POST /analyze` `POST /pii/extract` `POST /pii/deidentify`

</td> <td width="33%" valign="top">

**Batch**

from openmed import BatchProcessor

p = BatchProcessor(
  model_name=
  "disease_detection_superclinical",
  group_entities=True,
)
results = p.process_texts([...])
print(len(results), sum(len(r.entities) for r in results))
print([(e.label, e.text) for e in results[0].entities[:1]])

Example output:

3 7
[('DISEASE', 'leukemia')]

</td> </tr> </table>

**Browser / WebGPU**

Package ONNX token-classification exports for in-browser inference through Transformers.js:

python -m openmed.onnx.convert \
  --model dslim/bert-base-NER \
  --output dist/example-onnx \
  --include-transformersjs

Example output:

Exported Transformers.js bundle to dist/example-onnx
import { pipeline } from "@huggingface/transformers";

const detector = await pipeline(
  "token-classification",
  "/models/openmed-pii/transformersjs",
  { device: "webgpu" },
);
const entities = await detector("Patient Casey Example called 212-555-0198.");
console.log(entities.slice(0, 2));

Example output:

[
  { entity: "NAME", word: "Casey Example", score: 0.99 },
  { entity: "PHONE", word: "212-555-0198", score: 0.98 },
]

[Transformers.js export guide](docs/export-transformersjs.md)

**Offline / air-gapped?** Point `model_name` (or `model_id`) at a local directory and OpenMed loads it without contacting the Hugging Face Hub:

from openmed import OpenMedConfig, analyze_text

result = analyze_text(
    "Patient presents with chronic myeloid leukemia and Type 2 diabetes.",
    model_id="./models/OpenMed-NER-DiseaseDetect-SuperClinical-434M",
    config=OpenMedConfig(device="cpu"),
)
for entity in result.entities:
    print(f"{entity.label:<12} {entity.text:<28} {entity.confidence:.2f}")

Example output:

DISEASE      chronic myeloid leukemia     0.98
DISEASE      Type 2 diabetes              0.96

Because `model_id` points to a local directory, this example does not contact the Hugging Face Hub or any external model provider.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 94 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "openmed-skills",
  3. "owner": {
  4. "name": "OpenMed"
  5. },
  6. "metadata": {
  7. "description": "Skills for building clinical & biomedical NLP pipelines with OpenMed",
  8. "version": "1.0.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "openmed-skills",
  13. "description": "De-identify PHI, run clinical NER, export FHIR, evaluate with leakage gates, and the healthcare workflows around them.",
  14. "source": "./",
  15. "strict": false,
  16. "skills": [
  17. "./skills/annotating-variants",
  18. "./skills/ask-openmed",
  19. "./skills/assembling-fhir-bundles",
  20. "./skills/auditing-deid-leakage",
  21. "./skills/auditing-deidentification-runs",
  22. "./skills/auditing-part11-trails",
  23. "./skills/auditing-safe-harbor-checklist",
  24. "./skills/auditing-subgroup-fairness",
  25. "./skills/authoring-model-cards",
  26. "./skills/batch-processing-clinical-text",
  27. "./skills/benchmark-pii-recall",
  28. "./skills/benchmarking-clinical-ner",
  29. "./skills/bridging-presidio-and-spacy",
  30. "./skills/building-gold-corpus",
  31. "./skills/building-patient-timelines",
  32. "./skills/building-with-openmed",
  33. "./skills/checking-hipaa-compliance",
  34. "./skills/choosing-openmed-models",
  35. "./skills/coding-hcc-risk-adjustment",
  36. "./skills/coding-icd10",
  37. "./skills/computing-ecqms",
  38. "./skills/configuring-privacy-policies",
  39. "./skills/defining-cohort-phenotypes",
  40. "./skills/deidentify-a-dataset",
  41. "./skills/deidentifying-clinical-text",
  42. "./skills/deidentifying-multilingual-text",
  43. "./skills/deploying-openmed-mcp",
  44. "./skills/detecting-pv-signals",
  45. "./skills/enforcing-nophi-logging",
  46. "./skills/etl-to-omop-cdm",
  47. "./skills/evaluating-with-leakage-gates",
  48. "./skills/exporting-bulk-fhir",
  49. "./skills/exporting-to-fhir",
  50. "./skills/extract-clinical-entities-to-fhir",
  51. "./skills/extracting-clinical-entities",
  52. "./skills/extracting-dicom-metadata",
  53. "./skills/extracting-lab-tables",
  54. "./skills/extracting-pii-entities",
  55. "./skills/extracting-sdoh",
  56. "./skills/fetching-fhir-resources",
  57. "./skills/gating-deid-leakage",
  58. "./skills/generating-synthea-data",
  59. "./skills/generating-synthetic-surrogates",
  60. "./skills/ingesting-clinical-documents",
  61. "./skills/linking-umls-concepts",
  62. "./skills/loading-openmed-models",
  63. "./skills/mapping-loinc",
  64. "./skills/mapping-to-snomed",
  65. "./skills/mining-pubmed-literature",
  66. "./skills/normalizing-rxnorm",
  67. "./skills/parsing-ccda-documents",
  68. "./skills/parsing-hl7v2-messages",
  69. "./skills/parsing-lab-values",
  70. "./skills/parsing-trial-eligibility",
  71. "./skills/pick-a-pii-model",
  72. "./skills/pseudonymizing-for-gdpr",
  73. "./skills/querying-openfda-labels",
  74. "./skills/querying-terminology-service",
  75. "./skills/reconciling-problem-lists",
  76. "./skills/reidentifying-text",
  77. "./skills/reporting-adverse-events",
  78. "./skills/resolving-clinical-context",
  79. "./skills/reviewing-reidentification-risk",
  80. "./skills/running-openmed-ondevice",
  81. "./skills/running-zeroshot-ner",
  82. "./skills/scaffolding-smart-on-fhir",
  83. "./skills/searching-clinicaltrials",
  84. "./skills/segmenting-clinical-sections",
  85. "./skills/serving-openmed-rest-api",
  86. "./skills/setup-openmed",
  87. "./skills/shifting-clinical-dates",
  88. "./skills/structuring-radiology-reports",
  89. "./skills/summarizing-clinical-notes",
  90. "./skills/validating-us-core"
  91. ]
  92. }
  93. ]
  94. }
README.md · README · 761 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="docs/brand/openmed-readme-banner.png" alt="OpenMed README banner with the cat mascot, lowercase wordmark, Open Cross, and the text Open-source healthcare AI, 340M+ downloads, and 10M+ installs" width="1280" />
  3. <h2>Your Data. Your Model. Your Hardware.</h2>
  4. <p><b>Turn clinical text into structured, de-identified insight on hardware you control.</b><br/>
  5. OpenMed's core local runtime performs extraction and de-identification after required model artifacts are available. Model downloads, remote-provider adapters, telemetry-enabled paths, and user-configured integrations may use a network; review each model and dataset's terms.</p>
  6. <p>
  7. <a href="https://pypi.org/project/openmed/">PyPI package</a> ·
  8. <a href="https://www.python.org/downloads/">Python 3.11+</a> ·
  9. <a href="https://huggingface.co/OpenMed">Model catalog</a> ·
  10. <a href="https://arxiv.org/abs/2508.01630">Research paper</a> ·
  11. <a href="LICENSE">Apache-2.0 SDK source</a>
  12. </p>
  13. <p>
  14. <a href="swift/OpenMedKit">OpenMedKit</a> ·
  15. <a href="docs/mlx-backend.md">Apple Silicon / MLX</a> ·
  16. <a href="docs/export-onnx-android.md">Android / ONNX Runtime Mobile</a> ·
  17. <a href="docs/export-transformersjs.md">Browser / Transformers.js</a> ·
  18. <a href="https://openmed.life/docs">Documentation</a>
  19. </p>
  20. <p>
  21. <b>2,266 manifest entries</b> &nbsp;·&nbsp; <b>35 model-backed PII languages</b> &nbsp;·&nbsp; <b>Apache-2.0 SDK</b>
  22. </p>
  23. <p>
  24. <b>English</b> ·
  25. <a href="README.zh-CN.md">简体中文</a> ·
  26. <a href="README.es.md">Español</a> ·
  27. <a href="README.fr.md">Français</a> ·
  28. <a href="README.de.md">Deutsch</a> ·
  29. <a href="README.it.md">Italiano</a> ·
  30. <a href="README.pt.md">Português</a> ·
  31. <a href="README.nl.md">Nederlands</a> ·
  32. <a href="README.ar.md">العربية</a> ·
  33. <a href="README.hi.md">हिन्दी</a> ·
  34. <a href="README.te.md">తెలుగు</a> ·
  35. <a href="README.ja.md">日本語</a> ·
  36. <a href="README.tr.md">Türkçe</a> ·
  37. <a href="README.fa.md">فارسی</a> ·
  38. <a href="README.sw.md">Kiswahili</a>
  39. </p>
  40. </div>
  41. ---
  42. ## See it in action
  43. This iPhone example uses OpenMed's local runtime after the required model artifacts are available:
  44. <div align="center">
  45. <img src="docs/brand/openmed-ios-scan.png" alt="OpenMed Scan on iPhone · on-device PII de-identification and clinical extraction via OpenMedKit" width="840" />
  46. <br/>
  47. <sub><b>On iPhone via <a href="swift/OpenMedKit">OpenMedKit</a></b>: scan a clinical note, de-identify it, and extract clinical signals with Apple MLX processing locally in this configuration.</sub>
  48. </div>
  49. <br/>
  50. <div align="center">
  51. <img src="docs/brand/openmed-pii-demo.gif" alt="OpenMed redacting PII from a clinical discharge document in real time" width="760" />
  52. <br/>
  53. <sub><b>Real-time PII de-identification</b>: in this configured local workflow, the Nemotron Privacy Filter redacts names, addresses, IDs, and billing data from a synthetic clinical discharge packet. <i>(All values shown are synthetic.)</i></sub>
  54. </div>
  55. ---
  56. ## 30-second example
  57. ```python
  58. from openmed import analyze_text
  59. result = analyze_text(
  60. "Patient started on imatinib for chronic myeloid leukemia.",
  61. model_name="disease_detection_superclinical",
  62. )
  63. for entity in result.entities:
  64. print(f"{entity.label:<12} {entity.text:<28} {entity.confidence:.2f}")
  65. # DISEASE chronic myeloid leukemia 0.98
  66. # DRUG imatinib 0.95
  67. ```
  68. A clinical NER model using the local runtime after its required artifacts are available.
  69. ---
  70. ## Clinical brief in 30 seconds
  71. From a source checkout, run the CPU-only synthetic contract demonstration:
  72. ```bash
  73. python examples/v30_clinical_brief.py
  74. # Optional: --model mlx, with the pinned model already cached on Apple silicon.
  75. ```
  76. It de-identifies an embedded note, extracts and grounds a finding, then prints
  77. a cited brief, verdicts and a value-free review packet. **NER/NLI providers are
  78. explicit synthetic test doubles, not trained-model or clinical validation.**
  79. No external note input is accepted. The MLX option may refuse unsupported output;
  80. it never bypasses the guards. See the [brief guide](docs/clinical/clinical-brief.md)
  81. and [demo script](docs/demo/clinical-brief.md) for the boundaries and local setup.
  82. ---
  83. ## Building with an agent?
  84. Start with the [consumer agent-usage guide](docs/agent-usage.md), or load the
  85. curated [llms.txt](https://openmed.life/docs/llms.txt) documentation index.
  86. For callable local interfaces, use the [MCP server](docs/mcp-clients.md), the
  87. typed [tool registry](openmed/mcp/tool_registry.py), or the
  88. [command-line interface](docs/agent-usage.md#command-line-interface). Ready-made
  89. cross-tool procedures live in the [repository skills catalog](skills/README.md).
  90. ---
  91. ## Why OpenMed?
  92. | Deployment consideration | OpenMed SDK boundary |
  93. | --- | --- |
  94. | Core runtime | Processes locally after required artifacts are available |
  95. | Optional network paths | Downloads, remote adapters, telemetry-enabled paths, and user integrations may use a network |
  96. | Validation | Deployment owners validate model and dataset terms, privacy behavior, and clinical fitness |
  97. | Interfaces | Python, Swift, Android, browser, and service surfaces where supported |
  98. - **Curated model catalog**: validate each model, license, and dataset for your use case.
  99. - **Safe Harbor-aligned configuration**: can target the 18 identifier categories; expert deployment review remains required, and use of the SDK does not itself establish HIPAA compliance.
  100. - **Supported execution paths**: CPU, CUDA, MLX, mobile, service, and browser adapters vary by environment and artifact.
  101. - **Deployment interfaces**: Python, containers, services, and batch workflows require configuration and validation.
  102. - **SDK source**: released under the Apache-2.0 License; model and dataset terms vary.
  103. ---
  104. ## On-device on Apple: Swift, MLX & iOS
  105. On supported Apple hardware, OpenMed can use **MLX** and **[OpenMedKit](swift/OpenMedKit)** for local processing after required artifacts are available. Model acquisition and any user-configured remote integrations remain separate network boundaries.
  106. ```swift
  107. // Add OpenMedKit to your app
  108. dependencies: [
  109. .package(url: "https://github.com/maziyarpanahi/openmed.git", from: "3.3.0"),
  110. ]
  111. ```
  112. Expected result: Swift Package Manager resolves OpenMedKit and makes
  113. `import OpenMedKit` available to your app target.
  114. - **MLX runtime** for PII token classification, the Privacy Filter family, experimental GLiNER-family zero-shot tasks, and Python MLX-LM text generation with Laneformer; includes a CoreML fallback path for supported token-classification artifacts.
  115. - **Portable model naming where supported**: an MLX model name can fall back to a matching PyTorch checkpoint when that mapping and artifact are available on non-Apple hardware.
  116. - **Python on Apple Silicon** too: `pip install --upgrade "openmed[mlx]"`.
  117. Guides: [MLX backend](docs/mlx-backend.md) · [OpenMedKit (Swift)](docs/swift-openmedkit.md) · [CoreML export](docs/coreml-export.md)
  118. <div align="center">
  119. <img src="docs/brand/openmed-mlx-speedup.png" alt="MLX vs CPU latency on Apple Silicon: 24 to 33 times faster" width="840" />
  120. <br/>
  121. <sub><b>MLX on Apple Silicon: 24–33× faster than CPU PyTorch</b> for the Privacy Filter: median latency per inference step, lower is better.</sub>
  122. </div>
  123. ---
  124. ## On-device on Android — Kotlin & ONNX Runtime Mobile
  125. OpenMedKit also ships as a native Android/Kotlin library for local document
  126. intake, OCR handoff, PII redaction, and token-classification inference through
  127. **ONNX Runtime Mobile**. Mobile model repositories include stable tensor names,
  128. dynamic sequence axes, tokenizer files, labels, and Android-ready fp32, fp16,
  129. INT8, and optional `.ort` outputs.
  130. Add the scoped JitPack repository in `settings.gradle.kts`:
  131. ```kotlin
  132. dependencyResolutionManagement {
  133. repositories {
  134. google()
  135. mavenCentral()
  136. maven {
  137. url = uri("https://jitpack.io")
  138. content { includeGroup("com.github.maziyarpanahi") }
  139. }
  140. }
  141. }
  142. ```
  143. Then use the immutable OpenMed `v3.3.0` release:
  144. ```kotlin
  145. dependencies {
  146. implementation("com.github.maziyarpanahi:openmed:v3.3.0")
  147. }
  148. ```
  149. See the [Android installation guide](android/README.md) for local builds and
  150. publishing details.
  151. ```kotlin
  152. val model = OpenMedKit.fromDirectory(modelDir)
  153. val entities = model.analyzeText("Patient Alice Nguyen was seen in cardiology.")
  154. ```
  155. - **Android ONNX profile** emits `model.onnx`, `model_fp16.onnx`,
  156. `model_int8.onnx`, tokenizer assets, labels, and `openmed-onnx.json`.
  157. - **ORT Mobile support** records the minimal-build operator configuration when
  158. ONNX Runtime conversion tooling is installed.
  159. - **Kotlin parity tests** keep tokenizer offsets, span boundaries, and decoder
  160. output aligned with the Python runtime.
  161. Guides: [Android ONNX export](docs/export-onnx-android.md) ·
  162. [Android span parity](docs/android-parity.md) ·
  163. [OpenMedKit Android](android/openmedkit)
  164. ### The same ONNX model on Python CPU
  165. ```python
  166. from openmed import OnnxModel
  167. model = OnnxModel.from_pretrained(
  168. "OpenMed/OpenMed-PII-ClinicalE5-Small-33M-v1-onnx-android"
  169. )
  170. entities = model("Patient Alice Nguyen was seen in cardiology.")
  171. ```
  172. ### The same ONNX model in the browser
  173. ```bash
  174. npm install openmed @huggingface/transformers
  175. ```
  176. ```typescript
  177. import { loadOnnxModel } from "openmed";
  178. const model = await loadOnnxModel(
  179. "OpenMed/OpenMed-PII-ClinicalE5-Small-33M-v1-onnx-android",
  180. );
  181. const entities = await model("Patient Alice Nguyen was seen in cardiology.");
  182. ```
  183. ---
  184. ## How it works
  185. ```mermaid
  186. flowchart LR
  187. A["Clinical text"] --> B["OpenMed<br/>(local-first)"]
  188. B --> C["Medical entities"]
  189. B --> D["PII detected"]
  190. B --> E["De-identified text"]
  191. style B fill:#0D6E6E,stroke:#0A5656,stroke-width:2px,color:#ffffff
  192. style C fill:#D6EBEB,stroke:#0D6E6E,color:#0E1116
  193. style D fill:#F7DCD8,stroke:#C5453A,color:#0E1116
  194. style E fill:#F5E27A,stroke:#A9A088,color:#0E1116
  195. ```
  196. Rendered result: a local clinical-text pipeline that returns medical entities,
  197. PII findings, and de-identified text without sending data to a cloud API.
  198. ---
  199. ## Agent Skills — build with OpenMed from your coding agent
  200. The [`skills/`](skills/) catalog ships portable [Agent Skills](https://agentskills.io) for on-device de-identification, clinical NER, FHIR export, evaluation, and the healthcare workflows around them. The same `SKILL.md` folders work in **Claude Code**, **OpenAI Codex**, **OpenCode**, and compatible agents; the installer uses each client's skills directory plus the cross-client `~/.agents/skills` convention.
  201. ```bash
  202. git clone https://github.com/maziyarpanahi/openmed && cd openmed
  203. ./install-skills.sh # installs for Claude Code, Codex, OpenCode, and ~/.agents/skills
  204. ```
  205. Then ask your agent for the pipeline using synthetic placeholders:
  206. > Build a local OpenMed pipeline that de-identifies a synthetic discharge note and extracts medication entities.
  207. It loads the right skills and produces an on-device pipeline (`openmed.deidentify(...)` → `openmed.analyze_text(...)`). After the one-time model download, run that pipeline locally on real notes; do not paste real PHI into a cloud-hosted agent prompt. See the **[skills catalog and 30-second example](skills/README.md)**.
  208. ---
  209. ## Quick start
  210. ```bash
  211. # Core + Hugging Face runtime (Linux, macOS, Windows; CPU or CUDA)
  212. pip install --upgrade "openmed[hf]"
  213. # Add the REST service
  214. pip install --upgrade "openmed[hf,service]"
  215. # Apple Silicon acceleration (MLX)
  216. pip install --upgrade "openmed[mlx]"
  217. ```
  218. Expected result:
  219. ```text
  220. Successfully installed openmed-...
  221. ```
  222. <table>
  223. <tr>
  224. <td width="33%" valign="top">
  225. **Python API**
  226. ```python
  227. from openmed import analyze_text
  228. result = analyze_text(
  229. "Patient received 75mg "
  230. "clopidogrel for NSTEMI.",
  231. model_name=
  232. "pharma_detection_superclinical",
  233. )
  234. print([(e.label, e.text) for e in result.entities])
  235. ```
  236. Example output:
  237. ```text
  238. [('DRUG', 'clopidogrel'), ('CONDITION', 'NSTEMI')]
  239. ```
  240. </td>
  241. <td width="33%" valign="top">
  242. **REST service**
  243. ```bash
  244. python -m openmed.service.logging \
  245. --host 0.0.0.0 --port 8080
  246. ```
  247. Example output:
  248. ```text
  249. INFO: Uvicorn running on http://0.0.0.0:8080
  250. GET /health -> 200 OK
  251. ```
  252. `GET /health`
  253. `POST /analyze`
  254. `POST /pii/extract`
  255. `POST /pii/deidentify`
  256. </td>
  257. <td width="33%" valign="top">
  258. **Batch**
  259. ```python
  260. from openmed import BatchProcessor
  261. p = BatchProcessor(
  262. model_name=
  263. "disease_detection_superclinical",
  264. group_entities=True,
  265. )
  266. results = p.process_texts([...])
  267. print(len(results), sum(len(r.entities) for r in results))
  268. print([(e.label, e.text) for e in results[0].entities[:1]])
  269. ```
  270. Example output:
  271. ```text
  272. 3 7
  273. [('DISEASE', 'leukemia')]
  274. ```
  275. </td>
  276. </tr>
  277. </table>
  278. **Browser / WebGPU**
  279. Package ONNX token-classification exports for in-browser inference through
  280. Transformers.js:
  281. ```bash
  282. python -m openmed.onnx.convert \
  283. --model dslim/bert-base-NER \
  284. --output dist/example-onnx \
  285. --include-transformersjs
  286. ```
  287. Example output:
  288. ```text
  289. Exported Transformers.js bundle to dist/example-onnx
  290. ```
  291. ```javascript
  292. import { pipeline } from "@huggingface/transformers";
  293. const detector = await pipeline(
  294. "token-classification",
  295. "/models/openmed-pii/transformersjs",
  296. { device: "webgpu" },
  297. );
  298. const entities = await detector("Patient Casey Example called 212-555-0198.");
  299. console.log(entities.slice(0, 2));
  300. ```
  301. Example output:
  302. ```javascript
  303. [
  304. { entity: "NAME", word: "Casey Example", score: 0.99 },
  305. { entity: "PHONE", word: "212-555-0198", score: 0.98 },
  306. ]
  307. ```
  308. [Transformers.js export guide](docs/export-transformersjs.md)
  309. **Offline / air-gapped?** Point `model_name` (or `model_id`) at a local directory and OpenMed loads it without contacting the Hugging Face Hub:
  310. ```python
  311. from openmed import OpenMedConfig, analyze_text
  312. result = analyze_text(
  313. "Patient presents with chronic myeloid leukemia and Type 2 diabetes.",
  314. model_id="./models/OpenMed-NER-DiseaseDetect-SuperClinical-434M",
  315. config=OpenMedConfig(device="cpu"),
  316. )
  317. for entity in result.entities:
  318. print(f"{entity.label:<12} {entity.text:<28} {entity.confidence:.2f}")
  319. ```
  320. Example output:
  321. ```text
  322. DISEASE chronic myeloid leukemia 0.98
  323. DISEASE Type 2 diabetes 0.96
  324. ```
  325. Because `model_id` points to a local directory, this example does not contact
  326. the Hugging Face Hub or any external model provider.
  327. ---
  328. ## Models
  329. A curated registry of specialized medical NER models; browse the [full catalog](https://openmed.life/docs/model-registry).
  330. | Model | Specialization | Entity types | Size |
  331. |-------|----------------|--------------|------|
  332. | `disease_detection_superclinical` | Disease & conditions | DISEASE, CONDITION, DIAGNOSIS | 434M |
  333. | `pharma_detection_superclinical` | Drugs & medications | DRUG, MEDICATION, TREATMENT | 434M |
  334. | `pii_superclinical_large` | PII & de-identification | NAME, DATE, SSN, PHONE, EMAIL, ADDRESS | 434M |
  335. | `anatomy_detection_electramed` | Anatomy & body parts | ANATOMY, ORGAN, BODY_PART | 109M |
  336. | `gene_detection_genecorpus` | Genes & proteins | GENE, PROTEIN | 109M |
  337. ---
  338. ## Privacy: PII detection & de-identification
  339. ```python
  340. from openmed import extract_pii, deidentify
  341. text = "Patient: John Doe, DOB: 01/15/1970, SSN: 123-45-6789"
  342. # Extract PII with smart merging (prevents tokenization fragmentation)
  343. result = extract_pii(text, model_name="pii_superclinical_large", use_smart_merging=True)
  344. print([(e.label, e.text) for e in result.entities])
  345. # De-identify with the method you need
  346. print(deidentify(text, method="mask").deidentified_text)
  347. print(deidentify(text, method="replace").deidentified_text)
  348. print(deidentify(text, method="hash").deidentified_text)
  349. print(deidentify(text, method="shift_dates", date_shift_days=180).deidentified_text)
  350. ```
  351. Example output:
  352. ```text
  353. [('NAME', 'John Doe'), ('DATE', '01/15/1970'), ('SSN', '123-45-6789')]
  354. Patient: [NAME], DOB: [DATE], SSN: [SSN]
  355. Patient: Emily Chen, DOB: 03/22/1985, SSN: 456-78-9012
  356. Patient: 6b8f...c4a1, DOB: 48b1...91de, SSN: 3f13...e912
  357. Patient: John Doe, DOB: 07/14/1970, SSN: 123-45-6789
  358. ```
  359. - **Smart entity merging** keeps `01/15/1970` whole instead of fragmenting it.
  360. - **Policy-aware pipelines** add HIPAA/GDPR/research profiles, calibrated thresholds, signed audit reports, redaction previews, and minimum-necessary action selection.
  361. - **Faker-backed obfuscation** with custom clinical-ID providers (CPF, CNPJ, BSN, NIR, Codice Fiscale, NIE, Aadhaar, Steuer-ID, NPI).
  362. - **HIPAA boundary**: Safe Harbor-aligned categories and configurable thresholds are implementation aids; expert deployment review remains required, and SDK use alone does not establish compliance.
  363. - **Batch and streaming PII**: extract or de-identify across many documents with `BatchProcessor(operation="extract_pii" | "deidentify", batch_size=16)` or incremental streaming helpers.
  364. <div align="center">
  365. <img src="docs/assets/pii-batch-benchmark.png" alt="Batch PII processing throughput: up to 3.3x on CPU and 2.2x on MLX" width="840" />
  366. <br/>
  367. <sub><b>Batch processing</b>: up to <b>3.3×</b> higher throughput on CPU and <b>2.2×</b> on MLX vs. one document at a time.</sub>
  368. </div>
  369. [Complete PII notebook](examples/notebooks/PII_Detection_Complete_Guide.ipynb) · [Smart merging](docs/pii-smart-merging.md) · [Anonymization quickstart](docs/anonymization.md#quickstart-choosing-a-method)
  370. <details>
  371. <summary><b>Privacy Filter family</b>: three model families on the OpenAI Privacy Filter architecture</summary>
  372. <br/>
  373. Same model code (gpt-oss-style sparse-MoE transformer with local attention, sink tokens, RoPE+YaRN, tiktoken `o200k_base`), different training data. All route through the **same** `extract_pii()` / `deidentify()` API; only `model_name=` changes.
  374. `openai/privacy-filter` is a Hugging Face model identifier for local weights;
  375. using it here does not call the OpenAI API.
  376. | Variant | PyTorch (CPU + CUDA) | MLX (Apple Silicon) | MLX 8-bit |
  377. | --- | --- | --- | --- |
  378. | **OpenAI Privacy Filter** | [`openai/privacy-filter`](https://huggingface.co/openai/privacy-filter) | [`OpenMed/privacy-filter-mlx`](https://huggingface.co/OpenMed/privacy-filter-mlx) | [`…-mlx-8bit`](https://huggingface.co/OpenMed/privacy-filter-mlx-8bit) |
  379. | **Nemotron-PII fine-tune** | [`OpenMed/privacy-filter-nemotron`](https://huggingface.co/OpenMed/privacy-filter-nemotron) | [`…-nemotron-mlx`](https://huggingface.co/OpenMed/privacy-filter-nemotron-mlx) | [`…-nemotron-mlx-8bit`](https://huggingface.co/OpenMed/privacy-filter-nemotron-mlx-8bit) |
  380. | **OpenMed Multilingual** | [`OpenMed/privacy-filter-multilingual`](https://huggingface.co/OpenMed/privacy-filter-multilingual) | [`…-multilingual-mlx`](https://huggingface.co/OpenMed/privacy-filter-multilingual-mlx) | [`…-multilingual-mlx-8bit`](https://huggingface.co/OpenMed/privacy-filter-multilingual-mlx-8bit) |
  381. ```python
  382. from openmed import extract_pii
  383. text = "Patient Sarah Connor (DOB: 03/15/1985) at MRN 4471882."
  384. variants = {
  385. "baseline": extract_pii(text, model_name="openai/privacy-filter"),
  386. "nemotron": extract_pii(text, model_name="OpenMed/privacy-filter-nemotron"),
  387. "mlx": extract_pii(text, model_name="OpenMed/privacy-filter-mlx"),
  388. }
  389. print([(e.label, e.text) for e in variants["baseline"].entities])
  390. ```
  391. Example output:
  392. ```text
  393. [('NAME', 'Sarah Connor'), ('DATE', '03/15/1985'), ('ID', '4471882')]
  394. ```
  395. On non-Apple-Silicon hosts, MLX model names are automatically substituted with the matching PyTorch checkpoint (with a one-time warning): reuse one model name where a matching backend artifact is available. See [Privacy Filter architecture & backend routing](docs/anonymization.md#privacy-filter-family).
  396. </details>
  397. ---
  398. ## Multilingual PII (42 supported routes; 35 model-backed)
  399. Extraction and de-identification support **42 supported PII language codes**:
  400. `am`, `ar`, `as`, `bn`, `cs`, `da`, `de`, `el`, `en`, `es`, `fa`, `fr`, `gu`, `he`, `hi`, `id`,
  401. `it`, `ja`, `kn`, `ko`, `ml`, `mr`, `nl`, `no`, `or`, `pa`, `pl`, `pt`, `ro`, `ru`, `sv`, `sw`, `ta`,
  402. `te`, `th`, `tr`, `uk`, `ur`, `vi`, `xh`, `zh`, and `zu`, with **the registry-backed PII model catalog** in total.
  403. Russian routing currently uses a documented multilingual default-model
  404. placeholder. Bengali, Chinese, and Tamil have dedicated registry entries.
  405. An optional, user-configured Indic NER family can serve Assamese, Bengali,
  406. Gujarati, Hindi, Kannada, Malayalam, Marathi, Odia, Punjabi, Tamil, and
  407. Telugu. Set `OPENMED_INDIC_NER_MODEL`; OpenMed never
  408. bundles or automatically selects those optional weights.
  409. OpenMed also includes validator-backed national-ID coverage for additional
  410. ID-only locales such as Latvian, Slovak, Malay, Filipino, and Finnish.
  411. See the [per-language guide](docs/languages.md) for each code's default PII
  412. model, Faker locale, and a before/after de-identification example.
  413. ```bash
  414. python -c "from openmed import extract_pii; print([(e.label, e.text) for e in extract_pii('Dr. Pedro Almeida, CPF: 123.456.789-09, email: pedro@hospital.pt', lang='pt').entities])"
  415. ```
  416. Example output:
  417. ```text
  418. [('NAME', 'Pedro Almeida'), ('ID', '123.456.789-09'), ('EMAIL', 'pedro@hospital.pt')]
  419. ```
  420. <details>
  421. <summary>Show per-language examples (Portuguese, Dutch, Hindi, Arabic, Japanese, Turkish)</summary>
  422. <br/>
  423. ```python
  424. from openmed import extract_pii
  425. portuguese = extract_pii("Paciente: Pedro Almeida, CPF: 123.456.789-09, telefone: +351 912 345 678", lang="pt", use_smart_merging=True)
  426. dutch = extract_pii("Patiënt: Eva de Vries, BSN: 123456782, telefoon: +31 6 12345678", lang="nl", use_smart_merging=True)
  427. hindi = extract_pii("रोगी: अनीता शर्मा, फोन: +91 9876543210, पता: नई दिल्ली 110001", lang="hi", use_smart_merging=True)
  428. arabic = extract_pii("المريضة ليلى حسن، الهاتف +20 10 1234 5678، الرقم القومي 29801011234567.", lang="ar", use_smart_merging=True)
  429. japanese = extract_pii("患者 佐藤 花子、電話 +81 90 1234 5678、マイナンバー 1234 5678 9012.", lang="ja", use_smart_merging=True)
  430. turkish = extract_pii("Hasta Ayşe Yılmaz, telefon +90 532 123 45 67, TCKN 10000000146.", lang="tr", use_smart_merging=True)
  431. for r in (portuguese, dutch, hindi, arabic, japanese, turkish):
  432. print([(e.label, e.text) for e in r.entities])
  433. ```
  434. Example output:
  435. ```text
  436. [('NAME', 'Pedro Almeida'), ('ID', '123.456.789-09'), ('PHONE', '+351 912 345 678')]
  437. [('NAME', 'Eva de Vries'), ('ID', '123456782'), ('PHONE', '+31 6 12345678')]
  438. [('NAME', 'अनीता शर्मा'), ('PHONE', '+91 9876543210'), ('ADDRESS', 'नई दिल्ली 110001')]
  439. [('NAME', 'ليلى حسن'), ('PHONE', '+20 10 1234 5678'), ('ID', '29801011234567')]
  440. [('NAME', '佐藤 花子'), ('PHONE', '+81 90 1234 5678'), ('ID', '1234 5678 9012')]
  441. [('NAME', 'Ayşe Yılmaz'), ('PHONE', '+90 532 123 45 67'), ('ID', '10000000146')]
  442. ```
  443. </details>
  444. ---
  445. ## REST API
  446. A Docker-friendly FastAPI service with request validation, shared pipeline preload, and unified error envelopes.
  447. ```bash
  448. pip install --upgrade "openmed[hf,service]"
  449. python -m openmed.service.logging --host 0.0.0.0 --port 8080
  450. # or with Docker
  451. docker build -t openmed:local .
  452. docker run --rm -p 8080:8080 -e OPENMED_PROFILE=prod openmed:local
  453. ```
  454. Example output:
  455. ```text
  456. INFO: Uvicorn running on http://0.0.0.0:8080
  457. ```
  458. ```bash
  459. curl -X POST http://127.0.0.1:8080/pii/extract \
  460. -H "Content-Type: application/json" \
  461. -d '{"text":"Paciente: Maria Garcia, DNI: 12345678Z","lang":"es"}'
  462. ```
  463. Abbreviated example response:
  464. ```json
  465. {
  466. "text": "Paciente: Maria Garcia, DNI: 12345678Z",
  467. "entities": [
  468. {"text": "Maria Garcia", "label": "NAME", "confidence": 0.99, "start": 10, "end": 22},
  469. {"text": "12345678Z", "label": "ID", "confidence": 0.98, "start": 29, "end": 38}
  470. ],
  471. "model_name": "OpenMed/privacy-filter-multilingual"
  472. }
  473. ```
  474. **Model lifecycle and service controls:** free memory on demand with
  475. `GET /models/loaded`, `POST /models/unload`, and a `keep_alive` idle window;
  476. v1.8 also includes API-key/JWT auth, no-PHI request logging, tracing, gRPC,
  477. async jobs, webhooks, warm pools, dynamic batching, request coalescing, rate
  478. and concurrency limits, `/livez`, `/readyz`, and opt-in metrics:
  479. ```bash
  480. OPENMED_SERVICE_KEEP_ALIVE=10m python -m openmed.service.logging --host 0.0.0.0 --port 8080
  481. curl -X POST http://127.0.0.1:8080/models/unload -H "Content-Type: application/json" -d '{"all":true}'
  482. ```
  483. Example response:
  484. ```json
  485. {
  486. "unloaded": true,
  487. "released": {"models": 1, "tokenizers": 1, "pipelines": 1},
  488. "active_models": {}
  489. }
  490. ```
  491. See the full [REST service guide](docs/rest-service.md).
  492. ---
  493. ## Documentation
  494. Full guides at **[openmed.life/docs](https://openmed.life/docs/)**.
  495. AI agents can load the curated [llms.txt](https://openmed.life/docs/llms.txt)
  496. index or the inlined [llms-full.txt](https://openmed.life/docs/llms-full.txt)
  497. feed. Both are regenerated from the current documentation during every strict
  498. MkDocs build.
  499. | | | |
  500. |---|---|---|
  501. | [Getting Started](https://openmed.life/docs/) | [Analyze Text](https://openmed.life/docs/analyze-text) | [Model Registry](https://openmed.life/docs/model-registry) |
  502. | [FAQ](docs/faq.md) | [Anonymization](docs/anonymization.md) | [Batch Processing](https://openmed.life/docs/batch-processing) |
  503. | [Configuration Profiles](https://openmed.life/docs/profiles) | [REST Service](docs/rest-service.md) | [MLX Backend](docs/mlx-backend.md) |
  504. | [Transformers.js Export](docs/export-transformersjs.md) | [FHIR Interop](docs/fhir-interop.md) | [HL7 v2 De-identification](docs/hl7v2-deidentification.md) |
  505. | [OpenMed 3.3.0 Migration Guide](docs/migration/3.2-to-3.3.md) | [OpenMed 2.2.0 Release Notes](docs/release/v2.2.0.md) | [Examples](docs/examples.md) |
  506. | [Release Streams](docs/release/semver-and-channels.md) | [Generative Model Policy](docs/generative-model-policy.md) | [Contributing](docs/contributing.md) |
  507. | [Security Policy](SECURITY.md) | [Compliance Posture](docs/compliance.md) | [Extension Plugin SDK](docs/plugin-sdk.md) |
  508. | [v1 to v2 Migration](docs/migration.md) | [MCP Client Connections](docs/mcp-clients.md) | [African Developer Onboarding](docs/africa-onboarding.md) |
  509. ---
  510. ## Meet the mascot
  511. <img src="docs/brand/openmed-mascot-icon.png" alt="OpenMed mascot" width="104" align="left" />
  512. OpenMed's guardian is a fluffy Persian cat styled as a tiny **Avicenna (Ibn Sina)**: the great Persian
  513. physician whose *Canon of Medicine* was the world's standard medical text for some 600 years. He keeps
  514. watch over the open book of medical knowledge, in a palette built around Persian turquoise (*fīrūza*):
  515. a local-first guardian for your most private data.
  516. <br clear="left"/>
  517. ---
  518. ## Contributing
  519. Contributions welcome: bug reports, feature requests, and PRs alike. Please read the [Contributing guide](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md) first.
  520. - [Open an issue](https://github.com/maziyarpanahi/openmed/issues)
  521. - [Contributing guide](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Maintainers](MAINTAINERS.md) · [Security policy](SECURITY.md)
  522. - **Translations welcome**: help complete the other-language READMEs linked in the switcher at the top.
  523. ---
  524. ## Security
  525. Found a vulnerability? OpenMed redacts PHI, so a **redaction bypass or PHI/PII
  526. leak is a security issue**: please report it **privately**, never as a public
  527. issue. See **[SECURITY.md](SECURITY.md)** for the responsible-disclosure policy
  528. and the [private reporting form](https://github.com/maziyarpanahi/openmed/security/advisories/new).
  529. Never include real patient data in a report.
  530. ---
  531. ## Credits
  532. OpenMed builds on excellent open-source work: particular thanks to **OpenAI** (the [Privacy Filter](https://huggingface.co/openai/privacy-filter) architecture), **NVIDIA** (the [Nemotron PII dataset](https://huggingface.co/datasets/nvidia/Nemotron-PII-v1)), **Hugging Face** (`transformers`, Transformers.js & the model ecosystem), **Apple** ([MLX](https://github.com/ml-explore/mlx)), and the **[Faker](https://faker.readthedocs.io/)** maintainers.
  533. ## License
  534. The OpenMed SDK source is released under the [Apache-2.0 License](LICENSE). Third-party asset notices are recorded in [NOTICE](NOTICE).
  535. ## Citation
  536. ```bibtex
  537. @misc{panahi2025openmedneropensourcedomainadapted,
  538. title={OpenMed NER: Open-Source, Domain-Adapted State-of-the-Art Transformers for Biomedical NER Across 12 Public Datasets},
  539. author={Maziyar Panahi},
  540. year={2025},
  541. eprint={2508.01630},
  542. archivePrefix={arXiv},
  543. primaryClass={cs.CL},
  544. url={https://arxiv.org/abs/2508.01630},
  545. }
  546. ```
  547. Expected result: BibTeX-compatible citation metadata for referencing OpenMed in
  548. papers, posters, and derived documentation.
  549. ---
  550. ## Star History
  551. If OpenMed is useful to you, a star helps others discover it.
  552. [5,700+ GitHub stars · 11 Nov 2026 snapshot](https://github.com/maziyarpanahi/openmed/stargazers)
  553. ---
  554. <div align="center">
  555. Built by the OpenMed team
  556. <a href="https://openmed.life">Website</a> ·
  557. <a href="https://openmed.life/docs">Docs</a> ·
  558. <a href="https://x.com/openmed_ai">X / Twitter</a> ·
  559. <a href="https://www.linkedin.com/company/openmed-ai/">LinkedIn</a>
  560. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.