World Cup Scout 2026

Inspiration

The 2026 FIFA World Cup kicks off June 11 — the same day as this hackathon deadline. Professional clubs are making their final scouting decisions right now, yet most analysts still rely on spreadsheets and manual data pulls. I wanted to build something that demonstrates what AI-native sports analytics actually looks like: an agent that reasons over real data, answers natural language questions, and produces professional scouting reports on demand.

What It Does

Scout WC26 is an AI-powered football scouting agent that gives analysts instant access to player intelligence across 10 verified football leagues. Key capabilities:

• Natural language queries — ask "who are the best midfielders?" or "show me the England squad" and get grounded, data-backed answers
• Multi-league support — switch between UEFA WC Qualification, Premier League, Champions League, La Liga, Bundesliga, Serie A, Ligue 1, MLS, Brasileirao, and Scottish Prem with instant cache-first switching
• AI scouting reports — generate structured player assessments with key strengths, performance stats, and recruitment recommendations, downloadable as PDF
• Live analytics dashboard — BigQuery-powered charts, team browser with squad drill-down modals, top performers leaderboard
• Smart error handling — cross-league player lookup, accent folding (Mbappé, García), and "switch & retry" UX for players in unloaded leagues

How I Built It

Data Layer — Fivetran + BigQuery The foundation is a custom Fivetran Connector SDK integration that ingests live football data from the API-Football endpoint into BigQuery. Data flows through three layers:

• Bronze — raw API snapshots, idempotent writes using load jobs (not streaming inserts)
• Silver — cleaned, normalized player and match records with deduplication
• Gold — aggregated player stats and team summaries ready for the agent to query

Agent Layer — Gemini + ADK The Gemini 2.5 Flash agent has 9 purpose-built BigQuery tools: query_players, query_team_summary, get_player_detail, get_top_players_by_position, get_league_overview, get_team_roster, get_top_performers, refresh_scouting_data, and switch_league. A lightweight regex routing layer pre-processes every query before it reaches the agent, routing report requests cross-league and switch requests directly — reducing unnecessary agent calls. The project also includes a Google ADK 2.1.0 migration (scout_adk/ module) satisfying the Agent Builder requirement.

Backend — FastAPI on Cloud Run A FastAPI application deployed on Google Cloud Run (us-central1) exposes 15+ endpoints including the agent query endpoint, league switching with cache-first fast-path, team detail API, match scores, and PDF report generation.

Challenges

BigQuery streaming insert bloat — early iterations used streaming inserts which created 646,000+ duplicate rows (one player had 10,384 copies). The fix was rewriting all Bronze writers to use load jobs with explicit DELETE-then-INSERT, making writes fully idempotent. Row counts dropped from 1M+ to ~2,000 clean records.

League ID verification — API-Football uses non-obvious league IDs that change by season. Built a programmatic verifier that tests each candidate ID across 2024/2025/2026 seasons and picks the most recent season with actual data. Discovered Bundesliga was silently mapped to wrong ID (78→54).

Cold start 503s — Cloud Run was crashing on startup because Config() ran at import time, failing if env vars weren't set. Fixed with lazy initialization and bumped to 2Gi/2CPU/min-instances=1.

Unicode player names — "Mbappe" wouldn't find "Mbappé". Implemented accent folding using Python's unicodedata module applied to all player lookup queries.

What I Learned

Building a production-quality data pipeline is harder than building the AI on top of it. The Fivetran Connector SDK enforces good practices around idempotency and schema management that I had to learn the hard way. The Bronze/Silver/Gold pattern genuinely earns its complexity — having a clean Gold layer made the agent tools trivial to write.

What's Next

With the World Cup starting today, the pipeline is ready to ingest live match data from day one. The next step is adding real-time goal and substitution events to the agent's context so it can answer "who scored in the last match?" with live data, not just historical stats.

Built With

• api-football-(rapidapi)
• css
• fastapi
• fivetran-connector-sdk
• fivetran-rest-api
• google-agent-development-kit-(adk)-2.1.0
• google-bigquery
• google-cloud-build
• google-cloud-run
• google-gemini-2.5-flash
• html
• javascript
• pytest
• python
• reportlab