aimedicalcoding 0.3.1__tar.gz

aimedicalcoding-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trove Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aimedicalcoding-0.3.1/MANIFEST.in

@@ -0,0 +1,14 @@
+# sdist contents. IMPORTANT: setuptools does NOT honor .gitignore — the PHI
+# directories must be pruned explicitly here.
+include LICENSE
+include README.md
+include README_PYPI.md
+recursive-include docs *.md
+prune docs/input
+prune docs/Input_FHIRs
+prune docs/samples
+recursive-exclude aimedicalcoding/tests *
+exclude gaps*.json
+exclude *.gaps.json
+exclude run.sh
+exclude test.py

aimedicalcoding-0.3.1/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: aimedicalcoding
+Version: 0.3.1
+Summary: Detect missing/broken clinical codes (LOINC / SNOMED CT / RxNorm / ICD-10-CM / CVX) in CCDA and FHIR documents, with recovery evidence
+Author: Aakash Kag, Vinay Shankar Miryala, Siva Karthik, Mohammed Rayaan
+License: MIT
+Keywords: loinc snomed rxnorm icd-10-cm cvx ccda fhir clinical-terminology medical-coding interoperability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml>=4.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# aimedicalcoding
+
+**Find every missing or broken standard clinical code in a CCDA or FHIR document — with the evidence needed to fix it.**
+
+`aimedicalcoding` parses a clinical document (CCDA XML or FHIR R4 Bundle JSON),
+inspects every coded clinical item — labs, vitals, problems, medications,
+immunizations, allergies, procedures, social history — and reports the ones
+whose standard terminology code (**LOINC · SNOMED CT · RxNorm · ICD-10-CM ·
+CVX**) is missing, local-only, crosswalkable, or malformed. Each finding (a
+*gap*) is emitted as a self-contained JSON record carrying the classification,
+the document facts, and a ready-made recovery plan (search terms, axis filters,
+crosswalk candidates, check-digit corrections).
+
+Items that are already correctly coded produce no output — the result is a
+work list, not an inventory.
+
+---
+
+## Installation
+
+```bash
+pip install aimedicalcoding
+```
+
+Requires Python 3.10+. The only runtime dependency is `lxml`.
+
+---
+
+## Quick start (CLI)
+
+The input format is **auto-detected** — the same command works for CCDA XML
+and FHIR JSON, and the output schema is identical for both.
+
+```bash
+# human-readable gap report (card view)
+aimedicalcoding patient.xml
+
+# FHIR R4 Bundle — same flags, same output
+aimedicalcoding bundle.json --table
+
+# counts only
+aimedicalcoding patient.xml --summary --table
+
+# machine-readable JSON, written to a file as UTF-8
+aimedicalcoding patient.xml --out gaps.json
+
+# restrict to one terminology and/or certain contexts
+aimedicalcoding patient.xml --system loinc --contexts result,vital
+```
+
+If the entry point is not on your PATH, `python -m aimedicalcoding <file> [flags]`
+is equivalent.
+
+### CLI flags
+
+| Flag | Meaning |
+|---|---|
+| `--system` | `loinc` \| `snomed` \| `rxnorm` \| `icd10cm` \| `cvx` \| `all` (default `all`) |
+| `--contexts` | comma-separated contexts to include, e.g. `result,vital,problem` |
+| `--table` | compact one-line-per-gap table |
+| `--json` | print the JSON report to stdout |
+| `-o, --out FILE` | write the JSON report to FILE as UTF-8 (implies `--json`) |
+| `--summary` | counts only |
+| `--include-narrative` | also report narrative-table-only items (CCDA; off by default) |
+| `--apply-dict` | expand lab abbreviations (BUN → urea nitrogen) in search terms |
+| `--json-full` | dump the complete internal representation (debugging) |
+
+---
+
+## Quick start (Python)
+
+```python
+from aimedicalcoding import extract_gaps
+
+result = extract_gaps("patient.xml")        # CCDA — auto-detected
+result = extract_gaps("bundle.json")        # FHIR R4 Bundle — auto-detected
+result = extract_gaps(raw_bytes,            # bytes / str / path / file-like
+                      systems=("loinc", "snomed", "rxnorm", "icd10cm", "cvx"))
+
+len(result)           # number of gaps
+result.by_target      # {"LOINC": 17, "SNOMED-CT": 30, "RxNorm": 4, ...}
+result.by_pattern     # {"LOCAL_CODE_ONLY": 15, "NULLFLAVOR": 32, ...}
+result.gaps           # list[dict] — one record per (item, missing terminology)
+result.to_json()      # the same JSON the CLI emits
+```
+
+Lower-level access — parse to the intermediate representation without gap
+analysis:
+
+```python
+from aimedicalcoding.pipeline import parse_document
+
+statements = parse_document(open("bundle.json", "rb").read())
+for s in statements:
+    print(s.context, s.raw_text, [(c.system, c.code) for c in s.codings])
+```
+
+---
+
+## How it works
+
+The library is built on two independent axes that meet at a format-agnostic
+intermediate representation (IR):
+
+```
+ FORMAT axis (adapters)              TERMINOLOGY axis (extractors)
+   CCDA XML  ──┐                       LOINC      SNOMED CT
+   FHIR R4  ───┤──►  ClinicalStatement ──►  RxNorm   ICD-10-CM   CVX
+               │         (the IR)
+   (auto-detected)                    (identical for every input format)
+```
+
+1. **Detect** — XML with a `<ClinicalDocument>` root → CCDA adapter; JSON with
+   `"resourceType": "Bundle"` → FHIR adapter.
+2. **Parse to IR** — the adapter walks the document and emits one
+   `ClinicalStatement` per clinical item: every coding found on the item (root
+   code *plus* all translations / `coding[]` entries, each canonicalized by
+   system), the human labels, the value (quantity or coded answer), specimen,
+   panel membership, timestamps.
+3. **Extract gaps** — each terminology extractor examines the statements
+   relevant to it (labs/vitals for LOINC, problems/procedures/reactions for
+   SNOMED, medications for RxNorm, diagnoses for ICD-10-CM, immunizations for
+   CVX), validates any code present (check digits, format), and classifies
+   everything else into a gap pattern.
+4. **Serialize** — one JSON record per (item × missing terminology), identical
+   schema for CCDA and FHIR input.
+
+### What each adapter understands
+
+**CCDA**: document/section/entry structure, `<code>` + `<translation>`
+scan-and-identify, `nullFlavor`, `<originalText>` reference resolution into the
+narrative, organizer → panel linkage, specimen, interpretation and reference
+ranges, narrative-table fallback for sections without structured entries.
+
+**FHIR R4 Bundle**: routing by resource type + `Observation.category` (with
+section-tag fallback), `CodeableConcept.coding[]` as primary + translations,
+`valueQuantity` / `valueCodeableConcept` / `valueString` / `dataAbsentReason`,
+`hasMember` / `DiagnosticReport.result` panel linkage (children inherit context
+and specimen), `medicationReference → Medication.code` and
+`specimen → Specimen.type` resolution across the Bundle, per-reaction allergy
+statements, and normalization of `"unknown"` null-marker strings.
+
+---
+
+## Gap patterns
+
+Each record's `pattern` says *why* the code is missing — which determines how
+to fix it:
+
+| Pattern | What's wrong | Recovery route |
+|---|---|---|
+| `LOCAL_CODE_ONLY` | a local/in-house/CPT code, no standard code | crosswalk local → target, else text search |
+| `NULLFLAVOR` | code explicitly declared unknown (`nullFlavor`, `"unknown"`, `dataAbsentReason`) | resolve the recovered label |
+| `DISPLAY_ONLY` | only a display name, no code and no absence marker | resolve the label |
+| `NARRATIVE_ONLY` | exists only as narrative table text (CCDA, opt-in) | text search, low priority |
+| `BAD_CODE` | right shape, fails validation (LOINC Luhn · SNOMED Verhoeff · ICD format) | check-digit / format correction (suggested fix included) |
+| `ICD_ONLY` | ICD present, SNOMED missing | official ICD ↔ SNOMED map |
+| `SNOMED_ONLY` | SNOMED present, ICD-10-CM missing | official SNOMED → ICD-10-CM map |
+| `NDC_ONLY` | NDC present, RxNorm/CVX missing | NDC ↔ RxNorm / CDC NDC ↔ CVX table |
+| `RXNORM_ONLY` | RxNorm vaccine product, CVX missing | CVX ↔ RxNorm map |
+| `MULTUM_ONLY` / `FDB_ONLY` / `MEDISPAN_ONLY` | proprietary drug vocabulary, RxNorm missing | vendor ↔ RxNorm via UMLS |
+
+---
+
+## Output
+
+The JSON envelope:
+
+```jsonc
+{
+  "source": "patient.xml",
+  "source_format": "ccda",              // or "fhir" — auto-detected
+  "targets_checked": ["LOINC", "SNOMED-CT", "RxNorm", "ICD-10-CM", "CVX"],
+  "gap_count": 4,
+  "by_pattern": { "LOCAL_CODE_ONLY": 1, "NULLFLAVOR": 3 },
+  "by_target":  { "LOINC": 1, "SNOMED-CT": 3 },
+  "gaps": [ ... ]
+}
+```
+
+Each gap record separates four concerns — the classification, the facts, the
+plan, and the (pending) answer:
+
+```jsonc
+{
+  "id": 1,
+  "target":  { "system": "LOINC", "slot": "code" },   // what's missing, and in which slot
+  "pattern": "LOCAL_CODE_ONLY",                        // why
+  "section": { "code": "30954-2", "name": "Results", "system": "LOINC" },
+
+  "observation": {                                     // the facts, verbatim
+    "code": {
+      "display_text": "LIPID PANEL",
+      "original_text": "LIPID PANEL",
+      "codings": [
+        { "code": null,    "system": "LOINC", "system_raw": "http://loinc.org" },
+        { "code": "80061", "system": "CPT",   "system_raw": "http://www.ama-assn.org/go/cpt" }
+      ]
+    },
+    "value": null,
+    "qualifiers": { "specimen": { "value": "Bld", "confidence": "low" }, "...": "..." }
+  },
+
+  "recovery": {                                        // the plan
+    "search_terms": ["LIPID PANEL", "lipid panel"],
+    "match_key": "component:LIPID PANEL | specimen:Bld | property:? | scale:? | method:-",
+    "crosswalk": { "from_system": "http://www.ama-assn.org/go/cpt", "from_code": "80061" },
+    "suggested_action": "Try (source_system, local_code) crosswalk FIRST; ..."
+  },
+
+  "provenance": { "location": { "type": "fhirpath", "path": "..." } },
+  "resolution": { "status": "pending", "code": null, "...": "..." }  // filled by your recovery step
+}
+```
+
+Reading it: this lab was coded with CPT `80061` but its LOINC slot is empty
+(`code: null` — the source wrote a null marker). The record hands you the CPT
+crosswalk candidate, the text to search with, and the LOINC axis hints
+(specimen/property/scale) to constrain candidates — everything a
+crosswalk-database or LLM step needs to fill `resolution`.
+
+---
+
+## Scope and status
+
+- Emits **gap detections + recovery evidence**. It does not itself query
+  terminology databases or LLMs — `resolution` is intentionally left `pending`
+  for your downstream step.
+- Terminologies checked today: LOINC, SNOMED CT, RxNorm, ICD-10-CM, CVX.
+  CPT / HCPCS / ICD-10-PCS are planned.
+- Validation included: LOINC Luhn check digits, SNOMED Verhoeff check digits
+  (incl. long-format extension SCTIDs), ICD-10-CM format rules, CVX shape.
+- Code-system identification covers HL7 OIDs, FHIR URIs, `urn:oid:` forms and
+  free-text names for 20+ vocabularies (Epic/local OIDs are recognized as
+  local codes, HL7 structural vocabularies are excluded from gap detection).
+
+## License
+
+MIT — © 2026 Trove Health.

aimedicalcoding-0.3.1/README.md

@@ -0,0 +1,262 @@
+# aimedicalcoding
+
+Recover missing clinical codes (**LOINC · SNOMED CT · RxNorm · ICD-10-CM**) from
+CCDA / FHIR / custom documents. One pass detects every observation whose code is
+missing, local, ICD/NDC/SNOMED-only, malformed, or blank, and emits a
+**target-tagged gap record** for the (DB + LLM) recovery layer. DB and LLM layers
+are placeholders for now.
+
+## Install
+
+Editable (dev) from the repo:
+```bash
+pip install -e .
+```
+Build and install a wheel:
+```bash
+python -m build && pip install dist/aimedicalcoding-*.whl
+```
+Straight from CodeCommit (no registry):
+```bash
+pip install "git+https://git-codecommit.us-east-1.amazonaws.com/v1/repos/Trident.MedCodeParser@v0.2.0"
+```
+Version is set manually in `setup.py` (`version="0.3.0"`) — bump it there for
+each release, then build.
+
+## Use as a library
+
+```python
+from aimedicalcoding import extract_gaps
+
+result = extract_gaps("patient.xml")                       # CCDA — checks LOINC + SNOMED + RxNorm
+result = extract_gaps("bundle.json")                       # FHIR R4 Bundle — same call, auto-detected
+result = extract_gaps(data_bytes, systems=("rxnorm",))     # path | bytes | file-like; pick systems
+result.by_target        # {"LOINC": 5, "SNOMED-CT": 6, "RxNorm": 4}
+result.by_pattern       # {"LOCAL_CODE_ONLY": 6, ...}
+result.gaps             # list[dict] — target-tagged records (see docs/GAP_SCHEMA.md)
+result.to_json()        # str
+result.to_dict()        # full envelope
+```
+
+## Use as a CLI
+
+```bash
+aimedicalcoding patient.xml --json        # installed entry point
+# or, without installing:
+./run.sh patient.xml --json
+```
+
+## Build / publish (dev workflow)
+
+Install dev tools (pytest, build, twine) once:
+```bash
+pip install -e ".[dev]"
+```
+Run tests:
+```bash
+pytest
+```
+Build distributables (version comes from the git tag):
+```bash
+python -m build
+```
+Publish privately to AWS CodeArtifact (the repo is on CodeCommit):
+```bash
+aws codeartifact login --tool twine --domain <domain> --repository <repo>
+twine upload --repository codeartifact dist/*
+```
+
+## Status
+- **CCDA adapter** — implemented (`adapters/ccda/`): document/section/entry codes,
+  scan-and-identify over `<code>` + `<translation>`, `<value>`/units/interpretation/
+  reference range, originalText `#reference` resolution, narrative-table fallback,
+  organizer→panel linkage.
+- **FHIR adapter** — implemented (`adapters/fhir/`): parses an R4 Bundle
+  (Trove flavor) into the same IR. Routing by resource type +
+  `Observation.category`, falling back to the CCDA section LOINC stamped in
+  `meta.tag` (reuses `SECTION_ROUTING`). Handles `coding[]` as root +
+  translations, the Trove `"unknown"` null marker (code / display / system /
+  text → normalized to null; all-unknown concepts become a NULLFLAVOR signal),
+  `dataAbsentReason`, `hasMember`/`DiagnosticReport.result` → panel linkage
+  (children inherit context + specimen), `medicationReference` → `Medication.code`
+  and `specimen` → `Specimen.type` resolution across the Bundle, per-reaction
+  `allergy_reaction` statements, and value-slot placement for `Condition` /
+  `FamilyMemberHistory`. `detect()` requires `resourceType == "Bundle"`.
+- **Custom JSON adapter** — placeholder (config-driven mapping TODO).
+- **systems/loinc/** — LOINC gaps-only extractor (implemented): classifies each
+  LOINC-expected observation into a pattern and emits records ONLY for codes that
+  need correcting/filling, each with a recovery evidence packet + composite match
+  key. Patterns: `LOCAL_CODE_ONLY`, `NULLFLAVOR`, `DISPLAY_ONLY`, `NARRATIVE_ONLY`,
+  `BAD_CODE`. Valid LOINCs (incl. via `<translation>`) are skipped.
+- **systems/snomed/** — SNOMED CT gaps-only extractor (implemented): reads the
+  concept from the value/answer slot (problems, family hx, social hx, reactions)
+  or the code slot (procedures, allergen substance), classifies by section →
+  target hierarchy (ECL), and emits gaps. Patterns add `ICD_ONLY` (ICD↔SNOMED
+  crosswalk). Valid SNOMED + structural `ASSERTION` codes are skipped.
+- **systems/rxnorm/** — RxNorm gaps-only extractor (implemented): medications
+  (CCDA `manufacturedMaterial/code`). Disambiguates by ingredient + strength +
+  dose form + route → SCD/SBD. Patterns add `NDC_ONLY` (NDC↔RxNorm crosswalk).
+  RxCUI has no check digit (validity = DB existence + TTY).
+- **systems/icd10cm/** — ICD-10-CM gaps-only extractor (implemented): billing
+  diagnoses, the mirror of SNOMED (same value slot). Reads value + `<translation>`,
+  disambiguates by laterality/encounter/complication. Patterns add `SNOMED_ONLY`
+  (SNOMED→ICD-10-CM map). Format-validated (regex), no check digit.
+- **systems/cvx/** — CVX gaps-only extractor (implemented): immunizations
+  (CCDA `manufacturedMaterial/code` under `11369-6`). Code slot, no check digit
+  (short numeric). Patterns add `RXNORM_ONLY` (CVX↔RxNorm map) and `NDC_ONLY`
+  (CDC vaccine NDC↔CVX table); recovery key is the normalized vaccine concept.
+- **terminology/ · recovery/ · CPT/ICD-10-PCS systems** — placeholder contracts only.
+
+## LOINC gap extraction
+```python
+from aimedicalcoding.systems.loinc import LoincGapExtractor
+recs = LoincGapExtractor().extract_from_document(open("doc.xml", "rb").read())
+for r in recs:                       # only codes needing work
+    print(r.gap.type, r.gap.match_key, r.gap.evidence)
+```
+Note: the adapters (CCDA and FHIR) still extract *everything* (panel/sibling
+context is needed to recover a gap); the LOINC layer is what filters to gaps-only.
+
+## Layout
+```
+core/        IR models, system registry (OID/URI/name → System), check digits
+adapters/    FORMAT axis — ccda (done), fhir (done), custom_json (stub)
+systems/     TERMINOLOGY axis — loinc/snomed/rxnorm/icd10cm/cvx extractors
+terminology/ DB service (stub)
+recovery/    LLM engine (stub)
+pipeline/    orchestrator: detect format → run adapter → IR
+tests/       fixtures/sample_ccda.xml + sample_fhir_bundle.json + per-axis tests
+```
+
+## Run on a document (CLI)
+Works identically for CCDA XML and FHIR JSON — the format is auto-detected and
+the output schema is the same. From the repo root; each block is copy-paste ready.
+
+Try the bundled sample (all targets, card view):
+```bash
+./run.sh docs/samples/sample_all_systems.xml
+```
+A FHIR R4 Bundle (same flags, same output):
+```bash
+./run.sh /path/to/bundle.json --table
+```
+Compact table:
+```bash
+./run.sh /path/to/patient.xml --table
+```
+Counts only (per pattern + per target):
+```bash
+./run.sh /path/to/patient.xml --summary
+```
+Target-tagged JSON for downstream consumers (written as UTF-8; prefer `--out`
+over shell `>` — PowerShell redirection re-encodes output as UTF-16):
+```bash
+./run.sh /path/to/patient.xml --out gaps.json
+```
+Filter to one terminology and/or certain sections:
+```bash
+./run.sh /path/to/patient.xml --system loinc --contexts result,vital
+```
+Opt-in extras (abbreviations, narrative-only rows, raw IR):
+```bash
+./run.sh /path/to/patient.xml --apply-dict --include-narrative
+./run.sh /path/to/patient.xml --json-full
+```
+
+Output is **gaps only** — observations whose code needs correcting/filling.
+**One pass checks both LOINC and SNOMED**; each gap is tagged with its `target`
+(`{system, slot}`). `--system` just filters which targets to show.
+
+Flags:
+- `--system` — `loinc` | `snomed` | `rxnorm` | `icd10cm` | `all` (default `all`); CPT/ICD-10-PCS planned.
+- `--contexts result,vital` — restrict to certain section contexts (default: all).
+- `--include-narrative` — also report `NARRATIVE_ONLY` (human-readable table text); **off by default**.
+- `--apply-dict` — expand lab abbreviations (BUN→urea nitrogen) in the match key; **off by default**.
+- `--table` / `--json` / `--json-full` / `--summary` — output modes.
+- `-o/--out FILE` — write the JSON report to FILE as UTF-8 (implies `--json`).
+
+`run.sh` cds to the repo root, ensures `lxml` is installed, then runs the CLI.
+Equivalent without the wrapper: `python3 -m aimedicalcoding <document> [flags]`.
+
+## Coding systems the parser generates gaps for
+One pass over a document classifies every observation and emits a target-tagged
+gap for each terminology whose code is missing, non-standard, or malformed. The
+five terminologies currently generated, with where each lives in a CCDA and in
+a FHIR Bundle, and which gap patterns each can produce:
+
+| Target | CCDA source (slot) | FHIR source (slot) | Gap patterns it can emit |
+|---|---|---|---|
+| **LOINC** | results / vitals / surveys — observation `code` (question) | `Observation.code` (category `laboratory`/`vital-signs`/`social-history`/`survey`) | `LOCAL_CODE_ONLY` · `NULLFLAVOR` · `DISPLAY_ONLY` · `NARRATIVE_ONLY` · `BAD_CODE` |
+| **SNOMED CT** | problems / family hx / social hx / reactions — `value`; procedures / allergen substance — `code` | `Condition.code` / `FamilyMemberHistory.condition[].code` / `Observation.valueCodeableConcept` / `reaction[].manifestation[]` — value slot; `Procedure.code` / `AllergyIntolerance.code` — code slot | `LOCAL_CODE_ONLY` · **`ICD_ONLY`** · `NULLFLAVOR` · `DISPLAY_ONLY` · `NARRATIVE_ONLY` · `BAD_CODE` |
+| **RxNorm** | medications — `manufacturedMaterial/code` | `Medication.code` via `medicationReference` (or inline `medicationCodeableConcept`) | **`NDC_ONLY`** · **`MULTUM_ONLY`** · **`FDB_ONLY`** · **`MEDISPAN_ONLY`** · `LOCAL_CODE_ONLY` · `NULLFLAVOR` · `DISPLAY_ONLY` · `NARRATIVE_ONLY` |
+| **ICD-10-CM** | problems / encounters — diagnosis `value` | `Condition.code` (value slot) | **`SNOMED_ONLY`** · `LOCAL_CODE_ONLY` · `NULLFLAVOR` · `DISPLAY_ONLY` · `NARRATIVE_ONLY` · `BAD_CODE` |
+| **CVX** | immunizations — `manufacturedMaterial/code` | `Immunization.vaccineCode` | **`RXNORM_ONLY`** · **`NDC_ONLY`** · `LOCAL_CODE_ONLY` · `NULLFLAVOR` · `DISPLAY_ONLY` · `NARRATIVE_ONLY` · `BAD_CODE` |
+
+FHIR note: Trove bundles use the literal string `"unknown"` as the null marker
+(the CCDA `nullFlavor` equivalent). The FHIR adapter normalizes it everywhere
+(code / display / system / text); an entirely-"unknown" concept is reported as
+a `NULLFLAVOR` gap, and a real translation next to an "unknown" primary (e.g.
+CPT beside an "unknown" LOINC) is reported as `LOCAL_CODE_ONLY` with a
+crosswalk candidate.
+
+Planned (contracts stubbed): CPT · HCPCS · ICD-10-PCS.
+
+## Gap patterns (glossary)
+Two families. **Absence/quality patterns** apply to every system; **crosswalk
+patterns** (bold above) mean a code from *another* system is present that maps
+deterministically to the target. Full schema + per-pattern JSON in
+`docs/GAP_SCHEMA.md`.
+
+| Pattern | What's wrong | Recovery hint |
+|---|---|---|
+| `LOCAL_CODE_ONLY` | a local/in-house/proprietary code, no standard code | crosswalk local→target, else text+axis search |
+| `NULLFLAVOR` | code deliberately blank (`nullFlavor`); label from originalText/narrative | resolve recovered label |
+| `DISPLAY_ONLY` | a display name (or empty code) only, no usable code | resolve label |
+| `NARRATIVE_ONLY` | exists only as narrative-table text (opt-in) | value + reference range constrain |
+| `BAD_CODE` | right shape but fails validation (LOINC Mod-10 · SNOMED Verhoeff · ICD format · CVX numeric) | check-digit / format correction |
+| `ICD_ONLY` | ICD-9/10 present, no SNOMED | ICD↔SNOMED map (NLM) |
+| `SNOMED_ONLY` | SNOMED present, no ICD-10-CM | SNOMED→ICD-10-CM map (NLM) |
+| `NDC_ONLY` | NDC present, no RxNorm/CVX | NDC↔RxNorm / CDC NDC↔CVX table |
+| `RXNORM_ONLY` | RxNorm vaccine product, no CVX | CVX↔RxNorm map |
+| `MULTUM_ONLY` / `FDB_ONLY` / `MEDISPAN_ONLY` | proprietary drug vocab, no RxNorm | vendor↔RxNorm via UMLS CUI |
+
+Skipped (never emitted): a valid code for the target (incl. via `<translation>`),
+and observations whose only code is an HL7 structural marker like `ASSERTION` /
+`ActClass` (the real concept lives in the value slot).
+
+## Output schema (for the recovery / LLM team)
+The `--json` output is **format-agnostic** (identical for CCDA and FHIR) and
+flat. Per gap: `id, pattern, concept, section{}, codings[], absent_reason,
+value{type}, reference_range?, match_key, specimen{}, panel?, checkdigit_correction?,
+suggested_action, location{}`. The full contract, field reference, and a worked
+JSON example per pattern are in **`docs/GAP_SCHEMA.md`** — share that with the LLM team.
+
+## Tests
+```bash
+pip3 install lxml pytest --break-system-packages
+python3 -m pytest aimedicalcoding/tests/ -q
+python3 -m aimedicalcoding.tests.test_loinc_gaps     # prints a gap summary
+python3 -m aimedicalcoding.tests.test_fhir_adapter   # prints parsed FHIR statements
+```
+Fixtures are synthetic (no PHI): `fixtures/sample_ccda.xml`,
+`fixtures/sample_fhir_bundle.json`. Real documents live in `docs/input/` and
+`docs/Input_FHIRs/` (both gitignored — never commit).
+
+## Quick use
+```python3
+from aimedicalcoding.pipeline import parse_document
+stmts = parse_document(open("doc.xml", "rb").read())
+for s in stmts:
+    print(s.context, s.raw_text, [(c.system, c.code) for c in s.codings])
+```
+
+## Docs
+- **`docs/GAP_SCHEMA.md`** — the JSON output contract for consumers: envelope,
+  field reference, the discriminated `value`, and a JSON example per pattern with
+  the recommended recovery action. **Share this with the LLM/recovery team.**
+- **`docs/OUTPUT_GUIDE.md`** — how to read the human card/table report.
+- **`docs/ARCHITECTURE.md`** — system design.
+- **`docs/patterns/`** — per-terminology pattern analyses (LOINC, SNOMED, RxNorm):
+  structure, identifiers, where each appears in CCDA/FHIR, disambiguation, gap taxonomy.
+- **`docs/samples/`** — example CCDAs (`sample_all_systems.xml` exercises every
+  pattern across all three systems).