Bundle the whisper base model + one-shot standalone provisioning

- models/hf-cache/ vendors Systran/faster-whisper-base (142MB, gitignored);
  engine spawn pins HF_HUB_CACHE there, so transcription works with a cold
  ~/.cache and fully offline
- verified: HOME=/tmp/fakehome HF_HUB_OFFLINE=1 model loads and transcribes
  via the bundled cache alone
- setup-standalone.sh: idempotent fresh-clone provisioning (local venv,
  model copy-or-download, engine boot smoke on :8123) — runs green
- backend/README rewritten for the desktop bundled-lite reality (was
  pointing at a nonexistent root README/docs and a Postgres quickstart)

Kotlin suite still green (gradlew test, 0 failures)
This commit is contained in:
avi 2026-09-14 21:05:41 -05:00
commit c25d3ab150
4 changed files with 77 additions and 9 deletions

View file

@ -1,16 +1,19 @@
# S.H.O.N.A.R. backend
# S.H.O.N.A.R. backend (desktop bundled-lite)
FastAPI + PostgreSQL backend for the S.H.O.N.A.R. Android app.
FastAPI engine for SHONAR Desktop, running standalone on this machine:
SQLite + in-process queue, self-migrating on boot. No Postgres/Redis/Docker.
See the repository root [README](../README.md) and `docs/` for full documentation.
## Quick start (development)
## Setup (this repo is self-contained)
```bash
cd backend
uv venv .venv && uv pip install -e ".[dev]"
cp ../.env.example .env # then edit SHONAR_SECRET_KEY etc.
uvicorn shonar.main:app --reload --port 8000
uv venv .venv && uv pip install -p .venv/bin/python -e ".[dev,faster-whisper]"
```
Tests: `pytest` · Lint: `ruff check .` · Migrations: `alembic upgrade head`
The app (DesktopState) creates this venv's env vars itself, including
`HF_HUB_CACHE=models/hf-cache` — the `base` faster-whisper model is vendored
under `models/hf-cache/` (gitignored; copy from any HF cache to reprovision).
Tests: `.venv/bin/python -m pytest` (SQLite by default; point
`SHONAR_TEST_DATABASE_URL` at Postgres to test that path) · Lint: `ruff check .`
· Migrations: `alembic upgrade head`