aimedicalcoding 0.3.1__py3-none-any.whl

aimedicalcoding/systems/loinc/patterns.py

@@ -0,0 +1,166 @@
+"""Per-pattern LOINC gap classification + dedicated parsers.
+
+Each LOINC gap pattern has its own parser that builds a tailored ``Gap`` (with
+the shared evidence packet plus pattern-specific recovery hints). Valid,
+already-coded LOINCs return None — they need no correction/filling.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from ...core.checkdigits import correct_loinc_check_digit
+from ...core.models import ClinicalStatement, Gap, System
+from ...core.system_registry import HL7_STRUCTURAL
+from . import axes
+
+# Entry-level contexts where a LOINC code is expected on the observation.
+LOINC_ENTRY_CONTEXTS = {
+    "result", "vital", "social_history", "functional_status", "survey", "assessment",
+}
+
+# HL7 structural vocabularies that are NOT clinical codes. When one of these is
+# the only code on an observation (e.g. code="ASSERTION"), the real concept
+# lives in <value> (often SNOMED), so it is NOT a LOINC gap.
+STRUCTURAL_SYSTEMS = HL7_STRUCTURAL
+
+
+class GapPattern(str, Enum):
+    LOCAL_CODE_ONLY = "LOCAL_CODE_ONLY"   # a local code, but no LOINC
+    NULLFLAVOR = "NULLFLAVOR"             # nullFlavor code, label via originalText
+    DISPLAY_ONLY = "DISPLAY_ONLY"         # displayName present, no code attr
+    NARRATIVE_ONLY = "NARRATIVE_ONLY"     # value/label only in narrative table
+    BAD_CODE = "BAD_CODE"                 # LOINC-shaped but check digit fails
+
+
+def is_loinc_expected(stmt: ClinicalStatement) -> bool:
+    """True if a LOINC code belongs on this observation (so a missing/bad one
+    is a real correction target)."""
+    return (
+        stmt.target_system_hint == System.LOINC
+        and stmt.context in LOINC_ENTRY_CONTEXTS
+        and (stmt.raw_text is not None or stmt.value is not None)
+    )
+
+
+def classify(stmt: ClinicalStatement) -> Optional[GapPattern]:
+    """Return the gap pattern, or None if no correction/filling is needed."""
+    if not is_loinc_expected(stmt):
+        return None
+
+    loinc = stmt.coding_for(System.LOINC)
+
+    # A valid LOINC is present (root OR translation) -> nothing to do.
+    # (Deprecation re-mapping is deferred to the DB layer.)
+    if loinc and loinc.check_digit_valid:
+        return None
+
+    # LOINC-shaped but check digit fails -> correctable.
+    if loinc and loinc.check_digit_valid is False:
+        return GapPattern.BAD_CODE
+
+    # No usable LOINC. Distinguish real clinical codes from HL7 structural codes.
+    clinical_codes = [
+        c for c in stmt.codings
+        if c.code and c.system not in STRUCTURAL_SYSTEMS and c.system != System.NULLFLAVOR
+    ]
+    structural_only = (
+        not clinical_codes
+        and any(c.code and c.system in STRUCTURAL_SYSTEMS for c in stmt.codings)
+    )
+
+    # code="ASSERTION" etc. -> the concept is in <value> (e.g. SNOMED), not LOINC.
+    if structural_only:
+        return None
+
+    if clinical_codes:
+        return GapPattern.LOCAL_CODE_ONLY
+
+    has_nullflavor = any(c.system == System.NULLFLAVOR for c in stmt.codings)
+    if has_nullflavor:
+        return GapPattern.NULLFLAVOR
+    # no codings at all -> narrative vs structured display-only
+    if "/text" in (stmt.source_ref or ""):
+        return GapPattern.NARRATIVE_ONLY
+    return GapPattern.DISPLAY_ONLY
+
+
+# --------------------------------------------------------------------------
+# Per-pattern parsers: each returns a Gap with the evidence packet + hints.
+# --------------------------------------------------------------------------
+
+def parse_local_code_only(stmt: ClinicalStatement, expand_abbrev: bool = False) -> Gap:
+    local = next((c for c in stmt.codings if c.code and c.system != System.LOINC), None)
+    ev = axes.evidence_packet(stmt, expand_abbrev)
+    ev["local_code"] = local.code if local else None
+    ev["local_system"] = (local.raw_system if local else None)
+    return Gap(
+        type=GapPattern.LOCAL_CODE_ONLY.value,
+        match_key=axes.build_match_key(stmt, expand_abbrev),
+        evidence=ev,
+        note="Try (source_system, local_code) crosswalk FIRST; fall back to "
+             "text+axis search, then LLM. Cache the resolved mapping.",
+    )
+
+
+def parse_nullflavor(stmt: ClinicalStatement, expand_abbrev: bool = False) -> Gap:
+    nf = next((c for c in stmt.codings if c.system == System.NULLFLAVOR), None)
+    ev = axes.evidence_packet(stmt, expand_abbrev)
+    ev["null_flavor"] = nf.raw_system if nf else None
+    return Gap(
+        type=GapPattern.NULLFLAVOR.value,
+        match_key=axes.build_match_key(stmt, expand_abbrev),
+        evidence=ev,
+        note="Label recovered from originalText/narrative; resolve via "
+             "text+axis search then LLM.",
+    )
+
+
+def parse_display_only(stmt: ClinicalStatement, expand_abbrev: bool = False) -> Gap:
+    return Gap(
+        type=GapPattern.DISPLAY_ONLY.value,
+        match_key=axes.build_match_key(stmt, expand_abbrev),
+        evidence=axes.evidence_packet(stmt, expand_abbrev),
+        note="displayName present, no code attribute; resolve via text+axis search.",
+    )
+
+
+def parse_narrative_only(stmt: ClinicalStatement, expand_abbrev: bool = False) -> Gap:
+    return Gap(
+        type=GapPattern.NARRATIVE_ONLY.value,
+        match_key=axes.build_match_key(stmt, expand_abbrev),
+        evidence=axes.evidence_packet(stmt, expand_abbrev),
+        note="No structured entry; row parsed from narrative table. Unit + "
+             "reference range present to constrain candidates.",
+    )
+
+
+def parse_bad_code(stmt: ClinicalStatement, expand_abbrev: bool = False) -> Gap:
+    loinc = stmt.coding_for(System.LOINC)
+    bad = loinc.code if loinc else None
+    ev = axes.evidence_packet(stmt, expand_abbrev)
+    ev["malformed_code"] = bad
+    ev["checkdigit_correction"] = correct_loinc_check_digit(bad) if bad else None
+    return Gap(
+        type=GapPattern.BAD_CODE.value,
+        match_key=axes.build_match_key(stmt, expand_abbrev),
+        evidence=ev,
+        note="LOINC shape with failed check digit. If only the check digit is "
+             "wrong, 'checkdigit_correction' is the likely fix; still confirm "
+             "against text+axis before applying.",
+    )
+
+
+_PARSERS = {
+    GapPattern.LOCAL_CODE_ONLY: parse_local_code_only,
+    GapPattern.NULLFLAVOR: parse_nullflavor,
+    GapPattern.DISPLAY_ONLY: parse_display_only,
+    GapPattern.NARRATIVE_ONLY: parse_narrative_only,
+    GapPattern.BAD_CODE: parse_bad_code,
+}
+
+
+def parse_gap(stmt: ClinicalStatement, pattern: GapPattern,
+              expand_abbrev: bool = False) -> Gap:
+    return _PARSERS[pattern](stmt, expand_abbrev)

aimedicalcoding/systems/rxnorm/__init__.py

@@ -0,0 +1,13 @@
+"""RxNorm gap extraction (medications).
+
+The drug concept lives on the code slot (CCDA manufacturedMaterial/code, FHIR
+medicationCodeableConcept). RxCUI has NO check digit — validity is DB existence +
+TTY, so a present RxNorm code is treated as resolved here. The dominant recovery
+path is the NDC↔RxNorm crosswalk. DB lookup and LLM ranking are placeholders.
+See RxNorm_pattern_analysis.md.
+"""
+
+from .handler import RxnormGapExtractor, RxnormGapPattern
+from .patterns import classify, is_rxnorm_expected
+
+__all__ = ["RxnormGapExtractor", "RxnormGapPattern", "classify", "is_rxnorm_expected"]

aimedicalcoding/systems/rxnorm/handler.py

@@ -0,0 +1,55 @@
+"""RxnormGapExtractor — RxNorm-only, gaps-only entry point (medications)."""
+
+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 RxnormGapPattern
+
+__all__ = ["RxnormGapExtractor", "RxnormGapPattern"]
+
+
+class RxnormGapExtractor:
+    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 RxnormGapPattern.NARRATIVE_ONLY and not include_narrative:
+                continue
+            records.append(NormalizedRecord(
+                statement=stmt,
+                resolved_system=System.RXNORM,
+                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/rxnorm/normalize.py

@@ -0,0 +1,88 @@
+"""Parse the disambiguating drug attributes from a medication label.
+
+RxNorm's analog of LOINC axes / SNOMED hierarchy is: ingredient + strength +
+dose form + route (+ brand) → the TTY level (we target SCD/SBD).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+_STRENGTH = re.compile(
+    r"(\d+(?:\.\d+)?)\s*(mg|mcg|g|ml|%|unit|units|iu|meq|mmol)\b", re.I)
+
+# longest-first so "extended release oral tablet" wins over "oral tablet"
+_DOSE_FORMS = [
+    "extended release oral tablet", "extended release oral capsule",
+    "oral tablet", "oral capsule", "oral solution", "oral suspension",
+    "delayed release tablet", "chewable tablet",
+    "injection", "injectable solution", "ophthalmic solution",
+    "tablet", "capsule", "solution", "suspension", "cream", "ointment",
+    "patch", "inhaler", "suppository", "lotion", "gel", "spray", "syrup",
+]
+_ROUTES = ["oral", "intravenous", "iv", "topical", "subcutaneous",
+           "intramuscular", "inhalation", "rectal", "nasal", "ophthalmic"]
+
+_WS = re.compile(r"\s+")
+
+
+def parse_strength(text: Optional[str]) -> Optional[str]:
+    if not text:
+        return None
+    m = _STRENGTH.search(text)
+    return f"{m.group(1)} {m.group(2).upper()}" if m else None
+
+
+def parse_strengths(text: Optional[str]) -> list[str]:
+    """ALL strength tokens (combination products carry more than one)."""
+    if not text:
+        return []
+    return [f"{n} {u.upper()}" for n, u in _STRENGTH.findall(text)]
+
+
+def is_combination(text: Optional[str]) -> bool:
+    """A multi-ingredient product ("amlodipine 5 MG / benazepril 10 MG").
+
+    Detected by more than one distinct strength, or an ingredient-joining slash.
+    NOTE: '-' is NOT used — it appears inside salt names (e.g. metoprolol
+    tartrate). Combos map to a *combination* SCD, so a single-ingredient key
+    would resolve the wrong drug.
+    """
+    if not text:
+        return False
+    if len(set(parse_strengths(text))) > 1:
+        return True
+    # a slash between two alphabetic ingredient tokens (not a unit like mg/ml)
+    return bool(re.search(r"[A-Za-z]{3,}\s*/\s*[A-Za-z]{3,}", text))
+
+
+def parse_dose_form(text: Optional[str]) -> Optional[str]:
+    t = (text or "").lower()
+    for f in _DOSE_FORMS:
+        if f in t:
+            return f
+    return None
+
+
+def parse_route(text: Optional[str]) -> Optional[str]:
+    t = (text or "").lower()
+    for r in _ROUTES:
+        if re.search(rf"\b{re.escape(r)}\b", t):
+            return r
+    return None
+
+
+def normalize_ingredient(text: Optional[str]) -> Optional[str]:
+    """Rough ingredient: the label minus strength and dose-form words."""
+    if not text:
+        return None
+    t = text.lower()
+    t = _STRENGTH.sub(" ", t)
+    for f in _DOSE_FORMS:
+        t = t.replace(f, " ")
+    for r in _ROUTES:
+        t = re.sub(rf"\b{re.escape(r)}\b", " ", t)
+    t = re.sub(r"[^\w\s/+-]", " ", t)
+    t = _WS.sub(" ", t).strip(" -/")
+    return t or None

aimedicalcoding/systems/rxnorm/patterns.py

@@ -0,0 +1,143 @@
+"""Per-pattern RxNorm gap classification + parsers (medications, code slot)."""
+
+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
+
+RXNORM_CONTEXTS = {"medication"}
+STRUCTURAL = HL7_STRUCTURAL | {System.NULLFLAVOR}
+TARGET_TTY = "SCD|SBD"   # the prescribable level we aim to resolve to
+
+
+class RxnormGapPattern(str, Enum):
+    NDC_ONLY = "NDC_ONLY"                 # NDC present, no RxNorm -> NDC↔RxNorm crosswalk
+    MULTUM_ONLY = "MULTUM_ONLY"           # Cerner Multum drug code -> Multum↔RxNorm (UMLS)
+    FDB_ONLY = "FDB_ONLY"                 # First DataBank / NDDF code -> FDB↔RxNorm (UMLS)
+    MEDISPAN_ONLY = "MEDISPAN_ONLY"       # Medi-Span GPI / DDID -> Medi-Span↔RxNorm (UMLS)
+    LOCAL_CODE_ONLY = "LOCAL_CODE_ONLY"   # local/formulary code, no RxNorm
+    NULLFLAVOR = "NULLFLAVOR"
+    DISPLAY_ONLY = "DISPLAY_ONLY"
+    NARRATIVE_ONLY = "NARRATIVE_ONLY"
+
+
+# Proprietary drug source vocabularies that crosswalk to RxNorm via UMLS.
+# Each maps to its own gap pattern so the recovery layer runs the right crosswalk.
+_SOURCE_VOCAB_PATTERN = {
+    System.MULTUM: RxnormGapPattern.MULTUM_ONLY,
+    System.FDB: RxnormGapPattern.FDB_ONLY,
+    System.MEDISPAN: RxnormGapPattern.MEDISPAN_ONLY,
+}
+
+
+def is_rxnorm_expected(stmt: ClinicalStatement) -> bool:
+    return (
+        stmt.context in RXNORM_CONTEXTS
+        and (stmt.raw_text is not None or stmt.codings)
+    )
+
+
+def concept_coding(stmt: ClinicalStatement) -> Optional[CodingCandidate]:
+    """Meds 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[RxnormGapPattern]:
+    if not is_rxnorm_expected(stmt):
+        return None
+
+    cc = concept_coding(stmt)
+
+    # RxCUI present -> resolved (no checksum; existence/TTY checks need the DB).
+    if cc and cc.system == System.RXNORM and cc.code:
+        return None
+
+    if cc and cc.code and cc.system == System.NDC:
+        return RxnormGapPattern.NDC_ONLY
+    if cc and cc.code and cc.system in _SOURCE_VOCAB_PATTERN:
+        return _SOURCE_VOCAB_PATTERN[cc.system]   # Multum / FDB / Medi-Span
+    if cc and cc.code and cc.system not in STRUCTURAL:
+        return RxnormGapPattern.LOCAL_CODE_ONLY   # local/formulary/other
+
+    if _has_nullflavor(stmt):
+        return RxnormGapPattern.NULLFLAVOR
+    if stmt.raw_text:
+        if "/text" in (stmt.source_ref or ""):
+            return RxnormGapPattern.NARRATIVE_ONLY
+        return RxnormGapPattern.DISPLAY_ONLY
+    return None
+
+
+# --------------------------------------------------------------------------
+
+def _match_key(stmt: ClinicalStatement) -> str:
+    t = stmt.raw_text
+    combo = N.is_combination(t)
+    strength = " + ".join(N.parse_strengths(t)) if combo else (N.parse_strength(t) or "-")
+    return " | ".join([
+        f"ingredient:{N.normalize_ingredient(t) or '?'}",
+        f"strength:{strength}",
+        f"dose_form:{N.parse_dose_form(t) or '-'}",
+        f"route:{N.parse_route(t) or '-'}",
+        f"combination:{'yes' if combo else 'no'}",
+        f"target_tty:{TARGET_TTY}",
+    ])
+
+
+def _evidence(stmt: ClinicalStatement) -> dict:
+    t = stmt.raw_text
+    combo = N.is_combination(t)
+    return {
+        "term": t,
+        "ingredient": N.normalize_ingredient(t),
+        "strength": N.parse_strength(t),
+        "strengths": N.parse_strengths(t),          # all strengths (combos carry >1)
+        "is_combination": combo,                    # multi-ingredient -> combination SCD
+        "dose_form": N.parse_dose_form(t),
+        "route": N.parse_route(t),
+        "target_tty": TARGET_TTY,
+        "section_context": stmt.context,
+    }
+
+
+def parse_gap(stmt: ClinicalStatement, pattern: RxnormGapPattern) -> Gap:
+    gap = Gap(type=pattern.value, match_key=_match_key(stmt), evidence=_evidence(stmt))
+    cc = concept_coding(stmt)
+
+    if pattern == RxnormGapPattern.NDC_ONLY and cc:
+        gap.evidence["ndc_code"] = cc.code
+        gap.evidence["ndc_system"] = cc.raw_system
+        gap.note = ("Use the NDC↔RxNorm crosswalk (RxNorm release / REST API) — "
+                    "deterministic; LLM only if multiple RxCUIs map.")
+    elif pattern in _SOURCE_VOCAB_PATTERN.values() and cc:
+        vocab = cc.system.value if cc.system else "source vocabulary"
+        gap.evidence["source_code"] = cc.code
+        gap.evidence["source_vocab"] = vocab
+        gap.evidence["source_system"] = cc.raw_system
+        # serialize.py builds a crosswalk hint from local_code/local_system
+        gap.evidence["local_code"] = cc.code
+        gap.evidence["local_system"] = vocab
+        gap.note = (f"Crosswalk {vocab} → RxNorm via the UMLS Metathesaurus "
+                    f"(shared CUI) or the vendor's RxNorm map — deterministic; "
+                    f"LLM only if the mapping is ambiguous or 1→many.")
+    elif pattern == RxnormGapPattern.LOCAL_CODE_ONLY and cc:
+        gap.evidence["local_code"] = cc.code
+        gap.evidence["local_system"] = cc.raw_system
+        gap.note = ("Crosswalk local/formulary code → RxNorm first; else search by "
+                    "ingredient + strength + dose form → SCD/SBD.")
+    elif pattern == RxnormGapPattern.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 = "Drug name recovered from narrative; search ingredient+strength+form → SCD/SBD."
+    else:
+        gap.note = "Drug name only; parse strength/form and search → SCD/SBD."
+    return gap

aimedicalcoding/systems/snomed/__init__.py

@@ -0,0 +1,15 @@
+"""SNOMED CT gap extraction.
+
+Mirrors systems/loinc but for SNOMED CT: SNOMED is the *answer/value* (diagnosis,
+allergen, procedure, organism…), not the question. "Expected" is decided by the
+section/slot → target hierarchy (see config/snomed_section_bindings.yaml and
+SNOMED_pattern_analysis.md). Emits ONLY codes needing correction/filling.
+
+DB lookup (active/inactive, hierarchy, ECL/value-set candidate search) and LLM
+ranking remain placeholders; this layer prepares everything they need.
+"""
+
+from .handler import SnomedGapExtractor, SnomedGapPattern
+from .patterns import classify, is_snomed_expected
+
+__all__ = ["SnomedGapExtractor", "SnomedGapPattern", "classify", "is_snomed_expected"]

aimedicalcoding/systems/snomed/handler.py

@@ -0,0 +1,60 @@
+"""SnomedGapExtractor — SNOMED-only, gaps-only entry point.
+
+Same shape as LoincGapExtractor: document/IR in, gap NormalizedRecords out
+(only concepts needing correction/filling). resolved_* left for the DB/LLM step.
+"""
+
+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 SnomedGapPattern
+
+__all__ = ["SnomedGapExtractor", "SnomedGapPattern"]
+
+
+class SnomedGapExtractor:
+    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 SnomedGapPattern.NARRATIVE_ONLY and not include_narrative:
+                continue
+            gap = patterns.parse_gap(stmt, pattern)
+            records.append(NormalizedRecord(
+                statement=stmt,
+                resolved_system=System.SNOMEDCT,
+                resolved_code=None,
+                gap=gap,
+            ))
+        return records
+
+    def extract_from_document(
+        self,
+        document: str | bytes,
+        contexts: Optional[set[str]] = None,
+        include_narrative: bool = False,
+        apply_dict: bool = False,           # accepted for CLI parity; unused
+    ) -> 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/snomed/hierarchy.py

@@ -0,0 +1,96 @@
+"""Section/slot → target SNOMED hierarchy + ECL (the candidate constraint).
+
+Hard-codes the bindings from config/snomed_section_bindings.yaml (kept in code so
+the extractor has no YAML dependency at runtime; the YAML is the human/DB-layer
+reference). All root SCTIDs are Verhoeff-verified.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# top-level hierarchy roots (Verhoeff-verified)
+CLINICAL_FINDING = "404684003"
+PROCEDURE = "71388002"
+SITUATION = "243796009"
+OBSERVABLE = "363787002"
+BODY_STRUCTURE = "123037004"
+ORGANISM = "410607006"
+SUBSTANCE = "105590001"
+PRODUCT = "373873005"
+SPECIMEN = "123038009"
+QUALIFIER = "362981000"
+
+# context (as tagged by the adapter) -> (human label, ECL filter)
+CONTEXT_HIERARCHY: dict[str, tuple[str, str]] = {
+    "problem":           ("Clinical finding", f"< {CLINICAL_FINDING}"),
+    "family_history":    ("Finding/Situation", f"< {CLINICAL_FINDING} OR < {SITUATION}"),
+    "allergy_substance": ("Substance/Product", f"< {SUBSTANCE} OR < {PRODUCT}"),
+    "allergy_reaction":  ("Clinical finding", f"< {CLINICAL_FINDING}"),
+    "procedure":         ("Procedure", f"< {PROCEDURE}"),
+    "body_site":         ("Body structure", f"< {BODY_STRUCTURE}"),
+    "result_organism":   ("Organism", f"< {ORGANISM}"),
+    "social_history":    ("Clinical finding", f"< {CLINICAL_FINDING}"),
+    "functional_status": ("Clinical finding", f"< {CLINICAL_FINDING}"),
+    "specimen":          ("Specimen", f"< {SPECIMEN}"),
+}
+
+# contexts where a SNOMED concept is expected in the value/answer slot
+SNOMED_CONTEXTS = set(CONTEXT_HIERARCHY)
+
+# SNOMED FSN semantic tag (the trailing "(...)") -> top-level hierarchy root.
+# The document often carries the FSN, e.g. "Anticoagulant therapy (procedure)",
+# which states the hierarchy directly — far more reliable than the section
+# default (a Problem List legitimately holds findings, procedures AND situations).
+_SEMANTIC_TAG_ROOT: dict[str, str] = {
+    "finding": CLINICAL_FINDING,
+    "disorder": CLINICAL_FINDING,
+    "procedure": PROCEDURE,
+    "regime/therapy": PROCEDURE,
+    "situation": SITUATION,
+    "observable entity": OBSERVABLE,
+    "body structure": BODY_STRUCTURE,
+    "morphologic abnormality": BODY_STRUCTURE,
+    "organism": ORGANISM,
+    "substance": SUBSTANCE,
+    "product": PRODUCT,
+    "medicinal product": PRODUCT,
+    "clinical drug": PRODUCT,
+    "specimen": SPECIMEN,
+    "qualifier value": QUALIFIER,
+}
+_ROOT_LABEL: dict[str, str] = {
+    CLINICAL_FINDING: "Clinical finding", PROCEDURE: "Procedure",
+    SITUATION: "Situation", OBSERVABLE: "Observable entity",
+    BODY_STRUCTURE: "Body structure", ORGANISM: "Organism",
+    SUBSTANCE: "Substance", PRODUCT: "Product", SPECIMEN: "Specimen",
+    QUALIFIER: "Qualifier value",
+}
+_TAG_RE = re.compile(r"\(([^()]+)\)\s*$")
+
+
+def hierarchy_for(context: str) -> Optional[tuple[str, str]]:
+    """Return (label, ecl) for a context, or None if SNOMED isn't expected."""
+    return CONTEXT_HIERARCHY.get(context)
+
+
+def hierarchy_from_semantic_tag(term: Optional[str]) -> Optional[tuple[str, str]]:
+    """If a term ends in a SNOMED FSN semantic tag, return that hierarchy.
+    'Depression screening (procedure)' -> ('Procedure', '< 71388002')."""
+    if not term:
+        return None
+    m = _TAG_RE.search(term.strip())
+    if not m:
+        return None
+    root = _SEMANTIC_TAG_ROOT.get(m.group(1).strip().lower())
+    if not root:
+        return None
+    return (_ROOT_LABEL[root], f"< {root}")
+
+
+def resolve_hierarchy(context: str, term: Optional[str] = None) -> Optional[tuple[str, str]]:
+    """Hierarchy for a gap: the FSN semantic tag in the term wins (the document
+    states it), else the section default. This stops a Problem List procedure or
+    situation being force-fit to 'Clinical finding'."""
+    return hierarchy_from_semantic_tag(term) or hierarchy_for(context)