# NFL Picks Architecture

This repo follows the Sacboyz MLB operating pattern while keeping NFL-specific behavior in standalone modules.

## Core Flow

1. Load fixture or future provider data.
2. Build team context and market blends.
3. Build conservative baseline projections.
4. Evaluate six visible checks and hidden sub-gates.
5. Grade candidates into A, B, Review, Fade, Lean, or Abstain.
6. Render static docs artifacts and tracker/audit outputs.
7. Validate artifacts through the quality gate.

## Key Modules

- `nfl_picks/config.py`: V1 markets, thresholds, states, confidence tiers, lifecycle rules.
- `nfl_picks/contracts.py`: slate, market, projection, signal, candidate, and bet dataclasses.
- `nfl_picks/runner.py`: fixture slate evaluation.
- `nfl_picks/grading.py`: state and grade resolution.
- `nfl_picks/checks.py`: six visible check evaluation.
- `nfl_picks/scoring.py`: BetScore calculation.
- `nfl_picks/line_shopping.py`: best-line selection and publish-time edge checks.
- `nfl_picks/market_blend.py`: multi-book consensus and coverage quality.
- `nfl_picks/opportunity.py`: role, injury, next-man-up, and opponent injury classifications.
- `nfl_picks/matchup.py`: defensive matchup color logic and injury override.
- `nfl_picks/correlation.py`: same-game correlation and contradiction guards.
- `nfl_picks/team_context.py`: implied team totals and game-script context.
- `nfl_picks/report.py`: static HTML report.
- `nfl_picks/tracker.py`: tracker CSV rows.
- `nfl_picks/settlement.py`: win/loss/push/no-action settlement.
- `nfl_picks/backtest.py`: correlation-weighted summaries.
- `nfl_picks/market_health.py`: lifecycle recommendation rollups.
- `nfl_picks/artifact_validation.py`: generated artifact validation.
- `nfl_picks/adapters.py`: fixture and future live-provider adapter registry.
- `nfl_picks/env_config.py`: runtime mode and provider environment validation.
- `nfl_picks/live_enablement_checklist.py`: combined gate separating online prep from live-call enablement.
- `nfl_picks/provider_runtime.py`: fail-closed provider-call policy for no-call and quota-exhausted modes.
- `nfl_picks/provider_dry_run.py`: no-call provider dry-run plan by data-source family.
- `nfl_picks/provider_sample_request.py`: sanitized schema sample request packet for future provider review.
- `nfl_picks/provider_sample_intake.py`: offline intake checklist for approved sanitized provider samples.
- `nfl_picks/provider_sample_validation.py`: sanitized provider sample file validation against source contracts.
- `nfl_picks/provider_sample_redaction_audit.py`: redaction audit for sanitized provider sample files.
- `nfl_picks/provider_sample_review_summary.py`: compact provider sample handoff summary.
- `nfl_picks/provider_sample_collection_packet.py`: copy-ready Markdown checklist for future provider sample collection.
- `nfl_picks/network_guard_audit.py`: source scan for direct network-call primitives.
- `nfl_picks/runtime_mode_matrix.py`: fixture/sample/live-no-call/live policy matrix.

## Runtime Entrypoints

- `run_mock.py`: build the fixture report, audit, and tracker.
- `run_build_all.py`: build the full fixture artifact set.
- `run_validate_artifacts.py`: validate generated docs/mock outputs.
- `run_live_readiness.py`: summarize live, no-call, provider, quota, and environment readiness.
- `run_live_enablement_checklist.py`: summarize gates required before enabling live provider calls.
- `run_provider_dry_run.py`: generate a no-call provider dry-run plan.
- `run_provider_sample_request.py`: generate the sanitized provider sample request packet.
- `run_provider_sample_intake.py`: generate the provider sample intake checklist.
- `run_provider_sample_validation.py`: validate sanitized provider sample files.
- `run_provider_sample_redaction_audit.py`: audit sanitized provider samples for redaction issues.
- `run_provider_sample_review_summary.py`: roll provider sample readiness into one review packet.
- `run_provider_sample_collection_packet.py`: write the Markdown provider sample collection checklist.
- `run_network_guard_audit.py`: audit source files for direct network-provider calls.
- `run_runtime_mode_matrix.py`: generate the runtime mode and quota policy matrix.
- `run_quality_gate.py`: run tests, build artifacts, and validate outputs.

## Boundaries

- Live providers are not enabled in fixture, sample, or live-no-call mode.
- Future provider-backed code should call `require_provider_calls_enabled` before any network call.
- Provider decisions live in `docs/PROVIDER_DECISIONS.md`.
- Sanitized provider schema notes live in `data/provider_samples/README.md`.
- No NFL market inherits trusted status from MLB.
- Team bets remain Lean / Review / No Play until validated.