provider

package
v1.3.103 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// HostedToolWebSearch is the MothX-configured search capability. It is
	// controlled by the local web-search settings/session switch.
	HostedToolWebSearch = "web_search"
	// HostedToolOpenAIResponsesWebSearch is an internal name for the native
	// OpenAI Responses capability. Its wire type is still "web_search".
	HostedToolOpenAIResponsesWebSearch   = "openai_responses_web_search"
	HostedToolWebSearchAnthropicMessages = "web_search_20250305"
	HostedToolImageGeneration            = "image_generation"
)
View Source 
const DebugLogOnlyEnv = "VIBECODING_DEBUG_LOG_ONLY"

DebugLogOnlyEnv suppresses debug stderr output while retaining debug.log. The interactive TUI sets it so asynchronous provider output cannot disrupt Bubble Tea rendering.

View Source 
const StreamIdleTimeout = 30 * time.Minute

StreamIdleTimeout is the maximum time a streaming response body may go without delivering any data before it is considered stalled and aborted. Unlike a fixed wall-clock timeout, this only fires when the upstream stops sending data, so long-lived streams that keep delivering data are unaffected.

Variables

View Source 
var ErrInvalidToolCallArguments = errors.New("invalid tool-call JSON arguments")

ErrInvalidToolCallArguments indicates that a tool call's original argument payload was not valid JSON and therefore was not executed as supplied.

Functions

func ApplyDiscoveryAuthHeaders 

func ApplyDiscoveryAuthHeaders(req *http.Request, api, apiKey string, headers map[string]string)

ApplyDiscoveryAuthHeaders sets API-type specific auth headers plus any custom headers on a discovery request.

func ApplyHeaders 

func ApplyHeaders(req *http.Request, headers map[string]string)

ApplyHeaders applies configured custom headers after provider defaults.

func DebugCompleteResponse 

func DebugCompleteResponse(response DebugResponse)

DebugCompleteResponse marshals a reconstructed non-SSE response for debug logging.

func DebugJSON 

func DebugJSON(label string, body []byte)

DebugJSON writes a JSON request or complete response to debug.log when --debug has enabled VIBECODING_DEBUG. Non-TUI callers also receive it on stderr unless DebugLogOnlyEnv is set.

func DebugLogf 

func DebugLogf(format string, args ...any)

DebugLogf writes a diagnostic line to debug.log when --debug is enabled. Callers must not include credentials or other secrets in the formatted values.

func FormatRetryMessage 

func FormatRetryMessage(attempt, maxRetries int, delay time.Duration, err error) string

FormatRetryMessage returns a user-visible message for a retry attempt.

func FormatUsage 

func FormatUsage(u *Usage) string

FormatUsage renders a Usage for inclusion in error/status messages.

func HostedToolType 

func HostedToolType(providerType, name string) string

HostedToolType maps a provider-neutral hosted tool name to its provider-specific wire type. The mapping depends on the API family, not the vendor name.

func HostedWebSearchToolType 

func HostedWebSearchToolType(providerType, name string) string

HostedWebSearchToolType is retained for callers that only need the historical web_search mapping.

func IsContentRejectionError 

func IsContentRejectionError(err error) bool

IsContentRejectionError reports whether err is a permanent provider refusal caused by content inspection/moderation. Such failures are terminal for the offending content: automatic retries and stream-continuation retries must not re-send it.

func IsContextOverflowError 

func IsContextOverflowError(err error) bool

IsContextOverflowError reports whether err looks like a provider-side rejection caused by an oversized request (context window exceeded). Such errors are recoverable by compacting or truncating the conversation history and retrying, unlike auth, rate-limit, or transient network errors.

func IsRetryable 

func IsRetryable(err error, statusCode int) bool

IsRetryable determines whether an error or HTTP status code warrants a retry. Provider gateways frequently use 4xx for temporary quota, routing, and compatibility failures, so every HTTP 4xx/5xx response is retryable here. The provider retry budget still bounds the number of attempts.

func IsStreamTimeoutError 

func IsStreamTimeoutError(err error) bool

IsStreamTimeoutError reports whether err indicates an upstream/stream timeout (idle stream stall, response-header timeout, or a wrapped deadline). It is distinct from user-initiated cancellation (context.Canceled).

func IsStubUsage 

func IsStubUsage(u *Usage) bool

IsStubUsage reports whether a Usage looks like a placeholder/error sentinel. Nil usage or implausibly small values (total<=2, or input<=1 && output<=1) cannot occur on a real response because the prompt alone is always >= the context tokens, so this is safe across all vendors/protocols.

func ListProviders 

func ListProviders() []string

ListProviders returns all registered provider names.

func ListVendorAdapters 

func ListVendorAdapters() []string

ListVendorAdapters returns registered vendor adapter names in registration order.

func ModelsEndpoint 

func ModelsEndpoint(raw string) (string, error)

ModelsEndpoint derives the absolute /models URL from a provider base URL.

func NewHTTPClient 

func NewHTTPClient(timeout time.Duration, proxyURL string) (*http.Client, error)

NewHTTPClient returns a provider HTTP client. Empty proxyURL preserves the default environment proxy behavior from http.Transport.

func NewHTTPClientWithOptions 

func NewHTTPClientWithOptions(timeout time.Duration, opts HTTPClientOptions) (*http.Client, error)

NewHTTPClientWithOptions returns a provider HTTP client with transport options.

func NewIdleTimeoutReadCloser 

func NewIdleTimeoutReadCloser(rc io.ReadCloser, idle time.Duration) io.ReadCloser

NewIdleTimeoutReadCloser wraps rc with an inactivity deadline of idle. If rc is nil or idle <= 0, rc is returned unchanged.

func NewStreamHTTPClient 

func NewStreamHTTPClient(proxyURL string) (*http.Client, error)

NewStreamHTTPClient returns an HTTP client suited to long-lived streaming requests. Unlike NewHTTPClientWithOptions, it does not impose a single wall-clock Client.Timeout that would cap the entire (potentially long) SSE body; instead it bounds only the connect and response-header phases.

func NewStreamHTTPClientWithOptions 

func NewStreamHTTPClientWithOptions(opts HTTPClientOptions) (*http.Client, error)

NewStreamHTTPClientWithOptions is NewStreamHTTPClient with explicit options.

func NextToolCallFallbackID 

func NextToolCallFallbackID(prefix string) string

NextToolCallFallbackID returns a process-wide unique fallback ID for tool calls.

func NormalizeToolCallArguments 

func NormalizeToolCallArguments(tc *ToolCallBlock) (args map[string]any, repaired bool, err error)

NormalizeToolCallArguments makes streamed tool-call arguments safe to persist and replay. Go 1.27's JSON v2 encoder validates json.RawMessage values (jsontext.Value); a non-nil empty value therefore fails with "unexpected end of JSON input". Providers can legitimately produce an empty argument stream for a no-argument tool, so represent that as an empty object. For malformed non-empty arguments, preserve the original payload in InvalidArguments for diagnostics and replace the executable payload with an empty object. Callers must treat the returned error as a failed tool call and must not guess at the original side effect.

func Register 

func Register(name string, factory ProviderFactory)

Register registers a provider factory in the global registry.

func RegisterVendorAdapter 

func RegisterVendorAdapter(adapter VendorAdapter)

RegisterVendorAdapter registers a vendor adapter.

func ResolveSecretRef 

func ResolveSecretRef(value string) string

ResolveSecretRef expands ${ENV_VAR} references against the environment and returns any other value unchanged.

func RetryDelay 

func RetryDelay(attempt int, baseDelayMs int) time.Duration

RetryDelay calculates the delay before the next retry attempt using exponential backoff with jitter, capped at 30 seconds.

func RetryErrorDetail 

func RetryErrorDetail(err error) string

RetryErrorDetail returns only the sanitized reason for a retryable error, without the "Retrying (n/m)" wrapper. The result is always single-line and length-bounded, so adapters can render it verbatim as a supplementary diagnostic. It returns "" for a nil error. This text is presentation-only: retry scheduling and control flow must never depend on it.

func SamplingParamsDisabled 

func SamplingParamsDisabled(m *Model) bool

SamplingParamsDisabled reports whether sampling parameters (temperature/ top_p) should be omitted from requests for the model. It defaults to true: params are only sent when the model's compat explicitly sets DisableSamplingParams to false.

func ValidateAttachmentReferenceForResolver 

func ValidateAttachmentReferenceForResolver(ref string) error

ValidateAttachmentReferenceForResolver validates an opaque provider ref before it is interpolated into a provider-owned path.

func VendorFromBaseURL 

func VendorFromBaseURL(baseURL string) string

VendorFromBaseURL attempts to identify the vendor from a base URL. Returns empty string if no match.

Types

type AdapterConfig 

type AdapterConfig struct {
	Vendor         string
	API            string
	BaseURL        string
	ThinkingFormat string
	CacheControl   *bool
}

AdapterConfig is the provider configuration after vendor defaults are applied.

func ResolveAdapterConfig 

func ResolveAdapterConfig(cfg *config.ProviderConfig) AdapterConfig

ResolveAdapterConfig applies provider protocol detection plus vendor defaults.

type Attachment 

type Attachment struct {
	Kind        string         `json:"kind"` // citation, file, image, artifact, tool_result
	Name        string         `json:"name,omitempty"`
	URL         string         `json:"url,omitempty"`
	MediaType   string         `json:"mediaType,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	ProviderRef string         `json:"providerRef,omitempty"`
}

Attachment carries protocol-neutral generated files, citations, artifacts, and hosted tool outputs alongside a stream event.

type AttachmentContent 

type AttachmentContent struct {
	Data      []byte
	MediaType string
	Filename  string
}

AttachmentContent is an optional provider-specific download result. It is deliberately not part of Provider so vendors without file retrieval remain unaffected.

type AttachmentMetadataResolver 

type AttachmentMetadataResolver interface {
	ResolveAttachmentWithMetadata(context.Context, Attachment) (AttachmentContent, error)
}

AttachmentMetadataResolver is an optional refinement for providers whose file reference needs lifecycle context, such as a Code Interpreter container ID. Callers authorize the full archived Attachment first.

type AttachmentResolver 

type AttachmentResolver interface {
	ResolveAttachment(context.Context, string) (AttachmentContent, error)
}

AttachmentResolver is implemented only by providers that can resolve an archived provider reference into bytes. Callers must authorize the ref against the session archive before invoking it.

type AudioContent 

type AudioContent struct {
	MimeType string `json:"mimeType,omitempty"` // e.g. "audio/wav"
	Format   string `json:"format,omitempty"`   // wire format hint: "wav", "mp3", ...
	Data     string `json:"data,omitempty"`     // base64 encoded
	URL      string `json:"url,omitempty"`
	Bytes    int    `json:"bytes,omitempty"`
}

AudioContent carries inline audio input for models with native audio understanding. Data is the base64-encoded payload; URL is an alternative transport for wire formats that accept a remote or data URL reference. Audio input is user-turn only: assistant messages never carry audio blocks.

type BaseProvider 

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

BaseProvider provides common functionality for provider implementations.

func NewBaseProvider 

func NewBaseProvider(name string, models []*Model) BaseProvider

NewBaseProvider creates a new BaseProvider.

func (*BaseProvider) GetModel 

func (p *BaseProvider) GetModel(id string) *Model

GetModel returns a model by ID, or nil if not found.

func (*BaseProvider) Models 

func (p *BaseProvider) Models() []*Model

Models returns the list of available models.

func (*BaseProvider) Name 

func (p *BaseProvider) Name() string

Name returns the provider's name.

type CacheControl 

type CacheControl struct {
	Type string `json:"type"` // "ephemeral" for breakpoint markers
}

CacheControl represents cache control hints for prompt caching.

type ChatParams 

type ChatParams struct {
	Messages        []Message
	Tools           []ToolDefinition
	SystemPrompt    string
	ThinkingLevel   ThinkingLevel
	MaxTokens       int
	Temperature     *float64        // nil = use API default
	TopP            *float64        // nil = use API default
	ModelID         string          // which model to use
	Abort           <-chan struct{} // closed to abort the request
	ResponseOptions *ResponseOptions
}

ChatParams contains all parameters for a chat request.

type ContentBlock 

type ContentBlock struct {
	Type         string         `json:"type"` // "text", "image", "file", "audio", "video", "thinking", "toolCall"
	Text         string         `json:"text,omitempty"`
	Thinking     string         `json:"thinking,omitempty"`
	Signature    string         `json:"signature,omitempty"` // required for thinking block replay
	Image        *ImageContent  `json:"image,omitempty"`
	Audio        *AudioContent  `json:"audio,omitempty"`
	Video        *VideoContent  `json:"video,omitempty"`
	File         *FileContent   `json:"file,omitempty"`
	ToolCall     *ToolCallBlock `json:"toolCall,omitempty"`
	CacheControl *CacheControl  `json:"cache_control,omitempty"` // cache breakpoint marker
}

ContentBlock represents a block of content in a message.

type Cost 

type Cost struct {
	Input      float64 `json:"input"`
	Output     float64 `json:"output"`
	CacheRead  float64 `json:"cacheRead"`
	CacheWrite float64 `json:"cacheWrite"`
	Total      float64 `json:"total"`
}

Cost represents the monetary cost of a request.

type DebugResponse 

type DebugResponse struct {
	Provider   string          `json:"provider"`
	API        string          `json:"api"`
	Content    string          `json:"content,omitempty"`
	Reasoning  string          `json:"reasoning,omitempty"`
	ToolCalls  []ToolCallBlock `json:"toolCalls,omitempty"`
	StopReason string          `json:"stopReason,omitempty"`
	Usage      *Usage          `json:"usage,omitempty"`
	Error      string          `json:"error,omitempty"`
}

DebugResponse is the complete response reconstructed from a streamed provider response. It intentionally records the final result rather than individual SSE fragments.

type DiscoverModelsOptions 

type DiscoverModelsOptions struct {
	API         string
	BaseURL     string
	APIKey      string // literal key or a ${ENV_VAR} reference
	HTTPProxy   string
	ForceHTTP11 bool
	Headers     map[string]string
	Timeout     time.Duration // zero means defaultDiscoverTimeout
}

DiscoverModelsOptions describes how to reach a provider /models endpoint.

type DiscoveredModel 

type DiscoveredModel struct {
	ID            string   `json:"id"`
	Name          string   `json:"name,omitempty"`
	ContextWindow int      `json:"contextWindow,omitempty"`
	MaxTokens     int      `json:"maxTokens,omitempty"`
	Input         []string `json:"input,omitempty"`
	Reasoning     bool     `json:"reasoning,omitempty"`
}

DiscoveredModel is a model entry normalized from a provider /models listing endpoint. It is intentionally separate from config.ModelConfig because discovery results are drafts until a user explicitly adds them.

func DiscoverModels 

func DiscoverModels(ctx context.Context, opts DiscoverModelsOptions) ([]DiscoveredModel, error)

DiscoverModels validates the base URL, builds an HTTP client honoring proxy and HTTP/1.1 options, and fetches the provider /models listing.

func FetchDiscoveredModels 

func FetchDiscoveredModels(ctx context.Context, client *http.Client, endpoint, api, apiKey string, headers map[string]string) ([]DiscoveredModel, error)

FetchDiscoveredModels issues a GET against endpoint using client and parses the response. Errors never include the upstream response body: providers can return credentials, private diagnostics, or arbitrary HTML there, and the HTTP status alone is enough to explain a discovery failure.

func ParseDiscoveredModels 

func ParseDiscoveredModels(body []byte) ([]DiscoveredModel, error)

ParseDiscoveredModels normalizes a /models response body from the common provider envelope shapes ({"data": [...]}, {"models": [...]}, or a bare array) into DiscoveredModel entries.

type FileContent 

type FileContent struct {
	ID          string `json:"id,omitempty"`
	URL         string `json:"url,omitempty"`
	Data        string `json:"data,omitempty"` // base64 encoded
	Filename    string `json:"filename,omitempty"`
	MimeType    string `json:"mimeType,omitempty"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	Size        *int   `json:"size,omitempty"`
}

FileContent identifies an existing provider file or carries an inline file payload for APIs that support file content blocks.

type HTTPClientOptions 

type HTTPClientOptions struct {
	ProxyURL    string
	ForceHTTP11 bool
}

HTTPClientOptions controls provider HTTP transport behavior.

type HostedItem 

type HostedItem struct {
	ID          string         `json:"id,omitempty"`
	Type        string         `json:"type,omitempty"`
	Status      string         `json:"status,omitempty"`
	OutputIndex int            `json:"outputIndex,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

HostedItem is a provider-neutral lifecycle projection for native hosted tools. The canonical payload remains in the response archive; this event is only for live consumers that need added/done status without reimplementing a vendor codec.

type ImageContent 

type ImageContent struct {
	Data           string  `json:"data"`     // base64 encoded
	MimeType       string  `json:"mimeType"` // e.g. "image/png"
	Width          int     `json:"width,omitempty"`
	Height         int     `json:"height,omitempty"`
	Bytes          int     `json:"bytes,omitempty"`
	OriginalWidth  int     `json:"originalWidth,omitempty"`
	OriginalHeight int     `json:"originalHeight,omitempty"`
	OriginalBytes  int     `json:"originalBytes,omitempty"`
	Detail         string  `json:"detail,omitempty"` // "auto", "fast", "detail", "raw"
	Scale          float64 `json:"scale,omitempty"`
	Cropped        bool    `json:"cropped,omitempty"`
	CropX          int     `json:"cropX,omitempty"`
	CropY          int     `json:"cropY,omitempty"`
	CropWidth      int     `json:"cropWidth,omitempty"`
	CropHeight     int     `json:"cropHeight,omitempty"`
}

ImageContent represents an image in a message.

func (ImageContent) MapNormalizedPointToOriginal 

func (img ImageContent) MapNormalizedPointToOriginal(x, y, max float64) (float64, float64, bool)

MapNormalizedPointToOriginal maps a point from a normalized coordinate space such as [0,1000] back to the original source image coordinate space.

func (ImageContent) MapNormalizedRectToOriginal 

func (img ImageContent) MapNormalizedRectToOriginal(x, y, width, height, max float64) (float64, float64, float64, float64, bool)

MapNormalizedRectToOriginal maps a rectangle from a normalized coordinate space such as [0,1000] back to the original source image coordinate space.

func (ImageContent) MapPointToOriginal 

func (img ImageContent) MapPointToOriginal(x, y float64) (float64, float64, bool)

MapPointToOriginal maps a point in the sent image coordinate space back to the original source image coordinate space.

func (ImageContent) MapRectToOriginal 

func (img ImageContent) MapRectToOriginal(x, y, width, height float64) (float64, float64, float64, float64, bool)

MapRectToOriginal maps a rectangle in sent image coordinates back to the original source image coordinate space.

type Message 

type Message struct {
	Role           string         `json:"role"`                  // "user", "assistant", "toolResult"
	Content        string         `json:"content,omitempty"`     // simple text content
	Contents       []ContentBlock `json:"contents,omitempty"`    // rich content blocks
	Attachments    []Attachment   `json:"attachments,omitempty"` // provider-neutral output artifacts
	ToolCallID     string         `json:"toolCallId,omitempty"`  // for toolResult
	ToolName       string         `json:"toolName,omitempty"`    // for toolResult
	ToolKind       string         `json:"toolKind,omitempty"`    // function or custom
	IsError        bool           `json:"isError,omitempty"`     // for toolResult
	Timestamp      time.Time      `json:"timestamp"`
	Usage          *Usage         `json:"usage,omitempty"`          // token usage from API response
	SystemInjected bool           `json:"systemInjected,omitempty"` // true for injected messages (session context, compression instructions) - skipped by cache markers
}

Message represents a conversation message.

func NewAssistantMessage 

func NewAssistantMessage(contents []ContentBlock) Message

NewAssistantMessage creates an assistant message with content blocks.

func NewSystemInjectedUserMessage 

func NewSystemInjectedUserMessage(text string) Message

NewSystemInjectedUserMessage creates a system-injected user message (skipped by cache markers).

func NewToolResultMessage 

func NewToolResultMessage(toolCallID, toolName, content string, isError bool) Message

NewToolResultMessage creates a tool result message.

func NewToolResultMessageWithContents 

func NewToolResultMessageWithContents(toolCallID, toolName, text string, contents []ContentBlock, isError bool) Message

NewToolResultMessageWithContents creates a tool result message with rich content blocks. If contents is nil or empty, it falls back to using the text parameter.

func NewUserMessage 

func NewUserMessage(text string) Message

NewUserMessage creates a simple user text message.

func NormalizeMessage 

func NormalizeMessage(msg Message) (normalized Message, notices []string)

NormalizeMessage returns a deep-enough copy of msg for safe persistence and replay. It repairs every embedded tool call while leaving the caller's message and argument buffers untouched. The returned notices identify tool calls that were repaired so the Agent can make the recovery visible to the model instead of silently changing a request.

type MockProvider 

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

MockProvider is a mock implementation of Provider for testing.

func NewMockProvider 

func NewMockProvider(name string, models []*Model, responses []StreamEvent) *MockProvider

NewMockProvider creates a new MockProvider.

func (*MockProvider) API 

func (p *MockProvider) API() string

API returns the protocol/API type.

func (*MockProvider) Chat 

func (p *MockProvider) Chat(ctx context.Context, params ChatParams) <-chan StreamEvent

Chat sends a chat request and returns a channel of streaming events.

func (*MockProvider) GetCallCount 

func (p *MockProvider) GetCallCount() int

GetCallCount returns the number of times Chat was called.

func (*MockProvider) GetModel 

func (p *MockProvider) GetModel(id string) *Model

GetModel returns a model by ID, or nil if not found.

func (*MockProvider) Models 

func (p *MockProvider) Models() []*Model

Models returns the list of available models.

func (*MockProvider) Name 

func (p *MockProvider) Name() string

Name returns the provider's name.

func (*MockProvider) SetAPI 

func (p *MockProvider) SetAPI(api string)

SetAPI sets the mock provider's API type.

type Model 

type Model struct {
	ID            string       `json:"id"`
	Name          string       `json:"name"`
	Provider      string       `json:"provider"`
	Reasoning     bool         `json:"reasoning"` // supports extended thinking
	Input         []string     `json:"input"`     // "text", "image", "audio", "video"
	Cost          ModelPricing `json:"cost"`
	ContextWindow int          `json:"contextWindow"`         // max context tokens
	MaxTokens     int          `json:"maxTokens"`             // max output tokens
	MaxTokensSet  bool         `json:"-"`                     // true when maxTokens came from user/runtime config
	Temperature   *float64     `json:"temperature,omitempty"` // nil = use API default
	TopP          *float64     `json:"topP,omitempty"`        // nil = use API default
	Compat        *ModelCompat `json:"compat,omitempty"`
}

Model represents a model available from a provider.

func (*Model) SupportsInput 

func (m *Model) SupportsInput(kind string) bool

SupportsInput reports whether the model declares support for one input modality ("text", "image", "audio", "video"). It is the shared capability resolver used by Agent Core and the Runtime input pipeline; adapters must not re-implement modality checks against Model.Input.

type ModelCompat 

type ModelCompat struct {
	ThinkingFormat                      string `json:"thinkingFormat,omitempty"`
	RequiresReasoningContentOnAssistant bool   `json:"requiresReasoningContentOnAssistant,omitempty"`
	ForceAdaptiveThinking               bool   `json:"forceAdaptiveThinking,omitempty"`
	// ParseReasoningInContent extracts <think>...</think> wrapped reasoning from
	// the content stream for models that inline thinking in the body.
	ParseReasoningInContent bool `json:"parseReasoningInContent,omitempty"`

	SupportsDeveloperRole      *bool           `json:"supportsDeveloperRole,omitempty"`
	SupportsStore              *bool           `json:"supportsStore,omitempty"`
	SupportsResponses          *bool           `json:"supportsResponses,omitempty"`
	SupportsPreviousResponseID *bool           `json:"supportsPreviousResponseId,omitempty"`
	SupportsConversation       *bool           `json:"supportsConversation,omitempty"`
	SupportsBackground         *bool           `json:"supportsBackground,omitempty"`
	SupportsStructuredOutput   *bool           `json:"supportsStructuredOutput,omitempty"`
	SupportsServiceTier        *bool           `json:"supportsServiceTier,omitempty"`
	SupportsParallelToolCalls  *bool           `json:"supportsParallelToolCalls,omitempty"`
	SupportsToolChoice         *bool           `json:"supportsToolChoice,omitempty"`
	SupportsHostedTools        map[string]bool `json:"supportsHostedTools,omitempty"`
	SupportedInclude           []string        `json:"supportedInclude,omitempty"`
	SupportsReasoningEffort    *bool           `json:"supportsReasoningEffort,omitempty"`
	SupportsStrictMode         *bool           `json:"supportsStrictMode,omitempty"`
	MaxTokensField             string          `json:"maxTokensField,omitempty"`
	// DisableSamplingParams omits temperature/top_p from requests. It defaults
	// to true (nil): sampling parameters are only sent when explicitly set to
	// false for models that accept them.
	DisableSamplingParams *bool `json:"disableSamplingParams,omitempty"`

	SupportsCacheControlOnTools *bool `json:"supportsCacheControlOnTools,omitempty"`
	SupportsLongCacheRetention  *bool `json:"supportsLongCacheRetention,omitempty"`
	SupportsPromptCacheKey      *bool `json:"supportsPromptCacheKey,omitempty"`
	SupportsReasoningSummary    *bool `json:"supportsReasoningSummary,omitempty"`
	SendSessionAffinityHeaders  bool  `json:"sendSessionAffinityHeaders,omitempty"`

	SupportsEagerToolInputStreaming *bool `json:"supportsEagerToolInputStreaming,omitempty"`
}

ModelCompat captures vendor-specific behavior flags for otherwise compatible APIs.

type ModelPricing 

type ModelPricing struct {
	Input      float64 `json:"input"`
	Output     float64 `json:"output"`
	CacheRead  float64 `json:"cacheRead"`
	CacheWrite float64 `json:"cacheWrite"`
}

ModelPricing represents the cost per million tokens for a model.

type Provider 

type Provider interface {
	// Chat sends a chat request and returns a channel of streaming events.
	Chat(ctx context.Context, params ChatParams) <-chan StreamEvent

	// Name returns the provider's name (e.g. "openai", "anthropic").
	Name() string

	// API returns the protocol/API type (e.g. "openai-chat", "anthropic-messages").
	API() string

	// Models returns the list of available models.
	Models() []*Model

	// GetModel returns a model by ID, or nil if not found.
	GetModel(id string) *Model
}

Provider is the interface that all LLM providers must implement.

func CreateProvider 

func CreateProvider(name string, cfg *config.ProviderConfig) (Provider, error)

CreateProvider creates a provider using the global registry.

func ResolveProvider 

func ResolveProvider(cfg *config.ProviderConfig) (Provider, error)

ResolveProvider resolves a provider from config with three-level fallback: 1. explicit vendor 2. baseUrl auto-detect 3. generic fallback by API protocol

type ProviderFactory 

type ProviderFactory func(cfg *config.ProviderConfig) (Provider, error)

ProviderFactory creates a Provider from a ProviderConfig.

type ProviderRegistry 

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

ProviderRegistry manages provider factory registration and creation.

func NewProviderRegistry 

func NewProviderRegistry() *ProviderRegistry

NewProviderRegistry creates a new provider registry.

func (*ProviderRegistry) Create 

func (r *ProviderRegistry) Create(name string, cfg *config.ProviderConfig) (Provider, error)

Create creates a provider by name using the given config.

func (*ProviderRegistry) Has 

func (r *ProviderRegistry) Has(name string) bool

Has checks if a provider is registered.

func (*ProviderRegistry) List 

func (r *ProviderRegistry) List() []string

List returns all registered provider names.

func (*ProviderRegistry) Register 

func (r *ProviderRegistry) Register(name string, factory ProviderFactory)

Register registers a provider factory by name.

type ResponseArchive 

type ResponseArchive struct {
	ResponseID         string
	Status             string
	PreviousResponseID string
	ConversationID     string
	IncompleteReason   string
	StateMode          string
	Usage              *Usage
	Items              []ResponseArchiveItem
	Attachments        []Attachment
	UnknownEventTypes  []string
}

ResponseArchive is a protocol-neutral durable representation of a Responses turn. Providers retain their private wire codecs and only expose the fields required by session recovery and audit.

type ResponseArchiveItem 

type ResponseArchiveItem struct {
	ID          string
	Type        string
	Status      string
	OutputIndex int
	Canonical   json.RawMessage
}

type ResponseOptions 

type ResponseOptions struct {
	StructuredOutput *StructuredOutputOptions `json:"structuredOutput,omitempty"`
	ToolChoice       *ToolChoice              `json:"toolChoice,omitempty"`
	ParallelTools    *bool                    `json:"parallelTools,omitempty"`
	MaxToolCalls     *int                     `json:"maxToolCalls,omitempty"`
	// PreviousResponseID is used by providers that support remote response
	// lineage. It is optional so replay remains the default state strategy.
	PreviousResponseID string `json:"previousResponseId,omitempty"`
	// ReplayItems is a complete, ordered Responses input history. When set,
	// providers that support native item replay use it instead of rebuilding
	// the same history from role messages.
	ReplayItems []json.RawMessage `json:"-"`
	// SuppressConversation requests a local replay without the configured
	// remote conversation, used only after a provider reports that the remote
	// conversation is unavailable.
	SuppressConversation bool `json:"-"`
	// ResponseArchive receives a provider-neutral, sanitized representation of
	// a completed Responses turn. It is runtime-only and is never serialized.
	ResponseArchive func(ResponseArchive) `json:"-"`
}

ResponseOptions carries protocol features that have provider-neutral semantics. Provider-specific runtime state remains in provider config.

type ResponseStateFailureClass 

type ResponseStateFailureClass string

ResponseStateFailureClass describes a failed remote lineage request without exposing provider wire errors to session archives. 

const (
	ResponseStateFailureExpired       ResponseStateFailureClass = "expired"
	ResponseStateFailurePermission    ResponseStateFailureClass = "permission"
	ResponseStateFailureRequestFailed ResponseStateFailureClass = "request_failed"
)

type ResponseStateFailureClassifier 

type ResponseStateFailureClassifier interface {
	ResponseStateFailureClass(error) ResponseStateFailureClass
}

ResponseStateFailureClassifier reports a stable classification suitable for recovery/audit decisions.

type ResponseStateFallbackProvider 

type ResponseStateFallbackProvider interface {
	ResponseStateFallbackError(error) bool
}

ResponseStateFallbackProvider identifies remote lineage errors for which the agent may safely retry the current turn from its local replay archive.

type ResponseStateModeProvider 

type ResponseStateModeProvider interface {
	ResponseStateMode() string
}

ResponseStateModeProvider exposes the selected remote state behavior to the agent loop without leaking a provider's configuration implementation.

type RetryConfig 

type RetryConfig struct {
	Enabled     bool
	MaxRetries  int
	BaseDelayMs int
}

RetryConfig controls automatic retry behavior for API calls.

type StreamEvent 

type StreamEvent struct {
	Type              StreamEventType
	TextDelta         string         // for StreamTextDelta
	ThinkDelta        string         // for StreamThinkDelta
	ThinkSignature    string         // for StreamThinkSignature
	ToolCall          *ToolCallBlock // for StreamToolCall
	HostedItem        *HostedItem    // for StreamHostedItem
	Usage             *Usage         // for StreamUsage
	Error             error          // for StreamError
	StopReason        string         // for StreamDone: "stop", "length", "toolUse", "error", "aborted"
	RetryAttempt      int            // for StreamRetry: current retry attempt number
	RetryMax          int            // Deprecated: use RetryMaxAttempts.
	RetryMaxAttempts  int            // for StreamRetry: maximum retry attempts
	RetryAfterMS      int            // for StreamRetry: delay before the next attempt, in milliseconds
	RetryDetail       string         // for StreamRetry: sanitized single-line provider diagnostic for optional UI display; never affects retry behavior
	ProviderEventType string         // provider-native event type, sanitized
	ItemID            string         // protocol item id, when provider-neutral
	CallID            string         // protocol tool/function call id, when provider-neutral
	Metadata          map[string]any // sanitized, size-limited provider-neutral metadata
	Attachments       []Attachment   // sanitized generated files, citations, artifacts, tool results
}

StreamEvent represents a single event from a streaming response.

type StreamEventType 

type StreamEventType int

StreamEventType identifies the type of a streaming event. 

const (
	StreamStart          StreamEventType = iota // Stream started
	StreamTextDelta                             // Text content delta
	StreamThinkDelta                            // Thinking content delta
	StreamThinkSignature                        // Thinking block signature (for multi-turn replay)
	StreamToolCall                              // Tool call event
	StreamUsage                                 // Usage statistics
	StreamDone                                  // Stream completed
	StreamError                                 // Error occurred
	StreamHostedItem                            // Hosted Responses item lifecycle event
	StreamRetry                                 // Retry attempt in progress
)

type StructuredOutputOptions 

type StructuredOutputOptions struct {
	Name        string          `json:"name,omitempty"`
	Description string          `json:"description,omitempty"`
	Strict      bool            `json:"strict,omitempty"`
	Schema      json.RawMessage `json:"schema,omitempty"`
	Format      string          `json:"format,omitempty"` // text, json_object, json_schema
}

StructuredOutputOptions describes cross-provider structured text output.

type ThinkingLevel 

type ThinkingLevel string

ThinkingLevel represents the depth of reasoning. 

const (
	ThinkingOff     ThinkingLevel = "off"
	ThinkingMinimal ThinkingLevel = "minimal"
	ThinkingLow     ThinkingLevel = "low"
	ThinkingMedium  ThinkingLevel = "medium"
	ThinkingHigh    ThinkingLevel = "high"
	ThinkingXHigh   ThinkingLevel = "xhigh"
	ThinkingMax     ThinkingLevel = "max"
)

func NormalizeThinkingLevel 

func NormalizeThinkingLevel(level ThinkingLevel) ThinkingLevel

NormalizeThinkingLevel ensures a valid thinking level is returned. Empty or invalid values fall back to ThinkingMedium for reasoning models.

type ToolCallBlock 

type ToolCallBlock struct {
	ID               string          `json:"id"`
	Name             string          `json:"name"`
	Kind             string          `json:"kind,omitempty"` // function or custom
	Input            string          `json:"input,omitempty"`
	Arguments        json.RawMessage `json:"arguments"`
	InvalidArguments string          `json:"invalidArguments,omitempty"`
	ThoughtSignature string          `json:"thoughtSignature,omitempty"`
}

ToolCallBlock represents a tool call in an assistant message.

type ToolChoice 

type ToolChoice struct {
	Type string `json:"type,omitempty"` // auto, none, required, function
	Name string `json:"name,omitempty"` // function/custom tool name for explicit choices
}

ToolChoice describes cross-provider tool choice controls.

type ToolDefinition 

type ToolDefinition struct {
	Name         string          `json:"name"`
	Description  string          `json:"description"`
	Parameters   json.RawMessage `json:"parameters"`       // JSON Schema
	Kind         string          `json:"kind,omitempty"`   // function (default), custom, or hosted
	Format       json.RawMessage `json:"format,omitempty"` // custom tool text/grammar format
	Provider     string          `json:"provider,omitempty"`
	ProviderType string          `json:"providerType,omitempty"`
	Model        string          `json:"model,omitempty"`
}

ToolDefinition describes a tool available to the model.

type TurnClassification 

type TurnClassification int

TurnClassification describes whether a completed stream turn produced a meaningful response or was effectively empty (a likely provider error such as HTTP 200 with placeholder usage and no content). It is vendor- and protocol-agnostic so the agent loop can use it as a universal fallback regardless of which provider/model is in use. 

const (
	// TurnMeaningful means the turn produced content (text/thinking/toolCall)
	// or the model explicitly signalled a normal stop.
	TurnMeaningful TurnClassification = iota
	// TurnEmpty means the turn produced no content AND usage looks like a
	// placeholder/error sentinel with no explicit stop reason. This is the
	// signature of a provider returning an empty/error response (e.g. some
	// OpenAI-compatible gateways return usage {1,1,2} on empty/error bodies).
	TurnEmpty
)

func ClassifyTurn 

func ClassifyTurn(text, think string, toolCalls []ToolCallBlock, usage *Usage, stopReason string) TurnClassification

ClassifyTurn inspects the accumulated turn output and reports whether it is a meaningful response or an effectively empty one. It is the shared, vendor-agnostic signal the agent loop uses to decide whether a "no tool call" turn is a legitimate model-chosen stop or a provider failure that should be retried instead of silently ending the session.

The judgement rests on two cross-vendor invariants:

  • any real response carries at least the prompt tokens in usage.Input, so Input<=1 (or nil usage) with empty content cannot be a normal stop;
  • a model that genuinely chose to stop reports an explicit stop reason (stop/end_turn/finish/...), which we honour even with empty content.

type Usage 

type Usage struct {
	Input       int  `json:"input"`
	Output      int  `json:"output"`
	Reasoning   int  `json:"reasoning,omitempty"`
	CacheRead   int  `json:"cacheRead"`
	CacheWrite  int  `json:"cacheWrite"`
	TotalTokens int  `json:"totalTokens"`
	Cost        Cost `json:"cost"`
}

Usage represents token usage and cost information.

func (*Usage) CacheInfo 

func (u *Usage) CacheInfo() string

CacheInfo returns a short display string for cache activity (e.g. "Cache: 75%"), or an empty string when there is no cache data to show.

Cache percentage uses the full prompt footprint as the denominator so the value means "what portion of this turn's prompt came from cache".

func (*Usage) CalculateCost 

func (u *Usage) CalculateCost(model *Model)

CalculateCost computes the cost based on the model's pricing.

func (*Usage) PromptTokens 

func (u *Usage) PromptTokens() int

PromptTokens returns the provider-reported prompt token count for the turn. For OpenAI-compatible APIs this is the full prompt footprint. For Anthropic, Input is normalized to the non-cached prompt portion, so callers that need the full prompt footprint should use TotalInputTokens instead.

func (*Usage) TotalInputTokens 

func (u *Usage) TotalInputTokens() int

TotalInputTokens returns the full input footprint for the turn, including cache reads and cache writes when those are reported separately.

func (*Usage) UncachedInputTokens 

func (u *Usage) UncachedInputTokens() int

UncachedInputTokens returns input tokens to charge at the regular input rate. Anthropic reports Input separately from cache reads and writes, while OpenAI-compatible and Google APIs include cache reads in Input. TotalTokens lets us distinguish those wire formats without leaking provider types into shared accounting.

type VendorAdapter 

type VendorAdapter interface {
	Name() string
	MatchBaseURL(baseURL string) bool
	Apply(*AdapterConfig)
}

VendorAdapter applies vendor-specific defaults while keeping protocol providers generic.

func GetVendorAdapter 

func GetVendorAdapter(name string) (VendorAdapter, bool)

GetVendorAdapter returns a registered vendor adapter by name.

type VideoContent 

type VideoContent struct {
	MimeType string `json:"mimeType,omitempty"` // e.g. "video/mp4"
	Data     string `json:"data,omitempty"`     // base64 encoded
	URL      string `json:"url,omitempty"`
	Bytes    int    `json:"bytes,omitempty"`
}

VideoContent carries inline video input for models with native video understanding. Data is the base64-encoded payload; URL is an alternative transport for wire formats that accept a remote or data URL reference. Video input is user-turn only: assistant messages never carry video blocks.

Source Files

View all Source files

Directories

Path Synopsis

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.