Skip to content

Documentation Coverage Reference

This document summarizes the main documentation surfaces in the IINTS-AF SDK 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 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

  • 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.

  • 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.
  • 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: 

iints data list
iints data info <dataset_id>
iints data fetch <dataset_id> --output-dir data_packs/<dataset_id>

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:

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)

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
  • 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)
  • 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.