Metadata-Version: 2.4
Name: quantitative_sports
Version: 0.2.0
Summary: QuantLib for sports betting — open-source quantitative analysis toolkit
Project-URL: Homepage, https://github.com/Veedubin/quantitative-sports
Project-URL: Repository, https://github.com/Veedubin/quantitative-sports
Project-URL: Issues, https://github.com/Veedubin/quantitative-sports/issues
Project-URL: Changelog, https://github.com/Veedubin/quantitative-sports/releases
Author-email: VeeDubin <veedubin@neuralgentics.dev>
License: MIT
Keywords: backtesting,expected-value,kelly-criterion,middling,nfl,odds-api,quantitative-finance,sports-betting,timescaledb,xgboost
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: click>=8.0.0
Requires-Dist: duckdb>=0.9.0
Requires-Dist: httpx[http2]>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-dateutil>=2.9
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: matplotlib>=3.8.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: prefect>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: scikit-learn>=1.5.0; extra == 'dev'
Requires-Dist: scipy>=1.14.0; extra == 'dev'
Requires-Dist: seaborn>=0.13.0; extra == 'dev'
Requires-Dist: testcontainers>=4.7.0; extra == 'dev'
Requires-Dist: xgboost>=2.1.0; extra == 'dev'
Provides-Extra: notebook
Requires-Dist: ipykernel>=6.29.0; extra == 'notebook'
Requires-Dist: jupyter>=1.0.0; extra == 'notebook'
Requires-Dist: matplotlib>=3.8.0; extra == 'notebook'
Requires-Dist: nba-api>=1.8.0; extra == 'notebook'
Requires-Dist: nbconvert>=7.16.0; extra == 'notebook'
Requires-Dist: nbformat>=5.10.0; extra == 'notebook'
Requires-Dist: openpyxl>=3.1.0; extra == 'notebook'
Requires-Dist: pillow>=10.0.0; extra == 'notebook'
Requires-Dist: playwright>=1.57.0; extra == 'notebook'
Requires-Dist: psycopg2-binary>=2.9.9; extra == 'notebook'
Requires-Dist: scikit-learn>=1.5.0; extra == 'notebook'
Requires-Dist: scipy>=1.14.0; extra == 'notebook'
Requires-Dist: seaborn>=0.13.0; extra == 'notebook'
Requires-Dist: sqlalchemy>=2.0.0; extra == 'notebook'
Requires-Dist: xgboost>=2.1.0; extra == 'notebook'
Requires-Dist: xlsxwriter>=3.1.0; extra == 'notebook'
Provides-Extra: poller
Requires-Dist: asyncpg>=0.29.0; extra == 'poller'
Requires-Dist: httpx[http2]>=0.27.0; extra == 'poller'
Requires-Dist: prefect>=3.0.0; extra == 'poller'
Requires-Dist: prometheus-client>=0.19.0; extra == 'poller'
Requires-Dist: pydantic-settings>=2.1.0; extra == 'poller'
Requires-Dist: python-json-logger>=2.0.0; extra == 'poller'
Provides-Extra: web
Requires-Dist: aiofiles>=23.0.0; extra == 'web'
Requires-Dist: asyncpg>=0.29.0; extra == 'web'
Requires-Dist: fastapi>=0.109.0; extra == 'web'
Requires-Dist: jinja2>=3.1.0; extra == 'web'
Requires-Dist: markdown>=3.6.0; extra == 'web'
Requires-Dist: nbconvert>=7.16.0; extra == 'web'
Requires-Dist: nbformat>=5.10.0; extra == 'web'
Requires-Dist: python-multipart>=0.0.6; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'web'
Description-Content-Type: text/markdown

# Quant-Sports — Quantitative Sports Betting Toolkit

**Mathematical toolkit for sports betting. Bring your own data.**

![v0.2.0](https://img.shields.io/badge/version-v0.2.0-blue)
![Tests](https://img.shields.io/badge/tests-775_passing-brightgreen)
![License: MIT](https://img.shields.io/badge/license-MIT-green)

Quant-Sports is a professional-grade quantitative analysis toolkit designed for analysts, not tipsters. Think of it as "QuantLib for sports betting"—it provides the rigorous mathematical infrastructure needed to translate raw odds and statistics into actionable, risk-adjusted betting signals.

## Quick Start

```bash
# 1. Install the desktop package
uv add quantitative_sports[notebook]

# 2. Start the storage layer
cd ~/Projects/Infrastructure/quantitative_sports
make docker-up

# 3. Open a notebook
uv run jupyter lab labs/01_getting_started.ipynb
```

## Architecture

Quant-Sports v0.2.0 is decoupled into three primary layers to ensure scalability and separation of concerns:

```text
+-----------------------+       +-------------------------------------------+
|    Desktop Package    |       |              Docker Compose Stack         |
| (CLI, Library, Labs)   |       | (timescaledb + poller + web dashboard)    |
+-----------+-----------+       +-------------------+-----------------------+
            |                                       |
            |         Data Flow                    |
            |  [ Poller ] ----> [ TimescaleDB ] <---+
            |       |                |
            +-------+----------------+
                    |
                    v
            [ Notebooks / CLI / Web UI ]
```

- **Desktop Package**: The core Python library providing the math, models, and CLI.
- **Infrastructure Stack**: 
    - `timescaledb`: High-performance time-series storage (PG 18 + TimescaleDB 2.28).
    - `quant-sports/poller`: Background container for data collection (Odds API, ESPN).
    - `quant-sports/web`: Operations dashboard for health monitoring and metrics.
- **Data Flow**: The poller fetches live data $\rightarrow$ writes to TimescaleDB $\rightarrow$ consumed by the web dashboard and your analytical notebooks.

## Features

### 🧮 Betting Mathematics
- **Expected Value (EV)**: Precise calculation including implied probability and vig removal.
- **Kelly Criterion**: Full and fractional Kelly sizing for optimal bankroll growth.
- **Middling Detection**: Automatic identification of multi-book spread/total middles.

### 📈 Predictive Modeling
- **NFL Game Prediction**: XGBoost ensemble for win probability, spreads, and totals.
- **Ratings Systems**: Implementation of Elo, Massey, PageRank, and Glicko systems.
- **Custom Strategies**: Extensible registry to define, backtest, and deploy your own logic.

### ⚙️ Infrastructure & Ops
- **Backtesting Engine**: Professional walk-forward validation and parallel execution.
- **Live Data**: Integrated polling for Odds API and ESPN injury reports.
- **Web Ops Dashboard**: Monitor poller health, run history, log tailing, and system metrics.

## Package Layout

```
quantitative_sports/
├── core/           # Betting math (EV, Kelly, middling, metrics)
├── models/         # XGBoost, ratings, predictive models
├── backtest/       # Backtest engine
├── data/           # Data sources (Odds API, ESPN, nflverse)
├── infra/
│   ├── db/         # TimescaleDB connection, schema, queries, writers
│   └── poller/     # Background data fetcher
├── web/            # FastAPI ops dashboard
└── cli/            # Click commands

labs/               # 10 comprehensive Jupyter walkthroughs
docker/
├── Dockerfile.poller
├── Dockerfile.web
└── init-db.sql     # TimescaleDB schema
docker-compose.yml  # timescaledb + poller + web
```

## Running

### Installation
```bash
uv add quantitative_sports[notebook]
```

### Usage
```bash
# Run a CLI command
quantitative_sports nfl predict-game

# Start the docker stack (DB, Poller, Web)
make docker-up

# Run tests
make test
```

## Configuration

```bash
cp .env.example .env
# Edit .env with your Odds API key
# Then: make docker-up
```

## Disclaimer

*Quant-Sports is a mathematical toolkit provided for analytical purposes only. It does not provide betting advice or guaranteed returns. You are solely responsible for compliance with your local laws and regulations regarding sports wagering.*
