> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbased.health/llms.txt
> Use this file to discover all available pages before exploring further.

# AI surfaces map

> Where getbased uses AI versus deterministic code.

# AI in getbased — what's powered, what isn't

This page is the canonical map of where AI runs in the app. Three sections:

1. **[Light & Sun verdicts](#where-verdicts-appear)** — ten per-state and per-event surfaces inside the Light & Sun lens. Some run automatically; individual Sun and device-session interpretations are deliberately on-demand.
2. **[AI elsewhere in the app](#ai-elsewhere-in-the-app)** — the chat panel, Interpretive Lens, context-card dots, PDF + photo import, EMF interpretation, and others.
3. **[What is NOT AI](#what-is-not-ai-so-you-can-trust-the-numbers)** — the deterministic-math layer (channel doses, %MED, IU yields, trend alerts, PhenoAge, calculated markers). Big section because the math is auditable and reproducible — those numbers are NOT generated by an LLM.

Every live generative-health surface below requires a configured provider in **Settings → AI**. Demo profiles are the exception for context-card display: bundled summaries, dots, and tips can render without inference. The chat panel + Interpretive Lens read your enabled assembled lab context; per-row verdicts read just their own data slice. Agent Access uses a separate external-sharing permission and context path.

Voice transcription and speech synthesis are a separate subsystem configured in **Settings → Voice**. They can use downloaded browser models, a compatible server, a supported OpenRouter/PPQ/Venice AI connection, xAI, or ElevenLabs. Dictation inserts text into the composer; the normal chat provider and context path begin only when the user sends that text.

<Info>
  This page maps where AI runs. The [system prompt catalog](/developers/system-prompts) documents the exact or parameterized instruction contract, source, parser, and review concerns for each surface.
</Info>

## Light & Sun verdict shape

Every Light & Sun verdict has the same shape:

* **A colored dot** — green / yellow / red / gray (more on these below)
* **A tip** — one sentence (≤14–18 words) summarizing the verdict
* **A detail** — 1–4 sentences of context citing your specific numbers and the biology behind them
* **A refresh button (↻)** — re-runs the analysis with a fresh API call

Dots:

| Dot | Meaning |
| - | - |
| 🟢 green | The feature-specific prompt found no supplied warning or clear concern; it does not certify safety, sufficiency, or protocol compliance |
| 🟡 yellow | A prompt-defined caution, uncertainty, or data-backed gap is present |
| 🔴 red | A strong entered pattern or supplied deterministic warning meets that prompt's red rule; camera proxies alone cannot create red where the prompt forbids it |
| ⚪ gray | Insufficient evidence, or an intentionally neutral pattern review such as the weekly channel synthesis |

## Where verdicts appear

Automatic surfaces use input fingerprints so unchanged data does not repeatedly spend tokens. Individual Sun-session and light-device-session interpretations are manual because the automatic Today and weekly summaries already cover those records.

### Automatic event and setup verdicts

* **Light Tool measurement** — fires for a saved Lux Meter, Flicker Detector, CCT Meter, Spectrum Classifier, Sleep Darkness, or Glass Transmission reading. Aggregate audit rows and brightness-proxy records are excluded. The verdict lives below the reading row in the room panel.
* **Audit verdict** — fires when you save a Light Audit (a frozen snapshot of your environment). Appears at the top of the audit detail. A small colored dot also appears in the audit card header for at-a-glance status across multiple audits.
* **Onboarding plan** — fires when you complete the Light & Sun setup card (skin type, eyewear, home lighting, Ott burden audit). Generates a personalized starting plan with three concrete first-week actions. Appears below the saved-setup chips.

### On-demand session verdicts

* **Sun session row** — runs only when the user requests an interpretation in the completed session detail. Today and weekly synthesis already cover the broader pattern.
* **Light-device-session row** — runs only when requested for a completed panel, SAD lamp, dawn simulator, UVB/UVA, or targeted PBM session.

### Per-state verdicts (fire on render when you have enough data)

These surfaces don't have a clean "I'm done" trigger — the user is editing chip-pickers, adding rooms, the daily rollup shifts as new sessions land. Pre-2026-05-08 they had a manual *Analyze* button to avoid burning API calls during edit sessions; the per-render auto-fire now uses a fingerprint of the underlying state plus a per-tab-session guard so it fires once per meaningful state shift, not on every keystroke.

* **Light Today daily hero (+ dashboard chip)** — fires the first time you visit the Light & Sun page each day, and re-fires when the cache is stale. Synthesizes your day's full picture (sun + devices + tools + environment + recent biomarker context) into a single verdict at the top of the page. The same verdict appears as a compact chip on the dashboard's Light Today strip.
* **Light Environment room** — auto-fires when a room has a primary source set OR at least one measurement. Empty rooms skip auto-fire so a freshly-added blank room doesn't burn an API call before you finish editing. Lives inside the room's expanded body.
* **Per-screen** — auto-fires when a device type is set (default 'phone'). Lives inside the expanded screen card.
* **Indoor-burden summary** — auto-fires when you have at least one room or screen mapped. Lives at the top of the Light Environment block (above the audit list).
* **Channel-mix synthesis** — auto-fires when at least one channel has non-zero exposure in the rolling 7 days. Brand-new users with no logs skip until they have data worth interpreting. Lives in the "Your light, by what it does" section.

## Caching and force-refresh

Every verdict is cached against a fingerprint of the underlying data. Ordinary render paths reuse an unchanged valid verdict without a fresh API call. The refresh button (↻) deliberately bypasses that cache and requests a new verdict even when the fingerprint is unchanged.

When the data has changed (you edited a room, logged a new session, completed a measurement), the fingerprint mismatch invalidates the cache. The next render shows a "refresh AI verdict — your setup changed" CTA.

## Cross-device sync

Verdicts live on the same row as the data they describe — sun-session verdicts on the session row, room verdicts on the room row, and so on. They sync to your other devices via the same per-row CRDT path the rest of your data uses. Latency is typically sub-10 seconds (the engine pushes immediately after writing, skipping the usual debounce).

## What if the verdict seems wrong?

The AI is reasoning over your inputs, including measurement context. A few common failure modes worth knowing about:

* **Camera placement and source**: camera-derived lux, CCT, RGB/spectrum, darkness, flicker, and glass-transmission results are screening proxies, not calibrated dose measurements. A one-point lux calibration stays approximate and source-specific. Follow each tool's aiming guide and use the appropriate dedicated meter before a strong conclusion.
* **Cached vs current**: if you edited a room recently and the verdict still references old numbers, the fingerprint should have invalidated and the CTA should say "your setup changed". Click ↻ to regenerate.
* **Brand-name endorsement**: the AI is instructed to never name specific brand products, only categories ("DC-dimmable LED", "incandescent or halogen"). If a verdict mentions a specific product brand, that's a regression — please open an issue.

## Hardware advice

Seven verdict prompts share a load-bearing hardware block. A camera-banding result cannot identify flicker frequency, modulation depth, or health risk. Advice starts with comparisons—full versus reduced brightness, bypassed versus engaged dimming, or a different known fixture—and recommends product specifications or a purpose-built flicker meter before a strong conclusion. The prompt does not assume that any LED, smart bulb, dimmer, incandescent, or halogen source is flicker-free, does not name brands, and explicitly forbids open-flame recommendations.

## Provider requirements

Verdicts require an AI provider configured in **Settings → AI**. Supported providers: OpenRouter, PPQ, Routstr, Venice, Local AI (Ollama / LM Studio / Jan / Unsloth Studio / compatible endpoints), and Custom. Provider pricing and actual token use vary by prompt, context, model, and retry behavior. A downloaded model running on the user's own hardware has no provider fee; remote or cloud-tagged Local AI models may charge.

## Disabling verdicts

If you want to keep your AI provider configured for the chat panel and Interpretive Lens but pause the per-row verdicts (e.g., during a budget-sensitive month):

```
window.DISABLE_AI_VERDICTS = true
```

Run that in DevTools Console. All ten surfaces will short-circuit until you remove the flag (or reload — the flag doesn't persist).

## AI elsewhere in the app

The ten Light & Sun verdicts above are one corner of the app's AI surface. Below are every place AI runs in the rest of the app. All require a configured provider in **Settings → AI**.

### Text-generation surfaces

| Surface | Where | What it does |
| - | - | - |
| **AI chat panel** | Slide-out at bottom-right, every page | Free-form streaming conversation grounded in enabled profile context, with per-thread drafts, search, bounded rendering, latest-turn edit/retry, linked forks, custom personas, and sequential multi-persona discussions. |
| **Interpretive Lens** | Dashboard top, "Lens" pill | Routes a focused query through your knowledge base (research papers, notes, books). Uses the on-device transformers.js RAG by default, or an external server you configure. |
| **Focus Card** | Dashboard, top of the page | A 3–5 sentence "what to focus on right now" rollup synthesized across your goals + recent biomarker drift + active light/wearable signals. Auto-fires when its fingerprint changes. |
| **Context-card AI assessment** | 9 health-context cards | A reported-facts summary, health dot, and short marker-linked tip per stale card. Demo profiles use bundled results; Local AI can refresh edited demos automatically, while cloud/paid demo refresh requires session-only consent. |
| **Biology Score interpretations** | Insight → Biology Scores | Automatic missing/stale assessments use bounded shared batches and saved input fingerprints. Independent short summaries and full explanations describe deterministic scores. Saved comparison variants survive reloads, backups and sync; a card refresh updates that card, while Coherence refresh updates the group. See [Biology Scores](/guides/biology-scores). |
| **Report AI overview** | PDF report builder | Initially selected when a compatible AI route is available. **Generate AI overview & preview** sends the selected report snapshot; uncheck AI to preview without a new request. The overview remains labeled as AI-generated after editing. See [Health reports](/guides/health-reports). |
| **Guided chat setup** | First-time visitors, before any data | A chat-shaped setup flow for profile basics, optional provider choice, extra context, context cards, and import routing. The deterministic setup UI does not itself spend tokens. |
| **Custom persona draft** | Chat personality picker → New Personality | Generates a 400–500 word editable persona draft from a person, archetype, or communication style. It receives no lab context. |
| **Custom-marker description** | Marker detail modal, when AI is configured | One-sentence (≤30 words) explanation of what the marker measures + why it matters clinically. Cached per-marker so it only fires the first time. |
| **EMF assessment interpretation** | EMF assessment editor → Interpret | Synthesizes a room-by-room read of your EMF measurements with severity, source attribution, and mitigation recommendations. Manual trigger. |
| **EMF comparison interpretation** | EMF editor → Compare two snapshots | Side-by-side delta read between two saved assessments — what got better, what got worse. Manual trigger. |
| **Supplement mitochondrial context** | Current supplements and medications | **ask AI for context** opens a constrained question based on matched claim-level primary studies and the user's mitochondrial/energy biomarkers. Manual trigger. |
| **Nutrition History Ask AI** | Body → Meals & Nutrition → History | Builds an editable 30-day, 3-month, 6-month, 1-year, or all-time aggregate from reviewed meals. The request receipt prevents the normal nutrition context block from being included twice. |

### Vision-AI surfaces (image-in)

| Surface | Where | What it does |
| - | - | - |
| **PDF lab import** | Drop a PDF on the dashboard or sidebar | Extracts text → obfuscates PII (regex + optional local-AI streaming sanitizer) → AI parses values + maps to schema markers. Specialty labs then pass through deterministic product-aware normalization before custom-marker persistence. |
| **Built-in model test** | Settings → Data → Test models on lab reports | Runs the production PDF parser against a synthetic 68-result reference report, preserving raw model output so deterministic scoring can compare it with the verified answer key. |
| **Photo lab import** | Same drop-zone, accepts JPG / PNG / HEIC | Vision-extract path — same downstream as PDF, but starts from a phone snap of a printed lab report. |
| **Custom-marker suggestion (from PDF)** | Inside the PDF import flow | When a parsed value can't be matched to a known marker, AI suggests a key + name + unit + reference range based on the surrounding PDF context. |
| **Supplement/medication product review** | **Supplements & Meds → Review photos** | Reviews up to four product, Facts, directions, or COA images. Separates active ingredients, excipients/capsule materials, laboratory results, and warnings into a draft that the user must review and then save. |
| **Meal photo analysis** | Body → Meals & Nutrition → Log meal | Sends up to four selected meal photos through the optional dedicated nutrition model route and returns an editable nutrient/component estimate. Running analysis may continue in the background or be canceled. |
| **Nutrition-label analysis** | Body → Meals & Nutrition → Log meal | Extracts serving and nutrient facts from selected label images into the same review-first meal draft. |
| **Meal benchmark** | Body → Meals & Nutrition → Meal benchmarks | Runs selected configured models independently against benchmark photos. Each model run can be canceled, retried, or replaced without interrupting the others; deterministic code scores reviewed estimates against known values. |
| **Spectrum Classifier** | Light Tools → "What is this light?" | Camera-based light-source classifier (LED cool / LED warm / fluorescent / incandescent / daylight). Uses RGB ratios + flicker variance — the deterministic part is the classifier itself; the AI only kicks in for the verdict on the saved measurement (covered in Light & Sun above). |

## What is NOT AI (so you can trust the numbers)

A lot of the app is deterministic math, not AI inference. If you see a number on a chart or a tier on a pill, it came from one of these:

| Surface | Source |
| - | - |
| **Channel pills** (Vitamin D / Body clock / Cell energy & repair / Blood vessels / Skin & mood / Outdoor eye light) | Browser-side spectrum reconstruction → action-spectrum convolution → logged source/rhythm signal. Deterministic model, not a measured body response or target-progress score. |
| **% MED burn estimate** | Modeled erythemal action spectrum × Fitzpatrick reference threshold. It is a caution estimate, not a personal safe-time guarantee. |
| **Vitamin-D-effective estimate** | Modeled UVB reaching logged uncovered skin. It is not measured synthesis, serum status, or an oral-dose equivalent. |
| **Reference ranges** (`refMin` / `refMax`) on lab charts | Whatever the lab printed on the PDF, OR your own override. Never AI-generated. |
| **Trend alerts** ("dropped 25%" / "trending up") | Linear regression slope + R² thresholds in `data.ts`. Algorithmic, not LLM. |
| **PhenoAge biological age** | Levine 2018 formula over 9 biomarkers + age. Closed-form math. |
| **Calculated markers** (Free Water Deficit, BUN/Creatinine ratio, HOMA-IR) | Published formulas with conversion math for unit systems. |
| **Channel doses on dashboard / per-session** | Same Bird-Riordan reconstruction; no AI. |
| **Trend sparklines on context cards** | Direct plot of stored values. |
| **Light-environment screening tiers** | Deterministic heuristic from disclosed room/screen patterns and source-aware sensor, meter, or camera observations. It is not measured dose or diagnosis. The following narrative is AI-generated. |
| **Custom marker creation, sidebar edits, chip-picker changes, manual-value entry** | Local data writes. No AI call fires; the AI sees them on the next chat turn. |
| **Supplement/medication lifecycle, daily quantity math, contaminant grouping, and mitochondrial evidence matching** | Period/status rules, compatible-unit arithmetic, and claim-catalog lookup are deterministic. AI is used only for reviewed product extraction, requested context, or impact summaries. |
| **Genome import, association/evidence/relevance labels, APOE, and mtDNA resolution** | Raw/report/manual parsing and catalog lookup are deterministic and local. **Ask AI** on a finding is an explicit editable prompt that supplies the scoped catalog baseline; it is not part of import or classification. |
| **Nutrition totals, targets, timing, fasting windows, Fuel Mix, and response trends** | Computed from reviewed meal records in browser code. Target progress colors and meal-history charts do not come from a model. |
| **Meal component arithmetic and benchmark scoring** | Component totals, known-value comparison, error percentages, and winner ranking are deterministic after the model estimates have been normalized. |

## What runs on-device vs cloud

CLI-backed features use `ai-feature-routing.ts` and the capability-aware execution route instead of bypassing the selected assistant through a direct-provider call. Local CLI agents receive the same enabled context plus scoped getbased tools; personal gateways receive context and may advertise text-only feature support, but do not receive the local tool bridge. Image support does not imply audio support, and automatic voice remains on-device for CLI chat. See [CLI agent providers](/developers/cli-agent-providers) for the dispatch and approval contract.

| Path | Where it runs |
| - | - |
| **Knowledge Base (Interpretive Lens default)** | On-device transformers.js + OPFS — your knowledge documents never leave the browser. |
| **Local AI provider** (Ollama / LM Studio / Jan / Unsloth Studio / compatible endpoints, configured in Settings → AI → Local AI) | Direct from the browser to the configured endpoint. Loopback runs stay on the device; LAN, remote, and cloud-tagged setups leave it. |
| **PII obfuscation (compatible streaming sanitizer)** | Optional. It stays on-device only with a loopback endpoint and downloaded model, then passes the prepared content to the active provider. |
| **Voice — On this device** | Downloaded Whisper and Kokoro models run in browser workers. Raw recordings are transient and model files are rebuildable caches. |
| **Voice — compatible server / OpenRouter / PPQ / Venice / xAI / ElevenLabs** | The selected voice service receives only the recording being transcribed or assistant reply being synthesized. All are called directly from the browser; remote recipients require cloud-processing consent where applicable. **Same as chat** resolves supported AI accounts or falls back on-device. Private chat transports do not automatically cover ordinary voice endpoints. |
| **Cloud providers** (PPQ / Routstr / OpenRouter / Venice / Custom) | The browser calls the selected endpoint directly after recipient-scoped consent. Venice Encrypted TEE Mode encrypts message content with ECDH + AES-GCM and requires Intel TDX DCAP plus signed NVIDIA NRAS checks, but Venice still sees request metadata. The checks do not prove TDX/GPU co-location, approved code measurements, or the source of every response. |
| **Camera frames and selected images** (light tools, lab import, meal photo, nutrition label) | Prepared in the browser, then either kept on-device for light-tool metric extraction or sent to the configured AI provider for the requested vision call. Meals accept up to four images. Full-size meal images are request-only and are not saved; small reviewed thumbnails may be stored with the meal. |

## Caching + privacy notes

* Every per-row verdict caches against a fingerprint of the underlying data. If nothing's changed, the cached verdict is returned without a fresh API call.
* Import model-test records stay device-local and are stripped from sync payloads because timing, loaded state, and hardware metadata do not transfer meaningfully. See [AI model testing internals](/developers/ai-model-testing-internals).
* The chat panel pulls from `buildLabContext()` — the assembled section block filtered by **Manage → Context → Data sources** (`contextSourceSettings`). Those switches gate Insight Context Cards, Supplements & Medications, Blood marker results, per-specialty lab groups, Genome tiers, Light & Sun, Meals & Nutrition, and Wearable recovery context for in-app AI, score context, and source-driven warnings.
* Interpretive Lens and Knowledge Base live in the Answer grounding panel, separate from data-source gates. Agent Access is separate again: the browser pushes an encrypted gateway summary only after **Settings → Agent Access** is enabled, and that push calls `buildLabContext({ skipGroupFilter: true, ignoreContextToggles: true })` so external agents do not inherit the in-app Data sources switches.
* Custom-marker creation, manual-value entry, sidebar edits, and chip-picker changes do NOT trigger AI calls — they update local data, AI sees them on the next chat turn or the next per-state verdict render.

## Related guides

* [Sun Sessions](https://docs.getbased.health/guides/sun-sessions) — how outdoor light sessions work
* [Light Environment](https://docs.getbased.health/guides/light-environment) — rooms + screens + audits
* [Light Tools](https://docs.getbased.health/guides/light-tools) — the measurement tool ecosystem
* [AI Providers](https://docs.getbased.health/ai-providers) — how to configure a provider
* [AI Chat](https://docs.getbased.health/guides/ai-chat) — the chat panel that complements the per-row verdicts
* [Meals & Nutrition](/guides/meals-nutrition) — meal analysis, reviewed storage, trends, benchmarks, and AI context boundaries
* [Supplements and medications](/guides/supplements-medications) — therapy lifecycle, reviewed product import, quality evidence, and AI boundaries


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.