attune-ai 2.0.0__py3-none-any.whl

attune_healthcare/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",
+]

attune_healthcare/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."

attune_healthcare/monitors/monitoring/protocol_loader.py

@@ -0,0 +1,214 @@
+"""Protocol Loader
+
+Loads clinical pathway protocols from JSON files.
+
+This is like loading linting configs - protocols define the rules.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class ProtocolCriterion:
+    """A single criterion in a protocol"""
+
+    parameter: str
+    condition: str  # "<=", ">=", "==", "!=", "altered", etc.
+    value: Any | None = None
+    points: int = 0
+    description: str | None = None
+
+
+@dataclass
+class ProtocolIntervention:
+    """A required intervention"""
+
+    order: int
+    action: str
+    timing: str
+    required: bool = True
+    parameters: dict[str, Any] | None = None
+
+
+@dataclass
+class ClinicalProtocol:
+    """Clinical pathway protocol.
+
+    This is the "linting config" for healthcare - defines the rules.
+    """
+
+    name: str
+    version: str
+    applies_to: list[str]
+
+    # Screening criteria (when to activate protocol)
+    screening_criteria: list[ProtocolCriterion]
+    screening_threshold: int
+
+    # Required interventions (what to do)
+    interventions: list[ProtocolIntervention]
+
+    # Monitoring requirements
+    monitoring_frequency: str
+    reassessment_timing: str
+
+    # Escalation criteria (when to call for help)
+    escalation_criteria: list[str] | None = None
+
+    # Documentation requirements
+    documentation_requirements: list[str] | None = None
+
+    # Raw protocol data
+    raw_protocol: dict[str, Any] | None = None
+
+
+class ProtocolLoader:
+    """Loads clinical protocols from JSON files.
+
+    Similar to loading .eslintrc or pyproject.toml - we're loading
+    the protocol configuration.
+    """
+
+    def __init__(self, protocol_directory: str | None = None):
+        if protocol_directory:
+            self.protocol_dir = Path(protocol_directory)
+        else:
+            # Default to protocols directory in plugin
+            plugin_dir = Path(__file__).parent.parent.parent
+            self.protocol_dir = plugin_dir / "protocols"
+
+    def load_protocol(self, protocol_name: str) -> ClinicalProtocol:
+        """Load protocol by name.
+
+        Args:
+            protocol_name: Name of protocol (e.g., "sepsis", "post_operative")
+
+        Returns:
+            ClinicalProtocol object
+
+        Example:
+            >>> loader = ProtocolLoader()
+            >>> protocol = loader.load_protocol("sepsis")
+            >>> print(f"Loaded: {protocol.name} v{protocol.version}")
+
+        """
+        protocol_file = self.protocol_dir / f"{protocol_name}.json"
+
+        if not protocol_file.exists():
+            raise FileNotFoundError(
+                f"Protocol not found: {protocol_name}\nLooked in: {self.protocol_dir}",
+            )
+
+        with open(protocol_file) as f:
+            data = json.load(f)
+
+        return self._parse_protocol(data)
+
+    def _parse_protocol(self, data: dict[str, Any]) -> ClinicalProtocol:
+        """Parse protocol JSON into ClinicalProtocol object"""
+        # Parse screening criteria
+        screening_data = data.get("screening_criteria", {})
+        criteria = []
+
+        for crit in screening_data.get("criteria", []):
+            criteria.append(
+                ProtocolCriterion(
+                    parameter=crit["parameter"],
+                    condition=crit["condition"],
+                    value=crit.get("value"),
+                    points=crit.get("points", 0),
+                    description=crit.get("description"),
+                ),
+            )
+
+        # Parse interventions
+        interventions = []
+        for interv in data.get("interventions", []):
+            interventions.append(
+                ProtocolIntervention(
+                    order=interv["order"],
+                    action=interv["action"],
+                    timing=interv["timing"],
+                    required=interv.get("required", True),
+                    parameters=interv.get("parameters"),
+                ),
+            )
+
+        # Parse monitoring requirements
+        monitoring = data.get("monitoring_requirements", {})
+
+        return ClinicalProtocol(
+            name=data["protocol_name"],
+            version=data["protocol_version"],
+            applies_to=data.get("applies_to", []),
+            screening_criteria=criteria,
+            screening_threshold=screening_data.get("threshold", 0),
+            interventions=interventions,
+            monitoring_frequency=monitoring.get("vitals_frequency", "hourly"),
+            reassessment_timing=monitoring.get("reassessment", "hourly"),
+            escalation_criteria=data.get("escalation_criteria", {}).get("if", []),
+            documentation_requirements=data.get("documentation_requirements", []),
+            raw_protocol=data,
+        )
+
+    def list_available_protocols(self) -> list[str]:
+        """List all available protocols"""
+        if not self.protocol_dir.exists():
+            return []
+
+        protocols = []
+        for file in self.protocol_dir.glob("*.json"):
+            protocols.append(file.stem)
+
+        return sorted(protocols)
+
+    def validate_protocol(self, protocol: ClinicalProtocol) -> list[str]:
+        """Validate protocol structure.
+
+        Returns list of validation errors (empty if valid)
+        """
+        errors = []
+
+        if not protocol.name:
+            errors.append("Protocol must have a name")
+
+        if not protocol.version:
+            errors.append("Protocol must have a version")
+
+        if not protocol.screening_criteria:
+            errors.append("Protocol must have screening criteria")
+
+        if not protocol.interventions:
+            errors.append("Protocol must have interventions")
+
+        # Check intervention order
+        orders = [i.order for i in protocol.interventions]
+        if len(orders) != len(set(orders)):
+            errors.append("Intervention orders must be unique")
+
+        return errors
+
+
+def load_protocol(protocol_name: str, protocol_dir: str | None = None) -> ClinicalProtocol:
+    """Convenience function to load a protocol.
+
+    Args:
+        protocol_name: Name of protocol
+        protocol_dir: Optional custom protocol directory
+
+    Returns:
+        ClinicalProtocol object
+
+    Example:
+        >>> protocol = load_protocol("sepsis")
+        >>> print(f"{protocol.name}: {len(protocol.interventions)} interventions")
+
+    """
+    loader = ProtocolLoader(protocol_dir)
+    return loader.load_protocol(protocol_name)