providers schema

Canonical generated docsThis section is generated from caco config schema --json. The table below preserves the runtime field path, type, required/default markers, and canonical description for every value in this slice.

Provider credentials and canonical model catalogs — API keys, endpoints, configured models, and discovery overrides.

Field path	Type	Required	Default	Canonical description
`providers`	`section`	optional		Provider credentials and canonical model catalogs — API keys, endpoints, configured models, and discovery overrides.
└ `providers.openai`	`map`	optional		OpenAI provider.
└ `providers.openai.base_url`	`string`	optional		Base URL.
└ `providers.openai.api_key_file`	`string`	optional		Path to file containing API key.
└ `providers.openai.api_key_env`	`string`	optional	OPENAI_API_KEY	Env var name for API key.
└ `providers.openai.base_url_env`	`string`	optional	OPENAI_BASE_URL	Env var name for base URL.
└ `providers.openai.models`	`list[string \| map]`	optional		Canonical model catalog for this provider.
└ `providers.openai.models.name`	`string`	required		Provider-scoped model identifier.
└ `providers.openai.models.logical_provider`	`string`	optional		Canonical upstream provider that actually serves this model.
└ `providers.openai.model_endpoint`	`string`	optional	/v1/models	Model list endpoint path.
└ `providers.openai.model_discovery`	`map`	optional		Per-provider model discovery overrides.
└ `providers.openai.model_discovery.enabled`	`bool`	optional	true	Whether model discovery is enabled.
└ `providers.openai.model_discovery.interval_secs`	`u64`	optional	300	Polling interval in seconds.
└ `providers.openai.model_discovery.timeout_secs`	`u64`	optional	10	Per-request timeout in seconds.
└ `providers.anthropic`	`map`	optional		Anthropic provider.
└ `providers.anthropic.base_url`	`string`	optional		Base URL.
└ `providers.anthropic.auth_token_file`	`string`	optional		Path to file containing auth token.
└ `providers.anthropic.auth_token_env`	`string`	optional	ANTHROPIC_AUTH_TOKEN	Env var name for auth token.
└ `providers.anthropic.base_url_env`	`string`	optional	ANTHROPIC_BASE_URL	Env var name for base URL.
└ `providers.anthropic.models`	`list[string \| map]`	optional		Canonical model catalog for this provider.
└ `providers.anthropic.models.name`	`string`	required		Provider-scoped model identifier.
└ `providers.anthropic.models.logical_provider`	`string`	optional		Canonical upstream provider that actually serves this model.
└ `providers.anthropic.model_endpoint`	`string`	optional	/v1/models	Model list endpoint path.
└ `providers.anthropic.model_discovery`	`map`	optional		Per-provider model discovery overrides.
└ `providers.anthropic.model_discovery.enabled`	`bool`	optional	true	Whether model discovery is enabled.
└ `providers.anthropic.model_discovery.interval_secs`	`u64`	optional	300	Polling interval in seconds.
└ `providers.anthropic.model_discovery.timeout_secs`	`u64`	optional	10	Per-request timeout in seconds.
└ `providers.google`	`map`	optional		Google/Gemini provider.
└ `providers.google.base_url`	`string`	optional		Base URL.
└ `providers.google.api_key_file`	`string`	optional		Path to file containing API key.
└ `providers.google.api_key_env`	`string`	optional	GOOGLE_API_KEY	Env var name for API key.
└ `providers.google.models`	`list[string \| map]`	optional		Canonical model catalog for this provider.
└ `providers.google.models.name`	`string`	required		Provider-scoped model identifier.
└ `providers.google.models.logical_provider`	`string`	optional		Canonical upstream provider that actually serves this model.
└ `providers.google.model_endpoint`	`string`	optional	/v1/models	Model list endpoint path.
└ `providers.google.model_discovery`	`map`	optional		Per-provider model discovery overrides.
└ `providers.google.model_discovery.enabled`	`bool`	optional	true	Whether model discovery is enabled.
└ `providers.google.model_discovery.interval_secs`	`u64`	optional	300	Polling interval in seconds.
└ `providers.google.model_discovery.timeout_secs`	`u64`	optional	10	Per-request timeout in seconds.
└ `providers.azure`	`map`	optional		Direct Azure TTS/STT authentication; does not change OpenAI-compatible proxy auth.
└ `providers.azure.auth`	`string`	optional	key	Direct Azure authentication: key or entra. No automatic fallback between modes.
└ `providers.azure.az`	`string`	optional	az	Azure CLI-compatible token broker executable (e.g. az or az-token); invoked without a shell.
└ `providers.azure.api`	`string`	optional	openai-completions	Wire API: openai-completions or anthropic-messages; independent of provider identity.
└ `providers.azure.base_url`	`string`	optional		Base URL (e.g. http://localhost:8080/v1).
└ `providers.azure.api_key_file`	`string`	optional		Path to file containing API key.
└ `providers.azure.api_key_env`	`string`	optional		Env var name for API key.
└ `providers.azure.models`	`list[string \| map]`	optional		Canonical model catalog for this provider.
└ `providers.azure.models.name`	`string`	required		Provider-scoped model identifier.
└ `providers.azure.models.logical_provider`	`string`	optional		Canonical upstream provider that actually serves this model.
└ `providers.azure.model_endpoint`	`string`	optional	/v1/models	Model list endpoint path.
└ `providers.azure.model_headers`	`map[string,string]`	optional		Non-secret model-discovery protocol headers; authentication uses api_key_file/api_key_env.
└ `providers.azure.model_discovery`	`map`	optional		Per-provider model discovery overrides.
└ `providers.azure.model_discovery.enabled`	`bool`	optional	true	Whether model discovery is enabled.
└ `providers.azure.model_discovery.interval_secs`	`u64`	optional	300	Polling interval in seconds.
└ `providers.azure.model_discovery.timeout_secs`	`u64`	optional	10	Per-request timeout in seconds.
└ `providers.azure-speech`	`map`	optional		Azure Speech native STT/TTS and separately configured MAI STT provider.
└ `providers.azure-speech.resource_id`	`string`	optional		Azure ARM resource ID; required for direct native TTS with providers.azure.auth=entra.
└ `providers.azure-speech.base_url`	`string`	optional		Azure Speech region or resource base URL (e.g. https://eastus.api.cognitive.microsoft.com).
└ `providers.azure-speech.api_key_file`	`string`	optional		Path to file containing the Azure Speech subscription key.
└ `providers.azure-speech.api_key_env`	`string`	optional	AZURE_SPEECH_API_KEY	Env var name for the API key.
└ `providers.azure-speech.base_url_env`	`string`	optional	AZURE_SPEECH_BASE_URL	Env var name for the base URL.
└ `providers.azure-speech.api_version`	`string`	optional	2025-10-15	Transcription REST API version.
└ `providers.azure-speech.locales`	`list[string]`	optional		Default transcription locales (e.g. ["en-US"]).
└ `providers.azure-speech.tts_base_url`	`string`	optional		Optional explicit native TTS endpoint (.../cognitiveservices/v1); derived from base_url region when omitted.
└ `providers.azure-speech.mai`	`map`	optional		Separate Azure MAI STT resource binding for mai-transcribe-2 (multipart/form-data transcription API).
└ `providers.azure-speech.mai.base_url`	`string`	optional		Azure MAI resource root (services.ai.azure.com or cognitiveservices.azure.com).
└ `providers.azure-speech.mai.base_url_env`	`string`	optional	AZURE_STT_ENDPOINT	Endpoint environment variable.
└ `providers.azure-speech.mai.api_key_file`	`string`	optional		Path to MAI resource API key file; preferred over environment.
└ `providers.azure-speech.mai.api_key_env`	`string`	optional	AZURE_STT_API_KEY	API key environment variable.
└ `providers.azure-speech.mai.deployment`	`string`	optional		Required MAI transcription deployment name.
└ `providers.local`	`map`	optional		Local provider configuration for arbitrary model endpoints.
└ `providers.local.models`	`list[map]`	optional		Registered local model endpoints.
└ `providers.local.models.name`	`string`	required		Human-friendly name for this model configuration.
└ `providers.pi`	`map`	optional		Pi-native provider configuration.
└ `providers.pi.github-copilot`	`map`	optional		Native Pi GitHub Copilot provider configuration.
└ `providers.pi.github-copilot.auth-file`	`string`	optional		Path to the operator's Pi auth.json file copied into managed Pi workspaces.
└ `providers.pi.github-copilot.models`	`list[string \| map]`	optional		Canonical GitHub Copilot model catalog for Pi workspaces.
└ `providers.pi.github-copilot.models.name`	`string`	required		Provider-scoped model identifier.
└ `providers.pi.github-copilot.models.logical_provider`	`string`	optional		Canonical upstream provider that actually serves this model.
└ `providers.pi.models`	`map[string, map]`	optional		Custom provider declarations for Pi models.json materialization. Keyed by provider name.
└ `providers.pi.models.<provider-name>`	`map`	optional		Custom provider entry.
└ `providers.pi.models.<provider-name>.api`	`string`	optional		API type: anthropic-messages, openai-responses, openai-chat.
└ `providers.pi.models.<provider-name>.api_key_env`	`string`	optional		Environment variable name for the API key.
└ `providers.pi.models.<provider-name>.base_url`	`string`	optional		Base URL for the provider API.
└ `providers.pi.models.<provider-name>.logical_provider`	`string`	optional		Canonical upstream provider for this intermediary (e.g. 'anthropic' for litellm-anthropic). Used for Pi avatar selection.
└ `providers.pi.models.<provider-name>.models`	`list[string \| map]`	optional		Optional per-model entries with their own logical_provider overrides.
└ `providers.pi.models.<provider-name>.models.name`	`string`	required		Provider-scoped model identifier.
└ `providers.pi.models.<provider-name>.models.logical_provider`	`string`	optional		Canonical upstream provider that actually serves this model.
└ `providers.<custom>`	`map`	optional		Custom provider with OpenAI-compatible API.
└ `providers.<custom>.api`	`string`	optional	openai-completions	Wire API: openai-completions or anthropic-messages; independent of provider identity.
└ `providers.<custom>.base_url`	`string`	optional		Base URL (e.g. http://localhost:8080/v1).
└ `providers.<custom>.api_key_file`	`string`	optional		Path to file containing API key.
└ `providers.<custom>.api_key_env`	`string`	optional		Env var name for API key.
└ `providers.<custom>.models`	`list[string \| map]`	optional		Canonical model catalog for this provider.
└ `providers.<custom>.models.name`	`string`	required		Provider-scoped model identifier.
└ `providers.<custom>.models.logical_provider`	`string`	optional		Canonical upstream provider that actually serves this model.
└ `providers.<custom>.model_endpoint`	`string`	optional	/v1/models	Model list endpoint path.
└ `providers.<custom>.model_headers`	`map[string,string]`	optional		Non-secret model-discovery protocol headers; authentication uses api_key_file/api_key_env.
└ `providers.<custom>.model_discovery`	`map`	optional		Per-provider model discovery overrides.
└ `providers.<custom>.model_discovery.enabled`	`bool`	optional	true	Whether model discovery is enabled.
└ `providers.<custom>.model_discovery.interval_secs`	`u64`	optional	300	Polling interval in seconds.
└ `providers.<custom>.model_discovery.timeout_secs`	`u64`	optional	10	Per-request timeout in seconds.