iints-sdk-python35 1.5.3__py3-none-any.whl → 1.5.4__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.5.3"
+    __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.

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

@@ -15,6 +15,12 @@ from .study_protocol import (
     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,
@@ -112,8 +118,11 @@ __all__ = [
     "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",
@@ -121,6 +130,7 @@ __all__ = [
     "StudyArmSpec",
     "StudyComparison",
     "StudyDesignPayload",
+    "StudyExperimentConfig",
     "StudyMatrixRow",
     "StudyProfileSpec",
     "StudyRunSummary",

iints/analysis/baseline.py

@@ -8,6 +8,7 @@ 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
@@ -51,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()))
 

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

iints/analysis/eucys_results.py

@@ -70,7 +70,7 @@ def build_eucys_abstract_draft_markdown() -> str:
             "",
             "The central research question is whether a transparent, safety-first benchmark can evaluate candidate insulin-decision algorithms more rigorously than isolated demo runs or single-metric comparisons. "
             "The platform combines virtual patient simulation, baseline comparison, safety-layer analysis, protocol bundles, subgroup summaries, and exportable study artifacts. "
-            "Instead of showing one favorable run, IINTS-AF compares a candidate algorithm against classical baselines such as `PID Controller`, `Standard Pump`, and `Correction Bolus` across predefined patient profiles, scenario families, and random seeds.",
+            "Instead of showing one favorable run, IINTS-AF compares a candidate algorithm against classical baselines such as `Clinical Baseline`, `PID Controller`, `Standard Pump`, and `Correction Bolus` across predefined patient profiles, scenario families, and random seeds.",
             "",
             "In the final benchmark bundle, the platform evaluated **[RUN_COUNT]** runs across **[PROFILE_COUNT]** patient profiles, **[SCENARIO_COUNT]** scenario families, and **[ALGORITHM_COUNT]** algorithms. "
             "The candidate algorithm achieved **[CANDIDATE_TIR]%** time in range compared with **[BASELINE_TIR]%** for the strongest baseline, while the safety analysis showed **[SAFETY_RESULT]**. "
@@ -235,7 +235,7 @@ def build_eucys_filled_abstract_markdown(
             "In this project, I developed **IINTS-AF**, a simulation-first benchmark platform for testing insulin-decision algorithms under fixed study protocols.",
             "",
             "The platform combines virtual patient simulation, baseline comparison, safety-layer analysis, protocol bundles, subgroup summaries, and exportable study artifacts. "
-            "Instead of showing a single favorable run, IINTS-AF compares a candidate algorithm against classical baselines such as `PID Controller`, `Standard Pump`, and `Correction Bolus` across predefined profiles, scenario families, and random seeds.",
+            "Instead of showing a single favorable run, IINTS-AF compares a candidate algorithm against classical baselines such as `Clinical Baseline`, `PID Controller`, `Standard Pump`, and `Correction Bolus` across predefined profiles, scenario families, and random seeds.",
             "",
             f"In the current benchmark bundle, the platform evaluated **{run_count}** runs across **{counts['profile_count']}** patient profiles, **{counts['scenario_count']}** scenario families, and **{counts['algorithm_count']}** algorithms. "
             f"In the clean certified arm, **{candidate_name}** achieved **{candidate_tir}** time in range compared with **{baseline_tir}** for **{strongest_baseline}**, while the safety layer recorded **{safety_result}**. "

iints/analysis/hardware_benchmark.py

@@ -1,11 +1,17 @@
+from __future__ import annotations
+
+import json
+import logging
 import time
 import subprocess
 import threading
 import psutil
-import json
 from typing import Dict, List, Optional
 from dataclasses import dataclass, asdict
 
+
+logger = logging.getLogger(__name__)
+
 @dataclass
 class PerformanceMetrics:
     timestamp: float
@@ -32,7 +38,8 @@ class HardwareBenchmark:
             with open('/proc/device-tree/model', 'r') as f:
                 model = f.read().strip()
                 return 'jetson' in model.lower()
-        except:
+        except (FileNotFoundError, OSError, ValueError) as exc:
+            logger.debug("Jetson detection unavailable: %s", exc)
             return False
     
     def _get_tegrastats_metrics(self) -> Optional[Dict]:
@@ -51,8 +58,11 @@ class HardwareBenchmark:
                     line = lines[-1]  # Get last line
                     # This is a simplified parser - real implementation would be more robust
                     return {"raw_tegrastats": line}
-        except:
-            pass
+            logger.debug("tegrastats exited with non-zero status: %s", result.returncode)
+        except subprocess.TimeoutExpired as exc:
+            logger.debug("tegrastats timed out: %s", exc)
+        except (FileNotFoundError, OSError, ValueError) as exc:
+            logger.debug("tegrastats unavailable: %s", exc)
         return None
     
     def _collect_metrics(self) -> PerformanceMetrics:
@@ -82,8 +92,8 @@ class HardwareBenchmark:
                 with open('/sys/class/thermal/thermal_zone0/temp', 'r') as f:
                     temp_millicelsius = int(f.read().strip())
                     temperature = temp_millicelsius / 1000.0
-            except:
-                pass
+            except (FileNotFoundError, OSError, ValueError) as exc:
+                logger.debug("temperature probe unavailable: %s", exc)
         
         return PerformanceMetrics(
             timestamp=timestamp,
@@ -218,4 +228,4 @@ class HardwareBenchmark:
     
     def clear_metrics(self):
         """Clear collected metrics."""
-        self.metrics_history.clear()
+        self.metrics_history.clear()

iints/analysis/reporting.py

@@ -1,5 +1,6 @@
 import os
 import tempfile
+import logging
 from pathlib import Path
 from typing import Any, Dict, Optional
 
@@ -14,6 +15,8 @@ from fpdf.enums import XPos, YPos
 from iints.analysis.clinical_metrics import ClinicalMetricsCalculator
 from iints.utils.plotting import apply_plot_style
 
+logger = logging.getLogger("iints")
+
 
 class ClinicalReportGenerator:
     """Generate a clean, publication-ready PDF report."""
@@ -41,8 +44,8 @@ class ClinicalReportGenerator:
             x_pos = pdf.w - pdf.r_margin - logo_width
             y_pos = 6
             pdf.image(str(logo_path), x=x_pos, y=y_pos, w=logo_width)
-        except Exception:
-            # Fallback silently if image fails to load
+        except (OSError, RuntimeError, ValueError) as exc:
+            logger.debug("Skipping report logo render: %s", exc)
             return
 
     def _plot_glucose(self, df: pd.DataFrame, output_path: Path) -> None:

iints/analysis/study_engine.py

@@ -9,6 +9,7 @@ from iints.scenarios.study_pack import build_eucys_study_pack
 
 DEFAULT_PROFILE_SET = "clinic_safe_core"
 DEFAULT_BASELINE_ALGORITHMS = [
+    "Clinical Baseline",
     "PID Controller",
     "Standard Pump",
     "Correction Bolus",

iints/analysis/study_experiment.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass(frozen=True)
+class StudyExperimentConfig:
+    source_path: Path
+    name: str
+    preset: str
+    title: str
+    profile_set: str
+    scenarios: list[str]
+    seeds: list[int]
+    duration_minutes: int | None
+    time_step: int
+    include_default_baselines: bool
+    extra_algorithms: list[str]
+    prepare_ai: bool
+    gate_profile: str | None
+    gate_profiles_path: Path | None
+    fail_on_gate: bool
+    external_reference_label: str
+    candidate_algorithm: Path
+    output_dir: Path | None
+    carelink_metrics: Path | None
+    reference_csv: Path | None
+
+
+def _resolve_optional_path(base_dir: Path, raw_value: Any) -> Path | None:
+    if raw_value in (None, "", "null"):
+        return None
+    path = Path(str(raw_value)).expanduser()
+    if not path.is_absolute():
+        path = (base_dir / path).resolve()
+    return path
+
+
+def _require_mapping(payload: Any, label: str) -> dict[str, Any]:
+    if payload is None:
+        return {}
+    if not isinstance(payload, dict):
+        raise ValueError(f"{label} must be a mapping in the experiment file.")
+    return dict(payload)
+
+
+def _normalize_str_list(raw_value: Any, label: str) -> list[str]:
+    if raw_value in (None, "", []):
+        return []
+    if isinstance(raw_value, str):
+        return [item.strip() for item in raw_value.split(",") if item.strip()]
+    if isinstance(raw_value, list):
+        values = [str(item).strip() for item in raw_value if str(item).strip()]
+        return values
+    raise ValueError(f"{label} must be a list or comma-separated string.")
+
+
+def _normalize_seed_list(raw_value: Any) -> list[int]:
+    if raw_value in (None, "", []):
+        return [1, 2, 3, 4, 5]
+    if isinstance(raw_value, str):
+        return [int(item.strip()) for item in raw_value.split(",") if item.strip()]
+    if isinstance(raw_value, list):
+        return [int(item) for item in raw_value]
+    raise ValueError("experiment.seeds must be a list or comma-separated string.")
+
+
+def load_study_experiment_config(path: str | Path) -> StudyExperimentConfig:
+    source_path = Path(path).expanduser().resolve()
+    if not source_path.is_file():
+        raise FileNotFoundError(f"Study experiment config not found: {source_path}")
+
+    raw_payload = yaml.safe_load(source_path.read_text(encoding="utf-8")) or {}
+    if not isinstance(raw_payload, dict):
+        raise ValueError("Study experiment config must be a YAML mapping.")
+
+    experiment = _require_mapping(raw_payload.get("experiment"), "experiment")
+    algorithm = _require_mapping(raw_payload.get("algorithm"), "algorithm")
+    paths = _require_mapping(raw_payload.get("paths"), "paths")
+    study = _require_mapping(raw_payload.get("study"), "study")
+    base_dir = source_path.parent
+
+    candidate_raw = algorithm.get("candidate") or paths.get("candidate_algorithm")
+    if not candidate_raw:
+        raise ValueError("Study experiment config must define algorithm.candidate or paths.candidate_algorithm.")
+
+    candidate_algorithm = _resolve_optional_path(base_dir, candidate_raw)
+    if candidate_algorithm is None:
+        raise ValueError("Study experiment config candidate path could not be resolved.")
+
+    return StudyExperimentConfig(
+        source_path=source_path,
+        name=str(experiment.get("name") or source_path.stem),
+        preset=str(experiment.get("preset") or "default"),
+        title=str(experiment.get("title") or "IINTS Scientific Validation Protocol"),
+        profile_set=str(experiment.get("profile_set") or "clinic_safe_core"),
+        scenarios=_normalize_str_list(study.get("scenarios", experiment.get("scenarios")), "study.scenarios"),
+        seeds=_normalize_seed_list(experiment.get("seeds")),
+        duration_minutes=int(experiment["duration_minutes"]) if experiment.get("duration_minutes") is not None else None,
+        time_step=int(experiment.get("time_step", 5)),
+        include_default_baselines=bool(experiment.get("include_default_baselines", True)),
+        extra_algorithms=_normalize_str_list(algorithm.get("extra_algorithms", experiment.get("extra_algorithms")), "algorithm.extra_algorithms"),
+        prepare_ai=bool(experiment.get("prepare_ai", True)),
+        gate_profile=str(experiment["gate_profile"]).strip() if experiment.get("gate_profile") not in (None, "") else None,
+        gate_profiles_path=_resolve_optional_path(base_dir, paths.get("gate_profiles_path") or experiment.get("gate_profiles_path")),
+        fail_on_gate=bool(experiment.get("fail_on_gate", False)),
+        external_reference_label=str(
+            experiment.get("external_reference_label") or "CareLink personal workbench metrics"
+        ),
+        candidate_algorithm=candidate_algorithm,
+        output_dir=_resolve_optional_path(base_dir, paths.get("output_dir")),
+        carelink_metrics=_resolve_optional_path(base_dir, paths.get("carelink_metrics")),
+        reference_csv=_resolve_optional_path(base_dir, paths.get("reference_csv")),
+    )
+
+
+def build_study_experiment_template(
+    *,
+    preset: str,
+    title: str,
+    profile_set: str,
+    seeds: list[int],
+    candidate_algorithm: str,
+    scenarios: list[str],
+    include_default_baselines: bool,
+    extra_algorithms: list[str] | None = None,
+    external_reference_label: str = "CareLink personal workbench metrics",
+    default_output_dir: str | None = None,
+) -> dict[str, Any]:
+    if default_output_dir is None:
+        default_output_dir = "results/eucys_study" if preset == "eucys" else "results/study_bundle"
+    return {
+        "experiment": {
+            "name": "iints_scientific_validation",
+            "preset": preset,
+            "title": title,
+            "profile_set": profile_set,
+            "seeds": list(seeds),
+            "duration_minutes": None,
+            "time_step": 5,
+            "include_default_baselines": include_default_baselines,
+            "prepare_ai": True,
+            "gate_profile": None,
+            "fail_on_gate": False,
+            "external_reference_label": external_reference_label,
+        },
+        "study": {
+            "scenarios": list(scenarios),
+        },
+        "algorithm": {
+            "candidate": candidate_algorithm,
+            "extra_algorithms": list(extra_algorithms or []),
+        },
+        "paths": {
+            "output_dir": default_output_dir,
+            "carelink_metrics": None,
+            "reference_csv": None,
+            "gate_profiles_path": None,
+        },
+    }
+
+
+def render_study_experiment_yaml(payload: dict[str, Any]) -> str:
+    return yaml.safe_dump(payload, sort_keys=False)

iints/analysis/study_protocol.py

@@ -15,6 +15,10 @@ from iints.analysis.study_engine import (
     StudyDesignPayload,
     build_study_design_payload,
 )
+from iints.analysis.study_experiment import (
+    build_study_experiment_template,
+    render_study_experiment_yaml,
+)
 
 DEFAULT_SCENARIOS = [
     "baseline_day",
@@ -231,10 +235,38 @@ def write_study_protocol_bundle(
     design_json = target / "study_design.json"
     matrix_csv = target / "study_matrix.csv"
     algorithms_json = target / "algorithms.json"
+    experiment_yaml = target / "study_experiment.yaml"
 
     markdown_path.write_text(render_study_protocol_markdown(payload), encoding="utf-8")
     design_json.write_text(json.dumps(payload, indent=2), encoding="utf-8")
     algorithms_json.write_text(json.dumps(payload.get("algorithms", []), indent=2), encoding="utf-8")
+    candidate_entry = next(
+        (
+            entry
+            for entry in payload.get("algorithms", [])
+            if isinstance(entry, dict) and entry.get("role") == "candidate"
+        ),
+        {},
+    )
+    extra_algorithm_labels = [
+        str(entry.get("display_name"))
+        for entry in payload.get("algorithms", [])
+        if isinstance(entry, dict)
+        and entry.get("role") != "candidate"
+        and str(entry.get("display_name")) not in DEFAULT_BASELINE_ALGORITHMS
+    ]
+    experiment_payload = build_study_experiment_template(
+        preset=str(payload.get("preset", preset)),
+        title=str(payload.get("title", title)),
+        profile_set=str(payload.get("profile_set", profile_set)),
+        seeds=list(payload.get("seed_policy", {}).get("seeds", [])),
+        candidate_algorithm=str(candidate_entry.get("source_ref") or candidate_entry.get("display_name") or "algorithms/example_algorithm.py"),
+        scenarios=[str(item.get("slug")) for item in payload.get("scenarios", []) if isinstance(item, dict) and item.get("slug")],
+        include_default_baselines=include_default_baselines,
+        extra_algorithms=extra_algorithm_labels,
+        external_reference_label=str(payload.get("external_validation", {}).get("reference_label", external_reference_label)),
+    )
+    experiment_yaml.write_text(render_study_experiment_yaml(experiment_payload), encoding="utf-8")
 
     with matrix_csv.open("w", encoding="utf-8", newline="") as handle:
         fieldnames = [
@@ -271,4 +303,5 @@ def write_study_protocol_bundle(
         "study_design_json": str(design_json),
         "study_matrix_csv": str(matrix_csv),
         "algorithms_json": str(algorithms_json),
+        "study_experiment_yaml": str(experiment_yaml),
     }