dialogue.py

"""
PlotWeaver Voice Agent — Dialogue Manager
==========================================
FSM for multi-turn Hausa conversations across 3 verticals.
State lives in Gradio session state (dict) — no Redis needed in the Space.
"""
from __future__ import annotations
from dataclasses import dataclass, field, asdict
from enum import Enum
from typing import Optional


class Vertical(str, Enum):
    BANK = "bank"
    TELECOM = "telecom"
    ECOMMERCE = "ecommerce"


@dataclass
class DialogueState:
    session_id: str
    vertical: str
    current_state: str = "greeting"
    slots: dict = field(default_factory=dict)
    turn_count: int = 0
    escalate_to_human: bool = False
    history: list = field(default_factory=list)
    consecutive_unknowns: int = 0
    state_before_fallback: Optional[str] = None

    def to_dict(self):
        return asdict(self)

    @classmethod
    def from_dict(cls, d):
        return cls(**d) if d else None


SCENARIOS = {
    "bank": {
        "name": "PlotWeaver Bank",
        "states": {
            "greeting": {
                "ha": "Sannu! Wannan shine mataimakin banki na PlotWeaver. Yaya zan taimake ka yau? Za ka iya ce 'duba ma'auni', 'toshe kati', ko 'canjin kuɗi'.",
                "en": "Hello! This is the PlotWeaver banking assistant. How can I help you today? You can say 'check balance', 'block card', or 'transfer money'.",
                "expects": "intent",
                "transitions": {"check_balance": "ask_account_number", "block_card": "confirm_block_card", "transfer_money": "ask_recipient"},
            },
            "ask_account_number": {
                "ha": "Don Allah ka faɗi lambobin ƙarshe huɗu na asusunka.",
                "en": "Please say the last four digits of your account number.",
                "expects": "digits",
                "transitions": {"provide_digits": "return_balance"},
            },
            "return_balance": {
                "ha": "Ma'aunin asusunka shine Naira dubu ɗari biyu da arba'in da biyar. Akwai wani abu?",
                "en": "Your account balance is two hundred forty-five thousand Naira. Anything else?",
                "expects": "yesno",
                "transitions": {"yes": "greeting", "no": "exit"},
            },
            "confirm_block_card": {
                "ha": "Don tabbatar, kana son toshe katinka? Ka ce 'i' ko 'a'a'.",
                "en": "To confirm, you want to block your card? Say 'yes' or 'no'.",
                "expects": "yesno",
                "transitions": {"yes": "card_blocked", "no": "greeting"},
            },
            "card_blocked": {
                "ha": "An toshe katinka. Sabon kati zai iso a cikin kwanaki uku zuwa biyar. Ana juya ka ga wakili don tabbatar.",
                "en": "Your card is blocked. A new card will arrive in 3-5 days. Transferring you to an agent for confirmation.",
                "expects": None, "terminal": True, "escalate": True,
            },
            "ask_recipient": {
                "ha": "Zuwa wa kake son turawa? Ka faɗi sunan mai karɓa.",
                "en": "Who do you want to transfer to? Say the recipient's name.",
                "expects": "name",
                "transitions": {"provide_name": "ask_amount"},
            },
            "ask_amount": {
                "ha": "Nawa kake son turawa, a Naira?",
                "en": "How much do you want to transfer, in Naira?",
                "expects": "amount",
                "transitions": {"provide_amount": "confirm_transfer"},
            },
            "confirm_transfer": {
                "ha": "Zan tura kuɗin yanzu. Ka ce 'i' don ci gaba.",
                "en": "I'll send the money now. Say 'yes' to continue.",
                "expects": "yesno",
                "transitions": {"yes": "transfer_done", "no": "greeting"},
            },
            "transfer_done": {
                "ha": "An tura kuɗin. Godiya da zabar PlotWeaver Bank.",
                "en": "Money sent. Thank you for choosing PlotWeaver Bank.",
                "expects": None, "terminal": True,
            },
        },
    },
    "telecom": {
        "name": "PlotWeaver Telecom",
        "states": {
            "greeting": {
                "ha": "Sannu! Wannan shine PlotWeaver Telecom. Kana son 'saya airtime', 'saya bundle', ko 'yin korafi'?",
                "en": "Hello! This is PlotWeaver Telecom. Would you like to 'buy airtime', 'buy bundle', or 'file a complaint'?",
                "expects": "intent",
                "transitions": {"buy_airtime": "ask_airtime_amount", "buy_bundle": "ask_bundle_type", "complaint": "ask_complaint"},
            },
            "ask_airtime_amount": {
                "ha": "Nawa na airtime kake son saya? Misali, Naira ɗari ko dubu.",
                "en": "How much airtime? For example 100 or 1000 Naira.",
                "expects": "amount",
                "transitions": {"provide_amount": "airtime_done"},
            },
            "airtime_done": {
                "ha": "An kara airtime. Ma'aunin ka sabo shine Naira dubu ɗaya da ɗari biyar.",
                "en": "Airtime loaded. Your new balance is 1500 Naira.",
                "expects": None, "terminal": True,
            },
            "ask_bundle_type": {
                "ha": "Wane irin bundle? Muna da 'rana', 'mako', ko 'wata'.",
                "en": "Which bundle type? 'day', 'week', or 'month'.",
                "expects": "bundle",
                "transitions": {"provide_bundle": "bundle_done"},
            },
            "bundle_done": {
                "ha": "An kunna bundle ɗinka. Za ka iya yin amfani da shi yanzu.",
                "en": "Your bundle is active. You can use it now.",
                "expects": None, "terminal": True,
            },
            "ask_complaint": {
                "ha": "Me ya faru? Ka bayyana matsalar da kake fuskanta.",
                "en": "What happened? Please describe the issue.",
                "expects": "text",
                "transitions": {"provide_text": "escalate"},
            },
            "escalate": {
                "ha": "Nagode. Zan juya ka ga wakili na mutum yanzu.",
                "en": "Thank you. I'll transfer you to a human agent now.",
                "expects": None, "terminal": True, "escalate": True,
            },
        },
    },
    "ecommerce": {
        "name": "PlotWeaver Delivery",
        "states": {
            "greeting": {
                "ha": "Sannu! Wannan shine PlotWeaver Delivery. Kana son 'bincika oda', 'sake tsara lokaci', ko 'mayar da kaya'?",
                "en": "Hello! This is PlotWeaver Delivery. Would you like to 'check order', 'reschedule', or 'return'?",
                "expects": "intent",
                "transitions": {"check_order": "ask_order_id", "reschedule": "ask_order_id_reschedule", "return_item": "ask_order_id_return"},
            },
            "ask_order_id": {
                "ha": "Ka faɗi lambar oda naka.",
                "en": "Say your order number.",
                "expects": "digits",
                "transitions": {"provide_digits": "order_status"},
            },
            "order_status": {
                "ha": "Oda ɗinka yana kan hanya. Za a isar gobe da yamma.",
                "en": "Your order is on the way. It will be delivered tomorrow evening.",
                "expects": None, "terminal": True,
            },
            "ask_order_id_reschedule": {
                "ha": "Ka faɗi lambar oda da kake son sake tsarawa.",
                "en": "Say the order number you want to reschedule.",
                "expects": "digits",
                "transitions": {"provide_digits": "ask_new_date"},
            },
            "ask_new_date": {
                "ha": "Wace rana kake so? Misali 'jumma'a' ko 'asabar'.",
                "en": "Which day? For example 'Friday' or 'Saturday'.",
                "expects": "date",
                "transitions": {"provide_date": "reschedule_done"},
            },
            "reschedule_done": {
                "ha": "An sake tsara isar. Za ka sami SMS na tabbatarwa.",
                "en": "Delivery rescheduled. You'll receive a confirmation SMS.",
                "expects": None, "terminal": True,
            },
            "ask_order_id_return": {
                "ha": "Ka faɗi lambar oda da kake son mayarwa.",
                "en": "Say the order number you want to return.",
                "expects": "digits",
                "transitions": {"provide_digits": "return_reason"},
            },
            "return_reason": {
                "ha": "Me ya sa kake son mayarwa?",
                "en": "Why do you want to return it?",
                "expects": "text",
                "transitions": {"provide_reason": "return_done"},
            },
            "return_done": {
                "ha": "An karɓi buƙatarka. Wakili zai tattara kaya a gobe.",
                "en": "Your request is received. An agent will collect the item tomorrow.",
                "expects": None, "terminal": True,
            },
        },
    },
}


# 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.
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.",
        "en": "I didn't understand your question. Here I can help with 'check balance', 'block card', or 'transfer money'. For other questions, say 'agent' to speak with a person.",
    },
    "telecom": {
        "ha": "Ban fahimci tambayarka ba. Zan iya taimake ka da 'saya airtime', 'saya bundle', ko 'yin korafi'. Don wasu tambayoyi, ka ce 'wakili' don yin magana da mutum.",
        "en": "I didn't understand your question. I can help with 'buy airtime', 'buy bundle', or 'file a complaint'. For other questions, say 'agent' to speak with a person.",
    },
    "ecommerce": {
        "ha": "Ban fahimci tambayarka ba. Zan iya taimake ka da 'bincika oda', 'sake tsara lokaci', ko 'mayar da kaya'. Don wasu tambayoyi, ka ce 'wakili' don yin magana da mutum.",
        "en": "I didn't understand your question. I can help with 'check order', 'reschedule delivery', or 'return an item'. For other questions, say 'agent' to speak with a person.",
    },
}

# After this many consecutive 'unknown' intents, auto-escalate to human.
MAX_CONSECUTIVE_UNKNOWNS = 2


def get_prompt(vertical: str, state_name: str) -> dict:
    if state_name == "escalate_virtual":
        return {"ha": "Zan juya ka ga wakili na mutum yanzu. Ka jira ɗan lokaci.",
                "en": "I'll transfer you to a human agent now. Please hold."}
    if state_name == "exit":
        return {"ha": "Nagode. Sai watan.", "en": "Thank you. Goodbye."}
    if state_name == "fallback":
        return FALLBACK_PROMPTS.get(vertical, FALLBACK_PROMPTS["bank"])
    s = SCENARIOS[vertical]["states"].get(state_name)
    if not s:
        return {"ha": "Ban fahimci abin da ka ce ba.", "en": "I didn't understand."}
    return {"ha": s["ha"], "en": s["en"]}


def get_expected_slot(vertical: str, state_name: str) -> Optional[str]:
    if state_name == "fallback":
        # Fallback accepts any intent — user might repeat, rephrase, or escalate
        return "intent"
    s = SCENARIOS[vertical]["states"].get(state_name)
    return s.get("expects") if s else None


def transition(state: DialogueState, intent: str, entities: dict) -> DialogueState:
    state.turn_count += 1
    for k, v in entities.items():
        state.slots[k] = v

    # Explicit human-agent request or too many turns → escalate
    if intent == "human_agent" or state.turn_count > 12:
        state.current_state = "escalate_virtual"
        state.escalate_to_human = True
        return state

    # Unknown intent handling: route to fallback, track consecutive count,
    # auto-escalate if user keeps asking out-of-scope things.
    if intent == "unknown":
        state.consecutive_unknowns += 1
        if state.consecutive_unknowns >= MAX_CONSECUTIVE_UNKNOWNS:
            state.current_state = "escalate_virtual"
            state.escalate_to_human = True
            return state
        if state.current_state != "fallback":
            state.state_before_fallback = state.current_state
        state.current_state = "fallback"
        return state

    # Recognized intent → reset the unknown counter
    state.consecutive_unknowns = 0

    # If we're in fallback and the user now says something recognized,
    # resume from the state we were in before falling back
    if state.current_state == "fallback" and state.state_before_fallback:
        resume_state = state.state_before_fallback
        state.state_before_fallback = None
        state.current_state = resume_state

    current = SCENARIOS[state.vertical]["states"].get(state.current_state)
    if not current:
        state.current_state = "greeting"
        current = SCENARIOS[state.vertical]["states"]["greeting"]

    # Try transition from the current state first
    next_state = current.get("transitions", {}).get(intent)

    # If current state has no transition for this intent, but GREETING does,
    # treat this as the user pivoting to a new top-level intent (e.g. midway
    # through balance check they say "transfer money" instead). Restart flow.
    if not next_state:
        greeting = SCENARIOS[state.vertical]["states"]["greeting"]
        pivot_state = greeting.get("transitions", {}).get(intent)
        if pivot_state:
            state.slots = {}  # Reset slots when starting a new flow
            state.state_before_fallback = None
            next_state = pivot_state

    if next_state:
        state.current_state = next_state
        target = SCENARIOS[state.vertical]["states"].get(next_state, {})
        if target.get("escalate"):
            state.escalate_to_human = True
    else:
        # Intent recognized but neither current state nor greeting has a
        # transition for it. Route to fallback.
        state.consecutive_unknowns += 1
        if state.consecutive_unknowns >= MAX_CONSECUTIVE_UNKNOWNS:
            state.current_state = "escalate_virtual"
            state.escalate_to_human = True
            return state
        if state.current_state != "fallback":
            state.state_before_fallback = state.current_state
        state.current_state = "fallback"

    return state