iints-sdk-python35 1.1.3__py3-none-any.whl → 1.3.0__py3-none-any.whl

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.1.3"
+    __version__ = "1.3.0"
 
 # 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.
@@ -56,17 +56,24 @@ from .data.importer import (
     export_demo_csv,
     export_standard_csv,
     guess_column_mapping,
+    import_carelink_csv,
+    import_carelink_timeline,
     import_cgm_csv,
     import_cgm_dataframe,
+    load_carelink_event_log,
     load_demo_dataframe,
     scenario_from_csv,
     scenario_from_dataframe,
+    summarize_carelink_csv,
 )
 from .data.nightscout import NightscoutConfig, import_nightscout
 from .data.tidepool import TidepoolClient, load_openapi_spec
 from .data.guardians import mdmp_gate, MDMPGateError
 from .data.synthetic_mirror import generate_synthetic_mirror, SyntheticMirrorArtifact
 from .analysis.metrics import generate_benchmark_metrics # Added for benchmark
+from .analysis.booth_demo import build_booth_demo
+from .analysis.carelink_workbench import build_carelink_workbench
+from .analysis.poster import generate_results_poster
 from .analysis.reporting import ClinicalReportGenerator
 from .analysis.edge_efficiency import EnergyEstimate, estimate_energy_per_decision
 from .ai import AIResponse, IINTSAssistant, MDMPGuard
@@ -160,11 +167,15 @@ __all__ = [
     "export_demo_csv",
     "export_standard_csv",
     "guess_column_mapping",
+    "import_carelink_csv",
+    "import_carelink_timeline",
     "import_cgm_csv",
     "import_cgm_dataframe",
+    "load_carelink_event_log",
     "load_demo_dataframe",
     "scenario_from_csv",
     "scenario_from_dataframe",
+    "summarize_carelink_csv",
     "NightscoutConfig",
     "import_nightscout",
     "TidepoolClient",
@@ -175,6 +186,8 @@ __all__ = [
     "SyntheticMirrorArtifact",
     # Analysis Metrics
     "generate_benchmark_metrics",
+    "build_booth_demo",
+    "build_carelink_workbench",
     "ClinicalReportGenerator",
     "EnergyEstimate",
     "estimate_energy_per_decision",
@@ -185,6 +198,7 @@ __all__ = [
     "generate_report",
     "generate_quickstart_report",
     "generate_demo_report",
+    "generate_results_poster",
     # High-level API
     "run_simulation",
     "run_full",

iints/ai/prompts.py

@@ -8,8 +8,9 @@ TaskName = Literal["explain_decision", "analyze_trends", "detect_anomalies", "ge
 MAX_PROMPT_PAYLOAD_CHARS = 12000
 
 SYSTEM_PROMPT = (
-    "You are the IINTS-AF research assistant for closed-loop insulin delivery simulations. "
-    "Explain simulation behavior clearly, conservatively, and in plain language. "
+    "You are the IINTS-AF research assistant for closed-loop insulin delivery simulations "
+    "and imported glucose datasets. "
+    "Explain glycemic behavior clearly, conservatively, and in plain language. "
     "Do not give medical advice, treatment instructions, or patient-specific recommendations. "
     "State uncertainty when the input is incomplete. "
     "For research use only."
@@ -17,39 +18,39 @@ SYSTEM_PROMPT = (
 
 TASK_TEMPLATES: dict[TaskName, str] = {
     "explain_decision": (
-        "Given this single simulation step, explain:\n"
-        "1. What the algorithm decided and why\n"
-        "2. Whether the independent safety supervisor likely intervened\n"
-        "3. Whether the decision appears safe in context\n\n"
+        "Given this single decision step or noteworthy glucose snapshot, explain:\n"
+        "1. What is happening in the data and why it stands out\n"
+        "2. Whether there are safety signals, supervision, or notable context clues\n"
+        "3. What a research user should pay attention to next\n\n"
         "Respond in 3 short paragraphs.\n\n"
-        "Simulation step JSON:\n{data}"
+        "Input JSON:\n{data}"
     ),
     "analyze_trends": (
-        "Review this glucose-oriented simulation payload and summarize the main glycemic trends.\n"
+        "Review this glucose-oriented payload and summarize the main glycemic trends.\n"
         "Focus on direction, stability, excursions, and likely triggers.\n"
         "Respond with:\n"
         "- Trend summary\n"
         "- Main risk signals\n"
         "- Short operational takeaway\n\n"
-        "Simulation payload JSON:\n{data}"
+        "Payload JSON:\n{data}"
     ),
     "detect_anomalies": (
-        "Inspect this run summary and identify unusual patterns, inconsistent values, or clinically relevant anomalies.\n"
+        "Inspect this run or imported-data summary and identify unusual patterns, inconsistent values, or clinically relevant anomalies.\n"
         "Respond with:\n"
         "- Detected anomalies\n"
         "- Why each anomaly matters\n"
         "- Whether follow-up validation is recommended\n\n"
-        "Run summary JSON:\n{data}"
+        "Summary JSON:\n{data}"
     ),
     "generate_report": (
-        "Write a concise markdown report for this IINTS-AF simulation run.\n"
+        "Write a concise markdown report for this IINTS-AF simulation run or imported personal glucose dataset.\n"
         "Include sections:\n"
         "1. Executive summary\n"
         "2. Glycemic behavior\n"
-        "3. Safety and supervisor behavior\n"
-        "4. Notable events or anomalies\n"
+        "3. Safety, supervision, or device behavior\n"
+        "4. Notable events, patterns, or anomalies\n"
         "5. Research-only conclusion\n\n"
-        "Simulation run JSON:\n{data}"
+        "Input JSON:\n{data}"
     ),
 }
 

iints/analysis/__init__.py

@@ -1,12 +1,18 @@
 from .clinical_metrics import ClinicalMetricsCalculator, ClinicalMetricsResult
 from .baseline import compute_metrics, run_baseline_comparison, write_baseline_comparison
+from .booth_demo import build_booth_demo
+from .carelink_workbench import build_carelink_workbench
+from .poster import generate_results_poster
 from .reporting import ClinicalReportGenerator
 
 __all__ = [
+    "build_booth_demo",
+    "build_carelink_workbench",
     "ClinicalMetricsCalculator",
     "ClinicalMetricsResult",
     "ClinicalReportGenerator",
     "compute_metrics",
+    "generate_results_poster",
     "run_baseline_comparison",
     "write_baseline_comparison",
 ]

iints/analysis/booth_demo.py

@@ -0,0 +1,439 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from iints.ai.prepare import prepare_ai_ready_artifacts
+from iints.analysis.poster import generate_results_poster
+from iints.core.algorithms.mock_algorithms import RunawayAIAlgorithm
+from iints.core.algorithms.pid_controller import PIDController
+from iints.highlevel import run_full
+
+
+@dataclass(frozen=True)
+class BoothScenarioSpec:
+    slug: str
+    label: str
+    headline: str
+    jury_takeaway: str
+    scenario: dict[str, Any]
+    algorithm_factory: Callable[[], Any]
+
+
+def _scenario_specs() -> list[BoothScenarioSpec]:
+    return [
+        BoothScenarioSpec(
+            slug="01_normal_run",
+            label="Normal Run",
+            headline="The controller keeps glucose in range during a calm day.",
+            jury_takeaway=(
+                "This is the control case. It shows the SDK can simulate a realistic closed-loop day "
+                "and produce clean, auditable outputs."
+            ),
+            scenario={
+                "scenario_name": "Booth Demo - Normal Run",
+                "schema_version": "1.1",
+                "scenario_version": "1.0",
+                "description": "A calm day with one moderate meal to show normal controller behavior.",
+                "stress_events": [
+                    {
+                        "start_time": 45,
+                        "event_type": "meal",
+                        "value": 35,
+                        "reported_value": 35,
+                        "absorption_delay_minutes": 10,
+                        "duration": 45,
+                    }
+                ],
+            },
+            algorithm_factory=PIDController,
+        ),
+        BoothScenarioSpec(
+            slug="02_meal_stress_test",
+            label="Meal Stress Test",
+            headline="The controller reacts to a harder day with meals and exercise.",
+            jury_takeaway=(
+                "This is the stress case. We deliberately add larger disturbances and show that the "
+                "system remains explainable and clinically readable."
+            ),
+            scenario={
+                "scenario_name": "Booth Demo - Meal Stress Test",
+                "schema_version": "1.1",
+                "scenario_version": "1.0",
+                "description": "Two meal challenges plus exercise to stress the controller.",
+                "stress_events": [
+                    {
+                        "start_time": 45,
+                        "event_type": "meal",
+                        "value": 70,
+                        "reported_value": 70,
+                        "absorption_delay_minutes": 15,
+                        "duration": 75,
+                    },
+                    {
+                        "start_time": 150,
+                        "event_type": "meal",
+                        "value": 45,
+                        "reported_value": 45,
+                        "absorption_delay_minutes": 10,
+                        "duration": 50,
+                    },
+                    {
+                        "start_time": 210,
+                        "event_type": "exercise",
+                        "value": 0.5,
+                        "duration": 35,
+                    },
+                ],
+            },
+            algorithm_factory=PIDController,
+        ),
+        BoothScenarioSpec(
+            slug="03_supervisor_override",
+            label="Supervisor Override",
+            headline="A deliberately unsafe AI is blocked by the safety supervisor.",
+            jury_takeaway=(
+                "This is the safety case. We intentionally use a bad algorithm so the audience can see "
+                "that the supervisor prevents dangerous insulin commands and records why."
+            ),
+            scenario={
+                "scenario_name": "Booth Demo - Supervisor Override",
+                "schema_version": "1.1",
+                "scenario_version": "1.0",
+                "description": "A chaos run that forces unsafe insulin requests during a falling glucose phase.",
+                "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,
+                    },
+                ],
+            },
+            algorithm_factory=lambda: RunawayAIAlgorithm(max_bolus=5.0),
+        ),
+    ]
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def _write_text(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _build_jury_brief(
+    *,
+    output_dir: Path,
+    scenario_specs: list[BoothScenarioSpec],
+    poster_png: Path,
+    poster_summary_json: Path,
+    run_outputs: dict[str, dict[str, Any]],
+    ai_outputs: dict[str, str],
+    ai_status: str,
+) -> str:
+    lines: list[str] = [
+        "# IINTS-AF Booth Demo",
+        "",
+        "## 30-second intro",
+        "",
+        (
+            "IINTS-AF is a safety-first SDK for testing insulin-delivery algorithms. "
+            "In this demo we show three stories: normal control, stress handling, and a safety supervisor "
+            "blocking an unsafe AI recommendation."
+        ),
+        "",
+        "## Live flow",
+        "",
+        "1. Run the script and point out that it creates three full simulation bundles.",
+        f"2. Open the poster: `{poster_png}`",
+        "3. Walk the jury left to right: normal run, stress test, supervisor override.",
+        "4. Show that each run also has results CSV, audit trail, PDF report, and manifest.",
+        "5. Optionally show the local AI explanation on the supervisor run.",
+        "",
+        "## What to say per panel",
+        "",
+    ]
+    for spec in scenario_specs:
+        outputs = run_outputs[spec.slug]
+        lines.extend(
+            [
+                f"### {spec.label}",
+                "",
+                f"- Headline: {spec.headline}",
+                f"- Why it matters: {spec.jury_takeaway}",
+                f"- Run directory: `{outputs['output_dir']}`",
+                f"- Results CSV: `{outputs['results_csv']}`",
+                f"- PDF report: `{outputs['report_pdf']}`",
+                "",
+            ]
+        )
+
+    lines.extend(
+        [
+            "## Optional AI step",
+            "",
+            ai_status,
+            "",
+            "If local Ollama + Ministral are ready, run:",
+            "",
+            "```bash",
+            "iints ai local-check --model ministral-3:3b",
+            f"iints ai report {run_outputs['03_supervisor_override']['output_dir']} --model ministral-3:3b",
+            f"iints ai explain {run_outputs['03_supervisor_override']['output_dir']} --model ministral-3:3b",
+            "```",
+            "",
+            "## Key artifacts",
+            "",
+            f"- Poster PNG: `{poster_png}`",
+            f"- Poster summary: `{poster_summary_json}`",
+            f"- Demo summary JSON: `{output_dir / 'demo_summary.json'}`",
+            f"- Demo commands: `{output_dir / 'run_commands.md'}`",
+        ]
+    )
+
+    if ai_outputs:
+        lines.extend(
+            [
+                "",
+                "### AI-ready artifacts",
+                "",
+            ]
+        )
+        for key, value in ai_outputs.items():
+            lines.append(f"- {key}: `{value}`")
+
+    return "\n".join(lines) + "\n"
+
+
+def _build_commands_markdown(
+    *,
+    output_dir: Path,
+    example_script: Path,
+    run_outputs: dict[str, dict[str, Any]],
+) -> str:
+    supervisor_dir = run_outputs["03_supervisor_override"]["output_dir"]
+    return (
+        "# Booth Demo Commands\n\n"
+        "## Run from source tree\n\n"
+        "```bash\n"
+        f"PYTHONPATH=src python3 {example_script} --output-dir {output_dir}\n"
+        "```\n\n"
+        "## Run via installed CLI\n\n"
+        "```bash\n"
+        f"iints demo-booth --output-dir {output_dir}\n"
+        "```\n\n"
+        "## Optional local AI explanation\n\n"
+        "```bash\n"
+        "iints ai local-check --model ministral-3:3b\n"
+        f"iints ai report {supervisor_dir} --model ministral-3:3b\n"
+        f"iints ai explain {supervisor_dir} --model ministral-3:3b\n"
+        "```\n"
+    )
+
+
+def _build_live_demo_script_text(
+    *,
+    output_dir: Path,
+    poster_png: Path,
+    run_outputs: dict[str, dict[str, Any]],
+) -> str:
+    return (
+        "IINTS-AF BOOTH LIVE DEMO SCRIPT\n"
+        "===============================\n\n"
+        "1. WHAT CODE TO SHOW FIRST\n"
+        "- Show examples/demos/06_booth_demo.py first.\n"
+        "  Reason: it is the shortest, clearest orchestration file and shows the whole story in one screen.\n"
+        "- If someone asks how it really works, open src/iints/analysis/booth_demo.py.\n"
+        "  Reason: that file defines the three scenarios and writes the poster, talk track, and run bundle outputs.\n\n"
+        "2. LIVE COMMAND TO RUN\n"
+        "- From the repository root, run:\n"
+        "  ./scripts/run_booth_demo.sh\n"
+        "- Or use the installed CLI:\n"
+        "  iints demo-booth --output-dir results/booth_demo\n\n"
+        "3. WHAT TO SAY WHILE IT RUNS\n"
+        "- IINTS-AF is a safety-first SDK for testing insulin-delivery algorithms before real-world use.\n"
+        "- This demo generates three reproducible scenarios: a normal run, a stress test, and a supervisor override case.\n"
+        "- Every scenario produces real artifacts: CSV, PDF, audit trail, baseline comparison, and a manifest.\n\n"
+        "4. WHAT TO OPEN AFTER THE RUN\n"
+        f"- Open the poster: {poster_png}\n"
+        f"- Normal run folder: {run_outputs['01_normal_run']['output_dir']}\n"
+        f"- Meal stress folder: {run_outputs['02_meal_stress_test']['output_dir']}\n"
+        f"- Supervisor folder: {run_outputs['03_supervisor_override']['output_dir']}\n\n"
+        "5. JURY WALKTHROUGH\n"
+        "- Panel 1: Normal Run\n"
+        "  Say: this is the control case. The algorithm keeps glucose in a clinically readable range.\n"
+        "- Panel 2: Meal Stress Test\n"
+        "  Say: here we add larger disturbances and show that the system stays explainable under stress.\n"
+        "- Panel 3: Supervisor Override\n"
+        "  Say: here we intentionally use a bad AI policy so the safety supervisor can prove it blocks unsafe insulin.\n\n"
+        "6. OPTIONAL AI STEP\n"
+        "- If Ollama is ready, run:\n"
+        "  iints ai local-check --model ministral-3:3b\n"
+        f"  iints ai report {run_outputs['03_supervisor_override']['output_dir']} --model ministral-3:3b\n"
+        f"  iints ai explain {run_outputs['03_supervisor_override']['output_dir']} --model ministral-3:3b\n"
+        "- Say: the local model explains the result, but only after the SDK has prepared the run artifacts.\n\n"
+        "7. IF THE JURY ASKS WHY THIS MATTERS\n"
+        "- It is not just a graph generator.\n"
+        "- It is a reproducible safety workflow: simulate, stress, audit, visualize, explain.\n"
+        "- The supervisor case is the key proof that the SDK is safety-first, not just AI-first.\n\n"
+        "8. HANDY FILES\n"
+        f"- Poster PNG: {poster_png}\n"
+        f"- Jury markdown: {output_dir / 'JURY_TALK_TRACK.md'}\n"
+        f"- Demo commands: {output_dir / 'run_commands.md'}\n"
+        f"- Demo summary JSON: {output_dir / 'demo_summary.json'}\n"
+    )
+
+
+def build_booth_demo(
+    output_dir: str | Path = "./results/booth_demo",
+    *,
+    duration_minutes: int = 360,
+    time_step: int = 5,
+    seed: int = 42,
+    prepare_ai: bool = True,
+    create_dev_mdmp_cert: bool = True,
+) -> dict[str, str]:
+    """
+    Create a fair-ready demo bundle with three scenario runs, a poster, and jury notes.
+    """
+    resolved_output = Path(output_dir).expanduser().resolve()
+    resolved_output.mkdir(parents=True, exist_ok=True)
+
+    specs = _scenario_specs()
+    run_outputs: dict[str, dict[str, Any]] = {}
+    run_dirs: list[Path] = []
+    labels: list[str] = []
+
+    for spec in specs:
+        run_dir = resolved_output / spec.slug
+        outputs = run_full(
+            algorithm=spec.algorithm_factory(),
+            scenario=spec.scenario,
+            patient_config="default_patient",
+            duration_minutes=duration_minutes,
+            time_step=time_step,
+            seed=seed,
+            output_dir=run_dir,
+            enable_profiling=False,
+        )
+        run_outputs[spec.slug] = {
+            "label": spec.label,
+            "headline": spec.headline,
+            "jury_takeaway": spec.jury_takeaway,
+            "output_dir": str(run_dir),
+            "results_csv": str(outputs["results_csv"]),
+            "report_pdf": str(outputs["report_pdf"]),
+            "run_manifest_path": str(outputs["run_manifest_path"]),
+        }
+        run_dirs.append(run_dir)
+        labels.append(spec.label)
+
+    poster_outputs = generate_results_poster(
+        run_dirs=run_dirs,
+        labels=labels,
+        output_path=resolved_output / "booth_demo_poster.png",
+        summary_output_path=resolved_output / "booth_demo_poster.json",
+        poster_title="288 Decisions. Every Day. We Test Them All.",
+        subtitle="Normal control, stress handling, and safety override in one fair-ready story.",
+    )
+
+    ai_outputs: dict[str, str] = {}
+    ai_status = "AI preparation was skipped."
+    if prepare_ai:
+        supervisor_dir = run_dirs[-1]
+        try:
+            ai_outputs = prepare_ai_ready_artifacts(
+                supervisor_dir,
+                create_dev_mdmp_cert=create_dev_mdmp_cert,
+            )
+            if "mdmp_cert" in ai_outputs:
+                ai_status = (
+                    "AI-ready payloads and a local development MDMP certificate were generated for the "
+                    "Supervisor Override run."
+                )
+            else:
+                ai_status = "AI-ready payloads were generated for the Supervisor Override run."
+        except Exception as exc:
+            ai_status = f"AI preparation did not block the demo, but it could not finish cleanly: {exc}"
+
+    summary_payload = {
+        "output_dir": str(resolved_output),
+        "duration_minutes": duration_minutes,
+        "time_step_minutes": time_step,
+        "seed": seed,
+        "poster_png": poster_outputs["poster_png"],
+        "poster_summary_json": poster_outputs["summary_json"],
+        "ai_status": ai_status,
+        "scenarios": [
+            {
+                "slug": spec.slug,
+                "label": spec.label,
+                "headline": spec.headline,
+                "jury_takeaway": spec.jury_takeaway,
+                "scenario_name": spec.scenario["scenario_name"],
+                **run_outputs[spec.slug],
+            }
+            for spec in specs
+        ],
+    }
+    _write_json(resolved_output / "demo_summary.json", summary_payload)
+
+    example_script = Path("examples/demos/06_booth_demo.py")
+    commands_markdown = _build_commands_markdown(
+        output_dir=resolved_output,
+        example_script=example_script,
+        run_outputs=run_outputs,
+    )
+    commands_path = resolved_output / "run_commands.md"
+    _write_text(commands_path, commands_markdown)
+
+    live_demo_script_text = _build_live_demo_script_text(
+        output_dir=resolved_output,
+        poster_png=Path(poster_outputs["poster_png"]),
+        run_outputs=run_outputs,
+    )
+    live_demo_script_path = resolved_output / "BEURS_LIVE_DEMO_SCRIPT.txt"
+    _write_text(live_demo_script_path, live_demo_script_text)
+
+    jury_brief = _build_jury_brief(
+        output_dir=resolved_output,
+        scenario_specs=specs,
+        poster_png=Path(poster_outputs["poster_png"]),
+        poster_summary_json=Path(poster_outputs["summary_json"]),
+        run_outputs=run_outputs,
+        ai_outputs=ai_outputs,
+        ai_status=ai_status,
+    )
+    jury_brief_path = resolved_output / "JURY_TALK_TRACK.md"
+    _write_text(jury_brief_path, jury_brief)
+
+    artifact_paths: dict[str, str] = {
+        "output_dir": str(resolved_output),
+        "poster_png": poster_outputs["poster_png"],
+        "poster_summary_json": poster_outputs["summary_json"],
+        "demo_summary_json": str(resolved_output / "demo_summary.json"),
+        "jury_talk_track": str(jury_brief_path),
+        "run_commands": str(commands_path),
+        "live_demo_script": str(live_demo_script_path),
+    }
+    for spec in specs:
+        artifact_paths[f"{spec.slug}_dir"] = run_outputs[spec.slug]["output_dir"]
+    artifact_paths.update(ai_outputs)
+    return artifact_paths