Upload folder using huggingface_hub

app.py

@@ -1,6 +1,10 @@
 import traceback
 import numpy as np
-import spaces
+try:
+    import spaces
+except ModuleNotFoundError:
+    import types
+    spaces = types.SimpleNamespace(GPU=lambda fn: fn)
 from backend.orchestrator import run_pipeline
 from backend.presets import list_presets
 from frontend.layout import build_app

docs/Turn Detection - Aman.md

@@ -0,0 +1,259 @@
+# **Turn Detection for Hinglish Voice AI**
+
+A Gradio based dashboard to play around and understand different composable components to come up with best Turn Detection Stack.
+
+## 1. Executive Summary
+
+This project covers building an end to end turn detection system optimized for Hindi-English code-switch language. As we understand that silence doesn’t mean the speaker is done talking, for example: “Main aaj office jaun… ya na jaun ?” That pause after first ‘jaun’ shouldn’t be considered as speech done. To distinguish actual complete and incomplete sentences, these turn detection model comes handy. Though it’s very simplified answer but the things get interesting as we have to do this on a streaming audio.  
+Instead of building one stack, I made a dashboard where users can try multiple compostable stacks to understand which ones are good enough to take on further. The good part is one can live see the probabilities from different models (currently for acoustic only) live on the dashboard.  
+To easily understand I divide it in two branches as:
+
+1. **Acoustic Branch:** Tiny, fast model, around 39M params that takes on acoustic signals only. No transcriptions or LLMs, just how a person sounds.  
+2. **Semantic Branch:** This one understands the meaning of the speech and then answers if the speaker is done or not yet.
+
+Spoiler: for the semantic side I built a streaming path that reads meaning from a growing transcript instead of waiting for full text generation — what's still ahead is unifying that with the acoustic branch into one trainable model, not just voting between them.  
+Aim is to build fast, accurate, local models to perform turn detection which helps the voice agent respond accordingly without False Alarms on Pauses and Hinglish supported.
+
+What I'd highlight: it's tiny and fully local (no cloud APIs), the acoustic side has a 0.0 false-alarm rate so it never cuts a thinking user off, and it's built Hinglish-first rather than English-default.
+
+What I'd highlight: it's tiny and fully local (no cloud APIs), the acoustic side has a 0.0 false-alarm rate so it never cuts a thinking user off, and it's built Hinglish-first rather than English-default.
+
+## 2. Problem
+
+In voice AI, the agent needs to know the **exact moment** the speaker is done speaking. But real life conversations are messy.
+
+| Scenario | What the User Says | What Actually Happens |
+| :---- | :---- | :---- |
+| **Done** | "I'll have a pizza." | 2 seconds of silence. Agent should reply. |
+| **Thinking** | "I'll have a pizza... \[2s pause\] ...and a Coke." | 2 seconds of silence. Agent must wait. |
+
+We know simple VAD (Voice Activity Detection) filter won’t work here, it treats both ‘pauses’ and ‘end’ as equal silences and agent will either interrupt or wait for a time bound like 2 sec before interrupting.  
+In both cases it’s not good, it’s annoying.
+
+### Why Hinglish Makes It Harder
+
+Hindi-English code-switching adds a unique challenge of new fillers like "matlab", "toh", "haan", "um" confuse English-trained models.  
+Acoustic models may catchup cross language (not that great tho) but Semantic ones need to understand the meaning hence can’t apply eng-only models.
+
+## 3. Research
+
+Before jumping to code the solution, I personally like to spend a lot of my time going through research papers and articles to understand the existing ones and the best approaches to build future ones.  
+Here is the gist of the research:
+
+* **VAD only (silence based):** fails as we saw earlier. By research among webrtcvad and silero\_vad, the later one is chosen as webrtcvad is sensitive to flag random noises as speech.  
+* **ASR \+ text rules:** can't understand sound patterns, hence fails.  
+* **Encoder x Pooler x Header:** Best stack for acoustic branch, basically works by encoding the audio using Whisper or wav2vec. Though whisper is good in resourceful languages, a research on low resource language shows wav2vec as better encoder for acoustic properties.  
+* **Smart Turn:** It's a direct model available already trained on the given dataset of the challenge post, so kind of used as off the shelf acoustic model. Under the hood it also has v2 as Silero VAD (gate) → Wav2Vec2 encoder → mean pooling → linear classifier → binary complete/incomplete. For v3 the same but encoder changed to Whisper tiny and pooler to cross-attention pooling.  
+* **FastTurn (ASLP-lab):** This paper suggested using unified model which fuses a streaming acoustic path with incremental semantic understanding. Paper evaluates Chinese only, released no code/weights. Worth trying on Hinglish.  
+* **TEN Turn Detection:** This approach basically suggests passing the transcript to the LLM, it's slow but it's the one where extra labels like 'wait' could be added for cases where speaker says fillers like: "....ek sec ruko…" then comes back to complete the sentence.  
+* **LiveKit End-of-Turn:** a real BERT-style checkpoint distilled from a Qwen2.5-7B teacher, fine-tuned for exactly this task. This one is special coz it utilises existing power of most llm that is next token prediction. It smartly checks for probability of next token to be \<end\_term\> and hence identifies if speaker is finished or not.  
+* **Moshi / GPT-Live:** Not a turn detector but worth noting as it's a full duplex meaning it can speak and listen at the same time and hence can feel like someone talking on call. It has a component as Turn Detection.
+
+Extras:
+
+* There are lot more other research done along the way that saved time by ruling out lot of components earlier like many worse encoders, poolers and headers and hence for acoustic settled for (Whisper, wav2vec) x (Mean, Cross Attention) x (Linear, MLP) combinations.  
+* Similarly for semantic, I researched LLMs and settled on Qwen2.5-0.5B as the current model, with Qwen3-0.6B as the future fine-tune base.
+
+Currently due to time and resource constraint, few of the acoustic and semantic stacks are still not tried.
+
+## 4. Data Understanding & Preparation
+
+Coming to Dataset, the challenge gave the Smart Turn dataset but while training models I realised it’s a TTS dataset means the there is no real human speaking. Why this matters coz some of the acoustic models, when evaluated on real recordings later after training on this TTS dataset was not performing good as they overfitted on TTS acoustic signals hence failed on real ones.  
+This emerges a new task of obtaining real dataset, which comes out to be Easyturn dataset comprised of real speeches and curated for Turn Detection model training and validation. But it was only chinese or related languages hence not good for understanding niche Hindi-Eng acoustic signals.  
+*Note: Here I refer Train, Test, Val, Eval terms, the prior 3 terms are self understood, the Eval is basically the final evaluation of models on real speeches with constructed labels.*  
+Here comes the need of real Hin-Eng dataset which was not available (or I couldn’t find) for turn detection. Hence I decided to build it. Fetched the real speech dataset HiACC \+ FLEURS which is basically complete sentences.  
+But for our usecase we need incomplete and complete both labelled. To generate realistic incomplete sentences, I used the longest pause of the sentence as breaking point and truncated the audio. This way I managed to generate a set of complete and incomplete real speech dataset.
+
+| Dataset | Real? | Labels | Size | Notes |
+| :---- | :---- | :---- | :---- | :---- |
+| Smart Turn Dataset | No (TTS) | endpoint\_bool | 1,168 train | Hindi/Marathi, TTS |
+| Easy-Turn | Yes | Native C/I | \~9.3GB | Real-only shards |
+| HiACC \+ FLEURS | Yes | Constructed | 2,322 \+ FLEURS | Truncated clips |
+| Truncation Pilot | Yes | Constructed | 10 | Pilot run data |
+| OOD Test | Yes | Constructed | 5 clips | Real human readers |
+
+Truncation Pilot methodology: As told, real complete clips cut at their most prominent internal VAD pause, with ~250ms of −55dBFS synthetic noise. Directly tests False-Alarm rate on mid-sentence pauses. N=10 (3 English, 4 Hindi, 3 Hinglish).
+
+Stratification: challenge data split 70/15/15 train/val/test by Labels to stay class-balanced.  
+
+---
+
+## 5. Approach / Architecture
+
+The approach is basically trying and testing all reasonably possible combinations both in Acoustic as well as Semantic branches.  
+*By reasonable I mean based on the research we saw earlier.*  
+Let’s understand the architecture now:  
+As we already discussed about two branches Acoustic and Semantic, let’s deep dive in each.
+
+### The Acoustic Branch (Fast & Robust)
+
+* **What it does:** Listens to the raw audio waveform and detects turn-completion patterns in the *prosody* — the rhythm and pitch of speech: a drop in pitch, a breath, or trailing silence.  
+* **How it works:** Uses frozen audio embeddings from whisper tiny through a Cross-Attention pooling layer and a Linear head.  
+* **Speed:** Negligible latency (0.05ms for head) running in real-time.  
+* **Superpower:** 0.0 False Alarm Rate on mid-sentence pauses in pilot tests.
+
+### The Semantic Branch (Smart but Slow) (Chart 1)
+
+* **What it does:** Reads transcripts to judge grammatical and semantic completeness.  
+* **How it works:** Audio → Whisper ASR → Qwen2.5-0.5B LLM → Prediction.  
+* **Speed:** \~2.4s total (1.5s ASR \+ 1.0s LLM).  
+* **Superpower:** Catches explicit cues like "wait a second" that acoustic models miss.  
+* Note: this semantic branch also has the streaming variant described in the section right below.
+
+![Chart 1: Branch latency, acoustic vs semantic](../misc/figures/chart1_branch_latency.png)
+
+### A Faster Variant: The Streaming Semantic Branch
+
+The 2.4s Whisper+Qwen path is too slow to be the only option, so I also built a **streaming version**. Here's the trick: Whisper generates text *one token at a time* and needs the whole sentence before it can output anything useful. You can't easily ask it "what's the partial transcript so far?" mid-sentence.  
+But a **CTC model** (Connectionist Temporal Classification) works differently, one forward pass gives you a transcript for the entire audio you've fed it, so feeding it "a bit more audio" just means running it again on the longer clip. No generation loop, no waiting for the end. I plan to use theainerd/Wav2Vec2-large-xlsr-hindi (a Hindi code-switching CTC model) to produce a growing transcript, and re-run the Qwen classifier on each growing version.
+
+### The Fusion Layer 
+
+The two branches vote. The acoustic branch runs continuously and instantly. The semantic branch updates asynchronously. When they disagree, the acoustic branch wins by default (safety-first), but the semantic branch can override if it detects strong explicit signals.  
+Weighted vote: P\_final \= α·P\_acoustic \+ (1−α)·P\_semantic (α=0.6). Acoustic wins by default (safety-first); semantic can override on strong explicit signals (wait → forced incomplete).
+
+## 6. Experimentation & Modeling
+
+We tested the value of pooling capacity, encoder size, and training data by training four variants on whisper\_tiny embeddings, plus a 3-way dataset comparison.  
+**Training details:** frozen encoders, only pooling/head trained (\~1M params); binary cross-entropy; AdamW lr=1e-4, batch=32, 10 epochs.
+
+| Experiment | Question | Finding |
+| :---- | :---- | :---- |
+| **Pooling Ablation** | Does attention help? | Cross-Attn wins in-dist (98.8%), overfits OOD (20%). Mean-pool more robust (80% OOD). |
+| **Head Ablation** | Does MLP help? | MLP helps slightly on synthetic (+8%); mean+linear generalizes better OOD. |
+| **Encoder Scaling** | Bigger \= better? | Tiny optimal. Base helps simple heads (+5%), hurts complex (−11%). |
+| **Dataset Scaling** | Does real data fix overfitting? | Yes, Cross-Attn goes 1/5 → 5/5 on real Hindi. |
+| **Semantic Solo** | Can text detect pauses? | No, 100% False Alarm Rate. |
+| **Cross-Lingual** | Does Chinese turn-data help Hindi? | Yes for simpler models (mean+MLP 4/5 vs 2/5 synthetic). |
+| **ASR Quality** | Is Whisper-Tiny good enough for Hindi? | No, 2/4 clips catastrophic. |
+
+## 7. Evaluation & Results
+
+### 7.1 Acoustic Branch \- Evaluation & Results
+
+The acoustic branch listens to how speech sounds (pitch, pause, breath) and runs on frozen whisper\_tiny embeddings through a trainable pooling+head. It is the speed-first, always-on signal.
+
+#### 7.1.1 The Overfitting Lesson (Chart 4, Chart 5\)
+
+| Test | Mean+Linear | Mean+MLP | Cross-Attn+Linear |
+| :---- | :---- | :---- | :---- |
+| In-Distribution | 68.4% | 76.3% | 98.8% |
+| Out-of-Distribution | **80% (4/5)** | 40% (2/5) | 20% (1/5) |
+
+Pool+head latency is negligible (\<0.1ms) for every variant. What works: on the real-human OOD set, the simple Mean+Linear model is the most robust (80%), and crucially it achieves a 0.0 False-Alarm Rate on mid-sentence pauses in the pilot \- it never interrupts a thinking user. The catch: the high-capacity Cross-Attention model scored 98.8% in-distribution but only 20% OOD, because it memorized TTS voice artifacts.
+
+![Chart 4: Overfitting lesson, in-distribution](../misc/figures/chart4_in_distribution.png)
+
+![Chart 5: Overfitting lesson, out-of-distribution](../misc/figures/chart5_ood.png)
+
+#### 7.1.2 Encoder Comparison: Tiny vs Base
+
+| Model | Tiny | Base | Δ |
+| :---- | :---- | :---- | :---- |
+| Mean+Linear | 68.4% | 73.4% | \+5.0% |
+| Mean+MLP | 76.3% | 76.8% | \+0.5% |
+| Cross-Attn+Linear | 98.8% | 87.6% | \-11.3% |
+
+Bigger encoders help the simple head slightly but hurt the complex one. whisper\_tiny stays the optimal choice for latency.
+
+#### 7.1.3 The Dataset Effect: Synthetic vs Real vs Cross-Lingual (Chart 6\)
+
+| Architecture | Synthetic | Real Hindi | Cross-Lingual |
+| :---- | :---- | :---- | :---- |
+| Mean+Linear | 4/5 | 3/5 | 3/5 |
+| Mean+MLP | 2/5 | 3/5 | 4/5 |
+| Cross-Attn+Linear | 1/5 | **5/5** | 1/5 |
+
+The big win: the same Cross-Attention architecture went from 1/5 → 5/5 OOD purely by training on real Hindi audio instead of synthetic TTS. Real audio also transfers across languages better than synthetic artifacts transfer within a language.  
+
+![Chart 6: Dataset effect, synthetic vs real vs cross-lingual](../misc/figures/chart6_dataset_effect.png)
+
+![Chart 7: Truncation pilot preset comparison](../misc/figures/chart7_preset_comparison.png)
+
+What we learned & should try (minimal):
+
+* Real data fixes overfitting outright → deploy the real-Hindi-trained checkpoint (already built at 5/5; currently held separate by design).  
+* whisper\_tiny is enough; don\&apos;t pay for a bigger encoder.  
+* Simplest architecture (Mean+Linear) is the safe production default; Cross-Attention is worth it only on real data.
+
+### 7.2 Semantic Branch \- Evaluation & Results
+
+The semantic branch reads the transcript and judges if the sentence feels complete. It catches explicit cues (\&quot;wait\&quot;, \&quot;hold on\&quot;) that acoustics alone miss \- but it depends entirely on ASR quality.
+
+#### 7.2.1 The \&quot;Pizza Problem\&quot; \- Proven (Chart 2\)
+
+| Model | False Alarm Rate | Miss Rate |
+| :---- | :---- | :---- |
+| Qwen2.5-0.5B (Text) | **100%** | 10% |
+| LiveKit EOU (Fusion) | 40% | 60% |
+
+Text-only thought every truncated clip was complete (the cut lands at a clause boundary → grammatically complete transcript). What works: fusing with the acoustic branch drops False Alarms from 100% to 40% \- the acoustic veto correctly overrides the premature \&quot;complete\&quot; verdict.
+
+![Chart 2: The Pizza Problem, text-only fails on pauses](../misc/figures/chart2_pizza_problem.png)
+
+#### 7.2.2 Latency Breakdown (Chart 3\)
+
+| Component | Time | % of Semantic |
+| :---- | :---- | :---- |
+| ASR (Whisper-Tiny) | 1,476ms | 60% |
+| LLM (Qwen2.5-0.5B) | 965ms | 40% |
+| **Total Semantic** | **2,441ms** | 100% |
+
+The acoustic branch is 50,000× faster. The semantic branch is blocked by ASR \- you can\&apos;t read text until it exists.
+
+![Chart 3: Semantic latency breakdown](../misc/figures/chart3_latency_breakdown.png)
+
+#### 7.2.3 The Whisper-Tiny Hindi Problem
+
+All 4 real Hindi pilot clips transcribed by Whisper-Tiny were broken: hindi\_fleurs\_1524 hallucinated into French loops; hindi\_fleurs\_1526 degenerated to \&quot;hehehehe…\&quot;. This fully explains the Hindi Miss Rate hitting 1.0 in fusion. What works: faster-whisper large-v3 produced coherent Devanagari Hindi on all 4 \- the fix is real, just not yet wired in.  
+What we learned & should try (minimal):
+
+* Text-only detection fails alone → always fuse with the acoustic branch (already done; it cuts False Alarms 100%→40%).  
+* ASR is the bottleneck, not the LLM → swap in a stronger Hindi ASR (large-v3 tested and works) and stream the transcript to remove the 2.4s block.  
+* A CTC-based streaming path is the clear way forward.
+
+## 8. Deployment / Product
+
+The entire pipeline is deployed into a **real-time Gradio dashboard**:
+
+* **Streams microphone audio** \- re-scores the growing buffer at every cadence tick (default 100ms) for active presets.  
+* Plots probability against the waveform to easily visaulise the model output with respect to the waveform.  
+* There is a sample of 30 real demo clips (10 en / 10 hi / 10 hinglish) that replay through the same live loop. You can try directly.
+
+Note: short-window models jump erratically that is there would be high spikes which is hard to comprehend in visualisation hence added EMA smoothing.
+
+## 9. Limitations
+
+* **Small Sample Size** – With only 10 truncation and 5 OOD clips, the results show a clear direction but lack full statistical weight.  
+* **ASR Bottleneck** – The semantic branch is limited by Whisper-Tiny, which struggles with specific Hindi dialects and can cause the logic to fail.  
+* **Artificial Training Data** – Most heads were trained on TTS audio. While real data fixes the overfitting (scoring 5/5), those specific checkpoints haven't been deployed in the main dashboard yet.  
+* **Independent Branches** – There is no joint training between paths; they currently rely on a rule-based fusion layer to vote.  
+* **Streaming Simulation** – The current streaming module works by replaying growing audio prefixes rather than using a true live, frame-by-frame decoder.
+
+## 10. Future Work
+
+**Already built vs genuinely future (the word "streaming" appears in both):**
+
+* *Built:* live dashboard streams mic audio; a streaming semantic **preset** exists (CTC-based).  
+* *Future:* make streaming the **default** semantic path; **unify** the two branches into one trainable model (FastTurn's actual design) instead of post-hoc weighted-vote; build a real production frame-synchronous decoder.
+
+### Phase 2: Fine-Tune & Unified Fusion
+
+| Component | Plan | Why |
+| :---- | :---- | :---- |
+| **Base Model** | Qwen3-0.6B | Smaller than alternatives; in head-to-head turn-completion tests it scored 6/8 vs Qwen2.5-0.5B's 3/8. |
+| **Dataset** | Real Hindi/Hinglish | No ready-made set exists. |
+| **Budget** | Stream Easy-Turn shards | \~11.4GB to low tens of MB. |
+| **Fusion** | Trainable head over embeddings | Unifies streams. |
+
+### Phase 3: Streaming & ASR Upgrades
+
+| Component | Plan | Why |
+| :---- | :---- | :---- |
+| **Streaming Default** | CTC incremental path | Removes 2.4s block. |
+| **Unified Fusion** | One trainable model | Matches FastTurn design. |
+| **Hindi ASR** | faster-whisper large-v3 | Fixes Hindi clips. |
+| **Eval Set** | Scale N=10 to N=100 | Statistical power. |
+
+The throughline: turn detection for Hinglish needs both the ears (acoustics) and the brain (semantics). The acoustic branch is already fast and interruption-free enough to ship; the semantic side is fundamentally a latency and ASR-quality problem waiting for a streaming, unified fix.
+

frontend/layout.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
+import base64
 import json
+import re
 import time
+from pathlib import Path
 import gradio as gr
 import soundfile as sf
 import config
@@ -35,9 +38,20 @@ def _sample_clip_choices() -> list[tuple[str, str]]:
 
 def _all_public_presets() -> list[dict]:
     return live.all_public_presets()
+FUTURE_PRESET_LABELS = ['Easy Turn (unavailable)']
+
+def _display_presets() -> list[dict]:
+    presets = live.all_public_presets()
+    seen = {p['label'] for p in presets}
+    for label in FUTURE_PRESET_LABELS:
+        if label not in seen:
+            match = next((p for p in list_presets() if p['label'] == label), None)
+            if match:
+                presets.append(match)
+    return presets
 
 def _preset_display_order() -> list[str]:
-    return [live.DISPLAY_NAME.get(p['label'], p['label']) for p in _all_public_presets()]
+    return [live.DISPLAY_NAME.get(p['label'], p['label']).replace(' (unavailable)', '') for p in _display_presets()]
 
 def _default_active_display_names() -> list[str]:
     target = 'Whisper-Tiny + Mean-Pool + Linear (trained)'
@@ -58,63 +72,86 @@ def _param_relevance(active_display_names: list[str]) -> tuple[bool, bool]:
     semantic_relevant = any((live.uses_semantic_temperature(label) for label in labels))
     return (acoustic_relevant, semantic_relevant)
 
+def _load_doc_markdown() -> str:
+    root = Path(__file__).resolve().parent.parent
+    doc_path = root / 'docs' / 'Turn Detection - Aman.md'
+    if not doc_path.exists():
+        return '_Documentation is not included in this deployment._'
+    text = doc_path.read_text(encoding='utf-8')
+    for a, b in [('\\&quot;', '"'), ('\\&amp;', '&'), ('\\&apos;', "'"), ('\\&lt;', '<'), ('\\&gt;', '>')]:
+        text = text.replace(a, b)
+
+    def repl(m: re.Match) -> str:
+        alt, src = (m.group(1), m.group(2).strip())
+        if src.startswith(('http', 'data:')):
+            return m.group(0)
+        cand = (doc_path.parent / src).resolve()
+        if cand.exists():
+            b64 = base64.b64encode(cand.read_bytes()).decode('ascii')
+            return f'![{alt}](data:image/png;base64,{b64})'
+        return m.group(0)
+    return re.sub('!\\[([^\\]]*)\\]\\(([^)]+)\\)', repl, text)
+
 def build_app() -> gr.Blocks:
     with gr.Blocks(title='Turn Detection - Live Dashboard') as demo:
-        gr.Markdown('# Turn Detection - Live Dashboard\nSpeak, or replay a clip, and watch how different models judge whether the speaker is **done talking** vs. **still going** - plotted directly against the waveform as audio arrives.')
-        session_state = gr.State(live.new_session_state)
-        active_state = gr.State(_default_active_display_names())
-        with gr.Row():
-            with gr.Column(scale=1, min_width=280):
-                gr.Markdown('### Models to compare')
-                gr.Markdown('*Greyed models are not built yet (future work).*')
-                default_active = _default_active_display_names()
-                preset_checkboxes = []
-                for preset in _all_public_presets():
-                    label = preset['label']
-                    disp = live.DISPLAY_NAME.get(label, label)
-                    available = bool(preset.get('available'))
-                    cb_label = disp if available else f'{disp}  (future)'
-                    preset_checkboxes.append(gr.Checkbox(label=cb_label, value=disp in default_active, interactive=available))
-        with gr.Row():
-            threshold_slider = gr.Slider(0.0, 1.0, value=live.DEFAULT_DECISION_THRESHOLD, step=0.01, label='Decision threshold - probability above this = "complete"')
-            cadence_slider = gr.Slider(0, 5000, value=live.DEFAULT_CADENCE_MS, step=100, label='Update cadence (ms) - how often each model re-checks (slower models may still lag behind this)')
-            smoothing_slider = gr.Slider(0.0, 0.9, value=0.5, step=0.05, label="Smoothing - damps short swings on the chart (raw points still shown faintly; doesn't change what's logged)")
-        with gr.Row():
-            acoustic_weight_slider = gr.Slider(0.0, 1.0, value=0.6, label='Acoustic weight - audio tone vs. sentence grammar (fusion models only)', interactive=False)
-            temperature_slider = gr.Slider(0.0, 1.0, value=0.2, label='Semantic temperature - how deterministic the language judgment is (LLM-based models only)', interactive=False)
-        with gr.Row():
-            with gr.Column(scale=1):
-                gr.Markdown('### Audio')
-                mic = gr.Audio(sources=['microphone'], streaming=True, type='numpy', label='Record')
-                gr.Markdown('*Recordings are saved privately to improve the model - never played back or shown to others.*')
-                clear_btn = gr.Button('Clear / reset')
-                gr.Markdown('**...or replay a clip in real time** (paced to its real duration, not dumped in at once) - 10 real English, 10 Hindi, 10 Hinglish')
-                replay_clip_dropdown = gr.Dropdown(choices=_sample_clip_choices(), value=None, label='Sample clip')
-                replay_upload = gr.Audio(sources=['upload'], type='filepath', label='...or upload a recording')
-                replay_btn = gr.Button('Replay in real time')
-            with gr.Column(scale=2):
-                gr.Markdown('### Waveform + live probability, on one timeline')
-                chart = gr.Plot(value=live.render_chart(live.new_session_state(), [], live.DEFAULT_DECISION_THRESHOLD), label=None)
-        with gr.Accordion('History (this session)', open=False):
-            log_table = gr.Dataframe(headers=LOG_HEADERS, value=[], label=None)
-        for cb in preset_checkboxes:
-            cb.change(_on_preset_change, inputs=preset_checkboxes, outputs=[active_state, acoustic_weight_slider, temperature_slider])
+        gr.Markdown('# Turn Detection - Live Dashboard\nSpeak, or replay a clip, and watch how different models judge whether the speaker is **done talking** vs. **still going** - plotted directly against the waveform as audio arrives. Open the **Documentation** tab for the full write-up, methodology and results.')
+        with gr.Tabs():
+            with gr.Tab('Live Dashboard', id='live'):
+                session_state = gr.State(live.new_session_state)
+                active_state = gr.State(_default_active_display_names())
+                with gr.Row():
+                    threshold_slider = gr.Slider(0.0, 1.0, value=live.DEFAULT_DECISION_THRESHOLD, step=0.01, label='Decision threshold - probability above this = "complete"')
+                    cadence_slider = gr.Slider(0, 5000, value=live.DEFAULT_CADENCE_MS, step=100, label='Update cadence (ms) - how often each model re-checks (slower models may still lag behind this)')
+                    smoothing_slider = gr.Slider(0.0, 0.9, value=0.5, step=0.05, label="Smoothing - damps short swings on the chart (raw points still shown faintly; doesn't change what's logged)")
+                with gr.Row():
+                    acoustic_weight_slider = gr.Slider(0.0, 1.0, value=0.6, label='Acoustic weight - audio tone vs. sentence grammar (fusion models only)', interactive=False)
+                    temperature_slider = gr.Slider(0.0, 1.0, value=0.2, label='Semantic temperature - how deterministic the language judgment is (LLM-based models only)', interactive=False)
+                with gr.Row():
+                    with gr.Column(scale=1, min_width=250):
+                        gr.Markdown('### Models to compare')
+                        gr.Markdown('*Greyed models are not built yet (future work).*')
+                        default_active = _default_active_display_names()
+                        preset_checkboxes = []
+                        for preset in _display_presets():
+                            label = preset['label']
+                            disp = live.DISPLAY_NAME.get(label, label).replace(' (unavailable)', '')
+                            available = bool(preset.get('available'))
+                            cb_label = disp if available else f'{disp}  (future)'
+                            preset_checkboxes.append(gr.Checkbox(label=cb_label, value=disp in default_active, interactive=available))
+                    with gr.Column(scale=2):
+                        gr.Markdown('### Audio')
+                        mic = gr.Audio(sources=['microphone'], streaming=True, type='numpy', label='Record')
+                        gr.Markdown('*Recordings are saved privately to improve the model - never played back or shown to others.*')
+                        clear_btn = gr.Button('Clear / reset')
+                        gr.Markdown('**...or replay a clip in real time** (paced to its real duration, not dumped in at once) - 10 real English, 10 Hindi, 10 Hinglish')
+                        replay_clip_dropdown = gr.Dropdown(choices=_sample_clip_choices(), value=None, label='Sample clip')
+                        replay_upload = gr.Audio(sources=['upload'], type='filepath', label='...or upload a recording')
+                        replay_btn = gr.Button('Replay in real time')
+                        gr.Markdown('### Waveform + live probability, on one timeline')
+                        chart = gr.Plot(value=live.render_chart(live.new_session_state(), [], live.DEFAULT_DECISION_THRESHOLD), label=None)
+                with gr.Accordion('History (this session)', open=False):
+                    log_table = gr.Dataframe(headers=LOG_HEADERS, value=[], label=None)
+                for cb in preset_checkboxes:
+                    cb.change(_on_preset_change, inputs=preset_checkboxes, outputs=[active_state, acoustic_weight_slider, temperature_slider])
 
-        def replay_clip(clip_filename, uploaded_path, active_display_names, acoustic_weight, temperature, threshold, cadence_ms, smoothing):
-            path = uploaded_path or (str(config.SAMPLE_CLIPS_DIR / clip_filename) if clip_filename else None)
-            if not path:
-                yield (live.new_session_state(), live.render_chart(live.new_session_state(), [], threshold, smoothing), [])
-                return
-            audio, sr = sf.read(path, dtype='float32')
-            if audio.ndim > 1:
-                audio = audio.mean(axis=1)
-            state = live.new_session_state()
-            for chunk in live.chunk_audio(audio, sr, chunk_seconds=1.0):
-                chunk_duration_s = len(chunk) / sr
-                state, fig, log_rows = live.process_chunk(state, (sr, chunk), active_display_names, acoustic_weight, temperature, threshold, cadence_ms, smoothing)
-                yield (state, fig, log_rows)
-                time.sleep(chunk_duration_s)
-        replay_btn.click(replay_clip, inputs=[replay_clip_dropdown, replay_upload, active_state, acoustic_weight_slider, temperature_slider, threshold_slider, cadence_slider, smoothing_slider], outputs=[session_state, chart, log_table])
-        mic.stream(fn=live.process_chunk, inputs=[session_state, mic, active_state, acoustic_weight_slider, temperature_slider, threshold_slider, cadence_slider, smoothing_slider], outputs=[session_state, chart, log_table], stream_every=1.0, time_limit=None)
-        clear_btn.click(live.clear_session, inputs=session_state, outputs=[session_state, chart, log_table])
+                def replay_clip(clip_filename, uploaded_path, active_display_names, acoustic_weight, temperature, threshold, cadence_ms, smoothing):
+                    path = uploaded_path or (str(config.SAMPLE_CLIPS_DIR / clip_filename) if clip_filename else None)
+                    if not path:
+                        yield (live.new_session_state(), live.render_chart(live.new_session_state(), [], threshold, smoothing), [])
+                        return
+                    audio, sr = sf.read(path, dtype='float32')
+                    if audio.ndim > 1:
+                        audio = audio.mean(axis=1)
+                    state = live.new_session_state()
+                    for chunk in live.chunk_audio(audio, sr, chunk_seconds=1.0):
+                        chunk_duration_s = len(chunk) / sr
+                        state, fig, log_rows = live.process_chunk(state, (sr, chunk), active_display_names, acoustic_weight, temperature, threshold, cadence_ms, smoothing)
+                        yield (state, fig, log_rows)
+                        time.sleep(chunk_duration_s)
+                replay_btn.click(replay_clip, inputs=[replay_clip_dropdown, replay_upload, active_state, acoustic_weight_slider, temperature_slider, threshold_slider, cadence_slider, smoothing_slider], outputs=[session_state, chart, log_table])
+                mic.stream(fn=live.process_chunk, inputs=[session_state, mic, active_state, acoustic_weight_slider, temperature_slider, threshold_slider, cadence_slider, smoothing_slider], outputs=[session_state, chart, log_table], stream_every=1.0, time_limit=None)
+                clear_btn.click(live.clear_session, inputs=session_state, outputs=[session_state, chart, log_table])
+            with gr.Tab('Documentation', id='docs'):
+                gr.HTML('<style>.doc-md { max-height: 78vh; overflow: auto; padding-right: 16px; }.doc-md img { max-width: 100%; height: auto; border: 1px solid #ddd; border-radius: 6px; margin: 8px 0; }</style>')
+                gr.Markdown(_load_doc_markdown(), elem_classes=['doc-md'])
     return demo