Setup Guide
Requirements
- Python 3.12+
- Docker Desktop (optional, for containerised running)
- API keys for: API-Football (Ultra), Betfair Exchange, Anthropic (optional)
Installation
git clone <repo>
cd sportai
pip install -r requirements.txt
API Keys
Create a .env file:
# Required
API_FOOTBALL_KEY=your_api_football_key
BETFAIR_APP_KEY=your_betfair_app_key
BETFAIR_USERNAME=your_betfair_username
BETFAIR_PASSWORD=your_betfair_password
# Optional (for Claude qualitative analysis)
ANTHROPIC_API_KEY=sk-ant-your-key
Getting API Keys
- API-Football: Sign up at api-football.com. Ultra plan recommended (450 req/min, 75k/day).
- Betfair: Register for Exchange API access at developer.betfair.com.
- Anthropic: Get key from console.anthropic.com. Or use Claude Code CLI pipe mode (no key needed).
Running
HUD (main dashboard)
python hud.py
Auto-refreshes every 60 seconds. Shows matches, odds, analysis, bets, P&L.
Backtester
python backtester.py
Downloads historical fixtures + real odds, runs Poisson model, shows results.
Daily Odds Collector
python collector.py
Run once per day. Collects upcoming fixture odds for CLV tracking.
Docker
# HUD
docker-compose up hud
# Backtester
docker-compose --profile backtest up backtest
# Docs wiki
docker-compose --profile docs up docs
Data Files
| File | Purpose | Auto-created |
|---|---|---|
active_bets.json |
Current open bets | Yes |
bet_history.json |
Settled bet archive | Yes |
bankroll.json |
Bank balance + XP | Yes |
backtest.db |
Backtest fixtures + results (SQLite) | Yes |
sportai.db |
Daily odds snapshots (SQLite) | Yes |
Gamification
Start as Rookie (0 XP). Level up by placing and winning bets:
| Level | XP Required |
|---|---|
| Rookie | 0 |
| Scout | 50 |
| Trader | 150 |
| Shark | 400 |
| Whale | 800 |
| Legend | 1500 |
XP rewards: Win = 15, Grade A Win = 25, Loss = 2, Streak bonus = +5 per consecutive win.