iints-sdk-python35 1.5.2__py3-none-any.whl → 1.5.4__py3-none-any.whl

iints/__init__.py

@@ -1,7 +1,7 @@
 # src/iints/__init__.py
 
 import pandas as pd # Required for type hints like pd.DataFrame
-from typing import Optional
+from typing import Any, Optional
 
 try:
     from importlib.metadata import PackageNotFoundError, version
@@ -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.2"
+    __version__ = "1.5.4"
 
 # 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.
@@ -95,9 +95,26 @@ from .live_patient import (
     summarize_edge_workspace,
     write_edge_update_script,
 )
-from .highlevel import run_simulation, run_full, run_population
 from .scenarios import ScenarioGeneratorConfig, generate_random_scenario
 
+
+def run_simulation(*args: Any, **kwargs: Any) -> Any:
+    from .highlevel import run_simulation as _run_simulation
+
+    return _run_simulation(*args, **kwargs)
+
+
+def run_full(*args: Any, **kwargs: Any) -> Any:
+    from .highlevel import run_full as _run_full
+
+    return _run_full(*args, **kwargs)
+
+
+def run_population(*args: Any, **kwargs: Any) -> Any:
+    from .highlevel import run_population as _run_population
+
+    return _run_population(*args, **kwargs)
+
 try:
     from .analysis.booth_demo import build_booth_demo
 except Exception as exc:  # pragma: no cover - optional reports stack

iints/ai/cli.py

@@ -160,7 +160,7 @@ def _render_local_check(console: Console, status: dict[str, object]) -> None:
         console.print("[bold red]Ollama is too old for the open Ministral 3 runtime.[/bold red]")
 
 
-@app.command("models")
+@app.command(name="models")
 def models() -> None:
     console = Console()
     table = Table(title="IINTS AI Local Mistral Model Guide")
@@ -189,7 +189,7 @@ def models() -> None:
     )
 
 
-@app.command("prepare")
+@app.command(name="prepare")
 def prepare(
     run_dir: Annotated[Path, typer.Argument(help="Run output directory containing results.csv and run_metadata.json.")],
     create_dev_mdmp_cert: Annotated[
@@ -254,7 +254,7 @@ def _build_assistant(
     )
 
 
-@app.command("local-check")
+@app.command(name="local-check")
 def local_check(
     model: Annotated[str, typer.Option(help="Ollama model name to validate locally.")] = DEFAULT_MINISTRAL_MODEL,
     ollama_host: Annotated[Optional[str], typer.Option(help="Override the Ollama base URL.")] = None,
@@ -294,7 +294,7 @@ def local_check(
         raise typer.Exit(code=1)
 
 
-@app.command("explain")
+@app.command(name="explain")
 def explain(
     input_json: Annotated[Path, typer.Argument(help="Prepared run directory or JSON file with a single simulation step or decision context.")],
     mdmp_cert: Annotated[Optional[Path], typer.Option(help="Signed MDMP artifact required before AI analysis can run.")] = None,
@@ -335,7 +335,7 @@ def explain(
         raise typer.Exit(code=1)
 
 
-@app.command("trends")
+@app.command(name="trends")
 def trends(
     input_json: Annotated[Path, typer.Argument(help="Prepared run directory or JSON file with glucose trace data or a run payload.")],
     mdmp_cert: Annotated[Optional[Path], typer.Option(help="Signed MDMP artifact required before AI analysis can run.")] = None,
@@ -376,7 +376,7 @@ def trends(
         raise typer.Exit(code=1)
 
 
-@app.command("anomalies")
+@app.command(name="anomalies")
 def anomalies(
     input_json: Annotated[Path, typer.Argument(help="Prepared run directory or JSON file with simulation results or run summary.")],
     mdmp_cert: Annotated[Optional[Path], typer.Option(help="Signed MDMP artifact required before AI analysis can run.")] = None,
@@ -417,7 +417,7 @@ def anomalies(
         raise typer.Exit(code=1)
 
 
-@app.command("report")
+@app.command(name="report")
 def report(
     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,
@@ -458,7 +458,7 @@ def report(
         raise typer.Exit(code=1)
 
 
-@app.command("review")
+@app.command(name="review")
 def review(
     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,

iints/analysis/__init__.py

@@ -1,10 +1,26 @@
 from .clinical_metrics import ClinicalMetricsCalculator, ClinicalMetricsResult
 from .baseline import compute_metrics, run_baseline_comparison, write_baseline_comparison
+from .study_engine import (
+    StudyAlgorithmSpec,
+    StudyArmSpec,
+    StudyDesignPayload,
+    StudyMatrixRow,
+    StudyProfileSpec,
+    build_algorithm_registry,
+    build_study_design_payload,
+    resolve_profile_specs,
+)
 from .study_protocol import (
     build_study_protocol_payload,
     render_study_protocol_markdown,
     write_study_protocol_bundle,
 )
+from .study_experiment import (
+    StudyExperimentConfig,
+    build_study_experiment_template,
+    load_study_experiment_config,
+    render_study_experiment_yaml,
+)
 from .study_analysis import (
     analyze_run_directory,
     analyze_study_directory,
@@ -15,6 +31,15 @@ from .study_analysis import (
     StudyRunSummary,
     StudySummary,
 )
+from .eucys_results import (
+    build_eucys_abstract_draft_markdown,
+    build_eucys_filled_abstract_markdown,
+    build_eucys_jury_qa_markdown,
+    build_eucys_limitations_and_ethics_markdown,
+    build_eucys_poster_outline_markdown,
+    generate_eucys_main_figure,
+    generate_eucys_results_bundle,
+)
 
 
 def _missing_reports_dependency(feature: str, exc: Exception) -> None:
@@ -80,15 +105,34 @@ __all__ = [
     "ClinicalReportGenerator",
     "compute_metrics",
     "compare_studies",
+    "build_eucys_abstract_draft_markdown",
+    "build_eucys_filled_abstract_markdown",
+    "build_eucys_jury_qa_markdown",
+    "build_eucys_limitations_and_ethics_markdown",
+    "build_eucys_poster_outline_markdown",
+    "generate_eucys_main_figure",
+    "resolve_profile_specs",
+    "generate_eucys_results_bundle",
     "generate_results_poster",
     "generate_study_poster",
+    "build_algorithm_registry",
+    "build_study_design_payload",
     "build_study_protocol_payload",
+    "build_study_experiment_template",
     "render_study_protocol_markdown",
+    "render_study_experiment_yaml",
     "write_study_protocol_bundle",
+    "load_study_experiment_config",
     "load_study_summary",
     "quality_badges_for_metrics",
     "run_baseline_comparison",
+    "StudyAlgorithmSpec",
+    "StudyArmSpec",
     "StudyComparison",
+    "StudyDesignPayload",
+    "StudyExperimentConfig",
+    "StudyMatrixRow",
+    "StudyProfileSpec",
     "StudyRunSummary",
     "StudySummary",
     "write_baseline_comparison",

iints/analysis/baseline.py

@@ -8,10 +8,12 @@ import pandas as pd
 
 from iints.analysis.clinical_metrics import ClinicalMetricsCalculator
 from iints.api.base_algorithm import InsulinAlgorithm
+from iints.core.algorithms.clinical_baseline import ClinicalBaselineAlgorithm
 from iints.core.algorithms.pid_controller import PIDController
 from iints.core.algorithms.standard_pump_algo import StandardPumpAlgorithm
 from iints.core.patient.models import PatientModel
 from iints.core.simulator import Simulator
+from iints.utils.csv_safety import sanitize_csv_dataframe
 from iints.validation import build_stress_events
 
 
@@ -50,7 +52,10 @@ def run_baseline_comparison(
         }
     )
 
-    baselines: List[Tuple[str, InsulinAlgorithm]] = [("Standard PID", PIDController())]
+    baselines: List[Tuple[str, InsulinAlgorithm]] = [
+        ("Clinical Baseline", ClinicalBaselineAlgorithm()),
+        ("Standard PID", PIDController()),
+    ]
     if compare_standard_pump:
         baselines.append(("Standard Pump", StandardPumpAlgorithm()))
 
@@ -88,5 +93,5 @@ def write_baseline_comparison(comparison: Dict[str, Any], output_dir: Path) -> D
     json_path = output_dir / "baseline_comparison.json"
     csv_path = output_dir / "baseline_comparison.csv"
     json_path.write_text(json.dumps(comparison, indent=2))
-    pd.DataFrame(comparison.get("rows", [])).to_csv(csv_path, index=False)
+    sanitize_csv_dataframe(pd.DataFrame(comparison.get("rows", []))).to_csv(csv_path, index=False)
     return {"json": str(json_path), "csv": str(csv_path)}

iints/analysis/booth_demo.py

@@ -9,6 +9,7 @@ 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.core.safety.config import SafetyConfig
 from iints.highlevel import run_full
 
 
@@ -22,6 +23,17 @@ class BoothScenarioSpec:
     algorithm_factory: Callable[[], Any]
 
 
+@dataclass(frozen=True)
+class ShowcaseRunSpec:
+    run_dir: Path
+    algorithm_factory: Callable[[], Any]
+    algorithm_name: str
+    algorithm_role: str
+    study_arm: str
+    condition_group: str
+    supervisor_enabled: bool
+
+
 def _scenario_specs() -> list[BoothScenarioSpec]:
     return [
         BoothScenarioSpec(
@@ -138,6 +150,269 @@ def _write_text(path: Path, content: str) -> None:
     path.write_text(content, encoding="utf-8")
 
 
+def _booth_profile_id(patient_config: str | Path | dict[str, Any]) -> str:
+    if isinstance(patient_config, dict):
+        return str(patient_config.get("patient_name") or patient_config.get("profile_id") or "booth_demo_patient")
+    if isinstance(patient_config, Path):
+        return patient_config.stem
+    return Path(str(patient_config)).stem if str(patient_config).endswith(".json") else str(patient_config)
+
+
+def _booth_supervisor_off_safety_config() -> SafetyConfig:
+    return SafetyConfig(
+        min_glucose=10.0,
+        max_glucose=1000.0,
+        max_glucose_delta_per_5_min=250.0,
+        hypoglycemia_threshold=-1000.0,
+        severe_hypoglycemia_threshold=-1000.0,
+        hyperglycemia_threshold=10000.0,
+        max_insulin_per_bolus=1000.0,
+        glucose_rate_alarm=-1000.0,
+        max_insulin_per_hour=1000.0,
+        max_iob=1000.0,
+        trend_stop=-1000.0,
+        hypo_cutoff=-1000.0,
+        predicted_hypoglycemia_threshold=-1000.0,
+        predictor_uncertainty_gate_enabled=False,
+        predictor_ood_gate_enabled=False,
+        contract_enabled=False,
+        critical_glucose_threshold=-1000.0,
+        critical_glucose_duration_minutes=100000,
+    )
+
+
+def _annotate_showcase_run(
+    run_dir: Path,
+    *,
+    study_arm: str,
+    condition_group: str,
+    algorithm_name: str,
+    algorithm_role: str,
+    profile_id: str,
+    scenario_slug: str,
+    supervisor_enabled: bool,
+) -> None:
+    from iints.analysis.study_engine import slugify_study_token
+
+    algorithm_id = slugify_study_token(algorithm_name)
+    for candidate in (run_dir / "run_metadata.json", run_dir / "config.json"):
+        payload: dict[str, Any]
+        if candidate.is_file():
+            payload = json.loads(candidate.read_text(encoding="utf-8"))
+        else:
+            payload = {}
+
+        if candidate.name == "run_metadata.json":
+            config = payload.get("config", {}) if isinstance(payload.get("config"), dict) else {}
+        else:
+            config = payload if isinstance(payload, dict) else {}
+
+        config["study_condition"] = study_arm
+        config["study_arm"] = study_arm
+        config["condition_group"] = condition_group
+        config["study_protocol_preset"] = "showcase_demo"
+        config["algorithm_id"] = algorithm_id
+        config["algorithm_role"] = algorithm_role
+        config["profile_id"] = profile_id
+        config["scenario_slug"] = scenario_slug
+        config["supervisor_enabled"] = supervisor_enabled
+        config["corruption_modes"] = []
+        scenario_payload = config.get("scenario", {}) if isinstance(config.get("scenario"), dict) else {}
+        scenario_payload["condition_group"] = condition_group
+        scenario_payload["study_arm"] = study_arm
+        scenario_payload["study_protocol_preset"] = "showcase_demo"
+        scenario_payload["scenario_slug"] = scenario_slug
+        scenario_payload["supervisor_enabled"] = supervisor_enabled
+        config["scenario"] = scenario_payload
+
+        if candidate.name == "run_metadata.json":
+            payload["config"] = config
+            payload["algorithm_id"] = algorithm_id
+            payload["algorithm_role"] = algorithm_role
+            payload["profile_id"] = profile_id
+        else:
+            payload = config
+
+        candidate.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def _write_showcase_research_sync(
+    *,
+    output_dir: Path,
+    patient_config: str | Path | dict[str, Any],
+    duration_minutes: int,
+    time_step: int,
+    seed: int,
+    ai_status: str,
+) -> dict[str, str]:
+    from iints.analysis.study_analysis import analyze_study_directory, compare_studies
+    from iints.analysis.study_poster import generate_study_poster
+
+    profile_id = _booth_profile_id(patient_config)
+    showcase_dir = output_dir / "showcase_study"
+    baseline_dir = showcase_dir / "baseline_reference" / "pid_supervisor_override"
+    candidate_on_dir = showcase_dir / "candidate_safety_on" / "runaway_supervisor_override"
+    candidate_off_dir = showcase_dir / "candidate_safety_off" / "runaway_supervisor_override"
+
+    supervisor_spec = next(spec for spec in _scenario_specs() if spec.slug == "03_supervisor_override")
+    showcase_runs = [
+        ShowcaseRunSpec(
+            run_dir=baseline_dir,
+            algorithm_factory=PIDController,
+            algorithm_name="PID Controller",
+            algorithm_role="baseline",
+            study_arm="showcase_baseline_vs_candidate",
+            condition_group="showcase_baseline_vs_candidate",
+            supervisor_enabled=True,
+        ),
+        ShowcaseRunSpec(
+            run_dir=candidate_on_dir,
+            algorithm_factory=supervisor_spec.algorithm_factory,
+            algorithm_name="Runaway AI Candidate",
+            algorithm_role="candidate",
+            study_arm="showcase_baseline_vs_candidate",
+            condition_group="showcase_baseline_vs_candidate",
+            supervisor_enabled=True,
+        ),
+        ShowcaseRunSpec(
+            run_dir=candidate_off_dir,
+            algorithm_factory=supervisor_spec.algorithm_factory,
+            algorithm_name="Runaway AI Candidate",
+            algorithm_role="candidate",
+            study_arm="showcase_candidate_safety_off",
+            condition_group="showcase_candidate_safety_off",
+            supervisor_enabled=False,
+        ),
+    ]
+
+    for run_spec in showcase_runs:
+        run_full(
+            algorithm=run_spec.algorithm_factory(),
+            scenario=supervisor_spec.scenario,
+            patient_config=patient_config,
+            duration_minutes=duration_minutes,
+            time_step=time_step,
+            seed=seed,
+            output_dir=run_spec.run_dir,
+            safety_config=None if run_spec.supervisor_enabled else _booth_supervisor_off_safety_config(),
+            enable_profiling=False,
+        )
+        _annotate_showcase_run(
+            run_spec.run_dir,
+            study_arm=run_spec.study_arm,
+            condition_group=run_spec.condition_group,
+            algorithm_name=run_spec.algorithm_name,
+            algorithm_role=run_spec.algorithm_role,
+            profile_id=profile_id,
+            scenario_slug="showcase_supervisor_override",
+            supervisor_enabled=run_spec.supervisor_enabled,
+        )
+
+    summary = analyze_study_directory(showcase_dir)
+    payload = summary.to_dict()
+    summary_json = showcase_dir / "showcase_study_summary.json"
+    summary_md = showcase_dir / "showcase_study_summary.md"
+    summary_json.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    summary_md.write_text(
+        "# Showcase Research Sync\n\n"
+        "This mini-study mirrors the benchmark story used elsewhere in the SDK.\n\n"
+        f"- Profile: `{profile_id}`\n"
+        "- Scenario: `showcase_supervisor_override`\n"
+        "- Baseline: `PID Controller`\n"
+        "- Candidate: `Runaway AI Candidate`\n"
+        "- Safety comparison: candidate with supervisor on vs candidate with supervisor off\n",
+        encoding="utf-8",
+    )
+
+    poster_outputs = generate_study_poster(
+        summary,
+        output_path=showcase_dir / "showcase_study_poster.png",
+        title="IINTS Showcase Benchmark Sync",
+        subtitle="Baseline vs candidate, plus safety-on vs safety-off, with the same metrics used in study bundles.",
+        summary_output_path=showcase_dir / "showcase_study_poster.json",
+    )
+
+    baseline_vs_candidate = compare_studies(baseline_dir, candidate_on_dir, left_label="PID baseline", right_label="Candidate safety on").to_dict()
+    safety_on_vs_off = compare_studies(candidate_on_dir, candidate_off_dir, left_label="Candidate safety on", right_label="Candidate safety off").to_dict()
+    comparisons_dir = showcase_dir / "comparisons"
+    comparisons_dir.mkdir(parents=True, exist_ok=True)
+    baseline_vs_candidate_json = comparisons_dir / "baseline_vs_candidate.json"
+    safety_on_vs_off_json = comparisons_dir / "candidate_safety_on_vs_off.json"
+    baseline_vs_candidate_json.write_text(json.dumps(baseline_vs_candidate, indent=2), encoding="utf-8")
+    safety_on_vs_off_json.write_text(json.dumps(safety_on_vs_off, indent=2), encoding="utf-8")
+
+    baseline_delta = baseline_vs_candidate.get("delta", {})
+    safety_delta = safety_on_vs_off.get("delta", {})
+    explanation_lines = [
+        "# Showcase Explanation Panel",
+        "",
+        "Use this panel when you want the booth story to match the benchmark language used in the scientific workflow.",
+        "",
+        "## Baseline vs candidate",
+        "",
+        "- Baseline: `PID Controller`",
+        "- Candidate: `Runaway AI Candidate`",
+        f"- TIR delta (baseline - candidate): `{baseline_delta.get('mean_tir_70_180')}`",
+        f"- Intervention delta (baseline - candidate): `{baseline_delta.get('mean_supervisor_interventions')}`",
+        "",
+        "## Safety on vs safety off",
+        "",
+        "- Same candidate algorithm, same profile, same scenario",
+        f"- TIR delta (safety on - safety off): `{safety_delta.get('mean_tir_70_180')}`",
+        f"- Severe hypo delta: `{safety_delta.get('severe_hypo_runs')}`",
+        f"- Early termination delta: `{safety_delta.get('terminated_early_runs')}`",
+        "",
+        "## Plain-language talking points",
+        "",
+        "- This panel compares a stable baseline with a deliberately bad candidate.",
+        "- Then it compares the same candidate with the safety layer on and off.",
+        "- That makes the public demo line up with the benchmark logic used in the full study engine.",
+        "",
+    ]
+    explanation_panel = showcase_dir / "SHOWCASE_EXPLANATION_PANEL.md"
+    _write_text(explanation_panel, "\n".join(explanation_lines))
+
+    sync_lines = [
+        "# Showcase Research Sync",
+        "",
+        "This artifact links the fair demo to the scientific benchmark language used elsewhere in the SDK.",
+        "",
+        "## What this mirrors",
+        "",
+        "- Baseline vs candidate comparison",
+        "- Safety-on vs safety-off comparison",
+        "- The same TIR, hypo, intervention, uncertainty, and calibration vocabulary used in `run-study` bundles",
+        "",
+        "## Files",
+        "",
+        f"- Summary JSON: `{summary_json}`",
+        f"- Poster PNG: `{poster_outputs['poster_png']}`",
+        f"- Baseline vs candidate: `{baseline_vs_candidate_json}`",
+        f"- Safety on vs off: `{safety_on_vs_off_json}`",
+        "",
+        "## AI explanation note",
+        "",
+        ai_status,
+        "",
+        "If local AI is available, use the candidate safety-on run as the explanation target so the live explanation matches the benchmark story.",
+        "",
+    ]
+    sync_markdown = showcase_dir / "SHOWCASE_RESEARCH_SYNC.md"
+    _write_text(sync_markdown, "\n".join(sync_lines))
+
+    return {
+        "showcase_study_dir": str(showcase_dir),
+        "showcase_study_summary_json": str(summary_json),
+        "showcase_study_summary_md": str(summary_md),
+        "showcase_study_poster_png": str(poster_outputs["poster_png"]),
+        "showcase_study_poster_json": str(poster_outputs["poster_summary_json"]),
+        "showcase_baseline_vs_candidate_json": str(baseline_vs_candidate_json),
+        "showcase_safety_on_vs_off_json": str(safety_on_vs_off_json),
+        "showcase_research_sync_md": str(sync_markdown),
+        "showcase_explanation_panel_md": str(explanation_panel),
+    }
+
+
 def _build_jury_brief(
     *,
     output_dir: Path,
@@ -386,6 +661,15 @@ def build_booth_demo(
         except Exception as exc:
             ai_status = f"AI preparation did not block the demo, but it could not finish cleanly: {exc}"
 
+    showcase_outputs = _write_showcase_research_sync(
+        output_dir=resolved_output,
+        patient_config=patient_config,
+        duration_minutes=duration_minutes,
+        time_step=time_step,
+        seed=seed,
+        ai_status=ai_status,
+    )
+
     summary_payload = {
         "output_dir": str(resolved_output),
         "patient_config": str(patient_config),
@@ -406,6 +690,7 @@ def build_booth_demo(
             }
             for spec in specs
         ],
+        "showcase_sync": showcase_outputs,
     }
     _write_json(resolved_output / "demo_summary.json", summary_payload)
 
@@ -450,4 +735,5 @@ def build_booth_demo(
     for spec in specs:
         artifact_paths[f"{spec.slug}_dir"] = run_outputs[spec.slug]["output_dir"]
     artifact_paths.update(ai_outputs)
+    artifact_paths.update(showcase_outputs)
     return artifact_paths

iints/analysis/carelink_workbench.py

@@ -43,7 +43,7 @@ def _round(value: Any, digits: int = 2) -> float | int | None:
         return None
     try:
         number = float(value)
-    except Exception:
+    except (TypeError, ValueError, OverflowError):
         return None
     if math.isnan(number) or math.isinf(number):
         return None