Update nlu.py

nlu.py

@@ -1,5 +1,5 @@
 """
-NLU — NLLB + Qwen pivot-through-English architecture.
+NLU — NLLB + Qwen pivot-through-English architecture with keyword fast-path.
 
 Flow:
   1. Deterministic structural extractors run FIRST on the original Hausa
@@ -8,15 +8,19 @@ Flow:
      for banks, and regex is faster + more reliable than any model for
      this sub-task.
 
-  2. If structural extractors don't match the expected slot type, the text
-     is translated Hausa → English via NLLB-200, then classified by
-     Qwen2.5-1.5B in English (where it is strong) into one of a small
-     fixed set of intent labels.
+  2. Keyword fast-path for common Hausa + English intent phrases. Matches
+     "check balance", "duba ma'auni", "canjin kuɗi", etc. in <10ms without
+     loading any model. This is what real voice bots use for 90% of turns.
 
-  3. If NLLB or Qwen fails, we return "unknown" cleanly — the dialogue
-     manager will re-prompt.
+  3. If structural + keyword layers don't match, the text is translated
+     Hausa → English via NLLB-200 (skipped if input is already English),
+     then classified by Qwen2.5-1.5B in English (where it is strong) into
+     one of a small fixed set of intent labels.
 
-All models are lazy-loaded on first use. Cold-start downloads:
+  4. If NLLB or Qwen fails, we return "unknown" cleanly — the dialogue
+     manager routes to a vertical-specific fallback prompt.
+
+All heavy models are lazy-loaded on first use. Cold-start downloads:
   - NLLB-200-distilled-600M: ~2.4 GB
   - Qwen2.5-1.5B-Instruct: ~3 GB
 """
@@ -88,6 +92,81 @@ def _contains_human_keyword(text: str) -> bool:
     return any(kw in t for kw in HUMAN_KEYWORDS)
 
 
+# Keyword fast-path for common intents. Runs BEFORE NLLB+Qwen so that the
+# scripted demo flows don't require a 6GB LLM load. Phrases are Hausa and
+# English pairs that customers actually use. When none match, we fall
+# through to NLLB+Qwen for paraphrases.
+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]:
+    """Keyword fast-path for common customer-service intents.
+    Returns the intent name if a keyword matches, else None."""
+    t = text.lower().strip()
+    # Check longer phrases first so "check balance" wins over "check order"
+    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 kw in t:
+            return intent
+    return None
+
+
+def _looks_english(text: str) -> bool:
+    """Heuristic: if text contains no Hausa-specific characters and is majority
+    ASCII, treat as English and skip NLLB translation. Hausa uses ɓ, ɗ, ƙ, ƴ
+    and the apostrophe in 'a'a', 'ma'auni', 'jumma'a' etc."""
+    hausa_chars = set("ɓɗƙƴƁƊƘƳ")
+    if any(c in hausa_chars for c in text):
+        return False
+    # Common Hausa words — if any match, treat as Hausa
+    hausa_markers = {
+        "duba", "ma'auni", "toshe", "kati", "canjin", "kuɗi", "kudi",
+        "saya", "airtime", "bundle", "korafi", "bincika", "oda",
+        "sake", "tsara", "mayar", "kaya", "wakili", "mutum",
+        "sannu", "nagode", "don", "allah", "ka", "yana", "tana",
+        "dubu", "ɗari", "dari", "biyar", "biyu", "uku", "hudu", "huɗu",
+    }
+    tokens = set(text.lower().split())
+    return not bool(tokens & hausa_markers)
+
+
 # ---------------------------------------------------------------------------
 # NLLB-200 Ha → En translation (lazy-loaded)
 # ---------------------------------------------------------------------------
@@ -277,8 +356,10 @@ def parse(text: str, expected: Optional[str] = None,
           use_llm: bool = True) -> tuple[str, dict, str]:
     """
     NLU. Returns (intent, entities, source) where source is one of:
-      - 'structural': deterministic extractor caught it (digits, amount, yes/no)
-      - 'nllb+qwen': translated via NLLB and classified via Qwen
+      - 'structural': deterministic extractor caught digits/amount/yes-no
+      - 'keyword': fast-path keyword matcher caught a common intent
+      - 'qwen_en': input was English, classified directly by Qwen
+      - 'nllb+qwen': translated via NLLB then classified via Qwen
       - 'human_keyword': caught human-agent escape hatch by keyword
       - 'unknown': nothing matched
     """
@@ -309,8 +390,7 @@ def parse(text: str, expected: Optional[str] = None,
             return yn, entities, "structural"
 
     if expected == "name":
-        # Name is free-form; take the last token as a quick heuristic. Qwen
-        # would not help here — names don't translate meaningfully.
+        # Name is free-form; take the last token as a quick heuristic.
         name = text.strip().split()[-1] if text.strip() else ""
         if name:
             entities["name"] = name
@@ -320,22 +400,43 @@ def parse(text: str, expected: Optional[str] = None,
         entities["date"] = text.strip()
         return "provide_date", entities, "structural"
 
-    # Layer 2: NLLB Ha → En, then Qwen classification
+    # Layer 1.5: Keyword fast-path for common intents (Hausa + English).
+    # Runs in ANY state so users can pivot intent mid-flow ("actually I want
+    # to transfer money instead"). Structural extractors above already
+    # claimed strict-slot cases, so if we're in a slot-filling state and
+    # the text didn't match the slot, it's fair game to re-interpret as a
+    # new intent.
+    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: NLLB Ha → En (skip if input already English), then Qwen
     if not use_llm:
+        logger.info(f"NLU: use_llm=False, returning unknown for {text!r}")
         return "unknown", entities, "unknown"
 
-    english_text = translate_ha_to_en(text)
-    if english_text is None:
-        return "unknown", entities, "unknown"
+    if _looks_english(text):
+        logger.info(f"NLU: input looks English, skipping NLLB: {text!r}")
+        english_text = text
+        source_tag = "qwen_en"
+    else:
+        logger.info(f"NLU: translating Hausa via NLLB: {text!r}")
+        english_text = translate_ha_to_en(text)
+        if english_text is None:
+            logger.warning("NLU: NLLB failed, returning unknown")
+            return "unknown", entities, "unknown"
+        source_tag = "nllb+qwen"
 
     qwen_result = _qwen_classify(english_text, expected)
     if qwen_result is None:
+        logger.warning(f"NLU: Qwen returned no valid intent for {english_text!r}")
         return "unknown", entities, "unknown"
 
     intent, llm_entities = qwen_result
+    logger.info(f"NLU: Qwen classified {english_text!r} → intent={intent}")
 
-    # For free-text slots, pass the original Hausa text through (don't want
-    # English-translated complaint text stored as a Hausa complaint)
+    # For free-text slots, pass the original Hausa text through
     if expected == "bundle":
         t = text.lower()
         for b in ("rana", "mako", "wata"):
@@ -346,4 +447,4 @@ def parse(text: str, expected: Optional[str] = None,
     if expected == "text":
         llm_entities["text"] = text.strip()
 
-    return intent, llm_entities, "nllb+qwen"
+    return intent, llm_entities, source_tag