PROJECT / soccer-analytics-agent
Soccer Analytics Agent — Football analytics agent
Chat agent over ~49k international matches (1872–today) built with a hand-written LLM tool loop, no agent framework. Gemini reasons and calls tools; Postgres + pgvector is the single layer for data, memory, and observability. A learning-first replication of Oracle's workshop on an open, GCP-deployable stack.
Problem
Agent frameworks hide how an agent actually works. To understand the mechanism you have to write the loop by hand: when the model answers, when it delegates to a tool, how memory is wired.
What I did
Wrote the agent as a pure while loop over the google-genai SDK: the model emits text or asks to run tools, and my runtime executes them and feeds results back. A generalist (Gemini) that delegates to small local specialists: MiniLM for embeddings (384 dims) and a multiclass XGBoost outcome predictor (51 features, with an Elo fallback). Hybrid retrieval over 49k documents (pgvector + Postgres full-text, fused with RRF), three-tier memory (working, episodic, semantic), an Elo tracker for 336 national teams, and observability that persists every step of every turn. 9 tools, FastAPI + React frontend, on the way to Cloud Run.
Highlights
- Hand-written LLM tool loop over the google-genai SDK — no agent framework at all.
- A generalist (Gemini) delegating to cheap local specialists: MiniLM for embeddings, XGBoost for outcome prediction (with an Elo fallback).
- Hybrid retrieval over ~49k matches: pgvector + Postgres full-text, fused with Reciprocal Rank Fusion.
- Three-tier memory — working, episodic, and semantic.
- Observability that persists every step of every turn; an Elo tracker for 336 national teams and 9 tools.
Stack
- Python 3.12
- Gemini
- Vertex AI
- Postgres 16
- pgvector
- MiniLM
- XGBoost
- FastAPI
- React
Links