iints-sdk-python35 0.0.18__py3-none-any.whl

iints/api/base_algorithm.py

@@ -0,0 +1,307 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class AlgorithmInput:
+    """Dataclass for inputs to the insulin prediction algorithm."""
+    current_glucose: float
+    time_step: float
+    insulin_on_board: float = 0.0
+    carb_intake: float = 0.0
+    patient_state: Dict[str, Any] = field(default_factory=dict)
+    current_time: float = 0.0 # Added current_time
+    carbs_on_board: float = 0.0
+    isf: Optional[float] = None
+    icr: Optional[float] = None
+    dia_minutes: Optional[float] = None
+    basal_rate_u_per_hr: Optional[float] = None
+    glucose_trend_mgdl_min: Optional[float] = None
+    predicted_glucose_30min: Optional[float] = None
+
+
+@dataclass
+class AlgorithmMetadata:
+    """Metadata for algorithm registration and identification"""
+    name: str
+    version: str = "1.0.0"
+    author: str = "IINTS-AF Team"
+    paper_reference: Optional[str] = None
+    description: str = ""
+    algorithm_type: str = "rule_based"  # 'rule_based', 'ml', 'hybrid'
+    requires_training: bool = False
+    supported_scenarios: List[str] = field(default_factory=lambda: [
+        'standard_meal', 'unannounced_meal', 'exercise', 
+        'stress', 'hypoglycemia', 'hyperglycemia'
+    ])
+    
+    def to_dict(self) -> Dict:
+        return {
+            'name': self.name,
+            'version': self.version,
+            'author': self.author,
+            'paper_reference': self.paper_reference,
+            'description': self.description,
+            'algorithm_type': self.algorithm_type,
+            'requires_training': self.requires_training,
+            'supported_scenarios': self.supported_scenarios
+        }
+
+
+@dataclass
+class AlgorithmResult:
+    """Result of an insulin prediction with uncertainty"""
+    total_insulin_delivered: float
+    bolus_insulin: float = 0.0
+    basal_insulin: float = 0.0
+    correction_bolus: float = 0.0
+    meal_bolus: float = 0.0
+    
+    # Uncertainty quantification
+    uncertainty: float = 0.0  # 0.0 = certain, 1.0 = very uncertain
+    confidence_interval: tuple = (0.0, 0.0)  # (lower, upper)
+    
+    # Clinical reasoning
+    primary_reason: str = ""
+    secondary_reasons: List[str] = field(default_factory=list)
+    safety_constraints: List[str] = field(default_factory=list)
+    
+    # Metadata
+    algorithm_name: str = ""
+    timestamp: datetime = field(default_factory=datetime.now)
+    
+    def to_dict(self) -> Dict:
+        return {
+            'total_insulin_delivered': self.total_insulin_delivered,
+            'bolus_insulin': self.bolus_insulin,
+            'basal_insulin': self.basal_insulin,
+            'correction_bolus': self.correction_bolus,
+            'meal_bolus': self.meal_bolus,
+            'uncertainty': self.uncertainty,
+            'confidence_interval': self.confidence_interval,
+            'primary_reason': self.primary_reason,
+            'secondary_reasons': self.secondary_reasons,
+            'safety_constraints': self.safety_constraints,
+            'algorithm_name': self.algorithm_name,
+            'timestamp': self.timestamp.isoformat()
+        }
+
+
+@dataclass
+class WhyLogEntry:
+    """Single entry in the Why Log explaining a decision reason"""
+    reason: str
+    category: str  # 'glucose_level', 'velocity', 'insulin_on_board', 'safety', 'context'
+    value: Any = None
+    clinical_impact: str = ""
+
+    def to_dict(self) -> Dict:
+        return {
+            'reason': self.reason,
+            'category': self.category,
+            'value': self.value,
+            'clinical_impact': self.clinical_impact
+        }
+
+class InsulinAlgorithm(ABC):
+    """
+    Abstract base class for insulin delivery algorithms.
+
+    All specific insulin algorithms used in the simulation framework should
+    inherit from this class and implement its abstract methods.
+    
+    This class supports the Plug-and-Play architecture, allowing any algorithm
+    to be registered and compared in Battle Mode.
+    """
+
+    def __init__(self, settings: Optional[Dict[str, Any]] = None):
+        """
+        Initializes the algorithm with its specific settings.
+
+        Args:
+            settings (Dict[str, Any]): A dictionary of algorithm-specific parameters.
+        """
+        self.settings = settings if settings is not None else {}
+        self.state: Dict[str, Any] = {}  # To store internal algorithm state across calls
+        self.why_log: List[WhyLogEntry] = []  # Decision reasoning log
+        self._metadata: Optional[AlgorithmMetadata] = None  # Lazy-loaded metadata
+        self.isf = self.settings.get('isf', 50.0)  # Default ISF
+        self.icr = self.settings.get('icr', 10.0)  # Default ICR
+
+    def set_isf(self, isf: float):
+        """Set the Insulin Sensitivity Factor (mg/dL per unit)."""
+        if isf <= 0:
+            raise ValueError("ISF must be a positive value.")
+        self.isf = isf
+        
+    def set_icr(self, icr: float):
+        """Set the Insulin-to-Carb Ratio (grams per unit)."""
+        if icr <= 0:
+            raise ValueError("ICR must be a positive value.")
+        self.icr = icr
+        
+    def get_algorithm_metadata(self) -> AlgorithmMetadata:
+        """
+        Get algorithm metadata. Override in subclasses for custom metadata.
+        
+        Returns:
+            AlgorithmMetadata: Information about the algorithm for registration
+        """
+        if self._metadata is None:
+            # Default metadata - override in subclasses
+            self._metadata = AlgorithmMetadata(
+                name=self.__class__.__name__,
+                version="1.0.0",
+                author="IINTS-AF Team",
+                description=f"Insulin algorithm: {self.__class__.__name__}",
+                algorithm_type="rule_based"
+            )
+        return self._metadata
+    
+    def set_algorithm_metadata(self, metadata: AlgorithmMetadata):
+        """Set custom algorithm metadata"""
+        self._metadata = metadata
+    
+    def calculate_uncertainty(self, data: AlgorithmInput) -> float:
+        """
+        Calculate uncertainty score for the current prediction.
+        
+        Override in subclasses to implement custom uncertainty quantification.
+        
+        Args:
+            data: Current algorithm input
+            
+        Returns:
+            float: Uncertainty score between 0.0 (certain) and 1.0 (very uncertain)
+        """
+        # Default: low uncertainty for rule-based algorithms
+        return 0.1
+    
+    def calculate_confidence_interval(self, 
+                                      data: AlgorithmInput,
+                                      prediction: float,
+                                      uncertainty: float) -> tuple:
+        """
+        Calculate confidence interval for the prediction.
+        
+        Args:
+            data: Current algorithm input
+            prediction: Predicted insulin dose
+            uncertainty: Uncertainty score
+            
+        Returns:
+            tuple: (lower_bound, upper_bound) for the prediction
+        """
+        # Default: ±20% of prediction based on uncertainty
+        margin = prediction * 0.2 * (1 + uncertainty)
+        return (max(0, prediction - margin), prediction + margin)
+    
+    def explain_prediction(self, 
+                          data: AlgorithmInput, 
+                          prediction: Dict[str, Any]) -> str:
+        """
+        Generate human-readable explanation for the prediction.
+        
+        This is used for the Reasoning Log in the Clinical Control Center.
+        
+        Args:
+            data: Algorithm input
+            prediction: Prediction dictionary
+            
+        Returns:
+            str: Explanation like "2 units delivered because glucose rising >2 mg/dL/min"
+        """
+        reasons = []
+        
+        # Glucose level reasoning
+        if data.current_glucose < 70:
+            reasons.append(f"glucose critically low at {data.current_glucose:.0f} mg/dL")
+        elif data.current_glucose < 100:
+            reasons.append(f"glucose approaching low at {data.current_glucose:.0f} mg/dL")
+        elif data.current_glucose > 180:
+            reasons.append(f"glucose elevated at {data.current_glucose:.0f} mg/dL")
+        else:
+            reasons.append(f"glucose in target range at {data.current_glucose:.0f} mg/dL")
+        
+        # Insulin on board
+        if data.insulin_on_board > 2.0:
+            reasons.append(f"high insulin on board ({data.insulin_on_board:.1f} U)")
+        elif data.insulin_on_board > 0.5:
+            reasons.append(f"moderate insulin on board ({data.insulin_on_board:.1f} U)")
+        
+        # Carbs
+        if data.carb_intake > 0:
+            reasons.append(f"meal detected ({data.carb_intake:.0f}g carbs)")
+        
+        if prediction.get('total_insulin_delivered', 0) > 0:
+            return f"{prediction['total_insulin_delivered']:.2f} units delivered because " + ", ".join(reasons)
+        else:
+            return f"No insulin delivered: " + ", ".join(reasons)
+
+    @abstractmethod
+    def predict_insulin(self, data: AlgorithmInput) -> Dict[str, Any]:
+        """
+        Calculates the insulin dose based on current physiological data.
+        This is the primary method to be implemented by custom algorithms.
+
+        Args:
+            data (AlgorithmInput): A dataclass containing all relevant data for the decision.
+
+        Returns:
+            Dict[str, Any]: A dictionary containing the calculated insulin doses.
+                            A key 'total_insulin_delivered' is expected by the simulator.
+                            (e.g., {'total_insulin_delivered': 1.5, 'bolus_insulin': 1.0, 'basal_insulin': 0.5})
+        """
+        # Clear why_log at start of each calculation
+        self.why_log = []
+        raise NotImplementedError("Subclasses must implement predict_insulin method")
+    
+    def _log_reason(self, reason: str, category: str, value: Any = None, clinical_impact: str = ""):
+        """Helper method to add reasoning to why_log"""
+        entry = WhyLogEntry(
+            reason=reason,
+            category=category,
+            value=value,
+            clinical_impact=clinical_impact
+        )
+        self.why_log.append(entry)
+    
+    def get_why_log(self) -> List[WhyLogEntry]:
+        """Get the decision reasoning log for the last calculation"""
+        return self.why_log
+    
+    def get_why_log_text(self) -> str:
+        """Get human-readable why log"""
+        if not self.why_log:
+            return "No decision reasoning available"
+        
+        text = "WHY_LOG:\n"
+        for entry in self.why_log:
+            text += f"- {entry.reason}"
+            if entry.value is not None:
+                text += f" (value: {entry.value})"
+            if entry.clinical_impact:
+                text += f" → {entry.clinical_impact}"
+            text += "\n"
+        return text
+
+    def reset(self):
+        """
+        Resets the algorithm's internal state.
+        This should be called at the start of each new simulation run.
+        """
+        self.state = {}
+        self.why_log = []
+
+    def get_state(self) -> Dict[str, Any]:
+        """
+        Returns the current internal state of the algorithm.
+        """
+        return self.state
+
+    def set_state(self, state: Dict[str, Any]):
+        """
+        Sets the internal state of the algorithm.
+        """
+        self.state = state

iints/api/registry.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Mapping, Sequence, Iterable, Any, cast
+import importlib
+
+try:
+    from importlib import metadata as importlib_metadata
+except Exception:  # pragma: no cover
+    import importlib_metadata  # type: ignore
+
+from iints.api.base_algorithm import InsulinAlgorithm, AlgorithmMetadata
+from iints.core.algorithms.discovery import discover_algorithms
+
+
+@dataclass
+class AlgorithmListing:
+    name: str
+    class_path: str
+    source: str
+    metadata: Optional[AlgorithmMetadata]
+    status: str = "available"
+    error: Optional[str] = None
+
+
+def _load_entry_point(ep) -> AlgorithmListing:
+    try:
+        obj = ep.load()
+        if isinstance(obj, type) and issubclass(obj, InsulinAlgorithm):
+            instance = obj()
+            meta = instance.get_algorithm_metadata()
+            return AlgorithmListing(
+                name=meta.name,
+                class_path=f"{obj.__module__}.{obj.__name__}",
+                source=f"entry_point:{ep.name}",
+                metadata=meta,
+            )
+        return AlgorithmListing(
+            name=ep.name,
+            class_path=f"{ep.module}:{ep.attr}",
+            source=f"entry_point:{ep.name}",
+            metadata=None,
+            status="invalid",
+            error="Entry point does not resolve to an InsulinAlgorithm",
+        )
+    except Exception as exc:
+        return AlgorithmListing(
+            name=ep.name,
+            class_path=f"{ep.module}:{ep.attr}",
+            source=f"entry_point:{ep.name}",
+            metadata=None,
+            status="unavailable",
+            error=str(exc),
+        )
+
+
+def list_algorithm_plugins() -> List[AlgorithmListing]:
+    listings: List[AlgorithmListing] = []
+
+    # Built-in discovery
+    try:
+        discovered = discover_algorithms()
+        for name, cls in discovered.items():
+            try:
+                instance = cls()
+                meta = instance.get_algorithm_metadata()
+                listings.append(
+                    AlgorithmListing(
+                        name=meta.name,
+                        class_path=f"{cls.__module__}.{cls.__name__}",
+                        source="builtin",
+                        metadata=meta,
+                    )
+                )
+            except Exception as exc:
+                listings.append(
+                    AlgorithmListing(
+                        name=name,
+                        class_path=f"{cls.__module__}.{cls.__name__}",
+                        source="builtin",
+                        metadata=None,
+                        status="unavailable",
+                        error=str(exc),
+                    )
+                )
+    except Exception:
+        pass
+
+    # Entry points
+    try:
+        eps = importlib_metadata.entry_points()
+        group: Iterable[Any]
+        if hasattr(eps, "select"):
+            group = list(eps.select(group="iints.algorithms"))
+        else:
+            eps_mapping = cast(Mapping[str, Sequence[object]], eps)
+            group = eps_mapping.get("iints.algorithms", ())
+        for ep in group:
+            listings.append(_load_entry_point(ep))
+    except Exception:
+        pass
+
+    return listings

iints/api/template_algorithm.py

@@ -0,0 +1,195 @@
+# IINTS-AF RESEARCH SDK: ALGORITHM TEMPLATE
+#
+# Welcome to the IINTS-AF Research SDK! This file is your starting point
+# for creating your own insulin delivery algorithm.
+#
+# HOW IT WORKS:
+# 1. COPY THIS FILE: Copy this template into a new file within this same
+#     `user` directory (e.g., `MyAwesomeAlgorithm.py`).
+# 2. RENAME THE CLASS: Change the class name from `TemplateAlgorithm` to something
+#     unique (e.g., `MyAwesomeAlgorithm`).
+# 3. WRITE YOUR LOGIC: Implement your insulin calculation logic in the
+#     `predict_insulin` method.
+# 4. RUN THE BATTLE: Your new algorithm will be automatically detected
+#     and will appear as an option in the IINTS-AF terminal.
+#
+# Happy coding!
+#
+# -----------------------------------------------------------------------------
+
+from typing import Dict, Any, List
+
+# All algorithms must inherit from the InsulinAlgorithm base class.
+# It provides the necessary structure and methods that the IINTS-AF simulator expects.
+from iints.api.base_algorithm import InsulinAlgorithm, AlgorithmInput, AlgorithmMetadata, WhyLogEntry
+
+# A "Dose" is a dictionary containing the insulin breakdown. The simulator
+# currently only requires 'total_insulin_delivered'. The other keys are for
+# more detailed logging and analysis.
+Dose = Dict[str, float]
+
+
+class TemplateAlgorithm(InsulinAlgorithm):
+    """
+    This is a template for a user-defined insulin delivery algorithm.
+    It demonstrates the required structure and provides a basic, safe implementation
+    of a correction and meal bolus logic.
+    """
+
+    def get_algorithm_metadata(self) -> AlgorithmMetadata:
+        """
+        REQUIRED: This method provides metadata about your algorithm.
+        The simulator uses this to identify and display your algorithm in the UI.
+        """
+        return AlgorithmMetadata(
+            name="Template Algorithm",  # The name that will appear in the UI
+            version="1.0.0",
+            author="Your Name Here",
+            description="A basic example algorithm demonstrating the IINTS-AF SDK.",
+            algorithm_type="rule_based" # 'rule_based', 'ml', or 'hybrid'
+        )
+
+    def predict_insulin(self, data: AlgorithmInput) -> Dose:
+        """
+        REQUIRED: This is the core method of your algorithm.
+        The simulator calls this method at each time step (e.g., every 5 minutes).
+
+        Args:
+            data (AlgorithmInput): An object containing the current patient data.
+                - data.current_glucose (float): The latest glucose reading in mg/dL.
+                - data.insulin_on_board (float): Estimated insulin still active from previous doses.
+                - data.carb_intake (float): Carbohydrates from a meal announced at this time step (in grams).
+                - data.time_step (float): The duration since the last call, in minutes.
+                - data.current_time (float): The current simulation time in minutes from the start.
+                - data.patient_state (Dict): A dictionary for you to store custom state between function calls (e.g., tracking glucose trends).
+
+        Returns:
+            Dose (Dict[str, float]): A dictionary specifying the insulin dose to be delivered.
+                                     Must contain at least the 'total_insulin_delivered' key.
+        """
+        # This function is called at every time step.
+        # First, we clear the reasoning log from the previous step.
+        self.why_log = []
+
+        # --- Example: Accessing Patient Data ---
+        current_glucose = data.current_glucose
+        iob = data.insulin_on_board
+        carbs = data.carb_intake
+
+        # --- Your Custom State Management (Optional) ---
+        # The `self.state` dictionary persists across calls for this simulation run.
+        # You can use it to track trends, previous states, etc.
+        previous_glucose = self.state.get('previous_glucose', current_glucose)
+        glucose_trend = (current_glucose - previous_glucose) / data.time_step # mg/dL/min
+        self.state['previous_glucose'] = current_glucose # Update state for the next call
+
+        # ----------------------------------------------------------------------
+        # --- YOUR CUSTOM LOGIC START ---
+        # ----------------------------------------------------------------------
+
+        # Initialize insulin components
+        correction_bolus = 0.0
+        meal_bolus = 0.0
+        basal_rate = 0.0 # This simple example does not use a dynamic basal rate
+
+        # Define algorithm parameters
+        # In a real algorithm, these would be managed more robustly.
+        target_glucose = 110  # mg/dL
+        insulin_sensitivity_factor = self.isf # mg/dL per Unit of insulin (set in base class)
+        carb_to_insulin_ratio = self.icr # grams of carb per Unit of insulin (set in base class)
+
+        # --- Log Key Data for Traceability ---
+        # This is how you make your algorithm's reasoning transparent!
+        self._log_reason(f"Current glucose is {current_glucose:.0f} mg/dL.", "glucose_level", current_glucose)
+        self._log_reason(f"Glucose trend is {glucose_trend:+.1f} mg/dL/min.", "velocity", glucose_trend)
+        self._log_reason(f"Active insulin (IOB) is {iob:.2f} U.", "insulin_on_board", iob)
+
+
+        # --- Example Correction Bolus Logic ---
+        # Only correct if glucose is above the target
+        if current_glucose > target_glucose:
+            glucose_diff = current_glucose - target_glucose
+            # Standard correction formula: (Current - Target) / ISF
+            correction_bolus = glucose_diff / insulin_sensitivity_factor
+            self._log_reason(
+                f"Calculated correction bolus of {correction_bolus:.2f} U for high glucose.",
+                "calculation",
+                correction_bolus,
+                clinical_impact="Aims to bring glucose back to target range."
+            )
+        else:
+             self._log_reason("No correction bolus needed (glucose is at or below target).", "calculation")
+
+
+        # --- Example Meal Bolus Logic ---
+        # Deliver a bolus if carbs are announced
+        if carbs > 0:
+            # Standard meal bolus formula: Carbs / ICR
+            meal_bolus = carbs / carb_to_insulin_ratio
+            self._log_reason(
+                f"Calculated meal bolus of {meal_bolus:.2f} U for {carbs}g carbs.",
+                "calculation",
+                meal_bolus,
+                clinical_impact="Aims to cover carbohydrate intake from a meal."
+            )
+            
+        # --- Example Safety Guard: Insulin Stacking ---
+        # Reduce the calculated dose by the amount of insulin already on board (IOB).
+        # This is a crucial safety feature to prevent hypoglycemia from "stacking" insulin.
+        total_calculated_dose = meal_bolus + correction_bolus
+        
+        if total_calculated_dose > iob:
+            final_bolus = total_calculated_dose - iob
+            self._log_reason(
+                f"Reducing dose by IOB ({iob:.2f} U). Final bolus: {final_bolus:.2f} U.",
+                "safety",
+                final_bolus,
+                clinical_impact="Prevents insulin stacking and reduces hypoglycemia risk."
+            )
+        else:
+            final_bolus = 0.0 # Don't give a negative dose
+            self._log_reason(
+                f"Calculated dose ({total_calculated_dose:.2f} U) is less than IOB ({iob:.2f} U). No bolus advised.",
+                "safety",
+                final_bolus,
+                clinical_impact="High IOB indicates sufficient active insulin; delivering more could be dangerous."
+            )
+
+        # --- Example Safety Guard: Hypoglycemia Prevention ---
+        # If glucose is low or dropping fast, suspend all insulin delivery.
+        if current_glucose < 80 or glucose_trend < -3.0:
+            final_bolus = 0.0
+            basal_rate = 0.0
+            self._log_reason(
+                "SUSPENDING INSULIN: Glucose is low or dropping rapidly.",
+                "safety",
+                current_glucose,
+                clinical_impact="Critical safety action to prevent severe hypoglycemia."
+            )
+
+        # ----------------------------------------------------------------------
+        # --- YOUR CUSTOM LOGIC END ---
+        # ----------------------------------------------------------------------
+
+        # The final dose must be assembled into a dictionary.
+        # The simulator only strictly requires 'total_insulin_delivered'.
+        # The other keys are for detailed analysis and logging.
+        dose: Dose = {
+            'basal_insulin': basal_rate,
+            'meal_bolus': meal_bolus,
+            'correction_bolus': correction_bolus,
+            'total_insulin_delivered': max(0, final_bolus + basal_rate) # Ensure no negative insulin
+        }
+
+        return dose
+
+    def reset(self):
+        """
+        This method is called by the simulator at the start of a new simulation.
+        Use it to reset any internal state of your algorithm.
+        """
+        # Reset the state dictionary for the new simulation run.
+        self.state = {}
+        # Also clear the reasoning log.
+        self.why_log = []
+        print(f"[{self.get_algorithm_metadata().name}] has been reset.")