feat: LCD-anchored confidence scoring algorithm (v2) (#32)

* feat: add policy data models, confidence scorer, and generic fallback policy

- T001: PolicyCriterion + PolicyDefinition Pydantic models with LCD metadata
- T002: Weighted LCD compliance scoring algorithm with bypass logic
- T003: Generic fallback policy builder for unsupported procedure codes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add policy registry with 5 LCD-backed seed policies

- T001: PolicyCriterion + PolicyDefinition data models
- T003: Generic fallback policy for unsupported procedure codes
- T004: PolicyRegistry with resolve() and generic fallback
- T007: 5 seed policies (MRI Lumbar L34220, MRI Brain L37373, TKA L36575, PT L34049, ESI L39240)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: update PAFormResponse model and enhance evidence extractor

- T005: Add optional policy_id and lcd_reference to PAFormResponse
- T006: Evidence extractor accepts PolicyDefinition, includes LCD context in prompts, parses confidence signals

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: wire form generator and analyze endpoint to LCD policy engine

- T008: Form generator delegates scoring to ConfidenceScorer, includes policy metadata
  - generate_form_data now accepts PolicyDefinition instead of dict
  - Recommendation and confidence_score come from calculate_confidence()
  - PAFormResponse includes policy_id and lcd_reference fields
- T009: Analyze endpoint uses PolicyRegistry.resolve() instead of hardcoded policy
  - Removed SUPPORTED_PROCEDURE_CODES gate (unknown CPTs get generic policy)
  - Removed EXAMPLE_POLICY import and dead _build_field_mappings helper
  - evidence_extractor accepts PolicyDefinition | dict via _normalize_criteria()
- T010: All 34 tests pass

Prerequisite modules created:
  - src/models/policy.py: PolicyCriterion, PolicyDefinition
  - src/reasoning/confidence_scorer.py: ScoreResult, calculate_confidence
  - src/policies/generic_policy.py: build_generic_policy
  - src/policies/registry.py: PolicyRegistry with 5 seed LCD policies

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: rsalus

apps/gateway/Gateway.API/Services/PostgresPARequestStore.cs

@@ -301,17 +301,21 @@ private async Task<string> GenerateIdAsync(CancellationToken ct)
         await IdGenerationLock.WaitAsync(ct).ConfigureAwait(false);
         try
         {
-            var maxId = await _context.PriorAuthRequests
+            // Filter to only sequential PA-NNN IDs (exclude PA-DEMO-* etc.)
+            var sequentialIds = await _context.PriorAuthRequests
                 .AsNoTracking()
                 .Select(e => e.Id)
-                .OrderByDescending(id => id)
-                .FirstOrDefaultAsync(ct)
+                .Where(id => id.StartsWith("PA-") && id.Length <= 7)
+                .ToListAsync(ct)
                 .ConfigureAwait(false);
 
             var counter = 1;
-            if (maxId is not null && maxId.StartsWith("PA-") && int.TryParse(maxId[3..], out var existing))
+            foreach (var id in sequentialIds)
             {
-                counter = existing + 1;
+                if (int.TryParse(id[3..], out var existing) && existing >= counter)
+                {
+                    counter = existing + 1;
+                }
             }
 
             return $"PA-{counter:D3}";

apps/intelligence/src/api/analyze.py

@@ -12,15 +12,12 @@
 from src.models.clinical_bundle import ClinicalBundle
 from src.models.pa_form import PAFormResponse
 from src.parsers.pdf_parser import parse_pdf
-from src.policies.example_policy import EXAMPLE_POLICY
+from src.policies.registry import registry
 from src.reasoning.evidence_extractor import extract_evidence
 from src.reasoning.form_generator import generate_form_data
 
 router = APIRouter()
 
-# Supported procedure codes (MRI Lumbar Spine)
-SUPPORTED_PROCEDURE_CODES = {"72148", "72149", "72158"}
-
 
 class AnalyzeRequest(BaseModel):
     """Request payload for analysis endpoint."""
@@ -36,14 +33,8 @@ async def analyze(request: AnalyzeRequest) -> PAFormResponse:
     Analyze clinical data and generate PA form response.
 
     Uses LLM to extract evidence from clinical data and generate PA form.
+    Resolves policy from registry; unknown CPT codes fall back to generic policy.
     """
-    # Check if procedure is supported
-    if request.procedure_code not in SUPPORTED_PROCEDURE_CODES:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Procedure code {request.procedure_code} not supported",
-        )
-
     # Parse clinical data into structured format
     bundle = ClinicalBundle.from_dict(request.patient_id, request.clinical_data)
 
@@ -55,8 +46,8 @@ async def analyze(request: AnalyzeRequest) -> PAFormResponse:
             detail="patient.birth_date is required",
         )
 
-    # Load policy with requested procedure code
-    policy = {**EXAMPLE_POLICY, "procedure_codes": [request.procedure_code]}
+    # Resolve policy from registry (no more 400 rejection for unsupported CPTs)
+    policy = registry.resolve(request.procedure_code)
 
     # Extract evidence using LLM
     evidence = await extract_evidence(bundle, policy)
@@ -87,21 +78,11 @@ async def analyze_with_documents(
     except json.JSONDecodeError as e:
         raise HTTPException(status_code=400, detail=f"Invalid clinical data JSON: {e}")
 
-    # Check if procedure is supported
-    if procedure_code not in SUPPORTED_PROCEDURE_CODES:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Procedure code {procedure_code} not supported",
-        )
-
-    # Parse clinical data into structured format
     bundle = ClinicalBundle.from_dict(patient_id, clinical_data_dict)
 
     # Read all document bytes, then parse PDFs in parallel
     pdf_bytes_list = [await doc.read() for doc in documents]
-
     document_texts = list(await asyncio.gather(*[parse_pdf(b) for b in pdf_bytes_list]))
-
     bundle.document_texts = document_texts
 
     # Validate required patient data
@@ -112,8 +93,8 @@ async def analyze_with_documents(
             detail="patient.birth_date is required",
         )
 
-    # Load policy with requested procedure code
-    policy = {**EXAMPLE_POLICY, "procedure_codes": [procedure_code]}
+    # Resolve policy from registry
+    policy = registry.resolve(procedure_code)
 
     # Extract evidence using LLM
     evidence = await extract_evidence(bundle, policy)
@@ -122,30 +103,3 @@ async def analyze_with_documents(
     form_response = await generate_form_data(bundle, evidence, policy)
 
     return form_response
-
-
-def _build_field_mappings(bundle: ClinicalBundle, procedure_code: str) -> dict[str, str]:
-    """Build PDF field mappings from clinical bundle."""
-    patient_name = bundle.patient.name if bundle.patient else "Unknown"
-    patient_dob = (
-        bundle.patient.birth_date.isoformat()
-        if bundle.patient and bundle.patient.birth_date
-        else "Unknown"
-    )
-    member_id = (
-        bundle.patient.member_id
-        if bundle.patient and bundle.patient.member_id
-        else "Unknown"
-    )
-    diagnosis_codes = ", ".join(c.code for c in bundle.conditions) if bundle.conditions else ""
-
-    return {
-        "PatientName": patient_name,
-        "PatientDOB": patient_dob,
-        "MemberID": member_id,
-        "DiagnosisCodes": diagnosis_codes,
-        "ProcedureCode": procedure_code,
-        "ClinicalSummary": "Awaiting production configuration",
-        "ProviderSignature": "",
-        "Date": "",
-    }

apps/intelligence/src/models/pa_form.py

@@ -32,3 +32,7 @@ class PAFormResponse(BaseModel):
     field_mappings: dict[str, str] = Field(
         description="PDF field name to value mappings"
     )
+    policy_id: str | None = Field(default=None, description="Policy identifier")
+    lcd_reference: str | None = Field(
+        default=None, description="LCD article reference"
+    )

apps/intelligence/src/models/policy.py

@@ -0,0 +1,28 @@
+"""Policy data models for LCD-backed prior authorization criteria."""
+
+from pydantic import BaseModel
+
+
+class PolicyCriterion(BaseModel):
+    """A single criterion from a coverage policy."""
+
+    id: str
+    description: str
+    weight: float  # 0.0-1.0, clinical importance
+    required: bool = False  # Hard gate — if NOT_MET, caps score
+    lcd_section: str | None = None  # e.g. "L34220 §4.2"
+    bypasses: list[str] = []  # criterion IDs this one bypasses when MET
+
+
+class PolicyDefinition(BaseModel):
+    """Complete policy definition with LCD metadata."""
+
+    policy_id: str
+    policy_name: str
+    lcd_reference: str | None = None  # e.g. "L34220"
+    lcd_title: str | None = None
+    lcd_contractor: str | None = None
+    payer: str
+    procedure_codes: list[str]
+    diagnosis_codes: list[str] = []
+    criteria: list[PolicyCriterion]

apps/intelligence/src/policies/generic_policy.py

@@ -0,0 +1,35 @@
+"""Generic fallback policy for unsupported procedure codes."""
+
+from src.models.policy import PolicyCriterion, PolicyDefinition
+
+
+def build_generic_policy(procedure_code: str) -> PolicyDefinition:
+    """Build a generic medical necessity policy for any procedure code."""
+    return PolicyDefinition(
+        policy_id=f"generic-{procedure_code}",
+        policy_name="General Medical Necessity",
+        lcd_reference=None,
+        payer="General",
+        procedure_codes=[procedure_code],
+        diagnosis_codes=[],
+        criteria=[
+            PolicyCriterion(
+                id="medical_necessity",
+                description="Medical necessity is documented with clinical rationale",
+                weight=0.40,
+                required=True,
+            ),
+            PolicyCriterion(
+                id="diagnosis_present",
+                description="Valid diagnosis code is present and supports the procedure",
+                weight=0.30,
+                required=True,
+            ),
+            PolicyCriterion(
+                id="conservative_therapy",
+                description="Conservative therapy attempted or documented as not applicable",
+                weight=0.30,
+                required=False,
+            ),
+        ],
+    )

apps/intelligence/src/policies/registry.py

@@ -0,0 +1,30 @@
+"""Policy registry for resolving procedure codes to policy definitions."""
+
+from src.models.policy import PolicyDefinition
+from src.policies.generic_policy import build_generic_policy
+
+
+class PolicyRegistry:
+    """Resolves procedure codes to LCD-backed policy definitions."""
+
+    def __init__(self) -> None:
+        self._by_cpt: dict[str, PolicyDefinition] = {}
+
+    def register(self, policy: PolicyDefinition) -> None:
+        for cpt in policy.procedure_codes:
+            self._by_cpt[cpt] = policy
+
+    def resolve(self, procedure_code: str) -> PolicyDefinition:
+        """Return LCD-backed policy if available, else generic fallback."""
+        if procedure_code in self._by_cpt:
+            return self._by_cpt[procedure_code]
+        return build_generic_policy(procedure_code)
+
+
+# Module-level singleton
+registry = PolicyRegistry()
+
+# Import seed policies to register them
+from src.policies.seed import register_all_seeds  # noqa: E402
+
+register_all_seeds(registry)

apps/intelligence/src/policies/seed/__init__.py

@@ -0,0 +1,13 @@
+"""Seed policy loader."""
+from src.policies.seed.mri_lumbar import POLICY as MRI_LUMBAR
+from src.policies.seed.mri_brain import POLICY as MRI_BRAIN
+from src.policies.seed.tka import POLICY as TKA
+from src.policies.seed.physical_therapy import POLICY as PHYSICAL_THERAPY
+from src.policies.seed.epidural_steroid import POLICY as EPIDURAL_STEROID
+
+ALL_SEED_POLICIES = [MRI_LUMBAR, MRI_BRAIN, TKA, PHYSICAL_THERAPY, EPIDURAL_STEROID]
+
+
+def register_all_seeds(registry) -> None:
+    for policy in ALL_SEED_POLICIES:
+        registry.register(policy)

apps/intelligence/src/policies/seed/epidural_steroid.py

@@ -0,0 +1,51 @@
+"""Epidural Steroid Injection seed policy — LCD L39240."""
+
+from src.models.policy import PolicyCriterion, PolicyDefinition
+
+POLICY = PolicyDefinition(
+    policy_id="lcd-esi-L39240",
+    policy_name="Epidural Steroid Injection",
+    lcd_reference="L39240",
+    lcd_title="Epidural Steroid Injections",
+    lcd_contractor="Noridian Healthcare Solutions",
+    payer="CMS Medicare",
+    procedure_codes=["62322", "62323"],
+    diagnosis_codes=["M54.10", "M54.16", "M54.17", "M48.06"],
+    criteria=[
+        PolicyCriterion(
+            id="diagnosis_confirmed",
+            description="Radiculopathy/stenosis confirmed by history, exam, and imaging",
+            weight=0.25,
+            required=True,
+            lcd_section="L39240 — Requirement 1",
+        ),
+        PolicyCriterion(
+            id="severity_documented",
+            description="Pain severe enough to impact QoL/function, documented with standardized scale",
+            weight=0.20,
+            required=True,
+            lcd_section="L39240 — Requirement 2",
+        ),
+        PolicyCriterion(
+            id="conservative_care_4wk",
+            description="4 weeks conservative care failed/intolerable (except acute herpes zoster)",
+            weight=0.25,
+            required=True,
+            lcd_section="L39240 — Requirement 3",
+        ),
+        PolicyCriterion(
+            id="frequency_within_limits",
+            description="<=4 sessions per region per rolling 12 months",
+            weight=0.15,
+            required=True,
+            lcd_section="L39240 — Frequency Limits",
+        ),
+        PolicyCriterion(
+            id="image_guidance_planned",
+            description="Fluoroscopy or CT guidance with contrast planned",
+            weight=0.15,
+            required=True,
+            lcd_section="L39240 — Procedural Requirements",
+        ),
+    ],
+)

apps/intelligence/src/policies/seed/mri_brain.py

@@ -0,0 +1,44 @@
+"""MRI Brain seed policy — LCD L37373."""
+
+from src.models.policy import PolicyCriterion, PolicyDefinition
+
+POLICY = PolicyDefinition(
+    policy_id="lcd-mri-brain-L37373",
+    policy_name="MRI Brain",
+    lcd_reference="L37373",
+    lcd_title="Magnetic Resonance Imaging of the Brain",
+    lcd_contractor="Noridian Healthcare Solutions",
+    payer="CMS Medicare",
+    procedure_codes=["70551", "70552", "70553"],
+    diagnosis_codes=["G40.909", "R51.9", "G43.909", "G35"],
+    criteria=[
+        PolicyCriterion(
+            id="diagnosis_present",
+            description="Valid ICD-10 for neurological condition",
+            weight=0.15,
+            required=True,
+            lcd_section="L37373 / A57204 — Covered Diagnoses",
+        ),
+        PolicyCriterion(
+            id="neurological_indication",
+            description="Tumor, stroke, MS, seizures, unexplained neuro deficit",
+            weight=0.35,
+            required=True,
+            lcd_section="L37373 — Indications for MRI",
+        ),
+        PolicyCriterion(
+            id="ct_insufficient",
+            description="CT already performed and insufficient, or MRI specifically indicated",
+            weight=0.25,
+            required=False,
+            lcd_section="L37373 — MRI vs CT Selection",
+        ),
+        PolicyCriterion(
+            id="clinical_documentation",
+            description="Supporting clinical findings documented",
+            weight=0.25,
+            required=True,
+            lcd_section="L37373 — Coverage Requirements",
+        ),
+    ],
+)