client

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Dec 16, 2025 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package client provides a unified multi-provider client for AI capabilities.

The Client wraps provider-specific implementations and provides:

  • Provider abstraction: Switch between Anthropic, OpenAI, and Google with config changes
  • Feature detection: Check provider capabilities before making requests
  • Automatic retries: Built-in exponential backoff for transient errors
  • Unified defaults: Configure default models for chat, embeddings, and images

Basic Usage

Create a client with a specific provider: 

client, err := client.New(ctx, client.Config{
    Provider: client.ProviderOpenAI,
    APIKey:   os.Getenv("OPENAI_API_KEY"),
})
if err != nil {
    log.Fatal(err)
}

resp, err := client.Chat(ctx, []gains.Message{
    {Role: gains.RoleUser, Content: "Hello!"},
})

Provider Configuration

Configure default models for different capabilities: 

import "github.com/spetersoncode/gains/model"

client, err := client.New(ctx, client.Config{
    Provider:       client.ProviderOpenAI,
    APIKey:         os.Getenv("OPENAI_API_KEY"),
    ChatModel:      model.GPT52,
    ImageModel:     model.GPTImage1,
    EmbeddingModel: model.TextEmbedding3Small,
})

Feature Checking

Verify provider capabilities before use: 

if client.SupportsFeature(client.FeatureImage) {
    resp, err := client.GenerateImage(ctx, "A sunset over mountains")
}

Require features at construction time: 

client, err := client.New(ctx, client.Config{
    Provider:         client.ProviderAnthropic,
    APIKey:           apiKey,
    RequiredFeatures: []client.Feature{client.FeatureChat, client.FeatureEmbedding},
})
// Returns ErrFeatureNotSupported since Anthropic doesn't support embeddings

Retry Configuration

The client automatically retries transient errors (rate limits, timeouts, 5xx errors). Customize retry behavior: 

client, err := client.New(ctx, client.Config{
    Provider:    client.ProviderOpenAI,
    APIKey:      apiKey,
    RetryConfig: &client.RetryConfig{
        MaxAttempts:  5,
        InitialDelay: 500 * time.Millisecond,
        MaxDelay:     30 * time.Second,
    },
})

Disable retries entirely: 

cfg := client.DisabledRetryConfig()
client, err := client.New(ctx, client.Config{
    Provider:    client.ProviderOpenAI,
    APIKey:      apiKey,
    RetryConfig: &cfg,
})

Provider Capabilities

Feature support by provider: 

| Provider  | Chat | Embeddings | Images |
|-----------|------|------------|--------|
| Anthropic | Yes  | No         | No     |
| OpenAI    | Yes  | Yes        | Yes    |
| Google    | Yes  | Yes        | Yes    |

Switching Providers

The unified interface makes it easy to switch providers: 

providerName := os.Getenv("AI_PROVIDER")

var provider client.ProviderName
switch providerName {
case "anthropic":
    provider = client.ProviderAnthropic
case "google":
    provider = client.ProviderGoogle
default:
    provider = client.ProviderOpenAI
}

c, err := client.New(ctx, client.Config{
    Provider: provider,
    APIKey:   os.Getenv("API_KEY"),
})

Index

Constants

View Source 
const (
	RetryEventAttemptStart  = retry.EventAttemptStart
	RetryEventAttemptFailed = retry.EventAttemptFailed
	RetryEventRetrying      = retry.EventRetrying
	RetryEventSuccess       = retry.EventSuccess
	RetryEventExhausted     = retry.EventExhausted
)

Retry event type constants.

Variables

This section is empty.

Functions

func IsTransientError 

func IsTransientError(err error) bool

IsTransientError determines if an error is transient and should be retried. It checks for rate limits, server errors, network timeouts, and connection issues.

Types

type APIKeys 

type APIKeys struct {
	Anthropic string
	OpenAI    string
	Google    string
}

APIKeys holds API keys for different providers. Only configure keys for providers you intend to use.

type Client 

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

Client is a unified interface to all AI provider capabilities. Provider clients are lazily initialized when first needed.

func New 

func New(cfg Config) *Client

New creates a unified client with the given configuration. Provider clients are lazily initialized when first needed based on the model used.

func (*Client) Chat 

func (c *Client) Chat(ctx context.Context, messages []ai.Message, opts ...ai.Option) (*ai.Response, error)

Chat sends a conversation and returns a complete response. The model can be specified via WithModel option, or the default chat model is used. Automatically retries on transient errors according to the client's retry configuration.

func (*Client) ChatStream 

func (c *Client) ChatStream(ctx context.Context, messages []ai.Message, opts ...ai.Option) (<-chan ai.StreamEvent, error)

ChatStream sends a conversation and returns a channel of streaming events. The model can be specified via WithModel option, or the default chat model is used. Automatically retries on transient errors when establishing the stream connection.

func (*Client) Embed 

func (c *Client) Embed(ctx context.Context, texts []string, opts ...ai.EmbeddingOption) (*ai.EmbeddingResponse, error)

Embed generates embeddings for the provided texts. The model can be specified via WithEmbeddingModel option, or the default embedding model is used. Returns ErrFeatureNotSupported if the provider doesn't support embeddings. Automatically retries on transient errors according to the client's retry configuration.

func (*Client) GenerateImage 

func (c *Client) GenerateImage(ctx context.Context, prompt string, opts ...ai.ImageOption) (*ai.ImageResponse, error)

GenerateImage creates images from a text prompt. The model can be specified via WithImageModel option, or the default image model is used. Returns ErrFeatureNotSupported if the provider doesn't support image generation. Automatically retries on transient errors according to the client's retry configuration.

func (*Client) SupportsFeature 

func (c *Client) SupportsFeature(f Feature) bool

SupportsFeature returns true if the given feature is supported by any configured provider.

type Config 

type Config struct {
	// APIKeys contains authentication keys for each provider.
	// Only configure keys for providers you intend to use.
	APIKeys APIKeys

	// Defaults contains default models for each capability.
	// The model's provider determines which backend is used.
	Defaults Defaults

	// RetryConfig configures retry behavior for transient errors.
	// If nil, uses default retry configuration (10 retries with exponential backoff).
	RetryConfig *retry.Config

	// Events is an optional channel for receiving client operation events.
	// Events are sent non-blocking; if the channel is full, events are dropped.
	Events chan<- Event
}

Config holds configuration for creating a unified client.

type Defaults 

type Defaults struct {
	Chat      ai.Model
	Embedding ai.Model
	Image     ai.Model
}

Defaults holds default models for each capability. The model's provider determines which backend is used.

type ErrFeatureNotSupported 

type ErrFeatureNotSupported struct {
	Provider string
	Feature  string
}

ErrFeatureNotSupported is returned when a feature is unavailable for the provider.

func (*ErrFeatureNotSupported) Error 

func (e *ErrFeatureNotSupported) Error() string

type ErrMissingAPIKey 

type ErrMissingAPIKey struct {
	Provider string
	Model    string
}

ErrMissingAPIKey is returned when a model is used but no API key is configured for that model's provider.

func (*ErrMissingAPIKey) Error 

func (e *ErrMissingAPIKey) Error() string

type ErrNoModel 

type ErrNoModel struct {
	Operation string
}

ErrNoModel is returned when no model is specified and no default is configured.

func (*ErrNoModel) Error 

func (e *ErrNoModel) Error() string

type Event 

type Event struct {
	// Type identifies the kind of event.
	Type EventType

	// Operation identifies the API operation ("chat", "chat_stream", "embed", "image").
	Operation string

	// Provider identifies which AI provider is being used.
	Provider ai.Provider

	// Model is the model name being used (if known).
	Model string

	// Duration is the elapsed time for completed requests.
	Duration time.Duration

	// Usage contains token usage information (for chat operations).
	Usage *ai.Usage

	// Error contains the error for EventRequestError.
	Error error

	// RetryEvent contains the underlying retry event for EventRetry.
	RetryEvent *RetryEvent

	// Timestamp is when the event occurred.
	Timestamp time.Time
}

Event represents an observable occurrence during client operations.

type EventType 

type EventType string

EventType identifies the kind of event occurring during client operations. 

const (
	// EventRequestStart fires before an API request begins.
	EventRequestStart EventType = "request_start"

	// EventRequestComplete fires after an API request completes successfully.
	EventRequestComplete EventType = "request_complete"

	// EventRequestError fires when an API request fails.
	EventRequestError EventType = "request_error"

	// EventRetry fires when a retry event occurs (forwarded from retry package).
	EventRetry EventType = "retry"
)

type Feature 

type Feature string

Feature represents a capability that a provider may support. 

const (
	FeatureChat      Feature = "chat"
	FeatureImage     Feature = "image"
	FeatureEmbedding Feature = "embedding"
)

type RetryConfig 

type RetryConfig = retry.Config

RetryConfig holds retry configuration parameters.

func DefaultRetryConfig 

func DefaultRetryConfig() RetryConfig

DefaultRetryConfig returns the default retry configuration.

  • 10 max attempts
  • 1 second initial delay
  • 60 second max delay
  • 2x exponential multiplier
  • 10% jitter

func DisabledRetryConfig 

func DisabledRetryConfig() RetryConfig

DisabledRetryConfig returns a configuration that disables retries (single attempt).

type RetryEvent 

type RetryEvent = retry.Event

RetryEvent represents an observable occurrence during retry execution.

type RetryEventType 

type RetryEventType = retry.EventType

RetryEventType identifies the kind of event occurring during retry execution.

Source Files

View all Source files

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.