docs/deploy-huggingface.md

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

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.