Skip to content

providers.md

Latest commit

 

History

History
787 lines (638 loc) · 33.6 KB

providers.md

File metadata and controls

787 lines (638 loc) · 33.6 KB
Raw

Providers

Sigma separates model metadata from provider implementations. A model entry says what can be requested; a provider entry makes the request runnable. Register both on the same *sigma.Registry, then pass that registry to sigma.NewClient.

registry := sigma.NewRegistry()
if err := openai.Register(registry, sigma.ProviderOpenAI); err != nil {
	return err
}
model := sigma.Model{
	ID:              "gpt-4o-mini",
	Provider:        sigma.ProviderOpenAI,
	API:             sigma.APIOpenAICompletions,
	SupportedInputs: []sigma.ContentBlockType{sigma.ContentBlockText},
}
if err := registry.RegisterModel(model); err != nil {
	return err
}
client := sigma.NewClient(sigma.WithRegistry(registry))

sigma.DefaultRegistry returns a clone of built-in metadata. Provider packages are not automatically imported for you; import and register the providers your application uses. Use sigma.NewRegistry for tests, local endpoints, and applications that need explicit provider control.

Request Flow

Client.CompleteText
  -> Client.Complete
  -> Client.Stream
  -> Registry.Model and Registry.TextProvider
  -> provider.Stream
  -> Stream.Events
  -> Collect
  -> AssistantMessage

Image calls use the same registry pattern, but dispatch through Registry.ImageProvider and return AssistantImages.

Credentials

Provider adapters receive credentials through sigma.Options.AuthResolver. Application code can provide credentials in four ways:

  • sigma.WithAPIKey("...") for a single request.
  • sigma.WithAuthResolver(...) on a client.
  • sigma.WithProviderAuthResolver(provider, ...) for one provider.
  • Environment variables through sigma.EnvironmentAuthResolver, which is part of the default credential chain.

Use EnvironmentAuthResolver.EnvVars to show the ordered environment variables Sigma would check for a model, or ConfiguredEnvVars to show which of those names are currently set without exposing secret values:

resolver := sigma.EnvironmentAuthResolver{}
names := resolver.EnvVars(model)
configured := resolver.ConfiguredEnvVars(model)
_, _ = names, configured

Do not put credentials in Request, ProviderMetadata, tool arguments, or persisted JSON. See Security for redaction behavior.

Resolved request configuration

Resolvers implementing AuthResolutionResolver can return an AuthResolution containing credentials and request defaults. Codex SSE and WebSocket requests, OpenAI images and embeddings, Google and native Vertex text/images/embeddings, Vertex OpenAI/Anthropic MaaS text, and OpenRouter images apply those defaults before constructing their endpoint, payload, and headers. Credentials resolve once per request or connection attempt; retries and SSE fallback have their own attempt lifecycle. Explicit Codex token providers retain precedence over the general resolver. Google and OpenRouter image HTTP retries start from the original caller options, so refreshed auth-derived endpoints and headers replace the previous attempt's defaults. Google and Vertex text, images, and embeddings, including Vertex MaaS text routes, follow the same retry behavior. HTTP-client selection remains unchanged; callers still own embedding-cache namespace isolation.

Explicit caller configuration overrides auth-derived defaults. A caller-supplied base_url or baseURL blocks auth defaults under either spelling, including defaults in AuthResolution.ProviderOptions; explicit endpoint precedence is unchanged. Header names merge without regard to case across provider constructors, model metadata, client defaults, and request options. Later options win and retain their supplied spelling. Within one map, duplicate case variants are processed in lexical order, with the last variant winning. Auth-derived headers fill only absent caller names. Caller maps are copied, and each adapter retains its existing provider/model/request precedence and final header suppression.

Codex cached WebSocket connections require matching provider, effective URL, and final handshake headers for reuse. Changing routing, credentials, or account headers starts a fresh connection and continuation state. Busy connections remain owned by their active request, with overlaps using separate connections. A request falls back to SSE, and the session prefers SSE afterward, only when the WebSocket connection fails before any output, or when a connection-limit or missing-continuation error persists after its single retry. Provider errors, authentication failures, and payload errors are returned without an SSE resend. OpenAI tool-schema conversion preserves exact JSON numbers. Codex WebSocket requests and continuation copies retain those values, including integers beyond the exact range of float64; changing a schema invalidates continuation reuse.

InMemoryCredentialStore serializes modifications and deletions per provider. Cancellation or a deadline interrupts a wait for ownership without running the waiting modifier or deleting credentials. An active modifier retains ownership until its callback returns and keeps its existing commit behavior, including persisting a successful refresh rotation. Callbacks must honor their own contexts; operations for other providers remain independent.

The Codex, Anthropic, GitHub Copilot, Kimi, xAI, and Radius in-memory token providers serialize credential inspection, refresh, replacement, and persistence callbacks. A context canceled before or during the ownership wait returns promptly without starting refresh work or changing credentials. Once a refresh starts, the refresh request and its persistence callback ignore caller cancellation and are bounded by a 15-second timeout, because the provider may already have rotated the refresh token; stored-credential refresh through StoredCredentialAuthResolver follows the same rule. Successful waiters reuse refreshed credentials under the existing validity rules; callback failure and credential-rotation semantics are unchanged.

Request-scoped OAuth lifetime

Long-running streams and tool workflows can require an OAuth credential to retain a minimum lifetime before dispatch. The request minimum only lengthens a provider's existing refresh window; omitting it, or setting it to zero, keeps the current refresh timing. Credentials without a known expiry are unchanged.

client := sigma.NewClient(
	sigma.WithCredentialStore(store),
	sigma.WithStoredProviderAuth(),
	sigma.WithDefaultOptions(
		sigma.WithOAuthMinimumValidity(5*time.Minute),
	),
)

_, _ = client.Complete(ctx, model, request,
	sigma.WithOAuthMinimumValidity(30*time.Minute),
)
_, _ = client.GenerateImages(ctx, imageModel, imageRequest,
	sigma.WithImageOAuthMinimumValidity(15*time.Minute),
)
_, _ = client.Embed(ctx, embeddingModel, embeddingRequest,
	sigma.WithEmbeddingOAuthMinimumValidity(10*time.Minute),
)

Stored OAuth credentials use the registered provider refresh function and persist the rotation through the caller-supplied credential store. Sigma's built-in Anthropic, OpenAI Codex, GitHub Copilot, Kimi Coding, Radius, and xAI in-memory OAuth token providers honor the same option and continue reporting rotations through their existing callbacks. Negative durations fail locally before provider dispatch. If a refreshed token still expires within an explicit minimum, the rotation is persisted and the request fails with an error wrapping ErrCredentialUnavailable rather than dispatching a shorter-lived token; choose a minimum within the provider's token lifetime. A stored OAuth credential owns its provider: when its refresh or token derivation fails, the request fails instead of falling back to environment API keys or default provider callbacks.

Setup Snippets

OpenAI Chat Completions

registry := sigma.NewRegistry()
_ = openai.Register(registry, sigma.ProviderOpenAI)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: OPENAI_API_KEY.

Use openai.Register for APIOpenAICompletions. This adapter also supports OpenAI-compatible routers and local endpoints when model metadata describes the endpoint compatibility.

OpenAI Responses

registry := sigma.NewRegistry()
_ = openai.RegisterResponses(registry, sigma.ProviderOpenAI)

Environment: OPENAI_API_KEY.

Use APIOpenAIResponses model metadata. Responses supports streaming output, reasoning summaries, tool calls, image input, and usage where the upstream response includes it. Supplied cache reads and cache writes are retained in raw usage and deducted from ordinary input tokens, clamped at zero. Provider totals remain intact; cache-write pricing and existing cost/service tiers apply across shared Responses parsing, including Azure, Codex, and deferred results.

Chat Completions reasoning details replay only with exact, nonempty source provider/API/model provenance, including legacy tool-call metadata. Modern validated metadata takes precedence over the legacy fallback. Missing or mismatched provenance omits reasoning details while preserving ordinary history.

Azure OpenAI Responses

registry := sigma.NewRegistry()
_ = azure.Register(registry)

Environment: AZURE_OPENAI_API_KEY for API-key auth. Microsoft Entra auth uses azure.WithTokenCredential with a caller-supplied token source.

Generated models use ProviderAzureOpenAIResponses. Model metadata should include AzureOpenAIResponsesConfig, or requests should set endpoint, deployment, API version, and credential source with the Azure option helpers. Use openai.RegisterAzureResponses when registering a custom provider ID instead of the built-in Azure OpenAI Responses provider ID. Requests use Azure's /openai/v1/responses path, whose api-version accepts v1 (the generated default) or preview; dated versions such as 2025-04-01-preview belong to the legacy route.

OpenAI-Compatible Sampling Parameters

OpenAI-compatible Chat Completions, Responses, and Azure Responses requests can send provider-supported sampling fields without adding them to Sigma's provider-neutral option surface:

sampling := sigma.WithOpenAIOptions(sigma.OpenAIOptions{
	SamplingParameters: map[string]any{
		"top_p": 0.95,
		"top_k": 40,
		"seed":  0,
	},
})

Sampling parameters are applied after typed request fields, so they can override values such as temperature. Provider extra_body values are applied after sampling parameters and retain final precedence. Sigma does not validate arbitrary parameter names or values; the upstream provider owns that contract. Non-empty sampling parameters are rejected for Codex Responses and non-OpenAI APIs.

OpenAI Codex Responses

registry := sigma.NewRegistry()
_ = openai.RegisterCodexResponses(registry, sigma.ProviderOpenAICodex)

Generated Codex models use ProviderOpenAICodex. Codex Responses accepts OAuth credentials through openai.WithCodexResponsesOAuthTokenProvider or the general auth resolver, including stored provider auth. An explicit token provider takes precedence. Use openai.LoginOpenAICodexBrowser, openai.LoginOpenAICodexDeviceCode, openai.RefreshOpenAICodexToken, and openai.NewCodexOAuthTokenProvider for stdlib-only login and refresh. Codex browser login listens on port 1455, which the Codex CLI also uses; when that port is taken and OnManualCode is set, login completes with the pasted redirect URL or code.

Store-backed applications can persist a login result through a caller-owned credential store and let Sigma's stored-auth resolver handle refresh serialization:

store := sigma.NewInMemoryCredentialStore()
credentials, _ := openai.LoginOpenAICodexDeviceCode(ctx, openai.CodexDeviceCodeLoginOptions{})
_, _ = openai.StoreCodexOAuthCredentials(ctx, store, sigma.ProviderOpenAICodex, credentials)
_ = openai.RegisterCodexProviderAuth(registry, sigma.ProviderOpenAICodex, openai.CodexOAuthTokenProviderOptions{})
client := sigma.NewClient(sigma.WithRegistry(registry), sigma.WithCredentialStore(store), sigma.WithStoredProviderAuth())

Concrete disk, keychain, or encrypted credential storage remains caller-owned. Codex image input should use HTTPS image URLs; ChatGPT Codex rejects base64 image payloads.

Codex WebSocket proxy exclusions accept bare parent domains, leading-dot and *. forms for roots and descendants, and * anywhere in a NO_PROXY list. Matching respects DNS-label boundaries and optional ports; IPv4 and IPv6 literals match exact addresses, including bracketed IPv6 with a port. Invalid entries and CIDR ranges do not match. Proxy-variable precedence and SSE fallback are unchanged.

GitHub Copilot

registry := sigma.DefaultRegistry()
_ = githubcopilot.RegisterResponses(registry)
_ = githubcopilot.RegisterAnthropic(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: COPILOT_GITHUB_TOKEN.

provider/githubcopilot is a thin wrapper over the shared OpenAI-compatible and Anthropic-compatible adapters. Use Register for Chat Completions models, RegisterResponses for Responses models, and RegisterAnthropic for Anthropic Messages models. The wrapper applies the Copilot base URL, the Copilot dynamic initiator/intent/vision headers, static model headers from metadata, and bearer-token auth. Stored Copilot OAuth credentials and GitHubCopilotOAuthTokenProvider route business, enterprise, and data-residency accounts to the host in the token's proxy-ep field instead of the individual endpoint; an explicit request base_url provider option still wins.

Cloudflare AI Gateway

registry := sigma.DefaultRegistry()
_ = cloudflare.RegisterAIGatewayResponses(registry)
_ = cloudflare.RegisterAIGatewayAnthropic(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: CLOUDFLARE_API_KEY, CLOUDFLARE_ACCOUNT_ID, and CLOUDFLARE_GATEWAY_ID.

provider/cloudflare exposes AI Gateway helpers for OpenAI-compatible and Anthropic-compatible text routes. The wrapper resolves account and gateway placeholders in the base URL and sends API keys with Cloudflare's cf-aig-authorization header.

Direct Cloudflare Workers AI Chat Completions routes use the same package with normal bearer-token auth:

registry := sigma.DefaultRegistry()
_ = cloudflare.RegisterWorkersAI(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: CLOUDFLARE_API_KEY and CLOUDFLARE_ACCOUNT_ID.

Use cloudflare.WithWorkersAIAccountID for request-scoped account placeholder resolution when the process environment should not provide the account ID.

Vercel AI Gateway

registry := sigma.DefaultRegistry()
_ = vercel.Register(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: AI_GATEWAY_API_KEY.

The Vercel AI Gateway wrapper uses Sigma's shared Anthropic-compatible Messages adapter with the direct Vercel AI Gateway base URL. Built-in metadata is available under ProviderVercelAIGateway for curated gateway text routes, including adaptive thinking and temperature compatibility metadata where required by the route.

Hugging Face Router

registry := sigma.DefaultRegistry()
_ = huggingface.Register(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: HF_TOKEN.

provider/huggingface is a thin wrapper over Sigma's shared OpenAI-compatible Chat Completions adapter with the Hugging Face Router base URL. Built-in metadata is intentionally focused on a small reviewed set of router text routes; broad router catalog expansion stays in the reviewed catalog workflow.

Anthropic Messages

registry := sigma.NewRegistry()
_ = anthropic.Register(registry, sigma.ProviderAnthropic)

Environment: ANTHROPIC_API_KEY.

Claude Pro/Max subscriptions can authenticate with OAuth instead of an API key. Use anthropic.LoginAnthropicBrowser, anthropic.RefreshAnthropicToken, and anthropic.NewAnthropicOAuthTokenProvider for stdlib-only browser callback login, refresh, and request-time token resolution; credential persistence stays caller-owned. When the resolved credential is an Anthropic OAuth token, the adapter automatically sends the required Claude Code identity (beta headers, identity system block, and canonical tool-name casing, with streamed tool names restored to the caller's casing). Browser login prefers the callback at http://localhost:53692/callback; when that port is reserved or in use it binds a free loopback port, and if no port is available it completes with OnManualCode input alone.

This adapter also handles Anthropic-compatible endpoints used by some Kimi, Fireworks, and Xiaomi routes. Compatibility varies by endpoint; check provider parity.

Server-tool invocation counts, such as web_search_requests, remain in Usage.Raw.server_tool_use; they are not token counts and do not contribute to Usage.ToolUseInputTokens or total tokens. Raw usage accumulates supplied fields across streaming updates, retaining earlier metadata when later updates omit it. Explicit zero or null values replace earlier raw values, and nested objects merge by supplied key. Previously emitted usage snapshots remain unchanged.

Kimi and Kimi Coding

registry := sigma.DefaultRegistry()
_ = kimi.Register(registry)
_ = kimi.RegisterCoding(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: KIMI_API_KEY.

The Kimi wrappers use Sigma's shared Anthropic-compatible Messages adapter with the Kimi endpoint base URL and Kimi CLI request header defaults. Built-in metadata is available under ProviderKimi for the canonical kimi-for-coding route. ProviderKimiCoding carries the expanded coding model family with k3, kimi-for-coding, and kimi-for-coding-highspeed, including adaptive thinking, session-affinity, tool-use, and image-input metadata where supported by the model. K3 supports low, high, and max adaptive-thinking efforts.

Kimi Coding subscriptions can authenticate with device-code OAuth instead of an API key. Use kimi.LoginKimiCodingDeviceCode, kimi.RefreshKimiCodingToken, and kimi.NewKimiCodingOAuthTokenProvider for login, refresh, and request-time token resolution. Register kimi.RegisterAuth when resolving a caller-owned stored credential. OAuth registration is opt-in, KIMI_API_KEY remains the API-key fallback, and token persistence remains owned by the application.

credentials, _ := kimi.LoginKimiCodingDeviceCode(ctx, kimi.KimiCodingDeviceCodeLoginOptions{
	OnDeviceCode: func(info kimi.KimiCodingDeviceCodeInfo) {
		// Show info.UserCode and info.VerificationURI to the user.
	},
})
auth := kimi.NewKimiCodingOAuthTokenProvider(credentials, kimi.KimiCodingOAuthTokenProviderOptions{})
client := sigma.NewClient(
	sigma.WithRegistry(registry),
	sigma.WithDefaultOptions(sigma.WithProviderAuthResolver(sigma.ProviderKimiCoding, auth)),
)

Fireworks AI

registry := sigma.DefaultRegistry()
_ = fireworks.Register(registry)
_ = fireworks.RegisterAnthropic(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: FIREWORKS_API_KEY.

The built-in Fireworks text routes include accounts/fireworks/models/kimi-k2p7-code, accounts/fireworks/models/kimi-k3, and accounts/fireworks/routers/glm-5p2-fast. The adapter uses Fireworks' OpenAI-compatible Chat Completions endpoint and supports streaming text, usage, thinking, and function tools in the shared openai-completions path. sigma.WithReasoningLevel maps to Fireworks reasoning_effort; sigma.WithThinkingBudgetTokens maps to the Fireworks thinking object.

The built-in Fireworks Anthropic-compatible routes are accounts/fireworks/models/kimi-k2p6 and accounts/fireworks/models/kimi-k2p7-code under ProviderFireworksAnthropic. Register them with fireworks.RegisterAnthropic; they use the shared Anthropic Messages adapter against Fireworks' /messages endpoint and carry compatibility metadata for image input, thinking levels, cache behavior, and tool use.

Baseten

registry := sigma.DefaultRegistry()
_ = baseten.Register(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: BASETEN_API_KEY.

The Baseten wrapper uses Sigma's shared OpenAI-compatible Chat Completions adapter with the direct model API base URL. Focused built-in metadata covers zai-org/GLM-5.2 for text and moonshotai/Kimi-K2.6 for text and image input. Both support tools and explicit thinking toggles; GLM 5.2 also maps off, high, and max reasoning efforts.

NVIDIA NIM

registry := sigma.DefaultRegistry()
_ = nvidia.Register(registry)
_ = nvidia.RegisterEmbeddings(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: NVIDIA_API_KEY.

The NVIDIA NIM wrapper uses Sigma's shared OpenAI-compatible Chat Completions and Embeddings adapters with the direct NIM base URL. Built-in text metadata is available under ProviderNVIDIA, and built-in embedding metadata includes nvidia/nv-embedqa-e5-v5. The embedding wrapper maps sigma.EmbeddingInputTypeQuery to NVIDIA input_type: "query" and sigma.EmbeddingInputTypeDocument to input_type: "passage" unless callers set EmbeddingRequest.ProviderMetadata["input_type"] explicitly.

Moonshot AI

registry := sigma.DefaultRegistry()
_ = moonshot.Register(registry)
_ = moonshot.RegisterCN(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: MOONSHOT_API_KEY.

The Moonshot wrappers use Sigma's shared OpenAI-compatible Chat Completions adapter with direct Moonshot AI and Moonshot AI CN base URL defaults. Built-in metadata includes direct Kimi K2 rows such as kimi-k2.7-code and kimi-k2.7-code-highspeed, including image input, tool use, DeepSeek-style thinking controls, streaming usage, and K2.7 compatibility metadata that omits explicit disabled-thinking payloads by default.

Qwen Token Plan

registry := sigma.DefaultRegistry()
_ = qwen.Register(registry)
_ = qwen.RegisterIndividual(registry)
_ = qwen.RegisterCN(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: QWEN_TOKEN_PLAN_API_KEY for ProviderQwenTokenPlan and ProviderQwenTokenPlanIndividual; QWEN_TOKEN_PLAN_CN_API_KEY for ProviderQwenTokenPlanCN.

The Qwen Token Plan wrappers use Sigma's shared OpenAI-compatible Chat Completions adapter with international, Individual subscription, and China regional routes. The Individual route shares the international endpoint and credential and provides seven curated DeepSeek V4, GLM-5.2, Qwen3.6, Qwen3.7, and Qwen3.8 models. Built-in metadata preserves each model's text and image inputs, tool support, limits, and Qwen thinking controls.

Xiaomi MiMo

registry := sigma.DefaultRegistry()
_ = xiaomi.Register(registry)
_ = xiaomi.RegisterTokenPlanAMS(registry)
client := sigma.NewClient(sigma.WithRegistry(registry))

Environment: XIAOMI_API_KEY for ProviderXiaomi, XIAOMI_TOKEN_PLAN_CN_API_KEY for ProviderXiaomiTokenPlanCN, XIAOMI_TOKEN_PLAN_AMS_API_KEY for ProviderXiaomiTokenPlanAMS, and XIAOMI_TOKEN_PLAN_SGP_API_KEY for ProviderXiaomiTokenPlanSGP.

The Xiaomi wrapper uses Sigma's shared OpenAI-compatible Chat Completions adapter for the API-billing and regional token-plan /v1 routes. Built-in metadata includes mimo-v2.5, mimo-v2.5-pro, and mimo-v2.5-pro-ultraspeed for API billing. Each CN, AMS, and SGP token-plan route includes mimo-v2.5 and mimo-v2.5-pro; use RegisterTokenPlanCN, RegisterTokenPlanAMS, or RegisterTokenPlanSGP for the respective region. MiMo documents only a thinking on/off toggle, so these models accept the off and high reasoning levels and send thinking.type without reasoning_effort.

Google Generative AI

registry := sigma.NewRegistry()
_ = google.Register(registry, sigma.ProviderGoogle)

Environment: GOOGLE_API_KEY, GOOGLE_CLOUD_API_KEY, or GEMINI_API_KEY, checked in that order.

The Gemini API adapter supports text, image input, streaming, tools, thinking metadata, and usage in fixture-tested paths.

Google Vertex AI

The generated catalog includes 14 native Gemini text models, three Gemini image models, and one embedding model under google-vertex. Separate registrations provide 17 Claude models under google-vertex-anthropic and eight OpenAI-compatible MaaS models under google-vertex-openai, including Llama, GPT-OSS, Grok, and GLM. Use anthropic.RegisterVertex or openai.RegisterVertex for those text routes; native text registration does not register MaaS adapters. Catalog presence does not guarantee account access or availability in every region. In particular, select global for GLM-5.2.

Gemini Pro rows include long-context cost tiers, while newer Claude rows use flat global endpoint estimates. Regional Claude prices can differ. See Vertex pricing and model lifecycle dates. Deprecated entries remain selectable until their scheduled retirement; Sigma does not automatically migrate a caller to another model.

GPT-OSS supports named reasoning effort. Grok and GLM MaaS models preserve provider-default reasoning and reject named levels locally. GLM's Vertex-specific chat_template_kwargs.enable_thinking switch can be supplied explicitly through provider extra_body; the direct Z.ai thinking shape does not apply. See Vertex thinking controls. Native Flash and Flash-Lite latest aliases retain their existing named-thinking restrictions.

registry := sigma.NewRegistry()
_ = google.RegisterVertex(registry, sigma.ProviderGoogleVertex,
	google.WithVertexConfig(google.VertexConfig{
		ProjectID: "my-project",
		Location:  "us-central1",
	}),
)

Applications commonly resolve routing from GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION or GOOGLE_CLOUD_REGION, then pass it through VertexConfig or provider options. API-key auth can use GOOGLE_API_KEY or GOOGLE_CLOUD_API_KEY; ADC/OAuth auth should be supplied with google.WithVertexTokenProvider. Native Gemini text requests that use an API key without a project use Vertex express mode, which routes to https://aiplatform.googleapis.com/v1/publishers/google/models/{model}. OAuth credentials still require a project and location.

Rich auth resolutions can also supply missing routing, headers, and provider options. Each attempt resolves before endpoint and payload construction, with caller options taking precedence. The requested credential mode selects the credential source, and the merged mode validates the selected credential without a second resolution. Token mode with a configured token provider bypasses the general resolver; automatic mode retains its unavailable/placeholder-key fallback. These rules also apply to native image/embedding and OpenAI/Anthropic MaaS routes.

Mistral Conversations

registry := sigma.NewRegistry()
_ = mistral.Register(registry, sigma.ProviderMistral)

Environment: MISTRAL_API_KEY.

The current adapter covers streaming text, streamed thinking chunks, function tools, request-scoped x-affinity session reuse through sigma.WithSessionID, base64 image input, image-bearing tool results, and replay of cross-provider tool-call IDs. URL/file image references, built-in connectors, append, and restart are not implemented.

Amazon Bedrock Converse Stream

registry := sigma.NewRegistry()
_ = bedrock.Register(registry, sigma.ProviderAmazonBedrock,
	bedrock.WithRegion("us-east-1"),
)

The Bedrock adapter uses stdlib HTTP, SigV4 signing, and EventStream parsing; it does not import the AWS SDK. Configure the region with bedrock.WithRegion or provider options; if neither is set, it falls back to AWS_REGION and then AWS_DEFAULT_REGION. Bedrock first accepts a request-scoped bearer token, then uses the configured credential source. The default CredentialSourceAuto source tries the auth resolver before the built-in default chain; resolver failures other than unavailable credentials stop resolution. The default chain checks request-scoped static credentials, AWS_BEARER_TOKEN_BEDROCK, static AWS environment credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optional AWS_SESSION_TOKEN), shared profiles, ECS credentials, web identity, and IMDS, in that order. A configured ECS or web identity source reports fetch failures instead of falling through to IMDS. As in the AWS SDKs, AWS_CONTAINER_CREDENTIALS_FULL_URI may use HTTPS to any host, but plain HTTP only to loopback or the ECS and EKS container credential addresses.

Shared profile lookup uses AWS_PROFILE (or default). When AWS_PROFILE is set explicitly and that profile has static keys, it takes precedence over the static AWS environment credentials. AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE each replace their respective home-directory default; the effective credentials file is checked before the effective config file. Missing files or profiles continue to remaining sources, without consulting an overridden default file.

Profile and metadata-service credentials are cached against the credential environment: credentials without an expiry are cached for 15 minutes, and expiring credentials are cached until five minutes before expiry. A subsequent request resolves them again. Changing a profile file in place does not immediately invalidate that cache. Environment and request-scoped static credentials are checked before the cache.

Use bedrock.WithCredentialSource(bedrock.CredentialSourceAuthResolver) and an explicit resolver to avoid built-in file and metadata-service discovery. AWS SDK integration and SSO remain unsupported. OAuth persistence remains caller-owned.

Tests can inject ConverseStreamClient and CredentialDetector fakes, or use bedrock.WithEndpoint with an httptest.Server.

Use sigma.WithBedrockOptions for Bedrock-specific request controls such as tool choice, thinking display, interleaved thinking, stop sequences, top-p, request metadata, additional model request fields, and response field paths. Request headers from sigma.WithHeader and sigma.WithHeaders are applied before SigV4 signing; authorization, host, and x-amz-* headers remain owned by the adapter.

Claude requests without MaxTokens send the model's output limit as inferenceConfig.maxTokens; Bedrock otherwise caps Claude output at 4,096 tokens. Other model families keep Bedrock's default.

Manual Claude thinking reserves 1,024 tokens for output within the effective MaxTokens cap and clamps the thinking budget to the remaining space. If fewer than 1,024 thinking tokens fit, thinking is disabled. With no supplied cap, enabled manual thinking sends the model's output limit, falling back to 1,024. Interleaved thinking with tools in the final request may exceed the output cap; its thinking budget must still be at least 1,024. Adaptive thinking and non-Claude reasoning retain their existing controls, except that OpenAI models take a reasoning effort instead of a thinking budget: gpt-oss receives a flat reasoning_effort limited to low through high, other GPT models a nested reasoning.effort, and minimal is sent as low. Generated Bedrock gpt-oss and GPT-5.x rows advertise reasoning; GPT-5.x rows also accept xhigh.

Replayed non-Claude reasoning omits signatures. Claude thinking without a valid nonblank signature is sent as ordinary text; signed and redacted blocks retain their existing replay behavior. These conversions do not alter stored histories.

Bedrock usage retains the one-hour cache-write subset from cacheDetails in Usage.LongCacheWriteInputTokens, so long-retention writes use the existing long-duration cost formula. Total cache writes and raw usage remain available; missing duration details do not infer a one-hour subset. Custom Converse clients can populate ConverseUsage.LongCacheWriteInputTokens directly.

OpenRouter Chat Completions

registry := sigma.NewRegistry()
_ = openrouter.Register(registry)

Environment: OPENROUTER_API_KEY.

OpenRouter text generation uses the shared OpenAI-compatible Chat Completions adapter with OpenRouter base URL defaults, generated model metadata, prompt cache markers, nested reasoning requests, and request-scoped routing options. For Anthropic-routed models, the final conversation cache marker advances to the latest non-empty tool result after a tool call; empty results are skipped, and the system-prompt and final tool-definition markers remain bounded.

OpenRouter Images

registry := sigma.NewRegistry()
_ = openrouter.RegisterImages(registry)

Environment: OPENROUTER_API_KEY.

OpenRouter image generation is non-streaming and uses image-capable Chat Completions responses. OpenAI Images uses the dedicated OpenAI Images adapter for generation, edits, variations, and streaming partial image events.

OpenCode Zen and Go

The OpenCode wrapper maps sigma.WithSessionID(conversationID) to x-opencode-session across Chat Completions, Responses, Anthropic Messages, and Google Generative AI routes. Use a stable ID within a conversation and a distinct ID for each new conversation. OpenCode Go requires this header for routing and prompt-cache affinity.

Session routing remains enabled when CacheRetentionNone is selected. Explicit provider, model, and request session headers keep their normal precedence, and WithSuppressedHeader can remove the final header. The wrapper does not generate IDs when callers omit WithSessionID.

Provider Options

Use root options for common behavior:

  • sigma.WithTimeout
  • sigma.WithMaxRetries
  • sigma.WithMaxRetryDelay
  • sigma.WithHeader and sigma.WithHeaders
  • sigma.WithSessionID
  • sigma.WithProviderOption and sigma.WithProviderOptions

Provider-specific helper functions are thin wrappers over ProviderOptions. Prefer helpers when they exist because they document the expected key names.

Current Coverage

The authoritative implementation status is the provider parity matrix. Do not assume a provider ID is runnable just because metadata exists.