feat(m1): deployable FastAPI skeleton for Uzbek STT

- create_app() factory + lifespan; GET /api/health; root -> /docs
- RFC 9457 problem+json error model (413/422/400/429/503 inventory)
- single-source Settings (caps, rate, model ids)
- Dockerfile for HF Spaces (non-root UID 1000, port 7860, minimal M1 deps)
- spec features/uzbek-stt.md (team-lead SHAPE+JUDGE approved)
- tests green: ruff, mypy --strict, pytest (3 passed)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,13 @@
+.git/
+.venv/
+venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/
+features/
+tests/
+benchmark/
+.env

.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.env
+dist/
+build/

Dockerfile

@@ -0,0 +1,22 @@
+# M1 image — intentionally minimal (no torch / ffmpeg yet) so the first HF Spaces
+# build is fast and reliable. M2 adds the ML stack + ffmpeg + baked fast weights.
+FROM python:3.12-slim
+
+# HF Spaces runs containers as a non-root user with UID 1000.
+# Create /app owned by `user` BEFORE dropping privilege — otherwise Docker creates
+# the WORKDIR root-owned and later writes (M2 weight baking) fail.
+RUN useradd -m -u 1000 user && mkdir -p /app && chown user:user /app
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY --chown=user pyproject.toml README.md ./
+COPY --chown=user app ./app
+RUN pip install --no-cache-dir --user .
+
+# Port 7860 must stay in lockstep with README `app_port` and Settings.port.
+EXPOSE 7860
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,109 @@
+---
+title: Uzbek STT
+emoji: 🎙️
+colorFrom: green
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+---
+
+# Uzbek Speech-to-Text — a deployable service
+
+An end-to-end Uzbek speech-to-text **service**: a documented REST API, a demo UI, and an
+honest multi-engine benchmark — deployed to a live public URL on a **$0 budget** (no paid
+server, no paid API, no GPU). Built to demonstrate shipping and operating software, not just
+writing it.
+
+> **Live demo:** _coming with the M1 deploy_ → `https://huggingface.co/spaces/bintuulugbek/Uzbek-STT`
+> **API docs:** `/docs` on the same URL.
+
+---
+
+## Why this project
+
+Uzbek is an underserved language for speech tech. This project takes verified open Uzbek ASR
+models and wraps them in production-grade engineering: a clean FastAPI service, a swappable
+engine seam, problem+json errors, and a reproducible benchmark with real WER/CER numbers
+measured by us (not quoted from model cards).
+
+## Architecture
+
+```mermaid
+flowchart TD
+    U[User: mic / upload / API call] -->|audio| FE[Gradio UI '/']
+    U -->|POST audio| API[FastAPI '/api/*']
+    FE --> SVC[TranscriptionService]
+    API --> SVC
+    SVC --> SEAM[Engine seam - Protocol]
+    SEAM --> E1[whisper-small-uz  FAST]
+    SEAM --> E2[rubaistt_v2_medium  ACCURATE]
+    API --> DOCS[OpenAPI '/docs']
+    subgraph Offline [Benchmark - offline]
+        BM[harness] --> SEAM
+        BM --> E3[xls-r-uzbek  benchmark-only]
+        BM --> M[(metrics.csv + plots)]
+    end
+    subgraph Deploy [HF Spaces - Docker SDK - FREE]
+        API
+        FE
+        DOCS
+    end
+```
+
+## The $0 stack
+
+| Need | Free tool |
+|---|---|
+| API + demo hosting | Hugging Face Spaces (Docker SDK, free CPU, 16 GB) |
+| Models | Hugging Face Hub (Apache-2.0 Uzbek ASR) |
+| Benchmark data | FLEURS `uz_uz` test split |
+| Code | GitHub |
+
+## Engines
+
+| Role | Model | Deployed |
+|---|---|---|
+| Fast (default) | `BlueRaccoon/whisper-small-uz` | ✅ |
+| Accurate | `islomov/rubaistt_v2_medium` | ✅ |
+| Benchmark baseline | `lucio/xls-r-uzbek-cv8` | offline only |
+
+## API
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/health` | readiness (engines loaded) |
+| `POST /api/transcribe` | transcribe audio → text + word timings |
+| `GET /api/examples` | bundled FLEURS clips |
+| `POST /api/transcribe_example` | transcribe a bundled clip + live WER |
+| `GET /api/benchmark` | latest WER/CER per engine |
+
+Errors follow **RFC 9457** (`application/problem+json`). All times are integer milliseconds.
+
+### Why there's no login
+
+Deliberate: this is a public evaluation demo with no user data to protect. Auth would only
+add friction. Abuse is bounded by per-IP rate limiting + upload-size and duration caps instead.
+
+## Roadmap
+
+- [x] **M1** — deployable skeleton: live `/health` + `/docs` on HF Spaces
+- [ ] **M2** — fast engine wired: real Uzbek transcription via `/api/transcribe`
+- [ ] **M3** — Gradio UI (4 tabs) + one-click FLEURS examples with live WER
+- [ ] **M4** — 3-engine benchmark on FLEURS + error dashboard
+- [ ] **M5** — docs polish
+- [ ] **v2** — long-audio chunking
+
+## Local development
+
+```bash
+pip install -e ".[dev]"
+uvicorn app.main:app --reload --port 7860
+# open http://localhost:7860/docs
+```
+
+## License
+
+Apache-2.0. All deployed models are Apache-2.0. This is original work; it follows common
+FastAPI architectural conventions but contains no third-party application code.

app/__init__.py

@@ -0,0 +1 @@
+"""Uzbek STT service."""

app/core/errors.py

@@ -0,0 +1,168 @@
+"""Structured errors as RFC 9457 ``application/problem+json``.
+
+Domain code raises an ``AppError`` (or a subclass) with a stable ``type`` URI;
+the registered handlers turn it into a problem+json body. Routers stay free of
+ad-hoc ``HTTPException`` shapes, so every error the API emits looks the same.
+
+Two correctness rules (see features/uzbek-stt.md §6):
+1. Every body is serialized through ``jsonable_encoder`` — validation errors carry
+   non-JSON-native objects that a raw ``JSONResponse`` cannot encode.
+2. Per-error extras live under a nested ``params`` envelope, never merged at the
+   top level where they could shadow a reserved member.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, Request, status
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+PROBLEM_CONTENT_TYPE = "application/problem+json"
+_TYPE_PREFIX = "urn:uzbekstt:error"
+_RESERVED = {"type", "title", "status", "detail", "instance"}
+
+
+class AppError(Exception):
+    """A domain error carrying its HTTP status and a stable type URI."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        type_: str,
+        title: str,
+        detail: str | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(detail or title)
+        self.status_code = status_code
+        self.type_ = type_
+        self.title = title
+        self.detail = detail
+        self.params = params or {}
+        self.headers = headers or {}
+
+
+class UnsupportedAudioError(AppError):
+    def __init__(self, *, detail: str) -> None:
+        super().__init__(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            type_=f"{_TYPE_PREFIX}:unsupported-audio",
+            title="Unsupported or unreadable audio",
+            detail=detail,
+        )
+
+
+class PayloadTooLargeError(AppError):
+    def __init__(self, *, size_bytes: int, limit_bytes: int) -> None:
+        super().__init__(
+            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            type_=f"{_TYPE_PREFIX}:payload-too-large",
+            title="Upload exceeds the size cap",
+            detail=f"Upload is {size_bytes} bytes; the limit is {limit_bytes} bytes.",
+            params={"size_bytes": size_bytes, "limit_bytes": limit_bytes},
+        )
+
+
+class AudioTooLongError(AppError):
+    def __init__(self, *, seconds: float, limit: float) -> None:
+        super().__init__(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            type_=f"{_TYPE_PREFIX}:audio-too-long",
+            title="Audio exceeds the duration cap",
+            detail=f"Clip is {seconds:.1f}s; the limit is {limit:.0f}s.",
+            params={"seconds": seconds, "limit": limit},
+        )
+
+
+class RateLimitedError(AppError):
+    def __init__(self, *, retry_after: int) -> None:
+        super().__init__(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            type_=f"{_TYPE_PREFIX}:rate-limited",
+            title="Too many requests",
+            detail="Rate limit exceeded; retry after a short wait.",
+            params={"retry_after": retry_after},
+            headers={"Retry-After": str(retry_after)},
+        )
+
+
+class EngineNotReadyError(AppError):
+    def __init__(self, *, engine: str) -> None:
+        super().__init__(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            type_=f"{_TYPE_PREFIX}:engine-not-ready",
+            title="Engine is still loading",
+            detail=f"Engine '{engine}' is not ready yet; retry shortly.",
+            params={"engine": engine},
+        )
+
+
+def _problem(
+    *,
+    request: Request,
+    status_code: int,
+    type_: str,
+    title: str,
+    detail: str | None,
+    params: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+) -> JSONResponse:
+    body: dict[str, Any] = {
+        "type": type_,
+        "title": title,
+        "status": status_code,
+        "instance": str(request.url.path),
+    }
+    if detail:
+        body["detail"] = detail
+    if params:
+        # Nested envelope — never shadow a reserved member.
+        body["params"] = {k: v for k, v in params.items() if k not in _RESERVED}
+    return JSONResponse(
+        status_code=status_code,
+        content=jsonable_encoder(body),
+        media_type=PROBLEM_CONTENT_TYPE,
+        headers=headers or None,
+    )
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    @app.exception_handler(AppError)
+    async def _app_error(request: Request, exc: AppError) -> JSONResponse:
+        return _problem(
+            request=request,
+            status_code=exc.status_code,
+            type_=exc.type_,
+            title=exc.title,
+            detail=exc.detail,
+            params=exc.params,
+            headers=exc.headers,
+        )
+
+    @app.exception_handler(StarletteHTTPException)
+    async def _http_error(request: Request, exc: StarletteHTTPException) -> JSONResponse:
+        title = exc.detail if isinstance(exc.detail, str) else "HTTP error"
+        return _problem(
+            request=request,
+            status_code=exc.status_code,
+            type_=f"{_TYPE_PREFIX}:http-{exc.status_code}",
+            title=title,
+            detail=None,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def _validation_error(request: Request, exc: RequestValidationError) -> JSONResponse:
+        return _problem(
+            request=request,
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            type_=f"{_TYPE_PREFIX}:validation",
+            title="Validation error",
+            detail="One or more fields did not validate.",
+            params={"errors": exc.errors()},
+        )

app/core/logging.py

@@ -0,0 +1,12 @@
+"""Logging configuration. Called once from the app lifespan."""
+
+from __future__ import annotations
+
+import logging
+
+
+def configure_logging() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)-8s %(name)s — %(message)s",
+    )

app/core/settings.py

@@ -0,0 +1,48 @@
+"""Single-source application configuration.
+
+Every module reads config through ``get_settings()`` — never via ``os.environ``
+directly. Values come from environment variables (or a local ``.env``), so the
+same image behaves differently across dev / Spaces without code changes.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_prefix="", extra="ignore")
+
+    app_name: str = "Uzbek STT"
+    version: str = "0.1.0"
+    environment: str = "production"
+
+    # Public demo, no auth (see features/uzbek-stt.md §7.4); a permissive CORS
+    # policy is intentional here and revisited if an API-key mode is ever added.
+    cors_origins: list[str] = ["*"]
+
+    # HF Spaces (Docker SDK) routes traffic to this port by default.
+    # Keep in lockstep with Dockerfile (--port/EXPOSE) and README `app_port`.
+    port: int = 7860
+
+    # Audio guards (§7.1) — single-source; read by app/audio.py from M2 on.
+    max_upload_bytes: int = 10 * 1024 * 1024  # 10 MB, checked before decode -> 413
+    max_audio_seconds: float = 30.0  # checked after decode -> 400
+
+    # Rate limit (§7.3) — slowapi limit string; read by the limiter from M3 on.
+    rate_limit: str = "30/minute"
+
+    # Engine model IDs (§5) — single-source; only app/engines/ imports the ML libs.
+    fast_model_id: str = "BlueRaccoon/whisper-small-uz"
+    accurate_model_id: str = "islomov/rubaistt_v2_medium"
+
+    @property
+    def is_production(self) -> bool:
+        return self.environment.lower() == "production"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

app/main.py

@@ -0,0 +1,55 @@
+"""FastAPI application entrypoint — ``create_app()`` factory + lifespan."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import RedirectResponse
+
+from app.core.errors import register_exception_handlers
+from app.core.logging import configure_logging
+from app.core.settings import get_settings
+from app.routers import health
+
+
+@asynccontextmanager
+async def _lifespan(_: FastAPI) -> AsyncIterator[None]:
+    configure_logging()
+    # M2: warm the fast engine here, then flip /health readiness once weights load.
+    yield
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    app = FastAPI(
+        title=f"{settings.app_name} API",
+        version=settings.version,
+        description=(
+            "Uzbek speech-to-text service. Errors follow RFC 9457 "
+            "(application/problem+json). No authentication by design — see the README."
+        ),
+        lifespan=_lifespan,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins,
+        allow_methods=["GET", "POST", "OPTIONS"],
+        allow_headers=["*"],
+    )
+
+    register_exception_handlers(app)
+    app.include_router(health.router)
+
+    @app.get("/", include_in_schema=False)
+    async def _root() -> RedirectResponse:
+        # M3 mounts the Gradio UI here; until then, send visitors to the API docs.
+        return RedirectResponse(url="/docs")
+
+    return app
+
+
+app = create_app()

app/routers/health.py

@@ -0,0 +1,18 @@
+"""Health / readiness endpoint."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from app.core.settings import get_settings
+from app.schemas.health import HealthResponse
+
+router = APIRouter(prefix="/api", tags=["health"])
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health() -> HealthResponse:
+    settings = get_settings()
+    # M1 skeleton: no engines loaded yet, so the service is trivially ready.
+    # M2 redefines `ready` as "fast-engine weights present and warmed" (spec §7.2).
+    return HealthResponse(ready=True, engines_loaded=[], version=settings.version)

app/schemas/health.py

@@ -0,0 +1,11 @@
+"""Health endpoint schema (the HTTP-boundary contract)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class HealthResponse(BaseModel):
+    ready: bool
+    engines_loaded: list[str]
+    version: str

features/uzbek-stt.md

@@ -0,0 +1,340 @@
+# Spec: Uzbek Speech-to-Text Service
+
+**Status:** Draft for review · **Author:** Bahor · **Date:** 2026-06-23
+**Type:** Greenfield portfolio project — deployable Uzbek STT service with public API + demo UI + benchmark.
+
+> **Originality note.** This project's *code is written from scratch.* It follows senior structural
+> patterns that are standard FastAPI craft (app factory, Protocol-based provider seam, problem+json
+> errors, single-source settings, layered `core/routers/schemas/services`). Those patterns are
+> industry conventions — not anyone's property. No code is copied from any other repository.
+
+---
+
+## 1. Why this exists (the one-paragraph pitch)
+
+A deployed, evaluable Uzbek speech-to-text **service** — not a notebook, not a model dump. What a
+reviewer opens is a **live URL** with documented API endpoints (`/docs`), a working demo, and an
+honest benchmark. The model is a *component*; the **production engineering is the point.** Built
+under a hard constraint — **$0: no paid server, no paid API** — on an underserved language.
+
+**The 60-second proof:** open the URL → click a preloaded Uzbek example → see a transcript **and a
+real WER** against known ground truth.
+
+---
+
+## 2. Goals / Non-goals
+
+### Goals
+- A **real REST API** (FastAPI) with OpenAPI docs, deployed to a public URL, fully free.
+- A **demo UI** (Gradio, mounted on the same app) anyone can use without setup.
+- An **honest benchmark**: 3 engines on FLEURS uz_uz, WER/CER + error analysis, **re-measured by us**.
+- **Clean, defensible architecture**: a Protocol-based engine seam reused by both API and benchmark;
+  dependency rule respected (services/engines never import FastAPI).
+- Docs that let a reviewer evaluate by reading.
+
+### Non-goals (v1)
+- **No auth / login** — deliberate (§7.4).
+- **No long-audio chunking** — v1 caps at ~30s; long-audio is the **v2 milestone**.
+- **No training** — deploy verified off-the-shelf Uzbek models.
+- **No GPU** — must run on free HF Spaces CPU (16 GB).
+- **No DB / Celery / WebSocket** — the service is **stateless**; we don't need persistence.
+- **No CC-BY-NC models** (MMS excluded on purpose).
+
+---
+
+## 3. Architecture
+
+```mermaid
+flowchart TD
+    U[User: mic / upload / API call] -->|audio| FE[Gradio UI '/']
+    U -->|POST audio| API[FastAPI '/api/*']
+    FE --> SVC
+    API --> SVC[TranscriptionService]
+    SVC --> SEAM[Engine seam - Protocol]
+    SEAM --> E1[whisper-small-uz  FAST]
+    SEAM --> E2[rubaistt_v2_medium  ACCURATE]
+    API --> DOCS[OpenAPI '/docs']
+    subgraph Offline [Benchmark - offline / CI]
+        BM[benchmark harness] --> SEAM
+        BM --> E3[xls-r-uzbek  benchmark-only]
+        BM --> M[(metrics.csv + plots)]
+        M --> RPT[report + error dashboard]
+    end
+    RPT -.published.-> README[README + UI Benchmark tab]
+    subgraph Deploy [HF Spaces - Docker SDK - FREE]
+        API
+        FE
+        DOCS
+    end
+```
+
+**Layering (dependency rule — imports point inward only):**
+`routers → services → engines → models`. The Gradio UI calls the **service layer directly** (not HTTP)
+to avoid a self-call. The benchmark calls the **same engine seam** the API uses — one source of
+inference truth. **No engine/service module imports `fastapi`; no router contains inference logic.**
+
+---
+
+## 4. Repository layout (senior structure, our own code)
+
+```
+uzbek-stt/
+├── app/
+│   ├── main.py              # create_app() factory + lifespan (model warmup)
+│   ├── core/               # cross-cutting, framework-adjacent
+│   │   ├── settings.py     # get_settings() single-source config
+│   │   ├── errors.py       # AppError hierarchy + problem+json handlers
+│   │   ├── logging.py      # configure_logging()
+│   │   └── middleware.py   # request-id + rate limit
+│   ├── routers/            # HTTP endpoints only — no business logic
+│   │   ├── health.py
+│   │   ├── transcription.py
+│   │   └── benchmark.py
+│   ├── schemas/            # Pydantic request/response models (the API contract)
+│   │   ├── transcription.py
+│   │   └── benchmark.py
+│   ├── services/           # business logic — NEVER imports fastapi
+│   │   ├── transcription.py  # TranscriptionService
+│   │   └── examples.py       # bundled FLEURS example loader + WER
+│   ├── engines/            # the provider seam — NEVER imports fastapi
+│   │   ├── base.py         # Engine Protocol + frozen dataclass results
+│   │   ├── whisper.py      # WhisperEngine (covers fast + accurate via model id)
+│   │   └── factory.py      # select engine by name; single place models load
+│   ├── audio.py            # decode/resample to 16k mono, duration/size guards
+│   └── ui/
+│       └── gradio_app.py   # 4-tab Gradio UI, mounted at '/'
+├── benchmark/
+│   ├── run_benchmark.py    # WER/CER on FLEURS uz_uz across 3 engines
+│   └── error_analysis.py   # confused chars, WER-vs-length, latency plots
+├── data/examples/          # ~5 bundled FLEURS clips + references.json
+├── tests/                  # pytest — engine seam, audio guards, contracts
+├── Dockerfile              # the deployment artifact (HF Spaces Docker SDK)
+├── pyproject.toml          # deps, ruff, mypy config
+├── README.md               # architecture diagram + metrics + "why"
+└── INVENTORY.md            # spec-coverage map
+```
+
+*Differences from `studio-qiroat` (by design):* no `models/` (no DB), no `workers/` (no Celery),
+no `ws/` (no realtime), no `alembic/` (no migrations). We're stateless — simpler on purpose.
+
+---
+
+## 5. The engine seam (the architectural keystone)
+
+A `Protocol` so any model is one swappable class — API and benchmark both depend on the abstraction,
+never on a concrete model. **ML libraries (`transformers`, `torch`) are imported only inside
+`app/engines/`** — the dependency-discipline rule, our analogue of studio-qiroat's "never import the
+SDK outside its service module."
+
+```python
+# app/engines/base.py  (shape, written by us)
+# UNIT CONVENTION: all times are integer MILLISECONDS, everywhere — at this seam
+# AND in the public API JSON (§6). No seconds anywhere, no per-field ambiguity.
+@dataclass(frozen=True, slots=True)
+class RecognizedWord:
+    word: str
+    start_ms: int
+    end_ms: int
+
+@dataclass(frozen=True, slots=True)
+class Transcript:
+    text: str
+    words: list[RecognizedWord]   # MAY be empty — see "Word timings" note below
+    engine: str           # e.g. "fast:whisper-small-uz"
+    audio_ms: int         # decoded audio duration; the engine owns this value
+    inference_ms: int     # wall-clock spent inside transcribe()
+
+class Engine(Protocol):
+    name: str
+    def transcribe(self, audio: AudioInput) -> Transcript: ...
+```
+
+**Word timings.** `Transcript.words` **may be empty** and that is a valid result. The two
+deployed Whisper engines (fast + accurate) populate it via the HF pipeline's
+`return_timestamps="word"`. The benchmark-only `xls-r` (CTC) does **not** emit word timings —
+it returns `words=[]`, which is fine because the benchmark scores text (WER/CER), not timings.
+Consumers must treat `words` as optional, never assume it is non-empty.
+
+| Role | Model ID | Params | Deployed? | Notes |
+|---|---|---|---|---|
+| **Fast** (UI default) | `BlueRaccoon/whisper-small-uz` | 244M | ✅ live | publishes WER on named FLEURS+CV sets; snappy on CPU |
+| **Accurate** | `islomov/rubaistt_v2_medium` | 769M | ✅ live | most-adopted Uzbek model (10.2k dl/mo); slow on CPU (10–30s) |
+| **Baseline** (other arch) | `lucio/xls-r-uzbek-cv8` | 300M | ❌ benchmark-only | wav2vec2/CTC; KenLM dep too heavy for live image |
+
+Card WER numbers are measured on *different* splits and are **not comparable** — the benchmark
+re-measures all three on FLEURS uz_uz. That re-measurement *is* the analysis.
+
+---
+
+## 6. API contracts
+
+> Errors follow **RFC 9457 `application/problem+json`** via an `AppError` hierarchy (our own classes).
+> Every error has a stable `type`, `title`, `status`, `detail`. Two correctness rules the
+> implementation MUST follow (both flagged by review of the started `errors.py`):
+> 1. The body is always serialized through `jsonable_encoder(...)` before `JSONResponse` —
+>    validation errors carry non-JSON-native objects and a raw `JSONResponse` crashes the handler.
+> 2. Per-error extra data goes under a nested `"params": {...}` envelope — it must **never**
+>    be merged at top level where it could shadow a reserved member (`type`/`title`/`status`/`detail`/`instance`).
+
+### `POST /api/transcribe`
+- **Request:** multipart `audio` (wav/mp3/m4a/ogg) + optional `engine` ∈ {`fast`,`accurate`} (default `fast`).
+- **200** (all times integer ms; `words` may be `[]`):
+  ```json
+  { "text": "...", "engine": "fast", "audio_ms": 7200, "inference_ms": 1840,
+    "words": [{ "word": "salom", "start_ms": 120, "end_ms": 540 }] }
+  ```
+- **Error inventory** (each is an `AppError` subclass → problem+json):
+
+  | Status | Type slug | When |
+  |---|---|---|
+  | `413` | `payload-too-large` | upload exceeds the **byte-size** cap (§7.1) |
+  | `422` | `unsupported-audio` | unreadable / empty / unsupported format |
+  | `400` | `audio-too-long` | decoded **duration** exceeds the cap (§7.1) |
+  | `429` | `rate-limited` | per-IP rate limit hit (§7.3); includes `Retry-After` |
+  | `503` | `engine-not-ready` | requested engine's weights not yet loaded (§7.2) |
+
+  Size→`413` and duration→`400` are **distinct** and must not be conflated (§7.1 matches this table).
+
+### `GET /api/examples`
+- Bundled FLEURS clips: `[{ id, audio_url, reference }]`.
+
+### `POST /api/transcribe_example`  (`id`, `engine`)
+- Transcribes a bundled example → transcript **+ per-clip WER/CER vs its reference** (powers one-click demo).
+
+### `GET /api/benchmark`
+- Latest benchmark as JSON: per-engine WER/CER on FLEURS + metadata (date, n, set).
+
+### `GET /api/health`
+- `{ "ready": true, "engines_loaded": ["fast"], "version": "..." }` — `ready` is `true` **only after**
+  the default engine warms up (honest HF Spaces cold-start handling).
+
+---
+
+## 7. Cross-cutting decisions
+
+### 7.1 Audio handling (`app/audio.py`)
+- **Decode path is the `ffmpeg` binary** (installed as a system package in the Dockerfile — see §10),
+  wrapped from Python, resampling to **16 kHz mono** (model requirement). `librosa`/`soundfile` alone
+  cannot reliably decode `m4a`/`ogg`; the ffmpeg binary is a hard, non-pip deploy dependency.
+- **Two distinct caps, two distinct errors:**
+  - byte-size cap (`max_upload_bytes`, default ~10 MB) → **`413`** `payload-too-large`, checked *before* decode.
+  - duration cap (`max_audio_seconds`, default **30s**) → **`400`** `audio-too-long`, checked *after* decode.
+- Word timings come from the Whisper pipeline (`return_timestamps="word"`) for the deployed engines;
+  the contract allows `words=[]` (§5 "Word timings").
+
+### 7.2 Model loading / warmup (`lifespan`)
+- **Fast engine weights are baked into the Docker image at build time** (§10) → deterministic,
+  offline-safe cold-start with no first-request download penalty.
+- **Accurate engine is lazy**: downloaded from HF Hub on first use into the HF cache dir, then reused
+  for the life of the running Space (re-downloaded only after a rebuild). The **first** accurate call
+  after a cold-start is therefore slow — documented, and surfaced in the UI.
+- `/health.ready` means "**fast engine weights present and warmed**" — not merely "process up." It must
+  account for "weights still downloading," so a cold Space never 500s mid-load.
+
+### 7.3 Rate limiting & abuse (load-bearing — it is the whole no-auth safety argument)
+- **Library:** `slowapi` (Starlette-native limiter).
+- **Client identity:** real caller IP from the **first hop of `X-Forwarded-For`** (HF Spaces sits behind
+  a proxy; using the socket peer would lump every caller into one bucket). Fall back to the socket peer
+  if the header is absent.
+- **Limit:** `rate_limit` (default **30 requests/minute/IP**) on `POST /api/transcribe` and `/api/transcribe_example`.
+- **Store:** in-process / in-memory. It resets on cold-start and is per-worker — **acceptable for a
+  single-worker demo Space; stated explicitly, not hidden.**
+- **On limit:** `429` `rate-limited` problem+json with a `Retry-After` header.
+
+### 7.4 Why no auth (documented, not forgotten)
+- Auth is friction that suppresses evaluation; no user data to protect; Space is public anyway.
+  Abuse handled by §7.3. README states this. A future API-key mode is a noted non-v1 extension.
+
+### 7.5 Loud failures
+- App **refuses to start** if a *deployed* engine fails to load (fail fast). Benchmark-only engine
+  failures degrade the report, not the service.
+
+### 7.6 Type & quality discipline (the senior bar)
+- Full type hints; `Protocol` for seams; frozen `@dataclass(slots=True)` for value objects;
+  Pydantic v2 at the HTTP boundary. No `# type: ignore` without a reason comment.
+- `ruff format && ruff check` + `mypy app` clean before commit. Tests alongside non-trivial logic.
+- **All tunables live on `Settings` (single-source), never hardcoded in modules:**
+  `max_upload_bytes`, `max_audio_seconds`, `rate_limit`, plus the engine model IDs. `app/audio.py`
+  and the limiter read them from `get_settings()`.
+
+---
+
+## 8. Benchmark & error dashboard
+
+- **Set:** `google/fleurs`, config `uz_uz`, **test** split (~350 clips). Secondary: Common Voice 17 test.
+- **Metrics:** WER + CER per engine (jiwer); normalization (lowercase, punctuation strip) documented.
+- **One normalizer, shared:** the Examples tab (§9) and the benchmark MUST call the *same* normalization
+  function before scoring — bundled example references are stored raw and normalized at eval time, so a
+  single source of truth prevents the demo WER and the benchmark WER from diverging.
+- **Error dashboard (the "analysis" axis):** most-confused characters · WER vs audio length ·
+  per-engine CPU latency (the story behind the Fast/Accurate selector).
+- **Outputs:** `metrics.csv`, plots, `report.md` → README **and** UI Benchmark tab.
+- **Honesty rule:** publish n, set, normalization, date. No card-number quoting, no cherry-picking.
+
+---
+
+## 9. Frontend (Gradio, 4 tabs, mounted at `/`)
+
+1. **Transcribe** — mic/upload + Fast/Accurate selector → transcript, word timestamps, latency.
+2. **Examples** — preloaded FLEURS clips → prediction vs reference + per-clip WER (the 60-second wow).
+3. **Benchmark** — metrics table + plots + error dashboard.
+4. **About** — architecture diagram, GitHub link, `/docs` link, "$0 stack", "why no auth".
+
+---
+
+## 10. Deployment
+
+- **Target:** Hugging Face Spaces, **Docker SDK** (arbitrary Dockerfile, free CPU, 16 GB, public URL, no card).
+- **One deployment** serves `/` (UI), `/api/*` (REST), `/docs` (OpenAPI).
+- **Dockerfile must `apt-get install ffmpeg`** (the §7.1 decode dependency) and run as the non-root
+  `user` (UID 1000) HF Spaces expects, with `HOME`/HF cache pointed at a writable dir.
+- **Model weights — explicit policy:** the **fast** engine is downloaded **at image-build time** and
+  baked in (deterministic cold-start). The **accurate** engine is **not** baked (keeps the image lean);
+  it lazy-downloads on first use into the HF cache (§7.2). README carries the HF Spaces YAML header.
+
+---
+
+## 11. Acceptance criteria (v1 done)
+
+- [ ] `GET /api/health` → `ready:true` on the live Space.
+- [ ] `POST /api/transcribe` returns correct-shape JSON for a real Uzbek clip, both engines.
+- [ ] Examples tab: one click → transcript + WER against bundled reference.
+- [ ] `/docs` renders all endpoints with schemas on the live URL.
+- [ ] `python -m benchmark.run_benchmark` reproduces `metrics.csv` (WER/CER, 3 engines, FLEURS uz_uz).
+- [ ] Error dashboard renders the 3 plots.
+- [ ] README: diagram + metrics table + "why this design" + "$0 stack" + "why no auth".
+- [ ] Caps enforced: oversized/overlong/empty audio → documented problem+json codes.
+- [ ] `ruff`, `mypy`, `pytest` all green.
+- [ ] Repo public on GitHub; live URL linked from README.
+
+---
+
+## 12. Milestones (deploy-first)
+
+- **M1 — Skeleton, deployed empty:** `create_app()` + `/health` + Dockerfile live on HF Spaces. *URL before the model.*
+- **M2 — One engine live:** engine seam + `/api/transcribe` returns real Uzbek text (fast).
+- **M3 — UI + examples:** Gradio 4-tab, Fast/Accurate selector, one-click FLEURS examples + WER.
+- **M4 — Benchmark + dashboard:** 3-engine WER/CER on FLEURS, error plots, wired to README + UI.
+- **M5 — Docs polish:** diagram, metrics table, INVENTORY, "why" sections.
+- **v2 (post-ship) — long-audio chunking** as a visible roadmap item.
+
+---
+
+## 13. Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| HF Space cold-start / sleeps | `/health` gates readiness; warm fast engine at startup; document first-call latency |
+| `rubaistt` medium slow on CPU | it's the opt-in "Accurate" engine; latency shown as a feature, not hidden |
+| FLEURS WER worse than card numbers | expected (domain shift); honesty is the point — publish our own measurement |
+| Docker image too big / build timeout | pin deps, cache models, keep xls-r/KenLM out of the live image |
+| Scope creep (chunking, training) | explicitly v2/out-of-scope (§2) |
+
+---
+
+## 14. Open questions (need a human decision)
+
+1. **Repo / project name** (working name `uzbek-stt`) — memorable brand vs descriptive?
+2. **Hugging Face account** for the Space + model cache — do you have one? (free, needed at M1.)
+3. **GitHub repo** under `bintuulugbek` — confirm name and public-from-day-one.
+4. Bundle the ~5 FLEURS example clips **in the repo** (a few MB) or fetch at runtime? (Lean: bundle.)

pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uzbek-stt"
+version = "0.1.0"
+description = "Deployable Uzbek speech-to-text service: FastAPI API + Gradio demo + honest 3-engine benchmark."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.34",
+    "pydantic-settings>=2.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pytest>=8.3",
+    "httpx>=0.27",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

tests/test_health.py

@@ -0,0 +1,30 @@
+"""M1 contract tests: the service boots and the health/docs surface is correct."""
+
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+client = TestClient(app)
+
+
+def test_health_is_ready() -> None:
+    resp = client.get("/api/health")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["ready"] is True
+    assert body["engines_loaded"] == []
+    assert isinstance(body["version"], str)
+
+
+def test_root_redirects_to_docs() -> None:
+    resp = client.get("/", follow_redirects=False)
+    assert resp.status_code in (307, 308)
+    assert resp.headers["location"] == "/docs"
+
+
+def test_openapi_schema_is_served() -> None:
+    resp = client.get("/openapi.json")
+    assert resp.status_code == 200
+    assert resp.json()["info"]["title"] == "Uzbek STT API"