The Hat Trick

GitHub Repo

Inspiration

We wanted to combine autonomous AI workflows with real-world sports data—no API keys, no paid datasets—and make 2026 World Cup predictions that are transparent and explainable. The “hat trick” of winner, Golden Ball/Boot/Glove, and Young Player felt like the right set of goals to showcase planning, tool use, and interpretable results in one demo.

What it does

The Hat Trick is an autonomous AI workflow that predicts 2026 World Cup outcomes. Users pick a goal (World Cup winner, Golden Ball, Golden Boot, Golden Glove, or Young Player), run the workflow, and get top-five predictions with a description (who they are, key stats) and a reason (how the algorithm scored them). All data comes from the Wikipedia API—qualified teams, FIFA rankings, rosters, player pages, and historical World Cup results—with curated fallbacks so predictions still run when the API is empty or slow. Results are saved to JSON and viewable in a simple web UI with country flags and step-by-step execution.

How we built it

• Backend: FastAPI app with a workflow engine that turns a goal into a plan (up to 10 steps), executes tools in order, and persists state in JSON memory. Tools in tools.py fetch data (teams, rankings, rosters, player info, historical results) via wikipedia.py, then run scoring functions for each prediction type.
• Wikipedia integration: Custom client that hits the Wikipedia API for qualification, FIFA ranking, squad lists, player honours/caps/goals, and past World Cup results. Responses are cached under data/cache/ with a 24h TTL. Fallback lists of teams and star players cover gaps when parsing fails.
• Scoring: Team winner uses weighted factors (FIFA 25%, historical 20%, form 25%, squad 20%, home advantage 10%). Each player award has its own formula (e.g. Golden Ball: honours + rating + goals; Golden Glove: clean sheets + rating). Every top-five result includes a human-readable description and reason.
• Frontend: HTML/CSS/JS served by FastAPI. Goal selector, bullet-list explanations per goal, “Run workflow” button, step-by-step execution view, and result cards with crests, descriptions, reasons, and report links.

Challenges we ran into

• Wikipedia API shape: Response structure varies by page (e.g. rvslots vs plain content, different table/list formats). We had to add robust parsing and fallbacks for qualified teams, FIFA ranking, rosters, and player pages so the app never broke on missing or odd data.
• Rosters and positions: Extracting “Current squad” and mapping players to positions (GK, DEF, MID, FWD) from inconsistent section headers required flexible parsing and index-based fallbacks when subsections weren’t present.
• Player-level data: Getting honours (Ballon d’Or, Golden Boot, etc.), caps, and goals from individual Wikipedia player pages was brittle. We introduced known-player fallbacks and enrichment logic so Golden Ball/Boot/Glove/Young Player predictions stay high quality even when live parsing fails.
• Crests and flags: Reliable country flags for every team/player meant dealing with hotlinking and missing URLs. We added a server-side fallback map (e.g. FlagCDN) and client-side resolution so crests always display.

Accomplishments that we're proud of

• Fully API-driven predictions with no mock data: teams, rankings, rosters, and player stats come from Wikipedia, with sensible fallbacks.
• Interpretable results: Every prediction has a description and a reason, so users see not just “who” but “why.”
• Single workflow for five goals: One engine handles team winner and four player awards with clear separation of scoring logic and tool use.
• No API keys: Entire demo runs on public Wikipedia API and cached responses.
• Demo-ready UI: Step-by-step execution, goal descriptions, and result cards with flags make it easy to present and iterate.

What we learned

• Designing for inconsistent external APIs (Wikipedia) works best with layered fallbacks and clear separation between “fetch” and “score.”
• Interpretable ML—exposing description and reason per prediction—makes the system more trustworthy and easier to debug.
• Caching and fallback lists are essential for a smooth demo when network or parsing fails.
• A small set of well-scoped goals (winner + four awards) kept the workflow and UI manageable without sacrificing depth.

What's next for The Hat Trick

• Live data: Optional hooks to FIFA or other APIs when available, while keeping Wikipedia + fallbacks as the default.
• More goals: e.g. group-stage qualifiers, breakout teams, or “dark horse” predictions.
• User inputs: Let users adjust weights (e.g. more weight on historical performance) or lock in certain teams/players and re-run.
• Comparison mode: Side-by-side runs for different goals or different “what-if” assumptions.
• Export and sharing: One-click export of results and reasons (PDF or shareable link) for post-demo use.

Built With

• fastapi
• html/css/javascript
• minimax
• pydantic
• python
• uvicorn
• wikipedia-api