# Deploying the demo to a Hugging Face Space

The repository is a ready Docker Space: the `Dockerfile` starts the server on port 7860. A Space reads its configuration from a YAML block at the top of its `README.md`; that block lives in `space/README.md` (the Space card), and the deploy step puts it in place of the GitHub README, which stays a normal project README.

**Plan needed.** Since mid-2026, Hugging Face requires a paid plan to create Docker (and Gradio) Spaces: PRO ($9 a month) for a personal account, Team ($20 per user a month) for an organisation. Static Spaces stay free. The hardware itself (CPU basic, 2 vCPU, 16 GB) has no hourly cost. Check [huggingface.co/pricing](https://huggingface.co/pricing) for current prices.

This project hosts the Space on the lead's personal Hugging Face account (`ignatius/curatorbot`; the GitHub account is `IgnatiusEzeani`) with PRO, while the code stays in the `SpaceTimeNarratives` GitHub organisation. To move it to an organisation later, take a Team plan, create the Space there and change the `HF_SPACE` variable.

## One-time setup

1. **Subscribe to PRO** on the personal Hugging Face account (Settings > Billing, or huggingface.co/pro).
2. **Create the Space.** New Space: owner `ignatius`, name `curatorbot`, SDK **Docker**, blank template, hardware **CPU basic**, visibility **Private**.
3. **Add secrets** (Space > Settings > Variables and secrets):
   - `OPENROUTER_API_KEY` (secret). By default the demo uses Claude Sonnet through OpenRouter, falling back to an OpenAI model if Claude fails. To use another provider, see `docs/model-providers.md`
   - `CURATORBOT_DEMO_PASSCODE` (secret): protects your API credit on a public or shared Space
   - `CURATORBOT_SITE_PASSCODE` (secret): locks the whole demo behind a sign-in page (see Privacy settings)
   - for real interviews: secret `HF_TOKEN` (read access to the private dataset) and variable `CURATORBOT_DATA_REPO=ignatius/curatorbot-data` (see `docs/real-data-runbook.md`)
   - optional variables: `CURATORBOT_LLM_MODEL`, `CURATORBOT_ENABLE_ASR=1` for short audio clips (slow on CPU basic), `CURATORBOT_MAX_CHARS`
4. **Connect GitHub.** Create a Hugging Face access token with **write** permission. In the GitHub repo (Settings > Secrets and variables > Actions) add secret `HF_TOKEN` (that token) and variable `HF_SPACE=ignatius/curatorbot`. The `deploy to Hugging Face Space` workflow then pushes `main` to the Space after tests pass. Run it once by hand from the Actions tab.

To deploy without GitHub Actions:

```bash
git remote add space https://huggingface.co/spaces/ignatius/curatorbot
git switch -c space-deploy && cp space/README.md README.md && git commit -qam "Space card"
git push --force space space-deploy:main
git switch main && git branch -D space-deploy
```

## Privacy settings

- A private Space on a personal account is visible only to you. Individual people cannot be added to it.
- **To share with a team before going public:** add the secret `CURATORBOT_SITE_PASSCODE`, wait for the restart, check that `https://ignatius-curatorbot.hf.space` asks for the passcode, then set the Space to **Public** (Settings > Change Space visibility). Send the team the direct link `https://ignatius-curatorbot.hf.space` and the passcode separately. Every page and API call then needs the passcode, including the interviews loaded from the private dataset; the dataset itself stays private, and the Space's Files tab shows only code.
- Sign-ins last 14 days. Changing `CURATORBOT_SITE_PASSCODE` signs everyone out, so change it after each round of demos. Scripts can send the header `X-Site-Passcode` instead of signing in.
- Share the direct `hf.space` link rather than the huggingface.co Space page: some browsers block the sign-in cookie inside that page's frame.
- For named access instead of a shared passcode, move the Space to an organisation the reviewers belong to (Team plan), or add Hugging Face sign-in with a list of allowed users.
- Never deploy briefs for interviews whose release terms you have not confirmed.
- Live analysis sends pasted text to the model provider under your API account. The page says so to demo users.

## Checking a deployment

- `https://<space-url>/api/health` should report `"live": true` and the model name.
- The interview picker should list `DEMO-0001` and any released interviews you added.
- Run one live analysis with the synthetic transcript ("Load the synthetic transcript", then Analyse).

## Costs

PRO is the fixed cost. CPU basic hardware is free and sleeps when unused. Each live analysis of a 25-turn transcript makes one model call; check your provider's current prices. GPU hardware is only needed for whole-interview transcription, which is better done offline (`notebooks/prepare_on_colab.ipynb`).

## Free fallback

If PRO is not available, a free **static** Space can show the precomputed briefs without live analysis (needs a small static-export change), or the same Docker image can run on Google Cloud Run within its free monthly allowance.