refactor: runtime config, Q&A flow module, storage paths, and cleanup

- runtime_config.py: centralized storage paths (supports HF persistent storage)
- qa_flow.py: testable Q&A logic with dedup (claim_audio_submission)
- tts.py: pregeneration progress tracking (get_pregeneration_status)
- app.py: use runtime_config paths, show pregen status on book select,
remove flash-attn runtime install, fix profile stories count
- README.md: updated for LFM Q&A architecture
- .gitignore: add audio_cache/
- requirements.txt: updated deps

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.gitignore

@@ -1,3 +1,4 @@
 __pycache__/
 sample_sounds/
 Voice_Profile/
+audio_cache/

README.md

@@ -11,7 +11,7 @@ pinned: false
 
 # MomsVoice
 
-**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.**
+**A parent records their voice. A bedtime story plays in that voice. The child can ask questions and hear low-latency spoken answers from a local audio model.**
 
 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.
 
@@ -24,7 +24,7 @@ Built for the Hugging Face Hackathon. Runs entirely on local models inside a Gra
                                                        ↓
                                     ❓ Child taps Ask → Story pauses, mic auto-starts
                                                        ↓
-                                    Child asks a question → Answer auto-plays in narrator's voice
+                                    Child asks a question → Answer auto-plays from the Q&A audio model
                                                        ↓
                                               ↩️ Resume → Story continues from where it paused
 ```
@@ -35,8 +35,8 @@ Built for the Hugging Face Hackathon. Runs entirely on local models inside a Gra
 |---|---|---|
 | **Clone** | Parent records or uploads 15–30s of audio. Speaker embedding is extracted and cached. | Qwen3-TTS-1.7B Base |
 | **Listen** | Story plays in the cloned voice as interruptible sentence chunks. Falls back to CustomVoice 0.6B stock voice (speaker "vivian") if no clone. | Qwen3-TTS-1.7B / CustomVoice 0.6B |
-| **Ask** | Child taps Ask → narration pauses, microphone auto-starts. When recording stops, question is transcribed and answer auto-generates. | Whisper-small (ASR) |
-| **Answer** | A short grounded answer is generated from the full story context and spoken in the narrator's voice. Auto-plays immediately. | Qwen2.5-3B-Instruct + Qwen3-TTS |
+| **Ask** | Child taps Ask → narration pauses, microphone auto-starts. When recording stops, the question is sent directly to the Q&A audio model. | LFM2.5-Audio-1.5B |
+| **Answer** | A short grounded answer is generated from the story context and spoken by the low-latency Q&A audio model. It does not use the cloned narrator voice. | LFM2.5-Audio-1.5B |
 | **Resume** | Story continues from where it left off. Play also pauses on tab switch. | Cached chunks |
 
 ## Models
@@ -45,10 +45,9 @@ Built for the Hugging Face Hackathon. Runs entirely on local models inside a Gra
 |---|---|---|
 | [Qwen3-TTS-1.7B-Base](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-Base) | Zero-shot voice cloning + TTS | 1.7B params |
 | [Qwen3-TTS-0.6B-CustomVoice](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice) | Fast stock-voice TTS (predefined speakers) | 0.6B params |
-| [Qwen2.5-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct) | Story Q&A (context-grounded answers) | 3B params |
-| [Whisper-small](https://huggingface.co/openai/whisper-small) | Child speech-to-text | 244M params |
+| [LiquidAI/LFM2.5-Audio-1.5B](https://huggingface.co/LiquidAI/LFM2.5-Audio-1.5B) | End-to-end story Q&A with audio input and spoken audio output | 1.5B params |
 
-All models are preloaded at startup for fast response times.
+The stock narration model and LFM Q&A model are preloaded at startup for fast response times. The 1.7B cloning model is loaded when cloning or cloned narration is needed.
 
 ## Tech Stack
 
@@ -57,6 +56,7 @@ All models are preloaded at startup for fast response times.
 - **Stories:** 10 public domain `.txt` files (downloaded and cleaned from Project Gutenberg)
 - **Storage:** In-memory session cache + disk-persisted voice profiles (`Voice_Profile/`)
 - **TTS Backends:** Qwen3-TTS Base (cloned voice) + CustomVoice 0.6B (stock fallback)
+- **Q&A Backend:** LFM2.5-Audio for direct audio-in/audio-out answers with lower interaction latency
 
 ## Features
 
@@ -84,8 +84,10 @@ python app.py
 ├── app.py                  # Main Gradio app (UI + all event wiring)
 ├── voice_clone.py          # Qwen3-TTS voice cloning + profile persistence
 ├── tts.py                  # Unified TTS interface (Base cloned + CustomVoice stock)
-├── inference.py            # ASR (Whisper-small) + Q&A (Qwen2.5-3B-Instruct)
-├── requirements.txt        # Python deps (gradio, qwen-tts, transformers, torch)
+├── inference_lfm.py        # LFM2.5-Audio Q&A (audio/text input → text/audio output)
+├── inference.py            # Legacy Whisper + Qwen text Q&A path
+├── requirements.txt        # Python deps for the active LFM + Qwen app
+├── requirements_lfm.txt    # Legacy copy of the LFM requirements
 ├── stories/                # 10 cleaned public domain story texts (TTS-ready)
 ├── story_downloader/       # Story acquisition & cleaning pipeline
 │   ├── gutenberg_downloader.py  # Reusable Project Gutenberg downloader/parser
@@ -120,11 +122,12 @@ All stories are public domain from [Project Gutenberg](https://www.gutenberg.org
 
 ## Key Design Decisions
 
-- **All local inference** — voice, Q&A, and ASR run on the Space GPU. No external APIs.
+- **All local inference** — narration, voice cloning, and Q&A run on the Space GPU. No external APIs.
 - **Interruptible chunked streaming** — sentences synthesized and played one at a time for fast start and clean pause/resume.
-- **Voice-first Q&A** — microphone auto-starts on Ask; answer auto-plays when ready. No manual button clicks needed.
-- **Full story context** — Q&A uses the entire story (or top-5 relevant paragraphs for long stories) plus current position for grounded answers.
+- **Voice-first Q&A** — microphone auto-starts on Ask; LFM generates text and spoken audio in one low-latency path. No manual button clicks needed.
+- **Grounded Q&A** — LFM receives the selected story context so answers stay tied to the current story.
 - **Smart pause** — playback pauses on Ask, tab switch, or Pause button. Resume continues from exact position.
+- **Mounted runtime storage** — generated audio, narration cache, and voice profiles are written under `MOMSVOICE_STORAGE_DIR` / `SPACE_STORAGE_DIR`, or `/data/momsvoice` when a Hugging Face bucket is mounted at `/data`.
 - **Privacy-first** — no audio leaves the server, no user accounts, no external database.
 
 ## Privacy

app.py

@@ -1,11 +1,3 @@
-import subprocess, sys
-
-# Install FlashAttention-2 at runtime (needs CUDA, can't compile during Docker build)
-subprocess.run(
-    [sys.executable, "-m", "pip", "install", "flash-attn", "--no-build-isolation", "-q"],
-    capture_output=True,
-)
-
 import os
 import html
 import math
@@ -16,14 +8,18 @@ import gradio as gr
 import time
 from pathlib import Path
 
-from tts import split_into_chunks, generate_audio_stream, pregenerate_story_audio
+from tts import (
+    generate_audio_stream,
+    get_pregeneration_status,
+    pregenerate_story_audio,
+    split_into_chunks,
+)
 from inference import transcribe_audio, answer_story_question
-from inference_lfm import answer_question_audio, SAMPLE_RATE as LFM_SR
+from inference_lfm import answer_question_audio
+from qa_flow import build_qa_response, claim_audio_submission
+from runtime_config import SAMPLE_SOUNDS_DIR, gradio_allowed_paths
 from voice_clone import load_default_profile, list_saved_profiles
 
-# Create directories for sample audio files
-os.makedirs("sample_sounds", exist_ok=True)
-
 # Generate relaxing audio chime waveforms procedurally
 # This runs fully client/server-side with standard Python, eliminating mock limits or Torch wait times
 def generate_chimes_wav(filename, duration=120, melody_type="lullaby"):
@@ -68,8 +64,8 @@ def generate_chimes_wav(filename, duration=120, melody_type="lullaby"):
             wav_file.writeframes(packed_val)
 
 # Generate a short placeholder chime for the preview widget's initial value
-_preview_chime_path = "sample_sounds/cloned_preview.wav"
-if not os.path.exists(_preview_chime_path):
+_preview_chime_path = SAMPLE_SOUNDS_DIR / "cloned_preview.wav"
+if not _preview_chime_path.exists():
     generate_chimes_wav(_preview_chime_path, duration=15, melody_type="lullaby")
 
 COVERS_DIR = Path(__file__).parent / "assets" / "covers"
@@ -554,10 +550,10 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
                             elem_id="qa_audio_input",
                         )
                         question_text = gr.Textbox(visible=False)
-                        submit_question_btn = gr.Button("🔍 Get Answer in Narrator's Voice", variant="primary", elem_id="qa_submit_btn")
+                        submit_question_btn = gr.Button("🔍 Get Answer", variant="primary", elem_id="qa_submit_btn")
 
                     answer_display = gr.HTML(visible=False)
-                    answer_audio = gr.Audio(label="Answer in Narrator's Voice", interactive=False, visible=False, autoplay=True)
+                    answer_audio = gr.Audio(label="Answer Audio", interactive=False, visible=False, autoplay=True)
 
         # TAB 3: Clone Voice Studio
         with gr.TabItem("🎙️ Clone Voice Studio") as clone_tab:
@@ -597,7 +593,7 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
                     """)
 
                     voice_cloning_success_panel = gr.HTML(visible=False)
-                    voice_sample_preview_widget = gr.Audio(value="sample_sounds/cloned_preview.wav", visible=False, label="Pre-listening synthesized vocal pitch weights match preview", interactive=False)
+                    voice_sample_preview_widget = gr.Audio(value=str(_preview_chime_path), visible=False, label="Pre-listening synthesized vocal pitch weights match preview", interactive=False)
                     add_to_library_btn = gr.Button("✨ Synced successfully! Bind Companion Voice to Inventory", visible=False)
 
             gr.HTML("""
@@ -627,7 +623,7 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
                         <div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 8px; text-align: center;">
                             <div style="background: white; border: 1px solid #ebdccb; border-radius: 12px; padding: 10px;">
                                 <span style="font-size: 18px; display: block;">📚</span>
-                                <strong style="font-size: 15px; display: block; color: #1c1c19;">5</strong>
+                                <strong style="font-size: 15px; display: block; color: #1c1c19;">10</strong>
                                 <span style="font-size: 9px; text-transform: uppercase; color: #6f6257;">Stories</span>
                             </div>
                             <div style="background: white; border: 1px solid #ebdccb; border-radius: 12px; padding: 10px;">
@@ -702,10 +698,19 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
         total = max(len(paras) - 1, 0)
         tts_chunks = split_into_chunks("\n\n".join(paras))
         
-        # Pre-generate all audio in background for instant playback (#1 + #11)
+        # Pre-generate all audio in background for faster playback.
         pregenerate_story_audio(tts_chunks, voice_profile_id=profile_id)
-        
-        chunk_html = f"""<div style="margin-top: 8px; font-size: 10px; color: #64748b; font-family: monospace; text-align: center;">{len(tts_chunks)} chunks ready — tap Play</div>"""
+
+        pregen = get_pregeneration_status(tts_chunks, voice_profile_id=profile_id)
+        warmed = int(pregen["cached"])
+        total_chunks = int(pregen["total"])
+        if pregen["complete"]:
+            chunk_text = f"{warmed} / {total_chunks} chunks cached — ready"
+            chunk_color = "#4ade80"
+        else:
+            chunk_text = f"Warming audio: {warmed} / {total_chunks} chunks cached — tap Play anytime"
+            chunk_color = "#f59e0b"
+        chunk_html = f"""<div style="margin-top: 8px; font-size: 10px; color: {chunk_color}; font-family: monospace; text-align: center;">{chunk_text}</div>"""
         status_html = """
             <div style="margin-top: 12px; display: flex; align-items: center; gap: 10px; justify-content: center;">
                 <span style="width: 8px; height: 8px; border-radius: 50%; background: #94a3b8; display: inline-block;"></span>
@@ -781,8 +786,8 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
         progress(0.7, desc="Generating voice preview...")
         try:
             preview_wav, preview_sr = synthesize_cloned_preview(profile_id)
-            preview_path = f"sample_sounds/clone_preview_{profile_id}.wav"
-            sf.write(preview_path, preview_wav, preview_sr)
+            preview_path = SAMPLE_SOUNDS_DIR / f"clone_preview_{profile_id}.wav"
+            sf.write(str(preview_path), preview_wav, preview_sr)
         except Exception as e:
             import logging
             logging.getLogger(__name__).exception("Preview synthesis failed")
@@ -813,7 +818,7 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
         return (
             gr.HTML(visible=False),
             gr.HTML(value=cloned_card_html, visible=True),
-            gr.Audio(value=preview_path, visible=preview_path is not None),
+            gr.Audio(value=str(preview_path) if preview_path else None, visible=preview_path is not None),
             gr.Button(visible=True),
             profile_id,
         )
@@ -1008,22 +1013,6 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
         inputs=[],
         outputs=[player_status_bar, play_btn, pause_btn, ask_btn, resume_btn, qa_panel, qa_input_group, answer_display, answer_audio],
         cancels=[play_event],
-        js="""() => {
-            // Auto-start microphone recording after a brief delay for UI to render
-            setTimeout(() => {
-                const recordBtn = document.querySelector('#qa_audio_input button[aria-label="Record"], #qa_audio_input button.record-button, .qa-audio-group button[aria-label="Record"]');
-                if (recordBtn) { recordBtn.click(); }
-                else {
-                    // Fallback: find any record button inside the audio component
-                    const btns = document.querySelectorAll('button');
-                    for (const b of btns) {
-                        if (b.getAttribute('aria-label') === 'Record' || b.textContent.includes('Record')) {
-                            b.click(); break;
-                        }
-                    }
-                }
-            }, 500);
-        }"""
     )
 
     # 9. Submit question — LFM2.5-Audio end-to-end (single model: audio-in → audio+text-out)
@@ -1031,7 +1020,19 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
         q_txt = (question_txt or "").strip()
         has_audio = question_audio_path is not None and question_audio_path != ""
 
-        if not q_txt and not has_audio:
+        if has_audio and not claim_audio_submission(question_audio_path):
+            return gr.update(), gr.update()
+
+        result = build_qa_response(
+            question_text=q_txt,
+            question_audio_path=question_audio_path if has_audio else None,
+            paragraphs=paragraphs,
+            output_dir=SAMPLE_SOUNDS_DIR,
+            answer_fn=answer_question_audio,
+            max_new_tokens=100,
+        )
+
+        if not result["ok"]:
             answer_html = """
                 <div style="padding: 10px; background: #fef2f2; border: 1px solid #fecaca; border-radius: 10px; font-size: 12px; color: #991b1b;">
                     Please type a question or record one with the microphone.
@@ -1039,42 +1040,9 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
             """
             return gr.HTML(value=answer_html, visible=True), gr.Audio(visible=False)
 
-        # Build story context from paragraphs
-        story_context = "\n\n".join(paragraphs) if paragraphs else ""
-
-        # Use LFM2.5-Audio end-to-end: accepts audio/text → produces text+audio answer
-        import uuid
-        import soundfile as sf
-        import logging as _log
-
-        try:
-            answer_text, waveform, sr = answer_question_audio(
-                question_audio_path=question_audio_path if has_audio else None,
-                question_text=q_txt if q_txt and not has_audio else None,
-                story_context=story_context,
-                max_new_tokens=100,
-            )
-            if not answer_text:
-                answer_text = "Hmm, I'm not sure about that! Let's keep listening to find out."
-        except Exception as e:
-            answer_text = f"Oops, I couldn't think of an answer right now. Let's keep reading! ({type(e).__name__})"
-            waveform = None
-            sr = LFM_SR
-            _log.getLogger(__name__).exception("LFM Q&A failed: %s", e)
-
-        # Save audio if LFM produced it
-        answer_audio_path_out = None
-        if waveform is not None:
-            answer_audio_path_out = f"sample_sounds/qa_answer_{uuid.uuid4().hex[:8]}.wav"
-            sf.write(answer_audio_path_out, waveform, sr)
-
-        # Display question text (transcribe if needed for display only)
-        display_question = q_txt
-        if not display_question and has_audio:
-            display_question = "(audio question)"
-
-        safe_answer = html.escape(answer_text)
-        safe_question = html.escape(display_question)
+        answer_audio_path_out = result["audio_path"]
+        safe_answer = html.escape(str(result["answer_text"]))
+        safe_question = html.escape(str(result["display_question"]))
         answer_html = f"""
             <div style="margin-top: 12px; padding: 16px; background: rgba(240,253,244,0.1); border: 1px solid rgba(187,247,208,0.3); border-radius: 14px;">
                 <div style="font-size: 10px; font-weight: 700; text-transform: uppercase; color: #4ade80; margin-bottom: 6px;">Answer (LFM2.5-Audio)</div>
@@ -1087,7 +1055,7 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
             </div>
         """
         if answer_audio_path_out:
-            return gr.HTML(value=answer_html, visible=True), gr.Audio(value=answer_audio_path_out, visible=True)
+            return gr.HTML(value=answer_html, visible=True), gr.Audio(value=str(answer_audio_path_out), visible=True)
         return gr.HTML(value=answer_html, visible=True), gr.Audio(visible=False)
 
     submit_question_btn.click(
@@ -1096,23 +1064,8 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
         outputs=[answer_display, answer_audio]
     )
 
-    # Auto-submit when voice recording completes
-    # In Gradio 5.35, .stop_recording may not pass audio value reliably.
-    # Use .stop_recording with a small delay via JS to click the submit button.
-    question_audio.stop_recording(
-        fn=None,
-        inputs=None,
-        outputs=None,
-        js="""() => {
-            // Wait for audio value to be committed, then click submit
-            setTimeout(() => {
-                const btn = document.querySelector('#qa_submit_btn button, #qa_submit_btn');
-                if (btn) btn.click();
-            }, 500);
-        }"""
-    )
-
-    # .change() as primary Python handler — fires after audio value is committed
+    # Auto-submit when voice recording completes. .change() fires after the
+    # recorded audio file path is committed, avoiding duplicate submit events.
     def auto_submit_on_audio(audio_path, question_txt, paragraphs, slider_val, profile_id):
         """Auto-submit when a recording is available."""
         if not audio_path:
@@ -1177,4 +1130,4 @@ with gr.Blocks(title="MomsVoice", css=css_code) as demo:
     )
 
 if __name__ == "__main__":
-    demo.queue().launch(allowed_paths=[str(Path(__file__).parent / "assets")])
+    demo.queue(max_size=8).launch(allowed_paths=gradio_allowed_paths())

inference_lfm.py

@@ -8,6 +8,8 @@ import logging
 import torch
 import numpy as np
 
+from runtime_config import GPU_INFERENCE_LOCK
+
 logger = logging.getLogger(__name__)
 
 _processor = None
@@ -78,16 +80,17 @@ def answer_question_audio(
     text_out = []
     audio_out = []
 
-    for t in model.generate_interleaved(
-        **chat,
-        max_new_tokens=max_new_tokens,
-        audio_temperature=1.0,
-        audio_top_k=4,
-    ):
-        if t.numel() == 1:
-            text_out.append(t)
-        else:
-            audio_out.append(t)
+    with GPU_INFERENCE_LOCK, torch.inference_mode():
+        for t in model.generate_interleaved(
+            **chat,
+            max_new_tokens=max_new_tokens,
+            audio_temperature=1.0,
+            audio_top_k=4,
+        ):
+            if t.numel() == 1:
+                text_out.append(t)
+            else:
+                audio_out.append(t)
 
     # Decode text
     answer_text = ""
@@ -98,7 +101,8 @@ def answer_question_audio(
     waveform = None
     if audio_out and len(audio_out) > 1:
         audio_codes = torch.stack(audio_out[:-1], 1).unsqueeze(0)
-        waveform_tensor = processor.decode(audio_codes)
+        with GPU_INFERENCE_LOCK, torch.inference_mode():
+            waveform_tensor = processor.decode(audio_codes)
         waveform = waveform_tensor.cpu().numpy().squeeze()
 
     return answer_text, waveform, SAMPLE_RATE

mission.md

@@ -2,7 +2,7 @@
 
 ## Product Vision
 
-**ReadBookMom** — a parent records a short voice sample, then a bedtime story and story Q&A are spoken back in that parent's cloned voice. The demo runs on local models inside a Gradio app on Hugging Face Spaces.
+**ReadBookMom** — a parent records a short voice sample, then a bedtime story is narrated in that parent's cloned voice. Story Q&A uses a local audio model for fast spoken answers. The demo runs on local models inside a Gradio app on Hugging Face Spaces.
 
 ## Problem
 
@@ -15,14 +15,14 @@ Parent records 15s of voice → Pick a story → Story starts in parent's voice
                                     ↓
                     Child taps Ask mid-story → Narration pauses
                                     ↓
-                  Child asks a question → Hears answer in parent's voice
+                  Child asks a question → Hears a fast spoken answer
                                     ↓
               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. 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.
+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 with low delay, then resume without losing the story position. The Q&A answer voice is intentionally generated by the local audio Q&A model rather than the cloned narrator voice. 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.
 
@@ -31,7 +31,7 @@ Latency and natural interruption are part of the demo promise: the story should
 Ship a working Hugging Face Space that demonstrates:
 1. **Voice cloning** — parent uploads/records a short audio clip, Qwen3-TTS extracts speaker embedding
 2. **Interruptible story narration** — Qwen3-TTS streams sentence-sized chunks in the cloned voice (Supertonic fallback for stock voice)
-3. **Voice Q&A during narration** — child taps Ask, narration pauses, Qwen2.5-3B-Instruct answers from the story context, then Qwen3-TTS speaks the answer in the cloned voice
+3. **Voice Q&A during narration** — child taps Ask, narration pauses, LFM2.5-Audio answers from the story context, then speaks the answer directly for lower latency
 
 ## Target Demo User
 
@@ -60,7 +60,7 @@ A parent at a laptop who records their voice, picks a short story, and shows the
 - Play story narrated in cloned voice with interruptible chunked streaming
 - Pause narration through an Ask button, preserve the current story chunk, answer, then resume
 - Cache generated narration per voice session and story
-- Ask a question about the story, receive a grounded 1–2 sentence Qwen2.5-3B-Instruct answer, and hear it in the cloned voice
+- Ask a question about the story, receive a grounded 1–2 sentence LFM2.5-Audio answer, and hear it as low-latency generated speech
 - Clean, child-friendly UI (Google Stitch-inspired via gr.Server)
 
 **Out of scope:**
@@ -74,7 +74,7 @@ A parent at a laptop who records their voice, picks a short story, and shows the
 
 | Constraint | Implementation |
 |---|---|
-| Content grounding | Qwen2.5-3B-Instruct receives the selected story text plus a strict answer-from-story instruction |
+| Content grounding | LFM2.5-Audio receives the selected story text plus a strict answer-from-story instruction |
 | Voice privacy | All inference local on HF Space GPU — no audio leaves the server |
 | Child safety | Pre-curated stories only; no user-uploaded content |
 
@@ -86,17 +86,17 @@ A parent at a laptop who records their voice, picks a short story, and shows the
 | Story narration | Use interruptible chunked streaming: generate the first paragraph chunk, play it immediately, then continue generating queued chunks. |
 | Interruption | Add an Ask state that pauses playback, cancels or deprioritizes queued narration generation, and stores the current chunk index. |
 | 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. |
+| Q&A context | Send the current story position plus the most relevant story passages to LFM2.5-Audio instead of the full story when possible. |
+| Q&A length | Cap answers to 1–2 short child-friendly sentences to reduce spoken-answer latency. |
 | 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. |
+| Voice question input | Use LFM2.5-Audio directly for audio questions; text questions bypass audio input. |
 
 ## Design Review Notes
 
 | Topic | Critique | Upgrade |
 |---|---|---|
-| Privacy | An external LLM API would weaken the privacy story even if audio stayed local. | Use Qwen2.5-3B-Instruct for local story Q&A so the demo has one clear privacy narrative. |
-| Latency | A 3B-class Q&A model is a better fit for the demo loop than an 8B-class model, but TTS and interruption responsiveness remain the user-visible bottlenecks. | Cache voice setup, stream chunked narration, make playback cancellable, cap Q&A output, and use 4-bit or 8-bit loading on T4. |
+| Privacy | An external LLM API would weaken the privacy story even if audio stayed local. | Use local LFM2.5-Audio for story Q&A so the demo has one clear privacy narrative. |
+| Latency | The cloned narrator voice is valuable for story playback, but forcing every Q&A answer through cloned TTS adds delay to the live interaction loop. | Use LFM2.5-Audio for direct audio-in/audio-out answers, cache voice setup, stream chunked narration, make playback cancellable, and cap Q&A output. |
 | Demo clarity | Voice cloning, narration, ASR, and Q&A can feel like too many moving parts. | Present the loop as three simple actions: record, listen, ask. |
 

qa_flow.py

@@ -0,0 +1,119 @@
+"""Server-side Q&A flow helpers for the Gradio Ask interaction."""
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Callable, Iterable, Protocol
+
+logger = logging.getLogger(__name__)
+DEFAULT_SAMPLE_RATE = 24000
+
+_RECENT_AUDIO_LOCK = threading.Lock()
+_RECENT_AUDIO_SUBMISSIONS: dict[str, float] = {}
+_DUPLICATE_WINDOW_SEC = 30.0
+
+
+class AudioWriter(Protocol):
+    def __call__(self, path: Path, waveform, sample_rate: int) -> None:
+        ...
+
+
+def _normalize_audio_path(audio_path: str | Path | None) -> str:
+    if not audio_path:
+        return ""
+    try:
+        path = Path(audio_path).resolve()
+        stat = path.stat()
+        return f"{path}:{stat.st_size}:{stat.st_mtime_ns}"
+    except OSError:
+        return str(audio_path)
+
+
+def claim_audio_submission(audio_path: str | Path | None) -> bool:
+    """Return False when the same recorded audio was already claimed recently."""
+    normalized = _normalize_audio_path(audio_path)
+    if not normalized:
+        return True
+
+    now = time.monotonic()
+    cutoff = now - _DUPLICATE_WINDOW_SEC
+    with _RECENT_AUDIO_LOCK:
+        stale = [
+            key for key, seen_at in _RECENT_AUDIO_SUBMISSIONS.items()
+            if seen_at < cutoff
+        ]
+        for key in stale:
+            _RECENT_AUDIO_SUBMISSIONS.pop(key, None)
+
+        if normalized in _RECENT_AUDIO_SUBMISSIONS:
+            return False
+
+        _RECENT_AUDIO_SUBMISSIONS[normalized] = now
+        return True
+
+
+def _default_audio_writer(path: Path, waveform, sample_rate: int) -> None:
+    import soundfile as sf
+
+    sf.write(str(path), waveform, sample_rate)
+
+
+def build_qa_response(
+    *,
+    question_text: str | None,
+    question_audio_path: str | Path | None,
+    paragraphs: Iterable[str] | None,
+    output_dir: Path,
+    answer_fn: Callable[..., tuple[str, object | None, int]],
+    audio_writer: AudioWriter = _default_audio_writer,
+    max_new_tokens: int = 100,
+) -> dict[str, object]:
+    """Run Q&A and return display-ready data without importing Gradio."""
+    q_txt = (question_text or "").strip()
+    audio_path = str(question_audio_path) if question_audio_path else None
+    has_audio = bool(audio_path)
+
+    if not q_txt and not has_audio:
+        return {
+            "ok": False,
+            "answer_text": "Please type a question or record one with the microphone.",
+            "display_question": "",
+            "audio_path": None,
+            "error": None,
+        }
+
+    story_context = "\n\n".join(paragraphs or [])
+    try:
+        answer_text, waveform, sr = answer_fn(
+            question_audio_path=audio_path if has_audio else None,
+            question_text=q_txt if q_txt and not has_audio else None,
+            story_context=story_context,
+            max_new_tokens=max_new_tokens,
+        )
+        if not answer_text:
+            answer_text = "Hmm, I'm not sure about that! Let's keep listening to find out."
+    except Exception as exc:
+        logger.exception("LFM Q&A failed: %s", exc)
+        answer_text = (
+            "Oops, I couldn't think of an answer right now. Let's keep reading! "
+            f"({type(exc).__name__})"
+        )
+        waveform = None
+        sr = DEFAULT_SAMPLE_RATE
+
+    answer_audio_path = None
+    if waveform is not None:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        answer_audio_path = output_dir / f"qa_answer_{uuid.uuid4().hex[:8]}.wav"
+        audio_writer(answer_audio_path, waveform, sr)
+
+    return {
+        "ok": True,
+        "answer_text": answer_text,
+        "display_question": q_txt or "(audio question)",
+        "audio_path": answer_audio_path,
+        "error": None,
+    }

requirements.txt

@@ -7,10 +7,12 @@ soundfile
 numpy
 librosa
 
+# LFM2.5-Audio end-to-end Q&A model
+liquid-audio
+
 # Qwen3-TTS (voice cloning + stock voice)
 qwen-tts>=0.1.1
 huggingface-hub>=0.23.0
 
-# FlashAttention-2 — install separately on GPU machines:
-#   pip install flash-attn --no-build-isolation
-# Falls back to SDPA (PyTorch native) if not available.
+# FlashAttention-2 is intentionally not installed at runtime on Spaces.
+# The app falls back to SDPA unless a Docker/prebuilt image provides flash-attn.

runtime_config.py

@@ -0,0 +1,66 @@
+"""Runtime paths and shared execution controls for the Space."""
+import os
+import tempfile
+import threading
+import warnings
+from pathlib import Path
+
+
+APP_ROOT = Path(__file__).resolve().parent
+
+
+def _usable_root(path: Path, *, warn: bool = False) -> Path | None:
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        probe = path / ".write_probe"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink(missing_ok=True)
+        return path
+    except OSError as exc:
+        if warn:
+            warnings.warn(f"Runtime storage path is not writable: {path} ({exc})")
+        return None
+
+
+def _select_storage_root() -> Path:
+    configured = (
+        os.environ.get("MOMSVOICE_STORAGE_DIR")
+        or os.environ.get("SPACE_STORAGE_DIR")
+    )
+    candidates: list[tuple[Path, bool]] = []
+    if configured:
+        candidates.append((Path(configured).expanduser(), True))
+    candidates.extend([
+        (Path("/data") / "momsvoice", False),
+        (APP_ROOT, True),
+        (Path(tempfile.gettempdir()) / "momsvoice", True),
+    ])
+
+    for candidate, warn in candidates:
+        usable = _usable_root(candidate, warn=warn)
+        if usable is not None:
+            return usable
+
+    raise RuntimeError("No writable runtime storage path is available.")
+
+
+STORAGE_ROOT = _select_storage_root()
+
+VOICE_PROFILE_DIR = STORAGE_ROOT / "Voice_Profile"
+AUDIO_CACHE_DIR = STORAGE_ROOT / "audio_cache"
+SAMPLE_SOUNDS_DIR = STORAGE_ROOT / "sample_sounds"
+
+for _path in (VOICE_PROFILE_DIR, AUDIO_CACHE_DIR, SAMPLE_SOUNDS_DIR):
+    _path.mkdir(parents=True, exist_ok=True)
+
+
+# Serializes GPU-heavy model calls across Gradio events and background pregen
+# threads. This keeps the Space responsive under hackathon demo traffic.
+GPU_INFERENCE_LOCK = threading.RLock()
+
+
+def gradio_allowed_paths() -> list[str]:
+    return [
+        str(APP_ROOT / "assets"),
+        str(SAMPLE_SOUNDS_DIR),
+    ]

test_modules/test_qa_flow.py

@@ -0,0 +1,85 @@
+"""Dependency-light tests for the Ask/Q&A server flow."""
+import tempfile
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from qa_flow import build_qa_response, claim_audio_submission
+
+
+def check(label, condition):
+    if not condition:
+        raise AssertionError(label)
+    print(f"[OK] {label}")
+
+
+def fake_answer_fn(**kwargs):
+    check("story context forwarded", "Three Little Pigs" in kwargs["story_context"])
+    check("max_new_tokens forwarded", kwargs["max_new_tokens"] == 12)
+    if kwargs["question_audio_path"]:
+        return "The wolf huffed and puffed.", object(), 24000
+    return "The pig built a house.", None, 24000
+
+
+def fake_writer(path: Path, waveform, sample_rate: int):
+    check("audio writer receives sample rate", sample_rate == 24000)
+    path.write_bytes(b"RIFF fake wav")
+
+
+def test_empty_question():
+    result = build_qa_response(
+        question_text="",
+        question_audio_path=None,
+        paragraphs=[],
+        output_dir=Path(tempfile.gettempdir()),
+        answer_fn=fake_answer_fn,
+    )
+    check("empty question is rejected", result["ok"] is False)
+    check("empty question has no audio", result["audio_path"] is None)
+
+
+def test_text_question():
+    result = build_qa_response(
+        question_text="What did the pig build?",
+        question_audio_path=None,
+        paragraphs=["The Three Little Pigs built houses."],
+        output_dir=Path(tempfile.gettempdir()),
+        answer_fn=fake_answer_fn,
+        max_new_tokens=12,
+    )
+    check("text question succeeds", result["ok"] is True)
+    check("text answer returned", result["answer_text"] == "The pig built a house.")
+    check("text question does not write audio when model returns none", result["audio_path"] is None)
+
+
+def test_audio_question_writes_answer():
+    with tempfile.TemporaryDirectory() as tmp:
+        result = build_qa_response(
+            question_text="",
+            question_audio_path=Path(tmp) / "question.wav",
+            paragraphs=["The Three Little Pigs met a wolf."],
+            output_dir=Path(tmp),
+            answer_fn=fake_answer_fn,
+            audio_writer=fake_writer,
+            max_new_tokens=12,
+        )
+        check("audio question succeeds", result["ok"] is True)
+        check("audio question display fallback", result["display_question"] == "(audio question)")
+        check("audio answer path created", result["audio_path"] is not None)
+        check("audio answer file exists", Path(result["audio_path"]).exists())
+
+
+def test_duplicate_audio_claim():
+    with tempfile.TemporaryDirectory() as tmp:
+        audio = Path(tmp) / "same-question.wav"
+        check("first audio claim accepted", claim_audio_submission(audio) is True)
+        check("duplicate audio claim rejected", claim_audio_submission(audio) is False)
+
+
+if __name__ == "__main__":
+    test_empty_question()
+    test_text_question()
+    test_audio_question_writes_answer()
+    test_duplicate_audio_claim()
+    print("Q&A flow tests passed")

tts.py

@@ -26,6 +26,8 @@ import threading
 import numpy as np
 import soundfile as sf
 
+from runtime_config import AUDIO_CACHE_DIR
+
 logger = logging.getLogger(__name__)
 
 _SENTENCE_RE = re.compile(r'(?<=[.!?;])\s+')
@@ -36,7 +38,7 @@ _SENTINEL = object()
 _MAX_CHUNK_CHARS = 120
 
 # Audio cache directory
-_CACHE_DIR = "audio_cache"
+_CACHE_DIR = str(AUDIO_CACHE_DIR)
 os.makedirs(_CACHE_DIR, exist_ok=True)
 
 # Transition chime (soft sine fade, 0.3s at 24kHz)
@@ -49,6 +51,7 @@ _TRANSITION_CHIME = 0.08 * np.sin(2 * np.pi * 440 * _chime_t) * np.linspace(1, 0
 _pregen_lock = threading.Lock()
 _pregen_cache: dict[str, list[tuple[int, np.ndarray]]] = {}  # key -> [(sr, wav), ...]
 _pregen_in_progress: set[str] = set()
+_pregen_progress: dict[str, dict[str, int | bool]] = {}
 
 
 def _cache_key(text: str, voice_profile_id: str | None) -> str:
@@ -57,6 +60,44 @@ def _cache_key(text: str, voice_profile_id: str | None) -> str:
     return hashlib.md5(raw.encode()).hexdigest()
 
 
+def _story_key(chunks: list[str], voice_profile_id: str | None) -> str:
+    return _cache_key("\n".join(chunks), voice_profile_id)
+
+
+def get_pregeneration_status(
+    chunks: list[str],
+    voice_profile_id: str | None = None,
+) -> dict[str, int | bool]:
+    """Return how much of a story is actually cached or warmed."""
+    total = len(chunks)
+    if total == 0:
+        return {"cached": 0, "total": 0, "in_progress": False, "complete": False}
+
+    story_key = _story_key(chunks, voice_profile_id)
+    with _pregen_lock:
+        if story_key in _pregen_cache:
+            return {
+                "cached": len(_pregen_cache[story_key]),
+                "total": total,
+                "in_progress": False,
+                "complete": True,
+            }
+        progress = _pregen_progress.get(story_key)
+        if progress is not None:
+            return dict(progress)
+
+    cached = sum(
+        1 for chunk in chunks
+        if _get_cached_audio(chunk, voice_profile_id) is not None
+    )
+    return {
+        "cached": cached,
+        "total": total,
+        "in_progress": False,
+        "complete": cached == total,
+    }
+
+
 def _get_cached_audio(chunk_text: str, voice_profile_id: str | None) -> np.ndarray | None:
     """Check if audio for this chunk is already cached on disk."""
     key = _cache_key(chunk_text, voice_profile_id)
@@ -118,12 +159,18 @@ def pregenerate_story_audio(chunks: list[str], voice_profile_id: str | None = No
     
     Call this on book selection to pre-warm the cache. Non-blocking.
     """
-    story_key = _cache_key("\n".join(chunks), voice_profile_id)
+    story_key = _story_key(chunks, voice_profile_id)
     
     with _pregen_lock:
         if story_key in _pregen_in_progress or story_key in _pregen_cache:
             return  # Already running or done
         _pregen_in_progress.add(story_key)
+        _pregen_progress[story_key] = {
+            "cached": 0,
+            "total": len(chunks),
+            "in_progress": True,
+            "complete": False,
+        }
 
     def _worker():
         results = []
@@ -133,6 +180,8 @@ def pregenerate_story_audio(chunks: list[str], voice_profile_id: str | None = No
             cached = _get_cached_audio(chunk, voice_profile_id)
             if cached is not None:
                 results.append((sr, cached))
+                with _pregen_lock:
+                    _pregen_progress[story_key]["cached"] = len(results)
                 continue
             # Synthesize
             try:
@@ -143,9 +192,17 @@ def pregenerate_story_audio(chunks: list[str], voice_profile_id: str | None = No
             except Exception as e:
                 logger.warning("Pre-gen failed on chunk %d: %s", i, e)
                 results.append((sr, np.zeros(0, dtype=np.float32)))
+            with _pregen_lock:
+                _pregen_progress[story_key]["cached"] = len(results)
         
         with _pregen_lock:
             _pregen_cache[story_key] = results
+            _pregen_progress[story_key] = {
+                "cached": len(results),
+                "total": len(chunks),
+                "in_progress": False,
+                "complete": True,
+            }
             _pregen_in_progress.discard(story_key)
         logger.info("Pre-generation complete: %d chunks cached.", len(chunks))
 
@@ -186,7 +243,7 @@ def generate_audio_stream(
     sample_rate = 24000
 
     # Check if pre-generated cache is available
-    story_key = _cache_key("\n".join(chunks), voice_profile_id)
+    story_key = _story_key(chunks, voice_profile_id)
     pregen_results = None
     with _pregen_lock:
         if story_key in _pregen_cache:

voice_clone.py

@@ -34,6 +34,8 @@ import numpy as np
 import soundfile as sf
 import torch
 
+from runtime_config import GPU_INFERENCE_LOCK, VOICE_PROFILE_DIR
+
 logger = logging.getLogger(__name__)
 
 # ---------------------------------------------------------------------------
@@ -69,7 +71,6 @@ REF_AUDIO_TARGET_SR = 24000
 # ---------------------------------------------------------------------------
 # Voice profile persistence
 # ---------------------------------------------------------------------------
-VOICE_PROFILE_DIR = Path(__file__).parent / "Voice_Profile"
 VOICE_PROFILE_DIR.mkdir(exist_ok=True)
 
 # Default profile ID — used when no cloned voice exists
@@ -346,10 +347,11 @@ def create_voice_profile(ref_audio_path: str, voice_name: str = "Cloned Voice")
     model = get_qwen_tts()
 
     logger.info("Creating voice profile from %s...", ref_audio_path)
-    prompt_items = model.create_voice_clone_prompt(
-        ref_audio=trimmed_path,
-        x_vector_only_mode=True,
-    )
+    with GPU_INFERENCE_LOCK:
+        prompt_items = model.create_voice_clone_prompt(
+            ref_audio=trimmed_path,
+            x_vector_only_mode=True,
+        )
 
     profile_id = uuid.uuid4().hex[:12]
     with _cache_lock:
@@ -382,13 +384,14 @@ def synthesize_cloned(text: str, profile_id: str) -> tuple[np.ndarray, int]:
 
     model = get_qwen_tts()
 
-    audio_list, sample_rate = model.generate_voice_clone(
-        text=text,
-        language="english",
-        voice_clone_prompt=prompt_items,
-        non_streaming_mode=False,
-        **GENERATION_PARAMS,
-    )
+    with GPU_INFERENCE_LOCK:
+        audio_list, sample_rate = model.generate_voice_clone(
+            text=text,
+            language="english",
+            voice_clone_prompt=prompt_items,
+            non_streaming_mode=False,
+            **GENERATION_PARAMS,
+        )
 
     wav = np.concatenate(audio_list) if audio_list else np.zeros(0, dtype=np.float32)
     return wav, sample_rate
@@ -404,13 +407,14 @@ def synthesize_custom_voice_streaming(
     """
     model = get_custom_voice_model()
 
-    audio_list, sample_rate = model.generate_custom_voice(
-        text=text,
-        speaker=speaker,
-        language=language,
-        non_streaming_mode=False,
-        **GENERATION_PARAMS,
-    )
+    with GPU_INFERENCE_LOCK:
+        audio_list, sample_rate = model.generate_custom_voice(
+            text=text,
+            speaker=speaker,
+            language=language,
+            non_streaming_mode=False,
+            **GENERATION_PARAMS,
+        )
 
     # Yield each segment as it was generated
     for segment in audio_list:
@@ -428,13 +432,14 @@ def synthesize_custom_voice(
     """
     model = get_custom_voice_model()
 
-    audio_list, sample_rate = model.generate_custom_voice(
-        text=text,
-        speaker=speaker,
-        language=language,
-        non_streaming_mode=False,
-        **GENERATION_PARAMS,
-    )
+    with GPU_INFERENCE_LOCK:
+        audio_list, sample_rate = model.generate_custom_voice(
+            text=text,
+            speaker=speaker,
+            language=language,
+            non_streaming_mode=False,
+            **GENERATION_PARAMS,
+        )
 
     wav = np.concatenate(audio_list) if audio_list else np.zeros(0, dtype=np.float32)
     return wav, sample_rate