openspec/changes/hf-spaces-deployment/proposal.md

Why

G.U.I.D.E. runs locally today with no public access. Deploying to Hugging Face Spaces makes the academic demo accessible to evaluators without requiring a local setup, while keeping the existing two-server architecture (FastAPI + Gradio) intact.

What Changes

• New scripts/upload_models_to_hub.py — uploads only inference-needed model files to HF Model Hub, filtering out checkpoint-* training artifacts
• New Dockerfile — HF Spaces Dockerfile Space entry point; downloads weights from Hub at build time, starts both servers with --no-train
• Updated README.md — deployment instructions and HF Spaces architecture note

Capabilities

New Capabilities

• hf-spaces-deployment: Containerised deployment to Hugging Face Spaces using a Dockerfile Space; FastAPI on :8000 (internal) and Gradio on :7860 (public-facing)
• model-hub-upload: One-time script to push inference weights for domain_classifier, evidence_ner, and next_action models to HF Model Hub, filtering training-only artifacts

Modified Capabilities

Non-goals

• No changes to predict.py files, start.py, or ui/app.py
• No single-process refactor of the two-server design
• No CI/CD pipeline for automated re-deployment
• No user-facing API key input in the UI (key is a HF Space Secret)

Impact

• New files: Dockerfile, scripts/upload_models_to_hub.py
• Modified files: README.md
• New dependency at build time: huggingface_hub CLI (already in requirements via huggingface_hub transitive dep from transformers)
• ANTHROPIC_API_KEY must be set as an HF Spaces Secret before the Space goes live