Crate zeroclaw_providers 

ModelProvider subsystem for model inference backends.

This module implements the factory pattern for AI model model_providers. Each model_provider implements the ModelProvider trait defined in traits, and is registered in the factory function create_model_provider by its canonical string key (e.g., "openai", "anthropic", "ollama", "gemini"). ModelProvider aliases are resolved internally so that user-facing keys remain stable.

Each model_provider call goes through the ReliableModelProvider wrapper, which adds automatic retry with exponential backoff and API-key rotation on rate limits. Model routing across multiple model_providers is available via [create_routed_model_provider].

Extension

To add a new model_provider, implement ModelProvider in a new submodule and register it in create_model_provider_with_url. See AGENTS.md §7.1 for the full change playbook.

Modules

anthropic

auth

azure_openai

bedrock

AWS Bedrock model_provider using the Converse API.

catalog

Per-family catalog source table.

compatible

Generic OpenAI-compatible model_provider. Most LLM APIs follow the same /v1/chat/completions format. This module provides a single implementation that works for all of them.

copilot

GitHub Copilot model_provider with OAuth device-flow authentication.

factory

Per-family construction dispatch for model providers.

gemini

Google Gemini model_provider with support for:

gemini_cli

Gemini CLI subprocess model_provider.

kilocli

KiloCLI subprocess model_provider.

models_dev

Unauthenticated cross-provider model catalog via models.dev.

multimodal

ollama

openai

openai_codex

openrouter

openrouter_catalog

Cross-vendor model catalog via OpenRouter’s public /api/v1/models endpoint.

reliable

router

telnyx

Telnyx AI inference model_provider.

traits

Structs

ChatMessage

A single message in a conversation.

ChatRequest

Request payload for model_provider chat calls.

ChatResponse

An LLM response that may contain text, tool calls, or both.

ModelProviderInfo

Information about a supported model model_provider for display purposes.

ModelProviderRuntimeOptions

ProviderCapabilityError

Structured error returned when a requested capability is not supported.

ToolCall

A tool call requested by the LLM.

ToolResultMessage

A tool result to feed back to the LLM.

Enums

ConversationMessage

A message in a multi-turn conversation, including tool interactions.

Traits

ModelProvider

Functions

api_error

Build a sanitized model_provider error from a failed HTTP response.

canonicalize_v2_model_provider_name

Map a V2 model-provider family name (synonyms, regional variants, OAuth suffixes) to its V3 canonical family. Production configs are normalised at TOML load time by normalize_provider_type in zeroclaw-config/src/schema/v2.rs. This helper duplicates the same table at the runtime factory boundary so callers that bypass the schema migration (programmatic factory invocations, tests, the create_model_provider_with_url colon-URL legacy entry point) still resolve. Inputs that are already canonical or unknown pass through unchanged.

create_model_provider

Factory: create the right model_provider from config (without custom URL).

create_model_provider_for_alias

Factory: create model_provider with full alias context.

create_model_provider_for_alias_with_url

Factory: create model_provider with alias context AND custom base URL.

create_model_provider_with_options

Factory: create model_provider with runtime options.

create_model_provider_with_url

Factory: create model_provider with optional custom base URL.

create_resilient_model_provider_for_alias

Wrap the primary model_provider in a retry/backoff harness with full alias context. Production callers (gateway, orchestrator) use this so the dispatch sees the typed alias config and routes Azure/Codex/Gemini extras correctly.

create_resilient_model_provider_from_ref

Build a resilient model provider from a name that may be either a bare family ("openai") or a dotted alias ("openai.work"). Dotted names dispatch through the typed alias factory so endpoint URI, family extras, and per-alias credentials from [model_providers.<family>.<alias>] are honored; bare names route through the family factory directly.

create_resilient_model_provider_with_options

Wrap the primary model_provider in a retry/backoff harness, threading auth runtime options.

create_routed_model_provider_with_options

Build a router fronted by primary_name plus one provider per unique model_routes entry. Each dotted <family>.<alias> name resolves through the typed [model_providers.<family>.<alias>] config (endpoint URI, Azure resource, Gemini OAuth, etc.); bare family names use family defaults.

default_model_provider_url

Canonical base URL for name, mirroring what create_model_provider would dial. None for families without a fixed default (Azure, custom, multi-region, CLI shims).

format_error_chain

Format an error including its full source chain and sanitize the result.

is_bailian_alias

is_doubao_alias

is_glm_alias

is_glm_cn_alias

is_glm_global_alias

is_minimax_alias

is_minimax_cn_alias

is_minimax_intl_alias

is_moonshot_alias

is_moonshot_cn_alias

is_moonshot_intl_alias

is_qianfan_alias

is_qwen_alias

is_qwen_cn_alias

is_qwen_intl_alias

is_qwen_oauth_alias

is_qwen_us_alias

is_zai_alias

is_zai_cn_alias

is_zai_global_alias

list_model_providers

Return the list of all known model_providers for display in zeroclaw model_providers list.

model_provider_runtime_options_from_model_provider_entry

Build ModelProviderRuntimeOptions from a specific ModelProviderConfig entry plus the global config’s process-wide settings (zeroclaw_dir, secrets, runtime). Splits out the per-entry resolution so callers with agent context can pass in the alias-resolved entry instead of hitting first_model_provider().

options_for_provider_ref

Options to use when building a provider from a name that may be either a bare family or a dotted alias. Dotted names yield alias-resolved options; bare names inherit only provider-agnostic settings from fallback.

provider_runtime_options_for_agent

Resolve ModelProviderRuntimeOptions from an agent’s model_provider alias ("<type>.<alias>"). Falls back to first_model_provider() when the agent alias doesn’t exist, doesn’t have a model_provider set, or names a non-existent model_provider entry.

provider_runtime_options_for_alias

Build runtime options for a specific dotted provider alias (<family>.<alias>). Mirrors provider_runtime_options_for_agent but keyed on the typed provider entry directly, so routed providers can resolve their alias-specific endpoint URI and other typed extras without going through an owning agent.

provider_runtime_options_from_config

sanitize_api_error

Sanitize API error text by scrubbing secrets and truncating length.

scrub_secret_patterns

Scrub known secret-like token prefixes from model_provider error strings.