Upload 12 files

app.py

@@ -1,853 +1,426 @@
 """
-PlotWeaver Hausa Voice AI Agent — HuggingFace Spaces Demo
-==========================================================
-Full pipeline: Whisper ASR  →  NLLB translation  →  Dialogue Manager  →  MMS-TTS
-
-Run locally:
-    pip install -r requirements.txt
-    python app.py
+PlotWeaver Hausa Voice AI Agent — HuggingFace Spaces
+======================================================
+Verified against gradio 5.49.1. Key constraints this file respects:
+
+  * Models load LAZILY. The Space must show UI within seconds, not after a
+    3.5GB download. Nothing heavy is imported or loaded at module scope.
+  * CPU-SAFE DEFAULTS. whisper-large-v3 needs ~6GB and takes ~60s per utterance
+    on the 2-vCPU free tier — unusable. Default is whisper-small; large-v3 is
+    one env var away when you attach a GPU.
+  * gr.skip() on stream ticks that produce no audio, otherwise the player
+    restarts on every 0.5s tick and the agent's reply stutters.
+  * Streaming partials OFF by default on CPU: an extra decode every 900ms
+    saturates the box and makes the demo feel worse, not better.
 """
 
-import gradio as gr
-import numpy as np
 import os
-import uuid
-import json
+import sys
+import logging
 from datetime import datetime
 
+import gradio as gr
+import numpy as np
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("app")
+
 from pipeline import HausaVoiceAIPipeline
 from nlu import NLU
 from orchestrator import Orchestrator
-from integrations.crm import CRMClient
 
-# ── Singletons (lazy-loaded inside pipeline) ─────────────────────────────────
-ai_pipeline = HausaVoiceAIPipeline()
-# NLU backend chain: HF Inference API (if HF_TOKEN set) → local LLM → rules
-dm          = Orchestrator(crm=CRMClient(), nlu=NLU())
+# ── Optional integrations (never block startup) ──────────────────────────────
+try:
+    from integrations.crm import CRMClient
+    _crm = CRMClient()
+    INTEGRATIONS_OK = True
+except Exception as e:
+    logger.warning(f"Integrations unavailable ({e}) — demo mode.")
+    _crm, INTEGRATIONS_OK = None, False
 
-# ── Streaming config ─────────────────────────────────────────────────────────
-# Partials cost an extra Whisper decode every ~900ms. On a CPU-only Space that
-# can saturate the box, so allow turning them off via env var.
-SHOW_PARTIALS = os.getenv("SHOW_PARTIALS", "1") == "1"
+# ── Config ───────────────────────────────────────────────────────────────────
+HAS_GPU       = os.getenv("SPACES_GPU", "") or os.getenv("CUDA_VISIBLE_DEVICES", "")
+SHOW_PARTIALS = os.getenv("SHOW_PARTIALS", "0") == "1"   # off by default on CPU
+STREAM_EVERY  = float(os.getenv("STREAM_EVERY", "0.5"))
+
+ai_pipeline = HausaVoiceAIPipeline()
+dm          = Orchestrator(crm=_crm, nlu=NLU())
 
-# ── Demo phrases (for visitors who don't speak Hausa) ────────────────────────
 DEMO_PROMPTS = [
-    ("Compound: balance + transfer",
-     "Duba asusuna sannan ka aika naira dubu talatin da biyar zuwa Amina"),
-    ("Entity prefill: send to Abu",
-     "Ina son aika kuɗi zuwa Abu yanzu"),
-    ("Branch + card (not block!)",
+    ("Compound request (balance + transfer)",
+     "Duba asusuna sannan ka aika 35000 zuwa Amina"),
+    ("Entity prefill — recipient named",
+     "Ina son aika kuɗi zuwa Abu"),
+    ("Branch info, NOT block-card",
      "Ina ne reshenku mafi kusa domin in karɓi katin ATM"),
-    ("Report a problem",        "Ina da matsala"),
-    ("Talk to human agent",     "Ina son magana da mutum"),
+    ("Report a problem", "Ina da matsala da asusuna"),
+    ("Escalate to human", "Ina son magana da mutum"),
 ]
 
-# ── Custom CSS ────────────────────────────────────────────────────────────────
-CSS = """
-@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&family=Syne:wght@700;800&family=JetBrains+Mono:wght@400;500&display=swap');
-
-:root {
-    --amber:   #F59E0B;
-    --ember:   #DC2626;
-    --sand:    #FDE68A;
-    --dark:    #0C0A09;
-    --panel:   #1C1917;
-    --border:  #292524;
-    --text:    #E7E5E4;
-    --muted:   #78716C;
-    --success: #22C55E;
-    --info:    #38BDF8;
-}
-
-body, .gradio-container {
-    background: var(--dark) !important;
-    font-family: 'Space Grotesk', sans-serif !important;
-    color: var(--text) !important;
-}
-
-/* ── Header ── */
-.pw-header {
-    background: linear-gradient(135deg, #1C1917 0%, #292524 50%, #1C1917 100%);
-    border-bottom: 1px solid var(--border);
-    padding: 28px 40px 24px;
-    position: relative;
-    overflow: hidden;
-}
-.pw-header::before {
-    content: '';
-    position: absolute;
-    top: -60px; right: -60px;
-    width: 300px; height: 300px;
-    background: radial-gradient(circle, rgba(245,158,11,0.15) 0%, transparent 70%);
-    pointer-events: none;
-}
-.pw-logo {
-    font-family: 'Syne', sans-serif;
-    font-weight: 800;
-    font-size: 28px;
-    color: var(--amber);
-    letter-spacing: -0.5px;
-    margin: 0;
-}
-.pw-logo span { color: var(--text); }
-.pw-tagline {
-    color: var(--muted);
-    font-size: 13px;
-    margin: 4px 0 0;
-    letter-spacing: 0.5px;
-    text-transform: uppercase;
-}
-
-/* ── Pill badges ── */
-.pill {
-    display: inline-flex;
-    align-items: center;
-    gap: 6px;
-    background: rgba(245,158,11,0.12);
-    border: 1px solid rgba(245,158,11,0.3);
-    color: var(--amber);
-    padding: 4px 12px;
-    border-radius: 100px;
-    font-size: 11px;
-    font-weight: 600;
-    letter-spacing: 0.8px;
-    text-transform: uppercase;
-}
-.pill-green {
-    background: rgba(34,197,94,0.12);
-    border-color: rgba(34,197,94,0.3);
-    color: var(--success);
-}
-.pill-blue {
-    background: rgba(56,189,248,0.12);
-    border-color: rgba(56,189,248,0.3);
-    color: var(--info);
-}
-
-/* ── Panel cards ── */
-.pw-card {
-    background: var(--panel);
-    border: 1px solid var(--border);
-    border-radius: 12px;
-    padding: 20px;
-    margin-bottom: 12px;
-}
-.pw-card-title {
-    font-family: 'Syne', sans-serif;
-    font-size: 13px;
-    font-weight: 700;
-    color: var(--amber);
-    letter-spacing: 1px;
-    text-transform: uppercase;
-    margin-bottom: 14px;
-}
-
-/* ── Conversation bubbles ── */
-.conversation-box {
-    background: var(--panel);
-    border: 1px solid var(--border);
-    border-radius: 12px;
-    padding: 16px;
-    height: 360px;
-    overflow-y: auto;
-    font-family: 'Space Grotesk', sans-serif;
-    scroll-behavior: smooth;
-}
-.bubble {
-    max-width: 85%;
-    padding: 10px 14px;
-    border-radius: 14px;
-    margin-bottom: 10px;
-    line-height: 1.5;
-    font-size: 14px;
-}
-.bubble-user {
-    background: rgba(245,158,11,0.15);
-    border: 1px solid rgba(245,158,11,0.25);
-    margin-left: auto;
-    border-bottom-right-radius: 4px;
-}
-.bubble-agent {
-    background: rgba(255,255,255,0.05);
-    border: 1px solid var(--border);
-    border-bottom-left-radius: 4px;
-}
-.bubble-label {
-    font-size: 10px;
-    font-weight: 600;
-    letter-spacing: 0.8px;
-    text-transform: uppercase;
-    opacity: 0.6;
-    margin-bottom: 4px;
-}
-.bubble-hausa {
-    font-size: 12px;
-    color: var(--amber);
-    margin-top: 4px;
-    font-style: italic;
-}
-.bubble-time {
-    font-size: 10px;
-    color: var(--muted);
-    margin-top: 3px;
-    font-family: 'JetBrains Mono', monospace;
-}
-
-/* ── Pipeline status ── */
-.pipeline-step {
-    display: flex;
-    align-items: center;
-    gap: 10px;
-    padding: 8px 0;
-    border-bottom: 1px solid var(--border);
-    font-size: 13px;
-}
-.pipeline-step:last-child { border-bottom: none; }
-.step-icon {
-    width: 28px; height: 28px;
-    border-radius: 8px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    font-size: 14px;
-    flex-shrink: 0;
-}
-.step-active   { background: rgba(245,158,11,0.2); }
-.step-done     { background: rgba(34,197,94,0.2); }
-.step-idle     { background: rgba(255,255,255,0.05); }
-
-/* ── Gradio overrides ── */
-.gr-button-primary {
-    background: var(--amber) !important;
-    color: var(--dark) !important;
-    font-weight: 700 !important;
-    border: none !important;
-    font-family: 'Space Grotesk', sans-serif !important;
-}
-.gr-button-secondary {
-    background: var(--panel) !important;
-    color: var(--text) !important;
-    border: 1px solid var(--border) !important;
-}
-label, .gr-form > div > label {
-    color: var(--muted) !important;
-    font-size: 12px !important;
-    font-weight: 500 !important;
-    letter-spacing: 0.5px !important;
-    text-transform: uppercase !important;
-}
-.gr-box, .gr-input, textarea, .gr-text-input {
-    background: var(--panel) !important;
-    border-color: var(--border) !important;
-    color: var(--text) !important;
-    border-radius: 8px !important;
-    font-family: 'Space Grotesk', sans-serif !important;
-}
-.tabitem { background: var(--dark) !important; }
-.tab-nav button {
-    background: transparent !important;
-    color: var(--muted) !important;
-    border-bottom: 2px solid transparent !important;
-    font-family: 'Space Grotesk', sans-serif !important;
-    font-weight: 600 !important;
-}
-.tab-nav button.selected {
-    color: var(--amber) !important;
-    border-bottom-color: var(--amber) !important;
-}
-footer { display: none !important; }
-"""
 
-# ── Architecture diagram HTML ─────────────────────────────────────────────────
-ARCH_HTML = """
-<div style="font-family:'Space Grotesk',sans-serif; color:#E7E5E4; padding:16px;">
-<div style="font-family:'Syne',sans-serif; font-size:13px; font-weight:700;
-            color:#F59E0B; letter-spacing:1px; text-transform:uppercase;
-            margin-bottom:20px;">System Architecture</div>
-
-<div style="display:flex; gap:8px; align-items:center; flex-wrap:wrap; margin-bottom:20px;">
-
-  <!-- Input channels -->
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
-              padding:12px 16px; min-width:100px; text-align:center;">
-    <div style="font-size:20px;">🎤</div>
-    <div style="font-size:11px; color:#78716C; margin-top:4px;">MICROPHONE</div>
-    <div style="font-size:10px; color:#22C55E;">Gradio</div>
-  </div>
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
-              padding:12px 16px; min-width:100px; text-align:center;">
-    <div style="font-size:20px;">💬</div>
-    <div style="font-size:11px; color:#78716C; margin-top:4px;">WHATSAPP</div>
-    <div style="font-size:10px; color:#22C55E;">Cloud API</div>
-  </div>
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
-              padding:12px 16px; min-width:100px; text-align:center;">
-    <div style="font-size:20px;">📞</div>
-    <div style="font-size:11px; color:#78716C; margin-top:4px;">PHONE/SIP</div>
-    <div style="font-size:10px; color:#22C55E;">Twilio</div>
-  </div>
-
-  <div style="color:#F59E0B; font-size:20px; margin:0 4px;">→</div>
-
-  <!-- Pipeline -->
-  <div style="display:flex; flex-direction:column; gap:8px;">
-    <div style="background:rgba(220,38,38,0.1);border:1px solid rgba(220,38,38,0.3);
-                border-radius:8px; padding:10px 20px; text-align:center;">
-      <div style="font-size:11px; font-weight:700; color:#F87171;">VAD ENDPOINTING</div>
-      <div style="font-size:10px; color:#78716C;">Silero VAD · preroll · hangover · barge-in</div>
-    </div>
-    <div style="background:rgba(245,158,11,0.1);border:1px solid rgba(245,158,11,0.3);
-                border-radius:8px; padding:10px 20px; text-align:center;">
-      <div style="font-size:11px; font-weight:700; color:#F59E0B;">WHISPER (DUAL)</div>
-      <div style="font-size:10px; color:#78716C;">small → partials · large-v3 → final</div>
-    </div>
-    <div style="background:rgba(56,189,248,0.1);border:1px solid rgba(56,189,248,0.3);
-                border-radius:8px; padding:10px 20px; text-align:center;">
-      <div style="font-size:11px; font-weight:700; color:#38BDF8;">NLLB-200 (600M)</div>
-      <div style="font-size:10px; color:#78716C;">hau_Latn ↔ eng_Latn</div>
-    </div>
-    <div style="background:rgba(168,85,247,0.1);border:1px solid rgba(168,85,247,0.3);
-                border-radius:8px; padding:10px 20px; text-align:center;">
-      <div style="font-size:11px; font-weight:700; color:#A855F7;">DIALOGUE MANAGER</div>
-      <div style="font-size:10px; color:#78716C;">FSM + Intent · Multi-turn</div>
-    </div>
-    <div style="background:rgba(34,197,94,0.1);border:1px solid rgba(34,197,94,0.3);
-                border-radius:8px; padding:10px 20px; text-align:center;">
-      <div style="font-size:11px; font-weight:700; color:#22C55E;">MMS-TTS (HAU)</div>
-      <div style="font-size:10px; color:#78716C;">facebook/mms-tts-hau · VITS</div>
-    </div>
-  </div>
-
-  <div style="color:#F59E0B; font-size:20px; margin:0 4px;">→</div>
-
-  <!-- Integrations -->
-  <div style="display:flex; flex-direction:column; gap:8px;">
-    <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
-                padding:12px 16px; min-width:110px; text-align:center;">
-      <div style="font-size:20px;">🗂️</div>
-      <div style="font-size:11px; color:#78716C; margin-top:4px;">CRM / ZENDESK</div>
-      <div style="font-size:10px; color:#F59E0B;">Auto-tickets</div>
-    </div>
-    <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
-                padding:12px 16px; min-width:110px; text-align:center;">
-      <div style="font-size:20px;">👤</div>
-      <div style="font-size:11px; color:#78716C; margin-top:4px;">HUMAN AGENT</div>
-      <div style="font-size:10px; color:#DC2626;">Fallback</div>
-    </div>
-  </div>
-</div>
-
-<div style="display:flex; gap:20px; flex-wrap:wrap; margin-top:16px; padding-top:16px;
-            border-top:1px solid #292524;">
-  <div><span style="color:#F59E0B; font-weight:700;">Latency target:</span>
-       <span style="color:#78716C;"> ASR&lt;2s · MT&lt;0.5s · TTS&lt;1s · Total&lt;4s</span></div>
-  <div><span style="color:#F59E0B; font-weight:700;">Languages:</span>
-       <span style="color:#78716C;"> Hausa (primary) · English pivot · French (roadmap)</span></div>
-  <div><span style="color:#F59E0B; font-weight:700;">Deployment:</span>
-       <span style="color:#78716C;"> HF Spaces (POC) → Docker / K8s (prod)</span></div>
-</div>
-</div>
-"""
+# ── State ───────────────────────────────────��────────────────────────────────
 
-# ── State helpers ─────────────────────────────────────────────────────────────
+def new_state():
+    return {"conv": dm.new_session(), "history": [], "sasr": None,
+            "partial": "", "warm": False}
 
-def _init_state():
-    return {
-        "conv":    dm.new_session(),
-        "history": [],   # [{role, hausa, english, time}]
-        "sasr":    None, # StreamingASR — created on first streamed chunk
-        "partial": "",   # live (unconfirmed) transcript
-        "metrics": [],   # per-turn latency records
-    }
 
-def _render_conversation(history: list) -> str:
+def render(history):
     if not history:
-        return (
-            '<div style="color:#78716C; text-align:center; margin-top:60px; '
-            'font-size:13px;">🎤 Speak or type in Hausa to begin …</div>'
-        )
-    html = ""
-    for msg in history:
-        role   = msg["role"]
-        is_user = role == "user"
-        label  = "YOU" if is_user  else "AGENT"
-        cls    = "bubble-user" if is_user else "bubble-agent"
-        en     = msg.get("english", "")
-        ha     = msg.get("hausa",   "")
-        t      = msg.get("time",    "")
-        primary = ha if ha else en
-        secondary = en if ha else ""
-
-        html += f"""
-<div style="display:flex; flex-direction:column;
-            align-items:{'flex-end' if is_user else 'flex-start'}; margin-bottom:12px;">
-  <div class="bubble {cls}">
-    <div class="bubble-label">{label}</div>
-    <div>{primary}</div>
-    {'<div class="bubble-hausa">EN: ' + secondary + '</div>' if secondary else ''}
-    <div class="bubble-time">{t}</div>
-  </div>
-</div>"""
-    return html
-
-
-# ── Core processing function ──────────────────────────────────────────────────
-
-def process_voice(audio, text_input, state):
-    """
-    Entry: either audio or text (fallback for demo without mic).
-    Returns: (audio_out, conversation_html, status_text, updated_state)
-    """
-    if state is None:
-        state = _init_state()
-
-    hausa_text = ""
-    asr_status = "—"
-
-    # 1. ASR
-    if audio is not None:
-        sample_rate, audio_array = audio
-        audio_array = audio_array.astype(np.float32) / 32768.0
-        if audio_array.ndim > 1:
-            audio_array = audio_array.mean(axis=1)
-        hausa_text = ai_pipeline.audio_to_hausa_text(audio_array, sample_rate)
-        asr_status = f"✓ {hausa_text[:60]}…" if len(hausa_text) > 60 else f"✓ {hausa_text}"
-    elif text_input and text_input.strip():
-        hausa_text = text_input.strip()
-        asr_status = "(text input)"
-    else:
-        return None, _render_conversation(state["history"]), "⚠ No input provided", state
-
-    audio_out, status = _handle_turn(hausa_text, state)
-    return audio_out, _render_conversation(state["history"]), status, state
-
-
-# ── Shared turn handler (used by both push-to-talk and streaming) ────────────
-
-def _handle_turn(hausa_text: str, state: dict, asr_ms: float = 0.0):
-    """
-    Runs MT → dialogue → MT → TTS for one finalized Hausa utterance.
-    Mutates state['history'] and state['conv']. Returns (audio_out, status).
-    """
-    import time as _time
-    t_mt0 = _time.perf_counter()
-    english_text = ai_pipeline.hausa_to_english(hausa_text)
-    mt_in_ms = (_time.perf_counter() - t_mt0) * 1000
-
-    t_nlu0 = _time.perf_counter()
-    english_response, conv_state, escalate = dm.respond(
-        english_text, hausa_text, state["conv"]
-    )
-    state["conv"] = conv_state
-    nlu_ms = (_time.perf_counter() - t_nlu0) * 1000
-
-    t_mt1 = _time.perf_counter()
-    hausa_response = ai_pipeline.english_to_hausa(english_response)
-    mt_out_ms = (_time.perf_counter() - t_mt1) * 1000
-
-    t_tts = _time.perf_counter()
-    sr, audio_out = ai_pipeline.hausa_text_to_audio(hausa_response)
-    tts_ms = (_time.perf_counter() - t_tts) * 1000
+        return ('<div class="empty">Press <b>Warm up models</b>, then speak or '
+                'tap a demo prompt.</div>')
+    out = []
+    for m in history:
+        me = m["role"] == "user"
+        out.append(
+            f'<div class="row {"r-me" if me else "r-ag"}">'
+            f'<div class="bub {"b-me" if me else "b-ag"}">'
+            f'<div class="lbl">{"YOU" if me else "AGENT"}</div>'
+            f'<div class="ha">{m["hausa"]}</div>'
+            f'<div class="en">{m["english"]}</div>'
+            f'<div class="tm">{m["time"]}</div></div></div>')
+    return "".join(out)
+
+
+# ── Core turn ────────────────────────────────────────────────────────────────
+
+def run_turn(hausa_text, state, asr_ms=0.0):
+    import time
+    t = time.perf_counter()
+    english = ai_pipeline.hausa_to_english(hausa_text)
+    mt_in = (time.perf_counter() - t) * 1000
+
+    t = time.perf_counter()
+    reply_en, conv, escalated = dm.respond(english, hausa_text, state["conv"])
+    state["conv"] = conv
+    nlu_ms = (time.perf_counter() - t) * 1000
+
+    t = time.perf_counter()
+    reply_ha = ai_pipeline.english_to_hausa(reply_en)
+    mt_out = (time.perf_counter() - t) * 1000
+
+    t = time.perf_counter()
+    sr, wav = ai_pipeline.hausa_text_to_audio(reply_ha)
+    tts_ms = (time.perf_counter() - t) * 1000
 
     now = datetime.now().strftime("%H:%M:%S")
-    state["history"].append({"role": "user", "hausa": hausa_text,
-                             "english": english_text, "time": now})
-    state["history"].append({"role": "agent", "hausa": hausa_response,
-                             "english": english_response, "time": now})
-
-    total = asr_ms + mt_in_ms + nlu_ms + mt_out_ms + tts_ms
-    state["metrics"].append({
-        "asr": asr_ms, "mt_in": mt_in_ms, "nlu": nlu_ms,
-        "mt_out": mt_out_ms, "tts": tts_ms, "total": total,
-    })
-
-    open_tasks = [t for t in conv_state.tasks
-                  if t.status in ("pending", "collecting", "confirming")]
-    status = (f"Turn {conv_state.turn} · "
-              f"queue: {len(open_tasks)} open / "
-              f"{sum(1 for t in conv_state.tasks if t.status == 'done')} done")
-    if conv_state.active_task:
-        status += f" · active: {conv_state.active_task.intent}"
-    status += (f"  |  ASR {asr_ms:.0f}ms · MT {mt_in_ms + mt_out_ms:.0f}ms · "
-               f"NLU {nlu_ms:.0f}ms · TTS {tts_ms:.0f}ms · "
-               f"total {total:.0f}ms")
-    if escalate:
-        status += "  ⚠ ESCALATED TO HUMAN"
-
-    return (sr, audio_out), status
-
-
-# ── Streaming handler: VAD endpointing, no button press ──────────────────────
-
-def process_stream(stream_chunk, state):
+    state["history"] += [
+        {"role": "user",  "hausa": hausa_text, "english": english,  "time": now},
+        {"role": "agent", "hausa": reply_ha,   "english": reply_en, "time": now},
+    ]
+
+    total = asr_ms + mt_in + nlu_ms + mt_out + tts_ms
+    openq = [x for x in conv.tasks
+             if x.status in ("pending", "collecting", "confirming")]
+    status = (f"turn {conv.turn} · queue {len(openq)} open / "
+              f"{sum(1 for x in conv.tasks if x.status=='done')} done"
+              f"{' · ' + conv.active_task.intent if conv.active_task else ''}"
+              f"  |  ASR {asr_ms:.0f} · MT {mt_in+mt_out:.0f} · "
+              f"NLU {nlu_ms:.0f} · TTS {tts_ms:.0f} · total {total:.0f} ms")
+    if escalated:
+        status += "   ESCALATED"
+    return (sr, wav), status
+
+
+# ── Handlers ─────────────────────────────────────────────────────────────────
+
+def warm_up(state, progress=gr.Progress()):
+    """Download + load models with visible progress, so the first real
+    utterance isn't a 3-minute silence."""
+    if state is None:
+        state = new_state()
+    try:
+        progress(0.05, desc="Loading ASR …")
+        ai_pipeline._load_asr()
+        progress(0.55, desc="Loading translation …")
+        ai_pipeline._load_nllb()
+        progress(0.85, desc="Loading speech synthesis …")
+        ai_pipeline._load_tts()
+        progress(1.0, desc="Ready")
+        state["warm"] = True
+        gr.Info("Models loaded. You can speak now.")
+        return f"Ready · {ai_pipeline.describe_models()}", state
+    except Exception as e:
+        logger.exception("warm-up failed")
+        gr.Warning(f"Model load failed: {e}")
+        return f"Model load failed: {e}", state
+
+
+def on_text(text, state):
+    if state is None:
+        state = new_state()
+    if not text or not text.strip():
+        return gr.skip(), render(state["history"]), "Type or say something first.", state
+    try:
+        audio, status = run_turn(text.strip(), state)
+        return audio, render(state["history"]), status, state
+    except Exception as e:
+        logger.exception("turn failed")
+        gr.Warning(str(e))
+        return gr.skip(), render(state["history"]), f"Error: {e}", state
+
+
+def on_record(audio, state):
+    """Push-to-talk: one complete recording."""
+    if state is None:
+        state = new_state()
+    if audio is None:
+        return gr.skip(), render(state["history"]), "No audio recorded.", state
+    sr, arr = audio
+    try:
+        import time
+        t = time.perf_counter()
+        hausa = ai_pipeline.transcribe(arr, sr)
+        asr_ms = (time.perf_counter() - t) * 1000
+        if not hausa.strip():
+            return gr.skip(), render(state["history"]), "Didn't catch that.", state
+        out, status = run_turn(hausa, state, asr_ms)
+        return out, render(state["history"]), status, state
+    except Exception as e:
+        logger.exception("record failed")
+        gr.Warning(str(e))
+        return gr.skip(), render(state["history"]), f"Error: {e}", state
+
+
+def on_stream(chunk, state):
     """
-    Bound to gr.Audio(streaming=True).stream — fires every ~0.3s with a new
-    chunk of mic audio. The VAD decides when a turn has ended; no push-to-talk.
+    Live mic. Fires every STREAM_EVERY seconds. VAD decides when the turn ends,
+    so there is no send button.
 
-    Returns: (audio_out, conversation_html, status, live_partial, state)
+    Returns gr.skip() for the audio output on ticks with no reply, otherwise
+    the player restarts on every tick.
     """
     if state is None:
-        state = _init_state()
-    if stream_chunk is None:
-        return (None, _render_conversation(state["history"]),
-                "Listening …", state.get("partial", ""), state)
+        state = new_state()
+    if chunk is None:
+        return gr.skip(), gr.skip(), gr.skip(), state.get("partial", ""), state
 
     if state["sasr"] is None:
         state["sasr"] = ai_pipeline.make_streaming_session(
             emit_partials=SHOW_PARTIALS)
 
-    sr, chunk = stream_chunk
-    events = state["sasr"].accept_audio(chunk, sr)
+    sr, arr = chunk
+    try:
+        events = state["sasr"].accept_audio(arr, sr)
+    except Exception as e:
+        logger.exception("stream failed")
+        return gr.skip(), gr.skip(), f"Stream error: {e}", "", state
 
-    audio_out = None
-    status    = None
+    audio_out, status, convo = gr.skip(), gr.skip(), gr.skip()
 
     for ev in events:
         if ev.kind == "speech_start":
-            status = "🎙  Listening — speech detected …"
-
+            status = "listening — speech detected"
         elif ev.kind == "partial":
             state["partial"] = ev.text
-            status = f"🎙  … ({ev.duration_ms/1000:.1f}s)"
-
+            status = f"listening … {ev.duration_ms/1000:.1f}s"
         elif ev.kind == "bargein":
-            # Caller interrupted the agent: stop playback immediately
             audio_out = None
-            status = "✋  Barge-in — you interrupted, go ahead."
-
+            status = "you interrupted — go ahead"
         elif ev.kind == "discarded":
             state["partial"] = ""
-            status = "Listening …"
-
         elif ev.kind == "final":
             state["partial"] = ""
-            state["sasr"].agent_speaking = True     # arm barge-in for playback
-            audio_out, status = _handle_turn(ev.text, state,
-                                             asr_ms=ev.latency_ms)
+            state["sasr"].agent_speaking = True
+            audio_out, status = run_turn(ev.text, state, ev.latency_ms)
+            convo = render(state["history"])
 
-    return (audio_out,
-            _render_conversation(state["history"]),
-            status or "Listening …",
-            state.get("partial", ""),
-            state)
+    return audio_out, convo, status, state.get("partial", ""), state
 
 
-def reset_session(state):
-    state = _init_state()
-    return None, _render_conversation([]), "New session started.", "", state
+def reset(state):
+    return None, render([]), "New session.", "", new_state()
 
 
-def use_demo_prompt(prompt_ha, state):
-    """Inject a demo Hausa phrase as text input."""
-    return prompt_ha, state
+# ── UI ───────────────────────────────────────────────────────────────────────
 
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Sora:wght@400;600;800&family=IBM+Plex+Mono:wght@400;500&display=swap');
+:root{--bg:#0B0B0F;--pnl:#15151C;--brd:#26262F;--txt:#E8E6E3;--mut:#7A7A88;
+      --acc:#FF8A3D;--acc2:#4ADE80;--blu:#60A5FA}
+.gradio-container{background:var(--bg)!important;font-family:'Sora',sans-serif!important;
+      color:var(--txt)!important;max-width:1280px!important}
+.hdr{background:linear-gradient(135deg,#15151C,#1E1E28 60%,#15151C);
+     border:1px solid var(--brd);border-radius:14px;padding:22px 26px;margin-bottom:14px}
+.hdr h1{font-size:25px;font-weight:800;margin:0;letter-spacing:-.5px}
+.hdr h1 b{color:var(--acc)}
+.hdr p{color:var(--mut);font-size:12.5px;margin:6px 0 0;letter-spacing:.4px}
+.tags{display:flex;gap:7px;margin-top:13px;flex-wrap:wrap}
+.tag{background:rgba(255,138,61,.12);border:1px solid rgba(255,138,61,.3);
+     color:var(--acc);padding:3px 11px;border-radius:99px;font-size:10.5px;
+     font-weight:600;letter-spacing:.6px}
+.tag.g{background:rgba(74,222,128,.12);border-color:rgba(74,222,128,.3);color:var(--acc2)}
+.tag.b{background:rgba(96,165,250,.12);border-color:rgba(96,165,250,.3);color:var(--blu)}
+.convo{background:var(--pnl);border:1px solid var(--brd);border-radius:13px;
+       padding:15px;height:395px;overflow-y:auto}
+.empty{color:var(--mut);text-align:center;margin-top:150px;font-size:13px}
+.row{display:flex;margin-bottom:11px}
+.r-me{justify-content:flex-end}.r-ag{justify-content:flex-start}
+.bub{max-width:86%;padding:10px 13px;border-radius:13px;font-size:13.5px;line-height:1.5}
+.b-me{background:rgba(255,138,61,.14);border:1px solid rgba(255,138,61,.26);
+      border-bottom-right-radius:4px}
+.b-ag{background:rgba(255,255,255,.045);border:1px solid var(--brd);
+      border-bottom-left-radius:4px}
+.lbl{font-size:9.5px;font-weight:700;letter-spacing:.9px;opacity:.55;margin-bottom:4px}
+.ha{font-weight:600}
+.en{font-size:11.5px;color:var(--mut);margin-top:3px;font-style:italic}
+.tm{font-size:9.5px;color:#4A4A56;margin-top:4px;font-family:'IBM Plex Mono',monospace}
+.note{background:rgba(96,165,250,.07);border:1px solid rgba(96,165,250,.22);
+      border-radius:11px;padding:13px 15px;font-size:12.5px;color:#B9C4D4;line-height:1.65}
+.note b{color:var(--blu)}
+footer{display:none!important}
+"""
 
-# ── Build the Gradio app ──────────────────────────────────────────────────────
-
-with gr.Blocks(css=CSS, title="PlotWeaver · Hausa Voice AI") as demo:
-
-    # Shared state
-    app_state = gr.State(None)
-
-    # ── Header ─────────────────────────────────────────────────────────────────
-    gr.HTML("""
-    <div class="pw-header">
-      <p class="pw-logo">Plot<span>Weaver</span></p>
-      <p class="pw-tagline">Hausa Voice AI Agent · Investor Demo · v0.1-poc</p>
-      <div style="display:flex; gap:8px; margin-top:14px; flex-wrap:wrap;">
-        <span class="pill">🎤 Whisper v3</span>
-        <span class="pill">🌐 NLLB-200</span>
-        <span class="pill">🔊 MMS-TTS</span>
-        <span class="pill-green">⚡ Real-time</span>
-        <span class="pill-blue">🏢 Enterprise-ready</span>
+with gr.Blocks(css=CSS, title="PlotWeaver · Hausa Voice AI",
+               theme=gr.themes.Base()) as demo:
+
+    st = gr.State(None)
+
+    gr.HTML(f"""
+    <div class="hdr">
+      <h1>Plot<b>Weaver</b> — Hausa Voice AI Agent</h1>
+      <p>Real-time conversational AI for 100M+ Hausa speakers · investor POC</p>
+      <div class="tags">
+        <span class="tag">Whisper ASR</span>
+        <span class="tag">NLLB-200</span>
+        <span class="tag">MMS-TTS</span>
+        <span class="tag g">VAD endpointing</span>
+        <span class="tag g">Multi-intent NLU</span>
+        <span class="tag b">{'GPU' if HAS_GPU else 'CPU'} mode</span>
       </div>
-    </div>
-    """)
+    </div>""")
 
     with gr.Tabs():
+        with gr.TabItem("Live Demo"):
+            gr.HTML('<div class="note"><b>First run:</b> press '
+                    '<b>Warm up models</b> — roughly 2–4 minutes while ~3.5GB '
+                    'downloads and caches. It only happens once per Space '
+                    'restart. On CPU, expect 5–15s per reply; a GPU brings '
+                    'that under 3s.</div>')
 
-        # ── Tab 1 : Live Demo ───────────────────────────────────────────────
-        with gr.TabItem("🎙️  Live Demo"):
             with gr.Row():
-                # Left column
+                with gr.Column(scale=3):
+                    convo = gr.HTML(render([]), elem_classes=["convo"])
+                    partial_box = gr.Textbox(label="Live transcript",
+                                             interactive=False, lines=1)
+                    status = gr.Textbox(
+                        label="Status",
+                        value=("Not warmed up." if INTEGRATIONS_OK else
+                               "Not warmed up · demo mode (no integrations)."),
+                        interactive=False, lines=2)
+
                 with gr.Column(scale=2):
-                    gr.HTML('<div class="pw-card-title" '
-                            'style="margin-bottom:10px;">Conversation</div>')
-                    conversation_display = gr.HTML(
-                        _render_conversation([]),
-                        elem_classes=["conversation-box"]
-                    )
-                    partial_box = gr.Textbox(
-                        label="Live transcript (unconfirmed)",
-                        value="",
-                        interactive=False,
-                        lines=1,
-                    )
-                    status_box = gr.Textbox(
-                        label="Pipeline Status",
-                        value="Ready. Speak or type in Hausa.",
-                        interactive=False,
-                        lines=1,
-                    )
-
-                # Right column
-                with gr.Column(scale=1):
-                    gr.HTML('<div class="pw-card-title" '
-                            'style="margin-bottom:10px;">Input</div>')
-
-                    # ── Streaming mic: VAD endpoints the turn, no button ──
-                    stream_in = gr.Audio(
-                        sources=["microphone"],
-                        type="numpy",
-                        label="🔴 Live Mic — just talk, VAD ends your turn",
-                        streaming=True,
-                    )
-
-                    with gr.Accordion("Push-to-talk (fallback)", open=False):
-                        audio_in = gr.Audio(
-                            sources=["microphone", "upload"],
-                            type="numpy",
-                            label="Record or upload, then press Send",
-                            streaming=False,
-                        )
-
-                    text_in = gr.Textbox(
-                        label="Text fallback (Hausa)",
-                        placeholder="Sannu, ina son sanin asusun kuɗin…",
-                        lines=2,
-                    )
-
-                    with gr.Row():
-                        submit_btn = gr.Button("▶  Send", variant="primary")
-                        reset_btn  = gr.Button("↺  Reset", variant="secondary")
-
-                    audio_out = gr.Audio(
-                        label="Agent Response (Hausa audio)",
-                        autoplay=True,
-                    )
-
-                    # Demo quick prompts
-                    gr.HTML('<div class="pw-card-title" '
-                            'style="margin-top:16px; margin-bottom:10px;">'
-                            'Quick Demo Prompts</div>')
-                    for label_en, phrase_ha in DEMO_PROMPTS:
-                        btn = gr.Button(f"{label_en}  →  {phrase_ha}",
-                                        variant="secondary", size="sm")
-                        btn.click(
-                            fn=lambda p=phrase_ha, s=None: (p, s),
-                            inputs=[app_state],
-                            outputs=[text_in, app_state],
-                        )
-
-            # ── Events ─────────────────────────────────────────────────────
-            # Streaming: fires continuously; VAD decides when a turn ends.
-            stream_in.stream(
-                fn=process_stream,
-                inputs=[stream_in, app_state],
-                outputs=[audio_out, conversation_display, status_box,
-                         partial_box, app_state],
-                stream_every=0.3,
-                show_progress="hidden",
-            )
-            # Flush any in-progress utterance when the mic stops.
-            stream_in.stop_recording(
-                fn=lambda s: reset_session(s)[1:],
-                inputs=[app_state],
-                outputs=[conversation_display, status_box, partial_box,
-                         app_state],
-            )
-
-            submit_btn.click(
-                fn=process_voice,
-                inputs=[audio_in, text_in, app_state],
-                outputs=[audio_out, conversation_display, status_box, app_state],
-            )
-            reset_btn.click(
-                fn=reset_session,
-                inputs=[app_state],
-                outputs=[audio_out, conversation_display, status_box,
-                         partial_box, app_state],
-            )
-
-        # ── Tab 2 : Architecture ────────────────────────────────────────────
-        with gr.TabItem("🏗️  Architecture"):
-            gr.HTML(ARCH_HTML)
-
-        # ── Tab 3 : Integrations ────────────────────────────────────────────
-        with gr.TabItem("🔌  Integrations"):
-            gr.HTML("""
-<div style="font-family:'Space Grotesk',sans-serif; color:#E7E5E4; padding:16px;">
-<div style="font-family:'Syne',sans-serif; font-size:13px; font-weight:700;
-            color:#F59E0B; letter-spacing:1px; text-transform:uppercase;
-            margin-bottom:20px;">Enterprise Integration Matrix</div>
-
-<div style="display:grid; grid-template-columns:repeat(auto-fill,minmax(220px,1fr)); gap:16px;">
-
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
-    <div style="font-size:24px; margin-bottom:8px;">💬</div>
-    <div style="font-weight:700; margin-bottom:4px;">WhatsApp Business</div>
-    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
-      Meta Cloud API v18+. Inbound voice notes → ASR pipeline. 
-      Quick-reply buttons. Media download.
-    </div>
-    <span style="font-size:10px; background:rgba(34,197,94,0.12);
-                 border:1px solid rgba(34,197,94,0.3); color:#22C55E;
-                 padding:2px 8px; border-radius:100px;">READY</span>
-  </div>
-
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
-    <div style="font-size:24px; margin-bottom:8px;">📞</div>
-    <div style="font-weight:700; margin-bottom:4px;">Twilio / SIP</div>
-    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
-      Twilio Media Streams WebSocket. Inbound + outbound IVR.
-      Warm transfer to human agent. Bandwidth BXML also supported.
-    </div>
-    <span style="font-size:10px; background:rgba(34,197,94,0.12);
-                 border:1px solid rgba(34,197,94,0.3); color:#22C55E;
-                 padding:2px 8px; border-radius:100px;">READY</span>
-  </div>
-
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
-    <div style="font-size:24px; margin-bottom:8px;">🗂️</div>
-    <div style="font-weight:700; margin-bottom:4px;">CRM / Ticketing</div>
-    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
-      Zendesk native adapter. Generic REST adapter for Freshdesk, 
-      HubSpot, Salesforce. Auto-ticket on issue report.
-    </div>
-    <span style="font-size:10px; background:rgba(34,197,94,0.12);
-                 border:1px solid rgba(34,197,94,0.3); color:#22C55E;
-                 padding:2px 8px; border-radius:100px;">READY</span>
-  </div>
-
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
-    <div style="font-size:24px; margin-bottom:8px;">👤</div>
-    <div style="font-weight:700; margin-bottom:4px;">Human Fallback</div>
-    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
-      Threshold-based escalation: low confidence, explicit request, 
-      or max-turns. SIP REFER transfer + CRM context handoff.
-    </div>
-    <span style="font-size:10px; background:rgba(34,197,94,0.12);
-                 border:1px solid rgba(34,197,94,0.3); color:#22C55E;
-                 padding:2px 8px; border-radius:100px;">READY</span>
-  </div>
-
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
-    <div style="font-size:24px; margin-bottom:8px;">🌍</div>
-    <div style="font-weight:700; margin-bottom:4px;">More Languages</div>
-    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
-      Yorùbá, Igbo, Fulfulde, Kanuri roadmap. 
-      NLLB covers 200 languages. MMS covers 1,000+ TTS languages.
-    </div>
-    <span style="font-size:10px; background:rgba(245,158,11,0.12);
-                 border:1px solid rgba(245,158,11,0.3); color:#F59E0B;
-                 padding:2px 8px; border-radius:100px;">ROADMAP</span>
-  </div>
-
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
-    <div style="font-size:24px; margin-bottom:8px;">⚡</div>
-    <div style="font-weight:700; margin-bottom:4px;">Fine-tuned Models</div>
-    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
-      Custom Whisper fine-tune for Hausa dialectal variance. 
-      OuteTTS / MMS fine-tune on domain vocabulary. NLLB domain adaptation.
-    </div>
-    <span style="font-size:10px; background:rgba(245,158,11,0.12);
-                 border:1px solid rgba(245,158,11,0.3); color:#F59E0B;
-                 padding:2px 8px; border-radius:100px;">IN PROGRESS</span>
-  </div>
-
-</div>
-
-<div style="margin-top:24px; padding:16px; background:rgba(245,158,11,0.05);
-            border:1px solid rgba(245,158,11,0.2); border-radius:10px;">
-  <div style="font-size:12px; font-weight:700; color:#F59E0B; 
-              margin-bottom:8px; letter-spacing:0.5px;">⚙  CONFIGURATION</div>
-  <div style="font-family:'JetBrains Mono',monospace; font-size:11px; 
-              color:#78716C; line-height:2;">
-    WHATSAPP_TOKEN=&lt;meta-token&gt;  &nbsp; WHATSAPP_PHONE_ID=&lt;phone-id&gt;<br>
-    TWILIO_ACCOUNT_SID=ACxxxx  &nbsp; TWILIO_AUTH_TOKEN=xxxx<br>
-    CRM_PROVIDER=zendesk  &nbsp; ZENDESK_SUBDOMAIN=yourco  &nbsp; ZENDESK_API_TOKEN=xxxx<br>
-    SIP_PROVIDER=twilio  &nbsp; (or bandwidth)
-  </div>
-</div>
-</div>
+                    warm_btn = gr.Button("Warm up models", variant="primary")
+
+                    reply = gr.Audio(label="Agent reply", autoplay=True,
+                                     interactive=False)
+
+                    with gr.Tab("Type"):
+                        txt = gr.Textbox(
+                            label="Hausa text",
+                            placeholder="Duba asusuna sannan ka aika 35000 zuwa Amina",
+                            lines=2)
+                        send = gr.Button("Send", variant="primary")
+
+                    with gr.Tab("Record"):
+                        rec = gr.Audio(sources=["microphone", "upload"],
+                                       type="numpy", label="Record, then Send")
+                        send_rec = gr.Button("Send recording", variant="primary")
+
+                    with gr.Tab("Live mic (VAD)"):
+                        gr.Markdown(
+                            "Speak naturally — the VAD ends your turn on a "
+                            "pause. Heavy on CPU; use Type or Record if it lags.")
+                        live = gr.Audio(sources=["microphone"], type="numpy",
+                                        streaming=True, label="Live")
+
+                    reset_btn = gr.Button("Reset conversation")
+
+                    gr.Markdown("**Demo prompts**")
+                    for label, phrase in DEMO_PROMPTS:
+                        gr.Button(label, size="sm").click(
+                            lambda p=phrase: p, outputs=[txt])
+
+            warm_btn.click(warm_up, [st], [status, st])
+            send.click(on_text, [txt, st], [reply, convo, status, st])
+            txt.submit(on_text, [txt, st], [reply, convo, status, st])
+            send_rec.click(on_record, [rec, st], [reply, convo, status, st])
+            live.stream(on_stream, [live, st],
+                        [reply, convo, status, partial_box, st],
+                        stream_every=STREAM_EVERY, show_progress="hidden")
+            reset_btn.click(reset, [st],
+                            [reply, convo, status, partial_box, st])
+
+        with gr.TabItem("How it works"):
+            gr.Markdown("""
+### Pipeline
+
+`mic → VAD endpointing → Whisper (Hausa) → NLLB hau→eng → task-queue
+orchestrator → NLLB eng→hau → MMS-TTS → audio`
+
+### What the dialogue layer does
+
+Most voice bots resolve one intent and one missing slot per turn, which breaks
+the moment a caller combines requests or answers out of order. This one
+decomposes each message into a **task queue**:
+
+| Caller says | What happens |
+|---|---|
+| "check my balance **and also** send 35000 to Amina" | Both tasks queued and acknowledged; neither is silently dropped |
+| "send money **to Abu**" | Recipient prefilled from the utterance — never re-asked |
+| "where's your branch so I can **get** my ATM card" | Branch info. *Not* block-card — destructive intents need an explicit verb |
+| "too small" (as a return reason) | Accepted as a slot answer, not a fallback dead-end |
+| Transfer above balance | Refused before the confirmation prompt |
+| Two unparseable turns | Human handoff **with the transcript attached** |
+
+Money actions require confidence ≥ 0.75 *and* an explicit yes/no.
+
+### Model configuration
+
+Defaults are tuned for a free CPU Space. Override via Space secrets:
+
+| Variable | Default | Notes |
+|---|---|---|
+| `ASR_FINAL_MODEL` | `openai/whisper-small` | `whisper-large-v3` on GPU |
+| `SHOW_PARTIALS` | `0` | `1` only on GPU |
+| `HF_TOKEN` | unset | Enables LLM-based NLU (big quality gain) |
+| `CRM_PROVIDER` | `demo` | `zendesk` for real tickets |
+
+Without `HF_TOKEN` the NLU uses rule-based decomposition: it passes the full
+regression suite but only handles phrasings that were anticipated.
 """)
 
-        # ── Tab 4 : Business Case ────────────────────────────────────────────
-        with gr.TabItem("📊  Market"):
-            gr.HTML("""
-<div style="font-family:'Space Grotesk',sans-serif; color:#E7E5E4; padding:16px;">
-<div style="font-family:'Syne',sans-serif; font-size:13px; font-weight:700;
-            color:#F59E0B; letter-spacing:1px; text-transform:uppercase;
-            margin-bottom:20px;">Why Hausa Voice AI · Now</div>
-
-<div style="display:grid; grid-template-columns:repeat(auto-fill,minmax(180px,1fr));
-            gap:16px; margin-bottom:24px;">
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;
-              padding:18px; text-align:center;">
-    <div style="font-family:'Syne',sans-serif; font-size:32px; font-weight:800;
-                color:#F59E0B;">100M+</div>
-    <div style="font-size:12px; color:#78716C; margin-top:4px;">Hausa speakers</div>
-    <div style="font-size:11px; color:#22C55E;">#1 language in West Africa</div>
-  </div>
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;
-              padding:18px; text-align:center;">
-    <div style="font-family:'Syne',sans-serif; font-size:32px; font-weight:800;
-                color:#F59E0B;">63%</div>
-    <div style="font-size:12px; color:#78716C; margin-top:4px;">Low literacy rate</div>
-    <div style="font-size:11px; color:#38BDF8;">Voice is the UX</div>
-  </div>
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;
-              padding:18px; text-align:center;">
-    <div style="font-family:'Syne',sans-serif; font-size:32px; font-weight:800;
-                color:#F59E0B;">$4.2B</div>
-    <div style="font-size:12px; color:#78716C; margin-top:4px;">Africa call-centre spend</div>
-    <div style="font-size:11px; color:#F59E0B;">2027 projection</div>
-  </div>
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;
-              padding:18px; text-align:center;">
-    <div style="font-family:'Syne',sans-serif; font-size:32px; font-weight:800;
-                color:#F59E0B;">0</div>
-    <div style="font-size:12px; color:#78716C; margin-top:4px;">Production Hausa VoiceBots</div>
-    <div style="font-size:11px; color:#DC2626;">Whitespace opportunity</div>
-  </div>
-</div>
-
-<div style="display:grid; grid-template-columns:1fr 1fr; gap:16px;">
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
-    <div style="font-weight:700; color:#F59E0B; margin-bottom:12px;">🎯  Target Verticals</div>
-    <div style="font-size:13px; line-height:2; color:#A8A29E;">
-      📱 Telecoms (MTN, Airtel Nigeria, Glo)<br>
-      🏦 Fintech / Mobile money (Kuda, PalmPay)<br>
-      🏥 Health (NHIS, telemedicine IVR)<br>
-      🏛 Government services (NIMC, NIN)<br>
-      🛒 E-commerce (Jumia, Konga)
-    </div>
-  </div>
-  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
-    <div style="font-weight:700; color:#F59E0B; margin-bottom:12px;">🏆  Competitive Moat</div>
-    <div style="font-size:13px; line-height:2; color:#A8A29E;">
-      ✓ Open-source stack (no API lock-in)<br>
-      ✓ Fine-tuned Hausa models (PlotWeaver IP)<br>
-      ✓ On-premise deployable (data sovereignty)<br>
-      ✓ Multi-channel from day one<br>
-      ✓ Academic NLP + production engineering
-    </div>
-  </div>
-</div>
-</div>
+        with gr.TabItem("Market"):
+            gr.Markdown("""
+### Why Hausa, why now
+
+| | |
+|---|---|
+| **100M+** | Hausa speakers — the largest language in West Africa |
+| **~63%** | Low literacy in core regions — voice *is* the interface |
+| **$4.2B** | Projected African contact-centre spend by 2027 |
+| **~0** | Production-grade Hausa voice agents in market |
+
+**Target verticals** — telecoms (MTN, Airtel, Glo), fintech and mobile money
+(Kuda, PalmPay, OPay), public services (NIMC), health IVR, e-commerce.
+
+**Moat** — open-weights stack with no per-call API lock-in; fine-tuned Hausa
+models as owned IP; deployable on-premise for data-residency requirements;
+multi-channel (voice, WhatsApp, SIP) from day one.
+
+**Roadmap** — Yorùbá, Igbo, Fulfulde, Kanuri. NLLB covers 200 languages and
+MMS covers 1,000+ for TTS, so each new language is a fine-tune, not a rebuild.
 """)
 
-    # ── Footer ────────────────────────────────────────────────────────────────
-    gr.HTML("""
-    <div style="text-align:center; padding:20px; color:#44403C; font-size:11px;
-                border-top:1px solid #1C1917; margin-top:8px;">
-      PlotWeaver · Hausa Voice AI Agent POC &nbsp;|&nbsp;
-      Whisper large-v3 · NLLB-200 · MMS-TTS-hau &nbsp;|&nbsp;
-      <a href="https://plotweaver.ai" style="color:#F59E0B; text-decoration:none;">
-        plotweaver.ai</a>
-    </div>
-    """)
+    gr.HTML('<div style="text-align:center;padding:16px;color:#3A3A46;'
+            'font-size:11px">PlotWeaver · open-weights Hausa voice AI</div>')
 
 
 if __name__ == "__main__":
-    demo.launch(share=False)
+    demo.queue(max_size=12).launch(
+        server_name="0.0.0.0",
+        server_port=int(os.getenv("PORT", 7860)),
+        show_api=False,
+    )

deploy.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# ── Deploy to HuggingFace Spaces ─────────────────────────────────────────────
+# Validates the file layout BEFORE pushing, because the most common failure is
+# integrations/ never reaching the Space (the HF web uploader skips folders),
+# which crashes startup with ModuleNotFoundError.
+#
+# Usage:  ./deploy.sh <hf-username> <space-name>
+# Example: ./deploy.sh plotweaver hausa-voice-agent
+
+set -euo pipefail
+
+USER="${1:-}"
+SPACE="${2:-}"
+
+if [[ -z "$USER" || -z "$SPACE" ]]; then
+    echo "Usage: ./deploy.sh <hf-username> <space-name>"
+    exit 1
+fi
+
+echo "── Validating layout ─────────────────────────────────────────"
+
+REQUIRED=(
+    app.py pipeline.py nlu.py orchestrator.py vad.py streaming_asr.py
+    requirements.txt README.md
+    integrations/__init__.py integrations/crm.py
+    integrations/sip.py integrations/whatsapp.py
+)
+
+MISSING=0
+for f in "${REQUIRED[@]}"; do
+    if [[ -f "$f" ]]; then
+        printf '  ✓ %s\n' "$f"
+    else
+        printf '  ✗ %s  MISSING\n' "$f"
+        MISSING=1
+    fi
+done
+
+if [[ $MISSING -eq 1 ]]; then
+    echo ""
+    echo "Refusing to deploy: files are missing. The Space would crash on boot."
+    exit 1
+fi
+
+echo ""
+echo "── Running tests ─────────────────────────────────────────────"
+python verify_boot.py       || { echo "Boot check failed."; exit 1; }
+python test_app.py          || { echo "App launch test failed."; exit 1; }
+python test_streaming.py    || { echo "Streaming tests failed."; exit 1; }
+python test_regressions.py  || { echo "NLU tests failed."; exit 1; }
+
+echo ""
+echo "── Pushing to Space ──────────────────────────────────────────"
+
+if [[ ! -d .git ]]; then
+    git init -q
+    git remote add origin "https://huggingface.co/spaces/${USER}/${SPACE}"
+fi
+
+git add -A                  # -A, not '.', so nothing is quietly skipped
+
+echo ""
+echo "Staged files:"
+git status --short
+
+echo ""
+read -r -p "Push these to ${USER}/${SPACE}? [y/N] " CONFIRM
+[[ "$CONFIRM" == "y" || "$CONFIRM" == "Y" ]] || { echo "Aborted."; exit 0; }
+
+git commit -q -m "Deploy Hausa Voice AI Agent" || echo "Nothing new to commit."
+git push -u origin main
+
+echo ""
+echo "Done → https://huggingface.co/spaces/${USER}/${SPACE}"
+echo "Set HF_TOKEN under Settings → Variables and secrets for best NLU quality."

nlu.py

@@ -91,7 +91,13 @@ class NLU:
             "NLU_API_MODEL", "Qwen/Qwen2.5-72B-Instruct")
         self.local_model_id = os.getenv(
             "NLU_LOCAL_MODEL", "Qwen/Qwen2.5-1.5B-Instruct")
+        # The local backend is OPT-IN. Left automatic, the first NLU call on a
+        # Space silently downloads a ~3GB model mid-demo and blocks for
+        # minutes. Enable deliberately with NLU_LOCAL=1 on hardware that can
+        # take it.
+        self.use_local = os.getenv("NLU_LOCAL", "0") == "1"
         self._local_pipe = None
+        self._dead = set()          # backends that failed — never retried
         self.prefer = prefer
 
     # ── Public API ────────────────────────────────────────────────────────────
@@ -110,6 +116,9 @@ class NLU:
                        f"A short answer likely fills that slot.")
 
         for backend in self._backend_order():
+            name = backend.__name__
+            if name in self._dead:
+                continue
             try:
                 result = backend(text, context)
                 if result and result.get("tasks"):
@@ -118,7 +127,12 @@ class NLU:
                                 f"{json.dumps(result['tasks'])[:200]}")
                     return result
             except Exception as e:
-                logger.warning(f"NLU backend failed ({backend.__name__}): {e}")
+                # Mark dead so a missing dependency or bad token doesn't cost
+                # a retry (and a re-download attempt) on every single turn.
+                self._dead.add(name)
+                logger.warning(
+                    f"NLU backend {name} failed and is disabled for this "
+                    f"session: {e}")
         # Absolute last resort
         return {"tasks": [{"intent": "unknown", "confidence": 0.0,
                             "slots": {}, "utterance_span": text}],
@@ -132,7 +146,8 @@ class NLU:
         chain = []
         if self.hf_token:
             chain.append(self._api_backend)
-        chain.append(self._local_backend)
+        if self.use_local:
+            chain.append(self._local_backend)
         chain.append(self._rules_backend)
         return chain
 

pipeline.py

@@ -34,11 +34,24 @@ class HausaVoiceAIPipeline:
     the Space startup time reasonable on CPU.
     """
 
-    # Dual-model ASR: large-v3 for the FINAL decode (accuracy), a small model
-    # for live partials (latency). Partials are thrown away and replaced by the
-    # final, so their error rate matters far less than their speed.
-    ASR_FINAL_MODEL   = os.getenv("ASR_FINAL_MODEL",   "openai/whisper-large-v3")
-    ASR_PARTIAL_MODEL = os.getenv("ASR_PARTIAL_MODEL", "openai/whisper-small")
+    # Model selection is CPU-FIRST. whisper-large-v3 is ~6GB in fp32 and takes
+    # roughly a minute per utterance on the 2-vCPU free tier — it makes the
+    # Space look broken. Default to small on CPU, large-v3 when a GPU is
+    # present, and let an env var override either way.
+    _GPU = torch.cuda.is_available()
+    ASR_FINAL_MODEL = os.getenv(
+        "ASR_FINAL_MODEL",
+        "openai/whisper-large-v3" if _GPU else "openai/whisper-small")
+    ASR_PARTIAL_MODEL = os.getenv(
+        "ASR_PARTIAL_MODEL",
+        "openai/whisper-small" if _GPU else "openai/whisper-base")
+    NLLB_MODEL = os.getenv("NLLB_MODEL", "facebook/nllb-200-distilled-600M")
+    TTS_MODEL  = os.getenv("TTS_MODEL",  "facebook/mms-tts-hau")
+
+    def describe_models(self) -> str:
+        short = lambda m: m.split("/")[-1]
+        return (f"{short(self.ASR_FINAL_MODEL)} · {short(self.NLLB_MODEL)} · "
+                f"{short(self.TTS_MODEL)} · {'GPU' if self._GPU else 'CPU'}")
 
     def __init__(self, pivot_language: str = "english"):
         self.pivot = pivot_language          # dialogue logic runs in English
@@ -89,7 +102,7 @@ class HausaVoiceAIPipeline:
             return
         logger.info("Loading NLLB-200-distilled-600M …")
         from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
-        model_id = "facebook/nllb-200-distilled-600M"
+        model_id = self.NLLB_MODEL
         self._nllb_tokenizer = AutoTokenizer.from_pretrained(model_id)
         self._nllb_model = AutoModelForSeq2SeqLM.from_pretrained(model_id).to(DEVICE)
 
@@ -98,7 +111,7 @@ class HausaVoiceAIPipeline:
             return
         logger.info("Loading MMS-TTS Hausa …")
         from transformers import VitsModel, AutoTokenizer
-        model_id = "facebook/mms-tts-hau"
+        model_id = self.TTS_MODEL
         self._tts_tokenizer = AutoTokenizer.from_pretrained(model_id)
         self._tts_model = VitsModel.from_pretrained(model_id).to(DEVICE)
         self.tts_sample_rate = self._tts_model.config.sampling_rate

requirements.txt

@@ -1,37 +1,40 @@
 # ── PlotWeaver Hausa Voice AI Agent ──────────────────────────────────────────
-# Audited against actual imports. Nothing here is speculative.
-#
-# HF Spaces reinstalls this on every rebuild, so the list is deliberately small:
-# librosa was removed in favour of the scipy resampler already in the codebase
-# (librosa pulls numba + llvmlite and adds several minutes to cold builds).
+# Versions verified by actually launching the app (see test_app.py), not by
+# assumption. Two things were caught this way:
+#   * gradio 4.44 is now BROKEN against current huggingface_hub (HfFolder was
+#     removed) — a fresh Space build on 4.44 fails at import.
+#   * `stream_every` on Audio.stream does not exist before gradio 5.
+# Keep sdk_version in README.md frontmatter in sync with the gradio pin below.
+
+gradio>=5.49.0,<6.0.0       # Audio.stream(stream_every=...) + gr.skip()
 
 # ── Core ML ──────────────────────────────────────────────────────────────────
 torch>=2.2.0                # Whisper, NLLB, MMS, Silero VAD
 transformers>=4.40.0        # >=4.40 required for VitsModel (MMS-TTS)
-sentencepiece>=0.2.0        # NLLB tokenizer — NOT optional, NLLB fails without it
-accelerate>=0.28.0          # device_map="auto" for the local NLU model
+sentencepiece>=0.2.0        # NLLB tokenizer — NOT optional
+accelerate>=0.28.0          # device placement
 protobuf>=4.25.0            # slow→fast tokenizer conversion for NLLB
 
 # ── Audio ────────────────────────────────────────────────────────────────────
-numpy>=1.26.0,<3.0.0        # 2.x is fine; cap guards against a future 3.0 break
+numpy>=1.26.0,<3.0.0
 scipy>=1.12.0               # scipy.signal.resample — the only resampler used
 soundfile>=0.12.1           # Gradio audio I/O backend
 
-# ── App ──────────────────────────────────────────────────────────────────────
-gradio>=4.44.0              # streaming=True + stream_every need >=4.44
+# ── Misc ─────────────────────────────────────────────────────────────────────
 requests>=2.31.0            # WhatsApp Cloud API, Zendesk, HF Inference API
 
-# ── Optional integrations ────────────────────────────────────────────────────
-# Only needed when SIP_PROVIDER=twilio with real credentials. integrations/sip.py
-# imports twilio lazily inside the non-demo branches, so the demo never touches
-# it and this line can be dropped to slim the image.
-twilio>=9.0.0
+# ── Optional ─────────────────────────────────────────────────────────────────
+# torchaudio is NOT required by this app, but Silero VAD imports it via
+# torch.hub. Without it the built-in energy VAD is used instead, which works
+# fine — uncomment only if you want Silero's noise robustness.
+# torchaudio>=2.2.0
+#
+# Only needed with SIP_PROVIDER=twilio and real credentials; sip.py imports it
+# lazily, so the demo never touches it.
+# twilio>=9.0.0
 
 # ── Deliberately absent ──────────────────────────────────────────────────────
-# torchaudio  — nothing imports it.
-# librosa     — resampling uses scipy.signal.resample instead.
-# silero-vad  — vad.py loads it via torch.hub and falls back to the built-in
-#               energy VAD if the download is blocked. No package needed.
-# audioop     — G.711 mu-law decoding is implemented in numpy in
-#               integrations/sip.py, because audioop was REMOVED from the
-#               stdlib in Python 3.13 and would break telephony on new images.
+# librosa    — resampling uses scipy.signal.resample.
+# silero-vad — loaded via torch.hub with an energy-VAD fallback.
+# audioop    — removed from the stdlib in Python 3.13; G.711 mu-law decoding
+#              is implemented in numpy in integrations/sip.py.

test_app.py

@@ -0,0 +1,155 @@
+"""
+Verifies the app ACTUALLY LAUNCHES under the pinned gradio, and that every
+event handler is wired with a matching signature.
+
+This is the check that was missing before: the previous app.py used
+`stream_every`, which does not exist in gradio 4.44 — it would have crashed on
+Space startup no matter how correct the rest of the code was.
+
+Models are stubbed, so this tests the app wiring, not the ML.
+"""
+import os
+import sys
+import types
+import numpy as np
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# ── Stub the pipeline so no 3.5GB download happens ───────────────────────────
+import pipeline as _pl
+
+
+def _fake_transcribe(self, audio, sr=16000):
+    return "duba asusuna sannan ka aika 35000 zuwa Amina"
+
+
+def _fake_translate(self, text, src, tgt, **kw):
+    table = {
+        "duba asusuna sannan ka aika 35000 zuwa Amina":
+            "check my balance and also send 35000 to amina",
+        "2234567890": "2234567890",
+        "eh": "yes",
+    }
+    return table.get(text, text)
+
+
+def _fake_tts(self, text):
+    return 16000, (np.sin(np.arange(8000) / 20) * 8000).astype(np.int16)
+
+
+_pl.HausaVoiceAIPipeline.transcribe = _fake_transcribe
+_pl.HausaVoiceAIPipeline.transcribe_partial = _fake_transcribe
+_pl.HausaVoiceAIPipeline.translate = _fake_translate
+_pl.HausaVoiceAIPipeline.synthesize = _fake_tts
+_pl.HausaVoiceAIPipeline.hausa_text_to_audio = _fake_tts
+_pl.HausaVoiceAIPipeline._load_asr = lambda self: None
+_pl.HausaVoiceAIPipeline._load_asr_fast = lambda self: None
+_pl.HausaVoiceAIPipeline._load_nllb = lambda self: None
+_pl.HausaVoiceAIPipeline._load_tts = lambda self: None
+
+os.environ.setdefault("SHOW_PARTIALS", "0")
+
+PASS, FAIL = "\033[92mPASS\033[0m", "\033[91mFAIL\033[0m"
+results = []
+
+
+def check(name, cond, detail=""):
+    results.append((name, cond))
+    print(f"  [{PASS if cond else FAIL}] {name}" + (f"  — {detail}" if detail else ""))
+
+
+print("\n══ App imports and builds under the pinned gradio ══")
+import gradio as gr
+print(f"  gradio {gr.__version__}")
+import app as A
+check("app module imported", True)
+check("Blocks object built", isinstance(A.demo, gr.Blocks))
+
+print("\n══ Streaming API exists in this gradio version ══")
+import inspect
+p = inspect.signature(gr.Audio(streaming=True).stream).parameters
+check("Audio.stream accepts stream_every", "stream_every" in p)
+check("gr.skip available", hasattr(gr, "skip"))
+
+print("\n══ Event handlers are wired ══")
+fns = A.demo.fns
+check("events registered", len(fns) > 0, f"{len(fns)} handlers")
+
+print("\n══ Text handler: full compound-request conversation ══")
+st = None
+audio, convo, status, st = A.on_text(
+    "duba asusuna sannan ka aika 35000 zuwa Amina", st)
+check("turn 1 returns audio", audio is not None and audio is not gr.skip())
+check("turn 1 acknowledges BOTH tasks",
+      "one at a time" in convo.lower() or "balance" in convo.lower(),
+      status[:70])
+audio, convo, status, st = A.on_text("2234567890", st)
+check("turn 2 delivers balance + continues transfer",
+      "balance is" in convo.lower() and "amina" in convo.lower())
+audio, convo, status, st = A.on_text("eh", st)
+check("turn 3 executes the transfer", "sent to amina" in convo.lower())
+check("latency breakdown in status", "total" in status, status[-52:])
+
+print("\n══ Empty input does not crash ══")
+a, c, s, st2 = A.on_text("", None)
+check("empty text handled", a == gr.skip() or a is None)
+a, c, s, st2 = A.on_record(None, None)
+check("no recording handled", a == gr.skip() or a is None)
+
+print("\n══ Streaming handler with synthetic audio ══")
+SR = 16000
+
+
+def sil(ms, n=0.0005):
+    k = int(SR * ms / 1000)
+    return (np.random.randn(k) * n).astype(np.float32)
+
+
+def sp(ms, amp=0.25):
+    k = int(SR * ms / 1000)
+    t = np.arange(k) / SR
+    s = (np.sin(2*np.pi*120*t) + 0.5*np.sin(2*np.pi*700*t)
+         + 0.3*np.sin(2*np.pi*1220*t))
+    s = s * (0.6 + 0.4*np.sin(2*np.pi*4*t)) + np.random.randn(k)*0.01
+    return (s / np.abs(s).max() * amp).astype(np.float32)
+
+
+st = A.new_state()
+stream = np.concatenate([sil(400), sp(1600), sil(1200)])
+step = int(SR * 0.5)
+got_reply = False
+n_skips = 0
+for i in range(0, len(stream), step):
+    out = A.on_stream((SR, stream[i:i+step]), st)
+    check_len = len(out) == 5
+    audio_o, convo_o, status_o, partial_o, st = out
+    if audio_o == gr.skip():
+        n_skips += 1
+    elif audio_o is not None:
+        got_reply = True
+check("stream handler returns 5 values", check_len)
+check("VAD endpointed and produced a reply", got_reply)
+check("idle ticks return gr.skip (no player restart)", n_skips > 0,
+      f"{n_skips} skipped ticks")
+
+print("\n══ Reset ══")
+r = A.reset(st)
+check("reset returns 5 values", len(r) == 5)
+check("history cleared", "Press" in r[1] or "empty" in r[1])
+
+print("\n══ Launch smoke test (real server, then shut down) ══")
+try:
+    A.demo.queue(max_size=4)
+    _, url, _ = A.demo.launch(prevent_thread_lock=True, quiet=True,
+                              server_port=7899, show_api=False)
+    check("Gradio server started", True, url or "local")
+    import urllib.request
+    code = urllib.request.urlopen("http://127.0.0.1:7899/", timeout=15).getcode()
+    check("HTTP 200 from the app root", code == 200, f"status {code}")
+    A.demo.close()
+except Exception as e:
+    check("Gradio server started", False, str(e)[:110])
+
+passed = sum(1 for _, ok in results if ok)
+print(f"\n{'='*62}\n  {passed}/{len(results)} checks passed\n{'='*62}")
+sys.exit(0 if passed == len(results) else 1)

verify_boot.py

@@ -0,0 +1,85 @@
+"""
+Verifies app.py imports cleanly under file-layout problems that have actually
+broken this Space:
+
+  A  integrations/ folder missing entirely (HF web uploader skips folders)
+  B  integrations/ present but without __init__.py
+  C  integrations/ complete
+  D  app started from a different working directory
+
+Uses the REAL gradio (a verified dependency) and stubs only model loading, so
+nothing downloads. Never launches a server — that is test_app.py's job.
+"""
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+SRC = os.path.dirname(os.path.abspath(__file__))
+GREEN, RED, OFF = "\033[92m", "\033[91m", "\033[0m"
+
+HARNESS = '''
+import sys
+sys.path.insert(0, sys.argv[2])
+import pipeline as _pl
+_pl.HausaVoiceAIPipeline._load_asr      = lambda self: None
+_pl.HausaVoiceAIPipeline._load_asr_fast = lambda self: None
+_pl.HausaVoiceAIPipeline._load_nllb     = lambda self: None
+_pl.HausaVoiceAIPipeline._load_tts      = lambda self: None
+import runpy
+runpy.run_path(sys.argv[1], run_name="__not_main__")
+print("IMPORT_OK")
+'''
+
+
+def scenario(name, setup, cwd=None):
+    tmp = tempfile.mkdtemp()
+    for f in os.listdir(SRC):
+        if f.endswith(".py"):
+            shutil.copy(os.path.join(SRC, f), tmp)
+    setup(tmp)
+    harness = os.path.join(tmp, "_h.py")
+    with open(harness, "w") as fh:
+        fh.write(HARNESS)
+    r = subprocess.run(
+        [sys.executable, harness, os.path.join(tmp, "app.py"), tmp],
+        capture_output=True, text=True, cwd=cwd or tmp)
+    ok = "IMPORT_OK" in r.stdout
+    tag = f"{GREEN}BOOTS{OFF}" if ok else f"{RED}CRASH{OFF}"
+    print(f"  [{tag}] {name}")
+    if not ok:
+        tail = (r.stderr or r.stdout).strip().splitlines()
+        print("         " + (tail[-1] if tail else "no output"))
+    shutil.rmtree(tmp, ignore_errors=True)
+    return ok
+
+
+def none(tmp):
+    pass
+
+
+def no_init(tmp):
+    d = os.path.join(tmp, "integrations")
+    os.makedirs(d, exist_ok=True)
+    for f in ("crm.py", "sip.py", "whatsapp.py"):
+        shutil.copy(os.path.join(SRC, "integrations", f), d)
+
+
+def full(tmp):
+    d = os.path.join(tmp, "integrations")
+    os.makedirs(d, exist_ok=True)
+    for f in os.listdir(os.path.join(SRC, "integrations")):
+        if f.endswith(".py"):
+            shutil.copy(os.path.join(SRC, "integrations", f), d)
+
+
+print("\n== Space startup scenarios ==")
+res = [
+    scenario("A: integrations/ missing entirely", none),
+    scenario("B: integrations/ without __init__.py", no_init),
+    scenario("C: integrations/ complete", full),
+    scenario("D: different working directory", full, cwd="/"),
+]
+print(f"\n  {sum(res)}/{len(res)} scenarios boot cleanly")
+sys.exit(0 if all(res) else 1)