QuantCup Backend

QuantCup Backend is the data, modeling, artifact, and reporting layer for the QuantCup NFL prediction stack. The current backend focus is NFL regular-season prediction packages, bucket-backed model/report contracts, data freshness audits, odds/weather/availability readiness, and backend-graded analyst performance snapshots.

This repository is not the frontend product app and it is not the agent orchestration repo. quantcup_backend publishes canonical backend artifacts; quantcup_api exposes validated read models; quantcup_agent owns weekly slate and ODR orchestration; frontend/app services own product UI, auth/session UX, and protected user workflows.

Current Backend Responsibilities

• Build and refresh NFL data, warehouse, feature, prediction, and report surfaces through nflfastRv3.
• Publish canonical prediction packages under ml/prediction_artifacts/season={season}/run_id={run_id}/.
• Maintain backend-owned discovery indexes for prediction packages, workflows, reports, and training bundles.
• Audit ML artifact bucket parity before downstream consumers trust a publish.
• Audit bucket/database data freshness and explain source-window limitations.
• Produce weekly slate ODR input availability reports for agent handoff.
• Validate and grade externally published analyst pick snapshots. Backend does not create analyst picks.
• Keep report outputs explicit about forecasts, model outputs, diagnostics, source readiness, and warnings.

Current Verified State

The README was refreshed on 2026-07-06 from code, docs, reports, and the latest completed plans. Current evidence reviewed during the refresh:

• Direct nflfastRv3 CLI help renders successfully.
• The unified quantcup wrapper is the intended operator entry point. It depends on the runtime dependencies declared in pyproject.toml, including browser automation packages used by odds_scraper.
• Latest 2026 Week 1 prediction-refresh manifest: reports/ml/workflows/20260706T072903_prediction-refresh_manifest.json.
• Latest Week 1 prediction report: reports/predictions/prediction_report_2026_1_20260706_032911.md.
• Latest ML artifact parity report: reports/ml/bucket_parity/ml_artifact_bucket_parity_20260706T072912Z.md with status passed, 0 blockers, and 0 warnings.
• Latest data freshness report: reports/data_pipeline/freshness/data_freshness_20260706T093035Z.md with 56 bucket tables, 27 database tables, and warning status driven by known freshness/source-window limitations.
• Latest ODR input availability report: reports/ml/odr_input_availability/weekly_slate_odr_input_availability_2026_w01_20260706T072941.md with market and weather ready for 16 games and availability degraded for all 16 games because official injury-report windows are not open.
• Latest analyst performance report: reports/ml/analyst_performance/analyst_performance_20260706_023831.md with status empty, meaning the source snapshot exists but contains zero published picks.

The full README refresh audit is under reports/docs/.

Primary CLI Surface

Prefer the unified quantcup wrapper for discoverable operator commands:

python -m quantcup --help
python -m quantcup nflfastrv3 data --help
python -m quantcup nflfastrv3 ml --help

Current top-level groups:

• data: process, validate, warehouse, refresh-ncei-normals, freshness.
• ml: feature engineering, training, prediction, workflow orchestration, projections, analyst performance, artifact indexes, prediction package index, parity checks, ODR availability, confidence publication review, cron refresh, registry exports, training segment exports, preseason/regime diagnostics, backtesting, and window optimization.
• info: lightweight system metadata.

The installed console scripts declared in pyproject.toml are:

quantcup
nflfastrv3

Direct module commands such as python -m nflfastRv3.cli.main ... remain useful diagnostic fallbacks when isolating wrapper/bootstrap behavior.

Install And Configure

Prerequisites:

• Python 3.8 or newer. The current local docs refresh used Python 3.11.
• PostgreSQL access for database-backed warehouse and validation commands.
• S3-compatible bucket credentials for artifact publish, parity, freshness, and package-index workflows.
• Network access for provider-backed refreshes such as The Odds API, NOAA/NWS, NCEI, and nflverse/nflfastR-backed source refreshes.
• R/nflverse tooling only for workflows that call the R bridge. CLI help, docs checks, and many artifact/report tests do not require it.

Create and activate a virtual environment, then install the repo in editable mode:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Module-specific requirement files also exist for older or narrower workflows:

python -m pip install -r nflfastRv3/requirements.txt
python -m pip install -r odds_api/requirements.txt

The repo loads .env through python-dotenv where supported. Do not commit .env or local credentials. Committed code currently recognizes these configuration families:

Area	Variables
Local/backend PostgreSQL	NFLFASTR_DB_URL or NFLFASTR_DB_HOST, NFLFASTR_DB_PORT, NFLFASTR_DB_USER, NFLFASTR_DB_PASSWORD, NFLFASTR_DB_NAME
API/production PostgreSQL routing	SEVALLA_QUANTCUP_DB_URL or matching SEVALLA_QUANTCUP_DB_* host/port/user/password/name variables
Analytics PostgreSQL routing	ANALYTICS_DB_URL or matching ANALYTICS_DB_* host/port/user/password/name variables
Bucket/object storage	BUCKET_NAME or SEVALLA_BUCKET_NAME; BUCKET_ENDPOINT_URL or SEVALLA_BUCKET_ENDPOINT; BUCKET_ACCESS_KEY, AWS_ACCESS_KEY_ID, or SEVALLA_BUCKET_ACCESS_KEY_ID; BUCKET_SECRET_KEY, AWS_SECRET_ACCESS_KEY, or SEVALLA_BUCKET_SECRET_ACCESS_KEY; optional BUCKET_REGION or SEVALLA_BUCKET_REGION
Odds API	ODDS_API_KEY, optional PAID_ODDS_API_KEY, and optional BACKFILL_* settings from odds_api/config/settings.py
Runtime mode	optional ENVIRONMENT with values such as local, testing, or production

Provider credentials are only required for workflows that call those providers or publish artifacts. Dry-run and collect-only checks can usually run with a smaller local configuration.

Common Operator Workflows

Inspect workflow steps without changing artifacts:

python -m quantcup nflfastrv3 ml workflow prediction-refresh --model-name game_outcome --season 2026 --week 1 --policy auto --dry-run
python -m quantcup nflfastrv3 ml cron-refresh --season 2026 --week 1 --dry-run

Refresh a prediction package when model approval already exists:

python -m quantcup nflfastrv3 ml workflow prediction-refresh --model-name game_outcome --season 2026 --week 1 --policy auto

Audit data freshness:

python -m quantcup nflfastrv3 data freshness --season 2026 --week 1

Audit prediction package and ML artifact parity:

python -m quantcup nflfastrv3 ml prediction-package-index --season 2026 --validate-bucket-refs
python -m quantcup nflfastrv3 ml artifact-indexes --validate-bucket-refs
python -m quantcup nflfastrv3 ml artifact-parity --prediction-season 2026 --training-seasons 2023-2025

Audit backend inputs before agent/ODR runs:

python -m quantcup nflfastrv3 ml odr-input-availability --season 2026 --week 1

Review confidence gates without changing publication policy:

python -m quantcup nflfastrv3 ml confidence-publication-review --season 2026 --week 1

Grade externally published analyst pick snapshots:

python -m quantcup nflfastrv3 ml analyst-performance --season 2026 --week 1 --publish-to-bucket

Do not present these model outputs as financial or betting advice. The prediction and confidence reports are planning and product-data artifacts with explicit uncertainty and source-readiness warnings.

Artifact And Report Contracts

Canonical prediction package:

ml/prediction_artifacts/season={season}/run_id={run_id}/

Key files:

• prediction_package_manifest_v1.json
• prediction_final_v1.parquet
• prediction_policy_decisions_v1.parquet
• model_outputs_v1.parquet
• prediction_game_context_v1.parquet
• prediction_game_context_summary_v1.parquet
• season_story_summary_v1.parquet

Discovery and runtime indexes:

• ml/prediction_artifacts/index/season={season}/prediction_package_index_v1.json
• ml/workflows/index/ml_workflow_run_index_v1.json
• ml/reports/index/report_artifact_index_v1.json
• ml/training/index/season={season}/training_run_index_v1.json

Model registry and context evidence:

• ml/model_registry/model_approval_registry_v1.json
• ml/model_registry/model_context_performance_registry_v1.json

Important local report families:

• reports/predictions/
• reports/ml/workflows/
• reports/ml/bucket_parity/
• reports/ml/odr_input_availability/
• reports/ml/confidence_publication_review/
• reports/ml/analyst_performance/
• reports/ml/model_registry/
• reports/data_pipeline/freshness/
• reports/ops/freshness/
• reports/ops/cron_refresh/
• reports/training/
• reports/index/

Local reports/index/* files are debug/development outputs. Runtime consumers should prefer bucket-exported discovery indexes.

Main Packages

• nflfastRv3/: primary NFL data, warehouse, feature, ML, workflow, artifact, and reporting implementation.
• commonv2/: shared database, logging, config, and persistence utilities.
• odds_api/: The Odds API ingestion and odds-market data pipeline.
• weather/: forecast and historical/climatology weather helpers.
• odds_scraper/: sportsbook scraper code. It currently has optional runtime dependency requirements that can affect unified CLI bootstrap.
• cfd/, sportsdataverse/, espn_unofficial_api/, soccerAnimate/, and api_sports/: secondary or historical multi-sport/data access surfaces.
• docs/: architecture, data contracts, operations playbooks, planning queue, completed-plan evidence, and lessons learned.
• reports/: generated local audit/report artifacts.
• tests/: pytest coverage for CLI bootstrap, artifact contracts, workflows, reports, prediction packages, analyst performance, ODR readiness, freshness, and related data/ML behavior.

Data And Source Boundaries

The backend uses both bucket/object storage and PostgreSQL-backed surfaces. Current data freshness reporting distinguishes bucket and database availability instead of treating either one as implicitly complete.

Do not expose a warehouse or feature table directly to frontend consumers just because it exists. Product APIs should validate artifact contracts, field classification, access tiering, freshness, and source warnings before exposing fields.

Known source limitations as of the 2026-07-06 refresh:

• Official Week 1 player availability is not_open / unsupported_until_injury_reports; historical priors remain available but must not be displayed as current official availability.
• Future weather may be climatology-backed until the supported forecast window opens.
• Medium-confidence model leans are not the same as published analyst picks. Current high-confidence publication gate remains HIGH >= 0.80.
• Analyst performance is backend-graded from externally published snapshots. Backend should not infer picks from model predictions, ODR prose, or frontend content.

Documentation Map

• Docs hub: docs/README.md
• Operations playbook: docs/04-operations/Operations_Playbook.md
• Planning sequence: docs/05-planning/planning_sequence.md
• Live data source contract: docs/03-data-pipeline/LIVE_DATA_SOURCE_CONTRACT.md
• Prediction API artifact contract: docs/03-data-pipeline/ml-pipeline/PREDICTION_API_ARTIFACT_CONTRACT_V1.md
• Analyst performance artifact contract: docs/03-data-pipeline/ml-pipeline/ANALYST_PERFORMANCE_ARTIFACT_CONTRACT_V1.md
• Feature pipeline contract: docs/03-data-pipeline/ml-pipeline/FEATURE_PIPELINE_CONTRACT.md
• ML strategy/status docs: docs/03-data-pipeline/ml-pipeline/
• Module README: nflfastRv3/README.md

For meaningful feature work, use docs/05-planning/ and keep plans in the correct lifecycle folder: in-review/, in-progress/, completed/, backlog/, or archive/.

Development Notes

Use the narrowest relevant tests for the changed surface. Examples:

python -m pytest tests/test_cli_bootstrap.py -q
python -m pytest tests/test_ml_workflow_cli.py -q
python -m pytest tests/test_artifact_discovery_indexes.py -q
python -m pytest tests/test_ml_artifact_bucket_parity.py -q
python -m pytest tests/test_data_freshness.py -q
python -m pytest tests/test_weekly_slate_odr_availability.py -q
python -m pytest tests/test_analyst_performance.py -q

Generated reports and bucket artifacts can be large and may include sensitive environment-derived data. Do not stage unrelated generated reports, .env files, credentials, tokens, or local operator artifacts.