HandsDownAI (sports-ai)
Live site: https://adotscotty.github.io/HandsDownAI/
Predicts the margin of victory and win probability for NFL, NBA and college football (FBS) games,
using only free ESPN data. It runs on its own; nobody needs to touch the code.
What it does
- Team ratings. Every team has a rating in points. After each game the ratings move toward
what the score says. Between seasons they are pulled back partway toward average.
- Prediction = home-field edge + home rating - away rating - injury penalty.
Win probability comes from how big the predicted margin is.
- Injuries (from ESPN's injury report, refreshed every run):
- NBA: the value of regular rotation players listed Out (full), Doubtful (75%) or Questionable/Day-to-day (30%).
- NFL and college: whether the team's usual starting quarterback is listed out or doubtful.
- Betting line: ESPN's spread and over/under (ESPN BET) are shown next to our number.
Last season's backtest (graded on 2025, each game predicted only from earlier games; NFL tuned on 2021-2024, NBA and college on 2024)
| NFL | NBA | College (FBS v FBS) |
|---|
| Games graded | 285 | 1,316 | 809 |
| Our average miss (points) | 10.0 | 11.3 | 12.7 |
| Betting spread's average miss | 9.6 | 11.0 | 11.8 |
| Picked the winner, us | 64% | 70% | 73% |
| Picked the winner, spread | 66% | 69% | 73% |
| Against the spread, every game | 48% | 50% | 53% |
| Against the spread, when we disagree by 4+ pts | 32% (31 games) | 51% (309 games) | 54% (361 games) |
Breaking even against the spread needs about 52.4%. So the model is about as good as the betting
line at picking winners, slightly worse at the exact margin, and is not yet a proven betting edge.
Win chances are fitted to who actually won, and in the NBA they line up well (games we called 75% were won about 79% of the time).
The injury adjustment improved accuracy in all three sports (NBA most).
NFL extras (added Oct 2026): rest days (bye weeks, short weeks) and quarterback quality (a QB's adjusted
net yards per dropback, so losing a star costs more than losing an average starter). Tested on 2023-2025
(854 games), these took NFL from 63.5% to 64.6% winners and 47.5% to 49.6% against the spread. The NFL
betting line is very hard to beat with scores alone.
Play-by-play test (Oct 2026): we also tried learning team ratings from nflverse play-by-play efficiency
(EPA: all plays, competitive plays only, and without turnovers). On 2023-2025 none of these beat the
current model (best: 49.9% vs 49.6% against the spread, same average miss), and the model doesn't beat
opening lines either (50.3%). So it is not switched on. The code is kept in sportsai/nflverse.py and the
model setting epa_w (0 = off), with the efficiency numbers saved in data/games_nfl.csv.
Caveat: in the backtest, "injured" means the player didn't play (taken from box scores), which is a
bit more than what was known before kickoff. Live predictions use the real pre-game injury report.
Files
sportsai/fetch_history.py downloads past seasons (scores, closing spreads, who played).sportsai/backtest.py tunes the settings and grades last season. Results: data/backtest_summary.json, data/backtest_<sport>.csv.sportsai/predict.py makes predictions for upcoming games: data/predictions.json
(built to run every 15 minutes) and data/season_<sport>.csv (this season's track record so far).
Commands: python -m sportsai.fetch_history, python -m sportsai.backtest, python -m sportsai.predict.
No extra packages needed (plain Python 3).
When to consider paid data
- The Odds API (~$30/mo): if ESPN stops showing lines, or you want lines from several sportsbooks.
- SportsDataIO or similar: if injury news on ESPN lags (e.g. late scratches in the NBA).
- Licensed data: before charging money or running ads, since ESPN's API is unofficial and not licensed for commercial use.
Main prediction (Oct 2026)
The number shown first on each game is 90% the betting line and 10% our model (blend_w in
data/backtest_summary.json); our model's own number is shown underneath. Tested on 2023-2025, the line
alone was the most accurate, and our model adds little on top, so the main number leans on the line.
On 2025: average miss NFL 9.7 / NBA 11.0 / college 11.8 points; winners 66% / 69% / 73%.
College is now tuned on 2021-2024 (average miss of our model alone on 2025: 12.7 -> 12.3).
NBA tuning on more seasons and back-to-back rest made no difference, so NBA is unchanged.
Website and automatic updates
site/ is the website (plain HTML/CSS/JS). It reads site/data/predictions.json and site/data/track_record.json,
which python -m sportsai.build_site writes..github/workflows/update.yml runs every 15 minutes on GitHub: fetches the latest scores, injuries and odds,
makes predictions, rebuilds the site data and publishes it to GitHub Pages. Finished games and the last
pre-game prediction for each game (data/pregame_log.csv) are saved back to the repository.- Best bets (
sportsai/bestbets.py, Oct 2026): the winner, spread and both parlays only make the card when our
chance beats the break-even their price needs; among those the most likely is picked (and the best winner must
be more likely than not). A kind with no such bet is left off that day. The player prop keeps its own rule
(DraftKings' most likely side at 65%+), since its chance is DraftKings' own fair odds, which always sit just
under break-even.
- Parlays tab:
sportsai/parlays.py picks the best 2- and 3-game spread parlays for the day, locks the card
45 minutes before its first game and grades each parlay at $5 (data/parlays_log.csv).
.github/workflows/retune.yml re-picks the model's settings every quarter (Jan 1, Apr 1, Jul 1, Oct 1)
using every finished game so far (python -m sportsai.retune). New settings are only kept if they
predicted recent games at least as well as the old ones; each retune is logged under retunes in
data/backtest_summary.json.
