providers

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Jul 14, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

CLI-era credential helpers.

LoginProvider, WaitForLogin, GetOAuthToken, SetAPIKey and LoginCommand are designed for headless / CLI use. They store credentials in a local file (~/.seshat/auth.json via internal/auth/store.FileStore) and are NOT suited for multi-user server deployments.

In server mode, pass credentials to the engine via sdk.ClientConfig.APIKey or by implementing sdk.CredentialResolver for per-user resolution.

Index

Constants

View Source
const (
	RetryClassificationNetwork               = providerretry.RetryClassificationNetwork
	RetryClassificationRateLimit             = providerretry.RetryClassificationRateLimit
	RetryClassificationServerOverload        = providerretry.RetryClassificationServerOverload
	RetryClassificationTimeout               = providerretry.RetryClassificationTimeout
	RetryClassificationServerError           = providerretry.RetryClassificationServerError
	RetryClassificationClientError           = providerretry.RetryClassificationClientError
	RetryClassificationAuthError             = providerretry.RetryClassificationAuthError
	RetryClassificationUnknown               = providerretry.RetryClassificationUnknown
	RetryClassificationModelDeprecated       = providerretry.RetryClassificationModelDeprecated
	RetryClassificationRegionallyUnavailable = providerretry.RetryClassificationRegionallyUnavailable
	RetryClassificationQuotaExhausted        = providerretry.RetryClassificationQuotaExhausted
)

Variables

This section is empty.

Functions

func AllProvidersInfo

func AllProvidersInfo() map[types.APIProvider]ProviderInfo

func DefaultBaseURL

func DefaultBaseURL(providerName string) string

DefaultBaseURL returns the default API base URL for a provider. These are sync/discovery URLs (no /v1 suffix); client endpoints live in config.go.

func DefaultConfigs

func DefaultConfigs() map[types.APIProvider]*Config

func DefaultModelIdentifier

func DefaultModelIdentifier(provider types.APIProvider) (types.ModelIdentifier, bool)

func GetGlobalAPIKey

func GetGlobalAPIKey() string

GetGlobalAPIKey gets the global API key

func GetOAuthToken

func GetOAuthToken(ctx context.Context, provider string) (string, error)

GetOAuthToken returns a valid OAuth access token for provider, refreshing if needed.

func InitOAuth

func InitOAuth(clientID string)

InitOAuth initializes the OAuth client. clientID defaults to the Codex CLI client ID.

func Is529Error

func Is529Error(resp *http.Response, err error) bool

func IsCircuitBreakerOpenError

func IsCircuitBreakerOpenError(err error) bool

IsCircuitBreakerOpenError checks if an error is a circuit breaker open error

func IsCircuitBreakerTimeoutError

func IsCircuitBreakerTimeoutError(err error) bool

IsCircuitBreakerTimeoutError checks if an error is a circuit breaker timeout error

func IsModelDeprecatedError

func IsModelDeprecatedError(err error, resp *http.Response) bool

func IsQuotaExhaustedError

func IsQuotaExhaustedError(err error, resp *http.Response) bool

func IsRateLimitError

func IsRateLimitError(resp *http.Response) bool

func IsRegionallyUnavailableError

func IsRegionallyUnavailableError(err error, resp *http.Response) bool

func IsRetryableStatus

func IsRetryableStatus(statusCode int) bool

func LoginProvider

func LoginProvider(ctx context.Context, provider string) (string, string, error)

LoginProvider starts the ChatGPT device-code flow and returns the user code + URL to display. CLI-era: saves result to ~/.seshat/auth.json.

func NeedsCatalogReseed

func NeedsCatalogReseed(providerName string, knownModelIDs []string) bool

NeedsCatalogReseed returns true when none of the supplied model IDs exist in the provider's static catalog — meaning models from the wrong provider were seeded, or the list is empty.

func OllamaModelLookup

func OllamaModelLookup() map[string]ModelInfo

OllamaModelLookup returns a name → ModelInfo map of context-window hints for popular Ollama models. It is used as a best-effort fallback when /api/show does not return context length data. The authoritative dynamic model list comes from providers.FetchModels (internal/providers/fetch.go).

func ParseContextOverflowError

func ParseContextOverflowError(err error) (inputTokens, maxTokens, contextLimit int, ok bool)

func RecoveryHint

func RecoveryHint(classification RetryClassification, modelID string) string

func ResolveProviderFromString

func ResolveProviderFromString(s string) types.APIProvider

func RetryWithStrategy

func RetryWithStrategy(
	ctx context.Context,
	strategy *RetryStrategy,
	model types.ModelIdentifier,
	maxTokens int,
	fn RequestFunc,
) (*types.APIResponse, error)

func SetAPIKey

func SetAPIKey(ctx context.Context, provider, apiKey string) error

SetAPIKey explicitly sets an API key

func SetGlobalAPIKey

func SetGlobalAPIKey(key string)

SetGlobalAPIKey sets the global API key

func ValidateProviderConfig

func ValidateProviderConfig(config *Config) error

func WaitForLogin

func WaitForLogin(ctx context.Context, provider string) error

WaitForLogin polls Auth0 until the user completes authentication, then persists the full token to ~/.seshat/auth.json. CLI-era.

Types

type AuthClient

type AuthClient struct {
	*Client
}

AuthClient wraps a Client with authentication support

func NewAuthClient

func NewAuthClient(ctx context.Context, provider types.APIProvider) (*AuthClient, error)

NewAuthClient creates a new auth-aware client

func NewAuthClientWithConfig

func NewAuthClientWithConfig(ctx context.Context, config *Config) (*AuthClient, error)

NewAuthClientWithConfig creates a new auth-aware client with config

type BedrockTransport

type BedrockTransport = providertransport.BedrockTransport

func NewBedrockTransport

func NewBedrockTransport(apiKey string, config *Config) (*BedrockTransport, error)

type CircuitBreaker

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

CircuitBreaker implements the circuit breaker pattern for fault tolerance

func NewCircuitBreaker

func NewCircuitBreaker() *CircuitBreaker

NewCircuitBreaker creates a new circuit breaker with default configuration

func NewCircuitBreakerWithConfig

func NewCircuitBreakerWithConfig(config *CircuitBreakerConfig) *CircuitBreaker

NewCircuitBreakerWithConfig creates a new circuit breaker with custom configuration

func (*CircuitBreaker) CanExecute

func (cb *CircuitBreaker) CanExecute() bool

CanExecute checks if a request would be allowed right now

func (*CircuitBreaker) Execute

func (cb *CircuitBreaker) Execute(fn func() error) error

Execute runs the given function through the circuit breaker

func (*CircuitBreaker) ExecuteWithTimeout

func (cb *CircuitBreaker) ExecuteWithTimeout(ctx context.Context, fn func(context.Context) error) error

ExecuteWithTimeout runs the given function with timeout and circuit breaker protection. The context passed to fn carries the configured CallTimeout deadline; fn must respect ctx.Done() to guarantee no goroutine leaks when the deadline fires.

func (*CircuitBreaker) IsAvailable

func (cb *CircuitBreaker) IsAvailable() bool

IsAvailable checks if the circuit breaker allows calls (compatibility method for engine integration)

func (*CircuitBreaker) RecordFailure

func (cb *CircuitBreaker) RecordFailure()

RecordFailure records a failed call (compatibility method for engine integration)

func (*CircuitBreaker) RecordSuccess

func (cb *CircuitBreaker) RecordSuccess()

RecordSuccess records a successful call (compatibility method for engine integration)

func (*CircuitBreaker) Reset

func (cb *CircuitBreaker) Reset()

Reset resets the circuit breaker to closed state

func (*CircuitBreaker) State

func (cb *CircuitBreaker) State() CircuitState

State returns the current state of the circuit breaker

func (*CircuitBreaker) Stats

func (cb *CircuitBreaker) Stats() CircuitBreakerStats

Stats returns a snapshot of the current statistics

type CircuitBreakerConfig

type CircuitBreakerConfig struct {
	// MaxFailures is the number of consecutive failures before opening the circuit
	MaxFailures int `json:"max_failures"`

	// CallTimeout is the timeout for individual calls
	CallTimeout time.Duration `json:"call_timeout"`

	// ResetTimeout is the time to wait before transitioning from open to half-open
	ResetTimeout time.Duration `json:"reset_timeout"`

	// HalfOpenMaxCalls is the maximum number of calls allowed in half-open state
	HalfOpenMaxCalls int `json:"half_open_max_calls"`

	// ReadyToTrip is a callback that can veto the transition to open state
	ReadyToTrip func() bool `json:"-"`

	// OnStateChange is a callback for state transitions
	OnStateChange func(from, to CircuitState) `json:"-"`

	// Embedded circuit breaker instance for backward compatibility
	*CircuitBreaker
}

CircuitBreakerConfig represents the configuration for a circuit breaker

func DefaultCircuitBreakerConfig

func DefaultCircuitBreakerConfig() *CircuitBreakerConfig

DefaultCircuitBreakerConfig returns default circuit breaker configuration

type CircuitBreakerOpenError

type CircuitBreakerOpenError struct {
	State CircuitState
}

CircuitBreakerOpenError is returned when the circuit is open

func (*CircuitBreakerOpenError) Error

func (e *CircuitBreakerOpenError) Error() string

type CircuitBreakerStats

type CircuitBreakerStats struct {
	// TotalRequests is the total number of requests made
	TotalRequests uint64 `json:"total_requests"`

	// TotalSuccesses is the total number of successful requests
	TotalSuccesses uint64 `json:"total_successes"`

	// TotalFailures is the total number of failed requests
	TotalFailures uint64 `json:"total_failures"`

	// ConsecutiveFailures is the current streak of consecutive failures
	ConsecutiveFailures int `json:"consecutive_failures"`

	// HalfOpenCalls is the number of calls made in half-open state
	HalfOpenCalls int `json:"half_open_calls"`

	// LastFailureTime is when the last failure occurred
	LastFailureTime time.Time `json:"last_failure_time"`

	// LastSuccessTime is when the last success occurred
	LastSuccessTime time.Time `json:"last_success_time"`

	// StateTransitions is the total number of state transitions
	StateTransitions uint64 `json:"state_transitions"`
}

CircuitBreakerStats represents the statistics collected by the circuit breaker

type CircuitBreakerTimeoutError

type CircuitBreakerTimeoutError struct {
	Timeout  time.Duration
	Duration time.Duration
}

CircuitBreakerTimeoutError is returned when a call times out

func (*CircuitBreakerTimeoutError) Error

type CircuitState

type CircuitState string

CircuitState represents the current state of the circuit breaker

const (
	CircuitStateClosed   CircuitState = "closed"    // Requests are allowed
	CircuitStateOpen     CircuitState = "open"      // Requests are blocked
	CircuitStateHalfOpen CircuitState = "half-open" // Limited requests are allowed to test recovery
)

type Client

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

Client represents an API client

func NewClient

func NewClient(apiKey string, providerType types.APIProvider) *Client

NewClient creates a new API client

func NewClientWithConfig

func NewClientWithConfig(apiKey string, config *Config) *Client

NewClientWithConfig creates a new API client with provider-specific configuration

func NewFallbackClient

func NewFallbackClient(ctx context.Context, provider types.APIProvider) (*Client, error)

NewFallbackClient builds a provider client from the provider-local credential sources so the engine can follow configured inter-provider fallback chains.

func (*Client) CircuitBreakerStats

func (c *Client) CircuitBreakerStats() CircuitBreakerStats

CircuitBreakerStats returns the circuit breaker statistics

func (*Client) Config

func (c *Client) Config() *Config

Config returns the provider configuration currently bound to the client.

func (*Client) CreateMessage

func (c *Client) CreateMessage(ctx context.Context, req types.APIRequest) (*types.APIResponse, error)

CreateMessage sends a non-streaming message creation request

func (*Client) CreateMessageStream

func (c *Client) CreateMessageStream(ctx context.Context, req types.APIRequest) (<-chan types.APIResponseChunk, error)

CreateMessageStream sends a streaming message creation request

func (*Client) CreateMessageStreamResult

func (c *Client) CreateMessageStreamResult(ctx context.Context, req types.APIRequest) (*types.APIStreamResult, error)

CreateMessageStreamResult consumes the provider stream and returns a canonical aggregated response.

func (*Client) CreateMessageStreamResultWithCallback

func (c *Client) CreateMessageStreamResultWithCallback(ctx context.Context, req types.APIRequest, onChunk func(types.APIResponseChunk)) (*types.APIStreamResult, error)

CreateMessageStreamResultWithCallback consumes the provider stream, emits normalized chunks to the callback, and returns a canonical aggregated response.

func (*Client) EnableCircuitBreaker

func (c *Client) EnableCircuitBreaker()

EnableCircuitBreaker enables the circuit breaker with default configuration

func (*Client) EnableCircuitBreakerWithConfig

func (c *Client) EnableCircuitBreakerWithConfig(config *CircuitBreakerConfig)

EnableCircuitBreakerWithConfig enables the circuit breaker with custom configuration

func (*Client) GetCircuitBreaker

func (c *Client) GetCircuitBreaker() *CircuitBreaker

GetCircuitBreaker returns the current circuit breaker

func (*Client) ResetCircuitBreaker

func (c *Client) ResetCircuitBreaker()

ResetCircuitBreaker resets the circuit breaker to closed state

func (*Client) SetCircuitBreaker

func (c *Client) SetCircuitBreaker(cb *CircuitBreaker)

SetCircuitBreaker sets the circuit breaker for this client

func (*Client) SetHTTPClient

func (c *Client) SetHTTPClient(client *http.Client)

SetHTTPClient sets the HTTP client

func (*Client) SetMonitoring

func (c *Client) SetMonitoring(monitoringSys *monitoring.System)

SetMonitoring sets the monitoring system

func (*Client) SetRetryConfig

func (c *Client) SetRetryConfig(config types.RetryConfig)

SetRetryConfig sets the retry configuration

type Config

type Config struct {
	Provider          types.APIProvider
	APIKey            string
	BaseURL           string
	Region            string
	ProjectID         string
	ModelAliasMapping map[string]string
	CustomHeaders     map[string]string
	Routing           *RoutingConfig
}

func GetProviderConfig

func GetProviderConfig(provider types.APIProvider) *Config

func (*Config) BuildAuthHeaders

func (c *Config) BuildAuthHeaders() map[string]string

func (*Config) GetBaseURL

func (c *Config) GetBaseURL() string

func (*Config) GetEndpoint

func (c *Config) GetEndpoint(model string) string

func (*Config) IsSupportedModel

func (c *Config) IsSupportedModel(model string) bool

func (*Config) ResolveModel

func (c *Config) ResolveModel(model string) string

type DiscoveryResult

type DiscoveryResult struct {
	Provider    types.APIProvider
	DisplayName string
	Available   bool   // at least one auth credential is present/reachable
	AuthMethod  string // "api_key", "local", "aws", "gcp"
	EnvVar      string // env var name that was checked (empty for local services)
	Recommended bool   // included in the recommended set for first-time setup
	Priority    int    // lower = higher priority in the recommendation list
	Hint        string // human-readable note for the operator
}

DiscoveryResult reports the availability and authentication status of one provider.

func AvailableProviders

func AvailableProviders(ctx context.Context) []DiscoveryResult

AvailableProviders returns only the providers that have credentials present.

func DiscoverProviders

func DiscoverProviders(ctx context.Context) []DiscoveryResult

DiscoverProviders scans the environment for configured providers. It checks known env vars and pings Ollama's local endpoint. Results are sorted by recommendation priority; available providers appear before unavailable ones.

The context is used for the Ollama HTTP health check only.

type FetchedModel

type FetchedModel struct {
	ModelID       string
	DisplayName   string
	ContextWindow int
	MaxOutput     int
	IsDefault     bool
	SortOrder     int
}

FetchedModel is a provider-neutral model description returned by FetchModels and StaticModels. Callers convert it to their own storage type.

func FetchModels

func FetchModels(ctx context.Context, providerName, baseURL, apiKey string) ([]FetchedModel, error)

FetchModels retrieves the live model list from a provider API. For Ollama it calls /api/tags and enriches each model via /api/show. For OpenAI-compatible providers it calls /v1/models. Returns an error so the caller can fall back to StaticModels.

func NormalizeModels

func NormalizeModels(providerName string, models []FetchedModel) []FetchedModel

NormalizeModels applies provider-specific post-processing to a raw model list. Currently handles Z.ai (restricts to the 3 allowed GLM models and merges static metadata).

func StaticModels

func StaticModels(providerName string) []FetchedModel

StaticModels returns the hardcoded catalog for a provider. Returns nil for Ollama, which has no static model list (100% dynamic).

type FoundryTransport

type FoundryTransport = providertransport.FoundryTransport

func NewFoundryTransport

func NewFoundryTransport(apiKey string, config *Config) (*FoundryTransport, error)

type LoginCommand

type LoginCommand struct {
	Provider string
	Method   string
}

LoginCommand performs provider login

func (*LoginCommand) Execute

func (c *LoginCommand) Execute(ctx context.Context) error

Execute performs login

type ModelInfo

type ModelInfo struct {
	Identifier         string
	ContextWindow      int
	MaxOutput          int
	DefaultTemperature float64
	SupportsPC         bool
	Pricing            string
	Description        string
	Capabilities       model.Capabilities
}

ModelInfo describes a single model offered by a provider. Capabilities contains fine-grained per-model feature flags. The Pricing field is a legacy string; structured pricing lives in model.Metadata.

func GetModelInfo

func GetModelInfo(provider types.APIProvider, model string) (ModelInfo, bool)

type ProviderInfo

type ProviderInfo struct {
	Name         string
	DisplayName  string
	Description  string
	AuthType     string
	AuthTypes    []string
	SupportsCVMM bool
	SupportsPC   bool
	Models       []ModelInfo
}

func GetProviderInfo

func GetProviderInfo(provider types.APIProvider) (ProviderInfo, bool)

type RequestFunc

type RequestFunc = providerretry.RequestFunc

type RetryClassification

type RetryClassification = providerretry.RetryClassification

func ClassifyHTTPError

func ClassifyHTTPError(err error, statusCode int) RetryClassification

type RetryState

type RetryState = providerretry.RetryState

func NewRetryState

func NewRetryState() *RetryState

type RetryStrategy

type RetryStrategy = providerretry.RetryStrategy

func DefaultRetryStrategy

func DefaultRetryStrategy() *RetryStrategy

type RoutingConfig

type RoutingConfig struct {
	// Priority determines which provider to try first (lower = higher priority).
	Priority int `json:"priority"`

	// FallbackModels defines a chain of models to try if the primary fails.
	FallbackModels []types.ModelIdentifier `json:"fallback_models,omitempty"`

	// FallbackProviders defines a chain of providers to try if all models fail.
	FallbackProviders []types.APIProvider `json:"fallback_providers,omitempty"`

	// CircuitBreaker tracks provider health.
	CircuitBreaker *CircuitBreakerConfig `json:"circuit_breaker,omitempty"`
}

RoutingConfig defines provider routing and fallback behavior.

type Transport

type Transport = providertransport.Transport

func NewTransport

func NewTransport(apiKey string, config *Config) (Transport, error)

type VertexTransport

type VertexTransport = providertransport.VertexTransport

func NewVertexTransport

func NewVertexTransport(apiKey string, config *Config) (*VertexTransport, error)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL