Offline Clinical Nephrology & Neuro-ICU Severe Hyponatremic Encephalopathy Sterns 3% Saline Bolus, DDAVP Clamp & Osmotic Demyelination Syndrome (ODS) Prevention Titrator

"""
OpenPHR Cookbook 402: Severe Hyponatremic Encephalopathy & ODS Prevention Engine
Clinical Standards: US & European Guidelines on Hyponatremia / Sterns Protocol
Execution: Deterministic, Zero External Dependencies, Edge & Offline Ready
"""

from dataclasses import dataclass, field
from enum import Enum
from typing import Dict, List, Optional, Tuple


class NeurologicalSymptomSeverity(Enum):
    SEVERE = "Severe (Seizures, Stupor, Coma, Cardiorespiratory Distress, Brainstem Herniation)"
    MODERATE = "Moderate (Nausea without vomiting, Confusion, Disorientation, Ataxia)"
    MILD_OR_NONE = "Mild or Asymptomatic (Headache, Fatigue, Lethargy, Mild Cognitive Slowness)"


class HyponatremiaChronicity(Enum):
    ACUTE = "Acute (< 48 hours documented)"
    CHRONIC = "Chronic (>= 48 hours or Unknown duration)"


class ODSRiskTier(Enum):
    HIGH_RISK = "High Risk for Osmotic Demyelination Syndrome (Target: 4-6 mEq/L per 24h, Max: 8 mEq/L)"
    STANDARD_RISK = "Standard Risk (Target: 6-8 mEq/L per 24h, Max: 10 mEq/L)"


class InfusateType(Enum):
    HYPERTONIC_SALINE_3_PCT = "3% Hypertonic Saline (513 mEq/L Na+)"
    NORMAL_SALINE_0_9_PCT = "0.9% Normal Saline (154 mEq/L Na+)"
    DEXTROSE_5_WATER_D5W = "5% Dextrose in Water (0 mEq/L Na+)"


@dataclass
class PatientHyponatremiaProfile:
    age_years: float
    weight_kg: float
    is_male: bool
    serum_na_meq_l: float
    serum_k_meq_l: float
    symptom_severity: NeurologicalSymptomSeverity
    chronicity: HyponatremiaChronicity
    has_advanced_cirrhosis: bool = False
    has_chronic_alcoholism: bool = False
    has_severe_malnutrition: bool = False
    baseline_sodium_meq_l: Optional[float] = None
    recent_urine_output_ml_per_hr: float = 0.0


@dataclass
class HypertonicBolusRecommendation:
    indicated: bool
    bolus_volume_ml: float
    infusion_duration_minutes: int
    infusate_name: str
    target_immediate_delta_na: str
    max_repeat_doses: int
    clinical_rationale: str


@dataclass
class AdrogueMadiasKinetics:
    total_body_water_liters: float
    predicted_delta_per_liter_3pct_saline: float
    predicted_delta_per_liter_ns: float
    predicted_delta_per_liter_d5w: float
    recommended_hourly_rate_ml_hr: float
    target_24h_na_ceiling: float
    ods_risk_tier: ODSRiskTier


@dataclass
class SafetySentinelReport:
    alerts: List[str]
    ddavp_clamp_recommended: bool
    ddavp_rescue_dose_indicated: bool
    frequent_monitoring_interval_hours: int
    mandatory_action_items: List[str]


@dataclass
class ComprehensiveHyponatremiaGuidance:
    patient_summary: Dict[str, str]
    bolus_recommendation: HypertonicBolusRecommendation
    kinetics: AdrogueMadiasKinetics
    sentinel_report: SafetySentinelReport


class HyponatremicEncephalopathyEngine:
    """
    Offline Clinical Engine for Severe Hyponatremia & ODS Prevention.
    Implements Sterns 3% bolus protocol, DDAVP clamp, and Adrogué-Madias kinetics.
    """

    SODIUM_3PCT_MEQ_L = 513.0
    SODIUM_NS_MEQ_L = 154.0
    SODIUM_D5W_MEQ_L = 0.0

    @staticmethod
    def calculate_total_body_water(age: float, weight_kg: float, is_male: bool) -> float:
        """
        Estimates total body water (TBW) based on Watson-Sterns age-gender coefficients.
        """
        is_elderly = age >= 65.0
        if is_male:
            fraction = 0.50 if is_elderly else 0.60
        else:
            fraction = 0.45 if is_elderly else 0.50
        return round(weight_kg * fraction, 2)

    @classmethod
    def evaluate_ods_risk(cls, patient: PatientHyponatremiaProfile) -> ODSRiskTier:
        """
        Determines Osmotic Demyelination Syndrome vulnerability tier.
        """
        if (
            patient.serum_na_meq_l <= 105.0
            or patient.serum_k_meq_l < 3.0
            or patient.has_advanced_cirrhosis
            or patient.has_chronic_alcoholism
            or patient.has_severe_malnutrition
        ):
            return ODSRiskTier.HIGH_RISK
        return ODSRiskTier.STANDARD_RISK

    @classmethod
    def calculate_adrogue_madias(
        cls,
        serum_na: float,
        infusate_na: float,
        infusate_k: float,
        tbw: float,
    ) -> float:
        """
        Adrogué-Madias equation incorporating potassium displacement factor:
        Delta Na+ = ((Na_infusate + K_infusate) - Na_serum) / (TBW + 1)
        """
        delta = ((infusate_na + infusate_k) - serum_na) / (tbw + 1.0)
        return round(delta, 3)

    @classmethod
    def evaluate_acute_bolus_need(
        cls, patient: PatientHyponatremiaProfile
    ) -> HypertonicBolusRecommendation:
        """
        Assesses emergent need for Sterns 3% hypertonic saline bolus.
        """
        is_severe = patient.symptom_severity == NeurologicalSymptomSeverity.SEVERE
        is_moderate_with_acute = (
            patient.symptom_severity == NeurologicalSymptomSeverity.MODERATE
            and patient.chronicity == HyponatremiaChronicity.ACUTE
        )

        if is_severe or is_moderate_with_acute:
            return HypertonicBolusRecommendation(
                indicated=True,
                bolus_volume_ml=100.0 if patient.weight_kg < 60.0 else 150.0,
                infusion_duration_minutes=15,
                infusate_name="3% Hypertonic Saline (NaCl 513 mEq/L)",
                target_immediate_delta_na="4.0 to 6.0 mEq/L increase within 1-2 hours",
                max_repeat_doses=3,
                clinical_rationale=(
                    "Emergent 3% saline bolus halts active uncal/tonsillar brain herniation and "
                    "aborts hyponatremic status epilepticus by reducing intracranial brain volume by 5-8%."
                ),
            )
        return HypertonicBolusRecommendation(
            indicated=False,
            bolus_volume_ml=0.0,
            infusion_duration_minutes=0,
            infusate_name="None (Bolus not indicated)",
            target_immediate_delta_na="Gradual maintenance titration",
            max_repeat_doses=0,
            clinical_rationale="No acute severe neurological symptoms; avoid rapid bolus to prevent overcorrection.",
        )

    @classmethod
    def generate_safety_sentinels(
        cls,
        patient: PatientHyponatremiaProfile,
        ods_tier: ODSRiskTier,
        kinetics: AdrogueMadiasKinetics,
    ) -> SafetySentinelReport:
        """
        Generates guardrails against overcorrection, water diuresis, and osmotic demyelination.
        """
        alerts: List[str] = []
        action_items: List[str] = []
        ddavp_clamp = False
        ddavp_rescue = False

        # Alert 1: ODS Velocity Ceiling
        if ods_tier == ODSRiskTier.HIGH_RISK:
            alerts.append(
                "CRITICAL ODS RISK: Patient has high vulnerability (Na <= 105, hypokalemia, cirrhosis, or malnutrition). "
                "Absolute correction ceiling is <= 4-6 mEq/L in 24 hours. NEVER exceed 8 mEq/L/24h."
            )
        else:
            alerts.append(
                "STANDARD ODS RISK: Maximum safe 24-hour correction ceiling is <= 8 mEq/L. "
                "Goal is 4 - 6 mEq/L in 24 hours."
            )

        # Alert 2: Potassium Displacement Sentinel
        if patient.serum_k_meq_l < 3.5:
            alerts.append(
                f"POTASSIUM SHIFT SENTINEL: Co-administered potassium ({patient.serum_k_meq_l} mEq/L) will enter cells "
                f"via Na+/K+-ATPase and displace sodium into serum. Each 1 mEq/kg of KCl administered will raise serum Na+ by ~1 mEq/L!"
            )
            action_items.append("Factor all infused potassium into hourly sodium correction rate calculations.")

        # Alert 3: Free Water Diuresis Overcorrection Threat
        if patient.recent_urine_output_ml_per_hr > 100.0:
            alerts.append(
                f"WATER DIURESIS WARNING: High urine output ({patient.recent_urine_output_ml_per_hr} mL/hr) indicates "
                "endogenous ADH suppression (e.g. volume depletion restored). Spontaneous water diuresis triggers rapid, "
                "uncontrolled sodium surges and fatal pontine demyelination."
            )
            ddavp_rescue = True
            action_items.append(
                "ADMINISTER RESCUE DESMOPRESSIN: 2 mcg IV STAT + start D5W infusion to replace urinary free water losses."
            )

        # Alert 4: Proactive DDAVP Clamp Strategy
        if patient.serum_na_meq_l < 115.0 and patient.chronicity == HyponatremiaChronicity.CHRONIC:
            ddavp_clamp = True
            action_items.append(
                "CONSIDER PROACTIVE DDAVP CLAMP: 1-2 mcg Desmopressin IV q6-8h while slowly infusing 3% saline. "
                "This clamps renal water excretion and makes serum sodium ascent entirely predictable and user-controlled."
            )

        # Alert 5: Laboratory Frequency
        freq_hours = 2 if patient.symptom_severity == NeurologicalSymptomSeverity.SEVERE else 4
        action_items.append(f"Stat serum sodium point-of-care verification every {freq_hours} hours until stable.")

        return SafetySentinelReport(
            alerts=alerts,
            ddavp_clamp_recommended=ddavp_clamp,
            ddavp_rescue_dose_indicated=ddavp_rescue,
            frequent_monitoring_interval_hours=freq_hours,
            mandatory_action_items=action_items,
        )

    @classmethod
    def run_assessment(cls, patient: PatientHyponatremiaProfile) -> ComprehensiveHyponatremiaGuidance:
        """
        Executes end-to-end clinical assessment and generates precise dosing instructions.
        """
        tbw = cls.calculate_total_body_water(patient.age_years, patient.weight_kg, patient.is_male)
        ods_tier = cls.evaluate_ods_risk(patient)
        bolus = cls.evaluate_acute_bolus_need(patient)

        delta_3pct = cls.calculate_adrogue_madias(patient.serum_na_meq_l, cls.SODIUM_3PCT_MEQ_L, 0.0, tbw)
        delta_ns = cls.calculate_adrogue_madias(patient.serum_na_meq_l, cls.SODIUM_NS_MEQ_L, 0.0, tbw)
        delta_d5w = cls.calculate_adrogue_madias(patient.serum_na_meq_l, cls.SODIUM_D5W_MEQ_L, 0.0, tbw)

        # Compute recommended 24h ceiling
        max_delta_24h = 6.0 if ods_tier == ODSRiskTier.HIGH_RISK else 8.0
        target_ceiling = round(patient.serum_na_meq_l + max_delta_24h, 1)

        # Hourly maintenance rate of 3% saline to achieve ~0.25 mEq/L/hr ascent
        ml_for_1meq = (1.0 / delta_3pct) * 1000.0 if delta_3pct > 0 else 0.0
        hourly_rate_ml_hr = round((ml_for_1meq * (max_delta_24h / 24.0)), 1)
        # Clinical ceiling clamp: usually 15 - 35 mL/hr
        hourly_rate_ml_hr = max(10.0, min(50.0, hourly_rate_ml_hr))

        kinetics = AdrogueMadiasKinetics(
            total_body_water_liters=tbw,
            predicted_delta_per_liter_3pct_saline=delta_3pct,
            predicted_delta_per_liter_ns=delta_ns,
            predicted_delta_per_liter_d5w=delta_d5w,
            recommended_hourly_rate_ml_hr=hourly_rate_ml_hr,
            target_24h_na_ceiling=target_ceiling,
            ods_risk_tier=ods_tier,
        )

        sentinels = cls.generate_safety_sentinels(patient, ods_tier, kinetics)

        patient_summary = {
            "Age/Sex/Weight": f"{patient.age_years:.0f}yo {'M' if patient.is_male else 'F'}, {patient.weight_kg:.1f} kg",
            "Serum Electrolytes": f"Na+ {patient.serum_na_meq_l:.1f} mEq/L, K+ {patient.serum_k_meq_l:.1f} mEq/L",
            "Chronicity": patient.chronicity.value,
            "Neurological Presentation": patient.symptom_severity.value,
            "ODS Risk Classification": ods_tier.value,
        }

        return ComprehensiveHyponatremiaGuidance(
            patient_summary=patient_summary,
            bolus_recommendation=bolus,
            kinetics=kinetics,
            sentinel_report=sentinels,
        )


# ==============================================================================
# Clinical Verification & Validation Suite
# ==============================================================================

def verify_clinical_scenarios():
    print("=" * 80)
    print("OpenPHR Cookbook 402: Severe Hyponatremic Encephalopathy & ODS Titrator")
    print("=" * 80)

    # Scenario 1: Severe Acute Neuro Symptoms (Herniation / Seizure Risk)
    p1 = PatientHyponatremiaProfile(
        age_years=58.0,
        weight_kg=70.0,
        is_male=True,
        serum_na_meq_l=112.0,
        serum_k_meq_l=3.8,
        symptom_severity=NeurologicalSymptomSeverity.SEVERE,
        chronicity=HyponatremiaChronicity.CHRONIC,
    )
    res1 = HyponatremicEncephalopathyEngine.run_assessment(p1)

    assert res1.bolus_recommendation.indicated is True
    assert res1.bolus_recommendation.bolus_volume_ml == 150.0
    assert res1.kinetics.ods_risk_tier == ODSRiskTier.STANDARD_RISK
    assert res1.kinetics.target_24h_na_ceiling == 120.0  # 112 + 8.0
    assert res1.kinetics.predicted_delta_per_liter_3pct_saline > 8.0
    assert res1.sentinel_report.frequent_monitoring_interval_hours == 2

    print("[*] Test Case 1 (Severe Symptomatic Seizure/Coma Presentation) PASSED")
    print(f"    - Bolus: {res1.bolus_recommendation.bolus_volume_ml} mL of {res1.bolus_recommendation.infusate_name}")
    print(f"    - Predicted Delta per 1L 3% NaCl: +{res1.kinetics.predicted_delta_per_liter_3pct_saline:.2f} mEq/L")
    print(f"    - 24h Absolute Ceiling: {res1.kinetics.target_24h_na_ceiling} mEq/L")

    # Scenario 2: High ODS Risk Patient (Cirrhosis + Hypokalemia + Severe Na 104)
    p2 = PatientHyponatremiaProfile(
        age_years=62.0,
        weight_kg=60.0,
        is_male=False,
        serum_na_meq_l=104.0,
        serum_k_meq_l=2.7,
        symptom_severity=NeurologicalSymptomSeverity.MODERATE,
        chronicity=HyponatremiaChronicity.CHRONIC,
        has_advanced_cirrhosis=True,
        recent_urine_output_ml_per_hr=160.0,  # Spontaneous water diuresis!
    )
    res2 = HyponatremicEncephalopathyEngine.run_assessment(p2)

    assert res2.kinetics.ods_risk_tier == ODSRiskTier.HIGH_RISK
    assert res2.kinetics.target_24h_na_ceiling == 110.0  # 104 + 6.0
    assert res2.sentinel_report.ddavp_rescue_dose_indicated is True
    assert any("POTASSIUM SHIFT SENTINEL" in a for a in res2.sentinel_report.alerts)
    assert any("WATER DIURESIS WARNING" in a for a in res2.sentinel_report.alerts)

    print("\n[*] Test Case 2 (High ODS Risk Cirrhotic with Water Diuresis) PASSED")
    print(f"    - ODS Tier: {res2.kinetics.ods_risk_tier.value}")
    print(f"    - Safe 24h Ceiling: {res2.kinetics.target_24h_na_ceiling} mEq/L (Conservative 6 mEq/L limit)")
    print(f"    - DDAVP Rescue Indicated: {res2.sentinel_report.ddavp_rescue_dose_indicated}")

    print("\n>>> ALL CLINICAL VERIFICATION TESTS PASSED (100% CONCORDANCE) <<<")


if __name__ == "__main__":
    verify_clinical_scenarios()