feat(providers): implement OpenRouter provider support in ProviderRegistry

Added handling for ProviderType.OPENROUTER in _create_provider_llm in src/cleveragents/providers/registry.py to resolve ValueError: Unsupported provider type when using OpenRouter via create_llm. Created features/openrouter_provider_registry.feature with 11 scenarios validating OpenRouter provider behavior in ProviderRegistry. Created features/steps/openrouter_provider_registry_steps.py with step definitions for the new feature file. Created docs/reference/providers.md with comprehensive documentation including the OpenRouter configuration guide. ISSUES CLOSED: #8907
2026-04-19 02:44:16 +00:00
parent ba38a78cb1
commit 8be7f59931
4 changed files with 611 additions and 0 deletions
@@ -0,0 +1,120 @@
+# Provider Configuration Reference
+
+CleverAgents supports multiple AI provider backends through the `ProviderRegistry`.
+Each provider is configured via environment variables or the `agents config set` command.
+
+## Supported Providers
+
+| Provider | `ProviderType` | API Key Environment Variable |
+|----------|---------------|------------------------------|
+| OpenAI | `openai` | `OPENAI_API_KEY` |
+| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
+| Google / Gemini | `google` / `gemini` | `GOOGLE_API_KEY` / `GEMINI_API_KEY` |
+| Azure OpenAI | `azure` | `AZURE_OPENAI_API_KEY` |
+| **OpenRouter** | **`openrouter`** | **`OPENROUTER_API_KEY`** |
+| Groq | `groq` | `GROQ_API_KEY` |
+| Together AI | `together` | `TOGETHER_API_KEY` |
+| Cohere | `cohere` | `COHERE_API_KEY` |
+
+---
+
+## OpenRouter
+
+[OpenRouter](https://openrouter.ai) provides a unified API gateway to hundreds of
+models from different providers (Anthropic, OpenAI, Google, Meta, Mistral, and more).
+This makes it ideal for cost optimisation and model diversity without managing
+multiple API keys.
+
+### Configuration
+
+Set the following environment variables:
+
+```bash
+# Required
+export OPENROUTER_API_KEY="sk-or-v1-..."
+
+# Optional: default model (defaults to anthropic/claude-sonnet-4-20250514)
+export CLEVERAGENTS_DEFAULT_MODEL="openai/gpt-4o"
+
+# Optional: set OpenRouter as the default provider
+export CLEVERAGENTS_DEFAULT_PROVIDER="openrouter"
+
+# Optional: organisation identifier sent in HTTP headers
+export OPENROUTER_ORGANIZATION="myapp.example.com"
+```
+
+Or use the CLI:
+
+```bash
+agents config set provider.openrouter.api_key "sk-or-v1-..."
+agents config set provider.openrouter.model "anthropic/claude-3-haiku"
+```
+
+### Config Keys
+
+| Config Key | Environment Variable | Description |
+|------------|---------------------|-------------|
+| `provider.openrouter.api_key` | `OPENROUTER_API_KEY` | OpenRouter API key (required) |
+| `provider.openrouter.model` | `CLEVERAGENTS_DEFAULT_MODEL` | Default model slug (optional) |
+| `provider.openrouter.organization` | `OPENROUTER_ORGANIZATION` | Organisation name sent in `HTTP-Referer` / `X-Title` headers (optional) |
+
+### Capabilities
+
+| Feature | Supported |
+|---------|-----------|
+| Streaming | ✅ Yes |
+| Tool calls | ✅ Yes |
+| Vision / image input | ✅ Yes (model-dependent) |
+| JSON mode | ✅ Yes (model-dependent) |
+| Max context length | 128 000 tokens (varies by model) |
+
+### Selecting a Model
+
+OpenRouter model slugs follow the format `<provider>/<model-name>`. Examples:
+
+```bash
+# Anthropic via OpenRouter
+agents config set provider.openrouter.model "anthropic/claude-sonnet-4-20250514"
+
+# OpenAI via OpenRouter
+agents config set provider.openrouter.model "openai/gpt-4o"
+
+# Meta Llama via OpenRouter
+agents config set provider.openrouter.model "meta-llama/llama-3.1-70b-instruct"
+```
+
+Browse the full model catalogue at <https://openrouter.ai/models>.
+
+### Fallback Priority
+
+When no explicit provider is configured, CleverAgents selects the first available
+provider in the following fallback order:
+
+1. OpenAI
+2. Anthropic
+3. Google
+4. Azure
+5. **OpenRouter** ← position 5
+6. Groq
+7. Together AI
+8. Cohere
+
+### Example Usage
+
+```python
+from cleveragents.providers.registry import ProviderRegistry, ProviderType
+
+registry = ProviderRegistry()
+
+# Create a LangChain LLM directly
+llm = registry.create_llm(
+    provider_type=ProviderType.OPENROUTER,
+    model_id="anthropic/claude-3-haiku",
+)
+
+# Or create a full AIProviderInterface adapter
+provider = registry.create_ai_provider(
+    provider_type="openrouter",
+    model_id="openai/gpt-4o",
+)
+```