Headliner

An AI tour planning agent powered by Qloo's taste data. Type an artist, comedian, sports club or podcast, and a realistic 3D Earth lights up with a worldwide tour: where the fans are, which venues fit, who should open, who should sponsor, and the route between them.

Built for the Qloo Agentic Hackathon ("Agents, but with taste").

Live demo	Headliner
Code	This repository (MIT license)
Taste data	Qloo API (hackathon environment)
AI model	OpenAI API, model set by OPENAI_MODEL (the "luna" model)

---

Contents

1. The idea
2. What it does
3. Architecture
4. How Qloo is integrated
5. How the AI model is used
6. Route, dates and exports
7. The front end
8. API reference
9. Caching and performance
10. Project structure
11. Run it, warm it, deploy it
12. Honesty, limits and data handling
13. How it answers the judging criteria
14. Credits and license

---

1. The idea

Touring is a multi million dollar bet, and cities are usually picked from past ticket sales and gut feel. Past sales only show where an act already plays. They miss the cities that want a show and have never had one. Openers, venues, sponsors and local marketing are then planned in separate tools by separate people.

A plain language model cannot fix this. It has no live cultural data, so it guesses.

Headliner uses Qloo's taste graph as the source of truth. Qloo knows what people in a place love, and how closely an act's fans match them. The agent reads that signal for 99 cities in 7 regions, picks the strongest and most spread out markets, and builds the whole plan from it. A language model is used only to write and to check, never to invent the data.

It works for anything Qloo knows, so the same product covers four worlds:

Input	Example	"Support slot" becomes
Musician or band	Coldplay, A. R. Rahman, Bad Bunny	Opener
Comedian or actor	Dave Chappelle, Cedric the Entertainer	Opener
Sports club	Chelsea F.C., Los Angeles Dodgers	Friendly opponent (a preseason world tour)
Podcast	This Week in Startups	Guest show (live recordings)

---

2. What it does

One input gives a full, explainable tour plan.

• Worldwide scan. Scores 99 cities across North America, Latin America, Europe, Africa, the Middle East, Asia and Oceania by how well each city's places match the act's fans.
• Balanced route. On a worldwide tour every region with data gets stops first, then the rest are filled by score, so the route spans the globe instead of piling up in one continent.
• Real venues. Qloo returns stadiums, arenas, concert halls, theatres and clubs near each city, ranked by fan fit. The model then checks which of them actually host concerts.
• Popularity. A tier and rank for every city, a popularity by region chart, and global reach from Last.fm.
• What made them popular. A "known for" list (songs, albums, specials, seasons, episodes) and a suggested set to lead with in each city. This part comes from the model and is labelled.
• Best support slot. Chosen by audience overlap from Qloo, not by genre label.
• Sponsors. Brands whose fans look like the act's, each with a short reason tied to the city.
• VIP and fan plan. Restaurants, bars and nightlife near each show that the fans rank highly.
• Route optimizer. Shortest path, west to east, or highest demand first, with leg distances, travel days, a tour length and dates.
• Edit the tour. A dim dot on the globe for every scored city, a "next best markets" list, and Add or Remove buttons that rebuild the route.
• Any artist worldwide. Type ahead search over Qloo's catalogue with photos, for acts, comedians, clubs and podcasts.
• Exports. PDF brief, CSV, calendar (.ics) and JSON.
• Never blank. Saved plans replay in about 3 seconds, and if Qloo is unreachable the app falls back to clearly labelled sample data.

---

3. Architecture

3.1 System overview

flowchart TB
    subgraph Browser["Browser (Next.js client)"]
        UI["Landing page and Plan page<br/>React components"]
        AS["ArtistSearch<br/>type ahead combobox"]
        GL["GlobeView<br/>globe.gl + three.js<br/>day/night Earth shader"]
        RT["route.ts<br/>nearest neighbour + 2-opt<br/>dates and legs"]
        EX["export.ts<br/>CSV, ICS, JSON, PDF"]
        PC["planClient.ts<br/>reads the event stream<br/>falls back to sample data"]
    end

    subgraph Server["Next.js server (Node runtime)"]
        R1["GET /api/search"]
        R2["GET /api/plan<br/>Server-Sent Events"]
        R3["GET /api/stop<br/>add one stop"]
        AG["agent.ts<br/>runPlan / addStop"]
        QC["qloo.ts<br/>typed client, retry,<br/>in-memory cache"]
        LL["llm.ts<br/>OpenAI JSON client"]
        PL["planCache.ts<br/>saved plans"]
    end

    subgraph External["External services"]
        QL[("Qloo API<br/>hackathon.api.qloo.com")]
        OA[("OpenAI API")]
        UP[("Upstash Redis<br/>optional")]
    end

    AS --> R1
    PC --> R2
    UI --> R3
    R1 --> QC
    R2 --> PL
    R2 --> AG
    R3 --> AG
    AG --> QC
    AG --> LL
    QC --> QL
    LL --> OA
    PL -. "if configured" .-> UP
    PL -. "otherwise .cache/plans" .-> FS[("Local file cache")]
    PC --> UI
    UI --> GL
    UI --> RT
    UI --> EX

This is the beginning of the README. Read the rest at the original. Read the full README ↗