aimedicalcoding 0.3.1__py3-none-any.whl

aimedicalcoding/recovery/engine.py

@@ -0,0 +1,16 @@
+"""LLM recovery engine — PLACEHOLDER.
+
+Activated only on a Gap. Pattern: DB returns a candidate set from the match
+key -> LLM selects/ranks within that set (constraints forbid out-of-set
+output) -> emits resolved_* + confidence + source. Free generation is the last
+resort. See ARCHITECTURE.md §5.5.
+"""
+
+from __future__ import annotations
+
+from ..core.models import ClinicalStatement, Gap, NormalizedRecord
+
+
+class RecoveryEngine:
+    def recover(self, stmt: ClinicalStatement, gap: Gap, db) -> NormalizedRecord:
+        raise NotImplementedError("LLM layer is a placeholder (parsing-first phase).")

aimedicalcoding/serialize.py

@@ -0,0 +1,257 @@
+"""Serialize a gap (NormalizedRecord) into the target-tagged output structure.
+
+One self-contained record per (observation, target). Four concerns are kept
+separate: the facts (`observation`), the classification (`target`/`pattern`),
+the plan (`recovery`), and the answer (`resolution`, filled later).
+See docs/GAP_SCHEMA.md.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .core.models import ClinicalStatement, NormalizedRecord, System
+from .systems.loinc import axes as loinc_axes
+from .systems.snomed import qualifiers as snomed_q
+
+_LOCATION_TYPE = {"ccda": "xpath", "fhir": "fhirpath", "custom": "json-pointer"}
+_CODED_TYPES = {"Ord", "Nom"}
+
+
+# --------------------------------------------------------------------------
+# observation (the facts) — system-agnostic
+# --------------------------------------------------------------------------
+
+def _coding_dict(c) -> dict:
+    d = {
+        "code": c.code,
+        "system": (c.system.value if c.system else None),
+        "system_raw": c.raw_system,
+        "display": c.display,
+    }
+    if c.original_text:
+        d["original_text"] = c.original_text
+    if c.check_digit_valid is not None:
+        d["valid"] = c.check_digit_valid
+    return d
+
+
+def _code_block(stmt: ClinicalStatement) -> dict:
+    absent = None
+    codings = []
+    for c in stmt.codings:
+        if c.system == System.NULLFLAVOR:
+            absent = c.raw_system
+            continue
+        codings.append(_coding_dict(c))
+    return {
+        "display_text": stmt.display_name,
+        "original_text": stmt.original_text,
+        "absent_reason": absent,
+        "codings": codings,
+    }
+
+
+def _value_block(stmt: ClinicalStatement) -> Optional[dict]:
+    v = stmt.value
+    if v is None:
+        return None
+    cv = v.coded_value
+    absent = cv.raw_system if (cv and cv.system == System.NULLFLAVOR) else None
+    codings = []
+    if cv and cv.code and cv.system != System.NULLFLAVOR:
+        codings.append(_coding_dict(cv))
+
+    if v.num is not None:
+        vtype = "quantity"
+    elif v.type in _CODED_TYPES:
+        vtype = "coded"
+    elif v.type == "Nar" or v.raw:
+        vtype = "text"
+    else:
+        vtype = "none"
+
+    return {
+        "type": vtype,
+        "number": v.num,
+        "unit": v.unit,
+        "display_text": (cv.display if cv else None),
+        "original_text": v.original_text,
+        "absent_reason": absent,
+        "codings": codings,
+    }
+
+
+def _qualifiers(stmt: ClinicalStatement) -> dict:
+    spec_hint, spec_src, spec_conf = loinc_axes.infer_specimen(stmt)
+    unit = stmt.value.unit if stmt.value else None
+    q = snomed_q.extract_qualifiers(stmt, stmt.raw_text)
+    out = {
+        "specimen": {"value": spec_hint, "source": spec_src, "confidence": spec_conf},
+        "property": loinc_axes.property_from_unit(unit),
+        "scale": loinc_axes.scale_from_value(stmt),
+        "laterality": q["laterality"],
+        "severity": q["severity"],
+        "course": q["course"],
+        # structural negationInd wins over text cues ("denies", "no known")
+        "negation": ("negated" if stmt.companion.get("negation") else q["negation_context"]),
+        "panel": (stmt.panel.code if stmt.panel else None),
+        "effective_time": stmt.effective_time,
+    }
+    return out
+
+
+def _payload_type(stmt: ClinicalStatement) -> str:
+    v = stmt.value
+    if v and (v.type in _CODED_TYPES or (v.coded_value is not None)):
+        return "qa"
+    return "codeable"
+
+
+# --------------------------------------------------------------------------
+# recovery (the plan) — depends on the target slot
+# --------------------------------------------------------------------------
+
+def _dedupe(items) -> list:
+    seen, out = set(), []
+    for x in items:
+        if x and x not in seen:
+            seen.add(x)
+            out.append(x)
+    return out
+
+
+# SNOMED search-term enrichment: sections whose gaps also get the CODE-slot
+# labels appended (Problems 11450-4, Allergies 48765-2, Social History 29762-2),
+# matched by section LOINC or by the contexts those sections route to
+# (FHIR resources often carry no meta.tag/section code).
+_SNOMED_LABEL_SECTIONS = {"11450-4", "48765-2", "29762-2"}
+_SNOMED_LABEL_CONTEXTS = {"problem", "allergy_substance", "allergy_reaction",
+                          "social_history"}
+
+
+def _recovery(record: NormalizedRecord, slot: str, system: str) -> dict:
+    stmt, ev, g = record.statement, record.gap.evidence, record.gap
+
+    # search terms come from the targeted slot's labels
+    if slot == "value" and stmt.value:
+        terms = [stmt.value.coded_value.display if stmt.value.coded_value else None,
+                 stmt.value.original_text]
+    else:  # code slot
+        terms = [stmt.display_name, stmt.original_text]
+    # add any normalized term the handler produced
+    terms += [ev.get("analyte_normalized"), ev.get("term_normalized"), ev.get("ingredient")]
+    # SNOMED only, Problems/Allergies/Social History only: append the CODE
+    # tag's displayName/originalText (never the value's) as trailing context —
+    # e.g. the question label when the value label is a placeholder.
+    if system == System.SNOMEDCT.value and (
+            stmt.section_code in _SNOMED_LABEL_SECTIONS
+            or stmt.context in _SNOMED_LABEL_CONTEXTS):
+        terms += [stmt.display_name, stmt.original_text]
+
+    rec = {
+        "search_terms": _dedupe(terms),
+        "match_key": g.match_key,
+        "suggested_action": g.note or _ACTION.get(g.type, "resolve via DB + LLM"),
+    }
+
+    # filters / ecl (system-specific)
+    if ev.get("ecl"):                       # SNOMED
+        rec["ecl"] = ev["ecl"]
+        rec["filters"] = {"target_hierarchy": ev.get("target_hierarchy")}
+    elif ev.get("target_tty"):              # RxNorm
+        rec["filters"] = {
+            "ingredient": ev.get("ingredient"),
+            "strength": ev.get("strength"),
+            "dose_form": ev.get("dose_form"),
+            "route": ev.get("route"),
+            "target_tty": ev.get("target_tty"),
+        }
+    elif any(ev.get(k) for k in ("laterality", "encounter", "complication")):  # ICD-10-CM
+        rec["filters"] = {
+            "laterality": ev.get("laterality"),
+            "encounter": ev.get("encounter"),
+            "complication": ev.get("complication"),
+        }
+    elif any(ev.get(k) for k in ("specimen_hint", "property_hint", "scale_hint")):  # LOINC
+        # Hard-filter only on axes we trust (confidence >= medium). Low-confidence
+        # specimen/property stay as soft hints (below) so a shaky guess never
+        # forces the wrong code — the failure mode behind the Bld/Ser-Plas and
+        # %/MFr bugs. Scale (from xsi:type) is reliable, so it always filters.
+        _FILTER_OK = {"high", "medium"}
+        rec["filters"] = {
+            "specimen": ev.get("specimen_hint") if ev.get("specimen_confidence") in _FILTER_OK else None,
+            "property": ev.get("property_hint") if ev.get("property_confidence") in _FILTER_OK else None,
+            "scale": ev.get("scale_hint"),
+        }
+        # soft hints: keep the low-confidence guesses visible for LLM ranking
+        rec["hints"] = {
+            "specimen": {"value": ev.get("specimen_hint"), "confidence": ev.get("specimen_confidence")},
+            "property": {"value": ev.get("property_hint"), "confidence": ev.get("property_confidence")},
+        }
+
+    # crosswalk hint (local / ICD / NDC code present on the targeted slot)
+    if ev.get("local_code"):
+        rec["crosswalk"] = {"from_system": ev.get("local_system"), "from_code": ev["local_code"]}
+    elif ev.get("icd_code"):
+        rec["crosswalk"] = {"from_system": ev.get("icd_system"), "from_code": ev["icd_code"]}
+    elif ev.get("ndc_code"):
+        rec["crosswalk"] = {"from_system": ev.get("ndc_system"), "from_code": ev["ndc_code"]}
+    elif ev.get("snomed_code"):
+        rec["crosswalk"] = {"from_system": ev.get("snomed_system"), "from_code": ev["snomed_code"]}
+    elif ev.get("rxnorm_code"):
+        rec["crosswalk"] = {"from_system": ev.get("rxnorm_system"), "from_code": ev["rxnorm_code"]}
+    if ev.get("checkdigit_correction"):
+        rec["checkdigit_correction"] = ev["checkdigit_correction"]
+    return rec
+
+
+_ACTION = {
+    "LOCAL_CODE_ONLY": "crosswalk local code → target; else text + filter search",
+    "NDC_ONLY": "use the NDC↔RxNorm crosswalk; LLM only if 1→many RxCUIs",
+    "MULTUM_ONLY": "crosswalk Multum → RxNorm via UMLS CUI; LLM only if ambiguous",
+    "FDB_ONLY": "crosswalk FDB/NDDF → RxNorm via UMLS CUI; LLM only if ambiguous",
+    "MEDISPAN_ONLY": "crosswalk Medi-Span (GPI/DDID) → RxNorm via UMLS CUI; LLM only if ambiguous",
+    "RXNORM_ONLY": "use the CDC/NLM CVX↔RxNorm map; LLM only if 1→many valences",
+    "ICD_ONLY": "use the official ICD↔SNOMED map; LLM only to choose among targets",
+    "NULLFLAVOR": "map recovered label → target via text + filter search",
+    "DISPLAY_ONLY": "map display → target via text + filter search",
+    "NARRATIVE_ONLY": "narrative text; resolve via text + filter search (low priority)",
+    "BAD_CODE": "apply check-digit correction / re-resolve via text + filter",
+}
+
+
+# --------------------------------------------------------------------------
+# top-level record
+# --------------------------------------------------------------------------
+
+def build_record(record: NormalizedRecord, idx: int,
+                 target_system: str, target_slot: str) -> dict:
+    stmt = record.statement
+    return {
+        "id": idx,
+        "target": {"system": target_system, "slot": target_slot},
+        "pattern": record.gap.type,
+        "payload_type": _payload_type(stmt),
+        "section": {
+            "code": stmt.section_code,
+            "name": stmt.section_name,
+            "system": stmt.section_system,
+        },
+        "observation": {
+            "code": _code_block(stmt),
+            "value": _value_block(stmt),
+            "qualifiers": _qualifiers(stmt),
+        },
+        "recovery": _recovery(record, target_slot, target_system),
+        "provenance": {
+            "location": {
+                "type": _LOCATION_TYPE.get(stmt.source_format, "path"),
+                "path": stmt.source_ref,
+            }
+        },
+        "resolution": {
+            "status": "pending", "code": None, "display": None,
+            "system": None, "confidence": None, "source": None,
+        },
+    }

aimedicalcoding/systems/__init__.py

@@ -0,0 +1,3 @@
+from .base import TerminologyHandler
+
+__all__ = ["TerminologyHandler"]

aimedicalcoding/systems/base.py

@@ -0,0 +1,43 @@
+"""TerminologyHandler contract — PLACEHOLDER axis.
+
+A handler knows ONE code system and operates only on the IR. Validation,
+normalization, disambiguation, and gap detection live here. Implementations
+(loinc/, snomed/, …) will be added after the parsing layer is solid.
+See ARCHITECTURE.md §4/§5.3.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from ..core.models import (
+    ClinicalStatement,
+    CodingCandidate,
+    NormalizedRecord,
+    System,
+)
+
+
+class TerminologyHandler(ABC):
+    system: System
+
+    @abstractmethod
+    def applies_to(self, stmt: ClinicalStatement) -> bool:
+        """True if this handler should resolve the statement (system + context)."""
+
+    @abstractmethod
+    def validate(self, coding: CodingCandidate) -> bool:
+        """Shape + check digit + DB existence."""
+
+    @abstractmethod
+    def normalize(self, stmt: ClinicalStatement) -> Optional[CodingCandidate]:
+        """Pick the canonical coding from stmt.codings (scan-and-identify)."""
+
+    @abstractmethod
+    def build_match_key(self, stmt: ClinicalStatement) -> str:
+        """Composite disambiguation key (component + specimen + property + …)."""
+
+    @abstractmethod
+    def resolve(self, stmt: ClinicalStatement, db) -> NormalizedRecord:
+        """Full pipeline incl. gap classification + recovery handoff."""

aimedicalcoding/systems/cvx/__init__.py

@@ -0,0 +1,15 @@
+"""CVX gap extraction (immunizations).
+
+The vaccine concept lives on the code slot (CCDA manufacturedMaterial/code under
+an immunization act; FHIR Immunization.vaccineCode). CVX has NO check digit — it
+is a short numeric code, so a present, numeric CVX is treated as resolved here.
+The dominant recovery paths are the CDC CVX↔RxNorm and vaccine NDC↔CVX crosswalks
+(both free/deterministic). DB lookup and LLM ranking are placeholders.
+See CVX_pattern_analysis.md.
+"""
+
+from .handler import CvxGapExtractor, CvxGapPattern
+from .patterns import classify, is_cvx_expected, is_valid_cvx
+
+__all__ = ["CvxGapExtractor", "CvxGapPattern", "classify",
+           "is_cvx_expected", "is_valid_cvx"]

aimedicalcoding/systems/cvx/handler.py

@@ -0,0 +1,55 @@
+"""CvxGapExtractor — CVX-only, gaps-only entry point (immunizations)."""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+from ...core.models import ClinicalStatement, NormalizedRecord, System
+from ...pipeline import parse_document
+from . import patterns
+from .patterns import CvxGapPattern
+
+__all__ = ["CvxGapExtractor", "CvxGapPattern"]
+
+
+class CvxGapExtractor:
+    def extract(
+        self,
+        statements: Iterable[ClinicalStatement],
+        contexts: Optional[set[str]] = None,
+        include_narrative: bool = False,
+        apply_dict: bool = False,           # accepted for CLI parity; unused
+    ) -> list[NormalizedRecord]:
+        records: list[NormalizedRecord] = []
+        for stmt in statements:
+            if contexts is not None and stmt.context not in contexts:
+                continue
+            pattern = patterns.classify(stmt)
+            if pattern is None:
+                continue
+            if pattern is CvxGapPattern.NARRATIVE_ONLY and not include_narrative:
+                continue
+            records.append(NormalizedRecord(
+                statement=stmt,
+                resolved_system=System.CVX,
+                resolved_code=None,
+                gap=patterns.parse_gap(stmt, pattern),
+            ))
+        return records
+
+    def extract_from_document(
+        self,
+        document: str | bytes,
+        contexts: Optional[set[str]] = None,
+        include_narrative: bool = False,
+        apply_dict: bool = False,
+    ) -> list[NormalizedRecord]:
+        return self.extract(parse_document(document), contexts=contexts,
+                            include_narrative=include_narrative)
+
+    def summary(self, records: list[NormalizedRecord]) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for r in records:
+            t = r.gap.type if r.gap else "RESOLVED"
+            out[t] = out.get(t, 0) + 1
+        return out

aimedicalcoding/systems/cvx/normalize.py

@@ -0,0 +1,75 @@
+"""Parse the disambiguating attributes from an immunization label.
+
+CVX's analog of the RxNorm axes is much shallower: the vaccine *concept*
+(antigen / target disease) plus, where present, valence/formulation hints
+(e.g. "quadrivalent", "high-dose", "PCV13"). The dominant recovery key is the
+normalized vaccine name; CDC publishes deterministic CVX↔RxNorm and CVX↔NDC
+crosswalks, so a coded RxNorm/NDC almost always resolves a CVX without search.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+_WS = re.compile(r"\s+")
+
+# keyword -> normalized vaccine concept (longest/most-specific first wins)
+_VACCINE_KEYWORDS = [
+    ("covid-19", "COVID-19"),
+    ("covid", "COVID-19"),
+    ("sars-cov-2", "COVID-19"),
+    ("influenza", "influenza"),
+    ("flu", "influenza"),
+    ("hepatitis b", "hepatitis B"),
+    ("hep b", "hepatitis B"),
+    ("hepatitis a", "hepatitis A"),
+    ("hep a", "hepatitis A"),
+    ("tdap", "Tdap"),
+    ("dtap", "DTaP"),
+    ("td ", "Td"),
+    ("mmr", "MMR"),
+    ("measles", "MMR"),
+    ("varicella", "varicella"),
+    ("zoster", "zoster"),
+    ("shingles", "zoster"),
+    ("pneumococcal", "pneumococcal"),
+    ("pcv", "pneumococcal"),
+    ("ppsv", "pneumococcal"),
+    ("hpv", "HPV"),
+    ("human papillomavirus", "HPV"),
+    ("meningococcal", "meningococcal"),
+    ("menacwy", "meningococcal"),
+    ("polio", "polio"),
+    ("ipv", "polio"),
+    ("rsv", "RSV"),
+    ("rotavirus", "rotavirus"),
+    ("hib", "Hib"),
+    ("haemophilus", "Hib"),
+]
+
+# valence / formulation modifiers worth carrying into the match key
+_FORMULATION = [
+    "quadrivalent", "trivalent", "high-dose", "high dose", "adjuvanted",
+    "recombinant", "live", "inactivated", "preservative-free", "pcv13",
+    "pcv15", "pcv20", "ppsv23", "bivalent",
+]
+
+
+def parse_vaccine(text: Optional[str]) -> Optional[str]:
+    """Normalized vaccine concept (target disease), e.g. 'influenza'."""
+    if not text:
+        return None
+    t = text.lower()
+    for kw, concept in _VACCINE_KEYWORDS:
+        if kw in t:
+            return concept
+    return None
+
+
+def parse_formulation(text: Optional[str]) -> Optional[str]:
+    t = (text or "").lower()
+    for f in _FORMULATION:
+        if f in t:
+            return f.replace(" ", "-")
+    return None

aimedicalcoding/systems/cvx/patterns.py

@@ -0,0 +1,134 @@
+"""Per-pattern CVX gap classification + parsers (immunizations, code slot).
+
+The vaccine concept lives on the code slot (CCDA manufacturedMaterial/code under
+an immunization substanceAdministration; FHIR Immunization.vaccineCode). CVX has
+NO check digit — it is a short numeric code (1-4 digits), so validity = numeric
+format + DB existence. The dominant recovery paths are the CDC's deterministic
+CVX↔RxNorm and vaccine NDC↔CVX crosswalks. See CVX_pattern_analysis.md.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from ...core.models import ClinicalStatement, CodingCandidate, Gap, System
+from ...core.system_registry import HL7_STRUCTURAL
+from . import normalize as N
+
+CVX_CONTEXTS = {"immunization"}
+STRUCTURAL = HL7_STRUCTURAL | {System.NULLFLAVOR}
+
+
+class CvxGapPattern(str, Enum):
+    RXNORM_ONLY = "RXNORM_ONLY"           # RxNorm vaccine product, no CVX -> CVX↔RxNorm map
+    NDC_ONLY = "NDC_ONLY"                 # vaccine NDC, no CVX -> CDC vaccine NDC↔CVX map
+    LOCAL_CODE_ONLY = "LOCAL_CODE_ONLY"   # local/in-house immunization code
+    NULLFLAVOR = "NULLFLAVOR"
+    DISPLAY_ONLY = "DISPLAY_ONLY"
+    NARRATIVE_ONLY = "NARRATIVE_ONLY"
+    BAD_CODE = "BAD_CODE"                 # claims CVX but not a valid numeric code
+
+
+def is_valid_cvx(code: Optional[str]) -> bool:
+    """CVX codes are short numeric strings (no check digit). Format-validate;
+    DB existence is the recovery layer's job."""
+    if not code:
+        return False
+    c = code.strip()
+    return c.isdigit() and 1 <= len(c) <= 4
+
+
+def is_cvx_expected(stmt: ClinicalStatement) -> bool:
+    return (
+        stmt.context in CVX_CONTEXTS
+        and (stmt.raw_text is not None or stmt.codings)
+    )
+
+
+def concept_coding(stmt: ClinicalStatement) -> Optional[CodingCandidate]:
+    """Vaccines are code-slot: first non-structural coding with a code."""
+    return next((c for c in stmt.codings
+                 if c.code and c.system not in STRUCTURAL), None)
+
+
+def _has_nullflavor(stmt: ClinicalStatement) -> bool:
+    return any(c.system == System.NULLFLAVOR for c in stmt.codings)
+
+
+def classify(stmt: ClinicalStatement) -> Optional[CvxGapPattern]:
+    if not is_cvx_expected(stmt):
+        return None
+
+    cc = concept_coding(stmt)
+
+    # CVX present -> resolved if it format-validates, else malformed.
+    if cc and cc.system == System.CVX and cc.code:
+        return None if is_valid_cvx(cc.code) else CvxGapPattern.BAD_CODE
+
+    if cc and cc.code and cc.system == System.RXNORM:
+        return CvxGapPattern.RXNORM_ONLY
+    if cc and cc.code and cc.system == System.NDC:
+        return CvxGapPattern.NDC_ONLY
+    if cc and cc.code and cc.system not in STRUCTURAL:
+        return CvxGapPattern.LOCAL_CODE_ONLY
+
+    if _has_nullflavor(stmt):
+        return CvxGapPattern.NULLFLAVOR
+    if stmt.raw_text:
+        if "/text" in (stmt.source_ref or ""):
+            return CvxGapPattern.NARRATIVE_ONLY
+        return CvxGapPattern.DISPLAY_ONLY
+    return None
+
+
+# --------------------------------------------------------------------------
+
+def _match_key(stmt: ClinicalStatement) -> str:
+    t = stmt.raw_text
+    return " | ".join([
+        f"vaccine:{N.parse_vaccine(t) or '?'}",
+        f"formulation:{N.parse_formulation(t) or '-'}",
+        "target:CVX",
+    ])
+
+
+def _evidence(stmt: ClinicalStatement) -> dict:
+    t = stmt.raw_text
+    return {
+        "term": t,
+        "vaccine": N.parse_vaccine(t),
+        "formulation": N.parse_formulation(t),
+        "section_context": stmt.context,
+    }
+
+
+def parse_gap(stmt: ClinicalStatement, pattern: CvxGapPattern) -> Gap:
+    gap = Gap(type=pattern.value, match_key=_match_key(stmt), evidence=_evidence(stmt))
+    cc = concept_coding(stmt)
+
+    if pattern == CvxGapPattern.RXNORM_ONLY and cc:
+        gap.evidence["rxnorm_code"] = cc.code
+        gap.evidence["rxnorm_system"] = cc.raw_system
+        gap.note = ("Use the CDC/NLM CVX↔RxNorm crosswalk — deterministic; "
+                    "LLM only if a generic RxCUI maps to multiple CVX valences.")
+    elif pattern == CvxGapPattern.NDC_ONLY and cc:
+        gap.evidence["ndc_code"] = cc.code
+        gap.evidence["ndc_system"] = cc.raw_system
+        gap.note = ("Use the CDC vaccine NDC↔CVX table (published, free) — "
+                    "deterministic mapping from the dispensed NDC to CVX.")
+    elif pattern == CvxGapPattern.LOCAL_CODE_ONLY and cc:
+        gap.evidence["local_code"] = cc.code
+        gap.evidence["local_system"] = cc.raw_system
+        gap.note = ("Crosswalk local immunization code → CVX first; else search "
+                    "by normalized vaccine concept (+ valence) → CVX.")
+    elif pattern == CvxGapPattern.BAD_CODE and cc:
+        gap.evidence["malformed_code"] = cc.code
+        gap.note = "Claims CVX but not a valid numeric code; re-resolve via vaccine name → CVX."
+    elif pattern == CvxGapPattern.NULLFLAVOR:
+        nf = next((c for c in stmt.codings if c.system == System.NULLFLAVOR), None)
+        gap.evidence["null_flavor"] = nf.raw_system if nf else None
+        gap.note = "Vaccine recovered from narrative; search vaccine concept → CVX."
+    else:
+        gap.note = "Vaccine name only; normalize the concept and search → CVX."
+    return gap

aimedicalcoding/systems/icd10cm/__init__.py

@@ -0,0 +1,16 @@
+"""ICD-10-CM gap extraction (billing diagnoses) — the mirror of SNOMED.
+
+Reads the diagnosis value slot (problems, encounters). The dominant recovery
+path is the official SNOMED CT → ICD-10-CM map (the inverse of SNOMED's ICD_ONLY).
+ICD-10-CM has no check digit — validity is a format regex + DB existence.
+See docs/patterns/ICD10CM_pattern_analysis.md.
+"""
+
+from .handler import Icd10cmGapExtractor, Icd10cmGapPattern
+from .patterns import classify, is_icd_expected
+from .icdformat import is_valid_icd10cm
+
+__all__ = [
+    "Icd10cmGapExtractor", "Icd10cmGapPattern",
+    "classify", "is_icd_expected", "is_valid_icd10cm",
+]

aimedicalcoding/systems/icd10cm/handler.py

@@ -0,0 +1,55 @@
+"""Icd10cmGapExtractor — ICD-10-CM-only, gaps-only entry point (diagnoses)."""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+from ...core.models import ClinicalStatement, NormalizedRecord, System
+from ...pipeline import parse_document
+from . import patterns
+from .patterns import Icd10cmGapPattern
+
+__all__ = ["Icd10cmGapExtractor", "Icd10cmGapPattern"]
+
+
+class Icd10cmGapExtractor:
+    def extract(
+        self,
+        statements: Iterable[ClinicalStatement],
+        contexts: Optional[set[str]] = None,
+        include_narrative: bool = False,
+        apply_dict: bool = False,           # accepted for CLI parity; unused
+    ) -> list[NormalizedRecord]:
+        records: list[NormalizedRecord] = []
+        for stmt in statements:
+            if contexts is not None and stmt.context not in contexts:
+                continue
+            pattern = patterns.classify(stmt)
+            if pattern is None:
+                continue
+            if pattern is Icd10cmGapPattern.NARRATIVE_ONLY and not include_narrative:
+                continue
+            records.append(NormalizedRecord(
+                statement=stmt,
+                resolved_system=System.ICD10CM,
+                resolved_code=None,
+                gap=patterns.parse_gap(stmt, pattern),
+            ))
+        return records
+
+    def extract_from_document(
+        self,
+        document: str | bytes,
+        contexts: Optional[set[str]] = None,
+        include_narrative: bool = False,
+        apply_dict: bool = False,
+    ) -> list[NormalizedRecord]:
+        return self.extract(parse_document(document), contexts=contexts,
+                            include_narrative=include_narrative)
+
+    def summary(self, records: list[NormalizedRecord]) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for r in records:
+            t = r.gap.type if r.gap else "RESOLVED"
+            out[t] = out.get(t, 0) + 1
+        return out