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

empathy_healthcare_plugin/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)

empathy_healthcare_plugin/monitors/monitoring/sensor_parsers.py

@@ -0,0 +1,306 @@
+"""Sensor Data Parsers
+
+Parses sensor data from various formats (HL7, FHIR, manual entry).
+
+This is like parsing linter output - converting various formats to standard structure.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class VitalSignType(Enum):
+    """Types of vital signs"""
+
+    HEART_RATE = "heart_rate"
+    BLOOD_PRESSURE = "blood_pressure"
+    RESPIRATORY_RATE = "respiratory_rate"
+    TEMPERATURE = "temperature"
+    OXYGEN_SATURATION = "oxygen_saturation"
+    MENTAL_STATUS = "mental_status"
+    PAIN_SCORE = "pain_score"
+
+
+@dataclass
+class VitalSignReading:
+    """Standardized vital sign reading.
+
+    This is the universal format - all parsers convert to this.
+    """
+
+    vital_type: VitalSignType
+    value: Any
+    unit: str
+    timestamp: datetime
+    source: str  # "bedside_monitor", "manual_entry", "wearable"
+    patient_id: str
+    quality: str | None = None  # "good", "poor", "artifact"
+    metadata: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary"""
+        return {
+            "vital_type": self.vital_type.value,
+            "value": self.value,
+            "unit": self.unit,
+            "timestamp": self.timestamp.isoformat(),
+            "source": self.source,
+            "patient_id": self.patient_id,
+            "quality": self.quality,
+            "metadata": self.metadata or {},
+        }
+
+
+class BaseSensorParser:
+    """Base class for sensor data parsers"""
+
+    def parse(self, data: str) -> list[VitalSignReading]:
+        """Parse sensor data into standardized readings"""
+        raise NotImplementedError(
+            f"{self.__class__.__name__}.parse() must be implemented. "
+            "Create a subclass of BaseSensorParser and implement the parse() method. "
+            f"See FHIRObservationParser or SimpleJSONParser for examples."
+        )
+
+
+class FHIRObservationParser(BaseSensorParser):
+    """Parse FHIR Observation resources.
+
+    FHIR is standard for healthcare data exchange.
+    """
+
+    # LOINC codes for common vitals
+    LOINC_MAPPINGS = {
+        "8867-4": VitalSignType.HEART_RATE,
+        "8480-6": VitalSignType.BLOOD_PRESSURE,  # Systolic
+        "8462-4": VitalSignType.BLOOD_PRESSURE,  # Diastolic
+        "9279-1": VitalSignType.RESPIRATORY_RATE,
+        "8310-5": VitalSignType.TEMPERATURE,
+        "2708-6": VitalSignType.OXYGEN_SATURATION,
+        "38208-5": VitalSignType.PAIN_SCORE,
+    }
+
+    def parse(self, data: str) -> list[VitalSignReading]:
+        """Parse FHIR Observation JSON"""
+        try:
+            observation = json.loads(data)
+        except json.JSONDecodeError:
+            return []
+
+        if observation.get("resourceType") != "Observation":
+            return []
+
+        readings = []
+
+        # Extract LOINC code
+        code = observation.get("code", {})
+        loinc_code = None
+
+        for coding in code.get("coding", []):
+            if coding.get("system") == "http://loinc.org":
+                loinc_code = coding.get("code")
+                break
+
+        if not loinc_code or loinc_code not in self.LOINC_MAPPINGS:
+            return []
+
+        vital_type = self.LOINC_MAPPINGS[loinc_code]
+
+        # Extract value
+        value_qty = observation.get("valueQuantity", {})
+        value = value_qty.get("value")
+        unit = value_qty.get("unit", "")
+
+        # Extract timestamp
+        timestamp_str = observation.get("effectiveDateTime")
+        timestamp = (
+            datetime.fromisoformat(timestamp_str.replace("Z", "+00:00"))
+            if timestamp_str
+            else datetime.now()
+        )
+
+        # Extract patient ID
+        subject = observation.get("subject", {})
+        patient_id = subject.get("reference", "").split("/")[-1]
+
+        reading = VitalSignReading(
+            vital_type=vital_type,
+            value=value,
+            unit=unit,
+            timestamp=timestamp,
+            source="fhir_observation",
+            patient_id=patient_id,
+            metadata={"loinc_code": loinc_code},
+        )
+
+        readings.append(reading)
+
+        return readings
+
+
+class SimpleJSONParser(BaseSensorParser):
+    """Parse simple JSON format for manual entry or simulation.
+
+    Example:
+    {
+        "patient_id": "12345",
+        "timestamp": "2024-01-20T14:30:00Z",
+        "vitals": {
+            "hr": 110,
+            "systolic_bp": 95,
+            "diastolic_bp": 60,
+            "respiratory_rate": 24,
+            "temp_f": 101.5,
+            "o2_sat": 94
+        }
+    }
+
+    """
+
+    VITAL_MAPPINGS = {
+        "hr": (VitalSignType.HEART_RATE, "bpm"),
+        "heart_rate": (VitalSignType.HEART_RATE, "bpm"),
+        "systolic_bp": (VitalSignType.BLOOD_PRESSURE, "mmHg"),
+        "diastolic_bp": (VitalSignType.BLOOD_PRESSURE, "mmHg"),
+        "bp": (VitalSignType.BLOOD_PRESSURE, "mmHg"),
+        "respiratory_rate": (VitalSignType.RESPIRATORY_RATE, "/min"),
+        "rr": (VitalSignType.RESPIRATORY_RATE, "/min"),
+        "temp_f": (VitalSignType.TEMPERATURE, "°F"),
+        "temp_c": (VitalSignType.TEMPERATURE, "°C"),
+        "temperature": (VitalSignType.TEMPERATURE, "°F"),
+        "o2_sat": (VitalSignType.OXYGEN_SATURATION, "%"),
+        "spo2": (VitalSignType.OXYGEN_SATURATION, "%"),
+        "mental_status": (VitalSignType.MENTAL_STATUS, "text"),
+        "pain": (VitalSignType.PAIN_SCORE, "0-10"),
+    }
+
+    def parse(self, data: str) -> list[VitalSignReading]:
+        """Parse simple JSON format"""
+        try:
+            parsed = json.loads(data)
+        except json.JSONDecodeError:
+            return []
+
+        patient_id = parsed.get("patient_id", "unknown")
+        timestamp_str = parsed.get("timestamp")
+        timestamp = (
+            datetime.fromisoformat(timestamp_str.replace("Z", "+00:00"))
+            if timestamp_str
+            else datetime.now()
+        )
+
+        vitals = parsed.get("vitals", {})
+
+        readings = []
+
+        for key, value in vitals.items():
+            if key in self.VITAL_MAPPINGS:
+                vital_type, unit = self.VITAL_MAPPINGS[key]
+
+                reading = VitalSignReading(
+                    vital_type=vital_type,
+                    value=value,
+                    unit=unit,
+                    timestamp=timestamp,
+                    source="manual_entry",
+                    patient_id=patient_id,
+                )
+
+                readings.append(reading)
+
+        return readings
+
+
+class SensorParserFactory:
+    """Factory for creating appropriate sensor parser"""
+
+    _parsers = {"fhir": FHIRObservationParser, "simple_json": SimpleJSONParser}
+
+    @classmethod
+    def create(cls, format_type: str) -> BaseSensorParser:
+        """Create parser for specified format"""
+        parser_class = cls._parsers.get(format_type)
+
+        if not parser_class:
+            raise ValueError(
+                f"Unsupported sensor format: {format_type}. "
+                f"Supported: {', '.join(cls._parsers.keys())}",
+            )
+
+        return parser_class()
+
+
+def parse_sensor_data(data: str, format_type: str = "simple_json") -> list[VitalSignReading]:
+    """Convenience function to parse sensor data.
+
+    Args:
+        data: Raw sensor data (JSON string)
+        format_type: "fhir" or "simple_json"
+
+    Returns:
+        List of VitalSignReading objects
+
+    Example:
+        >>> data = '{"patient_id": "12345", "vitals": {"hr": 110}}'
+        >>> readings = parse_sensor_data(data, "simple_json")
+        >>> print(f"HR: {readings[0].value} {readings[0].unit}")
+
+    """
+    parser = SensorParserFactory.create(format_type)
+    return parser.parse(data)
+
+
+def normalize_vitals(readings: list[VitalSignReading]) -> dict[str, Any]:
+    """Normalize vital sign readings into protocol-checkable format.
+
+    Takes list of VitalSignReading and converts to dict for protocol checker.
+
+    Args:
+        readings: List of vital sign readings
+
+    Returns:
+        Dictionary with normalized values for protocol checking
+
+    Example:
+        >>> normalized = normalize_vitals(readings)
+        >>> # Returns: {"hr": 110, "systolic_bp": 95, "respiratory_rate": 24}
+
+    """
+    normalized = {}
+
+    for reading in readings:
+        if reading.vital_type == VitalSignType.HEART_RATE:
+            normalized["hr"] = reading.value
+
+        elif reading.vital_type == VitalSignType.BLOOD_PRESSURE:
+            # Determine if systolic or diastolic based on value
+            if reading.value > 60:  # Likely systolic
+                normalized["systolic_bp"] = reading.value
+            else:  # Likely diastolic
+                normalized["diastolic_bp"] = reading.value
+
+        elif reading.vital_type == VitalSignType.RESPIRATORY_RATE:
+            normalized["respiratory_rate"] = reading.value
+
+        elif reading.vital_type == VitalSignType.TEMPERATURE:
+            if reading.unit == "°F":
+                normalized["temp_f"] = reading.value
+            elif reading.unit == "°C":
+                normalized["temp_c"] = reading.value
+
+        elif reading.vital_type == VitalSignType.OXYGEN_SATURATION:
+            normalized["o2_sat"] = reading.value
+
+        elif reading.vital_type == VitalSignType.MENTAL_STATUS:
+            normalized["mental_status"] = reading.value
+
+        elif reading.vital_type == VitalSignType.PAIN_SCORE:
+            normalized["pain_score"] = reading.value
+
+    return normalized