PROJECT / soccer-analytics-agent
Soccer Analytics Agent — Agente de análisis futbolístico
Agente de chat sobre ~49k partidos internacionales (1872–hoy) construido con un tool-loop LLM escrito a mano, sin framework de agentes. Gemini razona y llama tools; Postgres + pgvector es la única capa para datos, memoria y observabilidad. Réplica learning-first del workshop de Oracle sobre stack abierto y deployable en GCP.
Problema
Los frameworks de agentes esconden cómo funciona un agente de verdad. Para entender el mecanismo hay que escribir el loop a mano: cuándo el modelo responde, cuándo delega en una tool, cómo se arma la memoria.
Qué hice
Escribí el agente como un while loop puro sobre el SDK de google-genai: el modelo emite texto o pide ejecutar tools, y mi runtime las ejecuta y le devuelve el resultado. Un generalista (Gemini) que delega en especialistas chicos y locales: MiniLM para embeddings (384 dims) y XGBoost multiclase para predecir resultados (51 features, con fallback a Elo). Retrieval híbrido sobre 49k documentos (pgvector + full-text de Postgres, fusionado con RRF), memoria de tres capas (working, episódica, semántica), tracker de Elo de 336 selecciones y observabilidad que persiste cada paso de cada turno. 9 tools, frontend FastAPI + React, camino a Cloud Run.
Destacados
- Tool-loop LLM escrito a mano sobre el SDK de google-genai, sin ningún framework de agentes.
- Un generalista (Gemini) que delega en especialistas locales y baratos: MiniLM para embeddings, XGBoost para predecir resultados (con fallback a Elo).
- Retrieval híbrido sobre ~49k partidos: pgvector + full-text de Postgres, fusionados con Reciprocal Rank Fusion.
- Memoria de tres capas — working, episódica y semántica.
- Observabilidad que persiste cada paso de cada turno; tracker de Elo de 336 selecciones y 9 tools.
Stack
- Python 3.12
- Gemini
- Vertex AI
- Postgres 16
- pgvector
- MiniLM
- XGBoost
- FastAPI
- React
Links