NFL Algorithm - Professional Value Betting System

Advanced NFL player performance prediction and value betting engine

Version: 2.1 | Status: Production Ready | Target MAE: ≤ 3.0 | Sports: NFL + NBA

---

System Overview

A comprehensive NFL betting algorithm combining:

Component	Description
ML Models	Position-specific predictive models with defense adjustments
Data Pipeline	Live odds, weather, injuries, and player stats via nflreadpy
Value Engine	Kelly Criterion optimization with CLV tracking
Validation	Cross-season backtesting and performance metrics
Automation	Scheduled data updates and model retraining

Core Philosophy: Achieve consistent profitability through disciplined, data-driven betting with rigorous risk management.

---

Quick Start

# Clone and setup
git clone https://github.com/mattleonard16/nflalgorithm.git
cd nflalgorithm

# Install dependencies (auto-detects UV or venv)
make install

# Ingest real NFL data (2024 + 2025 seasons)
make ingest-nfl

# Option 1: Launch Streamlit dashboard (legacy)
make dashboard

# Option 2: Launch React dashboard (recommended)
make api              # Start FastAPI backend on :8000
make frontend-dev     # Start Next.js frontend on :3000

Weekly Workflow

# 1. Generate projections for the week
make week-predict SEASON=2025 WEEK=13

# 2. Materialize value bets for dashboard
make week-materialize SEASON=2025 WEEK=13

# 3. Launch Streamlit dashboard
make dashboard

# 4. View at http://localhost:8501

---

React Dashboard

The project now includes a modern React/Next.js dashboard alongside the original Streamlit version.

Stack

• Frontend: Next.js 15 + TypeScript + Tailwind CSS + shadcn/ui
• Backend: FastAPI serving the same SQLite database
• Charts: Recharts for data visualization

Running the React Dashboard

# Terminal 1: Start the API
make api

# Terminal 2: Start the frontend
cd frontend && npm run dev

# Visit http://localhost:3000

Frontend Structure

frontend/
├── src/app/           # Next.js pages (Dashboard, Performance, Analytics, System)
├── src/app/nba/       # NBA pages (Dashboard, Players, Schedule, Analytics, Performance)
├── src/components/    # React components + shadcn/ui
└── src/lib/           # API client and TypeScript types

---

NBA Module

Full NBA player props pipeline with ML-powered projections and value betting.

NBA Features

Component	Description
Minutes × Rate Decomposition	Dedicated minutes model (StackingRegressor) feeds per-minute rate projections
StackingRegressor Ensemble	GBR + RandomForest + XGBoost with Ridge meta-learner
Opponent Defense Ratings	Z-score normalized per-market defensive adjustments
4-Market Coverage	Points, rebounds, assists, and 3-pointers
Under-Bet Evaluation	Evaluates both over and under sides per line
EWMA Sigma	Player-specific volatility with market floors
Optuna Tuning	Automated hyperparameter search per market
Monte Carlo Simulation	5000-draw simulation with correlated multi-stat portfolios, Gamma-Poisson for fg3m
Probability Calibration	Isotonic regression per market trained on historical outcomes
Injury Adjustments	Redistributes absent players' expected production among active teammates
Walk-Forward Backtesting	Historical bet grading with no lookahead bias
Drift Detection	PSI-based monitoring with 3-tier alerting (stable/monitor/alert)
Feature Importance	SHAP/permutation importance tracking per market
Explainability	"Why" payloads with model inputs, recency trends, variance, confidence, risk, agent verdicts

NBA Architecture

nba_api → ingest → injuries → minutes model → stat models (4 markets)
    → odds scraping → value engine (Kelly) → calibration → Monte Carlo
    → risk assessment → agent coordination → materialized view → dashboard

NBA Dashboard

Page	Description
/nba	Projections dashboard with market filters and explainability
/nba/players	Player browser with search and season filter
/nba/schedule	Live game schedule
/nba/analytics	Correlation and risk analysis charts
/nba/performance	P&L tracking and bet outcomes

NBA Quick Start

# Ingest NBA data (2024 + 2025 seasons)
make ingest-nba

# Train models (4 markets)
make nba-train

# Generate today's projections
make nba-predict

# Full pipeline (ingest → predict → odds → value ranking)
make nba-full

# Daily production pipeline
make nba-run

# Hyperparameter tuning with Optuna
make nba-tune

# Backtesting, drift detection, feature importance, calibration
make nba-backtest
make nba-drift
make nba-importance
make nba-calibrate

# Launch dashboard
make fullstack    # Visit http://localhost:3000/nba

---

Architecture

nflalgorithm/
├── models/              # Position-specific ML models
├── data/                # CSVs, projections, odds cache
├── docs/                # Documentation
├── scripts/             # Utility scripts and tools
├── tests/               # Comprehensive test suite
├── utils/               # Helpers (player_id, defense_adjustments)
├── dashboard/           # Streamlit monitoring UI
├── logs/                # Performance tracking
├── data_pipeline.py     # Data ingestion + feature engineering
├── value_betting_engine.py  # Value detection & CLV
├── prop_integration.py  # Player matching system
└── materialized_value_view.py  # Dashboard data layer

Data Sources

Source	Purpose	Update Frequency
nflreadpy	Player stats, schedules, rosters	Nightly
The Odds API	Prop lines from multiple books	Real-time
nflverse	Snap counts, depth charts, routes	4x daily

Key Features

• Defense Adjustments: Predictions adjusted based on how players perform vs their own average against specific defenses
• Multi-Source Matching: 3-tier player matching (ID → name+team → fuzzy)
• Best Line Detection: Auto-selects best sportsbook line per player/market
• SQLite/MySQL: Flexible backend for dev or production

---

Performance Metrics

Metric	Current	Target	Status
Rushing MAE	3.6	≤ 3.0	Optimizing
Receiving MAE	4.1	≤ 3.5	Optimizing
Value Bet ROI	15.2%	> 12%	Achieved
CLV Performance	+2.3%	> 0%	Achieved
Player Match Rate	28%	> 25%	Achieved

---

Dashboard Features

Access at http://localhost:8501:

Tab	Features
Live Bets	Current value opportunities, best lines, recommendations
Performance	Model accuracy, ROI tracking, edge distribution
CLV Analysis	Closing line value tracking
System	Pipeline health, data freshness

Dashboard Controls

• Best Line Only: Toggle to show only best sportsbook per player/market
• Minimum Edge %: Filter bets by edge threshold
• Quick Bet Mode: Simplified view for fast decisions

---

Configuration

Database Setup

# Copy example config
cp .env.example .env

SQLite (Local Dev):

DB_BACKEND=sqlite
SQLITE_DB_PATH=nfl_data.db

MySQL (Production):

DB_BACKEND=mysql
DB_URL="mysql://user:pass@host:port/database"

API Keys

ODDS_API_KEY="your_odds_api_key"

Security: Never commit .env to version control!

---

Testing

make test          # Run all tests
make lint          # Run mypy
make format        # Format with black + isort
make validate      # Cross-season validation

---

Make Targets

Command	Description
make install	Smart install (UV or venv)
make ingest-nfl	Fetch real NFL data (2024+2025)
make week-predict	Generate week projections
make week-materialize	Materialize value view
make dashboard	Launch Streamlit UI
make test	Run test suite
make report	Generate shareable reports

---

Roadmap

Completed

• Defense vs position adjustments (relative performance)

• nflreadpy integration for 2025 data

• Best line deduplication

• Multi-strategy player matching

• SQLite/MySQL dual backend support

• NBA module with full pipeline (ingest, models, odds, value engine, dashboard)

• StackingRegressor ensemble (GBR + RF + XGBoost + Ridge)

• Opponent defensive ratings with z-score normalization

• Under-bet evaluation and dual-side value ranking

• Optuna hyperparameter tuning per market

• NBA production runner (7-stage orchestrator)

• Minutes × Rate decomposition with dedicated minutes model

• Monte Carlo simulation (5000 draws, correlated portfolios)

• Isotonic regression probability calibration per market

• Walk-forward backtesting with no lookahead bias

• PSI-based drift detection with 3-tier alerting

• SHAP/permutation feature importance tracking

• Injury adjustment redistribution system

• Explainability payloads (model inputs, trends, variance, confidence)

In Progress

• Game script adjustments (implied totals)
• Weather factor integration

Planned

• Line movement tracking
• Target share predictions
• Same-game correlation analysis
• Mobile-friendly dashboard

---

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'feat: Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Standards: PEP 8 | Type hints | 90%+ coverage | Documented methods

---

License

MIT License - see LICENSE file for details.

---

NFL Algorithm v2.1

Built for accuracy. Designed for profit.