README.md

---
title: Safe Bet AI Precision
emoji: 🛡️
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# SAFE BET AI — Precision v2.2

Motor quantitativo de futebol para Docker Space, desenhado para **rejeitar apostas frágeis** em vez de forçar uma lista.

## Linux Lab gratuito

O mesmo Docker Space mantém o painel em `/` e oferece um VS Code no navegador em
`https://<subdominio-do-space>.hf.space/ide/`, com terminal Bash e ferramentas Linux.
Abra essa URL diretamente, fora do iframe do Hub. O editor é protegido pelo Secret
`IDE_PASSWORD`; sem esse Secret, a rota permanece bloqueada.

O workspace editável é clonado em `~/workspace/Vscode`. O disco do hardware gratuito é
efêmero: antes de o Space reiniciar ou dormir, faça commit e push das alterações que
quiser preservar.

Para testar o aplicativo alterado em outra porta dentro do terminal da IDE:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
uvicorn app.main:app --host 0.0.0.0 --port 8001
```

Abra o link da porta detectada pelo VS Code ou visite `/ide/proxy/8001/`.

## O que mudou nesta versão

- Painel completamente redesenhado, responsivo, acessível e sem dependências externas.
- Radar mostra até cinco leituras do modelo quando não há aposta SAFE, sempre como
  observação não aprovada e fora de bilhetes, histórico e métricas.
- Validação walk-forward agora separa tuning e holdout temporal para reduzir otimismo.
- Scans concorrentes compartilham uma única tarefa e sobrevivem à desconexão do cliente.
- Falhas totais de providers preservam o estado anterior; falhas parciais ficam como `degraded`.
- Liquidação usa IDs resolvidos de times e mantém trilha de publicação/partida liquidada.
- Storage Bucket montado em `/data` é usado automaticamente quando disponível.
- Histórico **separado por competição** para impedir misturas entre ligas.
- Matching de times com IDs/aliases do football-data.org e detecção de ambiguidade.
- Resultado histórico usa **tempo regulamentar** quando disponível (importante em mata-mata/1X2).
- Poisson refinado com ajuste **Dixon–Coles** para placares baixos.
- Elo + forma ponderada por recência + shrinkage de amostras pequenas.
- Pesos do ensemble ajustados por **walk-forward sem vazamento temporal**, com shrinkage contra overfitting e Brier Skill contra climatologia temporal.
- Mercado tratado como **prior forte**: odds de-vigadas por bookmaker antes da agregação.
- Livros antigos/outliers são filtrados; dispersão entre casas entra no Risk Gate.
- Probabilidade “conservadora” agora é **shrinkage por confiabilidade**, não um falso intervalo estatístico.
- Calibração forward entra apenas depois de amostra real suficiente da mesma versão.
- Cache de partidas evita reconstrução cega; temporada anterior é carregada quando a atual é rasa.
- The Odds API consulta primeiro `/sports`, que não consome quota, para ignorar ligas fora de temporada.
- Forward tracking não duplica o mesmo evento caso a seleção mude em outro scan.
- Bilhetes recebem stress de dependência quando há muitas pernas da mesma competição.
- Teste de liveness comprova que um favorito plausível atravessa os gates reais de produção.
- Testes automatizados cobrindo matemática, matching, mercado, providers, segurança, histórico, radar e tickets.

> **SAFE não significa garantia.** O sistema estima risco e qualidade de dados; futebol continua sendo aleatório.

## Secrets obrigatórios

- `FOOTBALL_DATA_TOKEN`
- `ODDS_API_KEY`
- `CRON_SECRET`

## Backup opcional

- `HF_WRITE_TOKEN`
- `HF_DATASET_REPO`

## Acesso ao Linux Lab

- `IDE_PASSWORD` — senha forte para entrar em `/ide/`; configure como **Secret**, nunca como Variable.

## Teste

```bash
pip install -r requirements-dev.txt
python -m compileall -q app tests
pytest -q
```

## Endpoints

- `/` — painel
- `/api/health` — saúde
- `/api/state` — estado completo
- `/api/cron/daily` — cron protegido por `X-Cron-Secret`
- `/api/admin/scan?wait=1` — scan manual protegido

Leia **TUTORIAL.md**, **PRECISION_REVIEW.md** e **RELEASE_NOTES_v2.2.md** antes do deploy.