step 2: add app_minimal.py — zero-shot baseline for rebuild.

app_minimal.py

@@ -0,0 +1,372 @@
+"""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, no IoT,
+no phrase matcher. Used for field testing and building a real-user eval set.
+
+See docs/baseline_rebuild.md for the plan this fits into.
+
+Run locally:
+    HF_TOKEN=hf_xxx python app_minimal.py
+
+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"
+    DEVICE         — "cuda" or "cpu" (auto if unset)
+    LOG_LEVEL      — default "INFO"
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional, Tuple
+
+import numpy as np
+
+# 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.tts.mms_tts import MMSTTSEngine
+
+logging.basicConfig(
+    level=os.getenv("LOG_LEVEL", "INFO"),
+    format="%(asctime)s  %(name)-30s  %(levelname)-7s  %(message)s",
+)
+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")
+_REQUESTED_DEVICE = os.environ.get("DEVICE")  # optional override
+
+LANG_CHOICES = [("Bambara", "bam"), ("Fula", "ful"), ("French", "fr"), ("English", "en")]
+LANG_NAMES = {"bam": "Bambara", "ful": "Fula", "fr": "French", "en": "English"}
+LANG_TO_WHISPER_HINT = {
+    # Whisper large-v3-turbo does not know Bambara/Fula as first-class
+    # languages. We leave `language` unset for those so Whisper auto-detects;
+    # fr/en are explicit hints for clean decoding.
+    "bam": None,
+    "ful": None,
+    "fr":  "french",
+    "en":  "english",
+}
+
+
+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.)"
+
+
+# ── Service singletons (lazy-loaded) ────────────────────────────────────────
+_backbone: Optional[WhisperBackbone] = None
+_llm:      Optional[GemmaClient]     = None
+_tts:      Optional[MMSTTSEngine]    = None
+
+
+def _resolve_device() -> str:
+    """Pick 'cuda' if torch sees a GPU, else 'cpu'. DEVICE env overrides."""
+    import torch  # lazy
+    if _REQUESTED_DEVICE:
+        return _REQUESTED_DEVICE
+    return "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def get_backbone() -> WhisperBackbone:
+    """Load the Whisper backbone once and cache. Zero-shot — no adapters."""
+    global _backbone
+    if _backbone is None:
+        _backbone = WhisperBackbone(config_path="configs/base_config.yaml")
+        _backbone.load(device=_resolve_device(), hf_token=HF_TOKEN)
+        logger.info("Whisper backbone ready: %s on %s",
+                    _backbone.model_id, _backbone.device)
+    return _backbone
+
+
+def get_llm() -> GemmaClient:
+    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)
+    return _llm
+
+
+def get_tts() -> MMSTTSEngine:
+    global _tts
+    if _tts is None:
+        _tts = MMSTTSEngine()
+        logger.info("MMS-TTS engine ready (lazy per-language load)")
+    return _tts
+
+
+# ── Core pipeline ────────────────────────────────────────────────────────────
+def transcribe(audio_np: np.ndarray, sample_rate: int, input_lang: str) -> str:
+    """Run zero-shot Whisper on a numpy audio array. Returns the raw transcript.
+
+    `input_lang` drives two things only: the Whisper language hint (for fr/en)
+    and whether bam_normalize is applied. It has no effect on the TTS voice or
+    on the LLM reply language — those are driven by the separate output-language
+    dropdown in the UI.
+    """
+    import torch  # lazy
+    import librosa  # lazy — resample if the mic gave us something non-16k
+
+    backbone = get_backbone()
+    target_sr = 16_000
+
+    # Ensure mono float32
+    if audio_np.ndim == 2:
+        audio_np = audio_np.mean(axis=1)
+    audio_np = audio_np.astype(np.float32)
+
+    # Gradio's gr.Audio often returns int16-scaled floats or ints — normalize.
+    peak = np.max(np.abs(audio_np)) if audio_np.size else 0.0
+    if peak > 1.5:  # looks like raw int16 cast to float
+        audio_np = audio_np / 32768.0
+
+    if sample_rate != target_sr:
+        audio_np = librosa.resample(audio_np, orig_sr=sample_rate, target_sr=target_sr)
+
+    inputs = backbone.processor(
+        audio_np, sampling_rate=target_sr, return_tensors="pt"
+    )
+    input_features = inputs.input_features.to(backbone.device)
+    if backbone.device == "cuda":
+        input_features = input_features.half()
+
+    gen_kwargs: dict = {"max_new_tokens": 128}
+    hint = LANG_TO_WHISPER_HINT.get(input_lang)
+    if hint:
+        gen_kwargs["language"] = hint
+        gen_kwargs["task"] = "transcribe"
+
+    with torch.no_grad():
+        output_ids = backbone.model.generate(input_features, **gen_kwargs)
+
+    transcript = backbone.processor.batch_decode(
+        output_ids, skip_special_tokens=True
+    )[0].strip()
+
+    if input_lang == "bam" and transcript:
+        transcript = bam_normalize(transcript)
+
+    return transcript
+
+
+def run_pipeline(
+    audio: Optional[Tuple[int, np.ndarray]],
+    input_lang: str,
+    output_lang: str,
+) -> Tuple[str, str, Optional[Tuple[int, np.ndarray]]]:
+    """Gradio handler for the Voice tab.
+
+    Args:
+        audio:       (sample_rate, audio_np) from gr.Audio.
+        input_lang:  language of the spoken input (drives Whisper hint + bam_normalize).
+        output_lang: language the LLM should reply in and the TTS should speak.
+
+    Returns (transcript, reply_text, reply_audio). Graceful degradation: any
+    stage failure yields a readable string and None audio instead of raising.
+    """
+    if audio is None:
+        return "", "(no audio received)", None
+
+    sample_rate, audio_np = audio
+    if audio_np.size == 0:
+        return "", "(empty audio)", None
+
+    try:
+        transcript = transcribe(audio_np, sample_rate, input_lang)
+    except Exception as exc:  # pragma: no cover — field-safety
+        logger.exception("Transcription failed")
+        return "", f"(STT error: {exc})", None
+
+    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="",
+        )
+    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)"
+
+    try:
+        wav, sr = get_tts().synthesize(
+            reply_text, language=output_lang, device=_resolve_device()
+        )
+    except Exception as exc:
+        logger.exception("TTS failed")
+        return transcript, reply_text, None
+
+    return transcript, reply_text, (sr, wav)
+
+
+def run_text_pipeline(
+    text: str,
+    output_lang: str,
+) -> Tuple[str, Optional[Tuple[int, np.ndarray]]]:
+    """Gradio handler for the Text tab.
+
+    Args:
+        text:        typed user input.
+        output_lang: language the LLM should reply in and the TTS should speak.
+
+    No input-language param — typed input is whatever the user types; the LLM
+    reads it as-is and replies in `output_lang`. Skips Whisper entirely; this
+    is the fast dev-loop path.
+    """
+    text = (text or "").strip()
+    if not text:
+        return "(no text entered)", None
+
+    try:
+        reply = get_llm().chat(
+            _with_reply_language_directive(text, output_lang),
+            vocabulary_context="",
+        )
+    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)"
+
+    try:
+        wav, sr = get_tts().synthesize(
+            reply_text, language=output_lang, device=_resolve_device()
+        )
+    except Exception as exc:
+        logger.exception("TTS failed")
+        return reply_text, None
+
+    return reply_text, (sr, wav)
+
+
+# ── Gradio UI ────────────────────────────────────────────────────────────────
+def build_ui():
+    """Construct and return the Gradio Blocks app."""
+    import gradio as gr  # lazy — keeps module importable without gradio installed
+
+    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`."
+        )
+
+        # Shared across tabs. Split into two so input and output language
+        # are never conflated — the Voice tab cares about both; the Text tab
+        # only uses output_lang (it doesn't feed Whisper).
+        with gr.Row():
+            input_lang = gr.Dropdown(
+                choices=LANG_CHOICES, value="bam", label="Input language",
+                info="Language you're speaking/typing. Drives Whisper hint "
+                     "(fr/en only) and bam_normalize (bam only).",
+            )
+            output_lang = gr.Dropdown(
+                choices=LANG_CHOICES, value="bam", label="Output language",
+                info="Language the LLM should reply in. Also picks the TTS voice.",
+            )
+
+        with gr.Tabs():
+            # ── Voice tab — the actual baseline the field test measures ─────
+            with gr.Tab("🎤 Voice (full STT → LLM → TTS)"):
+                with gr.Row():
+                    with gr.Column():
+                        audio_in = gr.Audio(
+                            sources=["microphone", "upload"],
+                            type="numpy",
+                            label="Speak (or upload a .wav)",
+                        )
+                        voice_submit = gr.Button(
+                            "Transcribe + Reply", variant="primary"
+                        )
+                    with gr.Column():
+                        transcript_out = gr.Textbox(
+                            label="Transcript (zero-shot Whisper)",
+                            lines=2, interactive=False,
+                        )
+                        voice_reply_out = gr.Textbox(
+                            label="LLM reply", lines=4, interactive=False,
+                        )
+                        voice_audio_out = gr.Audio(
+                            label="Reply audio", type="numpy", autoplay=False,
+                        )
+
+                voice_submit.click(
+                    fn=run_pipeline,
+                    inputs=[audio_in, input_lang, output_lang],
+                    outputs=[transcript_out, voice_reply_out, voice_audio_out],
+                )
+
+            # ── Text tab — dev loop, skips Whisper ──────────────────────────
+            with gr.Tab("⌨️ Text (LLM → TTS, dev loop)"):
+                with gr.Row():
+                    with gr.Column():
+                        text_in = gr.Textbox(
+                            label="Type your message",
+                            lines=3,
+                            placeholder="e.g. I ni ce — how do I say hello in Bambara?",
+                        )
+                        text_submit = gr.Button("Send", variant="primary")
+                    with gr.Column():
+                        text_reply_out = gr.Textbox(
+                            label="LLM reply", lines=4, interactive=False,
+                        )
+                        text_audio_out = gr.Audio(
+                            label="Reply audio", type="numpy", autoplay=False,
+                        )
+
+                # Text tab only uses output_lang — input_lang is a no-op here.
+                text_submit.click(
+                    fn=run_text_pipeline,
+                    inputs=[text_in, output_lang],
+                    outputs=[text_reply_out, text_audio_out],
+                )
+                # Pressing Enter in the textbox also submits.
+                text_in.submit(
+                    fn=run_text_pipeline,
+                    inputs=[text_in, output_lang],
+                    outputs=[text_reply_out, text_audio_out],
+                )
+
+        gr.Markdown(
+            "---\n"
+            "**What's intentionally missing:** LoRA adapters, memory/vocabulary "
+            "persistence, speaker ID, Waxal/F5 TTS, IoT sensor integration, "
+            "phrase-matcher shortcuts. All of those live in `app.py` — this is the "
+            "stripped-down baseline used to measure what Whisper zero-shot does on "
+            "real Bambara/Fula recordings and to collect a real-user eval set.\n\n"
+            "The **Text** tab skips Whisper — it's for fast iteration on the "
+            "LLM + TTS path, not for field-test measurement."
+        )
+
+    return demo
+
+
+def main() -> None:
+    if not HF_TOKEN:
+        logger.warning(
+            "HF_TOKEN is not set — the LLM call will fail. "
+            "Export HF_TOKEN before launching for the pipeline to work end-to-end."
+        )
+    demo = build_ui()
+    demo.queue().launch()
+
+
+if __name__ == "__main__":
+    main()

notebooks/kaggle_master_trainer/kaggle_master_trainer.ipynb

@@ -30,7 +30,19 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "print(\"test\")"
+    "# ── Cell 0: RUN_TRAINING gate ────────────────────────────────────────────────\n",
+    "# Kaggle runs the kernel on every `kaggle kernels push`. When you're just\n",
+    "# syncing code and don't want a real training run, leave this env var unset\n",
+    "# and the notebook exits in ~2s without burning GPU quota.\n",
+    "#\n",
+    "# To actually train: Kaggle web UI → Settings → Environment Variables →\n",
+    "# add RUN_TRAINING = 1, then push.\n",
+    "import os, sys\n",
+    "if os.environ.get('RUN_TRAINING', '0') != '1':\n",
+    "    print('RUN_TRAINING != 1 — code-only push, skipping execution.')\n",
+    "    print('Set RUN_TRAINING=1 in the Kaggle kernel env vars to run for real.')\n",
+    "    sys.exit(0)\n",
+    "print('RUN_TRAINING=1 — proceeding with full training run.')\n"
    ]
   },
   {