docs/README.md

Documentação — Bolão AI / api_noticia

Plataforma de previsões esportivas (bolão 1/X/2) que combina datalake de notícias, modelos estatísticos, motor tático KXL e interface web moderna.

Índice

Documento	Conteúdo
Visão geral	Objetivo, escopo, formato bolão, fluxo end-to-end
Arquitetura	Camadas, diagramas, estrutura de pastas
Instalação e configuração	Setup, .env, scripts, dois terminais dev
Referência da API	Todos os endpoints REST com exemplos
Modelos preditivos	Dixon-Coles, logística, Elo, KXL, ensemble, EV
Plano WC — Sprints 2–4	Artefato, walk-forward, convocações, notícias, Platt, CI
Datalake e pipelines	Bronze/silver/gold, CLIs, importação de fixtures
Frontend	React, rotas, Clean Architecture, componentes
Motor KXL — Colisão	Fórmulas Vcar, Vesc, TBRTL, letalidade×GK
Glossário	Termos técnicos e siglas
Deploy Fly.io	Container + volume persistente (gru)

Início rápido

# Backend
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
import-world-cup --missing-only
./scripts/dev-api.sh

# Frontend (outro terminal)
cd frontend && npm install && npm run dev

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

Repositório

api_noticia/
├── api/              # FastAPI
├── ingest/           # RSS, fixtures, odds
├── pipelines/        # Silver, gold, WC, KXL
├── models/           # ML e previsão
├── schemas/          # Contratos Pydantic
├── frontend/         # React + TypeScript
├── data/             # Rodadas, baselines KXL, sources.yaml
├── docs/             # Esta documentação
└── tests/

Licença e uso

Uso interno / pesquisa. Respeite os termos dos portais de notícias e das APIs externas (The Odds API).