How I Built This

nba_api is the Python wrapper around the official stats.nba.com endpoints — player game logs, advanced stats, play-by-play, lineup data. A daily APScheduler job inside the FastAPI server refreshes the live scoreboard and the next 14 days of upcoming games so the demo stays current through the Finals.

Players, games, player_game_stats, and play_by_play (top 30 only, because pbp explodes in row count). The interesting field is is_clutch_data — a flag that lets clutch-specific questions narrow to the clutch sub-table without scanning the whole season.

Articles and Reddit threads scraped politely (robots.txt, no OAuth — Reddit's public .json endpoints are enough). Aim was ~500-1000 chunks tagged with date, mentioned players, and source. Today's corpus has 197 Reddit threads (257 chunks) covering r/nba and team subs.

Every name variant resolves to a canonical player_id: "Steph", "Curry", "the Chef", "Wardell" all map to 201939. The map has 1,525 aliases today; 90%+ coverage of the active roster, 100% on the top 30. Every scraped chunk runs through this normalizer before embedding so a player filter at retrieval time is a single integer match instead of a fuzzy string game.

Why "unsexy gold": entity linking is a real production problem every sports data company solves. Pointing at this in interviews signals "I've shipped data systems", not "I followed a RAG tutorial".

Chunks are 400 tokens with 15% overlap. Voyage voyage-3-large (1024-dim) embeddings, stored in the same Postgres DB via pgvector. Contextual-retrieval prefix ("Article from {source}, {date}, about {players}: …") is prepended before embedding for a 35-50% recall lift on hard queries.

For each top-30 player, a one-time enrichment job pulls every chunk mentioning them and asks Claude Opus to write a 500-word scouting summary covering strengths, weaknesses, playoff performance, and trends. Stored as a single chunk with article_type = 'authored_summary' and a higher retrieval prior so the synthesis layer gets a strong baseline on Tier-2 players.

The heart of the project. A Sonnet 4.5 classifier with few-shot examples reads the question and returns {route, reasoning} . stats → text-to-SQL on Postgres. prose → vector search with Cohere Rerank. hybrid → SQL filter to narrow the player set, then vector search inside that set. The reasoning string surfaces in the trace sidebar so the decision is auditable.

A follow-up turn passes a short conversation history into the hybrid SQL prompt so pronouns like "him" can resolve against the previous answer.

Retrieved stats and chunks go to Claude Opus 4.6. The key UX move: the UI shows exactly what happened — the SQL that ran, the chunks that came back, the router's reasoning, and the model's cited paragraphs. Visible tool use is what makes the demo legible.

30 test queries, stratified: 10 stats, 10 prose, 10 hybrid. Each case has an expected route, expected SQL or chunk ids, and a model-graded answer rubric. Router accuracy, SQL correctness, and retrieval recall are tracked separately so a regression in one path doesn't hide behind another's wins.

Next.js 15 App Router, Tailwind, framer-motion, deployed locally for the demo. The visible-tool-use sidebar shows router decision, SQL panel, retrieved chunks, citations. A live RAG pipeline banner animates per stage on every turn, and copy buttons land question / answer / trace on the clipboard for follow-up workflows.