# Live Provider Config

Live providers are not enabled in V1 fixture mode. This document only defines the expected configuration shape for future implementation.

## Runtime Modes

- `fixture`: default local/CI mode. Uses checked-in data and makes no provider calls.
- `sample`: reserved for sanitized provider samples. Makes no provider calls.
- `live_no_call`: online-prep mode. Validates live readiness and wiring without provider calls.
- `live`: future production mode for approved providers only.

Fixture, sample, and live-no-call modes require no secrets.

```powershell
python run_build_all.py --output-dir docs\mock --results-csv docs\mock\sample_results.csv
```

Use `.env.example` as the local template. Real keys must stay outside git.

## Future Live Mode

Expected V1 environment variables:

- `ODDS_API_KEY`: odds provider key for sportsbook markets and best-line refreshes.
- `ODDS_API_QUOTA_STATE`: optional status marker such as `available`, `limited`, `exhausted`, or `unknown`.
- `NFL_LIVE_PROVIDERS_APPROVED`: must be true before live provider calls are allowed.
- `NFL_ALLOW_PROVIDER_CALLS`: must be true before any provider-call workflow can run.
- `NFL_ALLOW_LIVE_PUBLISH`: must be true before live picks can publish.

The three live switches are separate on purpose. A valid key plus available quota can prepare the adapter path, but it cannot publish live picks without explicit human approval.

V1 providers that do not require keys:

- `nflverse/nflreadpy`: local/package-backed schedule, usage, projection baseline, and matchup source.
- `Open-Meteo`: free-first weather source for V1 planning.
- manual CSV injury/inactive overrides: local role/injury/inactive input until an automated provider is approved.

The framework should fail closed if live mode is requested without required provider configuration. Missing live config must never silently fall back to fake recommendations.

When Odds API quota is exhausted, use `live_no_call` and keep provider calls disabled. This allows adapter wiring, readiness reporting, docs generation, and fixture/sample validation without spending API calls or publishing live picks.