Polish README with repo and eval links

README.md

@@ -37,38 +37,79 @@ models:
 
 # Decompress
 
-Decompress is a calm, bounded voice/text check-in companion. The point is not
-just what it says; it is when it chooses not to say anything. The same
-training-free when-to-speak controller from Pitch or Perish drives the timing:
-MiniCPM exposes surprise, hidden-state deltas, readiness, and turn-end
-probability, then the controller waits, backchannels, or responds at the pause.
+Decompress is a calm five-minute voice/text check-in companion. It is built for
+the practical Backyard track: after a stressful moment, the app listens without
+over-talking, gives a small backchannel when appropriate, and responds at the
+pause with one grounded next step.
 
-## Backyard Use
+Live app: https://build-small-hackathon-decompress.hf.space<br>
+GitHub repo: https://github.com/Hcoder10/whentospeak
 
-This is the practical track version of the method: a small companion for a
-five-minute decompression ritual after work, before sleep, or between stressful
-tasks. It gives one grounded next step and cites the source used by the RAG
-retriever. It is wellness support only, not medical advice, diagnosis, therapy,
-or crisis care.
+This is wellness support only. It is not medical advice, diagnosis, therapy, or
+crisis care.
 
-## Tiny Titan / Sponsor Stack
+## Why It Feels Less Robotic
 
-- **OpenBMB:** `openbmb/MiniCPM3-4B` is the load-bearing brain for NLL,
-  hidden states, readiness, and generated companion lines.
+The same WhenToSpeak controller from Pitch or Perish drives the timing. It does
+not train a supervised turn-taking head. MiniCPM exposes the signals it already
+has during inference: predictive surprise, hidden-state deltas, reply readiness,
+and turn-end probability. The controller decides whether to stay silent,
+backchannel, hold, or answer.
+
+In the cached live-model timing eval, the controller reaches F1 `0.788` versus
+`0.696` for the best baseline. The ablation is surprise-only `0.500`,
++readiness `0.538`, +change-point `0.563`, and full turn-end handling `0.788`.
+
+## Backyard Stack
+
+- **OpenBMB:** `openbmb/MiniCPM3-4B` is the load-bearing brain for NLL, hidden
+  states, readiness, turn-end probability, and generated companion replies.
 - **Cohere:** `CohereLabs/cohere-transcribe-03-2026` powers push-to-talk voice
-  input before the exact same text-streamed controller runs.
-- **Modal:** MiniCPM and Cohere ASR run as protected A10G endpoints with one
-  warm container during judging.
-- **OpenAI:** the repo history includes Codex-attributed implementation commits.
-- **Small weights:** the app uses <=4B LLM/ASR models, Kokoro-82M for CPU TTS,
-  and all-MiniLM-L6-v2 for local RAG retrieval.
-
-## Sources
-
-The shipped corpus is intentionally small and conservative. It paraphrases
-open-access stress-management, CBT, breathwork, and grounding sources from WHO,
-NHS, NIH NCCIH, University of Rochester Medical Center, and Scientific Reports,
-with citations displayed in the UI.
+  input, then the exact same text-streamed controller runs.
+- **Modal:** protected A10 endpoints host MiniCPM and Cohere ASR with cached
+  weights.
+- **Kokoro:** `hexgrad/Kokoro-82M` speaks the companion line from the Space CPU.
+- **RAG:** `sentence-transformers/all-MiniLM-L6-v2` retrieves from a small,
+  cited, open-access wellness corpus.
+- **OpenAI:** the public repo history is Codex-attributed.
+
+The app uses small weights: MiniCPM3-4B for the brain, a 2B Cohere ASR model,
+Kokoro-82M for speech, and a compact local embedder.
+
+## Grounding Sources
+
+The corpus is intentionally small and conservative. The UI cites retrieved
+sources from WHO, NHS Every Mind Matters, NIH NCCIH, University of Rochester
+Medical Center, and Scientific Reports. Suggestions are phrased as practical
+stress-management steps, not medical claims.
+
+## How It Works
+
+1. Type a check-in or record one with the mic.
+2. Cohere Transcribe converts voice clips to English text.
+3. The check-in is streamed as word groups through MiniCPM on Modal.
+4. The training-free controller decides whether Decompress should wait,
+   backchannel, hold, or take the floor.
+5. The final reply is short, spoken with Kokoro, and shown beside citations.
+
+## Run Locally
+
+The public Space is the intended demo. Local UI runs need the protected Modal
+endpoint URL/token in environment variables or Space secrets.
+
+```bash
+uv sync
+uv run python apps/decompress/app.py
+```
+
+Expected environment for the live backend:
+
+```text
+DECOMPRESS_BRAIN_ENDPOINT_URL
+DECOMPRESS_BRAIN_ENDPOINT_TOKEN
+DECOMPRESS_TRANSCRIBE_ENDPOINT_URL
+DECOMPRESS_TRANSCRIBE_ENDPOINT_TOKEN
+```
 
 ## Links