Metadata-Version: 2.4
Name: quantcup-backend
Version: 0.1.6
Summary: QuantCup backend data, modeling, artifact, and reporting tools
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: boto3>=1.34.0
Requires-Dist: joblib>=1.3.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas<2.4,>=2.2.3
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: sqlalchemy>=1.4.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: requests>=2.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: nfl-data-py>=0.3.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pytz>=2021.1
Requires-Dist: pytest>=7.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: agentql>=1.19.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: scipy>=1.11.0
Requires-Dist: xgboost>=2.0.0

# 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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

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

Audit data freshness:

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

Audit prediction package and ML artifact parity:

```powershell
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:

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

Review confidence gates without changing publication policy:

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

Grade externally published analyst pick snapshots:

```powershell
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:

```text
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`](docs/README.md)
- Operations playbook:
  [`docs/04-operations/Operations_Playbook.md`](docs/04-operations/Operations_Playbook.md)
- Planning sequence:
  [`docs/05-planning/planning_sequence.md`](docs/05-planning/planning_sequence.md)
- Live data source contract:
  [`docs/03-data-pipeline/LIVE_DATA_SOURCE_CONTRACT.md`](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`](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`](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`](docs/03-data-pipeline/ml-pipeline/FEATURE_PIPELINE_CONTRACT.md)
- ML strategy/status docs:
  [`docs/03-data-pipeline/ml-pipeline/`](docs/03-data-pipeline/ml-pipeline/)
- Module README:
  [`nflfastRv3/README.md`](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:

```powershell
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.
