# AI Smart Scheduling Environment Configuration

## Overview

This document details the environment variables required for the AI Smart Scheduling feature (Spec 026).

## Required Variables

### OPENAI_API_KEY

**Required**: Yes

The API key for OpenAI. Obtain from https://platform.openai.com/api-keys.

```bash
OPENAI_API_KEY=sk-proj-...
```

**Security Notes:**
- Never commit this to version control
- Store in secure secrets management (AWS Secrets Manager, etc.)
- Rotate keys periodically
- Use project-scoped keys when possible

### ABLY_KEY

**Required**: Yes (for real-time notifications)

Ably API key for real-time push notifications. Format: `keyName:keySecret`.

```bash
ABLY_KEY=xVLyHw.tQghGA:AbCdEfGhIjKlMnOp
```

**Notes:**
- Must have publish capability for `ai-schedule-*` channels
- Client-side uses same key (or public subscribe-only key)

## Optional Variables

### OPENAI_MODEL

**Required**: No
**Default**: Uses fallback chain (gpt-5-mini → gpt-5 → gpt-4o-mini)

Override the default model selection.

```bash
OPENAI_MODEL=gpt-4o-mini
```

**Recommended Models:**
- `gpt-4o-mini` - Fast, cost-effective (recommended for production)
- `gpt-4o` - Higher capability, higher cost
- `gpt-5-mini` - Newest model (when available)

### AI_SCHEDULE_MAX_RUNS_PER_WEEK

**Required**: No
**Default**: 5

Maximum AI schedule generations per pay week per store.

```bash
AI_SCHEDULE_MAX_RUNS_PER_WEEK=5
```

**Notes:**
- Set to 0 to disable the feature
- Higher values increase OpenAI costs
- Resets at each pay period boundary

## Example .env Configuration

```bash
# AI Smart Scheduling (Spec 026)
# =============================================================================

# Required: OpenAI API key for AI schedule generation
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional: Override default model (default: fallback chain)
# OPENAI_MODEL=gpt-4o-mini

# Optional: Rate limit per store per pay week (default: 5)
# AI_SCHEDULE_MAX_RUNS_PER_WEEK=5

# Required: Ably key for real-time notifications
ABLY_KEY=xVLyHw.xxxxx:xxxxxxxxxxxxxxxxxxxx
```

## Environment-Specific Settings

### Development

```bash
# Use a separate API key for development
OPENAI_API_KEY=sk-proj-dev-xxxxx

# Lower rate limit for testing
AI_SCHEDULE_MAX_RUNS_PER_WEEK=10

# Fast model for quicker iterations
OPENAI_MODEL=gpt-4o-mini
```

### Staging

```bash
# Staging API key
OPENAI_API_KEY=sk-proj-staging-xxxxx

# Standard rate limit
AI_SCHEDULE_MAX_RUNS_PER_WEEK=5

# Match production model
# OPENAI_MODEL=  (use default)
```

### Production

```bash
# Production API key (with usage limits configured in OpenAI dashboard)
OPENAI_API_KEY=sk-proj-prod-xxxxx

# Standard rate limit
AI_SCHEDULE_MAX_RUNS_PER_WEEK=5

# Use default model fallback chain
# OPENAI_MODEL=  (use default)
```

## Verifying Configuration

### Check API Key

```bash
# Test OpenAI connectivity (from server)
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### Check Ably Key

```bash
# Test Ably connectivity
curl "https://rest.ably.io/channels/test/messages" \
  -u "$ABLY_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"data":"test"}'
```

### Run Integration Tests

```bash
# Run AI scheduling integration tests
./test.sh --filter="Integration\\Scheduling\\AiScheduling"

# Run with live OpenAI calls
./test.sh --group=openai-live
```

## Troubleshooting

### "OPENAI_API_KEY not configured"

The API key is missing or empty.

```bash
# Check if variable is set
echo $OPENAI_API_KEY

# Ensure it's in .env file
grep OPENAI_API_KEY .env
```

### "OpenAI API error (401)"

Invalid or expired API key.

```bash
# Verify key is valid
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### "OpenAI API error (429)"

Rate limited by OpenAI (not our internal limit).

- Check OpenAI dashboard for quota
- Consider upgrading OpenAI plan
- Wait and retry

### "Model not found"

The configured model is not available.

```bash
# List available models
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | grep -E "gpt-4|gpt-5"

# Remove OPENAI_MODEL to use fallback chain
unset OPENAI_MODEL
```

## Cost Monitoring

Monitor OpenAI usage in the OpenAI dashboard:
https://platform.openai.com/usage

**Estimated costs per generation:**
- Input tokens: ~2,000-5,000 tokens (shifts + employees data)
- Output tokens: ~500-2,000 tokens (assignments + reasoning)
- Cost per generation: ~$0.01-0.05 (gpt-4o-mini)

**Monthly estimates (per store):**
- 5 runs/week × 4 weeks = 20 runs/month
- ~$0.20-1.00 per store per month

## Related Documentation

- [AI Scheduling API](../api/ai-scheduling-api.md)
- [OpenAI Integration Pattern](../patterns/openai-integration.md)
- [SDD Quality Requirements](../specs/026-ai-smart-scheduling/solution-design.md)