# OpenRouter Provider Usage Guide

Complete guide for using OpenRouter with Kollabor CLI.

## Overview

OpenRouter is an API gateway providing unified access to 100+ LLM models from various providers (OpenAI, Anthropic, Google, Meta, Mistral, and more) through a single OpenAI-compatible API.

Features:
- Unified API for multiple providers
- Automatic model routing and fallback
- Cost tracking and analytics
- Model comparison and leaderboards
- Site tracking for rankings

## Getting Started

### 1. Get Your API Key

Sign up at [openrouter.ai](https://openrouter.ai) and create an API key:

1. Create free account at https://openrouter.ai
2. Navigate to Settings -> API Keys
3. Click "Create API Key"
4. Copy and save your key (you won't see it again)

### 2. Configure Your Profile

Add OpenRouter profile to `~/.kollabor-cli/config.json`:

```json
{
  "profiles": {
    "openrouter": {
      "provider": "openrouter",
      "api_key": "sk-or-v1-YOUR-KEY-HERE",
      "model": "openai/gpt-4",
      "base_url": "https://openrouter.ai/api/v1",
      "http_referer": "https://myapp.com",
      "x_title": "MyApp",
      "temperature": 0.7,
      "max_tokens": 4096
    }
  },
  "current_profile": "openrouter"
}
```

### 3. Start Using OpenRouter

```bash
# Use kollab command
kollab

# Or with pipe mode
kollab "Explain quantum computing"
```

## Configuration Options

### Required Fields

- **provider**: Must be `"openrouter"`
- **api_key**: Your OpenRouter API key
- **model**: Model identifier (see Available Models below)

### Optional Fields

- **base_url**: API endpoint (default: `https://openrouter.ai/api/v1`)
- **http_referer**: Your site URL for OpenRouter rankings (recommended)
- **x_title**: Your site name for rankings (recommended)
- **temperature**: Sampling temperature 0.0-2.0 (default: 0.7)
- **max_tokens**: Maximum tokens to generate (default: 4096)
- **timeout**: Request timeout in seconds (default: 60.0)
- **top_p**: Nucleus sampling (0.0-1.0)

### Site Tracking Headers

OpenRouter uses HTTP-Referer and X-Title headers to:
- Track which applications use which models
- Display rankings on openrouter.ai
- Help other developers discover useful models

It's recommended but optional to include these:

```json
{
  "http_referer": "https://myapp.com",
  "x_title": "MyApp"
}
```

## Available Models

OpenRouter provides access to 100+ models. Popular choices:

### OpenAI Models
```
openai/gpt-4-turbo
openai/gpt-4
openai/gpt-3.5-turbo
openai/o1-preview
openai/o1-mini
```

### Anthropic Models
```
anthropic/claude-3.5-sonnet
anthropic/claude-3-opus
anthropic/claude-3-sonnet
anthropic/claude-3-haiku
```

### Google Models
```
google/gemini-pro-1.5
google/gemini-pro
google/palm-2-chat-bison
```

### Meta Models
```
meta-llama/llama-3.1-405b-instruct
meta-llama/llama-3.1-70b-instruct
meta-llama/llama-3-70b-instruct
```

### Other Popular Models
```
mistralai/mistral-large
cohere/command-r-plus
perplexity/llama-3.1-sonar-large-128k-online
```

See full list at: https://openrouter.ai/models

## Advanced Features

### Model Routing

OpenRouter supports automatic fallback to alternate models:

```json
{
  "model": "openai/gpt-4",
  "models": ["openai/gpt-4", "anthropic/claude-3-opus"],
  "route": "fallback"
}
```

This tries GPT-4 first, falls back to Claude if unavailable.

### Provider Preferences

Specify which provider to use for a model:

```json
{
  "model": "openai/gpt-4",
  "provider": {
    "order": ["Together", "OpenAI"],
    "require_parameters": true
  }
}
```

### Cost Tracking

OpenRouter provides detailed cost analytics:
- Per-model usage tracking
- Cost per request
- Token usage statistics

Access via OpenRouter dashboard at https://openrouter.ai/activity

## Programmatic Usage

### Python Example

```python
from kollabor.llm.providers import OpenRouterConfig, ProviderRegistry, ProviderType

# Create configuration
config = OpenRouterConfig(
    provider=ProviderType.OPENROUTER,
    api_key="sk-or-v1-YOUR-KEY-HERE",
    model="openai/gpt-4",
    http_referer="https://myapp.com",
    x_title="MyApp"
)

# Get provider instance
provider = await ProviderRegistry.get_provider(config)

# Make API call
messages = [{"role": "user", "content": "Hello!"}]
response = await provider.call(messages)

print(response.get_text_content())
print(f"Tokens: {response.usage.total_tokens}")
```

### Streaming Example

```python
# Stream response
async for chunk in provider.stream(messages):
    if hasattr(chunk.delta, 'content'):
        print(chunk.delta.content, end='', flush=True)
    elif chunk.is_final:
        print(f"\n\nTotal tokens: {chunk.usage.total_tokens}")
```

### Tool Calling Example

```python
# Define tools
tools = [
    {
        "name": "get_weather",
        "description": "Get weather for location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {"type": "string"}
            },
            "required": ["location"]
        }
    }
]

# Call with tools
response = await provider.call(messages, tools=tools)

# Check for tool use
tool_uses = response.get_tool_uses()
if tool_uses:
    for tool in tool_uses:
        print(f"Tool: {tool.name}")
        print(f"Args: {tool.input}")
```

## Switching Between Profiles

### Using /profile Command

```bash
# List available profiles
/profile list

# Switch to OpenRouter
/profile set openrouter

# Create new profile interactively
/profile create
```

### Multiple OpenRouter Profiles

You can have multiple OpenRouter profiles with different models:

```json
{
  "profiles": {
    "openrouter-gpt4": {
      "provider": "openrouter",
      "model": "openai/gpt-4",
      "api_key": "sk-or-v1-..."
    },
    "openrouter-claude": {
      "provider": "openrouter",
      "model": "anthropic/claude-3-opus",
      "api_key": "sk-or-v1-..."
    },
    "openrouter-llama": {
      "provider": "openrouter",
      "model": "meta-llama/llama-3.1-405b-instruct",
      "api_key": "sk-or-v1-..."
    }
  }
}
```

## Troubleshooting

### Authentication Errors

```
Error: Authentication failed
```

**Solution**: Verify your API key is correct. Get a new one from https://openrouter.ai/settings/keys

### Model Not Found

```
Error: Model not found: invalid-model
```

**Solution**: Check available models at https://openrouter.ai/models. Use exact model identifier.

### Rate Limiting

```
Error: Rate limit exceeded
```

**Solution**: OpenRouter has rate limits. Wait and retry, or add credits to your account.

### HTTPS Required

```
Error: Base URL must use HTTPS
```

**Solution**: Ensure base_url uses `https://` (or localhost for testing).

## Best Practices

1. **Use Site Tracking**: Include http_referer and x_title for better analytics
2. **Choose Appropriate Models**: Select models based on task complexity and cost
3. **Enable Fallback**: Use model routing for higher reliability
4. **Monitor Costs**: Track usage via OpenRouter dashboard
5. **Handle Errors**: Implement retry logic for rate limits
6. **Secure Keys**: Never commit API keys to version control
7. **Test Locally**: Use localhost base_url for development/testing

## Resources

- OpenRouter Website: https://openrouter.ai
- API Documentation: https://openrouter.ai/docs
- Model List: https://openrouter.ai/models
- Pricing: https://openrouter.ai/docs/limits
- Discord Community: https://discord.gg/openrouter

## Examples

### Quick Start Examples

```bash
# Use GPT-4 via OpenRouter
kollab "Explain recursion"

# Stream response
echo "Write a haiku about coding" | kollab -p

# With timeout
kollab --timeout 2min "Summarize quantum computing"
```

### Configuration Examples

**Minimal Configuration:**
```json
{
  "provider": "openrouter",
  "api_key": "sk-or-v1-...",
  "model": "openai/gpt-4"
}
```

**Full Configuration:**
```json
{
  "provider": "openrouter",
  "api_key": "sk-or-v1-...",
  "model": "openai/gpt-4",
  "base_url": "https://openrouter.ai/api/v1",
  "http_referer": "https://myapp.com",
  "x_title": "MyApp",
  "temperature": 0.7,
  "max_tokens": 4096,
  "top_p": 0.9,
  "timeout": 120.0
}
```

**With Fallback:**
```json
{
  "provider": "openrouter",
  "api_key": "sk-or-v1-...",
  "model": "openai/gpt-4",
  "models": ["openai/gpt-4", "anthropic/claude-3-opus", "meta-llama/llama-3.1-405b"],
  "route": "fallback"
}
```

## FAQ

**Q: Can I use my own OpenAI/Anthropic API key with OpenRouter?**
A: Yes! OpenRouter supports BYOK (Bring Your Own Key) for certain providers. See https://openrouter.ai/docs/guides/overview/auth/byok

**Q: Does OpenRouter support streaming?**
A: Yes, streaming is fully supported via Server-Sent Events (SSE).

**Q: Can I use tools/function calling with OpenRouter?**
A: Yes, tool calling is supported for models that support it (OpenAI, Anthropic, etc.).

**Q: How does pricing work?**
A: OpenRouter charges based on model usage. Prices vary by model. See https://openrouter.ai/models for details.

**Q: Is there a free tier?**
A: OpenRouter offers $1 in free credits to new users. After that, you pay as you go.

**Q: Can I use OpenRouter in production?**
A: Yes, OpenRouter is production-ready with high reliability and automatic failover.

**Q: How do I contribute to site rankings?**
A: Include `http_referer` and `x_title` headers in your configuration. OpenRouter will track your usage.

---

**Sources:**
- [OpenRouter API Reference](https://openrouter.ai/docs/api/reference/overview)
- [OpenRouter Quickstart](https://openrouter.ai/docs/quickstart)
- [OpenRouter Authentication](https://openrouter.ai/docs/api/reference/authentication)
- [OpenRouter Models](https://openrouter.ai/docs/api/api-reference/models/get-models)
