DEPLOY.md

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

# 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:

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):

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.