Apply design critique fixes + add README

mission.md:
- Make voice similarity testable (blind A/B test)
- Acknowledge 8s Q&A as compromise, add pre-generated Q&A target
- Add repeat-question and story-end behavior to demo loop
- Note demo time budget (3min allows ~2 Q&A rounds)

sprint.md:
- Fix underestimated tasks: #5 (30m->1h), #10 (1h->2h)
- Add pre-generated Q&A task (10a)
- Add latency measurement (20a) and state machine validation (20b)
- Add Day 1 overflow plan
- Add future_mobile doc to file structure

tech_stack.md:
- Add legal state transition rules
- Add VRAM budget table (~5-6GB of 16GB T4)
- Add concurrency model note
- Specify TF-IDF retrieval for Q&A
- Add audio format spec (24kHz, 16-bit, mono)

future_mobile_app_considerations.md:
- Add filler audio strategy for cache miss resume
- Clarify REST limitation for interrupt loop
- Add app size estimates (20MB thin to 4GB+ on-device)
- Add explicit offline fallback decision

README.md:
- New repo README with demo flow, models, tech stack, quick start

README.md

@@ -0,0 +1,82 @@
+# ReadBookMom
+
+**A parent records their voice. A bedtime story plays in that voice. The child can ask questions and hear answers — all in mom or dad's voice.**
+
+Built for the Hugging Face Hackathon. Runs entirely on local models inside a Gradio app on Hugging Face Spaces — no external APIs, no data leaves the server.
+
+## Demo
+
+```
+🎤 Record 15s of your voice → 📖 Pick a story → ▶️ Story plays in your voice
+                                                       ↓
+                                    ❓ Child taps Ask → Story pauses
+                                                       ↓
+                                    Child asks a question → Hears answer in your voice
+                                                       ↓
+                                              ▶️ Story resumes
+```
+
+## How It Works
+
+| Step | What Happens | Model |
+|---|---|---|
+| **Clone** | Parent records or uploads 15–30s of audio. Voice representation is computed and cached. | QWEN-TTS-0.6B |
+| **Listen** | Story plays in the cloned voice as interruptible paragraph chunks. | QWEN-TTS-0.6B |
+| **Ask** | Child taps Ask, narration pauses, child types or speaks a question. | Whisper-small (ASR, on-demand) |
+| **Answer** | A short grounded answer is generated from the story context and spoken in the cloned voice. | Qwen2.5-3B-Instruct + QWEN-TTS-0.6B |
+| **Resume** | Story continues from where it left off. | Cached chunks |
+
+## Models
+
+| Model | Role | Size |
+|---|---|---|
+| [QWEN-TTS-0.6B](https://huggingface.co/Qwen/Qwen-TTS-0.6B) | Voice cloning + TTS | 0.6B params |
+| [Qwen2.5-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct) | Story Q&A | 3B params (4-bit on T4) |
+| [Whisper-small](https://huggingface.co/openai/whisper-small) | Child speech-to-text | 244M params (loaded on demand) |
+
+## Tech Stack
+
+- **UI:** Gradio 5.x + gr.Server (custom CSS/JS for Google Stitch-inspired design)
+- **Runtime:** Single `app.py` process on HF Spaces (T4 or A10G GPU)
+- **Stories:** 3–5 public domain `.txt` files
+- **Storage:** In-memory session cache (no database)
+
+## Quick Start (Local Dev)
+
+```bash
+git clone https://github.com/MomsVoiceAI/HuggingFace_Hack.git
+cd HuggingFace_Hack
+pip install gradio transformers torch accelerate bitsandbytes soundfile numpy
+python app.py
+# → http://localhost:7860
+```
+
+## Project Structure
+
+```
+├── app.py                  # Main Gradio app
+├── requirements.txt        # Python deps
+├── stories/                # Public domain story texts
+├── static/                 # Custom CSS/JS for Stitch-style UI
+├── assets/covers/          # Story cover images
+├── mission.md              # Product vision
+├── sprint.md               # 2-day hackathon sprint plan
+├── tech_stack.md            # Technical architecture
+└── future_mobile_app_considerations.md  # Mobile deployment guidance
+```
+
+## Key Design Decisions
+
+- **All local inference** — voice, Q&A, and ASR run on the Space GPU. No external APIs.
+- **Interruptible chunked streaming** — paragraphs synthesized and played one at a time for fast start and clean pause/resume.
+- **Pre-generated Q&A** — anticipated questions are generated in the background during narration for sub-1s response on cache hits.
+- **Button-based interruption** — tap Ask to pause. No always-listening mic (privacy + complexity).
+- **Privacy-first** — no audio leaves the server, no user accounts, no database.
+
+## Privacy
+
+All inference runs on the Hugging Face Space GPU. Voice samples, story text, and generated audio stay on the server runtime and are not persisted after the session ends. No external APIs are called.
+
+## License
+
+Hackathon project. Stories are public domain.

future_mobile_app_considerations.md

@@ -42,7 +42,7 @@ Button-based interruption is the recommended first version. True voice barge-in,
 |---|---|---|
 | Mobile app | Recording, playback, Ask interruption, local state, local cache | Native iOS/Android app or React Native/Flutter with native audio modules. |
 | Backend API | Voice profile session, story chunk generation, Q&A answer generation, answer TTS | GPU backend using the same model stack as the Space demo. |
-| Streaming/control channel | Request chunks, pause/resume, cancel queued work, receive generation status | WebSocket for bidirectional control; REST plus polling is acceptable for a prototype. |
+| Streaming/control channel | Request chunks, pause/resume, cancel queued work, receive generation status | WebSocket for bidirectional control; REST plus polling is acceptable for narration-only prototyping but will not support the full interrupt/answer/resume loop reliably. |
 | Audio delivery | Stream or download generated chunks | Prefer short chunk files with signed URLs and local prefetch cache. |
 | Session state | Track story and interruption position | Store `story_id`, `voice_session_id`, `current_chunk_index`, playback state, and cache keys. |
 
@@ -101,7 +101,7 @@ The phone runs ASR, Q&A, voice cloning TTS, chunk generation, and playback local
 | Q&A text answer | 1-3 seconds | Use short prompts, 1-2 sentence answers, and backend Qwen2.5-3B-Instruct. |
 | Spoken Q&A answer | Starts in 4-8 seconds after question submit | Keep answer text short and generate TTS server-side. |
 | Story resume | Under 1 second when next chunk is cached | Resume from saved chunk position; fetch missing chunks in the background. |
-| Cache miss resume | 2-5 seconds | Show a lightweight loading state while the next chunk is generated or downloaded. |
+| Cache miss resume | 2-5 seconds | Show a lightweight loading state while the next chunk is generated or downloaded. Play a short filler clip (“Hmm, let me find my place…”) pre-synthesized in the cloned voice during voice setup, so the child hears the parent’s voice instead of silence. |
 
 Mobile latency depends heavily on network quality. The app should show resilient playback states instead of assuming the backend will always meet desktop demo timing.
 
@@ -115,6 +115,7 @@ Mobile latency depends heavily on network quality. The app should show resilient
 | Echo cancellation | Open-mic interruption can capture the story audio instead of the child. | Use tap-to-Ask first; research VAD and echo cancellation later. |
 | App lifecycle | Incoming calls, lock screen, and backgrounding can interrupt playback. | Treat v1 as foreground-first; persist playback state and chunk cache. |
 | Storage | Cached voice/story audio can grow quickly. | Cache by voice session, story ID, chunk index, and model version with TTL cleanup. |
+| App size | A thin cloud-backed client is ~20 MB. A hybrid app with on-device ASR (Whisper-tiny) may reach 100–200 MB. A fully on-device build with all models could exceed 4 GB. | Start thin; gate on-device model downloads behind user opt-in. |
 | Privacy | Family voice data and child questions are sensitive. | Make upload, retention, deletion, and cache behavior explicit. |
 
 ## Product Implications
@@ -122,7 +123,7 @@ Mobile latency depends heavily on network quality. The app should show resilient
 - The first mobile app should be a hybrid app, not a full local AI runtime.
 - The phone should own playback state and interruption responsiveness.
 - Privacy messaging must be explicit: explain what audio is sent to the backend, how long it is retained, and whether generated voice samples are cached.
-- If offline mode becomes a requirement, treat it as a separate research milestone, not a launch feature.
+- If offline mode becomes a requirement, treat it as a separate research milestone, not a launch feature. As a conscious tradeoff, v1 has no offline fallback — even a cached-story-only offline mode would add significant complexity.
 - Device qualification matters. Fully on-device AI should start with a short list of supported flagship phones.
 - Chunk prefetching and caching are key to making bedtime story playback and resume feel instant.
 - Always-listening barge-in should not be promised until echo cancellation, VAD, and mobile privacy UX are proven.

mission.md

@@ -17,10 +17,14 @@ Parent records 15s of voice → Pick a story → Story starts in parent's voice
                                     ↓
                   Child asks a question → Hears answer in parent's voice
                                     ↓
-                         Resume story from the same position
+              Resume story from the same position (or ask another question)
+                                    ↓
+                      Story finishes → Show "Pick another story" prompt
 ```
 
-Latency and natural interruption are part of the demo promise: the story should start quickly, pause cleanly when the child wants to ask something, answer in the cloned voice, then resume without losing the story position.
+Latency and natural interruption are part of the demo promise: the story should start quickly, pause cleanly when the child wants to ask something, answer in the cloned voice, then resume without losing the story position. The child may ask multiple questions in a row before resuming. When the last chunk finishes playing, the app returns to the story selection screen.
+
+**Demo time budget:** A 3-minute live walkthrough allows ~2 Q&A rounds (each round ≈ 15s of dead air: pause + ask + wait + answer + resume). Plan the demo script around 1–2 questions placed at natural story moments.
 
 ## Hackathon Goal (2 days)
 
@@ -37,11 +41,12 @@ A parent at a laptop who records their voice, picks a short story, and shows the
 
 | Criteria | Target |
 |---|---|
-| Voice clone from ≤ 30s audio | Recognizable similarity |
+| Voice clone from ≤ 30s audio | 2 of 3 listeners identify the voice in a blind A/B test |
 | Story start latency | First streamed audio chunk in ≤ 5s |
 | Narration interruption | Ask tap pauses playback in ≤ 500ms and preserves story position |
 | Cached story replay | Starts immediately after first generation |
-| Q&A answer (spoken) | Spoken answer starts in ≤ 8s from question submit |
+| Q&A answer (spoken, live) | Spoken answer starts in ≤ 8s from question submit (known compromise — a young child may lose attention) |
+| Q&A answer (spoken, pre-generated) | Sub-1s for anticipated questions matched from background Q&A cache |
 | Story resume latency | Resume from paused position in ≤ 1s when next chunk is cached |
 | Works on HF Spaces | Public link, no local setup needed |
 | Demo length | 3-minute live walkthrough |
@@ -83,6 +88,7 @@ A parent at a laptop who records their voice, picks a short story, and shows the
 | Story replay | Cache full generated narration by voice session and story ID. |
 | Q&A context | Send the current story position plus the most relevant story passages to Qwen2.5-3B-Instruct instead of the full story when possible. |
 | Q&A length | Cap answers to 1–2 short child-friendly sentences before sending to TTS. |
+| Pre-generated Q&A | While each chunk plays, generate 2–3 anticipated Q&A pairs with audio in the background. Match incoming questions against the cache for sub-1s responses; fall back to live generation on miss. |
 | Story resume | Resume from the paused chunk after the spoken answer; use cached next chunks when available. |
 | Voice question input | Load ASR only when audio questions are used; text questions bypass ASR. |
 

sprint.md

@@ -15,7 +15,7 @@ Ship a public Hugging Face Space: parent clones voice → story streams in that
 | 2 | Load QWEN-TTS-0.6B locally, test basic TTS (text → audio) | 1h | ☐ |
 | 3 | Implement voice cloning and cache voice representation after recording | 1.5h | ☐ |
 | 4 | Add 3 short stories as `.txt` files (public domain) | 30m | ☐ |
-| 5 | Wire up: pick story → stream first narration chunk, track chunk index, cache story audio | 30m | ☐ |
+| 5 | Wire up: pick story → stream first narration chunk, track chunk index, cache story audio | 1h | ☐ |
 
 **Checkpoint:** Can generate a story audio file in a cloned voice from CLI.
 
@@ -27,10 +27,13 @@ Ship a public Hugging Face Space: parent clones voice → story streams in that
 | 7 | Tab 1 (Clone): `gr.Audio` record/upload + preview button | 45m | ☐ |
 | 8 | Tab 2 (Listen): story dropdown + play/pause/resume controls for streamed chunks | 45m | ☐ |
 | 9 | Add on-demand ASR for child voice input; use lighter ASR fallback if needed | 30m | ☐ |
-| 10 | Tab 3 (Ask): interrupt narration → short grounded Qwen answer → TTS → resume story | 1h | ☐ |
+| 10 | Tab 3 (Ask): interrupt narration → short grounded Qwen answer → TTS → resume story | 2h | ☐ |
+| 10a | Pre-generate 2–3 anticipated Q&A pairs per chunk during narration playback (background task) | 30m | ☐ |
 
 **Checkpoint:** Full loop works locally — clone → listen → interrupt → ask → resume. Ugly but functional.
 
+**Day 1 Overflow Plan:** If the afternoon runs past 8h, cut Task 9 (on-demand ASR) and rely on text-only questions. CSS polish (Tasks 12–14) is the next cut candidate on Day 2.
+
 ---
 
 ## Day 2: Polish + Deploy (Make It Demo-Ready)
@@ -56,6 +59,8 @@ Ship a public Hugging Face Space: parent clones voice → story streams in that
 | 18 | Confirm no external LLM API secrets are required; set `HF_TOKEN` only if gated models require it | 5m | ☐ |
 | 19 | End-to-end test on live Space (clone → listen → interrupt → ask → resume) | 30m | ☐ |
 | 20 | Fix latency issues: preload weights, cache voice/story audio, cap Q&A tokens, validate pause/resume | 45m | ☐ |
+| 20a | Measure and log all latency targets from mission.md (first chunk, pause, Q&A, resume, replay) | 30m | ☐ |
+| 20b | Validate playback state machine: test all 6 states and legal transitions from tech_stack.md | 30m | ☐ |
 | 21 | Add error handling: graceful failures, loading messages | 30m | ☐ |
 | 22 | Record backup demo video (in case live demo fails) | 30m | ☐ |
 | 23 | Write README.md for the Space (screenshot, description) | 15m | ☐ |
@@ -99,7 +104,8 @@ VoiceClone/
 │   └── covers/            # Story cover images
 ├── mission.md             # Product vision (this hackathon)
 ├── tech_stack.md          # Technical decisions
-└── sprint.md              # This file
+├── sprint.md              # This file
+└── future_mobile_app_considerations.md  # Mobile deployment guidance
 ```
 
 ---

tech_stack.md

@@ -20,6 +20,18 @@ Single Python file Gradio app. Everything runs in one process on a GPU-enabled H
 
 No database. No external storage. No external LLM API. Stories are flat files. Audio is generated as interruptible chunks, then cached in the session for replay and resume.
 
+**VRAM Budget (T4 — 16 GB):**
+
+| Component | Estimated VRAM | Notes |
+|---|---|---|
+| QWEN-TTS-0.6B | ~1.2 GB | Always loaded |
+| Qwen2.5-3B-Instruct (4-bit) | ~2 GB | Always loaded |
+| Whisper-small | ~1 GB | Loaded on demand |
+| Gradio + PyTorch overhead | ~1–2 GB | Runtime |
+| **Total** | **~5–6 GB** | ~10 GB headroom for KV cache and activations |
+
+**Concurrency:** Single-process Gradio serializes concurrent users. The hackathon demo is single-user. For multi-user, consider Gradio queue or separate worker processes.
+
 ---
 
 ## 1. Front-End
@@ -49,7 +61,7 @@ No database. No external storage. No external LLM API. Stories are flat files. A
 | Size | 0.6B params — fits comfortably on T4 (16GB VRAM) |
 | Capability | Zero-shot voice cloning + TTS from text chunks |
 | Input | Reference audio (≥5s) + target text |
-| Output | WAV audio in cloned voice |
+| Output | WAV audio in cloned voice (24 kHz, 16-bit, mono) |
 | Latency | ~3–5s for a paragraph on T4 |
 | Optimization | Cache the voice representation after recording; generate story audio in interruptible paragraph chunks |
 
@@ -73,7 +85,7 @@ No database. No external storage. No external LLM API. Stories are flat files. A
 | Model | `Qwen/Qwen2.5-3B-Instruct` |
 | Why | Strong small-model instruction following with lower latency and VRAM pressure than an 8B-class model |
 | Method | Current story position + relevant story passages + strict answer-from-story instruction + child question → short answer |
-| Retrieval | Simple paragraph keyword overlap is enough for the demo; full-story prompt remains a fallback |
+| Retrieval | TF-IDF cosine similarity between the child's question and each story paragraph; return the top-2 paragraphs as context. Full-story prompt is the fallback when retrieval scores are low. |
 | Output cap | 1–2 child-friendly sentences, typically 40–80 new tokens |
 | Runtime note | Use 4-bit/8-bit loading on T4; use bf16 or 8-bit on A10G for more headroom |
 
@@ -130,6 +142,18 @@ Each file: title on line 1, text below. No metadata DB needed.
 | `resuming` | Answer finished and story playback is restarting. | Resume chunk index, cached next chunk |
 | `finished` | Story narration completed. | Cached full-story audio |
 
+**Legal transitions:**
+
+```
+playing → paused → playing
+playing → asking → answering → resuming → playing
+playing → finished
+paused  → asking  → answering → resuming → playing
+asking  → asking  (child asks a follow-up before answer starts)
+```
+
+All other transitions are illegal. The UI should disable buttons that would trigger an illegal transition.
+
 ---
 
 ## 9. Local Dev