README.md

---
title: NCAIR ASR API
emoji: 🎙️
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

## NCAIR Nigerian ASR — API backend

An OpenAI-compatible speech-to-text service for the voice assistant. It loads the
right NCAIR Whisper model based on the request's `language` field, so one endpoint
covers **Yorùbá, Igbo, Hausa, and Nigerian-accented English**.

```
POST /v1/audio/transcriptions   multipart: file [, model] [, language]  ->  {"text": "..."}
GET  /health
```

| language value | Model |
|----------------|-------|
| `yo` / `yoruba` | NCAIR1/Yoruba-ASR |
| `ig` / `igbo` | NCAIR1/Igbo-ASR |
| `ha` / `hausa` | NCAIR1/Hausa-ASR |
| `en` / `english` / `nigerian english` | NCAIR1/NigerianAccentedEnglish |

Models load lazily on first use and are cached, so startup is fast and only the
languages you use get loaded. **CPU is enough** (Whisper Small).

---

### Before you deploy

These models are **gated and license-restricted**:

1. **Accept the terms** for each model you'll use on Hugging Face (Yoruba-ASR,
   Igbo-ASR, Hausa-ASR, NigerianAccentedEnglish) with the account whose token
   you'll use.
2. Add an **`HF_TOKEN`** Secret so the gated weights can download.
3. **License:** research/innovation license — not for commercial or large-scale
   use (>1000 active users) without a separate Awarri agreement. Attribution:
   *"developed by Awarri Technologies in partnership with the Federal Government of
   Nigeria."* (Not legal advice.)

---

### Deploy

1. Create a **Docker → Blank** Space, push `app.py`, `requirements.txt`,
   `Dockerfile`, `README.md`.
2. Add the `HF_TOKEN` Secret.
3. Wait for the build; the first call per language downloads that model.

### Wire it into voice-ai-demo

On the **voice-ai-demo** Space, set per language (Yoruba shown):

| Secret | Value |
|--------|-------|
| `ASR_YORUBA_BASE_URL` | `https://<this-space>.hf.space/v1` |

The demo sends `language=yo`, so this service returns Yoruba. For Igbo/Hausa/English,
add those languages to the demo's `config.json` and set `ASR_<LANG>_BASE_URL` to the
same URL — the service routes by the language hint.

### Local test

```bash
curl -X POST http://localhost:7860/v1/audio/transcriptions \
  -F "file=@sample.wav" -F "language=yo"
```

### Project Structure

```
ncair-asr-api/
├── app.py              # FastAPI OpenAI-compatible ASR (multi-language)
├── requirements.txt    # transformers 5.x + serving deps
├── Dockerfile          # CPU image with ffmpeg
└── README.md           # this file
```