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):

   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:

     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.