push docs and script

docs/baseline_rebuild.md

@@ -0,0 +1,166 @@
+# Baseline Rebuild Plan — Recovering Months 1-3 Without Losing Existing Work
+
+*Created: 2026-04-20*
+*Maintainer: Broulaye*
+
+## The framing
+
+You are not restarting. You are **backfilling** the measurement foundation that was skipped the first time through Stages C (ASR + eval), E (memory loop with real users), and G (field test). Every existing file in `src/` stays exactly where it is. The `app.py` Gradio Space on HuggingFace keeps running. Phase 3 voice-to-voice, Waxal VITS, Adlam/Pular, F5-TTS, ONNX exporters, the FastAPI service — all of it stays.
+
+What you add is a **parallel minimal track**: a new, deliberately simple entry point that uses only the smallest slice of the existing codebase, runs a real field test against it, and collects the data that should have been collected in Months 1-3. Once the minimal track has produced field signal, you use that signal to guide which features in the main app are actually earning their keep.
+
+Three principles govern this plan:
+
+1. **Never delete, never rewrite.** If something is wrong in an existing module, fix it in place. The minimal track imports from `src/`; it does not fork it.
+2. **The existing `app.py` keeps shipping.** Do not take down the production Space. The minimal version deploys as a *separate* Space.
+3. **The measurement artifacts (eval set, logs, field-test notes) merge back into main when done.** Code stays isolated on a branch; data and docs come back.
+
+## Step-by-step
+
+### Step 1 — Protect main with a branch and a tag
+
+**Why.** Every experiment has to be safely discardable. Tagging the current commit lets you return to known-good state at any point; branching means nothing the rebuild does can touch the main deploy.
+
+**How.**
+
+```bash
+cd /sessions/practical-intelligent-knuth/mnt/sahel-agri-voice
+git status                                  # confirm clean working tree
+git tag v0.3-pre-rebuild -m "Last state before baseline rebuild"
+git push origin v0.3-pre-rebuild            # if you want the tag on GitHub
+git checkout -b experimental/baseline-rebuild
+```
+
+From this point on, all rebuild work happens on `experimental/baseline-rebuild`. Main is frozen for the duration of the rebuild. Hotfixes to production still go through main as normal.
+
+### Step 2 — Create the minimal entry point
+
+**Why.** You need to run Whisper + LLM + MMS-TTS in the simplest possible wiring, with nothing else in the critical path. This is what users will actually evaluate. Every extra component adds a failure mode you can't isolate. The minimal entry point becomes a joint debugging tool and a field-test artifact.
+
+**How.** Add a new file `app_minimal.py` at the repo root — a third entry point alongside `app.py` (full production) and `app_lab.py` (experimental). It should import only:
+
+- `src.llm.gemma_client` — the Qwen LLM client, unchanged
+- `src.engine.whisper_base` — Whisper backbone, used *zero-shot* (no adapter)
+- `src.tts.mms_tts` — MMS-TTS Bambara fallback
+- `src.data.bam_normalize` — the orthography normalizer
+
+It should **not** touch:
+
+- `src/engine/adapter_manager.py` (skip LoRA entirely — zero-shot only)
+- `src/engine/transcriber.py` (the adapter-aware wrapper — use `whisper_base` directly)
+- `src/memory/` (no memory loop in the minimal version yet)
+- `src/voice/speaker_profiles.py` (no speaker ID)
+- `src/iot/` (no sensors, no intent parsing — LLM handles it all)
+- `src/tts/waxal_tts.py`, `src/tts/f5_tts.py`, `src/tts/voice_cloner.py` (no upgraded TTS)
+- `src/conversation/phrase_matcher.py` (no fast-path shortcuts)
+
+Single Gradio interface, one tab: microphone input, audio output, transcript visible for debugging. Roughly 150-200 lines total. Add a header comment explaining what it is:
+
+```python
+"""Minimal baseline Gradio entry point for the Month 1-3 rebuild.
+
+Wires the simplest possible slice: Whisper (zero-shot) -> Qwen -> MMS-TTS.
+No LoRA adapters, no memory loop, no speaker ID, no voice cloning.
+Used for field testing and building a real-user eval set.
+See docs/baseline_rebuild.md for the plan this fits into.
+"""
+```
+
+### Step 3 — Add the evaluation infrastructure
+
+**Why.** This is the single most load-bearing deliverable of the rebuild. Without a real-user eval set, every subsequent decision is speculation. The eval set is what turns "I think this change helps" into "I measured this change helped." It also makes the LoRA Kaggle training work (Stage C continuation) scientifically valid whenever you get back to it.
+
+**How.** Create the folder structure:
+
+```
+data/eval/
+  bambara_field.jsonl        # the eval manifest — starts empty
+  audio/                     # the actual wav files (gitignore large files; keep manifest in git)
+  README.md                  # recording protocol
+scripts/
+  eval_baseline.py           # runs minimal stack against manifest, emits metrics
+docs/
+  eval_protocol.md           # how to add a new recording, quality criteria
+  metrics.md                 # where baseline numbers are recorded
+```
+
+The JSONL manifest format:
+
+```json
+{"audio_path": "audio/speaker01_001.wav", "transcript": "ji be min?", "speaker_id": "speaker01", "region": "Bamako", "noise": "quiet", "duration_s": 2.3}
+```
+
+`scripts/eval_baseline.py` loads the manifest, runs each audio through Whisper-large-v3-turbo (zero-shot, no adapter), compares to the ground-truth transcript, and prints WER and CER per-speaker and overall. Also prints a few failure cases for inspection. This script becomes your standard measurement harness — every future change gets compared against the same manifest.
+
+### Step 4 — Collect real recordings (the only human-gated step)
+
+**Why.** This is where the rebuild touches reality. Three to five native speakers, using their actual phones, in their actual environments. Fifteen to twenty utterances each covering the agricultural domain you scoped for. The recording conditions have to be real, or the eval set will give you FLEURS-like numbers that lie to you.
+
+**How.** Write a recording script with 50-100 prompts covering:
+
+- Greetings and politeness formulas (baseline — should be easy)
+- Agricultural queries the product actually needs to handle ("how wet is the soil," "when should I water the tomatoes," "is there a pest alert")
+- Vocabulary you know is underrepresented in FLEURS (crop names, tool names, regional agricultural terms)
+- A few natural code-switch utterances (Bambara with French loanwords)
+
+Share the script via WhatsApp voice messages or have them record in a free mobile app that returns wav or m4a. Transcribe by hand (or by LLM with manual correction). Commit the JSONL manifest to the repo; upload the audio to a private HF dataset to avoid bloating git history.
+
+Set a target: at least 50 utterances across at least 3 speakers before running your first baseline eval. More is better, but 50 is the usable floor.
+
+### Step 5 — Deploy the minimal Space
+
+**Why.** A second HF Space running `app_minimal.py` in parallel with the main Space gives testers a stripped-down version to react to. Comparing two Spaces teaches you which features in the main app are actually pulling weight — if minimal gets the same "I'd use this" reaction as the full version, most of the fancy work isn't load-bearing for first-use value (which doesn't mean it's wrong, just that adoption doesn't depend on it).
+
+**How.** Create a new Space, e.g. `ous-sow/sahel-voice-minimal`. Set the Space entry point to `app_minimal.py`. Keep `packages.txt` unchanged (ffmpeg is still needed). In `requirements.txt`, consider a trimmed version that doesn't pull in voice cloning or training-only deps — this is a chance to get the minimal Space to cold-boot faster.
+
+Add basic session logging: every interaction writes a row to a HF dataset `ous-sow/sahel-agri-field-logs` with fields `{timestamp, speaker_opt_in_id, audio_hash, transcript, llm_reply, tts_audio_hash, latency_ms}`. With opt-in consent text in the UI. No PII. This logging is what will feed your future training data and answer "are users actually coming back."
+
+### Step 6 — Run the field test
+
+**Why.** The whole rebuild exists to get this step done. Everything before it is scaffolding; everything after it is informed by what happens in it. The success metric is not WER. It is: **do the testers ask a second question they came up with themselves?** That is the shortest signal that tells you whether this is a product or a demo.
+
+**How.** Five testers, two weeks. WhatsApp intro: here is the link, please try to ask about soil or weather in Bambara, tell me anything weird. No coaching on phrasing. At the end of week 1 and week 2, ask each tester three questions: what worked, what failed, would you come back tomorrow. Record answers. No metrics from this stage go in a spreadsheet; they go in a short note under `docs/field_test_notes_YYYY-MM-DD.md` written in plain language.
+
+In parallel, the session logs from Step 5 accumulate. At the end of two weeks, run a small analysis: median latency, distribution of utterance lengths, most common failure utterances, return rate per tester.
+
+### Step 7 — Selective reintegration
+
+**Why.** Now you have evidence. Some of the Stage H features the main app already has will turn out to be essential — users asked for speaker memory, or they wanted the IoT integration enough to keep trying. Other features will turn out to be polish no tester noticed. The rebuild ends not with a big merge but with a prioritized list: which features go back into the critical path immediately, which wait, which get deprecated.
+
+**How.** Open a small PR from `experimental/baseline-rebuild` back into main that brings in *only the data and documentation*:
+
+- `data/eval/bambara_field.jsonl` and the audio reference
+- `scripts/eval_baseline.py`
+- `docs/eval_protocol.md`
+- `docs/metrics.md` with baseline numbers recorded
+- `docs/field_test_notes_*.md`
+- The session-logging infrastructure (if you want it in the production Space too — usually yes)
+
+Leave `app_minimal.py` on the branch as a long-lived tool — it's now your smoke-test harness. Don't merge it into main unless it's actively useful there.
+
+From the field test notes, write a short follow-up roadmap document (`docs/roadmap_post_field_test.md`) that reorders the Month 7+ work based on what you actually learned. The features the testers needed get priority. The features that weren't missed drop in rank.
+
+## What NOT to touch during the rebuild
+
+- **Production `app.py`** — stays as-is on main. Users continue to see it on the main HF Space.
+- **The HF dataset `ous-sow/sahel-agri-feedback`** — keep accepting writes from the main app; the minimal Space can also write to it or to a separate one, your call.
+- **LoRA training infrastructure** — fixing the Kaggle crash is important Stage C work but it is *not* part of this rebuild. Track it as a separate issue. The rebuild uses Whisper zero-shot deliberately, to decouple field testing from training progress.
+- **All `src/` modules** — use them, import them, fix bugs in-place if found, but do not rewrite.
+- **The FastAPI service** — leave dormant for the duration. It comes back into focus post-rebuild.
+
+## Rough timeline
+
+| Week | Work |
+|------|------|
+| 1 | Steps 1-2: branch, tag, `app_minimal.py` wired and locally runnable |
+| 2 | Step 3: eval infrastructure + script scaffolded; Step 4 started (recording script sent to speakers) |
+| 3 | Step 4 continues: first 50 utterances collected, transcribed, committed to eval manifest |
+| 4 | Step 3 closed: first baseline eval run, numbers recorded in `docs/metrics.md`; Step 5: minimal Space deployed |
+| 5-6 | Step 6: field test runs, logs accumulate, interviews at end of week 5 and week 6 |
+| 7 | Step 7: reintegration PR, follow-up roadmap written |
+
+Seven weeks to close the measurement gap, with production untouched the whole time.
+
+## One-line summary
+
+The rebuild is a parallel minimal track that collects the real-user signal the project was built without — nothing gets deleted, production keeps shipping, and the reintegration at the end is a PR of data and docs, not code.

docs/notebook_collaboration.md

@@ -0,0 +1,159 @@
+# Notebook Collaboration — How We Work on Kaggle Notebooks Together
+
+*Audience: anyone collaborating with Broulaye on Sahel-Voice-Lab*
+*Last updated: 2026-04-20*
+
+## Why we're changing how we work
+
+Up to now, we've mostly been editing notebooks inside the Kaggle web UI, downloading them occasionally, and pushing to git. That's painful because:
+
+- The Kaggle copy and the git copy drift apart — it's never clear which one is "right."
+- Cell outputs and execution counts change every run, so git diffs are huge and unreadable.
+- If both of us edit the same notebook at the same time, one of us accidentally overwrites the other.
+
+The new workflow fixes this by making **git the single source of truth** and using Kaggle purely as the place where notebooks *run*. We edit locally, commit to git, and push the notebook up to Kaggle with one command. The Kaggle web UI becomes read-only for our shared notebooks — we still go there to watch runs and read logs, but we don't type code into it anymore.
+
+## What you need to install (one time, on your own machine)
+
+```bash
+pip install kaggle nbstripout
+```
+
+- `kaggle` — the official Kaggle command-line tool. Lets you push, pull, run, and monitor Kaggle notebooks from your terminal.
+- `nbstripout` — strips cell outputs and execution counts from notebooks before they hit git, so diffs stay about *code*, not noise.
+
+## Set up your Kaggle API credentials (one time)
+
+1. Go to [kaggle.com](https://www.kaggle.com), click your avatar → **Settings** → **API** → **Create New API Token**. A file called `kaggle.json` downloads.
+2. Move it to the right place and lock down permissions:
+
+```bash
+mkdir -p ~/.kaggle
+mv ~/Downloads/kaggle.json ~/.kaggle/kaggle.json
+chmod 600 ~/.kaggle/kaggle.json
+```
+
+3. Confirm it works:
+
+```bash
+kaggle kernels list --mine
+```
+
+You should see your existing kernels. If you get an auth error, check the file location and permissions.
+
+**Never commit `kaggle.json` to git.** It's already in `.gitignore` in this repo, but if you work in another repo, add it yourself.
+
+## Repository layout for notebooks
+
+Each Kaggle notebook ("kernel" in Kaggle's API language) needs its own folder with a `kernel-metadata.json` file next to the `.ipynb`. Our structure:
+
+```
+notebooks/
+  kaggle_master_trainer/
+    kernel-metadata.json
+    kaggle_master_trainer.ipynb
+  train_fula_tts/
+    kernel-metadata.json
+    train_fula_tts.ipynb
+  bootstrap_repos.ipynb           # local helper, not a Kaggle kernel
+  train_colab.ipynb               # runs on Google Colab, different flow
+```
+
+A `kernel-metadata.json` looks roughly like this (example for the master trainer):
+
+```json
+{
+  "id": "ous-sow/sahel-kaggle-master-trainer",
+  "title": "Sahel-Voice-Lab Master Trainer",
+  "code_file": "kaggle_master_trainer.ipynb",
+  "language": "python",
+  "kernel_type": "notebook",
+  "is_private": true,
+  "enable_gpu": true,
+  "enable_internet": true,
+  "dataset_sources": ["google/fleurs", "robotsmali/jeli-asr"],
+  "kernel_sources": [],
+  "competition_sources": []
+}
+```
+
+The `id` field (`owner/slug`) is **permanent**. Once we've agreed on a slug for a shared kernel, never change it — that's our shared pointer to the kernel living on Kaggle.
+
+## Enable the nbstripout filter in the repo (one time per clone)
+
+From the repo root, the first time you clone:
+
+```bash
+nbstripout --install --attributes .gitattributes
+```
+
+This adds a git filter that runs on every `.ipynb` before it gets committed, stripping outputs and execution counts. Commit the `.gitattributes` file so everyone else picks it up automatically.
+
+**First-time caveat:** if the repo previously had notebooks-with-outputs committed, your first diff after enabling this will look like everything is being "deleted." That's correct and one-time — it's just stripping the old outputs.
+
+## The daily workflow
+
+```bash
+# 1. Pull the latest version from git
+git pull
+
+# 2. Edit the notebook locally (VS Code, JupyterLab, whatever you prefer)
+#    — running cells is fine; nbstripout handles the cleanup on commit.
+
+# 3. Commit your changes
+git add notebooks/kaggle_master_trainer/kaggle_master_trainer.ipynb
+git commit -m "experiment: lower LR for ASR adapter"
+git push
+
+# 4. Push the notebook up to Kaggle to actually run it
+cd notebooks/kaggle_master_trainer
+kaggle kernels push
+
+# 5. Watch the run
+kaggle kernels status ous-sow/sahel-kaggle-master-trainer
+
+# 6. When it's done, pull outputs if you need them
+kaggle kernels output ous-sow/sahel-kaggle-master-trainer -p ./runs/$(date +%F)/
+```
+
+Results go into `runs/` (which is gitignored). **They do not go back into the `.ipynb` in git** — that's what nbstripout is protecting us from.
+
+## Team rules (please read these — they matter)
+
+1. **Never edit shared notebooks in the Kaggle web UI.** Use the web UI to watch runs, read logs, download output files. If you want to experiment, do it locally. If you absolutely must try something quick in the web UI, treat it as a scratch copy — do not manually merge it back.
+
+2. **One runner at a time per kernel.** `kaggle kernels push` *replaces* the notebook on Kaggle's side. If you push while the other person's run is queued or mid-execution, you'll queue behind them or disrupt them. Coordinate over chat, or — better — give yourself a personal kernel slug (e.g. `ous-sow/sahel-trainer-dev-<yourname>`) for experimentation, and only push to the shared kernel (`ous-sow/sahel-kaggle-master-trainer`) when a change is ready to run cleanly.
+
+3. **Git is the source of truth, always.** Every Kaggle run begins with a `kaggle kernels push` from the current git state. Nothing on Kaggle is authoritative. If something on Kaggle looks different from git, git wins — pull from git, re-push, run again.
+
+## Troubleshooting
+
+**`kaggle kernels push` says "message: Kernel already exists."**
+Expected — it's just telling you the kernel already exists on Kaggle and will be updated. Not an error.
+
+**Huge diff with no real code changes.**
+`nbstripout` isn't active in your clone. Run `nbstripout --install --attributes .gitattributes` from the repo root and re-stage the file.
+
+**Auth errors from `kaggle` CLI.**
+Check `~/.kaggle/kaggle.json` exists, is yours (not someone else's), and has mode 600.
+
+**Merge conflict on a `kernel-metadata.json`.**
+Rare but possible if two people edit metadata simultaneously. The file is small JSON — resolve by hand, keeping the shared `id` untouched.
+
+**The notebook ran fine on Kaggle but saved outputs landed in git anyway.**
+You committed before `nbstripout` stripped outputs. Either re-stage (`git add`) which triggers the filter, or run `nbstripout <file.ipynb>` manually before `git add`.
+
+**You accidentally edited on the Kaggle web UI.**
+Go to Kaggle → your kernel → "..." → Download notebook. Overwrite the local `.ipynb` with the downloaded file. Commit. Re-push. Don't panic — just restore git as the source of truth.
+
+## What this workflow does not solve
+
+- **Two people editing the same cell at the same time.** Normal git merge conflicts will still happen if both of us touch the same notebook cell simultaneously. Mitigation: work on different notebooks when possible, or pair-edit voice-on-voice. If this becomes frequent, we can add `jupytext` later, which pairs each `.ipynb` with a `.py` mirror that merges like regular Python.
+- **Debugging a crashing Kaggle run.** The MCP/CLI pushes and watches, but fixing the crash is still back-and-forth between your local editor and the Kaggle logs. The workflow just removes the "which version is right" confusion from that loop.
+- **Kaggle's GPU quota.** You still get 30 free GPU hours per week. Plan accordingly.
+
+## TL;DR
+
+Edit locally, commit to git, `kaggle kernels push` to run, `kaggle kernels output` to retrieve. Never edit on the Kaggle web UI for shared kernels. Git is the source of truth. `nbstripout` keeps diffs clean.
+
+If anything here doesn't make sense, ping Broulaye before improvising.

docs/roadmap_2026-04.md

@@ -0,0 +1,292 @@
+# Sahel-Voice-Lab — Roadmap & Starting-from-Scratch Plan
+
+*Last updated: 2026-04-19*
+*Maintainer: Broulaye*
+
+This document has two parts:
+
+1. **Where the project stands today** — what's built, what's missing, and what to do next.
+2. **If I were starting from zero today** — a realistic, solo-maintainer, free-compute path from nothing to a usable Bambara voice assistant.
+
+---
+
+## Part 1 — The four layers, in plain language
+
+A voice assistant is four layers stacked on top of each other. Most of this project is about the fourth layer; the first three are mostly rented or borrowed.
+
+### Layer 1 — the ear: Speech-to-Text (STT / ASR)
+
+Abbreviations:
+- **STT** = Speech-to-Text
+- **ASR** = Automatic Speech Recognition (same thing)
+- **LoRA** = Low-Rank Adaptation — a technique to "patch" a large model with a tiny file (~50 MB) instead of retraining all of it
+- **PEFT** = Parameter-Efficient Fine-Tuning — the HuggingFace library that implements LoRA
+
+The model used is **Whisper** (OpenAI's open-source multilingual speech model). Out of the box, Whisper's Bambara is poor because it barely saw Bambara during training. The fix: train LoRA adapters per language. One ~1.5 GB Whisper backbone stays in memory; small Bambara and Fula patches swap in and out in ~50 ms.
+
+Where it lives in the repo:
+- `src/engine/whisper_base.py` — loads the backbone
+- `src/engine/adapter_manager.py` — the hot-swap
+- `src/engine/transcriber.py` — what the app calls
+- `src/training/trainer.py` + `notebooks/kaggle_master_trainer.ipynb` — training
+
+### Layer 2 — the brain: Large Language Model (LLM)
+
+Abbreviations:
+- **LLM** = Large Language Model
+- **JSON** = JavaScript Object Notation, a structured format
+
+No one trains this from scratch. You rent one. The project calls **Qwen** (Alibaba's multilingual model) through HuggingFace's hosted inference service, with a custom "adult-child" prompt that forces structured JSON output (fields like intent, reply, translation).
+
+Where it lives:
+- `src/llm/gemma_client.py` — named "gemma" for legacy reasons; now talks to Qwen.
+
+### Layer 3 — the mouth: Text-to-Speech (TTS)
+
+Abbreviations:
+- **TTS** = Text-to-Speech
+- **MMS** = Massively Multilingual Speech (Meta's 1000+ language model, lower quality, used as fallback)
+- **VITS** = Variational Inference Text-to-Speech (a specific architecture — higher quality, one speaker per trained model)
+- **F5-TTS** = a recent zero-shot voice-cloning TTS system
+
+The hardest layer for low-resource languages. Needs hours of clean studio audio from a native speaker. Used in tiers:
+- MMS-TTS as fallback baseline
+- Waxal-VITS for trained Bambara quality
+- F5-TTS for voice cloning in Phase 3
+
+Where it lives:
+- `src/tts/mms_tts.py`, `src/tts/waxal_tts.py`, `src/tts/f5_tts.py`, `src/tts/voice_cloner.py`
+
+### Layer 4 — the glue
+
+The real differentiator of the project — everything that makes the rented models into a product.
+
+Abbreviations:
+- **IoT** = Internet of Things (networked sensors)
+- **ECAPA-TDNN** = Emphasized Channel Attention Propagation — Time-Delay Neural Network; a speaker-fingerprint model
+
+Components:
+- Memory loop — `src/memory/memory_manager.py`
+- Normalization — `src/data/bam_normalize.py`, `src/data/adlam.py`
+- Fast-path phrases — `src/conversation/phrase_matcher.py`
+- Intent detection — `src/iot/intent_parser.py`
+- Voice responder (≤ 6-word replies) — `src/iot/voice_responder.py`
+- Sensor bridge — `src/iot/sensor_bridge.py`
+- Speaker ID — `src/voice/speaker_profiles.py`
+
+---
+
+## Part 2 — What's present vs missing
+
+### Present
+- All four layers scaffolded; every module named in the project description exists in `src/`
+- Two entry points: `app.py` (Gradio, HF Space) and `src/api/app.py` (FastAPI)
+- Training infrastructure and Kaggle notebooks
+- Mobile export pipeline (ONNX, TFLite) in `src/optimization/`
+- Bambara Waxal-VITS TTS working
+- Memory loop wired into UI
+- Agricultural domain vocabulary and intent model
+
+### Missing or weak
+1. `data/vocabulary.jsonl` is empty — no local snapshot of user-taught words
+2. LoRA fine-tuning still crashes on Kaggle T4 (active blocker per project notes)
+3. Fula TTS is a placeholder — no trained `ous-sow/fula-tts` yet
+4. No real-user evaluation set (no `data/eval/` folder with farmer recordings); all quality numbers currently come from FLEURS, which does not reflect real conditions
+5. No documented tone-handling policy for TTS (Bambara tone is unmarked in writing but matters for pronunciation)
+
+---
+
+## Part 3 — Actionable next steps (ordered by leverage)
+
+### Step 1 — Fix the LoRA training crash on Kaggle
+Highest leverage. Unblocks every ASR quality gain downstream.
+- Reproduce the exact error on a Kaggle T4 runtime
+- Pin `datasets` to a known-good version (either pre-4.x, or the correct torchcodec pin for 4.x)
+- If the AMP (Automatic Mixed Precision) scaler is the issue, either disable AMP or switch to bf16 if T4 supports it cleanly
+- Validate with a tiny 100-sample training job before a full run
+- Commit a working Bambara adapter before moving on
+
+### Step 2 — Build a real-user evaluation set
+Do this in parallel with Step 1.
+- Record 50-100 Bambara utterances from at least 3 native speakers
+- Include noisy conditions (wind, motorcycle, livestock — `noise_samples/` already anticipates this)
+- Transcribe by hand; store under `data/eval/bambara_field.jsonl`
+- Run the current stack and record baseline WER (Word Error Rate) and CER (Character Error Rate)
+- From here on, all changes measured against this set, not FLEURS
+
+### Step 3 — Exercise the memory loop end-to-end
+- Run 10 live teaching sessions
+- Confirm local JSONL grows; confirm HuggingFace Hub push
+- Add a test under `tests/` that mocks the Hub and validates the write path
+
+### Step 4 — Train `ous-sow/fula-tts`
+- Can run in parallel on RunPod
+- Need 1-3 hours of clean studio audio from a single Fula speaker
+- Same VITS recipe as Waxal Bambara
+
+### Step 5 — Close Phase 3 voice-to-voice parity
+- Once Fula TTS exists, test the full voice-in → voice-out pipeline for both languages
+- Measure round-trip CER: spoken sentence → transcript → response → synthesized speech → re-transcribe → compare
+- Catches compounding errors across layers
+
+### Step 6 — Small field test
+- Five Malian farmers. Cheap version: WhatsApp voice messages or a phone call with screen-shared Gradio
+- Log what they try to ask, whether the response is intelligible, whether they'd use it again
+- Success metric: do they ask a second question without being prompted?
+
+### Step 7 — Write a tone-handling policy
+- Pick a position: "accept tonally-wrong TTS on homographs as a known limitation" vs "invest in tone annotation for TTS training corpus in cycle N+1"
+- Either is defensible. The bad option is leaving it unspoken.
+
+---
+
+## Part 4 — If I were starting from zero today
+
+Realistic assumptions: solo maintainer, nights-and-weekends pace, free or cheap compute (Kaggle free T4, HuggingFace Spaces cpu-basic, occasional RunPod for bigger runs), access to native speakers (this one is non-negotiable — if you don't have them, stop and find them first).
+
+The single most important lesson from Sahel-Voice-Lab as it exists today: **it does four product's worth of things at once** (agricultural IoT, self-teaching, multi-language, voice cloning). If starting over, I'd ship one at a time.
+
+### Month 0 — Before writing any code
+1. Pick a narrow use case. Not "general Bambara assistant." Something like "voice queries for soil moisture" or "learn 100 agricultural words." One domain, one job.
+2. Identify 3-5 native speakers willing to test throughout. Get their phone numbers. Ask now, not later.
+3. Map the data landscape. Write a one-page doc listing every Bambara dataset you find: FLEURS (bam_ML), RobotsMali Jeli-ASR, OpenSLR, Masakhane resources, Common Voice. Note size, license, quality.
+4. Decide: Bambara only for the first version. Fula comes later. Do not start bilingual.
+
+### Month 1 — Text-first prototype (no audio yet)
+5. Wire the LLM (Qwen via HuggingFace Inference) with a carefully-written system prompt. Start in French or English; have it answer in Bambara.
+6. Build a Gradio text-in / text-out demo. Deploy to a HuggingFace Space on cpu-basic.
+7. Write the normalizer (the `bam_normalize.py` equivalent) with real tests. Spend real time on this; the audit you already did on the alphabet is the specification.
+8. Show it to your native speakers. Is the Bambara intelligible? Are the answers right?
+9. **Do not add STT or TTS yet.** This stage's only job is to learn what the LLM knows about Bambara and what it doesn't.
+
+### Month 2 — Add the ear, and the eval set
+10. **Build the evaluation set before training anything.** 50 utterances, 3 speakers, hand-transcribed. This is the most "wish I'd done this earlier" advice in low-resource ASR.
+11. Try Whisper-large-v3-turbo zero-shot on your eval set. Record the baseline WER. It will probably be 60-80%.
+12. Only then start LoRA fine-tuning with FLEURS + Jeli-ASR on Kaggle T4. Target: WER from ~70% to ~30% within four weeks.
+13. Wire the trained adapter into the Gradio app.
+
+### Month 3 — Add the mouth (baseline quality)
+14. Use MMS-TTS Bambara. One API call. It sounds robotic but it speaks.
+15. Ship this as the "Phase 1 complete" milestone on HuggingFace Spaces. This is a real product now: voice in, voice out.
+16. Collect 50-100 field interactions. Log everything.
+
+### Month 4 — Memory loop
+17. Build the teach-new-word flow.
+18. JSONL on disk + HuggingFace dataset push.
+19. Add the "curiosity" feature (system occasionally asks the user to teach it a word).
+20. Exercise it with real users before declaring it done. An empty `vocabulary.jsonl` is a sign the loop was never really tested.
+
+### Month 5 — Upgrade TTS
+21. Record 1-3 hours of studio audio with a single native speaker reading from a curated script that covers your domain vocabulary. This is the single biggest quality jump in the whole project.
+22. Train a VITS model (Waxal-style). Swap MMS out for it.
+23. Compare side-by-side with native listeners. Keep MMS as fallback.
+
+### Month 6 — Field test and iterate
+24. Five farmers. Phone calls or WhatsApp. Real conditions.
+25. Success metric: do they ask a second question unprompted? Do they come back tomorrow?
+26. Expect this stage to reshape priorities. Follow the feedback; do not defend the roadmap.
+
+### Month 7+ — Everything else
+27. Second language (Fula / Adlam): only after Bambara is stable
+28. Voice cloning (F5-TTS)
+29. Mobile / offline export (ONNX, TFLite)
+30. IoT sensor integration
+31. FastAPI service alongside the Gradio app
+
+### Things I would deliberately do differently
+- **Ship the ugliest possible version at Month 3, not the polished pipeline at Month 9.** Five farmers with a robotic voice tell you more than 500 hours of benchmark tuning.
+- **Build the evaluation set in Month 2, not later.** Every decision compounds; without an eval, you cannot tell which decisions to keep.
+- **One language, one entry point, one framework at a time.** The current project has FastAPI + Gradio + Kaggle + ONNX + TFLite + bitsandbytes + speaker ID + voice cloning. Each is a maintenance commitment. Add them only when the product's existence justifies them.
+- **No training your own ASR adapter until the LLM/TTS product has been tested.** Whisper zero-shot is good enough to validate the product idea. Training is expensive; you might end up optimizing a layer users don't care about.
+- **Native speakers as collaborators, not testers at the end.** Monthly review calls from Month 1, not Month 6.
+
+### One-sentence summary
+If I were starting from zero today, I would ship a narrow, ugly, one-language, text-first version to five real native-speaker users in the first three months, and build everything else on top of the feedback from those five people.
+
+---
+
+## Part 5 — Expanded walkthrough: why, how, and where Sahel-Voice-Lab fits
+
+Each stage below has three sections: **Why** (the purpose — why this stage exists and what breaks if you skip it), **How** (concrete mechanics — files, commands, tools, decisions), and **Current project status** (what you have, what's missing, relative to this stage).
+
+### Stage A — Scoping and data audit (Month 0)
+
+**Why.** The single biggest failure mode in low-resource voice AI is attempting a "general Bambara assistant." You cannot measure general; you cannot ship general; you cannot collect targeted data for general. You need one narrow domain so vocabulary is bounded, users can be found, failures are diagnosable, and every subsequent decision has a clear yes/no test: "does this help a farmer query soil moisture?" A bad scope locks in months of wasted work.
+
+**How.** Write a one-page scoping document that answers: (1) what is the single first use case — one sentence, measurable; (2) who is the first user — names, phone numbers, what language variety they speak; (3) what does success look like in three months — one metric, not five. Then write a data audit: every public Bambara dataset with size, license, quality, and known issues. FLEURS (`bam_ML`), RobotsMali Jeli-ASR, OpenSLR, Masakhane, Common Voice. Note what's missing — domain vocabulary usually is.
+
+**Current project status.** Stage A is implicitly done. The domain is "agricultural voice interface for Sahelian farmers." The data sources are identified and wired (`src/data/waxal_loader.py`, `src/data/web_harvester.py`, FLEURS referenced in training configs). The one thing weakly documented is the *target user profile* — which region, which dialect, what level of literacy, what phones they use. Writing this down explicitly (even as a one-paragraph persona in the README) tightens every downstream decision.
+
+### Stage B — Text-first prototype (Month 1)
+
+**Why.** Before introducing audio, you need to know what the LLM actually knows about Bambara and what it doesn't. If the text-in/text-out experience is bad, adding voice will not save it; voice only adds more failure modes. Text prototyping is cheap — one deployment, no GPU, a few prompts — and teaches you the vocabulary gap you will spend the rest of the project closing.
+
+**How.** Call a hosted multilingual LLM (Qwen, Mistral, Gemma) via HuggingFace Inference with `huggingface-hub`'s `InferenceClient`. Write a careful system prompt — the "adult-child" contract: LLM acts like a patient teacher, returns structured JSON with fields `{intent, reply_bm, reply_fr, confidence}`. Deploy a Gradio text-in/text-out interface to a HuggingFace Space on `cpu-basic`. Show it to two native speakers; ask what sounds wrong. Spend real time on the normalizer at this stage — the orthography audit (`ɛ ↔ e`, `ɔ ↔ o`, `ɲ ↔ ny/gn`, `ŋ ↔ ng`, 1967 vs older forms, and the `ny` ambiguity between palatal nasal and nasal + palatal glide) is the specification.
+
+**Current project status.** Stage B is done. `src/llm/gemma_client.py` implements the adult-child JSON contract against Qwen. `src/data/bam_normalize.py` handles the orthographic cleanups. The Gradio app has been deployed. This stage is behind you.
+
+### Stage C — The ear: STT plus the evaluation set (Month 2)
+
+**Why.** This is the stage with the highest "wish I'd done it earlier" rate in low-resource ASR. You need a real-user evaluation set *before* you train anything, because training without an eval is hill-climbing in the dark. FLEURS numbers do not predict field performance; field recordings do. Only after an eval exists is it worth investing Kaggle hours in fine-tuning.
+
+**How.** First, the eval set. Ask three native speakers to each record 15-20 utterances covering your domain vocabulary. Use their actual phones, in their actual environments (not a quiet office). Transcribe by hand. Store under `data/eval/bambara_field.jsonl` as `{audio_path, transcript, speaker_id, noise_conditions}`. Run Whisper-large-v3-turbo zero-shot against it. Record the baseline WER (Word Error Rate) and CER (Character Error Rate) numbers in the repo somewhere durable (`docs/metrics.md`). Only then: start LoRA fine-tuning with FLEURS + Jeli-ASR on Kaggle T4. Each training run is measured against your eval set, not against FLEURS.
+
+**Current project status. You are mostly here — with two important gaps.** The Whisper + LoRA + adapter-swap pipeline is built (`src/engine/whisper_base.py`, `src/engine/adapter_manager.py`, `src/engine/transcriber.py`). Training infrastructure exists (`src/training/trainer.py`, `notebooks/kaggle_master_trainer.ipynb`). However: (1) there is no `data/eval/` folder with real farmer recordings, and (2) the LoRA fine-tuning pipeline still crashes on Kaggle T4 per your project notes. These are your two most important current blockers. Until they resolve, every other ASR improvement is speculative.
+
+### Stage D — The mouth: baseline TTS and first ship (Month 3)
+
+**Why.** Shipping an ugly working product beats polishing a pretty broken one. The first voice-in/voice-out deployment reveals failure modes no amount of offline testing catches — wake-word confusion, ambient noise you didn't model, users speaking too fast or too softly, compounding latency that makes the system feel dead. You cannot learn these from benchmarks; you learn them from users. Ship at the robotic-voice MMS-TTS baseline, then improve.
+
+**How.** Wire MMS-TTS Bambara (`facebook/mms-tts-bam`) into the Gradio app — it's one `from transformers import VitsModel` call plus audio post-processing. Return audio as a Gradio `gr.Audio` output. Deploy. Write a very short intro text explaining this is a prototype. Share the Space URL with two native-speaker testers, tell them nothing about how it works, ask them to try three things.
+
+**Current project status.** Stage D is done. MMS-TTS is wired (`src/tts/mms_tts.py`), the Gradio Space is deployed, Phase 1 has shipped per your notes. Two things that might be worth auditing: whether the deployed Space is still on the MMS fallback or already on Waxal-VITS, and whether there is *any* logging/telemetry on usage to tell you whether real people are actually touching the deployed Space.
+
+### Stage E — The memory loop (Month 4)
+
+**Why.** The model does not know most Bambara vocabulary; users do. Without a mechanism to capture and persist what they teach, every conversation's knowledge dies with the session. The memory loop is the product's data-collection engine — the thing that lets it get better over time without you personally labeling data. This is also the core differentiation of Sahel-Voice-Lab versus a generic Bambara ASR+TTS demo.
+
+**How.** Three components. (1) A teach-new-word flow in the UI: the user says "this is how you say X," the system confirms, stores to `data/vocabulary.jsonl` as `{word, translation, speaker_id, timestamp, audio_ref}`. (2) An async push to a versioned HuggingFace dataset (`ous-sow/sahel-agri-feedback`). (3) A "curiosity" mechanism where every N turns the LLM is prompted to identify a vocabulary gap and ask the user — this inverts the teaching initiative and collects more data per session.
+
+**Current project status.** Stage E is structurally done but likely not exercised. `src/memory/memory_manager.py` implements the thread-safe JSONL + Hub push. `src/engine/curiosity.py` implements the CuriosityEngine. The Gradio app has a Teaching tab. However, your local `data/vocabulary.jsonl` is empty (0 lines). This means one of three things: (a) no one has used the teach flow yet, (b) the write path is broken and you haven't noticed because no one has used it, or (c) data goes only to the Hub and you've never pulled a snapshot locally. Worth a 20-minute investigation to confirm which. A test in `tests/` that mocks the Hub and asserts the local JSONL write is cheap insurance.
+
+### Stage F — Upgraded TTS (Month 5)
+
+**Why.** MMS-TTS works but sounds robotic, and users notice immediately. Moving to a single-speaker VITS model trained on 1-3 hours of clean studio audio is the single biggest perceived-quality jump in the entire pipeline. It also gives you something MMS cannot: a consistent, identifiable voice that users remember. For long-term adoption, voice identity matters as much as intelligibility.
+
+**How.** Record 1-3 hours of studio audio with one native speaker reading a curated script that covers your domain vocabulary plus conversational filler. Target: quiet room, decent USB mic, 22050 or 44100 Hz, single take per sentence. Align transcripts, clean silence, normalize loudness. Train a VITS model on your RunPod GPU (Kaggle T4 usually not enough memory for full VITS). Publish to HuggingFace as a private or public model repo. Swap out MMS in the TTS dispatcher, keep MMS as fallback.
+
+**Current project status.** Stage F is done for Bambara, not for Fula. The Waxal VITS integration lives in `src/tts/waxal_tts.py` and per your notes is partially shipped for Bambara (`ynnov/ekodi-bambara-tts-female`). Fula TTS is a placeholder — `ous-sow/fula-tts` does not exist yet. Closing this is one of your active goals. The recording session is usually the bottleneck, not the training.
+
+### Stage G — Field test (Month 6)
+
+**Why.** Everything before this stage is technical. This stage is where you find out whether the technical work produced something humans actually use. It's also where you discover that three of your prior assumptions were wrong — assumptions you could not have tested any other way. Every low-resource voice project that skips this stage ends up polished and unused.
+
+**How.** Five native-speaker users. Cheapest version: WhatsApp voice messages or a phone call with screen-shared Gradio. Give them a small task ("ask about your soil moisture"), observe without coaching. Record what they try to ask, whether the transcript is right, whether the answer is intelligible to them, whether they would use it unprompted again. The success metric is not WER. It is: *does the user ask a second question they came up with themselves?*
+
+**Current project status.** Stage G is **not done**. There is no field-test evidence in the repo, no usage logs, no session transcripts from actual farmers. This is, honestly, the single largest gap between where the project is and where it needs to be — more important than the Kaggle crash or the missing Fula TTS. You can ship a field test with what you have today and the feedback will reshape everything downstream.
+
+### Stage H — Expansion (Month 7+)
+
+**Why.** Only once a single-language, single-domain product has real users do you earn the right to expand. Each added dimension (second language, voice cloning, mobile export, IoT integration) doubles surface area for bugs and maintenance. Adding them in parallel to the core product means you will ship nothing well; adding them after the core is stable means each addition builds on a known-good base.
+
+**How.** Second language (Fula/Adlam): repeat stages B through G with the new language, reusing infrastructure but refitting normalization and TTS training. Voice cloning: F5-TTS or OpenVoice, keyed to a speaker embedding from the speaker-ID layer. Mobile export: ONNX per language, then TFLite via onnx-tf, then bundle into a thin Android app. IoT integration: FastAPI service in front of the sensor bridge, authenticated, cached.
+
+**Current project status. You are ahead of schedule here, which is the diagnostic.** Phase 3 voice-to-voice is merged and stabilizing. F5-TTS is scaffolded (`src/tts/f5_tts.py`). OpenVoice-based voice cloning is scaffolded (`src/tts/voice_cloner.py`). Speaker ID with ECAPA-TDNN is in place (`src/voice/speaker_profiles.py`). Adlam/Pular integration has landed. ONNX and TFLite exporters exist (`src/optimization/`). A FastAPI service is scaffolded (`src/api/`). This is Month 7+ work already in the codebase. The issue is not that this work is wrong — it is that it was built before Stages C (eval set), E (loop exercised with real data), and G (field test) were actually completed. The risk is building a polished Stage H surface on an unmeasured Stage C-E foundation.
+
+---
+
+## Where you actually are right now
+
+The honest diagnosis of Sahel-Voice-Lab as of 2026-04-19, mapped onto the staged plan:
+
+Done: Stages A, B, D. Bambara text and audio pipeline ships to users via Gradio on HF Spaces. The LLM contract is stable. Normalization is implemented.
+
+Partially done: Stage C (ASR pipeline built but no field eval set, training still crashes on Kaggle), Stage E (memory loop built but `vocabulary.jsonl` empty — not yet exercised with real users), Stage F (Bambara TTS upgraded, Fula TTS still placeholder).
+
+Not done: Stage G (no field test with real farmers).
+
+Ahead of schedule: Stage H (Phase 3 voice-to-voice, voice cloning, Adlam/Pular, ONNX/TFLite, FastAPI — all built in parallel with, or before, completing C/E/G).
+
+The path forward, ordered by leverage: (1) fix the Kaggle LoRA crash so Stage C can continue; (2) build the real-user eval set so Stage C has a measurement foundation; (3) exercise the memory loop with three real users so Stage E is confirmed; (4) run a small field test so Stage G is unblocked; (5) train `ous-sow/fula-tts` so Stage F closes for Fula; (6) return to Stage H work with actual user signal guiding priorities.
+
+Everything the project is missing is measurement. Everything the project has is implementation. That is a recoverable position, but only if the measurement work now gets the same weight the implementation work has had.

project-context.txt

@@ -0,0 +1,295 @@
+================================================================================
+PROJECT CONTEXT — sahel-agri-voice
+Generated: 2026-04-17
+================================================================================
+
+PROJECT NAME
+------------
+Sahel-Voice-Lab / Sahel-Agri Voice AI
+(HuggingFace Space title: "Sahel-Voice-Lab", Phase 1: "The Memory Loop")
+
+PURPOSE
+-------
+A voice-first, self-learning AI assistant for two West African languages —
+Bambara (bam, spoken in Mali) and Fula/Pular (ful, spoken in Guinea and
+Senegal) — targeted at farmers in the Sahel region.
+
+The system has two complementary capabilities:
+
+  1. LANGUAGE-LEARNING MEMORY LOOP (Phase 1)
+     The assistant behaves like an "eager child learner." Users teach it
+     Bambara/Fula words ("I ni ce means hello") via voice or text; an LLM
+     detects the teaching intent and the word pair is persisted to a
+     HuggingFace Hub dataset (ous-sow/sahel-agri-feedback → vocabulary.jsonl)
+     so knowledge accumulates across sessions and users. The vocabulary is
+     then injected into the LLM's system prompt as its source of truth for
+     answering questions.
+
+  2. AGRICULTURAL IoT VOICE INTERFACE
+     Farmers speak questions in their own language ("how is the soil?",
+     "is it going to rain?"). Whisper transcribes, an intent parser keyword-
+     matches Bambara/Fula agricultural terms (soil, rain, irrigation, pest),
+     a sensor bridge fetches data from an IoT backend (or mock data), and
+     VoiceResponder + a TTS engine reply in short Bambara/Fula sentences
+     with alert thresholds (e.g. "Bunding ji dɔgɔ. I ka foro ji." =
+     "Soil moisture is low. Irrigate your field.").
+
+The project is deployed as a HuggingFace Space (Gradio frontend) with an
+optional FastAPI service. The system is explicitly "100% non-Meta" for its
+core stack (Whisper / Qwen / F5-TTS / VITS), avoiding Meta models for the
+main loop.
+
+FULL TECH STACK
+---------------
+Deployment / hosting
+  - HuggingFace Spaces           (Gradio SDK 5.25.0, hardware: cpu-basic)
+  - Kaggle notebooks (T4 GPU)    for training runs
+  - RunPod                       alternative training environment
+  - HF Hub datasets              as persistent vocabulary + feedback store
+
+Frontend
+  - Gradio 5.25.0   (app.py — main UI; app_lab.py — experimental lab UI)
+
+Backend API
+  - FastAPI           (src/api/app.py via create_app() + lifespan)
+  - Pydantic v2       (schemas)
+  - httpx             (async calls to IoT sensor backend)
+
+Speech-to-text (STT)
+  - openai/whisper-large-v3-turbo  (default backbone)
+  - transformers 5.5.0 (WhisperForConditionalGeneration, WhisperProcessor)
+  - PEFT (LoRA adapters, hot-swappable per language)
+  - accelerate 1.13.0
+  - librosa 0.10.2, soundfile 0.12.1, torchaudio
+
+LLM (reasoning / teaching-intent detection)
+  - Qwen/Qwen2.5-72B-Instruct    (default, via HF Serverless Inference)
+  - Qwen/Qwen2.5-7B-Instruct, Mistral-7B-Instruct-v0.3, Zephyr-7b-beta
+    as faster alternatives
+  - huggingface-hub 1.9.0 InferenceClient
+
+Text-to-speech (TTS)
+  - Phase 1: facebook/mms-tts-bam, mms-tts-ful, mms-tts-fra, mms-tts-eng
+  - Phase 2: ynnov/ekodi-bambara-tts-female (VITS)
+             + placeholder ous-sow/fula-tts
+  - F5-TTS (SWivid/F5-TTS) for GPU voice cloning (optional, ~2GB)
+  - OpenVoice V2 (myshell-ai/openvoice-v2) for tone-color conversion
+  - SpeechBrain ECAPA-TDNN for speaker identification (per-user profiles)
+
+Data / datasets
+  - google/fleurs (bam_ML, ff_SN) as STT training corpus
+  - RobotsMali/jeli-asr, google/fleurs Fula, Wikipedia (bm, ff) harvested
+    text via src/data/web_harvester.py
+  - datasets 4.8.4 (+ torchcodec for 4.x audio decoding)
+  - Adlam ↔ Latin transliteration for Guinea Pular
+
+Training / fine-tuning
+  - PEFT LoRA + Seq2SeqTrainer
+  - jiwer 3.0.4 (WER / CER metrics)
+  - Custom callbacks: EarlyStoppingOnWER, AdapterCheckpointCallback
+  - FieldNoiseAugmenter (tractor / wind / livestock noise mixing)
+
+Optimization / edge deploy
+  - optimum[onnxruntime] → per-language ONNX export
+  - onnx-tf / TensorFlow → TFLite for Android
+  - bitsandbytes NF4 / 8-bit quantization (training environments)
+
+Utilities / runtime
+  - PyYAML 6.0.2, python-dotenv 1.1.0
+  - NumPy 2.2.4, SciPy 1.15.2
+  - rapidfuzz 3.13.0 (fuzzy phrase matching)
+  - pypdf, python-docx (Knowledge Base upload → vocabulary.jsonl)
+  - Kaggle API (Self-Teaching tab triggers training runs)
+  - ffmpeg (packages.txt — sole system-level dep)
+
+Environment variables
+  HF_TOKEN, FEEDBACK_REPO_ID (ous-sow/sahel-agri-feedback),
+  LLM_MODEL_ID, BAMBARA_ADAPTER_PATH, FULA_ADAPTER_PATH,
+  SENSOR_API_URL, BAMBARA_TTS_REPO, FULA_TTS_REPO, DEVICE, LOG_LEVEL
+
+KEY SOURCE FILES AND WHAT THEY DO
+---------------------------------
+Top-level entry points
+  app.py
+    Gradio UI (~99 KB). Main user-facing application running on the HF Space.
+    Wires STT → LLM → memory → TTS, exposes the Conversation / Teaching /
+    Knowledge Base / Self-Teaching tabs.
+  app_lab.py
+    Experimental/lab Gradio UI used to prototype new features
+    (e.g. CuriosityEngine integration) before folding into app.py.
+  setup.sh
+    Shell bootstrap for local + RunPod environments.
+
+src/api/  — FastAPI service (alternative to Gradio-only deploy)
+  app.py          FastAPI factory with async lifespan: loads Whisper backbone
+                  once, registers bam/ful adapters, pre-loads 'bam', attaches
+                  Transcriber + SensorBridge to app.state.
+  dependencies.py FastAPI DI helpers to pull shared objects off app.state.
+  middleware.py   CORS / logging middleware registration.
+  schemas.py      Pydantic v2 request/response models.
+  routes/health.py    GET /health — model status + loaded adapters.
+  routes/transcribe.py POST /transcribe — audio → text, 10 MB cap,
+                       wav/mp3/ogg/m4a/flac/webm.
+  routes/iot.py   POST /query — full pipeline: audio → transcribe → intent
+                   → sensor → voice response (IoTQueryResponse).
+
+src/engine/  — STT core
+  whisper_base.py     Singleton loader for WhisperForConditionalGeneration +
+                      WhisperProcessor. FP16 on CUDA, FP32 on CPU. free()
+                      releases VRAM.
+  adapter_manager.py  Hot-swap LoRA adapters via PEFT's multi-adapter API:
+                      first load ~2s, subsequent set_adapter ~50ms.
+                      Keeps one backbone in VRAM and swaps ~50MB adapters.
+  transcriber.py      Public inference API. Handles ≤30s chunks directly,
+                      >30s by slicing into 30s windows. Returns
+                      TranscriptionResult (text, language, duration_s,
+                      processing_time_ms, confidence).
+  stt_processor.py    avg_logprob confidence extractor; threshold -1.0 =
+                      "confused", caller should ask user to repeat.
+  curiosity.py        CuriosityEngine — every N interactions, prompts the
+                      LLM to spot a vocabulary gap and ask the user how to
+                      say a missing agricultural term.
+
+src/llm/
+  gemma_client.py     Wraps HF Serverless InferenceClient. Implements the
+                      "adult-child" system prompt that returns structured
+                      JSON with intent ∈ {teaching, question, conversation,
+                      error}. Parses JSON out of optional markdown fences.
+
+src/memory/
+  memory_manager.py   Thread-safe vocabulary store. Persists to
+                      data/vocabulary.jsonl locally and pushes asynchronously
+                      to HF Hub dataset. Provides get_recent() and a
+                      formatted get_vocabulary_context() for the LLM prompt.
+
+src/conversation/
+  phrase_matcher.py   RapidFuzz-based matcher over curated JSON phrase
+                      libraries (data/phrases/{lang}.json + _additions.json).
+                      Handles greetings / thanks / farewells without hitting
+                      the LLM.
+
+src/iot/
+  intent_parser.py    Keyword-based Intent classifier
+                      (greeting/thanks/farewell/check_soil/check_weather/
+                      irrigation_status/pest_alert) for bam, ful, fr, en.
+                      Confidence = matched_keywords / total_keywords.
+  sensor_bridge.py    Async bridge to an IoT backend (SENSOR_API_URL) for
+                      soil / weather / irrigation / pest readings.
+                      Falls back to mock random data.
+  voice_responder.py  Maps (Intent, SensorData) → short Bambara/Fula reply
+                      string (≤6 words per sentence for clean MMS-TTS) plus
+                      English translation. Alert thresholds encoded here
+                      (SOIL_MOISTURE_LOW=30, PH bounds, TEMP_HIGH=38, etc.).
+                      Also has a verbose French-language path.
+
+src/data/
+  agri_dictionary.py  Bambara + Fula domain vocab used to bias the Whisper
+                      decoder prompt toward agricultural terms.
+  waxal_loader.py     Streams google/fleurs (bam_ML, ff_SN) — the
+                      replacement for the retired google/waxal dataset.
+  feature_extractor.py Log-mel spectrogram extraction and batched padding
+                       collator for Whisper Seq2SeqTrainer.
+  augmentation.py     FieldNoiseAugmenter — mixes clean speech with
+                      tractor/wind/livestock samples; falls back to
+                      Gaussian noise.
+  bam_normalize.py    Bambara phonetic normalizer (ou→u, gn/ny→ɲ,
+                      N'Ko-derived standard).
+  adlam.py            Adlam (𞤀𞤣𞤤𞤢𞤥) ↔ Latin transliteration for Pular;
+                      normalize_pular() for ASR preprocessing.
+  web_harvester.py    Harvests RobotsMali/jeli-asr, google/fleurs ff_SN,
+                      and bm/ff Wikipedia into the feedback Hub dataset.
+
+src/training/
+  trainer.py          WhisperLoRATrainer — full fine-tune orchestration
+                      (backbone + LoraConfig + WaxalDataLoader +
+                      Seq2SeqTrainer).
+  metrics.py          WER/CER for Seq2SeqTrainer eval loop (via jiwer).
+  callbacks.py        EarlyStoppingOnWER, AdapterCheckpointCallback
+                      (saves adapter-only, not full model).
+
+src/tts/
+  waxal_tts.py        VITS engine wrapping ynnov/ekodi-bambara-tts-female
+                      for Bambara; Fula is a placeholder until
+                      ous-sow/fula-tts is trained.
+  mms_tts.py          Facebook MMS-TTS (bam/ful/fra/eng).
+  f5_tts.py           F5-TTS voice cloning (optional, GPU-only, ~750MB);
+                      gracefully falls back to MMS when missing.
+  voice_cloner.py     OpenVoice V2 tone-color converter — reshapes VITS
+                      audio to a target speaker's voice.
+
+src/voice/
+  speaker_profiles.py SpeakerProfileManager with SpeechBrain ECAPA-TDNN
+                      (192-d embeddings). Per-user running-average embeddings
+                      for identification + OpenVoice SE for cloning; cosine
+                      similarity ≥ 0.75 attributes to an existing user.
+
+src/optimization/
+  onnx_exporter.py    Merges LoRA into backbone and exports per-language
+                      ONNX (ONNX can't hot-swap adapters at runtime).
+  quantizer.py        BitsAndBytes NF4 / 8-bit quantization for GPU-
+                      constrained deploys (turbo ~3GB → ~1GB VRAM).
+  tflite_converter.py ONNX → TFLite for offline Android; exports encoder
+                      and decoder separately.
+
+Config / data folders
+  configs/            base_config.yaml + per-language LoRA configs.
+  data/               vocabulary.jsonl, phrases/*.json, profiles/, etc.
+  notebooks/          Kaggle / RunPod fine-tune + TTS training notebooks.
+  noise_samples/      .wav clips for field-noise augmentation.
+  scripts/            utility scripts (bootstrap, harvest, eval).
+  tests/              pytest suite (not installed in HF Spaces runtime).
+
+RECENT GIT COMMITS SUMMARY (last 20)
+------------------------------------
+The recent history is focused on three concurrent tracks:
+
+1. STT / training stability
+   - bb78cbf Add torchcodec install for datasets 4.x audio decoding
+   - 9049ef3 Prepare training stack for RunPod: env-aware notebook +
+             bootstrap script
+   - cc50efb Align Whisper default to turbo-v3 + add document upload to
+             Knowledge Base tab
+   - c33a061 Fix WhisperProcessor import in reload + upgrade base to
+             large-v3-turbo
+   - 7fae91b Fix mel-bin mismatch: load per-language processor from
+             fine-tuned checkpoint
+   - 6682858 Fix jiwer crash on post-normalisation empty refs;
+             register SLR106/105 datasets
+   - 58f431a Fix SyntaxError in Cell 17: unterminated f-string literal
+   - 3632a23 Fix compute_metrics crash on empty eval references
+             in Fula training
+   - 71bb3bc Fix: add trust_remote_code=True for datasets 3.x compatibility
+   - cd017e2 Fix Cell 16 ValueError: load model fp32 so AMP gradient scaler
+             works
+
+2. Language support / Adlam / Pular expansion
+   - ced078c Add Adlam/Pular Fula integration: transliterator +
+             3 new datasets + normalisation pipeline
+   - 40cf84d Fix language mixing: per-language prompts +
+             Mali Bambara / Guinea Pular context
+   - 33c3a5a Fix Self-Teaching language detection: parse code from
+             dropdown label
+   - 24b1617 Fix Self-Teaching tab: float sliders, deduplication,
+             Kaggle API fallback
+
+3. Conversation / voice pipeline
+   - 8952fff Phase 3: Voice-to-Voice S2S pipeline —
+             F5-TTS, LLM brain, CER metric
+   - ad902c6 Add real conversational memory + live learning to
+             Conversation Mode
+   - 8d7d9d8 Fix conversation mode timeout: two-stage pipeline + faster LLM
+   - 1958814 Fix "Model loading" stuck state: block in _do_asr until
+             Whisper is ready
+   - 618eab5 Fix model loading stuck forever + unhandled TTS crash in
+             conversation mode
+   - bfe5b59 Fix slow build: strip runtime-irrelevant heavy packages from
+             requirements.txt
+
+Overall trajectory: the project has moved past initial Phase 1 scaffolding
+and is iterating hard on (a) stabilising fine-tuning on Kaggle/RunPod with
+large-v3-turbo, (b) expanding to Guinea Pular with the native Adlam script,
+and (c) finishing the Phase 3 voice-to-voice pipeline (F5-TTS + LLM brain).
+Most recent commits are bug-fixes rather than net-new features, suggesting
+the current codebase is approaching a stable milestone.
+
+================================================================================

scripts/push_to_hf.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# push_to_hf.sh — Push current branch to Hugging Face Space main using HF_TOKEN.
+#
+# Usage:
+#   bash scripts/push_to_hf.sh
+#   HF_SPACE_REPO="spaces/ous-sow/sahel-agri-voice" bash scripts/push_to_hf.sh
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+HF_SPACE_REPO="${HF_SPACE_REPO:-spaces/ous-sow/sahel-agri-voice}"
+TARGET_BRANCH="${TARGET_BRANCH:-main}"
+
+# Load .env if present and HF_TOKEN is not already exported.
+if [[ -z "${HF_TOKEN:-}" && -f "$REPO_ROOT/.env" ]]; then
+    set -a
+    # shellcheck disable=SC1091
+    source "$REPO_ROOT/.env"
+    set +a
+fi
+
+if [[ -z "${HF_TOKEN:-}" ]]; then
+    echo "HF_TOKEN is not set."
+    echo "Set HF_TOKEN in your shell or in .env, then rerun."
+    exit 1
+fi
+
+CURRENT_BRANCH="$(git branch --show-current)"
+if [[ -z "$CURRENT_BRANCH" ]]; then
+    echo "Could not detect current git branch."
+    exit 1
+fi
+
+echo "Pushing '$CURRENT_BRANCH' to '$HF_SPACE_REPO' (remote branch: '$TARGET_BRANCH')..."
+git push "https://__token__:${HF_TOKEN}@huggingface.co/${HF_SPACE_REPO}" "${CURRENT_BRANCH}:${TARGET_BRANCH}"
+echo "Done."