⚽ Football Match Prediction Pipeline

📘 Visão Geral

Este projeto implementa um pipeline completo de Machine Learning para previsão de resultados de jogos de futebol (vitória, empate ou derrota).
O pipeline é composto por três etapas principais:

1. Treinamento inicial — cria o modelo e gera as features base a partir do histórico de partidas.
2. Ingestão e predição — consome dados de jogos futuros via API, aplica o modelo e envia as previsões ao Looker.
3. Retreinamento — atualiza o modelo automaticamente com os resultados reais dos jogos e substitui o modelo antigo se houver melhoria de performance.

O objetivo é manter um fluxo automático, reproduzível e escalável, garantindo consistência entre treinamento, predição e retreinamento — todas as etapas utilizam a mesma função central de feature engineering.

---

🏗️ Estrutura do Projeto

📦 projeto_futebol/
│
├── data/
│   ├── raw/               # Dados brutos da API e históricos
│   ├── processed/         # Dados tratados e com features
│   └── predictions/       # Previsões recentes enviadas ao Looker
│
├── models/
│   ├── catboost_model.pkl # Modelo treinado
│   └── scaler.pkl         # Normalizador/encoder (opcional)
│
├── src/
│   ├── api/
│   │   └── fetch_matches.py       # Acesso à API de jogos (futuros e passados)
│   ├── features/
│   │   └── feature_engineering.py # Criação de features consistente
│   ├── model/
│   │   ├── train.py               # Treinamento inicial
│   │   ├── predict.py             # Predição de novos jogos
│   │   └── retrain.py             # Retreinamento automático
│   ├── looker/
│   │   └── send_predictions.py    # Envio de resultados ao Looker (via DB ou API)
│   └── utils/
│       ├── logger.py              # Log centralizado
│       └── config.py              # Configurações globais (chaves, paths, etc.)
│
├── logs/
│   └── pipeline_YYYYMMDD.log
│
├── pipeline.py                    # Orquestração principal
├── requirements.txt
└── README.md

---

⚙️ 1. Treinamento inicial (train.py)

• Usa dados históricos de partidas com resultados conhecidos.
• Executa pré-processamento, criação de features e treinamento do modelo
• Salva o modelo em models/ e o dataset processado em data/processed/.

Exemplo de uso:

python pipeline.py --train

---

📥 2. Ingestão e predição (predict.py)

• Consulta jogos futuros via API-Football (ou API similar).
• Gera as mesmas features usadas no treinamento.
• Carrega o modelo salvo e calcula probabilidades de vitória, empate e derrota.
• Envia as previsões ao Looker (via banco SQL ou API REST).

Exemplo:

python pipeline.py --predict

---

🔁 3. Retreinamento (retrain.py)

• Busca novos resultados reais (status = “finished”) da API.
• Atualiza o dataset histórico.
• Recria as features e treina novamente o modelo.
• Compara o F1-score do novo modelo com o anterior.
• Se o novo modelo for melhor → substitui o antigo e salva o histórico atualizado.

Exemplo:

python pipeline.py --retrain

---

🧩 Engenharia de Features (feature_engineering.py)

A função create_features(df, is_train=True) é o coração do projeto.
Ela garante que o mesmo conjunto de transformações seja aplicado em todas as etapas (treino, predição e retreino).

Exemplo:

def create_features(df, is_train=True):
    df["avg_goals_home"] = df.groupby("team_home")["goals_home"].transform(lambda x: x.rolling(5, min_periods=1).mean())
    df["avg_goals_away"] = df.groupby("team_away")["goals_away"].transform(lambda x: x.rolling(5, min_periods=1).mean())
    df["goal_diff"] = df["avg_goals_home"] - df["avg_goals_away"]
    features = ["avg_goals_home", "avg_goals_away", "goal_diff"]
    target = "resultado" if is_train else None
    return df[features], df[target] if is_train else (df[features], None)

---

🧠 Orquestração (pipeline.py)

Controla a execução das três etapas principais, com logs automáticos e tratamento de erros.

run_pipeline(
    train=False,     # Rodar apenas na primeira execução
    predict=True,    # Executar diariamente (novos jogos)
    retrain=True     # Executar semanalmente (com resultados)
)

---

📊 Integração com Looker

As previsões geradas são enviadas automaticamente para o Looker, permitindo:

• Dashboards interativos com probabilidade de resultado.
• Comparação entre previsões e resultados reais.
• Monitoramento da acurácia ao longo do tempo.

---

🧮 Dependências

pip install -r requirements.txt

---

🧰 Agendamento

cron:

# Predição diária às 08h
0 8 * * * /usr/bin/python3 /path/pipeline.py --predict

# Retreinamento semanal (domingo 23h)
0 23 * * SUN /usr/bin/python3 /path/pipeline.py --retrain

---

🧾 Métricas de Avaliação

• Accuracy
• F1-Score ponderado
• Precision e Recall
• Matriz de confusão

---

👨‍💻 Autores

Jader Campos
Carlos Eduardo
Fabricio Viana
Projeto acadêmico e profissional de Machine Learning aplicado a esportes.

---

🧠 Licença

Licença MIT License — uso livre com atribuição.