[deploy] HF Space packaging: README frontmatter, packages.txt, DEPLOY.md

Make the repo a valid Gradio Space and document the two-piece deploy:
- README.md: HF Space YAML frontmatter (sdk: gradio, app_file: app/app.py) +
a 'Live demo: HF Space + Modal' section and NUM_CTX/MODAL_* in the config table.
- packages.txt: WeasyPrint's system libs (Pango/HarfBuzz) + Noto fonts so PDF
generation works on the Space's base image (and non-Latin docs render).
- deploy/DEPLOY.md: copy-pasteable steps — HF login, create Space in
build-small-hackathon, push code, upload the gitignored RAG index via hf upload
(auto-LFS), set Space secrets, verify, submit, and stop the Modal meter after.

Co-authored-by: Codex <noreply@openai.com>

README.md

@@ -1,3 +1,19 @@
+---
+title: Fugee
+emoji: 🏠
+colorFrom: green
+colorTo: yellow
+sdk: gradio
+sdk_version: 6.15.2
+app_file: app/app.py
+pinned: false
+license: mit
+short_description: Agentic AI guidance for displaced people, on a small (≤32B) LLM
+---
+
+<!-- The block above is Hugging Face Space metadata (required for the Space to
+     build). The hackathon submission tool appends track/badge tags to it. -->
+
 <div align="center">
 
 # 🏠 Fugee
@@ -20,9 +36,14 @@ countries, and generates a personalised documentation package they can download
 and edit.
 
 It is a **single-process Gradio web app** backed by a **pure-Python agent loop**
-(`agent/loop.py`, ported from pi-agent-core's patterns) and a **small local LLM**
+(`agent/loop.py`, ported from pi-agent-core's patterns) and a **small (≤32B) LLM**
 served by Ollama. No Node.js, no microservices, no external database.
 
+> **This Space** runs the Gradio UI on free CPU and calls the LLM (`lfm2.5:8b`)
+> and embeddings (`nomic-embed-text`) on a GPU **Ollama** endpoint hosted on
+> [Modal](https://modal.com) — so the same code and the same small model run
+> unchanged, just on rented GPU. See [`deploy/DEPLOY.md`](deploy/DEPLOY.md).
+
 The design point: *a genuinely useful agentic product running on a small model.*
 The interview is fully **deterministic** (fixed questions and controls,
 hand-translated into 10 languages) and the LLM is used only where it adds real
@@ -94,9 +115,11 @@ Read at startup by `app/config.py` (no `python-dotenv` dependency):
 
 | Variable        | Meaning                                                        | Example |
 |-----------------|----------------------------------------------------------------|---------|
-| `OLLAMA_HOST`   | Base URL of your Ollama server                                 | `http://192.168.0.233:11434` |
+| `OLLAMA_HOST`   | Base URL of the Ollama server (local, LAN, or Modal endpoint)  | `http://127.0.0.1:11434` |
 | `MODEL_ID`      | The single ≤32B tool-calling instruct model for the whole app  | `lfm2.5:8b` |
 | `MODEL_PROVIDER`| `ollama` (default) or a litellm provider name                  | `ollama` |
+| `NUM_CTX`       | Ollama context window — keep large; the small default truncates the assessment prompt | `16384` |
+| `MODAL_KEY` / `MODAL_SECRET` | Proxy-auth headers when `OLLAMA_HOST` is a protected Modal endpoint (hosted demo only) | — |
 
 > **One model, no fallback.** The hackathon build deliberately uses a single
 > small model end to end. `web_search` is **disabled** — the assessment is
@@ -105,6 +128,27 @@ Read at startup by `app/config.py` (no `python-dotenv` dependency):
 
 ---
 
+## Live demo: Hugging Face Space + Modal
+
+The deployed demo splits into two pieces so it runs **free** and **fast** without
+changing the app or the model:
+
+```
+HF Space (free CPU, Gradio)            Modal (GPU, Ollama)
+┌──────────────────────────┐  HTTPS   ┌──────────────────────────────┐
+│ app/app.py + curated data │ ───────▶ │ ollama serve                 │
+│ + guidelines RAG (cosine) │  proxy   │   • lfm2.5:8b   (assessment) │
+│ OLLAMA_HOST → Modal URL   │  auth    │   • nomic-embed-text  (RAG)  │
+└──────────────────────────┘          └──────────────────────────────┘
+```
+
+The Space sets `OLLAMA_HOST` to the Modal endpoint and sends the proxy-auth
+headers (`agent/ollama_auth.py`); everything else is identical to local. Full,
+copy-pasteable steps — create the Space, deploy Modal, set secrets, upload the
+RAG index — are in **[`deploy/DEPLOY.md`](deploy/DEPLOY.md)**.
+
+---
+
 ## Project layout
 
 ```

deploy/DEPLOY.md

@@ -0,0 +1,146 @@
+# Deploying Fugee — Hugging Face Space + Modal
+
+The demo runs in two pieces: the **Gradio UI on a free HF CPU Space**, calling the
+**LLM + embeddings on a GPU Ollama endpoint on Modal**. Same code, same model
+(`lfm2.5:8b`), just on rented GPU.
+
+```
+HF Space (free CPU)  ──HTTPS, proxy-auth──▶  Modal (L4 GPU, ollama serve)
+app/app.py                                    lfm2.5:8b + nomic-embed-text
+```
+
+Run the steps in order. Steps that only the maintainer can do (auth, secrets) are
+marked **[you]**.
+
+---
+
+## 0. Prerequisites (already done in this repo)
+
+- `deploy/modal_app.py` is deployed and **kept warm**
+  (`MODAL_MIN_CONTAINERS=1`) → endpoint `https://hf-labs--fugee-ollama-serve.modal.run`.
+- A Modal **Proxy Auth Token** exists; its id/secret are in `.env.modal`
+  (gitignored) as `MODAL_KEY` / `MODAL_SECRET`.
+- Models cached in the Modal Volume (`modal run deploy/modal_app.py::download_models`).
+
+Re-check the endpoint is warm before a demo:
+
+```bash
+set -a; . ./.env.modal; set +a
+curl -s -o /dev/null -w "%{http_code}\n" \
+  https://hf-labs--fugee-ollama-serve.modal.run/api/version \
+  -H "Modal-Key: $MODAL_KEY" -H "Modal-Secret: $MODAL_SECRET"     # expect 200
+```
+
+---
+
+## 1. **[you]** Authenticate the HF CLI
+
+Create a token with **write** access at <https://huggingface.co/settings/tokens>,
+then:
+
+```bash
+hf auth login        # paste the write token
+```
+
+---
+
+## 2. **[you]** Create the Space in the hackathon org
+
+Web: **New Space** → Owner `build-small-hackathon`, name `fugee`, SDK **Gradio**,
+hardware **CPU basic (free)**, **Public**. Or CLI:
+
+```bash
+hf repo create build-small-hackathon/fugee --repo-type space --space-sdk gradio
+```
+
+(If the flag name differs on your CLI version, run `hf repo create --help`.)
+
+---
+
+## 3. Push the code to the Space
+
+The Space is its own git repo. Add it as a remote and push the current branch to
+its `main` (force, to replace the starter README on first deploy):
+
+```bash
+git remote add space https://huggingface.co/spaces/build-small-hackathon/fugee
+git push space HEAD:main --force
+```
+
+This pushes everything except gitignored files — so **not** the 23 MB RAG index
+(next step). The Space starts building on push.
+
+---
+
+## 4. Upload the RAG index (gitignored → uploaded directly)
+
+`specs/data/guidelines_index.json` is needed at runtime for `guideline_search`.
+`hf upload` stores it via LFS automatically (no local git-lfs required):
+
+```bash
+hf upload build-small-hackathon/fugee \
+  specs/data/guidelines_index.json specs/data/guidelines_index.json \
+  --repo-type space
+```
+
+---
+
+## 5. **[you]** Set the Space secrets & variables
+
+Space → **Settings → Variables and secrets**. The app reads these from the
+environment (its `.env` loader never overrides real env vars).
+
+**Secrets** (encrypted):
+
+| Name | Value |
+|------|-------|
+| `OLLAMA_HOST` | `https://hf-labs--fugee-ollama-serve.modal.run` |
+| `MODAL_KEY` | your Modal Proxy Auth Token id (`wk-…`) |
+| `MODAL_SECRET` | your Modal Proxy Auth Token secret (`ws-…`) |
+
+**Variables** (public):
+
+| Name | Value |
+|------|-------|
+| `MODEL_ID` | `lfm2.5:8b` |
+| `MODEL_PROVIDER` | `ollama` |
+| `NUM_CTX` | `16384` |
+
+> `MODEL_ID` **must** be set — the code default is `qwen2.5:7b`, which isn't on
+> the Modal endpoint. `OLLAMA_HOST` + `MODAL_KEY` + `MODAL_SECRET` are required for
+> the Space to reach the model. The Modal **account** token never goes here — it
+> stays in `~/.modal.toml` on your machine.
+
+Setting a secret restarts the Space.
+
+---
+
+## 6. Verify the live Space
+
+Open `https://huggingface.co/spaces/build-small-hackathon/fugee`, wait for the
+build (watch the **Logs** tab), then walk a full flow: language → interview →
+assessment → recommendations → documents. First model call may take a few seconds
+even though Modal is warm.
+
+If PDF generation errors in the logs, it's a missing system lib — confirm
+`packages.txt` installed (Pango/HarfBuzz/Noto fonts).
+
+---
+
+## 7. Submit & costs
+
+- **Submission:** on the hackathon *submit* page, enter `fugee` under
+  `build-small-hackathon/` → it loads the README and writes track/badge tags into
+  the frontmatter → commit that back (`git pull space main` then push, or edit on HF).
+- **GPU limit:** the "10 ZeroGPU apps per user" rule does **not** apply — we use
+  Modal, not ZeroGPU.
+- **After the demo window**, stop the Modal meter:
+
+  ```bash
+  MODAL_MIN_CONTAINERS=0 modal deploy deploy/modal_app.py   # scale to zero
+  # or fully stop:
+  modal app stop fugee-ollama
+  ```
+
+  Scale-to-zero keeps the deployment but costs nothing while idle (cold start
+  ~40 s on the next request).

packages.txt

@@ -0,0 +1,6 @@
+libpango-1.0-0
+libpangocairo-1.0-0
+libpangoft2-1.0-0
+libharfbuzz0b
+fonts-noto-core
+fonts-noto-cjk