Module providers 

ModelProvider subsystem — re-exported from zeroclaw-providers.

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.

dispatch

ProviderDispatch — single source of truth for attribution_span! on the ModelProvider surface.

factory

Per-family construction dispatch for model providers.

gemini

Google Gemini model_provider with support for:

gemini_cli

Gemini CLI subprocess model_provider.

grok_cli

Grok Build CLI subprocess model provider.

kilocli

KiloCLI subprocess model_provider.

model_pin

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.

pricing

Live model pricing: a single process-global snapshot of token prices fetched from providers’ own /models listings (with the models.dev catalog as a secondary source for models the gateway doesn’t price), used as a FALLBACK beneath the operator’s [cost.rates] config.

reliable

router

telnyx

Telnyx AI inference model_provider.

traits

vision_override

Structs

AccountedChatResponse

A successful response plus billed usage from Reliable attempts that were rejected before that response was accepted.

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.

ProviderDispatch

Wraps a model provider so every call opens the correct attribution_span! automatically. See the module docs for the rationale and the CI gate that enforces routing through this type.

ProviderDispatchRef

ReliableProviderTerminalFailure

The typed terminal presentation cause for a Reliable provider failure.

ReliableRejectedCompletionUsage

A Reliable chat request exhausted its candidates after receiving rejected semantic completions. The provider-reported usage is retained so the turn loop can account for work that was billed even though no response was accepted.

ReliableSemanticEmptyCompletion

The final candidate attempt completed successfully at the transport layer but supplied neither usable text nor a native tool call. This remains typed independently from optional rejected-attempt usage so delivery layers can classify the actual terminal failure without guessing from accounting data.

ResolvedModelProviderRef

A provider resolved from a config reference together with the model declared by that same alias. The model is an on-demand view of Config, not stored provider state.

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.

ModelProviderCategory

Grouping for a model-provider family. Replaces the section comments in the registry list with data so surfaces (CLI list, docs capability table) can group families without re-typing the membership. Mirrors the registry’s own sections exactly; locality is the separate local flag, not a category.

ReliableProviderTerminalFailureKind

A terminal Reliable failure that can be rendered safely at a user-facing delivery boundary without exposing retry-attempt diagnostics.

Traits

ModelProvider

Functions

api_error

Build a sanitized model_provider error from a failed HTTP response.

canonical_model_provider_slots

canonicalize_v2_model_provider_name

create_model_provider

create_model_provider_for_alias

create_model_provider_for_alias_with_url

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

create_model_provider_from_ref

Build a bare (non-resilient) provider named by name - a bare family ("llamacpp"), a dotted alias ("llamacpp.text_model"), or a custom:<url> ref - resolving its alias-specific runtime options from config: the vision capability override, the endpoint URI, and per-alias credentials from [providers.models.<family>.<alias>].

create_model_provider_from_ref_with_model

Resolve a provider reference and its alias-owned model as one materialized view. Callers may apply their own explicit model override after resolution; when the reference is bare or URL-based, model is None.

create_model_provider_with_options

Factory: create model_provider with runtime options. Legacy entry point — see create_model_provider.

create_model_provider_with_url

Factory: create model_provider with optional custom base URL. Legacy entry point — see create_model_provider.

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

create_resilient_model_provider_with_options

create_routed_model_provider_with_options

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).

fetch_context_window

Attempt to fetch context window from provider’s /models endpoint. Returns None on any failure (network, parsing, missing field) — caller uses fallback.

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

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>"). Returns safe defaults when the agent alias doesn’t exist, doesn’t have a model_provider set, or names a non-existent entry.

provider_runtime_options_for_alias

recommended_runtime_profile

Provider-specific runtime recommendations. This is deliberately separate from local: credential-free CLI shims can call cloud models, and local providers without native tool support must retain text-fallback prompting.

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. Redacts tokens with prefixes like sk-, xoxb-, xoxp-, ghp_, gho_, ghu_, github_pat_, and Google/Gemini AIza keys. Complete query strings are removed from embedded HTTP(S) URLs because query parameters may carry credentials under provider-specific names.