iints-sdk-python35 1.5.9__tar.gz → 1.5.10__tar.gz

{iints_sdk_python35-1.5.9/src/iints_sdk_python35.egg-info → iints_sdk_python35-1.5.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iints-sdk-python35
-Version: 1.5.9
+Version: 1.5.10
 Summary: A pre-clinical Edge-AI SDK for diabetes management validation.
 Author-email: Rune Bobbaers <rune.bobbaers@gmail.com>
 License-Expression: Apache-2.0
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 License-File: LICENSE-MIT-IINTS-LEGACY
-Requires-Dist: fastapi<0.136.4,>=0.115.0
+Requires-Dist: fastapi!=0.136.3,<1.0.0,>=0.115.0
 Requires-Dist: numpy<3.0.0,>=1.24.0
 Requires-Dist: pandas<3.0.0,>=2.0.0
 Requires-Dist: pydantic<3.0.0,>=2.0.0
@@ -117,13 +117,13 @@ Full documentation: [python35.github.io/IINTS-SDK](https://python35.github.io/II
 
 ## Live Demo
 
-For a Zoom call, jury walkthrough, or sponsor demo where you want to show both the code and the generated outputs in one terminal flow:
+For a Zoom call, jury walkthrough, or sponsor demo where you want the story first and code as proof:
 
 ```bash
-iints demo-live --output-dir results/live_demo
+iints demo eucys --output-dir results/live_demo
 ```
 
-That exports the showable demo script, prints the key SDK calls, runs the demo, and lists the poster plus proof artifacts to open next.
+Use `iints demo doctor` for clinical feedback conversations and `iints demo booth` for public digital-patient demos.
 
 ---
 

{iints_sdk_python35-1.5.9 → iints_sdk_python35-1.5.10}/README.md

@@ -50,13 +50,13 @@ Full documentation: [python35.github.io/IINTS-SDK](https://python35.github.io/II
 
 ## Live Demo
 
-For a Zoom call, jury walkthrough, or sponsor demo where you want to show both the code and the generated outputs in one terminal flow:
+For a Zoom call, jury walkthrough, or sponsor demo where you want the story first and code as proof:
 
 ```bash
-iints demo-live --output-dir results/live_demo
+iints demo eucys --output-dir results/live_demo
 ```
 
-That exports the showable demo script, prints the key SDK calls, runs the demo, and lists the poster plus proof artifacts to open next.
+Use `iints demo doctor` for clinical feedback conversations and `iints demo booth` for public digital-patient demos.
 
 ---
 

{iints_sdk_python35-1.5.9 → iints_sdk_python35-1.5.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "iints-sdk-python35" 
-version = "1.5.9"
+version = "1.5.10"
 authors = [
   { name="Rune Bobbaers", email="rune.bobbaers@gmail.com" },
 ]
@@ -24,7 +24,7 @@ classifiers = [
     "Development Status :: 5 - Production/Stable",
 ]
 dependencies = [
-    "fastapi>=0.115.0,<0.136.4",
+    "fastapi>=0.115.0,!=0.136.3,<1.0.0",
     "numpy>=1.24.0,<3.0.0",
     "pandas>=2.0.0,<3.0.0",
     "pydantic>=2.0.0,<3.0.0",

{iints_sdk_python35-1.5.9 → iints_sdk_python35-1.5.10}/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.9"
+    __version__ = "1.5.10"
 
 # 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.9 → iints_sdk_python35-1.5.10}/src/iints/ai/__init__.py

@@ -1,7 +1,15 @@
 from .assistant import AIResponse, IINTSAssistant
 from .backends import DEFAULT_MINISTRAL_MODEL, DEFAULT_OLLAMA_HOST, OllamaBackend
 from .mdmp_guard import GuardResult, MDMPGuard
-from .model_catalog import LocalMistralModelProfile, list_local_mistral_models
+from .model_catalog import (
+    DEFAULT_MISTRAL_API_MODEL,
+    DEFAULT_MISTRAL_API_REASONING_EFFORT,
+    LocalMistralModelProfile,
+    MistralAPIMigrationProfile,
+    list_local_mistral_models,
+    list_mistral_api_migrations,
+    migrate_mistral_api_model,
+)
 from .prepare import prepare_ai_ready_artifacts
 
 __all__ = [
@@ -12,7 +20,12 @@ __all__ = [
     "OllamaBackend",
     "GuardResult",
     "MDMPGuard",
+    "DEFAULT_MISTRAL_API_MODEL",
+    "DEFAULT_MISTRAL_API_REASONING_EFFORT",
     "LocalMistralModelProfile",
+    "MistralAPIMigrationProfile",
     "list_local_mistral_models",
+    "list_mistral_api_migrations",
+    "migrate_mistral_api_model",
     "prepare_ai_ready_artifacts",
 ]

{iints_sdk_python35-1.5.9 → iints_sdk_python35-1.5.10}/src/iints/ai/assistant.py

@@ -82,12 +82,20 @@ class IINTSAssistant:
             ollama_backend.ensure_model_ready()
             return local_backend
         if requested == "api":
-            api_backend: CompletionBackend = MistralAPIBackend()
+            api_backend: CompletionBackend = MistralAPIBackend(model_name=model)
             if api_backend.available():
                 return api_backend
+            api_model = getattr(api_backend, "model_name", "mistral-small-latest")
+            api_reasoning = getattr(api_backend, "reasoning_effort", None)
+            reasoning_hint = (
+                f" with reasoning_effort='{api_reasoning}'"
+                if isinstance(api_reasoning, str) and api_reasoning.strip()
+                else ""
+            )
             raise RuntimeError(
                 "Cloud API fallback is not enabled in this SDK build yet. "
-                "Use mode='local' with Ollama."
+                "Use mode='local' with Ollama, or configure an external Mistral client with "
+                f"`{api_model}`{reasoning_hint}."
             )
         raise ValueError(f"Unsupported AI mode: {mode}")
 

iints_sdk_python35-1.5.10/src/iints/ai/backends/mistral_api.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from ..model_catalog import (
+    DEFAULT_MISTRAL_API_MODEL,
+    DEFAULT_MISTRAL_API_REASONING_EFFORT,
+    migrate_mistral_api_model,
+)
+
+
+class MistralAPIBackend:
+    backend_name = "mistral_api"
+
+    def __init__(
+        self,
+        *,
+        model_name: str = DEFAULT_MISTRAL_API_MODEL,
+        reasoning_effort: str | None = DEFAULT_MISTRAL_API_REASONING_EFFORT,
+        **kwargs,
+    ) -> None:
+        migrated_model, migrated_reasoning, migrated = migrate_mistral_api_model(model_name)
+        self.requested_model_name = model_name
+        self.model_name = migrated_model
+        self.reasoning_effort = migrated_reasoning if migrated_reasoning is not None else reasoning_effort
+        self.model_was_migrated = migrated
+
+    def available(self) -> bool:
+        return False
+
+    def complete(self, *, system_prompt: str, user_prompt: str) -> str:
+        migration_hint = (
+            f" Requested deprecated model '{self.requested_model_name}' was mapped to "
+            f"'{self.model_name}'."
+            if self.model_was_migrated
+            else ""
+        )
+        reasoning_hint = (
+            f" Default Mistral reasoning_effort is '{self.reasoning_effort}'."
+            if self.reasoning_effort
+            else ""
+        )
+        raise RuntimeError(
+            "Cloud fallback is not enabled in this SDK build yet. "
+            "Use mode='local' with Ollama for the open Ministral 3 model, or configure "
+            f"your external Mistral client for '{self.model_name}'."
+            f"{reasoning_hint}{migration_hint}"
+        )

{iints_sdk_python35-1.5.9 → iints_sdk_python35-1.5.10}/src/iints/ai/cli.py

@@ -12,7 +12,13 @@ from typing_extensions import Annotated
 
 from .assistant import AIResponse, IINTSAssistant
 from .backends import DEFAULT_MINISTRAL_MODEL, OllamaBackend
-from .model_catalog import list_local_mistral_models
+from .model_catalog import (
+    DEFAULT_MISTRAL_API_MODEL,
+    DEFAULT_MISTRAL_API_REASONING_EFFORT,
+    STRONG_MISTRAL_API_MODEL,
+    list_local_mistral_models,
+    list_mistral_api_migrations,
+)
 from .prepare import prepare_ai_ready_artifacts
 
 
@@ -183,10 +189,31 @@ def models() -> None:
         )
 
     console.print(table)
+    migration_table = Table(title="Mistral Serverless Migration Guide")
+    migration_table.add_column("Deprecated", style="yellow", overflow="fold")
+    migration_table.add_column("Replacement", style="cyan", no_wrap=True)
+    migration_table.add_column("Reasoning")
+    migration_table.add_column("Retires")
+    migration_table.add_column("Use Case", overflow="fold")
+    for migration_profile in list_mistral_api_migrations():
+        reasoning = migration_profile.reasoning_effort or "n/a"
+        migration_table.add_row(
+            ", ".join(migration_profile.deprecated_models),
+            migration_profile.replacement_model,
+            reasoning,
+            migration_profile.retirement_date,
+            migration_profile.use_case,
+        )
+    console.print(migration_table)
     console.print(
         "[dim]Tip:[/dim] start with "
         f"`{DEFAULT_MINISTRAL_MODEL}` unless you know your hardware can comfortably run a larger local model."
     )
+    console.print(
+        "[dim]Serverless:[/dim] use "
+        f"`{DEFAULT_MISTRAL_API_MODEL}` with `reasoning_effort={DEFAULT_MISTRAL_API_REASONING_EFFORT}` "
+        f"for small reasoning/code tasks, or `{STRONG_MISTRAL_API_MODEL}` for stronger review."
+    )
 
 
 @app.command(name="prepare")

iints_sdk_python35-1.5.10/src/iints/ai/model_catalog.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .backends.ollama import DEFAULT_MINISTRAL_MODEL
+
+DEFAULT_MISTRAL_API_MODEL = "mistral-small-latest"
+DEFAULT_MISTRAL_API_REASONING_EFFORT = "high"
+STRONG_MISTRAL_API_MODEL = "mistral-medium-3-5"
+DEFAULT_MISTRAL_OCR_MODEL = "mistral-ocr-latest"
+DEFAULT_MISTRAL_MODERATION_MODEL = "mistral-moderation-2603"
+DEFAULT_MISTRAL_TRANSCRIBE_MODEL = "voxtral-mini-latest"
+
+
+@dataclass(frozen=True)
+class LocalMistralModelProfile:
+    tag: str
+    label: str
+    approx_download_gb: float
+    recommended_system_ram_gb: int
+    recommended_vram_gb: int | None
+    fit: str
+    notes: str
+    aliases: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class MistralAPIMigrationProfile:
+    deprecated_models: tuple[str, ...]
+    replacement_model: str
+    reasoning_effort: str | None
+    retirement_date: str
+    use_case: str
+    notes: str
+
+
+LOCAL_MISTRAL_MODEL_PROFILES: tuple[LocalMistralModelProfile, ...] = (
+    LocalMistralModelProfile(
+        tag="ministral-3:3b",
+        label="Ministral 3 3B",
+        approx_download_gb=3.0,
+        recommended_system_ram_gb=16,
+        recommended_vram_gb=6,
+        fit="Entry-level laptop / small edge box",
+        notes="Best starting point for CPU-only systems or modest GPUs. Fastest option, lowest memory pressure.",
+        aliases=("ministral-3:3b",),
+    ),
+    LocalMistralModelProfile(
+        tag=DEFAULT_MINISTRAL_MODEL,
+        label="Ministral 3 8B",
+        approx_download_gb=6.0,
+        recommended_system_ram_gb=24,
+        recommended_vram_gb=10,
+        fit="Balanced desktop / strong laptop",
+        notes="Recommended default for most users. Best trade-off between quality, speed, and local memory footprint.",
+        aliases=("ministral", "ministral-3", "ministral-3:8b"),
+    ),
+    LocalMistralModelProfile(
+        tag="ministral-3:14b",
+        label="Ministral 3 14B",
+        approx_download_gb=10.0,
+        recommended_system_ram_gb=32,
+        recommended_vram_gb=16,
+        fit="High-end workstation",
+        notes="Use when you have plenty of RAM or a strong GPU and want better reasoning depth at the cost of latency.",
+        aliases=("ministral-3:14b",),
+    ),
+)
+
+
+MISTRAL_API_MIGRATION_PROFILES: tuple[MistralAPIMigrationProfile, ...] = (
+    MistralAPIMigrationProfile(
+        deprecated_models=("devstral-small-2507", "devstral-small-latest"),
+        replacement_model=DEFAULT_MISTRAL_API_MODEL,
+        reasoning_effort=DEFAULT_MISTRAL_API_REASONING_EFFORT,
+        retirement_date="2026-05-31",
+        use_case="code and agentic helper",
+        notes="Use Mistral Small 4 through the stable latest alias.",
+    ),
+    MistralAPIMigrationProfile(
+        deprecated_models=("devstral-medium-2507", "devstral-2512", "devstral-latest"),
+        replacement_model=STRONG_MISTRAL_API_MODEL,
+        reasoning_effort=DEFAULT_MISTRAL_API_REASONING_EFFORT,
+        retirement_date="2026-05-31 / 2026-07-31",
+        use_case="strong code and research assistant",
+        notes="Use Mistral Medium 3.5 for higher-complexity code/research review.",
+    ),
+    MistralAPIMigrationProfile(
+        deprecated_models=("magistral-small-2509",),
+        replacement_model=DEFAULT_MISTRAL_API_MODEL,
+        reasoning_effort=DEFAULT_MISTRAL_API_REASONING_EFFORT,
+        retirement_date="2026-07-31",
+        use_case="small reasoning",
+        notes="Mistral Small 4 now supports adjustable reasoning.",
+    ),
+    MistralAPIMigrationProfile(
+        deprecated_models=("magistral-medium-2509", "magistral-medium-latest"),
+        replacement_model=STRONG_MISTRAL_API_MODEL,
+        reasoning_effort=DEFAULT_MISTRAL_API_REASONING_EFFORT,
+        retirement_date="2026-07-31",
+        use_case="medium reasoning",
+        notes="Mistral Medium 3.5 supports adjustable reasoning for harder tasks.",
+    ),
+    MistralAPIMigrationProfile(
+        deprecated_models=(
+            "mistral-large-2411",
+            "pixtral-large-2411",
+            "mistral-medium-2505",
+            "mistral-medium-2508",
+        ),
+        replacement_model=STRONG_MISTRAL_API_MODEL,
+        reasoning_effort=DEFAULT_MISTRAL_API_REASONING_EFFORT,
+        retirement_date="2026-05-31 / 2026-08-31",
+        use_case="general strong cloud model",
+        notes="Medium 3.5 is the current stronger general-purpose replacement.",
+    ),
+    MistralAPIMigrationProfile(
+        deprecated_models=("mistral-small-2506",),
+        replacement_model=DEFAULT_MISTRAL_API_MODEL,
+        reasoning_effort=DEFAULT_MISTRAL_API_REASONING_EFFORT,
+        retirement_date="2026-07-31",
+        use_case="small general cloud model",
+        notes="Use the Mistral Small 4 latest alias.",
+    ),
+    MistralAPIMigrationProfile(
+        deprecated_models=("open-mistral-nemo-2407",),
+        replacement_model="ministral-8b-2512",
+        reasoning_effort=None,
+        retirement_date="2026-07-31",
+        use_case="small/low-cost serverless model",
+        notes="Serverless replacement for Nemo. Local SDK defaults still use Ollama `ministral-3:8b`.",
+    ),
+    MistralAPIMigrationProfile(
+        deprecated_models=("mistral-ocr-2505",),
+        replacement_model=DEFAULT_MISTRAL_OCR_MODEL,
+        reasoning_effort=None,
+        retirement_date="2026-05-31",
+        use_case="OCR",
+        notes="Use OCR 3 through the latest alias.",
+    ),
+    MistralAPIMigrationProfile(
+        deprecated_models=("mistral-moderation-2411", "mistral-moderation-latest"),
+        replacement_model=DEFAULT_MISTRAL_MODERATION_MODEL,
+        reasoning_effort=None,
+        retirement_date="2026-06-30",
+        use_case="moderation",
+        notes="Use Mistral Moderation 2.",
+    ),
+    MistralAPIMigrationProfile(
+        deprecated_models=("voxtral-mini-2507",),
+        replacement_model=DEFAULT_MISTRAL_TRANSCRIBE_MODEL,
+        reasoning_effort=None,
+        retirement_date="2026-05-31",
+        use_case="audio transcription",
+        notes="Use Voxtral Mini Transcribe 2.0 through the latest alias.",
+    ),
+)
+
+
+def list_local_mistral_models() -> list[LocalMistralModelProfile]:
+    return list(LOCAL_MISTRAL_MODEL_PROFILES)
+
+
+def list_mistral_api_migrations() -> list[MistralAPIMigrationProfile]:
+    return list(MISTRAL_API_MIGRATION_PROFILES)
+
+
+def migrate_mistral_api_model(model_name: str) -> tuple[str, str | None, bool]:
+    requested = model_name.strip()
+    requested_key = requested.lower()
+    for profile in MISTRAL_API_MIGRATION_PROFILES:
+        if requested_key in {model.lower() for model in profile.deprecated_models}:
+            return profile.replacement_model, profile.reasoning_effort, True
+    return requested, None, False

{iints_sdk_python35-1.5.9 → iints_sdk_python35-1.5.10}/src/iints/analysis/reporting.py

@@ -187,22 +187,36 @@ class ClinicalReportGenerator:
         p75 = q[0.75].to_numpy(dtype=float)
         p95 = q[0.95].to_numpy(dtype=float)
 
+        import seaborn as sns
+
+        sns.set_style("whitegrid")
+
         plt.figure(figsize=(10, 4.2))
-        plt.fill_between(x, p05, p95, color="#d6deef", label="5-95%", linewidth=0)
-        plt.fill_between(x, p25, p75, color="#8fa8cc", label="25-75%", linewidth=0)
-        plt.plot(x, p50, color="#111111", linewidth=2.0, label="Median")
-        plt.axhspan(target_low, target_high, color="#6fbf73", alpha=0.14)
-        plt.axhline(target_low, color="#6b8e23", linewidth=1)
-        plt.axhline(target_high, color="#6b8e23", linewidth=1)
+        plt.fill_between(x, p05, p95, color="#E0E0E0", label="5-95%", linewidth=0)
+        plt.fill_between(x, p25, p75, color="#A6A6A6", label="25-75%", linewidth=0)
+        plt.plot(x, p50, color="#000000", linewidth=2.5, label="Median")
+        plt.axhspan(target_low, target_high, color="#2E7D32", alpha=0.08)
+        plt.axhline(target_low, color="#424242", linestyle="--", linewidth=1.0)
+        plt.axhline(target_high, color="#424242", linestyle="--", linewidth=1.0)
+
+        ax = plt.gca()
+        ax.spines['top'].set_visible(False)
+        ax.spines['right'].set_visible(False)
+        ax.spines['left'].set_color('#333333')
+        ax.spines['bottom'].set_color('#333333')
+
         plt.xlim(0, 24)
         ymax = max(350.0, float(np.nanmax(p95)) + 20.0)
         plt.ylim(40, ymax)
         plt.xticks([0, 3, 6, 9, 12, 15, 18, 21, 24], ["12a", "3a", "6a", "9a", "12p", "3p", "6p", "9p", "12a"])
-        plt.ylabel("mg/dL")
-        plt.title("Ambulatory Glucose Profile (AGP-style modal day)")
-        plt.grid(True, axis="y", alpha=0.25)
+        plt.ylabel("mg/dL", fontweight="bold")
+        plt.title("Ambulatory Glucose Profile (AGP-style modal day)", fontweight="bold")
+
+        ax.grid(True, axis="y", alpha=0.3, linestyle="-", color="#CCCCCC")
+        ax.grid(False, axis="x")
+
         plt.tight_layout()
-        plt.savefig(output_path, dpi=180)
+        plt.savefig(output_path, dpi=300)
         plt.close()
 
     def _plot_daily_profiles(
@@ -230,23 +244,27 @@ class ClinicalReportGenerator:
             daily = df[df["day_index"] == day_id].copy()
             x = daily["minute_of_day"].to_numpy(dtype=float) / 60.0
             y = daily["glucose_actual_mgdl"].to_numpy(dtype=float)
-            ax.axhspan(target_low, target_high, color="#eeeeee", alpha=1.0)
-            ax.fill_between(x, target_high, y, where=y > target_high, color="#f5d51b", alpha=0.9)
-            ax.fill_between(x, y, target_low, where=y < target_low, color="#b71c1c", alpha=0.9)
-            ax.plot(x, y, color="#333333", linewidth=0.9)
+            ax.axhspan(target_low, target_high, color="#F5F5F5", alpha=1.0)
+            ax.fill_between(x, target_high, y, where=y > target_high, color="#FFB300", alpha=0.7)
+            ax.fill_between(x, y, target_low, where=y < target_low, color="#D32F2F", alpha=0.7)
+            ax.plot(x, y, color="#212121", linewidth=1.2)
             ax.set_xlim(0, 24)
             ax.set_ylim(40, max(260, float(np.nanmax(y)) + 20 if len(y) else 260))
             ax.set_xticks([0, 12, 24])
             ax.set_xticklabels(["12a", "12p", "12a"], fontsize=6)
             ax.set_yticks([])
-            ax.set_title(f"Day {int(day_id) + 1}", fontsize=8)
-            for spine in ax.spines.values():
-                spine.set_color("#555555")
-                spine.set_linewidth(0.5)
+            ax.set_title(f"Day {int(day_id) + 1}", fontsize=8, fontweight="bold")
+
+            ax.spines['top'].set_visible(False)
+            ax.spines['right'].set_visible(False)
+            ax.spines['left'].set_color("#888888")
+            ax.spines['left'].set_linewidth(0.5)
+            ax.spines['bottom'].set_color("#888888")
+            ax.spines['bottom'].set_linewidth(0.5)
 
         fig.suptitle("Daily Glucose Profiles", fontsize=12, fontweight="bold")
         fig.tight_layout(rect=(0, 0, 1, 0.92))
-        fig.savefig(output_path, dpi=180)
+        fig.savefig(output_path, dpi=300)
         plt.close(fig)
 
     @staticmethod

iints_sdk_python35-1.5.10/src/iints/analysis/run_quality.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import pandas as pd
+
+from iints.analysis.safety_visualizer import write_safety_visualizer
+from iints.data.realism_dashboard import write_realism_dashboard
+from iints.data.realism_validator import validate_realism_dataset, write_realism_report
+
+
+def _series_or_default(df: pd.DataFrame, column: str, default: float = 0.0) -> pd.Series:
+    if column not in df.columns:
+        return pd.Series([default] * len(df), index=df.index, dtype=float)
+    return pd.to_numeric(df[column], errors="coerce").fillna(default).astype(float)
+
+
+def standardize_simulation_for_realism(results_df: pd.DataFrame) -> pd.DataFrame:
+    """Convert an IINTS results CSV into the generic realism-check schema."""
+    if "glucose_actual_mgdl" not in results_df.columns:
+        raise ValueError("Realism scoring requires a glucose_actual_mgdl column.")
+
+    frame = pd.DataFrame(index=results_df.index)
+    frame["timestamp"] = _series_or_default(results_df, "time_minutes")
+    frame["glucose"] = _series_or_default(results_df, "glucose_actual_mgdl")
+    frame["carbs"] = _series_or_default(results_df, "carb_intake_grams")
+    frame["insulin"] = _series_or_default(results_df, "delivered_insulin_units")
+    return frame
+
+
+def _auto_realism_reference(realism_frame: pd.DataFrame, requested: str | None) -> str | None:
+    """Use empirical daily references only when the run is actually day-scale."""
+    if requested != "auto":
+        return requested
+
+    timestamps = pd.to_numeric(realism_frame.get("timestamp", pd.Series(dtype=float)), errors="coerce").dropna()
+    if len(timestamps) < 2:
+        return None
+
+    duration_hours = float((timestamps.max() - timestamps.min()) / 60.0)
+    carbs = pd.to_numeric(realism_frame.get("carbs", pd.Series(dtype=float)), errors="coerce").fillna(0.0)
+    meal_count = int((carbs >= 10.0).sum())
+    if duration_hours >= 18.0 and meal_count >= 3:
+        return "free_living_t1d"
+    return None
+
+
+def _write_run_quality_markdown(
+    output_path: Path,
+    *,
+    run_label: str,
+    realism_report: Any,
+    selected_reference: str | None,
+    reference_selection: str | None,
+) -> Path:
+    failed = [check for check in realism_report.checks if check.status == "failed"]
+    warnings = [check for check in realism_report.checks if check.status == "warning"]
+    lines = [
+        f"# IINTS Run Quality Review - {run_label}",
+        "",
+        "This review is generated automatically to catch physiologically implausible simulation artifacts before a run is used for demos, reports, or AI research.",
+        "",
+        "## Summary",
+        "",
+        f"- Verdict: `{realism_report.verdict}`",
+        f"- Realism score: `{realism_report.realism_score:.2f}`",
+        f"- Reference selection: `{reference_selection}`",
+        f"- Applied reference: `{selected_reference or 'none'}`",
+        f"- Mean glucose: `{realism_report.metrics.get('mean_glucose_mgdl')} mg/dL`",
+        f"- CV: `{realism_report.metrics.get('cv_pct')}%`",
+        f"- Max glucose rate: `{realism_report.metrics.get('max_abs_rate_mgdl_per_min')} mg/dL/min`",
+        f"- Longest near-flat stretch: `{realism_report.metrics.get('longest_low_motion_minutes')} min`",
+        "",
+        "## Interpretation",
+        "",
+        realism_report.summary,
+        "",
+    ]
+    if failed or warnings:
+        lines.extend(["## Review Items", ""])
+        for check in failed + warnings:
+            lines.append(f"- `{check.status}` - {check.title}: {check.detail}")
+        lines.append("")
+    else:
+        lines.extend(["## Review Items", "", "- No failed or warning realism checks were detected.", ""])
+
+    lines.extend([
+        "## Check Breakdown",
+        "",
+        "| Check | Status | Detail |",
+        "| --- | --- | --- |",
+    ])
+    for check in realism_report.checks:
+        detail = str(check.detail).replace("|", "\\|")
+        lines.append(f"| {check.title} | `{check.status}` | {detail} |")
+
+    lines.extend([
+        "",
+        "## Research Use Note",
+        "",
+        "A `likely_realistic` verdict means the trace passes the SDK's plausibility checks. It does not make the SDK a medical device and does not prove clinical validity. For local-AI training or public claims, use external reference profiles and the strict real-data gate.",
+        "",
+    ])
+    output_path.write_text("\n".join(lines), encoding="utf-8")
+    return output_path
+
+
+def write_run_quality_artifacts(
+    results_df: pd.DataFrame,
+    output_dir: str | Path,
+    *,
+    run_label: Optional[str] = None,
+    safety_report: Optional[Dict[str, Any]] = None,
+    realism_reference: Optional[str] = "auto",
+) -> Dict[str, Any]:
+    """Write reviewer-facing quality artifacts for one run.
+
+    The artifacts are intentionally non-blocking: if realism scoring cannot run
+    because a CSV is incomplete, the simulation still completes and a warning is
+    returned to the caller.
+    """
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+    label = run_label or output_path.name
+    outputs: Dict[str, Any] = {}
+
+    try:
+        realism_frame = standardize_simulation_for_realism(results_df)
+        selected_reference = _auto_realism_reference(realism_frame, realism_reference)
+        realism_report = validate_realism_dataset(realism_frame, reference=selected_reference)
+        realism_json = output_path / "realism_report.json"
+        realism_html = output_path / "realism_dashboard.html"
+        realism_markdown = output_path / "run_quality_review.md"
+        write_realism_report(realism_report, realism_json)
+        write_realism_dashboard(
+            realism_report,
+            realism_frame,
+            realism_html,
+            title="IINTS Run Realism Review",
+            source_label=label,
+        )
+        _write_run_quality_markdown(
+            realism_markdown,
+            run_label=label,
+            realism_report=realism_report,
+            selected_reference=selected_reference,
+            reference_selection=realism_reference,
+        )
+        realism_summary = {
+            "verdict": realism_report.verdict,
+            "realism_score": realism_report.realism_score,
+            "summary": realism_report.summary,
+            "reference": selected_reference,
+            "reference_selection": realism_reference,
+        }
+        if safety_report is not None:
+            safety_report["realism_review"] = realism_summary
+        outputs.update(
+            {
+                "realism_report_json": str(realism_json),
+                "realism_dashboard_html": str(realism_html),
+                "run_quality_review_md": str(realism_markdown),
+                "realism_review": realism_summary,
+            }
+        )
+    except Exception as exc:
+        outputs["realism_warning"] = str(exc)
+
+    safety_outputs = write_safety_visualizer(
+        results_df,
+        output_path / "safety_visualizer.html",
+        output_json=output_path / "safety_visualizer.json",
+        safety_report=safety_report,
+        title="IINTS Safety Contract Visualizer",
+    )
+    outputs["safety_visualizer_html"] = safety_outputs["html"]
+    outputs["safety_visualizer_json"] = safety_outputs.get("json")
+    return outputs