agentsia223/checkia-ml-api

Self-contained API for Bambara translation and speech-to-text # checkia-ml-api A FastAPI service exposing Bambara-enabling NLP models behind a stable HTTP contract: - **`POST /translate`** — text translation between Bambara, French, and English. - **`POST /transcribe`** — speech-to-text for Bambara and French audio. Each model is selected by configuration, so models can be swapped via environment variables without changing the API contract or any client. ## Requirements - uv (manages the Python 3.12 toolchain and deps) - A Hugging Face token for gated models (set `HF_TOKEN`) - A Google Cloud Translation API key (set `GOOGLE_TRANSLATE_API_KEY`) ## Setup ```bash uv sync --group dev # create the venv and install everything cp .env.example .env # then fill in HF_TOKEN and any model overrides ``` ## Run ```bash uv run uvicorn app.main:app --reload ``` Models are downloaded and loaded **once at startup**, so the first start is slow; afterwards they are held in memory. Open 127.0.0.1 for the interactive API. ## API ``` GET /health -> {"status": "ok"} GET /models -> {"translation": " ", "asr": " "} POST /translate req {"text": "I ni ce", "source_lang": "bm", "target_lang": "fr"} resp {"translated_text": "...", "source_lang": "bm", "target_lang": "fr", "model": " "} POST /transcribe # multipart file upload ... req file= language=bm (optional) # ... or JSON with a URL: req {"audio_url": "https://...", "language": "bm"} resp {"text": "...", "language": "bm", "duration_s": 12.4, "model": " "} ``` Language codes at the boundary are `bm`, `fr`, `en`. Responses always include the `model` that served the request. Response fields are append-only. ## Configuration All via environment / `.env` (see `.env.example`): | Variable | Purpose | Default | |-------------|-------------------------------------------|--------------------------------------| | `MT_MODEL` | Translation provider label (reported as `model …