Projeto da Copa — API + Agente ADK

Probabilidade de vencedor de jogos de seleções, via modelo estatístico Poisson / Dixon-Coles, exposto como API REST (FastAPI) e consumido por um agente Google ADK com tools.

Arquitetura

results.csv ──> treinar.py ──> modelo.pkl
                                   │
                       ┌───────────┴───────────┐
                       │                        │
                  api.py (FastAPI)        copa_core.py (lógica)
                  GET /prever                   │
                       │                        │ (modo local)
                       └──────► copa_agent/tools.py ◄──────┘
                                       │
                              copa_agent/agent.py (Gemini)

Arquivos

Arquivo	Papel
results.csv	Base de jogos de seleções (1872–presente).
copa_core.py	Lógica do modelo: carrega dados, ajusta, prevê, cacheia.
treinar.py	Treina e salva modelo.pkl (rode 1x antes da API).
api.py	API FastAPI: /health, /times, /prever.
copa_agent/agent.py	Agente ADK (Gemini) com as tools.
copa_agent/tools.py	Tools: prever_resultado, listar_selecoes.

Como rodar

pip install -r requirements.txt
cp .env.example .env        # edite e coloque sua GOOGLE_API_KEY

# 1) treinar o modelo (gera modelo.pkl)
python treinar.py

# 2) subir a API
uvicorn api:app --reload --port 8000
#    docs interativas: http://localhost:8000/docs

# 3) rodar o agente ADK (em outro terminal)
adk web                     # abre a UI; escolha o agente "copa_agent"
# ou
adk run copa_agent

Endpoints da API

• GET /health — status e metadados do modelo.
• GET /times?busca=kor — lista/filtra seleções (nomes em inglês).
• GET /prever?casa=Mexico&fora=South Africa&campo_neutro=true — probabilidades.

Exemplo de resposta de /prever:

{
  "casa": "Mexico", "fora": "South Africa", "campo_neutro": true,
  "prob_vitoria_casa": 0.5883, "prob_empate": 0.2993, "prob_vitoria_fora": 0.1124,
  "gols_esperados_casa": 1.43, "gols_esperados_fora": 0.49,
  "placar_mais_provavel": "1-0"
}

Modos da tool

A tool acessa o modelo de dois jeitos (variável COPA_MODE):

• http (default): chama a API em COPA_API_URL. Bom para produção.
• local: importa copa_core no mesmo processo, sem precisar da API no ar.

Observações

• Nomes das seleções são em inglês (ex: Brazil, South Korea).
• Modelo usa os últimos 8 anos com ponderação temporal (jogos recentes pesam mais).
• Para re-treinar com dados novos: atualize results.csv e rode python treinar.py.