lawmaluki/understand-kamba

Turn speech into text, in Kikamba, Swahili, or English. # understandkamba Turn speech into text, in Kikamba, Swahili, or English. Minimal FastAPI backend for Kikamba speech-to-text + translation service: audio recording, file upload, or a video/social-media link goes in; a transcript and Swahili/English translation come out. A static frontend (`frontend/`) also lets you translate typed Kikamba text directly, without any audio involved. This is a scaffold, not a finished product. Read `PLAN.md` first — it documents the build order and one important open question (whether the default ASR baseline actually supports Kamba) that needs resolving before the rest of this is worth trusting. ## Setup 1. Create a virtual environment and install dependencies: ``` python -m venv venv venv\Scripts\activate # Windows # source venv/bin/activate # macOS/Linux pip install -r requirements.txt ``` 2. Install ffmpeg if you don't already have it (required for audio conversion — `app/audio.py` shells out to `ffmpeg`/`ffprobe`): - Windows: ffmpeg.org (add the `bin` folder to PATH) - macOS: `brew install ffmpeg` - Linux: `apt install ffmpeg` (or your distro's equivalent) 3. Copy `.env.example` to `.env` and fill in `ANTHROPIC_API_KEY` and `TRANSLATION_MODEL` (check docs.claude.com for the current model identifier). Load it however you prefer — e.g. `pip install python-dotenv` and add `from dotenv import load_dotenv; load_dotenv()` at the top of `app/main.py`, or just `set`/`export` the variables in your shell. ## Step 1 — verify the ASR model actually supports Kamba **Do this before anything else.** See `PLAN.md` for why this isn't a given. ``` python scripts/check_asr_model.py ``` If it fails, see `PLAN.md`, "Fallback if MMS has no Kamba adapter" — don't proceed to steps 2/3 until you have a model that passes this check (or you've deliberately swapped in a fallback and updated `ASR_MODEL_ID` accordingly). ## Step 2 — test transcription standalone ``` python scripts/test_transcribe.py path\to\ …