aimedicalcoding 0.3.1__py3-none-any.whl

aimedicalcoding/api.py

@@ -0,0 +1,163 @@
+"""Public Python API.
+
+    from aimedicalcoding import extract_gaps
+
+    result = extract_gaps("patient.xml", systems=("loinc", "snomed", "rxnorm"))
+    result.gaps          # list[dict] — target-tagged gap records
+    result.by_target     # {"LOINC": 5, ...}
+    result.to_json()
+    result.to_dict()
+
+One pass checks every requested terminology; each gap is tagged with its
+``target`` (system + slot). See docs/GAP_SCHEMA.md for the record shape.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Optional, Sequence, Union
+
+from . import serialize
+from .core.models import ClinicalStatement, NormalizedRecord
+from .pipeline import parse_document
+from .systems.loinc import LoincGapExtractor
+from .systems.snomed import SnomedGapExtractor
+from .systems.snomed.patterns import VALUE_SLOT_CONTEXTS as _SN_VALUE_SLOTS
+from .systems.rxnorm import RxnormGapExtractor
+from .systems.icd10cm import Icd10cmGapExtractor
+from .systems.icd10cm.patterns import ICD_CONTEXTS as _ICD_CONTEXTS
+from .systems.cvx import CvxGapExtractor
+
+# system key -> (extractor factory, canonical name). Register new systems here.
+EXTRACTORS = {
+    "loinc": (LoincGapExtractor, "LOINC"),
+    "snomed": (SnomedGapExtractor, "SNOMED-CT"),
+    "rxnorm": (RxnormGapExtractor, "RxNorm"),
+    "icd10cm": (Icd10cmGapExtractor, "ICD-10-CM"),
+    "cvx": (CvxGapExtractor, "CVX"),
+}
+PLANNED = ("cpt", "hcpcs", "icd10pcs")
+
+Source = Union[str, bytes, os.PathLike, "os.PathLike[str]"]
+
+
+def _read(source: Source) -> bytes:
+    """Accept a path, raw bytes/str, or a file-like object."""
+    if isinstance(source, bytes):
+        return source
+    if hasattr(source, "read"):                      # file-like
+        data = source.read()
+        return data.encode() if isinstance(data, str) else data
+    if isinstance(source, str) and ("<" in source or "{" in source):
+        return source.encode()                        # inline document content
+    with open(source, "rb") as fh:                   # path
+        return fh.read()
+
+
+def _slot_for(system_key: str, stmt: ClinicalStatement) -> str:
+    if system_key == "snomed":
+        return "value" if stmt.context in _SN_VALUE_SLOTS else "code"
+    if system_key == "icd10cm":
+        return "value"   # diagnoses live in the value slot
+    return "code"
+
+
+def collect_gaps(
+    statements: Sequence[ClinicalStatement],
+    system_keys: Iterable[str],
+    contexts: Optional[set[str]] = None,
+    include_narrative: bool = False,
+    apply_dict: bool = False,
+) -> list[tuple[NormalizedRecord, str, str]]:
+    """Run each system over the SAME statements (one pass); tag with target.
+    Returns (record, canonical_system, slot) tuples."""
+    out: list[tuple[NormalizedRecord, str, str]] = []
+    for key in system_keys:
+        factory, canon = EXTRACTORS[key]
+        recs = factory().extract(statements, contexts=contexts,
+                                 include_narrative=include_narrative,
+                                 apply_dict=apply_dict)
+        for r in recs:
+            out.append((r, canon, _slot_for(key, r.statement)))
+    return out
+
+
+@dataclass
+class GapResult:
+    """Result of :func:`extract_gaps`."""
+    source_format: Optional[str]
+    targets_checked: list[str]
+    gaps: list[dict] = field(default_factory=list)
+    by_pattern: dict[str, int] = field(default_factory=dict)
+    by_target: dict[str, int] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source_format": self.source_format,
+            "targets_checked": self.targets_checked,
+            "gap_count": len(self.gaps),
+            "by_pattern": self.by_pattern,
+            "by_target": self.by_target,
+            "gaps": self.gaps,
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, default=str)
+
+    def __len__(self) -> int:
+        return len(self.gaps)
+
+    def __iter__(self):
+        return iter(self.gaps)
+
+
+def extract_gaps(
+    source: Source,
+    *,
+    input_format: str = "auto",
+    systems: Sequence[str] = ("loinc", "snomed", "rxnorm"),
+    contexts: Optional[Iterable[str]] = None,
+    include_narrative: bool = False,
+    apply_dict: bool = False,
+) -> GapResult:
+    """Extract terminology-code gaps from a clinical document.
+
+    Args:
+        source: path, raw bytes/str (document content), or a file-like object.
+        input_format: ``"auto"`` (detect), ``"ccda"``, ``"fhir"``, or ``"custom"``.
+        systems: which terminologies to check (subset of ``EXTRACTORS``).
+        contexts: optional set of statement contexts to restrict to.
+        include_narrative: also report NARRATIVE_ONLY gaps.
+        apply_dict: expand abbreviations in search terms (LOINC).
+
+    Returns:
+        A :class:`GapResult`.
+    """
+    unknown = [s for s in systems if s not in EXTRACTORS]
+    if unknown:
+        raise ValueError(f"unknown system(s): {unknown}; available: {sorted(EXTRACTORS)}")
+    if input_format not in ("auto", "ccda", "fhir", "custom"):
+        raise ValueError(f"invalid input_format: {input_format!r}")
+
+    statements = parse_document(_read(source))   # format auto-detected by the pipeline
+    ctx = set(contexts) if contexts is not None else None
+    tgaps = collect_gaps(statements, systems, ctx, include_narrative, apply_dict)
+
+    by_pattern: dict[str, int] = {}
+    by_target: dict[str, int] = {}
+    for r, sys_, _slot in tgaps:
+        by_pattern[r.gap.type] = by_pattern.get(r.gap.type, 0) + 1
+        by_target[sys_] = by_target.get(sys_, 0) + 1
+
+    gaps = [serialize.build_record(r, i, sys_, slot)
+            for i, (r, sys_, slot) in enumerate(tgaps, 1)]
+
+    return GapResult(
+        source_format=(statements[0].source_format if statements else None),
+        targets_checked=[EXTRACTORS[k][1] for k in systems],
+        gaps=gaps,
+        by_pattern=by_pattern,
+        by_target=by_target,
+    )

aimedicalcoding/core/__init__.py

@@ -0,0 +1,34 @@
+from .models import (
+    System,
+    CodingCandidate,
+    ValueInfo,
+    ClinicalStatement,
+    Gap,
+    NormalizedRecord,
+)
+from .system_registry import canonicalize, system_aliases
+from .checkdigits import (
+    loinc_check_digit,
+    is_valid_loinc,
+    correct_loinc_check_digit,
+    verhoeff_ok,
+    is_valid_sctid,
+    sctid_partition,
+)
+
+__all__ = [
+    "System",
+    "CodingCandidate",
+    "ValueInfo",
+    "ClinicalStatement",
+    "Gap",
+    "NormalizedRecord",
+    "canonicalize",
+    "system_aliases",
+    "loinc_check_digit",
+    "is_valid_loinc",
+    "correct_loinc_check_digit",
+    "verhoeff_ok",
+    "is_valid_sctid",
+    "sctid_partition",
+]

aimedicalcoding/core/checkdigits.py

@@ -0,0 +1,103 @@
+"""Check-digit & shape validation for code systems that support it.
+
+- LOINC: Luhn / Mod-10 over the numeric payload (verified vs 2160-0, 718-7, …).
+- SNOMED CT: Verhoeff check digit over the SCTID (verified vs 22298006, 73211009,
+  386661006, 44054006, 80146002, 387517004).
+"""
+
+from __future__ import annotations
+
+import re
+
+_LOINC_SHAPE = re.compile(r"^(\d{1,7})-(\d)$")
+_SCTID_SHAPE = re.compile(r"^\d{6,18}$")
+
+# Verhoeff tables (dihedral group D5) — for SNOMED SCTID check digits
+_V_D = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
+    [2, 3, 4, 0, 1, 7, 8, 9, 5, 6], [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
+    [4, 0, 1, 2, 3, 9, 5, 6, 7, 8], [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+    [6, 5, 9, 8, 7, 1, 0, 4, 3, 2], [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
+    [8, 7, 6, 5, 9, 3, 2, 1, 0, 4], [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
+]
+_V_P = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
+    [5, 8, 0, 3, 7, 9, 6, 1, 4, 2], [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
+    [9, 4, 5, 3, 1, 2, 6, 8, 7, 0], [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+    [2, 7, 9, 3, 8, 0, 6, 4, 1, 5], [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
+]
+
+
+def loinc_check_digit(payload: str) -> int:
+    """Luhn / Mod-10 check digit for the numeric payload (no hyphen)."""
+    total = 0
+    for i, ch in enumerate(reversed(payload)):
+        d = int(ch)
+        if i % 2 == 0:          # rightmost payload digit is doubled
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    return (10 - (total % 10)) % 10
+
+
+def is_valid_loinc(code: str) -> bool:
+    """Shape + check-digit validation (does NOT confirm DB existence)."""
+    if not code:
+        return False
+    m = _LOINC_SHAPE.match(code.strip())
+    if not m:
+        return False
+    payload, check = m.group(1), int(m.group(2))
+    return loinc_check_digit(payload) == check
+
+
+def correct_loinc_check_digit(code: str) -> str | None:
+    """If ``code`` is LOINC-shaped but has a wrong check digit, return the
+    code with the corrected check digit (assuming the payload is right).
+    Returns None if the shape doesn't match at all.
+    """
+    if not code:
+        return None
+    m = _LOINC_SHAPE.match(code.strip())
+    if not m:
+        return None
+    payload = m.group(1)
+    return f"{payload}-{loinc_check_digit(payload)}"
+
+
+# --------------------------------------------------------------------------
+# SNOMED CT
+# --------------------------------------------------------------------------
+
+def verhoeff_ok(sctid: str) -> bool:
+    """True if the SCTID's trailing Verhoeff check digit is valid."""
+    c = 0
+    for i, ch in enumerate(reversed(sctid)):
+        c = _V_D[c][_V_P[i % 8][int(ch)]]
+    return c == 0
+
+
+def sctid_partition(sctid: str) -> str | None:
+    """The 2-digit partition identifier (concept/description/relationship)."""
+    if len(sctid) < 3:
+        return None
+    return sctid[-3:-1]
+
+
+def is_valid_sctid(code: str, concept_only: bool = True) -> bool:
+    """Shape + Verhoeff validation (does NOT confirm DB existence).
+
+    ``concept_only`` (default True): also require the partition to be a *concept*
+    (2nd partition digit == '0'), so description/relationship ids are rejected.
+    """
+    if not code:
+        return False
+    code = code.strip()
+    if not _SCTID_SHAPE.match(code) or not verhoeff_ok(code):
+        return False
+    if concept_only:
+        part = sctid_partition(code)
+        if part is None or part[1] != "0":   # 2nd digit: 0=Concept,1=Desc,2=Rel
+            return False
+    return True

aimedicalcoding/core/models.py

@@ -0,0 +1,149 @@
+"""Canonical intermediate representation (IR).
+
+Every format adapter emits ``ClinicalStatement`` objects; terminology handlers
+and the recovery layer consume them and produce ``NormalizedRecord`` objects.
+The IR is deliberately format-agnostic: nothing here knows about XML or JSON.
+
+See ARCHITECTURE.md §3 and LOINC_pattern_analysis.md §6/§7.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class System(str, Enum):
+    """Canonical code systems. Adapters map raw OIDs/URIs/names to these."""
+
+    LOINC = "LOINC"
+    SNOMEDCT = "SNOMED-CT"
+    RXNORM = "RxNorm"
+    ICD10CM = "ICD-10-CM"
+    ICD9CM = "ICD-9-CM"
+    ICD10PCS = "ICD-10-PCS"
+    CPT = "CPT"
+    HCPCS = "HCPCS"
+    NDC = "NDC"
+    MULTUM = "Multum"           # Cerner Multum drug vocab → RxNorm
+    FDB = "FDB"                 # First DataBank / NDDF → RxNorm
+    MEDISPAN = "Medi-Span"      # Medi-Span GPI / DDID → RxNorm
+    UNII = "UNII"
+    UCUM = "UCUM"
+    CVX = "CVX"
+    # HL7 internal vocabularies (not recovery targets, but seen on nodes)
+    HL7_ACTCODE = "HL7-ActCode"
+    HL7_OBS_INTERP = "HL7-ObservationInterpretation"
+    HL7_ADMIN_GENDER = "HL7-AdministrativeGender"
+    HL7_ACTCLASS = "HL7-ActClass"               # structural: class of an act
+    HL7_ACTMOOD = "HL7-ActMood"                 # structural: mood (EVN/INT/…)
+    HL7_ROLECLASS = "HL7-RoleClass"             # structural: role class
+    HL7_PARTICIPATIONTYPE = "HL7-ParticipationType"  # structural: participation
+    NULLFLAVOR = "HL7-NullFlavor"
+    LOCAL = "LOCAL"           # any local/source-specific system
+    UNKNOWN = "UNKNOWN"       # system string present but unrecognized
+
+
+# Value "type" mirrors the LOINC Scale axis. Adapters infer it from the
+# document (CCDA xsi:type, FHIR value[x]); handlers cross-check it against
+# the resolved code's Scale.
+QN = "Qn"      # quantitative (numeric + unit)
+ORD = "Ord"    # ordinal (Positive/Negative, +/++/+++)
+NOM = "Nom"    # nominal (a coded answer)
+NAR = "Nar"    # narrative free text
+DOC = "Doc"    # attached document
+
+
+@dataclass
+class CodingCandidate:
+    """One (system, code) pairing found on a node. A node may have several:
+    the root code plus CCDA ``<translation>`` children / FHIR ``coding[]``.
+    """
+
+    raw_system: Optional[str] = None       # exactly what the document said
+    system: Optional[System] = None        # canonicalized (None until resolved)
+    code: Optional[str] = None
+    display: Optional[str] = None
+    original_text: Optional[str] = None    # resolved <originalText> for this code, if any
+    from_translation: bool = False         # came from <translation>/secondary coding
+    user_selected: bool = False            # FHIR coding.userSelected
+    check_digit_valid: Optional[bool] = None  # set by validators where applicable
+
+    def is_system(self, system: System) -> bool:
+        return self.system == system
+
+
+@dataclass
+class ValueInfo:
+    type: Optional[str] = None             # QN | ORD | NOM | NAR | DOC
+    raw: Optional[str] = None              # raw textual value
+    num: Optional[float] = None            # parsed numeric, if Qn
+    unit: Optional[str] = None
+    unit_system: Optional[str] = None      # e.g. "UCUM"
+    coded_value: Optional[CodingCandidate] = None  # the primary coded answer (root)
+    codings: list[CodingCandidate] = field(default_factory=list)  # root + <translation>s
+    original_text: Optional[str] = None    # the value's own resolved <originalText>
+
+
+@dataclass
+class ClinicalStatement:
+    """Format-agnostic unit of coded clinical data emitted by every adapter."""
+
+    source_format: str                     # ccda | fhir | custom
+    source_ref: str                        # xpath / fhir-path / json-pointer (provenance)
+    context: str                           # result | vital | problem | medication |
+                                           # survey | social_history | section | document_type
+    section_code: Optional[str] = None     # the section's code (LOINC for CCDA, category for FHIR)
+    section_name: Optional[str] = None     # the section's display name (e.g. "Results")
+    section_system: Optional[str] = None   # canonical system of section_code (e.g. "LOINC")
+    role: str = "value"                    # value | question
+    target_system_hint: Optional[System] = None  # adapter routing hint
+    raw_text: Optional[str] = None         # best-effort concept label (display/originalText/…)
+    display_name: Optional[str] = None     # the coded displayName (structured label)
+    original_text: Optional[str] = None    # the clinician's free text (resolved <originalText>)
+    codings: list[CodingCandidate] = field(default_factory=list)
+    value: Optional[ValueInfo] = None
+    effective_time: Optional[str] = None
+    panel: Optional[CodingCandidate] = None       # parent organizer / panel code
+    companion: dict[str, Any] = field(default_factory=dict)  # interpretation, ref range, specimen…
+
+    # --- convenience for downstream layers -------------------------------
+    def coding_for(self, system: System) -> Optional[CodingCandidate]:
+        """Return the first validated coding for ``system`` (root preferred)."""
+        hits = [c for c in self.codings if c.system == system]
+        if not hits:
+            return None
+        roots = [c for c in hits if not c.from_translation]
+        return roots[0] if roots else hits[0]
+
+    def has_any_code(self) -> bool:
+        return any(c.code for c in self.codings)
+
+
+@dataclass
+class Gap:
+    """Why a code is missing/untrustworthy — the handoff to the recovery layer.
+
+    type is one of: NO_CODE_TEXT_PRESENT | LOCAL_CODE_ONLY | NULLFLAVOR |
+    NARRATIVE_ONLY | BAD_CODE | DEPRECATED | AXIS_MISMATCH | AMBIGUOUS
+    """
+
+    type: str
+    match_key: Optional[str] = None
+    candidates: list[Any] = field(default_factory=list)  # DB candidate set for recovery
+    evidence: dict[str, Any] = field(default_factory=dict)  # recovery evidence packet
+    note: Optional[str] = None
+
+
+@dataclass
+class NormalizedRecord:
+    """Final output: a resolved (or gap-flagged) statement."""
+
+    statement: ClinicalStatement
+    resolved_system: Optional[System] = None
+    resolved_code: Optional[str] = None
+    resolved_display: Optional[str] = None
+    source: Optional[str] = None           # db_exact | db_translation | db_candidate+llm | llm_only
+    confidence: Optional[float] = None
+    gap: Optional[Gap] = None

aimedicalcoding/core/system_registry.py

@@ -0,0 +1,185 @@
+"""Single source of truth for code-system identity.
+
+Maps every alias a document might use — HL7 V3 OID, FHIR URI, ``urn:oid:`` form,
+or free-text name — to a canonical ``System`` enum. Adapters canonicalize here;
+handlers match on the enum only.
+
+Rule (ARCHITECTURE.md §7): identify by system, never by code shape or display
+name alone. ``canonicalize`` returns ``System.UNKNOWN`` when a system string is
+present but unrecognized, and ``None`` when no system string was given at all.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .models import System
+
+# OID (HL7 V3 / CCDA codeSystem) -> System
+_OID = {
+    "2.16.840.1.113883.6.1": System.LOINC,
+    "2.16.840.1.113883.6.96": System.SNOMEDCT,
+    "2.16.840.1.113883.6.88": System.RXNORM,
+    "2.16.840.1.113883.6.90": System.ICD10CM,
+    "2.16.840.1.113883.6.103": System.ICD9CM,        # ICD-9-CM diagnosis
+    "2.16.840.1.113883.6.104": System.ICD9CM,        # ICD-9-CM procedure
+    "2.16.840.1.113883.6.4": System.ICD10PCS,
+    "2.16.840.1.113883.6.12": System.CPT,
+    "2.16.840.1.113883.6.285": System.HCPCS,
+    "2.16.840.1.113883.6.69": System.NDC,
+    # Cerner Multum drug vocabulary
+    "2.16.840.1.113883.6.314": System.MULTUM,   # Multum drug id
+    "2.16.840.1.113883.6.312": System.MULTUM,   # Multum drug synonym id
+    "2.16.840.1.113883.6.311": System.MULTUM,   # Multum main drug code
+    "2.16.840.1.113883.6.27": System.MULTUM,    # Multum
+    # First DataBank / NDDF
+    "2.16.840.1.113883.6.208": System.FDB,      # NDDF
+    "2.16.840.1.113883.6.64": System.FDB,       # First DataBank
+    "2.16.840.1.113883.4.65": System.FDB,       # FDB HIC_SEQN
+    # Medi-Span
+    "2.16.840.1.113883.6.68": System.MEDISPAN,  # Medi-Span GPI
+    "2.16.840.1.113883.6.253": System.MEDISPAN, # Medi-Span Drug Descriptor ID (MDDID)
+    "2.16.840.1.113883.6.162": System.MEDISPAN, # Med-File
+    "2.16.840.1.113883.6.65": System.MEDISPAN,  # Medispan
+    "2.16.840.1.113883.4.9": System.UNII,
+    "2.16.840.1.113883.6.8": System.UCUM,
+    "2.16.840.1.113883.12.292": System.CVX,
+    "2.16.840.1.113883.5.4": System.HL7_ACTCODE,
+    "2.16.840.1.113883.5.6": System.HL7_ACTCLASS,            # ActClass (structural)
+    "2.16.840.1.113883.5.1001": System.HL7_ACTMOOD,          # ActMood (structural)
+    "2.16.840.1.113883.5.110": System.HL7_ROLECLASS,         # RoleClass (structural)
+    "2.16.840.1.113883.5.90": System.HL7_PARTICIPATIONTYPE,  # ParticipationType (structural)
+    "2.16.840.1.113883.5.83": System.HL7_OBS_INTERP,
+    "2.16.840.1.113883.5.1": System.HL7_ADMIN_GENDER,
+    "2.16.840.1.113883.5.1008": System.NULLFLAVOR,
+}
+
+# FHIR URI -> System (store canonical, lowercase, no trailing slash)
+_URI = {
+    "http://loinc.org": System.LOINC,
+    "http://snomed.info/sct": System.SNOMEDCT,
+    "http://www.nlm.nih.gov/research/umls/rxnorm": System.RXNORM,
+    "http://hl7.org/fhir/sid/icd-10-cm": System.ICD10CM,
+    "http://hl7.org/fhir/sid/icd-10": System.ICD10CM,
+    "http://hl7.org/fhir/sid/icd-9-cm": System.ICD9CM,
+    "http://hl7.org/fhir/sid/icd-9-cm/diagnosis": System.ICD9CM,
+    "http://hl7.org/fhir/sid/icd-9-cm/procedure": System.ICD9CM,
+    "http://www.cms.gov/medicare/coding/icd10": System.ICD10PCS,
+    "http://www.icd10data.com/icd10pcs": System.ICD10PCS,
+    "http://www.ama-assn.org/go/cpt": System.CPT,
+    "urn:oid:2.16.840.1.113883.6.285": System.HCPCS,
+    "http://www.nlm.nih.gov/research/umls/hcpcs": System.HCPCS,
+    "http://www.cms.gov/medicare/coding/hcpcsreleasecodesets": System.HCPCS,
+    "https://terminology.hl7.org/codesystem/hcpcs-all-codes": System.HCPCS,
+    "http://hl7.org/fhir/sid/ndc": System.NDC,
+    "http://fdasis.nlm.nih.gov": System.UNII,
+    "http://unitsofmeasure.org": System.UCUM,
+    "http://hl7.org/fhir/sid/cvx": System.CVX,
+    # HL7 terminology.hl7.org forms (FHIR R4). The v3-* vocabularies are
+    # structural — mapping them here keeps them out of LOCAL_CODE_ONLY gaps.
+    "http://terminology.hl7.org/codesystem/v3-actcode": System.HL7_ACTCODE,
+    "http://terminology.hl7.org/codesystem/v3-actclass": System.HL7_ACTCLASS,
+    "http://terminology.hl7.org/codesystem/v3-actmood": System.HL7_ACTMOOD,
+    "http://terminology.hl7.org/codesystem/v3-roleclass": System.HL7_ROLECLASS,
+    "http://terminology.hl7.org/codesystem/v3-participationtype": System.HL7_PARTICIPATIONTYPE,
+    "http://terminology.hl7.org/codesystem/v3-observationinterpretation": System.HL7_OBS_INTERP,
+    "http://terminology.hl7.org/codesystem/v3-administrativegender": System.HL7_ADMIN_GENDER,
+    # FHIR's nullFlavor analog: dataAbsentReason codings
+    "http://terminology.hl7.org/codesystem/data-absent-reason": System.NULLFLAVOR,
+}
+
+# Free-text name (codeSystemName / custom "code_system") -> System.
+# Matched case-insensitively after stripping punctuation/whitespace.
+_NAME = {
+    "loinc": System.LOINC,
+    "snomed": System.SNOMEDCT,
+    "snomedct": System.SNOMEDCT,
+    "snomedctus": System.SNOMEDCT,
+    "rxnorm": System.RXNORM,
+    "icd10cm": System.ICD10CM,
+    "icd10": System.ICD10CM,
+    "icd9cm": System.ICD9CM,
+    "icd9": System.ICD9CM,
+    "icd10pcs": System.ICD10PCS,
+    "cpt": System.CPT,
+    "cpt4": System.CPT,
+    "hcpcs": System.HCPCS,
+    "ndc": System.NDC,
+    "multum": System.MULTUM,
+    "multumgenericdrug": System.MULTUM,
+    "multumgenericdrugidentifier": System.MULTUM,
+    "multumdrugid": System.MULTUM,
+    "nddf": System.FDB,
+    "firstdatabank": System.FDB,
+    "fdb": System.FDB,
+    "medispan": System.MEDISPAN,
+    "medispangpi": System.MEDISPAN,
+    "gpi": System.MEDISPAN,
+    "mddid": System.MEDISPAN,
+    "medfile": System.MEDISPAN,
+    "unii": System.UNII,
+    "ucum": System.UCUM,
+    "cvx": System.CVX,
+}
+
+_URN_OID_PREFIX = "urn:oid:"
+
+# HL7 V3 structural vocabularies — present on nodes but never clinical recovery
+# targets (the real concept lives elsewhere, usually in <value>). Handlers exclude
+# these so a structural code (ASSERTION / ActClass / ActMood …) is not mistaken
+# for a local concept gap. Single source of truth; handlers import this.
+HL7_STRUCTURAL: frozenset = frozenset({
+    System.HL7_ACTCODE,
+    System.HL7_OBS_INTERP,
+    System.HL7_ADMIN_GENDER,
+    System.HL7_ACTCLASS,
+    System.HL7_ACTMOOD,
+    System.HL7_ROLECLASS,
+    System.HL7_PARTICIPATIONTYPE,
+})
+
+
+def _norm_name(s: str) -> str:
+    return "".join(ch for ch in s.lower() if ch.isalnum())
+
+
+def canonicalize(raw_system: Optional[str]) -> Optional[System]:
+    """Resolve any raw system identifier to a canonical ``System``.
+
+    Returns ``None`` if ``raw_system`` is falsy (no system asserted),
+    ``System.UNKNOWN`` if a value is present but unrecognized.
+    """
+    if not raw_system:
+        return None
+    s = raw_system.strip()
+
+    # urn:oid: form (FHIR may carry an OID this way). Unrecognized deep OIDs
+    # (e.g. Epic 1.2.840.114350.…) are LOCAL, same as the bare-OID branch.
+    if s.lower().startswith(_URN_OID_PREFIX):
+        oid = s[len(_URN_OID_PREFIX):]
+        return _OID.get(oid, System.LOCAL if oid.count(".") > 4 else System.UNKNOWN)
+
+    # bare OID
+    if _looks_like_oid(s):
+        return _OID.get(s, System.LOCAL if s.count(".") > 4 else System.UNKNOWN)
+
+    # URI (normalize: lowercase scheme/host, strip trailing slash)
+    if "://" in s:
+        return _URI.get(s.rstrip("/").lower(), System.UNKNOWN)
+
+    # free-text name
+    return _NAME.get(_norm_name(s), System.UNKNOWN)
+
+
+def _looks_like_oid(s: str) -> bool:
+    parts = s.split(".")
+    return len(parts) >= 3 and all(p.isdigit() for p in parts)
+
+
+def system_aliases(system: System) -> dict[str, list[str]]:
+    """Reverse lookup — useful for tests/diagnostics."""
+    return {
+        "oids": [k for k, v in _OID.items() if v == system],
+        "uris": [k for k, v in _URI.items() if v == system],
+        "names": [k for k, v in _NAME.items() if v == system],
+    }

aimedicalcoding/pipeline/__init__.py

@@ -0,0 +1,3 @@
+from .orchestrator import parse_document, detect_adapter
+
+__all__ = ["parse_document", "detect_adapter"]

aimedicalcoding/pipeline/orchestrator.py

@@ -0,0 +1,33 @@
+"""Pipeline entry point (parsing phase).
+
+Detects the input format and runs the matching adapter to produce the IR.
+Routing to terminology handlers + recovery is stubbed until those layers land.
+See ARCHITECTURE.md §2/§5.6.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..adapters.base import FormatAdapter
+from ..adapters.ccda import CcdaAdapter
+from ..adapters.fhir import FhirAdapter
+from ..core.models import ClinicalStatement
+
+# Detection order matters: CCDA (XML) and FHIR (JSON) are mutually exclusive.
+_ADAPTERS: list[FormatAdapter] = [CcdaAdapter(), FhirAdapter()]
+
+
+def detect_adapter(document: str | bytes) -> Optional[FormatAdapter]:
+    for adapter in _ADAPTERS:
+        if adapter.detect(document):
+            return adapter
+    return None
+
+
+def parse_document(document: str | bytes) -> list[ClinicalStatement]:
+    """Detect format and return the parsed IR statements."""
+    adapter = detect_adapter(document)
+    if adapter is None:
+        raise ValueError("Unrecognized document format (no adapter matched).")
+    return list(adapter.parse(document))

aimedicalcoding/recovery/__init__.py

@@ -0,0 +1,3 @@
+from .engine import RecoveryEngine
+
+__all__ = ["RecoveryEngine"]