Healthcare Data Quality & AI Clinical Summary Validation

from dataclasses import dataclass
from typing import List, Dict, Optional, Set

@dataclass
class MedicationOrder:
    name: str
    dose: float
    unit: str
    frequency: str
    route: str

@dataclass
class ValidationReport:
    is_valid: bool
    critical_defects: List[str]
    warnings: List[str]

class ClinicalSummaryValidator:
    """Automated clinical assertion engine verifying LLM outputs against EHR ground truth."""
    def __init__(self, ground_truth_orders: List[MedicationOrder], documented_allergies: List[str]):
        self.gt_orders = {m.name.lower(): m for m in ground_truth_orders}
        self.allergies = {a.lower() for a in documented_allergies}

    def validate(self, generated_orders: List[MedicationOrder]) -> ValidationReport:
        defects: List[str] = []
        warnings: List[str] = []
        gen_names = {m.name.lower() for m in generated_orders}

        # Gate 1: Clinical Completeness (Active Order Omission Check)
        for gt_name, gt_med in self.gt_orders.items():
            if gt_name not in gen_names:
                defects.append(f"OMISSION_DEFECT: Active prescription '{gt_med.name}' omitted from summary.")

        # Gate 2: Medication Fidelity & Allergy Contraindication Checks
        for gen_med in generated_orders:
            name_clean = gen_med.name.lower()
            
            # Allergy Cross-Check (Contraindication Protection)
            if any(allergen in name_clean for allergen in self.allergies):
                defects.append(f"CONTRAINDICATION_DEFECT: Generated '{gen_med.name}' conflicts with allergy registry!")

            # Ground Truth Matching
            if name_clean in self.gt_orders:
                gt_med = self.gt_orders[name_clean]
                if gen_med.unit.lower() != gt_med.unit.lower():
                    defects.append(f"UNIT_MISMATCH: '{gen_med.name}' generated as {gen_med.unit}, expected {gt_med.unit} (Factor of 1,000x error).")
                if gen_med.dose != gt_med.dose:
                    defects.append(f"DOSE_MISMATCH: '{gen_med.name}' generated as {gen_med.dose}, expected {gt_med.dose}.")

        return ValidationReport(is_valid=(len(defects) == 0), critical_defects=defects, warnings=warnings)

{
  "audit_id": "VAL-EHR-84920",
  "patient_id": "PT-84920",
  "overall_status": "REJECTED",
  "gate_failures": [
    {
      "entity": "Levothyroxine",
      "expected": {"dose": 50, "unit": "mcg"},
      "actual": {"dose": 50, "unit": "mg"},
      "delta_factor": 1000,
      "severity": "CRITICAL"
    },
    {
      "entity": "Amoxicillin",
      "flag": "CONTRAINDICATED_ALLERGY_MATCH",
      "allergy_crosscheck": "PENICILLIN_ANAPHYLAXIS",
      "severity": "CRITICAL"
    },
    {
      "entity": "Potassium Chloride",
      "flag": "ACTIVE_ORDER_OMITTED",
      "severity": "HIGH"
    }
  ]
}