PRECISION_REVIEW.md

Revisão profunda de precisão — v2.1-precision

Documento histórico da revisão v2.1. Para as mudanças atuais, consulte RELEASE_NOTES_v2.2.md.

Esta revisão focou em erros silenciosos que podem produzir uma confiança artificialmente alta.

1. Correções críticas

1.1 Tempo regulamentar em mata-mata

O código antigo usava score.fullTime. Em partidas com prorrogação, isso pode representar 120 minutos e classificar como vitória algo que foi empate no mercado 1X2 de 90 minutos.

A versão nova usa:

1. score.regularTime, quando existe;
2. score.fullTime como fallback.

1.2 Histórico não é mais global

O código anterior criava um catálogo global de equipes e tentava fazer fuzzy matching entre todas as ligas. Isso permitia casar nomes semelhantes de competições diferentes.

Agora cada evento do The Odds API possui um mapeamento explícito para o código do football-data.org:

• EPL → PL
• EFL Championship → ELC
• Bundesliga → BL1
• Serie A Itália → SA
• La Liga → PD
• Ligue 1 → FL1
• Brasileirão → BSA
• Eredivisie → DED
• Primeira Liga → PPL
• Champions League → CL

O matching ocorre somente dentro da competição correta.

1.3 Matching de times mais rígido

O motor usa:

• ID da equipe no football-data.org quando disponível;
• nome oficial;
• shortName;
• TLA;
• aliases;
• score mínimo;
• diferença mínima entre o melhor e o segundo candidato.

Se o nome for ambíguo, o evento é rejeitado.

1.4 Odds agregadas corretamente

A versão anterior fazia a mediana das odds e só depois removia a margem. Isso mistura preços de bookmakers diferentes e pode criar uma probabilidade sintética incoerente.

Agora:

1. cada bookmaker precisa ter Casa/Empate/Fora completos;
2. a margem é removida dentro de cada bookmaker;
3. probabilidades de-vigadas são agregadas robustamente;
4. odds de referência continuam sendo medianas;
5. bookmakers com timestamp muito velho são descartados;
6. dispersão entre casas é calculada e entra no Risk Gate.

1.5 Mercado como prior

Mercados líquidos contêm informação que um modelo gratuito sem escalações/xG não possui.

A nova versão não ignora isso. O modelo interno (Dixon-Coles + Elo + forma) é combinado com o consenso de mercado. Quanto menor a qualidade dos dados, mais forte o shrinkage para o mercado.

Isso reduz overconfidence.

2. Modelo de gols

O Poisson foi refeito.

O código antigo fazia médias lineares simples de gols marcados e sofridos. A versão nova:

• separa casa/fora;
• usa half-life de recência;
• calcula tamanho efetivo da amostra;
• aplica shrinkage para a média da liga;
• combina ataque e defesa geometricamente para evitar explosões;
• ajusta placares 0-0, 1-0, 0-1 e 1-1 com Dixon-Coles;
• estima o rho da competição a partir da taxa recente de empates, quando existe amostra suficiente.

3. Elo e forma

Elo continua sendo um modelo lento/estrutural.

Forma é separada e recebe peso menor. Jogos antigos perdem peso progressivamente. Assim uma sequência curta não domina o sistema.

3.1 Tuning walk-forward dos pesos

Os pesos Poisson/Elo/Forma não ficam mais totalmente fixos. Para cada competição, o motor reencena uma janela histórica em ordem temporal:

1. escolhe uma partida histórica de avaliação;
2. treina/calcula usando somente partidas anteriores;
3. guarda as três probabilidades dos modelos;
4. repete para dezenas de partidas;
5. procura uma grade grossa de pesos que minimize Brier Score;
6. encolhe os pesos aprendidos de volta para um prior conservador.

A grade é propositalmente grossa e o peso aprendido nunca é aceito se piorar o Brier do prior. Isso evita otimização excessiva em amostra pequena.

3.2 Brier Skill fora da amostra

A v2.1 acrescenta uma segunda verificação. Em cada partida de validação, o motor cria também uma climatologia temporal usando apenas os resultados conhecidos antes daquela partida. O ensemble recebe um Brier Skill Score contra essa referência.

Esse skill não serve para inflar a probabilidade. Ele funciona como regulador de confiança:

• skill forte + amostra suficiente → o modelo interno pode ter mais influência;
• skill fraco ou ainda desconhecido → a probabilidade é puxada mais para o consenso de mercado;
• componentes Poisson/Elo que não sustentam o favorito podem bloquear uma seleção mesmo que o posterior agregado pareça alto.

Assim, concordância interna deixa de ser confundida com habilidade preditiva real.

4. Probabilidade conservadora

O código antigo chamava uma penalização heurística de “limite conservador”, mas a fórmula parecia um intervalo estatístico sem ter distribuição amostral válida.

Agora é explicitamente reliability shrinkage:

• qualidade dos dados;
• concordância dos modelos;
• profundidade/estabilidade do mercado;
• confiança do matching de nomes;
• habilidade walk-forward do ensemble na competição.

A probabilidade é puxada em direção a 50% conforme a confiabilidade cai.

Isso é mais honesto e mais robusto.

5. Calibração forward

Depois que a mesma versão acumula amostra suficiente de palpites liquidados, o sistema aplica uma correção fraca baseada no desempenho real próximo daquela faixa de probabilidade.

Proteções:

• só usa resultados já encerrados;
• só usa a mesma model_version;
• exige amostra efetiva mínima;
• correção máxima de ±5 pontos percentuais;
• prior forte centrado na previsão atual.

Não há “autoaprendizado” agressivo em meia dúzia de apostas.

6. Histórico e métricas

O histórico agora:

• registra uma única recomendação por evento;
• não cria duas apostas opostas se a seleção mudar em outro scan;
• liquida por competição + horário + ambos os nomes;
• mede win rate;
• ROI;
• Brier Score;
• Log Loss;
• ECE de calibração;
• gap previsão x resultado;
• drawdown máximo em unidades.

7. Bilhetes

Multiplicar probabilidades assume independência. Em jogos diferentes a aproximação é útil, mas não perfeita.

A v2 adiciona um stress conservador para múltiplas pernas da mesma competição, principalmente quando ocorrem em horários próximos. O painel mostra:

• odd total;
• se o alvo foi atingido;
• probabilidade conjunta;
• probabilidade conjunta sob stress;
• EV estimado;
• fator de dependência.

8. APIs e cota

football-data.org

A versão v2 busca por competição/temporada e mantém cache local. Quando a temporada atual ainda possui poucos jogos, busca a temporada anterior. Há um rate guard com folga abaixo do limite gratuito.

The Odds API

Antes de gastar quota em /odds, consulta a lista /sports para descobrir ligas ativas. Essa chamada é gratuita segundo a documentação oficial.

9. Limitações que permanecem

Para manter o projeto gratuito:

• não há xG premium universal;
• escalações/lesões não são garantidas em todas as ligas;
• a Betano não é raspada automaticamente;
• a odd Betano deve ser digitada no painel;
• calibração forte precisa de meses de forward tracking;
• uma freebet odd 10 continua sendo de risco alto, independentemente do nome “SAFE”.

O sistema prefere dizer “nenhuma seleção aprovada” a fabricar confiança.

10. Validação executada

Na revisão final:

• python -m compileall -q app tests → OK
• pytest -q → 24 passed
• FastAPI /api/health → HTTP 200
• FastAPI /api/state → HTTP 200
• painel / → HTTP 200
• GET /api/cron/daily → HTTP 405 e POST sem segredo → HTTP 401
• JavaScript do painel validado com node --check
• validação walk-forward inclui baseline temporal e nunca recebe partidas futuras
• simulação sintética de favorito forte → probabilidade final ficou entre modelo interno e mercado, como projetado
• stress sintético adicional → 250 previsões em 10 competições, todas normalizadas e sem exceções; tuning concluído em ~1,4 s no ambiente de revisão

As integrações reais não foram chamadas com as chaves do usuário nesta revisão. O primeiro scan no Space continua sendo a validação de integração final. A tentativa de instalar um ambiente virtual novo também não pôde ser concluída porque o container de revisão não tinha acesso DNS externo; os testes foram executados com as bibliotecas já instaladas no ambiente.