iints-sdk-python35 1.5.15__tar.gz → 1.5.16__tar.gz

{iints_sdk_python35-1.5.15/src/iints_sdk_python35.egg-info → iints_sdk_python35-1.5.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iints-sdk-python35
-Version: 1.5.15
+Version: 1.5.16
 Summary: A pre-clinical Edge-AI SDK for diabetes management validation.
 Author-email: Rune Bobbaers <rune.bobbaers@gmail.com>
 License-Expression: Apache-2.0
@@ -80,6 +80,27 @@ Open-source research platform for insulin delivery algorithm simulation and vali
 
 ---
 
+## Repository Map
+
+| Path | Purpose |
+| --- | --- |
+| `src/iints/` | installable SDK source code |
+| `docs/` | public documentation, governance, release notes, and Obsidian vault mirror |
+| `examples/` | runnable examples and notebooks |
+| `tests/` | unit, CLI, system, and realism tests |
+| `research/` | research artifacts and benchmark snapshots |
+| `tools/` | maintainer scripts for docs, CI, and release workflows |
+| `data_packs/` | small bundled/demo data packs |
+| `algorithms/` | example insulin algorithm entry points |
+
+Important starting points:
+
+- `docs/THEORY_STRESS_LAB.md` — Jetson scientific stress-test mode
+- `docs/governance/API_STABILITY.md` — semver and API policy
+- `docs/governance/PRIVACY_POLICY.md` and `docs/governance/TERMS_OF_USE.md` — public legal docs
+
+---
+
 ## What It Does
 
 - **Simulate** virtual patients across thousands of scenarios before any algorithm reaches a real device
@@ -129,5 +150,5 @@ Use `iints demo doctor` for clinical feedback conversations and `iints demo boot
 
 ---
 
-> Research software. Not a medical device. MIT Licensed.  
+> Research software. Not a medical device. Apache-2.0 licensed, with legacy MIT notices where applicable.
 > *Built by a 17-year-old with type 1 diabetes.*

{iints_sdk_python35-1.5.15 → iints_sdk_python35-1.5.16}/README.md

@@ -11,6 +11,27 @@ Open-source research platform for insulin delivery algorithm simulation and vali
 
 ---
 
+## Repository Map
+
+| Path | Purpose |
+| --- | --- |
+| `src/iints/` | installable SDK source code |
+| `docs/` | public documentation, governance, release notes, and Obsidian vault mirror |
+| `examples/` | runnable examples and notebooks |
+| `tests/` | unit, CLI, system, and realism tests |
+| `research/` | research artifacts and benchmark snapshots |
+| `tools/` | maintainer scripts for docs, CI, and release workflows |
+| `data_packs/` | small bundled/demo data packs |
+| `algorithms/` | example insulin algorithm entry points |
+
+Important starting points:
+
+- `docs/THEORY_STRESS_LAB.md` — Jetson scientific stress-test mode
+- `docs/governance/API_STABILITY.md` — semver and API policy
+- `docs/governance/PRIVACY_POLICY.md` and `docs/governance/TERMS_OF_USE.md` — public legal docs
+
+---
+
 ## What It Does
 
 - **Simulate** virtual patients across thousands of scenarios before any algorithm reaches a real device
@@ -60,5 +81,5 @@ Use `iints demo doctor` for clinical feedback conversations and `iints demo boot
 
 ---
 
-> Research software. Not a medical device. MIT Licensed.  
+> Research software. Not a medical device. Apache-2.0 licensed, with legacy MIT notices where applicable.
 > *Built by a 17-year-old with type 1 diabetes.*

{iints_sdk_python35-1.5.15 → iints_sdk_python35-1.5.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "iints-sdk-python35" 
-version = "1.5.15"
+version = "1.5.16"
 authors = [
   { name="Rune Bobbaers", email="rune.bobbaers@gmail.com" },
 ]

{iints_sdk_python35-1.5.15 → iints_sdk_python35-1.5.16}/src/iints/__init__.py

@@ -11,7 +11,7 @@ except ImportError:  # pragma: no cover - Python < 3.8 fallback
 try:
     __version__ = version("iints-sdk-python35")
 except PackageNotFoundError:  # pragma: no cover - source tree fallback
-    __version__ = "1.5.15"
+    __version__ = "1.5.16"
 
 # Note to developers: this SDK is currently maintained by a single author.
 # Please report bugs via GitHub issues and feel free to contribute fixes via PRs.

{iints_sdk_python35-1.5.15 → iints_sdk_python35-1.5.16}/src/iints/ai/__init__.py

@@ -1,5 +1,12 @@
 from .assistant import AIResponse, IINTSAssistant
 from .backends import DEFAULT_MINISTRAL_MODEL, DEFAULT_OLLAMA_HOST, OllamaBackend
+from .deterministic import (
+    DETERMINISTIC_DOSE_VERSION,
+    DeterministicDoseResult,
+    DoseSafetyLimits,
+    calculate_deterministic_dose,
+)
+from .insights import AI_INSIGHT_CONTEXT_VERSION, build_insight_context
 from .mdmp_guard import GuardResult, MDMPGuard
 from .model_catalog import (
     DEFAULT_MISTRAL_API_MODEL,
@@ -18,6 +25,12 @@ __all__ = [
     "DEFAULT_MINISTRAL_MODEL",
     "DEFAULT_OLLAMA_HOST",
     "OllamaBackend",
+    "DETERMINISTIC_DOSE_VERSION",
+    "DeterministicDoseResult",
+    "DoseSafetyLimits",
+    "calculate_deterministic_dose",
+    "AI_INSIGHT_CONTEXT_VERSION",
+    "build_insight_context",
     "GuardResult",
     "MDMPGuard",
     "DEFAULT_MISTRAL_API_MODEL",

{iints_sdk_python35-1.5.15 → iints_sdk_python35-1.5.16}/src/iints/ai/assistant.py

@@ -5,6 +5,8 @@ from pathlib import Path
 from typing import Any
 
 from .backends import DEFAULT_MINISTRAL_MODEL, CompletionBackend, MistralAPIBackend, OllamaBackend
+from .deterministic import DETERMINISTIC_DOSE_VERSION, calculate_deterministic_dose
+from .insights import build_insight_context
 from .mdmp_guard import GuardResult, MDMPGuard
 from .prompts import TaskName, build_prompt
 
@@ -16,15 +18,22 @@ class AIResponse:
     backend: str
     model: str
     certification: GuardResult
+    deterministic_result: dict[str, Any] | None = None
+    insight_context: dict[str, Any] | None = None
 
     def to_dict(self) -> dict[str, Any]:
-        return {
+        payload = {
             "task": self.task,
             "text": self.text,
             "backend": self.backend,
             "model": self.model,
             "certification": self.certification.to_dict(),
         }
+        if self.deterministic_result is not None:
+            payload["deterministic_result"] = self.deterministic_result
+        if self.insight_context is not None:
+            payload["insight_context"] = self.insight_context
+        return payload
 
 
 class IINTSAssistant:
@@ -101,6 +110,7 @@ class IINTSAssistant:
 
     def _run_task(self, task: TaskName, payload: Any) -> AIResponse:
         certification = self.guard.check()
+        insight_context = build_insight_context(task, payload)
         system_prompt, user_prompt = build_prompt(task, payload)
         text = self.guard.wrap(
             self.backend.complete(system_prompt=system_prompt, user_prompt=user_prompt)
@@ -117,6 +127,7 @@ class IINTSAssistant:
             backend=getattr(self.backend, "backend_name", type(self.backend).__name__),
             model=response_model,
             certification=certification,
+            insight_context=insight_context,
         )
 
     def explain_decision(self, step: dict[str, Any]) -> AIResponse:
@@ -128,6 +139,9 @@ class IINTSAssistant:
     def detect_anomalies(self, results: dict[str, Any]) -> AIResponse:
         return self._run_task("detect_anomalies", results)
 
+    def generate_insights(self, run: dict[str, Any]) -> AIResponse:
+        return self._run_task("generate_insights", run)
+
     def generate_report(self, run: dict[str, Any]) -> AIResponse:
         return self._run_task("generate_report", run)
 
@@ -135,4 +149,29 @@ class IINTSAssistant:
         return self._run_task("review_realism", run)
 
     def predict_insulin(self, payload: dict[str, Any]) -> AIResponse:
-        return self._run_task("predict_insulin", payload)
+        """Resolve a fixed research dose without invoking the language model.
+
+        Kept for API compatibility. The numerical result comes exclusively
+        from deterministic controller output and transparent safety guards.
+        """
+
+        certification = self.guard.check()
+        result = calculate_deterministic_dose(payload)
+        reasons = ", ".join(result.reasons)
+        text = self.guard.wrap(
+            "Deterministic research-sandbox calculation. The language model was not invoked "
+            "and has no numerical authority.\n\n"
+            f"Calculation version: {result.calculation_version}\n"
+            f"Safety hold: {str(result.safety_hold).lower()}\n"
+            f"Reasons: {reasons}\n"
+            f"FINAL_DOSE: {result.final_insulin_units:.6f}\n"
+            f"FINAL_GLUCAGON_DOSE_MG: {result.final_glucagon_mg:.6f}"
+        )
+        return AIResponse(
+            task="predict_insulin",
+            text=text,
+            backend="deterministic",
+            model=DETERMINISTIC_DOSE_VERSION,
+            certification=certification,
+            deterministic_result=result.to_dict(),
+        )

{iints_sdk_python35-1.5.15 → iints_sdk_python35-1.5.16}/src/iints/ai/backends/ollama.py

@@ -35,11 +35,19 @@ class OllamaBackend:
         model_name: str = DEFAULT_MINISTRAL_MODEL,
         base_url: str | None = None,
         timeout_seconds: float = 120.0,
+        temperature: float = 0.0,
+        top_p: float = 0.85,
+        num_predict: int = 900,
+        num_ctx: int = 8192,
     ) -> None:
         self.model_name = model_name
         raw_base_url = base_url or os.getenv("OLLAMA_HOST") or DEFAULT_OLLAMA_HOST
         self.base_url = self._validate_base_url(raw_base_url)
         self.timeout_seconds = timeout_seconds
+        self.temperature = temperature
+        self.top_p = top_p
+        self.num_predict = num_predict
+        self.num_ctx = num_ctx
         self.resolved_model_name: str | None = None
 
     @staticmethod
@@ -280,10 +288,19 @@ class OllamaBackend:
             "ready": resolved is not None,
             "pull_command": None if resolved is not None else self._pull_hint(),
             "timeout_seconds": self.timeout_seconds,
+            "generation_options": self._generation_options(),
             "server_version": version,
             "version_ok": version_ok,
         }
 
+    def _generation_options(self) -> dict[str, int | float]:
+        return {
+            "temperature": self.temperature,
+            "top_p": self.top_p,
+            "num_predict": self.num_predict,
+            "num_ctx": self.num_ctx,
+        }
+
     def smoke_test(self) -> dict[str, object]:
         resolved_model = self.ensure_model_ready()
         payload = {
@@ -328,6 +345,7 @@ class OllamaBackend:
             "system": system_prompt,
             "prompt": user_prompt,
             "stream": False,
+            "options": self._generation_options(),
         }
         last_error: Exception | None = None
         for attempt in range(2):

{iints_sdk_python35-1.5.15 → iints_sdk_python35-1.5.16}/src/iints/ai/cli.py

@@ -48,6 +48,7 @@ def _default_prepared_payload(task: str, ai_dir: Path) -> Path:
         "explain": ["step_riskiest.json", "step_latest.json"],
         "trends": ["trends_payload.json"],
         "anomalies": ["anomalies_payload.json"],
+        "insights": ["insights_payload.json", "report_payload.json"],
         "report": ["report_payload.json"],
         "review": ["review_payload.json", "report_payload.json"],
     }.get(task, [])
@@ -78,7 +79,7 @@ def _resolve_cli_inputs(
         ai_dir = input_path / "ai"
         if (
             not ai_dir.exists()
-            or not any((ai_dir / candidate).is_file() for candidate in ("report_payload.json", "trends_payload.json", "anomalies_payload.json", "step_riskiest.json", "review_payload.json"))
+            or not any((ai_dir / candidate).is_file() for candidate in ("report_payload.json", "trends_payload.json", "anomalies_payload.json", "insights_payload.json", "step_riskiest.json", "review_payload.json"))
             or (resolved_cert is None and not (ai_dir / "report.signed.mdmp").is_file())
         ):
             prepare_ai_ready_artifacts(
@@ -119,6 +120,14 @@ def _default_output_for_review(input_path: Path, output: Path | None) -> Path |
     return None
 
 
+def _default_output_for_insights(input_path: Path, output: Path | None) -> Path | None:
+    if output is not None:
+        return output
+    if input_path.is_dir():
+        return input_path / "ai" / "insights.md"
+    return None
+
+
 def _render_response(console: Console, title: str, response: AIResponse, output: Path | None) -> None:
     console.print(Panel(response.text, title=title, border_style="cyan"))
     console.print(
@@ -136,6 +145,8 @@ def _render_local_check(console: Console, status: dict[str, object]) -> None:
     ready = bool(status.get("ready"))
     resolved_model = status.get("resolved_model") or "not found"
     smoke_text = status.get("smoke_test") or "not run"
+    options = status.get("generation_options")
+    options_text = json.dumps(options, sort_keys=True) if isinstance(options, dict) else "default"
     console.print(
         Panel(
             "\n".join(
@@ -145,6 +156,7 @@ def _render_local_check(console: Console, status: dict[str, object]) -> None:
                     f"Resolved local model: {resolved_model}",
                     f"Server version: {status.get('server_version') or 'unknown'}",
                     f"Timeout (s): {status.get('timeout_seconds')}",
+                    f"Insight generation options: {options_text}",
                     f"Installed models: {installed_text}",
                     (
                         f"Pull command: {status.get('pull_command')}"
@@ -444,6 +456,48 @@ def anomalies(
         raise typer.Exit(code=1)
 
 
+@app.command(name="insights")
+def insights(
+    input_json: Annotated[Path, typer.Argument(help="Prepared run directory or JSON file with run-level simulation outputs.")],
+    mdmp_cert: Annotated[Optional[Path], typer.Option(help="Signed MDMP artifact required before AI analysis can run.")] = None,
+    mode: Annotated[str, typer.Option(help="AI backend mode. Use 'local' for Ollama/Ministral.")] = "auto",
+    model: Annotated[str, typer.Option(help="Ollama model name to use.")] = DEFAULT_MINISTRAL_MODEL,
+    minimum_grade: Annotated[str, typer.Option(help="Minimum MDMP grade required to allow analysis.")] = "research_grade",
+    public_key: Annotated[Optional[Path], typer.Option(help="Explicit MDMP public key for verification.")] = None,
+    trust_store: Annotated[Optional[Path], typer.Option(help="MDMP trust store for verification.")] = None,
+    ollama_host: Annotated[Optional[str], typer.Option(help="Override the Ollama base URL.")] = None,
+    timeout_seconds: Annotated[float, typer.Option(help="HTTP timeout for Ollama generation requests.")] = 120.0,
+    output: Annotated[Optional[Path], typer.Option(help="Optional file path to save the insight brief.")] = None,
+) -> None:
+    console = Console()
+    try:
+        resolved_input, resolved_cert, resolved_public_key = _resolve_cli_inputs(
+            task="insights",
+            input_path=input_json,
+            mdmp_cert=mdmp_cert,
+            public_key=public_key,
+            trust_store=trust_store,
+        )
+        payload = _load_json_payload(resolved_input, "Input JSON")
+        assistant = _build_assistant(
+            mdmp_cert=resolved_cert,
+            mode=mode,
+            model=model,
+            minimum_grade=minimum_grade,
+            public_key=resolved_public_key,
+            trust_store=trust_store,
+            ollama_host=ollama_host,
+            timeout_seconds=timeout_seconds,
+        )
+        resolved_output = _default_output_for_insights(input_json, output)
+        response = assistant.generate_insights(payload)
+        _write_output(resolved_output, response)
+        _render_response(console, "IINTS AI Insights", response, resolved_output)
+    except Exception as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(code=1)
+
+
 @app.command(name="report")
 def report(
     input_json: Annotated[Path, typer.Argument(help="Prepared run directory or JSON file with run-level simulation outputs.")],

iints_sdk_python35-1.5.16/src/iints/ai/deterministic.py

@@ -0,0 +1,166 @@
+"""Deterministic numerical boundaries for the optional AI assistant.
+
+The language model may explain SDK results, but it must never calculate or
+alter physiological metrics, insulin candidates, or glucagon candidates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+from typing import Any, Mapping
+
+from iints.core.safety.config import (
+    CONTROLLER_FALLING_TREND_GUARD_MGDL_MIN,
+    CONTROLLER_HIGH_IOB_GUARD_UNITS,
+    CONTROLLER_HYPO_GUARD_MGDL,
+)
+from iints.core.units import finite_value
+
+
+DETERMINISTIC_DOSE_VERSION = "iints-deterministic-dose-v1"
+_INPUT_UNITS = {
+    "mpc_recommended_units": "U/step",
+    "hard_max_insulin_units": "U/step",
+    "deterministic_glucagon_candidate_mg": "mg/step",
+    "hard_max_glucagon_mg": "mg/step",
+    "current_glucose": "mg/dL",
+    "current_glucose_mgdl": "mg/dL",
+    "predicted_glucose_30min": "mg/dL",
+    "predicted_glucose_30min_mgdl": "mg/dL",
+    "glucose_trend_mgdl_min": "mg/dL/min",
+    "glucose_trend": "mg/dL/min",
+    "insulin_on_board": "U",
+    "active_insulin": "U",
+}
+
+
+@dataclass(frozen=True)
+class DoseSafetyLimits:
+    """Fixed research-sandbox limits applied after deterministic MPC output."""
+
+    low_glucose_mgdl: float = CONTROLLER_HYPO_GUARD_MGDL
+    falling_trend_mgdl_min: float = CONTROLLER_FALLING_TREND_GUARD_MGDL_MIN
+    high_iob_units: float = CONTROLLER_HIGH_IOB_GUARD_UNITS
+
+
+@dataclass(frozen=True)
+class DeterministicDoseResult:
+    """Auditable result produced without invoking a language model."""
+
+    final_insulin_units: float
+    final_glucagon_mg: float
+    mpc_recommended_units: float
+    deterministic_glucagon_candidate_mg: float
+    safety_hold: bool
+    reasons: tuple[str, ...]
+    calculation_version: str
+    input_fingerprint_sha256: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "final_insulin_units": self.final_insulin_units,
+            "final_glucagon_mg": self.final_glucagon_mg,
+            "mpc_recommended_units": self.mpc_recommended_units,
+            "deterministic_glucagon_candidate_mg": self.deterministic_glucagon_candidate_mg,
+            "safety_hold": self.safety_hold,
+            "reasons": list(self.reasons),
+            "calculation_version": self.calculation_version,
+            "input_fingerprint_sha256": self.input_fingerprint_sha256,
+            "ai_numeric_authority": False,
+        }
+
+
+def _finite_float(payload: Mapping[str, Any], key: str, *, default: float | None = None) -> float:
+    raw = payload.get(key, default)
+    if raw is None:
+        raise ValueError(f"Missing deterministic numeric input: {key}")
+    return finite_value(raw, name=f"Deterministic numeric input '{key}'", unit=_INPUT_UNITS[key])
+
+
+def _optional_finite_float(payload: Mapping[str, Any], *keys: str) -> float | None:
+    for key in keys:
+        if key in payload and payload[key] is not None:
+            return _finite_float(payload, key)
+    return None
+
+
+def _fingerprint(payload: Mapping[str, Any]) -> str:
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def calculate_deterministic_dose(
+    payload: Mapping[str, Any],
+    *,
+    limits: DoseSafetyLimits = DoseSafetyLimits(),
+) -> DeterministicDoseResult:
+    """Resolve fixed simulation doses from deterministic controller outputs.
+
+    Insulin starts from ``mpc_recommended_units`` and can only be clamped or
+    reduced to zero by transparent safety rules. Glucagon must be supplied by a
+    deterministic controller; this function never invents a rescue dose.
+    """
+
+    mpc_units = max(0.0, _finite_float(payload, "mpc_recommended_units"))
+    insulin_cap = max(
+        0.0,
+        _finite_float(payload, "hard_max_insulin_units", default=mpc_units),
+    )
+    deterministic_glucagon = max(
+        0.0,
+        _finite_float(payload, "deterministic_glucagon_candidate_mg", default=0.0),
+    )
+    glucagon_cap = max(
+        0.0,
+        _finite_float(payload, "hard_max_glucagon_mg", default=deterministic_glucagon),
+    )
+
+    current_glucose = _optional_finite_float(payload, "current_glucose", "current_glucose_mgdl")
+    predicted_glucose = _optional_finite_float(
+        payload,
+        "predicted_glucose_30min",
+        "predicted_glucose_30min_mgdl",
+    )
+    trend = _optional_finite_float(payload, "glucose_trend_mgdl_min", "glucose_trend")
+    iob = _optional_finite_float(payload, "insulin_on_board", "active_insulin")
+
+    reasons: list[str] = []
+    safety_hold = False
+    if current_glucose is not None and current_glucose <= limits.low_glucose_mgdl:
+        safety_hold = True
+        reasons.append("current_glucose_at_or_below_fixed_guard")
+    if predicted_glucose is not None and predicted_glucose <= limits.low_glucose_mgdl:
+        safety_hold = True
+        reasons.append("predicted_glucose_at_or_below_fixed_guard")
+    if trend is not None and trend <= limits.falling_trend_mgdl_min:
+        safety_hold = True
+        reasons.append("falling_trend_at_or_below_fixed_guard")
+    if iob is not None and iob >= limits.high_iob_units:
+        safety_hold = True
+        reasons.append("iob_at_or_above_fixed_guard")
+
+    clamped_insulin = min(mpc_units, insulin_cap)
+    if clamped_insulin < mpc_units:
+        reasons.append("insulin_clamped_to_hard_cap")
+    final_insulin = 0.0 if safety_hold else clamped_insulin
+
+    final_glucagon = min(deterministic_glucagon, glucagon_cap)
+    if final_glucagon < deterministic_glucagon:
+        reasons.append("glucagon_clamped_to_hard_cap")
+    if deterministic_glucagon == 0.0:
+        reasons.append("no_deterministic_glucagon_candidate")
+    if not reasons:
+        reasons.append("deterministic_controller_candidate_accepted")
+
+    return DeterministicDoseResult(
+        final_insulin_units=final_insulin,
+        final_glucagon_mg=final_glucagon,
+        mpc_recommended_units=mpc_units,
+        deterministic_glucagon_candidate_mg=deterministic_glucagon,
+        safety_hold=safety_hold,
+        reasons=tuple(reasons),
+        calculation_version=DETERMINISTIC_DOSE_VERSION,
+        input_fingerprint_sha256=_fingerprint(payload),
+    )