sigma

package module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 28 Imported by: 0

README

sigma

sigma is a Go package for provider-neutral AI model calls. The stable release surface is text-first: one root API for model metadata, text streaming, completions, tools, request persistence, custom OpenAI-compatible endpoints, and deterministic tests. Other documented surfaces, including image generation and some provider adapters, are preview or future work until release notes say otherwise.

The module path is currently:

go get github.com/wintermi/sigma

The root package name is sigma. Version tags follow standard Major.Minor.Patch numbering, starting with v0.1.0. Any breaking changes before v1.0.0 should be documented in CHANGELOG.md, release notes, and upgrade guidance. This checkout is licensed under the MIT License.

Quick Start

The fastest path uses sigmatest, which is deterministic and makes no network calls:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/wintermi/sigma"
	"github.com/wintermi/sigma/sigmatest"
)

func main() {
	provider := sigmatest.NewFauxProvider(sigmatest.Script{
		Final: sigma.AssistantMessage{
			Content: []sigma.ContentBlock{
				sigma.Text("Sigma provides provider-neutral model calls for Go."),
			},
		},
	})
	registry, err := sigmatest.Registry(provider)
	if err != nil {
		log.Fatal(err)
	}

	client := sigma.NewClient(sigma.WithRegistry(registry))
	text, err := client.CompleteText(
		context.Background(),
		sigmatest.TextModel(),
		"Write one short sentence about Sigma.",
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(text)
}

For a real provider, register a provider package on the same registry as the model metadata and provide credentials through options, an auth resolver, or the documented environment variables:

package main

import (
	"context"
	"log"

	"github.com/wintermi/sigma"
	"github.com/wintermi/sigma/provider/openai"
)

func main() {
	registry := sigma.NewRegistry()
	if err := openai.Register(registry, sigma.ProviderOpenAI); err != nil {
		log.Fatal(err)
	}

	model := sigma.Model{
		ID:              "gpt-4o-mini",
		Provider:        sigma.ProviderOpenAI,
		API:             sigma.APIOpenAICompletions,
		SupportedInputs: []sigma.ContentBlockType{sigma.ContentBlockText},
		SupportsTools:   true,
	}
	if err := registry.RegisterModel(model); err != nil {
		log.Fatal(err)
	}

	client := sigma.NewClient(sigma.WithRegistry(registry))
	text, err := client.CompleteText(context.Background(), model, "Reply in one sentence.")
	if err != nil {
		log.Fatal(err)
	}
	log.Println(text)
}

The OpenAI example above can use OPENAI_API_KEY through EnvironmentAuthResolver, or sigma.WithAPIKey("...") for a request-scoped override. Tests should prefer sigmatest or httptest.Server; the repository test suite must not make live provider calls.

Streaming

Client.Stream returns a single-consumer *sigma.Stream. Read ordered events from Events, then inspect Err and Final, or call sigma.Collect when you only need the final assistant message.

stream := client.Stream(ctx, model, sigma.Request{
	Messages: []sigma.Message{sigma.UserText("Explain streaming briefly.")},
})
defer stream.Close()

for event := range stream.Events() {
	switch event.Kind {
	case sigma.EventKindTextDelta:
		fmt.Print(event.DeltaText)
	case sigma.EventKindToolCallDelta:
		// Tool-call JSON may arrive over multiple deltas.
	case sigma.EventKindDone, sigma.EventKindError:
		// Terminal events also carry the final assistant message.
	}
}
if err := stream.Err(); err != nil {
	log.Fatal(err)
}
final, ok := stream.Final()
_ = final
_ = ok

Text, thinking, and tool-call blocks can be interleaved. Use Event.ContentIndex when building UI or transcript state.

How Requests Flow

Client
  -> Registry lookup for Model and Provider
  -> Provider.Stream or ImageProvider.Generate
  -> Stream events
  -> AssistantMessage

For text calls, Complete is implemented by collecting the provider stream. For images, GenerateImages dispatches to a registered image provider and returns AssistantImages.

Documentation

  • Changelog tracks release-visible changes and known limitations.
  • Release notes summarize the latest closed tag scope and compatibility boundary.
  • Releasing documents the validation commands and pre-tag checklist used for every release.
  • TODO lists deferred work that is outside the current release scope.
  • Providers covers registration, credentials, environment variables, and caveats.
  • Streaming covers event handling and terminal messages.
  • Tools covers schemas, validation, and tool-result replay.
  • Images covers image input and image generation.
  • Reasoning covers thinking controls and streamed thinking blocks.
  • Errors covers typed errors, cancellation, retries, and redaction-safe diagnostics.
  • Routing decisions covers deterministic request classification, tiered model selection, and fallback advice.
  • Custom models covers local OpenAI-compatible models and routers.
  • Testing covers sigmatest, httptest, and live-test boundaries.
  • Request persistence covers JSON replay.
  • Inspired by @earendil-works/pi-ai maps familiar TypeScript concepts to Go.
  • Provider parity distinguishes implemented, partial, planned, unsupported, and preview provider features.
  • Security covers credential handling and diagnostic redaction.
  • Generated model metadata describes catalog refreshes.
  • Examples lists runnable examples.

Verification

mise run go:test
mise run go:race
mise run go:vet
mise run go:generate
git diff --exit-code

Run mise run ci for the full CI-equivalent suite (formatting, lint, vet, and the race-enabled test run). The repository includes a Markdown internal-link test and builds the examples as part of mise run go:test. External links and live provider calls are not checked by default so verification stays deterministic and does not require credentials.

Documentation

Overview

Package sigma provides provider-neutral model calls for Go applications.

The root package owns stable request, response, model, registry, stream, image, tool, reasoning, persistence, and error types. Provider-specific HTTP and cloud SDK behavior lives in provider subpackages, which register implementations on a Registry.

Clients use a clone of the package-level default registry unless configured with WithRegistry. The default registry is intended for ordinary application code that wants built-in metadata. Provider packages still need to be imported and registered before runtime dispatch. Use NewRegistry with WithRegistry when tests, local endpoints, or applications need isolated custom providers and models.

HTTP provider adapters share the root retry policy: no retries by default, optional per-request timeouts through context, retries for transient network failures, 429, and 5xx responses, and conservative streaming retries only before a response body is consumed.

Index

Examples

Constants

View Source 
const (
	// MetadataAPIKeyEnvVar names one API-key environment variable in model metadata.
	MetadataAPIKeyEnvVar = "apiKeyEnvVar"
	// MetadataAPIKeyEnvVars names ordered API-key environment variables in model metadata.
	MetadataAPIKeyEnvVars = "apiKeyEnvVars"
)
View Source 
const (
	// ImageInputText identifies text input for image APIs.
	ImageInputText = "text"
	// ImageInputImage identifies image input or output for image APIs.
	ImageInputImage = "image"
	// ImageSourceBase64 identifies inline base64 image data.
	ImageSourceBase64 = "base64"
	// ImageSourceURL identifies URL-backed image data.
	ImageSourceURL = "url"
	// ImageSourceFileID identifies an already-uploaded provider file reference.
	ImageSourceFileID = "file_id"
)
View Source 
const (
	// MetadataOpenAICompatible marks a model as caller-registered
	// OpenAI-compatible metadata that should be validated as runnable.
	MetadataOpenAICompatible = "openAICompatible"
	// MetadataOpenAICompatibleBaseURL stores the /v1-compatible endpoint for a
	// caller-registered OpenAI-compatible model.
	MetadataOpenAICompatibleBaseURL = "openAICompatibleBaseURL"
	// MetadataOpenAICompatibleHeaders stores model-scoped HTTP headers for a
	// caller-registered OpenAI-compatible model.
	MetadataOpenAICompatibleHeaders = "openAICompatibleHeaders"
)
View Source 
const (
	// DefaultMaxRetries is the default number of retries after the first HTTP
	// request attempt.
	DefaultMaxRetries = 0
	// DefaultRetryBaseDelay is the base delay used between retries when a
	// provider does not return Retry-After.
	DefaultRetryBaseDelay = 100 * time.Millisecond
	// DefaultMaxRetryDelay caps retry waits, including Retry-After.
	DefaultMaxRetryDelay = 2 * time.Second
)
View Source 
const (
	RouteDimensionReasoningMarkers   = "reasoningMarkers"
	RouteDimensionTechnicalTerms     = "technicalTerms"
	RouteDimensionSimpleIndicators   = "simpleIndicators"
	RouteDimensionCodePresence       = "codePresence"
	RouteDimensionMultiStepPatterns  = "multiStepPatterns"
	RouteDimensionQuestionComplexity = "questionComplexity"
	RouteDimensionTokenCount         = "tokenCount"
)

Classifier dimension names accepted by WithRouteWeight.

Variables

View Source 
var (
	// ErrEmbeddingVectorDimensionMismatch reports vectors with incompatible dimensions.
	ErrEmbeddingVectorDimensionMismatch = errors.New("embedding vector dimensions do not match")
	// ErrEmbeddingVectorZeroNorm reports a vector that cannot be normalized.
	ErrEmbeddingVectorZeroNorm = errors.New("embedding vector norm is zero")
	// ErrEmbeddingVectorWeightMismatch reports a weight list that does not match the vector list.
	ErrEmbeddingVectorWeightMismatch = errors.New("embedding vector weights do not match vectors")
	// ErrEmbeddingVectorZeroWeight reports a weighted operation with no effective weight.
	ErrEmbeddingVectorZeroWeight = errors.New("embedding vector weight sum is zero")
)
View Source 
var (
	// ErrNoProvider indicates no provider is registered for a model.
	ErrNoProvider = errors.New("provider unavailable")
	// ErrModelNotFound indicates no model metadata is registered for a model.
	ErrModelNotFound = errors.New("model not found")
	// ErrCredentialUnavailable indicates no resolver could provide credentials.
	ErrCredentialUnavailable = errors.New("credential unavailable")
	// ErrAborted indicates generation stopped because the request was canceled.
	ErrAborted = errors.New("generation aborted")
	// ErrContextOverflow indicates a request exceeded the provider context limit.
	ErrContextOverflow = errors.New("context overflow")
	// ErrToolValidation indicates a tool definition or tool call failed validation.
	ErrToolValidation = errors.New("tool validation failed")
	// ErrProviderResponse indicates the provider returned an error response.
	ErrProviderResponse = errors.New("provider response error")
	// ErrInvalidOptions indicates request options failed local validation.
	ErrInvalidOptions = errors.New("invalid options")
	// ErrRetryAfterExceedsMaxDelay indicates a provider asked for a retry
	// delay longer than the configured cap.
	ErrRetryAfterExceedsMaxDelay = errors.New("retry-after exceeds max retry delay")
)
View Source 
var ErrDebugHook = errors.New("debug hook failed")

ErrDebugHook indicates a caller-provided debug hook failed.

View Source 
var ErrNoRouteCandidates = errors.New("no route candidates")

ErrNoRouteCandidates reports that a routing policy has no usable candidate for the classified tier or any other tier.

Functions

func AccountUsage added in v0.6.0 

func AccountUsage(model Model, usage Usage, opts ...UsageAccountingOption) (Usage, Cost)

AccountUsage stamps usage with model identity, preserves raw provider usage, and calculates Sigma's estimated cost from model metadata.

func ApplySuppressedHeaders added in v0.6.0 

func ApplySuppressedHeaders(headers http.Header, opts Options)

ApplySuppressedHeaders removes request headers configured with WithSuppressedHeader or WithSuppressedHeaders.

func CleanupSessionResources added in v0.6.0 

func CleanupSessionResources(sessionID string) error

CleanupSessionResources releases registered provider-owned session resources. Passing an empty sessionID releases all registered session resources.

func CombineEmbeddingVectors added in v0.3.0 

func CombineEmbeddingVectors(vectors [][]float32, weights []int) ([]float32, error)

CombineEmbeddingVectors returns a normalized weighted average of embedding vectors.

func CompleteText 

func CompleteText(ctx context.Context, model Model, prompt string, opts ...Option) (string, error)

CompleteText is a text-only helper using the default registry.

It returns an error if the final assistant message contains non-text content, so tool calls and thinking blocks are not silently discarded.

func ContextWithRequestTimeout 

func ContextWithRequestTimeout(ctx context.Context, opts Options) (context.Context, context.CancelFunc)

ContextWithRequestTimeout applies Options.Timeout to ctx. The returned cancel function must be called when the provider request is complete.

func CosineSimilarity added in v0.3.0 

func CosineSimilarity(a, b []float32) (float64, error)

CosineSimilarity calculates cosine similarity for two embedding vectors.

func DoHTTPWithRetry 

func DoHTTPWithRetry(
	ctx context.Context,
	client *http.Client,
	opts Options,
	newRequest func(context.Context) (*http.Request, error),
	providerError func(*http.Response) *ProviderError,
	hooks ...HTTPResponseHook,
) (*http.Response, error)

DoHTTPWithRetry sends a request with sigma's shared HTTP retry policy.

The returned response body belongs to the caller and has not been consumed by the retry helper. Bodies from retry attempts are closed before the next request attempt.

func DotProduct added in v0.3.0 

func DotProduct(a, b []float32) (float64, error)

DotProduct calculates the dot product for two embedding vectors.

func EstimateContentTokens added in v0.6.0 

func EstimateContentTokens(blocks []ContentBlock) int

EstimateContentTokens returns a deterministic approximate token count for message content blocks.

func EstimateMessageTokens added in v0.6.0 

func EstimateMessageTokens(message Message) int

EstimateMessageTokens returns a deterministic approximate token count for a persisted message.

func EstimateTextTokens added in v0.6.0 

func EstimateTextTokens(text string) int

EstimateTextTokens returns a deterministic approximate token count for text.

func IsContextOverflow added in v0.5.0 

func IsContextOverflow(message AssistantMessage, contextWindow int) bool

IsContextOverflow reports whether a final assistant message indicates that a request exceeded the model context window.

Error messages are detected from safe provider diagnostics. Usage-based detection requires a positive contextWindow supplied by the caller.

func MarshalRequest 

func MarshalRequest(req Request) ([]byte, error)

MarshalRequest serializes req as the public Request JSON shape.

func MaxTokensForContext added in v0.6.0 

func MaxTokensForContext(model Model, req Request, requestedMaxTokens int) int

MaxTokensForContext returns an opt-in max output token cap for req and model.

requestedMaxTokens is used when positive, clamped to model.MaxOutputTokens when the catalog reports one; otherwise model.MaxOutputTokens is used. A zero return means no usable output cap was available. The helper uses EstimateRequestTokens and a fixed safety margin; it does not call provider tokenizers or affect dispatch unless the caller applies the returned value.

func NewImageStream added in v0.3.0 

func NewImageStream(ctx context.Context) (*ImageStream, ImageStreamWriter)

NewImageStream constructs an image stream and its provider-side writer.

func NewStream 

func NewStream(ctx context.Context) (*Stream, StreamWriter)

NewStream constructs a stream and its provider-side writer.

func NormalizeEmbeddingNewlines added in v0.3.0 

func NormalizeEmbeddingNewlines(inputs []string) []string

NormalizeEmbeddingNewlines returns a copy of inputs with newlines replaced by spaces.

func NormalizeEmbeddingVector added in v0.3.0 

func NormalizeEmbeddingVector(vector []float32) ([]float32, error)

NormalizeEmbeddingVector returns a unit-length copy of vector.

func ParseRetryAfter 

func ParseRetryAfter(value string, now time.Time) time.Duration

ParseRetryAfter parses Retry-After seconds or HTTP-date values relative to now.

func RegisterDefaultEmbeddingModel added in v0.3.0 

func RegisterDefaultEmbeddingModel(model EmbeddingModel, opts ...RegisterOption) error

RegisterDefaultEmbeddingModel registers an embedding model on the default registry.

func RegisterDefaultEmbeddingProvider added in v0.3.0 

func RegisterDefaultEmbeddingProvider(id ProviderID, provider EmbeddingProvider, opts ...RegisterOption) error

RegisterDefaultEmbeddingProvider registers an embedding provider on the default registry.

func RegisterDefaultImageModel 

func RegisterDefaultImageModel(model ImageModel, opts ...RegisterOption) error

RegisterDefaultImageModel registers an image model on the default registry.

func RegisterDefaultImageProvider 

func RegisterDefaultImageProvider(id ProviderID, provider ImageProvider, opts ...RegisterOption) error

RegisterDefaultImageProvider registers an image provider on the default registry.

func RegisterDefaultModel 

func RegisterDefaultModel(model Model, opts ...RegisterOption) error

RegisterDefaultModel registers a text model on the default registry.

func RegisterDefaultProviderAuth added in v0.6.0 

func RegisterDefaultProviderAuth(id ProviderID, auth ProviderAuth, opts ...RegisterOption) error

RegisterDefaultProviderAuth registers provider auth on the default registry.

func RegisterDefaultTextModelSource added in v0.7.0 

func RegisterDefaultTextModelSource(provider ProviderID, source TextModelSource, opts ...RegisterOption) error

RegisterDefaultTextModelSource registers a runtime text model source on the default registry.

func RegisterDefaultTextProvider 

func RegisterDefaultTextProvider(id ProviderID, provider TextProvider, opts ...RegisterOption) error

RegisterDefaultTextProvider registers a text provider on the default registry.

func RegisterEmbeddingModel added in v0.3.0 

func RegisterEmbeddingModel(registry *Registry, model EmbeddingModel, opts ...RegisterOption) error

RegisterEmbeddingModel registers embedding model metadata on registry.

func RegisterEmbeddingModelSource added in v0.6.0 

func RegisterEmbeddingModelSource(registry *Registry, provider ProviderID, source EmbeddingModelSource, opts ...RegisterOption) error

RegisterEmbeddingModelSource registers a runtime embedding model source on registry.

func RegisterImageModelSource added in v0.6.0 

func RegisterImageModelSource(registry *Registry, provider ProviderID, source ImageModelSource, opts ...RegisterOption) error

RegisterImageModelSource registers a runtime image model source on registry.

func RegisterModel 

func RegisterModel(registry *Registry, model Model, opts ...RegisterOption) error

RegisterModel registers text model metadata on registry.

func RegisterProvider 

func RegisterProvider(registry *Registry, id ProviderID, provider TextProvider, opts ...RegisterOption) error

RegisterProvider registers a text provider on registry.

func RegisterProviderAuth added in v0.6.0 

func RegisterProviderAuth(registry *Registry, provider ProviderID, auth ProviderAuth, opts ...RegisterOption) error

RegisterProviderAuth registers auth metadata on registry.

func RegisterSessionResourceCleanup added in v0.6.0 

func RegisterSessionResourceCleanup(cleanup SessionResourceCleanup) func()

RegisterSessionResourceCleanup registers cleanup for provider-owned session resources and returns a function that unregisters it.

func RegisterTextModelSource added in v0.6.0 

func RegisterTextModelSource(registry *Registry, provider ProviderID, source TextModelSource, opts ...RegisterOption) error

RegisterTextModelSource registers a runtime text model source on registry.

func ResolveAuthForRequest added in v0.6.0 

func ResolveAuthForRequest(ctx context.Context, model Model, opts Options) (Options, Credential, error)

ResolveAuthForRequest resolves request auth and returns options augmented with descriptor-provided provider configuration. Caller-supplied headers and provider options keep precedence over auth-derived values.

func RetryAfter 

func RetryAfter(header http.Header) time.Duration

RetryAfter returns the duration requested by a Retry-After header.

func RetryableNetworkError 

func RetryableNetworkError(err error) bool

RetryableNetworkError reports whether err represents a transient network failure that occurred before an HTTP response body was returned.

func RetryableStatusCode 

func RetryableStatusCode(status int) bool

RetryableStatusCode reports whether status is safe for pre-body-consumption HTTP retries.

func RunEmbeddingPayloadDebugHooks added in v0.3.0 

func RunEmbeddingPayloadDebugHooks(ctx context.Context, opts Options, provider ProviderID, api EmbeddingAPI, model ModelID, payload []byte, headers http.Header) error

RunEmbeddingPayloadDebugHooks runs embedding payload hooks with redacted copies.

func RunImagePayloadDebugHooks 

func RunImagePayloadDebugHooks(ctx context.Context, opts Options, provider ProviderID, api ImageAPI, model ModelID, payload []byte, headers http.Header) error

RunImagePayloadDebugHooks runs image payload hooks with redacted copies.

func RunTextPayloadDebugHooks 

func RunTextPayloadDebugHooks(ctx context.Context, opts Options, provider ProviderID, api API, model ModelID, payload []byte, headers http.Header) error

RunTextPayloadDebugHooks runs text payload hooks with redacted copies.

func ToolErrorMessage 

func ToolErrorMessage(call ToolCall, err error) string

ToolErrorMessage converts a tool validation failure into text suitable for a ToolError result, so the model can retry with corrected arguments.

func ValidateModelRef 

func ValidateModelRef(ref ModelRef) error

ValidateModelRef validates the minimum fields needed to identify a model.

func ValidateRequest 

func ValidateRequest(req Request) error

ValidateRequest checks that req is structurally safe to persist and replay.

func ValidateToolCall 

func ValidateToolCall(tools []Tool, call ToolCall) (map[string]any, error)

ValidateToolCall validates a model-emitted tool call against the matching tool's JSON Schema-compatible InputSchema. It returns a decoded copy of the arguments on success and never mutates the supplied tool schema or call arguments.

func ValidateToolCallWithOptions added in v0.6.0 

func ValidateToolCallWithOptions(tools []Tool, call ToolCall, options ToolValidationOptions) (map[string]any, error)

ValidateToolCallWithOptions validates a model-emitted tool call against the matching tool's JSON Schema-compatible InputSchema. It returns a decoded copy of the arguments on success and never mutates the supplied tool schema or call arguments.

Types

type API 

type API string

API identifies a chat or text generation provider API surface. 

const (
	// APIOpenAICompletions identifies the OpenAI chat completions API.
	APIOpenAICompletions API = "openai-completions"
	// APIOpenAIResponses identifies the OpenAI responses API.
	APIOpenAIResponses API = "openai-responses"
	// APIAzureOpenAIResponses identifies the Azure OpenAI responses API.
	APIAzureOpenAIResponses API = "azure-openai-responses"
	// APIOpenAICodexResponses identifies the OpenAI Codex responses API.
	APIOpenAICodexResponses API = "openai-codex-responses"
	// APIAnthropicMessages identifies the Anthropic messages API.
	APIAnthropicMessages API = "anthropic-messages"
	// APIBedrockConverseStream identifies the Amazon Bedrock converse stream API.
	APIBedrockConverseStream API = "bedrock-converse-stream"
	// APIGoogleGenerativeAI identifies the Google Generative AI API.
	APIGoogleGenerativeAI API = "google-generative-ai"
	// APIGoogleVertex identifies the Google Vertex AI API.
	APIGoogleVertex API = "google-vertex"
	// APIMistralConversations identifies the Mistral conversations API.
	APIMistralConversations API = "mistral-conversations"
	// APIRadiusMessages identifies the Radius gateway messages API.
	APIRadiusMessages API = "radius-messages"
)

type APIKeyAuth added in v0.6.0 

type APIKeyAuth struct {
	Name    string
	EnvVars []string
	Resolve APIKeyAuthResolver
}

APIKeyAuth describes stored API-key and environment fallback auth.

func EnvironmentAPIKeyAuth added in v0.6.0 

func EnvironmentAPIKeyAuth(name string, envVars ...string) *APIKeyAuth

EnvironmentAPIKeyAuth constructs API-key auth that prefers a stored key and falls back to ordered environment variables.

type APIKeyAuthResolver added in v0.6.0 

type APIKeyAuthResolver func(context.Context, Model, Options, StoredCredential, bool) (AuthResolution, bool, error)

APIKeyAuthResolver resolves API-key auth, optionally using a stored credential.

type AnthropicCompatSupport added in v0.2.0 

type AnthropicCompatSupport string

AnthropicCompatSupport identifies whether an Anthropic Messages-compatible feature is known to be supported by a provider or endpoint. 

const (
	// AnthropicCompatDefault uses provider and endpoint defaults.
	AnthropicCompatDefault AnthropicCompatSupport = ""
	// AnthropicCompatSupported forces a compatibility feature on.
	AnthropicCompatSupported AnthropicCompatSupport = "supported"
	// AnthropicCompatUnsupported forces a compatibility feature off.
	AnthropicCompatUnsupported AnthropicCompatSupport = "unsupported"
)

type AnthropicMessagesCompat added in v0.2.0 

type AnthropicMessagesCompat struct {
	SupportsEagerToolInputStreaming AnthropicCompatSupport  `json:"supportsEagerToolInputStreaming,omitempty"`
	SupportsLongCacheRetention      AnthropicCompatSupport  `json:"supportsLongCacheRetention,omitempty"`
	SupportsSessionAffinity         AnthropicCompatSupport  `json:"supportsSessionAffinity,omitempty"`
	SupportsCacheControlOnTools     AnthropicCompatSupport  `json:"supportsCacheControlOnTools,omitempty"`
	SupportsEmptyThinkingSignature  AnthropicCompatSupport  `json:"supportsEmptyThinkingSignature,omitempty"`
	SupportsTemperature             AnthropicCompatSupport  `json:"supportsTemperature,omitempty"`
	SupportsDisabledThinking        AnthropicCompatSupport  `json:"supportsDisabledThinking,omitempty"`
	SupportsToolReferences          AnthropicCompatSupport  `json:"supportsToolReferences,omitempty"`
	ThinkingFormat                  AnthropicThinkingFormat `json:"thinkingFormat,omitempty"`
}

AnthropicMessagesCompat describes Messages compatibility differences for Anthropic-compatible routers and custom endpoints. Leave fields at their zero value to use provider or base-URL detection.

type AnthropicOptions 

type AnthropicOptions struct {
	ThinkingBudgetTokens   *int
	ToolChoice             *AnthropicToolChoice
	ThinkingDisplay        AnthropicThinkingDisplay
	InterleavedThinking    *bool
	OutputFormat           any
	DisableParallelToolUse *bool
}

AnthropicOptions carries Anthropic-specific request options known to the root package without importing provider adapters.

type AnthropicThinkingDisplay added in v0.4.0 

type AnthropicThinkingDisplay string

AnthropicThinkingDisplay controls how Claude thinking content is returned when the model supports the display field. 

const (
	// AnthropicThinkingDisplaySummarized requests summarized thinking text.
	AnthropicThinkingDisplaySummarized AnthropicThinkingDisplay = "summarized"
	// AnthropicThinkingDisplayOmitted asks Anthropic to omit thinking text while
	// preserving signatures for replay.
	AnthropicThinkingDisplayOmitted AnthropicThinkingDisplay = "omitted"
)

type AnthropicThinkingFormat added in v0.2.0 

type AnthropicThinkingFormat string

AnthropicThinkingFormat identifies how Anthropic Messages thinking is encoded by a provider or endpoint. 

const (
	// AnthropicThinkingDefault uses provider and endpoint defaults.
	AnthropicThinkingDefault AnthropicThinkingFormat = ""
	// AnthropicThinkingBudget sends budget-token thinking controls.
	AnthropicThinkingBudget AnthropicThinkingFormat = "budget"
	// AnthropicThinkingAdaptive sends adaptive thinking plus output_config effort.
	AnthropicThinkingAdaptive AnthropicThinkingFormat = "adaptive"
)

type AnthropicToolChoice added in v0.4.0 

type AnthropicToolChoice struct {
	Type AnthropicToolChoiceType `json:"type"`
	Name string                  `json:"name,omitempty"`
}

AnthropicToolChoice carries Anthropic Messages tool choice controls.

type AnthropicToolChoiceType added in v0.4.0 

type AnthropicToolChoiceType string

AnthropicToolChoiceType identifies Anthropic Messages tool selection behavior. 

const (
	// AnthropicToolChoiceAuto lets Anthropic choose whether to call a tool.
	AnthropicToolChoiceAuto AnthropicToolChoiceType = "auto"
	// AnthropicToolChoiceAny requires Anthropic to call one of the supplied tools.
	AnthropicToolChoiceAny AnthropicToolChoiceType = "any"
	// AnthropicToolChoiceNone prevents Anthropic from calling tools.
	AnthropicToolChoiceNone AnthropicToolChoiceType = "none"
	// AnthropicToolChoiceTool requires Anthropic to call the named tool.
	AnthropicToolChoiceTool AnthropicToolChoiceType = "tool"
)

type AssistantImages 

type AssistantImages struct {
	Images           []ImageInput   `json:"images,omitempty"`
	ResponseID       string         `json:"responseId,omitempty"`
	StopReason       StopReason     `json:"stopReason,omitempty"`
	Errors           []ImageError   `json:"errors,omitempty"`
	Usage            *Usage         `json:"usage,omitempty"`
	Cost             *Cost          `json:"cost,omitempty"`
	Model            ModelID        `json:"model,omitempty"`
	Provider         ProviderID     `json:"provider,omitempty"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

AssistantImages is provider-neutral image output plus generation metadata.

func CollectImages added in v0.3.0 

func CollectImages(ctx context.Context, stream *ImageStream) (AssistantImages, error)

CollectImages consumes stream until it receives a terminal event or ctx is canceled.

func GenerateImages 

func GenerateImages(ctx context.Context, model ImageModel, req ImageRequest, opts ...ImageOption) (AssistantImages, error)

GenerateImages calls the registered image provider using the default registry.

type AssistantMessage 

type AssistantMessage struct {
	Content          []ContentBlock `json:"content,omitempty"`
	StopReason       StopReason     `json:"stopReason,omitempty"`
	Usage            *Usage         `json:"usage,omitempty"`
	Cost             *Cost          `json:"cost,omitempty"`
	Model            ModelID        `json:"model,omitempty"`
	Provider         ProviderID     `json:"provider,omitempty"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
	Diagnostics      []Diagnostic   `json:"diagnostics,omitempty"`
}

AssistantMessage is provider-neutral assistant output plus turn metadata.

func Collect 

func Collect(ctx context.Context, stream *Stream) (AssistantMessage, error)

Collect consumes stream until it receives a terminal event or ctx is canceled.

func Complete 

func Complete(ctx context.Context, model Model, req Request, opts ...Option) (AssistantMessage, error)

Complete collects a provider stream using the default registry.

func (AssistantMessage) Citations added in v0.6.0 

func (m AssistantMessage) Citations() []ResultCitation

Citations returns normalized citations attached to all assistant content blocks, preserving content order.

func (AssistantMessage) ResponseID added in v0.6.0 

func (m AssistantMessage) ResponseID() string

ResponseID returns the provider response identifier reported on the assistant message, when one is available.

func (AssistantMessage) ResponseModel added in v0.6.0 

func (m AssistantMessage) ResponseModel() ModelID

ResponseModel returns the concrete provider-routed response model reported on the assistant message, when it differs from the requested model and is available.

func (AssistantMessage) Sources added in v0.6.0 

func (m AssistantMessage) Sources() []ResultSource

Sources returns normalized source entries reported on the assistant message.

type AuthResolution added in v0.6.0 

type AuthResolution struct {
	Credential      Credential
	ProviderEnv     map[string]string
	BaseURL         string
	Headers         map[string]string
	ProviderOptions map[string]any
	Source          string
}

AuthResolution is provider auth resolved for one model request.

func ResolveAuthResolution added in v0.6.0 

func ResolveAuthResolution(ctx context.Context, model Model, opts Options) (AuthResolution, error)

ResolveAuthResolution resolves request auth through opts.AuthResolver.

func ResolveProviderAuth added in v0.6.0 

func ResolveProviderAuth(ctx context.Context, model Model, opts Options, auth ProviderAuth, store CredentialStore) (AuthResolution, bool, error)

ResolveProviderAuth resolves auth using a descriptor and optional store.

type AuthResolutionResolver added in v0.6.0 

type AuthResolutionResolver interface {
	ResolveAuthResolution(context.Context, Model, Options) (AuthResolution, error)
}

AuthResolutionResolver resolves provider credentials plus provider-scoped request configuration for a request.

type AuthResolver 

type AuthResolver interface {
	Resolve(context.Context, Model, Options) (Credential, error)
}

AuthResolver resolves provider credentials for a request.

type AuthResolverFunc 

type AuthResolverFunc func(context.Context, Model, Options) (Credential, error)

AuthResolverFunc adapts a function into an AuthResolver.

func (AuthResolverFunc) Resolve 

func (f AuthResolverFunc) Resolve(ctx context.Context, model Model, opts Options) (Credential, error)

Resolve calls f.

type AzureOpenAIResponsesConfig 

type AzureOpenAIResponsesConfig struct {
	Endpoint         string `json:"endpoint,omitempty"`
	Deployment       string `json:"deployment,omitempty"`
	APIVersion       string `json:"apiVersion,omitempty"`
	APIKeyEnvVar     string `json:"apiKeyEnvVar,omitempty"`
	CredentialSource string `json:"credentialSource,omitempty"`
}

AzureOpenAIResponsesConfig carries Azure-specific model metadata for the Responses API. Endpoint is the Azure OpenAI resource endpoint, Deployment is the deployment name sent as the Responses model, APIVersion is the api-version query parameter, APIKeyEnvVar optionally overrides the default AZURE_OPENAI_API_KEY lookup, and CredentialSource may be "api-key" or "token" when callers need to document the intended auth path.

type BedrockOptions added in v0.2.0 

type BedrockOptions struct {
	ToolChoice                        *BedrockToolChoice
	BearerToken                       string
	ThinkingDisplay                   BedrockThinkingDisplay
	InterleavedThinking               *bool
	StopSequences                     []string
	TopP                              *float64
	ResponseFormat                    any
	RequestMetadata                   map[string]string
	AdditionalModelRequestFields      map[string]any
	AdditionalModelResponseFieldPaths []string
}

BedrockOptions carries Bedrock-specific request options known to the root package without importing the provider adapter.

type BedrockThinkingDisplay added in v0.2.0 

type BedrockThinkingDisplay string

BedrockThinkingDisplay controls how Claude thinking content is returned by Bedrock when the model supports the display field. 

const (
	// BedrockThinkingDisplaySummarized requests summarized thinking text.
	BedrockThinkingDisplaySummarized BedrockThinkingDisplay = "summarized"
	// BedrockThinkingDisplayOmitted asks Bedrock to omit thinking text while
	// preserving signatures for replay.
	BedrockThinkingDisplayOmitted BedrockThinkingDisplay = "omitted"
)

type BedrockToolChoice added in v0.2.0 

type BedrockToolChoice struct {
	Type BedrockToolChoiceType `json:"type"`
	Name string                `json:"name,omitempty"`
}

BedrockToolChoice carries Bedrock Converse tool choice controls.

type BedrockToolChoiceType added in v0.2.0 

type BedrockToolChoiceType string

BedrockToolChoiceType identifies Bedrock Converse tool selection behavior. 

const (
	// BedrockToolChoiceAuto lets Bedrock choose whether to call a tool.
	BedrockToolChoiceAuto BedrockToolChoiceType = "auto"
	// BedrockToolChoiceAny requires Bedrock to call one of the supplied tools.
	BedrockToolChoiceAny BedrockToolChoiceType = "any"
	// BedrockToolChoiceNone omits tools from the Bedrock request.
	BedrockToolChoiceNone BedrockToolChoiceType = "none"
	// BedrockToolChoiceTool requires Bedrock to call the named tool.
	BedrockToolChoiceTool BedrockToolChoiceType = "tool"
)

type CacheRetention 

type CacheRetention string

CacheRetention identifies how long provider-side prompt cache entries may live. 

const (
	// CacheRetentionNone disables provider-side prompt caching.
	CacheRetentionNone CacheRetention = "none"
	// CacheRetentionShort identifies provider cache entries kept briefly.
	CacheRetentionShort CacheRetention = "short"
	// CacheRetentionLong identifies provider cache entries kept beyond a single request.
	CacheRetentionLong CacheRetention = "long"
	// CacheRetentionEphemeral identifies provider cache entries kept briefly.
	CacheRetentionEphemeral CacheRetention = "ephemeral"
	// CacheRetentionPersistent identifies provider cache entries kept beyond a single request.
	CacheRetentionPersistent CacheRetention = "persistent"
)

func (CacheRetention) CacheEnabled 

func (retention CacheRetention) CacheEnabled() bool

CacheEnabled reports whether this retention requests provider-side prompt caching. Empty retention and CacheRetentionNone both mean no cache.

func (CacheRetention) CacheLongLived 

func (retention CacheRetention) CacheLongLived() bool

CacheLongLived reports whether this retention asks for a long-lived prompt cache entry.

func (CacheRetention) CacheShortLived 

func (retention CacheRetention) CacheShortLived() bool

CacheShortLived reports whether this retention asks for a short-lived prompt cache entry.

type CachedTextModelSource added in v0.7.0 

type CachedTextModelSource interface {
	TextModelSource
	CachedTextModels(context.Context) ([]Model, error)
}

CachedTextModelSource restores text models that a source previously stored outside the registry.

Cached models are applied through the same validation and source-ownership rules as refreshed models.

type ChainAuthResolver 

type ChainAuthResolver struct {
	Client                   AuthResolver
	Environment              AuthResolver
	ProviderCallbacks        map[ProviderID]AuthResolver
	DefaultProviderCallbacks map[ProviderID]AuthResolver
}

ChainAuthResolver resolves credentials through sigma's standard precedence.

ProviderCallbacks holds request-scoped provider callbacks and takes precedence over the client resolver. DefaultProviderCallbacks holds callbacks installed as client or model defaults; they resolve after the client resolver and environment, preserving their pre-request-scoped position so an explicit client resolver keeps winning over ambient defaults.

func (ChainAuthResolver) Resolve 

func (r ChainAuthResolver) Resolve(ctx context.Context, model Model, opts Options) (Credential, error)

Resolve checks request overrides, request-scoped provider callbacks, the client resolver, environment, then default provider callbacks.

func (ChainAuthResolver) ResolveAuthResolution added in v0.6.0 

func (r ChainAuthResolver) ResolveAuthResolution(ctx context.Context, model Model, opts Options) (AuthResolution, error)

ResolveAuthResolution checks request overrides, request-scoped provider callbacks, the client resolver, environment, then default provider callbacks.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client coordinates model lookup and generation requests.

func New 

func New(opts ...ClientOption) *Client

New constructs a Client.

func NewClient 

func NewClient(opts ...ClientOption) *Client

NewClient constructs a Client.

func (*Client) Complete 

func (c *Client) Complete(ctx context.Context, model Model, req Request, opts ...Option) (AssistantMessage, error)

Complete collects a provider stream into a final assistant message.

func (*Client) CompleteText 

func (c *Client) CompleteText(ctx context.Context, model Model, prompt string, opts ...Option) (string, error)

CompleteText is a text-only helper for simple prompt/response workflows.

It returns an error if the final assistant message contains non-text content, so tool calls and thinking blocks are not silently discarded.

func (*Client) Embed added in v0.3.0 

func (c *Client) Embed(ctx context.Context, model EmbeddingModel, req EmbeddingRequest, opts ...EmbeddingOption) (Embeddings, error)

Embed calls the registered embedding provider for model.

func (*Client) EmbedBatch added in v0.3.0 

func (c *Client) EmbedBatch(ctx context.Context, model EmbeddingModel, req EmbeddingRequest, config EmbeddingBatchConfig, opts ...EmbeddingOption) (EmbeddingBatchResult, error)

EmbedBatch embeds req.Inputs with duplicate reuse and retry-aware batch splitting.

func (*Client) EmbeddingModels added in v0.3.0 

func (c *Client) EmbeddingModels() []EmbeddingModel

EmbeddingModels returns embedding models from the client registry.

func (*Client) GenerateImages 

func (c *Client) GenerateImages(ctx context.Context, model ImageModel, req ImageRequest, opts ...ImageOption) (AssistantImages, error)

GenerateImages calls the registered image provider for model.

func (*Client) GetEmbeddingModel added in v0.3.0 

func (c *Client) GetEmbeddingModel(provider ProviderID, id ModelID) (EmbeddingModel, bool)

GetEmbeddingModel returns an embedding model by provider and model id.

func (*Client) GetImageModel 

func (c *Client) GetImageModel(provider ProviderID, id ModelID) (ImageModel, bool)

GetImageModel returns an image model by provider and model id.

func (*Client) GetModel 

func (c *Client) GetModel(provider ProviderID, id ModelID) (Model, bool)

GetModel returns a text model by provider and model id.

func (*Client) ImageModels 

func (c *Client) ImageModels() []ImageModel

ImageModels returns image models from the client registry.

func (*Client) Models 

func (c *Client) Models(filters ...ModelFilter) []Model

Models returns text models matching all filters.

func (*Client) RefreshEmbeddingModels added in v0.6.0 

func (c *Client) RefreshEmbeddingModels(ctx context.Context, providers ...ProviderID) error

RefreshEmbeddingModels refreshes runtime embedding model sources on the client's registry.

func (*Client) RefreshImageModels added in v0.6.0 

func (c *Client) RefreshImageModels(ctx context.Context, providers ...ProviderID) error

RefreshImageModels refreshes runtime image model sources on the client's registry.

func (*Client) RefreshTextModels added in v0.6.0 

func (c *Client) RefreshTextModels(ctx context.Context, providers ...ProviderID) error

RefreshTextModels refreshes runtime text model sources on the client's registry.

func (*Client) Registry 

func (c *Client) Registry() *Registry

Registry returns the client's registry.

func (*Client) RestoreTextModels added in v0.7.0 

func (c *Client) RestoreTextModels(ctx context.Context, providers ...ProviderID) error

RestoreTextModels restores cached runtime text models on the client's registry.

func (*Client) Stream 

func (c *Client) Stream(ctx context.Context, model Model, req Request, opts ...Option) *Stream

Stream starts a provider stream for model.

func (*Client) StreamImages added in v0.3.0 

func (c *Client) StreamImages(ctx context.Context, model ImageModel, req ImageRequest, opts ...ImageOption) *ImageStream

StreamImages starts a streaming image provider call for model.

type ClientEmbeddingEmbedder added in v0.3.0 

type ClientEmbeddingEmbedder struct {
	// contains filtered or unexported fields
}

ClientEmbeddingEmbedder adapts a Client and EmbeddingModel to the EmbeddingEmbedder interface.

func NewEmbeddingEmbedder added in v0.3.0 

func NewEmbeddingEmbedder(client *Client, model EmbeddingModel, config EmbeddingEmbedderConfig, opts ...EmbeddingOption) *ClientEmbeddingEmbedder

NewEmbeddingEmbedder wraps client and model with query/document embedding helpers.

func (*ClientEmbeddingEmbedder) EmbedDocuments added in v0.3.0 

func (e *ClientEmbeddingEmbedder) EmbedDocuments(ctx context.Context, texts []string) ([][]float32, error)

EmbedDocuments embeds texts as document inputs.

func (*ClientEmbeddingEmbedder) EmbedQuery added in v0.3.0 

func (e *ClientEmbeddingEmbedder) EmbedQuery(ctx context.Context, text string) ([]float32, error)

EmbedQuery embeds text as a query input and returns its vector.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures a Client.

func WithAuthResolver 

func WithAuthResolver(resolver AuthResolver) ClientOption

WithAuthResolver configures the credential resolver exposed to providers.

func WithCredentialStore added in v0.6.0 

func WithCredentialStore(store CredentialStore) ClientOption

WithCredentialStore configures stored credentials for opt-in provider auth.

The store is inert unless WithStoredProviderAuth is also configured.

func WithDefaultHeader 

func WithDefaultHeader(key, value string) ClientOption

WithDefaultHeader configures a default request header.

func WithDefaultHeaders 

func WithDefaultHeaders(headers map[string]string) ClientOption

WithDefaultHeaders configures default request headers.

func WithDefaultOptions 

func WithDefaultOptions(opts ...Option) ClientOption

WithDefaultOptions configures default provider request options.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient configures the HTTP client exposed to providers.

func WithRegistry 

func WithRegistry(registry *Registry) ClientOption

WithRegistry configures the client to use a registry.

func WithStoredProviderAuth added in v0.6.0 

func WithStoredProviderAuth() ClientOption

WithStoredProviderAuth enables store-backed provider auth resolution.

type CloudCredentialProvider 

type CloudCredentialProvider interface {
	Credential(context.Context, Model, Options) (Credential, error)
}

CloudCredentialProvider provides cloud credential material for a provider adapter.

type ContentBlock 

type ContentBlock struct {
	Type              ContentBlockType `json:"type"`
	Text              string           `json:"text,omitempty"`
	ThinkingText      string           `json:"thinking,omitempty"`
	Signature         string           `json:"signature,omitempty"`
	Redacted          bool             `json:"redacted,omitempty"`
	MIMEType          string           `json:"mimeType,omitempty"`
	ImageSource       string           `json:"imageSource,omitempty"`
	DocumentSource    string           `json:"documentSource,omitempty"`
	Filename          string           `json:"filename,omitempty"`
	FileID            string           `json:"fileID,omitempty"`
	Data              string           `json:"data,omitempty"`
	URL               string           `json:"url,omitempty"`
	ToolCallID        string           `json:"toolCallID,omitempty"`
	ToolName          string           `json:"toolName,omitempty"`
	ToolArguments     any              `json:"toolArguments,omitempty"`
	ProviderSignature string           `json:"providerSignature,omitempty"`
	ProviderMetadata  map[string]any   `json:"providerMetadata,omitempty"`
	ExtraFields       map[string]any   `json:"-"`
}

ContentBlock is a discriminated unit of message content.

Text blocks use Text. Thinking blocks use ThinkingText plus optional Signature, Redacted, and ProviderSignature. Image blocks use MIMEType, ImageSource, Data, and URL. Document blocks use MIMEType, DocumentSource, Filename, Data, URL, and FileID. Tool-call blocks use ToolCallID, ToolName, and ToolArguments. ProviderMetadata carries opaque provider fields for later replay without requiring provider-specific conversion in this package.

func DocumentBase64 added in v0.6.0 

func DocumentBase64(mimeType string, filename string, data string) ContentBlock

DocumentBase64 constructs a document content block backed by base64 data.

func DocumentFileID added in v0.6.0 

func DocumentFileID(mimeType string, filename string, fileID string) ContentBlock

DocumentFileID constructs a document content block backed by a provider file ID.

func DocumentURL added in v0.6.0 

func DocumentURL(mimeType string, filename string, url string) ContentBlock

DocumentURL constructs a document content block backed by a URL.

func ImageBase64 

func ImageBase64(mimeType string, data string) ContentBlock

ImageBase64 constructs an image content block backed by base64 data.

func ImageURL 

func ImageURL(mimeType string, url string) ContentBlock

ImageURL constructs an image content block backed by a URL.

func Text 

func Text(text string) ContentBlock

Text constructs a text content block.

func Thinking 

func Thinking(text string, signature string) ContentBlock

Thinking constructs a thinking content block.

func ToolCallBlock 

func ToolCallBlock(id string, name string, arguments any) ContentBlock

ToolCallBlock constructs an assistant tool-call content block.

func (ContentBlock) Citations added in v0.6.0 

func (b ContentBlock) Citations() []ResultCitation

Citations returns normalized citations attached to this content block.

func (ContentBlock) Clone added in v0.6.0 

func (b ContentBlock) Clone() ContentBlock

Clone returns a deep copy of the block: mutating the copy's tool arguments, provider metadata, or extra fields does not affect the original. New reference-typed fields added to ContentBlock must be cloned here so every package copying blocks picks up the change.

func (ContentBlock) MarshalJSON added in v0.6.0 

func (b ContentBlock) MarshalJSON() ([]byte, error)

func (*ContentBlock) UnmarshalJSON added in v0.6.0 

func (b *ContentBlock) UnmarshalJSON(data []byte) error

type ContentBlockType 

type ContentBlockType string

ContentBlockType identifies the shape of a message content block. 

const (
	// ContentBlockText identifies a text content block.
	ContentBlockText ContentBlockType = "text"
	// ContentBlockThinking identifies a thinking content block.
	ContentBlockThinking ContentBlockType = "thinking"
	// ContentBlockImage identifies an image content block.
	ContentBlockImage ContentBlockType = "image"
	// ContentBlockDocument identifies a document content block.
	ContentBlockDocument ContentBlockType = "document"
	// ContentBlockToolCall identifies a tool-call content block.
	ContentBlockToolCall ContentBlockType = "tool-call"
)

type Cost 

type Cost struct {
	InputCost                float64  `json:"inputCost,omitempty"`
	OutputCost               float64  `json:"outputCost,omitempty"`
	CacheReadInputCost       float64  `json:"cacheReadInputCost,omitempty"`
	CacheWriteInputCost      float64  `json:"cacheWriteInputCost,omitempty"`
	TotalCost                float64  `json:"totalCost,omitempty"`
	Currency                 string   `json:"currency,omitempty"`
	ProviderReportedCost     *float64 `json:"providerReportedCost,omitempty"`
	ProviderReportedCurrency string   `json:"providerReportedCurrency,omitempty"`
}

Cost records estimated and provider-reported cost accounting for a model turn.

The component costs and TotalCost are Sigma estimates calculated from model pricing metadata. ProviderReportedCost is only populated when the provider returns an explicit numeric cost.

func CostForEmbeddingUsage added in v0.3.0 

func CostForEmbeddingUsage(model EmbeddingModel, usage Usage) Cost

CostForEmbeddingUsage calculates deterministic embedding request cost from model rates.

func CostForUsage 

func CostForUsage(model Model, usage Usage) Cost

CostForUsage calculates deterministic per-turn cost from model rates.

Model cost rates are expressed as currency units per one million tokens. CostCurrency records the rate currency; when empty, USD is assumed. The helper does not round so callers can choose their own display precision.

type Credential 

type Credential struct {
	Type     CredentialType
	Value    string
	Expiry   time.Time
	Source   string
	Metadata map[string]any
}

Credential carries authentication material for a provider.

func (Credential) Format 

func (c Credential) Format(state fmt.State, verb rune)

Format prevents fmt from printing Credential.Value with struct formatting verbs.

func (Credential) String 

func (c Credential) String() string

String returns a diagnostic-safe credential description.

type CredentialModifyFunc added in v0.6.0 

type CredentialModifyFunc func(current StoredCredential, ok bool) (next StoredCredential, nextOK bool, err error)

CredentialModifyFunc receives the current stored credential. Return ok=false to leave the existing credential unchanged.

type CredentialStore added in v0.6.0 

type CredentialStore interface {
	ReadCredential(context.Context, ProviderID) (StoredCredential, bool, error)
	ModifyCredential(context.Context, ProviderID, CredentialModifyFunc) (StoredCredential, bool, error)
	DeleteCredential(context.Context, ProviderID) error
}

CredentialStore stores one credential per provider.

type CredentialType 

type CredentialType string

CredentialType identifies the kind of authentication material. 

const (
	// CredentialTypeAPIKey identifies a static API key.
	CredentialTypeAPIKey CredentialType = "api-key"
	// CredentialTypeOAuthToken identifies a bearer token from an OAuth provider.
	CredentialTypeOAuthToken CredentialType = "oauth-token"
	// CredentialTypeCloudCredential identifies cloud provider credential material.
	CredentialTypeCloudCredential CredentialType = "cloud-credential"
)

type CredentialUnavailableError 

type CredentialUnavailableError struct {
	Provider ProviderID
	Model    ModelID
	Sources  []string
}

CredentialUnavailableError reports a failed credential lookup without secrets.

func (*CredentialUnavailableError) Error 

func (e *CredentialUnavailableError) Error() string

Error returns diagnostic-safe source information.

func (*CredentialUnavailableError) Is 

func (e *CredentialUnavailableError) Is(target error) bool

Is supports errors.Is(err, ErrCredentialUnavailable).

type Diagnostic 

type Diagnostic struct {
	Kind                string     `json:"kind,omitempty"`
	Message             string     `json:"message,omitempty"`
	Provider            ProviderID `json:"provider,omitempty"`
	API                 API        `json:"api,omitempty"`
	Model               ModelID    `json:"model,omitempty"`
	StatusCode          int        `json:"statusCode,omitempty"`
	RequestID           string     `json:"requestID,omitempty"`
	ProviderCode        string     `json:"providerCode,omitempty"`
	ProviderMessage     string     `json:"providerMessage,omitempty"`
	RetryAfterMillis    int64      `json:"retryAfterMillis,omitempty"`
	MaxRetryDelayMillis int64      `json:"maxRetryDelayMillis,omitempty"`
	BodyPreview         string     `json:"bodyPreview,omitempty"`
	UnderlyingMessage   string     `json:"underlyingMessage,omitempty"`
}

Diagnostic is safe-to-log provider/runtime context that may be attached to an AssistantMessage. It must contain metadata and redacted previews only, never raw request or response payloads.

type Embedding added in v0.3.0 

type Embedding struct {
	Index  int       `json:"index"`
	Vector []float32 `json:"vector,omitempty"`
}

Embedding is one provider-neutral embedding vector.

type EmbeddingAPI added in v0.3.0 

type EmbeddingAPI string

EmbeddingAPI identifies a vector embedding provider API surface. 

const (
	// EmbeddingAPIOpenAIEmbeddings identifies OpenAI's embeddings API.
	EmbeddingAPIOpenAIEmbeddings EmbeddingAPI = "openai-embeddings"
	// EmbeddingAPIGoogleEmbeddings identifies Google's Gemini embeddings API.
	EmbeddingAPIGoogleEmbeddings EmbeddingAPI = "google-embeddings"
	// EmbeddingAPIGoogleVertexEmbeddings identifies Google's Vertex AI embeddings API.
	EmbeddingAPIGoogleVertexEmbeddings EmbeddingAPI = "google-vertex-embeddings"
	// EmbeddingAPIBedrockEmbeddings identifies Amazon Bedrock's InvokeModel embeddings API.
	EmbeddingAPIBedrockEmbeddings EmbeddingAPI = "bedrock-embeddings"
)

type EmbeddingAttempt added in v0.3.0 

type EmbeddingAttempt struct {
	Provider   ProviderID    `json:"provider,omitempty"`
	API        EmbeddingAPI  `json:"api,omitempty"`
	Model      ModelID       `json:"model,omitempty"`
	Attempt    int           `json:"attempt,omitempty"`
	StatusCode int           `json:"statusCode,omitempty"`
	RequestID  string        `json:"requestID,omitempty"`
	Latency    time.Duration `json:"latency,omitempty"`
}

EmbeddingAttempt records SDK-level metadata for one embedding provider attempt.

type EmbeddingBatchConfig added in v0.3.0 

type EmbeddingBatchConfig struct {
	ReuseDuplicateInputs bool
	MaxRetries           int
	MaxParallelBatches   int
	MaxBatchInputs       int
	MaxBatchBytes        int
	SplitOversized       bool
	Cache                EmbeddingCache
	SplitPolicy          EmbeddingSplitPolicy
	// Progress receives batch progress callbacks. When MaxParallelBatches is
	// greater than zero it may be called concurrently from multiple goroutines,
	// so it must be safe for concurrent use.
	Progress func(EmbeddingBatchProgress) error
}

EmbeddingBatchConfig configures resilient embedding batch behaviour.

type EmbeddingBatchPhase added in v0.3.0 

type EmbeddingBatchPhase string

EmbeddingBatchPhase identifies a resilient embedding batch progress stage. 

const (
	EmbeddingBatchPhaseCacheHit     EmbeddingBatchPhase = "cache_hit"
	EmbeddingBatchPhaseCacheLookup  EmbeddingBatchPhase = "cache_lookup"
	EmbeddingBatchPhaseCacheStore   EmbeddingBatchPhase = "cache_store"
	EmbeddingBatchPhaseBatchStart   EmbeddingBatchPhase = "batch_start"
	EmbeddingBatchPhaseBatchSuccess EmbeddingBatchPhase = "batch_success"
	EmbeddingBatchPhaseBatchError   EmbeddingBatchPhase = "batch_error"
	EmbeddingBatchPhaseLimitSplit   EmbeddingBatchPhase = "limit_split"
	EmbeddingBatchPhaseSplit        EmbeddingBatchPhase = "split"
)

type EmbeddingBatchProgress added in v0.3.0 

type EmbeddingBatchProgress struct {
	Phase        EmbeddingBatchPhase
	Attempt      int
	BatchSize    int
	InputIndexes []int
	SplitPart    int
	SplitTotal   int
	Err          error
}

EmbeddingBatchProgress reports progress from EmbedBatch.

type EmbeddingBatchResult added in v0.3.0 

type EmbeddingBatchResult struct {
	Embeddings Embeddings
	Reused     []bool
	Summary    EmbeddingBatchSummary
}

EmbeddingBatchResult is ordered embedding output plus batch metadata.

func EmbedBatch added in v0.3.0 

func EmbedBatch(ctx context.Context, model EmbeddingModel, req EmbeddingRequest, config EmbeddingBatchConfig, opts ...EmbeddingOption) (EmbeddingBatchResult, error)

EmbedBatch embeds req.Inputs using the default registry.

type EmbeddingBatchSummary added in v0.3.0 

type EmbeddingBatchSummary struct {
	RequestCount      int
	TotalRequestCount int
	ErrorCount        int
	VectorCount       int
	StatusBuckets     map[int]int
	RequestIDs        []string
	Attempts          []EmbeddingAttempt
	Trace             []EmbeddingBatchTraceEvent
	Usage             *Usage
	Cost              *Cost
}

EmbeddingBatchSummary reports aggregate provider work from EmbedBatch.

type EmbeddingBatchTraceEvent added in v0.3.0 

type EmbeddingBatchTraceEvent struct {
	Phase            EmbeddingBatchPhase
	Attempt          int
	BatchSize        int
	BatchBytes       int
	InputIndexes     []int
	MaxBatchInputs   int
	MaxBatchBytes    int
	CacheKey         EmbeddingCacheKey
	CacheHit         bool
	SplitPart        int
	SplitTotal       int
	SplitReason      string
	ErrorClass       ErrorClass
	ErrorMessage     string
	StatusCode       int
	ProviderCode     string
	RequestID        string
	Retryable        bool
	SplitRecoverable bool
	ProviderAttempts []EmbeddingAttempt
}

EmbeddingBatchTraceEvent reports structured, redacted EmbedBatch execution metadata. It never includes raw input text.

type EmbeddingCache added in v0.3.0 

type EmbeddingCache interface {
	Get(EmbeddingCacheKey) (Embedding, bool, error)
	Set(EmbeddingCacheKey, Embedding) error
}

EmbeddingCache stores embeddings for reuse across EmbedBatch calls.

When EmbeddingBatchConfig.MaxParallelBatches is greater than zero, Get and Set may be called concurrently from multiple goroutines, so implementations must be safe for concurrent use.

type EmbeddingCacheKey added in v0.3.0 

type EmbeddingCacheKey struct {
	Provider    ProviderID
	API         EmbeddingAPI
	Model       ModelID
	Dimensions  int
	InputType   EmbeddingInputType
	InputSHA256 string
}

EmbeddingCacheKey identifies one cacheable embedding input without exposing the raw input text.

type EmbeddingEmbedder added in v0.3.0 

type EmbeddingEmbedder interface {
	EmbedDocuments(ctx context.Context, texts []string) ([][]float32, error)
	EmbedQuery(ctx context.Context, text string) ([]float32, error)
}

EmbeddingEmbedder creates query and document vectors through Sigma's provider-neutral embedding surface.

type EmbeddingEmbedderConfig added in v0.3.0 

type EmbeddingEmbedderConfig struct {
	Dimensions int
	Batch      EmbeddingBatchConfig
}

EmbeddingEmbedderConfig configures NewEmbeddingEmbedder.

type EmbeddingInputType added in v0.3.0 

type EmbeddingInputType string

EmbeddingInputType identifies the intended use for embedding inputs. 

const (
	// EmbeddingInputTypeQuery marks an embedding request as search-query input.
	EmbeddingInputTypeQuery EmbeddingInputType = "query"
	// EmbeddingInputTypeDocument marks an embedding request as document input.
	EmbeddingInputTypeDocument EmbeddingInputType = "document"
)

type EmbeddingModel added in v0.3.0 

type EmbeddingModel struct {
	ID                  ModelID        `json:"id"`
	Provider            ProviderID     `json:"provider"`
	API                 EmbeddingAPI   `json:"api,omitempty"`
	Name                string         `json:"name,omitempty"`
	DefaultDimensions   int            `json:"defaultDimensions,omitempty"`
	MinDimensions       int            `json:"minDimensions,omitempty"`
	MaxDimensions       int            `json:"maxDimensions,omitempty"`
	MaxInputTokens      int            `json:"maxInputTokens,omitempty"`
	MaxBatchInputs      int            `json:"maxBatchInputs,omitempty"`
	MaxBatchBytes       int            `json:"maxBatchBytes,omitempty"`
	InputCostPerMillion float64        `json:"inputCostPerMillion,omitempty"`
	CostCurrency        string         `json:"costCurrency,omitempty"`
	ProviderMetadata    map[string]any `json:"providerMetadata,omitempty"`
}

EmbeddingModel describes a provider embedding model available through sigma.

func EmbeddingModels added in v0.3.0 

func EmbeddingModels() []EmbeddingModel

EmbeddingModels returns embedding models from the default registry.

func GetEmbeddingModel added in v0.3.0 

func GetEmbeddingModel(provider ProviderID, id ModelID) (EmbeddingModel, bool)

GetEmbeddingModel returns an embedding model from the default registry.

func OpenAICompatibleEmbeddingModel added in v0.3.0 

func OpenAICompatibleEmbeddingModel(config OpenAICompatibleEmbeddingModelConfig) EmbeddingModel

OpenAICompatibleEmbeddingModel constructs metadata for an OpenAI Embeddings-compatible model. Register the returned model on the same registry as an OpenAI embeddings provider, then pass that registry to NewClient with WithRegistry for an isolated setup.

type EmbeddingModelSource added in v0.6.0 

type EmbeddingModelSource interface {
	EmbeddingModels(context.Context) ([]EmbeddingModel, error)
}

EmbeddingModelSource lists embedding models for a provider-owned runtime source.

type EmbeddingModelSourceFunc added in v0.6.0 

type EmbeddingModelSourceFunc func(context.Context) ([]EmbeddingModel, error)

EmbeddingModelSourceFunc adapts a function into an EmbeddingModelSource.

func (EmbeddingModelSourceFunc) EmbeddingModels added in v0.6.0 

func (f EmbeddingModelSourceFunc) EmbeddingModels(ctx context.Context) ([]EmbeddingModel, error)

EmbeddingModels calls f.

type EmbeddingOption added in v0.3.0 

type EmbeddingOption func(*Options)

EmbeddingOption configures a single embedding provider request.

func WithEmbeddingAPIKey added in v0.3.0 

func WithEmbeddingAPIKey(apiKey string) EmbeddingOption

WithEmbeddingAPIKey configures a request-scoped embedding API key override.

func WithEmbeddingAuthResolver added in v0.3.0 

func WithEmbeddingAuthResolver(resolver AuthResolver) EmbeddingOption

WithEmbeddingAuthResolver configures a request-scoped credential resolver.

func WithEmbeddingHTTPClient added in v0.3.0 

func WithEmbeddingHTTPClient(httpClient *http.Client) EmbeddingOption

WithEmbeddingHTTPClient configures the HTTP client exposed to embedding providers.

func WithEmbeddingHeader added in v0.3.0 

func WithEmbeddingHeader(key, value string) EmbeddingOption

WithEmbeddingHeader adds or replaces an embedding request header.

func WithEmbeddingHeaders added in v0.3.0 

func WithEmbeddingHeaders(headers map[string]string) EmbeddingOption

WithEmbeddingHeaders adds or replaces embedding request headers.

func WithEmbeddingMaxRetries added in v0.3.0 

func WithEmbeddingMaxRetries(maxRetries int) EmbeddingOption

WithEmbeddingMaxRetries configures the maximum embedding provider retry attempts.

func WithEmbeddingMaxRetryDelay added in v0.3.0 

func WithEmbeddingMaxRetryDelay(maxRetryDelay time.Duration) EmbeddingOption

WithEmbeddingMaxRetryDelay configures the maximum delay between embedding provider retries.

func WithEmbeddingMetadata added in v0.3.0 

func WithEmbeddingMetadata(metadata map[string]any) EmbeddingOption

WithEmbeddingMetadata adds or replaces provider-neutral embedding request metadata.

func WithEmbeddingMetadataValue added in v0.3.0 

func WithEmbeddingMetadataValue(key string, value any) EmbeddingOption

WithEmbeddingMetadataValue adds or replaces one provider-neutral embedding metadata value.

func WithEmbeddingPayloadDebugHook added in v0.3.0 

func WithEmbeddingPayloadDebugHook(hook EmbeddingPayloadDebugHook) EmbeddingOption

WithEmbeddingPayloadDebugHook adds a safe embedding request payload debug hook.

func WithEmbeddingProviderAuthResolver added in v0.3.0 

func WithEmbeddingProviderAuthResolver(provider ProviderID, resolver AuthResolver) EmbeddingOption

WithEmbeddingProviderAuthResolver configures a provider-specific embedding credential callback.

func WithEmbeddingProviderOption added in v0.3.0 

func WithEmbeddingProviderOption(provider ProviderID, key string, value any) EmbeddingOption

WithEmbeddingProviderOption adds or replaces one advanced provider-specific embedding value.

func WithEmbeddingProviderOptions added in v0.3.0 

func WithEmbeddingProviderOptions(provider ProviderID, values map[string]any) EmbeddingOption

WithEmbeddingProviderOptions adds or replaces advanced provider-specific embedding values.

func WithEmbeddingResponseDebugHook added in v0.3.0 

func WithEmbeddingResponseDebugHook(hook EmbeddingResponseDebugHook) EmbeddingOption

WithEmbeddingResponseDebugHook adds a safe embedding response debug hook.

func WithEmbeddingSuppressedHeader added in v0.6.0 

func WithEmbeddingSuppressedHeader(key string) EmbeddingOption

WithEmbeddingSuppressedHeader removes a final outgoing embedding request header.

func WithEmbeddingSuppressedHeaders added in v0.6.0 

func WithEmbeddingSuppressedHeaders(keys ...string) EmbeddingOption

WithEmbeddingSuppressedHeaders removes final outgoing embedding request headers.

func WithEmbeddingTimeout added in v0.3.0 

func WithEmbeddingTimeout(timeout time.Duration) EmbeddingOption

WithEmbeddingTimeout configures the per-request embedding provider timeout.

type EmbeddingPayloadDebug added in v0.3.0 

type EmbeddingPayloadDebug struct {
	Provider       ProviderID
	API            EmbeddingAPI
	Model          ModelID
	Headers        http.Header
	Payload        []byte
	PayloadPreview string
}

EmbeddingPayloadDebug is the diagnostic view passed to embedding payload hooks.

type EmbeddingPayloadDebugHook added in v0.3.0 

type EmbeddingPayloadDebugHook func(context.Context, EmbeddingPayloadDebug) error

EmbeddingPayloadDebugHook inspects a redacted copy of an embedding provider payload.

Hooks run after provider payload and headers are built and before the HTTP request is sent. Payload replacement is intentionally unsupported: Payload is a redacted copy for diagnostics, so mutating it cannot change the request body or corrupt a later retry attempt.

type EmbeddingProvider added in v0.3.0 

type EmbeddingProvider interface {
	API() EmbeddingAPI
	Embed(context.Context, EmbeddingModel, EmbeddingRequest, Options) (Embeddings, error)
}

EmbeddingProvider adapts a provider API into sigma's vector embeddings interface.

type EmbeddingRequest added in v0.3.0 

type EmbeddingRequest struct {
	Inputs           []string           `json:"inputs,omitempty"`
	Dimensions       int                `json:"dimensions,omitempty"`
	InputType        EmbeddingInputType `json:"inputType,omitempty"`
	ProviderMetadata map[string]any     `json:"providerMetadata,omitempty"`
}

EmbeddingRequest is the provider-neutral input for vector embeddings.

func EmbeddingDocuments added in v0.3.0 

func EmbeddingDocuments(texts []string) EmbeddingRequest

EmbeddingDocuments builds an embedding request for document inputs.

func EmbeddingQuery added in v0.3.0 

func EmbeddingQuery(text string) EmbeddingRequest

EmbeddingQuery builds an embedding request for one search-query input.

type EmbeddingResponseDebug added in v0.3.0 

type EmbeddingResponseDebug struct {
	Provider   ProviderID
	API        EmbeddingAPI
	Model      ModelID
	StatusCode int
	Headers    http.Header
	RequestID  string
}

EmbeddingResponseDebug is the diagnostic view passed to embedding response hooks.

type EmbeddingResponseDebugHook added in v0.3.0 

type EmbeddingResponseDebugHook func(context.Context, EmbeddingResponseDebug) error

EmbeddingResponseDebugHook inspects redacted embedding response metadata before the response body is consumed.

type EmbeddingScore added in v0.3.0 

type EmbeddingScore struct {
	Embedding Embedding `json:"embedding"`
	Score     float64   `json:"score"`
}

EmbeddingScore is a candidate embedding plus its similarity score.

func RankEmbeddingsByCosine added in v0.3.0 

func RankEmbeddingsByCosine(query []float32, candidates []Embedding) ([]EmbeddingScore, error)

RankEmbeddingsByCosine scores candidates against query and sorts by descending similarity.

type EmbeddingSplitPolicy added in v0.3.0 

type EmbeddingSplitPolicy struct {
	PreferNewline    bool
	PreferWhitespace bool
}

EmbeddingSplitPolicy configures oversized embedding input splitting.

type Embeddings added in v0.3.0 

type Embeddings struct {
	Vectors          []Embedding        `json:"vectors,omitempty"`
	Usage            *Usage             `json:"usage,omitempty"`
	Cost             *Cost              `json:"cost,omitempty"`
	Model            ModelID            `json:"model,omitempty"`
	Provider         ProviderID         `json:"provider,omitempty"`
	Attempts         []EmbeddingAttempt `json:"attempts,omitempty"`
	ProviderMetadata map[string]any     `json:"providerMetadata,omitempty"`
}

Embeddings is provider-neutral embedding output plus request metadata.

func Embed added in v0.3.0 

func Embed(ctx context.Context, model EmbeddingModel, req EmbeddingRequest, opts ...EmbeddingOption) (Embeddings, error)

Embed calls the registered embedding provider using the default registry.

type EnvironmentAuthResolver 

type EnvironmentAuthResolver struct {
	LookupEnv func(string) (string, bool)
}

EnvironmentAuthResolver resolves static API keys from environment variables.

func (EnvironmentAuthResolver) ConfiguredEnvVars added in v0.6.0 

func (r EnvironmentAuthResolver) ConfiguredEnvVars(model Model) []string

ConfiguredEnvVars returns the ordered environment variable names that are currently set to non-empty values for model credentials. Secret values are not returned.

func (EnvironmentAuthResolver) EnvVars added in v0.6.0 

func (r EnvironmentAuthResolver) EnvVars(model Model) []string

EnvVars returns the ordered environment variable names that would be checked for model credentials. Model metadata takes precedence over provider defaults. Secret values are not returned.

func (EnvironmentAuthResolver) Resolve 

func (r EnvironmentAuthResolver) Resolve(_ context.Context, model Model, _ Options) (Credential, error)

Resolve returns the first non-empty provider API key found in the environment.

type Error 

type Error struct {
	Code     ErrorCode
	Message  string
	Provider ProviderID
	Model    ModelID
	Err      error
}

Error is the package error type.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Is 

func (e *Error) Is(target error) bool

Is supports errors.Is with sigma sentinel errors.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap returns the underlying cause.

type ErrorClass added in v0.3.0 

type ErrorClass string

ErrorClass is a stable provider/model execution error category. 

const (
	ErrorClassUnknown         ErrorClass = "unknown"
	ErrorClassTransient       ErrorClass = "transient"
	ErrorClassRateLimited     ErrorClass = "rate-limited"
	ErrorClassAuth            ErrorClass = "auth"
	ErrorClassQuota           ErrorClass = "quota"
	ErrorClassBilling         ErrorClass = "billing"
	ErrorClassContextOverflow ErrorClass = "context-overflow"
	ErrorClassInvalidRequest  ErrorClass = "invalid-request"
	ErrorClassProvider        ErrorClass = "provider"
)

type ErrorClassification added in v0.3.0 

type ErrorClassification struct {
	Class        ErrorClass
	Provider     ProviderID
	API          API
	Model        ModelID
	StatusCode   int
	ProviderCode string
	Message      string
	RequestID    string
	RetryHint    RetryHint
	// SplitRecoverable reports whether a smaller request may recover from the
	// same error even though retrying the identical request is not useful.
	SplitRecoverable bool
	Err              error
}

ErrorClassification exposes provider-neutral handling hints for an error.

func ClassifyError added in v0.3.0 

func ClassifyError(err error) ErrorClassification

ClassifyError returns stable provider-neutral classification for err.

type ErrorCode 

type ErrorCode string

ErrorCode identifies a sigma error category. 

const (
	// ErrorUnsupported indicates a requested capability is not implemented.
	ErrorUnsupported ErrorCode = "unsupported"
	// ErrorProviderNotFound indicates no provider is registered for a model.
	ErrorProviderNotFound ErrorCode = "provider-not-found"
	// ErrorModelNotFound indicates no model metadata is registered for a model.
	ErrorModelNotFound ErrorCode = "model-not-found"
	// ErrorContextOverflow indicates the provider rejected an oversized context.
	ErrorContextOverflow ErrorCode = "context-overflow"
	// ErrorToolValidation indicates local tool schema or call validation failed.
	ErrorToolValidation ErrorCode = "tool-validation"
	// ErrorProviderResponse indicates a provider returned a failed response.
	ErrorProviderResponse ErrorCode = "provider-response"
)
const (
	// ErrorStream indicates a provider stream ended with an error event.
	ErrorStream ErrorCode = "stream"
	// ErrorAborted indicates a stream ended because its context was canceled.
	ErrorAborted ErrorCode = "aborted"
	// ErrorStreamClosed indicates a write was attempted after stream closure.
	ErrorStreamClosed ErrorCode = "stream-closed"
	// ErrorInvalidStreamEvent indicates a writer was asked to emit an invalid event.
	ErrorInvalidStreamEvent ErrorCode = "invalid-stream-event"
)
const (
	// ErrorDebugHook indicates a caller-provided debug hook failed.
	ErrorDebugHook ErrorCode = "debug-hook"
)
const (
	// ErrorInvalidOptions indicates request options failed local validation.
	ErrorInvalidOptions ErrorCode = "invalid-options"
)
const (
	// ErrorInvalidRequest indicates a persisted request cannot be replayed safely.
	ErrorInvalidRequest ErrorCode = "invalid-request"
)

type Event 

type Event struct {
	Kind            EventKind         `json:"kind"`
	ContentIndex    *int              `json:"contentIndex,omitempty"`
	DeltaText       string            `json:"deltaText,omitempty"`
	Text            string            `json:"text,omitempty"`
	Thinking        string            `json:"thinking,omitempty"`
	Image           *ContentBlock     `json:"image,omitempty"`
	PartialImage    *ContentBlock     `json:"partialImage,omitempty"`
	ToolCall        *ToolCall         `json:"toolCall,omitempty"`
	PartialToolCall *PartialToolCall  `json:"partialToolCall,omitempty"`
	PartialMessage  *AssistantMessage `json:"partialMessage,omitempty"`
	FinalMessage    *AssistantMessage `json:"finalMessage,omitempty"`
	Usage           *Usage            `json:"usage,omitempty"`
	StopReason      StopReason        `json:"stopReason,omitempty"`
	Error           string            `json:"error,omitempty"`
}

Event is a provider-neutral text-generation stream event.

Content block events may be interleaved. Consumers must route text, thinking, and tool-call updates by ContentIndex instead of assuming events arrive as a single sequential output buffer.

Typical consumers switch on Kind: 

switch event.Kind {
case sigma.EventKindTextDelta:
	handleTextDelta(event.ContentIndex, event.DeltaText)
case sigma.EventKindToolCallEnd:
	handleToolCall(event.ContentIndex, event.ToolCall)
case sigma.EventKindDone, sigma.EventKindError:
	finish(event)
}

func (Event) IsDelta 

func (event Event) IsDelta() bool

IsDelta reports whether event carries an incremental content update.

func (Event) IsStart 

func (event Event) IsStart() bool

IsStart reports whether event starts a stream or content block.

func (Event) IsTerminal 

func (event Event) IsTerminal() bool

IsTerminal reports whether event ends a stream.

type EventKind 

type EventKind string

EventKind identifies the kind of provider-neutral streaming event. 

const (
	// EventKindStart marks the beginning of a stream.
	EventKindStart EventKind = "start"
	// EventKindTextStart marks the beginning of a text content block.
	EventKindTextStart EventKind = "text_start"
	// EventKindTextDelta carries text appended to a text content block.
	EventKindTextDelta EventKind = "text_delta"
	// EventKindTextEnd marks the end of a text content block.
	EventKindTextEnd EventKind = "text_end"
	// EventKindThinkingStart marks the beginning of a thinking content block.
	EventKindThinkingStart EventKind = "thinking_start"
	// EventKindThinkingDelta carries text appended to a thinking content block.
	EventKindThinkingDelta EventKind = "thinking_delta"
	// EventKindThinkingEnd marks the end of a thinking content block.
	EventKindThinkingEnd EventKind = "thinking_end"
	// EventKindToolCallStart marks the beginning of a tool-call content block.
	EventKindToolCallStart EventKind = "toolcall_start"
	// EventKindToolCallDelta carries partial tool-call data.
	EventKindToolCallDelta EventKind = "toolcall_delta"
	// EventKindToolCallEnd marks the end of a tool-call content block.
	EventKindToolCallEnd EventKind = "toolcall_end"
	// EventKindImageStart marks the beginning of an image content block.
	EventKindImageStart EventKind = "image_start"
	// EventKindImageDelta carries partial image content.
	EventKindImageDelta EventKind = "image_delta"
	// EventKindImageEnd marks the end of an image content block.
	EventKindImageEnd EventKind = "image_end"
	// EventKindDone marks the successful end of a stream.
	EventKindDone EventKind = "done"
	// EventKindError marks a stream error.
	EventKindError EventKind = "error"
)

func (EventKind) IsDelta 

func (kind EventKind) IsDelta() bool

IsDelta reports whether kind carries an incremental content update.

func (EventKind) IsStart 

func (kind EventKind) IsStart() bool

IsStart reports whether kind starts a stream or content block.

func (EventKind) IsTerminal 

func (kind EventKind) IsTerminal() bool

IsTerminal reports whether kind ends a stream.

func (EventKind) String 

func (kind EventKind) String() string

String returns the event kind string.

type GenerationError 

type GenerationError struct {
	Final AssistantMessage
	Err   error
}

GenerationError carries a final assistant message alongside a terminal error.

func (*GenerationError) Error 

func (e *GenerationError) Error() string

func (*GenerationError) FinalMessage 

func (e *GenerationError) FinalMessage() (AssistantMessage, bool)

FinalMessage returns the assistant message recorded at stream termination.

func (*GenerationError) String 

func (e *GenerationError) String() string

String returns the same diagnostic-safe text as Error.

func (*GenerationError) Unwrap 

func (e *GenerationError) Unwrap() error

Unwrap returns the terminal generation error.

type GoogleOptions 

type GoogleOptions struct {
	ThinkingBudgetTokens *int
	ToolChoice           string
	DisableThinking      *bool
}

GoogleOptions carries Google-specific request options known to the root package without importing provider adapters.

type HTTPAttempt added in v0.3.0 

type HTTPAttempt struct {
	Attempt    int
	StatusCode int
	RequestID  string
	Latency    time.Duration
}

HTTPAttempt records provider-neutral facts about one HTTP request attempt.

func DoHTTPWithRetryAttempts added in v0.3.0 

func DoHTTPWithRetryAttempts(
	ctx context.Context,
	client *http.Client,
	opts Options,
	newRequest func(context.Context) (*http.Request, error),
	providerError func(*http.Response) *ProviderError,
	hooks ...HTTPResponseHook,
) (*http.Response, []HTTPAttempt, error)

DoHTTPWithRetryAttempts sends a request with sigma's shared HTTP retry policy and returns metadata for every attempted HTTP request.

type HTTPResponseHook 

type HTTPResponseHook func(*http.Response) error

HTTPResponseHook inspects a response before retry status handling. The response body has not been consumed.

func EmbeddingResponseDebugHTTPHook added in v0.3.0 

func EmbeddingResponseDebugHTTPHook(ctx context.Context, opts Options, provider ProviderID, api EmbeddingAPI, model ModelID) HTTPResponseHook

EmbeddingResponseDebugHTTPHook adapts embedding response hooks to the shared retry helper.

func ImageResponseDebugHTTPHook 

func ImageResponseDebugHTTPHook(ctx context.Context, opts Options, provider ProviderID, api ImageAPI, model ModelID) HTTPResponseHook

ImageResponseDebugHTTPHook adapts image response hooks to the shared retry helper.

func TextResponseDebugHTTPHook 

func TextResponseDebugHTTPHook(ctx context.Context, opts Options, provider ProviderID, api API, model ModelID) HTTPResponseHook

TextResponseDebugHTTPHook adapts text response hooks to the shared retry helper.

type HandoffChange added in v0.6.0 

type HandoffChange struct {
	Kind               HandoffChangeKind `json:"kind"`
	MessageIndex       int               `json:"messageIndex"`
	OutputMessageIndex *int              `json:"outputMessageIndex,omitempty"`
	ContentIndex       *int              `json:"contentIndex,omitempty"`
	Detail             string            `json:"detail,omitempty"`
}

HandoffChange describes one source-neutral transformation.

type HandoffChangeKind added in v0.6.0 

type HandoffChangeKind string

HandoffChangeKind identifies one request adaptation made during handoff. 

const (
	// HandoffChangeThinkingConverted indicates a thinking block was converted
	// to text for a target that cannot safely replay it natively.
	HandoffChangeThinkingConverted HandoffChangeKind = "thinking-converted"
	// HandoffChangeDeveloperRoleConverted indicates a developer message was
	// converted to a user message for target compatibility.
	HandoffChangeDeveloperRoleConverted HandoffChangeKind = "developer-role-converted"
	// HandoffChangeToolResultNameRepaired indicates a missing tool result name
	// was filled from a prior assistant tool call.
	HandoffChangeToolResultNameRepaired HandoffChangeKind = "tool-result-name-repaired"
	// HandoffChangeUnansweredToolCallDropped indicates an assistant tool call
	// without a matching tool result before the next user/developer turn was
	// removed.
	HandoffChangeUnansweredToolCallDropped HandoffChangeKind = "unanswered-tool-call-dropped"
	// HandoffChangeRepairMessageInserted indicates an assistant bridge message
	// was inserted between a tool result and following user turn.
	HandoffChangeRepairMessageInserted HandoffChangeKind = "repair-message-inserted"
	// HandoffChangeToolResultSynthesized indicates a missing tool result was
	// synthesized for an unanswered assistant tool call.
	HandoffChangeToolResultSynthesized HandoffChangeKind = "tool-result-synthesized"
	// HandoffChangeUnsupportedImageReplaced indicates an image block was
	// replaced with caller-supplied text for a non-vision target.
	HandoffChangeUnsupportedImageReplaced HandoffChangeKind = "unsupported-image-replaced"
)

type HandoffMessagesResult added in v0.6.0 

type HandoffMessagesResult struct {
	Messages []Message     `json:"messages,omitempty"`
	Report   HandoffReport `json:"report,omitempty"`
}

HandoffMessagesResult is a transformed message list and its adaptation report.

func TransformMessagesForModel added in v0.6.0 

func TransformMessagesForModel(target Model, messages []Message, opts ...HandoffOption) (HandoffMessagesResult, error)

TransformMessagesForModel adapts a message list for replay against target. It is equivalent to TransformRequestForModel with only Request.Messages set.

type HandoffOption added in v0.6.0 

type HandoffOption func(*handoffConfig)

HandoffOption configures public cross-provider request adaptation.

func WithHandoffThinkingDelimiters added in v0.6.0 

func WithHandoffThinkingDelimiters(start string, end string) HandoffOption

WithHandoffThinkingDelimiters configures the text wrappers used when provider-native thinking blocks are converted to text.

func WithHandoffUnsupportedImageReplacement added in v0.6.0 

func WithHandoffUnsupportedImageReplacement(text string) HandoffOption

WithHandoffUnsupportedImageReplacement replaces unsupported image blocks with the supplied text instead of returning an unsupported-content error.

type HandoffReport added in v0.6.0 

type HandoffReport struct {
	ConvertedThinkingBlocks    int             `json:"convertedThinkingBlocks,omitempty"`
	ConvertedDeveloperMessages int             `json:"convertedDeveloperMessages,omitempty"`
	RepairedToolResultNames    int             `json:"repairedToolResultNames,omitempty"`
	DroppedUnansweredToolCalls int             `json:"droppedUnansweredToolCalls,omitempty"`
	InsertedRepairMessages     int             `json:"insertedRepairMessages,omitempty"`
	SynthesizedToolResults     int             `json:"synthesizedToolResults,omitempty"`
	ReplacedUnsupportedImages  int             `json:"replacedUnsupportedImages,omitempty"`
	Changes                    []HandoffChange `json:"changes,omitempty"`
}

HandoffReport summarizes adaptations made for a target model.

type HandoffResult added in v0.6.0 

type HandoffResult struct {
	Request Request       `json:"request"`
	Report  HandoffReport `json:"report,omitempty"`
}

HandoffResult is a transformed request and its adaptation report.

func TransformRequestForModel added in v0.6.0 

func TransformRequestForModel(target Model, req Request, opts ...HandoffOption) (HandoffResult, error)

TransformRequestForModel adapts a request for replay against target. The helper is opt-in and does not mutate the caller's request.

type ImageAPI 

type ImageAPI string

ImageAPI identifies an image generation provider API surface. 

const (
	// ImageAPIOpenAIImages identifies the OpenAI image generation API.
	ImageAPIOpenAIImages ImageAPI = "openai-images"
	// ImageAPIOpenRouterImages identifies OpenRouter image generation through Chat Completions.
	ImageAPIOpenRouterImages ImageAPI = "openrouter-images"
	// ImageAPIGoogleImages identifies Google's Gemini and Imagen image APIs.
	ImageAPIGoogleImages ImageAPI = "google-images"
	// ImageAPIGoogleVertexImages identifies Google's Vertex AI Imagen image API.
	ImageAPIGoogleVertexImages ImageAPI = "google-vertex-images"
)

type ImageError 

type ImageError struct {
	Code             string         `json:"code,omitempty"`
	Message          string         `json:"message,omitempty"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

ImageError records a provider-reported image generation error that belongs to a response body rather than the Go error return.

type ImageEvent added in v0.3.0 

type ImageEvent struct {
	Kind          ImageEventKind   `json:"kind"`
	Image         *ImageInput      `json:"image,omitempty"`
	PartialImage  *ImageInput      `json:"partialImage,omitempty"`
	FinalImages   *AssistantImages `json:"finalImages,omitempty"`
	Usage         *Usage           `json:"usage,omitempty"`
	StopReason    StopReason       `json:"stopReason,omitempty"`
	Error         string           `json:"error,omitempty"`
	SequenceIndex *int             `json:"sequenceIndex,omitempty"`
}

ImageEvent is a provider-neutral image-generation stream event.

func (ImageEvent) IsTerminal added in v0.3.0 

func (event ImageEvent) IsTerminal() bool

IsTerminal reports whether event ends an image stream.

type ImageEventKind added in v0.3.0 

type ImageEventKind string

ImageEventKind identifies the kind of provider-neutral image stream event. 

const (
	// ImageEventKindStart marks the beginning of an image stream.
	ImageEventKindStart ImageEventKind = "start"
	// ImageEventKindPartial carries a partial generated image.
	ImageEventKindPartial ImageEventKind = "image_partial"
	// ImageEventKindImage carries a final generated image.
	ImageEventKindImage ImageEventKind = "image"
	// ImageEventKindDone marks the successful end of an image stream.
	ImageEventKindDone ImageEventKind = "done"
	// ImageEventKindError marks an image stream error.
	ImageEventKindError ImageEventKind = "error"
)

func (ImageEventKind) IsTerminal added in v0.3.0 

func (kind ImageEventKind) IsTerminal() bool

IsTerminal reports whether kind ends an image stream.

type ImageInput 

type ImageInput struct {
	Type     string `json:"type"`
	Text     string `json:"text,omitempty"`
	MIMEType string `json:"mimeType,omitempty"`
	Source   string `json:"source,omitempty"`
	Data     string `json:"data,omitempty"`
	URL      string `json:"url,omitempty"`
}

ImageInput is an image or text input used by image APIs.

func ImageData 

func ImageData(mimeType string, data string) ImageInput

ImageData constructs a base64 image input or output for image APIs.

func ImageFileID added in v0.3.0 

func ImageFileID(id string) ImageInput

ImageFileID constructs a provider file reference for image APIs.

func ImageOutputData 

func ImageOutputData(mimeType string, data string) ImageInput

ImageOutputData constructs a base64 generated image output.

func ImageOutputURL 

func ImageOutputURL(mimeType string, url string) ImageInput

ImageOutputURL constructs a URL-backed generated image output.

func ImageText 

func ImageText(text string) ImageInput

ImageText constructs a text input for image APIs.

type ImageModel 

type ImageModel struct {
	ID               ModelID        `json:"id"`
	Provider         ProviderID     `json:"provider"`
	API              ImageAPI       `json:"api,omitempty"`
	Name             string         `json:"name,omitempty"`
	MaxWidth         int            `json:"maxWidth,omitempty"`
	MaxHeight        int            `json:"maxHeight,omitempty"`
	SupportedSizes   []string       `json:"supportedSizes,omitempty"`
	SupportedFormats []string       `json:"supportedFormats,omitempty"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

ImageModel describes a provider image model available through sigma.

func GetImageModel 

func GetImageModel(provider ProviderID, id ModelID) (ImageModel, bool)

GetImageModel returns an image model from the default registry.

func ImageModels 

func ImageModels() []ImageModel

ImageModels returns image models from the default registry.

type ImageModelSource added in v0.6.0 

type ImageModelSource interface {
	ImageModels(context.Context) ([]ImageModel, error)
}

ImageModelSource lists image models for a provider-owned runtime source.

type ImageModelSourceFunc added in v0.6.0 

type ImageModelSourceFunc func(context.Context) ([]ImageModel, error)

ImageModelSourceFunc adapts a function into an ImageModelSource.

func (ImageModelSourceFunc) ImageModels added in v0.6.0 

func (f ImageModelSourceFunc) ImageModels(ctx context.Context) ([]ImageModel, error)

ImageModels calls f.

type ImageOperation added in v0.3.0 

type ImageOperation string

ImageOperation identifies the requested provider-neutral image operation. 

const (
	// ImageOperationGenerate requests text-to-image generation.
	ImageOperationGenerate ImageOperation = "generate"
	// ImageOperationEdit requests reference-image editing.
	ImageOperationEdit ImageOperation = "edit"
	// ImageOperationVariation requests a variation of one source image.
	ImageOperationVariation ImageOperation = "variation"
)

type ImageOption 

type ImageOption func(*Options)

ImageOption configures a single image provider request.

Image generation options are intentionally separate from text generation options. Provider adapters still receive the shared internal Options shape so auth, headers, HTTP clients, retry policy, metadata, and provider extension values follow the same conventions as text requests.

func WithImageAPIKey 

func WithImageAPIKey(apiKey string) ImageOption

WithImageAPIKey configures a request-scoped image API key override.

func WithImageAuthResolver 

func WithImageAuthResolver(resolver AuthResolver) ImageOption

WithImageAuthResolver configures a request-scoped credential resolver.

func WithImageHTTPClient 

func WithImageHTTPClient(httpClient *http.Client) ImageOption

WithImageHTTPClient configures the HTTP client exposed to image providers.

func WithImageHeader 

func WithImageHeader(key, value string) ImageOption

WithImageHeader adds or replaces an image request header.

func WithImageHeaders 

func WithImageHeaders(headers map[string]string) ImageOption

WithImageHeaders adds or replaces image request headers.

func WithImageMaxRetries 

func WithImageMaxRetries(maxRetries int) ImageOption

WithImageMaxRetries configures the maximum image provider retry attempts.

func WithImageMaxRetryDelay 

func WithImageMaxRetryDelay(maxRetryDelay time.Duration) ImageOption

WithImageMaxRetryDelay configures the maximum delay between image provider retries.

func WithImageMetadata 

func WithImageMetadata(metadata map[string]any) ImageOption

WithImageMetadata adds or replaces provider-neutral image request metadata.

func WithImageMetadataValue 

func WithImageMetadataValue(key string, value any) ImageOption

WithImageMetadataValue adds or replaces one provider-neutral image metadata value.

func WithImagePayloadDebugHook 

func WithImagePayloadDebugHook(hook ImagePayloadDebugHook) ImageOption

WithImagePayloadDebugHook adds a safe image request payload debug hook.

func WithImageProviderAuthResolver 

func WithImageProviderAuthResolver(provider ProviderID, resolver AuthResolver) ImageOption

WithImageProviderAuthResolver configures a provider-specific image credential callback.

func WithImageProviderOption 

func WithImageProviderOption(provider ProviderID, key string, value any) ImageOption

WithImageProviderOption adds or replaces one advanced provider-specific image value.

func WithImageProviderOptions 

func WithImageProviderOptions(provider ProviderID, values map[string]any) ImageOption

WithImageProviderOptions adds or replaces advanced provider-specific image values.

func WithImageResponseDebugHook 

func WithImageResponseDebugHook(hook ImageResponseDebugHook) ImageOption

WithImageResponseDebugHook adds a safe image response debug hook.

func WithImageSuppressedHeader added in v0.6.0 

func WithImageSuppressedHeader(key string) ImageOption

WithImageSuppressedHeader removes a final outgoing image request header.

func WithImageSuppressedHeaders added in v0.6.0 

func WithImageSuppressedHeaders(keys ...string) ImageOption

WithImageSuppressedHeaders removes final outgoing image request headers.

func WithImageTimeout 

func WithImageTimeout(timeout time.Duration) ImageOption

WithImageTimeout configures the per-request image provider timeout.

type ImagePayloadDebug 

type ImagePayloadDebug struct {
	Provider       ProviderID
	API            ImageAPI
	Model          ModelID
	Headers        http.Header
	Payload        []byte
	PayloadPreview string
}

ImagePayloadDebug is the diagnostic view passed to image payload hooks.

type ImagePayloadDebugHook 

type ImagePayloadDebugHook func(context.Context, ImagePayloadDebug) error

ImagePayloadDebugHook inspects a redacted copy of an image provider payload.

Hooks run after provider payload and headers are built and before the HTTP request is sent. Payload replacement is intentionally unsupported: Payload is a redacted copy for diagnostics, so mutating it cannot change the request body or corrupt a later retry attempt.

type ImageProvider 

type ImageProvider interface {
	API() ImageAPI
	Generate(context.Context, ImageModel, ImageRequest, Options) (AssistantImages, error)
}

ImageProvider adapts a provider API into sigma's image generation interface.

type ImageQuality 

type ImageQuality string

ImageQuality identifies a provider-neutral generated image quality. 

const (
	// ImageQualityLow requests a lower-cost image where the provider supports it.
	ImageQualityLow ImageQuality = "low"
	// ImageQualityMedium requests a balanced image quality where the provider supports it.
	ImageQualityMedium ImageQuality = "medium"
	// ImageQualityHigh requests a higher-quality image where the provider supports it.
	ImageQualityHigh ImageQuality = "high"
)

type ImageRequest 

type ImageRequest struct {
	Model            ModelID        `json:"model,omitempty"`
	Provider         ProviderID     `json:"provider,omitempty"`
	Operation        ImageOperation `json:"operation,omitempty"`
	Prompt           string         `json:"prompt,omitempty"`
	Inputs           []ImageInput   `json:"inputs,omitempty"`
	Mask             *ImageInput    `json:"mask,omitempty"`
	Size             string         `json:"size,omitempty"`
	Quality          string         `json:"quality,omitempty"`
	MIMEType         string         `json:"mimeType,omitempty"`
	Count            int            `json:"count,omitempty"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

ImageRequest is the provider-neutral input for image generation.

This is separate from image inputs in chat/completion requests. Chat image input uses ContentBlock values built with ImageBase64 or ImageURL; image generation uses ImageInput values and returns AssistantImages.

type ImageResponseDebug 

type ImageResponseDebug struct {
	Provider   ProviderID
	API        ImageAPI
	Model      ModelID
	StatusCode int
	Headers    http.Header
	RequestID  string
}

ImageResponseDebug is the diagnostic view passed to image response hooks.

type ImageResponseDebugHook 

type ImageResponseDebugHook func(context.Context, ImageResponseDebug) error

ImageResponseDebugHook inspects redacted image response metadata before the response body is consumed.

type ImageSize 

type ImageSize string

ImageSize identifies a provider-neutral generated image size. 

const (
	// ImageSize1024x1024 requests a square image where the provider supports it.
	ImageSize1024x1024 ImageSize = "1024x1024"
	// ImageSize1024x1536 requests a portrait image where the provider supports it.
	ImageSize1024x1536 ImageSize = "1024x1536"
	// ImageSize1536x1024 requests a landscape image where the provider supports it.
	ImageSize1536x1024 ImageSize = "1536x1024"
)

type ImageStream added in v0.3.0 

type ImageStream struct {
	// contains filtered or unexported fields
}

ImageStream is a single-consumer stream of ordered image provider events.

func StreamImages added in v0.3.0 

func StreamImages(ctx context.Context, model ImageModel, req ImageRequest, opts ...ImageOption) *ImageStream

StreamImages starts a streaming image provider call using the default registry.

func (*ImageStream) Close added in v0.3.0 

func (s *ImageStream) Close()

Close stops the image stream without waiting for a provider terminal event.

func (*ImageStream) Done added in v0.3.0 

func (s *ImageStream) Done() <-chan struct{}

Done closes after Events closes.

func (*ImageStream) Err added in v0.3.0 

func (s *ImageStream) Err() error

Err returns the terminal image stream error, if any.

func (*ImageStream) Events added in v0.3.0 

func (s *ImageStream) Events() <-chan ImageEvent

Events returns the ordered image stream events.

func (*ImageStream) Final added in v0.3.0 

func (s *ImageStream) Final() (AssistantImages, bool)

Final returns the terminal image response, if the stream recorded one.

type ImageStreamWriter added in v0.3.0 

type ImageStreamWriter interface {
	Emit(context.Context, ImageEvent) error
	Done(context.Context, AssistantImages) error
	Error(context.Context, error, AssistantImages) error
	Close()
}

ImageStreamWriter is the provider side of an ImageStream.

type InMemoryCredentialStore added in v0.6.0 

type InMemoryCredentialStore struct {
	// contains filtered or unexported fields
}

InMemoryCredentialStore is a process-local CredentialStore implementation.

func NewInMemoryCredentialStore added in v0.6.0 

func NewInMemoryCredentialStore() *InMemoryCredentialStore

NewInMemoryCredentialStore constructs an empty in-memory credential store.

func (*InMemoryCredentialStore) DeleteCredential added in v0.6.0 

func (s *InMemoryCredentialStore) DeleteCredential(_ context.Context, provider ProviderID) error

DeleteCredential removes a provider credential.

func (*InMemoryCredentialStore) ModifyCredential added in v0.6.0 

func (s *InMemoryCredentialStore) ModifyCredential(ctx context.Context, provider ProviderID, fn CredentialModifyFunc) (StoredCredential, bool, error)

ModifyCredential serializes read-modify-write operations for one provider.

func (*InMemoryCredentialStore) ReadCredential added in v0.6.0 

func (s *InMemoryCredentialStore) ReadCredential(_ context.Context, provider ProviderID) (StoredCredential, bool, error)

ReadCredential returns a copied credential for provider.

type InMemoryRetrievalIndex added in v0.3.0 

type InMemoryRetrievalIndex struct {
	// contains filtered or unexported fields
}

InMemoryRetrievalIndex stores normalized embedding vectors in process memory.

func NewInMemoryRetrievalIndex added in v0.3.0 

func NewInMemoryRetrievalIndex(client *Client, model EmbeddingModel, config InMemoryRetrievalIndexConfig, opts ...EmbeddingOption) *InMemoryRetrievalIndex

NewInMemoryRetrievalIndex constructs an in-memory embedding-backed retrieval index.

func (*InMemoryRetrievalIndex) AddChunks added in v0.3.0 

func (i *InMemoryRetrievalIndex) AddChunks(ctx context.Context, chunks []RetrievalChunk) error

AddChunks embeds and indexes caller-supplied chunks as document inputs.

func (*InMemoryRetrievalIndex) AddDocuments added in v0.3.0 

func (i *InMemoryRetrievalIndex) AddDocuments(ctx context.Context, docs []RetrievalDocument) error

AddDocuments splits, embeds, and indexes documents as document inputs.

func (*InMemoryRetrievalIndex) Search added in v0.3.0 

func (i *InMemoryRetrievalIndex) Search(ctx context.Context, query string, limit int) ([]RetrievalResult, error)

Search embeds query as a query input and returns cosine-ranked chunks.

type InMemoryRetrievalIndexConfig added in v0.3.0 

type InMemoryRetrievalIndexConfig struct {
	Splitter   RetrievalSplitterConfig
	Batch      EmbeddingBatchConfig
	Dimensions int
}

InMemoryRetrievalIndexConfig configures an in-memory embedding-backed index.

type Message 

type Message struct {
	Role           Role           `json:"role"`
	Content        []ContentBlock `json:"content,omitempty"`
	ToolCallID     string         `json:"toolCallID,omitempty"`
	ToolName       string         `json:"toolName,omitempty"`
	AddedToolNames []string       `json:"addedToolNames,omitempty"`
	IsError        bool           `json:"isError,omitempty"`
	Provider       ProviderID     `json:"provider,omitempty"`
	API            API            `json:"api,omitempty"`
	Model          ModelID        `json:"model,omitempty"`
	StopReason     StopReason     `json:"stopReason,omitempty"`
	Usage          *Usage         `json:"usage,omitempty"`
}

Message is a conversation message discriminated by Role.

User, developer, and assistant messages use Content. Tool-result messages use Content plus ToolCallID, optional AddedToolNames, and IsError. Provider, API, Model, and StopReason preserve assistant provenance for later cross-provider replay. Go cannot make those role-specific fields impossible to combine in a plain struct, so callers should prefer UserText, UserContent, ToolResult, and ToolError when constructing persisted conversations.

func ToolError 

func ToolError(toolCallID string, text string) Message

ToolError constructs a failed tool-result message.

func ToolResult 

func ToolResult(toolCallID string, text string) Message

ToolResult constructs a successful tool-result message.

func UserContent 

func UserContent(blocks ...ContentBlock) Message

UserContent constructs a user message from content blocks.

func UserText 

func UserText(text string) Message

UserText constructs a user message with a single text block.

type MistralOptions added in v0.5.0 

type MistralOptions struct {
	ToolChoice *MistralToolChoice
}

MistralOptions carries Mistral-specific request options known to the root package without importing the provider adapter.

type MistralToolChoice added in v0.5.0 

type MistralToolChoice struct {
	Type MistralToolChoiceType `json:"type"`
	Name string                `json:"name,omitempty"`
}

MistralToolChoice carries Mistral Conversations tool choice controls.

type MistralToolChoiceType added in v0.5.0 

type MistralToolChoiceType string

MistralToolChoiceType identifies Mistral Conversations tool selection behavior. 

const (
	// MistralToolChoiceAuto lets Mistral choose whether to call a tool.
	MistralToolChoiceAuto MistralToolChoiceType = "auto"
	// MistralToolChoiceAny asks Mistral to call one of the supplied tools.
	MistralToolChoiceAny MistralToolChoiceType = "any"
	// MistralToolChoiceNone prevents Mistral from calling tools.
	MistralToolChoiceNone MistralToolChoiceType = "none"
	// MistralToolChoiceRequired requires Mistral to call one of the supplied tools.
	MistralToolChoiceRequired MistralToolChoiceType = "required"
	// MistralToolChoiceTool requires Mistral to call the named function.
	MistralToolChoiceTool MistralToolChoiceType = "function"
)

type Model 

type Model struct {
	ID                            ModelID                  `json:"id"`
	Provider                      ProviderID               `json:"provider"`
	API                           API                      `json:"api,omitempty"`
	Name                          string                   `json:"name,omitempty"`
	ContextWindow                 int                      `json:"contextWindow,omitempty"`
	MaxOutputTokens               int                      `json:"maxOutputTokens,omitempty"`
	SupportedInputs               []ContentBlockType       `json:"supportedInputs,omitempty"`
	SupportsTools                 bool                     `json:"supportsTools,omitempty"`
	SupportsThinking              bool                     `json:"supportsThinking,omitempty"`
	ThinkingLevels                []ThinkingLevel          `json:"thinkingLevels,omitempty"`
	ThinkingLevelMap              map[ThinkingLevel]string `json:"thinkingLevelMap,omitempty"`
	UnsupportedThinkingLevels     []ThinkingLevel          `json:"unsupportedThinkingLevels,omitempty"`
	InputCostPerMillion           float64                  `json:"inputCostPerMillion,omitempty"`
	OutputCostPerMillion          float64                  `json:"outputCostPerMillion,omitempty"`
	CacheReadInputCostPerMillion  float64                  `json:"cacheReadInputCostPerMillion,omitempty"`
	CacheWriteInputCostPerMillion float64                  `json:"cacheWriteInputCostPerMillion,omitempty"`
	CostTiers                     []ModelCostTier          `json:"costTiers,omitempty"`
	CostCurrency                  string                   `json:"costCurrency,omitempty"`
	DefaultTransport              Transport                `json:"defaultTransport,omitempty"`
	// OpenAICompletionsCompat overrides provider/base-URL compatibility
	// detection for OpenAI Chat Completions-compatible custom models.
	OpenAICompletionsCompat *OpenAICompletionsCompat `json:"openAICompletionsCompat,omitempty"`
	// AnthropicMessagesCompat overrides provider/base-URL compatibility
	// detection for Anthropic Messages-compatible custom models.
	AnthropicMessagesCompat *AnthropicMessagesCompat `json:"anthropicMessagesCompat,omitempty"`
	// OpenAIResponsesCompat configures compatibility behavior for OpenAI
	// Responses models. Leave nil for the default conservative behavior.
	OpenAIResponsesCompat *OpenAIResponsesCompat `json:"openAIResponsesCompat,omitempty"`
	// AzureOpenAIResponses configures Azure OpenAI Responses models. Leave nil
	// for non-Azure models.
	AzureOpenAIResponses *AzureOpenAIResponsesConfig `json:"azureOpenAIResponses,omitempty"`
	// OpenAICodexResponses configures OpenAI Codex Responses models. Leave nil
	// for non-Codex models.
	OpenAICodexResponses *OpenAICodexResponsesConfig `json:"openAICodexResponses,omitempty"`
	ProviderMetadata     map[string]any              `json:"providerMetadata,omitempty"`
}

Model describes a provider model available through sigma.

func GetModel 

func GetModel(provider ProviderID, id ModelID) (Model, bool)

GetModel returns a text model from the default registry.

func Models 

func Models(filters ...ModelFilter) []Model

Models returns text models from the default registry matching all filters.

func OpenAICompatibleModel 

func OpenAICompatibleModel(config OpenAICompatibleModelConfig) Model

OpenAICompatibleModel constructs metadata for an OpenAI Chat Completions-compatible model. Register the returned model on the same registry as an openai.Provider, then pass that registry to NewClient with WithRegistry for an isolated setup.

func (Model) ProviderThinkingLevel 

func (model Model) ProviderThinkingLevel(level ThinkingLevel) (string, bool)

ProviderThinkingLevel returns the provider-specific value for level. If a model only lists supported levels, the provider value is the level text.

func (Model) SupportsDocuments added in v0.6.0 

func (model Model) SupportsDocuments() bool

SupportsDocuments reports whether model accepts document content as input.

func (Model) SupportsImages 

func (model Model) SupportsImages() bool

SupportsImages reports whether model accepts image content as input.

func (Model) SupportsInput 

func (model Model) SupportsInput(kind ContentBlockType) bool

SupportsInput reports whether model metadata allows a request content kind. Models with no explicit input list are treated as text-only for backwards compatibility with earlier metadata.

func (Model) SupportsReasoning 

func (model Model) SupportsReasoning() bool

SupportsReasoning reports whether model metadata advertises provider reasoning or thinking support.

func (Model) SupportsThinkingLevel 

func (model Model) SupportsThinkingLevel(level ThinkingLevel) bool

SupportsThinkingLevel reports whether level can be requested for model.

type ModelCostTier added in v0.6.0 

type ModelCostTier struct {
	InputTokensAbove              int     `json:"inputTokensAbove"`
	InputCostPerMillion           float64 `json:"inputCostPerMillion"`
	OutputCostPerMillion          float64 `json:"outputCostPerMillion"`
	CacheReadInputCostPerMillion  float64 `json:"cacheReadInputCostPerMillion,omitempty"`
	CacheWriteInputCostPerMillion float64 `json:"cacheWriteInputCostPerMillion,omitempty"`
}

ModelCostTier specifies request-wide model rates above an input threshold. The highest strictly exceeded threshold applies to the whole request.

type ModelFilter 

type ModelFilter func(Model) bool

ModelFilter reports whether a model should be included in a model list.

type ModelID 

type ModelID string

ModelID identifies a provider-specific model.

type ModelRef 

type ModelRef struct {
	Provider ProviderID `json:"provider"`
	ID       ModelID    `json:"id"`
}

ModelRef identifies a provider-specific model.

type OAuthAuth added in v0.6.0 

type OAuthAuth struct {
	Name          string
	RefreshBefore time.Duration
	Refresh       OAuthRefreshFunc
	Credential    OAuthCredentialFunc
}

OAuthAuth describes a provider OAuth credential flow.

type OAuthCredentialFunc added in v0.6.0 

type OAuthCredentialFunc func(context.Context, Model, Options, StoredCredential) (Credential, error)

OAuthCredentialFunc converts stored OAuth credentials into request credentials.

type OAuthRefreshFunc added in v0.6.0 

type OAuthRefreshFunc func(context.Context, StoredCredential) (StoredCredential, error)

OAuthRefreshFunc refreshes stored OAuth credentials.

type OAuthTokenProvider 

type OAuthTokenProvider interface {
	Token(context.Context, Model, Options) (Credential, error)
}

OAuthTokenProvider provides OAuth tokens for a provider adapter.

type OAuthTokenProviderFunc 

type OAuthTokenProviderFunc func(context.Context, Model, Options) (Credential, error)

OAuthTokenProviderFunc adapts a function into an OAuthTokenProvider.

func (OAuthTokenProviderFunc) Token 

func (f OAuthTokenProviderFunc) Token(ctx context.Context, model Model, opts Options) (Credential, error)

Token calls f.

type OpenAICodexResponsesConfig 

type OpenAICodexResponsesConfig struct {
	Model              string `json:"model,omitempty"`
	SupportsToolSearch bool   `json:"supportsToolSearch,omitempty"`
}

OpenAICodexResponsesConfig carries Codex-specific Responses metadata. Model is the model name sent to OpenAI when it differs from sigma's model ID.

type OpenAICompatSupport 

type OpenAICompatSupport string

OpenAICompatSupport identifies whether an OpenAI-compatible feature is known to be supported by a provider or endpoint. 

const (
	// OpenAICompatDefault uses provider and endpoint defaults.
	OpenAICompatDefault OpenAICompatSupport = ""
	// OpenAICompatSupported forces a compatibility feature on.
	OpenAICompatSupported OpenAICompatSupport = "supported"
	// OpenAICompatUnsupported forces a compatibility feature off.
	OpenAICompatUnsupported OpenAICompatSupport = "unsupported"
)

type OpenAICompatibleEmbeddingModelConfig added in v0.3.0 

type OpenAICompatibleEmbeddingModelConfig struct {
	ID                  ModelID
	Provider            ProviderID
	BaseURL             string
	Name                string
	Headers             map[string]string
	DefaultDimensions   int
	MinDimensions       int
	MaxDimensions       int
	MaxInputTokens      int
	MaxBatchInputs      int
	MaxBatchBytes       int
	InputCostPerMillion float64
	CostCurrency        string
	ProviderMetadata    map[string]any
}

OpenAICompatibleEmbeddingModelConfig configures OpenAICompatibleEmbeddingModel.

type OpenAICompatibleModelConfig 

type OpenAICompatibleModelConfig struct {
	ID                            ModelID
	Provider                      ProviderID
	BaseURL                       string
	Name                          string
	Headers                       map[string]string
	ContextWindow                 int
	MaxOutputTokens               int
	SupportedInputs               []ContentBlockType
	SupportsTools                 bool
	SupportsThinking              bool
	ThinkingLevels                []ThinkingLevel
	ThinkingLevelMap              map[ThinkingLevel]string
	UnsupportedThinkingLevels     []ThinkingLevel
	InputCostPerMillion           float64
	OutputCostPerMillion          float64
	CacheReadInputCostPerMillion  float64
	CacheWriteInputCostPerMillion float64
	CostTiers                     []ModelCostTier
	CostCurrency                  string
	DefaultTransport              Transport
	OpenAICompletionsCompat       *OpenAICompletionsCompat
	ProviderMetadata              map[string]any
}

OpenAICompatibleModelConfig configures OpenAICompatibleModel.

type OpenAICompletionsCacheControlFormat 

type OpenAICompletionsCacheControlFormat string

OpenAICompletionsCacheControlFormat identifies how prompt cache markers are encoded by an OpenAI Chat Completions-compatible endpoint. 

const (
	// OpenAICompletionsCacheControlDefault uses provider and endpoint defaults.
	OpenAICompletionsCacheControlDefault OpenAICompletionsCacheControlFormat = ""
	// OpenAICompletionsCacheControlUnsupported suppresses cache-control fields.
	OpenAICompletionsCacheControlUnsupported OpenAICompletionsCacheControlFormat = "unsupported"
	// OpenAICompletionsCacheControlMessage sends cache_control beside message content.
	OpenAICompletionsCacheControlMessage OpenAICompletionsCacheControlFormat = "message"
	// OpenAICompletionsCacheControlContentPart sends cache_control on content parts.
	OpenAICompletionsCacheControlContentPart OpenAICompletionsCacheControlFormat = "content-part"
	// OpenAICompletionsCacheControlAnthropic sends Anthropic-style cache markers
	// on the instruction message, last tool, and last conversation message.
	OpenAICompletionsCacheControlAnthropic OpenAICompletionsCacheControlFormat = "anthropic"
)

type OpenAICompletionsCompat 

type OpenAICompletionsCompat struct {
	SupportsStore                               OpenAICompatSupport                 `json:"supportsStore,omitempty"`
	SupportsDeveloperRole                       OpenAICompatSupport                 `json:"supportsDeveloperRole,omitempty"`
	ReasoningFormat                             OpenAICompletionsReasoningFormat    `json:"reasoningFormat,omitempty"`
	SupportsReasoningEffort                     OpenAICompatSupport                 `json:"supportsReasoningEffort,omitempty"`
	SupportsStreamingUsage                      OpenAICompatSupport                 `json:"supportsStreamingUsage,omitempty"`
	SupportsStrictTools                         OpenAICompatSupport                 `json:"supportsStrictTools,omitempty"`
	SupportsRequiredToolChoice                  OpenAICompatSupport                 `json:"supportsRequiredToolChoice,omitempty"`
	SupportsToolStream                          OpenAICompatSupport                 `json:"supportsToolStream,omitempty"`
	SupportsGrammarTools                        OpenAICompatSupport                 `json:"supportsGrammarTools,omitempty"`
	SupportsJSONSchemaResponseFormat            OpenAICompatSupport                 `json:"supportsJSONSchemaResponseFormat,omitempty"`
	MaxTokensField                              OpenAICompletionsMaxTokensField     `json:"maxTokensField,omitempty"`
	CacheControlFormat                          OpenAICompletionsCacheControlFormat `json:"cacheControlFormat,omitempty"`
	SupportsSessionAffinity                     OpenAICompatSupport                 `json:"supportsSessionAffinity,omitempty"`
	SupportsLongCacheRetention                  OpenAICompatSupport                 `json:"supportsLongCacheRetention,omitempty"`
	RequiresToolResultName                      OpenAICompatSupport                 `json:"requiresToolResultName,omitempty"`
	RequiresAssistantAfterToolResult            OpenAICompatSupport                 `json:"requiresAssistantAfterToolResult,omitempty"`
	RequiresToolsForToolHistory                 OpenAICompatSupport                 `json:"requiresToolsForToolHistory,omitempty"`
	RequiresReasoningContentOnAssistantMessages OpenAICompatSupport                 `json:"requiresReasoningContentOnAssistantMessages,omitempty"`
	OpenRouterRouting                           *OpenRouterRoutingPreference        `json:"openRouterRouting,omitempty"`
	VercelAIGatewayRouting                      *VercelAIGatewayRoutingPreference   `json:"vercelAIGatewayRouting,omitempty"`
}

OpenAICompletionsCompat describes Chat Completions compatibility differences for routers and local OpenAI-compatible endpoints. Leave fields at their zero value to use provider or base-URL detection, or set them when registering a custom model to override conservative defaults.

type OpenAICompletionsMaxTokensField 

type OpenAICompletionsMaxTokensField string

OpenAICompletionsMaxTokensField identifies the token-limit field name used by an OpenAI Chat Completions-compatible endpoint. 

const (
	// OpenAICompletionsMaxTokensDefault uses provider and endpoint defaults.
	OpenAICompletionsMaxTokensDefault OpenAICompletionsMaxTokensField = ""
	// OpenAICompletionsMaxTokens sends max_tokens.
	OpenAICompletionsMaxTokens OpenAICompletionsMaxTokensField = "max_tokens"
	// OpenAICompletionsMaxCompletionTokens sends max_completion_tokens.
	OpenAICompletionsMaxCompletionTokens OpenAICompletionsMaxTokensField = "max_completion_tokens"
)

type OpenAICompletionsReasoningFormat 

type OpenAICompletionsReasoningFormat string

OpenAICompletionsReasoningFormat identifies how reasoning effort is encoded by an OpenAI Chat Completions-compatible endpoint. 

const (
	// OpenAICompletionsReasoningDefault uses provider and endpoint defaults.
	OpenAICompletionsReasoningDefault OpenAICompletionsReasoningFormat = ""
	// OpenAICompletionsReasoningUnsupported suppresses reasoning fields.
	OpenAICompletionsReasoningUnsupported OpenAICompletionsReasoningFormat = "unsupported"
	// OpenAICompletionsReasoningEffort sends reasoning_effort.
	OpenAICompletionsReasoningEffort OpenAICompletionsReasoningFormat = "reasoning_effort"
	// OpenAICompletionsReasoningObject sends a reasoning object.
	OpenAICompletionsReasoningObject OpenAICompletionsReasoningFormat = "reasoning"
	// OpenAICompletionsReasoningFireworks sends reasoning_effort for levels
	// and the Fireworks thinking object for explicit token budgets.
	OpenAICompletionsReasoningFireworks OpenAICompletionsReasoningFormat = "fireworks"
	// OpenAICompletionsReasoningDeepSeek sends a thinking object plus
	// reasoning_effort when reasoning is enabled.
	OpenAICompletionsReasoningDeepSeek OpenAICompletionsReasoningFormat = "deepseek"
	// OpenAICompletionsReasoningStringThinking sends a top-level thinking
	// string such as "none" or a provider-specific level.
	OpenAICompletionsReasoningStringThinking OpenAICompletionsReasoningFormat = "string-thinking"
	// OpenAICompletionsReasoningTogether sends Together's reasoning toggle
	// plus optional reasoning_effort.
	OpenAICompletionsReasoningTogether OpenAICompletionsReasoningFormat = "together"
	// OpenAICompletionsReasoningQwen sends a top-level Qwen enable_thinking flag.
	OpenAICompletionsReasoningQwen OpenAICompletionsReasoningFormat = "qwen"
	// OpenAICompletionsReasoningZAI sends a Z.ai thinking object with an
	// enabled or disabled type.
	OpenAICompletionsReasoningZAI OpenAICompletionsReasoningFormat = "zai"
	// OpenAICompletionsReasoningAntLing sends Ant Ling's reasoning object only
	// for explicitly supported effort levels.
	OpenAICompletionsReasoningAntLing OpenAICompletionsReasoningFormat = "ant-ling"
)

type OpenAIGrammar added in v0.7.0 

type OpenAIGrammar struct {
	Syntax     OpenAIGrammarSyntax `json:"syntax"`
	Definition string              `json:"definition"`
}

OpenAIGrammar configures an OpenAI custom tool grammar.

type OpenAIGrammarSyntax added in v0.7.0 

type OpenAIGrammarSyntax string

OpenAIGrammarSyntax identifies the grammar format accepted by OpenAI custom tools. 

const (
	// OpenAIGrammarLark identifies a Lark grammar definition.
	OpenAIGrammarLark OpenAIGrammarSyntax = "lark"
	// OpenAIGrammarRegex identifies a regular-expression grammar definition.
	OpenAIGrammarRegex OpenAIGrammarSyntax = "regex"
)

type OpenAIOptions 

type OpenAIOptions struct {
	ReasoningEffort              ThinkingLevel
	ReasoningSummary             string
	ServiceTier                  string
	ToolChoice                   any
	ResponseFormat               any
	TopLogprobs                  int
	PromptCacheRetention         string
	ParallelToolCalls            *bool
	EnableGrammarTools           *bool
	TextVerbosity                string
	CodexWebSocketConnectTimeout *time.Duration
}

OpenAIOptions carries OpenAI-specific request options known to the root package without importing provider adapters.

type OpenAIResponsesCompat added in v0.6.0 

type OpenAIResponsesCompat struct {
	SupportsToolSearch              bool                                 `json:"supportsToolSearch,omitempty"`
	SupportsGrammarTools            bool                                 `json:"supportsGrammarTools,omitempty"`
	SupportsExplicitPromptCacheMode bool                                 `json:"supportsExplicitPromptCacheMode,omitempty"`
	SupportsLongCacheRetention      OpenAICompatSupport                  `json:"supportsLongCacheRetention,omitempty"`
	SessionAffinityFormat           OpenAIResponsesSessionAffinityFormat `json:"sessionAffinityFormat,omitempty"`
}

OpenAIResponsesCompat describes OpenAI Responses API capabilities that vary by model or compatible endpoint.

type OpenAIResponsesSessionAffinityFormat added in v0.6.0 

type OpenAIResponsesSessionAffinityFormat string

OpenAIResponsesSessionAffinityFormat describes how cached Responses requests identify an affinity session. 

const (
	// OpenAIResponsesSessionAffinityOpenAINoSession sends an OpenAI-compatible
	// request ID without sending the OpenAI session_id header.
	OpenAIResponsesSessionAffinityOpenAINoSession OpenAIResponsesSessionAffinityFormat = "openai-nosession"
)

type OpenRouterRoutingPreference 

type OpenRouterRoutingPreference struct {
	Order                  []string       `json:"order,omitempty"`
	Only                   []string       `json:"only,omitempty"`
	Ignore                 []string       `json:"ignore,omitempty"`
	AllowFallbacks         *bool          `json:"allow_fallbacks,omitempty"`
	RequireParameters      *bool          `json:"require_parameters,omitempty"`
	DataCollection         string         `json:"data_collection,omitempty"`
	ZDR                    *bool          `json:"zdr,omitempty"`
	EnforceDistillableText *bool          `json:"enforce_distillable_text,omitempty"`
	Quantizations          []string       `json:"quantizations,omitempty"`
	MaxPrice               map[string]any `json:"max_price,omitempty"`
	PreferredMinThroughput any            `json:"preferred_min_throughput,omitempty"`
	PreferredMaxLatency    any            `json:"preferred_max_latency,omitempty"`
	Sort                   any            `json:"sort,omitempty"`
}

OpenRouterRoutingPreference describes OpenRouter's provider routing request body.

type Option 

type Option func(*Options)

Option configures a single provider request.

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey configures a request-scoped API key override.

API key overrides are intentionally not retained by WithDefaultOptions.

func WithAnthropicOptions 

func WithAnthropicOptions(anthropicOptions AnthropicOptions) Option

WithAnthropicOptions configures known Anthropic-specific request options.

func WithAutomaticMaxTokensForContext added in v0.6.0 

func WithAutomaticMaxTokensForContext(enabled bool) Option

WithAutomaticMaxTokensForContext configures dispatch-time max token budgeting from model context metadata and EstimateRequestTokens.

func WithBedrockOptions added in v0.2.0 

func WithBedrockOptions(bedrockOptions BedrockOptions) Option

WithBedrockOptions configures known Bedrock-specific request options.

func WithCacheRetention 

func WithCacheRetention(retention CacheRetention) Option

WithCacheRetention configures provider-side prompt cache retention.

func WithGoogleOptions 

func WithGoogleOptions(googleOptions GoogleOptions) Option

WithGoogleOptions configures known Google-specific request options.

func WithHeader 

func WithHeader(key, value string) Option

WithHeader adds or replaces a request header.

func WithHeaders 

func WithHeaders(headers map[string]string) Option

WithHeaders adds or replaces request headers.

func WithJSONOutput added in v0.6.0 

func WithJSONOutput() Option

WithJSONOutput asks the provider to return any JSON object.

func WithJSONSchemaOutput added in v0.6.0 

func WithJSONSchemaOutput(name string, schema any, strict bool) Option

WithJSONSchemaOutput asks the provider to return JSON matching schema.

func WithMaxRetries 

func WithMaxRetries(maxRetries int) Option

WithMaxRetries configures the maximum HTTP provider retry attempts after the first request. The default is DefaultMaxRetries.

func WithMaxRetryDelay 

func WithMaxRetryDelay(maxRetryDelay time.Duration) Option

WithMaxRetryDelay configures the maximum delay between HTTP provider retries, including provider Retry-After values. The default is DefaultMaxRetryDelay.

func WithMaxTokens 

func WithMaxTokens(maxTokens int) Option

WithMaxTokens configures the maximum output tokens for a request.

func WithMaxTokensForContext added in v0.6.0 

func WithMaxTokensForContext(model Model, req Request, requestedMaxTokens int) Option

WithMaxTokensForContext configures MaxTokens from MaxTokensForContext.

If MaxTokensForContext returns zero, this option leaves MaxTokens unset.

func WithMetadata 

func WithMetadata(metadata map[string]any) Option

WithMetadata adds or replaces provider-neutral request metadata.

func WithMetadataValue 

func WithMetadataValue(key string, value any) Option

WithMetadataValue adds or replaces one provider-neutral metadata value.

func WithMistralOptions added in v0.5.0 

func WithMistralOptions(mistralOptions MistralOptions) Option

WithMistralOptions configures known Mistral-specific request options.

func WithOpenAIOptions 

func WithOpenAIOptions(openAIOptions OpenAIOptions) Option

WithOpenAIOptions configures known OpenAI-specific request options.

func WithProviderAuthResolver 

func WithProviderAuthResolver(provider ProviderID, resolver AuthResolver) Option

WithProviderAuthResolver configures a provider-specific credential callback.

func WithProviderOption 

func WithProviderOption(provider ProviderID, key string, value any) Option

WithProviderOption adds or replaces one advanced provider-specific value.

func WithProviderOptions 

func WithProviderOptions(provider ProviderID, values map[string]any) Option

WithProviderOptions adds or replaces advanced provider-specific values.

func WithReasoningBudgetForContext added in v0.6.0 

func WithReasoningBudgetForContext(model Model, req Request, level ThinkingLevel, requestedMaxTokens int) Option

WithReasoningBudgetForContext configures ReasoningLevel, MaxTokens, and ThinkingBudgetTokens from ReasoningBudgetForContext.

If ReasoningBudgetForContext returns zero values, this option only applies the requested reasoning level.

func WithReasoningLevel 

func WithReasoningLevel(level ThinkingLevel) Option

WithReasoningLevel configures a provider-neutral reasoning level.

func WithRequestHTTPClient added in v0.7.0 

func WithRequestHTTPClient(httpClient *http.Client) Option

WithRequestHTTPClient configures an HTTP client for a text request.

A non-nil request client takes precedence over configured client and provider fallback clients. A nil client retains the existing fallback behavior. This option applies to HTTP and SSE dispatch; WebSocket transports keep their existing dialing behavior.

func WithSessionID 

func WithSessionID(sessionID string) Option

WithSessionID configures a provider conversation or response session id.

func WithStructuredOutput added in v0.6.0 

func WithStructuredOutput(output StructuredOutput) Option

WithStructuredOutput requests provider-neutral structured output.

func WithSuppressedHeader added in v0.6.0 

func WithSuppressedHeader(key string) Option

WithSuppressedHeader removes a final outgoing request header by name.

Suppression applies after provider, model, and caller headers are merged. Credential-bearing auth headers are not suppressed.

func WithSuppressedHeaders added in v0.6.0 

func WithSuppressedHeaders(keys ...string) Option

WithSuppressedHeaders removes final outgoing request headers by name.

Header names are matched case-insensitively. Empty names are ignored.

func WithTemperature 

func WithTemperature(temperature float64) Option

WithTemperature configures sampling temperature for a request.

func WithTextPayloadDebugHook 

func WithTextPayloadDebugHook(hook TextPayloadDebugHook) Option

WithTextPayloadDebugHook adds a safe text request payload debug hook.

Example 
package main

import (
	"context"

	"github.com/wintermi/sigma"
)

func main() {
	_ = sigma.WithTextPayloadDebugHook(func(_ context.Context, debug sigma.TextPayloadDebug) error {
		_ = debug.PayloadPreview
		return nil
	})
}

func WithTextResponseDebugHook 

func WithTextResponseDebugHook(hook TextResponseDebugHook) Option

WithTextResponseDebugHook adds a safe text response debug hook.

func WithThinkingBudgetTokens 

func WithThinkingBudgetTokens(tokens int) Option

WithThinkingBudgetTokens configures a provider-neutral thinking budget.

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout configures the per-request provider timeout. Zero disables the request timeout; cancellation still follows the parent context.

func WithTopLogprobs added in v0.6.0 

func WithTopLogprobs(top int) Option

WithTopLogprobs requests top token log probabilities when the provider API supports them.

func WithTransport 

func WithTransport(transport Transport) Option

WithTransport configures the provider transport for a request.

type Options 

type Options struct {
	Temperature                  *float64
	MaxTokens                    *int
	AutomaticMaxTokensForContext *bool
	APIKey                       string
	HTTPClient                   *http.Client
	AuthResolver                 AuthResolver
	Transport                    Transport
	CacheRetention               CacheRetention
	SessionID                    string
	Headers                      map[string]string
	SuppressedHeaders            []string
	Timeout                      *time.Duration
	MaxRetries                   *int
	MaxRetryDelay                *time.Duration
	Metadata                     map[string]any
	ReasoningLevel               ThinkingLevel
	ThinkingBudgetTokens         *int
	StructuredOutput             *StructuredOutput
	TopLogprobs                  int
	ProviderOptions              map[ProviderID]map[string]any
	ProviderAuthResolvers        map[ProviderID]AuthResolver
	TextPayloadDebugHooks        []TextPayloadDebugHook
	TextResponseDebugHooks       []TextResponseDebugHook
	ImagePayloadDebugHooks       []ImagePayloadDebugHook
	ImageResponseDebugHooks      []ImageResponseDebugHook
	EmbeddingPayloadDebugHooks   []EmbeddingPayloadDebugHook
	EmbeddingResponseDebugHooks  []EmbeddingResponseDebugHook
	OpenAIOptions                *OpenAIOptions
	AnthropicOptions             *AnthropicOptions
	GoogleOptions                *GoogleOptions
	MistralOptions               *MistralOptions
	BedrockOptions               *BedrockOptions
}

Options configures a single provider request.

Client.Stream merges options in this order: client defaults, defaults from the selected model metadata, call options, then provider-specific extension values inside ProviderOptions. Provider packages may define their own helper option functions that populate ProviderOptions without changing this root package.

type PartialToolCall 

type PartialToolCall struct {
	ID                string         `json:"id,omitempty"`
	Name              string         `json:"name,omitempty"`
	ArgumentsDelta    string         `json:"argumentsDelta,omitempty"`
	ProviderSignature string         `json:"providerSignature,omitempty"`
	ProviderMetadata  map[string]any `json:"providerMetadata,omitempty"`
}

PartialToolCall describes an in-progress tool-call update.

type ProviderAuth added in v0.6.0 

type ProviderAuth struct {
	APIKey *APIKeyAuth
	OAuth  *OAuthAuth
}

ProviderAuth describes supported credential flows for one provider.

type ProviderAuthInfo added in v0.6.0 

type ProviderAuthInfo struct {
	ID     ProviderID `json:"id"`
	APIKey bool       `json:"apiKey,omitempty"`
	OAuth  bool       `json:"oauth,omitempty"`
}

ProviderAuthInfo is a copyable view of registered provider auth capabilities.

type ProviderError 

type ProviderError struct {
	Provider        ProviderID
	API             API
	Model           ModelID
	StatusCode      int
	RequestID       string
	ProviderCode    string
	ProviderMessage string
	RetryAfter      time.Duration
	MaxRetryDelay   time.Duration
	BodyPreview     string
	Err             error
}

ProviderError reports a failed provider API response without exposing raw payloads.

Provider implementations should map HTTP and provider failures to ProviderError and finish text streams with StopReasonError. Request cancellation should map to ErrAborted and StopReasonAborted instead of ProviderError.

func NewProviderError 

func NewProviderError(provider ProviderID, api API, model ModelID, statusCode int, requestID string, retryAfter time.Duration, body []byte, err error) *ProviderError

NewProviderError builds a provider response error with a redacted body preview.

func (*ProviderError) Diagnostic 

func (e *ProviderError) Diagnostic() Diagnostic

Diagnostic returns a redacted provider diagnostic suitable for an assistant message that ends with StopReasonError.

func (*ProviderError) Error 

func (e *ProviderError) Error() string

func (*ProviderError) Format 

func (e *ProviderError) Format(state fmt.State, verb rune)

Format prevents fmt from printing raw ProviderError fields with struct verbs.

func (*ProviderError) Is 

func (e *ProviderError) Is(target error) bool

Is supports errors.Is(err, ErrProviderResponse).

func (*ProviderError) String 

func (e *ProviderError) String() string

String returns the same diagnostic-safe text as Error.

func (*ProviderError) Unwrap 

func (e *ProviderError) Unwrap() error

Unwrap returns the underlying provider cause.

type ProviderID 

type ProviderID string

ProviderID identifies a model provider. 

const (
	// ProviderOpenAI identifies OpenAI.
	ProviderOpenAI ProviderID = "openai"
	// ProviderAzureOpenAIResponses identifies Azure OpenAI Responses.
	ProviderAzureOpenAIResponses ProviderID = "azure-openai-responses"
	// ProviderOpenAICodex identifies OpenAI Codex.
	ProviderOpenAICodex ProviderID = "openai-codex"
	// ProviderAnthropic identifies Anthropic.
	ProviderAnthropic ProviderID = "anthropic"
	// ProviderGoogle identifies Google Generative AI.
	ProviderGoogle ProviderID = "google"
	// ProviderGoogleVertex identifies Google Vertex AI.
	ProviderGoogleVertex ProviderID = "google-vertex"
	// ProviderGoogleVertexOpenAI identifies Vertex AI OpenAI-compatible MaaS.
	ProviderGoogleVertexOpenAI ProviderID = "google-vertex-openai"
	// ProviderGoogleVertexAnthropic identifies Anthropic Claude on Vertex AI.
	ProviderGoogleVertexAnthropic ProviderID = "google-vertex-anthropic"
	// ProviderMistral identifies Mistral AI.
	ProviderMistral ProviderID = "mistral"
	// ProviderRadius identifies the Radius gateway.
	ProviderRadius ProviderID = "radius"
	// ProviderAmazonBedrock identifies Amazon Bedrock.
	ProviderAmazonBedrock ProviderID = "amazon-bedrock"
	// ProviderOpenRouter identifies OpenRouter.
	ProviderOpenRouter ProviderID = "openrouter"
	// ProviderDeepSeek identifies DeepSeek.
	ProviderDeepSeek ProviderID = "deepseek"
	// ProviderGroq identifies Groq.
	ProviderGroq ProviderID = "groq"
	// ProviderCerebras identifies Cerebras.
	ProviderCerebras ProviderID = "cerebras"
	// ProviderXAI identifies xAI.
	ProviderXAI ProviderID = "xai"
	// ProviderTogether identifies Together AI.
	ProviderTogether ProviderID = "together"
	// ProviderHuggingFace identifies Hugging Face Router.
	ProviderHuggingFace ProviderID = "huggingface"
	// ProviderCloudflareAIGateway identifies Cloudflare AI Gateway.
	ProviderCloudflareAIGateway ProviderID = "cloudflare-ai-gateway"
	// ProviderCloudflareWorkersAI identifies Cloudflare Workers AI.
	ProviderCloudflareWorkersAI ProviderID = "cloudflare-workers-ai"
	// ProviderGitHubCopilot identifies GitHub Copilot.
	ProviderGitHubCopilot ProviderID = "github-copilot"
	// ProviderNVIDIA identifies NVIDIA NIM.
	ProviderNVIDIA ProviderID = "nvidia"
	// ProviderZAI identifies Z.ai.
	ProviderZAI ProviderID = "zai"
	// ProviderZAICodingCN identifies Z.ai Coding CN.
	ProviderZAICodingCN ProviderID = "zai-coding-cn"
	// ProviderAntLing identifies Ant Ling.
	ProviderAntLing ProviderID = "ant-ling"
	// ProviderMoonshotAI identifies Moonshot AI.
	ProviderMoonshotAI ProviderID = "moonshotai"
	// ProviderMoonshotAICN identifies Moonshot AI CN.
	ProviderMoonshotAICN ProviderID = "moonshotai-cn"
	// ProviderMiniMax identifies MiniMax.
	ProviderMiniMax ProviderID = "minimax"
	// ProviderMiniMaxCN identifies MiniMax CN.
	ProviderMiniMaxCN ProviderID = "minimax-cn"
	// ProviderVercelAIGateway identifies Vercel AI Gateway.
	ProviderVercelAIGateway ProviderID = "vercel-ai-gateway"
	// ProviderOpenCode identifies OpenCode Zen.
	ProviderOpenCode ProviderID = "opencode"
	// ProviderOpenCodeGo identifies OpenCode Go.
	ProviderOpenCodeGo ProviderID = "opencode-go"
	// ProviderFireworks identifies Fireworks AI.
	ProviderFireworks ProviderID = "fireworks"
	// ProviderFireworksAnthropic identifies Fireworks AI's Anthropic-compatible
	// Messages endpoint.
	ProviderFireworksAnthropic ProviderID = "fireworks-anthropic"
	// ProviderKimi identifies Kimi.
	ProviderKimi ProviderID = "kimi"
	// ProviderKimiCoding identifies Kimi Coding.
	ProviderKimiCoding ProviderID = "kimi-coding"
	// ProviderXiaomi identifies Xiaomi.
	ProviderXiaomi ProviderID = "xiaomi"
	// ProviderXiaomiTokenPlanCN identifies Xiaomi Token Plan CN.
	ProviderXiaomiTokenPlanCN ProviderID = "xiaomi-token-plan-cn"
	// ProviderXiaomiTokenPlanAMS identifies Xiaomi Token Plan AMS.
	ProviderXiaomiTokenPlanAMS ProviderID = "xiaomi-token-plan-ams"
	// ProviderXiaomiTokenPlanSGP identifies Xiaomi Token Plan SGP.
	ProviderXiaomiTokenPlanSGP ProviderID = "xiaomi-token-plan-sgp"
	// ProviderQwenTokenPlan identifies Qwen Token Plan.
	ProviderQwenTokenPlan ProviderID = "qwen-token-plan"
	// ProviderQwenTokenPlanCN identifies Qwen Token Plan China.
	ProviderQwenTokenPlanCN ProviderID = "qwen-token-plan-cn"
	// ProviderCustom identifies a user-defined provider path.
	ProviderCustom ProviderID = "custom"
)

type ProviderInfo 

type ProviderInfo struct {
	ID           ProviderID   `json:"id"`
	TextAPI      API          `json:"textApi,omitempty"`
	ImageAPI     ImageAPI     `json:"imageApi,omitempty"`
	EmbeddingAPI EmbeddingAPI `json:"embeddingApi,omitempty"`
}

ProviderInfo is a copyable view of registered provider capabilities.

type ReasoningBudget added in v0.6.0 

type ReasoningBudget struct {
	MaxTokens            int `json:"maxTokens,omitempty"`
	ThinkingBudgetTokens int `json:"thinkingBudgetTokens,omitempty"`
}

ReasoningBudget reports an opt-in output and thinking budget plan.

func ReasoningBudgetForContext added in v0.6.0 

func ReasoningBudgetForContext(model Model, req Request, level ThinkingLevel, requestedMaxTokens int) ReasoningBudget

ReasoningBudgetForContext returns an opt-in max output and thinking budget plan for req, model, and level.

requestedMaxTokens is treated as the caller's desired visible output cap when positive; otherwise model.MaxOutputTokens is used. Non-off reasoning levels reserve a thinking budget inside the final max token cap while preserving at least 1024 visible output tokens when possible. The helper uses EstimateRequestTokens and a fixed safety margin; it does not call provider tokenizers or affect dispatch unless the caller applies the returned values.

type RegisterOption 

type RegisterOption func(*registerOptions)

RegisterOption configures registry registration behavior.

func WithMetadataOnly 

func WithMetadataOnly() RegisterOption

WithMetadataOnly allows model metadata to be registered without a provider.

func WithOverride 

func WithOverride() RegisterOption

WithOverride allows a registration to replace an existing provider or model.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry stores provider implementations and model metadata.

func DefaultRegistry 

func DefaultRegistry() *Registry

DefaultRegistry returns a clone of the package-level default registry.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry constructs an isolated empty registry.

func (*Registry) Clone 

func (r *Registry) Clone() *Registry

Clone returns an isolated copy of the registry.

func (*Registry) EmbeddingModel added in v0.3.0 

func (r *Registry) EmbeddingModel(provider ProviderID, id ModelID) (EmbeddingModel, bool)

EmbeddingModel returns an embedding model by provider and model id.

func (*Registry) EmbeddingProvider added in v0.3.0 

func (r *Registry) EmbeddingProvider(id ProviderID) (EmbeddingProvider, bool)

EmbeddingProvider returns the registered embedding provider for id.

func (*Registry) ImageModel 

func (r *Registry) ImageModel(provider ProviderID, id ModelID) (ImageModel, bool)

ImageModel returns an image model by provider and model id.

func (*Registry) ImageProvider 

func (r *Registry) ImageProvider(id ProviderID) (ImageProvider, bool)

ImageProvider returns the registered image provider for id.

func (*Registry) ListEmbeddingModels added in v0.3.0 

func (r *Registry) ListEmbeddingModels() []EmbeddingModel

ListEmbeddingModels returns embedding models in registration order.

func (*Registry) ListImageModels 

func (r *Registry) ListImageModels() []ImageModel

ListImageModels returns image models in registration order.

func (*Registry) ListModels 

func (r *Registry) ListModels() []Model

ListModels returns text models in registration order.

func (*Registry) ListProviderAuths added in v0.6.0 

func (r *Registry) ListProviderAuths() []ProviderAuthInfo

ListProviderAuths returns registered provider auth metadata in registration order.

func (*Registry) ListProviders 

func (r *Registry) ListProviders() []ProviderInfo

ListProviders returns providers in first-registration order.

func (*Registry) Model 

func (r *Registry) Model(provider ProviderID, id ModelID) (Model, bool)

Model returns a text model by provider and model id.

func (*Registry) ProviderAuth added in v0.6.0 

func (r *Registry) ProviderAuth(provider ProviderID) (ProviderAuth, bool)

ProviderAuth returns registered auth metadata for provider.

func (*Registry) RefreshEmbeddingModels added in v0.6.0 

func (r *Registry) RefreshEmbeddingModels(ctx context.Context, providers ...ProviderID) error

RefreshEmbeddingModels refreshes embedding models from registered runtime sources.

func (*Registry) RefreshImageModels added in v0.6.0 

func (r *Registry) RefreshImageModels(ctx context.Context, providers ...ProviderID) error

RefreshImageModels refreshes image models from registered runtime sources.

func (*Registry) RefreshTextModels added in v0.6.0 

func (r *Registry) RefreshTextModels(ctx context.Context, providers ...ProviderID) error

RefreshTextModels refreshes text models from registered runtime sources.

func (*Registry) RegisterEmbeddingModel added in v0.3.0 

func (r *Registry) RegisterEmbeddingModel(model EmbeddingModel, opts ...RegisterOption) error

RegisterEmbeddingModel registers embedding model metadata.

func (*Registry) RegisterEmbeddingModelSource added in v0.6.0 

func (r *Registry) RegisterEmbeddingModelSource(provider ProviderID, source EmbeddingModelSource, opts ...RegisterOption) error

RegisterEmbeddingModelSource registers a runtime embedding model source for provider.

func (*Registry) RegisterEmbeddingProvider added in v0.3.0 

func (r *Registry) RegisterEmbeddingProvider(id ProviderID, provider EmbeddingProvider, opts ...RegisterOption) error

RegisterEmbeddingProvider registers the implementation for a provider's embeddings API.

func (*Registry) RegisterImageModel 

func (r *Registry) RegisterImageModel(model ImageModel, opts ...RegisterOption) error

RegisterImageModel registers image model metadata.

func (*Registry) RegisterImageModelSource added in v0.6.0 

func (r *Registry) RegisterImageModelSource(provider ProviderID, source ImageModelSource, opts ...RegisterOption) error

RegisterImageModelSource registers a runtime image model source for provider.

func (*Registry) RegisterImageProvider 

func (r *Registry) RegisterImageProvider(id ProviderID, provider ImageProvider, opts ...RegisterOption) error

RegisterImageProvider registers the implementation for a provider's image API.

func (*Registry) RegisterModel 

func (r *Registry) RegisterModel(model Model, opts ...RegisterOption) error

RegisterModel registers text model metadata.

func (*Registry) RegisterProviderAuth added in v0.6.0 

func (r *Registry) RegisterProviderAuth(provider ProviderID, auth ProviderAuth, opts ...RegisterOption) error

RegisterProviderAuth registers auth metadata for provider.

func (*Registry) RegisterTextModelSource added in v0.6.0 

func (r *Registry) RegisterTextModelSource(provider ProviderID, source TextModelSource, opts ...RegisterOption) error

RegisterTextModelSource registers a runtime text model source for provider.

func (*Registry) RegisterTextProvider 

func (r *Registry) RegisterTextProvider(id ProviderID, provider TextProvider, opts ...RegisterOption) error

RegisterTextProvider registers the implementation for a provider's text API.

func (*Registry) RestoreTextModels added in v0.7.0 

func (r *Registry) RestoreTextModels(ctx context.Context, providers ...ProviderID) error

RestoreTextModels restores cached text models from registered runtime sources.

When providers are omitted, sources without cached-model support are skipped. An explicitly requested source must implement CachedTextModelSource.

func (*Registry) Snapshot 

func (r *Registry) Snapshot() RegistrySnapshot

Snapshot returns a copy of registry providers and model metadata.

func (*Registry) TextProvider 

func (r *Registry) TextProvider(id ProviderID) (TextProvider, bool)

TextProvider returns the registered text provider for id.

type RegistrySnapshot 

type RegistrySnapshot struct {
	Providers       []ProviderInfo     `json:"providers,omitempty"`
	ProviderAuths   []ProviderAuthInfo `json:"providerAuths,omitempty"`
	Models          []Model            `json:"models,omitempty"`
	ImageModels     []ImageModel       `json:"imageModels,omitempty"`
	EmbeddingModels []EmbeddingModel   `json:"embeddingModels,omitempty"`
}

RegistrySnapshot is an immutable-by-convention copy of registry state.

type Request 

type Request struct {
	SystemPrompt string    `json:"systemPrompt,omitempty"`
	Messages     []Message `json:"messages,omitempty"`
	Tools        []Tool    `json:"tools,omitempty"`
}

Request is the provider-neutral input for a model turn.

func UnmarshalRequest 

func UnmarshalRequest(data []byte) (Request, error)

UnmarshalRequest decodes Request JSON and validates it for replay.

Unknown struct fields are rejected. ProviderMetadata, ToolArguments, and tool schemas remain open JSON maps because providers may need opaque continuation data that sigma does not interpret.

type ResultCitation added in v0.6.0 

type ResultCitation struct {
	Type             string         `json:"type,omitempty"`
	ID               string         `json:"id,omitempty"`
	URL              string         `json:"url,omitempty"`
	URI              string         `json:"uri,omitempty"`
	Title            string         `json:"title,omitempty"`
	CitedText        string         `json:"citedText,omitempty"`
	StartIndex       *int           `json:"startIndex,omitempty"`
	EndIndex         *int           `json:"endIndex,omitempty"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

ResultCitation is a normalized citation attached to assistant content.

type ResultSource added in v0.6.0 

type ResultSource struct {
	Type             string         `json:"type,omitempty"`
	ID               string         `json:"id,omitempty"`
	URL              string         `json:"url,omitempty"`
	URI              string         `json:"uri,omitempty"`
	Title            string         `json:"title,omitempty"`
	StartIndex       *int           `json:"startIndex,omitempty"`
	EndIndex         *int           `json:"endIndex,omitempty"`
	ProviderMetadata map[string]any `json:"providerMetadata,omitempty"`
}

ResultSource is a normalized source entry reported by a provider response.

type RetrievalChunk added in v0.3.0 

type RetrievalChunk struct {
	ID         string         `json:"id,omitempty"`
	DocumentID string         `json:"documentID,omitempty"`
	Text       string         `json:"text,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
	StartByte  int            `json:"startByte,omitempty"`
	EndByte    int            `json:"endByte,omitempty"`
}

RetrievalChunk is one indexed text chunk.

func SplitRetrievalDocuments added in v0.3.0 

func SplitRetrievalDocuments(docs []RetrievalDocument, config RetrievalSplitterConfig) ([]RetrievalChunk, error)

SplitRetrievalDocuments splits documents and copies metadata onto each chunk.

func SplitRetrievalText added in v0.3.0 

func SplitRetrievalText(text string, config RetrievalSplitterConfig) ([]RetrievalChunk, error)

SplitRetrievalText splits text into deterministic retrieval chunks.

type RetrievalDocument added in v0.3.0 

type RetrievalDocument struct {
	ID       string         `json:"id,omitempty"`
	Text     string         `json:"text,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

RetrievalDocument is caller-owned text plus metadata used for retrieval.

type RetrievalResult added in v0.3.0 

type RetrievalResult struct {
	Chunk RetrievalChunk `json:"chunk"`
	Score float64        `json:"score"`
}

RetrievalResult is one retrieval hit without exposing stored vectors.

type RetrievalSplitterConfig added in v0.3.0 

type RetrievalSplitterConfig struct {
	ChunkSize     int      `json:"chunkSize,omitempty"`
	ChunkOverlap  int      `json:"chunkOverlap,omitempty"`
	Separators    []string `json:"separators,omitempty"`
	KeepSeparator bool     `json:"keepSeparator,omitempty"`
}

RetrievalSplitterConfig configures deterministic character-based splitting.

type RetryHint added in v0.3.0 

type RetryHint struct {
	Retryable bool
	After     time.Duration
}

RetryHint describes whether retrying the same request may be useful.

type Role 

type Role string

Role identifies the role of a persisted conversation message. 

const (
	// RoleUser identifies a user message.
	RoleUser Role = "user"
	// RoleDeveloper identifies provider developer instructions persisted as messages.
	RoleDeveloper Role = "developer"
	// RoleAssistant identifies an assistant message.
	RoleAssistant Role = "assistant"
	// RoleTool identifies a tool-result message.
	RoleTool Role = "tool"
)

type RouteAction added in v0.6.0 

type RouteAction string

RouteAction is the advised next step after a routed request failed. 

const (
	// RouteActionRetry advises retrying the same model, waiting RetryAfter
	// first when it is non-zero.
	RouteActionRetry RouteAction = "retry"
	// RouteActionFallback advises sending the request to the advice Model
	// instead. Use TransformRequestForModel before replaying a conversation
	// on a different provider.
	RouteActionFallback RouteAction = "fallback"
	// RouteActionAbort advises surfacing the error without retrying.
	RouteActionAbort RouteAction = "abort"
)

type RouteAdvice added in v0.6.0 

type RouteAdvice struct {
	Action         RouteAction
	Model          ModelRef
	RetryAfter     time.Duration
	Reason         string
	Classification ErrorClassification
}

RouteAdvice is a deterministic fallback recommendation. Sigma only decides; the caller executes the retry or fallback and tracks attempt state.

type RouteClassification added in v0.6.0 

type RouteClassification struct {
	Tier    RouteTier     `json:"tier"`
	Score   float64       `json:"score"`
	Signals []RouteSignal `json:"signals,omitempty"`
}

RouteClassification is a deterministic complexity classification. Score is the weighted sum of all signals; Signals lists non-zero contributions for observability.

func ClassifyRequest added in v0.6.0 

func ClassifyRequest(req Request, opts ...RouteOption) RouteClassification

ClassifyRequest classifies req into a route tier using weighted rule-based scoring. Classification is pure and deterministic: no model calls, no randomness, and the same request always classifies to the same tier.

Only the system prompt and the latest user message are scored, so prior conversation turns and tool results do not drift long agentic sessions into heavier tiers. Reasoning markers are scored against the user message alone so a system prompt cannot force every request into the reasoning tier. Two or more reasoning markers in the user message classify directly as the reasoning tier unless the dimension weight is zero.

type RouteDecision added in v0.6.0 

type RouteDecision struct {
	Model          ModelRef            `json:"model"`
	Tier           RouteTier           `json:"tier"`
	Classification RouteClassification `json:"classification"`
}

RouteDecision reports the model selected for a request and why.

type RouteOption added in v0.6.0 

type RouteOption func(*routeConfig)

RouteOption configures classification and candidate selection.

func WithRouteBoundaries added in v0.6.0 

func WithRouteBoundaries(simpleStandard float64, standardComplex float64, complexReasoning float64) RouteOption

WithRouteBoundaries overrides the ascending tier score boundaries. Scores below simpleStandard classify as simple, below standardComplex as standard, below complexReasoning as complex, and reasoning otherwise.

func WithRouteExclusions added in v0.6.0 

func WithRouteExclusions(refs ...ModelRef) RouteOption

WithRouteExclusions skips the supplied candidates during selection and fallback. Callers own health tracking; models on cooldown should be passed here on every call until the caller considers them healthy again.

func WithRouteModelLookup added in v0.6.0 

func WithRouteModelLookup(lookup func(ModelRef) (Model, bool)) RouteOption

WithRouteModelLookup overrides how candidate metadata is resolved for context-overflow fallback. The default lookup uses DefaultRegistry.

func WithRouteWeight added in v0.6.0 

func WithRouteWeight(dimension string, weight float64) RouteOption

WithRouteWeight overrides the weight of one classifier dimension. Setting a dimension weight to zero removes it from scoring. The tokenCount dimension defaults to zero weight because accumulated agentic context would otherwise bias every late-turn request toward heavier tiers; enable it only for single-turn workloads.

type RoutePolicy added in v0.6.0 

type RoutePolicy struct {
	Tiers map[RouteTier][]ModelRef `json:"tiers"`
}

RoutePolicy maps tiers to ordered model candidates. Earlier candidates are preferred. The policy is a plain value constructed by the caller; sigma does not load routing configuration from files or the environment.

func (RoutePolicy) Fallback added in v0.6.0 

func (p RoutePolicy) Fallback(decision RouteDecision, attempted []ModelRef, err error, opts ...RouteOption) RouteAdvice

Fallback classifies err and advises the next step for a failed decision.

The advice is stateless: attempted lists models the caller has already tried, and the failed decision model is always skipped when searching for a fallback candidate. The decision table is:

  • invalid-request and unknown errors abort.
  • transient errors retry the same model, honoring the provider retry hint.
  • rate-limited errors fall back to the next candidate, or retry the same model after the hinted delay when no candidate remains.
  • auth, quota, billing, and provider errors fall back to the next candidate, or abort when no candidate remains.
  • context-overflow errors fall back to the next candidate with a larger known context window, or abort when none exists.

func (RoutePolicy) Select added in v0.6.0 

func (p RoutePolicy) Select(req Request, opts ...RouteOption) (RouteDecision, error)

Select classifies req and returns the first usable candidate for the classified tier. When the classified tier has no usable candidate the search escalates to more capable tiers first, then falls back to less capable tiers. Candidates excluded via WithRouteExclusions or failing ValidateModelRef are skipped. ErrNoRouteCandidates is returned when no candidate remains.

type RouteSignal added in v0.6.0 

type RouteSignal struct {
	Dimension string  `json:"dimension"`
	Score     float64 `json:"score"`
	Weight    float64 `json:"weight"`
	Detail    string  `json:"detail,omitempty"`
}

RouteSignal is one scored classifier dimension. Score is the raw dimension score in [-1, 1] before weighting.

type RouteTier added in v0.6.0 

type RouteTier string

RouteTier is a deterministic request complexity tier. 

const (
	// RouteTierSimple identifies short lookups, definitions, and greetings.
	RouteTierSimple RouteTier = "simple"
	// RouteTierStandard identifies everyday requests without strong
	// complexity signals.
	RouteTierStandard RouteTier = "standard"
	// RouteTierComplex identifies technical, code-heavy, or multi-part
	// requests.
	RouteTierComplex RouteTier = "complex"
	// RouteTierReasoning identifies requests with explicit deep-reasoning
	// cues such as step-by-step analysis or trade-off comparisons.
	RouteTierReasoning RouteTier = "reasoning"
)

type Schema 

type Schema map[string]any

Schema is a JSON Schema-compatible tool parameter definition.

ValidateToolCall supports the subset commonly emitted for model tools: type, properties, required, enum, items, additionalProperties, minimum, maximum, minLength, maxLength, pattern, format, not, if/then/else, and oneOf/anyOf/allOf. It also resolves local JSON Pointer references through $ref, including recursive definitions. ValidateToolCallWithOptions can opt into primitive argument coercion before strict validation. External references and unsupported JSON Schema keywords are rejected or ignored respectively; coercion remains off by default.

type SessionResourceCleanup added in v0.6.0 

type SessionResourceCleanup func(sessionID string) error

SessionResourceCleanup releases cached provider resources for a session.

An empty sessionID asks the cleanup to release all session resources it owns.

type StopReason 

type StopReason string

StopReason identifies why a model stopped generating output. 

const (
	// StopReasonEndTurn indicates the assistant completed a normal turn.
	StopReasonEndTurn StopReason = "end-turn"
	// StopReasonMaxTokens indicates generation stopped at the output token limit.
	StopReasonMaxTokens StopReason = "max-tokens"
	// StopReasonStopSequence indicates generation stopped after a configured stop sequence.
	StopReasonStopSequence StopReason = "stop-sequence"
	// StopReasonToolCalls indicates generation stopped to request tool calls.
	StopReasonToolCalls StopReason = "tool-calls"
	// StopReasonContentFilter indicates generation stopped because content was filtered.
	StopReasonContentFilter StopReason = "content-filter"
	// StopReasonError indicates generation stopped because the provider returned an error.
	StopReasonError StopReason = "error"
	// StopReasonUnknown indicates the provider did not expose a stable stop reason.
	StopReasonUnknown StopReason = "unknown"
)
const (
	// StopReasonAborted indicates generation stopped because the stream context was canceled.
	StopReasonAborted StopReason = "aborted"
)

type StoredCredential added in v0.6.0 

type StoredCredential struct {
	Type         CredentialType
	Value        string
	RefreshToken string
	Expiry       time.Time
	Source       string
	ProviderEnv  map[string]string
	Metadata     map[string]any
}

StoredCredential is provider-owned authentication material read from a caller-supplied CredentialStore.

type StoredCredentialAuthResolver added in v0.6.0 

type StoredCredentialAuthResolver struct {
	Store    CredentialStore
	Registry *Registry
	Fallback AuthResolver
	Now      func() time.Time
}

StoredCredentialAuthResolver resolves credentials from a CredentialStore.

func (StoredCredentialAuthResolver) Resolve added in v0.6.0 

func (r StoredCredentialAuthResolver) Resolve(ctx context.Context, model Model, opts Options) (Credential, error)

Resolve implements AuthResolver.

func (StoredCredentialAuthResolver) ResolveAuthResolution added in v0.6.0 

func (r StoredCredentialAuthResolver) ResolveAuthResolution(ctx context.Context, model Model, opts Options) (AuthResolution, error)

ResolveAuthResolution implements AuthResolutionResolver.

type Stream 

type Stream struct {
	// contains filtered or unexported fields
}

Stream is a single-consumer stream of ordered provider-neutral events.

Events is single-consumer: callers should have exactly one goroutine receive from it, or coordinate their own fan-out. Close lets a consumer stop early.

func StreamModel 

func StreamModel(ctx context.Context, model Model, req Request, opts ...Option) *Stream

StreamModel starts a provider stream using the default registry.

func (*Stream) Close 

func (s *Stream) Close()

Close stops the stream without waiting for a provider terminal event.

func (*Stream) Done 

func (s *Stream) Done() <-chan struct{}

Done closes after Events closes.

func (*Stream) Err 

func (s *Stream) Err() error

Err returns the terminal stream error, if any.

func (*Stream) Events 

func (s *Stream) Events() <-chan Event

Events returns the ordered stream events.

func (*Stream) Final 

func (s *Stream) Final() (AssistantMessage, bool)

Final returns the terminal assistant message, if the stream recorded one.

type StreamWriter 

type StreamWriter interface {
	// Emit sends a non-terminal event.
	Emit(context.Context, Event) error
	// Done sends the single successful terminal event.
	Done(context.Context, AssistantMessage) error
	// Error sends the single error terminal event.
	Error(context.Context, error, AssistantMessage) error
	// Close closes the stream without emitting another event.
	Close()
}

StreamWriter is the provider side of a Stream.

type StreamingImageProvider added in v0.3.0 

type StreamingImageProvider interface {
	ImageProvider
	StreamImages(context.Context, ImageModel, ImageRequest, Options) *ImageStream
}

StreamingImageProvider optionally adapts a provider API into sigma's streaming image interface.

type StructuredOutput added in v0.6.0 

type StructuredOutput struct {
	Type   StructuredOutputType
	Name   string
	Schema any
	Strict bool
}

StructuredOutput describes a provider-neutral structured-output request.

type StructuredOutputType added in v0.6.0 

type StructuredOutputType string

StructuredOutputType identifies provider-neutral structured-output modes. 

const (
	// StructuredOutputJSONObject asks the provider to return any JSON object.
	StructuredOutputJSONObject StructuredOutputType = "json_object"
	// StructuredOutputJSONSchema asks the provider to return an object matching
	// the supplied JSON Schema-compatible schema.
	StructuredOutputJSONSchema StructuredOutputType = "json_schema"
)

type TextModelSource added in v0.6.0 

type TextModelSource interface {
	TextModels(context.Context) ([]Model, error)
}

TextModelSource lists text models for a provider-owned runtime source.

type TextModelSourceFunc added in v0.6.0 

type TextModelSourceFunc func(context.Context) ([]Model, error)

TextModelSourceFunc adapts a function into a TextModelSource.

func (TextModelSourceFunc) TextModels added in v0.6.0 

func (f TextModelSourceFunc) TextModels(ctx context.Context) ([]Model, error)

TextModels calls f.

type TextPayloadDebug 

type TextPayloadDebug struct {
	Provider       ProviderID
	API            API
	Model          ModelID
	Headers        http.Header
	Payload        []byte
	PayloadPreview string
}

TextPayloadDebug is the diagnostic view passed to text payload hooks.

type TextPayloadDebugHook 

type TextPayloadDebugHook func(context.Context, TextPayloadDebug) error

TextPayloadDebugHook inspects a redacted copy of a text provider payload.

Hooks run after provider payload and headers are built and before the HTTP request is sent. Payload replacement is intentionally unsupported: Payload is a redacted copy for diagnostics, so mutating it cannot change the request body or corrupt a later retry attempt.

type TextProvider 

type TextProvider interface {
	API() API
	Stream(context.Context, Model, Request, Options) *Stream
}

TextProvider adapts a provider API into sigma's streaming text interface.

type TextResponseDebug 

type TextResponseDebug struct {
	Provider   ProviderID
	API        API
	Model      ModelID
	StatusCode int
	Headers    http.Header
	RequestID  string
}

TextResponseDebug is the diagnostic view passed to text response hooks.

type TextResponseDebugHook 

type TextResponseDebugHook func(context.Context, TextResponseDebug) error

TextResponseDebugHook inspects redacted response metadata before the response body is consumed.

type ThinkingLevel 

type ThinkingLevel string

ThinkingLevel identifies a provider thinking or reasoning budget level. 

const (
	// ThinkingLevelOff disables provider reasoning or thinking features.
	ThinkingLevelOff ThinkingLevel = "off"
	// ThinkingLevelMinimal requests the smallest provider reasoning or thinking budget.
	ThinkingLevelMinimal ThinkingLevel = "minimal"
	// ThinkingLevelLow requests a low reasoning or thinking budget.
	ThinkingLevelLow ThinkingLevel = "low"
	// ThinkingLevelMedium requests a medium reasoning or thinking budget.
	ThinkingLevelMedium ThinkingLevel = "medium"
	// ThinkingLevelHigh requests a high reasoning or thinking budget.
	ThinkingLevelHigh ThinkingLevel = "high"
	// ThinkingLevelXHigh requests the largest provider reasoning or thinking budget.
	ThinkingLevelXHigh ThinkingLevel = "xhigh"
)

type TokenEstimate added in v0.6.0 

type TokenEstimate struct {
	Tokens                int  `json:"tokens"`
	UsageTokens           int  `json:"usageTokens,omitempty"`
	TrailingTokens        int  `json:"trailingTokens,omitempty"`
	LastUsageMessageIndex *int `json:"lastUsageMessageIndex,omitempty"`
}

TokenEstimate reports an approximate request token count.

func EstimateRequestTokens added in v0.6.0 

func EstimateRequestTokens(req Request) TokenEstimate

EstimateRequestTokens returns a deterministic approximate token count for a request.

When the latest successful assistant message carries provider-reported usage, the estimate uses that usage as the context anchor and estimates only messages after it. Otherwise it estimates the whole request from the system prompt, tools, and messages.

type Tool 

type Tool struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// InputSchema accepts Schema, map[string]any, json.RawMessage, []byte, or
	// another JSON-marshable value containing a JSON Schema-compatible object.
	InputSchema any `json:"inputSchema,omitempty"`
	// ProviderDefinedType identifies a server-side provider tool such as web
	// search or code execution. When set, supported providers serialize the tool
	// using their native tool shape instead of a JSON Schema function tool.
	ProviderDefinedType    string         `json:"providerDefinedType,omitempty"`
	ProviderDefinedOptions map[string]any `json:"providerDefinedOptions,omitempty"`
	ProviderMetadata       map[string]any `json:"providerMetadata,omitempty"`
	// OpenAIGrammar configures this tool as an OpenAI Responses custom tool
	// when grammar tools are enabled for the request.
	OpenAIGrammar *OpenAIGrammar `json:"openAIGrammar,omitempty"`
}

Tool describes a callable model tool.

type ToolCall 

type ToolCall struct {
	ID                string         `json:"id"`
	Name              string         `json:"name"`
	Arguments         any            `json:"arguments,omitempty"`
	ProviderSignature string         `json:"providerSignature,omitempty"`
	ProviderMetadata  map[string]any `json:"providerMetadata,omitempty"`
}

ToolCall describes a model request to invoke a tool.

func (*ToolCall) UnmarshalJSON added in v0.6.0 

func (c *ToolCall) UnmarshalJSON(data []byte) error

type ToolValidationError 

type ToolValidationError struct {
	ToolName string
	Path     string
	Expected string
	Actual   string
	Reason   string
	Err      error
}

ToolValidationError reports a tool-call argument or tool schema validation failure. Actual is a short, redacted summary safe for logs and tool-result retry messages.

func (*ToolValidationError) Error 

func (e *ToolValidationError) Error() string

func (*ToolValidationError) Is 

func (e *ToolValidationError) Is(target error) bool

Is supports errors.Is(err, ErrToolValidation).

func (*ToolValidationError) Unwrap 

func (e *ToolValidationError) Unwrap() error

Unwrap returns the underlying validation cause.

type ToolValidationOptions added in v0.6.0 

type ToolValidationOptions struct {
	// CoercePrimitives converts common model-emitted primitive mismatches on the
	// decoded argument copy before strict schema validation.
	CoercePrimitives bool
}

ToolValidationOptions configures local tool-call validation.

type Transport 

type Transport string

Transport identifies the wire transport used for provider calls. 

const (
	// TransportHTTP identifies ordinary HTTP request/response transport.
	TransportHTTP Transport = "http"
	// TransportSSE identifies server-sent event streaming transport.
	TransportSSE Transport = "sse"
	// TransportWebSocket identifies WebSocket streaming transport.
	TransportWebSocket Transport = "websocket"
)

type Usage 

type Usage struct {
	InputTokens               int            `json:"inputTokens,omitempty"`
	OutputTokens              int            `json:"outputTokens,omitempty"`
	TotalTokens               int            `json:"totalTokens,omitempty"`
	CacheReadInputTokens      int            `json:"cacheReadInputTokens,omitempty"`
	CacheWriteInputTokens     int            `json:"cacheWriteInputTokens,omitempty"`
	LongCacheWriteInputTokens int            `json:"longCacheWriteInputTokens,omitempty"`
	ThinkingTokens            int            `json:"thinkingTokens,omitempty"`
	ToolUseInputTokens        int            `json:"toolUseInputTokens,omitempty"`
	Provider                  ProviderID     `json:"provider,omitempty"`
	Model                     ModelID        `json:"model,omitempty"`
	Raw                       map[string]any `json:"raw,omitempty"`
}

Usage records provider token accounting for a model turn.

func (Usage) Total 

func (usage Usage) Total() int

Total returns provider-supplied total tokens when available, otherwise it computes a deterministic total from input, output, and prompt-cache token fields. ThinkingTokens is reported separately and should be included in OutputTokens by providers when it is billable as output.

Streaming providers that only receive usage at stream end should leave interim Event.Usage nil and attach the final Usage to the terminal AssistantMessage. The terminal event will then expose the same final usage.

type UsageAccountingOption added in v0.6.0 

type UsageAccountingOption func(*usageAccountingConfig)

UsageAccountingOption configures AccountUsage.

func WithEstimatedCostAdjustment added in v0.6.0 

func WithEstimatedCostAdjustment(adjust func(*Cost)) UsageAccountingOption

WithEstimatedCostAdjustment adjusts Sigma's estimated cost after model pricing has been applied. Providers use this for request-specific pricing modifiers such as service tiers.

func WithProviderReportedCost added in v0.6.0 

func WithProviderReportedCost(cost float64, currency string) UsageAccountingOption

WithProviderReportedCost records a provider-reported cost separately from Sigma's model-metadata estimate.

func WithRawUsage added in v0.6.0 

func WithRawUsage(raw any) UsageAccountingOption

WithRawUsage preserves the provider usage payload as JSON-like debug data.

type VercelAIGatewayRoutingPreference 

type VercelAIGatewayRoutingPreference struct {
	Order   []string       `json:"order,omitempty"`
	Only    []string       `json:"only,omitempty"`
	Models  []string       `json:"models,omitempty"`
	Caching string         `json:"caching,omitempty"`
	BYOK    map[string]any `json:"byok,omitempty"`
}

VercelAIGatewayRoutingPreference describes Vercel AI Gateway routing values accepted under providerOptions.gateway.

Source Files

View all Source files

Directories

Path Synopsis
cmd
sigma-evals-runner command
sigma-generate-models command
sigma-surface-probe command
examples
cancel command
chat command
custom-model command
fireworks command
images command
stream command
tools command
internal
evals
Package evals provides repository-internal behavioral evaluation helpers.
 Package evals provides repository-internal behavioral evaluation helpers.
goldentest
modeldata
Package modeldata validates the curated snapshot used to generate built-in model metadata.
 Package modeldata validates the curated snapshot used to generate built-in model metadata.
providertext
redact
Package redact contains helpers for removing secrets from diagnostics.
 Package redact contains helpers for removing secrets from diagnostics.
sse
Package sse parses provider-neutral Server-Sent Event frames.
 Package sse parses provider-neutral Server-Sent Event frames.
streamblocks
streamlifecycle
streamstate
Package streamstate contains the serialized state machine backing streams.
 Package streamstate contains the serialized state machine backing streams.
transform
Package transform will contain provider request and response transforms.
 Package transform will contain provider request and response transforms.
vertexai
provider
anthropic
Package anthropic adapts Anthropic Messages-compatible APIs to sigma.
 Package anthropic adapts Anthropic Messages-compatible APIs to sigma.
antling
Package antling adapts Ant Ling's OpenAI-compatible Chat Completions endpoint to Sigma.
 Package antling adapts Ant Ling's OpenAI-compatible Chat Completions endpoint to Sigma.
azure
Package azure adapts Azure OpenAI Responses to sigma.
 Package azure adapts Azure OpenAI Responses to sigma.
bedrock
Package bedrock adapts Amazon Bedrock Converse Stream to sigma.
 Package bedrock adapts Amazon Bedrock Converse Stream to sigma.
cerebras
Package cerebras adapts Cerebras's OpenAI-compatible Chat Completions endpoint to sigma.
 Package cerebras adapts Cerebras's OpenAI-compatible Chat Completions endpoint to sigma.
cloudflare
Package cloudflare adapts Cloudflare AI Gateway's compatible text endpoints to sigma.
 Package cloudflare adapts Cloudflare AI Gateway's compatible text endpoints to sigma.
deepseek
Package deepseek adapts DeepSeek's OpenAI-compatible Chat Completions endpoint to sigma.
 Package deepseek adapts DeepSeek's OpenAI-compatible Chat Completions endpoint to sigma.
fireworks
Package fireworks adapts Fireworks AI's OpenAI-compatible Chat Completions and Anthropic-compatible Messages endpoints to sigma.
 Package fireworks adapts Fireworks AI's OpenAI-compatible Chat Completions and Anthropic-compatible Messages endpoints to sigma.
githubcopilot
Package githubcopilot adapts GitHub Copilot's compatible text endpoints to sigma.
 Package githubcopilot adapts GitHub Copilot's compatible text endpoints to sigma.
google
Package google adapts Google Generative AI and Google Vertex AI to sigma.
 Package google adapts Google Generative AI and Google Vertex AI to sigma.
groq
Package groq adapts Groq's OpenAI-compatible Chat Completions endpoint to sigma.
 Package groq adapts Groq's OpenAI-compatible Chat Completions endpoint to sigma.
huggingface
Package huggingface adapts Hugging Face Router's OpenAI-compatible Chat Completions endpoint to sigma.
 Package huggingface adapts Hugging Face Router's OpenAI-compatible Chat Completions endpoint to sigma.
kimi
Package kimi provides Kimi and Kimi Coding convenience registration over Sigma's Anthropic-compatible Messages adapter.
 Package kimi provides Kimi and Kimi Coding convenience registration over Sigma's Anthropic-compatible Messages adapter.
minimax
Package minimax adapts MiniMax's Anthropic-compatible Messages endpoints to sigma.
 Package minimax adapts MiniMax's Anthropic-compatible Messages endpoints to sigma.
mistral
Package mistral adapts the Mistral Conversations API to sigma.
 Package mistral adapts the Mistral Conversations API to sigma.
moonshot
Package moonshot provides Moonshot AI convenience registration over Sigma's shared OpenAI-compatible Chat Completions provider.
 Package moonshot provides Moonshot AI convenience registration over Sigma's shared OpenAI-compatible Chat Completions provider.
nvidia
Package nvidia adapts NVIDIA NIM OpenAI-compatible text and embedding endpoints to sigma.
 Package nvidia adapts NVIDIA NIM OpenAI-compatible text and embedding endpoints to sigma.
openai
Package openai adapts OpenAI-compatible APIs to sigma.
 Package openai adapts OpenAI-compatible APIs to sigma.
opencode
Package opencode routes OpenCode Zen and OpenCode Go models to the Sigma adapter matching each model's OpenCode API family.
 Package opencode routes OpenCode Zen and OpenCode Go models to the Sigma adapter matching each model's OpenCode API family.
openrouter
Package openrouter adapts OpenRouter's OpenAI-compatible Chat Completions API to sigma.
 Package openrouter adapts OpenRouter's OpenAI-compatible Chat Completions API to sigma.
qwen
Package qwen registers Qwen Token Plan OpenAI-compatible text providers.
 Package qwen registers Qwen Token Plan OpenAI-compatible text providers.
radius
Package radius adapts the Radius gateway messages API to Sigma.
 Package radius adapts the Radius gateway messages API to Sigma.
together
Package together adapts Together AI's OpenAI-compatible Chat Completions endpoint to sigma.
 Package together adapts Together AI's OpenAI-compatible Chat Completions endpoint to sigma.
vercel
Package vercel adapts Vercel AI Gateway's Anthropic-compatible Messages endpoint to sigma.
 Package vercel adapts Vercel AI Gateway's Anthropic-compatible Messages endpoint to sigma.
xai
Package xai adapts xAI's Grok OpenAI-compatible Chat Completions and Responses endpoints to sigma.
 Package xai adapts xAI's Grok OpenAI-compatible Chat Completions and Responses endpoints to sigma.
xiaomi
Package xiaomi registers Xiaomi MiMo OpenAI-compatible text providers.
 Package xiaomi registers Xiaomi MiMo OpenAI-compatible text providers.
zai
Package zai registers Z.ai OpenAI-compatible text providers.
 Package zai registers Z.ai OpenAI-compatible text providers.
Package sigmatest provides deterministic providers and helpers for testing sigma clients without live provider calls.
 Package sigmatest provides deterministic providers and helpers for testing sigma clients without live provider calls.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.