Skip to main content

​
Prerequisites

  • Python 3.8 or later
  • pip package manager

​
Installation

Install the required dependencies: 
pip install nba_api pandas scikit-learn
The model must be trained before you can make predictions. Complete all steps below in order — skipping train_model_teamwins() will cause predict_game_teamwins() to fail with a missing model file error.

​
Run the full pipeline

1

Fetch NBA game data

Call fetch_games_teamwins() with a season string to pull team game logs from the NBA Stats API and store them in a local SQLite database (Data/nba_stats.db).
from Data.fetch_games import fetch_games_teamwins

fetch_games_teamwins("2025-26")
The season format is "YYYY-YY" (e.g. "2024-25", "2025-26"). Data is written to the games table and existing rows are replaced on conflict.
2

Generate features

Call generate_features_teamwins() to compute 5-game rolling averages for points, rebounds, and assists for each team. The results are written to the team_game_stats table.
from Data.generate_features import generate_features_teamwins

generate_features_teamwins()
The default rolling window is 5 games. Pass a different integer to rolling_window to change it:
generate_features_teamwins(rolling_window=10)
3

Train the model

Call train_model_teamwins() to fit a 200-estimator Random Forest classifier on the team_game_stats table. The trained model is saved to models/nba_model.pkl.
from prediction_ai import train_model_teamwins

train_model_teamwins()
The function prints test accuracy on a held-out 30% split before saving:
Test Accuracy: 0.XXX
The exact value depends on the season data used for training.
Rerun this step any time you fetch a new season of data to retrain on the latest games.
4

Make a prediction

Call predict_game_teamwins() with the rolling-average stats for both teams to get a win probability between 0.0 and 1.0.
from prediction_ai import predict_game_teamwins

prob = predict_game_teamwins(
    points_diff=0,        # float: team's rolling points avg minus opponent's
    team_reb_roll=4,      # float: team's 5-game rolling rebound average
    opponent_reb_roll=5,  # float: opponent's 5-game rolling rebound average
    team_ast_roll=4,      # float: team's 5-game rolling assist average
    opponent_ast_roll=5,  # float: opponent's 5-game rolling assist average
    home=1                # int: 1 if the team is playing at home, 0 if away
)
ParameterTypeDescription
points_difffloatTeam’s rolling points average minus the opponent’s rolling points average
team_reb_rollfloatTeam’s rolling rebound average
opponent_reb_rollfloatOpponent’s rolling rebound average
team_ast_rollfloatTeam’s rolling assist average
opponent_ast_rollfloatOpponent’s rolling assist average
homeint1 if the team plays at home, 0 if away
5

Evaluate the bet

Pass the probability to evaluate_bet_teamwins() to get a plain-language recommendation.
from prediction_ai import evaluate_bet_teamwins

print("Win Probability:", round(prob, 3))
print("Evaluation:", evaluate_bet_teamwins(prob))
ProbabilityResult
> 0.60"Good Bet"
> 0.52"Slight Edge"
≤ 0.52"Avoid"

​
Complete example

The following is the full end-to-end script from main.py: 
from Data.generate_features import generate_features_teamwins
from Data.fetch_games import fetch_games_teamwins
from prediction_ai import train_model_teamwins, predict_game_teamwins, evaluate_bet_teamwins

print("Getting NBA game data...")
fetch_games_teamwins("2025-26")

print("Populating database...")
generate_features_teamwins()

print("Training model on data...")
train_model_teamwins()

print("Getting results...")
prob = predict_game_teamwins(
    points_diff=0,
    team_reb_roll=4,
    opponent_reb_roll=5,
    team_ast_roll=4,
    opponent_ast_roll=5,
    home=1
)
print("Win Probability:", round(prob, 3))
print("Evaluation:", evaluate_bet_teamwins(prob))

​
Expected output

Getting NBA game data...
Pulling NBA data for season 2025-26...
Inserted/updated NNNN team-game rows.
Populating database...
Loaded NNNN rows from 'games' table.
Generated NNNN rows in 'team_game_stats'.
Training model on data...
Test Accuracy: 0.XXX
Getting results...
Win Probability: 0.XXX
Evaluation: Avoid
The final two lines show the win probability as a float rounded to three decimal places, followed by one of "Good Bet", "Slight Edge", or "Avoid".

Build docs developers (and LLMs) love

Get started for freeTalk to us