Add spine_coder package (core + dataset + tests)

spine_coder/spine_coder/spine_coder_core.py

@@ -19,6 +19,7 @@ def _level_sort_key(lv: str) -> Tuple[int, int]:
 
 def _extract_levels(t: str) -> List[str]:
     levels = set()
+    # Ranges like C4–C7 (en/em dashes) or hyphen
     for m in re.finditer(r"\b([CTLS])\s?(\d{1,2})\s*[-–]\s*([CTLS])?\s?(\d{1,2})\b", t, flags=re.I):
         pfx1, n1, pfx2, n2 = m.group(1).upper(), int(m.group(2)), (m.group(3) or m.group(1)).upper(), int(m.group(4))
         if pfx1 != pfx2:
@@ -26,6 +27,7 @@ def _extract_levels(t: str) -> List[str]:
         else:
             lo, hi = sorted([n1, n2])
             for k in range(lo, hi+1): levels.add(f"{pfx1}{k}")
+    # Singles like C5, L4, S1
     for m in re.finditer(r"\b([CTLS])\s?(\d{1,2})\b", t, flags=re.I):
         levels.add(f"{m.group(1).upper()}{int(m.group(2))}")
     return sorted(levels, key=_level_sort_key)
@@ -40,7 +42,9 @@ def _count_interspaces(levels: List[str]) -> int:
     for arr in by_band.values():
         if len(arr) >= 2:
             inters += sum(1 for i in range(1, len(arr)) if arr[i]-arr[i-1]==1)
+    # Special-case L5–S1 interspace if both present
     if "L5" in levels and "S1" in levels: inters += 1
+    # Fallback: if multiple segments but no explicit adjacency caught, assume at least 1 interspace
     if inters == 0:
         for arr in by_band.values():
             if len(arr) >= 2: inters = 1; break
@@ -61,7 +65,7 @@ def _laterality_mods(t: str) -> List[str]:
     mods: List[str] = []
     if _has(t, r"\bleft\b|left-sided|left side|leftward|hemilam\w* left|foraminotomy left|\blt\b"):
         mods.append("LT")
-    # tighten RIGHT: drop bare \brt\b to avoid accidental hits
+    # RIGHT: avoid bare \brt\b to reduce false positives
     if _has(t, r"\bright\b|right-sided|right side|rightward|hemilam\w* right|foraminotomy right"):
         mods.append("RT")
     return list(sorted(set(mods)))
@@ -82,6 +86,17 @@ def _inst_code_by_span(span_segments: int, anterior: bool) -> str:
     else:
         return "22842" if span_segments <= 3 else ("22843" if span_segments <= 7 else "22844")
 
+def tech_flags(note: str) -> dict:
+    """Surface microscope, navigation, neuromonitoring, and fluoro flags."""
+    t = _norm(note)
+    flags = {
+        "microscope": _has(t, r"\bmicroscope\b|operating microscope"),
+        "nav": _has(t, r"\bnavigation\b|o-?arm|computer[- ]?assisted"),
+        "io_monitor": _has(t, r"\bneuromonitor\w*|\b(ssep|meps?)\b|intraoperative monitoring"),
+        "fluoro": _has(t, r"\bfluoro\w*|\bc-arm\b"),
+    }
+    return {"flags": flags}
+
 # ---------- main ----------
 def suggest_with_cpt_billing(note: str, payer: str = "Medicare", top_k: int = 10) -> Dict[str, Any]:
     t = _norm(note)
@@ -93,13 +108,22 @@ def suggest_with_cpt_billing(note: str, payer: str = "Medicare", top_k: int = 10
     span   = _span_segments(levels)
     lat_mods = _laterality_mods(t)
 
-    # ---------- Region ----------
+    # ---------- Region (with transitional cervicothoracic first) ----------
     region = "unknown"
-    if any(l.startswith("C") for l in levels) or _has(t, r"\bcervic"): region = "cervical"
-    elif any(l.startswith("T") for l in levels) or _has(t, r"\bthorac"): region = "thoracic"
-    elif any(l.startswith(("L","S")) for l in levels) or _has(t, r"\blumbar|sacrum"): region = "lumbar"
-
-    # Helper flags
+    lvlset = set(levels)
+    # Transitional zone FIRST: cervicothoracic (e.g., C7–T2)
+    if _has(t, r"\bcervico[- ]?thoracic\b") \
+       or _has(t, r"\bc7\s*[-–]\s*t[1-3]\b") \
+       or ("C7" in lvlset and any(x in lvlset for x in ("T1","T2","T3"))):
+        region = "cervicothoracic"
+    elif any(l.startswith("C") for l in levels) or _has(t, r"\bcervic"):
+        region = "cervical"
+    elif any(l.startswith("T") for l in levels) or _has(t, r"\bthorac"):
+        region = "thoracic"
+    elif any(l.startswith(("L","S")) for l in levels) or _has(t, r"\blumbar|sacrum"):
+        region = "lumbar"
+
+    # Helper flags for instrumentation
     mentions_plate_ant = _has(t, r"\b(anterior (plate|instrument(ation)?)|plate fixed|plating)\b") or _has(t, r"\bplate\b")
     mentions_pedicle   = _has(t, r"\bpedicle screw|pedicle-screw|pedicle fixation|s2ai\b")
     mentions_rod       = _has(t, r"\brod(s)?\b")
@@ -211,7 +235,7 @@ def suggest_with_cpt_billing(note: str, payer: str = "Medicare", top_k: int = 10
                  "Pulse generator implanted.", "neurostimulator", False, 0.84)
         avoid_decompression_for_stimulator = True
 
-    # ---------- (7) Decompression (guarded: no history/corpectomy/revision/stimulator) ----------
+    # ---------- (7) Decompression (guarded) ----------
     if (not no_decompression_due_to_revision) and (not avoid_decompression_for_stimulator):
         if _has(t, r"\bdecompression(s)?\b|laminectom(y|ies)|laminotom(y|ies)|foraminotom(y|ies)|foraminal decompression(s)?|neuroforamen|lateral recess|central stenosis") \
            and not _has(t, r"\b(prior|previous|history of|s/?p)\s+(decompression|laminectomy|laminotomy|foraminotomy)\b"):
@@ -244,7 +268,6 @@ def suggest_with_cpt_billing(note: str, payer: str = "Medicare", top_k: int = 10
     if _has(t, r"\bcorpectomy\b") and (region == "cervical" or _has(t, r"\bcervic")):
         _add(suggestions, "63081", "Cervical corpectomy for decompression, first segment",
              "Cervical corpectomy documented.", "tumor/corpectomy", True, 0.86)
-        # rough extra estimate
         if _has(t, r"additional (level|segment)|two levels|three levels|multi|c\d-?c\d"):
             extra = max(1, inters or 1)
             _add(suggestions, "63082", f"Each additional cervical segment ×{extra}",
@@ -270,7 +293,6 @@ def suggest_with_cpt_billing(note: str, payer: str = "Medicare", top_k: int = 10
         _add(suggestions, base, "Posterior column osteotomy (Smith-Petersen), first level",
              "Deformity correction with SPO documented.", "deformity", True, 0.83)
         if _has(t, r"additional (level|segment)|two levels|three levels|multi"):
-            # For simplicity keep base+1 add-on mapping
             _add(suggestions, str(int(base)+1), "Each additional vertebral segment ×1+",
                  "Multi-level osteotomy.", "deformity add-on", False, 0.78)
 
@@ -336,7 +358,7 @@ def suggest_with_cpt_billing(note: str, payer: str = "Medicare", top_k: int = 10
     for k, pat in mod_map.items():
         if _has(t, pat): case_modifiers.append({"modifier": k, "reason": reasons[k]})
 
-    # EXPLICIT_BILATERAL_DECOMP: If 'bilateral' appears near decompression nouns, force 50 if not already set
+    # EXPLICIT_BILATERAL_DECOMP
     if not any(m["modifier"]=="50" for m in case_modifiers):
         if _has(t, r"\bbilateral\b") and _has(t, r"(foraminotom(y|ies)|facetectom(y|ies)|laminectom(y|ies)|laminotom(y|ies))"):
             case_modifiers.append({"modifier":"50","reason": reasons["50"]})
@@ -388,6 +410,19 @@ def suggest_with_cpt_billing(note: str, payer: str = "Medicare", top_k: int = 10
     out.sort(key=lambda r: (not r.get("primary", False), -(r.get("score", r.get("confidence",0.0))), _cpt_num(r)))
     if isinstance(top_k, int) and top_k > 0: out = out[:top_k]
 
+    # Tech flags
+    _tflags = tech_flags(note).get("flags", {})
+    _tflag_list = [k for k, v in _tflags.items() if v]
+
+    # Case-level laterality (meta)
+    case_laterality = "na"
+    if _has(t, r"\bbilateral\b|both sides"):
+        case_laterality = "bilateral"
+    elif _has(t, r"\bleft[- ]sided|\bleft\b"):
+        case_laterality = "left"
+    elif _has(t, r"\bright[- ]sided|\bright\b"):
+        case_laterality = "right"
+
     return {
         "payer": payer,
         "region": region,
@@ -395,5 +430,10 @@ def suggest_with_cpt_billing(note: str, payer: str = "Medicare", top_k: int = 10
         "interspaces_est": inters,
         "span_segments_est": span,
         "suggestions": out,
-        "case_modifiers": case_modifiers
+        "case_modifiers": case_modifiers,
+        "flags": _tflag_list,      # compact list for UI
+        "flags_map": _tflags,      # full boolean map
+        "laterality": case_laterality,
+        "build": "FINAL-v2.0",
+        "mode": "standard",
     }