# Documentation Coverage Reference

Use this page when you need an audit-style map of the documentation surface rather than a tutorial route.

It summarizes the main documentation areas across **software**, **data**, **content**, and **AI system** topics.

Public docs site: `https://python35.github.io/IINTS-SDK/`

## Who This Page Is For

- reviewers who need a documentation map
- researchers preparing study or audit packages
- maintainers checking documentation coverage across the SDK

## Terminology Used Consistently In Public Docs

- `Algorithm`: insulin-dosing logic under test.
- `Forecast model`: optional AI predictor (never final dosing authority).
- `Safety Supervisor`: deterministic safety layer.
- `Run bundle`: reproducible output folder with metrics and reports.
- `MDMP`: data-quality protocol for contract validation and grading.

## Section Structure

Each major chapter below follows:
- `Purpose`: what the chapter covers.
- `When to use`: when this information matters.
- `Commands / Entry points`: where to start.
- `Output / Artifacts`: what to keep for traceability.

For non-technical readers, start with:
- `PLAIN_LANGUAGE_GUIDE.md`
- `../README.md`

---

## 1) Software Documentation

**Purpose**
- Describe core SDK references for building and validating simulation workflows.

**When to use**
- When implementing a new algorithm, run workflow, or integration.

### Developer Docs
- **Primary entry point**: `DEVELOPER_PORTAL.md`
- **Visual architecture**: `ARCHITECTURE_OVERVIEW.md`
- **Generated API reference**: `API_REFERENCE.md`
- **Contribution safety**: `CONTRIBUTING_SAFELY.md`
- **Architecture guide**: `COMPREHENSIVE_GUIDE.md`
- **Technical details**: `TECHNICAL_README.md`
- **Data protocol (MDMP draft)**: `MDMP.md`
- **Evidence base**: `EVIDENCE_BASE.md`
- **API stability**: `../API_STABILITY.md`
- **Change history**: `../CHANGELOG.md`

### Technical Architecture
- **Core simulation**: `src/iints/core/` (Simulator, Supervisor, SafetyConfig)
- **Data ingestion**: `src/iints/data/` (registry, importers, parsers, quality checks)
- **Analysis & reporting**: `src/iints/analysis/` (metrics, reporting, baseline comparisons)
- **Emulation**: `src/iints/emulation/` (commercial pump emulators)
- **CLI**: `src/iints/cli/cli.py`

### User Guides
- **Choose a route**: `USER_GUIDE_MAP.md`
- **Workflow hub**: `WORKFLOWS.md`
- **Hardware hub**: `HARDWARE.md`
- **Reference hub**: `REFERENCE_OVERVIEW.md`
- **Quickstart**: `../README.md`
- **Notebooks**: `examples/notebooks/` (step‑by‑step walkthroughs)
- **Presets**: `src/iints/presets/presets.json`
- **AI Research Track**: `../research/README.md`

**Output / Artifacts**
- `run_metadata.json`, `run_manifest.json`, `validation_report.json`, and report outputs from run bundles.

### Research Checklist (Recommended)
- Use a fixed `seed` for every run (or record the auto‑seed in `run_metadata.json`).
- Archive `config.json`, `run_metadata.json`, `run_manifest.json`, and `results.csv` together.
- Keep `report.pdf` + `audit/` for reviewability.
- Cite datasets using `iints data cite <dataset_id>`.
- Export literature sources using `iints sources --output-json results/source_manifest.json`.
- Use `iints study-ready` when you want a ready-to-review bundle in one command.
- Use `iints data certify-visualizer` to turn `certification.json` into a shareable single-file audit dashboard.
- Use `iints init --template clinical-trial` for a ready-made MDMP scaffold (contract + demo data + audit folders).
- Use `iints data synthetic-mirror` to build privacy-safe synthetic datasets from validated source data.
- Use `iints data realism-check` to flag traces that are too flat, too perfect, or poorly matched to annotated meals.
- Add `--reference free_living_t1d`, `--reference azt1d`, or `--reference hupa_ucm` when you want the realism check anchored to an empirical cohort envelope.
- Add `--output-html` when you want a single-file realism dashboard with a trace preview and per-check breakdown.
- Prefer `iints data certify ...` commands and `iints.data` imports for public-facing certification workflows.
- Record the SDK version + git SHA from `run_metadata.json`.

---

## 2) Data Documentation

**Purpose**
- Define data schema, metadata sources, and data access commands.

**When to use**
- Before training, forecast evaluation, or reproducibility packaging.

### Data Dictionary (Standard Schema)
The IINTS standard schema for CGM time series uses these columns:
- `timestamp` (ISO8601 or epoch)
- `glucose` (mg/dL)
- `carbs` (grams)
- `insulin` (units)

Reference:
- `data_packs/DATA_SCHEMA.md`

### Metadata & Background
- Dataset registry: `src/iints/data/datasets.json`
- Bundled demo data: `src/iints/data/demo/demo_cgm.csv`

### Data Sources & Access Instructions
Use the CLI to discover and access datasets:
```bash
iints data list
iints data info <dataset_id>
iints data fetch <dataset_id> --output-dir data_packs/<dataset_id>
iints data realism-check data/my_trace.csv --reference free_living_t1d --output-html results/realism_dashboard.html
```

Recommended starting points:
- `ohio_t1dm` for a trusted CGM + insulin + meal benchmark.
- `diatrend` when you need a larger controlled-access pump/CGM cohort.
- `t1d_uom` when you need meal macronutrients, activity, and sleep together.
- `t1d_granada` for large longitudinal glucose-only population work.
- `azt1d` or `hupa_ucm` when you want meal + insulin data that is already supported in the current prep commands.

If a public source does not publish a pinned SHA-256 yet, the secure fallback is explicit:

```bash
iints data fetch <dataset_id> --output-dir data_packs/<dataset_id> --no-verify
```

That is a trust decision, not a cryptographic verification. Add a pinned hash to `src/iints/data/datasets.json` when one becomes available.

Registry documentation:
- `data_packs/DATASETS.md`

**Output / Artifacts**
- Dataset identifiers, source metadata, and schema references used in your study record.

---

## 3) Content Documentation

**Purpose**
- Explain non-code assets and required tools for notebooks and reports.

**When to use**
- When onboarding teams that consume outputs but do not modify SDK code.

For non‑code content (notebooks, PDF reports, plots), the following tools are required:

### Required Apps / Software
- **Python** 3.10+ (3.11+ recommended)
- **Jupyter / Colab** for notebooks
- **PDF reader** for reports
- **Terminal** for CLI use

### Hardware / Platform Compatibility
- macOS / Linux / Windows (tested on macOS + Ubuntu)
- GPU **not required** (Torch optional)
- NVIDIA Jetson can be used for headless adversarial endurance runs with `iints jetson endurance`; see `JETSON_ENDURANCE.md`.

### Usage Instructions
- Notebooks: open `examples/notebooks/*.ipynb` locally or in Colab.
- Reports: generated via `iints run-full` or `iints presets run`.

**Output / Artifacts**
- Notebook outputs, generated reports, and presentation-ready visuals.

---

## 4) AI Systems Documentation

**Purpose**
- Clarify how AI predictor research is documented and bounded by safety logic.

**When to use**
- When preparing model cards, datasheets, and forecast evaluation evidence.

IINTS‑AF is a **simulation platform**. It ships an **optional AI research pipeline** but does not
bundle a production‑trained model. The following documentation applies when using AI algorithms
inside the SDK:

### Model Card (Template)
**Model Name**: IINTS Predictor (research track)
- **Location**: `research/` and `src/iints/research/`
- **Purpose**: Forecast glucose 30-120 minutes ahead for Safety Supervisor foresight
- **Training Data**: *Not bundled in SDK* (user‑provided or synthetic)
- **Evaluation**: Compare using built‑in metrics (TIR, CV, LBGI/HBGI, safety violations)
- **Model card**: `research/model_card.md`

### Model Architecture
- LSTM predictor (time‑series forecaster)
- Safety Supervisor remains deterministic and always gates dosing

### Datasheet / Training‑Evaluation Notes
- The SDK includes **dataset registry** + **import tools** to support training data ingestion.
- Users should document the specific dataset, preprocessing, and evaluation protocol
  used for any trained model.
- Datasheet template: `research/datasheet.md`

### Recommended Evaluation Outputs
- Safety report (`safety_report`)
- Audit trail (`audit_trail.jsonl`)
- Clinical metrics (TIR, CV, GMI, LBGI/HBGI)

**Output / Artifacts**
- `model_card.md`, `datasheet.md`, forecast metrics, and safety/audit traces.

---

## Canonical Entry Points (Public)

- `../README.md` (start here)
- `USER_GUIDE_MAP.md`
- `WORKFLOWS.md`
- `HARDWARE.md`
- `REFERENCE_OVERVIEW.md`
- `COMPREHENSIVE_GUIDE.md`
- `TECHNICAL_README.md`
- `data_packs/DATA_SCHEMA.md`
- `data_packs/DATASETS.md`

---

## Notes on Scope
- IINTS‑AF is **pre‑clinical** software for research and validation.
- It is **not** approved for clinical use.
