LoopInsights: AI-powered therapy settings analysis

[taylorpatterson-T1D]

Summary

The three therapy settings that cause a lot of confusion are Carb Rates, Insulin Sensitivity and Basal Rates. They all can impact each other and setting the right baselines for these often involves fasting and precise documentation. I wanted AI to solve this problem for us.

The Problem We're Solving

Managing diabetes with a closed-loop system like Loop requires ongoing tuning of three core therapy settings — Carb Ratio (CR), Insulin Sensitivity Factor (ISF), and Basal Rate (BR). Today, users must manually interpret CGM data, identify patterns (dawn phenomenon, post-meal spikes, overnight lows), and translate those patterns into schedule adjustments. This process is:

• Time-consuming — cross-referencing hourly glucose averages, TIR breakdowns, and insulin delivery logs
• Error-prone — subtle patterns across 14–90 days of data are easy to miss
• Intimidating for new users — many Loopers leave settings unchanged for months because they don't know where to start
• Disconnected from context — existing tools show data but don't connect it to actionable setting changes

Endocrinologists do this work in 15-minute appointments a few times per year. LoopInsights brings that analytical capability to every Loop user, on demand, using their own data.

---

New Feature Impact

LoopInsights is an AI-powered therapy settings advisor that lives inside Loop's Settings screen. It reads glucose, insulin, and carbohydrate data (read-only), sends aggregated statistics to a user-configured AI provider, and returns specific, time-block-level setting adjustment suggestions with clinical reasoning.

What It Does

• Analyzes 3–90 days of data across glucose (CGM), insulin delivery, and carb entries
• Detects patterns — dawn phenomenon, overnight lows/highs, post-meal spikes, high variability, consistent highs/lows
• Generates specific suggestions — e.g., "Increase basal rate from 0.85 to 0.95 U/hr between 3:00 AM–7:00 AM to address dawn phenomenon"
• Provides a Settings Score (0–100) based on ADA/AACE consensus targets (TIR, time below range, CV, GMI)
• Dual-mode glucose chart — standard Ambulatory Glucose Profile (24-hour overlay) for 14-day lookback, Glucose Profile (multi-day time series) for all other periods
• Guided tuning flow — recommends CR → ISF → BR order (most impactful first)
• Suggestion history — full audit trail with before/after therapy snapshots and revert capability
• Interactive AI chat — follow-up questions about your data and suggestions
• Trends & Insights — time-in-range trends, hourly heatmaps, pattern timeline
• Goals & Reflections — set TIR/GMI targets, track progress, journal reflections
• Caffeine tracking — manual logging with half-life decay modeling
• Meal response analysis — per-food-type glucose response patterns (when FoodFinder data available)
• Background monitoring — optional automatic periodic checks with notification alerts
• Nightscout import — pull historical glucose/treatment data from Nightscout servers

---

User-Configurable Settings

Setting	Options	Default
Feature toggle	On / Off	Off
AI Provider	AI API agnostic in a BYO design for forward maintainability
AI Model	Any model string (e.g., gpt-4o, claude-sonnet-4-5-20250929)	Provider default
Custom endpoint	Any OpenAI-compatible URL	Provider default
API Key	User's own key (stored in iOS Keychain)	None
Analysis period	3, 7, 14, 30, 90 days	14 days
Apply mode	Manual, One-Tap, Pre-Fill Editor	Manual
AI Personality	Clinical Expert, Supportive Coach, Dry Wit, Tough Love	Clinical Expert
Biometrics	Heart rate, HRV, steps, sleep, weight from HealthKit	Off
Additional modules	Circadian profile, food response, caffeine, AGP chart, Nightscout	Each toggleable
Background monitor	Periodic analysis with notifications	Off
Test data mode	Use bundled Tidepool sample data instead of live stores	Off (dev mode only)

---

Safety Considerations

• Read-only data access — LoopInsights never writes to GlucoseStore, DoseStore, or CarbStore
• 20% change cap — AI suggestions are capped at ±20% from current values
• Conservative bias — system prompt instructs AI to under-adjust rather than over-adjust
• User confirmation required — every setting change requires explicit user action (except dev-mode Auto-Apply)
• Full audit trail — every suggestion is logged with before/after therapy snapshots
• One-tap revert — any applied change can be reverted to the pre-apply snapshot
• Disclaimer on apply — One-Tap and Pre-Fill modes show a medical disclaimer before writing
• Feature flag defaults to OFF — users must explicitly enable LoopInsights
• Developer mode hidden — Auto-Apply mode requires 3x long-press activation (location secret)
• No data leaves the device except aggregated statistics sent to the user's chosen AI provider
• API key in Keychain — never stored in UserDefaults or plain text
• BYO API key model — no Anthropic/OpenAI accounts are bundled; users control their own AI access

---

Requirements

• An AI API key — LoopInsights uses your AI API for analysis. Chose from popular providers like OpenAI, Google Gemini, Grok and Anthropic. Also supports self-hosted Azure type configurations. Stored in iOS keychain.
• Apple Health access — While LoopInsights works without this access it is significantly augmented the more data you allow it access to.
• Loop 3.10.0 or newer — Has not been tested with code prior to 3.10.0. Your mileage may vary.
  Requirements to Run LoopInsights
• Configured therapy settings — at least one of: basal rate, ISF, or carb ratio
  schedule
• Network connectivity — to reach your AI provider's endpoint
  Everything LoopInsights uses (HealthKit, Keychain, Networking, Push Notifications, CommonCrypto) is already in Loop's existing entitlements and linked frameworks.

---

Feature Architecture

Loop Integration Footprint

LoopInsights has been optimized for performance and designed with a minimal file footprint in mind. Only 3 existing Loop files are modified, with minimal changes:

File	Change	Lines Added
SettingsView.swift	NavigationLink to LoopInsights settings	~18
SettingsViewModel.swift	loopInsightsDataStores closure property	~3
StatusTableViewController.swift	Pass data stores to SettingsViewModel	~7

Total integration footprint: ~28 lines across 3 files.

New Files (40 files)

Loop/
├── Managers/LoopInsights/
│   ├── LoopInsights_BackgroundMonitor.swift      # Periodic analysis + notifications
│   └── LoopInsights_Coordinator.swift            # Service orchestrator, data bridge
├── Models/LoopInsights/
│   ├── LoopInsights_Models.swift                 # Core types, enums, data structures
│   ├── LoopInsights_Phase5Models.swift           # Circadian, food response, caffeine, AGP models
│   └── LoopInsights_SuggestionRecord.swift       # Persistent suggestion log entry
├── Resources/LoopInsights/
│   ├── LoopInsights_FeatureFlags.swift           # Runtime feature toggles + logging
│   └── TestData/                                 # Bundled Tidepool sample data (4 JSON files)
├── Services/LoopInsights/
│   ├── LoopInsights_AIAnalysis.swift             # Prompt engineering, response parsing
│   ├── LoopInsights_AIServiceAdapter.swift       # Provider-agnostic HTTP client
│   ├── LoopInsights_AdvancedAnalyzers.swift      # Negative basal, stress score computation
│   ├── LoopInsights_CaffeineTracker.swift        # Half-life decay caffeine model
│   ├── LoopInsights_DataAggregator.swift         # Reads Loop stores → aggregated stats
│   ├── LoopInsights_FoodResponseAnalyzer.swift   # Per-food glucose response patterns
│   ├── LoopInsights_GoalStore.swift              # Goal persistence + reflection journal
│   ├── LoopInsights_HealthKitManager.swift       # HK glucose/insulin/biometric queries
│   ├── LoopInsights_NightscoutImporter.swift     # Nightscout API client
│   ├── LoopInsights_ReportGenerator.swift        # PDF report generation
│   ├── LoopInsights_SecureStorage.swift          # Keychain wrapper for API keys
│   ├── LoopInsights_SuggestionStore.swift        # UserDefaults persistence for history
│   └── LoopInsights_TestDataProvider.swift       # Mock data provider for development
├── View Models/LoopInsights/
│   ├── LoopInsights_ChatViewModel.swift          # Interactive AI chat state management
│   └── LoopInsights_DashboardViewModel.swift     # Main observable, orchestrates analysis
├── Views/LoopInsights/
│   ├── LoopInsights_AGPChartView.swift           # Dual-mode glucose chart (AGP + Profile)
│   ├── LoopInsights_CaffeineLogView.swift        # Caffeine intake logging UI
│   ├── LoopInsights_ChatView.swift               # Conversational AI interface
│   ├── LoopInsights_DashboardView.swift          # Primary entry-point dashboard
│   ├── LoopInsights_GoalsView.swift              # Goals, progress tracking, reflections
│   ├── LoopInsights_MealInsightsView.swift       # Per-food glucose response cards
│   ├── LoopInsights_MonitorSettingsView.swift    # Background monitor configuration
│   ├── LoopInsights_SettingsView.swift           # Feature configuration screen
│   ├── LoopInsights_SuggestionDetailView.swift   # Single suggestion detail + apply
│   ├── LoopInsights_SuggestionHistoryView.swift  # Scrollable suggestion audit log
│   └── LoopInsights_TrendsInsightsView.swift     # TIR trends, heatmaps, patterns
├── Documentation/LoopInsights/
│   └── LoopInsights_README.md                    # Architecture documentation

LoopTests/LoopInsights/
├── LoopInsights_DataAggregatorTests.swift        # Aggregation logic with mock data
├── LoopInsights_ModelsTests.swift                # Model serialization, validation
└── LoopInsights_SuggestionStoreTests.swift       # Store persistence, status transitions

All LoopInsights code uses the LoopInsights_ prefix and lives in LoopInsights/ subdirectories. No LoopKit framework modifications required.

Data Flow

Loop Core (read-only)
  GlucoseStore ─┐
  DoseStore ────┤── DataAggregator ──→ Aggregated Stats ──→ AI Provider (BYO key)
  CarbStore ────┤        ↑ supplemented by HealthKit            │
  StoredSettings┘        for longer periods                     ▼
                                                    Suggestion Cards → User Reviews
                                                                │
                                                    ┌───────────┴────────────┐
                                                    ▼                        ▼
                                          SuggestionStore          Therapy Settings
                                          (audit trail)            (write via SettingsManager)

---

Screenshots

1. Dashboard with Settings Score — shows the score card, therapy settings overview with status indicators, and period selector

2. Glucose Profile chart (7-day) — multi-day time series with percentile bands and date labels

3. Ambulatory Glucose Profile chart (14-day) — standard AGP 24-hour overlay with hour labels and (i) info button

4. Suggestion detail card — a specific suggestion with time blocks, current vs. proposed values, reasoning, and confidence level

5. AI Chat conversation — follow-up question about a suggestion with contextual response

6. Trends & Insights — TIR trend chart with hourly glucose heatmap

7. Settings screen — AI provider configuration, apply mode selector, feature toggles

8. Suggestion history — audit trail showing applied, dismissed, and reverted suggestions

---

Video Demo

Check out how it works here: https://youtu.be/P-xfHt0AVTM

🎬 A walkthrough video demonstrating the full LoopInsights workflow — from enabling the feature, configuring an AI provider, running analysis, reviewing suggestions, and applying a change — will be linked here.

---

Test Data for Development & Demos

LoopInsights includes a Test Data mode for development, demos, and evaluation without needing live CGM data. A Python script pulls real data from a Tidepool account and converts it to fixture files that LoopInsights can load.

Generating Test Data from Tidepool

Prerequisites: pip3 install requests

# Pull 14 days of data (default)
python3 pull_tidepool_data.py --email YOUR_TIDEPOOL_EMAIL --password YOUR_TIDEPOOL_PASSWORD

# Pull 90 days for longer-range testing
python3 pull_tidepool_data.py --email YOUR_EMAIL --password YOUR_PASSWORD --days 90

# Also auto-copy fixtures to the iOS Simulator
python3 pull_tidepool_data.py --email YOUR_EMAIL --password YOUR_PASSWORD --simulator

The script authenticates with the Tidepool API, pulls CGM glucose, insulin doses, carb entries, and pump settings, converts them to Loop's native JSON format, and saves four fixture files:

• tidepool_glucose_samples.json
• tidepool_dose_entries.json
• tidepool_carb_entries.json
• tidepool_therapy_settings.json (optional)

Loading Test Data

Fixtures can be placed in two locations (checked in order):

1. App Documents — Documents/LoopInsights/ on device (no rebuild; drag-drop via Finder on physical device)
2. App Bundle — Resources/LoopInsights/TestData/ (requires rebuild)

Enabling Test Data Mode

1. Open Settings > LoopInsights
2. Long-press the header 5 times to unlock Developer Mode
3. Toggle "Use Test Data Fixtures" on
4. Open Dashboard and tap Analyze

Creating Fixtures Manually

If you don't have a Tidepool account, you can create JSON fixtures by hand. See Documentation/LoopInsights/LoopInsights_README.md for the exact JSON schema for each fixture file (glucose samples, dose entries, carb entries, and therapy settings).

---

Beta Test Plan

Prerequisites

• Loop build from feat/LoopInsights branch running on a physical device
• Active CGM with ≥3 days of glucose data in HealthKit OR test data fixtures loaded (see above)
• An API key from OpenAI, Anthropic, or Google

Phase 1: Basic Functionality

• Navigate to Settings → LoopInsights
• Enable LoopInsights via the master toggle
• Configure AI provider and enter API key
• Use "Test API" to verify connectivity
• Select 7-day analysis period
• Tap "Analyze BR" — verify suggestions appear with reasoning
• Tap "Analyze All" — verify all three setting types are analyzed sequentially
• Verify Settings Score appears and grade matches expectations

Phase 2: Glucose Charts

• With 7-day selected, verify "Glucose Profile" title with (i) button and date-based x-axis
• Switch to 14-day, run analysis — verify "Ambulatory Glucose Profile" title with 24-hour x-axis
• Switch to 30-day, run analysis — verify date labels span ~30 days
• Tap (i) buttons on both chart types — verify info popups explain the difference

Phase 3: Suggestion Workflow

• Open a suggestion detail card — verify current vs. proposed values and reasoning
• In Manual mode: verify suggestion shows values but doesn't write settings
• In One-Tap mode: verify disclaimer appears before applying
• In Pre-Fill mode: verify editor opens with proposed values pre-filled
• After applying: verify suggestion history shows the change with before/after snapshots
• Revert an applied suggestion — verify settings restore to pre-apply values

Phase 4: Secondary Features

• Open AI Chat — ask a follow-up question about a suggestion
• Navigate to Trends & Insights — verify TIR trend and hourly heatmap render
• Create a goal in Goals view — verify progress tracking updates after next analysis
• Add a caffeine entry — verify half-life decay curve displays
• Generate a PDF report — verify it opens in share sheet

Phase 5: Edge Cases & Safety

• Run analysis with only 1 day of data — verify graceful "insufficient data" handling
• Enter an invalid API key — verify clear error message
• Disable LoopInsights toggle — verify all LoopInsights UI disappears from Settings
• Switch AI providers — verify previous suggestions persist
• Verify no suggestion exceeds ±20% change from current values
• Kill and relaunch app — verify suggestion history and settings persist

Phase 6: Performance

• Run 90-day analysis — verify no UI freezing during data aggregation
• Rapidly switch between analysis periods — verify chart clears and no stale data appears
• Check memory usage in Xcode Instruments during analysis

---

Requesting review by @marionbarker based on availability.