client

package
v0.2.10 Latest Latest
Warning

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

 Go to latest Published: Dec 21, 2025 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

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

The Client wraps provider-specific implementations and provides:

  • Model-centric routing: Models know their provider; switching is automatic
  • Multi-provider support: Configure all providers at once, use any model
  • Automatic retries: Built-in exponential backoff for transient errors
  • Event emission: Observable operations via channel

Basic Usage

Create a client with API keys and default models: 

c := client.New(client.Config{
    APIKeys: client.APIKeys{
        Anthropic: os.Getenv("ANTHROPIC_API_KEY"),
        OpenAI:    os.Getenv("OPENAI_API_KEY"),
    },
    Defaults: client.Defaults{
        Chat: model.ClaudeSonnet45,
    },
})

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

Model-Centric Routing

Models determine their provider. The client routes automatically: 

// Uses default model (routes to Anthropic)
resp, _ := c.Chat(ctx, messages)

// Override with GPT-5.2 (routes to OpenAI)
resp, _ := c.Chat(ctx, messages, ai.WithModel(model.GPT52))

// Override with Gemini (routes to Google)
resp, _ := c.Chat(ctx, messages, ai.WithModel(model.Gemini25Flash))

Feature Detection

Check provider capabilities before use: 

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

Provider Capabilities

Feature support by provider: 

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

Retry Configuration

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

c := client.New(client.Config{
    APIKeys: client.APIKeys{OpenAI: os.Getenv("OPENAI_API_KEY")},
    RetryConfig: &retry.Config{
        MaxAttempts:  5,
        InitialDelay: 500 * time.Millisecond,
        MaxDelay:     30 * time.Second,
    },
})

Events

Observe operations via an event channel: 

events := make(chan client.Event, 100)
c := client.New(client.Config{
    APIKeys: client.APIKeys{OpenAI: os.Getenv("OPENAI_API_KEY")},
    Events:  events,
})

go func() {
    for e := range events {
        fmt.Printf("[%s] %s took %v\n", e.Type, e.Operation, e.Duration)
    }
}()

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 ChatTyped added in v0.2.4 

func ChatTyped[T any](ctx context.Context, c *Client, msgs []ai.Message, opts ...ai.Option) (T, error)

ChatTyped sends a chat request and unmarshals the response into type T. The response schema is automatically generated from the struct type.

This is a convenience function that combines WithResponseSchema and json.Unmarshal into a single call: 

// Instead of:
resp, err := c.Chat(ctx, msgs, ai.WithResponseSchema(ai.ResponseSchema{
    Name: "book_info", Schema: ai.MustSchemaFor[BookInfo](),
}))
var book BookInfo
json.Unmarshal([]byte(resp.Content), &book)

// You can use:
book, err := client.ChatTyped[BookInfo](ctx, c, msgs)

The schema name is derived from the type name using snake_case conversion. All provided options are passed through to the underlying Chat call.

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 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, opts ...ClientOption) *Client

New creates a unified client with the given configuration. Provider clients are lazily initialized when first needed based on the model used. Optional ClientOption arguments configure default behaviors like temperature.

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 event.Event, error)

ChatStream sends a conversation and returns a channel of unified 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.

Events emitted: MessageStart, MessageDelta*, MessageEnd (or RunError on failure).

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 ClientOption added in v0.2.3 

type ClientOption func(*Client)

ClientOption configures a Client.

func WithDefaultChatOptions added in v0.2.3 

func WithDefaultChatOptions(opts ...ai.Option) ClientOption

WithDefaultChatOptions sets default options for all chat requests. Per-request options override these defaults.

func WithDefaultMaxTokens added in v0.2.3 

func WithDefaultMaxTokens(n int) ClientOption

WithDefaultMaxTokens sets the default max tokens for chat requests. Per-request options override this default.

func WithDefaultTemperature added in v0.2.3 

func WithDefaultTemperature(t float64) ClientOption

WithDefaultTemperature sets the default temperature for chat requests. Per-request options override this default.

type Config 

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

	// 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 Credentials added in v0.2.9 

type Credentials struct {
	Anthropic string       // API key
	OpenAI    string       // API key
	Google    string       // API key
	Vertex    VertexConfig // Project + Location (uses ADC)
}

Credentials holds authentication credentials for different providers. Only configure credentials for providers you intend to use.

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.

type VertexConfig added in v0.2.9 

type VertexConfig struct {
	Project  string // GCP project ID
	Location string // e.g., "us-central1"
}

VertexConfig holds configuration for Vertex AI. Uses Application Default Credentials (ADC) for authentication.

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.