Upload 5 files

README.md

@@ -1,12 +1,39 @@
 ---
-title: Voice AI Agent Clean
-emoji: 👁
-colorFrom: purple
-colorTo: purple
+title: PlotWeaver Voice Agent
+emoji: 🗣️
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 6.13.0
+sdk_version: 6.12.0
 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 — rule-based keyword matcher (fast path) + Qwen2.5-1.5B-Instruct (zero-shot fallback for paraphrases)
+- **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. Type a Hausa phrase, record with microphone, or upload audio
+3. The bot's audio response autoplays
+
+**Sample bank flow**: Type `duba ma'auni` → then `1234` → bot returns balance.
+
+**Escalation**: Say "mutum" or "wakili" at any time to flag human handoff.
+
+## Notes
+
+First turn cold-starts ASR + TTS (~640 MB download). Qwen2.5-1.5B (~3 GB) only loads when rule-based NLU misses. Subsequent turns: 5-10s on CPU.
+
+This is a POC. Production plan: fine-tuned Hausa Whisper, fine-tuned AfroXLMR NLU (replacing the LLM tier), live WhatsApp Business Cloud integration, Twilio Voice.

app.py

@@ -0,0 +1,344 @@
+"""
+PlotWeaver Voice Agent — HuggingFace Space (Gradio 6 + Python 3.13)
+====================================================================
+Hausa-first conversational AI for African banks, telecoms, and delivery.
+
+Pipeline (all real, running on CPU):
+  ASR  (openai/whisper-small)
+    → NLU (rule-based + Qwen2.5-1.5B-Instruct fallback, see nlu.py)
+    → Dialogue FSM (see dialogue.py)
+    → TTS  (facebook/mms-tts-hau)
+
+First turn: ~30-60s model downloads. Subsequent turns: ~5-10s on CPU.
+"""
+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:
+    if audio_tuple is None:
+        return ""
+    sample_rate, audio_array = audio_tuple
+    if audio_array is None or len(audio_array) == 0:
+        return ""
+    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 training chunk size)
+    max_samples = sample_rate * 30
+    if len(audio_array) > max_samples:
+        audio_array = audio_array[:max_samples]
+    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]:
+    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)
+
+
+# ---------------------------------------------------------------------------
+# WhatsApp-style HTML rendering
+# ---------------------------------------------------------------------------
+def _now() -> str:
+    return time.strftime("%H:%M")
+
+
+def _user_bubble(text: str, is_voice: bool) -> str:
+    t = 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;">"{t}"</div>
+  <div class="pw-b-meta">{_now()} ✓✓</div>
+</div>'''
+    return f'<div class="pw-b user">{t}<div class="pw-b-meta">{_now()} ✓✓</div></div>'
+
+
+def _bot_bubble(text_ha: str, text_en: str) -> str:
+    ha = html_lib.escape(text_ha)
+    en = html_lib.escape(text_en)
+    return f'''<div class="pw-b bot">
+  <div>{ha}</div>
+  <div class="pw-b-trans">{en}</div>
+  <div class="pw-b-meta">{_now()} ✓✓</div>
+</div>'''
+
+
+def render_whatsapp(session: dict) -> 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 = []
+    for msg in session.get("history", []) if session else []:
+        if msg["role"] == "user":
+            bubbles.append(_user_bubble(msg["text"], msg.get("is_voice", False)))
+        else:
+            bubbles.append(_bot_bubble(msg.get("text_ha", ""), msg.get("text_en", "")))
+
+    banner = ('<div class="pw-esc-banner">Session escalated to human agent</div>'
+              if escalated else "")
+
+    if not bubbles:
+        body = '<div style="text-align:center;color:#667781;font-size:12px;padding:40px 0;">Send a message to begin…</div>'
+    else:
+        body = "".join(bubbles)
+
+    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}
+    {body}
+  </div>
+</div>
+<style>
+.pw-phone {{ max-width: 480px; margin: 0 auto; background: #ECE5DD; border-radius: 14px; overflow: hidden; border: 1px solid #ccc; display: flex; flex-direction: column; min-height: 540px; 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: 480px; overflow-y: auto; min-height: 420px; }}
+.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>
+"""
+
+
+# ---------------------------------------------------------------------------
+# Core turn handler
+# ---------------------------------------------------------------------------
+def run_turn(user_text: str, session: dict, is_voice: bool = False):
+    """Returns (updated_session_dict, bot_audio)."""
+    state = DialogueState.from_dict(session) if session else None
+    if state is None:
+        state = DialogueState(session_id="sess_" + uuid.uuid4().hex[:8], vertical="bank")
+
+    expected = get_expected_slot(state.vertical, state.current_state)
+    intent, entities, _ = nlu_parse(user_text, expected)
+    state = transition(state, intent, entities)
+
+    prompt = get_prompt(state.vertical, state.current_state)
+
+    state.history.append({"role": "user", "text": user_text, "is_voice": is_voice})
+    state.history.append({"role": "bot", "text_ha": prompt["ha"], "text_en": prompt["en"]})
+
+    try:
+        audio = synthesize_hausa(prompt["ha"])
+    except Exception as e:
+        print(f"TTS failed: {e}")
+        audio = None
+
+    return state.to_dict(), audio
+
+
+# ---------------------------------------------------------------------------
+# Gradio event handlers
+# ---------------------------------------------------------------------------
+def on_vertical_change(vertical: str):
+    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()
+    return session, render_whatsapp(session), None
+
+
+def on_text_submit(text: str, session: dict):
+    if not text or not text.strip():
+        return session, render_whatsapp(session), None, ""
+    new_session, audio = run_turn(text, session, is_voice=False)
+    return new_session, render_whatsapp(new_session), audio, ""
+
+
+def on_audio_submit(audio_data, session: dict):
+    if audio_data is None:
+        return session, render_whatsapp(session), None
+    try:
+        text = transcribe_hausa(audio_data)
+    except Exception as e:
+        print(f"ASR failed: {e}")
+        return session, render_whatsapp(session), None
+    if not text:
+        return session, render_whatsapp(session), None
+    new_session, audio = run_turn(text, session, is_voice=True)
+    return new_session, render_whatsapp(new_session), audio
+
+
+def on_reset(session: dict):
+    vertical = session.get("vertical", "bank") if session else "bank"
+    return on_vertical_change(vertical)
+
+
+# ---------------------------------------------------------------------------
+# Gradio UI (chat-only, minimal components)
+# ---------------------------------------------------------------------------
+CUSTOM_CSS = """
+.gradio-container { max-width: 720px !important; margin: 0 auto !important; }
+#whatsapp-container { padding: 20px 0; }
+"""
+
+with gr.Blocks(css=CUSTOM_CSS, title="PlotWeaver Voice Agent") as demo:
+    gr.HTML("""
+    <div style="text-align:center; padding: 0 0 12px;">
+      <h1 style="margin:0 0 4px; font-size: 22px; font-weight: 500;">PlotWeaver Voice Agent</h1>
+      <p style="margin:0; color: #5f5e5a; font-size: 14px;">Hausa-first conversational AI — pick a vertical, type or speak in Hausa</p>
+    </div>
+    """)
+
+    session_state = gr.State({})
+
+    vertical_radio = gr.Radio(
+        choices=[("PlotWeaver Bank", "bank"),
+                 ("PlotWeaver Telecom", "telecom"),
+                 ("PlotWeaver Delivery", "ecommerce")],
+        value="bank",
+        label="Vertical",
+        container=False,
+    )
+
+    whatsapp_html = gr.HTML(elem_id="whatsapp-container")
+
+    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")
+        reset_btn = gr.Button("Reset", scale=1)
+
+    audio_input = gr.Audio(
+        sources=["microphone", "upload"],
+        type="numpy",
+        label="Record or upload Hausa audio (click Stop when done recording)",
+    )
+
+    bot_audio = gr.Audio(
+        label="Bot response (Hausa TTS)",
+        autoplay=True,
+        interactive=False,
+    )
+
+    # Events
+    demo.load(
+        fn=lambda: on_vertical_change("bank"),
+        outputs=[session_state, whatsapp_html, bot_audio],
+    )
+    vertical_radio.change(
+        fn=on_vertical_change,
+        inputs=[vertical_radio],
+        outputs=[session_state, whatsapp_html, bot_audio],
+    )
+    send_btn.click(
+        fn=on_text_submit,
+        inputs=[text_input, session_state],
+        outputs=[session_state, whatsapp_html, bot_audio, text_input],
+    )
+    text_input.submit(
+        fn=on_text_submit,
+        inputs=[text_input, session_state],
+        outputs=[session_state, whatsapp_html, bot_audio, text_input],
+    )
+    audio_input.stop_recording(
+        fn=on_audio_submit,
+        inputs=[audio_input, session_state],
+        outputs=[session_state, whatsapp_html, bot_audio],
+    )
+    reset_btn.click(
+        fn=on_reset,
+        inputs=[session_state],
+        outputs=[session_state, whatsapp_html, bot_audio],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

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