aimedicalcoding 0.3.1__py3-none-any.whl

aimedicalcoding/__init__.py

@@ -0,0 +1,29 @@
+"""AI Medical Coding — recover missing clinical codes from CCDA/FHIR documents.
+
+Detects observations whose LOINC / SNOMED CT / RxNorm code is missing, local,
+ICD/NDC-only, malformed, or blank, and prepares each as a target-tagged "gap"
+record for the (DB + LLM) recovery layer.
+
+Quick start::
+
+    from aimedicalcoding import extract_gaps
+
+    result = extract_gaps("patient.xml")          # checks LOINC + SNOMED + RxNorm
+    print(result.by_target)                       # {"LOINC": 5, "SNOMED-CT": 6, ...}
+    print(result.to_json())
+
+See docs/GAP_SCHEMA.md for the output contract.
+"""
+
+from .api import extract_gaps, collect_gaps, GapResult, EXTRACTORS
+
+try:                                    # version from installed package metadata
+    from importlib.metadata import version, PackageNotFoundError
+    try:
+        __version__ = version("aimedicalcoding")
+    except PackageNotFoundError:        # running from source, not installed
+        __version__ = "0+unknown"
+except Exception:                       # pragma: no cover
+    __version__ = "0+unknown"
+
+__all__ = ["extract_gaps", "collect_gaps", "GapResult", "EXTRACTORS", "__version__"]

aimedicalcoding/__main__.py

@@ -0,0 +1,313 @@
+"""CLI: extract terminology gaps from a CCDA (or FHIR) document.
+
+Usage:
+    python -m aimedicalcoding <path-to-document> [--system loinc] [--json] [--summary]
+
+Outputs only the codes that need correcting/filling (gaps-only), each with its
+pattern, composite match key, and recovery evidence packet.
+
+Only LOINC is implemented today; --system is the extension point for the
+SNOMED / RxNorm / ICD-10 extractors to plug into next.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import os
+import sys
+
+from . import serialize
+from .api import EXTRACTORS as _EXTRACTORS, PLANNED as _PLANNED, collect_gaps
+from .pipeline import parse_document
+
+
+def _to_dict(record) -> dict:
+    d = dataclasses.asdict(record)
+    # System is a str-Enum so it JSON-serializes as its value already.
+    return d
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="aimedicalcoding",
+        description="Extract codes needing correction/filling from a clinical document.",
+    )
+    p.add_argument("path", help="Path to a CCDA XML (or FHIR JSON) document")
+    p.add_argument("--system", default="all",
+                   help="loinc | snomed | rxnorm | icd10cm | cvx | all (default: all). Filters targets.")
+    p.add_argument("--contexts", default=None,
+                   help="Comma-separated statement contexts to include (default: all)")
+    p.add_argument("--include-narrative", action="store_true",
+                   help="Also report NARRATIVE_ONLY gaps (narrative-table text). Off by default.")
+    p.add_argument("--apply-dict", action="store_true",
+                   help="Expand abbreviations (BUN→urea nitrogen) in search terms. Off by default.")
+    p.add_argument("--table", action="store_true", help="Compact tabular output")
+    p.add_argument("--json", action="store_true", help="Emit the target-tagged JSON")
+    p.add_argument("--json-full", action="store_true", help="Emit the complete internal IR (verbose)")
+    p.add_argument("-o", "--out", metavar="FILE", default=None,
+                   help="Write the JSON report to FILE as UTF-8 (implies --json). "
+                        "Prefer this over shell redirection: PowerShell '>' "
+                        "re-encodes output as UTF-16.")
+    p.add_argument("--summary", action="store_true", help="Print only the counts")
+    args = p.parse_args(argv)
+
+    contexts = ({c.strip() for c in args.contexts.split(",") if c.strip()}
+                if args.contexts else None)
+
+    if args.system == "all":
+        system_keys = list(_EXTRACTORS)
+    elif args.system in _EXTRACTORS:
+        system_keys = [args.system]
+    else:
+        print(f"error: system '{args.system}' not implemented yet "
+              f"(planned: {', '.join(_PLANNED)})", file=sys.stderr)
+        return 5
+
+    try:
+        with open(args.path, "rb") as fh:
+            document = fh.read()
+    except OSError as e:
+        print(f"error: cannot read {args.path}: {e}", file=sys.stderr)
+        return 2
+
+    try:
+        statements = parse_document(document)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 3
+    except NotImplementedError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 4
+
+    tgaps = collect_gaps(statements, system_keys, contexts,
+                         args.include_narrative, args.apply_dict)
+
+    by_pattern, by_target = {}, {}
+    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
+
+    targets = [_EXTRACTORS[k][1] for k in system_keys]
+    src_fmt = statements[0].source_format if statements else None
+
+    if args.json or args.json_full or args.out:
+        if args.json_full:
+            gaps = [_to_dict(r) for r, _, _ in tgaps]
+        else:
+            gaps = [serialize.build_record(r, i, sys_, slot)
+                    for i, (r, sys_, slot) in enumerate(tgaps, 1)]
+        payload = {
+            "source": os.path.basename(args.path),
+            "source_format": src_fmt,
+            "targets_checked": targets,
+            "gap_count": len(tgaps),
+            "by_pattern": by_pattern,
+            "by_target": by_target,
+            "gaps": gaps,
+        }
+        text = json.dumps(payload, indent=2, default=str)
+        if args.out:
+            with open(args.out, "w", encoding="utf-8") as fh:
+                fh.write(text + "\n")
+            print(f"{len(tgaps)} gap(s) written to {args.out}")
+        else:
+            print(text)
+        return 0
+
+    if args.table:
+        _print_table(tgaps, by_pattern, by_target, args.path, args.summary)
+    else:
+        _print_report(tgaps, by_pattern, by_target, args.path, targets, args.summary)
+    return 0
+
+
+# --------------------------------------------------------------------------
+# Pretty terminal report
+# --------------------------------------------------------------------------
+_W = 74
+
+_ACTION = {
+    "LOCAL_CODE_ONLY": "crosswalk local code → LOINC; else text + axis 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",
+    "NULLFLAVOR": "map recovered label → LOINC via text + axis search",
+    "DISPLAY_ONLY": "map displayName → LOINC via text + axis search",
+    "NARRATIVE_ONLY": "narrative row; resolve label → LOINC (low priority)",
+    "BAD_CODE": "apply check-digit correction (confirm against text + axis)",
+}
+
+
+def _rule(ch="─"):
+    return ch * _W
+
+
+def _kv(label, value):
+    return f"  {label:<12}: {value}"
+
+
+def _concept(record) -> str:
+    """Human label for a gap. Prefers the resolved concept term (SNOMED reads it
+    from the value, not the question code); falls back to a unit/context hint when
+    there is no code AND no display name (e.g. an unlabeled vital)."""
+    ev = record.gap.evidence
+    term = ev.get("term") or record.statement.raw_text
+    if term:
+        return term
+    unit = ev.get("unit") or "no unit"
+    return f"(unlabeled · {unit} · {record.statement.context})"
+
+
+def _print_report(tgaps, by_pattern, by_target, source, targets, summary_only):
+    print()
+    print("═" * _W)
+    print(" GAP REPORT".ljust(_W))
+    print("═" * _W)
+    print(_kv("Document", os.path.basename(source)))
+    print(_kv("Targets", ", ".join(targets)))
+    print(_kv("Gaps", len(tgaps)))
+    if by_pattern:
+        print(_kv("Patterns", "  ".join(f"{k}={v}" for k, v in sorted(by_pattern.items()))))
+    if by_target:
+        print(_kv("By target", "  ".join(f"{k}={v}" for k, v in sorted(by_target.items()))))
+    print("═" * _W)
+
+    if summary_only:
+        return
+    if not tgaps:
+        print("\n  No codes need correction or filling. ✓\n")
+        return
+
+    for i, (r, sys_, slot) in enumerate(tgaps, 1):
+        ev = r.gap.evidence
+        print()
+        print(f" {i}. {r.gap.type}   →  {sys_} ({slot} slot)")
+        print(_rule())
+        print(_kv("Concept", _concept(r)))
+        print(_kv("Section", f"{r.statement.section_code or '-'} {r.statement.section_name or ''}".strip()))
+
+        # value + unit + reference range, compactly
+        val = ev.get("value")
+        if val is not None:
+            vline = str(val)
+            if ev.get("unit") and ev["unit"] not in str(val):
+                vline += f" {ev['unit']}"
+            if ev.get("reference_range"):
+                vline += f"   (ref {ev['reference_range']})"
+            print(_kv("Value", vline))
+
+        # specimen with its provenance/confidence (panel-derived is low trust)
+        if ev.get("specimen_hint"):
+            print(_kv("Specimen", f"{ev['specimen_hint']}  "
+                                  f"({ev.get('specimen_source')}, "
+                                  f"{ev.get('specimen_confidence')} confidence)"))
+
+        # SNOMED: target hierarchy (the candidate constraint)
+        if ev.get("target_hierarchy"):
+            print(_kv("Hierarchy", ev["target_hierarchy"]))
+
+        # pattern-specific evidence
+        if ev.get("local_code"):
+            print(_kv("Local code", f"{ev['local_code']}  [{ev.get('local_system') or '?'}]"))
+        if ev.get("icd_code"):
+            print(_kv("ICD code", f"{ev['icd_code']}  [{ev.get('icd_system') or '?'}]"))
+        if ev.get("ndc_code"):
+            print(_kv("NDC code", f"{ev['ndc_code']}  [{ev.get('ndc_system') or '?'}]"))
+        if ev.get("snomed_code"):
+            print(_kv("SNOMED code", f"{ev['snomed_code']}  [{ev.get('snomed_system') or '?'}]"))
+        if ev.get("null_flavor"):
+            print(_kv("nullFlavor", ev["null_flavor"]))
+        if ev.get("malformed_code"):
+            fix = ev.get("checkdigit_correction")
+            print(_kv("Bad code", f"{ev['malformed_code']}" +
+                     (f"  →  suggested {fix}" if fix else "")))
+
+        print(_kv("Match key", r.gap.match_key))
+        print(_kv("Suggested", r.gap.note or _ACTION.get(r.gap.type, "resolve via DB + LLM")))
+        print(_kv("Location", r.statement.source_ref))
+
+    print()
+    print(_rule("═"))
+    print(f" {len(tgaps)} gap(s) ready for the recovery step "
+          f"(crosswalk → candidate search → LLM).")
+    print(_rule("═"))
+    print()
+
+
+def _trunc(s, n):
+    s = "" if s is None else str(s)
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+def _detail(ev: dict, pattern: str) -> str:
+    if pattern == "BAD_CODE" and ev.get("malformed_code"):
+        return f"{ev['malformed_code']}→{ev.get('checkdigit_correction') or '?'}"
+    if pattern == "ICD_ONLY" and ev.get("icd_code"):
+        return f"icd:{ev['icd_code']}"
+    if pattern == "NDC_ONLY" and ev.get("ndc_code"):
+        return f"ndc:{ev['ndc_code']}"
+    if pattern == "RXNORM_ONLY" and ev.get("rxnorm_code"):
+        return f"rxcui:{ev['rxnorm_code']}"
+    if pattern == "SNOMED_ONLY" and ev.get("snomed_code"):
+        return f"sct:{ev['snomed_code']}"
+    if pattern in ("MULTUM_ONLY", "FDB_ONLY", "MEDISPAN_ONLY") and ev.get("source_code"):
+        return f"{ev.get('source_vocab', 'src')}:{ev['source_code']}"
+    if pattern == "LOCAL_CODE_ONLY" and ev.get("local_code"):
+        return f"local:{ev['local_code']}"
+    if pattern == "NULLFLAVOR" and ev.get("null_flavor"):
+        return f"nullFlavor:{ev['null_flavor']}"
+    return ""
+
+
+def _print_table(tgaps, by_pattern, by_target, source, summary_only):
+    breakdown = "  ".join(f"{k}={v}" for k, v in sorted(by_pattern.items())) or "none"
+    tgt = "  ".join(f"{k}={v}" for k, v in sorted(by_target.items())) or "none"
+    print(f"\nGaps in {os.path.basename(source)}: {len(tgaps)}   "
+          f"patterns({breakdown})   targets({tgt})\n")
+    if summary_only:
+        return
+    if not tgaps:
+        print("  No codes need correction or filling. ✓\n")
+        return
+
+    headers = ["#", "TARGET", "PATTERN", "CONCEPT", "CTX", "DETAIL", "MATCH KEY"]
+    caps = [3, 14, 16, 24, 8, 16, 72]
+    rows = []
+    for i, (r, sys_, slot) in enumerate(tgaps, 1):
+        ev = r.gap.evidence
+        rows.append([
+            str(i),
+            f"{sys_}/{slot}",
+            r.gap.type,
+            _concept(r),
+            r.statement.context,
+            _detail(ev, r.gap.type),
+            r.gap.match_key,
+        ])
+
+    # All columns except the last are capped/padded for alignment. The last
+    # column (MATCH KEY) is printed in full — no truncation, no trailing pad.
+    last = len(headers) - 1
+    widths = [
+        min(caps[c], max(len(headers[c]), *(len(_trunc(row[c], caps[c])) for row in rows)))
+        for c in range(last)
+    ]
+
+    def _fmt(cells):
+        fixed = "  ".join(_trunc(cells[c], caps[c]).ljust(widths[c]) for c in range(last))
+        return f"  {fixed}  {cells[last] or ''}"
+
+    print(_fmt(headers))
+    sep = ["-" * widths[c] for c in range(last)] + ["-" * len(headers[last])]
+    print("  " + "  ".join(sep))
+    for row in rows:
+        print(_fmt(row))
+    print()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aimedicalcoding/adapters/__init__.py

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

aimedicalcoding/adapters/base.py

@@ -0,0 +1,25 @@
+"""FormatAdapter contract.
+
+An adapter knows ONE input format (CCDA, FHIR, custom JSON) and nothing about
+terminologies. It turns a raw document into an iterable of ``ClinicalStatement``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Iterable
+
+from ..core.models import ClinicalStatement
+
+
+class FormatAdapter(ABC):
+    #: short format key written onto each statement's ``source_format``
+    format_key: str = "unknown"
+
+    @abstractmethod
+    def detect(self, document: str | bytes) -> bool:
+        """Return True if ``document`` is this adapter's format."""
+
+    @abstractmethod
+    def parse(self, document: str | bytes) -> Iterable[ClinicalStatement]:
+        """Yield format-agnostic clinical statements."""

aimedicalcoding/adapters/ccda/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import CcdaAdapter
+
+__all__ = ["CcdaAdapter"]

aimedicalcoding/adapters/ccda/adapter.py

@@ -0,0 +1,294 @@
+"""CCDA (HL7 V3 / C-CDA) format adapter.
+
+Walks the document at all three altitudes (document type, section codes, entry
+observations), runs scan-and-identify over each <code>, resolves originalText,
+and falls back to narrative-table parsing for sections without structured
+entries. Emits terminology-agnostic ``ClinicalStatement`` objects.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+from lxml import etree
+
+from ...core.models import (
+    ClinicalStatement,
+    CodingCandidate,
+    System,
+    ValueInfo,
+    NAR,
+)
+from ...core.system_registry import canonicalize
+from ..base import FormatAdapter
+from . import codes as C
+from . import narrative as N
+from . import sections as S
+from .sections import route_section
+
+
+class CcdaAdapter(FormatAdapter):
+    format_key = "ccda"
+
+    # ------------------------------------------------------------------ #
+    def detect(self, document: str | bytes) -> bool:
+        try:
+            root = self._root(document)
+        except etree.XMLSyntaxError:
+            return False
+        return etree.QName(root).localname == "ClinicalDocument"
+
+    def parse(self, document: str | bytes) -> Iterable[ClinicalStatement]:
+        root = self._root(document)
+        self._tree = root.getroottree()
+        statements: list[ClinicalStatement] = []
+
+        # 1. document type code (top altitude)
+        doc_code = root.find(C.q("code"))
+        if doc_code is not None:
+            codings = C.scan_codings(doc_code)
+            if codings:
+                statements.append(ClinicalStatement(
+                    source_format=self.format_key,
+                    source_ref=self._path(doc_code),
+                    context="document_type",
+                    target_system_hint=System.LOINC,
+                    raw_text=doc_code.get("displayName"),
+                    codings=codings,
+                ))
+
+        # 2. sections
+        for section in root.iter(C.q("section")):
+            statements.extend(self._parse_section(section))
+
+        return statements
+
+    # ------------------------------------------------------------------ #
+    def _parse_section(self, section: etree._Element) -> list[ClinicalStatement]:
+        out: list[ClinicalStatement] = []
+
+        sec_code_el = section.find(C.q("code"))
+        sec_code = sec_code_el.get("code") if sec_code_el is not None else None
+        sec_name = sec_code_el.get("displayName") if sec_code_el is not None else None
+        sec_system = (canonicalize(sec_code_el.get("codeSystem")).value
+                      if sec_code_el is not None and canonicalize(sec_code_el.get("codeSystem"))
+                      else None)
+        context, hint = route_section(sec_code)
+        id_map = N.build_id_map(section)
+
+        # section-level statement (the section's own LOINC label)
+        if sec_code_el is not None:
+            out.append(ClinicalStatement(
+                source_format=self.format_key,
+                source_ref=self._path(sec_code_el),
+                context="section",
+                section_code=sec_code,
+                section_name=sec_name,
+                section_system=sec_system,
+                target_system_hint=System.LOINC,
+                raw_text=sec_name,
+                codings=C.scan_codings(sec_code_el),
+            ))
+
+        # 2a. organizers (panels) -> child observations carry the panel.
+        # NB: lxml elements have no stable Python identity across iter()/findall(),
+        # so we dedup structurally (by ancestry) rather than by id().
+        sec = (sec_code, sec_name, sec_system)
+        for org in section.iter(C.q("organizer")):
+            panel = self._panel_coding(org)
+            org_specimen = C.extract_specimen(org)   # organizer-level specimen
+            for obs in org.findall(f"{C.q('component')}/{C.q('observation')}"):
+                out.append(self._observation(obs, context, hint, id_map, panel,
+                                             org_specimen, sec))
+
+        # 2b. standalone observations: those NOT nested under an organizer or
+        # another observation (entryRelationship sub-observations are skipped).
+        for obs in section.iter(C.q("observation")):
+            if self._has_ancestor(obs, ("organizer", "observation")):
+                continue
+            out.append(self._observation(obs, context, hint, id_map, panel=None,
+                                         section=sec))
+
+        # 2b-2. Procedures: <procedure> acts carry the code directly (SNOMED/CPT).
+        for proc in section.iter(C.q("procedure")):
+            code_el = proc.find(C.q("code"))
+            if code_el is not None and (code_el.get("code") or code_el.get("nullFlavor")):
+                out.append(self._observation(proc, context, hint, id_map,
+                                             panel=None, section=sec))
+
+        # 2b-2b. Medications / immunizations: the product code lives on
+        # manufacturedMaterial (RxNorm/NDC for drugs; CVX/RxNorm/NDC for vaccines),
+        # nested in substanceAdministration → consumable → manufacturedProduct.
+        if context in ("medication", "immunization"):
+            for mm in section.iter(C.q("manufacturedMaterial")):
+                if mm.find(C.q("code")) is not None:
+                    out.append(self._observation(mm, context, hint, id_map,
+                                                 panel=None, section=sec))
+
+        # 2b-3. Allergy slots: the allergen substance (participant) and the
+        # reaction manifestation (nested observation) — only in allergy sections.
+        if context == "allergy":
+            for pe in section.iter(C.q("playingEntity")):
+                if pe.find(C.q("code")) is not None:
+                    out.append(self._observation(pe, "allergy_substance", hint,
+                                                 id_map, panel=None, section=sec))
+            for obs in section.iter(C.q("observation")):
+                if self._has_templateid(obs, S.TEMPLATE_ALLERGY_REACTION):
+                    out.append(self._observation(obs, "allergy_reaction", hint,
+                                                 id_map, panel=None, section=sec))
+
+        structured = [s for s in out if s.context not in ("section",)]
+
+        # 2c. narrative-only fallback: no structured observations -> parse table
+        if not structured:
+            for row in N.parse_narrative_table(section):
+                out.append(self._narrative_row(section, row, context, hint, sec))
+
+        return out
+
+    # ------------------------------------------------------------------ #
+    def _observation(
+        self,
+        obs: etree._Element,
+        context: str,
+        hint: Optional[System],
+        id_map: dict,
+        panel: Optional[CodingCandidate],
+        org_specimen: Optional[dict] = None,
+        section: tuple = (None, None, None),
+    ) -> ClinicalStatement:
+        code_el = obs.find(C.q("code"))
+        codings = C.scan_codings(code_el)
+
+        # resolved <originalText> for the root <code> (inline or #reference)
+        ot = N.original_text(code_el, id_map)
+        if ot:
+            root = next((c for c in codings if not c.from_translation), None)
+            if root is not None:
+                root.original_text = ot
+
+        # raw_text: prefer root displayName, else originalText, else any display
+        raw_text = None
+        if code_el is not None:
+            raw_text = code_el.get("displayName")
+        if not raw_text:
+            raw_text = ot
+        if not raw_text:
+            raw_text = next((c.display for c in codings if c.display), None)
+
+        companion = C.extract_companion(obs)
+        # negationInd="true" means the act is NEGATED (condition absent / med or
+        # vaccine NOT given) — must not be coded as present. Structural attribute,
+        # more reliable than text cues.
+        if obs.get("negationInd") == "true":
+            companion["negation"] = True
+        # explicit specimen: observation-level wins, else inherit organizer's
+        specimen = C.extract_specimen(obs) or org_specimen
+        if specimen:
+            companion["specimen"] = specimen.get("display")
+            companion["specimen_code"] = specimen.get("code")
+
+        # value: resolve the VALUE's own originalText / nullFlavor (the coded
+        # answer's label, e.g. a SNOMED problem recovered from narrative).
+        value = C.extract_value(obs)
+        val_el = obs.find(C.q("value"))
+        if value is not None and val_el is not None:
+            v_ot = N.original_text(val_el, id_map)
+            if v_ot:
+                value.original_text = v_ot
+            v_nf = val_el.get("nullFlavor")
+            if v_nf and (value.coded_value is None or not value.coded_value.code):
+                value.coded_value = CodingCandidate(system=System.NULLFLAVOR,
+                                                    raw_system=v_nf)
+
+        # explicit labels for THIS node's code (the question/observation code).
+        # These describe the CODE slot; the SNOMED handler overrides with the
+        # value's labels for value-slot concepts (see systems/snomed/patterns.py).
+        display_name = code_el.get("displayName") if code_el is not None else None
+        original_text = ot
+
+        return ClinicalStatement(
+            source_format=self.format_key,
+            source_ref=self._path(obs),
+            context=context,
+            section_code=section[0],
+            section_name=section[1],
+            section_system=section[2],
+            role="value",
+            target_system_hint=hint,
+            raw_text=raw_text,
+            display_name=display_name,
+            original_text=original_text,
+            codings=codings,
+            value=value,
+            effective_time=C.extract_effective_time(obs),
+            panel=panel,
+            companion=companion,
+        )
+
+    def _narrative_row(
+        self, section: etree._Element, row: dict, context: str,
+        hint: Optional[System], sec: tuple = (None, None, None),
+    ) -> ClinicalStatement:
+        value = None
+        if row.get("value_raw") is not None:
+            value = ValueInfo(
+                type="Qn" if row.get("num") is not None else NAR,
+                raw=row.get("value_raw"),
+                num=row.get("num"),
+                unit=row.get("unit"),
+                unit_system="UCUM" if row.get("unit") else None,
+            )
+        companion = {}
+        if row.get("reference_range"):
+            companion["reference_range"] = row["reference_range"]
+        return ClinicalStatement(
+            source_format=self.format_key,
+            source_ref=f"{self._path(section)}/text//tr[{row['row_index']}]",
+            context=context,
+            section_code=sec[0],
+            section_name=sec[1],
+            section_system=sec[2],
+            role="value",
+            target_system_hint=hint,
+            raw_text=row["label"],
+            original_text=row["label"],       # narrative-table text
+            codings=[],                       # no code in narrative -> recovery candidate
+            value=value,
+            companion=companion,
+        )
+
+    def _panel_coding(self, org: etree._Element) -> Optional[CodingCandidate]:
+        code_el = org.find(C.q("code"))
+        codings = C.scan_codings(code_el)
+        if not codings:
+            return None
+        loinc = C.best_loinc(codings)
+        if loinc:
+            return loinc
+        return next((c for c in codings if c.code), codings[0])
+
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _has_templateid(el: etree._Element, root: str) -> bool:
+        return any(t.get("root") == root for t in el.findall(C.q("templateId")))
+
+    @staticmethod
+    def _has_ancestor(el: etree._Element, localnames: tuple[str, ...]) -> bool:
+        parent = el.getparent()
+        while parent is not None:
+            if etree.QName(parent).localname in localnames:
+                return True
+            parent = parent.getparent()
+        return False
+
+    @staticmethod
+    def _root(document: str | bytes) -> etree._Element:
+        data = document.encode("utf-8") if isinstance(document, str) else document
+        return etree.fromstring(data)
+
+    def _path(self, el: etree._Element) -> str:
+        try:
+            return self._tree.getpath(el)
+        except Exception:
+            return "?"