# Environment Configuration (.env Setup)

## Quick Start

1. Copy the example file:
   ```bash
   cd backend
   cp .env.example .env
   ```

2. Edit `backend/.env` and add your LLM provider credentials (choose ONE option below)

## Option 1: OpenAI (Recommended for Quick Demo)

**Cost**: ~$0.10-1.00 per day of heavy use (gpt-4o is cheaper than GPT-4)

1. Get API key at: https://platform.openai.com/api-keys
2. Edit `backend/.env`:
   ```
   MODEL_PROVIDER=openai
   OPENAI_API_KEY=sk-your-actual-key-here
   OPENAI_MODEL=gpt-4o
   ```
3. Restart backend
4. Done! ✅

## Option 2: Claude / Anthropic

**Cost**: ~$0.05-0.50 per day of heavy use

1. Get API key at: https://console.anthropic.com/
2. Edit `backend/.env`:
   ```
   MODEL_PROVIDER=claude
   ANTHROPIC_API_KEY=sk-ant-your-actual-key-here
   ANTHROPIC_MODEL=claude-haiku-4-5-20251001
   ```
3. Restart backend
4. Done! ✅

## Option 3: Ollama (Free, Local)

**Cost**: Free! No API calls, everything runs locally
**Requirement**: Ollama installed and running

### Setup Ollama

1. Download from: https://ollama.ai
2. Install and run
3. In terminal, pull a model:
   ```bash
   ollama pull qwen2.5:7b-instruct
   ```
4. Verify it's running:
   ```bash
   curl http://localhost:11434/api/tags
   ```
   Should see: `{"models":[{"name":"qwen2.5:7b-instruct"}]}`

5. Edit `backend/.env`:
   ```
   MODEL_PROVIDER=ollama
   OLLAMA_BASE_URL=http://localhost:11434
   OLLAMA_MODEL=qwen2.5:7b-instruct
   OLLAMA_NUM_CTX=8192
   ```
6. Restart backend
7. Done! ✅

## Verify Setup

After updating `.env`, test the configuration:

```bash
# In backend/ directory:
python -m uvicorn app.main:app --reload --port 8000
```

Check logs for:
- ✅ `INFO: Application startup complete` - Backend started
- ❌ `litellm.InternalServerError` - Missing API key or Ollama not running

## Common Issues

### "Missing credentials. Please pass an `api_key`"
- Your API key is not set in `.env`
- Make sure you copied it correctly
- Restart backend after editing `.env`

### "Connection refused" (with Ollama)
- Ollama not running - start it first
- Wrong OLLAMA_BASE_URL in .env (should be `http://localhost:11434`)

### "Model not found" (with Ollama)
- Pull the model first: `ollama pull qwen2.5:7b-instruct`
- Check it's there: `ollama list`

## About Models

### OpenAI Models
- `gpt-4o` - Best quality, cheapest (recommended)
- `gpt-4-turbo` - More powerful, more expensive
- `gpt-3.5-turbo` - Fast, cheaper, slightly lower quality

### Claude Models
- `claude-opus-4-1` - Most capable
- `claude-sonnet-4` - Good balance
- `claude-haiku-4-5-20251001` - Fast, cheap (good for briefing)

### Ollama Models
- `qwen2.5:7b-instruct` - Fast, good for structured output (recommended)
- `neural-chat:7b` - Good general purpose
- `mistral:7b` - Very fast
- `llama2:7b` - Well-tested
- Larger models available: `:13b`, `:70b` (require more RAM)

## Cost Estimates

### OpenAI (gpt-4o)
- Input: $0.000005 per token
- Output: $0.000015 per token
- Morning briefing: ~$0.01-0.05
- Daily usage: ~$0.10-0.30

### Claude (Haiku)
- Input: $0.00008 per token
- Output: $0.00024 per token
- Morning briefing: ~$0.01-0.02
- Daily usage: ~$0.05-0.10

### Ollama
- Free! (costs only electricity to run)
- Uses CPU/GPU on your machine
- No internet API calls

## Optional: LangSmith Tracing (Debugging & Monitoring)

To trace and debug agent orchestration in real-time, set up LangSmith:

1. **Get API Key** (free tier available):
   - Sign up at https://smith.langchain.com/
   - Go to Settings → API Keys
   - Copy your key

2. **Add to `.env`:**
   ```
   LANGSMITH_API_KEY=your_key_here
   LANGSMITH_PROJECT_NAME=personal-chief-of-staff
   LANGSMITH_ENDPOINT=https://api.smith.langchain.com
   ```

3. **View traces:**
   - Open LangSmith dashboard
   - Make a Morning Briefing request
   - Watch traces appear in real-time
   - Inspect agent inputs/outputs and token usage

See [`LANGSMITH_SETUP.md`](LANGSMITH_SETUP.md) for detailed setup and usage.

## Next Steps

1. Choose your LLM provider
2. Get API key (if needed)
3. Edit `backend/.env`
4. (Optional) Add LangSmith for tracing
5. Restart backend
6. Go to Settings page and verify ✅ Model: available
7. Test by generating a Morning Briefing