Inspiration
AI agents are getting smarter, but they're culturally blind. Ask one where to go and you get fluent, generic, popularity-ranked "agentic slop" — the same ten places everyone already knows. Meanwhile people are shifting toward analog, screen-free, heritage-rooted third places, and nobody — traveler, relocatee, promoter, or agent — can answer the question that actually matters: is this place loved, or just loud?
Review sites measure popularity. LLMs hallucinate taste. We wanted a queryable engine for the difference — one that works as beautifully for a human flying a globe as for an agent grounding its next recommendation. TopoVibe (UX-inspired by the open-source "God's Eye View" project, clean-room build) is that engine.
What it does
TopoVibe is a cultural-intelligence globe for humans, and an MCP oracle for agents — both powered entirely by Qloo's taste graph.
- Click a city on the CesiumJS 3D globe → its Cultural DNA: signature tags, demographics (age/gender affinity deltas), and top places.
- Pick a tag (Italian dining, live music, coffee) → an affinity heatmap drapes over the city, blue to red.
- Every venue gets a Grounding Score (GS), 0–100:
GS = 100 × clamp(0.6·A + 0.4·T − 0.3·N)— affinity rank from/v2/insights, analog tag density from a/v2/tags-resolved lexicon (vinyl, independent bookshop, ceramics, craft, quiet, heritage, record store, third place), and a viral-noise penalty. Loved analog venues glow hot red; viral tourist traps glow cold blue. Click any marker and the score shows its work: A/T/N component bars, matched analog tags, and what people actually mention there. - For agents, a first-class MCP server with 5 tools (
resolve_entities,resolve_tags,get_insights,get_taste_profile,get_grounding_score) — every response embeds the raw Qloo query echo, so an agent can prove where its taste claims came from. - Share links serialize camera + city + tag into the URL hash; coverage badges (
live | cached | insufficient-data) appear on every panel.
Remove Qloo and TopoVibe is an empty basemap — cultural intelligence isn't a feature, it's the product.
How we built it
Vanilla JS + CesiumJS + Vite client; Node.js + Express server in six single-responsibility modules: a Qloo broker (X-Api-Key header, GET-only, 6-hour TTL cache, one retry), a validity matrix (param ↔ filter.type rules from the Qloo docs), the Grounding Score engine, REST routes, the MCP endpoint, and the cache with a demo pre-cache loader.
We worked to a hard 7-hour phase plan — scaffold → broker → DNA → heatmap → Grounding Score → MCP → share links → ship — with an acceptance check and a commit at every green gate. Every Qloo rule was enforced in code, not in comments: full-URN filter.type values, resolve IDs before signaling, /v2/insights GET-only, no legacy /recs. The demo pre-cache warms 3 cities × 3 tags in 27 calls so demos never burn quota. Deployed as one Render service (static client + REST + MCP) verified by a 7-point script: static, Cesium, health, DNA, Grounding, MCP, HTTPS.
Challenges we ran into
The best features came from API discoveries the docs don't make:
/v2/tagsrejects?query=. Only the API's own error message revealed the real parameter isfilter.query. Our broker now validates against the exact set the API accepts./v2/trendingdoesn't supporturn:entity:place— only actor, artist, brand, movie, person, podcast, tv_show. Our viral-noise component was designed around trending data for venues. Rather than fake it, every venue's N component reportsunknownand the UI says so. The score degrades honestly.- A location signal isn't a location filter. An Austin record-store query cheerfully returned San Antonio venues until we switched to
filter.location.queryas a hard filter. - Demographics are sparse. Niche tags return empty breakdowns, so the DNA panel falls back through a city's top tags → top places, and declares
insufficient-datawhen nothing yields — never inventing numbers. - Our analog lexicon got polluted. Resolving "third place" returned a burger-combo tag and the bare parent
urn:tag:genre:place— which intersected with every venue on Earth and silently inflated every score. A depth filter (leaf URNs only) fixed it. - Pretty presets, empty grids. The indie-music keyword tag has no place heat grid at all; specialty-coffee produced 22 cells. We density-tested replacements live and swapped tags, documenting why.
- Deployment whack-a-mole. AWS App Runner is closed to new customers (per AWS's own notice) — we pivoted to a Render free instance with a blueprint and a keep-warm health ping.
Accomplishments that we're proud of
- Honesty as architecture. No taste claim renders without its Qloo query echo; the Grounding Score is withheld, never interpolated, on insufficient data; coverage badges are everywhere. The demo can't lie by accident.
- A real agentic surface. Five MCP tools verified end-to-end over raw JSON-RPC — handshake, tool list, every tool called, invalid input rejected with actionable named errors, and the 30/min rate limit returning 429s.
- Discipline that shipped. Seven phases, seven acceptance gates, a commit at every green. Self-check green at minute zero; deploy sweep 7/7 at the end.
- The Grounding Score works. Austin's record stores score 15–60 with a clean monotonic ranking and a real analog-density signal — the FLIR contrast is honest data, not tuned theatrics.
What we learned
APIs silently ignore invalid parameters — which makes client-side validation a feature, not a courtesy (we strip and log what Qloo would ignore). Resolve before you signal, always: invented tag URNs fail silently too. Sparse data is a design input, not an edge case — fallback chains and honest empty states made the product more trustworthy, not less. And a metric that shows its work (A/T/N bars, matched tags, query echoes) turns a number into evidence.
What's next for TopoVibe
Per our roadmap: Sister Cities (neighborhood affinity matching via /v2/analysis/compare — "which Tokyo neighborhood feels like Bushwick?"), Promoter Mode for venue scouting, a voice/chat agent over the existing MCP tools, and the NVG "Quiet" map style. On the production side: graduating from the hackathon key to commercial Qloo terms, a durable pre-cached demo pack, and the final-version deployment to AWS Elastic Beanstalk. The Grounding Score deserves an API of its own — every agent deserves to know what's loved, not just loud.
Built With
- cesium
- express.js
- node.js
- qloo
- vanilla
- vite