Spaces:
Running on Zero
Running on Zero
File size: 3,555 Bytes
f00d669 10cf611 f00d669 10cf611 f00d669 10cf611 b34c92a 10cf611 b34c92a f00d669 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 | # Deploying DiscoverRoute to a Hugging Face Space
The project is push-ready: `app.py` + `README.md` (Space card) at the root,
`requirements.txt` pinned, and the offline artifacts (`data/paris_walk.graphml`
~90 MB, `data/paris_pois.parquet`) committed via Git LFS so the Space needs **no
runtime OSM download**.
## One-time
```bash
# from the project root
cd discoverroute
# 1. Auth + LFS
pip install -U "huggingface_hub[cli]"
hf auth login # paste a WRITE token from hf.co/settings/tokens
git lfs install
# 2. Create the Space (Gradio SDK). Use your username in the REPO_ID.
hf repos create <your-username>/discoverroute --type space --space-sdk gradio
# -> creates https://huggingface.co/spaces/<your-username>/discoverroute
```
## Push
This folder is nested inside another git repo, so give it its own repo for the Space:
```bash
cd discoverroute
git init # fresh repo just for the Space
git lfs track "*.graphml" "*.parquet" # already declared in .gitattributes
git add -A
git commit -m "DiscoverRoute v1 — taste-aware Paris detour routing"
git remote add origin https://huggingface.co/spaces/<your-username>/discoverroute
git push -u origin main # LFS uploads the graph (~90 MB) automatically
```
`.gitignore` already excludes `.venv/`, `cache/`, and Gradio scratch — only the
app, source, tests, and `data/` artifacts are pushed.
## Enable the narration LLM (optional)
The app runs CPU-only out of the box (grounded **template** narration + keyword/
embedding vibe weights). To turn on the in-Space MiniCPM5-1B generative path:
1. In the Space **Settings → Hardware**, select a **ZeroGPU** tier.
2. The `@spaces.GPU` decorator on `narrate/llm.py::run_inference` activates
automatically. Vibe→weights (Call 1) and narration (Call 2) only call the model
when a GPU is present, and **fall back to the keyword matcher / grounded template
if the model is absent or its output fails validation / the zero-hallucination
gate** — so the app is correct either way. Weights are pulled from the HF Hub.
To force the LLM on/off regardless of hardware, set the Space variable
`DISCOVERROUTE_USE_LLM` to `1` / `0`.
## Off the Grid — no external APIs
DiscoverRoute is OSM-only: there is **no** Google Places (or any cloud) dependency.
Open-now comes from OSM `opening_hours` tags (~31% of POIs carry them); the 1B model
runs inside the Space on ZeroGPU. Nothing leaves the Space at request time.
## Open Trace — optional inference trace dataset
Every model call logs a row to `logs/traces.jsonl`. To also publish them to an HF
Dataset, set the Space **secret** `HF_TOKEN` (write scope) — rows are then pushed
async to `DISCOVERROUTE_TRACE_REPO` (default `build-small-hackathon/discoverroute-traces`).
Without the token, logging stays local (graceful no-op).
## Refreshing the data snapshot
Place data is a build-time snapshot. To refresh it (e.g. before a demo):
```bash
rm -rf cache/ # drop the Overpass HTTP cache to force a fresh download
.venv/bin/python -m discoverroute.data.build_graph # ~3 min
.venv/bin/python -m discoverroute.data.build_pois # ~12 min
```
OSM edits typically reach Overpass within minutes, so a rebuild is near-live.
## Notes
- First boot loads the 90 MB graph (~9 s, one-time); warm requests are ~1 s.
- If you ever rebuild the data: `python -m discoverroute.data.build_graph` then
`python -m discoverroute.data.build_pois`, and re-commit `data/`.
- Free Space storage comfortably fits the ~91 MB of LFS artifacts.
|