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

{iints_sdk_python35-1.5.31 → iints_sdk_python35-1.5.32}/CITATION.cff

@@ -6,8 +6,8 @@ authors:
   - family-names: "Bobbaers"
     given-names: "Rune"
     email: "rune.bobbaers@gmail.com"
-version: "1.5.31"
-date-released: "2026-07-21"
+version: "1.5.32"
+date-released: "2026-07-23"
 repository-code: "https://github.com/python35/IINTS-SDK"
 url: "https://iints.org"
 license: "Apache-2.0"

{iints_sdk_python35-1.5.31 → iints_sdk_python35-1.5.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iints-sdk-python35
-Version: 1.5.31
+Version: 1.5.32
 Summary: A pre-clinical Edge-AI SDK for diabetes management validation.
 Author-email: Rune Bobbaers <rune.bobbaers@gmail.com>
 License-Expression: Apache-2.0
@@ -133,9 +133,28 @@ IINTS-AF is not a medical device. It must not be used for diagnosis, insulin dos
 
 - Website: [iints.org](https://iints.org)
 - Documentation: [python35.github.io/IINTS-SDK](https://python35.github.io/IINTS-SDK/)
-- Desktop app downloads: [latest beta](https://github.com/python35/IINTS-SDK/releases/tag/desktop-beta-latest)
+- Rust research workbench: [latest beta](https://github.com/python35/IINTS-SDK/releases/tag/tauri-beta-latest)
+- Classic desktop app: [latest Qt beta](https://github.com/python35/IINTS-SDK/releases/tag/desktop-beta-latest)
 
-## Desktop App
+## Rust Research Workbench
+
+The new native research workbench uses a Rust/Tauri security boundary around the Python scientific engine. It provides guided simulation workflows, result inspection, reproducibility records, local Ollama review, MDMP evidence tools, and audited research connectors.
+
+Current Rust/Tauri beta downloads:
+
+| Platform | Download |
+| --- | --- |
+| Windows | [`.exe` installer](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-windows-x64-setup.exe) |
+| macOS | [`.dmg`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-macos.dmg) |
+| Linux | [`.AppImage`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-linux-x64.AppImage) |
+
+The beta delegates scientific operations to the IINTS-AF Python engine. On first launch, choose
+**Install Python engine** if the bridge is unavailable; the app creates a private engine and keeps
+its setup visible in a terminal.
+
+See the [Tauri workbench documentation](https://python35.github.io/IINTS-SDK/TAURI_DESKTOP/) for architecture, security boundaries, and development instructions.
+
+## Classic Desktop App
 
 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.
 
@@ -154,8 +173,6 @@ python -m pip install -U "iints-sdk-python35[desktop-all]"
 iints-desktop
 ```
 
-Experimental next-generation shell: a Tauri + Rust desktop prototype lives in `apps/iints-tauri`. It keeps the Python SDK as the scientific engine while moving the native app boundary into Rust. See `docs/TAURI_DESKTOP.md`.
-
 ## License
 
 Apache-2.0 licensed, with legacy MIT notices where applicable.

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

@@ -17,9 +17,28 @@ IINTS-AF is not a medical device. It must not be used for diagnosis, insulin dos
 
 - Website: [iints.org](https://iints.org)
 - Documentation: [python35.github.io/IINTS-SDK](https://python35.github.io/IINTS-SDK/)
-- Desktop app downloads: [latest beta](https://github.com/python35/IINTS-SDK/releases/tag/desktop-beta-latest)
+- Rust research workbench: [latest beta](https://github.com/python35/IINTS-SDK/releases/tag/tauri-beta-latest)
+- Classic desktop app: [latest Qt beta](https://github.com/python35/IINTS-SDK/releases/tag/desktop-beta-latest)
 
-## Desktop App
+## Rust Research Workbench
+
+The new native research workbench uses a Rust/Tauri security boundary around the Python scientific engine. It provides guided simulation workflows, result inspection, reproducibility records, local Ollama review, MDMP evidence tools, and audited research connectors.
+
+Current Rust/Tauri beta downloads:
+
+| Platform | Download |
+| --- | --- |
+| Windows | [`.exe` installer](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-windows-x64-setup.exe) |
+| macOS | [`.dmg`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-macos.dmg) |
+| Linux | [`.AppImage`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-linux-x64.AppImage) |
+
+The beta delegates scientific operations to the IINTS-AF Python engine. On first launch, choose
+**Install Python engine** if the bridge is unavailable; the app creates a private engine and keeps
+its setup visible in a terminal.
+
+See the [Tauri workbench documentation](https://python35.github.io/IINTS-SDK/TAURI_DESKTOP/) for architecture, security boundaries, and development instructions.
+
+## Classic Desktop App
 
 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.
 
@@ -38,8 +57,6 @@ python -m pip install -U "iints-sdk-python35[desktop-all]"
 iints-desktop
 ```
 
-Experimental next-generation shell: a Tauri + Rust desktop prototype lives in `apps/iints-tauri`. It keeps the Python SDK as the scientific engine while moving the native app boundary into Rust. See `docs/TAURI_DESKTOP.md`.
-
 ## License
 
 Apache-2.0 licensed, with legacy MIT notices where applicable.

iints_sdk_python35-1.5.32/docs/APP_INSTALL.md

@@ -0,0 +1,104 @@
+# Desktop App Installation
+
+The IINTS-AF Research Workbench is the recommended desktop interface for the Python research SDK. It uses a native Rust/Tauri shell and keeps simulation, validation, reporting, and research calculations inside the Python SDK.
+
+!!! warning "Research scope"
+    IINTS-AF is research and education software. It is not a medical device and must not be used for diagnosis, dosing, treatment decisions, or real-time patient care.
+
+## Download The Current Beta
+
+The stable links below always point to the newest tested Tauri beta:
+
+| Platform | Installer | Start |
+| --- | --- | --- |
+| Windows | [Download `.exe`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-windows-x64-setup.exe) | run the setup file, then open **IINTS-AF Research Workbench** |
+| macOS | [Download `.dmg`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-macos.dmg) | open the DMG, drag the app to Applications, then open it |
+| Linux | [Download `.AppImage`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-linux-x64.AppImage) | mark it executable, then run it |
+
+Matching `.sha256` files are published beside each installer. See [Desktop App Signing](DESKTOP_SIGNING.md) for signature and notarization details.
+
+## First Launch
+
+The native app needs the IINTS-AF Python engine for scientific calculations. The app now handles this setup through a visible, fixed maintenance command:
+
+1. Open the workbench.
+2. If **Python bridge unavailable** appears, select **Install Python engine** on Overview, or open **Settings** and select **Install or update Python SDK**.
+3. Keep the terminal open while the installation completes.
+4. Return to the app and select **Refresh versions**.
+5. Run **Run diagnostics** before the first experiment.
+
+The app creates a private environment at `~/.iints-af/python-engine`. It does not modify an unrelated project virtual environment. On later runs, the same action updates or repairs that private engine.
+
+The bootstrap requires Python `3.10` through `3.14`. On macOS, the app checks common Homebrew, MacPorts, and Python.org framework locations before the limited Finder application `PATH`. Advanced users can override discovery with `IINTS_PYTHON`.
+
+### Manual Fallback
+
+If Python is not installed, install a current release from [python.org](https://www.python.org/downloads/), reopen the app, and use **Install or update Python SDK** again.
+
+Advanced users may prepare the engine manually:
+
+=== "macOS or Linux"
+
+    ```bash
+    python3 -m venv "$HOME/.iints-af/python-engine"
+    "$HOME/.iints-af/python-engine/bin/python" -m pip install --upgrade pip "iints-sdk-python35[desktop-all]"
+    ```
+
+=== "Windows PowerShell"
+
+    ```powershell
+    py -3 -m venv "$HOME\.iints-af\python-engine"
+    & "$HOME\.iints-af\python-engine\Scripts\python.exe" -m pip install --upgrade pip "iints-sdk-python35[desktop-all]"
+    ```
+
+## macOS Security Messages
+
+The CI pipeline verifies the complete app bundle inside the finished DMG. Public downloads still require Apple Developer ID signing and notarization to avoid all Gatekeeper warnings.
+
+If an official beta is ad-hoc signed, macOS may report an unidentified developer. Use Finder's **Open** context-menu action once. Do not disable Gatekeeper system-wide. If macOS reports that the app is damaged, download the newest DMG again and verify its SHA-256 value; do not bypass a failed integrity check.
+
+## Linux AppImage
+
+If the file is not executable:
+
+```bash
+chmod +x IINTS-AF-Research-Workbench-linux-x64.AppImage
+./IINTS-AF-Research-Workbench-linux-x64.AppImage
+```
+
+The private Python engine still needs a system Python with `venv` support. On Debian or Ubuntu, a missing `venv` module is normally supplied by the distribution's `python3-venv` package.
+
+## Optional External Tools
+
+The SDK package installs supported Python libraries. Large or independently licensed external applications remain explicit:
+
+- Ollama and local model files
+- COPASI
+- OpenCOR
+- trusted FMUs or external model files
+
+The workbench detects these tools and explains which feature needs them. It does not silently download executables, model weights, or native-code FMUs.
+
+## Python And Classic Qt App
+
+Researchers who prefer a Python-managed desktop environment can still install the classic Qt interface:
+
+```bash
+python -m pip install --upgrade "iints-sdk-python35[desktop-all]"
+iints-desktop
+```
+
+The classic packaged beta remains available from the [`desktop-beta-latest` release](https://github.com/python35/IINTS-SDK/releases/tag/desktop-beta-latest), but the Rust/Tauri workbench is the recommended desktop route.
+
+## Troubleshooting
+
+| Message or symptom | Action |
+| --- | --- |
+| Python bridge unavailable | select **Install Python engine**, wait for the terminal, then select **Refresh versions** |
+| Python 3.10-3.14 was not found | install Python from python.org and repeat the maintenance action |
+| `No module named iints_desktop` | update or repair the private engine from Settings; the selected Python does not contain the SDK bridge |
+| protocol list is empty | refresh versions, run diagnostics, then refresh protocols |
+| optional research engine unavailable | install only the external engine required by that lab |
+| app update available | close the app and install the newest file from the stable beta release |
+
+For the complete illustrated workflow, continue with the [Research Workbench User Guide](RESEARCH_WORKBENCH_GUIDE.md).

{iints_sdk_python35-1.5.31 → iints_sdk_python35-1.5.32}/docs/DESKTOP_APP.md

@@ -4,6 +4,8 @@ The IINTS-AF desktop app is a graphical workbench for the same Python SDK used b
 
 The app does not contain a second physiology or safety engine.
 
+For a visual, step-by-step walkthrough, start with the [Research Workbench User Guide](RESEARCH_WORKBENCH_GUIDE.md).
+
 ```mermaid
 flowchart LR
     A["Desktop interface"] --> B["Audited app bridge"]

iints_sdk_python35-1.5.32/docs/RESEARCH_WORKBENCH_GUIDE.md

@@ -0,0 +1,294 @@
+# Research Workbench User Guide
+
+The IINTS-AF Research Workbench is the native desktop interface for the Python SDK. It helps you run a protocol, inspect its outputs, create reproducibility evidence, and request a local AI review without reimplementing scientific logic in the app.
+
+!!! warning "Research scope"
+    IINTS-AF is research and education software. It is not a medical device and must not be used for diagnosis, insulin dosing, treatment decisions, or real-time patient care.
+
+!!! info "About the screenshots"
+    The screenshots below use a labelled documentation fixture. The values illustrate the interface only; they are not study results or validation evidence.
+
+## Install And Open
+
+Use the current native beta installer for your platform:
+
+| Platform | Installer |
+| --- | --- |
+| Windows | [Download `.exe`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-windows-x64-setup.exe) |
+| macOS | [Download `.dmg`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-macos.dmg) |
+| Linux | [Download `.AppImage`](https://github.com/python35/IINTS-SDK/releases/download/tauri-beta-latest/IINTS-AF-Research-Workbench-linux-x64.AppImage) |
+
+The native app delegates calculations to the Python SDK. If Overview reports that the Python engine is unavailable, select **Install Python engine**. The same action is available under **Settings → Install or update Python SDK**.
+
+The app opens a terminal with a fixed Rust-owned command, creates a private engine at `~/.iints-af/python-engine`, and installs the supported SDK dependencies there. After completion, return to the app and select **Refresh versions**. This avoids relying on the limited `PATH` inherited by a macOS Finder launch and does not modify an unrelated project environment.
+
+Python `3.10` through `3.14` must be available on the computer. The [installation guide](APP_INSTALL.md) includes a manual fallback when automatic discovery cannot find it.
+
+### Native interaction
+
+The installed app deliberately behaves like a desktop workbench rather than a website:
+
+- labels, navigation, and buttons cannot be accidentally selected or dragged
+- inputs, logs, AI answers, result values, and tables remain selectable for research work
+- the browser context menu is suppressed outside those copyable data areas
+- scientific charts appear immediately without decorative drawing animations
+- embedded browser developer tools are disabled in the packaged application
+- folder and model/result locations use native macOS, Windows, or Linux selectors; paths remain
+  editable for advanced reproducibility workflows
+
+Use <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>O</kbd> to open the result-file selector and
+<kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>,</kbd> to open Settings.
+
+These interface rules do not restrict access to generated artifacts; files remain available in the selected output folder.
+
+## The Normal Workflow
+
+Use the left navigation in this order:
+
+1. **Overview** — verify the local engine and optional tools.
+2. **Run protocols** — choose a protocol, output folder, and deterministic seed.
+3. **Inspect results** — review metrics, the glucose trace, and CSV rows.
+4. **Reproducibility** — create checksums, metadata, and an audit package.
+5. **Local AI review** — optionally ask Ollama to summarize the loaded result.
+6. **Research tools** — use independent biology, equation-model, or device-physics tools.
+7. **Evidence sources** — inspect connector status and open official resources.
+8. **Settings** — save local defaults, check versions, update software, and open help.
+
+## 1. Check The Environment
+
+![IINTS-AF overview showing engine readiness and software versions](assets/workbench/01-overview.png)
+
+Select **Run diagnostics** before a new experiment. A normal ready environment shows:
+
+- the installed IINTS-AF SDK version
+- the Python version used by the app bridge
+- whether Ollama is available
+- readiness of optional modules such as MDMP, Plotly, libRoadRunner, and FMPy
+
+Missing optional modules do not always block a normal simulation. They only block the feature that depends on them.
+
+Equivalent terminal check:
+
+```bash
+iints doctor
+python -c "import iints; print(iints.__version__)"
+```
+
+## 2. Run A Protocol
+
+![Protocol selection, deterministic seed, output folder, and run history](assets/workbench/02-run-protocol.png)
+
+1. Select one protocol in the left panel.
+2. Select **Choose folder...** and choose an output location you can archive later.
+3. Record the seed. The default `42` is suitable for a reproducible first run.
+4. Select **Run selected protocol**.
+5. Wait until the status field reports completion or a recorded error.
+
+Do not compare runs unless their protocol, SDK version, patient profile, time step, and seed policy are recorded.
+
+The app calls the same SDK engine used by CLI workflows. A typical command-line equivalent is:
+
+```bash
+iints presets run \
+  --name realistic_reference_day \
+  --algo algorithms/example_algorithm.py \
+  --seed 42 \
+  --output-dir results/reference_day_seed_42
+```
+
+The exact equivalent command can differ by curated desktop protocol. Treat the generated run configuration as the authoritative record.
+
+## 3. Inspect Results
+
+![Results workspace with summary metrics and a glucose trajectory](assets/workbench/03-results.png)
+
+After a desktop protocol completes, the app loads its `results.csv` automatically. To inspect an
+existing run, select **Choose CSV...**, choose the local file, and then select **Load preview**.
+Advanced users may still edit the displayed path directly.
+
+Review these parts together:
+
+- **Result status** — confirms the file and row count that were loaded.
+- **Summary metrics** — compact orientation metrics, not a complete analysis.
+- **Glucose trajectory** — a bounded visual preview with the configured 70–180 mg/dL reference band.
+- **Tabular preview** — the first bounded rows from the source CSV.
+- **MDMP certificate** — data-contract checks for the selected CSV.
+
+The preview is read-only. It must not silently interpolate, repair, or overwrite the source CSV.
+
+Useful CLI checks:
+
+```bash
+iints report --results-csv path/to/results.csv --style agp
+iints data certify data_contract.yaml path/to/results.csv --quick
+```
+
+Read [Understand A Run](RUN_OUTPUTS.md) before using a preview as evidence in a study.
+
+## 4. Create A Reproducibility Package
+
+![Reproducibility package form with run path, creator, ORCID, licence, and evidence IDs](assets/workbench/05-reproducibility.png)
+
+Open **Reproducibility** after loading a completed run.
+
+1. Confirm the completed run folder or select **Choose folder...** to locate one.
+2. Add a descriptive package title.
+3. Add the researcher name and ORCID when appropriate.
+4. Leave the run-artifact licence as `NOASSERTION` unless you know which licence applies to every exported artifact.
+5. Add explicit evidence source IDs only when those sources support the run.
+6. Select **Create academic package**.
+
+The package stays local. It adds RO-Crate metadata, checksums, a source snapshot, and an audit report. A successful export is not peer review, privacy approval, or clinical validation.
+
+Equivalent CLI command:
+
+```bash
+iints research academic-bundle path/to/completed_run
+```
+
+See [Academic Research Workbench](ACADEMIC_RESEARCH_WORKBENCH.md) for artifact definitions.
+
+## 5. Use Local AI Review
+
+![Local AI workspace showing model selection, question context, policy status, and a readable answer](assets/workbench/04-local-ai.png)
+
+Local AI is optional and advisory.
+
+1. Open **Local AI review**.
+2. Select or type an Ollama model name.
+3. Keep the host at `http://127.0.0.1:11434` for a local server.
+4. Select **Start local AI**. The app starts Ollama when possible and prepares the selected model.
+5. Confirm that the correct result CSV is attached below the question.
+6. Write a focused research question.
+7. Select **Analyze loaded result**.
+
+The answer is separated into model metadata, policy status, warnings, headings, and lists. Verify every numerical or physiological claim against deterministic SDK outputs.
+
+Example questions:
+
+```text
+Which deterministic metrics should I inspect before accepting this run as realistic?
+```
+
+```text
+Summarize the glucose pattern, list possible simulation artifacts, and identify claims that cannot be supported by this CSV alone.
+```
+
+Do not ask the model for dosing or treatment advice. Read [AI Safety Gates](LOCAL_AI_SAFETY_GATES.md) for the enforced boundaries.
+
+## 6. Use Research Tools
+
+![Research tools workspace with genomics, tissue stress, and independent reference model controls](assets/workbench/06-research-tools.png)
+
+The **Research tools** workspace contains independent evidence and stress-test layers:
+
+| Tool | Use | Important boundary |
+| --- | --- | --- |
+| AlphaFold assets | inspect protein structure and PAE confidence | confidence is not disease severity |
+| Genomics stressor | compare an explicit functional-scalar scenario | unknown variants are not assigned an effect automatically |
+| Tissue resistance | separate muscle and liver sensitivity assumptions | a stress test is not patient calibration |
+| SBML/libRoadRunner | execute an independent equation model | external units are not assumed to be mg/dL or minutes |
+| COPASI | inspect sensitivity and identifiability tasks | configured tasks and bounds require review |
+| OpenCOR/CellML | validate an independent physiology model | imported models remain separate evidence |
+| FMI/FMPy | inspect or run reviewed device-physics models | FMUs can contain native code and require explicit trust |
+| BindingDB | retrieve measured affinity records | Ki, Kd, IC50, pLDDT, and in-vivo effect are distinct evidence types |
+
+Start with **Check all engines**. Open only the lab you need, and preserve the generated evidence bundle with the study record.
+
+Use **Choose file...** beside SBML, COPASI, CellML, or FMI inputs. The native selector filters the
+visible files by the expected extension. Selecting a file never executes it: static inspection and
+explicit execution remain separate actions, and COPASI/FMI execution still requires the relevant
+confirmation checkbox.
+
+### Inspect an AlphaFold structure
+
+Each bundled protein card provides separate actions with different evidence meanings:
+
+1. **View 3D** opens a local, interactive C-alpha backbone in the app. Drag to rotate, scroll to
+   zoom, or use the arrow keys. Colours represent AlphaFold pLDDT confidence.
+2. **Open PNG** opens the bundled static render.
+3. **Reveal mmCIF** shows the exact local coordinate file in Finder, Explorer, or the Linux file
+   manager rather than relying on an operating-system association for `.cif`.
+4. **Generate PAE** retrieves the official AlphaFold Predicted Aligned Error data over verified
+   HTTPS and writes an interactive HTML artifact below the selected output folder.
+5. **AlphaFold entry** opens the matching official database page in the system browser.
+
+pLDDT describes local structure-prediction confidence and PAE describes confidence in relative
+residue placement. Neither value is converted into pathogenicity, insulin sensitivity, disease
+severity, or treatment logic.
+
+## 7. Evidence Sources
+
+The **Evidence sources** workspace describes whether a connector is:
+
+- **Integrated** — the SDK can retrieve or generate a bounded evidence artifact.
+- **Partial** — only part of the workflow is implemented.
+- **Portal** — the app opens the official external resource.
+- **Planned** — no functioning integration exists yet.
+
+Opening a portal does not import its content into a simulation. External evidence must be cited, reviewed, licensed appropriately, and connected to a claim explicitly.
+
+## 8. Configure And Maintain The App
+
+![Settings workspace with local preferences, app and SDK versions, update controls, and documentation links](assets/workbench/07-settings.png)
+
+Open **Settings** to maintain the workbench without mixing application controls into a scientific run.
+
+### Local preferences
+
+You can set:
+
+- the default output folder, selected with **Choose folder...**
+- the default deterministic seed
+- the default local Ollama model
+- the local Ollama host
+- whether diagnostics run at startup
+
+Select **Save settings** to apply these values to the Run and Local AI workspaces. Preferences are stored only in the app's local browser storage. The Settings panel does not store tokens, passwords, patient data, or run results. Ollama hosts are restricted to `localhost`, `127.0.0.1`, or `::1`.
+
+### Software updates
+
+The desktop app and Python SDK have separate version records:
+
+- **Install or update Python SDK** creates, repairs, or updates the private app engine through a fixed, Rust-owned command. The app does not accept arbitrary shell text.
+- **Download latest app update** opens the stable `tauri-beta-latest` GitHub release. Install the new signed installer for your platform after closing the current app.
+- **Refresh versions** checks the native app and the Python engine independently.
+
+The beta deliberately does not replace its own executable silently. This keeps downloads, signatures, and release notes visible until a signed Tauri self-updater is introduced and audited.
+
+### Help
+
+The same workspace links to this user guide, installation troubleshooting, the complete SDK documentation, and [iints.org](https://iints.org/).
+
+## Common Problems
+
+| Message or symptom | What to do |
+| --- | --- |
+| Python bridge unavailable | select **Install Python engine**, wait for completion, then select **Refresh versions** |
+| `No module named iints_desktop` | repair the private engine with **Install or update Python SDK**; the discovered Python does not contain the SDK bridge |
+| Protocol list is empty | run diagnostics, verify the SDK installation, then select Refresh protocols |
+| Native selector does not open | confirm you are using the installed app rather than a browser preview |
+| CSV preview fails | select the file again with **Choose CSV...** and confirm it is a supported results CSV |
+| Ollama not found | install Ollama once, then select Start local AI |
+| Model is missing | choose Refresh model list or allow Start local AI to pull the selected model |
+| Optional research engine missing | install or configure only the engine required for that lab |
+| macOS blocks the beta | follow the signed-build and Gatekeeper guidance in [Desktop App Installation](APP_INSTALL.md) |
+
+## Keep A Reviewable Record
+
+For every result you intend to discuss or publish, preserve:
+
+```text
+run-folder/
+├── results.csv
+├── config.json or run metadata
+├── clinical or research report
+├── safety and audit events
+├── MDMP artifacts when used
+└── academic_bundle/
+    ├── ro-crate-metadata.json
+    ├── checksums
+    └── academic audit
+```
+
+The interface is a workbench, not the scientific authority. The Python SDK output, recorded configuration, deterministic checks, and source evidence remain the basis for interpretation.