iints-sdk-python35 1.5.30__tar.gz → 1.5.31__tar.gz

iints_sdk_python35-1.5.31/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If you use IINTS-AF SDK in research, please cite the software and the exact release used."
+title: "IINTS-AF SDK"
+type: software
+authors:
+  - family-names: "Bobbaers"
+    given-names: "Rune"
+    email: "rune.bobbaers@gmail.com"
+version: "1.5.31"
+date-released: "2026-07-21"
+repository-code: "https://github.com/python35/IINTS-SDK"
+url: "https://iints.org"
+license: "Apache-2.0"
+keywords:
+  - diabetes technology
+  - glucose simulation
+  - digital twin
+  - research software
+  - artificial pancreas

iints_sdk_python35-1.5.31/MANIFEST.in

@@ -0,0 +1,3 @@
+include CITATION.cff
+include README.md
+include docs/*.md

{iints_sdk_python35-1.5.30/src/iints_sdk_python35.egg-info → iints_sdk_python35-1.5.31}/PKG-INFO

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: iints-sdk-python35
-Version: 1.5.30
+Version: 1.5.31
 Summary: A pre-clinical Edge-AI SDK for diabetes management validation.
 Author-email: Rune Bobbaers <rune.bobbaers@gmail.com>
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/python35/IINTS-SDK
+Project-URL: Documentation, https://python35.github.io/IINTS-SDK/
+Project-URL: Repository, https://github.com/python35/IINTS-SDK
+Project-URL: Issues, https://github.com/python35/IINTS-SDK/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -20,6 +23,7 @@ License-File: NOTICE
 License-File: LICENSE-MIT-IINTS-LEGACY
 Requires-Dist: certifi>=2024.2.2
 Requires-Dist: cryptography<50.0.0,>=48.0.1
+Requires-Dist: defusedxml<1.0.0,>=0.7.1
 Requires-Dist: fastapi!=0.136.3,<0.139.1,>=0.115.0
 Requires-Dist: numpy<3.0.0,>=1.24.0
 Requires-Dist: pandas<3.0.0,>=2.0.0
@@ -68,6 +72,10 @@ Requires-Dist: h5py<4.0.0,>=3.10.0; extra == "research"
 Requires-Dist: onnx<2.0.0,>=1.22.0; extra == "research"
 Requires-Dist: onnxscript<1.0.0,>=0.1.0; extra == "research"
 Requires-Dist: plotly<7.0.0,>=5.18.0; extra == "research"
+Provides-Extra: mechanistic
+Requires-Dist: libroadrunner<3.0.0,>=2.9.2; extra == "mechanistic"
+Provides-Extra: fmi
+Requires-Dist: FMPy<0.4.0,>=0.3.30; extra == "fmi"
 Provides-Extra: mdmp
 Requires-Dist: cryptography<50.0.0,>=48.0.1; extra == "mdmp"
 Provides-Extra: desktop
@@ -84,6 +92,26 @@ Provides-Extra: desktop-macos
 Requires-Dist: pyinstaller<7.0.0,>=6.11.0; extra == "desktop-macos"
 Requires-Dist: setuptools<84.0.0,>=83.0.0; extra == "desktop-macos"
 Requires-Dist: pyobjc-framework-Cocoa<13.0,>=10.0; extra == "desktop-macos"
+Provides-Extra: desktop-all
+Requires-Dist: FMPy<0.4.0,>=0.3.30; extra == "desktop-all"
+Requires-Dist: SciencePlots<3.0.0,>=2.1.0; extra == "desktop-all"
+Requires-Dist: fpdf2<3.0.0,>=2.8.0; extra == "desktop-all"
+Requires-Dist: h5py<4.0.0,>=3.10.0; extra == "desktop-all"
+Requires-Dist: libroadrunner<3.0.0,>=2.9.2; extra == "desktop-all"
+Requires-Dist: matplotlib<4.0.0,>=3.5.0; extra == "desktop-all"
+Requires-Dist: onnx<2.0.0,>=1.22.0; extra == "desktop-all"
+Requires-Dist: onnxscript<1.0.0,>=0.1.0; extra == "desktop-all"
+Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == "desktop-all"
+Requires-Dist: pillow<13.0.0,>=12.3.0; extra == "desktop-all"
+Requires-Dist: plotly<7.0.0,>=5.18.0; extra == "desktop-all"
+Requires-Dist: pyarrow<25.0.0,>=12.0.0; extra == "desktop-all"
+Requires-Dist: pyinstaller<7.0.0,>=6.11.0; extra == "desktop-all"
+Requires-Dist: pyobjc-framework-Cocoa<13.0,>=10.0; platform_system == "Darwin" and extra == "desktop-all"
+Requires-Dist: pyserial<4.0,>=3.5; extra == "desktop-all"
+Requires-Dist: PySide6<7.0.0,>=6.7.0; extra == "desktop-all"
+Requires-Dist: seaborn<1.0.0,>=0.11.0; extra == "desktop-all"
+Requires-Dist: setuptools<84.0.0,>=83.0.0; extra == "desktop-all"
+Requires-Dist: torch<3.0.0,>=2.13.0; extra == "desktop-all"
 Dynamic: license-file
 
 # IINTS-AF SDK
@@ -109,7 +137,7 @@ IINTS-AF is not a medical device. It must not be used for diagnosis, insulin dos
 
 ## Desktop App
 
-IINTS-AF also has a native desktop app for running demos and opening generated results without using many terminal commands. Windows and Linux beta builds use the richer Qt interface; the current macOS DMG uses a small native Cocoa fallback so it opens more reliably while the Mac Qt bundle is being hardened.
+IINTS-AF also has a native Qt desktop app for running demos, reviewing results, certifying data, and using the research workbench without memorising terminal commands. The packaged Windows, macOS, and Linux betas include their Python runtime and supported Python-side research engines.
 
 Current beta downloads:
 
@@ -122,7 +150,7 @@ Current beta downloads:
 Python install, including the PySide6 desktop runtime:
 
 ```bash
-python -m pip install -U "iints-sdk-python35[full,desktop,mdmp]"
+python -m pip install -U "iints-sdk-python35[desktop-all]"
 iints-desktop
 ```
 

{iints_sdk_python35-1.5.30 → iints_sdk_python35-1.5.31}/README.md

@@ -21,7 +21,7 @@ IINTS-AF is not a medical device. It must not be used for diagnosis, insulin dos
 
 ## Desktop App
 
-IINTS-AF also has a native desktop app for running demos and opening generated results without using many terminal commands. Windows and Linux beta builds use the richer Qt interface; the current macOS DMG uses a small native Cocoa fallback so it opens more reliably while the Mac Qt bundle is being hardened.
+IINTS-AF also has a native Qt desktop app for running demos, reviewing results, certifying data, and using the research workbench without memorising terminal commands. The packaged Windows, macOS, and Linux betas include their Python runtime and supported Python-side research engines.
 
 Current beta downloads:
 
@@ -34,7 +34,7 @@ Current beta downloads:
 Python install, including the PySide6 desktop runtime:
 
 ```bash
-python -m pip install -U "iints-sdk-python35[full,desktop,mdmp]"
+python -m pip install -U "iints-sdk-python35[desktop-all]"
 iints-desktop
 ```
 

iints_sdk_python35-1.5.31/docs/ACADEMIC_RESEARCH_WORKBENCH.md

@@ -0,0 +1,99 @@
+# Academic Research Workbench
+
+IINTS-AF can add a reviewable academic metadata layer to a completed simulation run. The goal is practical reproducibility: another researcher should be able to identify the software, configuration, seed, artifacts, checksums, and references without relying on a screenshot or an AI summary.
+
+!!! warning "Scope"
+    An academic package is not peer review, ethical approval, privacy clearance, clinical validation, or medical-device certification. It does not upload data. Review every artifact before sharing it.
+
+## Create A Package
+
+```bash
+iints research academic-bundle results/my_run \
+  --title "Baseline T1D reproducibility run" \
+  --creator "Researcher Name" \
+  --orcid "https://orcid.org/0000-0000-0000-0000" \
+  --license "CC-BY-4.0"
+```
+
+To associate references explicitly, repeat `--source-id`:
+
+```bash
+iints research academic-bundle results/my_run \
+  --source-id hovorka_2004_nmpc_t1d \
+  --source-id attd_2019_time_in_range
+```
+
+When no source IDs are supplied, the exporter makes only conservative associations that can be inferred from run metadata and artifacts. These associations are candidates for human review, not proof that a paper validates the implementation.
+
+The run-artifact licence defaults to `NOASSERTION`. The SDK code is Apache-2.0, but that software licence is not silently applied to real-data-derived CSV files, reports, or other research artifacts. Choose a data/output licence only when you have the right to do so.
+
+The same operation is available in both desktop workbenches from the **Results** or **Reproducibility package** area.
+
+## Generated Files
+
+| File | Purpose |
+| --- | --- |
+| `ro-crate-metadata.json` | [RO-Crate 1.2](https://www.researchobject.org/ro-crate/specification/1.2/introduction.html) JSON-LD with run, software, file, checksum, creator, licence, and source entities |
+| `academic_audit.json` | machine-readable checks for metadata, seed, configuration, manifest, revision, sources, attribution, licence, artifact inventory, and basic privacy markers |
+| `academic_sources.json` | exact evidence-registry snapshot, registry hash, selected sources, and selection method |
+| `ACADEMIC_BUNDLE.md` | short human review guide stored with the run |
+
+Existing experimental files are not copied or rewritten. The exporter reads them to calculate SHA-256 checksums and then writes the four metadata files beside them.
+
+## Readiness Status
+
+| Status | Meaning |
+| --- | --- |
+| `ready` | all implemented required, recommended, and review checks passed |
+| `needs_review` | required metadata exists, but one or more recommended or human-review checks remain |
+| `incomplete` | a required artifact or metadata field is missing |
+
+The score measures only the implemented checklist. A high score does not mean that a model is physiologically accurate or that a dataset may legally be shared.
+
+## Academic Integration Levels
+
+The app labels every external resource by maturity so a portal link cannot be mistaken for a functioning scientific integration.
+
+| Level | Meaning | Current examples |
+| --- | --- | --- |
+| Integrated | the SDK calls a defined local/API workflow and writes a reviewable artifact | RO-Crate export; AlphaFold; SBML/libRoadRunner; COPASI; CellML/OpenCOR validation; FMI/FMPy; BindingDB |
+| Partial | a useful query or render exists, but full versioned import and validation are not complete | GTEx expression, ChEMBL context, STRING networks, ClinVar context |
+| Planned | a scientifically useful boundary is documented but not implemented | SED-ML protocol export, automatic Physiome repository import, structured PubMed capture |
+| Portal | the app opens an official allowlisted resource; no evidence is ingested | RCSB PDB, UniProt, Human Protein Atlas, ClinicalTrials.gov, Zenodo |
+
+## Standards Direction
+
+- [FAIR4RS](https://www.nature.com/articles/s41597-022-01710-x) guides software citation, metadata, access, interoperability, and reuse. IINTS-AF is FAIR-oriented; it is not externally FAIR-certified.
+- [RO-Crate 1.2](https://www.researchobject.org/ro-crate/specification/1.2/introduction.html) is implemented for run-level metadata and artifact inventory.
+- [SED-ML Level 1 Version 5](https://sed-ml.org/) is the planned portable description for model/simulation/task/output protocols. IINTS-AF does not yet claim SED-ML compatibility.
+- [SBML Level 3 Version 2](https://sbml.org/documents/specifications/) is supported for safe structural inspection of local reference files. Optional independent execution uses libRoadRunner. Current Python patient models are not claimed to be SBML models.
+- [BioModels](https://www.biomodels.org/) is useful for model provenance and comparison. Automatic repository import is not implemented; local model files can be inspected only after the researcher has reviewed their source and licence.
+- [Zenodo](https://developers.zenodo.org/) remains a manual publication route after privacy, licensing, and completeness review; the SDK never uploads automatically.
+
+## Evidence Rules
+
+1. Record the exact database, identifier, query, access date, and local artifact hash.
+2. Prefer primary publications and official database records over summaries.
+3. Keep structural confidence, variant assertions, expression evidence, and physiological parameters separate.
+4. Never convert AlphaFold pLDDT or PAE directly into pathogenicity, insulin sensitivity, or a dosing parameter.
+5. Never let external evidence or local AI silently alter the deterministic simulation configuration.
+6. Preserve failed runs, exclusions, software versions, and changed assumptions.
+7. Review direct and indirect identifiers before publishing any real-patient-derived data.
+
+## Recommended Paper Workflow
+
+```mermaid
+flowchart LR
+    A["Freeze protocol and hypotheses"] --> B["Run with recorded seeds"]
+    B --> C["Validate raw artifacts"]
+    C --> D["Create academic package"]
+    D --> E["Resolve audit findings"]
+    E --> F["Review privacy and licences"]
+    F --> G["Archive code, environment, and approved outputs"]
+```
+
+Use deterministic metrics and raw time series as the numerical authority. Local AI can help critique or explain a run, but its response is a review note and is not included as ground truth.
+
+For independent external equation-model checks, use [Mechanistic Reference Models](MECHANISTIC_REFERENCE_MODELS.md). Reference execution remains separate from IINTS calibration so a successful solver run cannot silently change the virtual patient.
+
+For sensitivity tasks, CellML validation, physical-device FMUs, and measured affinity evidence, continue with [Cross-scale Reference Labs](CROSS_SCALE_REFERENCE_LABS.md). These outputs remain separate evidence layers and require explicit mappings before comparison.

iints_sdk_python35-1.5.31/docs/AI_ASSISTANT.md

@@ -0,0 +1,455 @@
+# AI Assistant Guide
+
+Use this guide when you want local AI help for explaining validated outputs, without giving the model dosing authority.
+
+By the end, you should understand what the assistant can do, how MDMP gating protects the workflow, and how to run the local setup end to end.
+
+## Scope
+
+- Research use only.
+- Not a medical device.
+- No clinical dosing advice.
+- AI output is blocked unless MDMP verification succeeds first.
+
+## What The AI Layer Does
+
+The local AI assistant is designed for four narrow tasks:
+
+- `explain`: explain a single simulation step in plain language
+- `trends`: summarize glucose-oriented trends from a payload
+- `anomalies`: call out unusual or safety-relevant patterns
+- `report`: generate a short markdown run summary
+
+The assistant is intentionally conservative. It explains simulation behavior or imported glucose data patterns; it does not produce treatment advice.
+
+## Architecture
+
+The flow is:
+
+1. `iints ai ...` loads a JSON payload from disk.
+2. `MDMPGuard` verifies the signed MDMP artifact and enforces the minimum grade.
+3. `IINTSAssistant` selects the backend.
+4. `OllamaBackend` checks that Ollama is reachable and that a local open Ministral 3 tag is installed.
+5. The prompt is built from a fixed system instruction plus a serialized payload.
+6. The response is wrapped with a hard-coded research-only disclaimer before output is shown or saved.
+
+## Local Backend Behavior
+
+The SDK defaults to local inference through Ollama.
+
+Default model:
+
+```bash
+ministral-3:8b
+```
+
+Supported convenience aliases include:
+
+- `ministral`
+- `ministral-3`
+- `ministral-3:8b`
+- `ministral-8b`
+- `ministral-8b-instruct`
+
+If the alias is used, IINTS resolves it to the installed local Ollama tag before generation.
+
+## Mistral Serverless API Migration
+
+The local SDK default is not affected by Mistral Serverless API retirements, because IINTS uses Ollama unless you explicitly build an external cloud workflow. For cloud-side scripts, use the current replacements:
+
+| Old family | New model |
+| --- | --- |
+| Devstral Small / Magistral Small / Mistral Small 3.2 | `mistral-small-latest` with `reasoning_effort="high"` |
+| Devstral Medium / Magistral Medium / Mistral Large 2 / Pixtral Large / Mistral Medium 3.x | `mistral-medium-3-5` with `reasoning_effort="high"` for code or research-review tasks |
+| Mistral OCR 2 | `mistral-ocr-latest` |
+| Mistral Moderation | `mistral-moderation-2603` |
+| Voxtral Mini Transcribe 1.0 | `voxtral-mini-latest` |
+
+Run the built-in migration table:
+
+```bash
+iints ai models
+```
+
+See [Mistral Model Migration](MISTRAL_MODEL_MIGRATION.md) for the full mapping.
+
+## Fastest Working Setup
+
+Always work from an active virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[full,mdmp]"
+```
+
+## Full Ollama Setup
+
+This is the shortest reliable setup if you want the local AI layer working end to end.
+
+### 1. Install the SDK
+
+Released SDK:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -U "iints-sdk-python35[full,mdmp]"
+```
+
+Source checkout:
+
+```bash
+cd /path/to/IINTS-SDK
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -U -e ".[full,mdmp]"
+```
+
+### 2. Install Ollama
+
+On macOS/Linux, the quick official path is:
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+ollama -v
+```
+
+If you are on Windows, install Ollama first via the official installer and then reopen your terminal.
+
+### 3. Start Ollama
+
+```bash
+ollama serve
+```
+
+If Ollama is already running as a service, you do not need to start it manually again.
+
+### 4. Pull a local model
+
+Balanced default:
+
+```bash
+ollama pull ministral-3:8b
+```
+
+Smaller fallback:
+
+```bash
+ollama pull ministral-3:3b
+```
+
+### 5. Link Ollama to the SDK
+
+By default, the SDK looks for Ollama here:
+
+```text
+http://127.0.0.1:11434
+```
+
+So on a normal single-machine setup, there is nothing extra to configure.
+
+If you want to set it explicitly:
+
+```bash
+export OLLAMA_HOST=http://127.0.0.1:11434
+```
+
+If you want to override it for one command only:
+
+```bash
+iints ai local-check \
+  --model ministral-3:8b \
+  --ollama-host http://127.0.0.1:11434
+```
+
+Important notes:
+
+- `OLLAMA_HOST` is the normal way to point the SDK at a non-default local Ollama endpoint.
+- Remote Ollama endpoints are blocked by default. Only enable them deliberately.
+- If you truly want to connect to a non-loopback Ollama host, you must also set `IINTS_ALLOW_REMOTE_OLLAMA=1`.
+
+### 6. Verify the full chain
+
+Install and check the local model:
+
+```bash
+ollama pull ministral-3:8b
+iints ai local-check --model ministral-3:8b
+```
+
+If the model is missing, the command fails with the exact `ollama pull ...` command to run next.
+If your Ollama runtime is too old for the open Ministral 3 line, `local-check` now tells you that as well.
+`local-check` also runs a tiny generation smoke-test by default, so it catches the common case where `/api/tags` works but the model crashes during real inference.
+The current Ollama listing for `ministral-3` expects Ollama `0.13.1` or newer.
+
+## Hardware Recommendations
+
+Use this as a practical starting point:
+
+| Model | Good Fit | Recommended System RAM | Recommended GPU VRAM | Approx Download |
+|---|---|---:|---:|---:|
+| `ministral-3:3b` | smaller laptops, CPU-first setups, entry-level edge boxes | 16 GB | 6 GB | ~3 GB |
+| `ministral-3:8b` | balanced desktop or strong laptop | 24 GB | 10 GB | ~6 GB |
+| `ministral-3:14b` | high-end workstation | 32 GB | 16 GB | ~10 GB |
+
+General advice:
+
+- Start with `ministral-3:8b` unless you have a specific reason to go smaller or larger.
+- Choose `ministral-3:3b` if latency and memory matter more than answer quality.
+- Choose `ministral-3:14b` only if your machine can comfortably absorb the extra RAM and latency.
+- Run `iints ai models` in the CLI to see the same recommendations in a terminal-friendly table.
+- If `ministral-3:8b` closes the connection during generation, try `ministral-3:3b` first before assuming something is wrong with the SDK.
+
+## Recommended Run Workflow
+
+After a run completes, prepare the run directory once:
+
+```bash
+iints ai prepare results/<run_id>
+```
+
+That command creates:
+
+- `ai/report_payload.json`
+- `ai/anomalies_payload.json`
+- `ai/trends_payload.json`
+- `ai/step_riskiest.json`
+- `ai/step_latest.json`
+- `ai/report.signed.mdmp` plus `ai/keys/` when the MDMP extra is installed
+
+After that, you can point the AI commands directly at the run directory:
+
+```bash
+iints ai explain results/<run_id>
+iints ai trends results/<run_id>
+iints ai anomalies results/<run_id>
+iints ai report results/<run_id> --output results/<run_id>/ai/ai_report.md
+iints ai review results/<run_id>
+```
+
+For imported CareLink data, generate a personal workspace first:
+
+```bash
+iints carelink-workbench \
+  --input-csv "/path/to/CareLink export.csv" \
+  --output-dir results/personal_carelink
+```
+
+That creates:
+
+- `carelink_dashboard.png`
+- `carelink_poster.png`
+- `carelink_dashboard.html`
+- `carelink_timeline.csv`
+- `carelink_metrics.json`
+- `ai/report_payload.json`
+- `ai/review_payload.json`
+- `ai/trends_payload.json`
+- `ai/anomalies_payload.json`
+- `ai/step_riskiest.json`
+- `ai/report.signed.mdmp` when the MDMP extra is installed
+
+After that, the same AI commands work directly on the CareLink workspace directory:
+
+```bash
+iints ai report results/personal_carelink --model ministral-3:3b
+iints ai review results/personal_carelink --model ministral-3:3b
+iints ai trends results/personal_carelink --model ministral-3:3b
+iints ai explain results/personal_carelink --model ministral-3:3b
+```
+
+## Digital Patient Review
+
+The Raspberry Pi live runtime also plugs into the same AI layer.
+
+After a live patient session has written its bundle under `patient_runtime/live_bundle/`, run:
+
+```bash
+iints patient review \
+  --workspace patient_runtime \
+  --model ministral-3:3b
+```
+
+That automatically prepares the runtime bundle, checks the MDMP gate, and writes:
+
+- `patient_runtime/live_bundle/ai/realism_review.md`
+
+This is useful for expo demos where you want the Pi to both simulate and critique the realism of the current run.
+
+## Generation Commands
+
+Prepared run directory mode:
+
+```bash
+iints ai explain results/<run_id>
+iints ai trends results/<run_id>
+iints ai anomalies results/<run_id>
+iints ai report results/<run_id> --output results/<run_id>/ai/ai_report.md
+iints ai review results/<run_id>
+```
+
+Prepared CareLink workspace mode:
+
+```bash
+iints carelink-workbench \
+  --input-csv "/path/to/CareLink export.csv" \
+  --output-dir results/personal_carelink
+
+iints ai report results/personal_carelink --model ministral-3:3b
+iints ai review results/personal_carelink --model ministral-3:3b
+iints ai trends results/personal_carelink --model ministral-3:3b
+iints ai explain results/personal_carelink --model ministral-3:3b
+```
+
+Direct JSON mode:
+
+```bash
+iints ai explain results/step.json \
+  --mdmp-cert results/report.signed.mdmp
+
+iints ai trends results/glucose_payload.json \
+  --mdmp-cert results/report.signed.mdmp
+
+iints ai anomalies results/simulation_run.json \
+  --mdmp-cert results/report.signed.mdmp
+
+iints ai report results/simulation_run.json \
+  --mdmp-cert results/report.signed.mdmp \
+  --output results/ai_report.md
+
+iints ai review results/simulation_run.json \
+  --mdmp-cert results/report.signed.mdmp \
+  --output results/realism_review.md
+```
+
+`iints ai review` writes a realism-focused critique. When you point it at a prepared run directory and do not pass `--output`, it automatically saves to `results/<run_id>/ai/realism_review.md`.
+
+The review now asks the local model to always structure feedback as:
+
+- overall realism verdict
+- what looks realistic
+- what looks suspicious
+- priority fixes
+- what to improve next
+- follow-up validation checks
+
+Useful options:
+
+- `--mode local` to require Ollama explicitly
+- `--model ministral-3:8b` or `--model ministral`
+- `--model ministral-3:3b` for lighter machines
+- `--model ministral-3:14b` for stronger workstations
+- `--ollama-host http://127.0.0.1:11434` to override the endpoint
+- `--timeout-seconds 120` for slower local hardware
+- `--minimum-grade research_grade` to raise or lower the MDMP floor
+
+## How Reliability Is Enforced
+
+For local robustness, the SDK now does four checks before a real generation call:
+
+- verifies that the Ollama HTTP endpoint is reachable
+- verifies that a compatible local open Ministral 3 model is installed
+- normalizes common local model aliases to the installed tag
+- truncates oversized JSON payloads before prompt construction so large run artifacts do not overwhelm local inference
+- flags too-old Ollama runtimes when they do not meet the minimum version expected for the open Ministral 3 line
+
+If a generation succeeds, the response records the actual resolved model name used by the local backend.
+
+## MDMP Guard Behavior
+
+The AI assistant does not run on unsigned or insufficiently graded artifacts.
+
+The guard enforces:
+
+- signed MDMP verification
+- minimum grade threshold
+- hard-coded disclaimer injection on every response
+
+That means the research-only warning is not dependent on the prompt and cannot be removed by changing prompt text alone.
+
+## Troubleshooting
+
+### Ollama Not Reachable
+
+Run:
+
+```bash
+iints ai local-check --model ministral-3:8b
+```
+
+This now checks both basic reachability and a tiny real generation.
+
+If the endpoint is wrong, retry with:
+
+```bash
+iints ai local-check --model ministral-3:8b --ollama-host http://127.0.0.1:11434
+```
+
+### Model Missing
+
+Pull the model shown in the error output:
+
+```bash
+ollama pull ministral-3:8b
+```
+
+### Local Inference Is Slow
+
+Increase the timeout:
+
+```bash
+iints ai report results/simulation_run.json \
+  --mdmp-cert results/report.signed.mdmp \
+  --timeout-seconds 180
+```
+
+If the server disconnects instead of timing out, the model may be too heavy for the machine at that moment. In that case try:
+
+```bash
+ollama pull ministral-3:3b
+iints ai local-check --model ministral-3:3b
+iints ai report results/<run_id> --model ministral-3:3b
+```
+
+### Large Run Payloads
+
+The assistant now clips oversized payloads automatically before sending them to the model. If you want tighter control, pass a smaller JSON summary rather than a full raw run dump.
+
+### No `report.signed.mdmp` In My Run Folder
+
+That is now expected for a fresh raw run. The easiest fix is:
+
+```bash
+iints ai prepare results/<run_id>
+```
+
+This creates a local development certificate for AI use when the MDMP extra is available, so you do not have to hand-build `step.json` and `report.signed.mdmp` yourself.
+
+### `No such command 'ai'`
+
+If the CLI says `No such command 'ai'`, the most common cause is a legacy `iints` package still being installed beside `iints-sdk-python35`. That older package can shadow the newer SDK command tree.
+
+Run the install doctor:
+
+```bash
+iints-sdk-doctor
+```
+
+If it reports a package ownership conflict, repair the environment:
+
+```bash
+python -m pip uninstall -y iints iints-sdk-python35
+python -m pip install -U "iints-sdk-python35[full,mdmp]"
+hash -r
+```
+
+Then retry:
+
+```bash
+iints ai models
+iints ai local-check --model ministral-3:8b
+```