Feat/voice stuff (#7)

* voice plan

* voice models config

* echocoach

* coach echo wip

* wip try fix record

* test record wip

* test echocoach

* wip fix recording

.cursor/plans/echocoach_voice_tab_45e774f7.plan.md

@@ -0,0 +1,249 @@
+---
+name: EchoCoach voice tab
+overview: "Add an EchoCoach tab to the existing Gradio app: record a pitch locally, transcribe with a configurable voice-model stack (Cohere Transcribe 2B default, Whisper.cpp fallback), analyze fillers/pace with matplotlib, coach via the existing MiniCPM5 text LLM, and speak feedback back with local TTS (Piper; MiniCPM-o 4.5 optional when GPU allows)."
+todos:
+  - id: scaffold-echocoach-lib
+    content: Create libs/echocoach package with config.py, voice_models.yaml loader, EchoCoachResult types, and workspace pyproject wiring
+    status: completed
+  - id: analysis-module
+    content: Implement filler detection, pace scoring, and matplotlib chart generation (fillers bar + pace timeline)
+    status: completed
+  - id: asr-backends
+    content: Add Cohere Transcribe ASR backend (primary) and pywhispercpp tiny/base fallback with factory pattern
+    status: completed
+  - id: coach-tts
+    content: Wire coach prompts to existing inference backend; add Piper TTS VoiceOut with per-language voice map
+    status: completed
+  - id: gradio-tab
+    content: Build echo_coach.py tab (mic record, language, analyze, transcript HTML, charts, audio out, trace) and register in app.py
+    status: completed
+  - id: docs-docker
+    content: Update voice_models.yaml, .env.example, USAGE.md, Dockerfile copy paths; add unit tests and smoke fixture
+    status: completed
+isProject: false
+---
+
+# EchoCoach — Real-Time Voice Practice Coach
+
+## Goal
+
+Ship a new **EchoCoach** tab in [`apps/gradio-space/src/gradio_space/app.py`](apps/gradio-space/src/gradio_space/app.py) that runs the hackathon demo end-to-end **locally**:
+
+> Record up to 30s pitch → transcript with **filler words highlighted** → **pace score** chart → **rewrite suggestion** from a small text LLM → **VoiceOut** audio reply in the selected language.
+
+Per your direction: **no SmolLM3 LoRA**. Voice I/O is config-driven; coaching stays on the existing text preset (`minicpm5-1b`).
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph ui [echo_coach.py Gradio tab]
+    Mic[gr.Audio mic max 30s]
+    Lang[Language dropdown 14 langs]
+    VoicePreset[ASR and TTS preset]
+    AnalyzeBtn[Analyze pitch]
+  end
+
+  subgraph voice [libs/echocoach]
+    ASR[ASR backend factory]
+    Analysis[filler + pace + matplotlib]
+    Coach[coach prompts via inference]
+    TTS[TTS VoiceOut backend]
+  end
+
+  Mic --> ASR
+  Lang --> ASR
+  ASR --> Transcript[transcript text]
+  Transcript --> Analysis
+  Analysis --> Charts[pace + filler plots]
+  Transcript --> Coach
+  Coach --> Feedback[rewrite + tips JSON]
+  Feedback --> TTS
+  TTS --> AudioOut[gr.Audio playback]
+```
+
+## Voice model strategy (configurable)
+
+Add a dedicated registry — [`voice_models.yaml`](voice_models.yaml) at repo root (parallel to [`models.yaml`](models.yaml)) — so ASR/TTS are swappable without touching the text LLM presets.
+
+| Preset key | Role | Stack | When to use |
+|------------|------|-------|-------------|
+| `cohere-transcribe` (default ASR) | Speech → text | `CohereLabs/cohere-transcribe-03-2026` via `transformers>=5.4` | 14 languages, edge-friendly 2B ASR, best accuracy |
+| `whisper-cpp-tiny` | Speech → text fallback | `pywhispercpp` (preferred over stale `whisper-cpp-python`) | CPU-only, fast, English-focused demos |
+| `whisper-cpp-base` | Speech → text fallback | same | Better WER, still lightweight |
+| `piper-multilingual` (default TTS) | Text → speech VoiceOut | Piper voices mapped per language code | Local TTS for all 14 Cohere langs |
+| `minicpm-o-4.5` (optional, stretch) | Speech in + speech out | `openbmb/MiniCPM-o-4_5` with `init_audio=True, init_tts=True` | GPU workstation only (~9B); EN/ZH TTS |
+
+**MVP ships:** `cohere-transcribe` + `piper-multilingual` + `minicpm5-1b` coach.
+
+**Evaluate MiniCPM-o 4.5** as an alternate preset behind `ECHOCOACH_VOICE_PROFILE=omni` — do not block MVP on its heavier deps / GPU requirements.
+
+Env vars (add to [`.env.example`](.env.example)):
+
+- `ECHOCOACH_ASR_PRESET` — default `cohere-transcribe`
+- `ECHOCOACH_TTS_PRESET` — default `piper-multilingual`
+- `ECHOCOACH_COACH_MODEL` — default `minicpm5-1b` (reuses [`libs/inference`](libs/inference))
+- `ECHOCOACH_MAX_SECONDS` — default `30`
+
+## New package: `libs/echocoach`
+
+Mirror the inference factory pattern in a focused library.
+
+### Layout
+
+```
+libs/echocoach/
+  pyproject.toml
+  src/echocoach/
+    config.py          # load voice_models.yaml + env overrides
+    asr/
+      base.py
+      cohere.py        # CohereAsrForConditionalGeneration wrapper
+      whisper_cpp.py   # pywhispercpp tiny/base
+      factory.py
+    tts/
+      base.py
+      piper.py         # language → voice map, WAV output
+      factory.py
+    analysis/
+      fillers.py       # detect um/uh/like/you know/… + highlight HTML
+      pace.py          # WPM, target band 120–160, 0–100 score
+      charts.py        # matplotlib → PNG paths for Gradio Image
+    coach.py           # structured JSON coach via get_backend()
+    pipeline.py        # orchestrate: audio path → EchoCoachResult
+```
+
+### ASR: Cohere Transcribe (primary)
+
+Follow the official HF quick start (`AutoProcessor`, `CohereAsrForConditionalGeneration`, `language="en"` etc.). Notes for implementation:
+
+- Model is **gated** on Hugging Face — document `huggingface-cli login` + accept terms in USAGE.
+- Requires `transformers>=5.4.0`, `soundfile`, `librosa`.
+- Pass explicit `language` from the UI dropdown (`en`, `fr`, `de`, `es`, `it`, `pt`, `nl`, `pl`, `el`, `ar`, `ja`, `zh`, `vi`, `ko`).
+- Resample incoming audio to 16 kHz mono (Gradio uploads may vary).
+
+### ASR: Whisper.cpp fallback
+
+Use **`pywhispercpp`** (actively maintained; same whisper.cpp backend you specified). Wrap `Model('tiny'|'base').transcribe(wav_path)` for offline file transcription. Skip `pyaudio` in MVP — Gradio `gr.Audio(sources=["microphone"], type="filepath")` captures mic without PortAudio in the server process.
+
+### Analysis (no LLM)
+
+Rule-based, fast, deterministic:
+
+- **Fillers:** configurable word list + regex; return spans for HTML highlight in transcript panel.
+- **Pace:** `words / (duration_minutes)`; score vs target band; flag too fast/slow.
+- **Charts** ([`matplotlib`](https://matplotlib.org/) Agg backend):
+  - Bar chart: filler counts
+  - Line chart: words-per-30s-window over recording duration
+
+### Coach (text LLM)
+
+Reuse [`get_backend(model_key).chat()`](libs/inference/src/inference/factory.py) with a tight system prompt asking for JSON:
+
+```json
+{
+  "summary": "...",
+  "filler_feedback": "...",
+  "pace_feedback": "...",
+  "rewrite": "...",
+  "one_tip": "..."
+}
+```
+
+Parse with existing JSON repair patterns from [`libs/agent/src/agent/runner.py`](libs/agent/src/agent/runner.py) (reuse `_parse_json` style, don't duplicate agent runner).
+
+### TTS VoiceOut
+
+- **Piper:** map language code → voice model; synthesize coach `summary + one_tip` (or full rewrite on toggle) to WAV under `AGENT_OUTPUTS_DIR`.
+- Return filepath to `gr.Audio` for playback.
+- If Piper voice missing for a language, fall back to English voice + show UI warning.
+
+## Gradio tab: `echo_coach.py`
+
+New file [`apps/gradio-space/src/gradio_space/tabs/echo_coach.py`](apps/gradio-space/src/gradio_space/tabs/echo_coach.py).
+
+**UI components:**
+
+| Component | Purpose |
+|-----------|---------|
+| `gr.Audio` (mic, max 30s) | Record pitch |
+| Language dropdown (14 codes) | Cohere ASR + TTS voice selection |
+| ASR preset dropdown (dev) | `cohere-transcribe` / `whisper-cpp-tiny` / `whisper-cpp-base` |
+| Coach model status | Reuse `model_status()` from [`model_loading.py`](apps/gradio-space/src/gradio_space/model_loading.py) |
+| Analyze button | Run full pipeline |
+| Transcript HTML | Filler highlights |
+| Markdown report | Pace score, filler count, coach JSON fields |
+| `gr.Image` × 2 | Matplotlib charts |
+| `gr.Audio` output | VoiceOut playback |
+| `gr.JSON` | Trace (Sharing is Caring badge) |
+
+Wire into [`app.py`](apps/gradio-space/src/gradio_space/app.py) as a fourth tab and export from [`tabs/__init__.py`](apps/gradio-space/src/gradio_space/tabs/__init__.py).
+
+## Dependencies
+
+Add to workspace:
+
+| Package | Where | Why |
+|---------|-------|-----|
+| `echocoach` | root `pyproject.toml` workspace member | new lib |
+| `matplotlib`, `soundfile`, `librosa` | `libs/echocoach` | charts + audio I/O |
+| `pywhispercpp` | `libs/echocoach` optional extra `[whisper]` | whisper fallback |
+| `piper-tts` or `piper-phonemize` | `libs/echocoach` optional extra `[piper]` | VoiceOut |
+| bump `transformers>=5.4` | `libs/inference` or `echocoach` | Cohere ASR class |
+
+Keep **`pyaudio` out of MVP** (Gradio handles capture). Document optional streaming mode (pyaudio + segment callback) as phase 2.
+
+## Docker / HF Space notes
+
+Current [`Dockerfile`](Dockerfile) copies only gradio-space + agent + inference. EchoCoach requires:
+
+- Copy `libs/echocoach` + `voice_models.yaml`
+- `apt-get install` `ffmpeg`, `libsndfile1` (audio deps)
+- **Mic access:** HF Space visitors can **upload** audio; live mic is **local dev only**
+- **GPU basic** recommended when `cohere-transcribe` is active (2B ASR + 1B coach)
+
+## Testing
+
+Lightweight unit tests in `libs/echocoach/tests/`:
+
+- `test_fillers.py` — highlight spans on sample transcript
+- `test_pace.py` — WPM + score for known duration/word count
+- `test_coach_parse.py` — JSON extraction from mocked LLM output
+- Skip GPU/integration tests in CI; smoke script `scripts/echo_coach_smoke.sh` with a bundled 5s WAV fixture
+
+## Docs
+
+Update [`USAGE.md`](USAGE.md):
+
+- EchoCoach tab walkthrough
+- Voice preset config (`voice_models.yaml`, env vars)
+- HF gated model login for Cohere Transcribe
+- Local-only mic vs Space upload
+- Hardware guidance (CPU whisper vs GPU cohere)
+
+## Implementation order
+
+1. **`libs/echocoach` scaffold** — config, types, `EchoCoachResult` dataclass
+2. **Analysis module** — fillers, pace, matplotlib (no ML deps)
+3. **ASR backends** — Cohere first, whisper fallback second
+4. **Coach module** — prompts + inference integration
+5. **TTS Piper backend** — language voice map + WAV output
+6. **Gradio tab** — wire UI + pipeline
+7. **Registry + docs** — `voice_models.yaml`, `.env.example`, USAGE.md, Dockerfile copy paths
+
+## Risks and mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Cohere model gated / large download | Document HF auth; allow `whisper-cpp-tiny` preset for offline CPU demo |
+| Cohere needs transformers 5.4+ | Pin in `echocoach` pyproject; test alongside existing inference |
+| Piper voice coverage gaps | English fallback + visible warning in UI |
+| MiniCPM-o 4.5 instability / VRAM | Optional preset only; not MVP blocker |
+| Real-time duplex | Deferred; MVP is record-then-analyze (matches demo) |
+
+## Hackathon alignment
+
+- **Backyard track** — teacher/student voice practice for someone you know
+- **Tiny Titan** — coach on MiniCPM5 1B; ASR on 2B Cohere (still "small model" stack)
+- **All local** — no cloud LLM API; optional HF weight download only
+- **Sharing is Caring** — JSON trace per analysis under `outputs/traces/`

.cursor/plans/teachervoice_realtime_plan_8950875f.plan.md

@@ -0,0 +1,211 @@
+---
+name: TeacherVoice Realtime Plan
+overview: EchoCoach today is a one-shot pitch *review* pipeline (record → analyze → report). TeacherVoice-style real-time teaching needs a new turn-based voice conversation layer that reuses existing ASR/LLM/TTS pieces but changes the interaction model, prompts, and integration with lessons/RAG.
+todos:
+  - id: teacher-voice-core
+    content: Add teacher_voice.py + mode prompts + TeacherVoiceTurnResult; wire ASR → chat(history) → TTS per turn
+    status: pending
+  - id: teacher-voice-ui
+    content: Create teacher_voice.py Gradio tab (modes, push-to-talk, chatbot, audio reply, optional RAG); register in app.py
+    status: pending
+  - id: rag-lesson-modes
+    content: Integrate ResearchMind retrieval into Explain/Lesson modes (reuse run_research_question / rag scope from chat tab)
+    status: pending
+  - id: docs-tests
+    content: Update USAGE.md with EchoCoach vs TeacherVoice; add mock-backend unit tests and trace skill teacher-voice
+    status: pending
+  - id: phase2-chunked-tts
+    content: "Optional: sentence-chunked Piper + shorter turn cap for faster time-to-first-audio"
+    status: pending
+  - id: phase3-omni
+    content: "Optional: MiniCPM-o 4.5 omni preset behind ECHOCOACH_VOICE_PROFILE=omni for speech-in/speech-out"
+    status: pending
+isProject: false
+---
+
+# TeacherVoice — from EchoCoach review to real-time voice teacher
+
+## What “coach help” is today
+
+In this repo, **coach help = EchoCoach** — a separate Gradio tab, not a global assistant.
+
+| What it does | What it does **not** do |
+|--------------|-------------------------|
+| Records up to 30s of **your** monologue (pitch practice) | Talk back-and-forth in a conversation |
+| Transcribes → scores fillers/pace → one LLM **JSON report** | Explain lesson topics on demand |
+| Speaks **one** Piper TTS clip (summary or rewrite) | Create slides or pitch decks by voice |
+| Runs once per click on **Analyze pitch** | Stream partial audio or interrupt mid-sentence |
+
+Pipeline (batch, sequential):
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Gradio as EchoCoach_tab
+  participant Pipe as run_echo_coach
+  participant ASR
+  participant Coach as coach.py_JSON
+  participant TTS
+
+  User->>Gradio: Record_stop_then_Analyze
+  Gradio->>Pipe: audio_filepath
+  Pipe->>ASR: full_file_transcribe
+  Pipe->>Pipe: fillers_pace_charts
+  Pipe->>Coach: single_shot_JSON_prompt
+  Pipe->>TTS: one_WAV_summary
+  Pipe->>Gradio: report_charts_audio
+```
+
+Key code: [`libs/echocoach/src/echocoach/pipeline.py`](libs/echocoach/src/echocoach/pipeline.py) orchestrates ASR → analysis → [`coach.py`](libs/echocoach/src/echocoach/coach.py) → Piper. UI is [`apps/gradio-space/src/gradio_space/tabs/echo_coach.py`](apps/gradio-space/src/gradio_space/tabs/echo_coach.py).
+
+**Lesson slides** ([`education_pptx.py`](apps/gradio-space/src/gradio_space/tabs/education_pptx.py)) and **Chat (debug)** ([`chat.py`](apps/gradio-space/src/gradio_space/tabs/chat.py)) are unrelated tabs: slides are batch `AgentRunner` jobs; chat is **text-only** multi-turn (optionally RAG via [`rag_aware_chat`](apps/gradio-space/src/gradio_space/research_helpers.py)).
+
+There is **no `TeacherVoice` name, WebSocket, or streaming voice** anywhere in the codebase. The EchoCoach plan explicitly deferred duplex:
+
+> Real-time duplex | Deferred; MVP is record-then-analyze
+
+---
+
+## How TeacherVoice differs (target behavior)
+
+**TeacherVoice** (what you’re describing) is a **conversational voice teacher**:
+
+- You speak a **question or short turn** → teacher **replies in voice** → repeat
+- Modes share one chat history but different system prompts:
+  - **Explain** — tutor a topic in plain language (optionally grounded in ResearchMind RAG)
+  - **Lesson** — discuss/outline a lesson verbally (can hand off topic to Lesson slides tab)
+  - **Pitch** — lighter coaching per turn (“try opening with X”) instead of one big JSON report
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant TV as TeacherVoice_tab
+  participant ASR
+  participant LLM as chat_with_history
+  participant TTS
+
+  loop each_turn
+    User->>TV: push_to_talk_stop
+    TV->>ASR: transcribe_turn
+    TV->>LLM: messages_plus_mode_system_prompt
+    LLM-->>TV: reply_text
+    TV->>TTS: synthesize_reply
+    TV->>User: play_audio_update_chat
+  end
+```
+
+This is **turn-based pseudo-real-time** (typical latency: ~2–8s per turn on GPU). True **duplex** TeacherVoice (interrupt while speaking, sub-second feel) would need streaming ASR + chunked TTS or an omni speech model — not present today.
+
+---
+
+## Recommended architecture (phased)
+
+### Phase 1 — TeacherVoice tab (MVP, fits current stack)
+
+Add a **TeacherVoice** tab alongside EchoCoach; keep EchoCoach as the deep pitch *analyzer*.
+
+**New module** in `libs/echocoach` (minimal new package surface):
+
+- `teacher_voice.py` — `run_teacher_voice_turn(audio_path, history, mode, language, backend, rag_context?) -> TeacherVoiceTurnResult`
+- `prompts.py` — mode system prompts (`explain`, `lesson`, `pitch`) as **plain text** chat (not JSON like EchoCoach)
+- Reuse: [`recording.py`](libs/echocoach/src/echocoach/recording.py), ASR factory, Piper TTS, `InferenceBackend.chat()`
+
+**New Gradio tab** `teacher_voice.py`:
+
+- Mode dropdown: Explain | Lesson coach | Pitch practice
+- Optional: ResearchMind session/docs (copy pattern from [`chat.py`](apps/gradio-space/src/gradio_space/tabs/chat.py))
+- Topic field for Lesson/Explain modes
+- **Push-to-talk**: reuse Start/Stop recording from EchoCoach (already works server-side)
+- `gr.Chatbot` (text history) + `gr.Audio` auto-play for teacher reply
+- “Clear conversation” button
+
+**Turn flow per button press:**
+
+1. Stop recording → WAV path
+2. ASR → user text (show in chat)
+3. Build messages: `system(mode)` + `history` + optional RAG context block + `user(transcript)`
+4. `backend.chat()` — same stack as debug chat ([`inference`](libs/inference/src/inference/base.py) has no streaming today; full response is fine for MVP)
+5. Piper TTS → play reply
+6. Append `(user, assistant)` to history
+
+**Pitch mode vs EchoCoach:** Pitch mode gives **conversational** tips each turn; EchoCoach remains the **quantitative** tool (WPM, filler charts, rewrite JSON). Link from TeacherVoice: “Deep analysis → open EchoCoach tab with last recording.”
+
+**Lesson mode:** Does not generate `.pptx` by voice in MVP. It verbally outlines and explains; user can copy topic into Lesson slides tab. Phase 2 can add “Generate slides from this conversation” button calling `AgentRunner.run_education_pptx`.
+
+### Phase 2 — Faster “feels live” (still not full duplex)
+
+- **VAD / max 15s turns** — cap turn length for lower latency
+- **Sentence-chunked TTS** — split LLM reply on `.!?`, synthesize first sentence while rest generates (reuse Piper in a small loop)
+- **Optional streaming ASR** — only if a backend supports partial transcripts (Cohere batch is fine for MVP; whisper stays file-based)
+- Latency target: first audio ~3s after stop on GPU
+
+### Phase 3 — True speech-in/speech-out (optional, GPU-heavy)
+
+From [`echocoach_voice_tab` plan](.cursor/plans/echocoach_voice_tab_45e774f7.plan.md), not implemented:
+
+- Add `minicpm-o-4.5` preset to [`voice_models.yaml`](voice_models.yaml) behind `ECHOCOACH_VOICE_PROFILE=omni`
+- New omni backend in `libs/echocoach` (or `libs/inference`) with `init_audio=True, init_tts=True`
+- TeacherVoice tab switches to omni when profile=omni and GPU available
+- EN/ZH only initially; falls back to Phase 1 pipeline otherwise
+
+Skip WebSocket server unless you need browser-native duplex outside Gradio — Gradio turn-based is enough for hackathon demo.
+
+---
+
+## What to reuse vs build new
+
+| Component | Reuse | New work |
+|-----------|-------|----------|
+| Mic capture | `recording.py`, `gr.Audio` | Wire to per-turn handler |
+| ASR | `asr/factory.py` | Call per turn, not once per monologue |
+| LLM | `get_backend().chat()` | Mode prompts + multi-turn history (like chat tab) |
+| RAG | `run_research_question` / `rag_aware_chat` logic | Inject retrieved context into TeacherVoice system prompt |
+| TTS | `tts/piper.py` | Per-turn synthesis; optional chunking in Phase 2 |
+| Pitch analytics | `analysis/fillers.py`, `pace.py` | **Not** on every TeacherVoice turn — keep in EchoCoach only |
+| Lesson PPTX | `AgentRunner.run_education_pptx` | Phase 2 button, not MVP voice loop |
+
+---
+
+## Files to touch (Phase 1)
+
+| File | Change |
+|------|--------|
+| [`libs/echocoach/src/echocoach/teacher_voice.py`](libs/echocoach/src/echocoach/teacher_voice.py) | **New** — turn orchestration + result type |
+| [`libs/echocoach/src/echocoach/prompts.py`](libs/echocoach/src/echocoach/prompts.py) | **New** — Explain / Lesson / Pitch system prompts |
+| [`apps/gradio-space/src/gradio_space/tabs/teacher_voice.py`](apps/gradio-space/src/gradio_space/tabs/teacher_voice.py) | **New** — UI |
+| [`apps/gradio-space/src/gradio_space/app.py`](apps/gradio-space/src/gradio_space/app.py) | Register TeacherVoice tab |
+| [`apps/gradio-space/src/gradio_space/tabs/__init__.py`](apps/gradio-space/src/gradio_space/tabs/__init__.py) | Export builder |
+| [`USAGE.md`](USAGE.md) | Document modes, latency expectations, EchoCoach vs TeacherVoice |
+| [`libs/echocoach/tests/test_teacher_voice.py`](libs/echocoach/tests/test_teacher_voice.py) | Mock-backend tests for prompt assembly + history |
+
+EchoCoach files stay unchanged except optional cross-link in UI markdown.
+
+---
+
+## Hardware and UX expectations
+
+- **CPU-only:** Whisper tiny ASR + MiniCPM5 1B + Piper — workable but ~5–15s per turn; set expectations in UI
+- **GPU:** Cohere Transcribe + same coach model — better for demo
+- **HF Space:** Upload/push-to-talk may be limited; document local-only mic (same as EchoCoach)
+- Label honestly: **“Voice conversation (turn-based)”** until Phase 3 omni
+
+---
+
+## Success criteria for MVP
+
+- User can hold a **3+ turn** spoken conversation in Explain mode
+- Lesson mode accepts a topic + optional RAG session and answers from ingested docs with citations in chat text
+- Pitch mode gives short spoken coaching without requiring Analyze pitch
+- EchoCoach tab still works independently for full pitch analysis
+- Trace JSON per session under `outputs/traces/` (skill: `teacher-voice`)
+
+---
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Users expect ChatGPT Voice latency | UI copy: turn-based; show “Transcribing / Thinking / Speaking” states |
+| RAG + voice doubles latency | Retrieve once per turn; keep `max_tokens` modest (~512) |
+| Piper missing voice for language | Existing English fallback in [`voice_models.yaml`](voice_models.yaml) |
+| Confusion between EchoCoach and TeacherVoice | Separate tabs; Pitch mode points to EchoCoach for charts |

.env.example

@@ -50,6 +50,17 @@ ALLOW_MODEL_SWITCH=false
 # After training, point Gradio at the adapter preset:
 # ACTIVE_MODEL=minicpm5-1b-lesson-lora
 
+# --- EchoCoach (voice practice coach) ---
+# VOICE_PRESETS_PATH=./voice_models.yaml
+# ECHOCOACH_ASR_PRESET=whisper-cpp-tiny
+# ECHOCOACH_TTS_PRESET=piper-multilingual
+# ECHOCOACH_COACH_MODEL=minicpm5-1b
+# ECHOCOACH_MAX_SECONDS=30
+# ECHOCOACH_CAPTURE_DEVICE=   # optional ALSA/PipeWire device (e.g. pipewire, alsa_input.pci-...)
+# PIPER_VOICES_DIR=~/.local/share/piper/voices
+# For Cohere Transcribe ASR: huggingface-cli login + accept model terms, then:
+# ECHOCOACH_ASR_PRESET=cohere-transcribe
+
 # --- Ensemble research (research/ensemble/) ---
 # Base LLM resolution (first match wins): ENSEMBLE_LLM, LLM_PATH, BASE, MODEL_ID, ACTIVE_MODEL
 # LLM_PATH=./models/finetuned/minicpm5-1b-lora-merged

.gitignore

@@ -14,4 +14,5 @@ outputs/traces
 
 /results
 
-outputs/researchmind
+outputs/researchmind
+outputs/echocoach

Dockerfile

@@ -7,19 +7,23 @@ ENV PYTHONUNBUFFERED=1 \
 RUN apt-get update && apt-get install -y --no-install-recommends \
     build-essential \
     cmake \
+    ffmpeg \
+    libsndfile1 \
     && rm -rf /var/lib/apt/lists/*
 
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
 WORKDIR /app
 
-COPY pyproject.toml uv.lock .python-version README.md models.yaml ./
+COPY pyproject.toml uv.lock .python-version README.md models.yaml voice_models.yaml ./
 COPY apps/gradio-space/pyproject.toml apps/gradio-space/README.md apps/gradio-space/
 COPY libs/inference/pyproject.toml libs/inference/README.md libs/inference/
 COPY libs/agent/pyproject.toml libs/agent/README.md libs/agent/
+COPY libs/echocoach/pyproject.toml libs/echocoach/README.md libs/echocoach/
 COPY apps/gradio-space/src apps/gradio-space/src
 COPY libs/inference/src libs/inference/src
 COPY libs/agent/src libs/agent/src
+COPY libs/echocoach/src libs/echocoach/src
 COPY skills skills
 
 RUN useradd -m -u 1000 user && \

USAGE.md

@@ -2,7 +2,7 @@
 
 How to run the **Lesson Agent** Gradio app locally, test it in Docker, and deploy to a Hugging Face Space for the [Build Small Hackathon](https://huggingface.co/build-small-hackathon).
 
-The primary UI is the **Lesson slides** tab (topic → local model outline → downloadable `.pptx`). Use **ResearchMind** for corpus Q&A, or ground lessons directly from the Lesson tab. The **Chat (debug)** tab tests the underlying model.
+The primary UI is the **Lesson slides** tab (topic → local model outline → downloadable `.pptx`). Use **ResearchMind** for corpus Q&A, **EchoCoach** for voice practice feedback, or ground lessons directly from the Lesson tab. The **Chat (debug)** tab tests the underlying model.
 
 ## Prerequisites
 
@@ -72,6 +72,55 @@ When **Web search** is selected, choose a **search workflow**:
 
 Web discover/auto search requires network access. MemRAG data is stored under `RESEARCHMIND_DATA_DIR` (default `outputs/researchmind`).
 
+Web discover/auto search requires network access. MemRAG data is stored under `RESEARCHMIND_DATA_DIR` (default `outputs/researchmind`).
+
+### EchoCoach — voice practice
+
+The **EchoCoach** tab records up to 30 seconds, then runs a local pipeline:
+
+**Getting audio in**
+
+- **Record from this computer** — click **Start recording**, speak, then **Stop recording** (uses PipeWire `pw-record` when available). The slider is a max-length safety cap.
+- **Browser Record** — needs mic permission and a secure context; open **http://localhost:7860** (not `0.0.0.0` or a LAN IP).
+- **Upload** — drop a `.wav` or `.mp3` file (works everywhere, including HF Space).
+
+If recordings sound silent, check system mic input/mute or set `ECHOCOACH_CAPTURE_DEVICE` in `.env` (see `arecord -L` or `pw-cli ls Node`).
+
+Pipeline steps:
+
+1. **ASR** — Cohere Transcribe 2B (14 languages) or Whisper.cpp tiny/base
+2. **Analysis** — filler highlights, pace score, matplotlib charts
+3. **Coach** — rewrite + tips from the text LLM (`ACTIVE_MODEL`, default `minicpm5-1b`)
+4. **VoiceOut** — Piper TTS speaks the summary (or full rewrite if checked)
+
+Install optional extras:
+
+```bash
+# Whisper.cpp fallback ASR (CPU)
+uv sync --package echocoach --extra whisper
+
+# Piper VoiceOut TTS
+uv sync --package echocoach --extra piper
+python -m piper.download_voices en_US-lessac-medium
+```
+
+Configure presets in [`voice_models.yaml`](voice_models.yaml) or via `.env`:
+
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| `ECHOCOACH_ASR_PRESET` | `whisper-cpp-tiny` | ASR preset key |
+| `ECHOCOACH_TTS_PRESET` | `piper-multilingual` | TTS preset key |
+| `ECHOCOACH_COACH_MODEL` | `minicpm5-1b` | Text coach preset (from `models.yaml`) |
+| `ECHOCOACH_MAX_SECONDS` | `30` | Max recording length |
+
+**Cohere Transcribe** (`cohere-transcribe`) is gated on Hugging Face — run `huggingface-cli login`, accept the model terms, then set `ECHOCOACH_ASR_PRESET=cohere-transcribe`. GPU recommended for ASR + coach together.
+
+Smoke tests (analysis only, no GPU):
+
+```bash
+bash scripts/echo_coach_smoke.sh
+```
+
 ### 5. Upload agent trace (Sharing is Caring badge)
 
 ```bash

apps/gradio-space/pyproject.toml

@@ -9,12 +9,14 @@ authors = [
 requires-python = ">=3.12"
 dependencies = [
     "agent",
+    "echocoach[whisper]",
     "gradio>=5.0.0",
     "inference",
 ]
 
 [tool.uv.sources]
 agent = { workspace = true }
+echocoach = { workspace = true }
 inference = { workspace = true }
 
 [build-system]

apps/gradio-space/src/gradio_space/app.py

@@ -3,8 +3,14 @@ import os
 import gradio as gr
 
 from gradio_space.model_loading import preload_active_model
-from gradio_space.tabs import build_chat_tab, build_education_pptx_tab, build_research_mind_tab
+from gradio_space.tabs import (
+    build_chat_tab,
+    build_education_pptx_tab,
+    build_echo_coach_tab,
+    build_research_mind_tab,
+)
 from gradio_space.tabs.education_pptx import gradio_allowed_paths
+from gradio_space.tabs.echo_coach import echo_coach_allowed_paths
 from gradio_space.tabs.research_mind import researchmind_allowed_paths
 from inference.config import get_app_config
 
@@ -22,9 +28,9 @@ def build_demo() -> gr.Blocks:
     with gr.Blocks(title="Lesson Agent + ResearchMind — Build Small Hackathon") as demo:
         gr.Markdown(
             f"""
-# Lesson Agent + ResearchMind
+# Lesson Agent + ResearchMind + EchoCoach
 
-Local skill-based agents — **lesson slides** and **research with MemRAG** (offline Q&A after ingest).
+Local skill-based agents — **lesson slides**, **research with MemRAG**, and **voice practice coaching** (offline).
 
 - **Model:** `{active.key}` — {active.label}
 - **Backend:** `{active.backend}`
@@ -39,6 +45,8 @@ Part of the [Build Small Hackathon](https://huggingface.co/build-small-hackathon
                 build_education_pptx_tab()
             with gr.Tab("ResearchMind"):
                 build_research_mind_tab()
+            with gr.Tab("EchoCoach"):
+                build_echo_coach_tab()
             with gr.Tab("Chat (debug)"):
                 build_chat_tab()
 
@@ -48,10 +56,20 @@ Part of the [Build Small Hackathon](https://huggingface.co/build-small-hackathon
 def main() -> None:
     preload_active_model()
     demo = build_demo()
+    port = int(os.environ.get("PORT", "7860"))
+    server_name = os.environ.get("GRADIO_SERVER_NAME", "0.0.0.0")
+    print(
+        f"\n  Local UI (browser mic works here): http://127.0.0.1:{port}\n"
+        f"  Bound address: {server_name}:{port}\n"
+    )
     demo.launch(
-        server_name="0.0.0.0",
-        server_port=int(os.environ.get("PORT", "7860")),
-        allowed_paths=[*gradio_allowed_paths(), *researchmind_allowed_paths()],
+        server_name=server_name,
+        server_port=port,
+        allowed_paths=[
+            *gradio_allowed_paths(),
+            *researchmind_allowed_paths(),
+            *echo_coach_allowed_paths(),
+        ],
     )
 
 

apps/gradio-space/src/gradio_space/tabs/__init__.py

@@ -1,5 +1,11 @@
 from gradio_space.tabs.chat import build_chat_tab
 from gradio_space.tabs.education_pptx import build_education_pptx_tab
+from gradio_space.tabs.echo_coach import build_echo_coach_tab
 from gradio_space.tabs.research_mind import build_research_mind_tab
 
-__all__ = ["build_chat_tab", "build_education_pptx_tab", "build_research_mind_tab"]
+__all__ = [
+    "build_chat_tab",
+    "build_education_pptx_tab",
+    "build_echo_coach_tab",
+    "build_research_mind_tab",
+]

apps/gradio-space/src/gradio_space/tabs/echo_coach.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import gradio as gr
+
+from echocoach.config import get_echo_coach_config
+from echocoach.pipeline import run_echo_coach
+from echocoach.recording import (
+    ServerRecordingError,
+    recording_backend_status,
+    recording_elapsed_seconds,
+    recording_level_warning,
+    start_server_recording,
+    stop_server_recording,
+)
+from gradio_space.model_loading import ensure_model_loaded, get_active_model_key, model_status
+from inference.factory import get_backend
+
+_config = get_echo_coach_config()
+_SAMPLE_AUDIO = (
+    Path(__file__).resolve().parents[5]
+    / "libs"
+    / "echocoach"
+    / "tests"
+    / "fixtures"
+    / "silence_2s.wav"
+)
+
+
+def _error_outputs(message: str) -> tuple:
+    return (
+        message,
+        f'<p style="color:#8a1f1f;">{message}</p>',
+        "",
+        None,
+        None,
+        None,
+        message,
+        {},
+    )
+
+
+def ui_start_recording(max_seconds: int) -> tuple[str, dict, dict]:
+    try:
+        start_server_recording(int(max_seconds))
+    except ServerRecordingError as exc:
+        return (
+            str(exc),
+            gr.update(interactive=True),
+            gr.update(interactive=False),
+        )
+    return (
+        (
+            f"Recording… speak now, then click **Stop recording** "
+            f"(auto-stops after {int(max_seconds)}s)."
+        ),
+        gr.update(interactive=False),
+        gr.update(interactive=True),
+    )
+
+
+def ui_stop_recording() -> tuple[str | None, str, dict, dict]:
+    try:
+        elapsed = recording_elapsed_seconds()
+        path = stop_server_recording()
+        warning = recording_level_warning(path)
+    except ServerRecordingError as exc:
+        return (
+            None,
+            str(exc),
+            gr.update(interactive=True),
+            gr.update(interactive=False),
+        )
+    except Exception as exc:  # noqa: BLE001 — surface unexpected recorder errors
+        return (
+            None,
+            f"Recording failed: {exc}",
+            gr.update(interactive=True),
+            gr.update(interactive=False),
+        )
+
+    status = f"Recording saved ({elapsed:.1f}s) → `{path}`. Click **Analyze pitch**."
+    if warning:
+        status += f" Warning: {warning}"
+    return (
+        gr.update(value=str(path)),
+        status,
+        gr.update(interactive=True),
+        gr.update(interactive=False),
+    )
+
+
+def load_sample_pitch() -> tuple[str | None, str]:
+    if not _SAMPLE_AUDIO.is_file():
+        return (
+            None,
+            f"Sample clip missing at `{_SAMPLE_AUDIO}`. Run `uv run python libs/echocoach/tests/make_fixture.py`.",
+        )
+    return gr.update(value=str(_SAMPLE_AUDIO)), "Loaded 2s sample clip. Click **Analyze pitch** to test the pipeline."
+
+
+def analyze_pitch(
+    audio_path: str | None,
+    language: str,
+    asr_preset: str,
+    speak_rewrite: bool,
+) -> tuple:
+    model_key = get_active_model_key()
+    load_error = ensure_model_loaded(model_key)
+    if load_error:
+        return _error_outputs(load_error)
+
+    if not audio_path:
+        return _error_outputs("Record or upload a pitch (up to 30 seconds), then click **Analyze pitch**.")
+
+    try:
+        result = run_echo_coach(
+            audio_path,
+            language=language,
+            asr_preset=asr_preset,
+            backend=get_backend(model_key),
+            speak_rewrite=speak_rewrite,
+        )
+    except Exception as exc:  # noqa: BLE001 — surface pipeline errors in UI
+        return _error_outputs(f"EchoCoach failed: {exc}")
+
+    status = "Analysis complete."
+    if result.voiceout_warning:
+        status += f" VoiceOut: {result.voiceout_warning}"
+
+    return (
+        status,
+        result.transcript_html,
+        result.report_markdown,
+        result.filler_chart_path,
+        result.pace_chart_path,
+        result.voiceout_path,
+        f"Trace saved: `{result.trace_path}`",
+        result.trace,
+    )
+
+
+def build_echo_coach_tab() -> None:
+    lang_choices = _config.language_choices()
+    asr_choices = _config.asr_choices()
+    default_lang = lang_choices[0][1] if lang_choices else "en"
+    default_asr = _config.asr_preset
+    mic_status = recording_backend_status()
+
+    gr.Markdown(
+        f"""
+Record up to **{_config.max_seconds} seconds**, then get local feedback: transcript with **filler highlights**,
+**pace score**, coach **rewrite**, and **VoiceOut** audio — all on-device.
+
+- **ASR:** configurable (`voice_models.yaml`) — Cohere Transcribe 2B or Whisper.cpp
+- **Coach:** text LLM preset (`ACTIVE_MODEL` / `ECHOCOACH_COACH_MODEL`)
+- **TTS:** Piper VoiceOut (optional; install `echocoach[piper]`)
+
+**Browser mic:** open **http://localhost:7860** in Chrome or Firefox (not Cursor's preview) and allow microphone access.
+If the mic icon fails, use **Start / Stop recording** below or **Upload** a `.wav` / `.mp3`.
+"""
+    )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            record_status_md = gr.Markdown(mic_status)
+            with gr.Accordion("Record from this computer (recommended)", open=True):
+                gr.Markdown(
+                    "Click **Start recording**, speak your pitch, then **Stop recording** when done. "
+                    "The slider sets the maximum length (auto-stop safety cap)."
+                )
+                record_seconds = gr.Slider(
+                    label="Max recording length (seconds)",
+                    minimum=3,
+                    maximum=_config.max_seconds,
+                    value=min(30, _config.max_seconds),
+                    step=1,
+                )
+                with gr.Row():
+                    record_start_btn = gr.Button("Start recording", variant="secondary")
+                    record_stop_btn = gr.Button("Stop recording", variant="stop", interactive=False)
+                sample_btn = gr.Button("Load sample clip", variant="secondary")
+            audio_in = gr.Audio(
+                label="Your pitch (browser mic or upload)",
+                sources=["upload", "microphone"],
+                type="filepath",
+                format="wav",
+            )
+            language = gr.Dropdown(
+                label="Language",
+                choices=lang_choices,
+                value=default_lang,
+            )
+            asr_preset = gr.Dropdown(
+                label="ASR preset",
+                choices=asr_choices,
+                value=default_asr,
+            )
+            speak_rewrite = gr.Checkbox(
+                label="VoiceOut speaks full rewrite (otherwise summary + tip)",
+                value=False,
+            )
+            analyze_btn = gr.Button("Analyze pitch", variant="primary")
+            status = gr.Textbox(label="Status", interactive=False, lines=3)
+            coach_status = gr.Markdown(model_status(get_active_model_key()))
+
+        with gr.Column(scale=2):
+            transcript_html = gr.HTML(label="Transcript")
+            report_md = gr.Markdown(label="Coach report")
+            with gr.Row():
+                filler_chart = gr.Image(label="Filler words", type="filepath")
+                pace_chart = gr.Image(label="Pace timeline", type="filepath")
+            voiceout = gr.Audio(label="VoiceOut", type="filepath")
+            trace_note = gr.Markdown()
+            trace_json = gr.JSON(label="Trace")
+
+    record_start_btn.click(
+        ui_start_recording,
+        inputs=[record_seconds],
+        outputs=[status, record_start_btn, record_stop_btn],
+    )
+    record_stop_btn.click(
+        ui_stop_recording,
+        outputs=[audio_in, status, record_start_btn, record_stop_btn],
+    ).then(
+        lambda: recording_backend_status(),
+        outputs=[record_status_md],
+    )
+
+    sample_btn.click(
+        load_sample_pitch,
+        outputs=[audio_in, status],
+    )
+
+    analyze_btn.click(
+        analyze_pitch,
+        inputs=[audio_in, language, asr_preset, speak_rewrite],
+        outputs=[
+            status,
+            transcript_html,
+            report_md,
+            filler_chart,
+            pace_chart,
+            voiceout,
+            trace_note,
+            trace_json,
+        ],
+    )
+
+
+def echo_coach_allowed_paths() -> list[str]:
+    base = get_echo_coach_config()
+    paths: list[str] = []
+    if base.presets_path:
+        paths.append(str(base.presets_path.parent))
+    from echocoach.config import outputs_dir
+
+    paths.append(str(outputs_dir()))
+    paths.append(str(outputs_dir() / "recordings"))
+    if _SAMPLE_AUDIO.is_file():
+        paths.append(str(_SAMPLE_AUDIO.parent))
+    return paths

libs/echocoach/README.md

@@ -0,0 +1,10 @@
+# echocoach
+
+Local voice practice coach for the Build Small Hackathon.
+
+- **ASR:** Cohere Transcribe 2B or Whisper.cpp (tiny/base)
+- **Analysis:** filler detection, pace scoring, matplotlib charts
+- **Coach:** text LLM via `inference` (default `minicpm5-1b`)
+- **VoiceOut:** Piper TTS (optional extra)
+
+Configure presets in repo-root `voice_models.yaml`.

libs/echocoach/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "echocoach"
+version = "0.1.0"
+description = "Local voice practice coach — ASR, pace/filler analysis, LLM coaching, TTS VoiceOut"
+readme = "README.md"
+authors = [
+    { name = "MSGhais", email = "msghais135@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "inference",
+    "agent",
+    "matplotlib>=3.9.0",
+    "numpy>=2.0.0",
+    "pyyaml>=6.0.2",
+    "soundfile>=0.12.0",
+    "sounddevice>=0.5.0",
+    "librosa>=0.10.0",
+    "transformers>=5.4.0",
+    "torch>=2.5.0",
+    "accelerate>=1.2.0",
+    "huggingface-hub>=0.27.0",
+]
+
+[project.optional-dependencies]
+whisper = [
+    "pywhispercpp>=1.3.0",
+]
+piper = [
+    "piper-tts>=1.3.0",
+]
+
+[tool.uv.sources]
+inference = { workspace = true }
+agent = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"

libs/echocoach/src/echocoach/__init__.py

@@ -0,0 +1,6 @@
+"""EchoCoach — local voice practice coach."""
+
+from echocoach.models import CoachFeedback, EchoCoachResult
+from echocoach.pipeline import run_echo_coach
+
+__all__ = ["CoachFeedback", "EchoCoachResult", "run_echo_coach"]

libs/echocoach/src/echocoach/analysis/charts.py

@@ -0,0 +1,96 @@
+"""Matplotlib charts for filler and pace visualization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt  # noqa: E402
+
+from echocoach.models import FillerAnalysis, PaceAnalysis
+
+
+def render_filler_chart(analysis: FillerAnalysis, out_path: Path) -> Path:
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    if not analysis.counts:
+        fig, ax = plt.subplots(figsize=(6, 3))
+        ax.bar(["(none)"], [0], color="#4a90d9")
+        ax.set_title("Filler words")
+        ax.set_ylabel("Count")
+    else:
+        labels = list(analysis.counts.keys())
+        values = [analysis.counts[k] for k in labels]
+        fig, ax = plt.subplots(figsize=(6, 3))
+        ax.bar(labels, values, color="#e67e22")
+        ax.set_title("Filler words")
+        ax.set_ylabel("Count")
+        plt.xticks(rotation=35, ha="right")
+    fig.tight_layout()
+    fig.savefig(out_path, dpi=120)
+    plt.close(fig)
+    return out_path
+
+
+def render_pace_timeline(
+    transcript: str,
+    duration_seconds: float,
+    pace: PaceAnalysis,
+    out_path: Path,
+    *,
+    window_seconds: float = 10.0,
+) -> Path:
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    words = transcript.split()
+    if not words or duration_seconds <= 0:
+        fig, ax = plt.subplots(figsize=(6, 3))
+        ax.plot([0, max(duration_seconds, 1)], [0, 0], color="#4a90d9")
+        ax.set_title("Words per minute (rolling)")
+        ax.set_xlabel("Seconds")
+        ax.set_ylabel("WPM")
+        ax.axhspan(pace.target_low, pace.target_high, alpha=0.15, color="green", label="Target band")
+        ax.legend(loc="upper right")
+    else:
+        n_windows = max(1, int(duration_seconds / window_seconds) + (1 if duration_seconds % window_seconds else 0))
+        times: list[float] = []
+        wpms: list[float] = []
+        words_per_sec = len(words) / duration_seconds
+        for i in range(n_windows):
+            start = i * window_seconds
+            end = min((i + 1) * window_seconds, duration_seconds)
+            window_dur = end - start
+            if window_dur <= 0:
+                continue
+            approx_words = words_per_sec * window_dur
+            wpm = approx_words / (window_dur / 60.0)
+            times.append((start + end) / 2)
+            wpms.append(wpm)
+
+        fig, ax = plt.subplots(figsize=(6, 3))
+        ax.plot(times, wpms, marker="o", color="#4a90d9", linewidth=2)
+        ax.axhspan(pace.target_low, pace.target_high, alpha=0.15, color="green", label="Target band")
+        ax.set_title("Words per minute (by segment)")
+        ax.set_xlabel("Seconds")
+        ax.set_ylabel("WPM")
+        ax.legend(loc="upper right")
+
+    fig.tight_layout()
+    fig.savefig(out_path, dpi=120)
+    plt.close(fig)
+    return out_path
+
+
+def build_charts(
+    transcript: str,
+    duration_seconds: float,
+    fillers: FillerAnalysis,
+    pace: PaceAnalysis,
+    output_dir: Path,
+    run_id: str,
+) -> tuple[Path, Path]:
+    filler_path = output_dir / f"{run_id}_fillers.png"
+    pace_path = output_dir / f"{run_id}_pace.png"
+    render_filler_chart(fillers, filler_path)
+    render_pace_timeline(transcript, duration_seconds, pace, pace_path)
+    return filler_path, pace_path

libs/echocoach/src/echocoach/analysis/fillers.py

@@ -0,0 +1,82 @@
+"""Filler word detection and HTML highlighting."""
+
+from __future__ import annotations
+
+import re
+
+from echocoach.models import FillerAnalysis, FillerSpan
+
+DEFAULT_FILLERS = [
+    "um",
+    "uh",
+    "uhm",
+    "erm",
+    "like",
+    "you know",
+    "basically",
+    "actually",
+    "literally",
+    "sort of",
+    "kind of",
+    "i mean",
+    "right",
+    "okay so",
+    "so yeah",
+]
+
+# Longer phrases first so "you know" wins over "you"
+_SORTED_FILLERS = sorted(DEFAULT_FILLERS, key=len, reverse=True)
+_PATTERN = re.compile(
+    r"\b(" + "|".join(re.escape(f) for f in _SORTED_FILLERS) + r")\b",
+    re.IGNORECASE,
+)
+
+
+def analyze_fillers(transcript: str, fillers: list[str] | None = None) -> FillerAnalysis:
+    if fillers is None:
+        pattern = _PATTERN
+    else:
+        ordered = sorted(fillers, key=len, reverse=True)
+        pattern = re.compile(
+            r"\b(" + "|".join(re.escape(f) for f in ordered) + r")\b",
+            re.IGNORECASE,
+        )
+
+    counts: dict[str, int] = {}
+    spans: list[FillerSpan] = []
+    for match in pattern.finditer(transcript):
+        word = match.group(1).lower()
+        counts[word] = counts.get(word, 0) + 1
+        spans.append(FillerSpan(start=match.start(), end=match.end(), word=word))
+
+    return FillerAnalysis(counts=counts, spans=spans, total=sum(counts.values()))
+
+
+def highlight_fillers_html(transcript: str, analysis: FillerAnalysis) -> str:
+    if not analysis.spans:
+        safe = _escape_html(transcript)
+        return f'<p style="line-height:1.6;">{safe}</p>'
+
+    parts: list[str] = []
+    cursor = 0
+    for span in sorted(analysis.spans, key=lambda s: s.start):
+        if span.start < cursor:
+            continue
+        parts.append(_escape_html(transcript[cursor : span.start]))
+        parts.append(
+            f'<mark style="background:#ffe08a;padding:0 2px;border-radius:3px;">'
+            f"{_escape_html(transcript[span.start : span.end])}</mark>"
+        )
+        cursor = span.end
+    parts.append(_escape_html(transcript[cursor:]))
+    body = "".join(parts)
+    return f'<p style="line-height:1.6;">{body}</p>'
+
+
+def _escape_html(text: str) -> str:
+    return (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )

libs/echocoach/src/echocoach/analysis/pace.py

@@ -0,0 +1,49 @@
+"""Speaking pace scoring."""
+
+from __future__ import annotations
+
+from echocoach.audio_io import count_words
+from echocoach.models import PaceAnalysis
+
+TARGET_LOW = 120
+TARGET_HIGH = 160
+
+
+def analyze_pace(
+    transcript: str,
+    duration_seconds: float,
+    *,
+    target_low: int = TARGET_LOW,
+    target_high: int = TARGET_HIGH,
+) -> PaceAnalysis:
+    word_count = count_words(transcript)
+    if duration_seconds <= 0:
+        wpm = 0.0
+    else:
+        wpm = word_count / (duration_seconds / 60.0)
+
+    score, label = _score_wpm(wpm, target_low, target_high)
+    return PaceAnalysis(
+        word_count=word_count,
+        duration_seconds=duration_seconds,
+        wpm=round(wpm, 1),
+        score=score,
+        label=label,
+        target_low=target_low,
+        target_high=target_high,
+    )
+
+
+def _score_wpm(wpm: float, low: int, high: int) -> tuple[int, str]:
+    if wpm <= 0:
+        return 0, "No speech detected"
+    if low <= wpm <= high:
+        return 100, "Ideal pace"
+    if wpm < low:
+        ratio = wpm / low
+        score = max(20, int(100 * ratio))
+        return score, "Too slow — pick up the energy"
+    # too fast
+    overshoot = (wpm - high) / high
+    score = max(20, int(100 * (1.0 - min(overshoot, 0.8))))
+    return score, "Too fast — pause and breathe"

libs/echocoach/src/echocoach/asr/cohere.py

@@ -0,0 +1,51 @@
+"""Cohere Transcribe 2B ASR backend."""
+
+from __future__ import annotations
+
+from echocoach.audio_io import TARGET_SAMPLE_RATE, load_audio_mono_16k
+from echocoach.config import AsrPreset
+
+
+class CohereAsrBackend:
+    def __init__(self, preset: AsrPreset) -> None:
+        self._preset = preset
+        self._processor = None
+        self._model = None
+
+    def _load(self) -> None:
+        if self._model is not None:
+            return
+        from transformers import AutoProcessor, CohereAsrForConditionalGeneration
+
+        model_id = self._preset.model_id or "CohereLabs/cohere-transcribe-03-2026"
+        self._processor = AutoProcessor.from_pretrained(model_id)
+        self._model = CohereAsrForConditionalGeneration.from_pretrained(
+            model_id,
+            device_map="auto",
+        )
+
+    def transcribe(self, audio_path: str, *, language: str) -> str:
+        self._load()
+        assert self._processor is not None
+        assert self._model is not None
+
+        audio, _ = load_audio_mono_16k(audio_path)
+        inputs = self._processor(
+            audio,
+            sampling_rate=TARGET_SAMPLE_RATE,
+            return_tensors="pt",
+            language=language,
+        )
+        audio_chunk_index = inputs.get("audio_chunk_index")
+        inputs = inputs.to(self._model.device, dtype=self._model.dtype)
+
+        outputs = self._model.generate(**inputs, max_new_tokens=512)
+        decoded = self._processor.decode(
+            outputs,
+            skip_special_tokens=True,
+            audio_chunk_index=audio_chunk_index,
+            language=language,
+        )
+        if isinstance(decoded, list):
+            return decoded[0].strip() if decoded else ""
+        return str(decoded).strip()

libs/echocoach/src/echocoach/asr/factory.py

@@ -0,0 +1,40 @@
+"""ASR backend protocol and factory."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from echocoach.config import AsrPreset, get_echo_coach_config
+
+
+class AsrBackend(Protocol):
+    def transcribe(self, audio_path: str, *, language: str) -> str: ...
+
+
+_asr_cache: dict[tuple, AsrBackend] = {}
+
+
+def get_asr_backend(preset_key: str | None = None) -> AsrBackend:
+    config = get_echo_coach_config()
+    preset = config.get_asr(preset_key)
+    cache_key = (preset.key, preset.backend, preset.model_id, preset.model_size)
+    if cache_key in _asr_cache:
+        return _asr_cache[cache_key]
+
+    if preset.backend == "cohere":
+        from echocoach.asr.cohere import CohereAsrBackend
+
+        backend: AsrBackend = CohereAsrBackend(preset)
+    elif preset.backend == "whisper_cpp":
+        from echocoach.asr.whisper_cpp import WhisperCppBackend
+
+        backend = WhisperCppBackend(preset)
+    else:
+        raise ValueError(f"Unsupported ASR backend: {preset.backend}")
+
+    _asr_cache[cache_key] = backend
+    return backend
+
+
+def reset_asr_backends() -> None:
+    _asr_cache.clear()

libs/echocoach/src/echocoach/asr/whisper_cpp.py

@@ -0,0 +1,33 @@
+"""Whisper.cpp ASR via pywhispercpp."""
+
+from __future__ import annotations
+
+from echocoach.config import AsrPreset
+
+
+class WhisperCppBackend:
+    def __init__(self, preset: AsrPreset) -> None:
+        self._preset = preset
+        self._model = None
+
+    def _load(self) -> None:
+        if self._model is not None:
+            return
+        try:
+            from pywhispercpp.model import Model
+        except ImportError as exc:
+            raise ImportError(
+                "Whisper.cpp backend requires pywhispercpp. "
+                "Install with: uv sync --package echocoach --extra whisper"
+            ) from exc
+
+        size = self._preset.model_size or "tiny"
+        self._model = Model(size, print_realtime=False, print_progress=False)
+
+    def transcribe(self, audio_path: str, *, language: str) -> str:
+        self._load()
+        assert self._model is not None
+
+        segments = self._model.transcribe(audio_path, language=language)
+        parts = [seg.text.strip() for seg in segments if getattr(seg, "text", "")]
+        return " ".join(parts).strip()

libs/echocoach/src/echocoach/audio_io.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import numpy as np
+
+TARGET_SAMPLE_RATE = 16_000
+
+
+def load_audio_mono_16k(path: str | Path) -> tuple[np.ndarray, float]:
+    """Load audio as mono float32 at 16 kHz; return (samples, duration_seconds)."""
+    import librosa
+
+    audio, _ = librosa.load(str(path), sr=TARGET_SAMPLE_RATE, mono=True)
+    duration = len(audio) / TARGET_SAMPLE_RATE if len(audio) else 0.0
+    return audio.astype(np.float32), duration
+
+
+def clamp_duration(audio: np.ndarray, max_seconds: float) -> np.ndarray:
+    max_samples = int(max_seconds * TARGET_SAMPLE_RATE)
+    if len(audio) > max_samples:
+        return audio[:max_samples]
+    return audio
+
+
+def write_wav_temp(audio: np.ndarray, directory: Path, stem: str = "clip") -> Path:
+    import soundfile as sf
+
+    directory.mkdir(parents=True, exist_ok=True)
+    out = directory / f"{stem}.wav"
+    sf.write(out, audio, TARGET_SAMPLE_RATE)
+    return out
+
+
+def count_words(text: str) -> int:
+    tokens = re.findall(r"\b[\w']+\b", text, flags=re.UNICODE)
+    return len(tokens)

libs/echocoach/src/echocoach/coach.py

@@ -0,0 +1,108 @@
+"""LLM coaching prompts and parsing."""
+
+from __future__ import annotations
+
+from inference.base import InferenceBackend
+from inference.response_clean import strip_reasoning_output
+
+from echocoach.models import CoachFeedback, FillerAnalysis, PaceAnalysis
+from echocoach.utils import extract_json
+
+COACH_SYSTEM = """You are EchoCoach, a concise public-speaking coach for students and teachers.
+Respond with a single JSON object only — no markdown fences, no extra text.
+
+Required keys:
+- summary: 1-2 sentence overall assessment
+- filler_feedback: specific advice about filler words
+- pace_feedback: specific advice about speaking pace
+- rewrite: improved 2-4 sentence version of the pitch (same language as the transcript)
+- one_tip: one actionable tip for the next attempt
+"""
+
+
+def coach_user_prompt(
+    transcript: str,
+    fillers: FillerAnalysis,
+    pace: PaceAnalysis,
+    language: str,
+) -> str:
+    filler_list = ", ".join(f"{k} ({v})" for k, v in fillers.counts.items()) or "none"
+    return f"""Language: {language}
+Duration: {pace.duration_seconds:.1f}s
+Word count: {pace.word_count}
+Pace: {pace.wpm} WPM (target {pace.target_low}-{pace.target_high}) — {pace.label} (score {pace.score}/100)
+Filler words: {fillers.total} total — {filler_list}
+
+Transcript:
+{transcript}
+"""
+
+
+def run_coach(
+    backend: InferenceBackend,
+    transcript: str,
+    fillers: FillerAnalysis,
+    pace: PaceAnalysis,
+    language: str,
+) -> tuple[CoachFeedback, str, str]:
+    user_content = coach_user_prompt(transcript, fillers, pace, language)
+    messages = [
+        {"role": "system", "content": COACH_SYSTEM},
+        {"role": "user", "content": user_content},
+    ]
+    raw = backend.chat(messages, max_tokens=768, temperature=0.4)
+    raw = strip_reasoning_output(raw)
+    feedback = parse_coach_response(raw)
+    return feedback, COACH_SYSTEM, raw
+
+
+def parse_coach_response(raw: str) -> CoachFeedback:
+    data = extract_json(raw)
+    return CoachFeedback(
+        summary=str(data.get("summary", "")).strip(),
+        filler_feedback=str(data.get("filler_feedback", "")).strip(),
+        pace_feedback=str(data.get("pace_feedback", "")).strip(),
+        rewrite=str(data.get("rewrite", "")).strip(),
+        one_tip=str(data.get("one_tip", "")).strip(),
+    )
+
+
+def format_report_markdown(
+    coach: CoachFeedback,
+    fillers: FillerAnalysis,
+    pace: PaceAnalysis,
+) -> str:
+    filler_lines = (
+        "\n".join(f"- **{word}**: {count}" for word, count in fillers.counts.items())
+        or "- None detected"
+    )
+    return f"""## Pace
+
+- **Score:** {pace.score}/100 — {pace.label}
+- **WPM:** {pace.wpm} (target {pace.target_low}–{pace.target_high})
+- **Duration:** {pace.duration_seconds:.1f}s · **Words:** {pace.word_count}
+
+## Fillers ({fillers.total})
+
+{filler_lines}
+
+## Coach summary
+
+{coach.summary}
+
+### Filler feedback
+
+{coach.filler_feedback}
+
+### Pace feedback
+
+{coach.pace_feedback}
+
+### Suggested rewrite
+
+{coach.rewrite}
+
+### One tip
+
+{coach.one_tip}
+"""

libs/echocoach/src/echocoach/config.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any, Literal
+
+AsrBackendName = Literal["cohere", "whisper_cpp"]
+TtsBackendName = Literal["piper"]
+
+
+@dataclass(frozen=True)
+class LanguageOption:
+    code: str
+    label: str
+
+
+@dataclass(frozen=True)
+class AsrPreset:
+    key: str
+    label: str
+    backend: AsrBackendName
+    model_id: str | None = None
+    model_size: str | None = None
+
+
+@dataclass(frozen=True)
+class TtsPreset:
+    key: str
+    label: str
+    backend: TtsBackendName
+    voices: dict[str, str]
+    fallback_voice: str
+
+
+@dataclass(frozen=True)
+class EchoCoachConfig:
+    asr_preset: str
+    tts_preset: str
+    coach_model: str
+    max_seconds: int
+    languages: list[LanguageOption]
+    asr_presets: dict[str, AsrPreset]
+    tts_presets: dict[str, TtsPreset]
+    presets_path: Path | None = None
+
+    def get_asr(self, key: str | None = None) -> AsrPreset:
+        preset_key = key or self.asr_preset
+        if preset_key not in self.asr_presets:
+            known = ", ".join(sorted(self.asr_presets))
+            raise KeyError(f"Unknown ASR preset {preset_key!r}. Known: {known}")
+        return self.asr_presets[preset_key]
+
+    def get_tts(self, key: str | None = None) -> TtsPreset:
+        preset_key = key or self.tts_preset
+        if preset_key not in self.tts_presets:
+            known = ", ".join(sorted(self.tts_presets))
+            raise KeyError(f"Unknown TTS preset {preset_key!r}. Known: {known}")
+        return self.tts_presets[preset_key]
+
+    def asr_choices(self) -> list[tuple[str, str]]:
+        return [(p.label, p.key) for p in self.asr_presets.values()]
+
+    def language_choices(self) -> list[tuple[str, str]]:
+        return [(lang.label, lang.code) for lang in self.languages]
+
+
+def _find_voice_presets_path() -> Path | None:
+    env_path = os.environ.get("VOICE_PRESETS_PATH")
+    if env_path:
+        path = Path(env_path)
+        if path.is_file():
+            return path.resolve()
+
+    for base in (Path.cwd(), *Path.cwd().parents):
+        candidate = base / "voice_models.yaml"
+        if candidate.is_file():
+            return candidate.resolve()
+    return None
+
+
+def _builtin_config() -> EchoCoachConfig:
+    langs = [
+        LanguageOption("en", "English"),
+        LanguageOption("fr", "French"),
+        LanguageOption("de", "German"),
+    ]
+    asr = {
+        "whisper-cpp-tiny": AsrPreset(
+            key="whisper-cpp-tiny",
+            label="Whisper.cpp tiny",
+            backend="whisper_cpp",
+            model_size="tiny",
+        ),
+    }
+    tts = {
+        "piper-multilingual": TtsPreset(
+            key="piper-multilingual",
+            label="Piper TTS",
+            backend="piper",
+            voices={"en": "en_US-lessac-medium"},
+            fallback_voice="en_US-lessac-medium",
+        ),
+    }
+    return EchoCoachConfig(
+        asr_preset="whisper-cpp-tiny",
+        tts_preset="piper-multilingual",
+        coach_model="minicpm5-1b",
+        max_seconds=30,
+        languages=langs,
+        asr_presets=asr,
+        tts_presets=tts,
+    )
+
+
+def _parse_asr_entry(key: str, raw: dict[str, Any]) -> AsrPreset:
+    backend = str(raw.get("backend", "whisper_cpp"))
+    if backend not in ("cohere", "whisper_cpp"):
+        raise ValueError(f"ASR preset {key!r}: backend must be cohere or whisper_cpp")
+    return AsrPreset(
+        key=key,
+        label=str(raw.get("label", key)),
+        backend=backend,  # type: ignore[arg-type]
+        model_id=raw.get("model_id"),
+        model_size=raw.get("model_size"),
+    )
+
+
+def _parse_tts_entry(key: str, raw: dict[str, Any]) -> TtsPreset:
+    backend = str(raw.get("backend", "piper"))
+    if backend != "piper":
+        raise ValueError(f"TTS preset {key!r}: only piper backend is supported in MVP")
+    voices = raw.get("voices") or {}
+    if not isinstance(voices, dict) or not voices:
+        raise ValueError(f"TTS preset {key!r}: voices mapping is required")
+    return TtsPreset(
+        key=key,
+        label=str(raw.get("label", key)),
+        backend="piper",
+        voices={str(k): str(v) for k, v in voices.items()},
+        fallback_voice=str(raw.get("fallback_voice", "en_US-lessac-medium")),
+    )
+
+
+def load_echo_coach_config() -> EchoCoachConfig:
+    presets_path = _find_voice_presets_path()
+    if presets_path is None:
+        config = _builtin_config()
+    else:
+        try:
+            import yaml
+        except ImportError as exc:
+            raise ImportError(
+                "Loading voice_models.yaml requires PyYAML. Install with: uv sync"
+            ) from exc
+
+        data = yaml.safe_load(presets_path.read_text()) or {}
+        defaults = data.get("defaults", {})
+        raw_langs = data.get("languages", [])
+        raw_asr = data.get("asr", {})
+        raw_tts = data.get("tts", {})
+
+        languages = [
+            LanguageOption(code=str(item["code"]), label=str(item["label"]))
+            for item in raw_langs
+        ]
+        asr_presets = {
+            key: _parse_asr_entry(key, value) for key, value in raw_asr.items()
+        }
+        tts_presets = {
+            key: _parse_tts_entry(key, value) for key, value in raw_tts.items()
+        }
+
+        asr_default = defaults.get("asr_preset", "whisper-cpp-tiny")
+        tts_default = defaults.get("tts_preset", "piper-multilingual")
+        if asr_default not in asr_presets:
+            asr_default = next(iter(asr_presets))
+        if tts_default not in tts_presets:
+            tts_default = next(iter(tts_presets))
+
+        config = EchoCoachConfig(
+            asr_preset=asr_default,
+            tts_preset=tts_default,
+            coach_model=str(defaults.get("coach_model", "minicpm5-1b")),
+            max_seconds=int(defaults.get("max_seconds", 30)),
+            languages=languages,
+            asr_presets=asr_presets,
+            tts_presets=tts_presets,
+            presets_path=presets_path,
+        )
+
+    updates: dict[str, Any] = {}
+    if os.environ.get("ECHOCOACH_ASR_PRESET"):
+        updates["asr_preset"] = os.environ["ECHOCOACH_ASR_PRESET"]
+    if os.environ.get("ECHOCOACH_TTS_PRESET"):
+        updates["tts_preset"] = os.environ["ECHOCOACH_TTS_PRESET"]
+    if os.environ.get("ECHOCOACH_COACH_MODEL"):
+        updates["coach_model"] = os.environ["ECHOCOACH_COACH_MODEL"]
+    if os.environ.get("ECHOCOACH_MAX_SECONDS"):
+        updates["max_seconds"] = int(os.environ["ECHOCOACH_MAX_SECONDS"])
+
+    return replace(config, **updates) if updates else config
+
+
+_config: EchoCoachConfig | None = None
+
+
+def get_echo_coach_config(reload: bool = False) -> EchoCoachConfig:
+    global _config
+    if _config is None or reload:
+        _config = load_echo_coach_config()
+    return _config
+
+
+def outputs_dir() -> Path:
+    env = os.environ.get("AGENT_OUTPUTS_DIR")
+    if env:
+        return Path(env)
+    for base in (Path.cwd(), *Path.cwd().parents):
+        if (base / "voice_models.yaml").is_file() or (base / "pyproject.toml").is_file():
+            path = base / "outputs" / "echocoach"
+            path.mkdir(parents=True, exist_ok=True)
+            return path
+    path = Path("/tmp/echocoach_outputs")
+    path.mkdir(parents=True, exist_ok=True)
+    return path

libs/echocoach/src/echocoach/models.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class FillerSpan:
+    start: int
+    end: int
+    word: str
+
+
+@dataclass(frozen=True)
+class FillerAnalysis:
+    counts: dict[str, int]
+    spans: list[FillerSpan]
+    total: int
+
+
+@dataclass(frozen=True)
+class PaceAnalysis:
+    word_count: int
+    duration_seconds: float
+    wpm: float
+    score: int
+    label: str
+    target_low: int = 120
+    target_high: int = 160
+
+
+@dataclass(frozen=True)
+class CoachFeedback:
+    summary: str
+    filler_feedback: str
+    pace_feedback: str
+    rewrite: str
+    one_tip: str
+
+
+@dataclass
+class EchoCoachResult:
+    transcript: str
+    transcript_html: str
+    language: str
+    duration_seconds: float
+    fillers: FillerAnalysis
+    pace: PaceAnalysis
+    coach: CoachFeedback
+    report_markdown: str
+    filler_chart_path: str | None
+    pace_chart_path: str | None
+    voiceout_path: str | None
+    voiceout_warning: str | None
+    trace_path: str
+    trace: dict[str, Any] = field(default_factory=dict)

libs/echocoach/src/echocoach/pipeline.py

@@ -0,0 +1,127 @@
+"""End-to-end EchoCoach pipeline."""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from typing import Any
+
+from agent.trace import TraceRecorder
+from inference.base import InferenceBackend
+
+from echocoach.analysis.charts import build_charts
+from echocoach.analysis.fillers import analyze_fillers, highlight_fillers_html
+from echocoach.analysis.pace import analyze_pace
+from echocoach.asr.factory import get_asr_backend
+from echocoach.audio_io import clamp_duration, load_audio_mono_16k, write_wav_temp
+from echocoach.coach import format_report_markdown, run_coach
+from echocoach.config import get_echo_coach_config, outputs_dir
+from echocoach.models import EchoCoachResult
+from echocoach.tts.piper import get_tts_backend
+
+
+def run_echo_coach(
+    audio_path: str,
+    *,
+    language: str = "en",
+    asr_preset: str | None = None,
+    tts_preset: str | None = None,
+    coach_model: str | None = None,
+    backend: InferenceBackend,
+    speak_rewrite: bool = False,
+) -> EchoCoachResult:
+    if not audio_path:
+        raise ValueError("No audio recording provided.")
+
+    config = get_echo_coach_config()
+    asr_key = asr_preset or config.asr_preset
+    tts_key = tts_preset or config.tts_preset
+    model_key = coach_model or config.coach_model
+    run_id = uuid.uuid4().hex[:12]
+    out_base = outputs_dir()
+
+    trace = TraceRecorder(
+        skill="echo-coach",
+        model=model_key,
+        user_input={
+            "language": language,
+            "asr_preset": asr_key,
+            "tts_preset": tts_key,
+            "audio_path": audio_path,
+            "speak_rewrite": speak_rewrite,
+        },
+        run_id=run_id,
+    )
+
+    audio, duration = load_audio_mono_16k(audio_path)
+    audio = clamp_duration(audio, config.max_seconds)
+    duration = len(audio) / 16_000
+    clipped_path = write_wav_temp(audio, out_base / "clips", stem=run_id)
+
+    trace.log_note("audio_loaded", duration_seconds=duration, path=str(clipped_path))
+
+    asr = get_asr_backend(asr_key)
+    transcript = asr.transcribe(str(clipped_path), language=language)
+    trace.log_note("asr_complete", preset=asr_key, chars=len(transcript))
+
+    fillers = analyze_fillers(transcript)
+    pace = analyze_pace(transcript, duration)
+    transcript_html = highlight_fillers_html(transcript, fillers)
+
+    filler_chart, pace_chart = build_charts(
+        transcript,
+        duration,
+        fillers,
+        pace,
+        out_base / "charts",
+        run_id,
+    )
+
+    coach_feedback, system_prompt, coach_raw = run_coach(
+        backend,
+        transcript,
+        fillers,
+        pace,
+        language,
+    )
+    trace.log_llm(system_prompt + "\n\n" + coach_user_for_trace(transcript, fillers, pace, language), coach_raw)
+
+    report = format_report_markdown(coach_feedback, fillers, pace)
+
+    voice_text = coach_feedback.rewrite if speak_rewrite else (
+        f"{coach_feedback.summary} {coach_feedback.one_tip}".strip()
+    )
+    tts = get_tts_backend(tts_key)
+    voiceout_path, voiceout_warning = tts.synthesize(
+        voice_text,
+        language=language,
+        out_dir=out_base / "voiceout",
+    )
+    if voiceout_path:
+        trace.set_artifact(voiceout_path)
+
+    trace_path = trace.save()
+    trace_dict: dict[str, Any] = trace.to_dict()
+
+    return EchoCoachResult(
+        transcript=transcript,
+        transcript_html=transcript_html,
+        language=language,
+        duration_seconds=duration,
+        fillers=fillers,
+        pace=pace,
+        coach=coach_feedback,
+        report_markdown=report,
+        filler_chart_path=str(filler_chart),
+        pace_chart_path=str(pace_chart),
+        voiceout_path=voiceout_path,
+        voiceout_warning=voiceout_warning,
+        trace_path=str(trace_path),
+        trace=trace_dict,
+    )
+
+
+def coach_user_for_trace(transcript: str, fillers, pace, language: str) -> str:
+    from echocoach.coach import coach_user_prompt
+
+    return coach_user_prompt(transcript, fillers, pace, language)

libs/echocoach/src/echocoach/recording.py

@@ -0,0 +1,348 @@
+"""Record audio from the server's local microphone (bypasses browser getUserMedia)."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import subprocess
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from echocoach.audio_io import TARGET_SAMPLE_RATE, load_audio_mono_16k
+from echocoach.config import get_echo_coach_config, outputs_dir
+
+CaptureBackend = Literal["pw-record", "sounddevice", "arecord"]
+SILENT_RMS_THRESHOLD = 0.002
+
+
+class ServerRecordingError(RuntimeError):
+    """Raised when server-side capture is unavailable or fails."""
+
+
+@dataclass
+class _RecordingSession:
+    process: subprocess.Popen[bytes]
+    out_path: Path
+    backend: CaptureBackend
+    max_seconds: int
+    started_at: float
+    watchdog: threading.Timer | None = None
+
+
+_session: _RecordingSession | None = None
+_last_recording_path: Path | None = None
+_session_lock = threading.Lock()
+
+
+def _capture_device() -> str | None:
+    device = os.environ.get("ECHOCOACH_CAPTURE_DEVICE", "").strip()
+    return device or None
+
+
+def _pw_record_available() -> bool:
+    return shutil.which("pw-record") is not None
+
+
+def _sounddevice_available() -> bool:
+    try:
+        import sounddevice as sd  # noqa: PLC0415
+    except (ImportError, OSError):
+        return False
+    try:
+        sd.query_devices()
+    except Exception:
+        return False
+    return True
+
+
+def _arecord_available() -> bool:
+    if shutil.which("arecord") is None:
+        return False
+    try:
+        result = subprocess.run(
+            ["arecord", "-l"],
+            capture_output=True,
+            text=True,
+            timeout=3,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    output = f"{result.stdout}\n{result.stderr}".lower()
+    return "card" in output
+
+
+def select_capture_backend() -> CaptureBackend | None:
+    """Pick the best capture tool for this machine."""
+    if _pw_record_available():
+        return "pw-record"
+    if _sounddevice_available():
+        return "sounddevice"
+    if _arecord_available():
+        return "arecord"
+    return None
+
+
+def recording_backend_status() -> str:
+    backend = select_capture_backend()
+    device = _capture_device()
+    if backend == "pw-record":
+        note = "PipeWire pw-record"
+    elif backend == "sounddevice":
+        note = "sounddevice / PortAudio"
+    elif backend == "arecord":
+        note = "ALSA arecord"
+    else:
+        note = None
+
+    if note:
+        extra = f" (device: `{device}`)" if device else ""
+        return f"Server microphone: ready ({note}{extra}). Click **Start recording**, speak, then **Stop recording**."
+
+    hints: list[str] = []
+    if not _pw_record_available() and not _arecord_available():
+        hints.append("install PipeWire (`pw-record`) or ALSA utils (`arecord`)")
+    elif not _arecord_available():
+        hints.append("enable a microphone in system sound settings")
+    if not _sounddevice_available():
+        hints.append(
+            "optional: `sudo apt install libportaudio2` for sounddevice fallback"
+        )
+    hint = "; ".join(hints) if hints else "no capture backend available"
+    return (
+        f"Server microphone: unavailable — {hint}. "
+        "Use **Upload** or open **http://localhost:7860** in Chrome/Firefox for browser mic."
+    )
+
+
+def is_recording_active() -> bool:
+    with _session_lock:
+        session = _session
+        return session is not None and session.process.poll() is None
+
+
+def recording_elapsed_seconds() -> float:
+    with _session_lock:
+        session = _session
+        if session is None:
+            return 0.0
+        return max(0.0, time.monotonic() - session.started_at)
+
+
+def start_server_recording(max_seconds: int | None = None) -> None:
+    """Begin an open-ended capture; call stop_server_recording() to finish."""
+    global _session, _last_recording_path
+
+    config = get_echo_coach_config()
+    seconds = max_seconds if max_seconds is not None else config.max_seconds
+    if seconds <= 0:
+        raise ServerRecordingError("Recording duration must be positive.")
+
+    backend = select_capture_backend()
+    if backend is None:
+        raise ServerRecordingError(recording_backend_status())
+
+    out_dir = outputs_dir() / "recordings"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / f"server_{uuid.uuid4().hex[:8]}.wav"
+
+    with _session_lock:
+        if _session is not None and _session.process.poll() is None:
+            raise ServerRecordingError("Already recording. Click **Stop recording** first.")
+
+        _last_recording_path = None
+        process = _spawn_capture_process(backend, out_path)
+        watchdog = threading.Timer(seconds, _auto_stop_recording)
+        watchdog.daemon = True
+        watchdog.start()
+        _session = _RecordingSession(
+            process=process,
+            out_path=out_path,
+            backend=backend,
+            max_seconds=seconds,
+            started_at=time.monotonic(),
+            watchdog=watchdog,
+        )
+
+
+def stop_server_recording() -> Path:
+    """Stop the active capture and return the WAV path."""
+    global _last_recording_path
+
+    with _session_lock:
+        session = _session
+        if session is None or session.process.poll() is not None:
+            if _last_recording_path is not None and _last_recording_path.is_file():
+                path = _last_recording_path
+                _last_recording_path = None
+                return path
+            raise ServerRecordingError("Not recording. Click **Start recording** first.")
+        return _finalize_session(session)
+
+
+def _auto_stop_recording() -> None:
+    with _session_lock:
+        session = _session
+        if session is None or session.process.poll() is not None:
+            return
+        try:
+            _finalize_session(session)
+        except ServerRecordingError:
+            pass
+
+
+def _finalize_session(session: _RecordingSession) -> Path:
+    global _session, _last_recording_path
+
+    if session.watchdog is not None:
+        session.watchdog.cancel()
+
+    process = session.process
+    if process.poll() is None:
+        process.send_signal(signal.SIGINT)
+        try:
+            process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait(timeout=2)
+
+    out_path = session.out_path
+    if out_path.is_file() and out_path.stat().st_size > 44:
+        _session = None
+        _last_recording_path = out_path
+        return out_path
+
+    ok_codes = {
+        0,
+        1,  # pw-record often exits 1 after SIGINT even with a valid WAV
+        -signal.SIGINT,
+        128 + signal.SIGINT,
+        -signal.SIGTERM,
+        128 + signal.SIGTERM,
+    }
+    if process.returncode not in ok_codes:
+        detail = ""
+        if process.stderr:
+            detail = process.stderr.read().decode("utf-8", errors="replace").strip()
+        msg = f"Capture stopped with exit code {process.returncode}"
+        if detail:
+            msg = f"{msg}: {detail}"
+        _session = None
+        _last_recording_path = None
+        raise ServerRecordingError(msg)
+
+    if not out_path.is_file() or out_path.stat().st_size == 0:
+        _session = None
+        _last_recording_path = None
+        raise ServerRecordingError("Recording finished but produced an empty file.")
+
+    _session = None
+    _last_recording_path = out_path
+    return out_path
+
+
+def analyze_recording_levels(path: str | Path) -> tuple[float, float, float]:
+    audio, duration = load_audio_mono_16k(path)
+    if len(audio) == 0:
+        return 0.0, 0.0, duration
+    import numpy as np
+
+    rms = float(np.sqrt(np.mean(np.square(audio))))
+    peak = float(np.max(np.abs(audio)))
+    return rms, peak, duration
+
+
+def recording_level_warning(path: str | Path) -> str | None:
+    rms, peak, duration = analyze_recording_levels(path)
+    if duration < 0.2:
+        return "Clip is very short — try recording a bit longer."
+    if rms < SILENT_RMS_THRESHOLD and peak < SILENT_RMS_THRESHOLD * 4:
+        return (
+            "Recording looks silent. Check system mic input/mute, pick the right input device "
+            "(set `ECHOCOACH_CAPTURE_DEVICE`), or use **Upload**."
+        )
+    return None
+
+
+def record_server_wav(
+    max_seconds: int | None = None,
+    *,
+    sample_rate: int = TARGET_SAMPLE_RATE,
+) -> Path:
+    """Fixed-length capture (used in tests and scripts)."""
+    start_server_recording(max_seconds)
+    time.sleep(max_seconds if max_seconds is not None else get_echo_coach_config().max_seconds)
+    return stop_server_recording()
+
+
+def _spawn_capture_process(backend: CaptureBackend, out_path: Path) -> subprocess.Popen[bytes]:
+    device = _capture_device()
+    if backend == "pw-record":
+        cmd = [
+            "pw-record",
+            "--media-category",
+            "Capture",
+            "--media-role",
+            "Speech",
+            "--rate",
+            str(TARGET_SAMPLE_RATE),
+            "--channels",
+            "1",
+            "--format",
+            "s16",
+        ]
+        if device:
+            cmd.extend(["--target", device])
+        cmd.append(str(out_path))
+    elif backend == "arecord":
+        cmd = [
+            "arecord",
+            "-q",
+            "-f",
+            "S16_LE",
+            "-r",
+            str(TARGET_SAMPLE_RATE),
+            "-c",
+            "1",
+        ]
+        if device:
+            cmd.extend(["-D", device])
+        else:
+            cmd.extend(["-D", "pipewire"])
+        cmd.append(str(out_path))
+    else:
+        raise ServerRecordingError(
+            "sounddevice does not support open-ended capture yet; install `pw-record` or use arecord."
+        )
+
+    try:
+        return subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+    except OSError as exc:
+        raise ServerRecordingError(f"Failed to start {backend}: {exc}") from exc
+
+
+def _record_sounddevice(out_path: Path, seconds: int, sample_rate: int) -> None:
+    import numpy as np
+    import sounddevice as sd
+    import soundfile as sf
+
+    frames = int(seconds * sample_rate)
+    device = _capture_device()
+    try:
+        recording = sd.rec(
+            frames,
+            samplerate=sample_rate,
+            channels=1,
+            dtype="float32",
+            device=device,
+        )
+        sd.wait()
+    except Exception as exc:  # noqa: BLE001 — surface device errors to UI
+        raise ServerRecordingError(f"sounddevice capture failed: {exc}") from exc
+
+    sf.write(out_path, np.squeeze(recording), sample_rate)

libs/echocoach/src/echocoach/tts/__init__.py

@@ -0,0 +1,3 @@
+from echocoach.tts.piper import PiperTtsBackend, get_tts_backend
+
+__all__ = ["PiperTtsBackend", "get_tts_backend"]

libs/echocoach/src/echocoach/tts/piper.py

@@ -0,0 +1,123 @@
+"""TTS VoiceOut backends."""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from typing import Protocol
+
+from echocoach.config import TtsPreset, get_echo_coach_config, outputs_dir
+
+
+class TtsBackend(Protocol):
+    def synthesize(self, text: str, *, language: str, out_dir: Path | None = None) -> tuple[str | None, str | None]: ...
+
+
+_tts_cache: dict[str, "PiperTtsBackend"] = {}
+
+
+class PiperTtsBackend:
+    def __init__(self, preset: TtsPreset) -> None:
+        self._preset = preset
+        self._voices: dict[str, object] = {}
+
+    def _voice_name(self, language: str) -> tuple[str, str | None]:
+        voice = self._preset.voices.get(language)
+        warning = None
+        if not voice:
+            voice = self._preset.fallback_voice
+            warning = f"No Piper voice for {language!r}; using {voice}."
+        return voice, warning
+
+    def _load_voice(self, voice_name: str):
+        if voice_name in self._voices:
+            return self._voices[voice_name]
+        try:
+            from piper import PiperVoice
+        except ImportError as exc:
+            raise ImportError(
+                "Piper TTS requires piper-tts. "
+                "Install with: uv sync --package echocoach --extra piper"
+            ) from exc
+
+        onnx_path = self._resolve_voice_path(voice_name)
+        voice = PiperVoice.load(str(onnx_path))
+        self._voices[voice_name] = voice
+        return voice
+
+    def _resolve_voice_path(self, voice_name: str) -> Path:
+        env_dir = __import__("os").environ.get("PIPER_VOICES_DIR")
+        candidates: list[Path] = []
+        if env_dir:
+            candidates.append(Path(env_dir) / f"{voice_name}.onnx")
+        home = Path.home() / ".local" / "share" / "piper" / "voices"
+        candidates.append(home / f"{voice_name}.onnx")
+        candidates.append(Path.cwd() / "models" / "piper" / f"{voice_name}.onnx")
+
+        for path in candidates:
+            if path.is_file():
+                return path
+
+        try:
+            from piper.download_voices import download_voice
+        except ImportError:
+            download_voice = None
+
+        if download_voice is not None:
+            try:
+                downloaded = download_voice(voice_name)
+                return Path(downloaded)
+            except Exception:
+                pass
+
+        import subprocess
+        import sys
+
+        subprocess.run(
+            [sys.executable, "-m", "piper.download_voices", voice_name],
+            check=True,
+        )
+        for path in candidates:
+            if path.is_file():
+                return path
+
+        raise FileNotFoundError(
+            f"Piper voice {voice_name!r} not found. "
+            f"Run: python -m piper.download_voices {voice_name}"
+        )
+
+    def synthesize(
+        self,
+        text: str,
+        *,
+        language: str,
+        out_dir: Path | None = None,
+    ) -> tuple[str | None, str | None]:
+        if not text.strip():
+            return None, "No text to synthesize."
+
+        voice_name, warning = self._voice_name(language)
+        try:
+            import wave
+
+            from piper import PiperVoice
+
+            voice = self._load_voice(voice_name)
+            base = out_dir or outputs_dir()
+            base.mkdir(parents=True, exist_ok=True)
+            out_path = base / f"voiceout_{uuid.uuid4().hex[:10]}.wav"
+            with wave.open(str(out_path), "wb") as wav_file:
+                voice.synthesize_wav(text, wav_file)
+            return str(out_path), warning
+        except ImportError:
+            return None, "piper-tts not installed; VoiceOut skipped."
+        except Exception as exc:  # noqa: BLE001
+            return None, f"VoiceOut failed: {exc}"
+
+
+def get_tts_backend(preset_key: str | None = None) -> TtsBackend:
+    config = get_echo_coach_config()
+    preset = config.get_tts(preset_key)
+    if preset.key not in _tts_cache:
+        _tts_cache[preset.key] = PiperTtsBackend(preset)
+    return _tts_cache[preset.key]

libs/echocoach/src/echocoach/utils.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+
+def extract_json(text: str) -> dict[str, Any]:
+    """Parse JSON from an LLM response (fenced blocks or trailing prose)."""
+    cleaned = text.strip()
+    fence = re.search(r"```(?:json)?\s*(.*?)\s*```", cleaned, re.DOTALL | re.IGNORECASE)
+    if fence:
+        cleaned = fence.group(1).strip()
+
+    start = cleaned.find("{")
+    if start < 0:
+        return json.loads(cleaned)
+
+    end = _matching_brace_end(cleaned, start)
+    if end is not None:
+        return json.loads(cleaned[start : end + 1])
+
+    fallback_end = cleaned.rfind("}")
+    if fallback_end > start:
+        return json.loads(cleaned[start : fallback_end + 1])
+    return json.loads(cleaned)
+
+
+def _matching_brace_end(text: str, start: int) -> int | None:
+    if start >= len(text) or text[start] != "{":
+        return None
+    depth = 0
+    in_string = False
+    escape = False
+    for index in range(start, len(text)):
+        char = text[index]
+        if escape:
+            escape = False
+            continue
+        if char == "\\" and in_string:
+            escape = True
+            continue
+        if char == '"':
+            in_string = not in_string
+            continue
+        if in_string:
+            continue
+        if char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                return index
+    return None

libs/echocoach/tests/make_fixture.py

@@ -0,0 +1,19 @@
+"""Generate a short silent WAV fixture for smoke tests."""
+
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+
+OUT = Path(__file__).resolve().parent / "fixtures" / "silence_2s.wav"
+
+
+def main() -> None:
+    OUT.parent.mkdir(parents=True, exist_ok=True)
+    audio = np.zeros(32_000, dtype=np.float32)  # 2s @ 16kHz
+    sf.write(OUT, audio, 16_000)
+    print(f"Wrote {OUT}")
+
+
+if __name__ == "__main__":
+    main()

libs/echocoach/tests/test_coach_parse.py

@@ -0,0 +1,18 @@
+from echocoach.coach import parse_coach_response
+
+
+def test_parse_coach_json_from_fenced_block():
+    raw = """Here is feedback:
+```json
+{
+  "summary": "Good energy.",
+  "filler_feedback": "Reduce um.",
+  "pace_feedback": "Slow down.",
+  "rewrite": "We should start now.",
+  "one_tip": "Pause after each point."
+}
+```
+"""
+    feedback = parse_coach_response(raw)
+    assert feedback.summary == "Good energy."
+    assert feedback.one_tip == "Pause after each point."

libs/echocoach/tests/test_fillers.py

@@ -0,0 +1,17 @@
+from echocoach.analysis.fillers import analyze_fillers, highlight_fillers_html
+
+
+def test_detects_common_fillers():
+    text = "So um I think like you know we should basically start."
+    analysis = analyze_fillers(text)
+    assert analysis.total >= 4
+    assert "um" in analysis.counts
+    assert "like" in analysis.counts
+
+
+def test_highlight_wraps_fillers():
+    text = "Um hello there."
+    analysis = analyze_fillers(text)
+    html = highlight_fillers_html(text, analysis)
+    assert "<mark" in html
+    assert "Um" in html or "um" in html.lower()

libs/echocoach/tests/test_pace.py

@@ -0,0 +1,18 @@
+from echocoach.analysis.pace import analyze_pace
+
+
+def test_ideal_pace_scores_high():
+    # 150 words in 60s => 150 WPM
+    text = " ".join(["word"] * 150)
+    pace = analyze_pace(text, 60.0)
+    assert pace.wpm == 150.0
+    assert pace.score == 100
+    assert pace.label == "Ideal pace"
+
+
+def test_slow_pace_penalized():
+    text = " ".join(["word"] * 50)
+    pace = analyze_pace(text, 60.0)
+    assert pace.wpm == 50.0
+    assert pace.score < 100
+    assert "slow" in pace.label.lower()

libs/echocoach/tests/test_recording.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from echocoach.recording import (
+    ServerRecordingError,
+    recording_level_warning,
+    select_capture_backend,
+    start_server_recording,
+    stop_server_recording,
+)
+
+
+class _FakeProcess:
+    def __init__(self, out_path: Path) -> None:
+        self._running = True
+        self.returncode: int | None = None
+        self.stderr = None
+        self._out_path = out_path
+
+    def poll(self) -> int | None:
+        return None if self._running else self.returncode
+
+    def send_signal(self, sig: int) -> None:
+        self._running = False
+        self.returncode = 1  # pw-record exits 1 on SIGINT
+        self._out_path.write_bytes(b"RIFF" + b"x" * 100)
+
+    def wait(self, timeout: float | None = None) -> int:
+        return 0
+
+
+def test_select_capture_backend_prefers_pw_record(monkeypatch):
+    monkeypatch.setattr("echocoach.recording._pw_record_available", lambda: True)
+    monkeypatch.setattr("echocoach.recording._sounddevice_available", lambda: True)
+    monkeypatch.setattr("echocoach.recording._arecord_available", lambda: True)
+    assert select_capture_backend() == "pw-record"
+
+
+class _FakeTimer:
+    def __init__(self, *_args, **_kwargs) -> None:
+        self.daemon = False
+
+    def start(self) -> None:
+        return None
+
+    def cancel(self) -> None:
+        return None
+
+
+def test_start_stop_session(monkeypatch, tmp_path):
+    import echocoach.recording as rec
+
+    rec._session = None
+
+    def fake_spawn(backend, path: Path):
+        return _FakeProcess(path)
+
+    monkeypatch.setattr("echocoach.recording.select_capture_backend", lambda: "pw-record")
+    monkeypatch.setattr("echocoach.recording.outputs_dir", lambda: tmp_path)
+    monkeypatch.setattr("echocoach.recording._spawn_capture_process", fake_spawn)
+    monkeypatch.setattr("echocoach.recording.threading.Timer", _FakeTimer)
+
+    start_server_recording(10)
+    path = stop_server_recording()
+    assert path.is_file()
+    rec._session = None
+
+
+def test_start_while_recording_raises(monkeypatch, tmp_path):
+    import echocoach.recording as rec
+
+    rec._session = None
+
+    def fake_spawn(backend, path: Path):
+        return _FakeProcess(path)
+
+    monkeypatch.setattr("echocoach.recording.select_capture_backend", lambda: "pw-record")
+    monkeypatch.setattr("echocoach.recording.outputs_dir", lambda: tmp_path)
+    monkeypatch.setattr("echocoach.recording._spawn_capture_process", fake_spawn)
+    monkeypatch.setattr("echocoach.recording.threading.Timer", _FakeTimer)
+
+    start_server_recording(10)
+    with pytest.raises(ServerRecordingError, match="Already recording"):
+        start_server_recording(10)
+    stop_server_recording()
+    rec._session = None
+
+
+def test_stop_without_start_raises():
+    import echocoach.recording as rec
+
+    rec._session = None
+    rec._last_recording_path = None
+    with pytest.raises(ServerRecordingError, match="Not recording"):
+        stop_server_recording()
+
+
+def test_recording_level_warning_detects_silence(tmp_path):
+    import numpy as np
+    import soundfile as sf
+
+    silent = tmp_path / "silent.wav"
+    sf.write(silent, np.zeros(16_000, dtype=np.float32), 16_000)
+    assert "silent" in (recording_level_warning(silent) or "").lower()
+
+
+def test_finalize_accepts_pw_record_exit_code_one(tmp_path, monkeypatch):
+    import echocoach.recording as rec
+
+    rec._session = None
+    rec._last_recording_path = None
+
+    out_path = tmp_path / "recordings" / "server_pw.wav"
+    out_path.parent.mkdir(parents=True)
+    fake_proc = _FakeProcess(out_path)
+
+    session = rec._RecordingSession(
+        process=fake_proc,
+        out_path=out_path,
+        backend="pw-record",
+        max_seconds=10,
+        started_at=0.0,
+        watchdog=None,
+    )
+    rec._session = session
+    path = rec.stop_server_recording()
+    assert path == out_path
+    assert path.stat().st_size > 44
+    rec._session = None

pyproject.toml

@@ -6,6 +6,7 @@ readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "agent",
+    "echocoach",
     "ensemble",
     "gradio-space",
     "inference",
@@ -44,6 +45,7 @@ members = [
 
 [tool.uv.sources]
 agent = { workspace = true }
+echocoach = { workspace = true }
 ensemble = { workspace = true }
 gradio-space = { workspace = true }
 inference = { workspace = true }

scripts/echo_coach_smoke.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Smoke test for EchoCoach analysis (no GPU / no ASR models).
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+FIXTURE="libs/echocoach/tests/fixtures/silence_2s.wav"
+if [[ ! -f "$FIXTURE" ]]; then
+  uv run python libs/echocoach/tests/make_fixture.py
+fi
+
+uv run pytest libs/echocoach/tests/test_fillers.py libs/echocoach/tests/test_pace.py libs/echocoach/tests/test_coach_parse.py -q
+echo "EchoCoach smoke tests passed."

voice_models.yaml

@@ -0,0 +1,75 @@
+# Voice model presets for EchoCoach (ASR + TTS).
+# Override defaults via ECHOCOACH_ASR_PRESET / ECHOCOACH_TTS_PRESET in .env
+
+defaults:
+  asr_preset: whisper-cpp-tiny
+  tts_preset: piper-multilingual
+  coach_model: minicpm5-1b
+  max_seconds: 30
+
+languages:
+  - code: en
+    label: English
+  - code: fr
+    label: French
+  - code: de
+    label: German
+  - code: es
+    label: Spanish
+  - code: it
+    label: Italian
+  - code: pt
+    label: Portuguese
+  - code: nl
+    label: Dutch
+  - code: pl
+    label: Polish
+  - code: el
+    label: Greek
+  - code: ar
+    label: Arabic
+  - code: ja
+    label: Japanese
+  - code: zh
+    label: Chinese (Mandarin)
+  - code: vi
+    label: Vietnamese
+  - code: ko
+    label: Korean
+
+asr:
+  cohere-transcribe:
+    label: Cohere Transcribe 2B (14 languages)
+    backend: cohere
+    model_id: CohereLabs/cohere-transcribe-03-2026
+
+  whisper-cpp-tiny:
+    label: Whisper.cpp tiny (CPU, fast)
+    backend: whisper_cpp
+    model_size: tiny
+
+  whisper-cpp-base:
+    label: Whisper.cpp base (CPU, better WER)
+    backend: whisper_cpp
+    model_size: base
+
+tts:
+  piper-multilingual:
+    label: Piper TTS (local VoiceOut)
+    backend: piper
+    voices:
+      en: en_US-lessac-medium
+      fr: fr_FR-siwis-medium
+      de: de_DE-thorsten-medium
+      es: es_ES-sharvard-medium
+      it: it_IT-riccardo-medium
+      pt: pt_BR-faber-medium
+      nl: nl_NL-mls-medium
+      pl: pl_PL-darkman-medium
+      el: en_US-lessac-medium
+      ar: ar_JO-kareem-medium
+      ja: ja_JP-natsuki-medium
+      zh: zh_CN-huayan-medium
+      vi: vi_VN-25hours-single
+      ko: ko_KR-kss-medium
+    fallback_voice: en_US-lessac-medium