Clinical Nlp Domain

Tagging scheme: BIO-2

• B-<LABEL> starts an entity, I-<LABEL> continues it, O is outside.
• Invariant: I-X must follow either B-X or I-X. Never follow O or a different entity type. Post-process repairs invalid sequences before returning to caller.
• Label ordering in the model config must be stable across train/export/serve — store in labels.yaml.

Entity record (every extracted entity carries all of these)

class ExtractedEntity(BaseModel):
    text: str                       # surface form from source
    label: EntityLabel              # one of taxonomy above
    char_span: tuple[int, int]      # [start, end) in the DE-IDENTIFIED text
    token_span: tuple[int, int]     # for debugging / re-attention
    confidence: float               # model softmax max, or aggregate
    assertion: Assertion            # present | negated | hypothetical | historical | family
    attributes: dict[str, str]      # e.g. {"dosage": "500 mg", "frequency": "bid"}
    normalization: Normalization | None  # CUI + vocab codes, or None if unmapped

Assertion (ConText-based, see medspacy-patterns)

Every entity MUST have an assertion. "No chest pain" must not be extracted as a positive SYMPTOM. Default to present only when no modifier matches; log unmapped modifiers for review.

Normalization

class Normalization(BaseModel):
    cui: str | None                 # UMLS CUI, e.g. "C0011849"
    preferred_term: str             # canonical name
    codes: dict[VocabSource, str]   # {"SNOMED": "73211009", "ICD10": "E11.9", "RXNORM": ...}
    method: Literal["exact", "semantic", "llm_arbiter"]
    score: float                    # retrieval score, 0–1

PHI handling (HARD RULES)

1. Raw input text is ephemeral. Never persisted.
2. Pipeline stage 2 is mandatory: Presidio de-identification runs before anything touches disk or logs.
3. What's persisted: deidentified_text, content_hash (SHA-256 of original for dedup), extracted entities.
4. Logs never contain raw note text. structlog processors redact any text / note / content fields in dev; in prod they're dropped.
5. Model cards and error reports use synthetic fixtures only.
6. See docs/threat-model.md for STRIDE analysis.

Datasets (all require DUA — never commit raw data)

• i2b2 / n2c2 2010, 2014, 2018 — medication extraction, smoking, obesity, de-id.
• BC5CDR — chemical/disease.
• NCBI Disease — disease NER baseline.
• MIMIC-III / MIMIC-IV — discharge summaries (PhysioNet access required).
• Record dataset version + access method in ml/data_card.md.

Evaluation

• Entity-type-stratified P/R/F1 (strict and lenient span matching).
• Confusion matrix at entity-type level.
• Per-section breakdown (intro vs. HPI vs. discharge meds).
• Clinically-weighted error: missing a MEDICATION costs 3×, SYMPTOM 1× (weights in labels.yaml).