docs/DEPLOY_HF_SPACE.md

Deploy Iris to a Hugging Face Space (Docker, self-contained)

This is the deploy plan for shipping Iris as a Gradio app on a Hugging Face Space under the Build Small org, with the small model running inside the Space via llama.cpp. No external model API is required at runtime.

Authorship note: these deploy files are scaffolding for Codex/Khalid to review and commit. They are additive (new files); they do not change the validated iris/ engine. The only manual step that touches an existing file is adding the Space YAML frontmatter to README.md (see step 3).

Why this shape

• Serving path B: Docker Space + llama.cpp + a small (<=4B) MiniCPM GGUF on the free CPU tier (2 vCPU / 16 GB).
• The Iris engine is already endpoint-agnostic (IRIS_API_BASE_URL), so the container just runs an OpenAI-compatible server on localhost and points Iris at it. The load-bearing engine code is unchanged.
• Default model MiniCPM3-4B (Q4_K_M, 2.47 GB) is chosen because it:
  • is <=4B params, so the submission is eligible for the Tiny Titan badge;
  • is reliably supported by upstream llama.cpp (newer MiniCPM4.1/MiniCPM5 architectures can lag in llama.cpp / llama-cpp-python);
  • fits CPU RAM with margin and gives acceptable per-call latency on CPU.
• The custom pressure-studio UI targets the Off Brand badge (best custom UI past default Gradio).

Badge reality check (verified against the official field guide, June 2026)

The current official Build Small badges are: Off Brand, Tiny Titan, Best Demo, Best Agent, Bonus Quest Champion, Judges' Wildcard. The FAQ still references an Off grid bonus quest, so keep the app genuinely self-contained and avoid external model APIs. Treat the final badge wording as a submission-time check against the latest official form. The two strongest explicit badges Iris can target today are Off Brand (custom Gradio UI) and Tiny Titan (<=4B model), with Best Demo depending on the final video and social post.

Latency expectations (important)

Iris fires 4+ model calls per "Proceed" click (one per direction, plus retries). On the free 2-vCPU CPU tier, even a 4B Q4 model is slow:

• Roughly 5-15s per model call on CPU, so 20-60s per Proceed click.
• For a smoother live demo, either:
  • bump the Space to a paid GPU hardware tier (the same Dockerfile works; the model just runs faster), or
  • drop to MiniCPM4-0.5B (set the build args below) for speed at a quality cost, or
  • pre-record the demo video on faster hardware.

The engine-level latency fix (running the 4 direction calls concurrently instead of sequentially) is tracked separately and is the highest-impact UX improvement; it is independent of this deploy.

Files added for the Space

• Dockerfile — downloads a pinned prebuilt llama.cpp llama-server, bakes the GGUF into the image, installs Iris + Gradio.
• scripts/space_entrypoint.sh — starts llama-server on localhost, waits for health, wires IRIS_* env vars, then launches app.py.
• scripts/patch_gradio_templates.py — removes optional external Google/CDN tags from Gradio's wrapper templates during the Docker build.
• requirements-space.txt — documents the extra build-time dependency (huggingface_hub) used to fetch the GGUF at image-build time. The Dockerfile installs that dependency in the fetch stage only; the runtime app still uses the clean requirements.txt.

How to deploy

1. Create the Space

Create a new Docker Space under the Build Small org (Hugging Face website: New Space -> SDK: Docker -> blank).

2. Push this repo to the Space

# from the repo root
git remote add space https://huggingface.co/spaces/<org>/<space-name>
git push space main

(Or develop on GitHub and mirror to the Space remote.)

3. Verify the Space frontmatter in README.md

Hugging Face reads Space config from YAML frontmatter at the very top of README.md. The repo already includes Docker Space frontmatter; before final submission, verify the track/badge tags match the hackathon form:

---
title: Iris
emoji: 🧠
colorFrom: red
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
tags:
  - build-small-hackathon
  - thousand-token-wood
  - minicpm
  - openbmb
  - codex
  - custom-ui
  - tiny-titan
---

4. (Optional) Choose a different model at build time

The Dockerfile takes build args so you can swap the model without code changes:

# Default (Tiny Titan, balanced quality):
#   GGUF_REPO=openbmb/MiniCPM3-4B-GGUF  GGUF_FILE=minicpm3-4b-q4_k_m.gguf

# Faster on CPU, smaller (still Tiny Titan):
#   GGUF_REPO=openbmb/MiniCPM4-0.5B-GGUF  GGUF_FILE=<file from that repo>

# Highest quality, needs GPU hardware tier (NOT Tiny Titan, 8B):
#   GGUF_REPO=openbmb/MiniCPM4.1-8B-GGUF  GGUF_FILE=<file from that repo>

On the Space, set these as build-time variables, or edit the ARG defaults in the Dockerfile.

Runtime configuration (set as Space variables/secrets if needed)

The entrypoint sets sane defaults; override via Space "Variables and secrets":

• LLAMA_CTX (default 8192) — context window.
• LLAMA_THREADS (default: all CPUs) — generation threads.
• IRIS_TIMEOUT_SECONDS (default 180) — engine request timeout.
• IRIS_MAX_TOKENS (default 1000) — lower (e.g. 400) to speed up CPU runs.
• IRIS_ENABLE_THINKING (default 0 in the Space) — MiniCPM3-4B is not a /think model; keep off. Re-enable only for MiniCPM4.1.

Runtime network posture

• Model calls stay inside the container: Gradio -> Iris -> localhost llama-server.
• The frontend does not load Google Fonts, jsDelivr, or other runtime CDN scripts. The final brief uses the browser's local print-to-PDF path.
• The Docker context ignores .env, .env.*, .envrc, .DS_Store, virtual environments, caches, and the large Stitch reference folder.

Local smoke test of the container

docker build -t iris-space .
docker run --rm -p 7860:7860 iris-space
# open http://localhost:7860 ; first request loads the model into RAM

What still needs a human decision

• Whether to keep MiniCPM3-4B (Tiny Titan + self-contained) or move to a GPU hardware tier with the 8B for sharper pressure.
• The exact hackathon track/badge tags for the README frontmatter.
• Demo video + social post links (submission must-haves), added to README.