empathy-framework 3.2.3__py3-none-any.whl → 3.8.2__py3-none-any.whl

empathy_healthcare_plugin/monitors/clinical_protocol_monitor.py

@@ -0,0 +1,315 @@
+"""Clinical Protocol Monitor (Level 4)
+
+Main monitoring system that combines protocol checking and trajectory analysis.
+
+This is the healthcare equivalent of the Advanced Debugging Wizard.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import logging
+from datetime import datetime
+from typing import Any
+
+from .monitoring.protocol_checker import ProtocolChecker, ProtocolCheckResult
+from .monitoring.protocol_loader import ClinicalProtocol, ProtocolLoader
+from .monitoring.sensor_parsers import normalize_vitals, parse_sensor_data
+from .monitoring.trajectory_analyzer import TrajectoryAnalyzer, TrajectoryPrediction
+
+logger = logging.getLogger(__name__)
+
+
+class ClinicalProtocolMonitor:
+    """Clinical Protocol Monitoring System.
+
+    Monitors patient sensor data against clinical protocols using
+    the same systematic approach as linting configuration:
+
+    1. Load protocol (the "config")
+    2. Parse sensor data (the "code state")
+    3. Check compliance (run the "linter")
+    4. Predict trajectory (Level 4 - anticipatory)
+    5. Generate alerts and documentation
+    """
+
+    def __init__(self, protocol_directory: str | None = None):
+        self.protocol_loader = ProtocolLoader(protocol_directory)
+        self.protocol_checker = ProtocolChecker()
+        self.trajectory_analyzer = TrajectoryAnalyzer()
+
+        # Active protocols per patient
+        self.active_protocols: dict[str, ClinicalProtocol] = {}
+
+        # Historical data per patient
+        self.patient_history: dict[str, list[dict[str, Any]]] = {}
+
+    def load_protocol(
+        self,
+        patient_id: str,
+        protocol_name: str,
+        patient_context: dict[str, Any] | None = None,
+    ) -> ClinicalProtocol:
+        """Load and activate protocol for patient.
+
+        Args:
+            patient_id: Patient identifier
+            protocol_name: Name of protocol to load
+            patient_context: Additional patient context
+
+        Returns:
+            Loaded protocol
+
+        Example:
+            >>> monitor = ClinicalProtocolMonitor()
+            >>> protocol = monitor.load_protocol(
+            ...     patient_id="12345",
+            ...     protocol_name="sepsis",
+            ...     patient_context={"age": 65, "post_op_day": 2}
+            ... )
+
+        """
+        protocol = self.protocol_loader.load_protocol(protocol_name)
+        self.active_protocols[patient_id] = protocol
+
+        logger.info(f"Loaded {protocol.name} v{protocol.version} for patient {patient_id}")
+
+        return protocol
+
+    async def analyze(self, context: dict[str, Any]) -> dict[str, Any]:
+        """Main analysis method - unified interface.
+
+        Context expects:
+            - patient_id: Patient identifier
+            - sensor_data: Current sensor readings (JSON string or dict)
+            - sensor_format: "simple_json" or "fhir" (default: simple_json)
+            - protocol_name: Protocol to check (optional if already loaded)
+            - intervention_status: Status of interventions (optional)
+
+        Returns:
+            Comprehensive analysis with alerts, predictions, recommendations
+
+        """
+        patient_id = context.get("patient_id")
+        sensor_data = context.get("sensor_data")
+        sensor_format = context.get("sensor_format", "simple_json")
+        protocol_name = context.get("protocol_name")
+        intervention_status = context.get("intervention_status", {})
+
+        if not patient_id:
+            return {"error": "patient_id required"}
+
+        if not sensor_data:
+            return {"error": "sensor_data required"}
+
+        # Load protocol if not already active
+        if patient_id not in self.active_protocols and protocol_name:
+            self.load_protocol(patient_id, protocol_name)
+
+        if patient_id not in self.active_protocols:
+            return {"error": f"No active protocol for patient {patient_id}"}
+
+        protocol = self.active_protocols[patient_id]
+
+        # Parse sensor data
+        if isinstance(sensor_data, str):
+            readings = parse_sensor_data(sensor_data, sensor_format)
+            normalized_data = normalize_vitals(readings)
+        else:
+            normalized_data = sensor_data
+
+        # Store in history
+        if patient_id not in self.patient_history:
+            self.patient_history[patient_id] = []
+
+        historical_entry = {"timestamp": datetime.now().isoformat(), **normalized_data}
+        self.patient_history[patient_id].append(historical_entry)
+
+        # Keep last 24 hours only
+        if len(self.patient_history[patient_id]) > 144:  # 24hrs at 10min intervals
+            self.patient_history[patient_id] = self.patient_history[patient_id][-144:]
+
+        # Phase 1: Check protocol compliance
+        compliance_result = self.protocol_checker.check_compliance(
+            protocol,
+            normalized_data,
+            intervention_status,
+        )
+
+        # Phase 2: Analyze trajectory (Level 4)
+        trajectory_prediction = self.trajectory_analyzer.analyze_trajectory(
+            normalized_data,
+            self.patient_history[patient_id][:-1],  # Exclude current reading
+        )
+
+        # Phase 3: Generate alerts
+        alerts = self._generate_alerts(compliance_result, trajectory_prediction)
+
+        # Phase 4: Generate recommendations
+        recommendations = self._generate_recommendations(
+            compliance_result,
+            trajectory_prediction,
+            protocol,
+        )
+
+        # Phase 5: Generate predictions (Level 4)
+        predictions = self._generate_predictions(trajectory_prediction, compliance_result)
+
+        return {
+            "patient_id": patient_id,
+            "protocol": {"name": protocol.name, "version": protocol.version},
+            "current_vitals": normalized_data,
+            # Protocol compliance (like linter output)
+            "protocol_compliance": {
+                "activated": compliance_result.protocol_activated,
+                "score": compliance_result.activation_score,
+                "threshold": compliance_result.threshold,
+                "alert_level": compliance_result.alert_level,
+                "deviations": [
+                    {
+                        "action": d.intervention.action,
+                        "status": d.status.value,
+                        "due": d.intervention.timing,
+                        "reasoning": d.reasoning,
+                    }
+                    for d in compliance_result.deviations
+                ],
+                "compliant": compliance_result.compliant_items,
+            },
+            # Trajectory analysis (Level 4)
+            "trajectory": {
+                "state": trajectory_prediction.trajectory_state,
+                "estimated_time_to_critical": trajectory_prediction.estimated_time_to_critical,
+                "trends": [
+                    {
+                        "parameter": t.parameter,
+                        "current": t.current_value,
+                        "change": t.change,
+                        "direction": t.direction,
+                        "concerning": t.concerning,
+                        "reasoning": t.reasoning,
+                    }
+                    for t in trajectory_prediction.vital_trends
+                ],
+                "assessment": trajectory_prediction.overall_assessment,
+                "confidence": trajectory_prediction.confidence,
+            },
+            # Alerts
+            "alerts": alerts,
+            # Standard wizard outputs
+            "predictions": predictions,
+            "recommendations": recommendations,
+            "confidence": trajectory_prediction.confidence,
+        }
+
+    def _generate_alerts(
+        self,
+        compliance: ProtocolCheckResult,
+        trajectory: TrajectoryPrediction,
+    ) -> list[dict[str, Any]]:
+        """Generate alerts based on compliance and trajectory"""
+        alerts = []
+
+        # Protocol activation alert
+        if compliance.protocol_activated:
+            alerts.append(
+                {
+                    "type": "protocol_activated",
+                    "severity": "high",
+                    "message": compliance.recommendation,
+                },
+            )
+
+        # Overdue intervention alerts
+        overdue = [d for d in compliance.deviations if d.status.value == "overdue"]
+        if overdue:
+            alerts.append(
+                {
+                    "type": "intervention_overdue",
+                    "severity": "critical",
+                    "message": f"{len(overdue)} interventions overdue",
+                    "details": [d.intervention.action for d in overdue],
+                },
+            )
+
+        # Trajectory alerts (Level 4 - early warning)
+        if trajectory.trajectory_state == "critical":
+            alerts.append(
+                {
+                    "type": "trajectory_critical",
+                    "severity": "critical",
+                    "message": trajectory.overall_assessment,
+                },
+            )
+        elif trajectory.trajectory_state == "concerning":
+            alerts.append(
+                {
+                    "type": "trajectory_concerning",
+                    "severity": "warning",
+                    "message": trajectory.overall_assessment,
+                    "time_to_critical": trajectory.estimated_time_to_critical,
+                },
+            )
+
+        return alerts
+
+    def _generate_recommendations(
+        self,
+        compliance: ProtocolCheckResult,
+        trajectory: TrajectoryPrediction,
+        protocol: ClinicalProtocol,
+    ) -> list[str]:
+        """Generate actionable recommendations"""
+        recommendations = []
+
+        # From protocol compliance
+        if compliance.recommendation:
+            recommendations.append(compliance.recommendation)
+
+        # From trajectory analysis
+        recommendations.extend(trajectory.recommendations)
+
+        # From protocol-specific guidance
+        if compliance.protocol_activated:
+            recommendations.append(
+                f"Follow {protocol.name} monitoring frequency: {protocol.monitoring_frequency}",
+            )
+
+        return list(set(recommendations))  # Deduplicate
+
+    def _generate_predictions(
+        self,
+        trajectory: TrajectoryPrediction,
+        compliance: ProtocolCheckResult,
+    ) -> list[dict[str, Any]]:
+        """Generate Level 4 predictions"""
+        predictions = []
+
+        # Trajectory-based predictions
+        if trajectory.trajectory_state in ["concerning", "critical"]:
+            predictions.append(
+                {
+                    "type": "patient_deterioration",
+                    "severity": "high" if trajectory.trajectory_state == "critical" else "medium",
+                    "description": trajectory.overall_assessment,
+                    "time_horizon": trajectory.estimated_time_to_critical,
+                    "confidence": trajectory.confidence,
+                    "prevention_steps": trajectory.recommendations,
+                },
+            )
+
+        # Compliance-based predictions
+        if compliance.protocol_activated and compliance.deviations:
+            predictions.append(
+                {
+                    "type": "protocol_deviation_risk",
+                    "severity": "high",
+                    "description": "In our experience, protocol deviations correlate with adverse outcomes",
+                    "prevention_steps": [
+                        "Complete pending interventions",
+                        "Document deviations and rationale",
+                    ],
+                },
+            )
+
+        return predictions

empathy_healthcare_plugin/monitors/monitoring/__init__.py

@@ -0,0 +1,44 @@
+"""Clinical Monitoring Components
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from .protocol_checker import (
+                               ComplianceStatus,
+                               ProtocolChecker,
+                               ProtocolCheckResult,
+                               ProtocolDeviation,
+)
+from .protocol_loader import (
+                               ClinicalProtocol,
+                               ProtocolCriterion,
+                               ProtocolIntervention,
+                               ProtocolLoader,
+                               load_protocol,
+)
+from .sensor_parsers import VitalSignReading, VitalSignType, normalize_vitals, parse_sensor_data
+from .trajectory_analyzer import TrajectoryAnalyzer, TrajectoryPrediction, VitalTrend
+
+__all__ = [
+    # Protocol Loading
+    "ClinicalProtocol",
+    "ComplianceStatus",
+    "ProtocolCheckResult",
+    # Protocol Checking
+    "ProtocolChecker",
+    "ProtocolCriterion",
+    "ProtocolDeviation",
+    "ProtocolIntervention",
+    "ProtocolLoader",
+    # Trajectory Analysis
+    "TrajectoryAnalyzer",
+    "TrajectoryPrediction",
+    # Sensor Parsing
+    "VitalSignReading",
+    "VitalSignType",
+    "VitalTrend",
+    "load_protocol",
+    "normalize_vitals",
+    "parse_sensor_data",
+]

empathy_healthcare_plugin/monitors/monitoring/protocol_checker.py

@@ -0,0 +1,300 @@
+"""Protocol Checker
+
+Checks patient sensor data against clinical protocol criteria.
+
+This is the "linter" for healthcare - runs the protocol rules against current state.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from .protocol_loader import ClinicalProtocol, ProtocolCriterion, ProtocolIntervention
+
+
+class ComplianceStatus(Enum):
+    """Status of protocol compliance"""
+
+    COMPLIANT = "compliant"
+    DEVIATION = "deviation"
+    OVERDUE = "overdue"
+    PENDING = "pending"
+    COMPLETED = "completed"
+
+
+@dataclass
+class CriterionResult:
+    """Result of evaluating a single criterion"""
+
+    criterion: ProtocolCriterion
+    met: bool
+    actual_value: Any
+    points_awarded: int
+    reasoning: str
+
+
+@dataclass
+class ProtocolDeviation:
+    """A deviation from protocol (like a linting violation)"""
+
+    intervention: ProtocolIntervention
+    status: ComplianceStatus
+    time_activated: datetime | None = None
+    time_due: datetime | None = None
+    time_completed: datetime | None = None
+    overdue_by: str | None = None
+    reasoning: str = ""
+
+
+@dataclass
+class ProtocolCheckResult:
+    """Result of checking patient against protocol.
+
+    This is like the output of running a linter.
+    """
+
+    protocol_activated: bool
+    activation_score: int
+    threshold: int
+    criteria_results: list[CriterionResult]
+    deviations: list[ProtocolDeviation]
+    compliant_items: list[str]
+    alert_level: str  # "NONE", "WARNING", "CRITICAL"
+    recommendation: str
+
+
+class ProtocolChecker:
+    """Checks patient state against clinical protocol.
+
+    This is the "linter engine" for healthcare.
+    """
+
+    def __init__(self):
+        pass
+
+    def check_compliance(
+        self,
+        protocol: ClinicalProtocol,
+        patient_data: dict[str, Any],
+        intervention_status: dict[str, Any] | None = None,
+    ) -> ProtocolCheckResult:
+        """Check if patient data meets protocol criteria.
+
+        Args:
+            protocol: Clinical protocol to check against
+            patient_data: Current patient sensor data
+            intervention_status: Status of interventions (if protocol active)
+
+        Returns:
+            ProtocolCheckResult with deviations
+
+        Example:
+            >>> patient = {"systolic_bp": 95, "respiratory_rate": 24, "hr": 110}
+            >>> result = checker.check_compliance(sepsis_protocol, patient)
+            >>> if result.protocol_activated:
+            ...     print(f"ALERT: {result.recommendation}")
+
+        """
+        # Step 1: Evaluate screening criteria
+        criteria_results = []
+        total_points = 0
+
+        for criterion in protocol.screening_criteria:
+            result = self._evaluate_criterion(criterion, patient_data)
+            criteria_results.append(result)
+            if result.met:
+                total_points += result.points_awarded
+
+        # Step 2: Determine if protocol should activate
+        protocol_activated = total_points >= protocol.screening_threshold
+
+        # Step 3: If activated, check intervention compliance
+        deviations = []
+        compliant_items = []
+
+        if protocol_activated and intervention_status:
+            for intervention in protocol.interventions:
+                status = intervention_status.get(intervention.action, {})
+                deviation = self._check_intervention_status(intervention, status)
+
+                if deviation:
+                    deviations.append(deviation)
+                else:
+                    compliant_items.append(intervention.action)
+
+        # Step 4: Determine alert level
+        alert_level = self._determine_alert_level(
+            protocol_activated,
+            deviations,
+            total_points,
+            protocol.screening_threshold,
+        )
+
+        # Step 5: Generate recommendation
+        recommendation = self._generate_recommendation(
+            protocol,
+            protocol_activated,
+            deviations,
+            criteria_results,
+        )
+
+        return ProtocolCheckResult(
+            protocol_activated=protocol_activated,
+            activation_score=total_points,
+            threshold=protocol.screening_threshold,
+            criteria_results=criteria_results,
+            deviations=deviations,
+            compliant_items=compliant_items,
+            alert_level=alert_level,
+            recommendation=recommendation,
+        )
+
+    def _evaluate_criterion(
+        self,
+        criterion: ProtocolCriterion,
+        patient_data: dict[str, Any],
+    ) -> CriterionResult:
+        """Evaluate a single criterion"""
+        actual_value = patient_data.get(criterion.parameter)
+
+        if actual_value is None:
+            return CriterionResult(
+                criterion=criterion,
+                met=False,
+                actual_value=None,
+                points_awarded=0,
+                reasoning=f"{criterion.parameter} not available",
+            )
+
+        # Evaluate condition
+        met = self._evaluate_condition(actual_value, criterion.condition, criterion.value)
+
+        return CriterionResult(
+            criterion=criterion,
+            met=met,
+            actual_value=actual_value,
+            points_awarded=criterion.points if met else 0,
+            reasoning=f"{criterion.parameter}={actual_value} {criterion.condition} {criterion.value}",
+        )
+
+    def _evaluate_condition(self, actual: Any, condition: str, expected: Any) -> bool:
+        """Evaluate a condition (like <=, >=, ==, etc.)"""
+        if condition == "<=":
+            return actual <= expected
+        if condition == ">=":
+            return actual >= expected
+        if condition == "==":
+            return actual == expected
+        if condition == "!=":
+            return actual != expected
+        if condition == "<":
+            return actual < expected
+        if condition == ">":
+            return actual > expected
+        if condition == "altered":
+            # Special case for mental status
+            return actual != "normal" if isinstance(actual, str) else actual < 15
+        return False
+
+    def _check_intervention_status(
+        self,
+        intervention: ProtocolIntervention,
+        status: dict[str, Any],
+    ) -> ProtocolDeviation | None:
+        """Check if intervention has been completed"""
+        completed = status.get("completed", False)
+        _time_completed = status.get("time_completed")
+        time_due = status.get("time_due")
+
+        if completed:
+            return None  # No deviation - intervention done
+
+        # Check if overdue
+        if time_due:
+            if isinstance(time_due, datetime) and datetime.now() > time_due:
+                return ProtocolDeviation(
+                    intervention=intervention,
+                    status=ComplianceStatus.OVERDUE,
+                    time_due=time_due,
+                    overdue_by=str(datetime.now() - time_due),
+                    reasoning=f"{intervention.action} overdue (due: {intervention.timing})",
+                )
+
+        # Pending but not yet overdue
+        return ProtocolDeviation(
+            intervention=intervention,
+            status=ComplianceStatus.PENDING,
+            reasoning=f"{intervention.action} pending (due: {intervention.timing})",
+        )
+
+    def _determine_alert_level(
+        self,
+        protocol_activated: bool,
+        deviations: list[ProtocolDeviation],
+        score: int,
+        threshold: int,
+    ) -> str:
+        """Determine alert level"""
+        if not protocol_activated:
+            return "NONE"
+
+        # Check for overdue critical interventions
+        overdue_count = sum(1 for d in deviations if d.status == ComplianceStatus.OVERDUE)
+
+        if overdue_count > 0:
+            return "CRITICAL"
+
+        # Check for pending interventions
+        pending_count = sum(1 for d in deviations if d.status == ComplianceStatus.PENDING)
+
+        if pending_count > 0:
+            return "WARNING"
+
+        return "NONE"
+
+    def _generate_recommendation(
+        self,
+        protocol: ClinicalProtocol,
+        activated: bool,
+        deviations: list[ProtocolDeviation],
+        criteria_results: list[CriterionResult],
+    ) -> str:
+        """Generate actionable recommendation"""
+        if not activated:
+            met_criteria = [c for c in criteria_results if c.met]
+            if met_criteria:
+                return (
+                    f"Patient meets {len(met_criteria)} of {protocol.screening_threshold} "
+                    f"criteria. Continue monitoring."
+                )
+            return "Patient stable. Continue routine monitoring."
+
+        # Protocol activated
+        if not deviations:
+            return (
+                f"{protocol.name} protocol active. All interventions complete. "
+                f"Continue monitoring per protocol."
+            )
+
+        # Has deviations
+        overdue = [d for d in deviations if d.status == ComplianceStatus.OVERDUE]
+        pending = [d for d in deviations if d.status == ComplianceStatus.PENDING]
+
+        if overdue:
+            return (
+                f"CRITICAL: {len(overdue)} interventions OVERDUE. "
+                f"Immediate action required: {', '.join(d.intervention.action for d in overdue[:3])}"
+            )
+
+        if pending:
+            return (
+                f"WARNING: {protocol.name} activated. "
+                f"{len(pending)} interventions pending: "
+                f"{', '.join(d.intervention.action for d in pending[:3])}"
+            )
+
+        return "Protocol monitoring active."