Settlement

Inspiration

"Settlement" is the end-of-night accounting at a show: gross vs guarantee. Booking agents and managers plan tours from gut feel, past grosses and spreadsheets. We wanted a tool that shows where an act's audience actually is, why, and what a date might pay, and lets you check every step.

What it does

A booking agent or manager types a musician or comedian. Settlement:

1. Finds the act in Qloo and pulls where its audience lives.
2. Picks cities, routes them under a daily drive cap, and assigns dates.
3. Picks a room per city sized to the act, plus openers and local promo angles (podcasts, bars, brands).
4. Saves the plan to a share link that stays up (Convex).

Also live now:

• Why these cities strip: each city ranked by how much the act over or under indexes vs a 12-act reference panel.
• Receipts drawer: every Qloo call the run made, which pick it fed, and per-source totals. There's a /receipt endpoint too.
• With / Without Qloo toggle on the map and itinerary. "Without" is the same router using the biggest metros and zero Qloo calls, so you can see exactly what taste data changes.
• Deal math + advance packet: capacity bands by room size, a ticket estimate from Qloo price level and act popularity, projected gross, guarantee vs 85% of net, and warnings for radius clauses, holds and long drive legs. Every assumption is labeled and editable. The packet has hold-request email drafts per stop (text only, nothing gets sent), CSV export and receipt links.
• /proof backtest page (below).
• Booking fixes: wrong rooms get swapped out, opener size is capped, labels are honest.

How it's Qloo-powered

Without Qloo there's no tour. Qloo drives every pick:

• Entity search resolves the act and the venues, openers and promo entities for each stop.
• City heatmaps (urn:heatmap, snapped to cities) give audience affinity and popularity by location. City score is affinity times popularity of the best cell within 40 miles.
• Lift vs a 12-act reference panel: we pull heatmaps for 12 reference acts, then score the act's cities by how far it beats the panel mean. That separates "this act's fans live here" from "everyone's fans live here."
• Price level and popularity feed the ticket estimate in the deal math.
• Receipts record each call, so a judge can open a plan and trace any pick back to the Qloo data behind it.

The /proof backtest (honest numbers)

We checked city picks against 29 real 2025-26 tours. Metric: recall at K, meaning how many of the real tour's cities the method picked, with K set to the real tour's city count.

• Head to head: metros won 10 acts, combined 5, lift 3, with 11 ties.
• 6 acts were skipped because Qloo had no data for them.
• The 50/50 weight was fixed before the run and not tuned. We added the combined method after seeing the first lift vs metros result, and /proof says so.

Qloo doesn't beat the big-city pick on this test, and we're not claiming it does. Real tours chase big rooms, so "where did they play" leans toward big metros. What the combined ranking shows is you keep about the same accuracy as the obvious route, and Qloo adds the reasons per city, the receipts and the money side. Tour lists, sources and per-act results are in the repo.

How we built it

• Next.js 16 App Router on Vercel. The agent runs in lib/agent/run.ts and streams each step to the UI.
• Qloo fetch layer with a cache, shared in-flight requests, at most 3 concurrent calls, 429 retries and a per-run call budget.
• Routing: greedy pick, nearest neighbor, then 2-opt under a drive cap. Dates skip holidays.
• Convex stores plans, share links and cached Qloo payloads.
• vitest suite: 148 tests passing across the six PRs. Rate limit of 15 plans per hour to protect the API key.

Challenges

• Qloo's city boundary option returned errors, so we snap heatmap cells to cities ourselves.
• Raw affinity picks the same big cities for everyone. The reference panel lift fixed that, and the backtest kept us honest about what it does and doesn't do.
• The first live audit picked wrong rooms and oversized openers. We added a venue swap loop and opener caps.

What's next

• Pull real past grosses to calibrate the deal math.
• More reference panels by genre and act size.
• Rerun /proof as new tours are announced.

Built With

• api
• convex
• devin
• gl
• maplibre
• next.js
• qloo
• react
• typescript
• vercel
• vitest