[bryanshao07]

Summary

Adds a unified retrieval layer to the CrossOver backend, powering two features from one precomputed artifact set:

• Semantic player search — GET /search?mode=semantic embeds a natural-language query and ranks players by cosine similarity over precomputed style-card embeddings. Falls back to the existing substring search when unavailable.
• Grounded explanations — /explain now injects each player's retrieved style card into the Gemini prompt, so bullets reference concrete stylistic facts instead of paraphrasing raw attribute numbers. (Replaces the previously-unused stats_a/stats_b params.)

Everything degrades gracefully: with no artifacts or no GEMINI_API_KEY, the app behaves exactly as before.

How it works

• Offline build script backend/scripts/build_rag.py generates a ~3-sentence style card per player from their raw stat line (gemini-2.5-flash) and embeds it (text-embedding-004), writing exports/style_cards.json + exports/style_embeddings.json (idempotent/resumable, atomic writes).
• data_store loads these once at startup into an L2-normalized NumPy matrix (same in-memory approach as sim_matrix.csv — no vector DB; ~585 players). Resilient to both missing and corrupt artifacts.
• services/rag.py embeds queries (lru_cached) and ranks by cosine.

Design & plan

• Spec: docs/superpowers/specs/2026-07-29-rag-layer-design.md
• Plan: docs/superpowers/plans/2026-07-29-rag-layer.md

Testing

New hermetic tests for the data layer, rag service, semantic search, explanation grounding, and the build script's prompt builder. Full backend suite green except 3 pre-existing auth tests that require a local PostgreSQL (unrelated to this branch).

Follow-up (not in this PR)

• Generate + commit the artifacts (python -m scripts.build_rag). Currently pending — the available API key is rate/quota limited. Until the artifacts exist, semantic search falls back to keyword and explanations stay ungrounded (by design).
• Frontend "smart search" toggle on the results page (separate increment).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
crossover	Ready	Preview	Jul 31, 2026 6:39am

[bryanshao07]

Artifacts generated + committed ✅

The RAG artifacts are now built and included in the branch:

• 585/585 style cards (exports/style_cards.json, 318K) — 0 empty
• 585/585 embeddings (exports/style_embeddings.json, 24M) — all 3072-dim, none missing

Model migration (required): the target account 404s on the originally-specced gemini-2.5-flash ("no longer available to new users") and text-embedding-004 (not served on this API version). Switched to gemini-flash-latest (cards) and gemini-embedding-001 (embeddings), with both IDs centralized in config.py as the single source of truth so the offline document build and the runtime query embedding can never drift apart. Also added 429/504 backoff+retry to the build script.

Live sanity check (real embeddings, mode=semantic):

• "lockdown perimeter defender with elite passing" → Davion Mitchell, Kawhi Leonard, Derrick White, OG Anunoby
• "high-volume three point sharpshooter" → DiVincenzo, A.J. Green, Grayson Allen, Stephen Curry
• "dominant physical rim protector" → Clingan, Zubac, Anthony Davis, Mark Williams

Note on repo size: the embeddings file is 24 MB (3072-dim vectors). Committed per decision, consistent with other precomputed files in exports/. If repo weight is a concern later, gemini-embedding-001 supports output_dimensionality reduction (e.g. 768/1536) which would shrink it ~2–4× at a small recall cost — a one-line change + rebuild.