Update dialogue.py

dialogue.py

@@ -3,12 +3,29 @@ PlotWeaver Voice Agent — Dialogue Manager
 ==========================================
 FSM for multi-turn Hausa conversations across 3 verticals.
 State lives in Gradio session state (dict) — no Redis needed in the Space.
+
+What changed vs the POC
+-----------------------
+1. Backend actions: data/terminal states may carry an ``"action"`` key naming a
+   Backend method (see backend.py). The method runs on entry and merges
+   language-neutral results into ``state.slots``.
+2. Prompt templating: prompts may contain ``{slot}`` placeholders, filled from
+   slots via ``render_prompt``. Confirmations now echo the real amount/recipient
+   instead of saying "I'll send the money now" with no detail.
 """
 from __future__ import annotations
+
+import logging
 from dataclasses import dataclass, field, asdict
 from enum import Enum
 from typing import Optional
 
+from backend import Backend, MockBackend
+
+logger = logging.getLogger("plotweaver.dialogue")
+
+_DEFAULT_BACKEND: Backend = MockBackend()
+
 
 class Vertical(str, Enum):
     BANK = "bank"
@@ -53,8 +70,9 @@ SCENARIOS = {
                 "transitions": {"provide_digits": "return_balance"},
             },
             "return_balance": {
-                "ha": "Ma'aunin asusunka shine Naira dubu ɗari biyu da arba'in da biyar. Akwai wani abu?",
-                "en": "Your account balance is two hundred forty-five thousand Naira. Anything else?",
+                "ha": "Ma'aunin asusunka shine Naira {balance}. Akwai wani abu?",
+                "en": "Your account balance is {balance} Naira. Anything else?",
+                "action": "get_balance",
                 "expects": "yesno",
                 "transitions": {"yes": "greeting", "no": "exit"},
             },
@@ -65,8 +83,9 @@ SCENARIOS = {
                 "transitions": {"yes": "card_blocked", "no": "greeting"},
             },
             "card_blocked": {
-                "ha": "An toshe katinka. Sabon kati zai iso a cikin kwanaki uku zuwa biyar. Ana juya ka ga wakili don tabbatar.",
-                "en": "Your card is blocked. A new card will arrive in 3-5 days. Transferring you to an agent for confirmation.",
+                "ha": "An toshe katinka (lamba {block_ref}). Sabon kati zai iso a cikin kwanaki {card_eta_days}. Ana juya ka ga wakili don tabbatarwa.",
+                "en": "Your card is blocked (ref {block_ref}). A new card will arrive in {card_eta_days} days. Transferring you to an agent for confirmation.",
+                "action": "block_card",
                 "expects": None, "terminal": True, "escalate": True,
             },
             "ask_recipient": {
@@ -82,14 +101,15 @@ SCENARIOS = {
                 "transitions": {"provide_amount": "confirm_transfer"},
             },
             "confirm_transfer": {
-                "ha": "Zan tura kuɗin yanzu. Ka ce 'i' don ci gaba.",
-                "en": "I'll send the money now. Say 'yes' to continue.",
+                "ha": "Don tabbatarwa: zan tura Naira {amount} zuwa {name}. Ka ce 'i' don ci gaba.",
+                "en": "To confirm: I'll transfer {amount} Naira to {name}. Say 'yes' to continue.",
                 "expects": "yesno",
                 "transitions": {"yes": "transfer_done", "no": "greeting"},
             },
             "transfer_done": {
-                "ha": "An tura kuɗin. Godiya da zabar PlotWeaver Bank.",
-                "en": "Money sent. Thank you for choosing PlotWeaver Bank.",
+                "ha": "An tura Naira {amount} zuwa {name}. Lambar tabbatarwa: {txn_ref}. Godiya da zabar PlotWeaver Bank.",
+                "en": "Sent {amount} Naira to {name}. Reference: {txn_ref}. Thank you for choosing PlotWeaver Bank.",
+                "action": "transfer",
                 "expects": None, "terminal": True,
             },
         },
@@ -110,8 +130,9 @@ SCENARIOS = {
                 "transitions": {"provide_amount": "airtime_done"},
             },
             "airtime_done": {
-                "ha": "An kara airtime. Ma'aunin ka sabo shine Naira dubu ɗaya da ɗari biyar.",
-                "en": "Airtime loaded. Your new balance is 1500 Naira.",
+                "ha": "An kara Naira {amount} na airtime. Ma'aunin ka sabo shine Naira {airtime_balance}.",
+                "en": "Loaded {amount} Naira airtime. Your new balance is {airtime_balance} Naira.",
+                "action": "buy_airtime",
                 "expects": None, "terminal": True,
             },
             "ask_bundle_type": {
@@ -121,8 +142,9 @@ SCENARIOS = {
                 "transitions": {"provide_bundle": "bundle_done"},
             },
             "bundle_done": {
-                "ha": "An kunna bundle ɗinka. Za ka iya yin amfani da shi yanzu.",
-                "en": "Your bundle is active. You can use it now.",
+                "ha": "An kunna bundle na '{bundle}'. Za ka iya yin amfani da shi yanzu.",
+                "en": "Your '{bundle}' bundle is active. You can use it now.",
+                "action": "buy_bundle",
                 "expects": None, "terminal": True,
             },
             "ask_complaint": {
@@ -132,8 +154,9 @@ SCENARIOS = {
                 "transitions": {"provide_text": "escalate"},
             },
             "escalate": {
-                "ha": "Nagode. Zan juya ka ga wakili na mutum yanzu.",
-                "en": "Thank you. I'll transfer you to a human agent now.",
+                "ha": "Nagode. An buɗe lamba {ticket_id}. Zan juya ka ga wakili na mutum yanzu.",
+                "en": "Thank you. Ticket {ticket_id} opened. I'll transfer you to a human agent now.",
+                "action": "file_complaint",
                 "expects": None, "terminal": True, "escalate": True,
             },
         },
@@ -154,8 +177,9 @@ SCENARIOS = {
                 "transitions": {"provide_digits": "order_status"},
             },
             "order_status": {
-                "ha": "Oda ɗinka yana kan hanya. Za a isar gobe da yamma.",
-                "en": "Your order is on the way. It will be delivered tomorrow evening.",
+                "ha": "Oda {order_id} yana kan hanya. Za a isar gobe da yamma.",
+                "en": "Order {order_id} is on the way. It will be delivered tomorrow evening.",
+                "action": "check_order",
                 "expects": None, "terminal": True,
             },
             "ask_order_id_reschedule": {
@@ -171,8 +195,9 @@ SCENARIOS = {
                 "transitions": {"provide_date": "reschedule_done"},
             },
             "reschedule_done": {
-                "ha": "An sake tsara isar. Za ka sami SMS na tabbatarwa.",
-                "en": "Delivery rescheduled. You'll receive a confirmation SMS.",
+                "ha": "An sake tsara isar oda {order_id} zuwa {date}. Za ka sami SMS na tabbatarwa.",
+                "en": "Order {order_id} rescheduled to {date}. You'll receive a confirmation SMS.",
+                "action": "reschedule",
                 "expects": None, "terminal": True,
             },
             "ask_order_id_return": {
@@ -188,8 +213,9 @@ SCENARIOS = {
                 "transitions": {"provide_reason": "return_done"},
             },
             "return_done": {
-                "ha": "An karɓi buƙatarka. Wakili zai tattara kaya a gobe.",
-                "en": "Your request is received. An agent will collect the item tomorrow.",
+                "ha": "An karɓi buƙatarka (lamba {return_ref}). Wakili zai tattara kaya a gobe.",
+                "en": "Your request is received (ref {return_ref}). An agent will collect the item tomorrow.",
+                "action": "return_item",
                 "expects": None, "terminal": True,
             },
         },
@@ -198,8 +224,7 @@ SCENARIOS = {
 
 
 # Vertical-specific fallback prompts — spoken when the user asks something
-# out of scope. Each prompt: (1) acknowledges confusion, (2) lists the
-# services this bot CAN perform in that vertical, (3) offers human agent.
+# out of scope.
 FALLBACK_PROMPTS = {
     "bank": {
         "ha": "Ban fahimci tambayarka ba. A nan, zan iya taimake ka da 'duba ma'auni', 'toshe kati', ko 'canjin kuɗi'. Don wasu tambayoyi, ka ce 'wakili' don yin magana da mutum.",
@@ -219,7 +244,16 @@ FALLBACK_PROMPTS = {
 MAX_CONSECUTIVE_UNKNOWNS = 2
 
 
+class _SafeDict(dict):
+    """format_map helper: leaves unknown placeholders intact instead of raising,
+    so a missing slot surfaces as a visible literal during testing."""
+
+    def __missing__(self, key):
+        return "{" + key + "}"
+
+
 def get_prompt(vertical: str, state_name: str) -> dict:
+    """Raw prompt (may contain {slot} placeholders). Use render_prompt to fill."""
     if state_name == "escalate_virtual":
         return {"ha": "Zan juya ka ga wakili na mutum yanzu. Ka jira ɗan lokaci.",
                 "en": "I'll transfer you to a human agent now. Please hold."}
@@ -233,6 +267,13 @@ def get_prompt(vertical: str, state_name: str) -> dict:
     return {"ha": s["ha"], "en": s["en"]}
 
 
+def render_prompt(vertical: str, state_name: str, slots: dict) -> dict:
+    """Prompt with {slot} placeholders interpolated from slots."""
+    p = get_prompt(vertical, state_name)
+    safe = _SafeDict(slots or {})
+    return {k: v.format_map(safe) for k, v in p.items()}
+
+
 def get_expected_slot(vertical: str, state_name: str) -> Optional[str]:
     if state_name == "fallback":
         # Fallback accepts any intent — user might repeat, rephrase, or escalate
@@ -241,7 +282,30 @@ def get_expected_slot(vertical: str, state_name: str) -> Optional[str]:
     return s.get("expects") if s else None
 
 
-def transition(state: DialogueState, intent: str, entities: dict) -> DialogueState:
+def _maybe_run_action(backend: Backend, vertical: str, state_name: str, state: "DialogueState") -> None:
+    """If the target state declares an action, call the backend and merge the
+    returned (language-neutral) values into slots. Never raises into the FSM."""
+    spec = SCENARIOS[vertical]["states"].get(state_name, {})
+    action = spec.get("action")
+    if not action or backend is None:
+        return
+    method = getattr(backend, action, None)
+    if method is None:
+        logger.warning("Backend has no action %r", action)
+        return
+    try:
+        result = method(dict(state.slots))
+        if result:
+            state.slots.update(result)
+    except Exception as e:
+        logger.warning("Backend action %r failed: %s", action, e)
+
+
+def transition(state: DialogueState, intent: str, entities: dict,
+               backend: Optional[Backend] = None) -> DialogueState:
+    if backend is None:
+        backend = _DEFAULT_BACKEND
+
     state.turn_count += 1
     for k, v in entities.items():
         state.slots[k] = v
@@ -297,6 +361,9 @@ def transition(state: DialogueState, intent: str, entities: dict) -> DialogueSta
     if next_state:
         state.current_state = next_state
         target = SCENARIOS[state.vertical]["states"].get(next_state, {})
+        # Run any backend action attached to the state we just entered, so its
+        # results are in slots before the prompt is rendered.
+        _maybe_run_action(backend, state.vertical, next_state, state)
         if target.get("escalate"):
             state.escalate_to_human = True
     else: