Value Bet Scanner

Premier socle exécutable du MVP de scanner de value bets football pré-match.

Ce qui est inclus

• API FastAPI avec endpoints de santé et d'aperçu des signaux
• SQLAlchemy 2 + Alembic
• Double mode local:
  • SQLite pour un démarrage ultra-rapide sans Docker
  • PostgreSQL via Docker Compose pour se rapprocher de la cible runtime
• Modèles de domaine initiaux pour fixtures, cotes, résultats et signaux
• Adapters structurés pour football-data.org et The Odds API
• Service de scan minimal avec calcul EV/no-vig sur 1X2
• Seed de démonstration pour alimenter la DB et produire des signaux visibles
• Sync publique sans clé via football-data.co.uk (fixtures + résultats + cotes 1X2 historiques)

Prérequis

• Python 3.9+
• Docker + Docker Compose (optionnel pour le mode SQLite local, requis pour le mode Postgres)

Variables d'environnement

Copier .env.example vers .env.

cp .env.example .env

Par défaut, .env.example utilise SQLite pour permettre un test immédiat sans dépendance Docker. Si tu veux tester en PostgreSQL local, remplace DATABASE_URL par:

DATABASE_URL=postgresql+psycopg://valuebet:valuebet@localhost:5432/valuebet

Smoke test MVP

Un script unique permet de vérifier le chemin critique local:

• migration
• seed de données
• tests
• démarrage API
• signaux visibles

Validation qualité rapide complémentaire:

make lint
make typecheck

cd value-bet-scanner
bash scripts/local_smoke_test.sh
# ou
make smoke

Variante avec ingestion publique réelle:

bash scripts/local_smoke_test.sh --public-data --competition E0 --season 2425
# ou
make smoke-public COMPETITION=E0 SEASON=2425

Comportement:

• si .env pointe vers SQLite, le smoke test tourne sans Docker
• si .env pointe vers PostgreSQL et que Docker est dispo, il démarre la base automatiquement
• si API_PORT est déjà occupé, le smoke test choisit automatiquement un port libre pour éviter un faux positif/faux négatif sur l'API
• par défaut il seed des données de démo; --public-data remplace cela par une vraie ingestion football-data.co.uk et vérifie aussi les signaux sur fixtures finished

Lancement rapide local (sans Docker, recommandé pour premier test)

cd value-bet-scanner
make venv
source .venv/bin/activate
make install
cp .env.example .env
make migrate
make seed-demo
make api

API dispo sur http://127.0.0.1:8000.

Lancement avec Docker/Postgres

cd value-bet-scanner
cp .env.example .env
# puis remplacer DATABASE_URL dans .env par l'URL PostgreSQL localhost si tu veux aussi exécuter l'API hors conteneur

docker compose -f infra/compose/docker-compose.yml up --build

Notes Docker:

• le service db expose Postgres sur localhost:5432
• le service api utilise automatiquement db:5432 en interne dans Compose

API: http://127.0.0.1:8000 Postgres: localhost:5432

Endpoints MVP

• GET /health
• GET /api/v1/signals/top (après seed demo ou sync publique, retourne les meilleurs signaux calculés avec contexte lisible: fixture, compétition, statut, kickoff, EV, Kelly)
• POST /api/v1/ops/scan-preview (calcule un preview EV à partir des snapshots présents)

Paramètres utiles:

• limit — nombre max de lignes renvoyées
• fixture_status=all|scheduled|finished — permet de distinguer les signaux historiques/backtest (finished) des matchs encore jouables (scheduled)

Sync réelle sans clé

Le projet peut maintenant charger de vraies données publiques via football-data.co.uk, sans FOOTBALL_DATA_API_KEY ni THE_ODDS_API_KEY.

Exemple minimal:

cd value-bet-scanner
python3 -m alembic upgrade head
python3 -m value_bet_scanner.scripts.sync_public_football_data_uk --season 2425 --competition E0
curl http://127.0.0.1:8000/api/v1/signals/top

Wrapper shell équivalent:

bash scripts/sync_public_real_data.sh --competition E0

Options utiles pour réseau instable:

python3 -m value_bet_scanner.scripts.sync_public_football_data_uk \
  --season 2425 \
  --competition E0 \
  --timeout 45 \
  --max-attempts 5 \
  --backoff-seconds 3

Ce que cette sync publique remplit en base:

• competitions
• teams
• fixtures
• fixture_source_states
• fixture_results
• bookmakers
• odds_snapshots
• odds_outcomes
• best_odds_snapshots

Codes supportés en natif:

• E0 — Premier League
• SP1 — La Liga
• D1 — Bundesliga
• F1 — Ligue 1
• I1 — Serie A

Migrations

python3 -m alembic upgrade head
python3 -m alembic revision --autogenerate -m "message"

Dashboard Streamlit

streamlit run apps/dashboard/streamlit_app.py
# ou
make dashboard

Le dashboard permet maintenant de:

• vérifier que l'API locale répond bien (/health)
• voir immédiatement les métriques MVP de scan (/api/v1/signals/summary)
• changer l'URL de l'API si besoin
• filtrer les signaux par scheduled / finished / all
• ajuster rapidement le nombre de lignes affichées

Notes sources

Fonctionne sans clé maintenant

• football-data.co.uk: sync publique branchée, testable immédiatement, couvre fixtures + résultats + cotes 1X2 historiques par bookmaker

Nécessite encore une clé

• football-data.org: adapter prêt, nécessite FOOTBALL_DATA_API_KEY
• The Odds API: adapter prêt, nécessite THE_ODDS_API_KEY

Checklist produit testable (MVP)

Le repo est considéré testable si ces 5 points passent:

• installation locale documentée (README.md + docs/local-development.md)
• migration DB OK (python -m alembic upgrade head)
• ingestion utile OK (seed_demo_data ou sync_public_football_data_uk)
• scan visible OK (GET /api/v1/signals/top renvoie des items)
• premier test humain crédible OK (API locale + curl ou dashboard)

Premier test fonctionnel crédible (humain)

cd value-bet-scanner
source .venv/bin/activate
python -m alembic upgrade head
python -m value_bet_scanner.scripts.sync_public_football_data_uk --season 2425 --competition E0
uvicorn value_bet_scanner.main:app --host 127.0.0.1 --port 8000

Puis dans un autre terminal:

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/api/v1/signals/top
curl 'http://127.0.0.1:8000/api/v1/signals/top?fixture_status=finished&limit=10'

Option visuelle:

streamlit run apps/dashboard/streamlit_app.py

Ce test valide qu'un humain peut:

• remplir la base avec une ingestion réelle publique
• démarrer l'API localement
• voir des signaux calculés avec probas de modèle dérivées de l'historique des équipes, plutôt qu'un simple barème fixe
• vérifier le résultat rapidement via curl ou dashboard

Limites actuelles

• la voie publique sans clé est historique/closing odds, pas un flux live pre-match temps réel
• le modèle de probabilité reste volontairement simple (forme/résultats historiques) : utile pour un MVP testable, pas encore pour de la prod betting
• pour du vrai scan pré-match live en production, l'étape suivante la plus rentable est de brancher la persistance sur The Odds API dès qu'une clé est fournie