Crowd Compass

A taste-aware booking agent for small venues: it reads your town's taste through Qloo and tells you which night to run next, which offer to book, and where to promote it.

Comment

Inspiration

Every week, thousands of small venues make the same bet: what do we put on Friday? Pubs, bowling-alley bars and community halls run tribute nights, film screenings and trivia. Most pick by gut feel, or by whatever a booking agent is pushing. One empty room can wipe out a week's margin, and grassroots venues run on thin margins already.

We asked a general AI assistant what a bowling-alley bar in Pittsburgh should book. It gave the same global hits it gives everyone. That is the problem the hackathon describes: agents are smart but culturally blind. A venue doesn't need "popular". It needs "what this crowd, in this town, will pay to come out for". That is what Qloo's taste graph knows.

What it does

A venue owner gives Crowd Compass a short brief: venue, town, a few past nights that packed the room (e.g. The Big Lebowski, Bon Jovi, The Office), crowd age, act budget, and optionally the acts a booking agent has offered. The agent returns:

  1. The next nights to run. One card each for live music, film night and themed trivia, each with five headliners, theme tags, a ready-to-use pitch and a fit score, ranked by local fit. Every pick says why: "because your crowd loved X", from Qloo explainability.
  2. Local lift, side by side. What a generic recommender would pitch next to what your town favours: same seeds, same age, and the only difference is Qloo's location signal. Picks that only appear locally are flagged.
  3. Which offer to book. Paste the acts on the table and they come back ranked by local taste, with how far each one moves against a generic ranking.
  4. Where to promote it. A Qloo heatmap of where fans of the headliner cluster around town, so flyers and geo-targeted ads go to the right suburbs.
  5. A town taste fingerprint. Genres and themes the town over-indexes on compared with a baseline.
  6. A full agent trace. Every step, every Qloo call (key redacted), timings, and every decision, including when the agent widens a thin small-town signal to the wider region.

Everything is a proposal for a human to approve. Nothing is booked or sent automatically. Crowd Compass is also an MCP server, so any agent (Claude Desktop, Cursor, custom agents) can call plan_venue_nights, rank_offers and town_taste_fingerprint.

Real output from the live site (Qloo hackathon API, 23 Oct 2026), preset "Half Moon Lanes, Pittsburgh PA", ages 25–34, seeds The Big Lebowski, Bon Jovi, The Office:

  • Top night: themed trivia (fit 0.95) built around Good Trouble, New Girl, Last Man Standing, A.P. Bio, Shameless. A generic, location-blind list pitched Backstreet Rookie and The Michael J. Fox Show instead.
  • Live music (fit 0.92): The Mad Gear and Missile Kid, Brendon Urie, Ruston Kelly, Charles Wesley Godwin, The Wrecks. The generic list said Harem Scarem and Creedence Clearwater Revisited.
  • Film night (fit 0.90): Booksmart, Once Upon a Time in… Hollywood, Love, Simon, Mid90s.
  • Offers ranked: Taylor Swift, Ed Sheeran, Mac Miller, Wiz Khalifa, Bruce Springsteen.
  • Promotion heatmap hotspots centred on Pittsburgh (40.44, −80.00).
  • About 20 live Qloo calls per plan, all visible in the trace.

How we built it

Python 3 + Flask serve a single-page UI (no build step, no external assets) and a JSON API (POST /api/plan, GET /api/presets, GET /healthz). Deployed on Render from a Dockerfile. Configs for Vercel and Docker hosts are included.

Agent design. A tool-using agent with an observe → act → check → adapt loop (crowd_compass/agent.py). Each step records what it did and why in a trace that the UI shows.

Agent tool Qloo endpoint and parameters Purpose
resolve_seeds GET /search (query, types, take) Turn past hits ("ABBA", "Red Dog") into Qloo entity IDs
fingerprint GET /v2/insights filter.type=urn:tag, signal.location.query, signal.demographics.age (with and without location) What the town over-indexes on
local_taste GET /v2/insights filter.type=urn:entity:{artist,movie,tv_show}, signal.interests.entities, signal.location.query, signal.demographics.age, filter.popularity.max (budget), feature.explainability Candidates per event format, with "because your crowd loved X"
adapt same, widened to fallback_region Small towns can return thin data: widen, then say so on the card
generic_taste same query without location The culturally blind baseline
local_lift comparison Local top picks missing from the generic top list
rank_shortlist GET /v2/insights filter.results.entities=<offers> (local and generic) "Which of these offers should we book?"
promote_where GET /v2/insights filter.type=urn:heatmap, filter.location.query, signal.interests.entities=<headliner> Where to put flyers and ads

Robust Qloo client (crowd_compass/qloo.py): tolerant of the documented response shapes; bounded retries on 429/5xx with exponential backoff, jitter and Retry-After; fail-fast on 401/403; a thread-safe TTL + LRU cache; typed errors so optional steps can be skipped without breaking the plan. The app falls back from live API to recorded real snapshots to clearly labelled sample data, so judges always get a working demo. The API key stays on the server and never reaches the browser, logs or trace. A pytest suite covers the client, agent, app and MCP server.

Challenges we ran into

  • Thin signal in small towns. A mining town has far less taste data than a big city. We built the adapt step: detect a thin result, widen to the region the owner supplies, and label the card so nobody is misled.
  • Proving Qloo makes a difference. "Better recommendations" is easy to claim. We ran every query twice, with and without location, so the local lift is visible on screen and not just asserted.
  • Location and baseline edge cases. Some live queries behave differently from the docs. For example, the location-free baseline for tag insights needs an interest or tag signal, and ambiguous town names can resolve to the wrong place. The agent records these in the trace and skips the optional step without breaking the plan. Tightening this is ongoing.
  • Keeping it demo-proof. Live APIs fail at the worst moment, so we built the live → snapshot → labelled-sample fallback chain.

Accomplishments that we're proud of

  • A complete product, not a proof of concept: brief in, bookable plan out, with a pitch, an offer ranking and a promotion map.
  • The side-by-side local vs generic view makes Qloo's value visible to a non-technical pub owner in seconds.
  • A fully transparent agent: every Qloo call and decision is on screen, so you can audit it.
  • The same agent works as an MCP tool, so other agents can gain cultural grounding.
  • Responsible defaults: no personal data sent (just a town, an age bucket and public entity names), human approval for everything, and limitations stated in the UI.

What we learned

  • Location changes the answer far more than we expected. The generic and local top-5 lists often had no overlap at all.
  • Explainability ("because your crowd loved X") is what turns a list into something an owner will trust.
  • Agents need guardrails around data quality: knowing when a signal is thin, or a location looks wrong, matters as much as the recommendation.

What's next for Crowd Compass

  • Stronger location handling: confirm the resolved town before planning, and use explicit coordinates for small towns.
  • Learning from outcomes: log ticket sales from each night and feed back which seeds really packed the room.
  • More formats (comedy, food pop-ups, themed dining menus using Qloo places and dining tags) and calendar-aware planning across a month.
  • Integrations: post approved nights to Eventbrite and social channels, and send flyer targeting straight into ad platforms, always behind human approval.
  • A pilot with a handful of regional pubs and bowling alleys.

Built With

Share this project:

Updates

Submission history