NBA Live Predictor
A real-time NBA game analytics dashboard built with Flask and Socket.IO. It ingests live play-by-play data, runs an XGBoost shot-quality model and a PyTorch win-probability model, and renders a single-page dashboard with playoff standings, player/team profiles, and contextual news — all updating live via WebSocket.
The repository ships with synthetic training data and pre-trained model artifacts so the app is immediately runnable without a separate data pipeline.

Features
- Live scoreboard — detects active NBA games via
nba_apiand polls every 3 seconds - Play-by-play tracker — score, possession, latest event, shot context, shot quality, and win probability
- Live box score — top scorers per team (points, rebounds, assists, steals, blocks, +/-) pulled from the NBA CDN boxscore feed
- Shot-quality model — XGBoost regressor using distance, angle, defender distance, shot clock, and game situation
- Win-probability model — PyTorch network using score differential, time remaining, possession, fouls, and shot quality
- Win-probability trend chart — live line chart of the home team's win probability across the game, capped at the last 1,000 snapshots
- Playoff dashboard — standings, schedule, team form, player leaders, sentiment, and alerts
- Advanced team stats — offensive/defensive rating, pace, effective FG%, true shooting%, and turnover% per team (NBA Stats
MeasureType=Advanced), shown on each team profile - Per-game predictions —
Run Modelbutton with a plain-English explanation of the pick, factoring in team strength, injuries, news sentiment, rest/back-to-back schedule fatigue, recent form, home/road performance splits, and shooting-efficiency/turnover (four factors) splits - Player and team pages — profile views with refreshable contextual news from ESPN
- Sortable players page — rank every playoff player by PTS, REB, AST, STL, BLK, TS%, USG%, or PIE (in addition to team filtering)
- Player game log — real last-10-game boxscore table (date, matchup, W/L, MIN/PTS/REB/AST/+/-) on every player profile, pulled live from
playergamelogwith a regular-season fallback for players without playoff minutes - WebSocket push — live prediction events emitted to all connected clients every 3 seconds
- Light/dark theme — toggle in the topbar, respects system preference by default, persisted in
localStorage - Global search — topbar search box for jumping straight to any player or team profile by name
- Player comparison — side-by-side stat comparison for any two playoff players, with the better value highlighted per category
- Power rankings — all 16 playoff teams ranked by net rating blended with last-10 form (not raw record), with a plain-English blurb and a record-vs-power movement indicator per team
- Playoff bracket — series scores grouped by conference and round (First Round / Conf. Semifinals / Conf. Finals / NBA Finals), sourced from the same live
scoreboardv3series data the standings already computed but the UI never surfaced - Model accuracy page — backtested win-pick accuracy, log loss, and games/seasons used to fit the pre-game model, versus a home-favorite baseline (the topbar "Model Accuracy" KPI is now wired to this same number instead of a static placeholder), plus the shot-quality model's R²/MAE on a synthetic holdout (labeled as such — there's no real-shot ground truth to backtest against)
Tech Stack
| Layer | Libraries |
|---|---|
| Backend | Flask 3, Flask-SocketIO 5, simple-websocket |
| Frontend | HTML, CSS, JavaScript (no framework) |
| ML | XGBoost, PyTorch, scikit-learn, pandas, NumPy |
| Data | nba_api, ESPN public APIs |
| Tooling | joblib, Matplotlib |
Project Structure
.
├── app.py # Entry point
├── requirements.txt
├── scripts/
│ └── train_models.py # Regenerate model artifacts
├── app/
│ ├── main.py # Flask app factory + API routes + Socket.IO loop
│ ├── models/
│ │ ├── shot_quality.py # XGBoost model wrapper + synthetic data generator
│ │ └── win_probability.py # PyTorch model wrapper + synthetic data generator
│ ├── services/
│ │ ├── nba_live.py # Live scoreboard/play-by-play adapter
│ │ ├── shot_quality_service.py# Converts play-by-play actions to model inputs
│ │ ├── league_analytics.py # Playoff data, schedule, predictions, news, fallbacks
│ │ └── news_sources.py # ESPN news fetcher
│ ├── static/
│ │ ├── dashboard.js # SPA router, rendering logic, Socket.IO client
│ │ └── styles.css
│ └── templates/
│ └── index.html
└── data/
├── shot_quality_xgb.joblib # Pre-trained XGBoost artifact
├── win_probability.pt # Pre-trained PyTorch artifact
└── synthetic_shot_quality_training.csv
Quickstart
Requirements: Python 3.10+
# 1. Clone and set up a virtual environment
git clone https://github.com/saiompatro/NBA-AI.git
cd NBA-AI
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows
.\.venv\Scripts\Activate.ps1
# 2. Install dependencies
pip install -r requirements.txt
# 3. (Optional) Regenerate model artifacts
python scripts/train_models.py
# 4. Start the server
python app.py
Open http://127.0.0.1:5000.
The server runs in debug mode by default. Set debug=False in app.py before deploying.
API Reference
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
Dashboard shell |
| GET | /api/prediction |
Latest live or no-game snapshot |
| GET | /api/analytics |
Full analytics bundle |
| GET | /api/table |
Live playoff series scores by round (feeds the bracket page) |
| GET | /api/players |
Playoff player stats |
| GET | /api/players/<id>/game-log |
Real last-10 boxscore log for a player (playoffs, falling back to regular season) |
| GET | /api/teams |
Playoff team data |
| GET | /api/schedule |
Upcoming games |
| GET | /api/power-rankings |
Teams ranked by net rating + recent form |
| GET | /api/model-performance |
Backtested accuracy/log-loss for the pre-game model |
| GET | /api/game-prediction?away=DET&home=CLE |
Matchup prediction with plain-English summary |
| GET | /api/news?type=team&team=DET&term=Detroit+Pistons&refresh=1 |
Contextual ESPN news |
| GET | /api/shot-quality |
Model metadata and feature importance |
| GET | /teams/<slug> |
Team profile page |
| GET | /players/<slug> |
Player profile page |
Socket.IO — connect to the root endpoint; the server emits a prediction event every 3 seconds.
Hash Routes (SPA)
The frontend is a single-page app driven by hash routes:
| Route | View |
|---|---|
#/live |
Live game tracker |
#/table |
Playoff standings |
#/players |
Player list |
#/players/<slug>-<id> |
Player profile |
#/teams |
Team list |
#/teams/<slug> |
Team profile |
#/predictions |
Game prediction tool |
#/compare |
Player comparison |
#/power-rankings |
Power rankings |
#/bracket |
Playoff bracket |
#/model |
Model accuracy |
#/alerts |
News alerts |
#/settings |
Settings |
Data Sources & Attribution
This project uses the following public, unauthenticated data sources. No API keys are required.
nba_api
- Package:
nba_api(MIT License) — a community Python client for the NBA Stats website - Endpoints used:
nba_api.live.nba.endpoints.scoreboard.ScoreBoard— live scoreboardnba_api.live.nba.endpoints.playbyplay.PlayByPlay— live play-by-playnba_api.stats.endpoints.scoreboardv3— extended scoreboardnba_api.stats.endpoints.leaguedashplayerstats— season player statsnba_api.stats.endpoints.leaguedashteamstats— season team statsnba_api.stats.endpoints.playoffpicture— playoff bracket picture
- Data owner: NBA Stats (
stats.nba.com) — data is property of the NBA. Use is subject to NBA Terms of Use.
ESPN Public APIs
- Endpoints used:
site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard— scoreboard fallbacksite.api.espn.com/apis/site/v2/sports/basketball/nba/news— news articles
- Data owner: ESPN. These are undocumented public endpoints. ESPN may rate-limit or deprecate them without notice. Use respectfully.
Synthetic Training Data
The ML models in this repository are trained on synthetically generated data (data/synthetic_shot_quality_training.csv). The generator (app/models/shot_quality.py) produces plausible shot-context distributions but does not use any proprietary tracking data (e.g. Second Spectrum, SportVU). For production-quality predictions, replace the synthetic generators with real historical play-by-play and tracking data.
ML Models
| Model | File | Algorithm | Inputs |
|---|---|---|---|
| Shot Quality | data/shot_quality_xgb.joblib |
XGBoost regressor | distance, angle, defender_distance, shot_clock, game_situation |
| Win Probability | data/win_probability.pt |
PyTorch MLP | score_diff, time_remaining, home_possession, home_fouls, away_fouls, shot_quality |
Both artifacts are pre-trained on synthetic data and included in the repository. Regenerate them at any time:
python scripts/train_models.py
Contributing
Pull requests are welcome. For major changes, open an issue first to discuss what you'd like to change.
- Fork the repo and create a feature branch
- Run
python -m py_compile app.py app/main.py app/services/*.py app/models/*.pyas a quick syntax check - Open a pull request
License
MIT — see LICENSE for details.
Disclaimer
Predictions and analytics are experimental and generated from public feeds and prototype machine-learning models trained on synthetic data. They should not be used for betting, fantasy sports decisions, or any financial purpose.