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:

# 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:

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

Or install from requirements.txt:

pip install -r requirements.txt

Usage

Automatic Provider Selection

The system automatically selects the appropriate provider for each agent:

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:

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:

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:

# 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:

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:

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

# 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