# ConfPickEm CLI Tools

Unified command-line interface for NFL Confidence Pick'Em optimization and analysis.

## Quick Start

```bash
# Optimize picks for mid-week with live odds
python src/confpickem/cli/optimize.py --week 10 --mode midweek --live-odds

# Check win probabilities
python src/confpickem/cli/win_probability.py --week 10 --live-odds

# Update player skills
python src/confpickem/cli/player_skills.py update --weeks 3,4,5,6,7,8,9 --week 10
```

## Available Commands

### 1. `optimize.py` - Pick Optimization

Optimizes your confidence pick assignments using Monte Carlo simulation.

**Modes:**
- `beginning` - All games are pending (start of week)
- `midweek` - Some games completed (mid-week optimization)

**Features:**
- Live Vegas odds integration
- Fast mode (10x faster, ~85% accuracy)
- Player skill integration
- Game importance analysis
- Projected standings

**Examples:**
```bash
# Mid-week with live odds (most accurate)
python src/confpickem/cli/optimize.py --week 10 --mode midweek --live-odds

# Beginning of week, fast mode
python src/confpickem/cli/optimize.py --week 10 --mode beginning --fast

# Custom simulations
python src/confpickem/cli/optimize.py --week 10 --mode beginning --num-sims 10000
```

**Full Options:**
```
--week, -w         NFL week number (required)
--league-id, -l    Yahoo league ID (default: 15435)
--mode, -m         'beginning' or 'midweek' (required)
--live-odds        Use live Vegas odds
--odds-api-key, -k The Odds API key
--fast             Fast mode (~85% accuracy, 10x speed)
--num-sims, -n     Number of simulations
--no-cache         Clear cache before loading
```

---

### 2. `win_probability.py` - Win Probability Calculator

Calculates win probabilities for all players using Monte Carlo simulation.

**Features:**
- Live Vegas odds support
- Game importance analysis per player
- Current standings tracking
- Time-point simulation (Sunday 10am, custom)

**Examples:**
```bash
# Basic win probabilities
python src/confpickem/cli/win_probability.py --week 10

# With live Vegas odds
python src/confpickem/cli/win_probability.py --week 10 --live-odds

# More simulations for accuracy
python src/confpickem/cli/win_probability.py --week 10 --num-sims 10000
```

**Full Options:**
```
--week, -w         NFL week number (required)
--league-id, -l    Yahoo league ID (default: 15435)
--live-odds        Use live Vegas odds
--odds-api-key, -k The Odds API key
--num-sims, -n     Number of simulations (default: 5000)
```

---

### 3. `player_skills.py` - Player Skills Management

Analyzes historical player performance and applies realistic skill levels to the simulator.

**Commands:**
- `analyze` - Analyze historical performance
- `apply` - Apply saved skills to simulator
- `update` - Do both: analyze then apply

**Examples:**
```bash
# Analyze historical weeks
python src/confpickem/cli/player_skills.py analyze --weeks 3,4,5,6

# Apply to current week
python src/confpickem/cli/player_skills.py apply --week 10

# Do both in one command
python src/confpickem/cli/player_skills.py update --weeks 3,4,5,6,7,8,9 --week 10
```

**Full Options:**
```
analyze:
  --weeks, -w      Comma-separated week numbers (required)
  --league-id, -l  Yahoo league ID (default: 15435)

apply:
  --week, -w       NFL week number (required)
  --league-id, -l  Yahoo league ID (default: 15435)

update:
  --weeks          Weeks to analyze (required)
  --week, -w       Week to apply to (required)
  --league-id, -l  Yahoo league ID (default: 15435)
```

---

## Prerequisites

### Required Files

1. **cookies.txt** - Yahoo session cookies
   ```
   # Save your Yahoo cookies to cookies.txt in project root
   # Format: Netscape HTTP Cookie File
   ```

2. **current_player_skills.json** (optional) - Player skill levels
   ```
   # Generated by player_skills.py analyze/update
   # Used by optimize.py for realistic player modeling
   ```

### Environment Variables

```bash
# Set your Odds API key (optional but recommended)
export ODDS_API_KEY=your_key_here

# Then you can omit --odds-api-key flag
python src/confpickem/cli/optimize.py --week 10 --mode midweek --live-odds
```

---

## Typical Workflow

### Weekly Routine

**Beginning of Week:**
```bash
# 1. Update player skills (once per season, or when you want to refresh)
python src/confpickem/cli/player_skills.py update --weeks 3,4,5,6,7,8,9 --week 10

# 2. Get your optimal picks (fast mode for quick decisions)
python src/confpickem/cli/optimize.py --week 10 --mode beginning --fast
```

**Mid-Week (After Thursday Night Football):**
```bash
# Re-optimize with live odds and completed game results
python src/confpickem/cli/optimize.py --week 10 --mode midweek --live-odds
```

**Check Your Position:**
```bash
# See everyone's win probabilities
python src/confpickem/cli/win_probability.py --week 10 --live-odds
```

---

## Output Files

All scripts generate output files with results:

- **Optimization**: `NFL_Week{N}_MidWeek_LiveOdds_{Player}_{Timestamp}.txt`
- **Win Probability**: Console output only (for now)
- **Player Skills**: `current_player_skills.json`

---

## Tips & Best Practices

### 1. Use Live Odds When Possible
Live Vegas odds are more accurate than Yahoo spreads:
```bash
--live-odds --odds-api-key YOUR_KEY
```

### 2. Mid-Week Re-Optimization
After Thursday/Friday games, re-optimize with `--mode midweek` to account for completed results.

### 3. Fast Mode for Quick Decisions
Use `--fast` when you need results quickly and can accept ~85% accuracy:
```bash
--mode beginning --fast
```

### 4. Update Player Skills Periodically
Refresh player skills every few weeks with recent historical data:
```bash
player_skills.py update --weeks 7,8,9,10,11,12 --week 13
```

### 5. Use Environment Variables
Set `ODDS_API_KEY` once instead of passing it every time.

---

## Troubleshooting

### Import Errors
Always run from project root:
```bash
cd /path/to/confpickem
python src/confpickem/cli/optimize.py ...
```

### Missing cookies.txt
Ensure `cookies.txt` exists in project root with valid Yahoo session cookies.

### Odds API Errors
Check your API key and rate limits at [The Odds API](https://the-odds-api.com/).

### Slow Performance
- Use `--fast` mode for optimization
- Reduce `--num-sims` (trade accuracy for speed)
- Use cached data (don't use `--no-cache`)

---

## Getting Help

Each script has comprehensive help:
```bash
python src/confpickem/cli/optimize.py --help
python src/confpickem/cli/win_probability.py --help
python src/confpickem/cli/player_skills.py --help
```

For subcommands:
```bash
python src/confpickem/cli/player_skills.py analyze --help
```

---

## Migration from Old Scripts

See [CLI_MIGRATION_GUIDE.md](../../../CLI_MIGRATION_GUIDE.md) for detailed migration instructions from the old root-level scripts.

---

## Architecture

These CLI tools use the core `confpickem` package:
- `yahoo_pickem_scraper.py` - Data extraction
- `live_odds_scraper.py` - Vegas odds integration
- `confidence_pickem_sim.py` - Monte Carlo simulation engine

The CLI layer provides a user-friendly interface to these core components.
