cleveragents-core/docs/reference/providers.md

# 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. The CLI surface is actor-only—`--provider`/`--model` flags are removed in favor of selecting an actor (or using the configured default actor).

## 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` | ✅ | ✅ | ✅ | ✅ |

Keep this table in sync with provider capability metadata and required environment variables.

## Default selection logic

1. **Actor selection (required)** – `agents tell/build --actor <name>` chooses the provider/model embedded in the actor config. If omitted, the default actor set via `agents actor set-default` is used; in test mode (`CLEVERAGENTS_TESTING_USE_MOCK_AI=true`), the mock actor is auto-provisioned.
2. **Actor configuration** – provider/model come from the actor’s stored config blob; these replace the removed `--provider/--model` overrides on CLI commands.
3. **Settings defaults** – `Settings.default_provider` / `Settings.default_model` still seed built-in actors, but the actor registry remains the source of truth.
4. **Auto fallback** – when a built-in actor is requested and no model is specified, the registry uses its published default; built-ins are created from the fallback order `openai → anthropic → google → azure → openrouter → groq → together → cohere → gemini`.

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

## Actor CLI quick start

- `agents actor add --name local/<id> --config <path> [--unsafe] [--set-default]` stores the canonical actor blob (provider/model/options/graph_descriptor) and requires `--unsafe` when the config is marked unsafe. Example: `agents actor add --name local/dev --config examples/actor.yaml --unsafe --set-default` seeds a default custom actor.
- `agents actor update --name <actor> [--config <path>] [--unsafe|--safe] [--set-default] [--option key=value]` merges overrides into the stored blob; unsafe/safe are mutually exclusive. Example: `agents actor update --name local/dev --option temperature=0.3 --set-default` applies option overrides without touching provider/model metadata.
- `agents actor set-default <name>` sets the default actor used when `--actor` is omitted; defaults cannot be removed.
- `agents actor list` / `agents actor show <name>` display built-in `<provider>/<model>` actors plus custom `local/<id>` entries with unsafe/default/built-in markers and config hashes.
- `agents actor remove local/<id>` removes only custom actors that are not the default; built-ins are immutable. Removing the default actor raises an error until a new default is selected.
- Plan/Chat usage: `agents tell --actor local/dev "add pagination"` or rely on the configured default actor; runtime warns at verbosity ≥ warning when invoking unsafe actors, but does not require `--unsafe` during execution.

## Actor configuration schema (v2-compatible)

Actor config files must remain in the original v2 format (no alternative schemas). Canonical fields:
- `provider` / `model`: required and stored as part of the actor blob; drive registry selection.
- `graph_descriptor`: optional graph metadata emitted by the actor package and injected into LangGraph execution.
- `options`: arbitrary option map merged from package defaults and CLI overrides; stored canonically in the blob.
- `unsafe`: boolean flag; CLI `add/update` requires `--unsafe` when true, and runtime emits a warning (verbosity ≥ warning) when invoking unsafe actors.

Configs are stored in the config DB as canonical JSON/YAML blobs with a content hash; built-ins are immutable `<provider>/<model>` entries and customs must use `local/<id>` naming.

## 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; then select an actor that references it.
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** – select an actor whose config points at a supported model ID for the chosen provider (update the actor config if needed).
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.