provider

package
v1.1.57 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	HostedToolWebSearch                  = "web_search"
	HostedToolWebSearchAnthropicMessages = "web_search_20250305"
)

Variables

This section is empty.

Functions

func ApplyHeaders 

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

ApplyHeaders applies configured custom headers after provider defaults.

func FormatRetryMessage 

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

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

func HostedWebSearchToolType 

func HostedWebSearchToolType(providerType, name string) string

HostedWebSearchToolType maps a hosted web_search tool to the provider-specific wire type. It is provider-neutral: the mapping depends on the tool's API family, not the vendor name.

func IsRetryable 

func IsRetryable(err error, statusCode int) bool

IsRetryable determines whether an error or HTTP status code warrants a retry. Returns true for transient network errors and server-side overload/status errors.

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 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 NextToolCallFallbackID 

func NextToolCallFallbackID(prefix string) string

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

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 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 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 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
}

ChatParams contains all parameters for a chat request.

type ContentBlock 

type ContentBlock struct {
	Type         string         `json:"type"` // "text", "image", "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"`
	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 HTTPClientOptions 

type HTTPClientOptions struct {
	ProxyURL    string
	ForceHTTP11 bool
}

HTTPClientOptions controls provider HTTP transport behavior.

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
	ToolCallID     string         `json:"toolCallId,omitempty"` // for toolResult
	ToolName       string         `json:"toolName,omitempty"`   // for toolResult
	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.

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"
	Cost          ModelPricing `json:"cost"`
	ContextWindow int          `json:"contextWindow"`         // max context tokens
	MaxTokens     int          `json:"maxTokens"`             // max output tokens
	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.

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"`
	SupportsReasoningEffort *bool  `json:"supportsReasoningEffort,omitempty"`
	SupportsStrictMode      *bool  `json:"supportsStrictMode,omitempty"`
	MaxTokensField          string `json:"maxTokensField,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 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
	Usage          *Usage         // for StreamUsage
	Error          error          // for StreamError
	StopReason     string         // for StreamDone: "stop", "length", "toolUse", "error", "aborted"
	RetryAttempt   int            // for StreamRetry: current attempt number
	RetryMax       int            // for StreamRetry: max attempts
}

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
	StreamRetry                                 // Retry attempt in progress
)

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

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"`
	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 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) or "hosted"
	Provider     string          `json:"provider,omitempty"`
	ProviderType string          `json:"providerType,omitempty"`
	Model        string          `json:"model,omitempty"`
}

ToolDefinition describes a tool available to the model.

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.

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.

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.