Cookbook 320: Offline Clinical Interventional Cardiology Coronary Bifurcation Medina & DK-Crush Engine

"""
Cookbook 320: Offline Interventional Cardiology Coronary Bifurcation & DK-Crush 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 BifurcationLesionTelemetry:
    patient_id: str
    age_years: float
    is_left_main_bifurcation: bool = True # True = LM-LAD-LCx; False = LAD-Diag or LCx-OM
    bifurcation_location_name: str = "Distal Left Main (LM/LAD/LCx)"
    # Medina Binary Parameters (True if diameter stenosis >= 50%)
    medina_proximal_main_vessel: int = 1 # 0 or 1
    medina_distal_main_vessel: int = 1 # 0 or 1
    medina_side_branch_ostium: int = 1 # 0 or 1
    # Quantitative Coronary Angiography (QCA) Telemetry
    side_branch_reference_diameter_mm: float = 3.0 # mm (Must be >= 2.5 mm for 2-stent)
    side_branch_lesion_length_mm: float = 14.0 # mm (>= 10 mm = Major criterion)
    side_branch_diameter_stenosis_percent: float = 85.0 # % (>= 70% = Major criterion)
    main_vessel_reference_diameter_mm: float = 4.0 # mm
    main_vessel_lesion_length_mm: float = 28.0 # mm (>= 25 mm = Minor criterion)
    bifurcation_angle_degrees: float = 78.0 # degrees (< 45 or > 70 = Minor criterion)
    moderate_or_severe_calcification: bool = True # Minor criterion
    multiple_bifurcation_lesions_present: bool = False
    intracoronary_thrombus_present: bool = False
    # Intravascular Ultrasound (IVUS) Post-Stent Telemetry
    ivus_main_vessel_polygon_msa_mm2: float = 8.4 # Target >= 7.0-8.0 mm2 for LM
    ivus_lad_ostial_msa_mm2: float = 6.8 # Target >= 6.0 mm2
    ivus_lcx_side_branch_ostial_msa_mm2: float = 4.6 # Target >= 4.0 mm2

@dataclass
class BifurcationEvaluationReport:
    patient_id: str
    medina_classification_string: str # e.g. "Medina (1,1,1) - True Bifurcation"
    definition_ii_complexity_tier: str # "Complex Bifurcation (DEFINITION II Positive)", "Simple Bifurcation (DEFINITION II Negative)"
    recommended_stenting_strategy: str # "Upfront 2-Stent DK-Crush Technique", "Provisional 1-Stent Strategy with POT"
    procedural_execution_steps: List[str]
    ivus_optimization_audit: List[str]
    safety_sentinels: List[str]
    clinical_ebc_scai_directive: str

class CoronaryBifurcationDecisionEngine:
    """
    Offline clinical engine for Medina bifurcation lesion classification,
    DEFINITION II complexity risk scoring, stenting technique selection,
    and post-PCI IVUS optimization auditing.
    """

    def classify_medina(self, p: int, d: int, s: int) -> Tuple[str, bool]:
        medina_str = f"Medina ({p},{d},{s})"
        # True bifurcation = (1,1,1), (1,0,1), (0,1,1)
        is_true = (s == 1) and (p == 1 or d == 1)
        label = f"{medina_str} - {'True Bifurcation' if is_true else 'Non-True / Simple Bifurcation'}"
        return label, is_true

    def evaluate_definition_ii_complexity(self, d: BifurcationLesionTelemetry) -> Tuple[str, List[str], List[str]]:
        major_criteria = []
        minor_criteria = []

        # Major Criteria: SB lesion length >= 10 mm AND SB diameter stenosis >= 70%
        if d.side_branch_diameter_stenosis_percent >= 70.0 and d.side_branch_lesion_length_mm >= 10.0:
            major_criteria.append(f"Major Criterion Met: Side Branch Stenosis ({d.side_branch_diameter_stenosis_percent:.0f}%) >= 70% AND Lesion Length ({d.side_branch_lesion_length_mm} mm) >= 10 mm.")

        # Minor Criteria
        if d.moderate_or_severe_calcification:
            minor_criteria.append("Minor Criterion: Moderate-to-severe vessel calcification.")
        if d.multiple_bifurcation_lesions_present:
            minor_criteria.append("Minor Criterion: Multiple bifurcation lesions.")
        if d.bifurcation_angle_degrees < 45.0 or d.bifurcation_angle_degrees > 70.0:
            minor_criteria.append(f"Minor Criterion: Unfavorable bifurcation angle ({d.bifurcation_angle_degrees:.0f} deg).")
        if d.main_vessel_reference_diameter_mm < 2.5:
            minor_criteria.append(f"Minor Criterion: Small main vessel RVD ({d.main_vessel_reference_diameter_mm} mm < 2.5 mm).")
        if d.main_vessel_lesion_length_mm >= 25.0:
            minor_criteria.append(f"Minor Criterion: Main vessel lesion length ({d.main_vessel_lesion_length_mm} mm >= 25 mm).")
        if d.intracoronary_thrombus_present:
            minor_criteria.append("Minor Criterion: Intracoronary thrombus.")

        # DEFINITION II Positive: 1 Major OR (>= 2 Minor for borderline)
        if len(major_criteria) >= 1 and (len(minor_criteria) >= 2 or d.is_left_main_bifurcation):
            tier = "Complex Bifurcation (DEFINITION II Positive - Upfront 2-Stent Indicated)"
        elif len(major_criteria) >= 1:
            tier = "Moderate-to-High Complexity Bifurcation (DEFINITION II Major Met)"
        else:
            tier = "Simple Bifurcation (DEFINITION II Negative - Provisional Preferred)"

        return tier, major_criteria, minor_criteria

    def determine_stenting_strategy(self, tier: str, is_true: bool, d: BifurcationLesionTelemetry) -> Tuple[str, List[str]]:
        steps = []

        if "Complex" in tier or (is_true and d.side_branch_lesion_length_mm >= 10.0 and d.side_branch_reference_diameter_mm >= 2.5):
            strategy = "Upfront 2-Stent Double-Kissing Crush (DK-Crush) Strategy"
            steps.append("1. STEP 1 (PREPARATION): Wire both MV and SB; perform aggressive non-compliant pre-dilatation of both branches (Consider rotational/orbital atherectomy or intravascular lithotripsy if severe calcium).")
            steps.append(f"2. STEP 2 (SB STENTING): Advance DES into SB ({d.side_branch_reference_diameter_mm} mm RVD) with 1-2 mm protrusion into MV. Park an uninflated balloon (1:1 sized) in MV.")
            steps.append("3. STEP 3 (FIRST BALLOON CRUSH): Deploy SB DES at nominal pressure. Remove SB wire and stent balloon. Inflate MV balloon at 12-16 atm to crush the protruding SB stent struts flat against the MV wall.")
            steps.append("4. STEP 4 (FIRST KISSING INFLATION - FKI): Re-wire SB through non-distal/middle strut. Inflate NC balloons simultaneously in MV and SB (First Kiss) to clear ostial struts.")
            steps.append("5. STEP 5 (MV STENTING): Deploy MV DES across the crushed SB ostium at nominal pressure.")
            steps.append("6. STEP 6 (PROXIMAL OPTIMIZATION TECHNIQUE - POT): Perform POT in proximal MV stent segment using short NC balloon sized 1:1 to proximal MV reference.")
            steps.append("7. STEP 7 (SECOND KISSING INFLATION - SKI): Re-wire SB through middle/non-distal strut. Perform Second Kissing Balloon Inflation with NC balloons at high pressure.")
            steps.append("8. STEP 8 (FINAL RE-POT): Perform Final re-POT in proximal MV to eliminate kissing balloon-induced elliptical stent distortion and guarantee circular apposition.")
        else:
            strategy = "Provisional 1-Stent Strategy with Mandatory POT"
            steps.append("1. STEP 1 (PREPARATION & WIRING): Wire both MV and SB; pre-dilate main vessel (pre-dilate SB only if severe calcification or compromised TIMI flow).")
            steps.append("2. STEP 2 (MV STENTING): Deploy DES in main vessel across side branch with jailed wire in SB.")
            steps.append("3. STEP 3 (MANDATORY POT): Perform immediate Proximal Optimization Technique (POT) with short NC balloon sized 1:1 to proximal MV.")
            steps.append("4. STEP 4 (SIDE BRANCH ASSESSMENT): Evaluate SB flow; if TIMI 3 flow, no severe ostial dissection, and FFR > 0.80, finish case without SB intervention.")
            steps.append("5. STEP 5 (BAILOUT 2ND STENT IF NEEDED): If SB TIMI < 3, severe dissection, or persistent ischemia, re-wire SB and deploy second stent via T-and-Protrusion (TAP) or Culotte technique.")

        return strategy, steps

    def audit_ivus_expansion(self, d: BifurcationLesionTelemetry) -> List[str]:
        audit = []
        if d.is_left_main_bifurcation:
            if d.ivus_main_vessel_polygon_msa_mm2 >= 8.0:
                audit.append(f"✅ LM Polygonal Confluence MSA ({d.ivus_main_vessel_polygon_msa_mm2} mm2) meets target (>= 8.0 mm2).")
            else:
                audit.append(f"⚠️ UNDER-EXPANSION: LM Polygonal MSA ({d.ivus_main_vessel_polygon_msa_mm2} mm2) is below target (8.0 mm2) -> Perform high-pressure post-dilatation with larger NC balloon.")

            if d.ivus_lad_ostial_msa_mm2 >= 6.0:
                audit.append(f"✅ LAD Ostial MSA ({d.ivus_lad_ostial_msa_mm2} mm2) meets target (>= 6.0 mm2).")
            else:
                audit.append(f"⚠️ UNDER-EXPANSION: LAD Ostial MSA ({d.ivus_lad_ostial_msa_mm2} mm2) < 6.0 mm2.")

            if d.ivus_lcx_side_branch_ostial_msa_mm2 >= 4.0:
                audit.append(f"✅ LCx Ostial MSA ({d.ivus_lcx_side_branch_ostial_msa_mm2} mm2) meets target (>= 4.0 mm2).")
            else:
                audit.append(f"⚠️ UNDER-EXPANSION: LCx Ostial MSA ({d.ivus_lcx_side_branch_ostial_msa_mm2} mm2) < 4.0 mm2.")
        else:
            if d.ivus_lcx_side_branch_ostial_msa_mm2 >= 3.5:
                audit.append(f"✅ Side Branch Ostial MSA ({d.ivus_lcx_side_branch_ostial_msa_mm2} mm2) meets target (>= 3.5 mm2).")
            else:
                audit.append(f"⚠️ UNDER-EXPANSION: Side Branch MSA ({d.ivus_lcx_side_branch_ostial_msa_mm2} mm2) < 3.5 mm2.")

        return audit

    def evaluate_case(self, data: BifurcationLesionTelemetry) -> BifurcationEvaluationReport:
        medina_label, is_true = self.classify_medina(data.medina_proximal_main_vessel, data.medina_distal_main_vessel, data.medina_side_branch_ostium)
        complexity_tier, major, minor = self.evaluate_definition_ii_complexity(data)
        strategy, steps = self.determine_stenting_strategy(complexity_tier, is_true, data)
        ivus_audit = self.audit_ivus_expansion(data)

        sentinels = []
        if data.is_left_main_bifurcation and "Complex" in complexity_tier:
            sentinels.append("HIGH-RISK LEFT MAIN COMPLEX BIFURCATION: DKCRUSH-V trial demonstrates significant 3-year TLF reduction with DK-Crush over Provisional stenting (Risk difference 7.9% vs 14.8%). Upfront 2-stent strategy strongly recommended.")
        if data.side_branch_reference_diameter_mm < 2.5:
            sentinels.append(f"SMALL SIDE BRANCH WARNING (RVD {data.side_branch_reference_diameter_mm} mm < 2.5 mm): 2-stent techniques carry elevated in-stent restenosis risk in small vessels; consider Provisional stenting.")

        directives = []
        directives.append(f"CLASSIFICATION: {medina_label}.")
        directives.append(f"COMPLEXITY: {complexity_tier}.")
        directives.append(f"RECOMMENDED STRATEGY: {strategy}.")
        directives.append("IMAGING GUIDANCE: Mandatory pre- and post-PCI IVUS optimization.")

        return BifurcationEvaluationReport(
            patient_id=data.patient_id,
            medina_classification_string=medina_label,
            definition_ii_complexity_tier=complexity_tier,
            recommended_stenting_strategy=strategy,
            procedural_execution_steps=steps,
            ivus_optimization_audit=ivus_audit,
            safety_sentinels=sentinels,
            clinical_ebc_scai_directive=" ".join(directives)
        )

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

    print("=" * 80)
    print("OpenPHR Clinical Interventional Cardiology Bifurcation & DK-Crush Engine")
    print("=" * 80)

    # Test Case 1: 64-year-old male with Distal Left Main True Bifurcation (Medina 1,1,1)
    # QCA: LM (4.0 mm RVD), LAD (3.5 mm RVD), LCx (3.0 mm RVD) with LCx lesion length = 14 mm (>= 10 mm) and stenosis = 85% (>= 70%)
    # Minor criteria: Heavy calcification + Angle 78 deg -> DEFINITION II Positive Complex Bifurcation!
    # Triage: Upfront 2-Stent DK-Crush (8-Step Protocol with FKI, POT, SKI, Final re-POT) + IVUS Optimization!
    bif1 = BifurcationLesionTelemetry(
        patient_id="CATH-BIF-9104",
        age_years=64.0,
        is_left_main_bifurcation=True,
        bifurcation_location_name="Distal Left Main (LM/LAD/LCx)",
        medina_proximal_main_vessel=1,
        medina_distal_main_vessel=1,
        medina_side_branch_ostium=1,
        side_branch_reference_diameter_mm=3.0,
        side_branch_lesion_length_mm=14.0,
        side_branch_diameter_stenosis_percent=85.0,
        main_vessel_reference_diameter_mm=4.0,
        main_vessel_lesion_length_mm=28.0,
        bifurcation_angle_degrees=78.0,
        moderate_or_severe_calcification=True,
        ivus_main_vessel_polygon_msa_mm2=8.4,
        ivus_lad_ostial_msa_mm2=6.8,
        ivus_lcx_side_branch_ostial_msa_mm2=4.6
    )

    rep1 = engine.evaluate_case(bif1)

    print(f"\n[Patient {rep1.patient_id} - Cath Lab Assessment]")
    print(f"Medina Classification: {rep1.medina_classification_string}")
    print(f"Complexity Tier: {rep1.definition_ii_complexity_tier}")
    print(f"Recommended Strategy: {rep1.recommended_stenting_strategy}")
    print("\nProcedural Steps:")
    for step in rep1.procedural_execution_steps:
        print(f"  {step}")
    print("\nIVUS Expansion Audit:")
    for ivus in rep1.ivus_optimization_audit:
        print(f"  {ivus}")
    print("\nSafety Sentinels:")
    for s in rep1.safety_sentinel_alerts if hasattr(rep1, 'safety_sentinel_alerts') else rep1.safety_sentinels:
        print(f"  • {s}")
    print(f"\nEBC / SCAI Consensus Directive:\n{rep1.clinical_ebc_scai_directive}")

    # Test Case 2: LAD / Diagonal Simple Bifurcation (Medina 1,1,0) -> Provisional 1-Stent Strategy!
    bif2 = BifurcationLesionTelemetry(
        patient_id="CATH-BIF-1042",
        age_years=56.0,
        is_left_main_bifurcation=False,
        bifurcation_location_name="Mid-LAD / First Diagonal (D1)",
        medina_proximal_main_vessel=1,
        medina_distal_main_vessel=1,
        medina_side_branch_ostium=0,
        side_branch_reference_diameter_mm=2.5,
        side_branch_lesion_length_mm=3.0,
        side_branch_diameter_stenosis_percent=30.0,
        main_vessel_reference_diameter_mm=3.25,
        main_vessel_lesion_length_mm=18.0,
        bifurcation_angle_degrees=55.0,
        moderate_or_severe_calcification=False
    )

    rep2 = engine.evaluate_case(bif2)
    print(f"\n[Patient {rep2.patient_id}] - Strategy: {rep2.recommended_stenting_strategy}")