cleveragents-core/docs/api/providers.md

cleveragents.providers — AI Provider Registry

The providers package implements the LangChain/LangGraph-powered provider registry that discovers configured AI providers from environment variables, reports capability metadata, and selects defaults.

---

ProviderRegistry

from cleveragents.providers.registry import ProviderRegistry, get_provider_registry

# Use the global singleton (recommended)
registry = get_provider_registry()

# Or create a scoped instance with custom settings
registry = ProviderRegistry(settings=my_settings)

The registry auto-discovers configured providers on construction by inspecting API key environment variables.

Key Methods

Method	Returns	Description
get_configured_providers()	list[ProviderInfo]	Providers with valid credentials
get_all_providers()	list[ProviderInfo]	All known providers (configured or not)
get_provider_info(provider_type)	ProviderInfo | None	Info for a specific provider
is_provider_configured(provider_type)	bool	Whether a provider has valid credentials
get_default_provider_type()	ProviderType | None	Default provider per config/env
get_default_model(provider_type)	str | None	Default model for a provider
create_llm(provider_type, model_id, **kwargs)	BaseLanguageModel	Create a LangChain LLM
create_ai_provider(provider_type, model_id, max_retries)	AIProviderInterface	Create an AI provider

Provider Selection Order

get_default_provider_type() resolves the active provider using this precedence:

1. CLEVERAGENTS_DEFAULT_PROVIDER environment variable
2. settings.default_provider value
3. First configured provider in the fallback order: openai → anthropic → google → azure → openrouter → groq → together → cohere

---

ProviderType

from cleveragents.providers.registry import ProviderType

ProviderType.OPENAI      # "openai"
ProviderType.ANTHROPIC   # "anthropic"
ProviderType.GOOGLE      # "google"
ProviderType.AZURE       # "azure"
ProviderType.OPENROUTER  # "openrouter"
ProviderType.GEMINI      # "gemini"
ProviderType.COHERE      # "cohere"
ProviderType.GROQ        # "groq"
ProviderType.TOGETHER    # "together"
ProviderType.MOCK        # "mock"  (testing only)

---

ProviderCapabilities

Frozen dataclass describing what a provider supports:

from cleveragents.providers.registry import ProviderCapabilities

caps = registry.get_provider_info(ProviderType.OPENAI).capabilities
caps.supports_streaming    # bool
caps.supports_tool_calls   # bool
caps.supports_vision       # bool
caps.max_context_length    # int (tokens)
caps.supports_json_mode    # bool

Capability matrix:

Provider	Streaming	Tool Calls	Vision	Context (tokens)	JSON Mode
OpenAI	✓	✓	✓	128,000	✓
Anthropic	✓	✓	✓	200,000	✗
Google / Gemini	✓	✓	✓	1,000,000	✓
Azure OpenAI	✓	✓	✓	128,000	✓
OpenRouter	✓	✓	✓	128,000	✓
Cohere	✓	✓	✗	128,000	✗
Groq	✓	✓	✗	32,000	✓
Together	✓	✓	✗	32,000	✗

---

ProviderInfo

from cleveragents.providers.registry import ProviderInfo

info: ProviderInfo = registry.get_provider_info(ProviderType.ANTHROPIC)
info.provider_type    # ProviderType
info.name             # str — display name
info.api_key_env_var  # str — environment variable name
info.default_model    # str — default model ID
info.capabilities     # ProviderCapabilities
info.is_configured    # bool

---

resolve_provider_by_name

Convenience function to resolve a provider by string name with a clear error when not configured:

from cleveragents.providers.registry import resolve_provider_by_name

provider = resolve_provider_by_name("anthropic")
# Raises ValueError if not configured or name is unknown

---

get_provider_registry / reset_provider_registry

from cleveragents.providers.registry import get_provider_registry, reset_provider_registry

# Get or create the global singleton
registry = get_provider_registry()

# Reset (useful in tests for clean state)
reset_provider_registry()

---

Default Models

Provider	Default Model
OpenAI	gpt-4o
Anthropic	claude-sonnet-4-20250514
Google	gemini-2.0-flash
Gemini	gemini-2.0-flash
Azure	gpt-4o
OpenRouter	anthropic/claude-sonnet-4-20250514
Cohere	command-r-plus
Groq	llama-3.1-70b-versatile
Together	meta-llama/Llama-3.1-70B-Instruct-Turbo

Override with CLEVERAGENTS_DEFAULT_MODEL environment variable or settings.default_model.

---

Provider Implementations

Class	Module	Description
LangChainChatProvider	llm.langchain_chat_provider	Generic LangChain wrapper (OpenAI, Anthropic, Groq, etc.)
GoogleChatProvider	llm.google_provider	Google Generative AI provider
OpenRouterChatProvider	llm.openrouter_provider	OpenRouter multi-model provider

All implementations satisfy the AIProviderInterface protocol defined in cleveragents.domain.providers.

---

Performance Benchmarks

The providers module has a comprehensive ASV benchmark suite covering:

• ProviderRegistry initialization (none / one / all providers configured)
• get_all_providers() throughput
• get_provider_info() by enum and by string name
• is_provider_configured() for configured and unconfigured providers
• get_default_provider_type() with env-var, settings, and fallback paths
• get_default_model() resolution
• create_ai_provider() factory overhead

Run benchmarks with:

nox -s benchmarks
# or directly:
asv run --bench providers_registry_bench