iints-sdk-python35 1.4.0__py3-none-any.whl → 1.5.1__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.4.0"
+    __version__ = "1.5.1"
 
 # 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.
@@ -70,11 +70,13 @@ 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 .data.study_corruption import AVAILABLE_STUDY_CORRUPTIONS, apply_study_corruptions, write_corrupted_study_csv
 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.study_protocol import build_study_protocol_payload, render_study_protocol_markdown, write_study_protocol_bundle
 from .analysis.edge_efficiency import EnergyEstimate, estimate_energy_per_decision
 from .ai import AIResponse, IINTSAssistant, MDMPGuard
 from .highlevel import run_simulation, run_full, run_population
@@ -184,10 +186,16 @@ __all__ = [
     "MDMPGateError",
     "generate_synthetic_mirror",
     "SyntheticMirrorArtifact",
+    "AVAILABLE_STUDY_CORRUPTIONS",
+    "apply_study_corruptions",
+    "write_corrupted_study_csv",
     # Analysis Metrics
     "generate_benchmark_metrics",
     "build_booth_demo",
     "build_carelink_workbench",
+    "build_study_protocol_payload",
+    "render_study_protocol_markdown",
+    "write_study_protocol_bundle",
     "ClinicalReportGenerator",
     "EnergyEstimate",
     "estimate_energy_per_decision",

iints/ai/assistant.py

@@ -122,3 +122,6 @@ class IINTSAssistant:
 
     def generate_report(self, run: dict[str, Any]) -> AIResponse:
         return self._run_task("generate_report", run)
+
+    def review_realism(self, run: dict[str, Any]) -> AIResponse:
+        return self._run_task("review_realism", run)

iints/ai/cli.py

@@ -43,6 +43,7 @@ def _default_prepared_payload(task: str, ai_dir: Path) -> Path:
         "trends": ["trends_payload.json"],
         "anomalies": ["anomalies_payload.json"],
         "report": ["report_payload.json"],
+        "review": ["review_payload.json", "report_payload.json"],
     }.get(task, [])
     for filename in candidates:
         candidate = ai_dir / filename
@@ -69,6 +70,15 @@ def _resolve_cli_inputs(
 
     if input_path.is_dir():
         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 (resolved_cert is None and not (ai_dir / "report.signed.mdmp").is_file())
+        ):
+            prepare_ai_ready_artifacts(
+                input_path,
+                create_dev_mdmp_cert=resolved_cert is None,
+            )
         resolved_input = _default_prepared_payload(task, ai_dir)
         if resolved_cert is None:
             candidate_cert = ai_dir / "report.signed.mdmp"
@@ -95,6 +105,14 @@ def _write_output(path: Path | None, response: AIResponse) -> None:
     path.write_text(response.text + "\n", encoding="utf-8")
 
 
+def _default_output_for_review(input_path: Path, output: Path | None) -> Path | None:
+    if output is not None:
+        return output
+    if input_path.is_dir():
+        return input_path / "ai" / "realism_review.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(
@@ -438,3 +456,45 @@ def report(
     except Exception as exc:
         console.print(f"[bold red]Error:[/bold red] {exc}")
         raise typer.Exit(code=1)
+
+
+@app.command("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,
+    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 realism review.")] = None,
+) -> None:
+    console = Console()
+    try:
+        resolved_input, resolved_cert, resolved_public_key = _resolve_cli_inputs(
+            task="review",
+            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_review(input_json, output)
+        response = assistant.review_realism(payload)
+        _write_output(resolved_output, response)
+        _render_response(console, "IINTS AI Realism Review", response, resolved_output)
+    except Exception as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(code=1)

iints/ai/prepare.py

@@ -97,6 +97,13 @@ def _sample_trace(df: pd.DataFrame, *, max_rows: int = 48) -> list[dict[str, Any
     return [_normalize_series_record(record) for record in sampled.to_dict(orient="records")]
 
 
+def _max_glucose_delta_per_step(df: pd.DataFrame, glucose_column: str) -> float:
+    clean = pd.to_numeric(df[glucose_column], errors="coerce").dropna()
+    if clean.empty or len(clean) < 2:
+        return 0.0
+    return float(clean.diff().abs().dropna().max())
+
+
 def _position_for_label(df: pd.DataFrame, label: Any) -> int:
     location = df.index.get_loc(label)
     if isinstance(location, int):
@@ -166,9 +173,12 @@ def _build_summary(df: pd.DataFrame, run_metadata: dict[str, Any], audit_summary
         "mean_glucose_mgdl": _normalize_value(float(glucose.mean())),
         "min_glucose_mgdl": _normalize_value(float(glucose.min())),
         "max_glucose_mgdl": _normalize_value(float(glucose.max())),
+        "max_glucose_delta_per_step_mgdl": _normalize_value(_max_glucose_delta_per_step(df, glucose_column)),
         "time_in_range_70_180_pct": _normalize_value(_time_in_band_pct(glucose, 70.0, 180.0)),
         "time_below_70_pct": _normalize_value(float((glucose < 70.0).mean() * 100.0)),
+        "time_below_54_pct": _normalize_value(float((glucose < 54.0).mean() * 100.0)),
         "time_above_180_pct": _normalize_value(float((glucose > 180.0).mean() * 100.0)),
+        "time_above_250_pct": _normalize_value(float((glucose > 250.0).mean() * 100.0)),
         "delivered_insulin_total_units": _normalize_value(_safe_sum(df, "delivered_insulin_units")),
         "recommended_insulin_total_units": _normalize_value(_safe_sum(df, "algo_recommended_insulin_units")),
         "safety_trigger_count": _bool_sum(df, "safety_triggered"),
@@ -228,6 +238,23 @@ def _build_payloads(
             "trace_sample": trace_sample,
             "baseline_comparison": baseline_comparison,
         },
+        "review_payload.json": {
+            **common,
+            "audit_summary": audit_summary,
+            "baseline_comparison": baseline_comparison,
+            "trace_sample": trace_sample,
+            "review_focus": {
+                "goal": "Judge whether the simulation or imported dataset looks physiologically plausible and internally coherent.",
+                "checks": [
+                    "glucose range plausibility",
+                    "excursion size and recovery behavior",
+                    "time in range and severe hypo/hyper exposure",
+                    "insulin delivery realism relative to observed glucose behavior",
+                    "safety trigger and override consistency",
+                ],
+            },
+            "run_manifest": run_manifest,
+        },
         "step_riskiest.json": {
             **common,
             **risk_payload,

iints/ai/prompts.py

@@ -4,7 +4,13 @@ import json
 from typing import Any, Literal
 
 
-TaskName = Literal["explain_decision", "analyze_trends", "detect_anomalies", "generate_report"]
+TaskName = Literal[
+    "explain_decision",
+    "analyze_trends",
+    "detect_anomalies",
+    "generate_report",
+    "review_realism",
+]
 MAX_PROMPT_PAYLOAD_CHARS = 12000
 
 SYSTEM_PROMPT = (
@@ -52,6 +58,19 @@ TASK_TEMPLATES: dict[TaskName, str] = {
         "5. Research-only conclusion\n\n"
         "Input JSON:\n{data}"
     ),
+    "review_realism": (
+        "Review this simulation or imported-data payload and judge whether the results look physiologically plausible for research use.\n"
+        "Be conservative and do not overclaim. If the payload is incomplete, say so clearly.\n"
+        "Respond in markdown with these sections:\n"
+        "1. Overall realism verdict (Likely realistic / Needs review / Likely unrealistic)\n"
+        "2. What looks realistic\n"
+        "3. What looks suspicious\n"
+        "4. Priority fixes\n"
+        "5. What to improve next\n"
+        "6. Suggested follow-up validation checks\n\n"
+        "Focus on glycemic ranges, excursion patterns, insulin behavior, safety overrides, and whether the data looks internally coherent.\n\n"
+        "Input JSON:\n{data}"
+    ),
 }
 
 

iints/analysis/__init__.py

@@ -4,15 +4,43 @@ from .booth_demo import build_booth_demo
 from .carelink_workbench import build_carelink_workbench
 from .poster import generate_results_poster
 from .reporting import ClinicalReportGenerator
+from .study_poster import generate_study_poster
+from .study_protocol import (
+    build_study_protocol_payload,
+    render_study_protocol_markdown,
+    write_study_protocol_bundle,
+)
+from .study_analysis import (
+    analyze_run_directory,
+    analyze_study_directory,
+    compare_studies,
+    load_study_summary,
+    quality_badges_for_metrics,
+    StudyComparison,
+    StudyRunSummary,
+    StudySummary,
+)
 
 __all__ = [
+    "analyze_run_directory",
+    "analyze_study_directory",
     "build_booth_demo",
     "build_carelink_workbench",
     "ClinicalMetricsCalculator",
     "ClinicalMetricsResult",
     "ClinicalReportGenerator",
     "compute_metrics",
+    "compare_studies",
     "generate_results_poster",
+    "generate_study_poster",
+    "build_study_protocol_payload",
+    "render_study_protocol_markdown",
+    "write_study_protocol_bundle",
+    "load_study_summary",
+    "quality_badges_for_metrics",
     "run_baseline_comparison",
+    "StudyComparison",
+    "StudyRunSummary",
+    "StudySummary",
     "write_baseline_comparison",
 ]

iints/analysis/booth_demo.py

@@ -196,6 +196,7 @@ def _build_jury_brief(
             "```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 review {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",
             "```",
             "",
@@ -247,6 +248,7 @@ def _build_commands_markdown(
         "```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 review {supervisor_dir} --model ministral-3:3b\n"
         f"iints ai explain {supervisor_dir} --model ministral-3:3b\n"
         "```\n"
     )
@@ -296,6 +298,7 @@ def _build_live_demo_script_text(
         "- 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 review {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"

iints/analysis/carelink_workbench.py

@@ -202,6 +202,23 @@ def _prepare_ai_payloads(
             "profile_24h": profile_records,
             "trace_sample": trace_sample,
         },
+        "review_payload.json": {
+            **common,
+            "daily_summary": daily_records,
+            "profile_24h": profile_records,
+            "trace_sample": trace_sample,
+            "top_alerts": alert_counts,
+            "top_sensor_exceptions": sensor_exception_counts,
+            "review_focus": {
+                "goal": "Judge whether the imported glucose history looks internally coherent and physiologically plausible.",
+                "checks": [
+                    "time in range versus extreme exposure",
+                    "daily variability and day-to-day stability",
+                    "consistency between glucose, carbs, and insulin logs",
+                    "frequency of alerts and sensor exceptions",
+                ],
+            },
+        },
         "anomalies_payload.json": {
             **common,
             "lowest_readings": [