README.md

metadata

title: WanderLust
emoji: 🗺️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.18.0
python_version: '3.12'
app_file: app.py
pinned: true
license: apache-2.0
short_description: A-to-B routes through places you'll love
tags:
  - track:backyard
  - sponsor:openbmb
  - achievement:offgrid
  - achievement:offbrand
  - achievement:sharing
  - achievement:fieldnotes
  - badge-off-the-grid
  - badge-off-brand
  - badge-tiny-titan
  - badge-field-notes
  - openbmb

WanderLust

Spend your extra time on discovery.

Track 1 — Backyard AI · Live Space: https://huggingface.co/spaces/build-small-hackathon/WanderLust

Most navigation apps answer one question: what's the fastest way there? WanderLust asks a better one: what if those few extra minutes were a gift? You tell it where you're going and the kind of moment you're after — "a slow Sunday-morning kind of walk," "bookshops and quiet streets," "a lively café crawl" — and it threads you from A to B past the places you'll actually love, then tells you, in your own words, why each one is on your path. Same destination. A walk you'll remember instead of one you'll forget.

One-liner: WanderLust turns any walk or ride from A to B into a personal discovery — routing you through places that match your taste, not just the fastest path. Nine cities across four continents — Paris, London, Barcelona, Berlin, New York, San Francisco, Tokyo, Mumbai, Shanghai — all routed fully offline (no cloud APIs at request time).

---

Why we built it (Backyard AI)

This started as our own itch. We're cyclists, and pedaling around new cities we kept hitting the same frustration: the map only ever knows the fastest line between two points, but the whole joy of exploring your "backyard" — the city around you — is the bookshop, the quiet square, the viewpoint you'd never have found on the direct route. We wanted a tool that plans the interesting way from A to B, tuned to the mood we're in that day. WanderLust is that tool: a personal, local-first exploration companion for the ground right under your wheels.

🔗 Links (judges start here)

• 🗺️ Live Space: https://huggingface.co/spaces/build-small-hackathon/WanderLust
• 💻 Source code (GitHub): https://github.com/tristanleduc/wanderlust
• 🎬 Demo video: https://www.youtube.com/watch?v=55Ofnt6Hhv4
• 📣 Social post: LinkedIn · X/Twitter
• 📝 Field notes (HF blog): https://huggingface.co/blog/coreprinciple/wanderlust
• 🧑‍🤝‍🧑 Team:
  • Ishrat Jahan Ananya — Hugging Face · GitHub · Website
  • Tristan Leduc — Hugging Face · GitHub · LinkedIn

---

Why the AI is load-bearing

WanderLust cannot work without the model. The hard problem isn't routing — it's the gap between how people describe what they want and what a router can optimize. A user types a fuzzy, open-ended vibe ("somewhere that feels like a slow Sunday morning"), and MiniCPM5-1B converts it into concrete, scored routing weights across 17 place categories plus quiet/green/lively modifiers. No lookup table, keyword list, or rule engine can map unbounded human mood onto a route — the model is the bridge. It then writes the itinerary that explains why each chosen stop matches what you asked for, grounded so it can only name real places on your route.

(When no GPU is allocated, the app degrades gracefully to an embedding + keyword interpreter and a deterministic template — it never breaks — but the model is what makes the experience feel like it read your mind.)

The tech, one sentence each

• Model — openbmb/MiniCPM5-1B: a 1B-parameter model does two jobs — vibe → routing weights (JSON), and route → first-person itinerary narration.
• ZeroGPU: the model runs inside the Space on HF ZeroGPU via @spaces.GPU, weights pulled from the Hub — no external inference API, nothing leaves the Space.
• OpenStreetMap + OSMnx: walking/biking graphs and POIs for nine cities, pre-built and pulled from an open Hub dataset, then pre-warmed at boot so every city is instant — and routes with no cloud API calls at request time — fully offline.
• Routing — classical, exact: a networkx + SciPy multi-source Dijkstra travel-time matrix, solved by a custom orienteering (prize-collecting TSP) heuristic with submodular diversity — so you get a park + a viewpoint + a bookshop, not five cafés.
• Frontend — Gradio gr.Server: a hand-built HTML/CSS/JS app-shell on Gradio's FastAPI backend, called from the browser via @gradio/client — no default Gradio UI.

What it does

• Plain vs. discovery route drawn on one map, with the exact time the detour buys you.
• Vibe → route: free-text mood reshapes which places the route seeks out.
• Walk or bike, across nine cities, with a city picker (cores pulled on demand).
• Detour budget: one slider trades extra time for discovery; the route never exceeds (1 + budget) × the direct time. Budget 0 = the plain fastest route.
• Adventurousness: low → well-documented places; high → injects hidden gems.
• Grounded narration: an itinerary naming only real waypoints, behind a hard zero-hallucination gate.
• Alternative routes: up to three genuinely distinct options.
• Persistent taste profile: standing preferences + saved places, per device, blended with each trip's mood. No accounts.

Achievements & badges we're claiming

Achievements (achievement:* tags):

Achievement	How WanderLust earns it
Off the Grid (offgrid)	With DISCOVERROUTE_OFFLINE=1, zero cloud APIs at request time — every city is pre-baked + pre-warmed at boot, geocoding is local, and the 1B model runs in-Space on ZeroGPU.
Off-Brand (offbrand)	A hand-built gr.Server HTML/CSS/JS app-shell — zero default Gradio components: custom map, custom controls, custom live-map loader.
Sharing is Caring (sharing)	Two reusable artifacts shared publicly on the Hub: the city-cores dataset build-small-hackathon/discoverroute-cities and the inference-trace dataset build-small-hackathon/discoverroute-traces.
Field Notes (fieldnotes)	The end-to-end build story — decisions, dead ends, fixes — in FIELD_NOTES.md and published as an HF blog post.

Bonus badges (prize categories) we're going for:

Badge	Basis
Off Brand ($1,500)	The hand-built gr.Server custom UI (same evidence as the achievement).
Tiny Titan ($1,500)	MiniCPM5-1B — 1B parameters (well under the 4B cap), in-Space on ZeroGPU.
Best Agent ($1,000)	Four-stage planning pipeline: vibe → routing weights → POI scoring → orienteering solve → grounded narration.

Sponsor prize: built on OpenBMB's MiniCPM5-1B, so eligible for Best MiniCPM Build (OpenBMB).

Run it locally

uv venv --python 3.11
uv pip install -e ".[ml,dev]"   # routing + vibe interpretation/narration + tests

# one-time offline data prep for Paris (downloads OSM, builds the graph + POIs)
python -m discoverroute.data.build_graph
python -m discoverroute.data.build_pois

python app.py                   # serves the gr.Server app-shell on :7860

The other eight cities are pulled on demand from the Hub dataset (and pre-warmed at boot). Run the test suite with pytest (config in pyproject.toml, tests in tests/). See FIELD_NOTES.md for the build story.

Architecture

Offline (built once per city, cached): OSM extract → walk/bike routing graph → POIs with feature priors + confidence. Paris ships full-city; the other eight (London, Barcelona, Berlin, New York, San Francisco, Tokyo, Mumbai, Shanghai) are baked as walkable cores via python -m discoverroute.data.build_city and hosted as an open Hub dataset, then pulled + pre-warmed at boot.

Runtime (per request): pick the city → interpret vibe → score corridor POIs → solve the detour (orienteering) → trace a real polyline → narrate + overlay on the map.

The model is load-bearing only in interpretation and narration; routing is pure classical algorithms. Geocoding is local-first — named places resolve against the cached POI index with no network call. With DISCOVERROUTE_OFFLINE=1 (the deployed config) there are zero cloud API calls at request time — routing is limited to the pre-baked cities. Map data © OpenStreetMap contributors (ODbL).