Documentation
¶
Overview ¶
Package client provides a clean wrapper around the Claude SDK client.
Package client provides resilience wrappers for API calls.
Index ¶
- Variables
- type CharBasedCounter
- type CircuitBreakerConfig
- type Client
- type ClientOption
- type CompactionMessage
- type Compactor
- type CompactorConfig
- type Message
- type MockCall
- type MockClient
- type Provider
- type ProviderConfig
- type ProviderFactory
- type Querier
- type RateLimitError
- type RateLimiterConfig
- type ResilienceConfig
- type ResilienceWrapper
- type RetryConfig
- type ServerError
- type SimpleCompactor
- type SlidingWindowCompactor
- type StreamingQuerier
- type SyntheticClient
- func (c SyntheticClient) CallCount() int
- func (c SyntheticClient) Calls() []MockCall
- func (c SyntheticClient) Close() error
- func (c SyntheticClient) LastCall() MockCall
- func (c SyntheticClient) Query(ctx context.Context, prompt string) (string, error)
- func (c SyntheticClient) QueryStream(ctx context.Context, prompt string) (<-chan Message, <-chan error)
- func (c SyntheticClient) Reset()
- func (c SyntheticClient) SetError(err error)
- func (c SyntheticClient) SetResponse(response string)
- func (c SyntheticClient) SetResponseFunc(fn func(prompt string) string)
- func (c SyntheticClient) SetResponseQueue(responses ...string)
- type TokenCounter
- type WordBasedCounter
- type ZAIClient
- func (c ZAIClient) CallCount() int
- func (c ZAIClient) Calls() []MockCall
- func (c ZAIClient) Close() error
- func (c ZAIClient) LastCall() MockCall
- func (c ZAIClient) Query(ctx context.Context, prompt string) (string, error)
- func (c ZAIClient) QueryStream(ctx context.Context, prompt string) (<-chan Message, <-chan error)
- func (c ZAIClient) Reset()
- func (c ZAIClient) SetError(err error)
- func (c ZAIClient) SetResponse(response string)
- func (c ZAIClient) SetResponseFunc(fn func(prompt string) string)
- func (c ZAIClient) SetResponseQueue(responses ...string)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotConnected indicates the client is not connected. ErrNotConnected = errors.New("client not connected") // ErrInvalidProvider indicates an unsupported provider was specified. ErrInvalidProvider = errors.New("invalid provider") )
var ( // ErrCircuitOpen indicates the circuit breaker is open. ErrCircuitOpen = errors.New("circuit breaker is open") // ErrRateLimited indicates rate limiting is active. ErrRateLimited = errors.New("rate limited") // ErrMaxRetriesExceeded indicates all retry attempts failed. ErrMaxRetriesExceeded = errors.New("max retries exceeded") )
Resilience errors.
Functions ¶
This section is empty.
Types ¶
type CharBasedCounter ¶
type CharBasedCounter struct{}
CharBasedCounter estimates tokens as chars/4.
func (*CharBasedCounter) Count ¶
func (c *CharBasedCounter) Count(text string) int
type CircuitBreakerConfig ¶
type CircuitBreakerConfig struct {
// Name identifies the circuit breaker.
Name string
// MaxRequests is the maximum number of requests allowed in half-open state.
MaxRequests uint32
// Interval is the cyclic period for clearing counts in closed state.
Interval time.Duration
// Timeout is the duration in open state before transitioning to half-open.
Timeout time.Duration
// ConsecutiveFailures is the number of consecutive failures to trip the breaker.
ConsecutiveFailures uint32
// OnStateChange is called when the circuit breaker state changes.
OnStateChange func(name string, from, to gobreaker.State)
}
CircuitBreakerConfig configures the circuit breaker.
func DefaultCircuitBreakerConfig ¶
func DefaultCircuitBreakerConfig() *CircuitBreakerConfig
DefaultCircuitBreakerConfig returns sensible defaults.
type Client ¶
type Client = StreamingQuerier
Client provides backward compatibility as an alias for StreamingQuerier. Deprecated: Use Querier or StreamingQuerier directly for narrower contracts.
func New ¶
func New(ctx context.Context, sdkOpts []claude.ClientOption, clientOpts ...ClientOption) (Client, error)
New creates a new Client with the given SDK options.
type ClientOption ¶
type ClientOption func(*clientOptions)
ClientOption configures a Client.
func WithCircuitBreaker ¶
func WithCircuitBreaker(cfg *CircuitBreakerConfig) ClientOption
WithCircuitBreaker enables circuit breaker protection. Opens after consecutive failures, half-opens after timeout.
func WithRateLimiter ¶
func WithRateLimiter(cfg *RateLimiterConfig) ClientOption
WithRateLimiter enables adaptive rate limiting with 429 detection.
func WithResilience ¶
func WithResilience() ClientOption
WithResilience enables all resilience features with default configs.
func WithRetry ¶
func WithRetry(cfg *RetryConfig) ClientOption
WithRetry enables retry with exponential backoff for transient failures.
type CompactionMessage ¶
CompactionMessage represents a conversation message for compaction.
type Compactor ¶
type Compactor interface {
// ShouldCompact returns true if compaction is needed.
ShouldCompact(messages []CompactionMessage, maxTokens int) bool
// Compact summarizes messages to reduce token count.
Compact(ctx context.Context, messages []CompactionMessage) ([]CompactionMessage, error)
// EstimateTokens estimates token count for a message.
EstimateTokens(content string) int
}
Compactor handles context compaction when approaching token limits.
type CompactorConfig ¶
type CompactorConfig struct {
// Threshold is the percentage of max tokens that triggers compaction (0.0-1.0).
Threshold float64
// KeepRecent is the number of recent messages to preserve uncompacted.
KeepRecent int
// SummaryPrompt is the prompt used for summarization.
SummaryPrompt string
// MaxSummaryTokens limits the summary size.
MaxSummaryTokens int
}
CompactorConfig configures compaction behavior.
func DefaultCompactorConfig ¶
func DefaultCompactorConfig() *CompactorConfig
DefaultCompactorConfig returns sensible defaults.
type MockClient ¶ added in v0.3.0
type MockClient interface {
Client
// SetResponse sets a fixed response for all queries.
SetResponse(response string)
// SetResponseQueue sets a queue of responses consumed in order.
SetResponseQueue(responses ...string)
// SetResponseFunc sets a function that generates responses based on prompt.
SetResponseFunc(fn func(prompt string) string)
// SetError configures the client to return an error on queries.
SetError(err error)
// Calls returns all recorded calls for test assertions.
Calls() []MockCall
// CallCount returns the total number of calls made.
CallCount() int
// LastCall returns the most recent call.
LastCall() MockCall
// Reset clears all recorded calls and resets to default response.
Reset()
}
MockClient is the interface for test clients that don't make real API calls.
type Provider ¶
type Provider string
Provider represents an AI provider.
const ( // ProviderAnthropic uses the Anthropic Claude API via agent-sdk-go. ProviderAnthropic Provider = "anthropic" // ProviderZAI uses synthetic responses for Z.AI API compatibility testing. ProviderZAI Provider = "zai" // ProviderSynthetic uses synthetic responses for testing. ProviderSynthetic Provider = "synthetic" )
type ProviderConfig ¶
ProviderConfig contains provider-specific configuration.
type ProviderFactory ¶
type ProviderFactory struct {
// contains filtered or unexported fields
}
ProviderFactory creates clients for different providers.
func NewProviderFactory ¶
func NewProviderFactory() *ProviderFactory
NewProviderFactory creates a new provider factory with default providers.
func (*ProviderFactory) Create ¶
func (f *ProviderFactory) Create(ctx context.Context, cfg ProviderConfig, opts ...claude.ClientOption) (Client, error)
Create creates a client for the specified provider.
func (*ProviderFactory) Register ¶
func (f *ProviderFactory) Register(provider Provider, fn func(ctx context.Context, cfg ProviderConfig, opts ...claude.ClientOption) (Client, error))
Register registers a provider factory function.
type Querier ¶ added in v0.3.0
type Querier interface {
// Query sends a prompt and returns the complete response.
Query(ctx context.Context, prompt string) (string, error)
// Close releases resources associated with the client.
Close() error
}
Querier is the minimal interface for querying an LLM.
type RateLimitError ¶
RateLimitError represents a 429 response.
func (*RateLimitError) Error ¶
func (e *RateLimitError) Error() string
type RateLimiterConfig ¶
type RateLimiterConfig struct {
// InitialBackoff is the initial backoff after a 429.
InitialBackoff time.Duration
// MaxBackoff is the maximum backoff duration.
MaxBackoff time.Duration
// BackoffMultiplier increases backoff on consecutive 429s.
BackoffMultiplier float64
}
RateLimiterConfig configures rate limiting with 429 detection.
func DefaultRateLimiterConfig ¶
func DefaultRateLimiterConfig() *RateLimiterConfig
DefaultRateLimiterConfig returns sensible defaults.
type ResilienceConfig ¶
type ResilienceConfig struct {
// Circuit breaker settings
CircuitBreaker *CircuitBreakerConfig
// Retry settings
Retry *RetryConfig
// Rate limiter settings
RateLimiter *RateLimiterConfig
}
ResilienceConfig configures resilience behavior.
type ResilienceWrapper ¶
type ResilienceWrapper struct {
// contains filtered or unexported fields
}
ResilienceWrapper wraps API calls with resilience patterns.
func NewResilienceWrapper ¶
func NewResilienceWrapper(config *ResilienceConfig) *ResilienceWrapper
NewResilienceWrapper creates a new resilience wrapper.
func (*ResilienceWrapper) Counts ¶
func (w *ResilienceWrapper) Counts() gobreaker.Counts
Counts returns the current circuit breaker counts.
func (*ResilienceWrapper) Execute ¶
func (w *ResilienceWrapper) Execute(ctx context.Context, operation func() (string, error)) (string, error)
Execute runs the operation with all configured resilience patterns.
func (*ResilienceWrapper) State ¶
func (w *ResilienceWrapper) State() gobreaker.State
State returns the current circuit breaker state.
type RetryConfig ¶
type RetryConfig struct {
// MaxRetries is the maximum number of retry attempts.
MaxRetries uint64
// InitialInterval is the initial backoff interval.
InitialInterval time.Duration
// MaxInterval is the maximum backoff interval.
MaxInterval time.Duration
// Multiplier is the factor by which the interval increases.
Multiplier float64
// RandomizationFactor adds jitter to prevent thundering herd.
RandomizationFactor float64
}
RetryConfig configures retry behavior.
func DefaultRetryConfig ¶
func DefaultRetryConfig() *RetryConfig
DefaultRetryConfig returns sensible defaults.
type ServerError ¶
ServerError represents a 5xx response.
func (*ServerError) Error ¶
func (e *ServerError) Error() string
type SimpleCompactor ¶
type SimpleCompactor struct {
// contains filtered or unexported fields
}
SimpleCompactor provides basic compaction using token estimation.
func NewSimpleCompactor ¶
func NewSimpleCompactor(config *CompactorConfig, summarizer func(ctx context.Context, prompt string) (string, error)) *SimpleCompactor
NewSimpleCompactor creates a new compactor.
func (*SimpleCompactor) Compact ¶
func (c *SimpleCompactor) Compact(ctx context.Context, messages []CompactionMessage) ([]CompactionMessage, error)
Compact summarizes older messages while keeping recent ones.
func (*SimpleCompactor) EstimateTokens ¶
func (c *SimpleCompactor) EstimateTokens(content string) int
EstimateTokens provides a rough token estimate (4 chars per token).
func (*SimpleCompactor) ShouldCompact ¶
func (c *SimpleCompactor) ShouldCompact(messages []CompactionMessage, maxTokens int) bool
ShouldCompact checks if compaction is needed.
type SlidingWindowCompactor ¶
type SlidingWindowCompactor struct {
// contains filtered or unexported fields
}
SlidingWindowCompactor uses a sliding window approach (no LLM needed).
func NewSlidingWindowCompactor ¶
func NewSlidingWindowCompactor(windowSize int) *SlidingWindowCompactor
NewSlidingWindowCompactor creates a simple sliding window compactor.
func (*SlidingWindowCompactor) Compact ¶
func (c *SlidingWindowCompactor) Compact(_ context.Context, messages []CompactionMessage) ([]CompactionMessage, error)
Compact keeps only the most recent messages within window.
func (*SlidingWindowCompactor) EstimateTokens ¶
func (c *SlidingWindowCompactor) EstimateTokens(content string) int
EstimateTokens provides a rough estimate.
func (*SlidingWindowCompactor) ShouldCompact ¶
func (c *SlidingWindowCompactor) ShouldCompact(messages []CompactionMessage, _ int) bool
ShouldCompact checks if messages exceed window size.
type StreamingQuerier ¶ added in v0.3.0
type StreamingQuerier interface {
Querier
// QueryStream sends a prompt and streams the response.
QueryStream(ctx context.Context, prompt string) (<-chan Message, <-chan error)
}
StreamingQuerier extends Querier with streaming support.
type SyntheticClient ¶ added in v0.3.0
type SyntheticClient struct {
// contains filtered or unexported fields
}
SyntheticClient is a mock client for testing that doesn't make real API calls. It returns configurable responses and tracks all calls for assertions.
func NewSyntheticClient ¶ added in v0.3.0
func NewSyntheticClient() *SyntheticClient
NewSyntheticClient creates a new synthetic client with a default response.
func (SyntheticClient) QueryStream ¶ added in v0.3.0
func (SyntheticClient) SetResponse ¶ added in v0.3.0
func (c SyntheticClient) SetResponse(response string)
func (SyntheticClient) SetResponseFunc ¶ added in v0.3.0
func (SyntheticClient) SetResponseQueue ¶ added in v0.3.0
func (c SyntheticClient) SetResponseQueue(responses ...string)
type TokenCounter ¶
TokenCounter provides accurate token counting.
type WordBasedCounter ¶
type WordBasedCounter struct{}
WordBasedCounter estimates tokens as words * 1.3.
func (*WordBasedCounter) Count ¶
func (c *WordBasedCounter) Count(text string) int
type ZAIClient ¶ added in v0.3.0
type ZAIClient struct {
// contains filtered or unexported fields
}
ZAIClient is a mock client for Z.AI API compatibility testing. It returns configurable responses and tracks all calls for assertions.
func NewZAIClient ¶ added in v0.3.0
func NewZAIClient() *ZAIClient
NewZAIClient creates a new Z.AI mock client with a default response.
func (ZAIClient) QueryStream ¶ added in v0.3.0
func (ZAIClient) SetResponse ¶ added in v0.3.0
func (c ZAIClient) SetResponse(response string)
func (ZAIClient) SetResponseFunc ¶ added in v0.3.0
func (ZAIClient) SetResponseQueue ¶ added in v0.3.0
func (c ZAIClient) SetResponseQueue(responses ...string)