# Provider Registry and Defaults

CleverAgents routes every LangGraph workflow through the provider registry defined in `src/cleveragents/providers/registry.py`. The registry inspects configured API keys, publishes capability metadata, and picks a sensible default provider/model whenever the CLI does not specify one.

## Supported providers

| Provider | Required variables | Default model | Streaming | Tool Calls | Vision | JSON mode |
| --- | --- | --- | --- | --- | --- | --- |
| OpenAI | `OPENAI_API_KEY` | `gpt-4o` | ✅ | ✅ | ✅ | ✅ |
| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` | ✅ | ✅ | ✅ | ❌ |
| Google AI Studio | `GOOGLE_API_KEY` *or* `GOOGLE_GENAI_API_KEY` | `gemini-2.0-flash` | ✅ | ✅ | ✅ | ✅ |
| Azure OpenAI | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT` | `gpt-4o` | ✅ | ✅ | ✅ | ✅ |
| OpenRouter | `OPENROUTER_API_KEY` (+ optional `CLEVERAGENTS_OPENROUTER_ORGANIZATION`) | `anthropic/claude-sonnet-4-20250514` | ✅ | ✅ | ✅ | ✅ |
| Groq | `GROQ_API_KEY` | `llama-3.1-70b-versatile` | ✅ | ✅ | ❌ | ✅ |
| Together | `TOGETHER_API_KEY` | `meta-llama/Llama-3.1-70B-Instruct-Turbo` | ✅ | ✅ | ❌ | ❌ |
| Cohere | `COHERE_API_KEY` | `command-r-plus` | ✅ | ✅ | ❌ | ❌ |
| Gemini (standalone) | `GEMINI_API_KEY` *or* `GOOGLE_GEMINI_API_KEY` | `gemini-2.0-flash` | ✅ | ✅ | ✅ | ✅ |

See `docs/reference/env_variables.yaml` for the full catalog (including AWS/Vertex-compatible aliases) and machine-readable capability metadata.

## Default selection logic

1. **CLI flags** – `agents tell --provider openai --model gpt-4o` and `agents build` accept per-command overrides. These always win.
2. **Environment overrides** – export `CLEVERAGENTS_DEFAULT_PROVIDER` and/or `CLEVERAGENTS_DEFAULT_MODEL` to set global defaults.
3. **Settings object** – `Settings.default_provider` / `Settings.default_model` (for example via Hatch profile) are next in line.
4. **Auto fallback** – when nothing is pinned, the registry chooses the first configured provider in this order: `openai → anthropic → google → azure → openrouter → groq → together → cohere → gemini`. The provider’s published default model is used automatically.

The `agents diagnostics` command prints whether credentials were discovered along with the selected provider/model. Behave scenarios in `features/provider_registry_coverage.feature` cover every branch of this flow.

## OpenRouter header semantics

If `CLEVERAGENTS_OPENROUTER_ORGANIZATION` is set, the OpenRouter adapter mirrors that value into the `HTTP-Referer` and `X-Title` headers (see `src/cleveragents/providers/llm/openrouter_provider.py`). This keeps OpenRouter quotas segmented per organization without hard-coding branding elsewhere. Headers are sanitized (converted to strings, trimmed, and only added when non-empty).

## Testing and safety levers

- Set `CLEVERAGENTS_TESTING_USE_MOCK_AI=true` (or `1/yes`) to force the in-repository mock provider. The DI container injects it automatically, guaranteeing that local and CI test runs avoid accidental API calls.
- Use `agents diagnostics` after changing credentials to confirm that the registry sees your keys.
- Provider diagnostics surfaced by `PlanService` include environment hints when required keys are missing; the Behave coverage under `features/plan_service.feature` exercises these messages.

## Troubleshooting checklist

1. **"No AI provider configured"** – export at least one API key above or enable the mock provider when testing.
2. **Azure errors** – confirm `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT`, and `AZURE_OPENAI_API_VERSION` (or their `CLEVERAGENTS_` aliases) are set together. Validation will fail if any field is missing.
3. **Model mismatch** – specify `--model` on the CLI or set `CLEVERAGENTS_DEFAULT_MODEL` to point at a supported ID for your provider.
4. **OpenRouter metadata issues** – ensure any custom headers are passed via `CLEVERAGENTS_OPENROUTER_ORGANIZATION`; manual headers are sanitized before invoking LangChain’s `ChatOpenAI` shim.
5. **Coverage gaps** – run `nox -s unit_tests -- features/provider_registry_coverage.feature` to revalidate every scenario after updating credentials or defaults.