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

iints/research/predictor.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Tuple, Protocol, Sequence, TYPE_CHECKING
+
+import numpy as np
+
+_IMPORT_ERROR: Optional[BaseException]
+try:
+    import torch
+    from torch import nn
+except Exception as exc:  # pragma: no cover
+    torch = None  # type: ignore
+    nn = None  # type: ignore
+    _IMPORT_ERROR = exc
+else:
+    _IMPORT_ERROR = None
+
+
+# ---------------------------------------------------------------------------
+# LSTM predictor
+# ---------------------------------------------------------------------------
+
+if TYPE_CHECKING:
+    import torch  # pragma: no cover
+    from torch import nn  # pragma: no cover
+
+    class LSTMPredictor(nn.Module):
+        def __init__(
+            self,
+            input_size: int,
+            hidden_size: int = 64,
+            num_layers: int = 2,
+            dropout: float = 0.1,
+            horizon_steps: int = 12,
+        ) -> None: ...
+
+        def forward(self, x: "torch.Tensor") -> "torch.Tensor": ...
+
+        def predict_with_uncertainty(
+            self,
+            x: "torch.Tensor",
+            n_samples: int = 50,
+        ) -> Tuple["torch.Tensor", "torch.Tensor"]: ...
+else:
+    if nn is None:  # pragma: no cover
+        class LSTMPredictor:  # type: ignore[no-redef]
+            def __init__(self, *args: object, **kwargs: object) -> None:
+                raise ImportError(
+                    "Torch is required for LSTMPredictor. Install with `pip install iints-sdk-python35[research]`."
+                ) from _IMPORT_ERROR
+    else:
+        class LSTMPredictor(nn.Module):  # type: ignore[misc,no-redef]
+            def __init__(
+                self,
+                input_size: int,
+                hidden_size: int = 64,
+                num_layers: int = 2,
+                dropout: float = 0.1,
+                horizon_steps: int = 12,
+            ) -> None:
+                if torch is None or nn is None:  # pragma: no cover
+                    raise ImportError(
+                        "Torch is required for LSTMPredictor. Install with `pip install iints-sdk-python35[research]`."
+                    ) from _IMPORT_ERROR
+                super().__init__()
+                self.horizon_steps = horizon_steps
+                self.lstm = nn.LSTM(
+                    input_size=input_size,
+                    hidden_size=hidden_size,
+                    num_layers=num_layers,
+                    dropout=dropout if num_layers > 1 else 0.0,
+                    batch_first=True,
+                )
+                self.head = nn.Sequential(
+                    nn.Linear(hidden_size, hidden_size),
+                    nn.ReLU(),
+                    nn.Dropout(p=dropout),   # P3-12: dropout in head for MC Dropout inference
+                    nn.Linear(hidden_size, horizon_steps),
+                )
+
+            def forward(self, x: "torch.Tensor") -> "torch.Tensor":
+                _, (hidden, _) = self.lstm(x)
+                last_hidden = hidden[-1]
+                return self.head(last_hidden)
+
+            # P3-12: Monte Carlo Dropout inference
+            def predict_with_uncertainty(
+                self,
+                x: "torch.Tensor",
+                n_samples: int = 50,
+            ) -> Tuple["torch.Tensor", "torch.Tensor"]:
+                """
+                Run MC Dropout inference to estimate predictive uncertainty.
+
+                Activates dropout at inference time and runs ``n_samples`` forward
+                passes.  Returns the mean prediction and standard deviation across
+                samples as a proxy for aleatoric + epistemic uncertainty.
+
+                Parameters
+                ----------
+                x : torch.Tensor of shape [B, T, F]
+                    Input batch.
+                n_samples : int
+                    Number of stochastic forward passes.
+
+                Returns
+                -------
+                mean : torch.Tensor of shape [B, horizon_steps]
+                std  : torch.Tensor of shape [B, horizon_steps]
+                """
+                if torch is None:  # pragma: no cover
+                    raise ImportError("Torch required.") from _IMPORT_ERROR
+                # Keep dropout active during inference
+                self.train()
+                with torch.no_grad():
+                    preds = torch.stack([self.forward(x) for _ in range(n_samples)], dim=0)
+                self.eval()
+                return preds.mean(dim=0), preds.std(dim=0)
+
+
+# ---------------------------------------------------------------------------
+# P3-11: Baseline predictors
+# ---------------------------------------------------------------------------
+
+class BaselinePredictor(Protocol):
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        ...
+
+    def name(self) -> str:
+        ...
+
+
+class LastValueBaseline:
+    """
+    Naïve last-value (persistence) baseline for glucose forecasting.
+
+    Predicts the same glucose value for all future time steps
+    (i.e. ``y_hat[t+k] = y[t]`` for k = 1..horizon).
+
+    This is the minimum bar any LSTM model must beat.
+    """
+
+    def __init__(self, horizon_steps: int) -> None:
+        self.horizon_steps = horizon_steps
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """
+        Parameters
+        ----------
+        X : np.ndarray of shape [N, T, F]
+            Feature sequences.  Assumes the first feature column is glucose
+            (index 0 along the last axis), which is standard for the AZT1D pipeline.
+
+        Returns
+        -------
+        np.ndarray of shape [N, horizon_steps]
+        """
+        # Last glucose reading in each sequence
+        last_glucose = X[:, -1, 0]  # shape [N]
+        return np.tile(last_glucose[:, None], (1, self.horizon_steps)).astype(np.float32)
+
+    def name(self) -> str:
+        return "LastValue"
+
+
+class LinearTrendBaseline:
+    """
+    Linear-trend extrapolation baseline.
+
+    Fits a least-squares line to the glucose values in the history window and
+    extrapolates it ``horizon_steps`` steps into the future.
+
+    Captures short-term trends (e.g. a rising glucose after a meal) without
+    any knowledge of insulin or carbs, providing a stronger baseline than
+    simple last-value persistence.
+    """
+
+    def __init__(self, horizon_steps: int, time_step_minutes: float = 5.0) -> None:
+        self.horizon_steps = horizon_steps
+        self.time_step_minutes = time_step_minutes
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """
+        Parameters
+        ----------
+        X : np.ndarray of shape [N, T, F]
+            Feature sequences.  First feature (index 0) must be glucose.
+
+        Returns
+        -------
+        np.ndarray of shape [N, horizon_steps]
+        """
+        N, T, _ = X.shape
+        glucose = X[:, :, 0]  # [N, T]
+        t_hist = np.arange(T, dtype=np.float32)  # relative time indices
+        t_future = np.arange(T, T + self.horizon_steps, dtype=np.float32)
+
+        preds = np.empty((N, self.horizon_steps), dtype=np.float32)
+        # Vectorised least-squares over the batch
+        t_mean = t_hist.mean()
+        t_var = ((t_hist - t_mean) ** 2).sum()
+
+        if t_var < 1e-8:
+            # Degenerate case: all time points identical → last-value fallback
+            preds[:] = glucose[:, -1, None]
+            return preds
+
+        slopes = ((glucose * (t_hist - t_mean)).sum(axis=1)) / t_var  # [N]
+        intercepts = glucose.mean(axis=1) - slopes * t_mean             # [N]
+        preds = intercepts[:, None] + slopes[:, None] * t_future[None, :]
+        return preds.astype(np.float32)
+
+    def name(self) -> str:
+        return "LinearTrend"
+
+
+def evaluate_baselines(
+    X: np.ndarray,
+    y: np.ndarray,
+    horizon_steps: int,
+    time_step_minutes: float = 5.0,
+) -> dict:
+    """
+    Compute MAE and RMSE for both baseline predictors.
+
+    Parameters
+    ----------
+    X : np.ndarray [N, T, F]
+    y : np.ndarray [N, horizon_steps]
+    horizon_steps : int
+    time_step_minutes : float
+
+    Returns
+    -------
+    dict with keys "last_value" and "linear_trend", each containing
+    {"mae": float, "rmse": float}.
+    """
+    results = {}
+    baselines: Sequence[BaselinePredictor] = [
+        LastValueBaseline(horizon_steps),
+        LinearTrendBaseline(horizon_steps, time_step_minutes),
+    ]
+    for baseline in baselines:
+        preds = baseline.predict(X)
+        mae = float(np.mean(np.abs(preds - y)))
+        rmse = float(np.sqrt(np.mean((preds - y) ** 2)))
+        results[baseline.name()] = {"mae": mae, "rmse": rmse}
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Service / loading helpers
+# ---------------------------------------------------------------------------
+
+class PredictorService:
+    def __init__(self, model: "LSTMPredictor", config: dict) -> None:
+        self.model = model
+        self.config = config
+        self.feature_columns = list(config.get("feature_columns", []))
+        self.history_steps = int(config.get("history_steps", 1))
+        self.horizon_steps = int(config.get("horizon_steps", 1))
+
+        # Restore scaler if present in checkpoint
+        from iints.research.dataset import FeatureScaler
+        scaler_data = config.get("scaler")
+        self.scaler: Optional[FeatureScaler] = (
+            FeatureScaler.from_dict(scaler_data) if scaler_data else None
+        )
+
+    def predict(self, x: np.ndarray) -> np.ndarray:
+        if torch is None:  # pragma: no cover
+            raise ImportError(
+                "Torch is required for predictor inference. Install with `pip install iints-sdk-python35[research]`."
+            ) from _IMPORT_ERROR
+        if self.scaler is not None:
+            x = self.scaler.transform(x)
+        self.model.eval()
+        with torch.no_grad():
+            tensor = torch.from_numpy(x.astype(np.float32))
+            outputs = self.model(tensor).cpu().numpy()
+        return outputs
+
+    def predict_with_uncertainty(
+        self, x: np.ndarray, n_samples: int = 50
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        """MC Dropout inference — returns (mean, std) arrays."""
+        if torch is None:  # pragma: no cover
+            raise ImportError("Torch required.") from _IMPORT_ERROR
+        if self.scaler is not None:
+            x = self.scaler.transform(x)
+        tensor = torch.from_numpy(x.astype(np.float32))
+        mean_t, std_t = self.model.predict_with_uncertainty(tensor, n_samples=n_samples)
+        return mean_t.detach().cpu().numpy(), std_t.detach().cpu().numpy()
+
+
+def load_predictor(model_path: Path) -> Tuple["LSTMPredictor", dict]:
+    if torch is None or nn is None:  # pragma: no cover
+        raise ImportError(
+            "Torch is required for predictor loading. Install with `pip install iints-sdk-python35[research]`."
+        ) from _IMPORT_ERROR
+    payload = torch.load(model_path, map_location="cpu", weights_only=False)
+    config = payload["config"]
+    model = LSTMPredictor(
+        input_size=config["input_size"],
+        hidden_size=config["hidden_size"],
+        num_layers=config["num_layers"],
+        dropout=config["dropout"],
+        horizon_steps=config["horizon_steps"],
+    )
+    model.load_state_dict(payload["state_dict"])
+    model.eval()
+    return model, config
+
+
+def load_predictor_service(model_path: Path) -> PredictorService:
+    model, config = load_predictor(model_path)
+    return PredictorService(model, config)
+
+
+def predict_batch(model: "LSTMPredictor", x: np.ndarray) -> np.ndarray:
+    if torch is None:  # pragma: no cover
+        raise ImportError(
+            "Torch is required for predictor inference. Install with `pip install iints-sdk-python35[research]`."
+        ) from _IMPORT_ERROR
+    with torch.no_grad():
+        tensor = torch.from_numpy(x.astype(np.float32))
+        outputs = model(tensor).cpu().numpy()
+    return outputs

iints/scenarios/__init__.py

@@ -0,0 +1,3 @@
+from .generator import ScenarioGeneratorConfig, generate_random_scenario
+
+__all__ = ["ScenarioGeneratorConfig", "generate_random_scenario"]

iints/scenarios/generator.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+import random
+
+from iints.validation.schemas import LATEST_SCHEMA_VERSION
+
+
+@dataclass
+class ScenarioGeneratorConfig:
+    name: str
+    schema_version: str = LATEST_SCHEMA_VERSION
+    version: str = "1.0"
+    description: str = "Generated scenario"
+    duration_minutes: int = 1440
+    seed: Optional[int] = None
+
+    meal_count: int = 3
+    meal_min_grams: float = 30.0
+    meal_max_grams: float = 80.0
+    meal_delay_min: int = 10
+    meal_delay_max: int = 60
+    meal_duration_min: int = 30
+    meal_duration_max: int = 120
+
+    exercise_count: int = 0
+    exercise_intensity_min: float = 0.2
+    exercise_intensity_max: float = 0.8
+    exercise_duration_min: int = 30
+    exercise_duration_max: int = 90
+
+    sensor_error_count: int = 0
+    sensor_error_min: float = 40.0
+    sensor_error_max: float = 300.0
+
+
+def _unique_times(rng: random.Random, max_time: int, count: int) -> List[int]:
+    if count <= 0:
+        return []
+    if max_time <= count:
+        return sorted(rng.sample(range(max_time + 1), k=max_time + 1))[:count]
+    return sorted(rng.sample(range(max_time), k=count))
+
+
+def generate_random_scenario(config: ScenarioGeneratorConfig) -> Dict[str, Any]:
+    rng = random.Random(config.seed)
+    events: List[Dict[str, Any]] = []
+    max_time = max(config.duration_minutes - 1, 1)
+
+    meal_times = _unique_times(rng, max_time, config.meal_count)
+    for t in meal_times:
+        events.append(
+            {
+                "start_time": int(t),
+                "event_type": "meal",
+                "value": float(rng.uniform(config.meal_min_grams, config.meal_max_grams)),
+                "absorption_delay_minutes": int(rng.randint(config.meal_delay_min, config.meal_delay_max)),
+                "duration": int(rng.randint(config.meal_duration_min, config.meal_duration_max)),
+            }
+        )
+
+    exercise_times = _unique_times(rng, max_time, config.exercise_count)
+    for t in exercise_times:
+        events.append(
+            {
+                "start_time": int(t),
+                "event_type": "exercise",
+                "value": float(rng.uniform(config.exercise_intensity_min, config.exercise_intensity_max)),
+                "duration": int(rng.randint(config.exercise_duration_min, config.exercise_duration_max)),
+            }
+        )
+
+    sensor_times = _unique_times(rng, max_time, config.sensor_error_count)
+    for t in sensor_times:
+        events.append(
+            {
+                "start_time": int(t),
+                "event_type": "sensor_error",
+                "value": float(rng.uniform(config.sensor_error_min, config.sensor_error_max)),
+            }
+        )
+
+    events = sorted(events, key=lambda e: e["start_time"])
+
+    return {
+        "scenario_name": config.name,
+        "schema_version": config.schema_version,
+        "scenario_version": config.version,
+        "description": config.description,
+        "stress_events": events,
+    }

iints/templates/default_algorithm.py

@@ -0,0 +1,91 @@
+from iints import InsulinAlgorithm, AlgorithmInput, AlgorithmResult, AlgorithmMetadata
+from typing import Dict, Any
+
+class {{ALGO_NAME}}(InsulinAlgorithm):
+    def __init__(self, settings: Dict[str, Any] = None):
+        super().__init__(settings)
+        self.set_algorithm_metadata(AlgorithmMetadata(
+            name="{{ALGO_NAME}}",
+            author="{{AUTHOR_NAME}}",
+            description="A new custom insulin algorithm.",
+            algorithm_type="rule_based" # Change as appropriate
+        ))
+        # Initialize any specific state or parameters for your algorithm here
+
+    def predict_insulin(self, data: AlgorithmInput) -> Dict[str, Any]:
+        # --- SAFETY-FIRST STARTER LOGIC ---
+        # This template is intentionally conservative to avoid hypoglycemia.
+
+        self.why_log = []
+
+        current_glucose = data.current_glucose
+        iob = data.insulin_on_board
+        carbs = data.carb_intake
+
+        previous_glucose = self.state.get("previous_glucose", current_glucose)
+        glucose_trend = (current_glucose - previous_glucose) / max(data.time_step, 1)
+        self.state["previous_glucose"] = current_glucose
+
+        total_insulin = 0.0
+        bolus_insulin = 0.0
+        basal_insulin = 0.0
+        correction_bolus = 0.0
+        meal_bolus = 0.0
+
+        # Hard safety cutoff
+        if current_glucose < 90:
+            self._log_reason("Glucose below 90 mg/dL; holding insulin.", "safety_cutoff", current_glucose)
+            return {
+                "total_insulin_delivered": 0.0,
+                "bolus_insulin": 0.0,
+                "basal_insulin": 0.0,
+                "correction_bolus": 0.0,
+                "meal_bolus": 0.0,
+            }
+
+        # If glucose is falling quickly, avoid correction bolus
+        if glucose_trend < -1.0:
+            self._log_reason(
+                f"Glucose dropping at {glucose_trend:.2f} mg/dL/min; skipping correction bolus.",
+                "safety_trend",
+                glucose_trend,
+            )
+        else:
+            # Conservative correction only if quite high
+            if current_glucose > 180:
+                correction_bolus = (current_glucose - 140) / self.isf
+                correction_bolus = min(max(correction_bolus, 0.0), 0.5)
+                total_insulin += correction_bolus
+                self._log_reason(
+                    f"Conservative correction bolus {correction_bolus:.2f} U.",
+                    "correction",
+                    current_glucose,
+                )
+
+        # Meal bolus (capped)
+        if carbs > 0:
+            meal_bolus = min(carbs / self.icr, 2.0)
+            total_insulin += meal_bolus
+            self._log_reason(
+                f"Meal bolus {meal_bolus:.2f} U for {carbs:.0f} g carbs.",
+                "meal_bolus",
+                carbs,
+            )
+
+        # Optional: cap total insulin based on IOB
+        if iob > 2.0:
+            total_insulin = min(total_insulin, 0.2)
+            self._log_reason("High IOB; capping total insulin to 0.2 U.", "iob_cap", iob)
+
+        total_insulin = max(0.0, total_insulin)
+        bolus_insulin = total_insulin
+
+        self._log_reason(f"Final insulin decision: {total_insulin:.2f} units", "decision", total_insulin)
+
+        return {
+            "total_insulin_delivered": total_insulin,
+            "bolus_insulin": bolus_insulin,
+            "basal_insulin": basal_insulin,
+            "correction_bolus": correction_bolus,
+            "meal_bolus": meal_bolus,
+        }

iints/templates/scenarios/chaos_insulin_stacking.json

@@ -0,0 +1,29 @@
+{
+  "scenario_name": "Chaos: Insulin Stacking",
+  "schema_version": "1.1",
+  "scenario_version": "1.0",
+  "description": "Red-team scenario with repeated false-high CGM values to induce stacked boluses. Use with StackingAIAlgorithm.",
+  "stress_events": [
+    {
+      "start_time": 30,
+      "event_type": "sensor_error",
+      "value": 260
+    },
+    {
+      "start_time": 35,
+      "event_type": "sensor_error",
+      "value": 260
+    },
+    {
+      "start_time": 40,
+      "event_type": "sensor_error",
+      "value": 260
+    },
+    {
+      "start_time": 60,
+      "event_type": "meal",
+      "value": 40,
+      "reported_value": 40
+    }
+  ]
+}

iints/templates/scenarios/chaos_runaway_ai.json

@@ -0,0 +1,25 @@
+{
+  "scenario_name": "Chaos: Runaway AI",
+  "schema_version": "1.1",
+  "scenario_version": "1.0",
+  "description": "Red-team scenario with falling glucose during exercise. Use with RunawayAIAlgorithm.",
+  "stress_events": [
+    {
+      "start_time": 30,
+      "event_type": "meal",
+      "value": 60,
+      "reported_value": 60
+    },
+    {
+      "start_time": 120,
+      "event_type": "exercise",
+      "value": 0.8,
+      "duration": 60
+    },
+    {
+      "start_time": 200,
+      "event_type": "sensor_error",
+      "value": 180
+    }
+  ]
+}

iints/templates/scenarios/example_scenario.json

@@ -0,0 +1,35 @@
+{
+    "scenario_name": "Standard Meal Challenge",
+    "schema_version": "1.1",
+    "scenario_version": "1.0",
+    "description": "A standard day with three meals and a missed bolus event.",
+    "stress_events": [
+      {
+        "start_time": 60,
+        "event_type": "meal",
+        "value": 45,
+        "absorption_delay_minutes": 15,
+        "duration": 60
+      },
+      {
+        "start_time": 360,
+        "event_type": "meal",
+        "value": 70,
+        "absorption_delay_minutes": 20,
+        "duration": 90
+      },
+      {
+        "start_time": 720,
+        "event_type": "meal",
+        "value": 85,
+        "absorption_delay_minutes": 15,
+        "duration": 120
+      },
+      {
+        "start_time": 1000,
+        "event_type": "exercise",
+        "value": 0.5,
+        "duration": 45
+      }
+    ]
+  }

iints/templates/scenarios/exercise_stress.json

@@ -0,0 +1,30 @@
+{
+  "scenario_name": "Exercise Sensitivity Shift",
+  "schema_version": "1.1",
+  "scenario_version": "1.0",
+  "description": "Exercise raises insulin sensitivity mid-run. Includes ratio_change event.",
+  "stress_events": [
+    {
+      "start_time": 60,
+      "event_type": "meal",
+      "value": 60,
+      "absorption_delay_minutes": 10,
+      "duration": 60
+    },
+    {
+      "start_time": 180,
+      "event_type": "exercise",
+      "value": 0.6,
+      "duration": 45
+    },
+    {
+      "start_time": 180,
+      "event_type": "ratio_change",
+      "isf": 90,
+      "icr": 18,
+      "basal_rate": 0.3,
+      "dia_minutes": 240,
+      "duration": 180
+    }
+  ]
+}

iints/utils/__init__.py

@@ -0,0 +1,3 @@
+from .plotting import apply_plot_style
+
+__all__ = ["apply_plot_style"]