Spaces:

PlotweaverAI
/

Voice-AI-Agent-Clean

Sleeping

App Files Files Community

Toadoum commited on 23 days ago

Commit

d402333

verified ·

1 Parent(s): 6d23228

Upload 4 files

Browse files

Files changed (4) hide show

app.py +722 -333
nlu.py +332 -469
orchestrator.py +1 -1
test_regressions.py +124 -0

app.py CHANGED Viewed

@@ -1,340 +1,729 @@
 """
-NLU Module — Multi-Intent Decomposition + Entity Extraction
-=============================================================
-Fixes P0/P1 from the feedback:
-  - Decomposes ONE user message into a LIST of tasks (compound requests)
-  - Extracts ALL entities present in the message (slot prefill —
-    "send money to abu" never re-asks for the recipient)
-  - Returns per-task confidence so destructive intents can be gated
-  - Distinguishes "ask about X" from "do X" (branch location ≠ block card)
-Backend chain (first available wins):
-  1. LLM_API    — HF Serverless Inference (set HF_TOKEN) — best quality
-  2. LLM_LOCAL  — Qwen2.5-1.5B-Instruct loaded in-process — good, slower
-  3. RULES      — improved keyword rules — degraded but never crashes
-All backends return the same schema:
-  {
-    "tasks": [
-      {
-        "intent": "send_money",
-        "confidence": 0.93,
-        "slots": {"recipient": "abu", "amount": "350000"},
-        "utterance_span": "send 350000 to abu"
-      },
-      ...
-    ],
-    "backend": "llm_api"
-  }
 """
-import os
-import re
 import json
-import logging
-from typing import Optional
-logger = logging.getLogger(__name__)
-# ── Intent catalogue (shared by all backends) ────────────────────────────────
-INTENT_SCHEMA = {
-    "greeting":         {"slots": [],                          "destructive": False},
-    "balance_inquiry":  {"slots": ["account_id"],              "destructive": False},
-    "send_money":       {"slots": ["recipient", "amount", "account_id"], "destructive": True},
-    "bill_payment":     {"slots": ["account_id", "amount"],    "destructive": True},
-    "block_card":       {"slots": ["account_id"],              "destructive": True},
-    "branch_info":      {"slots": [],                          "destructive": False},
-    "card_request":     {"slots": [],                          "destructive": False},
-    "report_issue":     {"slots": ["issue_desc"],              "destructive": False},
-    "track_order":      {"slots": ["order_id"],                "destructive": False},
-    "return_item":      {"slots": ["order_id", "return_reason"], "destructive": False},
-    "human_agent":      {"slots": [],                          "destructive": False},
-    "confirmation_yes": {"slots": [],                          "destructive": False},
-    "confirmation_no":  {"slots": [],                          "destructive": False},
-    "cancel":           {"slots": [],                          "destructive": False},
-    "goodbye":          {"slots": [],                          "destructive": False},
-    "unknown":          {"slots": [],                          "destructive": False},
 }
-NLU_SYSTEM_PROMPT = """You are the NLU module of a customer-service voice agent.
-Decompose the user's message into ALL tasks it contains, in order.
-Extract every entity present. Never invent entities that are not in the text.
-Intents: greeting, balance_inquiry, send_money, bill_payment, block_card,
-branch_info, card_request, report_issue, track_order, return_item,
-human_agent, confirmation_yes, confirmation_no, cancel, goodbye, unknown.
-Slots: recipient, amount, account_id, location, issue_desc, order_id, return_reason.
-CRITICAL disambiguation rules:
-- "where is your branch so I can get my card" = branch_info + card_request.
-  It is NOT block_card. Only choose block_card if the user explicitly wants to
-  BLOCK, FREEZE, or DEACTIVATE a card.
-- A message can contain multiple tasks joined by "and", "also", "then".
-  Output one task per action. "check my balance and send 5000 to musa"
-  = [balance_inquiry, send_money{recipient: musa, amount: 5000}].
-- If the user answers a question (e.g. gives a reason like "too small"),
-  map it to the slot of the pending task, intent = the pending intent.
-- Confidence in [0,1]: how sure you are of the INTENT (not the slots).
-Respond with ONLY valid JSON, no markdown, no commentary:
-{"tasks":[{"intent":"...","confidence":0.0,"slots":{},"utterance_span":"..."}]}"""
-class NLU:
-    def __init__(self, prefer: str = "auto"):
-        self.hf_token = os.getenv("HF_TOKEN", "")
-        self.api_model = os.getenv(
-            "NLU_API_MODEL", "Qwen/Qwen2.5-72B-Instruct")
-        self.local_model_id = os.getenv(
-            "NLU_LOCAL_MODEL", "Qwen/Qwen2.5-1.5B-Instruct")
-        self._local_pipe = None
-        self.prefer = prefer
-    # ── Public API ────────────────────────────────────────────────────────────
-    def parse(self, text: str, pending_intent: Optional[str] = None,
-              pending_slot: Optional[str] = None) -> dict:
-        """
-        text           : English pivot text of the user turn
-        pending_intent : intent currently awaiting a slot (context for the LLM)
-        pending_slot   : which slot we asked for last turn
-        """
-        context = ""
-        if pending_intent and pending_slot:
-            context = (f"\nContext: you previously asked the user for the "
-                       f"'{pending_slot}' of a '{pending_intent}' task. "
-                       f"A short answer likely fills that slot.")
-        for backend in self._backend_order():
-            try:
-                result = backend(text, context)
-                if result and result.get("tasks"):
-                    result = self._sanitize(result)
-                    logger.info(f"NLU[{result['backend']}]: "
-                                f"{json.dumps(result['tasks'])[:200]}")
-                    return result
-            except Exception as e:
-                logger.warning(f"NLU backend failed ({backend.__name__}): {e}")
-        # Absolute last resort
-        return {"tasks": [{"intent": "unknown", "confidence": 0.0,
-                            "slots": {}, "utterance_span": text}],
-                "backend": "none"}
-    # ── Backend chain ─────────────────────────────────────────────────────────
-    def _backend_order(self):
-        if self.prefer == "rules":
-            return [self._rules_backend]
-        chain = []
-        if self.hf_token:
-            chain.append(self._api_backend)
-        chain.append(self._local_backend)
-        chain.append(self._rules_backend)
-        return chain
-    # ── 1. HF Serverless Inference API ───────────────────────────────────────
-    def _api_backend(self, text: str, context: str) -> Optional[dict]:
-        import requests
-        url = f"https://api-inference.huggingface.co/models/{self.api_model}/v1/chat/completions"
-        payload = {
-            "model": self.api_model,
-            "messages": [
-                {"role": "system", "content": NLU_SYSTEM_PROMPT + context},
-                {"role": "user",   "content": text},
-            ],
-            "max_tokens": 400,
-            "temperature": 0.1,
-        }
-        r = requests.post(url, json=payload, timeout=20,
-                          headers={"Authorization": f"Bearer {self.hf_token}"})
-        r.raise_for_status()
-        raw = r.json()["choices"][0]["message"]["content"]
-        parsed = self._extract_json(raw)
-        if parsed:
-            parsed["backend"] = "llm_api"
-        return parsed
-    # ── 2. Local small LLM ────────────────────────────────────────────────────
-    def _local_backend(self, text: str, context: str) -> Optional[dict]:
-        if self._local_pipe is None:
-            logger.info(f"Loading local NLU model {self.local_model_id} …")
-            from transformers import pipeline as hf_pipeline
-            import torch
-            self._local_pipe = hf_pipeline(
-                "text-generation",
-                model=self.local_model_id,
-                torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
-                device_map="auto",
             )
-        messages = [
-            {"role": "system", "content": NLU_SYSTEM_PROMPT + context},
-            {"role": "user",   "content": text},
-        ]
-        out = self._local_pipe(messages, max_new_tokens=400,
-                                do_sample=False, temperature=None, top_p=None)
-        raw = out[0]["generated_text"][-1]["content"]
-        parsed = self._extract_json(raw)
-        if parsed:
-            parsed["backend"] = "llm_local"
-        return parsed
-    # ── 3. Improved rules (never fails) ───────────────────────────────────────
-    def _rules_backend(self, text: str, context: str) -> dict:
-        """
-        Better than the old FSM keywords:
-          - splits on conjunctions to find MULTIPLE tasks
-          - extracts entities per clause
-          - branch_info vs block_card disambiguation
-        """
-        t = text.lower().strip()
-        # Split compound message into clauses
-        clauses = re.split(r'\b(?:and also|and then|then|and|also|;|\. )\b', t)
-        clauses = [c.strip() for c in clauses if c.strip()]
-        tasks = []
-        for clause in clauses:
-            task = self._rules_classify_clause(clause)
-            if task:
-                tasks.append(task)
-        # Merge duplicate consecutive intents (e.g. "and" split an entity off)
-        merged = []
-        for task in tasks:
-            if merged and merged[-1]["intent"] == task["intent"]:
-                merged[-1]["slots"].update(task["slots"])
-                merged[-1]["utterance_span"] += " " + task["utterance_span"]
-            else:
-                merged.append(task)
-        if not merged:
-            merged = [{"intent": "unknown", "confidence": 0.3,
-                       "slots": {}, "utterance_span": t}]
-        return {"tasks": merged, "backend": "rules"}
-    def _rules_classify_clause(self, clause: str) -> Optional[dict]:
-        slots = {}
-        # ── Entity extraction (always, regardless of intent) ────────────────
-        # In a money-action clause ("send/transfer/pay X to Y"), the number is
-        # an AMOUNT. Only treat 6-12 digit numbers as account_id when the
-        # clause is about the account itself, or there is no money verb.
-        money_verb = any(v in clause for v in ("send", "transfer", "pay"))
-        account_ctx = any(v in clause for v in ("account", "acct", "number is"))
-        numbers = re.findall(r'\b\d[\d,\.]*\b', clause)
-        for num in numbers:
-            digits = num.replace(",", "").replace(".", "")
-            if money_verb and "amount" not in slots and len(digits) <= 7:
-                slots["amount"] = digits
-            elif (account_ctx or not money_verb) and 6 <= len(digits) <= 12 \
-                    and "account_id" not in slots:
-                slots["account_id"] = digits
-            elif "amount" not in slots and len(digits) <= 7:
-                slots["amount"] = digits
-        # recipient: "to <name>" — take the LAST valid match, skipping verbs
-        # ("I want to send money to abu" must yield 'abu', not 'send')
-        RECIPIENT_STOPWORDS = {
-            "my", "the", "a", "an", "me", "you", "check", "send", "transfer",
-            "pay", "get", "make", "do", "know", "see", "block", "return",
-            "track", "him", "her", "them", "it", "confirm", "cancel"}
-        for m in re.finditer(r'\bto\s+([a-z]{2,20})\b', clause):
-            name = m.group(1)
-            if name not in RECIPIENT_STOPWORDS:
-                slots["recipient"] = name
-        # order id
-        m = re.search(r'\border\s*#?\s*([a-z0-9\-]{4,20})\b', clause)
-        if m:
-            slots["order_id"] = m.group(1)
-        # ── Intent (order matters: destructive intents need explicit verbs) ──
-        def has(*kws):
-            return any(kw in clause for kw in kws)
-        # branch/location questions BEFORE block_card — fixes P0 #2
-        if has("branch", "closest", "nearest", "location", "where is", "address"):
-            intent, conf = "branch_info", 0.85
-            if has("card", "atm"):
-                # compound: they also want a card — but NOT to block it
-                return {"intent": "branch_info", "confidence": 0.85,
-                        "slots": slots, "utterance_span": clause}
-        elif has("block my card", "block card", "freeze", "deactivate", "stolen", "lost my card"):
-            intent, conf = "block_card", 0.8
-        elif has("send", "transfer") and (slots.get("recipient") or slots.get("amount")):
-            intent, conf = "send_money", 0.85
-        elif has("send money", "transfer money"):
-            intent, conf = "send_money", 0.75
-        elif has("balance", "how much", "asusun"):
-            intent, conf = "balance_inquiry", 0.85
-        elif has("pay", "bill", "recharge", "invoice"):
-            intent, conf = "bill_payment", 0.75
-        elif has("track", "where is my order", "delivery", "shipment"):
-            intent, conf = "track_order", 0.8
-        elif has("return", "refund", "send back"):
-            intent, conf = "return_item", 0.8
-        elif has("problem", "issue", "complaint", "not working", "error"):
-            intent, conf = "report_issue", 0.7
-            slots["issue_desc"] = clause
-        elif has("human", "agent", "person", "operator", "representative"):
-            intent, conf = "human_agent", 0.9
-        elif has("yes", "yep", "correct", "confirm", "sure", "okay", "ok"):
-            intent, conf = "confirmation_yes", 0.8
-        elif has("no", "nope", "wrong", "cancel that"):
-            intent, conf = "confirmation_no", 0.8
-        elif has("hello", "hi ", "good morning", "sannu", "salam"):
-            intent, conf = "greeting", 0.9
-        elif has("bye", "goodbye", "thank"):
-            intent, conf = "goodbye", 0.85
-        else:
-            return {"intent": "unknown", "confidence": 0.3,
-                    "slots": slots, "utterance_span": clause}
-        return {"intent": intent, "confidence": conf,
-                "slots": slots, "utterance_span": clause}
-    # ── Helpers ───────────────────────────────────────────────────────────────
-    @staticmethod
-    def _extract_json(raw: str) -> Optional[dict]:
-        """Robustly pull the first JSON object out of LLM output."""
-        raw = raw.strip()
-        raw = re.sub(r'^```(?:json)?|```$', '', raw, flags=re.MULTILINE).strip()
-        # find first { … matching last }
-        start = raw.find("{")
-        end   = raw.rfind("}")
-        if start == -1 or end == -1:
-            return None
-        try:
-            return json.loads(raw[start:end + 1])
-        except json.JSONDecodeError:
-            return None
-    @staticmethod
-    def _sanitize(result: dict) -> dict:
-        """Validate schema, clamp confidence, drop hallucinated slots."""
-        valid_slots = {"recipient", "amount", "account_id", "location",
-                       "issue_desc", "order_id", "return_reason"}
-        clean_tasks = []
-        for task in result.get("tasks", []):
-            intent = task.get("intent", "unknown")
-            if intent not in INTENT_SCHEMA:
-                intent = "unknown"
-            conf = float(task.get("confidence", 0.5))
-            conf = max(0.0, min(1.0, conf))
-            slots = {k: str(v).strip() for k, v in (task.get("slots") or {}).items()
-                     if k in valid_slots and v not in (None, "", "null", "None")}
-            clean_tasks.append({
-                "intent": intent, "confidence": conf, "slots": slots,
-                "utterance_span": str(task.get("utterance_span", ""))[:200],
-            })
-        result["tasks"] = clean_tasks or [
-            {"intent": "unknown", "confidence": 0.0, "slots": {},
-             "utterance_span": ""}]
-        return result

 """
+PlotWeaver Hausa Voice AI Agent — HuggingFace Spaces Demo
+==========================================================
+Full pipeline: Whisper ASR  →  NLLB translation  →  Dialogue Manager  →  MMS-TTS
+Run locally:
+    pip install -r requirements.txt
+    python app.py
 """
+import gradio as gr
+import numpy as np
+import uuid
 import json
+from datetime import datetime
+from pipeline import HausaVoiceAIPipeline
+from nlu import NLU
+from orchestrator import Orchestrator
+from integrations.crm import CRMClient
+# ── Singletons (lazy-loaded inside pipeline) ─────────────────────────────────
+ai_pipeline = HausaVoiceAIPipeline()
+# NLU backend chain: HF Inference API (if HF_TOKEN set) → local LLM → rules
+dm          = Orchestrator(crm=CRMClient(), nlu=NLU())
+# ── Demo phrases (for visitors who don't speak Hausa) ────────────────────────
+DEMO_PROMPTS = [
+    ("Compound: balance + transfer",
+     "Duba asusuna sannan ka aika naira dubu talatin da biyar zuwa Amina"),
+    ("Entity prefill: send to Abu",
+     "Ina son aika kuɗi zuwa Abu yanzu"),
+    ("Branch + card (not block!)",
+     "Ina ne reshenku mafi kusa domin in karɓi katin ATM"),
+    ("Report a problem",        "Ina da matsala"),
+    ("Talk to human agent",     "Ina son magana da mutum"),
+]
+# ── Custom CSS ────────────────────────────────────────────────────────────────
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&family=Syne:wght@700;800&family=JetBrains+Mono:wght@400;500&display=swap');
+:root {
+    --amber:   #F59E0B;
+    --ember:   #DC2626;
+    --sand:    #FDE68A;
+    --dark:    #0C0A09;
+    --panel:   #1C1917;
+    --border:  #292524;
+    --text:    #E7E5E4;
+    --muted:   #78716C;
+    --success: #22C55E;
+    --info:    #38BDF8;
+}
+body, .gradio-container {
+    background: var(--dark) !important;
+    font-family: 'Space Grotesk', sans-serif !important;
+    color: var(--text) !important;
+}
+/* ── Header ── */
+.pw-header {
+    background: linear-gradient(135deg, #1C1917 0%, #292524 50%, #1C1917 100%);
+    border-bottom: 1px solid var(--border);
+    padding: 28px 40px 24px;
+    position: relative;
+    overflow: hidden;
+}
+.pw-header::before {
+    content: '';
+    position: absolute;
+    top: -60px; right: -60px;
+    width: 300px; height: 300px;
+    background: radial-gradient(circle, rgba(245,158,11,0.15) 0%, transparent 70%);
+    pointer-events: none;
+}
+.pw-logo {
+    font-family: 'Syne', sans-serif;
+    font-weight: 800;
+    font-size: 28px;
+    color: var(--amber);
+    letter-spacing: -0.5px;
+    margin: 0;
+}
+.pw-logo span { color: var(--text); }
+.pw-tagline {
+    color: var(--muted);
+    font-size: 13px;
+    margin: 4px 0 0;
+    letter-spacing: 0.5px;
+    text-transform: uppercase;
 }
+/* ── Pill badges ── */
+.pill {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    background: rgba(245,158,11,0.12);
+    border: 1px solid rgba(245,158,11,0.3);
+    color: var(--amber);
+    padding: 4px 12px;
+    border-radius: 100px;
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.8px;
+    text-transform: uppercase;
+}
+.pill-green {
+    background: rgba(34,197,94,0.12);
+    border-color: rgba(34,197,94,0.3);
+    color: var(--success);
+}
+.pill-blue {
+    background: rgba(56,189,248,0.12);
+    border-color: rgba(56,189,248,0.3);
+    color: var(--info);
+}
+/* ── Panel cards ── */
+.pw-card {
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 20px;
+    margin-bottom: 12px;
+}
+.pw-card-title {
+    font-family: 'Syne', sans-serif;
+    font-size: 13px;
+    font-weight: 700;
+    color: var(--amber);
+    letter-spacing: 1px;
+    text-transform: uppercase;
+    margin-bottom: 14px;
+}
+/* ── Conversation bubbles ── */
+.conversation-box {
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 16px;
+    height: 360px;
+    overflow-y: auto;
+    font-family: 'Space Grotesk', sans-serif;
+    scroll-behavior: smooth;
+}
+.bubble {
+    max-width: 85%;
+    padding: 10px 14px;
+    border-radius: 14px;
+    margin-bottom: 10px;
+    line-height: 1.5;
+    font-size: 14px;
+}
+.bubble-user {
+    background: rgba(245,158,11,0.15);
+    border: 1px solid rgba(245,158,11,0.25);
+    margin-left: auto;
+    border-bottom-right-radius: 4px;
+}
+.bubble-agent {
+    background: rgba(255,255,255,0.05);
+    border: 1px solid var(--border);
+    border-bottom-left-radius: 4px;
+}
+.bubble-label {
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.8px;
+    text-transform: uppercase;
+    opacity: 0.6;
+    margin-bottom: 4px;
+}
+.bubble-hausa {
+    font-size: 12px;
+    color: var(--amber);
+    margin-top: 4px;
+    font-style: italic;
+}
+.bubble-time {
+    font-size: 10px;
+    color: var(--muted);
+    margin-top: 3px;
+    font-family: 'JetBrains Mono', monospace;
+}
+/* ── Pipeline status ── */
+.pipeline-step {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 8px 0;
+    border-bottom: 1px solid var(--border);
+    font-size: 13px;
+}
+.pipeline-step:last-child { border-bottom: none; }
+.step-icon {
+    width: 28px; height: 28px;
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 14px;
+    flex-shrink: 0;
+}
+.step-active   { background: rgba(245,158,11,0.2); }
+.step-done     { background: rgba(34,197,94,0.2); }
+.step-idle     { background: rgba(255,255,255,0.05); }
+/* ── Gradio overrides ── */
+.gr-button-primary {
+    background: var(--amber) !important;
+    color: var(--dark) !important;
+    font-weight: 700 !important;
+    border: none !important;
+    font-family: 'Space Grotesk', sans-serif !important;
+}
+.gr-button-secondary {
+    background: var(--panel) !important;
+    color: var(--text) !important;
+    border: 1px solid var(--border) !important;
+}
+label, .gr-form > div > label {
+    color: var(--muted) !important;
+    font-size: 12px !important;
+    font-weight: 500 !important;
+    letter-spacing: 0.5px !important;
+    text-transform: uppercase !important;
+}
+.gr-box, .gr-input, textarea, .gr-text-input {
+    background: var(--panel) !important;
+    border-color: var(--border) !important;
+    color: var(--text) !important;
+    border-radius: 8px !important;
+    font-family: 'Space Grotesk', sans-serif !important;
+}
+.tabitem { background: var(--dark) !important; }
+.tab-nav button {
+    background: transparent !important;
+    color: var(--muted) !important;
+    border-bottom: 2px solid transparent !important;
+    font-family: 'Space Grotesk', sans-serif !important;
+    font-weight: 600 !important;
+}
+.tab-nav button.selected {
+    color: var(--amber) !important;
+    border-bottom-color: var(--amber) !important;
+}
+footer { display: none !important; }
+"""
+# ── Architecture diagram HTML ─────────────────────────────────────────────────
+ARCH_HTML = """
+<div style="font-family:'Space Grotesk',sans-serif; color:#E7E5E4; padding:16px;">
+<div style="font-family:'Syne',sans-serif; font-size:13px; font-weight:700;
+            color:#F59E0B; letter-spacing:1px; text-transform:uppercase;
+            margin-bottom:20px;">System Architecture</div>
+<div style="display:flex; gap:8px; align-items:center; flex-wrap:wrap; margin-bottom:20px;">
+  <!-- Input channels -->
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
+              padding:12px 16px; min-width:100px; text-align:center;">
+    <div style="font-size:20px;">🎤</div>
+    <div style="font-size:11px; color:#78716C; margin-top:4px;">MICROPHONE</div>
+    <div style="font-size:10px; color:#22C55E;">Gradio</div>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
+              padding:12px 16px; min-width:100px; text-align:center;">
+    <div style="font-size:20px;">💬</div>
+    <div style="font-size:11px; color:#78716C; margin-top:4px;">WHATSAPP</div>
+    <div style="font-size:10px; color:#22C55E;">Cloud API</div>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
+              padding:12px 16px; min-width:100px; text-align:center;">
+    <div style="font-size:20px;">📞</div>
+    <div style="font-size:11px; color:#78716C; margin-top:4px;">PHONE/SIP</div>
+    <div style="font-size:10px; color:#22C55E;">Twilio</div>
+  </div>
+  <div style="color:#F59E0B; font-size:20px; margin:0 4px;">→</div>
+  <!-- Pipeline -->
+  <div style="display:flex; flex-direction:column; gap:8px;">
+    <div style="background:rgba(245,158,11,0.1);border:1px solid rgba(245,158,11,0.3);
+                border-radius:8px; padding:10px 20px; text-align:center;">
+      <div style="font-size:11px; font-weight:700; color:#F59E0B;">WHISPER LARGE-V3</div>
+      <div style="font-size:10px; color:#78716C;">Hausa ASR  · openai/whisper-large-v3</div>
+    </div>
+    <div style="background:rgba(56,189,248,0.1);border:1px solid rgba(56,189,248,0.3);
+                border-radius:8px; padding:10px 20px; text-align:center;">
+      <div style="font-size:11px; font-weight:700; color:#38BDF8;">NLLB-200 (600M)</div>
+      <div style="font-size:10px; color:#78716C;">hau_Latn ↔ eng_Latn</div>
+    </div>
+    <div style="background:rgba(168,85,247,0.1);border:1px solid rgba(168,85,247,0.3);
+                border-radius:8px; padding:10px 20px; text-align:center;">
+      <div style="font-size:11px; font-weight:700; color:#A855F7;">DIALOGUE MANAGER</div>
+      <div style="font-size:10px; color:#78716C;">FSM + Intent · Multi-turn</div>
+    </div>
+    <div style="background:rgba(34,197,94,0.1);border:1px solid rgba(34,197,94,0.3);
+                border-radius:8px; padding:10px 20px; text-align:center;">
+      <div style="font-size:11px; font-weight:700; color:#22C55E;">MMS-TTS (HAU)</div>
+      <div style="font-size:10px; color:#78716C;">facebook/mms-tts-hau · VITS</div>
+    </div>
+  </div>
+  <div style="color:#F59E0B; font-size:20px; margin:0 4px;">→</div>
+  <!-- Integrations -->
+  <div style="display:flex; flex-direction:column; gap:8px;">
+    <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
+                padding:12px 16px; min-width:110px; text-align:center;">
+      <div style="font-size:20px;">🗂️</div>
+      <div style="font-size:11px; color:#78716C; margin-top:4px;">CRM / ZENDESK</div>
+      <div style="font-size:10px; color:#F59E0B;">Auto-tickets</div>
+    </div>
+    <div style="background:#1C1917;border:1px solid #292524;border-radius:10px;
+                padding:12px 16px; min-width:110px; text-align:center;">
+      <div style="font-size:20px;">👤</div>
+      <div style="font-size:11px; color:#78716C; margin-top:4px;">HUMAN AGENT</div>
+      <div style="font-size:10px; color:#DC2626;">Fallback</div>
+    </div>
+  </div>
+</div>
+<div style="display:flex; gap:20px; flex-wrap:wrap; margin-top:16px; padding-top:16px;
+            border-top:1px solid #292524;">
+  <div><span style="color:#F59E0B; font-weight:700;">Latency target:</span>
+       <span style="color:#78716C;"> ASR&lt;2s · MT&lt;0.5s · TTS&lt;1s · Total&lt;4s</span></div>
+  <div><span style="color:#F59E0B; font-weight:700;">Languages:</span>
+       <span style="color:#78716C;"> Hausa (primary) · English pivot · French (roadmap)</span></div>
+  <div><span style="color:#F59E0B; font-weight:700;">Deployment:</span>
+       <span style="color:#78716C;"> HF Spaces (POC) → Docker / K8s (prod)</span></div>
+</div>
+</div>
+"""
+# ── State helpers ─────────────────────────────────────────────────────────────
+def _init_state():
+    return {
+        "conv":    dm.new_session(),
+        "history": [],   # [{role, hausa, english, time}]
+    }
+def _render_conversation(history: list) -> str:
+    if not history:
+        return (
+            '<div style="color:#78716C; text-align:center; margin-top:60px; '
+            'font-size:13px;">🎤 Speak or type in Hausa to begin …</div>'
+        )
+    html = ""
+    for msg in history:
+        role   = msg["role"]
+        is_user = role == "user"
+        label  = "YOU" if is_user  else "AGENT"
+        cls    = "bubble-user" if is_user else "bubble-agent"
+        en     = msg.get("english", "")
+        ha     = msg.get("hausa",   "")
+        t      = msg.get("time",    "")
+        primary = ha if ha else en
+        secondary = en if ha else ""
+        html += f"""
+<div style="display:flex; flex-direction:column;
+            align-items:{'flex-end' if is_user else 'flex-start'}; margin-bottom:12px;">
+  <div class="bubble {cls}">
+    <div class="bubble-label">{label}</div>
+    <div>{primary}</div>
+    {'<div class="bubble-hausa">EN: ' + secondary + '</div>' if secondary else ''}
+    <div class="bubble-time">{t}</div>
+  </div>
+</div>"""
+    return html
+# ── Core processing function ──────────────────────────────────────────────────
+def process_voice(audio, text_input, state):
+    """
+    Entry: either audio or text (fallback for demo without mic).
+    Returns: (audio_out, conversation_html, status_text, updated_state)
+    """
+    if state is None:
+        state = _init_state()
+    hausa_text = ""
+    asr_status = "—"
+    # 1. ASR
+    if audio is not None:
+        sample_rate, audio_array = audio
+        audio_array = audio_array.astype(np.float32) / 32768.0
+        if audio_array.ndim > 1:
+            audio_array = audio_array.mean(axis=1)
+        hausa_text = ai_pipeline.audio_to_hausa_text(audio_array, sample_rate)
+        asr_status = f"✓ {hausa_text[:60]}…" if len(hausa_text) > 60 else f"✓ {hausa_text}"
+    elif text_input and text_input.strip():
+        hausa_text = text_input.strip()
+        asr_status = "(text input)"
+    else:
+        return None, _render_conversation(state["history"]), "⚠ No input provided", state
+    # 2. Hausa → English
+    english_text = ai_pipeline.hausa_to_english(hausa_text)
+    # 3. Dialogue
+    english_response, conv_state, escalate = dm.respond(
+        english_text, hausa_text, state["conv"]
+    )
+    state["conv"] = conv_state
+    # 4. English → Hausa
+    hausa_response = ai_pipeline.english_to_hausa(english_response)
+    # 5. TTS
+    sr, audio_out = ai_pipeline.hausa_text_to_audio(hausa_response)
+    # 6. Update history
+    now = datetime.now().strftime("%H:%M:%S")
+    state["history"].append({
+        "role": "user", "hausa": hausa_text,
+        "english": english_text, "time": now
+    })
+    state["history"].append({
+        "role": "agent", "hausa": hausa_response,
+        "english": english_response, "time": now
+    })
+    open_tasks = [t for t in conv_state.tasks
+                  if t.status in ("pending", "collecting", "confirming")]
+    status = (f"Turn {conv_state.turn} · "
+              f"queue: {len(open_tasks)} open / "
+              f"{sum(1 for t in conv_state.tasks if t.status == 'done')} done")
+    if conv_state.active_task:
+        status += f" · active: {conv_state.active_task.intent}"
+    if escalate:
+        status += "  ⚠ ESCALATED TO HUMAN"
+    return (sr, audio_out), _render_conversation(state["history"]), status, state
+def reset_session(state):
+    state = _init_state()
+    return None, _render_conversation([]), "New session started.", state
+def use_demo_prompt(prompt_ha, state):
+    """Inject a demo Hausa phrase as text input."""
+    return prompt_ha, state
+# ── Build the Gradio app ──────────────────────────────────────────────────────
+with gr.Blocks(css=CSS, title="PlotWeaver · Hausa Voice AI") as demo:
+    # Shared state
+    app_state = gr.State(None)
+    # ── Header ─────────────────────────────────────────────────────────────────
+    gr.HTML("""
+    <div class="pw-header">
+      <p class="pw-logo">Plot<span>Weaver</span></p>
+      <p class="pw-tagline">Hausa Voice AI Agent · Investor Demo · v0.1-poc</p>
+      <div style="display:flex; gap:8px; margin-top:14px; flex-wrap:wrap;">
+        <span class="pill">🎤 Whisper v3</span>
+        <span class="pill">🌐 NLLB-200</span>
+        <span class="pill">🔊 MMS-TTS</span>
+        <span class="pill-green">⚡ Real-time</span>
+        <span class="pill-blue">🏢 Enterprise-ready</span>
+      </div>
+    </div>
+    """)
+    with gr.Tabs():
+        # ── Tab 1 : Live Demo ───────────────────────────────────────────────
+        with gr.TabItem("🎙️  Live Demo"):
+            with gr.Row():
+                # Left column
+                with gr.Column(scale=2):
+                    gr.HTML('<div class="pw-card-title" '
+                            'style="margin-bottom:10px;">Conversation</div>')
+                    conversation_display = gr.HTML(
+                        _render_conversation([]),
+                        elem_classes=["conversation-box"]
+                    )
+                    status_box = gr.Textbox(
+                        label="Pipeline Status",
+                        value="Ready. Speak or type in Hausa.",
+                        interactive=False,
+                        lines=1,
+                    )
+                # Right column
+                with gr.Column(scale=1):
+                    gr.HTML('<div class="pw-card-title" '
+                            'style="margin-bottom:10px;">Input</div>')
+                    audio_in = gr.Audio(
+                        sources=["microphone"],
+                        type="numpy",
+                        label="Voice Input (Hausa)",
+                        streaming=False,
+                    )
+                    text_in = gr.Textbox(
+                        label="Text fallback (Hausa)",
+                        placeholder="Sannu, ina son sanin asusun kuɗin…",
+                        lines=2,
+                    )
+                    with gr.Row():
+                        submit_btn = gr.Button("▶  Send", variant="primary")
+                        reset_btn  = gr.Button("↺  Reset", variant="secondary")
+                    audio_out = gr.Audio(
+                        label="Agent Response (Hausa audio)",
+                        autoplay=True,
+                    )
+                    # Demo quick prompts
+                    gr.HTML('<div class="pw-card-title" '
+                            'style="margin-top:16px; margin-bottom:10px;">'
+                            'Quick Demo Prompts</div>')
+                    for label_en, phrase_ha in DEMO_PROMPTS:
+                        btn = gr.Button(f"{label_en}  →  {phrase_ha}",
+                                        variant="secondary", size="sm")
+                        btn.click(
+                            fn=lambda p=phrase_ha, s=None: (p, s),
+                            inputs=[app_state],
+                            outputs=[text_in, app_state],
+                        )
+            # ── Events ─────────────────────────────────────────────────────
+            submit_btn.click(
+                fn=process_voice,
+                inputs=[audio_in, text_in, app_state],
+                outputs=[audio_out, conversation_display, status_box, app_state],
             )
+            reset_btn.click(
+                fn=reset_session,
+                inputs=[app_state],
+                outputs=[audio_out, conversation_display, status_box, app_state],
+            )
+        # ── Tab 2 : Architecture ────────────────────────────────────────────
+        with gr.TabItem("🏗️  Architecture"):
+            gr.HTML(ARCH_HTML)
+        # ── Tab 3 : Integrations ────────────────────────────────────────────
+        with gr.TabItem("🔌  Integrations"):
+            gr.HTML("""
+<div style="font-family:'Space Grotesk',sans-serif; color:#E7E5E4; padding:16px;">
+<div style="font-family:'Syne',sans-serif; font-size:13px; font-weight:700;
+            color:#F59E0B; letter-spacing:1px; text-transform:uppercase;
+            margin-bottom:20px;">Enterprise Integration Matrix</div>
+<div style="display:grid; grid-template-columns:repeat(auto-fill,minmax(220px,1fr)); gap:16px;">
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
+    <div style="font-size:24px; margin-bottom:8px;">💬</div>
+    <div style="font-weight:700; margin-bottom:4px;">WhatsApp Business</div>
+    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
+      Meta Cloud API v18+. Inbound voice notes → ASR pipeline.
+      Quick-reply buttons. Media download.
+    </div>
+    <span style="font-size:10px; background:rgba(34,197,94,0.12);
+                 border:1px solid rgba(34,197,94,0.3); color:#22C55E;
+                 padding:2px 8px; border-radius:100px;">READY</span>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
+    <div style="font-size:24px; margin-bottom:8px;">📞</div>
+    <div style="font-weight:700; margin-bottom:4px;">Twilio / SIP</div>
+    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
+      Twilio Media Streams WebSocket. Inbound + outbound IVR.
+      Warm transfer to human agent. Bandwidth BXML also supported.
+    </div>
+    <span style="font-size:10px; background:rgba(34,197,94,0.12);
+                 border:1px solid rgba(34,197,94,0.3); color:#22C55E;
+                 padding:2px 8px; border-radius:100px;">READY</span>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
+    <div style="font-size:24px; margin-bottom:8px;">🗂️</div>
+    <div style="font-weight:700; margin-bottom:4px;">CRM / Ticketing</div>
+    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
+      Zendesk native adapter. Generic REST adapter for Freshdesk,
+      HubSpot, Salesforce. Auto-ticket on issue report.
+    </div>
+    <span style="font-size:10px; background:rgba(34,197,94,0.12);
+                 border:1px solid rgba(34,197,94,0.3); color:#22C55E;
+                 padding:2px 8px; border-radius:100px;">READY</span>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
+    <div style="font-size:24px; margin-bottom:8px;">👤</div>
+    <div style="font-weight:700; margin-bottom:4px;">Human Fallback</div>
+    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
+      Threshold-based escalation: low confidence, explicit request,
+      or max-turns. SIP REFER transfer + CRM context handoff.
+    </div>
+    <span style="font-size:10px; background:rgba(34,197,94,0.12);
+                 border:1px solid rgba(34,197,94,0.3); color:#22C55E;
+                 padding:2px 8px; border-radius:100px;">READY</span>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
+    <div style="font-size:24px; margin-bottom:8px;">🌍</div>
+    <div style="font-weight:700; margin-bottom:4px;">More Languages</div>
+    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
+      Yorùbá, Igbo, Fulfulde, Kanuri roadmap.
+      NLLB covers 200 languages. MMS covers 1,000+ TTS languages.
+    </div>
+    <span style="font-size:10px; background:rgba(245,158,11,0.12);
+                 border:1px solid rgba(245,158,11,0.3); color:#F59E0B;
+                 padding:2px 8px; border-radius:100px;">ROADMAP</span>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
+    <div style="font-size:24px; margin-bottom:8px;">⚡</div>
+    <div style="font-weight:700; margin-bottom:4px;">Fine-tuned Models</div>
+    <div style="font-size:12px; color:#78716C; margin-bottom:10px;">
+      Custom Whisper fine-tune for Hausa dialectal variance.
+      OuteTTS / MMS fine-tune on domain vocabulary. NLLB domain adaptation.
+    </div>
+    <span style="font-size:10px; background:rgba(245,158,11,0.12);
+                 border:1px solid rgba(245,158,11,0.3); color:#F59E0B;
+                 padding:2px 8px; border-radius:100px;">IN PROGRESS</span>
+  </div>
+</div>
+<div style="margin-top:24px; padding:16px; background:rgba(245,158,11,0.05);
+            border:1px solid rgba(245,158,11,0.2); border-radius:10px;">
+  <div style="font-size:12px; font-weight:700; color:#F59E0B;
+              margin-bottom:8px; letter-spacing:0.5px;">⚙  CONFIGURATION</div>
+  <div style="font-family:'JetBrains Mono',monospace; font-size:11px;
+              color:#78716C; line-height:2;">
+    WHATSAPP_TOKEN=&lt;meta-token&gt;  &nbsp; WHATSAPP_PHONE_ID=&lt;phone-id&gt;<br>
+    TWILIO_ACCOUNT_SID=ACxxxx  &nbsp; TWILIO_AUTH_TOKEN=xxxx<br>
+    CRM_PROVIDER=zendesk  &nbsp; ZENDESK_SUBDOMAIN=yourco  &nbsp; ZENDESK_API_TOKEN=xxxx<br>
+    SIP_PROVIDER=twilio  &nbsp; (or bandwidth)
+  </div>
+</div>
+</div>
+""")
+        # ── Tab 4 : Business Case ────────────────────────────────────────────
+        with gr.TabItem("📊  Market"):
+            gr.HTML("""
+<div style="font-family:'Space Grotesk',sans-serif; color:#E7E5E4; padding:16px;">
+<div style="font-family:'Syne',sans-serif; font-size:13px; font-weight:700;
+            color:#F59E0B; letter-spacing:1px; text-transform:uppercase;
+            margin-bottom:20px;">Why Hausa Voice AI · Now</div>
+<div style="display:grid; grid-template-columns:repeat(auto-fill,minmax(180px,1fr));
+            gap:16px; margin-bottom:24px;">
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;
+              padding:18px; text-align:center;">
+    <div style="font-family:'Syne',sans-serif; font-size:32px; font-weight:800;
+                color:#F59E0B;">100M+</div>
+    <div style="font-size:12px; color:#78716C; margin-top:4px;">Hausa speakers</div>
+    <div style="font-size:11px; color:#22C55E;">#1 language in West Africa</div>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;
+              padding:18px; text-align:center;">
+    <div style="font-family:'Syne',sans-serif; font-size:32px; font-weight:800;
+                color:#F59E0B;">63%</div>
+    <div style="font-size:12px; color:#78716C; margin-top:4px;">Low literacy rate</div>
+    <div style="font-size:11px; color:#38BDF8;">Voice is the UX</div>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;
+              padding:18px; text-align:center;">
+    <div style="font-family:'Syne',sans-serif; font-size:32px; font-weight:800;
+                color:#F59E0B;">$4.2B</div>
+    <div style="font-size:12px; color:#78716C; margin-top:4px;">Africa call-centre spend</div>
+    <div style="font-size:11px; color:#F59E0B;">2027 projection</div>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;
+              padding:18px; text-align:center;">
+    <div style="font-family:'Syne',sans-serif; font-size:32px; font-weight:800;
+                color:#F59E0B;">0</div>
+    <div style="font-size:12px; color:#78716C; margin-top:4px;">Production Hausa VoiceBots</div>
+    <div style="font-size:11px; color:#DC2626;">Whitespace opportunity</div>
+  </div>
+</div>
+<div style="display:grid; grid-template-columns:1fr 1fr; gap:16px;">
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
+    <div style="font-weight:700; color:#F59E0B; margin-bottom:12px;">🎯  Target Verticals</div>
+    <div style="font-size:13px; line-height:2; color:#A8A29E;">
+      📱 Telecoms (MTN, Airtel Nigeria, Glo)<br>
+      🏦 Fintech / Mobile money (Kuda, PalmPay)<br>
+      🏥 Health (NHIS, telemedicine IVR)<br>
+      🏛 Government services (NIMC, NIN)<br>
+      🛒 E-commerce (Jumia, Konga)
+    </div>
+  </div>
+  <div style="background:#1C1917;border:1px solid #292524;border-radius:12px;padding:18px;">
+    <div style="font-weight:700; color:#F59E0B; margin-bottom:12px;">🏆  Competitive Moat</div>
+    <div style="font-size:13px; line-height:2; color:#A8A29E;">
+      ✓ Open-source stack (no API lock-in)<br>
+      ✓ Fine-tuned Hausa models (PlotWeaver IP)<br>
+      ✓ On-premise deployable (data sovereignty)<br>
+      ✓ Multi-channel from day one<br>
+      ✓ Academic NLP + production engineering
+    </div>
+  </div>
+</div>
+</div>
+""")
+    # ── Footer ────────────────────────────────────────────────────────────────
+    gr.HTML("""
+    <div style="text-align:center; padding:20px; color:#44403C; font-size:11px;
+                border-top:1px solid #1C1917; margin-top:8px;">
+      PlotWeaver · Hausa Voice AI Agent POC &nbsp;|&nbsp;
+      Whisper large-v3 · NLLB-200 · MMS-TTS-hau &nbsp;|&nbsp;
+      <a href="https://plotweaver.ai" style="color:#F59E0B; text-decoration:none;">
+        plotweaver.ai</a>
+    </div>
+    """)
+if __name__ == "__main__":
+    demo.launch(share=False)

nlu.py CHANGED Viewed

@@ -1,477 +1,340 @@
 """
-NLU — Embedding similarity architecture.
-=========================================
-Replaces the legacy NLLB+Qwen pipeline (preserved in nlu_legacy.py).
-Why embeddings?
-  - Latency: ~200ms vs ~10s on CPU for the legacy stack
-  - Memory:  ~420MB vs ~8GB
-  - Hausa coverage: paraphrase-multilingual-MiniLM-L12-v2 was trained on 50+
-    languages including Hausa, so we no longer need a translation step
-  - Confidence comes for free: cosine similarity IS a calibrated confidence
-Pipeline (in order):
-  Layer 0: Human-keyword escape ("wakili", "agent") → always wins
-  Layer 1: Structural extractors (digits, amounts, yes/no, name, date, free
-           text, bundle) when the dialogue state sets an expected slot
-  Layer 1.5: Keyword fast-path for ultra-common phrases ("duba ma'auni")
-             — sub-millisecond, no model call
-  Layer 2: Sentence-embedding similarity vs per-intent centroids
-           — cosine sim ≥ threshold (0.4) → that intent, else unknown
-The dialogue manager receives the same (intent, entities, source) tuple
-as before, so app.py needs no changes.
-Fixes vs the POC
-----------------
-* _match_yesno no longer treats English "I" (inside any sentence) as Hausa
-  "i"=yes via substring containment; short tokens match exactly.
-* _match_intent_keyword matches keywords as whole whitespace-delimited tokens,
-  so short keywords ("ba", "data", "oda") can't fire inside unrelated words.
-* expected == "text" / "bundle" now emit the provide_text / provide_bundle
-  intents the FSM transitions expect — previously these slots were never
-  satisfied, silently breaking the complaint, bundle, and return flows.
 """
-from __future__ import annotations
 import re
 import logging
 from typing import Optional
-logger = logging.getLogger("plotweaver.nlu")
-# ---------------------------------------------------------------------------
-# Deterministic structural extractors (run on raw Hausa text)
-# ---------------------------------------------------------------------------
-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,
-}
-# Short yes/no tokens: matched EXACTLY (whole utterance) to avoid substring
-# false positives. Multi-word cues are matched as whitespace-bounded phrases.
-HAUSA_YES_EXACT = {"i", "eh", "ok", "okay", "yes"}
-HAUSA_YES_PHRASE = {"haka ne", "haka"}
-HAUSA_NO_EXACT = {"a'a", "a'aa", "ba", "no"}
-HAUSA_NO_PHRASE = {"ba haka"}
-HUMAN_KEYWORDS = {"mutum", "wakili", "agent", "human"}
-BUNDLE_TYPES = ("rana", "mako", "wata")
-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 _match_yesno(text: str) -> Optional[str]:
-    t = text.lower().strip()
-    if t in HAUSA_YES_EXACT:
-        return "yes"
-    if t in HAUSA_NO_EXACT:
-        return "no"
-    padded = f" {t} "
-    if any(f" {kw} " in padded for kw in HAUSA_YES_PHRASE):
-        return "yes"
-    if any(f" {kw} " in padded for kw in HAUSA_NO_PHRASE):
-        return "no"
-    return None
-def _contains_human_keyword(text: str) -> bool:
-    padded = f" {text.lower().strip()} "
-    return any(f" {kw} " in padded for kw in HUMAN_KEYWORDS)
-# ---------------------------------------------------------------------------
-# Keyword fast-path — instant matches for common scripted phrases
-# ---------------------------------------------------------------------------
-INTENT_KEYWORDS = {
-    "check_balance": [
-        "duba ma'auni", "ma'auni", "balance", "check balance",
-        "account balance", "how much", "kudin asusu",
-    ],
-    "block_card": [
-        "toshe kati", "block card", "cancel card", "freeze card",
-        "toshe", "lost card", "ɓatar da kati",
-    ],
-    "transfer_money": [
-        "canjin kuɗi", "canjin kudi", "transfer", "transfer money",
-        "send money", "aiki kuɗi", "aiki kudi",
-    ],
-    "buy_airtime": [
-        "saya airtime", "airtime", "buy airtime", "top up", "topup",
-        "recharge", "karɓi airtime",
-    ],
-    "buy_bundle": [
-        "saya bundle", "bundle", "buy bundle", "buy data", "data",
-        "internet", "megabyte",
-    ],
-    "complaint": [
-        "yin korafi", "korafi", "complaint", "complain", "problem",
-        "matsala", "file complaint",
-    ],
-    "check_order": [
-        "bincika oda", "oda", "check order", "order status", "my order",
-        "where is my order", "track order",
-    ],
-    "reschedule": [
-        "sake tsara", "reschedule", "change time", "another day",
-        "later", "tomorrow",
-    ],
-    "return_item": [
-        "mayar da kaya", "return", "return item", "send back", "mayar",
-    ],
-}
-def _match_intent_keyword(text: str) -> Optional[str]:
-    # Whitespace-bounded match: the keyword must appear as a whole token (or
-    # token sequence), never as a fragment inside another word.
-    padded = f" {text.lower().strip()} "
-    all_kw = [(intent, kw) for intent, kws in INTENT_KEYWORDS.items() for kw in kws]
-    all_kw.sort(key=lambda x: len(x[1]), reverse=True)
-    for intent, kw in all_kw:
-        if f" {kw} " in padded:
-            return intent
-    return None
-# ---------------------------------------------------------------------------
-# Intent example dataset — the heart of the embedding NLU.
-# These phrases are encoded once into centroids; at inference, user input is
-# compared (cosine similarity) against each centroid. More examples = better
-# coverage of paraphrases. Hausa + English mixed deliberately so cross-lingual
-# matches work via the multilingual encoder.
-# ---------------------------------------------------------------------------
-INTENT_EXAMPLES = {
-    "check_balance": [
-        "duba ma'auni",
-        "ina son sanin kuɗin asusuna",
-        "nawa ne a asusuna",
-        "menene ma'aunin asusuna",
-        "yi mini bayanin asusuna",
-        "ina son ganin kuɗina",
-        "check my balance",
-        "what is my account balance",
-        "how much money do I have",
-        "show me my balance",
-        "tell me my balance",
-        "how much is in my account",
-    ],
-    "block_card": [
-        "toshe kati",
-        "ina son toshe katina",
-        "ɓatar da kati na",
-        "katina ya ɓace",
-        "yi mini taimako, kati na ya ɓace",
-        "in toshe ATM card",
-        "block my card",
-        "I lost my card",
-        "freeze my debit card",
-        "I need to cancel my card",
-        "my card was stolen",
-        "please block my ATM card",
-    ],
-    "transfer_money": [
-        "canjin kuɗi",
-        "ina son aika kuɗi",
-        "tura kuɗi zuwa wani",
-        "yi canji",
-        "in turawa abokina kuɗi",
-        "aiki kuɗi ga abokina",
-        "transfer money",
-        "send money to someone",
-        "I want to make a transfer",
-        "wire money to my friend",
-        "send naira to another account",
-        "make a payment",
-    ],
-    "buy_airtime": [
-        "saya airtime",
-        "ina son saya airtime",
-        "kunna waya",
-        "in saya credit",
-        "saya credit na waya",
-        "recharge waya na",
-        "buy airtime",
-        "top up my phone",
-        "recharge my phone",
-        "I need airtime",
-        "load credit",
-        "add credit to my phone",
-    ],
-    "buy_bundle": [
-        "saya bundle",
-        "ina son saya data",
-        "kunna intanet",
-        "in saya data bundle",
-        "saya megabyte",
-        "buy data",
-        "buy internet bundle",
-        "I want a data plan",
-        "purchase data bundle",
-        "get me a megabyte plan",
-        "subscribe to data",
-        "renew my data",
-    ],
-    "complaint": [
-        "yin korafi",
-        "ina da matsala",
-        "in yi koka",
-        "akwai matsala da hidima",
-        "ina son in kawo matsala",
-        "ba na gamsuwa",
-        "I want to file a complaint",
-        "I have a problem",
-        "report an issue",
-        "something is wrong",
-        "the service is bad",
-        "I'm not satisfied",
-    ],
-    "check_order": [
-        "bincika oda",
-        "ina oda na yake",
-        "tabbatar oda",
-        "yaushe za a kawo oda na",
-        "in san halin oda na",
-        "track order",
-        "where is my order",
-        "check order status",
-        "when will my order arrive",
-        "is my order ready",
-        "I want to know about my order",
-    ],
-    "reschedule": [
-        "sake tsara",
-        "ina son sake tsara lokaci",
-        "canjin ranar isar",
-        "in canza ranar kawowa",
-        "rana ta dabam",
-        "reschedule delivery",
-        "change delivery date",
-        "I want a different day",
-        "deliver tomorrow instead",
-        "postpone the delivery",
-        "move the delivery to later",
-    ],
-    "return_item": [
-        "mayar da kaya",
-        "ina son mayar da kaya",
-        "ba na son kaya",
-        "ina son mayarwa",
-        "kaya ba shi da kyau",
-        "return this item",
-        "I want to return my order",
-        "send it back",
-        "I want a refund",
-        "I don't want this anymore",
-        "the item is broken",
-    ],
-    "human_agent": [
-        "ina son magana da mutum",
-        "ka kawo mutum",
-        "wakili",
-        "in yi magana da wakilin",
-        "ba zan iya da bot ba",
-        "I want to speak to a human",
-        "connect me to an agent",
-        "transfer me to a person",
-        "I need to talk to someone",
-        "real person please",
-        "agent please",
-    ],
-}
-# Confidence threshold: cosine similarities below this become 'unknown'.
-# Tuned by hand at 0.4 — re-tune with eval_nlu.py (threshold sweep) once you
-# have real Hausa traffic from the turn logs.
-CONFIDENCE_THRESHOLD = 0.4
-# Embedding model. Multilingual (50+ languages), 420MB, CPU-fast.
-EMBEDDING_MODEL_ID = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
-# ---------------------------------------------------------------------------
-# Embedding model + centroid cache (lazy-loaded)
-# ---------------------------------------------------------------------------
-_encoder = None
-_intent_centroids: Optional[dict] = None  # intent_name -> np.ndarray
-_embed_failed = False
-def _load_encoder():
-    """Lazy-load the sentence encoder + compute intent centroids.
-    Pinned to CPU: on ZeroGPU the GPU isn't attached at import time, and the
-    encoder is fast enough on CPU (~200ms) that a GPU round-trip would be a net
-    loss — only ASR/TTS belong on the GPU."""
-    global _encoder, _intent_centroids, _embed_failed
-    if _embed_failed:
-        return None
-    if _encoder is not None:
-        return _encoder
-    try:
-        import numpy as np
-        from sentence_transformers import SentenceTransformer
-        logger.info(f"Loading embedding model {EMBEDDING_MODEL_ID}…")
-        _encoder = SentenceTransformer(EMBEDDING_MODEL_ID, device="cpu")
-        logger.info("Computing intent centroids…")
-        _intent_centroids = {}
-        for intent, phrases in INTENT_EXAMPLES.items():
-            # normalize_embeddings=True ⇒ unit vectors ⇒ dot product = cosine sim
-            embeddings = _encoder.encode(phrases, normalize_embeddings=True)
-            centroid = embeddings.mean(axis=0)
-            # Re-normalize the centroid so cosine math stays clean
-            centroid = centroid / np.linalg.norm(centroid)
-            _intent_centroids[intent] = centroid
-        logger.info(f"Encoder ready, {len(_intent_centroids)} intents.")
-        return _encoder
-    except Exception as e:
-        logger.warning(f"Encoder load failed: {e}")
-        _embed_failed = True
-        return None
-def _classify_with_embedding(text: str) -> Optional[tuple[str, float]]:
-    """Cosine similarity vs all intent centroids. Returns (intent, confidence)
-    or None on failure.
-    Note: we deliberately score against every intent rather than constraining by
-    the dialogue's expected slot. This is what lets a caller pivot mid-flow
-    (e.g. say "transfer money" while we're asking for account digits). The
-    expected-slot constraint is enforced upstream by the structural extractors
-    in parse(), not here."""
-    encoder = _load_encoder()
-    if encoder is None or _intent_centroids is None:
-        return None
-    try:
-        import numpy as np
-        query = encoder.encode(text, normalize_embeddings=True)
-        scores = {intent: float(np.dot(query, centroid))
-                  for intent, centroid in _intent_centroids.items()}
-        best_intent = max(scores, key=scores.get)
-        best_score = scores[best_intent]
-        top3 = {k: round(v, 3) for k, v in sorted(scores.items(), key=lambda x: -x[1])[:3]}
-        logger.info(f"NLU embedding: top match {best_intent}@{best_score:.3f}, top3: {top3}")
-        return best_intent, best_score
-    except Exception as e:
-        logger.warning(f"Embedding classification failed: {e}")
-        return None
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-def parse(text: str, expected: Optional[str] = None,
-          use_llm: bool = True) -> tuple[str, dict, str]:
-    """
-    NLU entry point. Returns (intent, entities, source) where source is:
-      - 'structural':    digit/amount/yes-no/name/date/text/bundle matched
-      - 'keyword':       keyword fast-path matched
-      - 'embedding':     sentence encoder matched above threshold
-      - 'human_keyword': escape-hatch keyword caught
-      - 'unknown':       nothing matched
-    `use_llm` is a misnomer kept for backward compat with the legacy module's
-    signature — here it means "use the embedding layer". Set False to test
-    rule-only behavior.
-    """
-    entities: dict = {}
-    if not text or not text.strip():
-        return "unknown", entities, "unknown"
-    # Layer 0: Always-on human-agent escape
-    if _contains_human_keyword(text):
-        return "human_agent", entities, "human_keyword"
-    # Layer 1: Structural extractors for slot-filling states
-    if expected == "digits":
-        d = _extract_digits(text)
-        if d:
-            entities["digits"] = d
-            return "provide_digits", entities, "structural"
-    if expected == "amount":
-        a = _extract_amount(text)
-        if a is not None:
-            entities["amount"] = a
-            return "provide_amount", entities, "structural"
-    if expected == "yesno":
-        yn = _match_yesno(text)
-        if yn:
-            return yn, entities, "structural"
-    if expected == "name":
-        # NOTE: naive — takes the last token, so "Musa Ibrahim" → "Ibrahim".
-        # Fine for single-name demos; add a recipient-confirmation turn before
-        # using this for real money movement.
-        name = text.strip().split()[-1] if text.strip() else ""
-        if name:
-            entities["name"] = name
-            return "provide_name", entities, "structural"
-    if expected == "date":
-        entities["date"] = text.strip()
-        return "provide_date", entities, "structural"
-    if expected == "text":
-        # Free-text capture (complaint body, return reason). Layer 0 already
-        # handled an explicit human-agent request, so anything else is content.
-        entities["text"] = text.strip()
-        return "provide_text", entities, "structural"
-    if expected == "bundle":
-        t = text.lower()
-        for b in BUNDLE_TYPES:
-            if f" {b} " in f" {t} " or t.strip() == b:
-                entities["bundle"] = b
-                return "provide_bundle", entities, "structural"
-        # No recognized bundle word — fall through so the user can still pivot
-        # (e.g. change their mind to airtime) or get a fallback re-prompt.
-    # Layer 1.5: Keyword fast-path (cheap, runs in any state so users can
-    # pivot intent mid-flow).
-    kw_intent = _match_intent_keyword(text)
-    if kw_intent:
-        logger.info(f"NLU keyword: matched {text!r} → {kw_intent}")
-        return kw_intent, entities, "keyword"
-    # Layer 2: Embedding similarity
-    if not use_llm:
-        logger.info(f"NLU: use_llm=False, returning unknown for {text!r}")
-        return "unknown", entities, "unknown"
-    embed_result = _classify_with_embedding(text)
-    if embed_result is None:
-        logger.warning(f"NLU embedding unavailable, returning unknown for {text!r}")
-        return "unknown", entities, "unknown"
-    intent, confidence = embed_result
-    if confidence < CONFIDENCE_THRESHOLD:
-        logger.info(f"NLU embedding: {intent}@{confidence:.3f} below threshold "
-                    f"{CONFIDENCE_THRESHOLD}, returning unknown")
-        return "unknown", entities, "unknown"
-    logger.info(f"NLU embedding accepted: {text!r} → {intent} (conf={confidence:.3f})")
-    return intent, entities, "embedding"

 """
+NLU Module — Multi-Intent Decomposition + Entity Extraction
+=============================================================
+Fixes P0/P1 from the feedback:
+  - Decomposes ONE user message into a LIST of tasks (compound requests)
+  - Extracts ALL entities present in the message (slot prefill —
+    "send money to abu" never re-asks for the recipient)
+  - Returns per-task confidence so destructive intents can be gated
+  - Distinguishes "ask about X" from "do X" (branch location ≠ block card)
+Backend chain (first available wins):
+  1. LLM_API    — HF Serverless Inference (set HF_TOKEN) — best quality
+  2. LLM_LOCAL  — Qwen2.5-1.5B-Instruct loaded in-process — good, slower
+  3. RULES      — improved keyword rules — degraded but never crashes
+All backends return the same schema:
+  {
+    "tasks": [
+      {
+        "intent": "send_money",
+        "confidence": 0.93,
+        "slots": {"recipient": "abu", "amount": "350000"},
+        "utterance_span": "send 350000 to abu"
+      },
+      ...
+    ],
+    "backend": "llm_api"
+  }
 """
+import os
 import re
+import json
 import logging
 from typing import Optional
+logger = logging.getLogger(__name__)
+# ── Intent catalogue (shared by all backends) ────────────────────────────────
+INTENT_SCHEMA = {
+    "greeting":         {"slots": [],                          "destructive": False},
+    "balance_inquiry":  {"slots": ["account_id"],              "destructive": False},
+    "send_money":       {"slots": ["recipient", "amount", "account_id"], "destructive": True},
+    "bill_payment":     {"slots": ["account_id", "amount"],    "destructive": True},
+    "block_card":       {"slots": ["account_id"],              "destructive": True},
+    "branch_info":      {"slots": [],                          "destructive": False},
+    "card_request":     {"slots": [],                          "destructive": False},
+    "report_issue":     {"slots": ["issue_desc"],              "destructive": False},
+    "track_order":      {"slots": ["order_id"],                "destructive": False},
+    "return_item":      {"slots": ["order_id", "return_reason"], "destructive": False},
+    "human_agent":      {"slots": [],                          "destructive": False},
+    "confirmation_yes": {"slots": [],                          "destructive": False},
+    "confirmation_no":  {"slots": [],                          "destructive": False},
+    "cancel":           {"slots": [],                          "destructive": False},
+    "goodbye":          {"slots": [],                          "destructive": False},
+    "unknown":          {"slots": [],                          "destructive": False},
 }
+NLU_SYSTEM_PROMPT = """You are the NLU module of a customer-service voice agent.
+Decompose the user's message into ALL tasks it contains, in order.
+Extract every entity present. Never invent entities that are not in the text.
+Intents: greeting, balance_inquiry, send_money, bill_payment, block_card,
+branch_info, card_request, report_issue, track_order, return_item,
+human_agent, confirmation_yes, confirmation_no, cancel, goodbye, unknown.
+Slots: recipient, amount, account_id, location, issue_desc, order_id, return_reason.
+CRITICAL disambiguation rules:
+- "where is your branch so I can get my card" = branch_info + card_request.
+  It is NOT block_card. Only choose block_card if the user explicitly wants to
+  BLOCK, FREEZE, or DEACTIVATE a card.
+- A message can contain multiple tasks joined by "and", "also", "then".
+  Output one task per action. "check my balance and send 5000 to musa"
+  = [balance_inquiry, send_money{recipient: musa, amount: 5000}].
+- If the user answers a question (e.g. gives a reason like "too small"),
+  map it to the slot of the pending task, intent = the pending intent.
+- Confidence in [0,1]: how sure you are of the INTENT (not the slots).
+Respond with ONLY valid JSON, no markdown, no commentary:
+{"tasks":[{"intent":"...","confidence":0.0,"slots":{},"utterance_span":"..."}]}"""
+class NLU:
+    def __init__(self, prefer: str = "auto"):
+        self.hf_token = os.getenv("HF_TOKEN", "")
+        self.api_model = os.getenv(
+            "NLU_API_MODEL", "Qwen/Qwen2.5-72B-Instruct")
+        self.local_model_id = os.getenv(
+            "NLU_LOCAL_MODEL", "Qwen/Qwen2.5-1.5B-Instruct")
+        self._local_pipe = None
+        self.prefer = prefer
+    # ── Public API ────────────────────────────────────────────────────────────
+    def parse(self, text: str, pending_intent: Optional[str] = None,
+              pending_slot: Optional[str] = None) -> dict:
+        """
+        text           : English pivot text of the user turn
+        pending_intent : intent currently awaiting a slot (context for the LLM)
+        pending_slot   : which slot we asked for last turn
+        """
+        context = ""
+        if pending_intent and pending_slot:
+            context = (f"\nContext: you previously asked the user for the "
+                       f"'{pending_slot}' of a '{pending_intent}' task. "
+                       f"A short answer likely fills that slot.")
+        for backend in self._backend_order():
+            try:
+                result = backend(text, context)
+                if result and result.get("tasks"):
+                    result = self._sanitize(result)
+                    logger.info(f"NLU[{result['backend']}]: "
+                                f"{json.dumps(result['tasks'])[:200]}")
+                    return result
+            except Exception as e:
+                logger.warning(f"NLU backend failed ({backend.__name__}): {e}")
+        # Absolute last resort
+        return {"tasks": [{"intent": "unknown", "confidence": 0.0,
+                            "slots": {}, "utterance_span": text}],
+                "backend": "none"}
+    # ── Backend chain ─────────────────────────────────────────────────────────
+    def _backend_order(self):
+        if self.prefer == "rules":
+            return [self._rules_backend]
+        chain = []
+        if self.hf_token:
+            chain.append(self._api_backend)
+        chain.append(self._local_backend)
+        chain.append(self._rules_backend)
+        return chain
+    # ── 1. HF Serverless Inference API ───────────────────────────────────────
+    def _api_backend(self, text: str, context: str) -> Optional[dict]:
+        import requests
+        url = f"https://api-inference.huggingface.co/models/{self.api_model}/v1/chat/completions"
+        payload = {
+            "model": self.api_model,
+            "messages": [
+                {"role": "system", "content": NLU_SYSTEM_PROMPT + context},
+                {"role": "user",   "content": text},
+            ],
+            "max_tokens": 400,
+            "temperature": 0.1,
+        }
+        r = requests.post(url, json=payload, timeout=20,
+                          headers={"Authorization": f"Bearer {self.hf_token}"})
+        r.raise_for_status()
+        raw = r.json()["choices"][0]["message"]["content"]
+        parsed = self._extract_json(raw)
+        if parsed:
+            parsed["backend"] = "llm_api"
+        return parsed
+    # ── 2. Local small LLM ──────────────────────────────────���─────────────────
+    def _local_backend(self, text: str, context: str) -> Optional[dict]:
+        if self._local_pipe is None:
+            logger.info(f"Loading local NLU model {self.local_model_id} …")
+            from transformers import pipeline as hf_pipeline
+            import torch
+            self._local_pipe = hf_pipeline(
+                "text-generation",
+                model=self.local_model_id,
+                torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
+                device_map="auto",
+            )
+        messages = [
+            {"role": "system", "content": NLU_SYSTEM_PROMPT + context},
+            {"role": "user",   "content": text},
+        ]
+        out = self._local_pipe(messages, max_new_tokens=400,
+                                do_sample=False, temperature=None, top_p=None)
+        raw = out[0]["generated_text"][-1]["content"]
+        parsed = self._extract_json(raw)
+        if parsed:
+            parsed["backend"] = "llm_local"
+        return parsed
+    # ── 3. Improved rules (never fails) ───────────────────────────────────────
+    def _rules_backend(self, text: str, context: str) -> dict:
+        """
+        Better than the old FSM keywords:
+          - splits on conjunctions to find MULTIPLE tasks
+          - extracts entities per clause
+          - branch_info vs block_card disambiguation
+        """
+        t = text.lower().strip()
+        # Split compound message into clauses
+        clauses = re.split(r'\b(?:and also|and then|then|and|also|;|\. )\b', t)
+        clauses = [c.strip() for c in clauses if c.strip()]
+        tasks = []
+        for clause in clauses:
+            task = self._rules_classify_clause(clause)
+            if task:
+                tasks.append(task)
+        # Merge duplicate consecutive intents (e.g. "and" split an entity off)
+        merged = []
+        for task in tasks:
+            if merged and merged[-1]["intent"] == task["intent"]:
+                merged[-1]["slots"].update(task["slots"])
+                merged[-1]["utterance_span"] += " " + task["utterance_span"]
+            else:
+                merged.append(task)
+        if not merged:
+            merged = [{"intent": "unknown", "confidence": 0.3,
+                       "slots": {}, "utterance_span": t}]
+        return {"tasks": merged, "backend": "rules"}
+    def _rules_classify_clause(self, clause: str) -> Optional[dict]:
+        slots = {}
+        # ── Entity extraction (always, regardless of intent) ────────────────
+        # In a money-action clause ("send/transfer/pay X to Y"), the number is
+        # an AMOUNT. Only treat 6-12 digit numbers as account_id when the
+        # clause is about the account itself, or there is no money verb.
+        money_verb = any(v in clause for v in ("send", "transfer", "pay"))
+        account_ctx = any(v in clause for v in ("account", "acct", "number is"))
+        numbers = re.findall(r'\b\d[\d,\.]*\b', clause)
+        for num in numbers:
+            digits = num.replace(",", "").replace(".", "")
+            if money_verb and "amount" not in slots and len(digits) <= 7:
+                slots["amount"] = digits
+            elif (account_ctx or not money_verb) and 6 <= len(digits) <= 12 \
+                    and "account_id" not in slots:
+                slots["account_id"] = digits
+            elif "amount" not in slots and len(digits) <= 7:
+                slots["amount"] = digits
+        # recipient: "to <name>" — take the LAST valid match, skipping verbs
+        # ("I want to send money to abu" must yield 'abu', not 'send')
+        RECIPIENT_STOPWORDS = {
+            "my", "the", "a", "an", "me", "you", "check", "send", "transfer",
+            "pay", "get", "make", "do", "know", "see", "block", "return",
+            "track", "him", "her", "them", "it", "confirm", "cancel"}
+        for m in re.finditer(r'\bto\s+([a-z]{2,20})\b', clause):
+            name = m.group(1)
+            if name not in RECIPIENT_STOPWORDS:
+                slots["recipient"] = name
+        # order id
+        m = re.search(r'\border\s*#?\s*([a-z0-9\-]{4,20})\b', clause)
+        if m:
+            slots["order_id"] = m.group(1)
+        # ── Intent (order matters: destructive intents need explicit verbs) ──
+        def has(*kws):
+            return any(kw in clause for kw in kws)
+        # branch/location questions BEFORE block_card — fixes P0 #2
+        if has("branch", "closest", "nearest", "location", "where is", "address"):
+            intent, conf = "branch_info", 0.85
+            if has("card", "atm"):
+                # compound: they also want a card — but NOT to block it
+                return {"intent": "branch_info", "confidence": 0.85,
+                        "slots": slots, "utterance_span": clause}
+        elif has("block my card", "block card", "freeze", "deactivate", "stolen", "lost my card"):
+            intent, conf = "block_card", 0.8
+        elif has("send", "transfer") and (slots.get("recipient") or slots.get("amount")):
+            intent, conf = "send_money", 0.85
+        elif has("send money", "transfer money"):
+            intent, conf = "send_money", 0.75
+        elif has("balance", "how much", "asusun"):
+            intent, conf = "balance_inquiry", 0.85
+        elif has("pay", "bill", "recharge", "invoice"):
+            intent, conf = "bill_payment", 0.75
+        elif has("track", "where is my order", "delivery", "shipment"):
+            intent, conf = "track_order", 0.8
+        elif has("return", "refund", "send back"):
+            intent, conf = "return_item", 0.8
+        elif has("problem", "issue", "complaint", "not working", "error"):
+            intent, conf = "report_issue", 0.7
+            slots["issue_desc"] = clause
+        elif has("human", "agent", "person", "operator", "representative"):
+            intent, conf = "human_agent", 0.9
+        elif has("yes", "yep", "correct", "confirm", "sure", "okay", "ok"):
+            intent, conf = "confirmation_yes", 0.8
+        elif has("no", "nope", "wrong", "cancel that"):
+            intent, conf = "confirmation_no", 0.8
+        elif has("hello", "hi ", "good morning", "sannu", "salam"):
+            intent, conf = "greeting", 0.9
+        elif has("bye", "goodbye", "thank"):
+            intent, conf = "goodbye", 0.85
+        else:
+            return {"intent": "unknown", "confidence": 0.3,
+                    "slots": slots, "utterance_span": clause}
+        return {"intent": intent, "confidence": conf,
+                "slots": slots, "utterance_span": clause}
+    # ── Helpers ───────────────────────────────────────────────────────────────
+    @staticmethod
+    def _extract_json(raw: str) -> Optional[dict]:
+        """Robustly pull the first JSON object out of LLM output."""
+        raw = raw.strip()
+        raw = re.sub(r'^```(?:json)?|```$', '', raw, flags=re.MULTILINE).strip()
+        # find first { … matching last }
+        start = raw.find("{")
+        end   = raw.rfind("}")
+        if start == -1 or end == -1:
+            return None
+        try:
+            return json.loads(raw[start:end + 1])
+        except json.JSONDecodeError:
+            return None
+    @staticmethod
+    def _sanitize(result: dict) -> dict:
+        """Validate schema, clamp confidence, drop hallucinated slots."""
+        valid_slots = {"recipient", "amount", "account_id", "location",
+                       "issue_desc", "order_id", "return_reason"}
+        clean_tasks = []
+        for task in result.get("tasks", []):
+            intent = task.get("intent", "unknown")
+            if intent not in INTENT_SCHEMA:
+                intent = "unknown"
+            conf = float(task.get("confidence", 0.5))
+            conf = max(0.0, min(1.0, conf))
+            slots = {k: str(v).strip() for k, v in (task.get("slots") or {}).items()
+                     if k in valid_slots and v not in (None, "", "null", "None")}
+            clean_tasks.append({
+                "intent": intent, "confidence": conf, "slots": slots,
+                "utterance_span": str(task.get("utterance_span", ""))[:200],
+            })
+        result["tasks"] = clean_tasks or [
+            {"intent": "unknown", "confidence": 0.0, "slots": {},
+             "utterance_span": ""}]
+        return result

orchestrator.py CHANGED Viewed

@@ -511,4 +511,4 @@ class Orchestrator:
                 return res["ticket_id"]
             except Exception as e:
                 logger.warning(f"CRM ticket failed: {e}")
-        return f"TKT-{session.session_id}-{str(uuid.uuid4())[:4].upper()}"

                 return res["ticket_id"]
             except Exception as e:
                 logger.warning(f"CRM ticket failed: {e}")
+        return f"TKT-{session.session_id}-{str(uuid.uuid4())[:4].upper()}"

test_regressions.py ADDED Viewed

	@@ -0,0 +1,124 @@

+"""
+Regression tests — one test per failure in the feedback.
+Runs with the RULES backend (no model download) so it's fast and CI-able.
+The LLM backends only improve on these results.
+"""
+import sys
+import logging
+logging.basicConfig(level=logging.WARNING)
+from nlu import NLU
+from orchestrator import Orchestrator, fmt_amount
+PASS, FAIL = "\033[92mPASS\033[0m", "\033[91mFAIL\033[0m"
+results = []
+def check(name: str, cond: bool, detail: str = ""):
+    results.append((name, cond))
+    print(f"  [{PASS if cond else FAIL}] {name}" + (f"  — {detail}" if detail else ""))
+def new_orch():
+    return Orchestrator(nlu=NLU(prefer="rules"))
+def turn(orch, session, text):
+    resp, session, esc = orch.respond(text, text, session)
+    return resp, session, esc
+print("\n══ P1: 'send money to abu now' must NOT re-ask for recipient ══")
+orch = new_orch()
+s = orch.new_session()
+resp, s, _ = turn(orch, s, "I want to send money to abu now")
+check("recipient 'abu' prefilled (no 'who do you want to send to')",
+      "who" not in resp.lower() and "abu" not in resp.lower().replace("abu", "") or
+      ("recipient" not in resp.lower() and "who would you like to send" not in resp.lower()),
+      f"agent said: {resp[:90]}")
+check("asks for the AMOUNT instead (the actually-missing slot)",
+      "how much" in resp.lower(), f"agent said: {resp[:90]}")
+print("\n══ P0: compound 'check my balance and also send 350000 to amina' ══")
+orch = new_orch()
+s = orch.new_session()
+resp, s, _ = turn(orch, s, "check my balance and also send 350000 to amina")
+check("acknowledges BOTH tasks", "one at a time" in resp.lower() or
+      ("balance" in resp.lower() and ("transfer" in resp.lower() or "amina" in resp.lower())),
+      f"agent said: {resp[:120]}")
+# give account number → balance executes, transfer flow continues
+resp, s, _ = turn(orch, s, "1234567890")
+check("balance is delivered", "balance is" in resp.lower(), f"{resp[:90]}")
+check("transfer to amina NOT dropped (asks to confirm or continues it)",
+      "amina" in resp.lower() or "send" in resp.lower() or "confirm" in resp.lower()
+      or "yes" in resp.lower(),
+      f"{resp[:140]}")
+print("\n══ P0: 'where is your closest branch so I can get my ATM card' ══")
+orch = new_orch()
+s = orch.new_session()
+resp, s, _ = turn(orch, s, "where is your closest branch so I can get my ATM card")
+check("NOT classified as block_card (no 'block' confirmation)",
+      "block" not in resp.lower(), f"{resp[:120]}")
+check("gives branch info", "branch" in resp.lower() or "open" in resp.lower(),
+      f"{resp[:120]}")
+print("\n══ P1: return reason 'too small' must not dead-end ══")
+orch = new_orch()
+s = orch.new_session()
+resp, s, _ = turn(orch, s, "I want to return my order")
+resp, s, _ = turn(orch, s, "ORD-4521")
+resp, s, _ = turn(orch, s, "too small")
+check("'too small' accepted as return reason",
+      "too small" in resp.lower() or "return" in resp.lower(),
+      f"{resp[:120]}")
+check("no 'did not understand' dead-end",
+      "didn't understand" not in resp.lower() and "did not understand" not in resp.lower(),
+      f"{resp[:90]}")
+print("\n══ P1: unknown input → clarify once, then human WITH context ══")
+orch = new_orch()
+s = orch.new_session()
+resp, s, esc = turn(orch, s, "florble the wumbus")
+check("first unknown → clarifying question, not menu dump",
+      "are you asking" in resp.lower() or "balance" in resp.lower(), f"{resp[:110]}")
+check("not escalated yet", not esc)
+resp, s, esc = turn(orch, s, "zorp zorp quux")
+check("second unknown → human handoff", esc, f"{resp[:110]}")
+check("handoff mentions context is preserved",
+      "won't have to repeat" in resp.lower() or "conversation" in resp.lower(),
+      f"{resp[:140]}")
+print("\n══ P2: balance guard — 350,000 against smaller balance ══")
+orch = new_orch()
+s = orch.new_session()
+resp, s, _ = turn(orch, s, "check my balance")
+resp, s, _ = turn(orch, s, "1111111")     # deterministic mock balance
+bal = s.balance
+too_much = bal + 100_000
+resp, s, _ = turn(orch, s, f"send {too_much} to musa")
+check("over-balance transfer is refused, not confirmed",
+      "can't process" in resp.lower() or "balance is" in resp.lower(),
+      f"balance={fmt_amount(bal)}, asked={fmt_amount(too_much)} → {resp[:130]}")
+print("\n══ P2: consistent ₦ formatting ══")
+check("fmt_amount('350000') == '₦350,000'", fmt_amount("350000") == "₦350,000")
+check("fmt_amount('134200') == '₦134,200'", fmt_amount("134200") == "₦134,200")
+check("fmt_amount(245000) == '₦245,000'",   fmt_amount(245000)   == "₦245,000")
+print("\n══ Destructive confirmation gate ══")
+orch = new_orch()
+s = orch.new_session()
+resp, s, _ = turn(orch, s, "send 5000 to fatima")
+resp, s, _ = turn(orch, s, "1234567890")   # account slot
+check("transfer requires explicit yes/no before executing",
+      "yes" in resp.lower() and "confirm" in resp.lower(), f"{resp[:130]}")
+resp, s, _ = turn(orch, s, "no")
+check("'no' cancels cleanly", "cancelled" in resp.lower(), f"{resp[:90]}")
+# ── Summary ────────────────────────────────────────────────────────────────────
+passed = sum(1 for _, ok in results if ok)
+total  = len(results)
+print(f"\n{'='*60}\n  {passed}/{total} checks passed\n{'='*60}")
+sys.exit(0 if passed == total else 1)