README.md

metadata

title: Decompress
emoji: 🌿
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.18.0
python_version: '3.12'
app_file: app.py
startup_duration_timeout: 45min
pinned: true
license: mit
short_description: A MiniCPM voice companion that knows when not to talk.
tags:
  - gradio
  - build-small-hackathon
  - stress-management
  - wellness
  - full-duplex
  - training-free
  - rag
  - track:backyard
  - sponsor:openbmb
  - sponsor:cohere
  - sponsor:modal
  - sponsor:openai
  - achievement:offbrand
  - tiny-titan
  - minicpm
  - cohere
models:
  - openbmb/MiniCPM3-4B
  - CohereLabs/cohere-transcribe-03-2026
  - hexgrad/Kokoro-82M
  - sentence-transformers/all-MiniLM-L6-v2

Decompress

Decompress proves the same small, training-free timing policy can make a companion wait through stress, backchannel lightly, then answer with one grounded step.

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.

Try it on Hugging Face Space: https://build-small-hackathon-decompress.hf.space
GitHub repo: https://github.com/Hcoder10/whentospeak

This is wellness support only. It is not medical advice, diagnosis, therapy, or crisis care.

Why It Feels Less Robotic

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, 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 live demo runs on Modal, but the timing path uses small, on-device-class weights: MiniCPM3-4B for the brain, a 2B Cohere ASR model, Kokoro-82M for speech, and a compact local embedder. There is no supervised turn-taking head and no cloud LLM call for the core when-to-speak policy.

Demo

Plain link fallback: eval/decompress_capture.mp4

Social post: SOCIAL_URL_PLACEHOLDER

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.

uv sync
uv run python apps/decompress/app.py

Expected environment for the live backend:

DECOMPRESS_BRAIN_ENDPOINT_URL
DECOMPRESS_BRAIN_ENDPOINT_TOKEN
DECOMPRESS_TRANSCRIBE_ENDPOINT_URL
DECOMPRESS_TRANSCRIBE_ENDPOINT_TOKEN