# v1.5.5

Release date: 2026-05-17

`v1.5.5` is the realism, EUCYS, and validation release.

This release collects the full SDK work completed after `v1.5.4`: more physiologically credible simulated glucose, a finished Tidepool import lane, stricter predictor validation, stronger Jetson endurance studies, a clearer first-run path, a rebuilt documentation experience, and a more polished EUCYS / live-demo package.

## Highlights

### 1. Simulator realism is now grounded in empirical glucose behavior

The SDK now has a much stronger physiology layer for synthetic and simulated traces:

- physiological realism checks for implausibly flat traces
- causal meal-to-insulin realism checks
- empirical reference profiles and residual profiles derived from real CGM datasets
- new realistic day presets and calibration tooling
- dashboards and plots that compare simulated traces against real-data envelopes

The result is that simulated outputs are much less “toy-like” and much more useful for research review, demos, and model training.

### 2. Tidepool is now a real import path

`iints import-tidepool` is no longer a placeholder. It now:

- authenticates with a Tidepool session token supplied safely via environment variable or file
- resolves the current user automatically when `--user-id` is omitted
- imports CGM, bolus, wizard, and food events
- converts Tidepool glucose values into the SDK standard frame
- exports both `scenario.json` and `cgm_standard.csv`

This makes the real-data toolchain much more complete alongside CareLink and Nightscout.

### 3. Predictor evaluation is much stricter

`research/evaluate_predictor.py` now supports:

- multiple external held-out datasets with `--external-data`
- feature-drift checks with `--reference-data`
- subgroup reports with repeated `--subgroup-column`
- hypo-detection sensitivity, specificity, false-positive rate, and missed-hypo rate
- MC-dropout uncertainty reliability bins and plot export

That means the SDK can now answer more serious questions than “does the LSTM run?”:

- does it generalize outside the training lane?
- does uncertainty mean anything?
- does performance degrade for specific cohorts?
- does it miss low-glucose events?
- has the evaluation distribution drifted from training?

### 4. Jetson endurance mode is safer for real long runs

Jetson studies now support:

- configurable simulated-time checkpoints
- partial `steps.csv` persistence during the run
- periodic hardware telemetry in `raw/hardware_metrics.csv`
- richer status output with checkpoint minute, resume count, wall-clock elapsed time, and ETA
- more robust resume behavior after interruption

During release hardening, the resume path also uncovered and fixed a real sensor-state restore edge case caused by JSON tuple/list conversion.

### 5. One canonical onboarding command

New users now have one obvious route:

```bash
iints onboard
iints onboard --run-safe-steps
```

The command walks through:

1. environment validation
2. demo execution
3. demo-data import
4. realism checking
5. study protocol generation
6. study execution

That removes a lot of ambiguity from the first hour with the SDK.

### 6. EUCYS and live-demo packaging got much stronger

This release also includes:

- EUCYS PDF brief bundles
- clearer technical, physiological, ethical, and jury-facing materials
- a more usable live-demo CLI flow for calls and presentations
- easier edge onboarding for Raspberry Pi and UNO Q
- refreshed final evidence packaging

The public presentation layer is now much closer to the quality of the technical core underneath it.

### 7. Documentation was rebuilt instead of patched

The documentation site has been reorganized into a cleaner role-based structure with:

- a clearer homepage
- a developer portal
- generated API reference coverage
- better footer routing into technical docs
- cleaner onboarding, hardware, troubleshooting, and workflow paths

This is a real documentation rebuild, not a cosmetic sweep.

### 8. Smaller hardening work also landed

The release includes:

- local plugin foundations and versioned outputs
- runtime SQLite cleanup fixes
- governance and repository-root CI hardening
- dependency updates
- repeated notebook refreshes and health-badge maintenance

## Validation

Before release, the updated SDK passed:

- `python3 -m pytest tests/ -q`
  - `396 passed, 4 skipped`
- `flake8 .`
- `mypy src/iints/`
- `python3 tools/docs/generate_api_reference.py --check`
- `PYTHONPATH=src python3 tools/ci/check_mdmp_sync.py`

The full release check also rebuilds the docs, package artifacts, and technical manual.

## Upgrade

Full workstation:

```bash
python -m pip install -U "iints-sdk-python35[full,mdmp]==1.5.5"
```

Edge / Raspberry Pi:

```bash
python -m pip install -U "iints-sdk-python35[edge,mdmp]==1.5.5"
```

## Practical takeaway

`v1.5.5` is the release where IINTS-AF becomes noticeably more convincing as a real research SDK:

- the data lane is broader
- the simulated physiology is more believable
- the AI evaluation story is stricter
- the long-run hardware evidence is safer
- the public documentation and EUCYS materials finally tell one coherent story
