common

package
v1.0.7 Latest Latest
Warning

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

 Go to latest Published: Nov 29, 2025 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package common provides shared utilities and infrastructure for AI provider implementations. This includes standardized error handling, authentication helpers, configuration management, health checking, metrics collection, and other common functionality across providers.

Package common provides shared utilities and helper functions for AI providers. It includes file operations, configuration helpers, and other common functionality used across different provider implementations.

Package common provides shared utilities and helper functions for AI provider implementations

Package common provides shared utilities for AI provider implementations.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreateAnthropicStream 

func CreateAnthropicStream(response *http.Response) types.ChatCompletionStream

CreateAnthropicStream creates a stream for Anthropic responses

func CreateCustomStream 

func CreateCustomStream(response *http.Response, parser StreamParser) types.ChatCompletionStream

CreateCustomStream creates a stream with a custom parser

func CreateErrorStream 

func CreateErrorStream(err error) types.ChatCompletionStream

CreateErrorStream creates a stream that immediately returns an error

func CreateOpenAIStream 

func CreateOpenAIStream(response *http.Response) types.ChatCompletionStream

CreateOpenAIStream creates a stream for OpenAI-compatible responses

func JSONLineProcessor 

func JSONLineProcessor(data string, target interface{}, chunkExtractor func(interface{}) types.ChatCompletionChunk) (types.ChatCompletionChunk, error, bool)

JSONLineProcessor provides standard JSON line processing with error handling

func ReadConfigFile 

func ReadConfigFile(configPath string) ([]byte, error)

ReadConfigFile reads a configuration file and returns its raw byte content. This is commonly used by providers to read YAML/JSON configuration files. Returns the raw file content as bytes and any error encountered.

func SSELineProcessor 

func SSELineProcessor(data string, responseParser func(string) (types.ChatCompletionChunk, bool)) (types.ChatCompletionChunk, error, bool)

SSELineProcessor provides standard SSE (Server-Sent Events) line processing

func StreamFromContext 

func StreamFromContext(ctx context.Context, baseStream types.ChatCompletionStream) types.ChatCompletionStream

StreamFromContext creates a stream from context with cancellation support

Types

type APIError added in v1.0.4 

type APIError struct {
	StatusCode int
	Type       APIErrorType
	Message    string
	RawBody    string
	Retryable  bool
}

APIError represents a standardized provider error

func ClassifyHTTPError added in v1.0.4 

func ClassifyHTTPError(statusCode int, body []byte) *APIError

ClassifyHTTPError creates an APIError from HTTP status code This provides a basic classification based on standard HTTP status codes

func (*APIError) Error added in v1.0.4 

func (e *APIError) Error() string

Error implements the error interface

func (*APIError) IsRateLimit added in v1.0.4 

func (e *APIError) IsRateLimit() bool

IsRateLimit checks if the error is a rate limit error

func (*APIError) IsRetryable added in v1.0.4 

func (e *APIError) IsRetryable() bool

IsRetryable checks if the error is retryable

type APIErrorType added in v1.0.4 

type APIErrorType string

APIErrorType classifies API errors 

const (
	APIErrorTypeRateLimit      APIErrorType = "rate_limit"
	APIErrorTypeAuth           APIErrorType = "auth"
	APIErrorTypeNotFound       APIErrorType = "not_found"
	APIErrorTypeInvalidRequest APIErrorType = "invalid_request"
	APIErrorTypeServer         APIErrorType = "server_error"
	APIErrorTypeUnknown        APIErrorType = "unknown"
)

type AnthropicStreamParser 

type AnthropicStreamParser struct{}

AnthropicStreamParser provides a parser for Anthropic's streaming format

func NewAnthropicStreamParser 

func NewAnthropicStreamParser() *AnthropicStreamParser

NewAnthropicStreamParser creates a new Anthropic stream parser

func (*AnthropicStreamParser) ParseLine 

func (p *AnthropicStreamParser) ParseLine(data string) (types.ChatCompletionChunk, bool, error)

ParseLine parses a line from an Anthropic stream

type AuthHelper 

type AuthHelper struct {
	ProviderName string
	KeyManager   *keymanager.KeyManager
	OAuthManager *oauthmanager.OAuthKeyManager
	HTTPClient   *http.Client
	Config       types.ProviderConfig
}

AuthHelper provides shared authentication functionality for providers

func NewAuthHelper 

func NewAuthHelper(providerName string, config types.ProviderConfig, client *http.Client) *AuthHelper

NewAuthHelper creates a new authentication helper

func (*AuthHelper) ClearAuthentication 

func (h *AuthHelper) ClearAuthentication()

ClearAuthentication clears all authentication credentials

func (*AuthHelper) ExecuteWithAuth 

func (h *AuthHelper) ExecuteWithAuth(
	ctx context.Context,
	options types.GenerateOptions,
	oauthOperation func(context.Context, *types.OAuthCredentialSet) (string, *types.Usage, error),
	apiKeyOperation func(context.Context, string) (string, *types.Usage, error),
) (string, *types.Usage, error)

ExecuteWithAuth executes an operation using available authentication methods Automatically chooses OAuth over API key, with failover support

func (*AuthHelper) GetAuthMethod 

func (h *AuthHelper) GetAuthMethod() string

GetAuthMethod returns the currently available authentication method

func (*AuthHelper) GetAuthStatus 

func (h *AuthHelper) GetAuthStatus() map[string]interface{}

GetAuthStatus returns a detailed authentication status

func (*AuthHelper) HandleAuthError 

func (h *AuthHelper) HandleAuthError(err error, statusCode int) error

HandleAuthError handles authentication-specific errors and provides user-friendly messages

func (*AuthHelper) IsAuthenticated 

func (h *AuthHelper) IsAuthenticated() bool

IsAuthenticated checks if any authentication method is configured

func (*AuthHelper) MakeAuthenticatedRequest 

func (h *AuthHelper) MakeAuthenticatedRequest(
	ctx context.Context,
	method, url string,
	headers map[string]string,
	body interface{},
) (*http.Response, error)

MakeAuthenticatedRequest makes an HTTP request with proper authentication

func (*AuthHelper) RefreshAllOAuthTokens 

func (h *AuthHelper) RefreshAllOAuthTokens(ctx context.Context) error

RefreshAllOAuthTokens attempts to refresh all OAuth tokens

func (*AuthHelper) SetAuthHeaders 

func (h *AuthHelper) SetAuthHeaders(req *http.Request, authToken string, authType string)

SetAuthHeaders sets appropriate authentication headers on HTTP requests

func (*AuthHelper) SetProviderSpecificHeaders 

func (h *AuthHelper) SetProviderSpecificHeaders(req *http.Request)

SetProviderSpecificHeaders sets provider-specific headers beyond auth

func (*AuthHelper) SetupAPIKeys 

func (h *AuthHelper) SetupAPIKeys()

SetupAPIKeys configures API key management with support for multiple keys Extracts keys from both config.APIKey and config.ProviderConfig["api_keys"]

func (*AuthHelper) SetupOAuth 

func (h *AuthHelper) SetupOAuth(refreshFunc oauthmanager.RefreshFunc)

SetupOAuth configures OAuth management with multiple credential support

func (*AuthHelper) ValidateAuthConfig 

func (h *AuthHelper) ValidateAuthConfig(authConfig types.AuthConfig) error

ValidateAuthConfig validates authentication configuration

type BaseStream 

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

BaseStream provides a base implementation of ChatCompletionStream

func NewBaseStream 

func NewBaseStream(processor *StreamProcessor, parser StreamParser) *BaseStream

NewBaseStream creates a new base stream

func (*BaseStream) Close 

func (bs *BaseStream) Close() error

Close closes the stream

func (*BaseStream) Next 

func (bs *BaseStream) Next() (types.ChatCompletionChunk, error)

Next returns the next chunk from the stream

type CacheInfo 

type CacheInfo struct {
	ProviderCount  int                  `json:"provider_count"`
	TotalModels    int                  `json:"total_models"`
	ProviderModels map[string]int       `json:"provider_models"`
	CacheTimes     map[string]time.Time `json:"cache_times"`
	OldestCache    time.Time            `json:"oldest_cache"`
	NewestCache    time.Time            `json:"newest_cache"`
}

CacheInfo contains information about the model cache

type ConfigHelper 

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

ConfigHelper provides standardized configuration validation, extraction, and defaults for all AI providers, eliminating duplicate configuration code.

func NewConfigHelper 

func NewConfigHelper(providerName string, providerType types.ProviderType) *ConfigHelper

NewConfigHelper creates a new configuration helper for a specific provider

func (*ConfigHelper) ApplyTopLevelOverrides 

func (h *ConfigHelper) ApplyTopLevelOverrides(config types.ProviderConfig, providerConfig interface{}) error

ApplyTopLevelOverrides applies top-level config fields to provider-specific config

func (*ConfigHelper) ConfigSummary 

func (h *ConfigHelper) ConfigSummary(config types.ProviderConfig) map[string]interface{}

ConfigSummary provides a human-readable summary of the configuration

func (*ConfigHelper) ExtractAPIKeys 

func (h *ConfigHelper) ExtractAPIKeys(config types.ProviderConfig) []string

ExtractAPIKeys extracts and consolidates API keys from various sources

func (*ConfigHelper) ExtractBaseURL 

func (h *ConfigHelper) ExtractBaseURL(config types.ProviderConfig) string

ExtractBaseURL extracts base URL with provider-specific defaults

func (*ConfigHelper) ExtractDefaultModel 

func (h *ConfigHelper) ExtractDefaultModel(config types.ProviderConfig) string

ExtractDefaultModel extracts default model from config Note: Does not provide fallback defaults - each provider handles its own defaults via GetDefaultModel()

func (*ConfigHelper) ExtractDefaultOAuthClientID 

func (h *ConfigHelper) ExtractDefaultOAuthClientID() string

ExtractDefaultOAuthClientID returns provider-specific default OAuth client IDs

func (*ConfigHelper) ExtractMaxTokens 

func (h *ConfigHelper) ExtractMaxTokens(config types.ProviderConfig) int

ExtractMaxTokens extracts max tokens with provider-specific defaults

func (*ConfigHelper) ExtractProviderSpecificConfig 

func (h *ConfigHelper) ExtractProviderSpecificConfig(config types.ProviderConfig, target interface{}) error

ExtractProviderSpecificConfig extracts provider-specific configuration into a struct

func (*ConfigHelper) ExtractStringField 

func (h *ConfigHelper) ExtractStringField(config types.ProviderConfig, fieldName, fallback string) string

ExtractStringField extracts a string field from provider config with fallback

func (*ConfigHelper) ExtractStringSliceField 

func (h *ConfigHelper) ExtractStringSliceField(config types.ProviderConfig, fieldName string) []string

ExtractStringSliceField extracts a string slice field from provider config

func (*ConfigHelper) ExtractTimeout 

func (h *ConfigHelper) ExtractTimeout(config types.ProviderConfig) time.Duration

ExtractTimeout extracts timeout with sensible defaults

func (*ConfigHelper) GetProviderCapabilities 

func (h *ConfigHelper) GetProviderCapabilities() (supportsToolCalling, supportsStreaming, supportsResponsesAPI bool)

GetProviderCapabilities returns the capabilities flags for the provider

func (*ConfigHelper) MergeWithDefaults 

func (h *ConfigHelper) MergeWithDefaults(config types.ProviderConfig) types.ProviderConfig

MergeWithDefaults merges the provided config with provider defaults

func (*ConfigHelper) SanitizeConfigForLogging 

func (h *ConfigHelper) SanitizeConfigForLogging(config types.ProviderConfig) types.ProviderConfig

SanitizeConfigForLogging returns a configuration copy with sensitive data removed

func (*ConfigHelper) ValidateProviderConfig 

func (h *ConfigHelper) ValidateProviderConfig(config types.ProviderConfig) ValidationResult

ValidateProviderConfig performs comprehensive configuration validation

type ContextAwareStream 

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

ContextAwareStream wraps a stream with context awareness

func (*ContextAwareStream) Close 

func (cas *ContextAwareStream) Close() error

Close closes the underlying stream

func (*ContextAwareStream) Next 

func (cas *ContextAwareStream) Next() (types.ChatCompletionChunk, error)

Next returns the next chunk, respecting context cancellation

type ErrorClassifier added in v1.0.4 

type ErrorClassifier interface {
	Classify(statusCode int, body []byte) *APIError
}

ErrorClassifier interface for provider-specific error parsing Providers can implement this to provide more detailed error classification based on their specific API error response formats

type ErrorStream 

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

ErrorStream is a stream that always returns an error

func (*ErrorStream) Close 

func (es *ErrorStream) Close() error

func (*ErrorStream) Next 

func (es *ErrorStream) Next() (types.ChatCompletionChunk, error)

type ErrorSummary 

type ErrorSummary struct {
	TotalErrors int64       `json:"total_errors"`
	ErrorTypes  []ErrorType `json:"error_types"`
}

ErrorSummary represents a summary of errors

type ErrorType 

type ErrorType struct {
	Type       string  `json:"type"`
	Count      int64   `json:"count"`
	Percentage float64 `json:"percentage"`
}

ErrorType represents an error type with count and percentage

type GenericSSEStream added in v1.0.4 

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

GenericSSEStream wraps SSE parsing for any provider that implements SSELineParser. It handles the low-level SSE protocol details (reading lines, handling "data:" prefix) while delegating provider-specific parsing to the SSELineParser implementation.

func NewGenericSSEStream added in v1.0.4 

func NewGenericSSEStream(resp *http.Response, parser SSELineParser) *GenericSSEStream

NewGenericSSEStream creates a new generic SSE stream with the given response and parser. The parser parameter defines how individual SSE lines are parsed into ChatCompletionChunk objects.

func (*GenericSSEStream) Close added in v1.0.4 

func (s *GenericSSEStream) Close() error

Close closes the underlying HTTP response body and cleans up resources.

func (*GenericSSEStream) Next added in v1.0.4 

func (s *GenericSSEStream) Next() (types.ChatCompletionChunk, error)

Next returns the next chunk from the SSE stream. It reads lines from the stream, extracts SSE data, and uses the parser to convert them to chunks. Returns io.EOF when the stream is complete or an error if parsing fails.

type HealthCheckCallback 

type HealthCheckCallback func(provider types.ProviderType, health *ProviderHealth)

HealthCheckCallback is called when a health check completes

type HealthCheckResult 

type HealthCheckResult struct {
	Healthy      bool                   `json:"healthy"`
	ResponseTime time.Duration          `json:"response_time"`
	Error        string                 `json:"error,omitempty"`
	Details      map[string]interface{} `json:"details,omitempty"`
}

HealthCheckResult represents the result of a single health check

type HealthChecker 

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

HealthChecker performs health checks on providers

func NewHealthChecker 

func NewHealthChecker(interval time.Duration) *HealthChecker

NewHealthChecker creates a new health checker

func (*HealthChecker) AddCallback 

func (hc *HealthChecker) AddCallback(callback HealthCheckCallback)

AddCallback adds a callback to be called when health checks complete

func (*HealthChecker) CheckProvider 

func (hc *HealthChecker) CheckProvider(ctx context.Context, provider *InitializedProvider) error

CheckProvider performs a health check on a specific provider

func (*HealthChecker) GetAllHealthStatus 

func (hc *HealthChecker) GetAllHealthStatus() map[types.ProviderType]ProviderHealth

GetAllHealthStatus returns health status for all providers

func (*HealthChecker) GetHealthStatus 

func (hc *HealthChecker) GetHealthStatus(providerType types.ProviderType) ProviderHealth

GetHealthStatus returns the current health status for a provider

func (*HealthChecker) GetHealthSummary 

func (hc *HealthChecker) GetHealthSummary() HealthSummary

GetHealthSummary returns a summary of health status across all providers

func (*HealthChecker) GetHealthyProviders 

func (hc *HealthChecker) GetHealthyProviders() []types.ProviderType

GetHealthyProviders returns a list of currently healthy providers

func (*HealthChecker) GetUnhealthyProviders 

func (hc *HealthChecker) GetUnhealthyProviders() []types.ProviderType

GetUnhealthyProviders returns a list of currently unhealthy providers

func (*HealthChecker) IsHealthy 

func (hc *HealthChecker) IsHealthy(providerType types.ProviderType) bool

IsHealthy checks if a provider is currently healthy

func (*HealthChecker) ResetHealthStatus 

func (hc *HealthChecker) ResetHealthStatus(providerType types.ProviderType)

ResetHealthStatus resets the health status for a provider

func (*HealthChecker) Start 

func (hc *HealthChecker) Start()

Start starts the health checker

func (*HealthChecker) Stop 

func (hc *HealthChecker) Stop()

Stop stops the health checker

type HealthSummary 

type HealthSummary struct {
	TotalProviders     int64                            `json:"total_providers"`
	HealthyProviders   int64                            `json:"healthy_providers"`
	UnhealthyProviders int64                            `json:"unhealthy_providers"`
	LastCheckTimes     map[types.ProviderType]time.Time `json:"last_check_times"`
}

HealthSummary represents a summary of health status across providers

type InitializedProvider 

type InitializedProvider struct {
	Type            types.ProviderType   `json:"type"`
	Config          types.ProviderConfig `json:"config"`
	HTTPClient      *http.HTTPClient     `json:"-"`
	AvailableModels []types.Model        `json:"available_models,omitempty"`
	Metrics         *ProviderMetrics     `json:"-"`
	HealthCheck     *HealthChecker       `json:"-"`
	InitializedAt   time.Time            `json:"initialized_at"`
	Status          ProviderStatus       `json:"status"`
}

InitializedProvider represents a fully initialized provider

type InitializerConfig 

type InitializerConfig struct {
	DefaultTimeout      time.Duration `json:"default_timeout"`
	MaxRetries          int           `json:"max_retries"`
	EnableHealthCheck   bool          `json:"enable_health_check"`
	HealthCheckInterval time.Duration `json:"health_check_interval"`
	EnableMetrics       bool          `json:"enable_metrics"`
	AutoDetectModels    bool          `json:"auto_detect_models"`
	CacheModels         bool          `json:"cache_models"`
	ModelCacheTTL       time.Duration `json:"model_cache_ttl"`
}

InitializerConfig configures provider initialization

type MetricsSnapshot 

type MetricsSnapshot struct {
	TotalRequests    int64                `json:"total_requests"`
	SuccessRequests  int64                `json:"success_requests"`
	FailedRequests   int64                `json:"failed_requests"`
	SuccessRate      float64              `json:"success_rate"`
	AvgResponseTime  time.Duration        `json:"avg_response_time"`
	MinResponseTime  time.Duration        `json:"min_response_time"`
	MaxResponseTime  time.Duration        `json:"max_response_time"`
	TotalTokensUsed  int64                `json:"total_tokens_used"`
	ErrorsByType     map[string]int64     `json:"errors_by_type"`
	ErrorsByProvider map[string]int64     `json:"errors_by_provider"`
	Initializations  map[string]int64     `json:"initializations"`
	HealthChecks     map[string]int64     `json:"health_checks"`
	HealthCheckFails map[string]int64     `json:"health_check_fails"`
	ModelUsage       map[string]int64     `json:"model_usage"`
	RateLimitHits    map[string]int64     `json:"rate_limit_hits"`
	LastRequestTime  map[string]time.Time `json:"last_request_time"`
	Uptime           time.Duration        `json:"uptime"`
}

MetricsSnapshot represents a snapshot of metrics at a point in time

type MockStream 

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

MockStream provides a mock implementation of ChatCompletionStream for testing

func NewMockStream 

func NewMockStream(chunks []types.ChatCompletionChunk) *MockStream

NewMockStream creates a new mock stream with the given chunks

func (*MockStream) Close 

func (ms *MockStream) Close() error

Close resets the mock stream

func (*MockStream) Next 

func (ms *MockStream) Next() (types.ChatCompletionChunk, error)

Next returns the next chunk from the mock stream

type ModelCache 

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

ModelCache stores cached model list with timestamp and thread-safe access

func NewModelCache 

func NewModelCache(ttl time.Duration) *ModelCache

NewModelCache creates a new model cache with the specified TTL

func (*ModelCache) Clear 

func (mc *ModelCache) Clear()

Clear empties the cache and resets the timestamp

func (*ModelCache) Get 

func (mc *ModelCache) Get() []types.Model

Get returns cached models (thread-safe)

func (*ModelCache) GetModels 

func (mc *ModelCache) GetModels(fetchFunc func() ([]types.Model, error), fallbackFunc func() []types.Model) ([]types.Model, error)

GetModels returns cached models if available and fresh, or calls the fetch function This is a convenience method that implements the common cache-check-fetch-update pattern

func (*ModelCache) GetTTL 

func (mc *ModelCache) GetTTL() time.Duration

GetTTL returns the cache's time-to-live duration

func (*ModelCache) GetTimestamp 

func (mc *ModelCache) GetTimestamp() time.Time

GetTimestamp returns when the cache was last updated

func (*ModelCache) IsStale 

func (mc *ModelCache) IsStale() bool

IsStale checks if the cache is expired

func (*ModelCache) SetTTL 

func (mc *ModelCache) SetTTL(ttl time.Duration)

SetTTL updates the cache's time-to-live duration

func (*ModelCache) Update 

func (mc *ModelCache) Update(models []types.Model)

Update updates the cache with new models (thread-safe)

type ModelCapability 

type ModelCapability struct {
	MaxTokens         int                  `json:"max_tokens"`
	SupportsStreaming bool                 `json:"supports_streaming"`
	SupportsTools     bool                 `json:"supports_tools"`
	SupportsVision    bool                 `json:"supports_vision"`
	Providers         []types.ProviderType `json:"providers"`
	InputPrice        float64              `json:"input_price_per_1k"`  // Price per 1K input tokens
	OutputPrice       float64              `json:"output_price_per_1k"` // Price per 1K output tokens
	Categories        []string             `json:"categories"`          // e.g., "text", "code", "multimodal"
}

ModelCapability represents provider model capabilities

type ModelRegistry 

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

ModelRegistry manages model information and caching

func NewModelRegistry 

func NewModelRegistry(ttl time.Duration) *ModelRegistry

NewModelRegistry creates a new model registry

func (*ModelRegistry) CacheModels 

func (mr *ModelRegistry) CacheModels(providerType types.ProviderType, models []types.Model)

CacheModels caches models for a provider

func (*ModelRegistry) ClearCache 

func (mr *ModelRegistry) ClearCache(providerType *types.ProviderType)

ClearCache clears the cache for a specific provider or all providers

func (*ModelRegistry) GetCacheInfo 

func (mr *ModelRegistry) GetCacheInfo() CacheInfo

GetCacheInfo returns information about the cache

func (*ModelRegistry) GetCachedModels 

func (mr *ModelRegistry) GetCachedModels(providerType types.ProviderType) []types.Model

GetCachedModels returns cached models for a provider if not expired

func (*ModelRegistry) GetModelCapability 

func (mr *ModelRegistry) GetModelCapability(modelID string) *ModelCapability

GetModelCapability returns the capabilities for a model

func (*ModelRegistry) GetModelsByProvider 

func (mr *ModelRegistry) GetModelsByProvider(providerType types.ProviderType) []types.Model

GetModelsByProvider returns all models for a specific provider

func (*ModelRegistry) GetProviderCount 

func (mr *ModelRegistry) GetProviderCount() int

GetProviderCount returns the number of providers with cached models

func (*ModelRegistry) GetTotalModelCount 

func (mr *ModelRegistry) GetTotalModelCount() int

GetTotalModelCount returns the total number of cached models

func (*ModelRegistry) RegisterModel 

func (mr *ModelRegistry) RegisterModel(modelID string, capability *ModelCapability)

RegisterModel registers a model with its capabilities

func (*ModelRegistry) SearchModels 

func (mr *ModelRegistry) SearchModels(criteria SearchCriteria) []types.Model

SearchModels searches for models matching criteria

type ModelUsage 

type ModelUsage struct {
	ModelID string `json:"model_id"`
	Count   int64  `json:"count"`
}

ModelUsage represents model usage statistics

type OAuthRefreshHelper 

type OAuthRefreshHelper struct {
	ProviderName string
	HTTPClient   *http.Client
}

OAuthRefreshHelper provides common OAuth token refresh implementations

func NewOAuthRefreshHelper 

func NewOAuthRefreshHelper(providerName string, client *http.Client) *OAuthRefreshHelper

NewOAuthRefreshHelper creates a new OAuth refresh helper

func (*OAuthRefreshHelper) AnthropicOAuthRefresh 

func (h *OAuthRefreshHelper) AnthropicOAuthRefresh(ctx context.Context, cred *types.OAuthCredentialSet) (*types.OAuthCredentialSet, error)

AnthropicOAuthRefresh implements Anthropic's OAuth 2.0 token refresh

func (*OAuthRefreshHelper) GeminiOAuthRefresh 

func (h *OAuthRefreshHelper) GeminiOAuthRefresh(ctx context.Context, cred *types.OAuthCredentialSet) (*types.OAuthCredentialSet, error)

GeminiOAuthRefresh implements Google's OAuth 2.0 token refresh using the oauth2 library

func (*OAuthRefreshHelper) GenericOAuthRefresh 

func (h *OAuthRefreshHelper) GenericOAuthRefresh(ctx context.Context, cred *types.OAuthCredentialSet, tokenURL string) (*types.OAuthCredentialSet, error)

GenericOAuthRefresh provides a generic OAuth 2.0 token refresh implementation

func (*OAuthRefreshHelper) OpenAIOAuthRefresh 

func (h *OAuthRefreshHelper) OpenAIOAuthRefresh(ctx context.Context, cred *types.OAuthCredentialSet) (*types.OAuthCredentialSet, error)

OpenAIOAuthRefresh implements OpenAI's OAuth 2.0 token refresh

func (*OAuthRefreshHelper) QwenOAuthRefresh 

func (h *OAuthRefreshHelper) QwenOAuthRefresh(ctx context.Context, cred *types.OAuthCredentialSet) (*types.OAuthCredentialSet, error)

QwenOAuthRefresh implements Qwen's OAuth 2.0 token refresh

type OpenAICompatibleParser added in v1.0.4 

type OpenAICompatibleParser struct {
	// SkipEmptyContent determines whether to skip chunks with empty content
	SkipEmptyContent bool
}

OpenAICompatibleParser handles OpenAI-style SSE responses. This parser works with the standard OpenAI streaming format and can be used by any provider that follows OpenAI's streaming API conventions.

func NewOpenAICompatibleParser added in v1.0.4 

func NewOpenAICompatibleParser() *OpenAICompatibleParser

NewOpenAICompatibleParser creates a new OpenAI-compatible SSE parser with default settings.

func (*OpenAICompatibleParser) IsDone added in v1.0.4 

func (p *OpenAICompatibleParser) IsDone(line string) bool

IsDone checks if the given line indicates stream completion. OpenAI sends "[DONE]" as the final message in the stream.

func (*OpenAICompatibleParser) ParseLine added in v1.0.4 

func (p *OpenAICompatibleParser) ParseLine(line string) (types.ChatCompletionChunk, error)

ParseLine parses a single SSE data line in OpenAI format into a ChatCompletionChunk. The OpenAI format is JSON with the structure: 

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "created": 1234567890,
  "model": "gpt-4",
  "choices": [{
    "index": 0,
    "delta": {
      "role": "assistant",
      "content": "Hello"
    },
    "finish_reason": null
  }]
}

type ProcessLineFunc 

type ProcessLineFunc func(line string) (types.ChatCompletionChunk, error, bool)

ProcessLineFunc processes a single line from a streaming response

type ProviderHealth 

type ProviderHealth struct {
	Provider     types.ProviderType     `json:"provider"`
	Healthy      bool                   `json:"healthy"`
	LastCheck    time.Time              `json:"last_check"`
	LastSuccess  time.Time              `json:"last_success"`
	LastError    time.Time              `json:"last_error"`
	ErrorMessage string                 `json:"error_message,omitempty"`
	ResponseTime time.Duration          `json:"response_time"`
	CheckCount   int64                  `json:"check_count"`
	SuccessCount int64                  `json:"success_count"`
	FailureCount int64                  `json:"failure_count"`
	Details      map[string]interface{} `json:"details,omitempty"`
}

ProviderHealth represents the health status of a provider

type ProviderInitializer 

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

ProviderInitializer handles common provider initialization patterns

func NewProviderInitializer 

func NewProviderInitializer(config InitializerConfig) *ProviderInitializer

NewProviderInitializer creates a new provider initializer

func (*ProviderInitializer) InitializeProvider 

func (pi *ProviderInitializer) InitializeProvider(
	ctx context.Context,
	providerType types.ProviderType,
	config types.ProviderConfig,
) (*InitializedProvider, error)

InitializeProvider initializes a provider with common patterns

type ProviderMetrics 

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

ProviderMetrics tracks performance and usage metrics for providers

func NewProviderMetrics 

func NewProviderMetrics() *ProviderMetrics

NewProviderMetrics creates a new provider metrics instance

func (*ProviderMetrics) GetErrorSummary 

func (pm *ProviderMetrics) GetErrorSummary() ErrorSummary

GetErrorSummary returns a summary of errors by type

func (*ProviderMetrics) GetMetricsForProvider 

func (pm *ProviderMetrics) GetMetricsForProvider(providerType types.ProviderType) ProviderMetricsSnapshot

GetMetricsForProvider returns metrics specific to a provider

func (*ProviderMetrics) GetSnapshot 

func (pm *ProviderMetrics) GetSnapshot() MetricsSnapshot

GetSnapshot returns a snapshot of current metrics

func (*ProviderMetrics) GetTopModels 

func (pm *ProviderMetrics) GetTopModels(limit int) []ModelUsage

GetTopModels returns the most used models

func (*ProviderMetrics) RecordError 

func (pm *ProviderMetrics) RecordError(providerType types.ProviderType, errorType string)

RecordError records a failed request

func (*ProviderMetrics) RecordHealthCheck 

func (pm *ProviderMetrics) RecordHealthCheck(providerType types.ProviderType, success bool)

RecordHealthCheck records a health check attempt

func (*ProviderMetrics) RecordInitialization 

func (pm *ProviderMetrics) RecordInitialization(providerType types.ProviderType)

RecordInitialization records a provider initialization

func (*ProviderMetrics) RecordRateLimitHit 

func (pm *ProviderMetrics) RecordRateLimitHit(providerType types.ProviderType)

RecordRateLimitHit records a rate limit occurrence

func (*ProviderMetrics) RecordRequest 

func (pm *ProviderMetrics) RecordRequest(providerType types.ProviderType)

RecordRequest records a request attempt

func (*ProviderMetrics) RecordSuccess 

func (pm *ProviderMetrics) RecordSuccess(providerType types.ProviderType, responseTime time.Duration, tokens int64, modelID string)

RecordSuccess records a successful request

func (*ProviderMetrics) Reset 

func (pm *ProviderMetrics) Reset()

Reset resets all metrics

type ProviderMetricsSnapshot 

type ProviderMetricsSnapshot struct {
	Provider         string    `json:"provider"`
	Errors           int64     `json:"errors"`
	HealthChecks     int64     `json:"health_checks"`
	HealthCheckFails int64     `json:"health_check_fails"`
	RateLimitHits    int64     `json:"rate_limit_hits"`
	Initializations  int64     `json:"initializations"`
	LastRequestTime  time.Time `json:"last_request_time"`
}

ProviderMetricsSnapshot represents metrics for a specific provider

type ProviderStatus 

type ProviderStatus struct {
	Healthy      bool          `json:"healthy"`
	LastCheck    time.Time     `json:"last_check"`
	ErrorCount   int64         `json:"error_count"`
	RequestCount int64         `json:"request_count"`
	ResponseTime time.Duration `json:"avg_response_time"`
}

ProviderStatus represents the current status of a provider

type RateLimitHelper 

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

RateLimitHelper provides shared rate limiting functionality for all AI providers. It encapsulates the common patterns of rate limit tracking, parsing, and enforcement used across different provider implementations.

func NewRateLimitHelper 

func NewRateLimitHelper(parser ratelimit.Parser) *RateLimitHelper

NewRateLimitHelper creates a new RateLimitHelper with the given provider-specific parser.

func (*RateLimitHelper) CanMakeRequest 

func (h *RateLimitHelper) CanMakeRequest(model string, estimatedTokens int) bool

CanMakeRequest checks if a request can be made for the given model and estimated tokens. Returns true if the request should proceed, false if rate limited.

func (*RateLimitHelper) CheckRateLimitAndWait 

func (h *RateLimitHelper) CheckRateLimitAndWait(model string, estimatedTokens int) bool

CheckRateLimitAndWait checks rate limits and waits if necessary before making a request. This combines the common pattern of checking limits and sleeping if needed. Returns true if the caller should proceed with the request, false if rate limited.

func (*RateLimitHelper) GetParser 

func (h *RateLimitHelper) GetParser() ratelimit.Parser

GetParser returns the underlying rate limit parser for advanced operations. This should be used sparingly when the helper methods don't provide sufficient functionality.

func (*RateLimitHelper) GetRateLimitInfo 

func (h *RateLimitHelper) GetRateLimitInfo(model string) (*ratelimit.Info, bool)

GetRateLimitInfo retrieves the current rate limit information for a model. Returns the info and a boolean indicating whether data exists for the model.

func (*RateLimitHelper) GetTracker 

func (h *RateLimitHelper) GetTracker() *ratelimit.Tracker

GetTracker returns the underlying rate limit tracker for advanced operations. This should be used sparingly when the helper methods don't provide sufficient functionality.

func (*RateLimitHelper) GetWaitTime 

func (h *RateLimitHelper) GetWaitTime(model string) time.Duration

GetWaitTime returns the duration to wait before the next request can be made. Returns 0 if no waiting is required.

func (*RateLimitHelper) ParseAndUpdateRateLimits 

func (h *RateLimitHelper) ParseAndUpdateRateLimits(headers http.Header, model string)

ParseAndUpdateRateLimits parses rate limit headers from an HTTP response and updates the tracker. This is the most common operation performed after receiving API responses.

func (*RateLimitHelper) ShouldThrottle 

func (h *RateLimitHelper) ShouldThrottle(model string, threshold float64) bool

ShouldThrottle determines if requests should be throttled based on current usage. threshold is a value between 0 and 1 representing the percentage of limits consumed at which throttling should begin (e.g., 0.8 = throttle at 80% usage).

func (*RateLimitHelper) UpdateRateLimitInfo 

func (h *RateLimitHelper) UpdateRateLimitInfo(info *ratelimit.Info)

UpdateRateLimitInfo directly updates the rate limit info for a model. This is useful for providers that get rate limit info from API endpoints rather than response headers.

type RefreshFuncFactory 

type RefreshFuncFactory struct {
	Helper *OAuthRefreshHelper
}

RefreshFuncFactory creates refresh functions for different providers

func NewRefreshFuncFactory 

func NewRefreshFuncFactory(providerName string, client *http.Client) *RefreshFuncFactory

NewRefreshFuncFactory creates a new refresh function factory

func (*RefreshFuncFactory) CreateAnthropicRefreshFunc 

func (f *RefreshFuncFactory) CreateAnthropicRefreshFunc() oauthmanager.RefreshFunc

CreateAnthropicRefreshFunc creates an Anthropic refresh function

func (*RefreshFuncFactory) CreateGeminiRefreshFunc 

func (f *RefreshFuncFactory) CreateGeminiRefreshFunc() oauthmanager.RefreshFunc

CreateGeminiRefreshFunc creates a Gemini refresh function

func (*RefreshFuncFactory) CreateGenericRefreshFunc 

func (f *RefreshFuncFactory) CreateGenericRefreshFunc(tokenURL string) oauthmanager.RefreshFunc

CreateGenericRefreshFunc creates a generic refresh function for custom providers

func (*RefreshFuncFactory) CreateOpenAIRefreshFunc 

func (f *RefreshFuncFactory) CreateOpenAIRefreshFunc() oauthmanager.RefreshFunc

CreateOpenAIRefreshFunc creates an OpenAI refresh function

func (*RefreshFuncFactory) CreateQwenRefreshFunc 

func (f *RefreshFuncFactory) CreateQwenRefreshFunc() oauthmanager.RefreshFunc

CreateQwenRefreshFunc creates a Qwen refresh function

type SSELineParser added in v1.0.4 

type SSELineParser interface {
	// ParseLine parses a single SSE data line into a chunk.
	// Returns the parsed chunk and any error that occurred during parsing.
	ParseLine(line string) (types.ChatCompletionChunk, error)

	// IsDone checks if this line indicates stream completion.
	// Common completion signals include "[DONE]" or specific event types.
	IsDone(line string) bool
}

SSELineParser defines provider-specific parsing behavior for SSE streams. This interface allows different providers to implement their own parsing logic while using the common SSE stream infrastructure.

type SearchCriteria 

type SearchCriteria struct {
	Provider          *types.ProviderType `json:"provider,omitempty"`
	MinTokens         *int                `json:"min_tokens,omitempty"`
	MaxTokens         *int                `json:"max_tokens,omitempty"`
	SupportsStreaming *bool               `json:"supports_streaming,omitempty"`
	SupportsTools     *bool               `json:"supports_tools,omitempty"`
	Categories        []string            `json:"categories,omitempty"`
	NameContains      string              `json:"name_contains,omitempty"`
}

SearchCriteria defines search criteria for models

type StandardStreamParser 

type StandardStreamParser struct {
	// Custom field mappings for provider-specific responses
	ContentField          string
	ReasoningField        string // For GLM-4.6, OpenCode/Zen style
	ReasoningContentField string // For vLLM/Synthetic style
	DoneField             string
	UsageField            string
	ToolCallsField        string
	FinishReason          string
}

StandardStreamParser provides a standard parser for OpenAI-compatible streaming responses

func NewStandardStreamParser 

func NewStandardStreamParser() *StandardStreamParser

NewStandardStreamParser creates a new standard stream parser with default OpenAI mappings

func (*StandardStreamParser) ParseLine 

func (p *StandardStreamParser) ParseLine(data string) (types.ChatCompletionChunk, bool, error)

ParseLine parses a line from the stream using standard OpenAI format

type StreamParser 

type StreamParser interface {
	ParseLine(data string) (types.ChatCompletionChunk, bool, error)
}

StreamParser defines the interface for parsing streaming responses

type StreamProcessor 

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

StreamProcessor provides common streaming functionality for all providers

func NewStreamProcessor 

func NewStreamProcessor(response *http.Response) *StreamProcessor

NewStreamProcessor creates a new stream processor

func (*StreamProcessor) Close 

func (sp *StreamProcessor) Close() error

Close closes the stream and cleans up resources

func (*StreamProcessor) IsDone 

func (sp *StreamProcessor) IsDone() bool

IsDone returns whether the stream is finished

func (*StreamProcessor) MarkDone 

func (sp *StreamProcessor) MarkDone()

MarkDone marks the stream as done

func (*StreamProcessor) NextChunk 

func (sp *StreamProcessor) NextChunk(processLine ProcessLineFunc) (types.ChatCompletionChunk, error)

NextChunk reads and processes the next chunk from the stream

type ValidationResult 

type ValidationResult struct {
	Valid  bool
	Errors []string
}

ValidationResult contains the result of configuration validation

Source Files

View all Source files

Directories

Path Synopsis
Package testing provides common testing helpers and utilities for AI provider implementations including authentication, configuration, tool calling, and mock server functionality.
 Package testing provides common testing helpers and utilities for AI provider implementations including authentication, configuration, tool calling, and mock server functionality.

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.