Upload 5 files

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

nlu.py

@@ -0,0 +1,310 @@
+"""
+NLU — Hybrid Hausa intent + entity extraction.
+
+Three-tier architecture:
+  1. Rule-based keyword matcher (fast path, ~80% of demo utterances)
+  2. Qwen2.5-1.5B-Instruct zero-shot JSON extractor (paraphrases, novel phrasings)
+  3. Rule-based fallback (if LLM fails or returns unparseable output)
+
+The LLM is lazy-loaded on first non-matched utterance so the Space boots fast.
+In production this would be replaced with a fine-tuned classifier on
+PlotWeaver's Hausa intent corpus.
+"""
+from __future__ import annotations
+import re
+import json
+import logging
+from typing import Optional
+
+logger = logging.getLogger("plotweaver.nlu")
+
+# ---------------------------------------------------------------------------
+# Layer 1: rule-based fast path (covers common demo phrases)
+# ---------------------------------------------------------------------------
+INTENT_KEYWORDS = {
+    "check_balance": ["duba", "ma'auni", "balance", "kudi", "asusu"],
+    "block_card": ["toshe", "kati", "block"],
+    "transfer_money": ["tura", "canji", "canjin", "aika", "transfer"],
+    "buy_airtime": ["airtime", "caji"],
+    "buy_bundle": ["bundle", "data", "intanet"],
+    "complaint": ["korafi", "matsala", "complain"],
+    "check_order": ["bincika", "order", "oda"],
+    "reschedule": ["sake tsara", "reschedule", "canja lokaci"],
+    "return_item": ["mayar", "mayarwa", "return"],
+    "human_agent": ["mutum", "wakili", "agent", "human"],
+    "yes": ["i ", " i", "eh", "haka ne", "yes", "ok", "okay"],
+    "no": ["a'a", "a'aa", "ba haka", " no", "no "],
+}
+
+WORD_DIGITS = {
+    "sifili": "0", "daya": "1", "ɗaya": "1", "biyu": "2", "uku": "3",
+    "hudu": "4", "huɗu": "4", "biyar": "5", "shida": "6", "bakwai": "7",
+    "takwas": "8", "tara": "9",
+}
+
+WORD_AMOUNTS = {
+    "dubu goma": 10000, "dubu biyar": 5000, "dubu biyu": 2000,
+    "dubu": 1000, "ɗari biyar": 500, "dari biyar": 500,
+    "ɗari": 100, "dari": 100,
+}
+
+
+def _norm(t: str) -> str:
+    return " " + t.lower().strip() + " "
+
+
+def _match_intent_kw(text: str) -> Optional[str]:
+    t = _norm(text)
+    for intent, kws in INTENT_KEYWORDS.items():
+        for kw in kws:
+            if kw in t:
+                return intent
+    return None
+
+
+def _extract_digits(text: str) -> Optional[str]:
+    m = re.findall(r"\d+", text)
+    if m:
+        return "".join(m)
+    tokens = text.lower().split()
+    d = [WORD_DIGITS[tok] for tok in tokens if tok in WORD_DIGITS]
+    return "".join(d) if d else None
+
+
+def _extract_amount(text: str) -> Optional[int]:
+    m = re.search(r"\d+", text)
+    if m:
+        return int(m.group())
+    t = text.lower()
+    for phrase in sorted(WORD_AMOUNTS.keys(), key=len, reverse=True):
+        if phrase in t:
+            return WORD_AMOUNTS[phrase]
+    return None
+
+
+def _rule_based_parse(text: str, expected: Optional[str]) -> tuple[str, dict]:
+    """Layer 1 + 3: deterministic keyword + slot matcher."""
+    entities: dict = {}
+    if not text or not text.strip():
+        return "unknown", entities
+
+    # Universal escape
+    if _match_intent_kw(text) == "human_agent":
+        return "human_agent", entities
+
+    if expected == "digits":
+        d = _extract_digits(text)
+        if d:
+            entities["digits"] = d
+            return "provide_digits", entities
+
+    if expected == "amount":
+        a = _extract_amount(text)
+        if a is not None:
+            entities["amount"] = a
+            return "provide_amount", entities
+
+    if expected == "name":
+        name = text.strip().split()[-1] if text.strip() else ""
+        if name:
+            entities["name"] = name
+            return "provide_name", entities
+
+    if expected == "date":
+        entities["date"] = text.strip()
+        return "provide_date", entities
+
+    if expected == "bundle":
+        t = text.lower()
+        for b in ("rana", "mako", "wata"):
+            if b in t:
+                entities["bundle"] = b
+                return "provide_bundle", entities
+
+    if expected == "text":
+        entities["text"] = text.strip()
+        return "provide_text", entities
+
+    if expected == "yesno":
+        i = _match_intent_kw(text)
+        if i in ("yes", "no"):
+            return i, entities
+
+    i = _match_intent_kw(text)
+    if i:
+        return i, entities
+
+    return "unknown", entities
+
+
+# ---------------------------------------------------------------------------
+# Layer 2: Qwen2.5-1.5B-Instruct zero-shot NLU
+# ---------------------------------------------------------------------------
+_llm_model = None
+_llm_tokenizer = None
+_llm_failed = False  # set to True after any load failure, to prevent retries
+
+
+def _load_llm():
+    """Lazy-load Qwen2.5-1.5B-Instruct. Called only when rule-based misses."""
+    global _llm_model, _llm_tokenizer, _llm_failed
+    if _llm_failed:
+        return None, None
+    if _llm_model is not None:
+        return _llm_model, _llm_tokenizer
+    try:
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+        logger.info("Loading Qwen2.5-1.5B-Instruct for NLU…")
+        model_id = "Qwen/Qwen2.5-1.5B-Instruct"
+        _llm_tokenizer = AutoTokenizer.from_pretrained(model_id)
+        _llm_model = AutoModelForCausalLM.from_pretrained(
+            model_id,
+            torch_dtype=torch.float32,  # CPU — bfloat16 not broadly supported
+            low_cpu_mem_usage=True,
+        )
+        _llm_model.eval()
+        logger.info("Qwen2.5-1.5B-Instruct ready.")
+        return _llm_model, _llm_tokenizer
+    except Exception as e:
+        logger.warning(f"LLM load failed: {e}")
+        _llm_failed = True
+        return None, None
+
+
+# Candidate intents per expected-slot context. Keeps the LLM prompt small
+# and constrains output to valid options only.
+CANDIDATE_INTENTS = {
+    None: ["check_balance", "block_card", "transfer_money",
+           "buy_airtime", "buy_bundle", "complaint",
+           "check_order", "reschedule", "return_item",
+           "human_agent", "unknown"],
+    "intent": ["check_balance", "block_card", "transfer_money",
+               "buy_airtime", "buy_bundle", "complaint",
+               "check_order", "reschedule", "return_item",
+               "human_agent", "unknown"],
+    "yesno": ["yes", "no", "human_agent", "unknown"],
+    "digits": ["provide_digits", "human_agent", "unknown"],
+    "amount": ["provide_amount", "human_agent", "unknown"],
+    "name": ["provide_name", "human_agent", "unknown"],
+    "date": ["provide_date", "human_agent", "unknown"],
+    "bundle": ["provide_bundle", "human_agent", "unknown"],
+    "text": ["provide_text", "human_agent", "unknown"],
+}
+
+
+SYSTEM_PROMPT = """You are an intent classifier for a Hausa-language customer service voice agent.
+
+Analyze the user's Hausa utterance and return a JSON object with:
+- "intent": one of the candidate intents provided
+- "entities": a dict of extracted values (may be empty)
+
+Intent meanings:
+- check_balance: user wants to check their account balance
+- block_card: user wants to block or freeze their bank card
+- transfer_money: user wants to transfer or send money
+- buy_airtime: user wants to buy phone airtime
+- buy_bundle: user wants to buy a data bundle
+- complaint: user wants to file a complaint
+- check_order: user wants to check an order status
+- reschedule: user wants to reschedule a delivery
+- return_item: user wants to return an item
+- human_agent: user wants to speak to a human
+- yes / no: affirmative or negative response
+- provide_digits / provide_amount / provide_name / provide_date / provide_bundle / provide_text: user is providing specific information
+- unknown: cannot determine the intent
+
+Return ONLY a valid JSON object, no explanation. Example: {"intent": "check_balance", "entities": {}}"""
+
+
+def _llm_parse(text: str, expected: Optional[str]) -> Optional[tuple[str, dict]]:
+    """Layer 2: zero-shot LLM classification. Returns None on any failure."""
+    model, tokenizer = _load_llm()
+    if model is None:
+        return None
+
+    candidates = CANDIDATE_INTENTS.get(expected, CANDIDATE_INTENTS[None])
+    user_prompt = (
+        f'Hausa utterance: "{text}"\n'
+        f'Expected slot type: {expected or "any"}\n'
+        f'Candidate intents: {", ".join(candidates)}\n\n'
+        'Respond with JSON only.'
+    )
+    messages = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": user_prompt},
+    ]
+    try:
+        import torch
+        prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+        inputs = tokenizer(prompt, return_tensors="pt")
+        with torch.no_grad():
+            out = model.generate(
+                **inputs,
+                max_new_tokens=80,
+                do_sample=False,
+                pad_token_id=tokenizer.eos_token_id,
+            )
+        generated = tokenizer.decode(out[0][inputs.input_ids.shape[1]:], skip_special_tokens=True).strip()
+        logger.info(f"LLM raw output: {generated}")
+
+        # Extract JSON (model sometimes wraps it in markdown fences or prose)
+        m = re.search(r"\{.*?\}", generated, re.DOTALL)
+        if not m:
+            return None
+        parsed = json.loads(m.group())
+        intent = parsed.get("intent", "unknown")
+        entities = parsed.get("entities", {}) or {}
+        if not isinstance(entities, dict):
+            entities = {}
+        # Validate intent is in candidate list
+        if intent not in candidates:
+            logger.info(f"LLM returned out-of-candidate intent: {intent}")
+            return None
+        return intent, entities
+    except Exception as e:
+        logger.warning(f"LLM inference failed: {e}")
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+def parse(text: str, expected: Optional[str] = None,
+          use_llm: bool = True) -> tuple[str, dict, str]:
+    """
+    Hybrid NLU. Returns (intent, entities, source) where source is one of
+    'rule', 'llm', or 'rule_fallback'.
+
+    Flow:
+      1. Try rule-based keyword/slot matcher (fast, deterministic)
+      2. If result is 'unknown' AND use_llm=True: try Qwen2.5 zero-shot
+      3. If LLM fails or returns invalid output: return rule-based 'unknown'
+    """
+    intent, entities = _rule_based_parse(text, expected)
+
+    if intent != "unknown":
+        return intent, entities, "rule"
+
+    if not use_llm:
+        return intent, entities, "rule"
+
+    # Rule-based missed — try LLM
+    llm_result = _llm_parse(text, expected)
+    if llm_result is None:
+        return intent, entities, "rule_fallback"
+
+    llm_intent, llm_entities = llm_result
+
+    # Sanity-check entities for slot-typed expected (LLM might hallucinate
+    # digits; re-run our deterministic extractors for strict-format slots)
+    if expected == "digits":
+        d = _extract_digits(text)
+        if d:
+            llm_entities["digits"] = d
+    elif expected == "amount":
+        a = _extract_amount(text)
+        if a is not None:
+            llm_entities["amount"] = a
+
+    return llm_intent, llm_entities, "llm"

requirements.txt

@@ -0,0 +1,7 @@
+transformers==4.48.0
+torch==2.5.1
+accelerate==1.2.1
+numpy==2.1.3
+scipy==1.15.0
+sentencepiece==0.2.0
+audioop-lts==0.2.2