# NFL Picks Provider Decisions

This document records live-provider decisions before any live adapter is enabled.

## Current Status

- Default mode: `fixture`
- Live mode: not enabled
- Approved odds provider: The Odds API
- Approved weather provider: Open-Meteo
- Approved injury/inactives provider: manual CSV overrides
- Approved usage/projection provider: nflverse/nflreadpy
- Provider-neutral schema samples: present for local validation
- Provider-specific schema samples: required before staged live adapter enablement
- Live provider calls: disabled by default

## Decision Rules

- Fixture mode must remain runnable without secrets.
- No provider key should be required for tests or static docs builds.
- No live provider call should be enabled only because a placeholder exists.
- Provider-neutral schema samples do not enable live mode.
- Provider-specific schema samples validate adapter shape but still do not enable live calls.
- Provider-specific schema fixtures should be added before live mode is enabled.
- Sanitized schema fixture notes live in `data/provider_samples/README.md`.
- Any live projection source must preserve anti-circular grading: the graded sportsbook line cannot be the only edge source.

## Provider Approval Template

Use this shape when a provider is approved:

```text
Provider:
Category:
Status: approved / pilot / rejected
Approved date:
Owner:
Credential name:
Allowed environments:
Schema fixture path:
Notes:
```

## Locked V1 Defaults

1. Odds: The Odds API for NFL moneyline, spread, total, team total, player props, sportsbook consensus, and line shopping.
2. Usage/projection: nflverse/nflreadpy for schedules, rosters, weekly stats, play-by-play-derived usage, team baselines, and cold-start priors.
3. Weather: Open-Meteo for wind, precipitation, temperature, and outdoor-stadium risk flags.
4. Injuries/inactives: manual CSV overrides for V1 role, injury, next-man-up, and inactive-state handling.
5. SportsDataIO: optional only if existing keys/config/scripts are already present; not required for V1.

## Open Decisions

1. Whether and when to replace manual injury/inactive overrides with an official automated provider.
2. Whether paid route participation / matchup fields are available for V1.5.
3. What backtested sample size promotes an NFL market from watch/research to trusted.