> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# LLM Provider Configuration

> Configure LLM providers (OpenRouter, OpenAI, Anthropic, Google) for Aurora's AI agents

Aurora supports multiple LLM providers for its AI agents. At least one provider API key is required.

## Supported Providers

* **OpenRouter** (recommended) - Access multiple models through a single API
* **OpenAI** - GPT models (GPT-4o, GPT-5.2, etc.)
* **Anthropic** - Claude models (Claude 3.5 Sonnet, etc.)
* **Google AI** - Gemini models (Gemini Pro, Ultra, etc.)

## Quick Start

```bash theme={null}
# Get an OpenRouter API key (recommended)
# Visit: https://openrouter.ai/keys

# Add to .env
OPENROUTER_API_KEY=sk-or-v1-...
LLM_PROVIDER_MODE=openrouter

# Restart Aurora
make down
make prod-prebuilt
```

## Configuration

### Environment Variables

<ParamField path="LLM_PROVIDER_MODE" type="string" default="openrouter">
  Default LLM provider to use.

  Options: `openrouter`, `openai`, `anthropic`, `google`
</ParamField>

<ParamField path="AGENT_RECURSION_LIMIT" type="number" default="240">
  Maximum recursion depth for agent workflows. Prevents infinite loops.
</ParamField>

## OpenRouter (Recommended)

OpenRouter provides access to multiple LLM models through a unified API.

### Setup

1. Get an API key: [https://openrouter.ai/keys](https://openrouter.ai/keys)
2. Add to `.env`:
   ```bash theme={null}
   OPENROUTER_API_KEY=sk-or-v1-...
   LLM_PROVIDER_MODE=openrouter
   ```

### Benefits

* **Single API** for multiple models (GPT, Claude, Gemini, etc.)
* **Automatic routing** to cheapest/fastest provider
* **Fallback support** if a model is unavailable
* **Usage tracking** and billing

### Supported Models

OpenRouter supports 100+ models including:

* **OpenAI**: GPT-4o, GPT-5.2, GPT-3.5
* **Anthropic**: Claude 3.5 Sonnet, Claude 3 Opus
* **Google**: Gemini Pro, Gemini Ultra
* **Meta**: Llama 3, Llama 2
* **Mistral**: Mixtral, Mistral Large
* **Many more**: Cohere, AI21, etc.

See full list: [https://openrouter.ai/models](https://openrouter.ai/models)

### Usage

```python theme={null}
from chat.backend.agent.providers import get_registry

registry = get_registry()
provider = registry.get_provider("openrouter")

# Use any OpenRouter-supported model
chat_model = provider.get_chat_model("openai/gpt-5.2")
response = chat_model.invoke("Hello, world!")
```

### Cost Optimization

OpenRouter automatically routes to the cheapest available model:

```python theme={null}
# Use cost-optimized routing
chat_model = provider.get_chat_model("openai/gpt-5.2:auto")
```

## OpenAI

Direct integration with OpenAI's API.

### Setup

1. Get an API key: [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
2. Add to `.env`:
   ```bash theme={null}
   OPENAI_API_KEY=sk-...
   LLM_PROVIDER_MODE=openai
   ```

### Supported Models

* **GPT-4o**: Latest GPT-4 optimization
* **GPT-5.2**: Next-generation model (when available)
* **GPT-3.5**: Faster, cheaper model

### Usage

```python theme={null}
from chat.backend.agent.providers import get_registry

registry = get_registry()
provider = registry.get_provider("openai")

chat_model = provider.get_chat_model("gpt-5.2")
response = chat_model.invoke("Explain quantum computing")
```

### Configuration

```bash theme={null}
# .env
OPENAI_API_KEY=sk-...
LLM_PROVIDER_MODE=openai

# Optional: Use OpenAI organization
OPENAI_ORGANIZATION=org-...
```

## Anthropic

Integration with Anthropic's Claude models.

### Setup

1. Get an API key: [https://console.anthropic.com/](https://console.anthropic.com/)
2. Add to `.env`:
   ```bash theme={null}
   ANTHROPIC_API_KEY=sk-ant-...
   LLM_PROVIDER_MODE=anthropic
   ```

### Supported Models

* **Claude 3.5 Sonnet**: Best balance of performance and speed
* **Claude 3 Opus**: Most capable model
* **Claude 3 Haiku**: Fastest, most affordable

### Usage

```python theme={null}
from chat.backend.agent.providers import get_registry

registry = get_registry()
provider = registry.get_provider("anthropic")

chat_model = provider.get_chat_model("claude-3-5-sonnet-20240620")
response = chat_model.invoke("Write a Python function to sort a list")
```

### Configuration

```bash theme={null}
# .env
ANTHROPIC_API_KEY=sk-ant-...
LLM_PROVIDER_MODE=anthropic
```

## Google AI (Gemini)

Integration with Google's Gemini models.

### Setup

1. Get an API key: [https://aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)
2. Add to `.env`:
   ```bash theme={null}
   GOOGLE_AI_API_KEY=AIza...
   LLM_PROVIDER_MODE=google
   ```

### Supported Models

* **Gemini Pro**: Balanced performance
* **Gemini Ultra**: Most capable (when available)
* **Gemini Nano**: On-device model

### Usage

```python theme={null}
from chat.backend.agent.providers import get_registry

registry = get_registry()
provider = registry.get_provider("google")

chat_model = provider.get_chat_model("gemini-pro")
response = chat_model.invoke("What is machine learning?")
```

### Configuration

```bash theme={null}
# .env
GOOGLE_AI_API_KEY=AIza...
LLM_PROVIDER_MODE=google

# Optional: Disable thinking mode
GEMINI_DISABLE_THINKING=true
```

## Multi-Provider Setup

You can configure multiple providers and switch between them:

```bash theme={null}
# .env
OPENROUTER_API_KEY=sk-or-v1-...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=AIza...

# Default provider
LLM_PROVIDER_MODE=openrouter
```

Switch providers at runtime:

```python theme={null}
from chat.backend.agent.providers import get_registry

registry = get_registry()

# Use OpenRouter
openrouter = registry.get_provider("openrouter")
model1 = openrouter.get_chat_model("openai/gpt-5.2")

# Use OpenAI directly
openai = registry.get_provider("openai")
model2 = openai.get_chat_model("gpt-5.2")

# Use Anthropic
anthropic = registry.get_provider("anthropic")
model3 = anthropic.get_chat_model("claude-3-5-sonnet-20240620")
```

## API Endpoints

### Check Available Providers

```bash theme={null}
curl http://localhost:5080/api/llm-config/available-providers
```

Response:

```json theme={null}
{
  "success": true,
  "provider_mode": "openrouter",
  "providers": {
    "openrouter": {"available": true, "configured": true},
    "openai": {"available": true, "configured": true},
    "anthropic": {"available": false, "configured": false},
    "google": {"available": false, "configured": false}
  }
}
```

### Get Provider Details

```bash theme={null}
curl http://localhost:5080/api/llm-config/provider-details
```

Response:

```json theme={null}
{
  "success": true,
  "providers": [
    {
      "name": "openrouter",
      "available": true,
      "supported_models": [
        "openai/gpt-5.2",
        "openai/gpt-4o",
        "anthropic/claude-3-5-sonnet",
        "..."
      ],
      "total_models": 120
    }
  ]
}
```

### Test Provider

```bash theme={null}
curl -X POST http://localhost:5080/api/llm-config/test-provider \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "model": "gpt-5.2"}'
```

Response:

```json theme={null}
{
  "success": true,
  "provider": "openai",
  "available": true,
  "message": "Provider 'openai' is configured and ready to use"
}
```

### Get Supported Models

```bash theme={null}
# All models
curl http://localhost:5080/api/llm-config/supported-models

# Filter by provider
curl "http://localhost:5080/api/llm-config/supported-models?provider=openai"
```

## Model Mapping

Aurora automatically maps model names across providers:

```python theme={null}
from chat.backend.agent.model_mapper import ModelMapper

# Detect provider from model name
provider = ModelMapper.detect_provider("gpt-5.2")
print(provider)  # "openai"

# Get native name for a provider
native_name = ModelMapper.get_native_name("gpt-5.2", "openrouter")
print(native_name)  # "openai/gpt-5.2"

# Get supported models for a provider
models = ModelMapper.get_supported_models_for_provider("anthropic")
print(models)  # ["claude-3-5-sonnet-20240620", "claude-3-opus-20240229", ...]
```

## Cost Optimization

### RCA Cost Optimization

<ParamField path="RCA_OPTIMIZE_COSTS" type="boolean" default="false">
  Enable cost optimization for root cause analysis.

  When enabled, Aurora uses cheaper models for preliminary analysis and more capable models only when needed.
</ParamField>

```bash theme={null}
# .env
RCA_OPTIMIZE_COSTS=true
```

### Model Selection Strategy

1. **Fast tasks**: Use GPT-3.5 or Claude Haiku
2. **Standard tasks**: Use GPT-4o or Claude Sonnet
3. **Complex reasoning**: Use GPT-5.2 or Claude Opus

```python theme={null}
# Example: Tiered model usage
def get_model_for_task(complexity: str):
    if complexity == "simple":
        return "openai/gpt-3.5-turbo"  # Cheap, fast
    elif complexity == "standard":
        return "openai/gpt-4o"  # Balanced
    else:
        return "openai/gpt-5.2"  # Most capable
```

## Troubleshooting

### Provider Not Available

```bash theme={null}
# Check which providers are configured
curl http://localhost:5080/api/llm-config/available-providers

# Verify API key is set
docker exec aurora-server-1 printenv | grep API_KEY

# Test provider
curl -X POST http://localhost:5080/api/llm-config/test-provider \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai"}'
```

### API Key Invalid

```bash theme={null}
# Check API key format
echo $OPENROUTER_API_KEY  # Should start with sk-or-v1-
echo $OPENAI_API_KEY      # Should start with sk-
echo $ANTHROPIC_API_KEY   # Should start with sk-ant-
echo $GOOGLE_AI_API_KEY   # Should start with AIza

# Test key directly
curl https://openrouter.ai/api/v1/auth/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"
```

### Rate Limits

If you hit rate limits:

1. **Use multiple providers** as fallbacks
2. **Implement retry logic** with exponential backoff
3. **Upgrade API plan** for higher limits
4. **Use OpenRouter** for automatic rate limit handling

### Model Not Found

```bash theme={null}
# Check model name is correct
curl "http://localhost:5080/api/llm-config/model-info?model=gpt-5.2"

# List supported models
curl "http://localhost:5080/api/llm-config/supported-models?provider=openai"
```

## Best Practices

1. **Use OpenRouter** for simplicity and reliability
2. **Configure multiple providers** as fallbacks
3. **Test provider connectivity** before deploying
4. **Monitor usage and costs** regularly
5. **Rotate API keys** periodically
6. **Use environment variables** (never commit keys)
7. **Enable RCA cost optimization** in production
8. **Set appropriate recursion limits** to prevent runaway costs

## Security

<Warning>
  Never commit API keys to version control. Always use environment variables and `.env` files.
</Warning>

```bash theme={null}
# Good: .env file (gitignored)
OPENROUTER_API_KEY=sk-or-v1-...

# Bad: Hardcoded in code
api_key = "sk-or-v1-..."  # NEVER DO THIS
```

### Key Rotation

```bash theme={null}
# 1. Generate new API key from provider
# 2. Update .env
OPENROUTER_API_KEY=sk-or-v1-NEW_KEY

# 3. Restart Aurora
make down
make prod-prebuilt

# 4. Verify new key works
curl -X POST http://localhost:5080/api/llm-config/test-provider \
  -d '{"provider": "openrouter"}'

# 5. Revoke old key from provider dashboard
```

### Access Control

* **Restrict API keys** to specific IP addresses (if supported)
* **Use separate keys** for development and production
* **Monitor usage** for unusual activity
* **Set spending limits** on provider dashboards