TurfRace

Analyse et prédiction des courses hippiques (collecte multi-sources, stats, modèles ML, API FastAPI).

Installation rapide

Prérequis:

• Python 3.9 via conda

• Windows PowerShell (recommandé)

Étapes:

1. Cloner le repo, puis ouvrir un terminal dans le dossier du projet

2. Créer et activer l'environnement conda

conda create -n turfrace python=3.9 -y

conda activate turfrace

3. Installer les dépendances

pip install -r requirements.txt

Règles CLI:

• Pas de && ni de |

• Exécuter les commandes une par une, sur des lignes séparées

Lancer l'API

Initialiser la base (SQLite) et lancer le serveur:

python -c "from src.db.init_db import init_db; init_db()"

uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000

Documentation interactive:

http://localhost:8000/docs

Endpoints utiles:

• GET /api/v1/races?date=YYYY-MM-DD&track=...&bet_type=quinte|quarte|tierce&page=1&page_size=20&sort_by=date&sort_dir=desc

• GET /api/v1/races/{race_id}

• GET /api/v1/races/{race_id}/horses

• GET /api/v1/statistics?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&track=...&bet_type=...

• GET /api/v1/statistics/trends?days=30&metric=races|entries

Ingestion de données (stubs multi-sources)

Remplir la base pour une date donnée:

python -c "from src.ingestion.pipeline import IngestionPipeline; print('rows:', IngestionPipeline().run(date='2024-01-15'))"

Script d'ingestion quotidienne (Windows): scripts/daily_ingestion.ps1

• Doc: docs/INGESTION_JOURNALIERE_WINDOWS.md

Tests

Toujours dans l'environnement conda turfrace:

conda activate turfrace

pytest -q

Architecture

src/

  api/              # FastAPI (routes races, predictions, statistics)

  config/           # settings.py (DATABASE_URL, etc.)

  data_collectors/  # Adapters stubs PMU/Geny/Equidia + agrégateur

  data_processors/  # Nettoyage, features, ETL

  db/               # SQLAlchemy models + session + init_db

  ingestion/        # pipeline.py (ingestion multi-sources -> SQLite)

  models/           # ML (features, entraînement)

  utils/            # HTTP (retries, throttling)

Données:

data/

  raw/ processed/ models/

  turfrace.db  # créé automatiquement

Modèles et ML (aperçu)

• Features de base: cotes (log, rank), encodages jockey/entraîneur

• Modèles disponibles: RandomForest (par défaut), XGBoost (optionnel selon OS)

• Sauvegarde/chargement via joblib

Docker (RPi 2B+)

• Images basées sur Python 3.9 pour compatibilité ARMv7

• Voir Dockerfile.api (allégé) et docker-compose.portainer.yml

Roadmap

Voir docs/ROADMAP.md pour la todo et les étapes à venir (stats avancées, scraping réel PMU/Geny/Equidia, ingestion quotidienne, pipeline ML, CI, etc.).

Notes

• En cas d'erreur de tests, vérifier d'abord que l'environnement conda turfrace est bien activé

• Respect des sites: User-Agent, throttling, robots.txt (déjà gérés dans src/utils/http.py)

Configuration

• Copier env.example en .env si besoin de variables custom

• Paramètres par défaut dans src/config/settings.py (ex: chemin SQLite)

• Base SQLite créée automatiquement dans data/turfrace.db

Démarrage rapide avec Docker

Option API seule:

docker build -f Dockerfile.api -t turfrace-api .

docker run -p 8000:8000 turfrace-api

Avec docker-compose:

docker compose up

Doc API:

http://localhost:8000/docs