Cookbook 332: Offline Clinical Nephrology Lupus Nephritis ISN/RPS 2018, NIH Index & Voclosporin Engine

"""
Cookbook 332: Offline Nephrology Lupus Nephritis ISN/RPS 2018, NIH Index & Voclosporin 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 LupusNephritisTelemetry:
    patient_id: str
    age_years: float = 32.0
    sex: str = "Female"
    patient_weight_kg: float = 60.0
    # Renal Biomarker Telemetry
    baseline_egfr_ml_min: float = 85.0 # mL/min/1.73m2
    current_egfr_ml_min: float = 78.0 # mL/min/1.73m2
    serum_creatinine_mg_dl: float = 1.15 # mg/dL
    baseline_upcr_g_g: float = 3.80 # g/g (Nephrotic-range proteinuria)
    current_upcr_g_g: float = 1.60 # g/g (At 6 months follow-up: 57.9% reduction)
    months_on_induction_therapy: int = 6 # Follow-up milestone
    # Serological Telemetry
    anti_dsdna_titers_iu_ml: float = 180.0 # High positive (> 30 IU/mL)
    serum_c3_mg_dl: float = 54.0 # Low (< 90 mg/dL = active complement consumption)
    serum_c4_mg_dl: float = 8.0 # Low (< 10 mg/dL)
    # ISN/RPS 2018 Histopathological Class Telemetry
    primary_histologic_class: str = "Class IV-G" # "Class I", "Class II", "Class III", "Class IV-S", "Class IV-G", "Class V", "Class VI"
    coexisting_class_v_membranous: bool = True # Class IV + V overlap
    # Modified NIH Activity Index Components (0 - 3 points each; 4 components weighted x2)
    nih_endocapillary_hypercellularity: int = 2 # (0-3)
    nih_neutrophils_karyorrhexis: int = 1 # (0-3) [x2]
    nih_fibrinoid_necrosis: int = 1 # (0-3) [x2]
    nih_cellular_crescents: int = 2 # (0-3) [x2]
    nih_hyaline_deposits_wire_loops: int = 2 # (0-3)
    nih_interstitial_inflammation: int = 1 # (0-3)
    # Modified NIH Chronicity Index Components (0 - 3 points each; max 12)
    nih_glomerulosclerosis: int = 1 # (0-3)
    nih_fibrous_crescents: int = 0 # (0-3)
    nih_tubular_atrophy: int = 1 # (0-3)
    nih_interstitial_fibrosis: int = 1 # (0-3)
    # Current Active Pharmacotherapy
    active_hydroxychloroquine: bool = False # 🚨 MANDATORY BACKGROUND CONTRAINDICATION!
    active_induction_regimen: str = "MMF 2.0g/day + Oral Prednisone" # Candidate for Triple Therapy add-on

@dataclass
class LNEvaluationReport:
    patient_id: str
    isn_rps_staging: str # "Class IV-G (A/C) + Class V (Diffuse Global Proliferative + Membranous LN)"
    modified_nih_activity_score: int # 0 - 24
    modified_nih_chronicity_score: int # 0 - 12
    nih_indices_interpretation: str
    kdigo_induction_recommendation: List[str]
    renal_response_milestone_status: str # "Partial Renal Response (PRR) Achieved at 6 Months (57.9% UPCR reduction)"
    safety_sentinels: List[str]
    clinical_kdigo_eular_directive: str

class LupusNephritisDecisionEngine:
    """
    Offline clinical engine for ISN/RPS 2018 lupus nephritis classification,
    Modified NIH Activity & Chronicity scoring, and KDIGO 2024 triple induction titration.
    """

    def calculate_nih_indices(self, d: LupusNephritisTelemetry) -> Tuple[int, int, str]:
        # Activity Index (Max 24): Note x2 weighting for severe necrotizing lesions
        act_score = (
            d.nih_endocapillary_hypercellularity +
            (d.nih_neutrophils_karyorrhexis * 2) +
            (d.nih_fibrinoid_necrosis * 2) +
            (d.nih_cellular_crescents * 2) +
            d.nih_hyaline_deposits_wire_loops +
            d.nih_interstitial_inflammation
        )

        # Chronicity Index (Max 12)
        chron_score = (
            d.nih_glomerulosclerosis +
            d.nih_fibrous_crescents +
            d.nih_tubular_atrophy +
            d.nih_interstitial_fibrosis
        )

        if act_score >= 12:
            act_interp = f"HIGH HISTOLOGIC ACTIVITY ({act_score}/24) -> Aggressive reversible necrotizing/crescentic inflammation"
        elif act_score >= 6:
            act_interp = f"MODERATE HISTOLOGIC ACTIVITY ({act_score}/24)"
        else:
            act_interp = f"LOW HISTOLOGIC ACTIVITY ({act_score}/24)"

        if chron_score >= 6:
            chron_interp = f"ADVANCED CHRONICITY ({chron_score}/12) -> Significant irreversible scarring"
        elif chron_score >= 3:
            chron_interp = f"MODERATE CHRONICITY ({chron_score}/12)"
        else:
            chron_interp = f"LOW CHRONICITY ({chron_score}/12) -> High nephron reversibility"

        summary = f"{act_interp}; {chron_interp}."
        return act_score, chron_score, summary

    def determine_isn_rps_stage(self, d: LupusNephritisTelemetry, act_score: int, chron_score: int) -> str:
        ac_suffix = ""
        if act_score > 0 and chron_score > 0:
            ac_suffix = " (A/C)"
        elif act_score > 0:
            ac_suffix = " (A)"
        elif chron_score > 0:
            ac_suffix = " (C)"

        overlap = " + Class V (Membranous Overlap)" if d.coexisting_class_v_membranous else ""
        return f"{d.primary_histologic_class}{ac_suffix}{overlap}"

    def audit_renal_response(self, d: LupusNephritisTelemetry) -> str:
        pct_reduction = ((d.baseline_upcr_g_g - d.current_upcr_g_g) / max(d.baseline_upcr_g_g, 0.1)) * 100.0
        egfr_stable = d.current_egfr_ml_min >= (d.baseline_egfr_ml_min * 0.85)

        if d.months_on_induction_therapy <= 3:
            return f"Month 3 Audit: {pct_reduction:.1f}% UPCR reduction (Target >= 25%). eGFR {'Stable' if egfr_stable else 'Declining'}."
        elif d.months_on_induction_therapy <= 6:
            if pct_reduction >= 50.0 and egfr_stable:
                return f"✅ PARTIAL RENAL RESPONSE (PRR) ACHIEVED at 6 Months ({pct_reduction:.1f}% UPCR reduction to {d.current_upcr_g_g:.2f} g/g with stable eGFR)."
            else:
                return f"⚠️ SUBOPTIMAL 6-MONTH RESPONSE ({pct_reduction:.1f}% UPCR reduction, target >= 50%). Consider regimen escalation / repeat biopsy."
        else: # 12 Months
            if d.current_upcr_g_g < 0.5 and egfr_stable:
                return f"🎉 COMPLETE RENAL RESPONSE (CRR) ACHIEVED at 12 Months (UPCR {d.current_upcr_g_g:.2f} g/g < 0.5 g/g target with preserved eGFR)."
            elif pct_reduction >= 50.0 and egfr_stable:
                return f"Partial Renal Response maintained (UPCR {d.current_upcr_g_g:.2f} g/g)."
            else:
                return f"🚨 TREATMENT REFRACTORY LUPUS NEPHRITIS at {d.months_on_induction_therapy} Months (UPCR {d.current_upcr_g_g:.2f} g/g). Indication for second-line rescue."

    def generate_kdigo_induction_plan(self, stage: str, act_score: int, d: LupusNephritisTelemetry) -> Tuple[List[str], List[str]]:
        plan = []
        sentinels = []

        is_proliferative = any(c in stage for c in ["Class III", "Class IV"])
        is_pure_membranous = "Class V" in stage and not is_proliferative

        # Hydroxychloroquine Safety Sentinel
        if not d.active_hydroxychloroquine:
            sentinels.append("🚨 MANDATORY HYDROXYCHLOROQUINE (HCQ) SENTINEL: HCQ (target dose <= 5 mg/kg/day of real weight) is the fundamental cornerstone of SLE management, proven to prevent renal flares, reduce ESKD progression, and lower overall mortality. STAT INITIATE HCQ!")

        # Calcineurin Inhibitor / Voclosporin Monitoring Sentinel
        if "Voclosporin" in d.active_induction_regimen or "Tacrolimus" in d.active_induction_regimen:
            egfr_drop_pct = ((d.baseline_egfr_ml_min - d.current_egfr_ml_min) / max(d.baseline_egfr_ml_min, 1.0)) * 100.0
            if egfr_drop_pct >= 20.0:
                sentinels.append(f"CNI NEPHROTOXICITY ALERT: eGFR has declined {egfr_drop_pct:.1f}% on calcineurin inhibitor. Reduce Voclosporin / hold until eGFR stabilizes to within 10-15% of baseline.")

        if is_proliferative:
            plan.append("1. FIRST-LINE INDUCTION (KDIGO 2024 / EULAR 2023): Targeted Triple Immunosuppressive Therapy:")
            plan.append("   • OPTION A (TRIPLE THERAPY WITH NOVEL CNI): Voclosporin 23.7 mg PO BID + Mycophenolate Mofetil (MMF 1.0g BID) + Rapidly tapering Glucocorticoids (Prednisone 0.5 mg/kg/day tapering to <= 5 mg/day by Week 24).")
            plan.append("   • OPTION B (TARGETED B-CELL BIOLOGIC TRIPLE THERAPY): Belimumab 10 mg/kg IV (Days 0, 14, 28, then q4w) + MMF (1.0-1.5g BID) + Low-Dose Glucocorticoids.")
            plan.append("   • OPTION C (EURO-LUPUS CYCLOPHOSPHAMIDE): IV Cyclophosphamide 500 mg q2w x 6 pulses (total 3.0g), transitioning to maintenance MMF or Azathioprine.")
        elif is_pure_membranous:
            plan.append("1. MEMBRANOUS LUPUS NEPHRITIS (CLASS V) INDUCTION:")
            plan.append("   • MMF (1.0-1.5g BID) + Low-Dose Glucocorticoids.")
            plan.append("   • If nephrotic-range proteinuria persists (UPCR >= 3.0 g/g), add Voclosporin (23.7 mg BID) or Tacrolimus.")
        else:
            plan.append("1. MESANGIAL LN (CLASS I/II): Treat based on extra-renal SLE manifestations.")

        # Nephroprotective Adjuncts
        plan.append("2. ADJUNCTIVE NEPHROPROTECTION: Enforce maximum tolerated ACEi / ARB therapy (Target SBP < 120 mmHg) + SGLT2 inhibitor (Dapagliflozin/Empagliflozin) for persistent proteinuria.")

        return plan, sentinels

    def evaluate_case(self, data: LupusNephritisTelemetry) -> LNEvaluationReport:
        act_score, chron_score, indices_interp = self.calculate_nih_indices(data)
        stage_str = self.determine_isn_rps_stage(data, act_score, chron_score)
        resp_status = self.audit_renal_response(data)
        induction_plan, sentinels = self.generate_kdigo_induction_plan(stage_str, act_score, data)

        directives = []
        directives.append(f"STAGING: {stage_str}.")
        directives.append(f"NIH INDICES: Activity {act_score}/24, Chronicity {chron_score}/12.")
        directives.append(f"RESPONSE: {resp_status}")

        return LNEvaluationReport(
            patient_id=data.patient_id,
            isn_rps_staging=stage_str,
            modified_nih_activity_score=act_score,
            modified_nih_chronicity_score=chron_score,
            nih_indices_interpretation=indices_interp,
            kdigo_induction_recommendation=induction_plan,
            renal_response_milestone_status=resp_status,
            safety_sentinels=sentinels,
            clinical_kdigo_eular_directive=" ".join(directives)
        )

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

    print("=" * 80)
    print("OpenPHR Clinical Nephrology Lupus Nephritis ISN/RPS 2018 & Voclosporin Engine")
    print("=" * 80)

    # Test Case 1: 32-year-old female with SLE, biopsy showing Class IV-G + V Lupus Nephritis.
    # Modified NIH Activity: 11/24 (High), Chronicity: 3/12 (Low-Moderate).
    # Baseline UPCR 3.80 g/g -> Current UPCR 1.60 g/g at 6 months (57.9% reduction = PRR!).
    # Not on HCQ -> 🚨 STAT MANDATORY HYDROXYCHLOROQUINE SENTINEL!
    # Triage: Triple Therapy (MMF + Voclosporin or Belimumab) + HCQ + ACEi/SGLT2i!
    ln1 = LupusNephritisTelemetry(
        patient_id="NEPH-LN-3301",
        age_years=32.0,
        baseline_egfr_ml_min=85.0,
        current_egfr_ml_min=78.0,
        baseline_upcr_g_g=3.80,
        current_upcr_g_g=1.60,
        months_on_induction_therapy=6,
        anti_dsdna_titers_iu_ml=180.0,
        serum_c3_mg_dl=54.0,
        serum_c4_mg_dl=8.0,
        primary_histologic_class="Class IV-G",
        coexisting_class_v_membranous=True,
        nih_endocapillary_hypercellularity=2,
        nih_neutrophils_karyorrhexis=1,
        nih_fibrinoid_necrosis=1,
        nih_cellular_crescents=2,
        nih_hyaline_deposits_wire_loops=2,
        nih_interstitial_inflammation=1,
        nih_glomerulosclerosis=1,
        nih_fibrous_crescents=0,
        nih_tubular_atrophy=1,
        nih_interstitial_fibrosis=1,
        active_hydroxychloroquine=False
    )

    rep1 = engine.evaluate_case(ln1)

    print(f"\n[Patient {rep1.patient_id} - Lupus Nephritis Assessment]")
    print(f"ISN/RPS 2018 Stage: {rep1.isn_rps_staging}")
    print(f"Modified NIH Activity Index: {rep1.modified_nih_activity_score}/24")
    print(f"Modified NIH Chronicity Index: {rep1.modified_nih_chronicity_score}/12")
    print(f"Histopathology Summary: {rep1.nih_indices_interpretation}")
    print(f"\nRenal Response Milestone: {rep1.renal_response_milestone_status}")
    print("\nKDIGO 2024 Induction Recommendations:")
    for r in rep1.kdigo_induction_recommendation:
        print(f"  {r}")
    if rep1.safety_sentinels:
        print("\nSafety Sentinels:")
        for s in rep1.safety_sentinels:
            print(f"  🚨 {s}")
    print(f"\nKDIGO / EULAR Consensus Directive:\n{rep1.clinical_kdigo_eular_directive}")