Content
# CopaMind 2026 🧠⚽
[](https://github.com/Phemassa/copamind-2026/actions/workflows/ci.yml)
[](https://www.python.org/)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
[](LICENSE)
> Plataforma **local** e **open source** de inteligência esportiva: coleta dados de futebol, treina modelos preditivos locais, simula a Copa 2026 milhares de vezes e responde perguntas via chat com RAG, MCP e múltiplos LLMs locais executados em sequência — sempre com **transparência e reprodutibilidade**.
**Aviso:** projeto sem vínculo oficial com FIFA, seleções, federações ou organizadores. As probabilidades são **experimentais e educacionais**, não representam garantia de resultado e não incentivam apostas.
---
## Recursos
- 📊 **Modelos preditivos**: Elo, Poisson/Dixon-Coles, ensemble e calibração isotônica (Brier/Log-Loss/ECE)
- 🎲 **Simulação Monte Carlo** do torneio (chances por fase e de título), reprodutível por seed
- 🏆 **Bolão de IAs Locais** — ~30 modelos LM Studio preveem cada partida do mata-mata; placar, vencedor, pênaltis, probabilidades e jogadores-chave; runner model-first com progresso ao vivo
- 📐 **Analytics FIFA v2** — 13 índices derivados por equipe (attack, defense, keeper, control, pressing, transition, volatility, champion_profile, upset_risk, etc.) com anti-leakage por snapshot
- 📰 **Context Notes** — notas contextuais manuais (lesão, rotação, tática) injetadas como evidência estruturada nos prompts; extrator automático de notícias via LLM
- 🔍 **RAG** com busca híbrida (vetorial + léxico) e proteção contra prompt injection
- 🤖 **Orquestração de LLMs locais** (LM Studio/Ollama): sequencial, model-first, retry e benchmark por fase
- 🔌 **MCP** (`copamind-mcp`): ferramentas read-only e de escrita para o agente/IDE
- 🖥️ **Portal estático** (`apps/portal/`) com tabela-resumo de previsões, ranking das LLMs, dashboard de seleções/jogadores e aba Tabela e Jogos
- 🧾 **Linhagem e reprodutibilidade** em cada resultado (origem, snapshot, evidências)
## Diferencial
Não é um chatbot que "chuta" o campeão. As probabilidades vêm de **modelos de ML calibrados** (Elo, Poisson, CatBoost, ensemble, Monte Carlo); os LLMs apenas **interpretam, consultam e explicam**. Cada resposta registra de onde veio o dado, qual modelo calculou, onde os modelos divergiram e qual snapshot foi usado.
Veja o plano completo em [CopaMind_2026_MASTER_PLAN.md](CopaMind_2026_MASTER_PLAN.md), o backlog em [TASKS.md](TASKS.md), as decisões em [DECISIONS.md](DECISIONS.md) e o cronograma em [ROADMAP.md](ROADMAP.md).
## Demonstração
Chances de título + caminho até o título (simulação Monte Carlo):
Bolão de IAs (leaderboard + curva de calibração):
## Arquitetura
## Hardware recomendado
- Windows 11 (também roda em Linux), Docker Desktop, VS Code
- Python 3.12
- GPU NVIDIA com **8 GB de VRAM** (RTX 5070 Laptop) — evolução para servidor **24 GB** já prevista (perfis de hardware)
- 32 GB de RAM
- LM Studio e/ou Ollama para os LLMs locais
## Instalação
### Windows (PowerShell)
```powershell
git clone https://github.com/Phemassa/copamind-2026.git
cd copamind-2026
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[data,dev]"
Copy-Item .env.example .env
```
### Linux / macOS (bash)
```bash
git clone https://github.com/Phemassa/copamind-2026.git
cd copamind-2026
python -m venv .venv
source .venv/bin/activate
pip install -e ".[data,dev]"
cp .env.example .env
```
## Uso rápido
```bash
# Verificar o ambiente (Python, dependências, configs, serviços locais)
copamind doctor
# Subir o Qdrant (RAG) via Docker
docker compose -f docker/compose.yaml up -d
# Subir a API
copamind api serve
# health check:
curl http://127.0.0.1:8000/health
```
## Dashboard
```bash
copamind ingest sample # carrega o dataset de exemplo
pip install -e ".[ui]" # instala Streamlit/Plotly
copamind ui serve # abre o dashboard bilíngue (EN/PT-BR)
```
## Desenvolvimento
```bash
pre-commit install # hooks de qualidade
ruff check . # lint
ruff format . # formatação
mypy # tipos
pytest # testes + cobertura
```
## Estado do projeto (09/07/2026)
**Fase ativa: Quartas de final** (França×Marrocos · Espanha×Bélgica · Noruega×Inglaterra · Argentina×Suíça). Final: 19/07/2026.
Núcleo entregue (160+ testes): dados/ingestão (E1), user reports (E2), Elo + forma (E3a), Poisson/Dixon-Coles (E4), ensemble + calibração (E3b), simulação Monte Carlo (E4b), RAG (E5), MCP (E6), orquestração de LLMs + benchmark (E7), dashboard Streamlit (E8a/E8b), portal estático (E9) e Bolão de IAs com runner model-first (E11). Analytics FIFA v2 com 13 índices, context notes com extrator LLM e tabela-resumo de previsões implementados. Veja [TASKS.md](TASKS.md) e o [ROADMAP.md](ROADMAP.md).
## Conteúdo para divulgação
```bash
copamind content ranking --locale pt-BR # card de chances de título (Markdown)
copamind content match --home T-NTL --away T-SDR --locale en
```
## Dados reais (OpenFootball)
```bash
# Baixe um worldcup.json de https://github.com/openfootball/worldcup.json
copamind ingest worldcup caminho/para/worldcup.json
```
## Contribuição e segurança
- [CONTRIBUTING](.github/CONTRIBUTING.md) · [SECURITY](.github/SECURITY.md) · [MODEL_CARD](MODEL_CARD.md)
- Conventional Commits; qualidade obrigatória (`ruff`, `mypy`, `pytest`) antes do PR.
## Licença
[MIT](LICENSE).
