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.

hailo_ollama

kilocli

KiloCLI subprocess model_provider.

model_pin

models_dev

Unauthenticated cross-provider model catalog via models.dev.

multimodal

ollama

openai

openai_codex

opencode_session

x-opencode-session — OpenCode relay session-affinity header.

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

safeguard_notice

Task-local side-channel for safeguard (refusal-triggered) model switches.

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.

AnthropicRefusalError

A provider safety refusal that completed at the transport layer but cannot be accepted as an assistant response.

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.

SafeguardFallbackNotice

One safeguard (refusal-triggered) fallback event for the current turn. Read post-loop by the channel orchestrator (PR 5); mirrors ProviderFallbackInfo’s task-local contract.

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.

SafeguardFallbackKind

Which layer performed the safeguard-triggered model switch.

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

commit_safeguard_fallback

Commit the safeguard attribution for the latest accepted response.

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

create_routed_model_provider_with_options_and_resolver

Build the routed provider together with the exact immutable route resolver it uses. Agent turn metadata can therefore resolve the serving profile and model without maintaining a second hint table.

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

durable_chat_messages

Project a full agent conversation history down to the flat ChatMessage shape durable session backends store: user/assistant chat turns only, system prompt excluded (the backend restores against the caller’s own system prompt, not a persisted one). AssistantToolCalls and ToolResults are tool-loop plumbing that durable session transcripts have never persisted; only the visible chat turns are kept.

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

model_refusal_from_error

Return the typed refusal that terminated a provider result, if any.

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

provider_runtime_options_for_bare_family

Runtime options for a bare family reference (e.g. ollama), which has no alias entry to resolve.

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.

rejected_attempt_usage_from_error

Return billed usage carried by a rejected provider result.

sanitize_api_error

Sanitize API error text by scrubbing secrets and truncating length.

scope_safeguard_fallback

Run the given future within a safeguard-fallback scope. Both commit_safeguard_fallback (inside the accepted-response owner) and take_last_safeguard_fallback (the runtime turn boundary) must execute within this scope for the data to be visible.

scrub_secret_patterns

Scrub known secret-like token prefixes from model_provider error strings. Provider API-key prefixes come from the same canonical table used for credential-family validation; non-provider prefixes cover Slack, GitHub, and Google/Gemini credentials. Complete query strings and fragments are removed from embedded HTTP(S) URLs because either suffix may carry credentials under provider-specific names.

take_last_safeguard_fallback

Take (consume) the last safeguard fallback notice, if any. Must be called within a scope_safeguard_fallback scope.

visible_provider_fallback

Select the generic provider-fallback record that still needs its own presentation next to safeguard.