GigRoute

Route your next tour to where your fans already are.

GigRoute is a taste-grounded tour planner for independent musicians, built on the Qloo Taste AI Insights API. Enter your artist (or a better-known artist you sound like) and a region. An agent then:

1. resolves the artist in Qloo and finds similar artists for local co-bills,
2. ranks the cities where audiences for that taste over-index (fan hotspots),
3. ranks venues, bars and record shops in each city by audience affinity,
4. finds cross-domain tastes (brands, films) for merch and poster ideas,
5. orders the stops into a route and drafts a data-backed pitch for each venue.

Every city and venue has a “Why this city / venue?” panel built from Qloo's query.affinity and query.explainability: the affinity score, the tags that match your sound, and the artists whose fans drove the result.

Try it in one click: the landing page has a “See a sample tour” button (Radiohead · UK). It always runs on built-in sample data, so it works instantly with no keys.

Quick start

Requires Node 20 or 22 (see .nvmrc).

nvm use            # optional, picks Node 22
npm ci
npm run dev        # http://localhost:3000

With no environment variables, the app runs in mock mode: a deterministic mock LLM drives the agent against hand-written fixture data. No network calls are made to Qloo or to any LLM.

Command	What it does
npm run dev	Development server
npm run build / npm start	Production build and server
npm test	Vitest unit tests (all mocked, no network)
npm run lint	ESLint
npm run contract-check	Optional live contract check against Qloo (see below).

Live contract check (when the Qloo key arrives)

The key lives only in your shell for the length of one command. It is never written to a file or committed:

QLOO_API_KEY=... npm run contract-check

The script (scripts/qloo-contract-check.ts) makes one real request per endpoint GigRoute uses (search, similar artists, fan hotspots, venues with explainability, brand and movie cross-domain, tags) and checks that the response has the fields the app reads. It prints one line per check, with counts and field names only. It never prints response data or the key (anything it prints is scrubbed of the key as a safeguard).

PASS  GET /search (artist): 10 artists; fields: id, name, type, popularity, tags, explainability
PASS  /v2/insights filter.type=urn:entity:place (venues in London) + explainability: 5 places; ...; explainability on 5/5
FAIL  /v2/insights filter.type=urn:entity:movie (cross-domain): Qloo 403: entity type or endpoint not enabled for this key

• PASS: the endpoint answered and the fields GigRoute needs are there.
• FAIL: the message says what was missing or which HTTP error came back (401 means a bad key or base URL, 403 means the entity type isn't enabled for the key, 400 means a parameter is rejected).
• SKIP: /search failed, so the checks that need an artist ID didn't run.
• Exit code 0 means everything passed; 1 means at least one check failed or was skipped. With no key set it calls nothing, prints a skip message and exits 0.

Environment variables

Set these in .env.local for local development (it is gitignored) or in Vercel → Project → Settings → Environment Variables. Never commit real values.

Variable	Required	Example (empty means unset)	Purpose
QLOO_API_KEY	For live Qloo	QLOO_API_KEY=	Sent as the X-Api-Key header. If empty, mock mode is used.
QLOO_BASE_URL	No	QLOO_BASE_URL=	Defaults to https://hackathon.api.qloo.com.
QLOO_MOCK	No	QLOO_MOCK=	Set to 1 to force mock Qloo data even when a key is present.
LLM_BASE_URL	No	LLM_BASE_URL=	Any OpenAI-compatible chat completions endpoint. Defaults to OpenAI.
LLM_API_KEY	For a live LLM	LLM_API_KEY=	If empty, the deterministic MockLLM plans the tour.
LLM_MODEL	With LLM_API_KEY	LLM_MODEL=	Model name for the endpoint above. Must support tool calling.
NEBIUS_API_KEY	No	NEBIUS_API_KEY=	Enables Nebius Token Factory summary rewrite when non-empty.
NEBIUS_BASE_URL	No	NEBIUS_BASE_URL=	Defaults to https://api.tokenfactory.nebius.com/v1/.
NEBIUS_MODEL	No	NEBIUS_MODEL=	Defaults to nvidia/nemotron-3-super-120b-a12b.
NEBIUS_TIMEOUT_MS	No	NEBIUS_TIMEOUT_MS=	Defaults to 20000.
NEBIUS_REASONING	No	NEBIUS_REASONING=	Empty = reasoning off (reasoning_effort: none + chat_template_kwargs.enable_thinking: false). Set default to omit both fields.

Going live: set QLOO_API_KEY (and leave QLOO_MOCK unset). That is the only change. The real client already sends the documented requests (see below). The LLM is independent: with no LLM key, the mock LLM drives the real Qloo client.

Nebius Token Factory (NVIDIA Nemotron)

GigRoute includes an optional, non-blocking final step that passes the deterministic tour summary and the Qloo facts it was built from to NVIDIA Nemotron on the Nebius Token Factory for rewriting. Set NEBIUS_API_KEY to enable it. If it times out, throws an error, or the key is not set, GigRoute seamlessly falls back to the deterministic summary without failing the plan.

Deploy to Vercel

1. Push this repo to GitHub and Import Project in Vercel (framework preset: Next.js, defaults are fine).
2. Vercel reads "engines": { "node": ">=20 <23" } from package.json and uses Node 22.
3. Optionally add the environment variables above. Without them, the deployment runs fully in mock mode, which is good for a judging demo.
4. Deploy. /api/plan is a streaming (SSE) route function; / and /plan are static.

A build with QLOO_MOCK=1 and no LLM key is tested as part of CI-style verification (npm ci && npm run build && npm test && npm run lint).

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