Ground-zero Stages 1–3: dialect anchors + phrasebook short-circuit + Aya-Expanse

Stage 1 — dialect-pinned LLM client (src/llm/minimal_client.py)
Plain-text replacement for GemmaClient's JSON/teacher flow. System prompt
pins Bambara-Mali and Pular-Fuuta-Jallon explicitly, names forbidden
neighbouring languages (Wolof, Hausa, Pulaar-Senegal, Fulfulde-Nigeria,
Jula-CI), and injects a 30-pair bilingual gold list as few-shot anchoring
from configs/dialect_anchors/{bambara_mali,pular_guinea}.json.

Stage 2 — curated phrasebook short-circuit (src/llm/phrasebook.py)
100 Bambara + 110 Pular English-keyed pairs across greetings, family,
food, farming, health, shopping, travel, clarity, time, parting. Fuzzy
matched (threshold 0.88) before every LLM call; on hit returns the gold
translation directly — zero drift risk, zero latency.

Stage 3 — default LLM swapped to CohereLabs/aya-expanse-32b
23-language multilingual base with stronger West African coverage than
Qwen 2.5-7B. Overridable via LLM_MODEL_ID.

Space wiring
- README frontmatter app_file: app.py → app_minimal.py (Space now serves
the minimal baseline; app.py untouched for the full production stack).
- .env auto-loaded via python-dotenv so HF_TOKEN is picked up on launch.
- README updated: minimal-baseline section, Stack + env-var tables,
Run-locally block.

README.md

@@ -31,7 +31,46 @@ Two intertwined jobs:
 1. **Memory loop** — users *teach* the assistant new words; it persists them to a HuggingFace dataset and uses them as the source of truth in future answers.
 2. **Agricultural IoT voice interface** — Sahelian farmers query soil, weather, irrigation, and pest data in their own language, short answers, ≤ 6 words per sentence for clean TTS.
 
-The core stack is explicitly **100% non-Meta** (Whisper / Qwen / F5-TTS / VITS); MMS-TTS is only used as a baseline fallback.
+The core stack is explicitly **100% non-Meta** (Whisper / Aya-Expanse / F5-TTS / VITS); MMS-TTS is only used as a baseline fallback.
+
+---
+
+## What this Space currently runs — the `ground-zero` minimal baseline
+
+The deployed Space (`app_file: app_minimal.py`) is the **Month 1–3 rebuild**
+baseline — a stripped-down Whisper → LLM → MMS-TTS pipeline used for field
+testing and to build a real-user eval set. No LoRA adapters, no memory loop,
+no speaker ID, no voice cloning, no IoT, no phrase matcher. Everything in
+`app.py` still exists for the full production stack; it is just not what the
+Space serves today.
+
+Three stacked changes land dialect fidelity without any training:
+
+1. **Stage 1 — dialect-pinned system prompt** (`src/llm/minimal_client.py`).
+   Replaces the `GemmaClient` JSON/teacher flow with a plain-text client whose
+   system prompt pins the target dialect explicitly — *Bambara as spoken in
+   Bamako, Mali* and *Pular of Fuuta Jallon, as spoken in Guinea* — names the
+   languages the model must **not** drift into (Wolof, Hausa, Pulaar of
+   Senegal, Fulfulde of Nigeria, Jula of Côte d'Ivoire), and injects a 30-pair
+   bilingual gold list as few-shot anchoring
+   (`configs/dialect_anchors/{bambara_mali,pular_guinea}.json`).
+
+2. **Stage 2 — curated phrasebook short-circuit** (`src/llm/phrasebook.py`).
+   Before calling the LLM, the user's input is normalised and fuzzy-matched
+   (threshold 0.88) against a curated English-keyed phrasebook
+   (`configs/dialect_anchors/{bambara,pular}_phrasebook.json` — 100 Bambara /
+   110 Pular entries across greetings, family, food, farming, health,
+   shopping, travel, clarity, time, parting). A hit returns the gold
+   translation directly — zero LLM risk, zero latency.
+
+3. **Stage 3 — better multilingual base LLM.**
+   Default `LLM_MODEL_ID` is now **`CohereLabs/aya-expanse-32b`**, a 23-language
+   multilingual model with much stronger West African coverage than Qwen
+   2.5-7B. Can be overridden via the `LLM_MODEL_ID` env var (e.g. to
+   `Qwen/Qwen2.5-72B-Instruct`) if Cohere's inference provider is not
+   available on your HF account.
+
+See `docs/baseline_rebuild.md` for the broader minimal-track plan.
 
 ---
 
@@ -54,7 +93,9 @@ See `docs/roadmap_2026-04.md` for the full plan and `docs/baseline_rebuild.md` f
 | Layer | Tool |
 |-------|------|
 | STT | `openai/whisper-large-v3-turbo` + PEFT LoRA hot-swap (~50 MB adapter per language, ~50 ms switch) |
-| LLM | `Qwen/Qwen2.5-7B-Instruct` (prod default) via HF Serverless InferenceClient — overridable to `Qwen2.5-72B-Instruct`, Mistral, Zephyr |
+| LLM | `CohereLabs/aya-expanse-32b` (minimal-baseline default, strong African-language coverage) via HF Serverless InferenceClient — overridable to `Qwen/Qwen2.5-72B-Instruct`, `Qwen2.5-7B-Instruct`, Mistral, Zephyr |
+| Dialect anchoring (minimal) | `src/llm/minimal_client.py` — pinned Bambara-Mali / Pular-Guinea system prompt with 30-pair bilingual few-shot + forbidden-drift guardrails |
+| Phrasebook short-circuit (minimal) | `src/llm/phrasebook.py` — 100 Bambara + 110 Pular curated gold pairs, fuzzy-matched (0.88 threshold) before any LLM call |
 | TTS (baseline) | `facebook/mms-tts-bam`, `facebook/mms-tts-ful` |
 | TTS (Bambara) | `ynnov/ekodi-bambara-tts-female` (Waxal VITS) |
 | TTS (Fula) | placeholder → `ous-sow/fula-tts` when published |
@@ -70,7 +111,8 @@ See `docs/roadmap_2026-04.md` for the full plan and `docs/baseline_rebuild.md` f
 
 | File | Purpose | Lifecycle |
 |------|---------|-----------|
-| `app.py` | **Production Gradio UI** on HF Spaces. Single-file (~99 KB) by design. Tabs: Conversation / Teaching / Knowledge Base / Self-Teaching. | `python app.py` |
+| `app_minimal.py` | **Minimal baseline Gradio UI** — what the HF Space currently serves. Whisper → LLM → MMS-TTS with dialect-pinned prompts + curated phrasebook short-circuit. Tabs: Voice / Text. | `python app_minimal.py` |
+| `app.py` | **Full production Gradio UI** (not currently served on the Space). Single-file (~99 KB) by design. Tabs: Conversation / Teaching / Knowledge Base / Self-Teaching. | `python app.py` |
 | `app_lab.py` | **Experimental Gradio UI** for prototyping (e.g. `CuriosityEngine`) before folding into `app.py`. | `python app_lab.py` |
 | `src/api/app.py` | **FastAPI service** — loads Whisper once, registers `bam`/`ful` adapters via `AdapterManager`, preloads `bam`, attaches `Transcriber` + `SensorBridge` to `app.state`. | `python scripts/run_server.py` |
 
@@ -163,7 +205,7 @@ All variables have sensible defaults, so you can boot the Space without any of t
 | `FEEDBACK_REPO_ID` | `ous-sow/sahel-agri-feedback` | Memory-loop target dataset. |
 | `ADAPTER_REPO_ID` | `ous-sow/sahel-agri-adapters` | Published LoRA adapters. |
 | `WHISPER_MODEL_ID` | `openai/whisper-large-v3-turbo` | STT base model. |
-| `LLM_MODEL_ID` | `Qwen/Qwen2.5-7B-Instruct` | LLM via HF Serverless. |
+| `LLM_MODEL_ID` | `CohereLabs/aya-expanse-32b` | LLM via HF Serverless. Override to any HF Serverless-supported model. |
 | `LOG_LEVEL` | `INFO` | Standard Python logging level. |
 | `DEVICE` | `cuda` (FastAPI) | Torch device for inference. |
 
@@ -193,8 +235,11 @@ All variables have sensible defaults, so you can boot the Space without any of t
 ## Run locally
 
 ```bash
-# Gradio production UI
+# Minimal baseline (what the Space runs)
 pip install -r requirements.txt
+python app_minimal.py
+
+# Full production UI (not currently on the Space)
 python app.py
 
 # FastAPI service
@@ -253,7 +298,7 @@ At minimum:
 |-----|-------|
 | `HF_TOKEN` | write-scope token |
 | `FEEDBACK_REPO_ID` | `ous-sow/sahel-agri-feedback` |
-| `LLM_MODEL_ID` | `Qwen/Qwen2.5-7B-Instruct` (or any HF Serverless-supported model) |
+| `LLM_MODEL_ID` | `CohereLabs/aya-expanse-32b` (or any HF Serverless-supported model) |
 
 ---
 

app_minimal.py

@@ -12,7 +12,8 @@ Run locally:
 Environment variables (all optional except HF_TOKEN, which is needed for the
 Qwen HF Serverless call):
     HF_TOKEN       — HuggingFace token with read access
-    LLM_MODEL_ID   — default "Qwen/Qwen2.5-7B-Instruct"
+    LLM_MODEL_ID   — default "CohereLabs/aya-expanse-32b"
+                     (23-language multilingual, strong African-language coverage)
     DEVICE         — "cuda" or "cpu" (auto if unset)
     LOG_LEVEL      — default "INFO"
 """
@@ -24,11 +25,20 @@ from typing import Optional, Tuple
 
 import numpy as np
 
+# Load .env (HF_TOKEN etc.) before reading os.environ below. Silent no-op if
+# python-dotenv is not installed or no .env is present.
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
 # Local imports — the four modules the baseline-rebuild plan authorizes.
 # Everything else in src/ is intentionally unused here.
 from src.data.bam_normalize import normalize as bam_normalize
 from src.engine.whisper_base import WhisperBackbone
-from src.llm.gemma_client import GemmaClient
+from src.llm.minimal_client import MinimalClient
+from src.llm.phrasebook import lookup as phrasebook_lookup
 from src.tts.mms_tts import MMSTTSEngine
 
 logging.basicConfig(
@@ -40,7 +50,7 @@ logger = logging.getLogger(__name__)
 
 # ── Environment ──────────────────────────────────────────────────────────────
 HF_TOKEN     = os.environ.get("HF_TOKEN")
-LLM_MODEL_ID = os.environ.get("LLM_MODEL_ID", "Qwen/Qwen2.5-7B-Instruct")
+LLM_MODEL_ID = os.environ.get("LLM_MODEL_ID", "CohereLabs/aya-expanse-32b")
 _REQUESTED_DEVICE = os.environ.get("DEVICE")  # optional override
 
 LANG_CHOICES = [("Bambara", "bam"), ("Fula", "ful"), ("French", "fr"), ("English", "en")]
@@ -56,20 +66,13 @@ LANG_TO_WHISPER_HINT = {
 }
 
 
-def _with_reply_language_directive(user_text: str, output_lang: str) -> str:
-    """Append an explicit reply-language directive to the user message.
-
-    The LLM's system prompt (in GemmaClient) does not know which language we
-    want the reply in — it picks based on vibes, which can drift (e.g. to
-    Wolof). We keep GemmaClient untouched and steer from the user turn.
-    """
-    name = LANG_NAMES.get(output_lang, "English")
-    return f"{user_text}\n\n(Please reply in {name} only.)"
+# Reply-language steering is handled inside MinimalClient via a dialect-anchored
+# system prompt (see src/llm/minimal_client.py). No per-turn directive needed.
 
 
 # ── Service singletons (lazy-loaded) ────────────────────────────────────────
 _backbone: Optional[WhisperBackbone] = None
-_llm:      Optional[GemmaClient]     = None
+_llm:      Optional[MinimalClient]   = None
 _tts:      Optional[MMSTTSEngine]    = None
 
 
@@ -92,11 +95,11 @@ def get_backbone() -> WhisperBackbone:
     return _backbone
 
 
-def get_llm() -> GemmaClient:
+def get_llm() -> MinimalClient:
     global _llm
     if _llm is None:
-        _llm = GemmaClient(model_id=LLM_MODEL_ID, hf_token=HF_TOKEN)
-        logger.info("LLM client configured: %s", LLM_MODEL_ID)
+        _llm = MinimalClient(model_id=LLM_MODEL_ID, hf_token=HF_TOKEN)
+        logger.info("Minimal LLM client configured: %s", LLM_MODEL_ID)
     return _llm
 
 
@@ -193,17 +196,25 @@ def run_pipeline(
     if not transcript:
         return "", "(no speech detected)", None
 
-    try:
-        # No memory loop in minimal — always pass empty vocabulary context.
-        reply = get_llm().chat(
-            _with_reply_language_directive(transcript, output_lang),
-            vocabulary_context="",
+    # ── Phrasebook short-circuit ──────────────────────────────────────────
+    # Canonical greetings/courtesies hit the curated gold phrasebook directly,
+    # skipping the LLM entirely. Only fires for bam/ful targets.
+    hit = phrasebook_lookup(transcript, output_lang)
+    if hit:
+        logger.info(
+            "Phrasebook hit (%s, score=%.2f): %r → %r [cat=%s]",
+            hit["match"], hit["score"], transcript, hit["target"], hit["category"],
         )
-    except Exception as exc:  # pragma: no cover
-        logger.exception("LLM call failed")
-        return transcript, f"(LLM error: {exc})", None
+        reply_text = hit["target"]
+    else:
+        try:
+            # Dialect-anchored plain-string reply (see MinimalClient).
+            reply_text = get_llm().chat(transcript, target_lang=output_lang)
+        except Exception as exc:  # pragma: no cover
+            logger.exception("LLM call failed")
+            return transcript, f"(LLM error: {exc})", None
 
-    reply_text: str = reply.get("response", "") or "(empty reply)"
+    reply_text = reply_text or "(empty reply)"
 
     try:
         wav, sr = get_tts().synthesize(
@@ -234,16 +245,22 @@ def run_text_pipeline(
     if not text:
         return "(no text entered)", None
 
-    try:
-        reply = get_llm().chat(
-            _with_reply_language_directive(text, output_lang),
-            vocabulary_context="",
+    # ── Phrasebook short-circuit (see voice path above) ──────────────────
+    hit = phrasebook_lookup(text, output_lang)
+    if hit:
+        logger.info(
+            "Phrasebook hit (%s, score=%.2f): %r → %r [cat=%s]",
+            hit["match"], hit["score"], text, hit["target"], hit["category"],
         )
-    except Exception as exc:  # pragma: no cover
-        logger.exception("LLM call failed")
-        return f"(LLM error: {exc})", None
+        reply_text = hit["target"]
+    else:
+        try:
+            reply_text = get_llm().chat(text, target_lang=output_lang)
+        except Exception as exc:  # pragma: no cover
+            logger.exception("LLM call failed")
+            return f"(LLM error: {exc})", None
 
-    reply_text: str = reply.get("response", "") or "(empty reply)"
+    reply_text = reply_text or "(empty reply)"
 
     try:
         wav, sr = get_tts().synthesize(
@@ -264,8 +281,10 @@ def build_ui():
     with gr.Blocks(title="Sahel-Voice — Minimal Baseline") as demo:
         gr.Markdown(
             "# 🌾 Sahel-Voice — Minimal Baseline\n"
-            "Zero-shot Whisper → Qwen → MMS-TTS. No adapters, no memory, no polish. "
-            "This is the field-test baseline — see `docs/baseline_rebuild.md`."
+            f"Zero-shot Whisper → {LLM_MODEL_ID} → MMS-TTS, with a curated "
+            "Bambara/Pular phrasebook short-circuit in front of the LLM. "
+            "No adapters, no memory, no polish. This is the field-test "
+            "baseline — see `docs/baseline_rebuild.md`."
         )
 
         # Shared across tabs. Split into two so input and output language

configs/dialect_anchors/bambara_mali.json

@@ -0,0 +1,37 @@
+{
+  "dialect": "Bambara as spoken in Bamako, Mali",
+  "iso": "bam",
+  "notes": "Curated 30-phrase gold list. Orthography uses ɛ, ɔ, ɲ. Elisions (t', b', k') are preserved as in standard written Mali Bambara. Do NOT substitute with Jula/Dyula (Côte d'Ivoire) forms.",
+  "pairs": [
+    {"source": "Good morning / Bonjour", "target": "I ni sɔgɔma"},
+    {"source": "Good afternoon / Bon après-midi", "target": "I ni tile"},
+    {"source": "Good evening / Bonsoir", "target": "I ni wula"},
+    {"source": "Hello (general) / Salut", "target": "I ni ce"},
+    {"source": "Thank you / Merci", "target": "I ni ce"},
+    {"source": "How are you? / Comment vas-tu ?", "target": "I ka kɛnɛ wa?"},
+    {"source": "I am fine. / Je vais bien.", "target": "Kɛnɛ, tɔɔrɔ tɛ."},
+    {"source": "How is the family? / Comment va la famille ?", "target": "Sɔmɔgɔw bɛ di?"},
+    {"source": "They are fine. / Ils vont bien.", "target": "Tɔɔrɔ t'u la."},
+    {"source": "What is your name? / Comment t'appelles-tu ?", "target": "I tɔgɔ bi di?"},
+    {"source": "My name is... / Je m'appelle...", "target": "Ne tɔgɔ ye..."},
+    {"source": "Where are you going? / Où vas-tu ?", "target": "I bɛ taa min?"},
+    {"source": "I am going to the market. / Je vais au marché.", "target": "N bɛ taa sugu la."},
+    {"source": "How much is this? / C'est combien ?", "target": "Nin ye joli ye?"},
+    {"source": "It is too expensive. / C'est trop cher.", "target": "A da ka gɛlɛn."},
+    {"source": "Please / S'il vous plaît", "target": "Hakɛ to"},
+    {"source": "I am sorry / Je suis désolé", "target": "Yafa n ma"},
+    {"source": "I don't understand / Je ne comprends pas", "target": "N m'a faamu"},
+    {"source": "Speak slowly / Parle doucement", "target": "Kuma dɔɔni dɔɔni"},
+    {"source": "I am hungry / J'ai faim", "target": "Kɔngɔ bɛ n na"},
+    {"source": "I want to eat / Je veux manger", "target": "N b'a fɛ ka dumu"},
+    {"source": "Give me water / Donne-moi de l'eau", "target": "Ji di n ma"},
+    {"source": "How is the work/field? / Comment va le travail/champ ?", "target": "Baara bɛ di? / Sɛnɛ bɛ di?"},
+    {"source": "The work is good. / Le travail va bien.", "target": "Baara bɛ kɛnɛ."},
+    {"source": "Where is the doctor? / Où est le docteur ?", "target": "Dɔkɔtɔrɔ bɛ min?"},
+    {"source": "I am tired / Je suis fatigué", "target": "N sɛgɛnna"},
+    {"source": "See you tomorrow / À demain", "target": "K'an bɛn sini"},
+    {"source": "Goodbye / Au revoir", "target": "K'an bɛn"},
+    {"source": "God bless you / Que Dieu te bénisse", "target": "Ala ka duga i ye"},
+    {"source": "Peace only / La paix seulement", "target": "Hɛɛrɛ dɔrɔn"}
+  ]
+}

configs/dialect_anchors/bambara_phrasebook.json

@@ -0,0 +1,107 @@
+{
+  "dialect": "Bambara as spoken in Bamako, Mali",
+  "iso": "bam",
+  "notes": "Curated 100-phrase field phrasebook, organized by conversational category. Used by the phrasebook short-circuit in src/llm/phrasebook.py — English-keyed, fuzzy-matched. Do NOT substitute with Jula/Dyula (Côte d'Ivoire) forms.",
+  "pairs": [
+    {"category": "Greetings", "source": "Hello / Thank you", "target": "I ni ce"},
+    {"category": "Greetings", "source": "Good morning", "target": "I ni sɔgɔma"},
+    {"category": "Greetings", "source": "Good afternoon", "target": "I ni tile"},
+    {"category": "Greetings", "source": "Good evening", "target": "I ni wula"},
+    {"category": "Greetings", "source": "Welcome", "target": "I ni dɔn"},
+    {"category": "Greetings", "source": "How are you?", "target": "I ka kɛnɛ wa?"},
+    {"category": "Greetings", "source": "Fine, no trouble", "target": "Kɛnɛ, tɔɔrɔ tɛ"},
+    {"category": "Greetings", "source": "How was the night?", "target": "Sini kɛnɛ?"},
+    {"category": "Greetings", "source": "How was the work?", "target": "Baara ni ce"},
+    {"category": "Greetings", "source": "Well done", "target": "I ni baara"},
+    {"category": "Identity", "source": "What is your name?", "target": "I tɔgɔ bi di?"},
+    {"category": "Identity", "source": "My name is...", "target": "Ne tɔgɔ ye..."},
+    {"category": "Identity", "source": "Where are you from?", "target": "I bɔra min?"},
+    {"category": "Identity", "source": "I am from...", "target": "N bɔra..."},
+    {"category": "Identity", "source": "What is your work?", "target": "I bɛ mun baara kɛ?"},
+    {"category": "Family", "source": "How is the family?", "target": "Sɔmɔgɔw bɛ di?"},
+    {"category": "Family", "source": "How is your wife?", "target": "I muso bɛ di?"},
+    {"category": "Family", "source": "How is your husband?", "target": "I tigi bɛ di?"},
+    {"category": "Family", "source": "How are the children?", "target": "Denmisɛnw bɛ di?"},
+    {"category": "Family", "source": "How is the baby?", "target": "Denu bɛ di?"},
+    {"category": "Family", "source": "They are fine", "target": "Tɔɔrɔ t'u la"},
+    {"category": "Family", "source": "My father is well", "target": "N fa bɛ kɛnɛ"},
+    {"category": "Family", "source": "My mother is well", "target": "N ba bɛ kɛnɛ"},
+    {"category": "Family", "source": "Are you married?", "target": "I furula wa?"},
+    {"category": "Food/Water", "source": "I am hungry", "target": "Kɔngɔ bɛ n na"},
+    {"category": "Food/Water", "source": "I am thirsty", "target": "Min nɔgɔ bɛ n na"},
+    {"category": "Food/Water", "source": "I want to eat", "target": "N b'a fɛ ka dumu"},
+    {"category": "Food/Water", "source": "Give me water", "target": "Ji di n ma"},
+    {"category": "Food/Water", "source": "The food is sweet", "target": "Dumuni ka di"},
+    {"category": "Food/Water", "source": "I am full", "target": "N fara"},
+    {"category": "Food/Water", "source": "Bread", "target": "Buruburu"},
+    {"category": "Food/Water", "source": "Rice", "target": "Malo"},
+    {"category": "Food/Water", "source": "Meat", "target": "Sogo"},
+    {"category": "Food/Water", "source": "Tea", "target": "Te"},
+    {"category": "Food/Water", "source": "Sugar", "target": "Sukaro"},
+    {"category": "Farming", "source": "How is the farming?", "target": "Sɛnɛ bɛ di?"},
+    {"category": "Farming", "source": "It rained today", "target": "Sanji nna bi"},
+    {"category": "Farming", "source": "The field", "target": "Sɛnɛfɛla"},
+    {"category": "Farming", "source": "Maize / Corn", "target": "Kaba"},
+    {"category": "Farming", "source": "Cow", "target": "Misi"},
+    {"category": "Farming", "source": "Sheep", "target": "Saga"},
+    {"category": "Farming", "source": "Goat", "target": "Ba"},
+    {"category": "Farming", "source": "Chicken", "target": "Shɛ"},
+    {"category": "Farming", "source": "Where is the hoe?", "target": "Daba bɛ min?"},
+    {"category": "Farming", "source": "We are working", "target": "An bɛ baara kɛ"},
+    {"category": "Health", "source": "I am sick", "target": "N bana"},
+    {"category": "Health", "source": "My head hurts", "target": "N kungolo bɛ n dimi"},
+    {"category": "Health", "source": "My stomach hurts", "target": "N kɔnɔ bɛ n dimi"},
+    {"category": "Health", "source": "I have fever", "target": "Sumaya bɛ n na"},
+    {"category": "Health", "source": "Where is the hospital?", "target": "Ɲɛnajɛso bɛ min?"},
+    {"category": "Health", "source": "Where is the doctor?", "target": "Dɔkɔtɔrɔ bɛ min?"},
+    {"category": "Health", "source": "Take the medicine", "target": "Fura min"},
+    {"category": "Health", "source": "Drink this", "target": "Nin min"},
+    {"category": "Health", "source": "Lie down", "target": "I la"},
+    {"category": "Health", "source": "Do you feel better?", "target": "A ka fisa wa?"},
+    {"category": "Shopping", "source": "How much?", "target": "Joli ye?"},
+    {"category": "Shopping", "source": "It is too much", "target": "A ka ca"},
+    {"category": "Shopping", "source": "Reduce it", "target": "Dɔɔni dɔɔni bɔ a la"},
+    {"category": "Shopping", "source": "I have no money", "target": "Wari tɛ n fɛ"},
+    {"category": "Shopping", "source": "Here is the money", "target": "Wari filɛ"},
+    {"category": "Shopping", "source": "Market", "target": "Sugu"},
+    {"category": "Shopping", "source": "Shop", "target": "Butiki"},
+    {"category": "Shopping", "source": "Soap", "target": "Safinɛ"},
+    {"category": "Shopping", "source": "Oil", "target": "Tulu"},
+    {"category": "Shopping", "source": "Salt", "target": "Kɔgɔ"},
+    {"category": "Travel", "source": "Where is the road?", "target": "Sira bɛ min?"},
+    {"category": "Travel", "source": "Is it far?", "target": "A ka jan wa?"},
+    {"category": "Travel", "source": "It is close", "target": "A surunya"},
+    {"category": "Travel", "source": "Turn right", "target": "Kini bolo fɛ"},
+    {"category": "Travel", "source": "Turn left", "target": "Numa bolo fɛ"},
+    {"category": "Travel", "source": "Stop here", "target": "I jɔ yan"},
+    {"category": "Travel", "source": "Let's go", "target": "An ka taa"},
+    {"category": "Travel", "source": "Car", "target": "Mobili"},
+    {"category": "Travel", "source": "Bus", "target": "Sɔta"},
+    {"category": "Travel", "source": "Motorbike", "target": "Nɛgɛso"},
+    {"category": "Clarity", "source": "I understand", "target": "N n'a faamu"},
+    {"category": "Clarity", "source": "I don't understand", "target": "N m'a faamu"},
+    {"category": "Clarity", "source": "Repeat it", "target": "Segi a kan"},
+    {"category": "Clarity", "source": "Speak slowly", "target": "Kuma dɔɔni dɔɔni"},
+    {"category": "Clarity", "source": "Do you speak Bambara?", "target": "I bɛ Bamanankan mɛn wa?"},
+    {"category": "Clarity", "source": "A little", "target": "Dɔɔni dɔɔni"},
+    {"category": "Clarity", "source": "I don't know", "target": "N m'a lɔn"},
+    {"category": "Clarity", "source": "Yes", "target": "Awɔ"},
+    {"category": "Clarity", "source": "No", "target": "Ayi"},
+    {"category": "Clarity", "source": "Wait", "target": "Kɔnɔ"},
+    {"category": "Time", "source": "Today", "target": "Bi"},
+    {"category": "Time", "source": "Tomorrow", "target": "Sini"},
+    {"category": "Time", "source": "Yesterday", "target": "Kunu"},
+    {"category": "Time", "source": "Now", "target": "Sisan"},
+    {"category": "Time", "source": "Later", "target": "Kɔfɛ"},
+    {"category": "Parting", "source": "Goodbye", "target": "K'an bɛn"},
+    {"category": "Parting", "source": "Until later", "target": "K'an bɛn kɔfɛ"},
+    {"category": "Parting", "source": "Until tomorrow", "target": "K'an bɛn sini"},
+    {"category": "Parting", "source": "Have a good day", "target": "Tile hɛɛrɛ"},
+    {"category": "Parting", "source": "Have a good night", "target": "Su hɛɛrɛ"},
+    {"category": "Parting", "source": "Go in peace", "target": "Taa hɛɛrɛ la"},
+    {"category": "Parting", "source": "God bless you", "target": "Ala ka duga i ye"},
+    {"category": "Parting", "source": "God willing", "target": "Ala sɔnna"},
+    {"category": "Parting", "source": "Thank God", "target": "Ala tando"},
+    {"category": "Parting", "source": "Peace only", "target": "Hɛɛrɛ dɔrɔn"}
+  ]
+}

configs/dialect_anchors/pular_guinea.json

@@ -0,0 +1,37 @@
+{
+  "dialect": "Pular of Fuuta Jallon, as spoken in Guinea",
+  "iso": "ful",
+  "notes": "Curated 30-phrase gold list, cross-checked against the Peace Corps Guinea 2015 Pular manual. Orthography uses ɓ, ɗ, ñ, ŋ. Signature Fuuta Jallon markers: 'Miɗo yaha' (1sg progressive), 'No ... wa'i' (how is), 'Jam tun' (peace only response), 'A jaraama' (thank you / hello). Do NOT substitute with Pulaar (Senegal) or Fulfulde (Nigeria, Cameroon) forms.",
+  "pairs": [
+    {"source": "Hello / Thank you (General)", "target": "A jaraama"},
+    {"source": "Good morning (Did you sleep in peace?)", "target": "On walli e jam?"},
+    {"source": "Good afternoon (Have you spent the day in peace?)", "target": "On ñalli e jam?"},
+    {"source": "Good evening (Have you spent the evening in peace?)", "target": "On hiiri e jam?"},
+    {"source": "Peace only (Standard response)", "target": "Jam tun"},
+    {"source": "How are you? / How is it?", "target": "No wa'i?"},
+    {"source": "Is there any trouble? / Is it okay?", "target": "Tana alaa?"},
+    {"source": "No trouble / Fine", "target": "Tana alaa"},
+    {"source": "Thank you (Respectful/Plural)", "target": "On jaraama"},
+    {"source": "How is the family?", "target": "No ɓeyngure nden wa'i?"},
+    {"source": "How are the children?", "target": "No fayɓe ɓen wa'i?"},
+    {"source": "What is your name?", "target": "Innde maa ko woni?"},
+    {"source": "My name is...", "target": "Innde am ko..."},
+    {"source": "Where are you going?", "target": "Hoto yahataa?"},
+    {"source": "I am going to the market", "target": "Miɗo yaha ka sugu"},
+    {"source": "Please (I ask you)", "target": "Mi yidiima"},
+    {"source": "Excuse me / Sorry", "target": "Accu hakke"},
+    {"source": "I understand", "target": "Mi faamii"},
+    {"source": "I don't understand", "target": "Mi faamaali"},
+    {"source": "Do you speak Pular?", "target": "Aɗa waawi Pular?"},
+    {"source": "Just a little bit", "target": "Seeɗa tun"},
+    {"source": "I want water", "target": "Miɗo yiɗi ndiyam"},
+    {"source": "Give me...", "target": "Okku am..."},
+    {"source": "How much is it?", "target": "Ko jelu?"},
+    {"source": "It is expensive", "target": "No tiiɗi"},
+    {"source": "God bless you", "target": "Alla duga maa"},
+    {"source": "If God wills (God willing)", "target": "Si Alla jaɓii"},
+    {"source": "Goodbye (Formal)", "target": "Oo-o"},
+    {"source": "Until tomorrow (See you tomorrow)", "target": "En jango"},
+    {"source": "Go in peace", "target": "Yahu e jam"}
+  ]
+}

configs/dialect_anchors/pular_phrasebook.json

@@ -0,0 +1,117 @@
+{
+  "dialect": "Pular of Fuuta Jallon, as spoken in Guinea",
+  "iso": "ful",
+  "notes": "Curated 110-phrase field phrasebook, organized by conversational category. Used by the phrasebook short-circuit in src/llm/phrasebook.py — English-keyed, fuzzy-matched. Cross-checked against Peace Corps Guinea 2015 Pular manual. Do NOT substitute with Pulaar (Senegal) or Fulfulde (Nigeria/Cameroon) forms.",
+  "pairs": [
+    {"category": "Greetings", "source": "Hello / Thank you", "target": "A jaraama"},
+    {"category": "Greetings", "source": "Good morning", "target": "On walli e jam?"},
+    {"category": "Greetings", "source": "Good afternoon", "target": "On ñalli e jam?"},
+    {"category": "Greetings", "source": "Good evening", "target": "On hiiri e jam?"},
+    {"category": "Greetings", "source": "Peace only (Response)", "target": "Jam tun"},
+    {"category": "Greetings", "source": "How are you?", "target": "No wa'i?"},
+    {"category": "Greetings", "source": "Is there any trouble?", "target": "Tana alaa?"},
+    {"category": "Greetings", "source": "No trouble", "target": "Tana alaa"},
+    {"category": "Greetings", "source": "How is the heat/weather?", "target": "Ho no yasi ken waye?"},
+    {"category": "Greetings", "source": "Welcome", "target": "Tana alaa"},
+    {"category": "Identity", "source": "What is your name?", "target": "Ko ho no inne te dah?"},
+    {"category": "Identity", "source": "My name is...", "target": "Innde am ko..."},
+    {"category": "Identity", "source": "Where are you coming from?", "target": "Hoto iwruɗaa?"},
+    {"category": "Identity", "source": "Where are you from?", "target": "Eewdi maadiin koh hontoh?"},
+    {"category": "Identity", "source": "I am coming from...", "target": "Mi iwri ko..."},
+    {"category": "Identity", "source": "I am from", "target": "Eewdi an diin koh"},
+    {"category": "Identity", "source": "I am a farmer", "target": "Koh mee rehmohwoh"},
+    {"category": "Family", "source": "How is the family?", "target": "No ɓeyngure nden wa'i?"},
+    {"category": "Family", "source": "How is the woman?", "target": "No debbo on wa'i?"},
+    {"category": "Family", "source": "How is your wife?", "target": "No mbehgu ma wa'i?"},
+    {"category": "Family", "source": "How is your husband?", "target": "No mohdi ma wa'i?"},
+    {"category": "Family", "source": "How is the man?", "target": "No gorko on wa'i?"},
+    {"category": "Family", "source": "How are the children?", "target": "No fayɓe ɓen wa'i?"},
+    {"category": "Family", "source": "How is the baby?", "target": "No boobo on wa'i?"},
+    {"category": "Family", "source": "Everyone is fine", "target": "Hiɓe e jam"},
+    {"category": "Family", "source": "My father is well", "target": "Baba am no e jam"},
+    {"category": "Family", "source": "My mother is well", "target": "Neene am no e jam"},
+    {"category": "Family", "source": "How many children?", "target": "Fayɓe ben ko jelu?"},
+    {"category": "Food/Water", "source": "I am hungry", "target": "Mi weelaa maa"},
+    {"category": "Food/Water", "source": "I am thirsty", "target": "Miɗo ɗonɗa"},
+    {"category": "Food/Water", "source": "I want to eat", "target": "Miɗo faalaa ñaamude"},
+    {"category": "Food/Water", "source": "Give me water", "target": "Okku am ndiyam"},
+    {"category": "Food/Water", "source": "The food is good", "target": "Ñaameteeɗon no weli"},
+    {"category": "Food/Water", "source": "I am full", "target": "Mi haraama"},
+    {"category": "Food/Water", "source": "Bread", "target": "Biirehdi"},
+    {"category": "Food/Water", "source": "Rice", "target": "Maaro"},
+    {"category": "Food/Water", "source": "Milk", "target": "Mɓeerah"},
+    {"category": "Food/Water", "source": "Sour Cream", "target": "Kosam"},
+    {"category": "Food/Water", "source": "Hot water", "target": "Ndiyam wuuldham"},
+    {"category": "Food/Water", "source": "Cold water", "target": "Ndiyam ɓuuɓudham"},
+    {"category": "Food/Water", "source": "Coffee", "target": "Kafe"},
+    {"category": "Food/Water", "source": "Sugar", "target": "Sukkar"},
+    {"category": "Farming", "source": "How is the farming?", "target": "No ngsa kan wa'i?"},
+    {"category": "Farming", "source": "The rain is good", "target": "Ndiyam ndan no moƴƴi"},
+    {"category": "Farming", "source": "The field", "target": "Ngesa"},
+    {"category": "Farming", "source": "Garden", "target": "Suntuure"},
+    {"category": "Farming", "source": "Cattle / Cows", "target": "Nai"},
+    {"category": "Farming", "source": "Sheep", "target": "Baali"},
+    {"category": "Farming", "source": "Goat", "target": "Mbeewa"},
+    {"category": "Farming", "source": "Chicken", "target": "Gertogal"},
+    {"category": "Farming", "source": "Where is the thing?", "target": "Hoto huunde nden woni?"},
+    {"category": "Farming", "source": "To cultivate or to farm", "target": "Remugol"},
+    {"category": "Farming", "source": "To sow or plant seeds", "target": "Aawugol"},
+    {"category": "Farming", "source": "To harvest", "target": "Heptugol"},
+    {"category": "Farming", "source": "We are working (speaking to the person I'm working with)", "target": "Hiɗen e golle"},
+    {"category": "Farming", "source": "We are working (speaking to another person not working with us)", "target": "Meein gollu deh"},
+    {"category": "Health", "source": "I am sick", "target": "Miɗo nawni"},
+    {"category": "Health", "source": "My head hurts", "target": "Hoore am den no muusa"},
+    {"category": "Health", "source": "My stomach hurts", "target": "Reedu am doun no muusa"},
+    {"category": "Health", "source": "I have fever", "target": "Miɗo jogi yontere"},
+    {"category": "Health", "source": "Where is the clinic?", "target": "Hoto kilinik on woni?"},
+    {"category": "Health", "source": "Where is the doctor?", "target": "Hoto dɔkɔtɔrɔ on woni?"},
+    {"category": "Health", "source": "Take this medicine", "target": "Jehhtu leki kin"},
+    {"category": "Health", "source": "Drink this", "target": "Yaru ɗun"},
+    {"category": "Health", "source": "Rest now", "target": "Fow'w toh"},
+    {"category": "Health", "source": "Are you better?", "target": "Aɗa selli jooni?"},
+    {"category": "Shopping", "source": "How much is this?", "target": "Dounn ko jelu?"},
+    {"category": "Shopping", "source": "It is too expensive", "target": "No sahtee"},
+    {"category": "Shopping", "source": "Reduce the price", "target": "Dhuitah nam seeɗa"},
+    {"category": "Shopping", "source": "I have no money", "target": "Mi alaa buudi"},
+    {"category": "Shopping", "source": "Here is the money", "target": "Hinoh buudi dinn"},
+    {"category": "Shopping", "source": "Market", "target": "Luhmoh"},
+    {"category": "Shopping", "source": "Shop / Boutique", "target": "Bitiki"},
+    {"category": "Shopping", "source": "Soap", "target": "Sabunnde"},
+    {"category": "Shopping", "source": "Matches", "target": "Almet"},
+    {"category": "Shopping", "source": "Salt", "target": "Landan"},
+    {"category": "Travel", "source": "Where is the road to...?", "target": "Hoto ngol laawol yahata...?"},
+    {"category": "Travel", "source": "Is it far?", "target": "No woɗɗi?"},
+    {"category": "Travel", "source": "It is near", "target": "No ɓadii"},
+    {"category": "Travel", "source": "Turn right", "target": "Ýillu ka ñaamo"},
+    {"category": "Travel", "source": "Turn left", "target": "Ýillu ka nannoh"},
+    {"category": "Travel", "source": "Stop here", "target": "Daroh ɗoo"},
+    {"category": "Travel", "source": "Let's go", "target": "Mah een"},
+    {"category": "Travel", "source": "Car / Taxi", "target": "Oto"},
+    {"category": "Travel", "source": "Bicycle", "target": "Velo"},
+    {"category": "Travel", "source": "Motorcycle", "target": "Moto"},
+    {"category": "Clarity", "source": "I understand", "target": "Mi faamii"},
+    {"category": "Clarity", "source": "I don't understand", "target": "Mi faamaali"},
+    {"category": "Clarity", "source": "Please repeat", "target": "Fultu kadi"},
+    {"category": "Clarity", "source": "Speak slowly", "target": "Halu seeɗa seeɗa"},
+    {"category": "Clarity", "source": "Do you speak French?", "target": "Aɗa waawi Faransi?"},
+    {"category": "Clarity", "source": "I can just a little", "target": "Mi nan waawi seeɗa tun"},
+    {"category": "Clarity", "source": "I don't know", "target": "Mi andaa"},
+    {"category": "Clarity", "source": "Yes", "target": "Eyyo / Hii'hi"},
+    {"category": "Clarity", "source": "No", "target": "O'o"},
+    {"category": "Clarity", "source": "Wait", "target": "Sabboh"},
+    {"category": "Time", "source": "Today", "target": "Hannde"},
+    {"category": "Time", "source": "Tomorrow", "target": "Jango"},
+    {"category": "Time", "source": "Yesterday", "target": "Hanki"},
+    {"category": "Time", "source": "Now", "target": "Joni"},
+    {"category": "Time", "source": "Later", "target": "On tuma"},
+    {"category": "Parting", "source": "Goodbye", "target": "Oo-o"},
+    {"category": "Parting", "source": "See you later", "target": "En on tuma"},
+    {"category": "Parting", "source": "See you tomorrow", "target": "En jango"},
+    {"category": "Parting", "source": "Have a good day", "target": "Ñallu e jam"},
+    {"category": "Parting", "source": "Have a good night", "target": "Waalu e jam"},
+    {"category": "Parting", "source": "Go in peace", "target": "Yahu e jam"},
+    {"category": "Parting", "source": "God willing", "target": "Si Alla jaɓii"},
+    {"category": "Parting", "source": "Thank God", "target": "Ko ýettude Alla"},
+    {"category": "Parting", "source": "Peace only", "target": "Jam tun"}
+  ]
+}

src/llm/minimal_client.py

@@ -0,0 +1,179 @@
+"""MinimalClient — dialect-anchored plain-text LLM client for the Month 1–3 rebuild.
+
+Why this exists (and not GemmaClient):
+  GemmaClient wraps every reply in a JSON object and runs a "teacher / child"
+  intent-classification flow. That's fine for the full app, but for the minimal
+  baseline it (a) spends model capacity on JSON compliance, (b) lets the model
+  drift into neighbouring languages (Wolof, Hausa, Pulaar of Senegal, Fulfulde
+  of Nigeria, Jula of Côte d'Ivoire), and (c) produces text that isn't clean
+  for TTS.
+
+This client instead:
+  - pins the target dialect explicitly (Bambara / Bamako–Mali or Pular / Fuuta
+    Jallon–Guinea),
+  - injects the curated 30-phrase gold list for the target language as
+    few-shot anchoring in the system prompt,
+  - names forbidden neighbouring languages the model must not code-switch to,
+  - returns a plain string, ready for MMS-TTS.
+
+GemmaClient and app.py are intentionally untouched.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# configs/dialect_anchors/*.json lives at <repo>/configs/dialect_anchors
+_ANCHOR_DIR = (
+    Path(__file__).resolve().parent.parent.parent / "configs" / "dialect_anchors"
+)
+
+_ANCHOR_FILE = {
+    "bam": "bambara_mali.json",
+    "ful": "pular_guinea.json",
+}
+
+LANG_FULL_NAME = {
+    "bam": "Bambara as spoken in Bamako, Mali",
+    "ful": "Pular of Fuuta Jallon, as spoken in Guinea",
+    "fr":  "French",
+    "en":  "English",
+}
+
+# Neighbouring languages the model is most likely to drift into. Empty for
+# fr/en — we don't need to fence those.
+FORBIDDEN_DRIFT = {
+    "bam": (
+        "Jula / Dyula of Côte d'Ivoire, Wolof, Hausa, Swahili, Lingala, "
+        "or any other African language"
+    ),
+    "ful": (
+        "Pulaar of Senegal, Fulfulde of Nigeria or Cameroon, Wolof, Hausa, "
+        "Swahili, or any other African language"
+    ),
+    "fr":  "",
+    "en":  "",
+}
+
+
+@lru_cache(maxsize=4)
+def _load_anchors(lang: str) -> list[dict]:
+    """Load the curated gold-phrase list for `lang`. Cached per process."""
+    fname = _ANCHOR_FILE.get(lang)
+    if not fname:
+        return []
+    path = _ANCHOR_DIR / fname
+    if not path.exists():
+        logger.warning("Dialect anchor file missing: %s", path)
+        return []
+    with path.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    return data.get("pairs", [])
+
+
+def _build_system_prompt(target_lang: str) -> str:
+    """Assemble the per-call system prompt for a target output language."""
+    full = LANG_FULL_NAME.get(target_lang, "English")
+    forbidden = FORBIDDEN_DRIFT.get(target_lang, "")
+    anchors = _load_anchors(target_lang)
+
+    lines: list[str] = [
+        f"You are a warm, concise conversational assistant that replies ONLY in {full}.",
+        "",
+        "Output format: plain natural text only. No JSON, no code fences, no "
+        "markdown, no translations, no romanisation, no explanations. Reply in "
+        "1–3 short sentences suitable to be read aloud by a text-to-speech voice.",
+    ]
+
+    if forbidden:
+        lines += [
+            "",
+            (
+                f"CRITICAL — dialect fidelity: do NOT use, mix, or substitute words "
+                f"from {forbidden}. If you are not confident a word belongs to "
+                f"{full}, rephrase using simpler vocabulary you are certain of, or "
+                f"apologise briefly in {full} (for example that you did not "
+                f"understand)."
+            ),
+        ]
+
+    if anchors:
+        lines += [
+            "",
+            f"Reference phrases in {full} — use this exact orthography, spelling, "
+            "and dialectal style as your model for every reply:",
+        ]
+        for item in anchors:
+            src = item.get("source", "").strip()
+            tgt = item.get("target", "").strip()
+            if src and tgt:
+                lines.append(f"- {src}  →  {tgt}")
+
+    lines += [
+        "",
+        f"Always reply in {full}, even if the user writes to you in English, "
+        "French, or another language. Never translate your own reply.",
+    ]
+    return "\n".join(lines)
+
+
+class MinimalClient:
+    """Dialect-anchored plain-text LLM client over HF Serverless Inference.
+
+    Usage:
+        client = MinimalClient(model_id="Qwen/Qwen2.5-7B-Instruct", hf_token=TOK)
+        reply  = client.chat("Good morning", target_lang="bam")
+        # → "I ni sɔgɔma. I ka kɛnɛ wa?"
+    """
+
+    def __init__(
+        self,
+        model_id: str = "CohereLabs/aya-expanse-32b",
+        hf_token: Optional[str] = None,
+    ) -> None:
+        self.model_id = model_id
+        self.hf_token = hf_token
+        self._client = None  # lazy init
+
+    def _get_client(self):
+        if self._client is None:
+            from huggingface_hub import InferenceClient
+            self._client = InferenceClient(token=self.hf_token)
+        return self._client
+
+    def chat(self, user_text: str, target_lang: str = "bam") -> str:
+        """Return a plain-text reply in `target_lang`.
+
+        On any error returns a short parenthetical error string so the caller
+        can still feed something into TTS / display.
+        """
+        system_prompt = _build_system_prompt(target_lang)
+        try:
+            client = self._get_client()
+            completion = client.chat_completion(
+                model=self.model_id,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user",   "content": user_text},
+                ],
+                max_tokens=256,
+                temperature=0.3,
+            )
+            raw = (completion.choices[0].message.content or "").strip()
+            # Defensive: strip any stray code fences the model may emit anyway.
+            if raw.startswith("```"):
+                raw = raw.strip("`").strip()
+                # If a language tag slipped in on the first line, drop it.
+                if "\n" in raw:
+                    first, rest = raw.split("\n", 1)
+                    if len(first) < 20 and " " not in first:
+                        raw = rest.strip()
+            return raw
+        except Exception as exc:  # pragma: no cover — surfaced to UI
+            logger.error("MinimalClient error: %s", exc)
+            return f"(LLM unavailable: {exc})"

src/llm/phrasebook.py

@@ -0,0 +1,123 @@
+"""Phrasebook short-circuit — skip the LLM when the user hits a curated phrase.
+
+Purpose
+    For the 80% of field-demo inputs that are canonical greetings, courtesies,
+    or basic questions, the LLM adds risk (dialect drift, hallucination,
+    latency) without adding value — we already have a gold translation. This
+    module does an English-keyed, fuzzy-normalised match against the curated
+    phrasebooks in configs/dialect_anchors/{bambara,pular}_phrasebook.json and
+    returns the target string directly when the match is strong.
+
+Scope
+    - Only fires when target language is bam or ful. For en/fr output we let
+      the LLM (or a passthrough) handle it — nothing to short-circuit.
+    - Only English source keys (what the curated sheets contain). French or
+      in-language inputs will not match and will fall through to the LLM —
+      that's correct behaviour.
+
+Matching
+    - Exact match on normalised string → score 1.0 ("exact").
+    - Otherwise SequenceMatcher ratio; threshold DEFAULT_THRESHOLD = 0.88.
+    - Normalisation: lowercase, strip punctuation (keeps internal apostrophes),
+      collapse whitespace.
+
+API
+    lookup(user_text, target_lang) -> dict | None
+        dict has keys: source, target, category, score, match
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from difflib import SequenceMatcher
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_PHRASEBOOK_DIR = (
+    Path(__file__).resolve().parent.parent.parent / "configs" / "dialect_anchors"
+)
+
+_PHRASEBOOK_FILE = {
+    "bam": "bambara_phrasebook.json",
+    "ful": "pular_phrasebook.json",
+}
+
+DEFAULT_THRESHOLD = 0.88
+
+
+def _normalize(text: str) -> str:
+    """Lowercase, strip most punctuation, collapse whitespace."""
+    text = (text or "").lower().strip()
+    # Keep internal apostrophes (e.g. "don't", "b'a"), drop other punctuation.
+    text = re.sub(r"[^\w\s']", " ", text, flags=re.UNICODE)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+@lru_cache(maxsize=4)
+def _load_phrasebook(lang: str) -> list[dict]:
+    fname = _PHRASEBOOK_FILE.get(lang)
+    if not fname:
+        return []
+    path = _PHRASEBOOK_DIR / fname
+    if not path.exists():
+        logger.warning("Phrasebook missing: %s", path)
+        return []
+    with path.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    pairs = data.get("pairs", [])
+    # Precompute normalised source for speed.
+    for p in pairs:
+        p["_norm"] = _normalize(p.get("source", ""))
+    return pairs
+
+
+def lookup(
+    user_text: str,
+    target_lang: str,
+    threshold: float = DEFAULT_THRESHOLD,
+) -> Optional[dict]:
+    """Return best curated match for `user_text` in `target_lang`, or None.
+
+    Short-circuits only for curated dialects (bam, ful). For any other target
+    returns None so the caller falls through to the LLM.
+    """
+    pairs = _load_phrasebook(target_lang)
+    if not pairs:
+        return None
+    q = _normalize(user_text)
+    if not q:
+        return None
+
+    best: Optional[dict] = None
+    best_score = 0.0
+    for p in pairs:
+        src = p.get("_norm", "")
+        if not src:
+            continue
+        if src == q:
+            return {
+                "source":   p.get("source"),
+                "target":   p.get("target"),
+                "category": p.get("category"),
+                "score":    1.0,
+                "match":    "exact",
+            }
+        score = SequenceMatcher(None, q, src).ratio()
+        if score > best_score:
+            best_score = score
+            best = p
+
+    if best and best_score >= threshold:
+        return {
+            "source":   best.get("source"),
+            "target":   best.get("target"),
+            "category": best.get("category"),
+            "score":    round(best_score, 3),
+            "match":    "fuzzy",
+        }
+    return None