Tour Router

Routes a tour inside your rules, shows what taste data changed

Comment

Inspiration

A promoter routing a tour works from last tour's ticket counts, a venue calendar full of holds and blackout dates, a radius clause in every contract, and whoever the booking agent knows in each market. Qloo knows the other half: which cities' audiences over-index on an act, which venue's crowd overlaps those fans, which local brand they share, which act is trending with the same audience. We saw twenty tools that chain Qloo's answers into a route. None let the promoter write the rules the route must obey, none picked one support act for the whole run, and every counterfactual compared data sources, never rules. Tour Router routes a tour inside the promoter's own rules, and shows what the taste data changed.

What it does

You write the routing policy as data: city cap, budget per city, excluded cities, regions, capacity window, days between shows, blackout dates, held venues (city, venue, date), a radius clause (minimum km between any two stops) and a per-leg cap. Then you give it a brief: "Plan an 8-city North American tour for Khruangbin starting in Austin in March 2027".

The agent resolves the act with Qloo /search (musicians as artist entities, comedians as person entities, because the comedian's heatmap lives on the person), reads ONE Qloo heatmap per country and scores every candidate city from the cells within 60 km (fan affinity, listener density, and a taste lift = size rank minus taste rank: Denver +21, Portland +24, New York -6). For each city it asks Qloo Insights with explainability for a venue whose crowd overlaps the fans, a brand both audiences over-index on, and a trending local opener. Then it routes, inside the policy: dates skip blackout days, held venues pin their city to their date and show HELD, and two stops inside the radius clause are refused with the pair and the field named. Over the cap it stops with an approval card ("8 stops is over your 6-city cap"). Every decision lands in an audit log citing the policy field.

Then the two things nobody else does. A tour opener and the co-bill markets: from the per-city opener lists, the act that recurs across the routed stops becomes the opener for the whole run (locals stay as alternates), and one more heatmap per country is signalled by headliner and opener together, so every city shows its co-bill affinity next to the headliner-only one. For Khruangbin + SAULT the pairing lifts Seattle #7 -> #3 and New York #8 -> #4 and costs Denver #2 -> #8; the co-bill route swaps Denver and Austin for Seattle and New York. Two counterfactuals on identical routing: the obvious route (the same number of stops by metro size, what a model with no taste data picks: New York, Chicago, Dallas, Houston out; Denver, San Francisco, Portland, Vancouver in; +5 pts affinity, 662 km fewer with both routes starting in Austin) and policy B, the same brief with one rule changed (cap 6 -> 8, a city excluded, a 300 km radius, a blackout), rebuilt from the cached ranking with the decisions that flip: "Build a 6-stop itinerary: allowed under A, denied under B [minKmBetweenStops]". "Why Denver?" answers from the data; "Why not Chicago?" answers from the rank, the obvious route and the policy. A Qloo demographics card shows the act's over/under-index by age and gender, labelled as exactly that. The share link carries the plan, the policy snapshot and the audit decisions in the URL and prints as a promoter brief: "Rules this route obeyed" and "Where the agent asked, and where it was refused".

How we built it

Qloo: a typed adapter over /search (artist + person), /v2/insights for urn:entity:place (with the venue tags that actually exist), urn:entity:brand, urn:entity:artist, urn:entity:person (with signal.location.query, bias.trends, feature.explainability), urn:heatmap per country with one or two signal entities, and urn:demographics, all against hackathon.api.qloo.com with a private in-memory cache, 350 ms pacing, two in flight, bounded retries, typed errors that surface as a banner (fixtures are never substituted). A synthetic fixture adapter implements the same interface so the product and the tests run with no key.

Agent: Vercel AI SDK 7 loop (streamText, multi-step tools, toolApproval) with seven tools; a pure policy engine evaluates each call (allow / approve / deny) and cites the rule; the same evaluation runs under policy A and B for the counterfactual. Gemini or Groq free tiers behind daily caps; past the cap a keyless rule planner that implements LanguageModelV3 drives the same tools.

UI: Next.js 16, React 19, AG Grid (ranked markets with co-bill columns, inline exclude / re-order), Leaflet, Tailwind; client-carried state so each visitor plans in isolation on Vercel. 93 vitest tests across 15 files.

Challenges we ran into

Turning a heatmap into a city score: Qloo normalises affinity inside the queried area, so per-city heatmaps all peak at 1.0; one heatmap per country binned to cities ranks on one scale (measured in docs/LIVE-NOTES.md). Whether a heatmap accepts two signals: it does, and the joint map is neither the headliner map nor the mean of two single maps; the averaged fallback exists, labelled, and was not needed live. Opener affinities are flat (82-83%), so the tour opener is carried by how many stops an act recurs in, with the runners-up one click away. Scheduling around holds: free stops take the next dates in route order, never on a blackout and never within the gap of a held date, then the itinerary is ordered by date. Keeping the share link short enough to carry a policy and an audit log: the payload trims itself to a 7,500-character budget and says what it left out.

Accomplishments that we're proud of

A promoter can hand the agent a radius clause, three holds and a blackout week and get a route that obeys them, with an audit line for every decision. A tour opener chosen from the data, and cities ranked on the pairing. Two counterfactuals that answer different questions: what did Qloo change, and what would my own rule change. One code path for fixtures and the live key, and live measurements in the repo.

What we learned

The agent gets small and safe once "what may it decide alone" is explicit data; the interesting work moves into the policy engine and the counterfactuals. Qloo's two-signal heatmap is a real co-bill signal, not a blend.

What's next

Venue avails from the venues themselves, per-stop pitch emails, a per-city budget as a policy field, package tours with three acts, and promoter accounts with saved policies.

Built With

Share this project:

Updates

Submission history