Tour Scout

An agent that routes tours for indie musicians and stand-up comedians from Qloo taste data: where fans over-index, a realistic opener, and the evidence behind every stop.

Comment

Inspiration

Ask a general chatbot to route a tour for Lomelda, a singer-songwriter from Texas, and it stays in Texas, the South and the Plains. That is a fair guess from the biography, but Qloo shows Lomelda's audience is densest in Austin, then Seattle, San Francisco, Boston and New York. For an act that sells a few hundred tickets a night, one wrong city can eat the margin of the whole trip. Managers of small acts route by habit and guesswork. Qloo measures what they can't easily get anywhere else: where an act's audience is denser than the baseline, and which other acts share it.

What it does

Pick musician or stand-up comedian, type the act, a region and a number of stops. Tour Scout:

  1. Resolves the act to one Qloo entity and uses its ID from then on.
  2. Ranks the region's metros by the act's Qloo audience affinity.
  3. Builds the route from the top of that ranking: the #1 metro is required, stops stay at least 150 km apart, and the order is the shortest drive.
  4. Books an opener whose fans overlap the headliner's and who is not bigger than the headliner (another comedian, for a comedian).
  5. Returns the plan on a map, with every stop citing the numbered Qloo calls (E1, E2, ...) behind it, streamed live as the agent works.
  6. Versus a generic LLM: one button sends the same request to the same Gemini models with no tools and no Qloo, then scores both plans against the same Qloo evidence.

Generic LLM vs Tour Scout

Both plans are scored in the app against the act's Qloo heatmap for the United States.

Musician: Lomelda (133 ranked metros)

Stop Generic LLM Qloo rank Tour Scout Qloo rank
1 Austin #1 Austin #1
2 Dallas #18 Denver #11
3 Houston #33 San Francisco #3
4 New Orleans #67 Seattle #2
5 Atlanta #37 Chicago #7
In the top 20 2 of 5 5 of 5
Median rank #33 #3

The generic plan missed nine of Lomelda's top ten metros. Four of its five openers aren't in Qloo at all, and the fifth, Hello Ocho, scores 0.840 audience overlap with Lomelda; Tour Scout's opener, Hand Habits, scores 0.966.

Comedian: Taylor Tomlinson (192 ranked metros)

Stop Generic LLM Qloo rank Tour Scout Qloo rank
1 Chicago #68 Seattle #1
2 Indianapolis #64 Portland, OR #2
3 Columbus, OH #56 Boulder #3
4 Pittsburgh #48 Minneapolis #14
5 Philadelphia #82 Boston #10
In the top 20 0 of 5 5 of 5
Median rank #64 #3

Another generic run went through the Southeast (Nashville, Atlanta, Charlotte, Raleigh, Richmond) and also put 0 of 5 in Tomlinson's top 20, median #116. On the Midwest route it suggested Nikki Glaser, Nate Bargatze and Sarah Silverman as openers, all more popular than Tomlinson in Qloo.

The generic answer varies between runs (Lomelda: median #19 to #35 over seven runs), and it isn't always wrong: for Hand Habits it put four of five stops in the top 20, because that audience follows the familiar indie map. The gap opens when an audience departs from what the biography suggests, which is when a manager needs data. Same pattern for Florist (generic median #16 vs #3; it skipped Albany, the band's #1) and Ratboys (#18 vs #5; it suggested Liz Phair as the opener).

What makes it Qloo-powered

Remove Qloo and Tour Scout has nothing to plan with. The model decides how to combine the evidence, but it can't supply the facts, and the server checks the plan in code: a stop citing evidence that doesn't exist is rejected, and a plan that skips the #1 metro, books an opener bigger than the headliner, or puts two stops under 100 km apart is sent back once.

Step Qloo call
Resolve the act qloo_describe (artist for musicians, person for comedians)
Fan metros Insights heatmap, GET /v2/insights?filter.type=urn:heatmap, averaged per metro
Opener candidates qloo_recommend; for comedians, person narrowed to urn:tag:genre:person:comedian
Opener per city qloo_rank with signal_location
Marketing angle qloo_audience_demographics, qloo_entity_tags
Momentum qloo_trends
Comparison panel qloo_describe, heatmap, one qloo_rank over every opener from both plans

Request to result (one live run)

Lomelda, United States, five stops:

  • E1 qloo_describe returns the artist entity: "the stage name of Hannah Read, an American indie folk singer-songwriter", popularity 0.940.
  • E2 The heatmap returns 2,172 cells. Averaging the cells within 40 km of each city of 100,000+ people gives 133 metros, led by Austin (0.989), Seattle (0.895), San Francisco (0.893), Boston and New York. Waco (#6) and Killeen (#10), two Texas cities of 130,000-140,000 people, rank above Portland and Denver.
  • E4-E7, E11 qloo_rank in each stop city puts Soccer Mommy first, but Qloo rates Soccer Mommy as more popular than Lomelda. The agent booked Hand Habits (popularity 0.90) instead and said why in the caveats.
  • Stop 1: "Seattle, Washington. Seattle ranks as Lomelda's #2 market in the United States with an affinity of 0.895." Opener: Hand Habits. Evidence: E2, E4.

How I built it

  • Agent: a Gemini function-calling loop with a three-model fallback chain; it also runs on Claude when an Anthropic key is set.
  • Qloo: the official harness as an MCP server (qloo mcp) for most calls; the heatmap is requested directly from the backend (see Challenges). Calls are queued and retried on 429, and each response is logged as numbered evidence before the model sees it.
  • Geography: 5,864 GeoNames cities of 100,000+ people; routes ordered with nearest neighbour plus 2-opt.
  • App: plain HTML and JavaScript with server-sent events and Leaflet, in a Docker container on Google Cloud Run. Keys stay in Secret Manager, and identical requests are cached for six hours.

Challenges I ran into

  • The top 20 heatmap cells are the wrong 20. qloo_where_popular returns the 20 highest-affinity cells. For a smaller act those are sparse rural cells where a handful of fans saturates the score: Hand Habits' top cells sat in the Navajo Nation and rural Alaska. The full heatmap (about 5,000 cells for Hand Habits), averaged per metro, puts real markets on top.
  • Comedians are people. As artists, Taylor Tomlinson and Atsuko Okatsuka didn't resolve. As people they do, but plain person recommendations mixed TikTok creators and Nick Offerman in with comics, until narrowed by Qloo's comedian tag. Some comedians have no audience data yet (Atsuko Okatsuka, Leanne Morgan), so Tour Scout checks for that and says so.
  • Borders. Snapping cells to the biggest nearby city filed San Diego under Tijuana, and Tomlinson's home market vanished. Cells now stay in the heatmap's main country; San Diego came back at #7.
  • Keeping the agent on the evidence. The model skipped Albany, Florist's #1 metro, as "too dense a cluster with Boston and New York", though it is about 220 km from both. It also booked openers bigger than the headliner and put Boulder and Denver, 39 km apart, on one run. Each is now checked in code.

Accomplishments that I'm proud of

  • Every stop traces back to the exact Qloo call that justified it.
  • The comparison panel holds Tour Scout to the same standard as the generic model, and anyone can rerun it.
  • It works for musicians and stand-up comedians, live, with no account or key.

What I learned

  • A generic model guesses from biography. When the audience matches it, the guess is good. When it doesn't, the guess misses most of the top metros, and that is where Qloo earns its place.
  • Per-city opener ranking rarely changes the winner. In 21 city rankings across four runs, it changed once (San Diego, 0.954 vs 0.952). Opener size mattered more than city.
  • Trends were flat on the hackathon data (Big Thief, Chappell Roan and Sabrina Carpenter all near the 0.11 percentile for 20 weeks), so Tour Scout reports momentum as not established.

What's next

  • Fall back to a comedian's comedy-album entity when the person entity has no audience data.
  • A larger city list, so college towns under 100,000 people can be stops.
  • Venue capacity and dates, and export to a booking sheet for promoters.

What a plan does not establish

  • Affinity is relative interest, not a ticket forecast or venue availability.
  • Towns under 100,000 people can't be stops yet.
  • The generic LLM's answer varies; the panel shows one run, cached for six hours.
  • No personal data is sent to Qloo; audience results are aggregate only.

Setup (clean environment)

Node.js 22.19 or newer.

git clone https://github.com/rayhannajla-hash/tour-scout.git
cd tour-scout
npm install
cp .env.example .env   # add QLOO_API_KEY and GEMINI_API_KEY
npm start              # http://localhost:8787

Without QLOO_API_KEY the app runs on labelled sample data; without a model key it runs a fixed playbook over the same tools.

Built With

Share this project:

Updates

Submission history