# Tutorial passo a passo — Safe Bet AI Precision v2 ## 1. O que esta versão precisa O projeto roda em **Docker** e não usa GPU nem API de IA. Obrigatório: - um Space Docker que possa executar compute; - token gratuito do football-data.org; - API key gratuita do The Odds API; - uma conta no cron-job.org; - três Secrets no Hugging Face. Recomendado: - Dataset privado no Hugging Face para guardar histórico/cache. --- # 2. Criar as chaves ## football-data.org Crie uma conta e copie seu token. Secret: ```text FOOTBALL_DATA_TOKEN ``` ## The Odds API Crie uma conta e copie sua API key. Secret: ```text ODDS_API_KEY ``` ## Segredo do cron Crie uma senha grande e aleatória, por exemplo com um gerenciador de senhas. Secret: ```text CRON_SECRET ``` Não use uma senha curta e não coloque o valor na URL. --- # 3. Enviar o projeto para o Space O Space deve usar SDK Docker. O `README.md` já possui: ```yaml sdk: docker app_port: 7860 ``` Extraia o ZIP e envie **todo o conteúdo da pasta** para a raiz do repositório do Space. A raiz precisa ficar assim: ```text Dockerfile README.md requirements.txt app/ tests/ ... ``` Não coloque uma pasta extra como: ```text safe-bet-ai-v2-precision/safe-bet-ai-v2-precision/app ``` O `Dockerfile` deve estar na raiz. --- # 4. Secrets no Hugging Face No Space: ```text Settings → Variables and secrets → New secret ``` Crie exatamente: ```text FOOTBALL_DATA_TOKEN ODDS_API_KEY CRON_SECRET ``` Valores são as chaves criadas anteriormente. --- # 5. Variables recomendadas Em **Variables**: ```text ODDS_REGIONS=eu HISTORY_DAYS=240 SCAN_HORIZON_HOURS=36 MIN_SCAN_INTERVAL_MINUTES=180 MIN_SAFE_SCORE=76 MIN_PROBABILITY=0.64 MIN_CONSERVATIVE_PROBABILITY=0.57 MIN_BOOKMAKERS=3 MIN_NAME_SCORE=82 TOP_PICKS_LIMIT=10 TZ_DISPLAY=America/Sao_Paulo ``` Ligas: ```text ODDS_SPORT_KEYS=soccer_epl,soccer_efl_champ,soccer_germany_bundesliga,soccer_italy_serie_a,soccer_spain_la_liga,soccer_france_ligue_one,soccer_brazil_campeonato,soccer_netherlands_eredivisie,soccer_portugal_primeira_liga,soccer_uefa_champs_league ``` Não acrescente ligas arbitrárias. A versão Precision só aceita ligas com mapeamento explícito para o football-data.org. --- # 6. Build Depois do upload, acompanhe: ```text Space → Logs ``` O final esperado contém Uvicorn na porta 7860. Teste: ```text https://SEU-USUARIO-SEU-SPACE.hf.space/api/health ``` Você deve receber JSON com: ```json { "ok": true, "ready": true, "version": "2.2-precision" } ``` Confira também: ```text configured.football_data = true configured.odds_api = true configured.cron_secret = true ``` Se algum estiver `false`, o nome do Secret está errado ou não foi salvo. --- # 7. Primeiro scan manual Use: ```bash curl -X POST \ 'https://SEU-USUARIO-SEU-SPACE.hf.space/api/admin/scan?wait=1' \ -H 'X-Cron-Secret: SEU_CRON_SECRET' ``` ## Atenção no primeiro scan A versão v2 pode buscar a temporada atual e a anterior quando a amostra atual é pequena. O football-data.org tem limite gratuito por minuto e o bot respeita esse limite. Por isso o **primeiro bootstrap pode levar cerca de 1–2 minutos ou mais**, dependendo das ligas e retries. Não interrompa só porque demorou alguns segundos. Depois abra: ```text https://SEU-USUARIO-SEU-SPACE.hf.space/ ``` --- # 8. Como saber se o scan funcionou Abra: ```text /api/state ``` Campos importantes: ```text status model_version summary picks radar tickets performance providers warnings rejected_preview ``` Estados normais: ```text status = ok status = degraded # scan concluído, mas algum provider teve falha parcial model_version = 2.2-precision ``` Se `picks` estiver vazio, veja `radar` e `rejected_preview`. Um dia sem apostas SAFE não é considerado erro. O `radar` mostra as melhores leituras não aprovadas, mas elas não entram nos bilhetes nem no histórico. --- # 9. Configurar cron-job.org Crie um job. ## URL ```text https://SEU-USUARIO-SEU-SPACE.hf.space/api/cron/daily ``` ## Método ```text POST ``` ## Horário Sugestão: ```text 08:00 America/Sao_Paulo ``` ## Header Adicione: ```text X-Cron-Secret: SEU_CRON_SECRET ``` Não coloque o segredo como query string. O endpoint responde rapidamente com HTTP `202` e o scan continua dentro do Space. --- # 10. Frequência recomendada Comece com **1 scan completo por dia**. O endpoint de cron também bloqueia repetições muito próximas (`MIN_SCAN_INTERVAL_MINUTES`, padrão 180) para preservar quota. O projeto consulta uma vez o mercado H2H por liga ativa. A lista gratuita `/sports` é consultada antes para evitar gastar quota com ligas fora de temporada. Veja a quota restante em: ```text /api/state → providers.odds_api.quota.remaining ``` Se a quota estiver baixa, o Quota Guardian deixa de consultar novas ligas. Não configure cron a cada 5 ou 10 minutos. --- # 11. Backup persistente — altamente recomendado Crie um Dataset privado no Hugging Face, por exemplo: ```text SEU_USUARIO/safe-bet-ai-state ``` Crie um token com permissão de escrita nesse Dataset. Adicione Secrets: ```text HF_WRITE_TOKEN HF_DATASET_REPO ``` Exemplo de valor: ```text HF_DATASET_REPO=SEU_USUARIO/safe-bet-ai-state ``` O bot passa a guardar: ```text state/state.json state/history.json state/matches.json ``` O `matches.json` é importante na v2 porque evita reconstruir toda a base histórica após cada reinício. Se o Dataset não estiver configurado, o bot continua funcionando, mas pode precisar refazer o bootstrap quando o disco local for perdido. --- # 12. Painel Cada seleção mostra: - Probabilidade final. - Probabilidade conservadora. - SafeScore. - Odd de referência. - Odd justa. - Qualidade. - Confiabilidade. - Número de casas no consenso. - Dispersão de mercado. - Matching de nomes. - Dixon-Coles/Poisson. - Elo. - Forma. - Calibração forward. - Edge. O Radar de Palpites mostra até cinco prognósticos que foram modelados, mas não passaram por todos os controles. Seus cards sempre aparecem como **EM OBSERVAÇÃO — NÃO APROVADA** e devem ser usados somente para acompanhar o mercado. ## Odd Betano Digite manualmente a odd encontrada na Betano. O painel calcula: ```text EV = probabilidade_estimada × odd_betano - 1 ``` A odd de referência das APIs não é tratada como se fosse a odd da sua conta. --- # 13. Como o Risk Gate rejeita uma partida Motivos possíveis: ```text histórico insuficiente matching ambíguo poucas casas mercado disperso qualidade de dados baixa probabilidade baixa probabilidade conservadora baixa modelos divergentes modelo muito distante do mercado odd fora da faixa preço fraco movimento de mercado contra seleção mudou desde o scan anterior SafeScore baixo ``` Não reduza os filtros só para gerar mais palpites. --- # 14. Bilhetes O painel tenta criar: ```text SAFE alvo ~2.5, até 3 pernas BALANCEADO alvo ~4.0, até 4 pernas FREEBET alvo ~10.0, até 4 pernas ``` Ele mostra se o alvo realmente foi atingido. Também mostra probabilidade sob stress quando existem seleções da mesma competição. A odd 10 não é tratada como “segura”; ela continua tendo risco elevado. --- # 15. Forward tracking e calibração O sistema guarda uma recomendação por evento. Quando o jogo acaba: 1. tenta localizar o resultado na competição correta; 2. verifica ambos os times; 3. liquida win/loss; 4. atualiza métricas. Depois de amostra suficiente da **mesma versão do modelo**, uma calibração fraca pode corrigir probabilidades futuras em no máximo ±5 pontos percentuais. Isso evita “aprendizado” instável em poucas apostas. --- # 16. Métricas O painel/estado inclui: ```text win_rate roi profit_units brier_score log_loss ece calibration_gap max_drawdown_units ``` Não avalie o modelo somente por taxa de acerto. Uma taxa alta pode existir apenas porque as odds são muito baixas. --- # 17. Testes antes de editar Em uma máquina com Python: ```bash pip install -r requirements-dev.txt python -m compileall -q app tests pytest -q ``` A revisão v2.2 passou: ```text 44 passed ``` Também foram testados: ```text / /api/health /api/state ``` com HTTP 200. --- # 18. Diagnóstico ## `401 X-Cron-Secret inválido` Header errado ou Secret diferente. ## `configuration_error` FOOTBALL_DATA_TOKEN ou ODDS_API_KEY ausente. ## primeiro scan demorado Pode ser o bootstrap histórico respeitando rate limit. ## zero palpites Veja o Radar e `rejected_preview`. O Radar informa a melhor leitura de cada jogo, mas não transforma retorno esperado negativo ou baixa confiança em aposta SAFE. ## matching ambíguo Não force o nome. A rejeição existe para impedir mistura entre equipes. ## quota Odds API baixa Reduza ligas ou frequência. ## Space reiniciou Com Dataset de backup, o cache volta automaticamente. Sem backup, o histórico pode precisar ser reconstruído. --- # 19. Regras para manter a precisão 1. Não transforme SafeScore em probabilidade. 2. Não force dez seleções. 3. Não desative o market prior. 4. Não use `fullTime` para 1X2 de mata-mata quando `regularTime` existir. 5. Não misture ligas no matching. 6. Não considere uma única bookmaker como “consenso” no modo padrão. 7. Não aumente frequência sem acompanhar quota. 8. Não faça martingale. 9. Não use scraping da Betano como dependência crítica. 10. Mantenha `model_version` quando alterar regras estatísticas; ao fazer mudança grande, crie uma nova versão. 11. Rode os testes depois de cada alteração. Leia também `PRECISION_REVIEW.md`.