AI_PROVIDERS_GUIDE.md

# AI Providers Configuration Guide

This guide explains how to configure and use multiple AI providers (Google Gemini and Anthropic Claude) in the Lifestyle Journey application.

## Overview

The application now supports multiple AI providers with intelligent agent-specific assignments:

- **MainLifestyleAssistant** → Anthropic Claude (advanced reasoning for complex coaching)
- **All other agents** → Google Gemini (optimized for speed and consistency)

## Configuration

### Environment Variables

Set up your API keys in the `.env` file:

```bash
# Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key_here

# Anthropic Claude API Key  
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Optional: Enable detailed logging
LOG_PROMPTS=true
```

### Agent Assignments

Current agent-to-provider mapping:

| Agent | Provider | Model | Temperature | Reasoning |
|-------|----------|-------|-------------|-----------|
| MainLifestyleAssistant | Anthropic | claude-sonnet-4-20250514 | 0.3 | Complex lifestyle coaching requires advanced reasoning |
| EntryClassifier | Gemini | gemini-2.5-flash | 0.1 | Fast classification, optimized for speed |
| TriageExitClassifier | Gemini | gemini-2.5-flash | 0.2 | Medical triage decisions require consistency |
| MedicalAssistant | Gemini | gemini-2.5-pro | 0.2 | Medical guidance requires reliable responses |
| SoftMedicalTriage | Gemini | gemini-2.5-flash | 0.3 | Gentle triage can use faster model |
| LifestyleProfileUpdater | Gemini | gemini-2.5-pro | 0.2 | Profile analysis requires detailed processing |

## Installation

Install required dependencies:

```bash
pip install anthropic>=0.40.0 google-genai>=0.5.0
```

Or install from requirements.txt:

```bash
pip install -r requirements.txt
```

## Usage

### Automatic Provider Selection

The system automatically selects the appropriate provider for each agent:

```python
from core_classes import AIClientManager

# Create the AI client manager
api = AIClientManager()

# Each agent automatically uses its configured provider
entry_classifier = EntryClassifier(api)  # Uses Gemini
main_lifestyle = MainLifestyleAssistant(api)  # Uses Anthropic
```

### Manual Client Creation

For direct client usage:

```python
from ai_client import create_ai_client

# Create client for specific agent
client = create_ai_client("MainLifestyleAssistant")

# Generate response
response = client.generate_response(
    system_prompt="You are a lifestyle coach",
    user_prompt="Help me start exercising",
    call_type="LIFESTYLE_COACHING"
)
```

## Fallback System

The system includes automatic fallback:

1. **Primary Provider Unavailable**: Falls back to any available provider
2. **API Call Failure**: Tries fallback provider if available
3. **No Providers Available**: Returns error message

## Configuration Validation

Check your configuration:

```python
from ai_providers_config import validate_configuration, check_environment_setup

# Check environment setup
env_status = check_environment_setup()
print(env_status)

# Validate full configuration
validation = validate_configuration()
if validation["valid"]:
    print("✅ Configuration is valid")
else:
    print("❌ Errors:", validation["errors"])
```

## Testing

Run the test suite to verify everything works:

```bash
# Test configuration
python3 ai_providers_config.py

# Test client creation and functionality
python3 test_ai_providers.py
```

## Customization

### Adding New Providers

1. Add provider to `AIProvider` enum in `ai_providers_config.py`
2. Add models to `AIModel` enum
3. Create client class in `ai_client.py`
4. Update `PROVIDER_CONFIGS` and `AGENT_CONFIGURATIONS`

### Changing Agent Assignments

Modify `AGENT_CONFIGURATIONS` in `ai_providers_config.py`:

```python
AGENT_CONFIGURATIONS = {
    "YourAgent": {
        "provider": AIProvider.ANTHROPIC,  # or AIProvider.GEMINI
        "model": AIModel.CLAUDE_SONNET_4,  # or any available model
        "temperature": 0.3,
        "reasoning": "Why this configuration makes sense"
    }
}
```

## Monitoring and Logging

Enable detailed logging to monitor AI interactions:

```bash
export LOG_PROMPTS=true
```

Logs are written to:
- Console output
- `ai_interactions.log` file

## Troubleshooting

### Common Issues

1. **"No AI providers available"**
   - Check API keys are set correctly
   - Verify internet connection
   - Ensure required packages are installed

2. **"API Error" messages**
   - Check API key validity
   - Verify account has sufficient credits
   - Check rate limits

3. **Fallback being used unexpectedly**
   - Primary provider may be unavailable
   - Check logs for specific error messages

### Debug Commands

```python
# Check which providers are available
from ai_providers_config import get_available_providers
print(get_available_providers())

# Get client info for specific agent
from ai_client import create_ai_client
client = create_ai_client("MainLifestyleAssistant")
print(client.get_client_info())
```

## Performance Considerations

- **Gemini**: Faster responses, good for classification and simple tasks
- **Anthropic**: More sophisticated reasoning, better for complex coaching scenarios
- **Fallback**: May impact response quality if primary provider unavailable

## Security

- Store API keys securely in environment variables
- Never commit API keys to version control
- Use different keys for development/production environments
- Monitor API usage and costs

## Migration from Old System

The new system is backward compatible:

- Existing `GeminiAPI` references work unchanged
- All existing functionality preserved
- Gradual migration possible by updating individual components

## Support

For issues or questions:

1. Check this guide and configuration files
2. Run test scripts to identify problems
3. Review logs for detailed error information
4. Verify API keys and provider availability