Cookbook 321: Offline Clinical Nephrology KDIGO AKI, Furosemide Stress Test & CRRT Dose Engine

"""
Cookbook 321: Offline Nephrology KDIGO AKI, Furosemide Stress Test & CRRT Dose Engine
OpenPHR Clinical AI Working Group (https://openphr.org)
"""

import math
import numpy as np
import pandas as pd
from typing import Dict, List, Tuple, Optional
from dataclasses import dataclass

@dataclass
class NephrologyICUTelemetry:
    patient_id: str
    age_years: float
    patient_weight_kg: float = 78.0 # kg
    hematocrit_fraction: float = 0.30 # 30% Hct
    # Renal Biomarkers
    baseline_serum_creatinine_mg_dl: float = 1.0 # mg/dL
    current_serum_creatinine_mg_dl: float = 3.2 # mg/dL
    hours_since_baseline_scr: float = 36.0 # hours
    urine_output_last_6h_ml_kg_h: float = 0.25 # mL/kg/h
    urine_output_last_12h_ml_kg_h: float = 0.20 # mL/kg/h
    urine_output_last_24h_ml_kg_h: float = 0.18 # mL/kg/h
    anuria_duration_hours: float = 0.0
    # Furosemide Stress Test (FST) Parameters
    fst_administered: bool = True
    is_loop_diuretic_naive: bool = False # False = exposed within 7d (Needs 1.5 mg/kg)
    fst_furosemide_dose_mg: float = 120.0 # mg
    fst_cumulative_2h_urine_volume_ml: float = 110.0 # mL (Cutoff < 200 mL = Non-responder)
    # CRRT Prescription & Telemetry
    crrt_active: bool = True
    crrt_modality: str = "CVVHDF" # CVVHDF, CVVH, CVVHD
    blood_flow_rate_qb_ml_min: float = 200.0 # mL/min
    dialysate_flow_rate_qd_ml_h: float = 1000.0 # mL/h
    replacement_pre_filter_qpre_ml_h: float = 600.0 # mL/h
    replacement_post_filter_qpost_ml_h: float = 400.0 # mL/h
    pre_blood_pump_citrate_qpbp_ml_h: float = 200.0 # mL/h
    net_ultrafiltration_fluid_removal_ml_h: float = 150.0 # mL/h
    estimated_daily_downtime_percent: float = 12.0 # % (10-15%)
    # Regional Citrate Anticoagulation (RCA) Laboratory Metrics
    circuit_post_filter_ionized_ca_mmol_l: float = 0.32 # Target 0.25 - 0.40 mmol/L
    systemic_ionized_ca_mmol_l: float = 1.18 # Target 1.10 - 1.30 mmol/L
    total_serum_calcium_mg_dl: float = 9.2 # mg/dL

@dataclass
class NephrologyEvaluationReport:
    patient_id: str
    kdigo_aki_stage: str # "KDIGO AKI Stage 3", "Stage 2", "Stage 1", "No AKI"
    kdigo_criteria_triggered: List[str]
    fst_responsiveness_status: str # "FST Non-Responsive (High Risk for RRT)", "FST Responsive"
    fst_analysis: str
    crrt_prescribed_effluent_dose_ml_kg_h: float
    crrt_delivered_effluent_dose_ml_kg_h: float
    crrt_dose_adequacy_status: str
    rca_anticoagulation_audit: List[str]
    safety_sentinels: List[str]
    clinical_kdigo_adqi_directive: str

class CriticalCareNephrologyEngine:
    """
    Offline clinical engine for KDIGO AKI staging, Furosemide Stress Test (FST)
    stratification, CRRT effluent dose verification, and Regional Citrate Anticoagulation
    safety monitoring.
    """

    def stage_kdigo_aki(self, d: NephrologyICUTelemetry) -> Tuple[str, List[str]]:
        triggers = []
        stage = 0

        # Serum Creatinine Criteria
        scr_delta = d.current_serum_creatinine_mg_dl - d.baseline_serum_creatinine_mg_dl
        scr_ratio = d.current_serum_creatinine_mg_dl / max(d.baseline_serum_creatinine_mg_dl, 0.1)

        if scr_ratio >= 3.0 or d.current_serum_creatinine_mg_dl >= 4.0 or d.crrt_active:
            stage = max(stage, 3)
            triggers.append(f"Stage 3 SCr: Current SCr ({d.current_serum_creatinine_mg_dl:.1f} mg/dL) >= 3.0x baseline ({d.baseline_serum_creatinine_mg_dl:.1f} mg/dL) or CRRT active.")
        elif scr_ratio >= 2.0:
            stage = max(stage, 2)
            triggers.append(f"Stage 2 SCr: Current SCr ({d.current_serum_creatinine_mg_dl:.1f} mg/dL) >= 2.0-2.9x baseline.")
        elif scr_ratio >= 1.5 or (scr_delta >= 0.3 and d.hours_since_baseline_scr <= 48.0):
            stage = max(stage, 1)
            triggers.append(f"Stage 1 SCr: SCr rise >= 0.3 mg/dL within 48h (Delta: {scr_delta:+.2f} mg/dL) or >= 1.5x baseline.")

        # Urine Output Criteria
        if d.anuria_duration_hours >= 12.0 or d.urine_output_last_24h_ml_kg_h < 0.3:
            stage = max(stage, 3)
            triggers.append(f"Stage 3 UOP: UOP < 0.3 mL/kg/h for 24h ({d.urine_output_last_24h_ml_kg_h:.2f} mL/kg/h) or Anuria >= 12h.")
        elif d.urine_output_last_12h_ml_kg_h < 0.5:
            stage = max(stage, 2)
            triggers.append(f"Stage 2 UOP: UOP < 0.5 mL/kg/h for >= 12h ({d.urine_output_last_12h_ml_kg_h:.2f} mL/kg/h).")
        elif d.urine_output_last_6h_ml_kg_h < 0.5:
            stage = max(stage, 1)
            triggers.append(f"Stage 1 UOP: UOP < 0.5 mL/kg/h for >= 6h ({d.urine_output_last_6h_ml_kg_h:.2f} mL/kg/h).")

        stage_labels = {
            0: "No AKI Detected",
            1: "KDIGO AKI Stage 1 (Mild)",
            2: "KDIGO AKI Stage 2 (Moderate)",
            3: "KDIGO AKI Stage 3 (Severe / Critical)"
        }
        return stage_labels.get(stage, "KDIGO AKI Stage 3"), triggers

    def evaluate_fst(self, d: NephrologyICUTelemetry) -> Tuple[str, str]:
        if not d.fst_administered:
            return "FST Not Administered", "Furosemide Stress Test not performed in this encounter."

        recommended_dose = d.patient_weight_kg * (1.0 if d.is_loop_diuretic_naive else 1.5)
        dose_check = f"Administered dose: {d.fst_furosemide_dose_mg:.0f} mg (Target: {recommended_dose:.0f} mg for {'Naive' if d.is_loop_diuretic_naive else 'Exposed'})."

        # Cutoff: < 200 mL in 2 hours
        if d.fst_cumulative_2h_urine_volume_ml < 200.0:
            status = "FST Non-Responsive (High Risk for Progression to Stage 3 AKI / RRT)"
            analysis = f"{dose_check} Cumulative 2-hour urine volume was {d.fst_cumulative_2h_urine_volume_ml:.0f} mL (< 200 mL cutoff). High likelihood (>85%) of severe tubular dysfunction requiring CRRT initiation."
        else:
            status = "FST Responsive (Intact Tubular Integrity)"
            analysis = f"{dose_check} Cumulative 2-hour urine volume was {d.fst_cumulative_2h_urine_volume_ml:.0f} mL (>= 200 mL cutoff). Preserved medullary responsiveness."

        return status, analysis

    def calculate_crrt_dose(self, d: NephrologyICUTelemetry) -> Tuple[float, float, str, float]:
        # Total effluent = Qd + Qpre + Qpost + Qpbp + Qnet_uf
        total_effluent_ml_h = (
            d.dialysate_flow_rate_qd_ml_h +
            d.replacement_pre_filter_qpre_ml_h +
            d.replacement_post_filter_qpost_ml_h +
            d.pre_blood_pump_citrate_qpbp_ml_h +
            d.net_ultrafiltration_fluid_removal_ml_h
        )

        prescribed_dose = total_effluent_ml_h / d.patient_weight_kg

        # Pre-filter dilution factor:
        # Cdil = (Qb * (1-Hct)) / (Qb * (1-Hct) + Qpre_total)
        # Convert Qb (mL/min) to mL/h: Qb * 60
        plasma_flow_ml_h = (d.blood_flow_rate_qb_ml_min * 60.0) * (1.0 - d.hematocrit_fraction)
        pre_filter_total_ml_h = d.replacement_pre_filter_qpre_ml_h + d.pre_blood_pump_citrate_qpbp_ml_h
        dilution_factor = plasma_flow_ml_h / (plasma_flow_ml_h + pre_filter_total_ml_h) if pre_filter_total_ml_h > 0 else 1.0

        # Delivered dose adjusts for dilution factor and downtime
        downtime_factor = 1.0 - (d.estimated_daily_downtime_percent / 100.0)
        delivered_dose = prescribed_dose * dilution_factor * downtime_factor

        if delivered_dose >= 20.0 and delivered_dose <= 25.0:
            adequacy = f"✅ OPTIMAL KDIGO EFFLUENT DOSE: Delivered {delivered_dose:.1f} mL/kg/h within 20-25 mL/kg/h guideline target."
        elif delivered_dose < 20.0:
            adequacy = f"⚠️ UNDER-DIALYSIS WARNING: Delivered dose {delivered_dose:.1f} mL/kg/h < 20 mL/kg/h target. Increase prescribed flow rates."
        else:
            adequacy = f"ℹ️ SUPRA-THERAPEUTIC DOSE: Delivered {delivered_dose:.1f} mL/kg/h > 25 mL/kg/h (No survival benefit demonstrated for >25 mL/kg/h in ATN/RENAL trials)."

        return round(prescribed_dose, 1), round(delivered_dose, 1), adequacy, round(dilution_factor, 3)

    def audit_rca_citrate(self, d: NephrologyICUTelemetry) -> Tuple[List[str], List[str]]:
        audit = []
        sentinels = []

        # Circuit Post-filter iCa target: 0.25 - 0.40 mmol/L
        if d.circuit_post_filter_ionized_ca_mmol_l >= 0.25 and d.circuit_post_filter_ionized_ca_mmol_l <= 0.40:
            audit.append(f"✅ Circuit Post-Filter iCa: {d.circuit_post_filter_ionized_ca_mmol_l:.2f} mmol/L within target (0.25 - 0.40 mmol/L).")
        elif d.circuit_post_filter_ionized_ca_mmol_l > 0.40:
            audit.append(f"⚠️ UNDER-ANTICOAGULATION: Circuit iCa {d.circuit_post_filter_ionized_ca_mmol_l:.2f} mmol/L > 0.40 mmol/L -> Increase pre-blood pump citrate rate.")
        else:
            audit.append(f"ℹ️ EXCESSIVE ANTICOAGULATION: Circuit iCa {d.circuit_post_filter_ionized_ca_mmol_l:.2f} mmol/L < 0.25 mmol/L.")

        # Systemic iCa target: 1.10 - 1.30 mmol/L
        if d.systemic_ionized_ca_mmol_l >= 1.10 and d.systemic_ionized_ca_mmol_l <= 1.30:
            audit.append(f"✅ Systemic Arterial iCa: {d.systemic_ionized_ca_mmol_l:.2f} mmol/L within target (1.10 - 1.30 mmol/L).")
        elif d.systemic_ionized_ca_mmol_l < 1.10:
            sentinels.append(f"HYPOCALCEMIA ALERT: Systemic iCa {d.systemic_ionized_ca_mmol_l:.2f} mmol/L < 1.10 mmol/L -> Increase systemic calcium infusion rate.")
        else:
            sentinels.append(f"HYPERCALCEMIA ALERT: Systemic iCa {d.systemic_ionized_ca_mmol_l:.2f} mmol/L > 1.30 mmol/L -> Decrease systemic calcium infusion.")

        # Total Ca (mmol/L) = Total Ca (mg/dL) * 0.25
        total_ca_mmol_l = d.total_serum_calcium_mg_dl * 0.25
        citrate_ratio = total_ca_mmol_l / max(d.systemic_ionized_ca_mmol_l, 0.1)

        if citrate_ratio > 2.5:
            sentinels.append(f"🚨 CITRATE ACCUMULATION / CITRATE TOXICITY DETECTED: Total Ca / Systemic iCa ratio = {citrate_ratio:.2f} (> 2.5 cutoff). Indicates impaired hepatic citrate metabolism. Immediately reduce/stop citrate, increase dialysate clearance, or switch to heparin.")
        else:
            audit.append(f"✅ Citrate Ratio: Total Ca / iCa = {citrate_ratio:.2f} (<= 2.5 normal metabolic clearance).")

        return audit, sentinels

    def evaluate_case(self, data: NephrologyICUTelemetry) -> NephrologyEvaluationReport:
        stage_label, triggers = self.stage_kdigo_aki(data)
        fst_status, fst_desc = self.evaluate_fst(data)
        presc_dose, deliv_dose, dose_adequacy, dil_factor = self.calculate_crrt_dose(data)
        rca_audit, sentinels = self.audit_rca_citrate(data)

        directives = []
        directives.append(f"STAGE: {stage_label}.")
        directives.append(f"FST STATUS: {fst_status}.")
        directives.append(f"CRRT DOSE: Prescribed {presc_dose} mL/kg/h, Delivered {deliv_dose} mL/kg/h (Dilution factor {dil_factor}).")
        directives.append(dose_adequacy)

        return NephrologyEvaluationReport(
            patient_id=data.patient_id,
            kdigo_aki_stage=stage_label,
            kdigo_criteria_triggered=triggers,
            fst_responsiveness_status=fst_status,
            fst_analysis=fst_desc,
            crrt_prescribed_effluent_dose_ml_kg_h=presc_dose,
            crrt_delivered_effluent_dose_ml_kg_h=deliv_dose,
            crrt_dose_adequacy_status=dose_adequacy,
            rca_anticoagulation_audit=rca_audit,
            safety_sentinels=sentinels,
            clinical_kdigo_adqi_directive=" ".join(directives)
        )

# Example Execution & Verification
if __name__ == "__main__":
    engine = CriticalCareNephrologyEngine()

    print("=" * 80)
    print("OpenPHR Clinical Nephrology KDIGO AKI, FST & CRRT Dose Engine")
    print("=" * 80)

    # Test Case 1: 68-year-old male in Septic Shock with Severe Oliguric AKI
    # Weight: 78 kg. Baseline SCr: 1.0 mg/dL, Current: 3.2 mg/dL.
    # FST: 120 mg furosemide administered -> 2-hour volume: 110 mL (< 200 mL non-responder).
    # CVVHDF Active: Prescribed 2350 mL/h effluent (30.1 mL/kg/h) -> Delivered: 22.8 mL/kg/h (Optimal KDIGO).
    # RCA Citrate: Circuit iCa 0.32 mmol/L, Systemic iCa 1.18 mmol/L, Total Ca 9.2 mg/dL (Ratio 1.95 <= 2.5).
    icu1 = NephrologyICUTelemetry(
        patient_id="ICU-NEPH-5501",
        age_years=68.0,
        patient_weight_kg=78.0,
        baseline_serum_creatinine_mg_dl=1.0,
        current_serum_creatinine_mg_dl=3.2,
        urine_output_last_12h_ml_kg_h=0.20,
        urine_output_last_24h_ml_kg_h=0.18,
        fst_administered=True,
        is_loop_diuretic_naive=False,
        fst_furosemide_dose_mg=120.0,
        fst_cumulative_2h_urine_volume_ml=110.0,
        crrt_active=True,
        crrt_modality="CVVHDF",
        blood_flow_rate_qb_ml_min=200.0,
        dialysate_flow_rate_qd_ml_h=1000.0,
        replacement_pre_filter_qpre_ml_h=600.0,
        replacement_post_filter_qpost_ml_h=400.0,
        pre_blood_pump_citrate_qpbp_ml_h=200.0,
        net_ultrafiltration_fluid_removal_ml_h=150.0,
        estimated_daily_downtime_percent=12.0,
        circuit_post_filter_ionized_ca_mmol_l=0.32,
        systemic_ionized_ca_mmol_l=1.18,
        total_serum_calcium_mg_dl=9.2
    )

    rep1 = engine.evaluate_case(icu1)

    print(f"\n[Patient {rep1.patient_id} - ICU Nephrology Audit]")
    print(f"Staging: {rep1.kdigo_aki_stage}")
    for t in rep1.kdigo_criteria_triggered:
        print(f"  • {t}")
    print(f"\nFST Dynamic Challenge: {rep1.fst_responsiveness_status}")
    print(f"  {rep1.fst_analysis}")
    print(f"\nCRRT Effluent Dosing:")
    print(f"  Prescribed Dose: {rep1.crrt_prescribed_effluent_dose_ml_kg_h} mL/kg/h")
    print(f"  Delivered Dose:  {rep1.crrt_delivered_effluent_dose_ml_kg_h} mL/kg/h")
    print(f"  Status:          {rep1.crrt_dose_adequacy_status}")
    print(f"\nRegional Citrate Anticoagulation (RCA) Monitoring:")
    for a in rep1.rca_anticoagulation_audit:
        print(f"  {a}")
    if rep1.safety_sentinels:
        print(f"\nSafety Sentinels:")
        for s in rep1.safety_sentinels:
            print(f"  🚨 {s}")
    print(f"\nKDIGO / ADQI Directive:\n{rep1.clinical_kdigo_adqi_directive}")