Upload 4 files

README.md

@@ -1,12 +1,62 @@
 ---
-title: Voice AI Agent
-emoji: 🐨
-colorFrom: blue
-colorTo: green
+title: PlotWeaver Voice Agent
+emoji: 🗣️
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 6.13.0
+sdk_version: 4.44.1
 app_file: app.py
-pinned: false
+pinned: true
+short_description: Hausa voice AI for African banks, telecoms, and delivery
+license: apache-2.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# PlotWeaver Voice Agent
+
+Hausa-first conversational AI demo. Product 7 of the PlotWeaver suite: voice bots for WhatsApp, phone, and customer support across African banks, telecoms, and delivery services.
+
+## What it does
+
+- **ASR**: Whisper-small transcribes your Hausa audio
+- **NLU**: Hybrid three-tier system — rule-based keyword fast path → Qwen2.5-1.5B-Instruct zero-shot classifier for paraphrases → rule-based safety fallback. The pipeline trace shows which tier answered each turn.
+- **Dialogue manager**: deterministic FSM across 3 verticals (Bank, Telecom, Delivery)
+- **TTS**: `facebook/mms-tts-hau` synthesizes the bot's Hausa response
+
+## How to use
+
+1. Pick a vertical (Bank / Telecom / Delivery)
+2. Three ways to talk to the agent:
+   - **Type** a Hausa phrase in the text box
+   - **Record** via browser microphone
+   - **Upload** a pre-recorded Hausa audio file (.wav, .mp3, .ogg — up to 30s)
+3. For audio, click "Transcribe & send" after recording/uploading
+4. Watch the pipeline trace on the left — session load, ASR, NLU, dialogue manager, TTS
+5. The bot's audio response autoplays; full multi-turn flows work (balance check, transfers, complaints, rescheduling, etc.)
+
+## Demo flows
+
+**Bank**: "duba ma'auni" → "1234" → bot returns your balance.
+
+**Telecom**: "saya airtime" → "1000" → airtime loaded.
+
+**Delivery**: "bincika oda" → "10234" → order status.
+
+**Escalation**: say "mutum" or "wakili" at any time to flag a human handoff.
+
+## Architecture
+
+```
+User (WhatsApp/Phone/Web)
+    ↓
+ASR (Whisper) → NLU (XLM-R) → Dialogue FSM → Response Gen → TTS (MMS)
+    ↓                                                          ↓
+Session state (Redis, 10min TTL)                          Bot audio
+```
+
+## Notes
+
+First turn takes ~30-60s to cold-start ASR + TTS models (~640MB total). The Qwen2.5-1.5B NLU model (~3GB) only loads when a user utterance doesn't match the rule-based keyword set — so common phrases stay fast, and novel phrasings trigger a 30-40s one-time LLM load (then ~5-8s per subsequent LLM call on CPU).
+
+For production a GPU Space or dedicated endpoint brings full turn latency under 1s.
+
+This is a POC demo. Production plan covers fine-tuned Hausa Whisper, fine-tuned XLM-R or AfroXLMR NLU classifier (replacing the LLM for consistent sub-100ms NLU), live WhatsApp Business Cloud integration, and Twilio Voice.

app.py

@@ -0,0 +1,509 @@
+"""
+PlotWeaver Voice Agent — HuggingFace Space
+============================================
+Gradio app demonstrating a Hausa-first conversational AI for
+African banks, telecoms, and delivery services.
+
+Pipeline: ASR (Whisper-small) → NLU (rule-based) → Dialogue FSM →
+           TTS (facebook/mms-tts-hau).
+
+Runs on CPU. First turn triggers model download (~500MB), subsequent turns
+are ~2-4s end-to-end.
+"""
+from __future__ import annotations
+import time
+import uuid
+import html as html_lib
+from typing import Optional
+
+import gradio as gr
+import numpy as np
+import torch
+from transformers import (
+    VitsModel, AutoTokenizer,
+    WhisperProcessor, WhisperForConditionalGeneration,
+)
+
+from dialogue import (
+    DialogueState, SCENARIOS,
+    get_prompt, get_expected_slot, transition,
+)
+from nlu import parse as nlu_parse
+
+
+# ---------------------------------------------------------------------------
+# Model loading (lazy, cached)
+# ---------------------------------------------------------------------------
+_asr_model = None
+_asr_processor = None
+_tts_model = None
+_tts_tokenizer = None
+
+
+def load_asr():
+    global _asr_model, _asr_processor
+    if _asr_model is None:
+        print("Loading Whisper-small…")
+        _asr_processor = WhisperProcessor.from_pretrained("openai/whisper-small")
+        _asr_model = WhisperForConditionalGeneration.from_pretrained("openai/whisper-small")
+        _asr_model.eval()
+        print("Whisper-small ready.")
+    return _asr_model, _asr_processor
+
+
+def load_tts():
+    global _tts_model, _tts_tokenizer
+    if _tts_model is None:
+        print("Loading MMS-TTS Hausa…")
+        _tts_model = VitsModel.from_pretrained("facebook/mms-tts-hau")
+        _tts_tokenizer = AutoTokenizer.from_pretrained("facebook/mms-tts-hau")
+        _tts_model.eval()
+        print("MMS-TTS Hausa ready.")
+    return _tts_model, _tts_tokenizer
+
+
+def transcribe_hausa(audio_tuple) -> str:
+    """audio_tuple is (sample_rate, np.ndarray) from Gradio."""
+    if audio_tuple is None:
+        return ""
+    sample_rate, audio_array = audio_tuple
+    if audio_array is None or len(audio_array) == 0:
+        return ""
+    # Convert to float32 mono
+    if audio_array.dtype != np.float32:
+        audio_array = audio_array.astype(np.float32) / np.iinfo(audio_array.dtype).max
+    if audio_array.ndim > 1:
+        audio_array = audio_array.mean(axis=1)
+    # Cap at 30s — Whisper-small is trained on 30s chunks; longer audio
+    # would need windowing which slows the demo
+    max_samples = sample_rate * 30
+    if len(audio_array) > max_samples:
+        audio_array = audio_array[:max_samples]
+    # Resample to 16 kHz
+    if sample_rate != 16000:
+        import scipy.signal
+        num_samples = int(len(audio_array) * 16000 / sample_rate)
+        audio_array = scipy.signal.resample(audio_array, num_samples).astype(np.float32)
+
+    model, processor = load_asr()
+    inputs = processor(audio_array, sampling_rate=16000, return_tensors="pt")
+    forced_ids = processor.get_decoder_prompt_ids(language="hausa", task="transcribe")
+    with torch.no_grad():
+        ids = model.generate(inputs.input_features, forced_decoder_ids=forced_ids, max_new_tokens=128)
+    text = processor.batch_decode(ids, skip_special_tokens=True)[0].strip()
+    return text
+
+
+def synthesize_hausa(text: str) -> Optional[tuple]:
+    """Return (sample_rate, np.ndarray) or None."""
+    if not text.strip():
+        return None
+    model, tokenizer = load_tts()
+    inputs = tokenizer(text, return_tensors="pt")
+    with torch.no_grad():
+        out = model(**inputs).waveform
+    audio = out.squeeze().cpu().numpy().astype(np.float32)
+    return (model.config.sampling_rate, audio)
+
+
+# ---------------------------------------------------------------------------
+# Core turn handler
+# ---------------------------------------------------------------------------
+def run_turn(user_text: str, session: dict, trace: list, asr_ms: int = 0) -> tuple:
+    """
+    Executes one turn. Returns (bot_prompt_dict, updated_session, trace, tts_audio).
+    `session` is a serialized dict stored in gr.State.
+    """
+    state = DialogueState.from_dict(session) if session else None
+    if state is None:
+        state = DialogueState(session_id="sess_" + uuid.uuid4().hex[:8], vertical="bank")
+
+    turn_trace = []
+    if asr_ms:
+        turn_trace.append({"stage": "asr (whisper-small)", "ms": asr_ms,
+                           "detail": f'→ "{user_text}"'})
+
+    t0 = time.time()
+    expected = get_expected_slot(state.vertical, state.current_state)
+    intent, entities, nlu_source = nlu_parse(user_text, expected)
+    nlu_stage_label = {
+        "rule": "nlu (rule-based)",
+        "llm": "nlu (qwen2.5-1.5b)",
+        "rule_fallback": "nlu (rule + llm fallback)",
+    }.get(nlu_source, "nlu")
+    turn_trace.append({
+        "stage": nlu_stage_label,
+        "ms": max(1, int((time.time() - t0) * 1000)),
+        "detail": f"intent={intent}  entities={entities}",
+    })
+
+    t1 = time.time()
+    prev_state = state.current_state
+    state = transition(state, intent, entities)
+    turn_trace.append({
+        "stage": "dialogue_manager",
+        "ms": max(1, int((time.time() - t1) * 1000)),
+        "detail": f"{prev_state} → {state.current_state}",
+    })
+
+    t2 = time.time()
+    prompt = get_prompt(state.vertical, state.current_state)
+    turn_trace.append({"stage": "response_gen", "ms": max(1, int((time.time() - t2) * 1000))})
+
+    t3 = time.time()
+    audio = synthesize_hausa(prompt["ha"])
+    turn_trace.append({"stage": "tts (mms-tts-hau)", "ms": int((time.time() - t3) * 1000)})
+
+    state.history.append({"role": "user", "text": user_text})
+    state.history.append({"role": "bot", "text_ha": prompt["ha"], "text_en": prompt["en"]})
+
+    return prompt, state.to_dict(), turn_trace, audio
+
+
+# ---------------------------------------------------------------------------
+# WhatsApp-style HTML renderer
+# ---------------------------------------------------------------------------
+def render_whatsapp(session: dict, pending_user: Optional[str] = None,
+                     pending_is_voice: bool = False) -> str:
+    vertical = session.get("vertical", "bank") if session else "bank"
+    name = SCENARIOS[vertical]["name"]
+    avatar = {"bank": "PB", "telecom": "PT", "ecommerce": "PD"}[vertical]
+    escalated = session.get("escalate_to_human", False) if session else False
+
+    bubbles = []
+    history = session.get("history", []) if session else []
+    for msg in history:
+        if msg["role"] == "user":
+            is_voice = msg.get("is_voice", False)
+            bubbles.append(_user_bubble(msg["text"], is_voice))
+        else:
+            bubbles.append(_bot_bubble(msg.get("text_ha", ""), msg.get("text_en", "")))
+    if pending_user:
+        bubbles.append(_user_bubble(pending_user, pending_is_voice))
+
+    banner = ('<div class="pw-esc-banner">Session escalated to human agent</div>'
+              if escalated else "")
+
+    return f"""
+<div class="pw-phone">
+  <div class="pw-ph-header">
+    <div class="pw-ph-avatar">{avatar}</div>
+    <div>
+      <div class="pw-ph-name">{html_lib.escape(name)}</div>
+      <div class="pw-ph-status">online • voice agent</div>
+    </div>
+  </div>
+  <div class="pw-ph-messages">
+    {banner}
+    {"".join(bubbles) if bubbles else '<div style="text-align:center; color:#667781; font-size:12px; padding:40px 0;">Waiting for first message…</div>'}
+  </div>
+</div>
+<style>
+.pw-phone {{ max-width: 440px; margin: 0 auto; background: #ECE5DD; border-radius: 14px; overflow: hidden; border: 1px solid #ccc; display: flex; flex-direction: column; min-height: 520px; font-family: -apple-system, "Segoe UI", Roboto, sans-serif; }}
+.pw-ph-header {{ background: #075E54; color: #fff; padding: 10px 14px; display: flex; align-items: center; gap: 10px; }}
+.pw-ph-avatar {{ width: 36px; height: 36px; border-radius: 50%; background: #128C7E; display: flex; align-items: center; justify-content: center; font-weight: 500; font-size: 13px; color: #fff; }}
+.pw-ph-name {{ font-size: 14px; font-weight: 500; line-height: 1.2; }}
+.pw-ph-status {{ font-size: 11px; color: #D4EDE8; }}
+.pw-ph-messages {{ flex: 1; padding: 14px 10px; background: #ECE5DD; background-image: radial-gradient(#D8CFC2 1px, transparent 1px); background-size: 18px 18px; max-height: 460px; overflow-y: auto; min-height: 400px; }}
+.pw-b {{ max-width: 80%; padding: 7px 10px 5px; border-radius: 8px; margin-bottom: 6px; font-size: 13.5px; line-height: 1.4; color: #1f2d1f; word-wrap: break-word; }}
+.pw-b.user {{ background: #DCF8C6; margin-left: auto; border-bottom-right-radius: 2px; }}
+.pw-b.bot {{ background: #fff; margin-right: auto; border-bottom-left-radius: 2px; }}
+.pw-b-meta {{ font-size: 10px; color: #667781; margin-top: 3px; text-align: right; }}
+.pw-b-trans {{ font-size: 11px; color: #667781; font-style: italic; margin-top: 3px; border-top: 1px solid #E5E5E5; padding-top: 3px; }}
+.pw-voice-row {{ display: flex; align-items: center; gap: 8px; }}
+.pw-voice-icon {{ width: 22px; height: 22px; border-radius: 50%; background: #128C7E; color: #fff; font-size: 10px; display: flex; align-items: center; justify-content: center; }}
+.pw-voice-bars {{ flex: 1; height: 14px; display: flex; align-items: center; gap: 2px; }}
+.pw-voice-bars span {{ flex: 1; background: #8D9A9F; border-radius: 1px; }}
+.pw-esc-banner {{ background: #FAEEDA; color: #854F0B; font-size: 12px; padding: 8px 12px; border-radius: 8px; margin-bottom: 10px; border: 1px solid #EF9F27; text-align: center; }}
+</style>
+"""
+
+
+def _now() -> str:
+    return time.strftime("%H:%M")
+
+
+def _user_bubble(text: str, is_voice: bool) -> str:
+    text_safe = html_lib.escape(text)
+    if is_voice:
+        bars = "".join(
+            f'<span style="height:{4 + int(8 * abs(np.sin(i * 0.7)))}px;"></span>'
+            for i in range(20)
+        )
+        return f'''<div class="pw-b user">
+  <div class="pw-voice-row">
+    <div class="pw-voice-icon">▶</div>
+    <div class="pw-voice-bars">{bars}</div>
+  </div>
+  <div style="font-size:12px; color:#667781; margin-top:3px;">"{text_safe}"</div>
+  <div class="pw-b-meta">{_now()} ✓✓</div>
+</div>'''
+    return f'<div class="pw-b user">{text_safe}<div class="pw-b-meta">{_now()} ✓✓</div></div>'
+
+
+def _bot_bubble(text_ha: str, text_en: str) -> str:
+    ha_safe = html_lib.escape(text_ha)
+    en_safe = html_lib.escape(text_en)
+    return f'''<div class="pw-b bot">
+  <div>{ha_safe}</div>
+  <div class="pw-b-trans">{en_safe}</div>
+  <div class="pw-b-meta">{_now()} ✓✓</div>
+</div>'''
+
+
+def render_trace(trace: list) -> str:
+    if not trace:
+        return '<div style="color:#888; font-size:13px;">Send a message to see the pipeline trace.</div>'
+    rows = []
+    for r in trace:
+        row = f'<div style="display:flex; justify-content:space-between; padding:5px 0; border-bottom:1px solid #eee;"><span style="color:#5f5e5a;">{html_lib.escape(r["stage"])}</span><span style="color:#0C447C; font-weight:500;">{r["ms"]}ms</span></div>'
+        rows.append(row)
+        if r.get("detail"):
+            rows.append(f'<div style="font-size:11px; color:#888; padding:0 0 5px; font-family:monospace;">{html_lib.escape(str(r["detail"]))}</div>')
+    return f'<div style="font-family:monospace; font-size:12px;">{"".join(rows)}</div>'
+
+
+def render_metrics(session: dict) -> str:
+    if not session:
+        return ""
+    sid = session.get("session_id", "—")
+    turn = session.get("turn_count", 0)
+    state = session.get("current_state", "greeting")
+    slots = session.get("slots", {})
+    slots_html = ", ".join(f"<code>{k}={v}</code>" for k, v in slots.items()) or "—"
+    return f'''
+<div style="display:grid; grid-template-columns:1fr 1fr; gap:8px; font-size:13px;">
+  <div><div style="color:#888; font-size:11px; text-transform:uppercase;">Session</div><div style="font-family:monospace;">{sid}</div></div>
+  <div><div style="color:#888; font-size:11px; text-transform:uppercase;">Turn</div><div style="font-weight:500;">{turn}</div></div>
+  <div><div style="color:#888; font-size:11px; text-transform:uppercase;">State</div><div style="font-family:monospace;">{state}</div></div>
+  <div><div style="color:#888; font-size:11px; text-transform:uppercase;">Slots</div><div>{slots_html}</div></div>
+</div>'''
+
+
+# ---------------------------------------------------------------------------
+# Gradio event handlers
+# ---------------------------------------------------------------------------
+def on_vertical_change(vertical: str, synth_greeting: bool = False):
+    """Reset session when vertical changes. TTS the greeting only on first real
+    user interaction — keeps initial page load fast (avoids MMS-TTS cold-start)."""
+    state = DialogueState(session_id="sess_" + uuid.uuid4().hex[:8], vertical=vertical)
+    greet = get_prompt(vertical, "greeting")
+    state.history.append({"role": "bot", "text_ha": greet["ha"], "text_en": greet["en"]})
+    session = state.to_dict()
+    audio = None
+    if synth_greeting:
+        try:
+            audio = synthesize_hausa(greet["ha"])
+        except Exception as e:
+            print(f"TTS failed on greeting: {e}")
+    return (
+        session,
+        render_whatsapp(session),
+        render_trace([]),
+        render_metrics(session),
+        audio,
+    )
+
+
+def on_text_submit(text: str, session: dict):
+    if not text or not text.strip():
+        return session, render_whatsapp(session), render_trace([]), render_metrics(session), None, ""
+    prompt, new_session, trace, audio = run_turn(text, session, [], asr_ms=0)
+    return (
+        new_session,
+        render_whatsapp(new_session),
+        render_trace(trace),
+        render_metrics(new_session),
+        audio,
+        "",  # clear input
+    )
+
+
+def on_audio_submit(audio_data, session: dict):
+    if audio_data is None:
+        return session, render_whatsapp(session), render_trace([]), render_metrics(session), None
+    t0 = time.time()
+    try:
+        text = transcribe_hausa(audio_data)
+    except Exception as e:
+        print(f"ASR failed: {e}")
+        return session, render_whatsapp(session), render_trace([{"stage": "asr error", "ms": 0, "detail": str(e)}]), render_metrics(session), None
+    asr_ms = int((time.time() - t0) * 1000)
+    if not text:
+        return session, render_whatsapp(session), render_trace([{"stage": "asr", "ms": asr_ms, "detail": "(no speech detected)"}]), render_metrics(session), None
+    # Mark last user message as voice after appending
+    prompt, new_session, trace, audio = run_turn(text, session, [], asr_ms=asr_ms)
+    # Tag the last user entry as voice
+    if new_session.get("history"):
+        for i in range(len(new_session["history"]) - 1, -1, -1):
+            if new_session["history"][i]["role"] == "user":
+                new_session["history"][i]["is_voice"] = True
+                break
+    return (
+        new_session,
+        render_whatsapp(new_session),
+        render_trace(trace),
+        render_metrics(new_session),
+        audio,
+    )
+
+
+def on_reset(session: dict):
+    vertical = session.get("vertical", "bank") if session else "bank"
+    return on_vertical_change(vertical)
+
+
+def on_escalate(session: dict):
+    return on_text_submit("Ina son wakili mutum", session)
+
+
+# ---------------------------------------------------------------------------
+# Preset phrases for quick-click demo
+# ---------------------------------------------------------------------------
+PRESETS = {
+    "bank": ["duba ma'auni", "toshe kati", "canjin kuɗi", "1234", "Aisha", "dubu biyar", "i"],
+    "telecom": ["saya airtime", "saya bundle", "korafi", "1000", "rana", "Intanet bai aiki"],
+    "ecommerce": ["bincika oda", "sake tsara", "mayar da kaya", "10234", "jumma'a", "Ya lalace"],
+}
+
+
+# ---------------------------------------------------------------------------
+# Gradio UI
+# ---------------------------------------------------------------------------
+CUSTOM_CSS = """
+.gradio-container { max-width: 1200px !important; }
+#vertical-selector { background: #fff; border-radius: 10px; padding: 12px; }
+#whatsapp-html { background: #f5f4ef; border-radius: 12px; padding: 20px; }
+#trace-box, #metrics-box { background: #fff; border-radius: 10px; padding: 12px; border: 1px solid #e5e5e5; }
+h1 { font-size: 22px !important; font-weight: 500 !important; }
+.header-sub { color: #5f5e5a; font-size: 14px; margin-top: -8px; margin-bottom: 16px; }
+"""
+
+with gr.Blocks(css=CUSTOM_CSS, title="PlotWeaver Voice Agent") as demo:
+    gr.HTML("""
+    <h1 style="margin-bottom:4px;">PlotWeaver Voice Agent</h1>
+    <p class="header-sub">Hausa-first conversational AI for African banks, telecoms, and delivery services. Real Whisper-small ASR and MMS-TTS Hausa running on CPU.</p>
+    """)
+
+    session_state = gr.State({})
+
+    with gr.Row():
+        # Left column: controls + trace
+        with gr.Column(scale=1):
+            gr.Markdown("### Select vertical")
+            vertical_radio = gr.Radio(
+                choices=[("PlotWeaver Bank", "bank"),
+                         ("PlotWeaver Telecom", "telecom"),
+                         ("PlotWeaver Delivery", "ecommerce")],
+                value="bank",
+                label="",
+                elem_id="vertical-selector",
+            )
+
+            with gr.Row():
+                reset_btn = gr.Button("Reset session", size="sm")
+                escalate_btn = gr.Button("Force escalate", size="sm")
+
+            gr.Markdown("### Session metrics")
+            metrics_html = gr.HTML(elem_id="metrics-box")
+
+            gr.Markdown("### Pipeline trace (last turn)")
+            trace_html = gr.HTML(elem_id="trace-box")
+
+        # Middle column: WhatsApp mockup
+        with gr.Column(scale=2):
+            whatsapp_html = gr.HTML(elem_id="whatsapp-html")
+
+            with gr.Row():
+                text_input = gr.Textbox(
+                    placeholder="Type in Hausa… e.g. 'duba ma'auni'",
+                    label="",
+                    scale=4,
+                    container=False,
+                )
+                send_btn = gr.Button("Send", scale=1, variant="primary")
+
+            gr.Markdown("**Or speak / upload audio in Hausa:**")
+            audio_input = gr.Audio(
+                sources=["microphone", "upload"],
+                type="numpy",
+                label="Record or upload a Hausa audio file (.wav, .mp3, .ogg)",
+                show_download_button=False,
+            )
+            with gr.Row():
+                transcribe_btn = gr.Button("Transcribe & send", variant="secondary", size="sm")
+                clear_audio_btn = gr.Button("Clear", size="sm")
+
+            bot_audio = gr.Audio(
+                label="Bot response (Hausa TTS)",
+                autoplay=True,
+                interactive=False,
+            )
+
+            # Preset quick-clicks
+            gr.Markdown("### Quick phrases (Hausa)")
+            preset_btns = []
+            with gr.Row():
+                for p in PRESETS["bank"]:
+                    preset_btns.append(gr.Button(p, size="sm"))
+
+    # -----------------------------------------------------------------------
+    # Event wiring
+    # -----------------------------------------------------------------------
+    outputs = [session_state, whatsapp_html, trace_html, metrics_html, bot_audio]
+
+    demo.load(
+        fn=lambda: on_vertical_change("bank"),
+        outputs=outputs,
+    )
+
+    vertical_radio.change(
+        fn=on_vertical_change,
+        inputs=[vertical_radio],
+        outputs=outputs,
+    )
+
+    send_btn.click(
+        fn=on_text_submit,
+        inputs=[text_input, session_state],
+        outputs=outputs + [text_input],
+    )
+    text_input.submit(
+        fn=on_text_submit,
+        inputs=[text_input, session_state],
+        outputs=outputs + [text_input],
+    )
+
+    audio_input.stop_recording(
+        fn=on_audio_submit,
+        inputs=[audio_input, session_state],
+        outputs=outputs,
+    )
+    transcribe_btn.click(
+        fn=on_audio_submit,
+        inputs=[audio_input, session_state],
+        outputs=outputs,
+    )
+    clear_audio_btn.click(
+        fn=lambda: None,
+        outputs=[audio_input],
+    )
+
+    reset_btn.click(fn=on_reset, inputs=[session_state], outputs=outputs)
+    escalate_btn.click(
+        fn=on_escalate,
+        inputs=[session_state],
+        outputs=outputs + [text_input],
+    )
+
+    # Preset buttons submit their own text
+    for btn, phrase in zip(preset_btns, PRESETS["bank"]):
+        btn.click(
+            fn=lambda s, _phrase=phrase: on_text_submit(_phrase, s),
+            inputs=[session_state],
+            outputs=outputs + [text_input],
+        )
+
+
+if __name__ == "__main__":
+    demo.launch()

dialogue.py

@@ -0,0 +1,237 @@
+"""
+PlotWeaver Voice Agent — Dialogue Manager
+==========================================
+FSM for multi-turn Hausa conversations across 3 verticals.
+State lives in Gradio session state (dict) — no Redis needed in the Space.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from typing import Optional
+
+
+class Vertical(str, Enum):
+    BANK = "bank"
+    TELECOM = "telecom"
+    ECOMMERCE = "ecommerce"
+
+
+@dataclass
+class DialogueState:
+    session_id: str
+    vertical: str
+    current_state: str = "greeting"
+    slots: dict = field(default_factory=dict)
+    turn_count: int = 0
+    escalate_to_human: bool = False
+    history: list = field(default_factory=list)
+
+    def to_dict(self):
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(**d) if d else None
+
+
+SCENARIOS = {
+    "bank": {
+        "name": "PlotWeaver Bank",
+        "states": {
+            "greeting": {
+                "ha": "Sannu! Wannan shine mataimakin banki na PlotWeaver. Yaya zan taimake ka yau? Za ka iya ce 'duba ma'auni', 'toshe kati', ko 'canjin kuɗi'.",
+                "en": "Hello! This is the PlotWeaver banking assistant. How can I help you today? You can say 'check balance', 'block card', or 'transfer money'.",
+                "expects": "intent",
+                "transitions": {"check_balance": "ask_account_number", "block_card": "confirm_block_card", "transfer_money": "ask_recipient"},
+            },
+            "ask_account_number": {
+                "ha": "Don Allah ka faɗi lambobin ƙarshe huɗu na asusunka.",
+                "en": "Please say the last four digits of your account number.",
+                "expects": "digits",
+                "transitions": {"provide_digits": "return_balance"},
+            },
+            "return_balance": {
+                "ha": "Ma'aunin asusunka shine Naira dubu ɗari biyu da arba'in da biyar. Akwai wani abu?",
+                "en": "Your account balance is two hundred forty-five thousand Naira. Anything else?",
+                "expects": "yesno",
+                "transitions": {"yes": "greeting", "no": "exit"},
+            },
+            "confirm_block_card": {
+                "ha": "Don tabbatar, kana son toshe katinka? Ka ce 'i' ko 'a'a'.",
+                "en": "To confirm, you want to block your card? Say 'yes' or 'no'.",
+                "expects": "yesno",
+                "transitions": {"yes": "card_blocked", "no": "greeting"},
+            },
+            "card_blocked": {
+                "ha": "An toshe katinka. Sabon kati zai iso a cikin kwanaki uku zuwa biyar. Ana juya ka ga wakili don tabbatar.",
+                "en": "Your card is blocked. A new card will arrive in 3-5 days. Transferring you to an agent for confirmation.",
+                "expects": None, "terminal": True, "escalate": True,
+            },
+            "ask_recipient": {
+                "ha": "Zuwa wa kake son turawa? Ka faɗi sunan mai karɓa.",
+                "en": "Who do you want to transfer to? Say the recipient's name.",
+                "expects": "name",
+                "transitions": {"provide_name": "ask_amount"},
+            },
+            "ask_amount": {
+                "ha": "Nawa kake son turawa, a Naira?",
+                "en": "How much do you want to transfer, in Naira?",
+                "expects": "amount",
+                "transitions": {"provide_amount": "confirm_transfer"},
+            },
+            "confirm_transfer": {
+                "ha": "Zan tura kuɗin yanzu. Ka ce 'i' don ci gaba.",
+                "en": "I'll send the money now. Say 'yes' to continue.",
+                "expects": "yesno",
+                "transitions": {"yes": "transfer_done", "no": "greeting"},
+            },
+            "transfer_done": {
+                "ha": "An tura kuɗin. Godiya da zabar PlotWeaver Bank.",
+                "en": "Money sent. Thank you for choosing PlotWeaver Bank.",
+                "expects": None, "terminal": True,
+            },
+        },
+    },
+    "telecom": {
+        "name": "PlotWeaver Telecom",
+        "states": {
+            "greeting": {
+                "ha": "Sannu! Wannan shine PlotWeaver Telecom. Kana son 'saya airtime', 'saya bundle', ko 'yin korafi'?",
+                "en": "Hello! This is PlotWeaver Telecom. Would you like to 'buy airtime', 'buy bundle', or 'file a complaint'?",
+                "expects": "intent",
+                "transitions": {"buy_airtime": "ask_airtime_amount", "buy_bundle": "ask_bundle_type", "complaint": "ask_complaint"},
+            },
+            "ask_airtime_amount": {
+                "ha": "Nawa na airtime kake son saya? Misali, Naira ɗari ko dubu.",
+                "en": "How much airtime? For example 100 or 1000 Naira.",
+                "expects": "amount",
+                "transitions": {"provide_amount": "airtime_done"},
+            },
+            "airtime_done": {
+                "ha": "An kara airtime. Ma'aunin ka sabo shine Naira dubu ɗaya da ɗari biyar.",
+                "en": "Airtime loaded. Your new balance is 1500 Naira.",
+                "expects": None, "terminal": True,
+            },
+            "ask_bundle_type": {
+                "ha": "Wane irin bundle? Muna da 'rana', 'mako', ko 'wata'.",
+                "en": "Which bundle type? 'day', 'week', or 'month'.",
+                "expects": "bundle",
+                "transitions": {"provide_bundle": "bundle_done"},
+            },
+            "bundle_done": {
+                "ha": "An kunna bundle ɗinka. Za ka iya yin amfani da shi yanzu.",
+                "en": "Your bundle is active. You can use it now.",
+                "expects": None, "terminal": True,
+            },
+            "ask_complaint": {
+                "ha": "Me ya faru? Ka bayyana matsalar da kake fuskanta.",
+                "en": "What happened? Please describe the issue.",
+                "expects": "text",
+                "transitions": {"provide_text": "escalate"},
+            },
+            "escalate": {
+                "ha": "Nagode. Zan juya ka ga wakili na mutum yanzu.",
+                "en": "Thank you. I'll transfer you to a human agent now.",
+                "expects": None, "terminal": True, "escalate": True,
+            },
+        },
+    },
+    "ecommerce": {
+        "name": "PlotWeaver Delivery",
+        "states": {
+            "greeting": {
+                "ha": "Sannu! Wannan shine PlotWeaver Delivery. Kana son 'bincika oda', 'sake tsara lokaci', ko 'mayar da kaya'?",
+                "en": "Hello! This is PlotWeaver Delivery. Would you like to 'check order', 'reschedule', or 'return'?",
+                "expects": "intent",
+                "transitions": {"check_order": "ask_order_id", "reschedule": "ask_order_id_reschedule", "return_item": "ask_order_id_return"},
+            },
+            "ask_order_id": {
+                "ha": "Ka faɗi lambar oda naka.",
+                "en": "Say your order number.",
+                "expects": "digits",
+                "transitions": {"provide_digits": "order_status"},
+            },
+            "order_status": {
+                "ha": "Oda ɗinka yana kan hanya. Za a isar gobe da yamma.",
+                "en": "Your order is on the way. It will be delivered tomorrow evening.",
+                "expects": None, "terminal": True,
+            },
+            "ask_order_id_reschedule": {
+                "ha": "Ka faɗi lambar oda da kake son sake tsarawa.",
+                "en": "Say the order number you want to reschedule.",
+                "expects": "digits",
+                "transitions": {"provide_digits": "ask_new_date"},
+            },
+            "ask_new_date": {
+                "ha": "Wace rana kake so? Misali 'jumma'a' ko 'asabar'.",
+                "en": "Which day? For example 'Friday' or 'Saturday'.",
+                "expects": "date",
+                "transitions": {"provide_date": "reschedule_done"},
+            },
+            "reschedule_done": {
+                "ha": "An sake tsara isar. Za ka sami SMS na tabbatarwa.",
+                "en": "Delivery rescheduled. You'll receive a confirmation SMS.",
+                "expects": None, "terminal": True,
+            },
+            "ask_order_id_return": {
+                "ha": "Ka faɗi lambar oda da kake son mayarwa.",
+                "en": "Say the order number you want to return.",
+                "expects": "digits",
+                "transitions": {"provide_digits": "return_reason"},
+            },
+            "return_reason": {
+                "ha": "Me ya sa kake son mayarwa?",
+                "en": "Why do you want to return it?",
+                "expects": "text",
+                "transitions": {"provide_reason": "return_done"},
+            },
+            "return_done": {
+                "ha": "An karɓi buƙatarka. Wakili zai tattara kaya a gobe.",
+                "en": "Your request is received. An agent will collect the item tomorrow.",
+                "expects": None, "terminal": True,
+            },
+        },
+    },
+}
+
+
+def get_prompt(vertical: str, state_name: str) -> dict:
+    if state_name == "escalate_virtual":
+        return {"ha": "Zan juya ka ga wakili na mutum yanzu. Ka jira ɗan lokaci.",
+                "en": "I'll transfer you to a human agent now. Please hold."}
+    if state_name == "exit":
+        return {"ha": "Nagode. Sai watan.", "en": "Thank you. Goodbye."}
+    s = SCENARIOS[vertical]["states"].get(state_name)
+    if not s:
+        return {"ha": "Ban fahimci abin da ka ce ba.", "en": "I didn't understand."}
+    return {"ha": s["ha"], "en": s["en"]}
+
+
+def get_expected_slot(vertical: str, state_name: str) -> Optional[str]:
+    s = SCENARIOS[vertical]["states"].get(state_name)
+    return s.get("expects") if s else None
+
+
+def transition(state: DialogueState, intent: str, entities: dict) -> DialogueState:
+    state.turn_count += 1
+    for k, v in entities.items():
+        state.slots[k] = v
+
+    if intent == "human_agent" or state.turn_count > 12:
+        state.current_state = "escalate_virtual"
+        state.escalate_to_human = True
+        return state
+
+    current = SCENARIOS[state.vertical]["states"].get(state.current_state)
+    if not current:
+        state.current_state = "greeting"
+        return state
+
+    next_state = current.get("transitions", {}).get(intent)
+    if next_state:
+        state.current_state = next_state
+        target = SCENARIOS[state.vertical]["states"].get(next_state, {})
+        if target.get("escalate"):
+            state.escalate_to_human = True
+
+    return state

requirements.txt

@@ -0,0 +1,8 @@
+gradio==4.44.1
+transformers==4.46.2
+torch==2.2.2
+torchaudio==2.2.2
+accelerate==0.34.2
+numpy==1.26.4
+scipy==1.13.1
+sentencepiece==0.2.0