Add HF Spaces deployment openspec change

Documents the model-hub upload script, Dockerfile build flow, and
README deployment section (code already committed prior).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

openspec/changes/hf-spaces-deployment/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-22

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

@@ -0,0 +1,72 @@
+## Context
+
+G.U.I.D.E. currently runs as two processes launched by `start.py`: FastAPI on `:8000` (model inference + agent API) and Gradio on `:7860` (UI). The Gradio frontend calls `http://localhost:8000` — an internal URL that works within any single container.
+
+HF Spaces Dockerfile Spaces expose exactly one public port (`:7860`) but allow arbitrary internal processes. This maps cleanly onto the existing architecture without modification.
+
+Three trained model artifacts exist locally:
+- `models/domain_classifier/` — DistilBERT fine-tuned on CFPB data (~256MB safetensors)
+- `models/evidence_ner/` — DistilBERT NER, root-level files only (~270MB safetensors); `checkpoint-*` subdirs are training artifacts (~3.2GB total, not needed at inference)
+- `models/next_action/model.pt` — MLP state dict (~24KB)
+
+## Goals / Non-Goals
+
+**Goals:**
+- Public HF Spaces demo accessible via browser with no local setup
+- Full pipeline (DomainClassifier + EvidenceNER + NextActionPredictor) using trained weights
+- One-time upload script for model weights with checkpoint filtering
+- Two-server design preserved exactly as-is
+
+**Non-Goals:**
+- Modifying any `predict.py`, `start.py`, or `ui/app.py` files
+- Single-process refactor
+- CI/CD automation
+- User-supplied API key input in the UI
+
+## Decisions
+
+### Decision 1: Dockerfile Space over SDK Space
+
+HF SDK Spaces require `app.py` as the entrypoint and expect a single Gradio `demo.launch()` call. Wiring FastAPI as a background thread from inside `app.py` is fragile and breaks the existing process model.
+
+Dockerfile Spaces let us use `CMD ["python", "start.py", "--no-train"]` exactly as-is.
+
+**Alternatives considered:** SDK Space with threading — rejected because it requires changes to `ui/app.py` and creates a coupled process model that's harder to debug.
+
+### Decision 2: Download weights at Docker build time, not runtime
+
+Cold-start download (~800MB) would block HF Spaces visitors for 2-3 minutes. Baking weights into the image layer via `RUN huggingface-cli download` at build time means the container starts in seconds.
+
+**Alternatives considered:** Download at container startup in `start.py` — rejected due to cold-start UX on free-tier HF Spaces.
+
+### Decision 3: One HF Model Hub repo, three subdirectories
+
+`your-username/guide-models` with `domain_classifier/`, `evidence_ner/`, `next_action/` subdirs. A single `huggingface-cli download` in the Dockerfile fetches everything into `models/` — matching the existing local path structure that all `predict.py` files already expect.
+
+**Alternatives considered:** Three separate HF repos — cleaner HF Hub browsing but requires three download commands and complicates the upload script.
+
+### Decision 4: Filter checkpoint-* at upload time via script
+
+`models/evidence_ner/checkpoint-*/` directories are intermediate training snapshots (~3.2GB). Only the root-level `models/evidence_ner/` files are needed for inference. The upload script explicitly skips any path component matching `checkpoint-*` and `.DS_Store`.
+
+## Risks / Trade-offs
+
+- **[Risk] HF Spaces free-tier memory limit (~16GB RAM)** → Mitigation: spaCy `en_core_web_lg` (~750MB) + two DistilBERT models (~540MB each) + ViT + Tesseract fits within 16GB. Monitor via HF Spaces logs on first deploy.
+- **[Risk] Build time timeout on HF Spaces** → Mitigation: `spacy download` + Hub download is ~1.5GB at build time; HF Spaces build timeout is 30 min, well within budget.
+- **[Risk] ANTHROPIC_API_KEY exposure** → Mitigation: Key is set only via HF Spaces Secrets UI, never in Dockerfile or committed code. `ENV ANTHROPIC_API_KEY=""` in Dockerfile is a placeholder only.
+- **[Risk] HF Hub model repo must be public for free-tier download** → Mitigation: Models contain no PII (trained on synthetic data + CFPB public dataset); public repo is acceptable for academic use.
+
+## Migration Plan
+
+1. Run `scripts/upload_models_to_hub.py` locally (one-time, requires `huggingface-cli login`)
+2. Create HF Space (Dockerfile type) via HF UI or CLI
+3. Push repo code to HF Space git remote
+4. Set `ANTHROPIC_API_KEY` in HF Space Secrets UI
+5. HF builds the Docker image — downloads weights, installs deps
+6. Space goes live at `https://huggingface.co/spaces/<username>/guide`
+
+Rollback: Delete the HF Space. No changes to the local codebase.
+
+## Open Questions
+
+- HF username to use for the model repo (affects the `huggingface-cli download` line in Dockerfile) — parameterise via a build ARG or hardcode after account is confirmed

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

@@ -0,0 +1,32 @@
+## 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

openspec/changes/hf-spaces-deployment/specs/hf-spaces-deployment/spec.md

@@ -0,0 +1,50 @@
+## ADDED Requirements
+
+### Requirement: Dockerfile Space entrypoint
+The project SHALL include a `Dockerfile` at the repo root that builds a runnable HF Spaces image. The Dockerfile MUST install all system and Python dependencies, download spaCy model and HF Hub weights at build time, expose port 7860, and start both servers via `python start.py --no-train`.
+
+#### Scenario: Successful Docker build
+- **WHEN** `docker build` is run on the repo root
+- **THEN** the image builds without error, all dependencies are installed, and model weights are present at `models/`
+
+#### Scenario: Container starts both servers
+- **WHEN** the built container is started
+- **THEN** FastAPI is accessible at `localhost:8000` and Gradio at `localhost:7860` within 90 seconds
+
+#### Scenario: ANTHROPIC_API_KEY injected at runtime
+- **WHEN** the container starts with `ANTHROPIC_API_KEY` set as an environment variable (e.g., via HF Spaces Secrets)
+- **THEN** the agent uses the injected key and no key is baked into the image
+
+#### Scenario: No training at container startup
+- **WHEN** the container starts
+- **THEN** `start.py` runs with `--no-train` and no model training is attempted
+
+### Requirement: Tesseract available in container
+The Dockerfile SHALL install `tesseract-ocr` via `apt-get` so document OCR functions correctly.
+
+#### Scenario: OCR on uploaded document
+- **WHEN** a user uploads an image or PDF in the Documents tab
+- **THEN** Tesseract processes the file without a missing-binary error
+
+---
+
+## ADDED Requirements
+
+### Requirement: Model weights upload script
+The project SHALL include `scripts/upload_models_to_hub.py` that uploads inference-only model files to a specified HF Model Hub repository. The script MUST skip `checkpoint-*` subdirectories and `.DS_Store` files.
+
+#### Scenario: Upload filters checkpoint directories
+- **WHEN** the upload script is run with `models/evidence_ner/` present (including `checkpoint-225/`, `checkpoint-450/`, etc.)
+- **THEN** only root-level files (`config.json`, `model.safetensors`, `tokenizer*.json`, `training_args.bin`) are uploaded; no `checkpoint-*` files are uploaded
+
+#### Scenario: Upload three model subdirs
+- **WHEN** the upload script completes successfully
+- **THEN** HF Model Hub repo contains `domain_classifier/`, `evidence_ner/`, and `next_action/` subdirectories with correct files
+
+#### Scenario: Missing local model directory
+- **WHEN** the upload script is run but a model directory does not exist locally
+- **THEN** the script logs a clear warning for that model and continues uploading the others
+
+#### Scenario: Unauthenticated run
+- **WHEN** the upload script is run without a valid HF token (`huggingface-cli login` not done)
+- **THEN** the script exits with a clear authentication error message before attempting any upload

openspec/changes/hf-spaces-deployment/specs/model-hub-upload/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Inference-only file filtering
+The upload script SHALL determine which files are inference-needed by excluding any path under a `checkpoint-*` directory and any `.DS_Store` file. It MUST upload: `config.json`, `model.safetensors`, `tokenizer_config.json`, `tokenizer.json`, `training_args.bin` for HuggingFace-format models; and `model.pt` for the next_action MLP.
+
+#### Scenario: Checkpoint dirs excluded
+- **WHEN** `models/evidence_ner/` contains both root-level files and `checkpoint-225/`, `checkpoint-450/`, `checkpoint-675/`, `checkpoint-900/` subdirs
+- **THEN** the script uploads only files directly under `models/evidence_ner/` (not inside any `checkpoint-*` subdir)
+
+#### Scenario: DS_Store excluded
+- **WHEN** any `models/` directory contains a `.DS_Store` file
+- **THEN** that file is not uploaded
+
+### Requirement: HF repo target is configurable
+The upload script SHALL accept the HF Hub repo ID (e.g., `username/guide-models`) as a CLI argument or environment variable so it can be used with any HF account.
+
+#### Scenario: Repo ID via CLI argument
+- **WHEN** the script is run as `python scripts/upload_models_to_hub.py --repo-id myuser/guide-models`
+- **THEN** files are uploaded to `myuser/guide-models` on HF Hub
+
+#### Scenario: Missing repo ID
+- **WHEN** the script is run without `--repo-id`
+- **THEN** the script prints usage instructions and exits with a non-zero code

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

@@ -0,0 +1,15 @@
+## 1. Model Upload Script
+
+- [x] 1.1 Create `scripts/upload_models_to_hub.py` with `parse_args()` function that accepts `--repo-id` CLI argument and validates it is provided (exits with usage message if missing)
+- [x] 1.2 Implement `filter_inference_files(model_dir: Path) -> list[Path]` that returns only root-level files (skipping any path under a `checkpoint-*` subdir and any `.DS_Store` file)
+- [x] 1.3 Implement `upload_models(repo_id: str) -> None` that iterates over `domain_classifier/`, `evidence_ner/`, and `next_action/` under `models/`, calls `filter_inference_files()` for each, and uploads via `huggingface_hub.upload_file()` — logging a warning and continuing if a model directory does not exist locally
+
+## 2. Dockerfile
+
+- [x] 2.1 Create `Dockerfile` at repo root: base `python:3.11-slim`, install `tesseract-ocr` and `git` via `apt-get`, copy `requirements.txt` and run `pip install`
+- [x] 2.2 Add `RUN python -m spacy download en_core_web_lg` layer after pip install
+- [x] 2.3 Add `ARG HF_MODEL_REPO` and `RUN huggingface-cli download $HF_MODEL_REPO --local-dir models` layer to pull weights at build time; add `COPY . /app`, `WORKDIR /app`, `EXPOSE 7860`, `ENV ANTHROPIC_API_KEY=""`, and `CMD ["python", "start.py", "--no-train"]`
+
+## 3. README Update
+
+- [x] 3.1 Add a "Deploying to HF Spaces" section to `README.md` documenting: (a) upload script usage with `--repo-id`, (b) Dockerfile build ARG `HF_MODEL_REPO`, (c) setting `ANTHROPIC_API_KEY` in HF Spaces Secrets UI, and (d) the two-server port layout (FastAPI `:8000` internal, Gradio `:7860` public)