README.md

metadata

title: api-noticia
emoji: 📈
colorFrom: blue
colorTo: green
sdk: docker
pinned: false

Datalake de Notícias Esportivas — Bolão AI

Pipeline de coleta, transformação e previsão de resultados de bolão (1 / X / 2) com notícias esportivas, modelos estatísticos (Dixon-Coles + logística), motor tático KXL e interface web React.

Documentação completa

Índice central: docs/README.md

Guia	Descrição
Visão geral	Objetivo, fluxos, capacidades
Arquitetura	Camadas, pastas, integrações
Instalação	Setup, .env, troubleshooting
API REST	Todos os endpoints + exemplos
Modelos ML	Dixon-Coles, logística, KXL, EV
Datalake	Pipelines e CLIs
Frontend	UI React, rotas, componentes
KXL Colisão	Fórmulas táticas detalhadas
Glossário	Termos e siglas

Início rápido

pip install -e ".[dev]"
cp .env.example .env
import-world-cup --missing-only
./scripts/dev-api.sh          # terminal 1
cd frontend && npm run dev    # terminal 2

• API: http://localhost:8000/docs
• UI: http://localhost:5173

Arquitetura

flowchart LR
    subgraph Fontes
        GE[Globo Esporte]
        ESPN[ESPN BR]
        UOL[UOL Esporte]
        LANCE[Lance!]
    end

    subgraph Ingestão
        RSS[Coletor RSS]
    end

    subgraph Datalake
        B[Bronze\nJSON/Parquet bruto]
        S[Silver\nArtigos normalizados]
        G[Gold\nContexto por jogo]
    end

    subgraph ML
        DS[Dataset JSONL]
        LM[Fine-tuning LM]
        API[FastAPI]
    end

    GE & ESPN & UOL & LANCE --> RSS --> B --> S --> G --> DS --> LM --> API

Camadas

Camada	Conteúdo	Formato
Bronze	Feed RSS bruto + metadados	Parquet particionado por fonte/data
Silver	Artigos limpos, times mencionados, sentimento	Parquet
Gold	Contexto agregado por confronto (bolão)	Parquet + JSONL para treino

Fontes (RSS)

Configuradas em data/sources.yaml — adicione novas fontes sem editar código:

sources:
  - id: minha_fonte
    name: Minha Fonte
    url: https://exemplo.com/rss.xml

Fontes ativas:

ID	Portal
globo_esporte	Globo Esporte
espn_br	ESPN Brasil
uol_esporte	UOL Esporte
fogaonet	Fogaonet
gazeta_esportiva	Gazeta Esportiva

collect-news --list-sources   # ver todas as fontes ativas

Priorizamos RSS por ser legal, estável e respeitar robots.txt. Scraping de HTML completo é opcional (--fetch-body).

Setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

Uso

1. Coletar notícias (contínuo)

daily-sync              # coleta + silver (use 2-3x/dia)
collect-news            # só bronze

Agende com cron (scripts/cron_collect.sh) ou GitHub Actions (.github/workflows/daily-collect.yml).

2. Importar resultados do Brasileirão (ground truth)

import-brasileirao                    # temporadas 2022, 2023, 2024
import-brasileirao --seasons 2024     # temporada específica

Fonte: openfootball/south-america (domínio público).

2b. Base histórica da Copa do Mundo

import-world-cup --list              # edições na fonte vs lake local
import-world-cup --missing-only      # importa só o que falta (1930–2022)
import-world-cup --seasons 1970 1982 2022
import-world-cup --force             # reimporta todas as edições

Fonte: openfootball/worldcup (1930 a 2022). Após importar, reinicie a API para os modelos WC recarregarem os jogos.

2c. Baselines táticos KXL (Copa 2026)

Perfis vetoriais por seleção em data/wc/team_baselines.json (48 times). O palpite WC mistura 75% ensemble histórico + 25% DNA KXL e inclui matchup setorial no context.

python3 scripts/import_wc_baselines.py "/caminho/DADOS PARCEIAIS ... COPA.txt"

Fase 3 — motor de colisão: pipelines/wc_kxl_collision.py e fórmulas em docs/kxl-colisao.md (Vcar, Vesc, TBRTL, colisão setorial, letalidade×GK cabeça/fora/área/BP, EACP). UI: gramado interativo + painel Letalidade×Goleiro.

Fase 2 — entrada dinâmica (opcional no POST /worldcup/predict): exemplo completo em data/wc/kxl_match_example.json. Campos alinhados ao PDF: previsao_chuva_pct, estado_gramado, mandante_titulares_notas (goleiro/defensores/meio/atacantes), impacto_nota_elenco, contexto_peso_caos.

{
  "home_team": "Brasil",
  "away_team": "Marrocos",
  "phase": "group",
  "kxl_match": {
    "fecl": { "previsao_chuva_pct": 55, "estado_gramado": "Molhado" },
    "feju": { "perfil": "punitivista", "indice_cartao_falta": 0.28 },
    "fede": {
      "desfalques_visitante": [
        { "jogador": "Ziyech", "impacto_nota_elenco": -0.8 }
      ]
    },
    "fept": {
      "esquema_mandante": "4-3-3",
      "mandante_titulares_notas": {
        "goleiro": { "nome": "Alisson", "nota_sofascore": 7.1 },
        "atacantes": [{ "nome": "Vini Jr", "nota_sofascore": 7.9 }]
      }
    },
    "feem": { "contexto_peso_caos": 1.25, "jogo_decisivo": true }
  }
}

Calibração holdout (ensemble vs blend KXL 25%):

python3 scripts/wc_kxl_calibrate.py --season 2022

3. Rodar pipeline de transformação

run-pipeline silver              # bronze → silver
run-pipeline gold --season 2024  # silver + fixtures → gold com labels
run-pipeline export              # exporta JSONL para treino

4. Palpites da rodada atual

Edite data/rounds/current.json com os jogos da rodada e execute:

predict-round
predict-round --json    # saída JSON

Ou via API: GET /round/predict

5. Exportar dataset para treino

from models.dataset import export_jsonl
export_jsonl("data/training/bolao_train.jsonl")

Adicione o campo label nos jogos gold (1, X ou 2) com resultados históricos antes de treinar.

6. Treinar LM

pip install -e ".[ml]"
python -m models.train

Integração recomendada com Unsloth para fine-tuning eficiente.

7. Subir API

uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

Endpoints principais (detalhes em docs/api-referencia.md):

• GET /health — status
• GET /news/feed, POST /news/sync — notícias
• POST /context, POST /predict — Brasileirão + notícias
• GET /round/predict — rodada Brasileirão
• POST /worldcup/predict — palpite WC (ensemble + KXL opcional)
• GET /worldcup/round, GET /worldcup/teams — rodada e seleções
• GET /worldcup/editions, POST /worldcup/validate — backtest histórico
• POST /worldcup/value/live — value bets (requer ODDS_API_KEY)

8. Frontend web

cd frontend && npm install && npm run dev

Ver docs/frontend.md.

9. Odds reais + EV (Copa)

Configure ODDS_API_KEY no .env e execute:

fetch-wc-odds --schedule-file data/rounds/wc_2026.json --output-file data/rounds/wc_2026_odds.json
value-wc-odds --odds-file data/rounds/wc_2026_odds.json --min-edge 0.03

Fluxo:

• fetch-wc-odds busca odds em tempo real (The Odds API) e sobrescreve o JSON de odds.
• value-wc-odds cruza probabilidades do modelo com odds reais e mostra apenas entradas com EV positivo.

10. Benchmark de modelos + visual (MLflow)

Para comparar modelos e reduzir erro com validação temporal:

benchmark-wc-models --eval-season 2022
benchmark-wc-models --eval-season 2022 --mlflow
mlflow-ui

Saídas:

• Relatório JSON em data/lake/reports/wc_benchmark_report.json
• Opcional: métricas no MLflow (accuracy, brier, log_loss por modelo), experimento api-noticia/wc-benchmark em mlflow.db

Use sempre mlflow-ui (não mlflow ui puro) para a UI ler o mesmo backend SQLite do benchmark. URL padrão: http://127.0.0.1:5001 (porta 5001 evita conflito com AirPlay no macOS).

Estrutura do projeto

api_noticia/
├── ingest/          # Coleta RSS + storage bronze + odds
├── pipelines/       # Transformações silver, gold, WC, KXL
├── schemas/         # Contratos Pydantic
├── models/          # Dixon-Coles, logística, baseline, EV
├── api/             # FastAPI
├── frontend/        # React + TypeScript (Bolão AI)
├── docs/            # Documentação detalhada
├── tests/
├── config.py
└── data/lake/       # Datalake local (gitignored)

Próximos passos

1. Ground truth — importar resultados históricos (Brasileirão, Copa do Brasil) para labels
2. NER de jogadores — substituir heurística por modelo de entidades
3. BigQuery/GCS — escalar para GCP com pip install -e ".[gcp]"
4. Orquestração — Prefect ou Cloud Composer para coleta diária
5. Fine-tuning — conectar Unsloth ao JSONL gold
6. Odds e estatísticas — enriquecer gold com APIs esportivas (API-Football, etc.)

Formato bolão

Código	Significado
1	Vitória do mandante
X	Empate
2	Vitória do visitante

Licença

Uso interno / pesquisa. Respeite os termos de uso dos portais de notícias.