Add integration and output quality documentation

README.md

@@ -89,12 +89,19 @@ The model predicts the next token. Slot placeholders like `<STEPS_TODAY>` are fi
 
 On-device smartwatch / wearable assistant demos. Not intended for general-purpose chat or safety-critical applications.
 
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Intent reference](docs/intent-reference.md) | All 35 intents and slot placeholders |
+| [Web output quality](docs/web-output-quality.md) | Sampling, cleanup, and anti-gibberish techniques for browser/on-device runtimes |
+| [Smartwatch integration](docs/smartwatch-integration.md) | End-to-end guide to wire the model into wrist hardware |
+
+Live browser demo: see the `collab-run-1/web` app in the electron-v1 training project (links to this model on Hugging Face).
+
 ## Limitations
 
 - Trained on synthetic data; behavior on real user phrasing may vary
 - Does not output real metric values — only intents and slot tokens
 - Small model with limited reasoning capability
 
-## Training
-
-Trained with the `electron-v1` project (`collab-run-1`). See the parent repo for training instructions and intent reference.

docs/intent-reference.md

@@ -0,0 +1,163 @@
+# Wrist Wearable Assistant — Intent Reference
+
+This document describes every intent in the [`tinydata/schema.py`](../tinydata/schema.py) vocabulary. Intents are machine-readable action tags the on-device model emits; your app parses them and runs the matching handler.
+
+## How intents work
+
+Bot lines in training data and at runtime use this format:
+
+```
+bot: <INTENT:GET_STEPS> You're at <STEPS_TODAY> of <STEP_GOAL> — keep going!
+```
+
+| Part | Role |
+|------|------|
+| `<INTENT:NAME>` | Tells the app **what to do** (fetch steps, start timer, etc.) |
+| `<SLOT>` placeholders | Names **which values** the app injects from sensors/settings |
+| Text after the tag | What the user **sees or hears** on the watch |
+
+The model never outputs real metric values — only intents and slot tokens. Your runtime replaces slots with live data.
+
+`NONE` is used when the bot only acknowledges or chats with no device action.
+
+---
+
+## Steps
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `GET_STEPS` | Read step metrics from the pedometer: today’s count, goals, streaks, week/month totals, comparisons. | `<STEPS_TODAY>`, `<STEPS_YESTERDAY>`, `<STEP_GOAL>`, `<STEPS_REMAINING>`, `<STEP_GOAL_PCT>`, `<STEP_STREAK_DAYS>`, `<STEPS_WEEK_TOTAL>`, `<STEPS_LAST_WEEK_TOTAL>`, `<STEPS_MONTH_TOTAL>`, `<TIME>`, `<DATE>`, `<PERCENT>` |
+| `SET_STEP_GOAL` | Change the user’s daily step target. | `<STEP_GOAL>` |
+
+---
+
+## Distance
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `GET_DISTANCE` | Read distance metrics: today’s total, last session, units, weekly progress, lifetime mileage, hourly average. | `<DISTANCE_TODAY>`, `<DISTANCE_LAST_SESSION>`, `<DISTANCE_UNIT>`, `<DISTANCE_WEEK_REMAINING>`, `<DISTANCE_WEEK_BEST>`, `<DISTANCE_LIFETIME>`, `<DISTANCE_HOURLY_AVG>`, `<TIME>`, `<DATE>` |
+
+---
+
+## Heart rate
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `GET_HEART_RATE` | Read heart rate data: current BPM, resting rate, overnight low, session average, daily peak, elevated minutes, effort zone. | `<HR_CURRENT_BPM>`, `<HR_RESTING_BPM>`, `<HR_RESTING_OVERNIGHT_LOW>`, `<HR_AVG_SESSION>`, `<HR_PEAK_TODAY>`, `<HR_ELEVATED_MINUTES>`, `<HR_ZONE>`, `<DURATION>` |
+| `MEASURE_HEART_RATE` | Trigger a live on-demand pulse reading from the optical sensor. | `<HR_CURRENT_BPM>` |
+
+---
+
+## Sleep
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `GET_SLEEP` | Read sleep data: duration last night, sleep/wake times, weekly average, awake minutes, goal gap, weekend total. | `<SLEEP_HOURS_LAST_NIGHT>`, `<SLEEP_START_TIME>`, `<SLEEP_WAKE_TIME>`, `<SLEEP_AVG_WEEK>`, `<SLEEP_AWAKE_MINUTES>`, `<SLEEP_GOAL_HOURS>`, `<SLEEP_WEEKEND_TOTAL>`, `<DATE>`, `<DURATION>` |
+| `LOG_NAP` | Record or confirm a short nap session. | `<DURATION>`, `<SLEEP_HOURS_LAST_NIGHT>`, `<TIME>` |
+
+---
+
+## Calories
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `GET_CALORIES` | Read calorie burn: daily total, active burn, remaining to goal, yesterday comparison, per-mile estimate. | `<CALORIES_TODAY>`, `<CALORIES_ACTIVE>`, `<CALORIES_REMAINING>`, `<CALORIE_GOAL>`, `<CALORIE_GOAL_PCT>`, `<CALORIES_YESTERDAY>`, `<CALORIES_PER_MILE>`, `<DISTANCE_UNIT>`, `<DURATION>` |
+| `SET_CALORIE_GOAL` | Change the user’s daily active calorie burn target. | `<CALORIE_GOAL>` |
+
+---
+
+## Active minutes
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `GET_ACTIVE_MINUTES` | Read movement time: today’s active minutes, remaining to goal, weekly total, most active day. | `<ACTIVE_MINUTES_TODAY>`, `<ACTIVE_MINUTES_REMAINING>`, `<ACTIVE_MINUTES_GOAL>`, `<ACTIVE_MINUTES_WEEK>`, `<MOST_ACTIVE_DAY>`, `<DURATION>`, `<TIME>`, `<DATE>` |
+| `SET_ACTIVE_GOAL` | Change the user’s daily active minutes target. | `<ACTIVE_MINUTES_GOAL>` |
+
+---
+
+## Battery
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `GET_BATTERY` | Read power state: percentage, estimated days left, days since charge, charge complete status. | `<BATTERY_PCT>`, `<BATTERY_DAYS_LEFT>`, `<DAYS_SINCE_CHARGE>`, `<CHARGE_COMPLETE>`, `<DURATION>`, `<DATE>` |
+| `ENABLE_POWER_SAVE` | Turn on low-power / battery saver mode on the device. | `<BATTERY_PCT>` |
+| `DISABLE_AOD` | Turn off always-on display to reduce power draw. | `<BATTERY_PCT>` |
+
+---
+
+## Alarms and reminders
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `SET_ALARM` | Create or update a wake alarm at a given time. | `<ALARM_TIME>`, `<ALARM_LABEL>`, `<DATE>`, `<TIME>` |
+| `LIST_ALARMS` | Show all alarms currently stored on the device. | `<ALARM_TIME>`, `<ALARM_LABEL>` |
+| `DELETE_ALARM` | Remove one or all alarms. | `<ALARM_LABEL>`, `<ALARM_TIME>` |
+| `SNOOZE_ALARM` | Snooze the currently firing alarm for a short period. | `<ALARM_TIME>`, `<DURATION>`, `<ALARM_LABEL>` |
+| `SET_REMINDER` | Schedule a recurring reminder (water, bedtime wind-down, move prompts). | `<ALARM_TIME>`, `<ALARM_LABEL>`, `<REMINDER_INTERVAL>`, `<TIME>` |
+| `MUTE_REMINDERS` | Disable hourly move reminders or similar nudges. | *(none)* |
+| `EXPLAIN_NUDGE` | Explain why the watch just vibrated (e.g. sedentary move nudge). | `<NUDGE_REASON>`, `<DURATION>`, `<TIME>` |
+
+---
+
+## Timers and stopwatch
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `START_TIMER` | Start a countdown timer (cooking, stretch, etc.). | `<DURATION>`, `<TIME>` |
+| `PAUSE_TIMER` | Pause an active countdown. | `<TIMER_REMAINING>`, `<DURATION>` |
+| `CANCEL_TIMER` | Stop and clear a running timer. | `<TIMER_REMAINING>`, `<DURATION>` |
+| `GET_TIMER_REMAINING` | Report time left on a timer or whether it has finished. | `<TIMER_REMAINING>`, `<DURATION>` |
+| `START_STOPWATCH` | Open or start the stopwatch app. | *(none)* |
+| `LAP_STOPWATCH` | Record a lap split on the stopwatch. | `<LAP_TIME>`, `<DURATION>` |
+| `RESET_STOPWATCH` | Reset stopwatch to zero. | `<DURATION>`, `<LAP_TIME>` |
+
+---
+
+## Workout toggles
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `START_WORKOUT` | Begin tracking a workout (walk, run, cycle, indoor cardio). | `<WORKOUT_TYPE>` |
+| `PAUSE_WORKOUT` | Pause the active workout session. | `<WORKOUT_ELAPSED>`, `<WORKOUT_STATE>`, `<WORKOUT_TYPE>` |
+| `RESUME_WORKOUT` | Resume a paused workout. | `<WORKOUT_ELAPSED>`, `<WORKOUT_STATE>`, `<WORKOUT_TYPE>` |
+| `STOP_WORKOUT` | End the workout and save the session. | `<WORKOUT_ELAPSED>`, `<WORKOUT_TYPE>`, `<WORKOUT_STATE>` |
+| `DISCARD_WORKOUT` | End the workout without saving data. | `<WORKOUT_TYPE>`, `<WORKOUT_STATE>` |
+| `GET_WORKOUT_STATUS` | Check if a workout is running, paused, or left on by mistake; report elapsed time. | `<WORKOUT_ELAPSED>`, `<WORKOUT_STATE>`, `<WORKOUT_TYPE>` |
+| `GET_WORKOUT_SUMMARY` | Show the post-workout summary screen (duration, distance, calories, HR). | `<WORKOUT_TYPE>`, `<WORKOUT_ELAPSED>`, `<DISTANCE_TODAY>`, `<DISTANCE_UNIT>`, `<CALORIES_ACTIVE>`, `<HR_AVG_SESSION>` |
+
+---
+
+## Non-action
+
+| Intent | What it does | Typical slots |
+|--------|--------------|---------------|
+| `NONE` | Pure conversational reply — thanks, encouragement, clarification — with no sensor fetch or device command. | *(none)* |
+
+---
+
+## Summary
+
+| Category | Intents | Count |
+|----------|---------|------:|
+| Steps | `GET_STEPS`, `SET_STEP_GOAL` | 2 |
+| Distance | `GET_DISTANCE` | 1 |
+| Heart rate | `GET_HEART_RATE`, `MEASURE_HEART_RATE` | 2 |
+| Sleep | `GET_SLEEP`, `LOG_NAP` | 2 |
+| Calories | `GET_CALORIES`, `SET_CALORIE_GOAL` | 2 |
+| Active minutes | `GET_ACTIVE_MINUTES`, `SET_ACTIVE_GOAL` | 2 |
+| Battery | `GET_BATTERY`, `ENABLE_POWER_SAVE`, `DISABLE_AOD` | 3 |
+| Alarms / reminders | `SET_ALARM`, `LIST_ALARMS`, `DELETE_ALARM`, `SNOOZE_ALARM`, `SET_REMINDER`, `MUTE_REMINDERS`, `EXPLAIN_NUDGE` | 7 |
+| Timers / stopwatch | `START_TIMER`, `PAUSE_TIMER`, `CANCEL_TIMER`, `GET_TIMER_REMAINING`, `START_STOPWATCH`, `LAP_STOPWATCH`, `RESET_STOPWATCH` | 7 |
+| Workout | `START_WORKOUT`, `PAUSE_WORKOUT`, `RESUME_WORKOUT`, `STOP_WORKOUT`, `DISCARD_WORKOUT`, `GET_WORKOUT_STATUS`, `GET_WORKOUT_SUMMARY` | 7 |
+| Non-action | `NONE` | 1 |
+| **Total** | | **35** |
+
+---
+
+## Related files
+
+- [`tinydata/schema.py`](../tinydata/schema.py) — canonical intent and placeholder definitions
+- [`tinydata/topics.py`](../tinydata/topics.py) — 100 training scenarios mapped to intents and slots
+- [`tinydata/generate.py`](../tinydata/generate.py) — synthetic conversation generator
+
+Each wearable product may implement only a subset of these intents depending on hardware and firmware. Train and deploy against the intents your device actually supports.

docs/smartwatch-integration.md

@@ -0,0 +1,299 @@
+# Smartwatch Integration Guide — Export-0.1
+
+How to run **Smartwatch LM v0.1** (`Export-0.1`) on a real wrist device and wire it to sensors, timers, and apps.
+
+The model is a ~28M-parameter GPT exported as ONNX. It does **not** execute device actions itself — it emits **intent tags** and **slot placeholders** that your firmware or companion app parses and handles.
+
+---
+
+## What you ship
+
+From this repo (repo root):
+
+| Artifact | Size (approx.) | Use on watch |
+|----------|----------------|--------------|
+| `smartwatch_lm_merged.onnx` | ~52 MB | ONNX Runtime inference |
+| `tokenizer.json` | ~200 KB | Text ↔ token ids |
+| `tokenizer_config.json` | small | Tokenizer metadata |
+| `config.json` | small | Architecture constants, I/O names |
+
+Optional for training / debugging on a PC:
+
+- `checkpoint.pt` — PyTorch weights
+- `chat.py` — reference REPL with the same prompt format as production
+
+**ONNX I/O** (from `config.json`):
+
+- **Input:** `input_ids` — `int64`, shape `[batch, seq]`, max seq length **256**
+- **Output:** `logits` — `float`, shape `[batch, seq, vocab_size]` (vocab **3524**)
+
+Use the **last position** logits (`logits[batch, seq-1, :]`) to sample the next token, autoregressively, until EOS or max tokens.
+
+---
+
+## Architecture on the watch
+
+```mermaid
+flowchart LR
+  subgraph input
+    MIC[Mic / touch]
+    STT[Speech-to-text optional]
+  end
+
+  subgraph lm [Smartwatch LM]
+    PROMPT[buildPrompt]
+    TOK[Tokenizer]
+    ONNX[ONNX Runtime]
+    PARSE[extractIntentReply]
+    FILL[fillSlots]
+  end
+
+  subgraph device
+    ROUTER[Intent router]
+    HANDLERS[Sensor / app handlers]
+    UI[Display / TTS]
+  end
+
+  MIC --> STT --> PROMPT
+  PROMPT --> TOK --> ONNX
+  ONNX --> TOK --> PARSE --> FILL
+  PARSE --> ROUTER --> HANDLERS
+  HANDLERS --> FILL
+  FILL --> UI
+```
+
+**Separation of concerns:**
+
+| Component | Responsibility |
+|-----------|------------------|
+| **LM** | Pick intent + reply template with `<SLOT>` tokens |
+| **Router** | Map `<INTENT:NAME>` to a function / service |
+| **Handlers** | Read/write real device state (steps, HR, alarms, …) |
+| **Slot map** | `{"STEPS_TODAY": "4,231", "STEP_GOAL": "10,000", …}` from live data |
+| **UI** | Show or speak the filled template string |
+
+The model **never outputs real step counts or heart rates** — only placeholders. Your app must inject values before display.
+
+See the full intent list in [Intent reference](./readme.md).
+
+---
+
+## Integration steps
+
+### Step 1 — Choose an inference runtime
+
+| Platform | Suggested runtime | Notes |
+|----------|-------------------|-------|
+| **Wear OS** (Kotlin) | [ONNX Runtime Mobile](https://onnxruntime.ai/docs/get-started/with-mobile.html) | NNAPI / XNNPACK EP; quantize later for size |
+| **watchOS** | ORT Mobile or Core ML conversion | 52 MB is heavy — consider INT8 quant or smaller context |
+| **Samsung / Fitbit / Garmin** | Vendor SDK + ORT or TFLite | May need custom build; check RAM limits |
+| **Companion phone** | Same model on phone, BLE to watch | Offloads compute; watch shows final text + runs handlers |
+| **Browser / WebView** | Reference: [`collab-run-1/web`](../collab-run-1/web) | ONNX Runtime Web (WASM); good prototype |
+
+Minimum RAM budget: model weights (~52 MB) + activations + tokenizer + app heap. Many watches need **quantization** (INT8) or **phone-side inference** to fit comfortably.
+
+### Step 2 — Port the generation loop
+
+Mirror [`collab-run-1/web/src/model.ts`](../collab-run-1/web/src/model.ts) and [`config.ts`](../collab-run-1/web/src/config.ts):
+
+```text
+TEMPERATURE = 0.5
+TOP_K = 40
+MAX_NEW_TOKENS = 40
+BLOCK_SIZE = 256
+```
+
+Loop:
+
+1. Encode prompt → `input_ids`
+2. While under max tokens:
+   - Run ONNX with last ≤256 ids
+   - Sample next token (top-k + temperature)
+   - Append; stop on EOS (token id 0) after a few steps
+3. Decode **only new** token ids
+4. Post-process (see [Web output quality](./web-output-quality.md))
+
+Reference Python loop: [`model.py`](../model.py) `GPT.generate()` and [`chat.py`](../chat.py) `ChatSession.say()`.
+
+### Step 3 — Implement prompt + history
+
+```text
+user: How many steps today?
+bot: <INTENT:GET_STEPS> You're at <STEPS_TODAY> of <STEP_GOAL> — keep going!
+user: Set a 10 minute timer
+bot:
+```
+
+Rules:
+
+- Store **`rawBot`** in history: `<INTENT:GET_STEPS> You're at <STEPS_TODAY> of …` (slots unfilled)
+- Do **not** store filled strings like `"You're at 4,231 of 10,000"` in history
+- Trim history if encoded length nears 256 tokens (drop oldest turns)
+
+Port [`buildPrompt()`](../collab-run-1/web/src/reply.ts) verbatim.
+
+### Step 4 — Parse intent and fill slots
+
+Port from [`reply.ts`](../collab-run-1/web/src/reply.ts):
+
+1. `cleanReply(rawText)` — fix BPE / encoding glitches
+2. `extractIntentReply(cleaned)` → `{ intent, template }`
+3. `fillSlots(template, slotMap)` → user-visible string
+
+Example slot map (refresh before each reply):
+
+```json
+{
+  "STEPS_TODAY": "4,231",
+  "STEP_GOAL": "10,000",
+  "STEPS_REMAINING": "5,769",
+  "STEP_GOAL_PCT": "42%",
+  "TIME": "2:15 PM",
+  "DATE": "Sunday"
+}
+```
+
+Format numbers and units to match your locale — the model was trained on human-readable strings in synthetic data.
+
+### Step 5 — Intent router
+
+Register one handler per intent your hardware supports (subset of 35 is fine):
+
+```kotlin
+// Pseudocode — Wear OS style
+fun dispatch(intent: String, template: String, slots: SlotMap): String {
+    val filled = fillSlots(template, slots)
+    when (intent) {
+        "GET_STEPS" -> { /* optional: refresh step cache */ }
+        "START_TIMER" -> timerService.start(parseDuration(slots))
+        "START_WORKOUT" -> workoutService.start(slots["WORKOUT_TYPE"])
+        "NONE" -> { /* no op */ }
+        else -> log.warn("Unsupported intent: $intent")
+    }
+    return filled
+}
+```
+
+**Validate intents** against an allowlist before calling handlers. If the model emits an unknown or unsupported intent, show the filled template anyway but skip the side effect, or ask the user to repeat.
+
+Handler → slot refresh pattern:
+
+| Intent | Handler reads | Typical slots updated |
+|--------|---------------|------------------------|
+| `GET_STEPS` | Pedometer API | `STEPS_TODAY`, `STEP_GOAL`, `STEPS_REMAINING`, … |
+| `GET_HEART_RATE` | HR sensor | `HR_CURRENT_BPM`, `HR_ZONE`, … |
+| `GET_BATTERY` | Power manager | `BATTERY_PCT`, `BATTERY_DAYS_LEFT` |
+| `START_TIMER` | Timer app | `TIMER_REMAINING`, `DURATION` |
+| `SET_ALARM` | Alarm storage | `ALARM_TIME`, `ALARM_LABEL` |
+
+Full mapping: [Intent reference](./readme.md).
+
+### Step 6 — User input path
+
+| Input mode | Flow |
+|------------|------|
+| **Touch** | Typed or quick-reply chips → `userMessage` string |
+| **Voice** | On-watch or phone STT → text → same pipeline |
+| **Hybrid** | STT on phone, LM on phone, send `{intent, displayText}` to watch via BLE |
+
+Keep utterances short — training data mimics wrist-scale queries (“steps today”, “start a walk”, “battery level”).
+
+### Step 7 — Output path
+
+- **Display:** one or two lines on watch face / assistant overlay
+- **TTS:** speak `fillSlots` result only (not raw `<INTENT:…>` tags unless you want “Opening timer” style debug)
+- **Haptics:** optional pulse when `intent != NONE` and handler succeeds
+
+Show intent in debug builds only (the web demo appends `[GET_STEPS]` for testing).
+
+---
+
+## Example end-to-end trace
+
+**User:** “How many steps do I need to hit my goal?”
+
+1. **Prompt** (with prior history if any):
+
+   ```text
+   user: How many steps do I need to hit my goal?
+   bot:
+   ```
+
+2. **Model generates** (raw decode):
+
+   ```text
+   <INTENT:GET_STEPS> You need <STEPS_REMAINING> more to reach <STEP_GOAL>.
+   ```
+
+3. **Parse:** intent = `GET_STEPS`, template = `You need <STEPS_REMAINING> more to reach <STEP_GOAL>.`
+
+4. **Handler:** `GET_STEPS` → read pedometer + goals → update slot map.
+
+5. **Fill slots:**
+
+   ```text
+   You need 5,769 more to reach 10,000.
+   ```
+
+6. **History append:**
+
+   ```text
+   rawBot = "<INTENT:GET_STEPS> You need <STEPS_REMAINING> more to reach <STEP_GOAL>."
+   ```
+
+---
+
+## Performance and size tips
+
+| Technique | Benefit |
+|-----------|---------|
+| **INT8 quantization** | Cuts model size ~4×; test intent accuracy after quant |
+| **Phone-side inference** | Watch stays thin; model updates without OTA to watch |
+| **Cache ONNX session** | Amortize 30–60s web load cost — on watch, load once at boot |
+| **Limit history** | 2–4 turns usually enough; saves context window |
+| **Lower max tokens** | 25–40 tokens keeps latency down on CPU |
+| **Warm-up run** | One dummy forward pass after load avoids first-query stall |
+
+Web reference timings: first WASM session init can take 30–60 seconds; generation is sequential token-by-token. Plan UX (spinner, “thinking…” glyph) accordingly.
+
+---
+
+## Testing without hardware
+
+1. **Browser demo** — [`collab-run-1/web`](../collab-run-1/web): `bun run copy-models && bun run dev`
+2. **Python REPL** — `python chat.py` (requires `torch`, `tokenizers`)
+3. **Dummy slot panel** — web Settings sidebar edits the same slot map your watch firmware should expose
+
+Compare browser vs Python replies for the same prompts before flashing firmware.
+
+---
+
+## Production checklist
+
+- [ ] ONNX + tokenizer bundled in app storage or downloaded once
+- [ ] Tokenizer matches `Export-0.1/tokenizer.json` exactly
+- [ ] Generation params match web reference (temp 0.5, top_k 40, max 40)
+- [ ] `buildPrompt` / `extractIntentReply` / `fillSlots` ported or shared
+- [ ] History stores unfilled bot lines only
+- [ ] Intent allowlist matches implemented handlers
+- [ ] Slot map refreshed from real sensors before `fillSlots`
+- [ ] Graceful fallback for parse failures and unsupported intents
+- [ ] Privacy: on-device inference — no cloud required for core loop
+- [ ] Power: defer inference off critical paths; avoid running LM on every tick
+
+---
+
+## Limitations
+
+- Trained on **synthetic** dialogs — real speech recognition errors and slang may reduce intent accuracy
+- **No safety layer** — not for medical advice or safety-critical control
+- **35 intents** — extend by fine-tuning on new data, not by prompt hacking alone
+- **English-centric** BPE vocab — other languages need retraining
+
+---
+
+## Related docs
+
+- [Web output quality](./web-output-quality.md) — sampling, cleanup, anti-gibberish techniques
+- [Intent reference](./readme.md) — all intents and slots
+- [Model README](../README.md) — model card and Hugging Face deployment

docs/web-output-quality.md

@@ -0,0 +1,201 @@
+# Web Output Quality — Avoiding Gibberish and Bad Replies
+
+This document describes every technique the **Export-0.1 / browser demo** (`collab-run-1/web`) uses to keep model output readable, on-format, and useful. The web app is the reference runtime for the exported model; most of these patterns should be replicated on-device.
+
+Related code lives in:
+
+- [`collab-run-1/web/src/config.ts`](../collab-run-1/web/src/config.ts) — generation defaults
+- [`collab-run-1/web/src/model.ts`](../collab-run-1/web/src/model.ts) — ONNX inference loop
+- [`collab-run-1/web/src/reply.ts`](../collab-run-1/web/src/reply.ts) — post-processing
+- [`collab-run-1/web/src/app.ts`](../collab-run-1/web/src/app.ts) — prompt assembly and slot fill
+- [`chat.py`](../chat.py) — Python reference (`extract_bot_reply`)
+
+---
+
+## Overview
+
+Small language models on constrained domains still drift: they ramble, invent fake numbers, corrupt BPE tokens, or start a new user turn mid-reply. The web stack handles this in four layers:
+
+| Layer | Goal |
+|-------|------|
+| **Training & data** | Teach a narrow, structured format (intents + slots, no raw metrics) |
+| **Sampling** | Keep generation short and low-randomness |
+| **Prompt & history** | Anchor the model in `user:/bot:` turns |
+| **Post-processing** | Clean tokenizer artifacts, parse one line, inject real sensor values |
+
+The browser demo is stricter than the Python REPL in a few places (lower temperature, fewer tokens). That is intentional — WASM inference is slower, and shorter, more deterministic replies feel better on a wrist UI.
+
+---
+
+## 1. Constrained output format (training + runtime)
+
+The model is not trained for open-ended chat. Every bot line follows:
+
+```
+bot: <INTENT:GET_STEPS> You're at <STEPS_TODAY> of <STEP_GOAL> — keep going!
+```
+
+**Why this reduces gibberish:**
+
+- **Intent tags** (`<INTENT:NAME>`) give the app a machine-readable action even if the natural-language tail is slightly off.
+- **Slot placeholders** (`<STEPS_TODAY>`, `<HR_CURRENT_BPM>`, …) replace raw numbers. The model never learns to emit `"8432 steps"` — it learns token names your runtime fills from sensors. That prevents hallucinated metrics.
+- **Closed vocabulary** — only 35 intents and a fixed placeholder set (see [`tinydata/schema.py`](../tinydata/schema.py)). Training data is validated so bot lines cannot invent tags like `<step_count>` or nest intents.
+
+Training data generation ([`tinydata/generate.py`](../tinydata/generate.py)) rejects samples that:
+
+- Miss the leading `<INTENT:…>` on bot lines
+- Use unknown intents or placeholders
+- Include raw numeric metrics (2+ digit numbers) in bot text
+- Break the strict `user:` / `bot:` line format
+
+Your runtime should **never show slot tokens raw to the user** — always run `fillSlots()` with live values (see [`reply.ts`](../collab-run-1/web/src/reply.ts)).
+
+---
+
+## 2. Sampling controls (inference)
+
+Web defaults in [`config.ts`](../collab-run-1/web/src/config.ts):
+
+| Parameter | Web value | Python REPL (Export-0.1) | Effect |
+|-----------|-----------|--------------------------|--------|
+| `TEMPERATURE` | **0.5** | 0.8 | Lower = less random token choice, fewer weird word combinations |
+| `TOP_K` | 40 | 40 | Sample only from the 40 most likely next tokens |
+| `MAX_NEW_TOKENS` | **40** | 120 | Hard cap on reply length — stops rambling early |
+| `BLOCK_SIZE` | 256 | 256 | Context window; older tokens are dropped from the forward pass |
+
+Implementation in [`model.ts`](../collab-run-1/web/src/model.ts):
+
+- **Top-k sampling** — sort vocab by probability, renormalize over top 40, then sample. Cuts off the long tail of nonsense tokens.
+- **Temperature scaling** — divide logits by `max(temperature, 1e-8)` before softmax.
+- **EOS early stop** — after step 2, if the sampled token id is `0`, stop generating. Prevents run-on after an end-of-sequence signal.
+- **Context trimming** — only the last 256 token ids are passed to ONNX each step (`inputIds.slice(-seqLen)`), matching training context limits.
+
+For a smartwatch, prefer **web-style settings** (temp ~0.5, max tokens ~40) unless you need longer replies for voice.
+
+---
+
+## 3. Prompt format and conversation history
+
+The model expects a fixed transcript shape:
+
+```
+user: How many steps today?
+bot: <INTENT:GET_STEPS> You're at <STEPS_TODAY> of <STEP_GOAL> — keep going!
+user: thanks
+bot:
+```
+
+[`buildPrompt()`](../collab-run-1/web/src/reply.ts) builds this string. Important details:
+
+- Every turn uses lowercase `user:` and `bot:` prefixes with a trailing space after the colon.
+- The current turn ends with `bot:` and **no** reply yet — the model continues from there.
+- **History stores `rawBot`** — the intent tag and unfilled slot template, not the display string with dummy sensor values. If you put filled text like `"You're at 1,000 steps"` back into history, the model sees numbers it was never trained on and quality drops.
+
+Only **new** tokens are decoded (`ids.slice(promptLen)`), so the reply extraction starts clean after the prompt.
+
+---
+
+## 4. Post-processing (`reply.ts`)
+
+Raw decode output can still contain tokenizer glitches or extra lines. The web app runs a pipeline before display.
+
+### 4.1 `cleanReply(text)`
+
+Fixes common BPE / UTF-8 artifacts:
+
+- `Ġ` → space (GPT-style space marker)
+- `Ċ` → newline
+- Mojibake sequences for em dash and curly quotes → `—`, `'`
+- Collapse repeated spaces
+- Normalize spaces **inside** angle brackets: `< INTENT : GET_STEPS >` → `<INTENT:GET_STEPS>`
+- Trim stray space-before-apostrophe: ` '` → `'`
+
+### 4.2 `extractIntentReply(text)`
+
+Parses the structured reply:
+
+1. Run `cleanReply`.
+2. Find the first `<INTENT:…>` tag (case-insensitive, tolerant of internal spaces).
+3. **Truncate at `\nuser:`** — if the model starts a fake next turn, discard everything after.
+4. Take **only the first line** — one utterance per reply, matching Python `extract_bot_reply`.
+5. Return `{ intent, template }` where `template` is the text after the intent tag.
+
+If no intent tag is found, intent defaults to `NONE` and the first line is used as template.
+
+### 4.3 `fillSlots(template, data)`
+
+Replace `<SLOT_NAME>` with values from your sensor map. Unknown slots stay as-is (useful for debugging).
+
+### 4.4 Python parity — `extract_bot_reply`
+
+The Colab / Export-0.1 Python helper does the same job with prompt-relative slicing:
+
+- Strip the prompt prefix from the full decode
+- Stop at `\nuser:`, `\n\n`, or first newline
+- Return a single-line bot utterance
+
+The web README notes: *"Generation uses the same prompt format and cleanup as Colab `ask()`"* — with the extra `cleanReply` and intent parsing layers on top for browser display.
+
+---
+
+## 5. Infrastructure choices that affect quality
+
+These are not sampling tricks, but bad infrastructure produces garbage logits or wrong token ids.
+
+| Choice | Location | Why |
+|--------|----------|-----|
+| **Legacy ONNX export** (opset 17, `dynamo=False`) | [`export_onnx.py`](../collab-run-1/export_onnx.py) | Colab’s default exporter can produce invalid graphs; re-export fixes nonsense outputs in WASM |
+| **Single merged ONNX file** | `smartwatch_lm_merged.onnx` | Browser fetch + ORT session needs one blob; external weights often fail in static hosting |
+| **`@huggingface/tokenizers` (JS)** | [`tokenizer.ts`](../collab-run-1/web/src/tokenizer.ts) | Pure JS tokenizer matches training `tokenizer.json`; avoids ORT tokenizer conflicts |
+| **`graphOptimizationLevel: "disabled"`** | [`model.ts`](../collab-run-1/web/src/model.ts) | Some WASM builds misbehave with aggressive graph opts on this model |
+| **Decode only new tokens** | [`model.ts`](../collab-run-1/web/src/model.ts) | Prevents prompt text from leaking into the “reply” string |
+
+---
+
+## 6. Recommended runtime checklist
+
+When porting off the web demo, implement this loop:
+
+```
+1. buildPrompt(history with raw bot lines, userMessage)
+2. encode → generate (temp 0.5, top_k 40, max 40 tokens, EOS stop)
+3. decode new tokens only
+4. cleanReply → extractIntentReply
+5. route intent to device handler (optional: refresh slot map from sensors)
+6. fillSlots(template, slotMap) → show / speak to user
+7. append (userMessage, rawBotLine) to history
+```
+
+**Do not:**
+
+- Feed display strings with real numbers back into history
+- Skip truncation at `\nuser:` or first newline
+- Use high temperature on a 28M-param domain model
+- Let the model invent metric values — always use slots
+
+**Do:**
+
+- Reset or trim history when context approaches 256 tokens
+- Fall back to a safe message if intent is unknown or template is empty
+- Keep generation caps tight for wrist UX (one short sentence)
+
+---
+
+## 7. What this does *not* fix
+
+These techniques improve **format adherence and readability**, not general reasoning:
+
+- Off-domain questions may still get weak or wrong intents
+- Typos in user input are not corrected
+- No content moderation or safety filter is applied
+- Synthetic training data may not match real user phrasing
+
+For production wearables, combine this model with **intent validation** (reject unknown intents), **handler guards** (don’t start a workout if one is already active), and optional **cloud fallback** for out-of-scope queries.
+
+---
+
+## Related docs
+
+- [Intent reference](./readme.md) — all 35 intents and slot names
+- [Smartwatch integration guide](./smartwatch-integration.md) — end-to-end device wiring
+- [Export-0.1 README](../README.md) — model card and ONNX I/O