deploy/README.md

# Deploy SearchAudio (online, archive.org audio) to Hugging Face Spaces

This deploys the slim, **text-only** search service. Audio streams from archive.org, so the
Space hosts **no audio** and runs **no ASR** — only bge-m3 (CPU) for query embedding.

## Prerequisites
- The offline index is built (you've run `bulk_ingest.py` for the files you want searchable).
- A free Hugging Face account.

## One-time setup

1. **Export the index** (locally):
   ```bash
   python scripts/export_index.py        # -> deploy/index/lancedb
   ```

2. **Create a Space** → https://huggingface.co/new-space → SDK: **Docker** → Hardware:
   **CPU basic (free)**.

3. The Space repo's root `README.md` must begin with this front matter (tells Spaces the
   port and SDK):
   ```yaml
   ---
   title: SearchAudio
   sdk: docker
   app_port: 7860
   ---
   ```

4. **Add these to the Space repo** (at the repo root):
   - `app/`  (the application code)
   - `config.yaml`
   - `requirements-online.txt`
   - `Dockerfile`  — copy `deploy/Dockerfile` to the repo root as `Dockerfile`
   - `data/index/lancedb/`  — the exported index, tracked with **Git LFS**:
     ```bash
     git lfs install
     git lfs track "data/index/lancedb/**"
     git add .gitattributes data/index/lancedb
     ```

5. **Push.** The Space builds the Docker image and serves at
   `https://<user>-<space>.hf.space`. First build downloads/bakes bge-m3 (a few minutes).

## Verifying after deploy
- Open the Space URL, run an English query, click a result → it should play from the
  timestamp, streaming from `archive.org`.
- `GET /api/config` should return `{"mode":"archive","audio_query":false}` (mic/upload hidden).

## Updating the searchable content later
Re-run ingestion locally → `python scripts/export_index.py` → commit the new
`data/index/lancedb` (LFS) → push. The Space rebuilds automatically.

## Notes & upgrade path
- **Cold starts:** free Spaces sleep when idle (~30–60 s to wake). For always-on with a
  custom domain, use a ~$5–7/mo instance (Render/Fly/Railway); on low-RAM tiers switch to an
  int8 bge-m3-ONNX (see the design spec `docs/superpowers/specs/2026-07-01-online-deployment-design.md`).
- **Keep the archive.org item public** — playback depends on it.
- The audio-query (mic/upload) feature is intentionally disabled online; it remains available
  in the local build.