Upload 4 files

backend.py

@@ -0,0 +1,88 @@
+"""
+PlotWeaver Voice Agent — Backend interface
+==========================================
+Separates *what the bot says* (dialogue.py) from *what actually happens*
+(account lookups, card blocks, transfers, order status, ...).
+
+How it wires in
+---------------
+A state spec in dialogue.py may carry an optional ``"action"`` key naming a
+Backend method. When the FSM transitions *into* that state, it calls the
+method with the current slots dict; the method returns a dict of values that
+are merged back into slots, which the prompt templates then interpolate.
+
+Contract
+--------
+Backends return ONLY language-neutral data — numbers, ids, names, dates the
+caller supplied. They never return Hausa/English sentences: all phrasing lives
+in dialogue.py prompts. This keeps a real integration (bank sandbox, telecom
+API, logistics API) free of any localization concern.
+
+MockBackend ships canned-but-input-aware data for the demo. To go live, drop in
+an implementation satisfying the ``Backend`` protocol; dialogue.py is unchanged.
+"""
+from __future__ import annotations
+
+import random
+import string
+from typing import Protocol, runtime_checkable
+
+
+def _ref(prefix: str, n: int = 6) -> str:
+    return prefix + "".join(random.choices(string.ascii_uppercase + string.digits, k=n))
+
+
+@runtime_checkable
+class Backend(Protocol):
+    # --- bank ---
+    def get_balance(self, slots: dict) -> dict: ...
+    def block_card(self, slots: dict) -> dict: ...
+    def transfer(self, slots: dict) -> dict: ...
+    # --- telecom ---
+    def buy_airtime(self, slots: dict) -> dict: ...
+    def buy_bundle(self, slots: dict) -> dict: ...
+    def file_complaint(self, slots: dict) -> dict: ...
+    # --- ecommerce ---
+    def check_order(self, slots: dict) -> dict: ...
+    def reschedule(self, slots: dict) -> dict: ...
+    def return_item(self, slots: dict) -> dict: ...
+
+
+class MockBackend:
+    """Deterministic-enough mock. Echoes user-provided slots so confirmations
+    and receipts reflect what the caller actually said, and fabricates only the
+    values a real backend would return (balances, refs, etc.)."""
+
+    # --- bank ---
+    def get_balance(self, slots: dict) -> dict:
+        return {"balance": "245,000", "account_last4": slots.get("digits", "")}
+
+    def block_card(self, slots: dict) -> dict:
+        return {"card_eta_days": "3-5", "block_ref": _ref("BLK")}
+
+    def transfer(self, slots: dict) -> dict:
+        return {
+            "txn_ref": _ref("TXN"),
+            "amount": slots.get("amount", ""),
+            "name": slots.get("name", ""),
+        }
+
+    # --- telecom ---
+    def buy_airtime(self, slots: dict) -> dict:
+        return {"amount": slots.get("amount", ""), "airtime_balance": "1,500"}
+
+    def buy_bundle(self, slots: dict) -> dict:
+        return {"bundle": slots.get("bundle", "")}
+
+    def file_complaint(self, slots: dict) -> dict:
+        return {"ticket_id": _ref("TKT")}
+
+    # --- ecommerce ---
+    def check_order(self, slots: dict) -> dict:
+        return {"order_id": slots.get("digits", "")}
+
+    def reschedule(self, slots: dict) -> dict:
+        return {"order_id": slots.get("digits", ""), "date": slots.get("date", "")}
+
+    def return_item(self, slots: dict) -> dict:
+        return {"order_id": slots.get("digits", ""), "return_ref": _ref("RET")}

eval_nlu.py

@@ -0,0 +1,100 @@
+"""
+NLU eval harness — intent accuracy, threshold sweep, per-intent recall.
+=======================================================================
+Usage:
+    python eval_nlu.py                 # leave-one-out over INTENT_EXAMPLES
+    python eval_nlu.py labeled.csv     # external set, columns: text,intent
+
+Leave-one-out is a *sanity* tool: for each example phrase, it is held out of
+its own intent's centroid, then classified. It tells you whether the centroids
+are internally separable and lets you sweep CONFIDENCE_THRESHOLD. It does NOT
+substitute for a held-out, human-labeled Hausa test set — collect that from the
+turn logs (logging_util.py) and pass it as the CSV argument.
+"""
+from __future__ import annotations
+
+import csv
+import sys
+from collections import defaultdict
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+from nlu import INTENT_EXAMPLES, EMBEDDING_MODEL_ID, CONFIDENCE_THRESHOLD
+
+THRESHOLDS = [0.30, 0.35, 0.40, 0.45, 0.50, 0.55, 0.60]
+
+
+def _centroid(vecs, exclude=None):
+    if exclude is not None:
+        vecs = [v for i, v in enumerate(vecs) if i != exclude]
+    c = np.mean(vecs, axis=0)
+    return c / np.linalg.norm(c)
+
+
+def _build_records(encoder):
+    """Returns list of (text, gold_intent, pred_intent, confidence)."""
+    emb = {it: encoder.encode(ph, normalize_embeddings=True)
+           for it, ph in INTENT_EXAMPLES.items()}
+
+    if len(sys.argv) > 1:
+        rows = list(csv.DictReader(open(sys.argv[1], encoding="utf-8")))
+        cents = {it: _centroid(list(v)) for it, v in emb.items()}
+        records = []
+        for r in rows:
+            q = encoder.encode(r["text"], normalize_embeddings=True)
+            scores = {it: float(np.dot(q, c)) for it, c in cents.items()}
+            best = max(scores, key=scores.get)
+            records.append((r["text"], r["intent"], best, scores[best]))
+        return records
+
+    # leave-one-out over the examples themselves
+    records = []
+    for it, vecs in emb.items():
+        vecs = list(vecs)
+        for i, q in enumerate(vecs):
+            cents = {jt: (_centroid(list(v), exclude=i) if jt == it else _centroid(list(v)))
+                     for jt, v in emb.items()}
+            scores = {jt: float(np.dot(q, c)) for jt, c in cents.items()}
+            best = max(scores, key=scores.get)
+            records.append((INTENT_EXAMPLES[it][i], it, best, scores[best]))
+    return records
+
+
+def main():
+    print(f"Loading {EMBEDDING_MODEL_ID} …")
+    encoder = SentenceTransformer(EMBEDDING_MODEL_ID, device="cpu")
+    records = _build_records(encoder)
+    n = len(records)
+    mode = "external CSV" if len(sys.argv) > 1 else "leave-one-out"
+    print(f"Evaluating {n} utterances ({mode}).\n")
+
+    print("threshold   accuracy   coverage   (below thresh → predicted 'unknown')")
+    for th in THRESHOLDS:
+        correct = cov = 0
+        for _, gold, pred, conf in records:
+            p = pred if conf >= th else "unknown"
+            if p != "unknown":
+                cov += 1
+            if p == gold:
+                correct += 1
+        marker = "  <- current" if abs(th - CONFIDENCE_THRESHOLD) < 1e-9 else ""
+        print(f"  {th:.2f}       {correct/n:.3f}      {cov/n:.3f}{marker}")
+
+    th = CONFIDENCE_THRESHOLD
+    confusion = defaultdict(lambda: defaultdict(int))
+    for _, gold, pred, conf in records:
+        p = pred if conf >= th else "unknown"
+        confusion[gold][p] += 1
+
+    print(f"\nPer-intent recall @ {th:.2f}:")
+    for gold in sorted(confusion):
+        total = sum(confusion[gold].values())
+        hit = confusion[gold][gold]
+        worst = sorted(((c, p) for p, c in confusion[gold].items() if p != gold), reverse=True)
+        leak = f"  (most confused → {worst[0][1]}×{worst[0][0]})" if worst else ""
+        print(f"  {gold:14s} {hit}/{total}  recall={hit/total:.2f}{leak}")
+
+
+if __name__ == "__main__":
+    main()

logging_util.py

@@ -0,0 +1,71 @@
+"""
+PlotWeaver Voice Agent — turn-level logging
+===========================================
+The Spaces filesystem is ephemeral (wiped on restart / rebuild / sleep), so a
+plain ``open("log.jsonl","a")`` loses everything. This module writes each turn
+to a local JSONL file and, when configured, syncs it to a *private* HF Dataset
+via ``CommitScheduler`` — giving both durable logs and a growing, weakly-labeled
+Hausa corpus (utterance + ASR text + chosen intent + source) for later threshold
+tuning and INTENT_EXAMPLES expansion.
+
+Configuration (Space → Settings → Variables and secrets):
+    HF_TOKEN          secret, write-scoped token
+    PW_LOG_DATASET    e.g. "plotweaver/voice-agent-logs"  (enables sync)
+    PW_LOG_DIR        optional; defaults to /data if persistent storage is
+                      attached, else ./logs
+
+If PW_LOG_DATASET / HF_TOKEN are absent, logging degrades to local-file-only
+(handy for dev) and never raises into the request path.
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+_HF_TOKEN = os.environ.get("HF_TOKEN")
+_LOG_DATASET = os.environ.get("PW_LOG_DATASET")
+_default_dir = "/data/logs" if Path("/data").exists() else "logs"
+_LOG_DIR = Path(os.environ.get("PW_LOG_DIR", _default_dir))
+_LOG_DIR.mkdir(parents=True, exist_ok=True)
+_LOG_FILE = _LOG_DIR / f"turns_{uuid.uuid4().hex[:8]}.jsonl"
+
+_scheduler = None
+_lock = threading.Lock()
+
+if _LOG_DATASET and _HF_TOKEN:
+    try:
+        from huggingface_hub import CommitScheduler
+
+        _scheduler = CommitScheduler(
+            repo_id=_LOG_DATASET,
+            repo_type="dataset",
+            folder_path=_LOG_DIR,
+            path_in_repo="data",
+            every=5,            # minutes between commits
+            token=_HF_TOKEN,
+            private=True,
+            squash_history=True,
+        )
+        print(f"[logging] syncing turns to dataset {_LOG_DATASET}")
+    except Exception as e:  # never block startup over logging
+        print(f"[logging] dataset sync disabled ({e}); local file only")
+else:
+    print(f"[logging] local file only at {_LOG_FILE}")
+
+
+def log_turn(record: dict) -> None:
+    """Append one turn record. Safe to call from concurrent Gradio handlers."""
+    record = {"ts": datetime.now(timezone.utc).isoformat(), **record}
+    line = json.dumps(record, ensure_ascii=False) + "\n"
+    try:
+        # CommitScheduler exposes .lock to avoid committing mid-write
+        guard = _scheduler.lock if _scheduler is not None else _lock
+        with guard:
+            with _LOG_FILE.open("a", encoding="utf-8") as f:
+                f.write(line)
+    except Exception as e:
+        print(f"[logging] write failed: {e}")

requirements.txt

@@ -1,8 +1,10 @@
-transformers==4.48.0
-torch==2.5.1
-accelerate==1.2.1
-numpy==2.1.3
-scipy==1.15.0
-sentencepiece==0.2.0
-audioop-lts==0.2.2
-sentence-transformers==3.3.1
+# PlotWeaver Voice Agent — HF Space (Gradio SDK + ZeroGPU)
+gradio>=6.0,<7.0
+spaces
+torch>=2.2
+transformers>=4.44
+sentence-transformers>=3.0
+huggingface_hub>=0.24
+accelerate
+numpy
+scipy