common

package
v1.0.63 Latest Latest
Warning

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

 Go to latest Published: Dec 24, 2025 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

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 for AI provider implementations

Package common provides shared utilities 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 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 ResolveModel 

func ResolveModel(optionsModel, configDefaultModel, providerDefaultModel string) string

ResolveModel returns the model to use, with fallback priority: 1. Model specified in options 2. Default model from provider config 3. Provider's hardcoded default model

Types

type ConnectivityCache 

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

ConnectivityCache provides thread-safe caching of connectivity test results It prevents hammering provider APIs during rapid health checks by caching results for a configurable TTL

func NewConnectivityCache 

func NewConnectivityCache(config ConnectivityCacheConfig) *ConnectivityCache

NewConnectivityCache creates a new connectivity cache with the given configuration

func NewDefaultConnectivityCache 

func NewDefaultConnectivityCache() *ConnectivityCache

NewDefaultConnectivityCache creates a new connectivity cache with default configuration

func (*ConnectivityCache) CleanupExpired 

func (cc *ConnectivityCache) CleanupExpired() int

CleanupExpired removes all expired entries from the cache This is useful for periodic cleanup to prevent memory growth

func (*ConnectivityCache) Clear 

func (cc *ConnectivityCache) Clear(providerType types.ProviderType)

Clear removes a specific provider's cached result This is useful when you want to force a fresh check on the next call without using bypassCache

func (*ConnectivityCache) ClearAll 

func (cc *ConnectivityCache) ClearAll()

ClearAll removes all cached results This is useful for resetting the cache state

func (*ConnectivityCache) GetCachedResult 

func (cc *ConnectivityCache) GetCachedResult(providerType types.ProviderType) (time.Time, bool, error)

GetCachedResult returns the cached result for a provider without performing a test Returns the timestamp of the cache entry, whether a valid (non-expired) entry exists, and the cached error

func (*ConnectivityCache) GetConfig 

func (cc *ConnectivityCache) GetConfig() ConnectivityCacheConfig

GetConfig returns the current cache configuration

func (*ConnectivityCache) GetStats 

func (cc *ConnectivityCache) GetStats() ConnectivityCacheStats

GetStats returns statistics about the cache

func (*ConnectivityCache) SetConfig 

func (cc *ConnectivityCache) SetConfig(config ConnectivityCacheConfig)

SetConfig updates the cache configuration Note: Changing the TTL doesn't invalidate existing cache entries

func (*ConnectivityCache) TestConnectivity 

func (cc *ConnectivityCache) TestConnectivity(
	ctx context.Context,
	providerType types.ProviderType,
	testFunc func(context.Context) error,
	bypassCache bool,
) error

TestConnectivity performs a cached connectivity test If a valid cached result exists (not expired), it returns the cached result Otherwise, it calls the actual test function and caches the result

Parameters:

  • ctx: Context for the connectivity test
  • providerType: The type of provider being tested
  • testFunc: The actual connectivity test function to call if cache miss or bypass
  • bypassCache: If true, forces a fresh connectivity check and updates the cache

Returns an error if the connectivity test fails, or nil if successful

type ConnectivityCacheConfig 

type ConnectivityCacheConfig struct {
	// TTL is the time-to-live for cached connectivity results
	// After this duration, the cache entry will be considered stale and a fresh check will be performed
	TTL time.Duration

	// Enabled controls whether caching is enabled
	// When disabled, all TestConnectivity calls will perform actual connectivity checks
	Enabled bool
}

ConnectivityCacheConfig holds configuration for the connectivity cache

func DefaultConnectivityCacheConfig 

func DefaultConnectivityCacheConfig() ConnectivityCacheConfig

DefaultConnectivityCacheConfig returns the default cache configuration Default TTL is 30 seconds to prevent hammering provider APIs during rapid health checks

type ConnectivityCacheStats 

type ConnectivityCacheStats struct {
	// TotalEntries is the current number of cached entries
	TotalEntries int

	// ValidEntries is the number of non-expired cached entries
	ValidEntries int

	// ExpiredEntries is the number of expired cached entries
	ExpiredEntries int

	// SuccessfulChecks is the number of cached successful connectivity checks
	SuccessfulChecks int

	// FailedChecks is the number of cached failed connectivity checks
	FailedChecks int
}

ConnectivityCacheStats represents statistics about the connectivity cache

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

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

ModelUsage represents model usage statistics

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 ProviderInitializerOptions 

type ProviderInitializerOptions struct {
	// SkipAPIKeySetup skips the API key setup step (for providers that handle this differently)
	SkipAPIKeySetup bool
	// SkipOAuthSetup skips the OAuth setup step (for providers that don't support OAuth)
	SkipOAuthSetup bool
	// CustomTimeout allows overriding the timeout from config
	CustomTimeout time.Duration
}

ProviderInitializerOptions provides optional configuration for provider initialization

type ProviderInitializerResult 

type ProviderInitializerResult struct {
	MergedConfig types.ProviderConfig
	HTTPClient   *http.Client
	PooledClient *pkghttp.HTTPClient
	AuthHelper   *auth.AuthHelper
	ConfigHelper *commonconfig.ConfigHelper
}

ProviderInitializerResult contains the results of provider initialization

func InitializeProvider 

func InitializeProvider(
	providerName string,
	providerType types.ProviderType,
	config types.ProviderConfig,
	options ProviderInitializerOptions,
) (*ProviderInitializerResult, error)

InitializeProvider provides a shared initialization pattern for all providers It extracts the common logic found in New*Provider() functions across 10+ providers

Example usage: 

result, err := common.InitializeProvider("Anthropic", types.ProviderTypeAnthropic, config, common.ProviderInitializerOptions{})
if err != nil {
    return nil, err
}
// Use result.MergedConfig, result.HTTPClient, result.AuthHelper, etc.

func InitializeProviderWithConfig 

func InitializeProviderWithConfig(
	providerName string,
	providerType types.ProviderType,
	config types.ProviderConfig,
	providerSpecificConfig interface{},
	options ProviderInitializerOptions,
) (*ProviderInitializerResult, error)

InitializeProviderWithConfig extracts provider-specific configuration and applies overrides This is a convenience function that combines InitializeProvider with config extraction

Example usage: 

result, err := common.InitializeProviderWithConfig("Anthropic", types.ProviderTypeAnthropic, config, &anthropicConfig{}, common.ProviderInitializerOptions{})
if err != nil {
    return nil, err
}
// Use result.MergedConfig, result.HTTPClient, result.AuthHelper, and result.ProviderConfig (typed as your config struct)

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 RateLimitInfo 

type RateLimitInfo struct {
	RequestsLimit     int
	RequestsRemaining int
	RequestsReset     int64 // Unix timestamp
	TokensLimit       int
	TokensRemaining   int
	TokensReset       int64 // Unix timestamp
	RetryAfter        int   // Seconds to wait
}

RateLimitInfo holds parsed rate limit information in a simplified format. This provides easy access to the most commonly used rate limit fields without requiring knowledge of the underlying ratelimit.Info structure.

type RateLimitTracker 

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

RateLimitTracker wraps RateLimitHelper with automatic response tracking. It provides a cleaner API that reduces code duplication by combining rate limit parsing and tracking into a single method call.

func NewRateLimitTracker 

func NewRateLimitTracker(parser ratelimit.Parser) *RateLimitTracker

NewRateLimitTracker creates a new tracker with the given parser.

func (*RateLimitTracker) GetHelper 

func (t *RateLimitTracker) GetHelper() *RateLimitHelper

GetHelper returns the underlying helper for backwards compatibility. This allows access to advanced features like CheckRateLimitAndWait, ShouldThrottle, and provider-specific rate limit information.

func (*RateLimitTracker) GetLastInfo 

func (t *RateLimitTracker) GetLastInfo() *RateLimitInfo

GetLastInfo returns the most recent rate limit info. This can be used to check rate limits without making another API call.

func (*RateLimitTracker) GetRetryAfter 

func (t *RateLimitTracker) GetRetryAfter() int

GetRetryAfter returns seconds to wait, or 0 if not rate limited.

func (*RateLimitTracker) IsRateLimited 

func (t *RateLimitTracker) IsRateLimited() bool

IsRateLimited returns true if we should back off based on the last check. This provides a simple way to check if rate limits have been exceeded.

func (*RateLimitTracker) TrackResponse 

func (t *RateLimitTracker) TrackResponse(headers http.Header, model string) *RateLimitInfo

TrackResponse extracts and stores rate limit info from response headers. This is the single point where rate limits are parsed, replacing multiple ParseAndUpdateRateLimits() calls throughout the codebase.

Usage: 

info := p.rateLimitTracker.TrackResponse(resp.Header, modelName)
if info != nil && info.RetryAfter > 0 {
    // Handle rate limit
}

Source Files

View all Source files

Directories

Path Synopsis
Package auth provides authentication utilities and helper functions for AI provider implementations
 Package auth provides authentication utilities and helper functions for AI provider implementations
Package config provides configuration utilities for AI provider implementations
 Package config provides configuration utilities for AI provider implementations
Package connectivity provides shared connectivity testing utilities for AI providers.
 Package connectivity provides shared connectivity testing utilities for AI providers.
Package errors provides rich error context for AI provider operations.
 Package errors provides rich error context for AI provider operations.
Package http provides common HTTP utilities for provider implementations.
 Package http provides common HTTP utilities for provider implementations.
Package middleware provides a flexible middleware infrastructure for AI provider requests and responses.
 Package middleware provides a flexible middleware infrastructure for AI provider requests and responses.
Package models provides model metadata, caching, and registry functionality for AI providers, including capability tracking and discovery.
 Package models provides model metadata, caching, and registry functionality for AI providers, including capability tracking and discovery.
Package retry provides retry infrastructure for AI provider implementations.
 Package retry provides retry infrastructure for AI provider implementations.
Package streaming provides a shared streaming request executor for AI providers.
 Package streaming provides a shared streaming request executor for AI providers.
decoders
Package decoders provides pluggable stream decoders for various streaming formats including Server-Sent Events (SSE), NDJSON, and EventStream.
 Package decoders provides pluggable stream decoders for various streaming formats including Server-Sent Events (SSE), NDJSON, and EventStream.
Package telemetry provides telemetry utilities for AI provider tracking and monitoring.
 Package telemetry provides telemetry utilities for AI provider tracking and monitoring.
Package tools provides Anthropic-specific tool conversion utilities.
 Package tools provides Anthropic-specific tool conversion utilities.

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.