maziyarpanahi/openmed

---

name: annotating-variants

description: Annotates VCF variants and normalizes HGVS nomenclature with public, license-free annotators (Ensembl VEP REST, VEP/SnpEff/ANNOVAR offline) and links variants to gnomAD population frequencies and the clinical context OpenMed extracts. Use when the user wants to predict variant consequences, map HGVS to genomic coordinates, annotate a VCF, attach allele frequencies, or pair variants with phenotype/oncology context. Trigger keywords: VCF, HGVS, variant annotation, VEP, SnpEff, ANNOVAR, consequence, missense, gnomAD, allele frequency, GRCh38, rsID, transcript. Pairs adjacent to OpenMed: combine annotated variants with Genomics/Oncology entities and phenotype from openmed.analyze_text. Tools used are free; restricted clinical databases are user-supplied.

---

name: ask-openmed

description: Choose the first OpenMed workflow skill for an intake, privacy, extraction, exchange, or verification request using deterministic local routing. Use when a goal is broad, spans several clinical-data stages, or leaves the data-sensitivity status unclear; the privacy gate is selected before downstream work when raw clinical or personal content may be present.

---

name: assembling-fhir-bundles

description: Package multiple FHIR R4 resources produced from OpenMed output into a single valid transaction Bundle ready to POST to an EHR, using OpenMed's verified bundle assembler openmed.clinical.exporters.fhir.to_bundle. Covers deterministic urn:uuid fullUrls, automatic in-Bundle reference rewriting, request blocks (method/url) for transaction vs batch, and conditional create. Use after exporting-to-fhir when the user has several Condition/Observation/MedicationStatement resources and wants one transaction Bundle, mentions Bundle, transaction, references, or posting to a FHIR server. Builds on exporting-to-fhir; pairs after.

---

name: auditing-deidentification-runs

description: Produce a signed, reproducible, no-PHI audit trail for an OpenMed de-identification run via deidentify(audit=True). Use when the user needs compliance evidence, a tamper-evident record of what was redacted and why, to verify nothing was changed, to retain proof for HIPAA/GDPR audits, or to review de-id decisions without exposing plaintext PHI. Covers the AuditReport / AuditSignature / AuditSpan / DetectorInfo fields, why audits store offsets+hashes+provenance+residual-risk and never plaintext, signing with .sign(key), and verifying with .verify(key). Pairs with OpenMed deidentifying-clinical-text and auditing-safe-harbor-checklist.

---

name: auditing-deid-leakage

description: Adversarially scan already-de-identified clinical text for residual identifiers and emit a leakage report that blocks release on any hit. Use after OpenMed de-identification when the user asks to verify a redaction, prove no PHI/PII leaked, gate a dataset before sharing, or run a second-pass detector. Covers format and checksum detectors (SSN, Luhn for card numbers, MRN/account patterns, emails, phones, dates), entropy heuristics for high-randomness tokens, severity scoring, and a hard block-on-leak rule. This is the verification half of OpenMed's leakage-first ethos. Hand-off: re-run openmed.extract_pii on the de-id output and diff against expectations. License-free, local-first. Pairs after deidentifying-clinical-text.

---

name: auditing-part11-trails

description: Generates and verifies 21 CFR Part 11-style audit trails — who/what/when, electronic signatures, and tamper-evidence — for OpenMed pipelines in GxP and clinical-trial (GCP) settings. Use when the user runs OpenMed in a regulated/validated environment and needs an attributable, time-stamped, tamper-evident record of each processing action, electronic-signature manifestations, or computer-system-validation (CSV) evidence. Trigger keywords: 21 CFR Part 11, Part 11, audit trail, electronic signature, e-signature, GxP, GCP, GLP, GMP, CSV, computer system validation, data integrity, ALCOA, tamper-evident, contemporaneous. Pairs adjacent to OpenMed: maps directly onto OpenMed deidentify(audit=True) -> signed AuditReport with .sign(key)/.verify(key), whose repro_hash + HMAC give the tamper-evidence and attribution Part 11 expects. This is a compliance-enablement aid, not a validation certification.

---

name: auditing-safe-harbor-checklist

description: Verify OpenMed de-identified output against all 18 HIPAA Safe Harbor identifier categories and report residual re-identification risk. Use when the user must confirm a note meets HIPAA Safe Harbor (45 CFR 164.514(b)(2)), needs a coverage checklist mapping detected entities to the 18 categories, wants to flag gaps like ages over 89, rare geography, fax vs phone, or biometrics, or asks whether masking was complete. Maps OpenMed CANONICAL_LABELS to the 18 HIPAA classes and uses extract_pii / deidentify to check coverage. Pairs with OpenMed deidentifying-clinical-text and auditing-deidentification-runs.

---

name: auditing-subgroup-fairness

description: Audit an OpenMed NER or de-identification model for performance disparities across demographic subgroups (sex, age band, race/ethnicity when available) using openmed.eval.fairness_report. Use when the user wants per-subgroup recall and leakage, wants to check whether de-identification under-protects a group, wants to surface a documentation gap where subgroup data is missing, or needs equalized-odds-style disparity numbers for a clinical model. Trigger on "fairness", "subgroup", "bias audit", "disparity", "equalized odds", "under-protected group", "per-group recall", or "STANDING Together" for an OpenMed model.

---

name: authoring-model-cards

description: Generate a model card for an OpenMed clinical NER or de-identification model documenting intended use, quantitative metrics, subgroup performance, limitations, and a medical-device disclaimer for clinical AI governance. Use when the user wants to write or update a model card, a README model section, or governance documentation, or to turn OpenMed eval outputs (release gate report, fairness_report, error_report) into the card's metrics and limitations sections. Trigger on "model card", "intended use", "model documentation", "governance", "limitations section", "datasheet", or "FDA/ONC transparency" for an OpenMed model.

---

name: batch-processing-clinical-text

description: Run large-scale batch NER, PII extraction, or de-identification over many clinical notes on-device with OpenMed, with sharding, checkpointing, resumability, and append-only JSONL output. Use when the user needs to process a corpus or folder of notes, de-identify a dataset, run NER over thousands of documents, build a resumable batch pipeline, or stream results to JSONL without holding everything in memory. Covers process_batch / BatchProcessor / BatchItem / BatchResult, the operation= selector (analyze_text | extract_pii | deidentify), iter_process streaming, the PHI-safe on_progress callback, chunking long documents, and no-PHI logging. Produces a resumable batch runner over an OpenMed model.

---

name: benchmarking-clinical-ner

description: Score an OpenMed clinical or biomedical NER model against a user-supplied gold corpus with entity-level precision, recall, and F1, then break errors down per label. Use when the user wants a seqeval-style scorecard, strict vs partial (relaxed) span matching, a per-label confusion matrix, false-negative / false-positive examples, or to debug why a model misses entities. Trigger on "evaluate NER", "entity-level F1", "seqeval", "precision recall F1", "confusion matrix", "error analysis", "strict vs partial match", or "score against gold" in an OpenMed context. The gold corpus is user-supplied; OpenMed bundles no i2b2/n2c2/MIMIC data.

---

name: benchmark-pii-recall

description: Benchmark an OpenMed PII model with synthetic gold spans and report label-aware exact-span and grapheme recall without emitting identifier surfaces. Use when an agent must compare a model, threshold, backend, or quantized artifact and enforce a recall floor before release.

---

name: bridging-presidio-and-spacy

description: Combine OpenMed clinical NLP with Microsoft Presidio, spaCy, or LangChain through OpenMed's built-in interop adapter registry (openmed.interop). Covers the lazy adapter registry (available_adapters, get_adapter, adapter_spec), the presidio/spacy/langchain pip extras, and the verified callables — Presidio to_canonical/from_canonical/merge_with_openmed, the spaCy openmed_deid pipeline factory, and the LangChain create_redaction_runnable. Use when the user wants to add Presidio recognizers, embed OpenMed PII detection in a spaCy pipeline, or use OpenMed de-identification as a LangChain runnable. Pairs adjacent to the OpenMed PII skills.

---

name: building-gold-corpus

description: Scaffold a synthetic gold-standard annotation project for evaluating OpenMed NER and de-identification models — label schema, annotation guidelines, BRAT or Label Studio config, and disjoint train/dev/test splits. Use when the user wants to create eval fixtures, set up annotation, define a label set, write guidelines, configure an annotation tool, or build a held-out gold set for the OpenMed eval harness. Trigger on "gold corpus", "annotation project", "label schema", "annotation guidelines", "BRAT", "Label Studio", "train dev test split", or "build eval fixtures" for OpenMed. Committed gold must be synthetic; licensed (i2b2/n2c2/MIMIC) data is eval-only and never committed.

---

name: building-patient-timelines

description: Assemble a chronological patient timeline from OpenMed-extracted clinical events, normalizing dates and resolving relative time expressions on-device. Use when the user wants to build a patient timeline, order events from clinical notes, reconstruct a longitudinal history, plot a course of illness, or turn analyze_text/deidentify output into a sorted sequence of dated encounters, diagnoses, medications, and procedures. Covers temporal normalization (absolute and relative), event modeling toward FHIR Encounter/Condition.onsetDateTime, anchoring to a document/admission date, and handling undated or ambiguous events. Consumes OpenMed analyze_text entities plus clinical temporality (resolving-clinical-context); produces a sorted event list ready for charting or FHIR export.

---

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.

---

name: checking-hipaa-compliance

description: Runs a HIPAA Privacy and Security Rule checklist over a data pipeline and produces a gap report before deploying OpenMed on PHI. Use when the user is about to process protected health information, needs a pre-deployment compliance review, wants to know which administrative, physical, and technical safeguards apply, is scoping a Business Associate Agreement, or must document minimum-necessary and de-identification controls. Trigger keywords: HIPAA, Privacy Rule, Security Rule, 45 CFR 164, PHI, BAA, business associate, minimum necessary, safeguards, Safe Harbor, Expert Determination, gap analysis, compliance review. Pairs adjacent to OpenMed: the checklist shows where openmed.deidentify and signed audit reports satisfy the de-identification and audit-control requirements. The control list lives in references/hipaa-checklist.md. This is a structured self-assessment aid, not legal advice.

---

name: choosing-openmed-models

description: Discover and pick the right OpenMed model for a clinical or biomedical task, domain, or language. Use when the user asks which OpenMed model to use, wants to list model categories, find a Disease vs Oncology vs Privacy/PII model, get a PII model for a specific language, search models by size or task, or inspect a model's labels and metadata before loading. Covers list_model_categories, get_models_by_category, get_pii_models_by_language, get_default_pii_model, search_models(ModelQuery(...)), get_model_info, and the openmed models CLI. Pairs with loading-openmed-models.

---

name: coding-hcc-risk-adjustment

description: Maps chronic conditions extracted by OpenMed to CMS-HCC V28 risk-adjustment categories and estimates a RAF (Risk Adjustment Factor) score as decision support. Use when the user wants to surface risk-adjustable diagnoses from notes, map ICD-10-CM codes to HCC categories, estimate or reconcile a patient/panel RAF, find suspected-but-undocumented HCCs, or check MEAT documentation support. Trigger keywords: HCC, CMS-HCC, V28, RAF score, risk adjustment, Medicare Advantage, hierarchical condition category, MEAT, recapture, suspect HCC, RADV. Pairs after OpenMed NER + ICD-10 coding: consume Disease/Pathology entities from openmed.analyze_text, code them (see coding-icd10), then roll up to HCCs. CMS-HCC mappings and weights are public from CMS. This is a coding-support aid for human review, never autonomous risk-adjustment coding.

---

name: coding-icd10

description: Suggests candidate ICD-10-CM diagnosis codes (and ICD-10-PCS procedure codes) for diagnoses and procedures extracted by OpenMed, with rationale and a human-coder caveat. Use when the user wants to code a problem list, map a diagnosis span to a billable ICD-10-CM code, route a finding to the right chapter, cross-walk ICD-9 via GEMs, or pre-fill an encounter for coder review. Trigger keywords: ICD-10-CM, ICD-10-PCS, diagnosis coding, billable code, GEMs, problem list coding, encounter diagnosis, chapter range, CMS code lookup. references/icd10-chapters.md holds the chapter/section ranges. Pairs after OpenMed NER: consume Disease/Pathology entities from openmed.analyze_text and propose codes a certified coder validates. ICD-10-CM/PCS files are public domain from CMS — no license barrier (unlike CPT, which is restricted and out of scope).

---

name: computing-ecqms

description: Compute electronic clinical quality measures (eCQMs) over structured data using CQL/QDM logic, lifting note-derived numerator and exclusion facts from OpenMed to improve measure capture. Use when the user wants to compute an eCQM, evaluate a CMS/ECQI quality measure, improve numerator capture from clinical notes, build CQL/QDM measure logic, or close documentation gaps that structured codes miss. Covers eCQM structure (IPP/denominator/numerator/exclusions), CQL v1.5 and QDM v5.6, MADiE authoring, and mapping OpenMed entities to QDM data elements. Consumes OpenMed analyze_text facts (coded via the linking skills) to supplement structured EHR data; does not replace certified measure engines.

---

name: configuring-privacy-policies

description: Select and customize OpenMed's seven bundled privacy policy profiles for de-identification, and build custom surrogate generators. Use when the user asks which policy fits HIPAA Safe Harbor vs Expert Determination vs GDPR vs PIPEDA vs a research limited dataset vs strict no-leak, wants to pass policy= to deidentify(), needs to keep quasi-identifiers for research, or must register a custom MRN/name/address surrogate provider. Covers the profile-to-use-case map, AnonymizerConfig/Anonymizer for fine control, and register_clinical_provider / register_label_generator. Pairs with OpenMed deidentifying-clinical-text and generating-synthetic-surrogates.

---

name: defining-cohort-phenotypes

description: Authors computable phenotype and cohort definitions in the OHDSI ATLAS / CIRCE style over the OMOP CDM, combining standard concept sets with NLP-derived features that OpenMed extracts. Use when the user wants to define a patient cohort, write a computable phenotype, reuse PheKB or OHDSI Phenotype Library logic, build concept sets, or augment code-based criteria with text features. Trigger keywords: phenotype, cohort definition, OHDSI, ATLAS, CIRCE, OMOP CDM, concept set, PheKB, Phenotype Library, eMERGE, computable phenotype. Pairs adjacent to OpenMed: NLP features from openmed.analyze_text augment code-based phenotypes for entities that are poorly captured by structured codes. OMOP CDM and OHDSI tools are open source; restricted vocabularies (SNOMED, CPT) are user-supplied.

---

name: deidentify-a-dataset

description: De-identify selected free-text columns in a local CSV, JSONL, or Parquet dataset with OpenMed and produce a separate redacted dataset plus a PHI-free aggregate summary. Use when an agent must prepare a clinical dataset for analysis or sharing without overwriting the source or exposing cell values in logs.

---

name: deidentifying-clinical-text

description: Remove, mask, or replace PHI/PII in clinical free text on-device with OpenMed's deidentify(). Use when the user needs to de-identify medical notes, strip patient identifiers, redact PHI before sharing or analysis, anonymize discharge summaries, or pick a de-id method (mask vs remove vs replace vs hash vs shift_dates). Covers confidence_threshold for safety, consistent+seed for stable surrogates, keep_mapping for reversible de-id, policy= profiles, and the DeidentificationResult fields. Pairs with OpenMed extract_pii (detect spans), reidentify (restore), configuring-privacy-policies, and auditing-deidentification-runs.

---

name: deidentifying-multilingual-text

description: De-identify non-English clinical text on-device with OpenMed by passing lang= and locale= to deidentify(). Use when the user has Spanish, German, French, Italian, Portuguese, Dutch, Hindi, Telugu, Arabic, Japanese, or Turkish medical notes, needs locale-aware fake surrogates, must handle language-specific national IDs (DNI, NIR, Steuer-ID, codice fiscale, BSN, CPF, TCKN, Aadhaar), or asks which languages OpenMed PII supports. Covers SUPPORTED_LANGUAGES, get_pii_models_by_language, get_patterns_for_language, LANG_TO_LOCALE, and accent normalization. Pairs with OpenMed deidentifying-clinical-text and generating-synthetic-surrogates.

---

name: deploying-openmed-mcp

description: Run OpenMed's Model Context Protocol (MCP) server so coding agents (Claude Code, Codex) and chat clients can call clinical NER, PII extraction, and de-identification as tools, on-device. Use when the user wants to add OpenMed to an agent's MCP config, expose de-id/NER as MCP tools, run an MCP server over stdio or Streamable HTTP, give Claude/Codex access to OpenMed, or containerize the MCP server. Covers the mcp extra, create_mcp_server, the 7 tools (openmed_analyze_text, openmed_extract_pii, openmed_deidentify, openmed_list_models, openmed_list_pii_languages, openmed_loaded_models, openmed_unload_model), the resources and prompts, stdio vs streamable-http transports, ServiceRuntime env config, and MCP client config snippets.

---

name: detecting-pv-signals

description: Computes disproportionality signals — PRR, ROR, EBGM, and IC (BCPNN) — over FAERS / OpenFDA drug-event data to flag potential safety signals. Use when the user wants to mine spontaneous-report data for drug-reaction associations, build a 2x2 contingency table, compute a Proportional Reporting Ratio or Reporting Odds Ratio, run Empirical Bayes (EBGM/EB05) or Information Component shrinkage, or screen a drug for over-reported reactions. Trigger keywords: disproportionality, signal detection, PRR, ROR, EBGM, EB05, IC, BCPNN, MGPS, 2x2 table, signal of disproportionate reporting, SDR, OpenFDA, FAERS. Pairs adjacent to OpenMed: aggregate de-identified, coded cases (from reporting-adverse-events) then query the public OpenFDA /drug/event count API to build the contingency table. Reaction terms are MedDRA PTs (licensed, user-supplied).

---

name: enforcing-nophi-logging

description: Add a logging and telemetry guard that scrubs or blocks PHI from logs, traces, and error reports around an OpenMed deployment. Use when the user wants a Python logging.Filter that redacts protected health information before records are emitted, wants to keep PHI out of OpenTelemetry spans or error trackers, needs structured no-PHI log fields, or is worried that logs and stack traces are leaking patient data. Trigger on "scrub logs", "redact PHI from logs", "no-PHI logging", "logging filter", "telemetry redaction", "logs leaking patient data", or "OpenTelemetry redaction" in an OpenMed deployment.

---

name: etl-to-omop-cdm

description: Map OpenMed-extracted, terminology-coded conditions, drugs, and measurements into OMOP CDM v5.4 clinical tables (condition_occurrence, drug_exposure, measurement) for OHDSI/ATLAS analytics. Use when the user wants to load NLP-derived facts into an OMOP database, build an OHDSI ETL from clinical notes, populate condition_occurrence or drug_exposure from text, or standardize note-derived findings to OMOP standard concepts. Covers the source-to-standard concept mapping pattern, required vs optional CDM fields, type concepts for NLP-derived rows, and the user-supplied OHDSI vocabulary (CONCEPT/CONCEPT_RELATIONSHIP). Consumes coded OpenMed analyze_text output (after SNOMED/RxNorm/LOINC linking) and produces OMOP-conformant rows.