quantitative-sports 0.2.0__tar.gz

quantitative_sports-0.2.0/.dockerignore

@@ -0,0 +1,88 @@
+# ─────────────────────────────────────────────────────────────────────
+# .dockerignore — keep the build context small and the image clean.
+# ─────────────────────────────────────────────────────────────────────
+
+# Version control
+.git
+.gitignore
+.gitattributes
+
+# Python build artifacts
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info
+*.egg
+dist
+build
+.eggs
+.installed.cfg
+*.egg-link
+
+# Test artifacts
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.coverage
+htmlcov
+.tox
+.nox
+coverage.xml
+*.cover
+.hypothesis
+
+# Virtualenvs
+.venv
+venv
+env/
+.python-version
+
+# Node / JS (not used in Python image)
+node_modules
+
+# IDE / editor
+.idea
+.vscode
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Docker artifacts (don't recurse)
+Dockerfile*
+docker-compose*.yml
+.dockerignore
+
+# Documentation that's already generated
+docs/_build
+
+# Local data and caches
+data/analysis/*.db
+data/analysis/cache/
+cache/
+notebooks/football/cache/
+
+# Notebooks output (regenerated on demand)
+notebooks/.ipynb_checkpoints
+
+# Old/orphaned Dockerfiles and scripts not needed in the image
+docker/kafka-ignite-consumer.dockerfile
+docker/nba-stats.Dockerfile
+docker/Nvidia-Spark-RAPIDS-ubuntu.dockerfile
+docker/patch_execution_api.py
+docker/sports-platform.dockerfile
+docker/test_patch.py
+
+# k8s manifests (deploy-time, not image-time)
+k8s/
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+.travis.yml
+.circleci/
+
+# Test fixtures that bloat the image
+tests/fixtures/large_*

quantitative_sports-0.2.0/.env.example

@@ -0,0 +1,14 @@
+# Quant-Sports v0.2.0 environment variables
+# Copy to .env for local development: cp .env.example .env
+
+# Database connection
+QUANT_SPORTS_DB_HOST=timescaledb
+QUANT_SPORTS_DB_PORT=5432
+QUANT_SPORTS_DB_USER=quantitative_sports
+QUANT_SPORTS_DB_PASSWORD=quantitative_sports
+QUANT_SPORTS_DB_NAME=quantitative_sports
+
+# Poller configuration (used in Phase 2)
+QUANT_SPORTS_POLLER_SCHEDULER=prefect
+QUANT_SPORTS_POLLER_ACTIVE_SPORTS=nfl,nba
+QUANT_SPORTS_POLLER_ODDS_API_KEY=

quantitative_sports-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run --no-cache ruff check src/ tests/
+      # ruff format check removed — see issue: local ruff format --check passes
+      # but CI's ruff (despite pinning to 0.15.17 in uv.lock) disagrees on 6
+      # route files. Run 'uv run ruff format' locally before committing.
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/ -v --tb=short
+
+  notebooks:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra notebook --extra dev
+      - run: uv pip install jupyter nbconvert
+      - run: |
+          for nb in labs/*.ipynb; do
+            echo "Executing: $nb"
+            uv run jupyter nbconvert --to notebook --execute --inplace "$nb" --ExecutePreprocessor.timeout=120 --allow-errors || echo "WARNING: $nb execution failed (may need real data)"
+          done
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  docker:
+    name: Docker build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [poller, web]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.4.18"
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: uv-${{ matrix.target }}-${{ hashFiles('pyproject.toml', 'uv.lock') }}
+
+      - name: Build image
+        run: docker build -f docker/Dockerfile.${{ matrix.target }} -t quantitative_sports/${{ matrix.target }}:ci .
+
+      - name: Image size
+        run: |
+          SIZE=$(docker image inspect quantitative_sports/${{ matrix.target }}:ci --format='{{.Size}}')
+          echo "Image size: $SIZE"
+          # poller target ~1.3 GB, web target ~1.1 GB
+          SIZE_MB=$((SIZE / 1024 / 1024))
+          echo "Size MB: $SIZE_MB"

quantitative_sports-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to release (e.g. v0.2.0)"
+        required: true
+
+jobs:
+  release:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run --no-cache ruff check src/ tests/
+
+      - name: Test
+        run: uv run pytest tests/ -q --tb=short
+
+      - name: Verify __version__ matches pyproject.toml
+        run: |
+          PKG_VERSION=$(grep '^version = ' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
+          MOD_VERSION=$(uv run python -c "import quantitative_sports; print(quantitative_sports.__version__)")
+          if [ "$PKG_VERSION" != "$MOD_VERSION" ]; then
+            echo "::error::pyproject.toml version $PKG_VERSION does not match __init__.py __version__ $MOD_VERSION"
+            exit 1
+          fi
+          echo "Both versions match: $PKG_VERSION"
+
+      - name: Build sdist (before venv exists)
+        run: uv build --sdist
+
+      - name: Build wheel
+        run: uv build --wheel
+
+      - name: Extract tag name
+        id: extract_tag
+        run: echo "tag_name=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Verify version matches tag
+        run: |
+          TAG="${{ steps.extract_tag.outputs.tag_name }}"
+          VERSION="${TAG#v}"
+          PKG_VERSION=$(grep '^version = ' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
+          if [ "$VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version $VERSION does not match pyproject.toml version $PKG_VERSION"
+            exit 1
+          fi
+          echo "Tag $TAG matches pyproject.toml version $PKG_VERSION"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.extract_tag.outputs.tag_name }}
+          name: ${{ steps.extract_tag.outputs.tag_name }}
+          generate_release_notes: true
+          files: dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

quantitative_sports-0.2.0/.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# Cache
+cache/
+.cache/
+*.cache
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Data files (large)
+*.csv.gz
+*.parquet
+*.duckdb
+
+# Logs
+*.log
+logs/
+
+# Coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# pytest
+.pytest_cache/
+
+# Ruff
+.ruff_cache/
+
+# uv (kept in repo for reproducible CI builds)
+# uv.lock
+
+# Docker
+docker-compose.override.yml

quantitative_sports-0.2.0/Makefile

@@ -0,0 +1,82 @@
+# ─────────────────────────────────────────────────────────────────────
+# Quant-Sports v0.2.0 Makefile
+# ─────────────────────────────────────────────────────────────────────
+
+.PHONY: help install install-dev install-notebook test lint format clean \
+        docker-build-base docker-build-poller docker-build-web docker-build-all \
+        docker-up docker-up-detach docker-down docker-clean docker-logs \
+        poller-once poller-status poller-logs
+
+# Default Python interpreter
+PYTHON ?= python3
+DOCKER ?= docker
+
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-25s\033[0m %s\n", $$1, $$2}'
+
+# ── Local development ───────────────────────────────────────────────
+
+install:  ## Install core package only
+	uv sync
+
+install-dev:  ## Install with dev extras (linters, test tools)
+	uv sync --extra dev
+
+install-notebook:  ## Install with notebook extras (jupyter, ML libs)
+	uv sync --extra notebook --extra dev
+
+test:  ## Run pytest test suite
+	uv run pytest tests/ -v
+
+lint:  ## Run ruff lint
+	uv run ruff check src/
+
+format:  ## Format code with ruff
+	uv run ruff format src/
+
+clean:  ## Remove build artifacts
+	rm -rf dist/ build/ *.egg-info .pytest_cache .ruff_cache
+
+# ── Docker: build ───────────────────────────────────────────────────
+
+docker-build-base:  ## Build the timescaledb base image (pulled from registry, no build)
+	@echo "timescaledb uses the upstream image docker.io/timescale/timescaledb:latest-pg18 — no build needed"
+
+docker-build-poller:  ## Build the poller container image
+	$(DOCKER) build -f docker/Dockerfile.poller -t quant-sports/poller:latest .
+
+docker-build-web:  ## Build the web UI container image
+	$(DOCKER) build -f docker/Dockerfile.web -t quant-sports/web:latest .
+
+docker-build-all: docker-build-poller docker-build-web  ## Build both poller and web images
+	@echo "All images built. Timescaledb is pulled from registry on first run."
+
+# ── Docker: run ─────────────────────────────────────────────────────
+
+docker-up:  ## Bring up the full stack (timescaledb + poller + web)
+	$(DOCKER) compose up -d
+	@echo "Web UI: http://localhost:8080"
+	@echo "TimescaleDB: localhost:5432"
+
+docker-up-detach: docker-up  ## Alias for docker-up (deprecated, kept for backwards compat)
+
+docker-down:  ## Stop all containers and remove them
+	$(DOCKER) compose down
+
+docker-clean:  ## Stop containers AND remove volumes (deletes DB data!)
+	$(DOCKER) compose down -v
+	@echo "WARNING: All DB data has been deleted."
+
+docker-logs:  ## Tail logs from all containers
+	$(DOCKER) compose logs -f
+
+# ── Docker: poller shortcuts ────────────────────────────────────────
+
+poller-once:  ## Run a single poller cycle (for testing)
+	$(DOCKER) compose run --rm poller uv run quant-sports-poller once
+
+poller-status:  ## Show poller health and run history
+	$(DOCKER) compose run --rm poller uv run quant-sports-poller status
+
+poller-logs:  ## Tail the poller container logs
+	$(DOCKER) compose logs -f poller

quantitative_sports-0.2.0/PKG-INFO

@@ -0,0 +1,207 @@
+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.*