providers

package
v0.2.7 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2026 License: MIT Imports: 20 Imported by: 1

Documentation

Index

Constants

View Source 
const CodexHomeEnvVar = cliprovider.CodexHomeEnvVar

Variables

This section is empty.

Functions

func CreateCodexCliTokenSource added in v0.1.2 

func CreateCodexCliTokenSource() func() (string, string, error)

func DefaultAPIBaseForProtocol added in v0.2.5 

func DefaultAPIBaseForProtocol(protocol string) string

DefaultAPIBaseForProtocol returns the configured default API base for a protocol. It returns empty string if the protocol has no default base.

func ExtractProtocol added in v0.2.0 

func ExtractProtocol(model string) (protocol, modelID string)

ExtractProtocol extracts the protocol prefix and model identifier from a model string. If no prefix is specified, it defaults to "openai". Examples:

  • "openai/gpt-4o" -> ("openai", "gpt-4o")
  • "anthropic/claude-sonnet-4.6" -> ("anthropic", "claude-sonnet-4.6")
  • "gpt-4o" -> ("openai", "gpt-4o") // default protocol

func FetchAntigravityProjectID added in v0.2.0 

func FetchAntigravityProjectID(accessToken string) (string, error)

func IsEmptyAPIKeyAllowedForProtocol added in v0.2.5 

func IsEmptyAPIKeyAllowedForProtocol(protocol string) bool

IsEmptyAPIKeyAllowedForProtocol reports whether a protocol allows requests without api_key when using its default local endpoint.

func IsImageDimensionError added in v0.2.0 

func IsImageDimensionError(msg string) bool

IsImageDimensionError returns true if the message indicates an image dimension error.

func IsImageSizeError added in v0.2.0 

func IsImageSizeError(msg string) bool

IsImageSizeError returns true if the message indicates an image file size error.

func ModelKey added in v0.2.0 

func ModelKey(provider, model string) string

ModelKey returns a canonical "provider/model" key for deduplication.

func NormalizeProvider added in v0.2.0 

func NormalizeProvider(provider string) string

NormalizeProvider normalizes provider identifiers to canonical form.

func ReadCodexCliCredentials added in v0.1.2 

func ReadCodexCliCredentials() (accessToken, accountID string, expiresAt time.Time, err error)

func ResolveAPIBase added in v0.2.5 

func ResolveAPIBase(cfg *config.ModelConfig) string

ResolveAPIBase returns the configured API base, or the protocol default when the model uses an HTTP-based provider family with a known default endpoint.

Types

type AntigravityModelInfo added in v0.2.0 

type AntigravityModelInfo = oauthprovider.AntigravityModelInfo

func FetchAntigravityModels added in v0.2.0 

func FetchAntigravityModels(accessToken, projectID string) ([]AntigravityModelInfo, error)

type AntigravityProvider added in v0.2.0 

type AntigravityProvider = oauthprovider.AntigravityProvider

func NewAntigravityProvider added in v0.2.0 

func NewAntigravityProvider() *AntigravityProvider

type CacheControl added in v0.2.0 

type CacheControl = protocoltypes.CacheControl

type ClaudeCliProvider added in v0.1.1 

type ClaudeCliProvider = cliprovider.ClaudeCliProvider

func NewClaudeCliProvider added in v0.1.1 

func NewClaudeCliProvider(workspace string) *ClaudeCliProvider

type ClaudeProvider added in v0.1.1 

type ClaudeProvider = oauthprovider.ClaudeProvider

func NewClaudeProvider added in v0.1.1 

func NewClaudeProvider(token string) *ClaudeProvider

func NewClaudeProviderWithBaseURL added in v0.2.0 

func NewClaudeProviderWithBaseURL(token, apiBase string) *ClaudeProvider

func NewClaudeProviderWithTokenSource added in v0.1.1 

func NewClaudeProviderWithTokenSource(token string, tokenSource func() (string, error)) *ClaudeProvider

func NewClaudeProviderWithTokenSourceAndBaseURL added in v0.2.0 

func NewClaudeProviderWithTokenSourceAndBaseURL(
	token string, tokenSource func() (string, error), apiBase string,
) *ClaudeProvider

type CodexCliAuth added in v0.1.2 

type CodexCliAuth = cliprovider.CodexCliAuth

type CodexCliProvider added in v0.1.2 

type CodexCliProvider = cliprovider.CodexCliProvider

func NewCodexCliProvider added in v0.1.2 

func NewCodexCliProvider(workspace string) *CodexCliProvider

type CodexProvider added in v0.1.1 

type CodexProvider = oauthprovider.CodexProvider

func NewCodexProvider added in v0.1.1 

func NewCodexProvider(token, accountID string) *CodexProvider

func NewCodexProviderWithTokenSource added in v0.1.1 

func NewCodexProviderWithTokenSource(
	token, accountID string, tokenSource func() (string, string, error),
) *CodexProvider

type ContentBlock added in v0.2.0 

type ContentBlock = protocoltypes.ContentBlock

type CooldownTracker added in v0.2.0 

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

CooldownTracker manages per-provider cooldown state for the fallback chain. Thread-safe via sync.RWMutex. In-memory only (resets on restart).

func NewCooldownTracker added in v0.2.0 

func NewCooldownTracker() *CooldownTracker

NewCooldownTracker creates a tracker with default 24h failure window.

func (*CooldownTracker) CooldownRemaining added in v0.2.0 

func (ct *CooldownTracker) CooldownRemaining(provider string) time.Duration

CooldownRemaining returns how long until the provider becomes available. Returns 0 if already available.

func (*CooldownTracker) ErrorCount added in v0.2.0 

func (ct *CooldownTracker) ErrorCount(provider string) int

ErrorCount returns the current error count for a provider.

func (*CooldownTracker) FailureCount added in v0.2.0 

func (ct *CooldownTracker) FailureCount(provider string, reason FailoverReason) int

FailureCount returns the failure count for a specific reason.

func (*CooldownTracker) IsAvailable added in v0.2.0 

func (ct *CooldownTracker) IsAvailable(provider string) bool

IsAvailable returns true if the provider is not in cooldown or disabled.

func (*CooldownTracker) MarkFailure added in v0.2.0 

func (ct *CooldownTracker) MarkFailure(provider string, reason FailoverReason)

MarkFailure records a failure for a provider and sets appropriate cooldown. Resets error counts if last failure was more than failureWindow ago.

func (*CooldownTracker) MarkSuccess added in v0.2.0 

func (ct *CooldownTracker) MarkSuccess(provider string)

MarkSuccess resets all counters and cooldowns for a provider.

type ExtraContent added in v0.2.0 

type ExtraContent = protocoltypes.ExtraContent

type FailoverError added in v0.2.0 

type FailoverError struct {
	Reason   FailoverReason
	Provider string
	Model    string
	Status   int
	Wrapped  error
}

FailoverError wraps an LLM provider error with classification metadata.

func ClassifyError added in v0.2.0 

func ClassifyError(err error, provider, model string) *FailoverError

ClassifyError classifies an error into a FailoverError with reason. Returns nil if the error is not classifiable (unknown errors should not trigger fallback).

func (*FailoverError) Error added in v0.2.0 

func (e *FailoverError) Error() string

func (*FailoverError) IsRetriable added in v0.2.0 

func (e *FailoverError) IsRetriable() bool

IsRetriable returns true if this error should trigger fallback to next candidate. Non-retriable: Format errors (bad request structure, image dimension/size).

func (*FailoverError) Unwrap added in v0.2.0 

func (e *FailoverError) Unwrap() error

type FailoverReason added in v0.2.0 

type FailoverReason string

FailoverReason classifies why an LLM request failed for fallback decisions. 

const (
	FailoverAuth            FailoverReason = "auth"
	FailoverRateLimit       FailoverReason = "rate_limit"
	FailoverBilling         FailoverReason = "billing"
	FailoverNetwork         FailoverReason = "network"
	FailoverTimeout         FailoverReason = "timeout"
	FailoverFormat          FailoverReason = "format"
	FailoverContextOverflow FailoverReason = "context_overflow"
	FailoverOverloaded      FailoverReason = "overloaded"
	FailoverUnknown         FailoverReason = "unknown"
)

type FallbackAttempt added in v0.2.0 

type FallbackAttempt struct {
	Provider string
	Model    string
	Error    error
	Reason   FailoverReason
	Duration time.Duration
	Skipped  bool // true if skipped due to cooldown
}

FallbackAttempt records one attempt in the fallback chain.

type FallbackCandidate added in v0.2.0 

type FallbackCandidate struct {
	Provider    string
	Model       string
	RPM         int    // requests per minute; 0 means unrestricted
	IdentityKey string // optional stable config identity for cooldown/rate limiting
}

FallbackCandidate represents one model/provider to try.

func ResolveCandidates added in v0.2.0 

func ResolveCandidates(cfg ModelConfig, defaultProvider string) []FallbackCandidate

ResolveCandidates parses model config into a deduplicated candidate list.

func ResolveCandidatesWithLookup added in v0.2.0 

func ResolveCandidatesWithLookup(
	cfg ModelConfig,
	defaultProvider string,
	lookup func(raw string) (resolved string, ok bool),
) []FallbackCandidate

func (FallbackCandidate) StableKey added in v0.2.5 

func (c FallbackCandidate) StableKey() string

StableKey returns the candidate's config-level identity when available, otherwise it falls back to the runtime provider/model key.

type FallbackChain added in v0.2.0 

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

FallbackChain orchestrates model fallback across multiple candidates.

func NewFallbackChain added in v0.2.0 

func NewFallbackChain(cooldown *CooldownTracker, rl *RateLimiterRegistry) *FallbackChain

NewFallbackChain creates a new fallback chain with the given cooldown tracker and rate limiter registry.

func (*FallbackChain) Execute added in v0.2.0 

func (fc *FallbackChain) Execute(
	ctx context.Context,
	candidates []FallbackCandidate,
	run func(ctx context.Context, provider, model string) (*LLMResponse, error),
) (*FallbackResult, error)

Execute runs the fallback chain for text/chat requests. It tries each candidate in order, respecting cooldowns and error classification.

Behavior:

  • Candidates in cooldown are skipped (logged as skipped attempt).
  • context.Canceled aborts immediately (user abort, no fallback).
  • Non-retriable errors (format) abort immediately.
  • Retriable errors trigger fallback to next candidate.
  • Success marks provider as good (resets cooldown).
  • If all fail, returns aggregate error with all attempts.

func (*FallbackChain) ExecuteImage added in v0.2.0 

func (fc *FallbackChain) ExecuteImage(
	ctx context.Context,
	candidates []FallbackCandidate,
	run func(ctx context.Context, provider, model string) (*LLMResponse, error),
) (*FallbackResult, error)

ExecuteImage runs the fallback chain for image/vision requests. Simpler than Execute: no cooldown checks (image endpoints have different rate limits). Image dimension/size errors abort immediately (non-retriable).

type FallbackExhaustedError added in v0.2.0 

type FallbackExhaustedError struct {
	Attempts []FallbackAttempt
}

FallbackExhaustedError indicates all fallback candidates were tried and failed.

func (*FallbackExhaustedError) Error added in v0.2.0 

func (e *FallbackExhaustedError) Error() string

type FallbackResult added in v0.2.0 

type FallbackResult struct {
	Response *LLMResponse
	Provider string
	Model    string
	Attempts []FallbackAttempt
}

FallbackResult contains the successful response and metadata about all attempts.

type FunctionCall 

type FunctionCall = protocoltypes.FunctionCall

type GeminiProvider added in v0.2.7 

type GeminiProvider = httpapi.GeminiProvider

func NewGeminiProvider added in v0.2.7 

func NewGeminiProvider(
	apiKey string,
	apiBase string,
	proxy string,
	userAgent string,
	requestTimeoutSeconds int,
	extraBody map[string]any,
	customHeaders map[string]string,
) *GeminiProvider

type GitHubCopilotProvider added in v0.1.2 

type GitHubCopilotProvider = cliprovider.GitHubCopilotProvider

func NewGitHubCopilotProvider added in v0.1.2 

func NewGitHubCopilotProvider(uri string, connectMode string, model string) (*GitHubCopilotProvider, error)

type GoogleExtra added in v0.2.0 

type GoogleExtra = protocoltypes.GoogleExtra

type HTTPProvider 

type HTTPProvider = httpapi.HTTPProvider

func NewHTTPProvider 

func NewHTTPProvider(apiKey, apiBase, proxy string) *HTTPProvider

func NewHTTPProviderWithMaxTokensField added in v0.2.0 

func NewHTTPProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string) *HTTPProvider

func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout added in v0.2.0 

func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
	apiKey, apiBase, proxy, maxTokensField, userAgent string,
	requestTimeoutSeconds int,
	extraBody map[string]any,
	customHeaders map[string]string,
) *HTTPProvider

type LLMProvider 

type LLMProvider interface {
	Chat(
		ctx context.Context,
		messages []Message,
		tools []ToolDefinition,
		model string,
		options map[string]any,
	) (*LLMResponse, error)
	GetDefaultModel() string
}

func CreateProvider 

func CreateProvider(cfg *config.Config) (LLMProvider, string, error)

CreateProvider creates a provider based on the configuration. It uses the model_list configuration (new format) to create providers. The old providers config is automatically converted to model_list during config loading. Returns the provider, the model ID to use, and any error.

func CreateProviderFromConfig added in v0.2.0 

func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, error)

CreateProviderFromConfig creates a provider based on the ModelConfig. It uses the protocol prefix in the Model field to determine which provider to create. Supported protocol families include OpenAI-compatible prefixes (e.g., openai, openrouter, groq), Azure OpenAI, Amazon Bedrock, Anthropic (including messages), and various CLI/compatibility shims. See the switch on protocol in this function for the authoritative list. Returns the provider, the model ID (without protocol prefix), and any error.

type LLMResponse 

type LLMResponse = protocoltypes.LLMResponse

type Message 

type Message = protocoltypes.Message

type ModelConfig added in v0.2.0 

type ModelConfig struct {
	Primary   string
	Fallbacks []string
}

ModelConfig holds primary model and fallback list.

type ModelRef added in v0.2.0 

type ModelRef struct {
	Provider string
	Model    string
}

ModelRef represents a parsed model reference with provider and model name.

func ParseModelRef added in v0.2.0 

func ParseModelRef(raw string, defaultProvider string) *ModelRef

ParseModelRef parses "anthropic/claude-opus" into {Provider: "anthropic", Model: "claude-opus"}. If no slash present, uses defaultProvider. Returns nil for empty input.

type NativeSearchCapable added in v0.2.4 

type NativeSearchCapable interface {
	SupportsNativeSearch() bool
}

NativeSearchCapable is an optional interface for providers that support built-in web search during LLM inference (e.g. OpenAI web_search_preview, xAI Grok search). When the active provider implements this interface and returns true, the agent loop can hide the client-side web_search tool to avoid duplicate search surfaces and use the provider's native search instead.

type RateLimiter added in v0.2.5 

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

RateLimiter implements a token-bucket rate limiter for a single key. Allows up to RPM requests per minute with a burst equal to RPM. Thread-safe.

func (*RateLimiter) TryAcquire added in v0.2.5 

func (rl *RateLimiter) TryAcquire() bool

TryAcquire attempts to consume a token without blocking.

func (*RateLimiter) Wait added in v0.2.5 

func (rl *RateLimiter) Wait(ctx context.Context) error

Wait blocks until a token is available or ctx is canceled. Returns ctx.Err() if canceled while waiting.

type RateLimiterRegistry added in v0.2.5 

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

RateLimiterRegistry holds per-candidate rate limiters. Candidates with RPM=0 are unrestricted. Thread-safe for concurrent reads/writes.

func NewRateLimiterRegistry added in v0.2.5 

func NewRateLimiterRegistry() *RateLimiterRegistry

NewRateLimiterRegistry creates an empty registry.

func (*RateLimiterRegistry) Register added in v0.2.5 

func (r *RateLimiterRegistry) Register(key string, rpm int)

Register adds a rate limiter for the given key at the given RPM. If rpm <= 0, no limiter is registered (unrestricted).

func (*RateLimiterRegistry) RegisterCandidates added in v0.2.5 

func (r *RateLimiterRegistry) RegisterCandidates(candidates []FallbackCandidate)

RegisterCandidates registers rate limiters for all candidates that have RPM > 0. Candidates with RPM == 0 are ignored (no restriction).

func (*RateLimiterRegistry) TryAcquire added in v0.2.5 

func (r *RateLimiterRegistry) TryAcquire(key string) bool

TryAcquire attempts to consume a token for the given key without blocking. If no limiter is registered for key, it returns true.

func (*RateLimiterRegistry) Wait added in v0.2.5 

func (r *RateLimiterRegistry) Wait(ctx context.Context, key string) error

Wait acquires a token for the given key, blocking if needed. If no limiter is registered for key, returns immediately.

type StatefulProvider added in v0.2.0 

type StatefulProvider interface {
	LLMProvider
	Close()
}

type StreamingProvider added in v0.2.4 

type StreamingProvider interface {
	ChatStream(
		ctx context.Context,
		messages []Message,
		tools []ToolDefinition,
		model string,
		options map[string]any,
		onChunk func(accumulated string),
	) (*LLMResponse, error)
}

StreamingProvider is an optional interface for providers that support token streaming. onChunk receives the accumulated text so far (not individual deltas). The returned LLMResponse is the same complete response for compatibility with tool-call handling.

type ThinkingCapable added in v0.2.1 

type ThinkingCapable interface {
	SupportsThinking() bool
}

ThinkingCapable is an optional interface for providers that support extended thinking (e.g. Anthropic). Used by the agent loop to warn when thinking_level is configured but the active provider cannot use it.

type ToolCall 

type ToolCall = protocoltypes.ToolCall

func NormalizeToolCall added in v0.2.0 

func NormalizeToolCall(tc ToolCall) ToolCall

type ToolDefinition 

type ToolDefinition = protocoltypes.ToolDefinition

type ToolFunctionDefinition 

type ToolFunctionDefinition = protocoltypes.ToolFunctionDefinition

type UsageInfo 

type UsageInfo = protocoltypes.UsageInfo

Source Files

View all Source files

Directories

Path Synopsis
Package bedrock provides a stub implementation when built without the bedrock tag.
 Package bedrock provides a stub implementation when built without the bedrock tag.
Package common provides shared utilities used by multiple LLM provider implementations (openai_compat, azure, etc.).
 Package common provides shared utilities used by multiple LLM provider implementations (openai_compat, azure, etc.).
Package openai_responses_common provides shared utilities for providers that use the OpenAI Responses API (e.g., Azure, Codex).
 Package openai_responses_common provides shared utilities for providers that use the OpenAI Responses API (e.g., Azure, Codex).

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.