api

package
v0.0.0-...-c5791a9 Latest Latest
Warning

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

 Go to latest Published: May 15, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsConnectionResetError 

func IsConnectionResetError(err error) bool

IsConnectionResetError reports whether the error is specifically a TCP connection reset (ECONNRESET/EPIPE), indicating a stale keep-alive socket.

func IsTransientError 

func IsTransientError(err error) bool

IsTransientError reports whether the error is safe to retry: network-level connection errors (ECONNRESET, EPIPE) or HTTP-level transient failures (429 rate-limit, 529 overloaded, 5xx server errors).

Types

type AnthropicProvider 

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

AnthropicProvider implements the Provider interface for the first-class Anthropic Messages API. Unlike external provider proxies, this is the default provider used for all claude-* models with full support for thinking, effort, prompt caching, OAuth billing, and context management.

func NewAnthropicProvider 

func NewAnthropicProvider(baseURL string, resolver *auth.Resolver) *AnthropicProvider

NewAnthropicProvider creates a new first-class Anthropic provider. baseURL defaults to "https://api.anthropic.com" if empty.

func NewAnthropicProviderWithKey 

func NewAnthropicProviderWithKey(baseURL, apiKey string) *AnthropicProvider

NewAnthropicProviderWithKey creates an AnthropicProvider for an external Anthropic-compatible proxy where auth is a static user-supplied API key (no OAuth resolver needed). Prompt caching is enabled by default.

func (*AnthropicProvider) CopyConfig 

func (a *AnthropicProvider) CopyConfig() *AnthropicProvider

CopyConfig returns a new AnthropicProvider with the same configuration but different model/thinking settings. Used for sub-agent creation.

func (*AnthropicProvider) EffortLabel 

func (a *AnthropicProvider) EffortLabel() string

EffortLabel returns a human-readable label for the current effort level.

func (*AnthropicProvider) GetBudgetTokens 

func (a *AnthropicProvider) GetBudgetTokens() int

func (*AnthropicProvider) GetEffortLevel 

func (a *AnthropicProvider) GetEffortLevel() string

func (*AnthropicProvider) GetThinkingMode 

func (a *AnthropicProvider) GetThinkingMode() string

func (*AnthropicProvider) IsPromptCachingEnabled 

func (a *AnthropicProvider) IsPromptCachingEnabled() bool

func (*AnthropicProvider) Name 

func (a *AnthropicProvider) Name() string

Name returns the provider name.

func (*AnthropicProvider) SendMessage 

func (a *AnthropicProvider) SendMessage(ctx context.Context, httpClient *http.Client, req *MessagesRequest) (*MessageResp, error)

SendMessage sends a non-streaming request to the Anthropic Messages API.

func (*AnthropicProvider) SetBaseURL 

func (a *AnthropicProvider) SetBaseURL(url string)

func (*AnthropicProvider) SetBudgetTokens 

func (a *AnthropicProvider) SetBudgetTokens(n int)

func (*AnthropicProvider) SetEffortLevel 

func (a *AnthropicProvider) SetEffortLevel(level string)

func (*AnthropicProvider) SetModel 

func (a *AnthropicProvider) SetModel(model string)

func (*AnthropicProvider) SetPromptCaching 

func (a *AnthropicProvider) SetPromptCaching(enabled bool)

func (*AnthropicProvider) SetStorage 

func (a *AnthropicProvider) SetStorage(store storage.SecureStorage)

func (*AnthropicProvider) SetThinkingMode 

func (a *AnthropicProvider) SetThinkingMode(mode string)

func (*AnthropicProvider) StreamMessages 

func (a *AnthropicProvider) StreamMessages(ctx context.Context, httpClient *http.Client, req *MessagesRequest) (<-chan StreamEvent, <-chan error)

StreamMessages sends a streaming request to the Anthropic Messages API.

func (*AnthropicProvider) ThinkingLabel 

func (a *AnthropicProvider) ThinkingLabel() string

ThinkingLabel returns a human-readable label for the current thinking configuration.

type CacheControlBlock 

type CacheControlBlock struct {
	Type string `json:"type"` // always "ephemeral"
}

CacheControlBlock instructs the API to cache content up to this point.

type Client 

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

Client communicates with the Anthropic Messages API.

func NewClient 

func NewClient(resolver *auth.Resolver, opts ...ClientOption) *Client

NewClient creates a new API client.

func NewClientFromExisting 

func NewClientFromExisting(parent *Client, model string) *Client

NewClientFromExisting creates a copy of an existing client with a different model and its own independent HTTP transport. All other settings (auth, base URL, thinking mode, etc.) are inherited from the parent.

Each sub-agent/teammate gets its own transport so they open independent TCP connections to the API. Without this, all agents share one HTTP/2 connection and the server's per-stream flow control can delay some streams arbitrarily, causing false watchdog timeouts and cascading retry storms.

func (*Client) AddModelRoute 

func (c *Client) AddModelRoute(pattern, providerName string)

AddModelRoute maps a glob pattern (e.g. "llama-*") to a provider name.

func (*Client) AddModelShortcut 

func (c *Client) AddModelShortcut(shortcut, modelID string)

AddModelShortcut registers a slash-command shortcut for a model.

func (*Client) DiscoverModels 

func (c *Client) DiscoverModels(ctx context.Context) []ModelInfo

DiscoverModels queries all providers that support model listing and returns the combined results. Providers that don't implement ModelLister are skipped.

func (*Client) EffortLabel 

func (c *Client) EffortLabel() string

EffortLabel returns a human-readable label for the current effort level.

func (*Client) GetBudgetTokens 

func (c *Client) GetBudgetTokens() int

GetBudgetTokens returns the thinking budget token limit.

func (*Client) GetEffortLevel 

func (c *Client) GetEffortLevel() string

GetEffortLevel returns the current effort level ("low", "medium", "high", or "" for default).

func (*Client) GetModel 

func (c *Client) GetModel() string

GetModel returns the current default model.

func (*Client) GetModelShortcuts 

func (c *Client) GetModelShortcuts() map[string]string

GetModelShortcuts returns all registered model shortcuts (shortcut -> model ID).

func (*Client) GetProvider 

func (c *Client) GetProvider(name string) Provider

GetProvider returns a provider by name, or nil if not found.

func (*Client) GetProviderModels 

func (c *Client) GetProviderModels() map[string]string

GetProviderModels returns all model routing entries (pattern → provider).

func (*Client) GetProviderNames 

func (c *Client) GetProviderNames() []string

GetProviderNames returns names of all registered providers.

func (*Client) GetThinkingMode 

func (c *Client) GetThinkingMode() string

GetThinkingMode returns the current thinking mode ("adaptive", "enabled", "disabled", or "" for auto).

func (*Client) HasProvider 

func (c *Client) HasProvider(name string) bool

HasProvider returns true if a provider with the given name is registered.

func (*Client) HealthCheck 

func (c *Client) HealthCheck(ctx context.Context, providerName string) HealthCheckResult

HealthCheck tests connectivity to a specific provider by sending a tiny request.

func (*Client) HealthCheckAll 

func (c *Client) HealthCheckAll(ctx context.Context) []HealthCheckResult

HealthCheckAll tests connectivity to all registered providers.

func (*Client) IsExternalModel 

func (c *Client) IsExternalModel(model string) bool

IsExternalModel returns true if the given model routes to an external (non-Anthropic) provider. This is used to gate Claude-specific system prompt sections (e.g. Auto Memory instructions) that confuse smaller local models like Gemma.

func (*Client) RegisterProvider 

func (c *Client) RegisterProvider(name string, p Provider)

RegisterProvider adds a provider that can be used for model routing.

func (*Client) RenewTransport 

func (c *Client) RenewTransport()

RenewTransport replaces the HTTP client's transport with a fresh one that has no stale keep-alive connections. Call this after an ECONNRESET error.

func (*Client) ResolveModelShortcut 

func (c *Client) ResolveModelShortcut(shortcut string) (string, bool)

ResolveModelShortcut returns the model ID for a shortcut, or empty string if not found. Checks user-configured shortcuts first, then built-in shortcuts.

func (*Client) SendMessage 

func (c *Client) SendMessage(ctx context.Context, req *MessagesRequest) (*MessageResp, error)

SendMessage sends a non-streaming messages request.

func (*Client) SetBudgetTokens 

func (c *Client) SetBudgetTokens(tokens int)

SetBudgetTokens sets the thinking budget token limit (used when mode is "enabled").

func (*Client) SetEffortLevel 

func (c *Client) SetEffortLevel(level string)

SetEffortLevel sets the reasoning effort level. Use "" for default (high).

func (*Client) SetModel 

func (c *Client) SetModel(model string)

SetModel changes the default model at runtime.

func (*Client) SetThinkingMode 

func (c *Client) SetThinkingMode(mode string)

SetThinkingMode sets the thinking mode. Use "" for auto-detect based on model.

func (*Client) StreamMessages 

func (c *Client) StreamMessages(ctx context.Context, req *MessagesRequest) (<-chan StreamEvent, <-chan error)

StreamMessages sends a streaming messages request and returns a channel of events.

func (*Client) ThinkingLabel 

func (c *Client) ThinkingLabel() string

ThinkingLabel returns a human-readable label for the current thinking configuration.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures the API client.

func WithBaseURL 

func WithBaseURL(url string) ClientOption

WithBaseURL sets a custom API base URL.

func WithModel 

func WithModel(model string) ClientOption

WithModel sets the default model.

func WithPromptCaching 

func WithPromptCaching(enabled bool) ClientOption

WithPromptCaching enables or disables prompt caching (default: true).

func WithStorage 

func WithStorage(store storage.SecureStorage) ClientOption

WithStorage provides a SecureStorage so the client can force-refresh the OAuth token and retry when the API returns HTTP 401.

type ContentBlock 

type ContentBlock struct {
	Type      string          `json:"type"` // "text", "tool_use", "tool_result", "thinking"
	Text      string          `json:"text,omitempty"`
	Thinking  string          `json:"thinking,omitempty"`
	Signature string          `json:"signature,omitempty"` // Required when sending thinking blocks back
	ID        string          `json:"id,omitempty"`
	ToolUseID string          `json:"tool_use_id,omitempty"` // Used in tool_result blocks
	Content   string          `json:"content,omitempty"`     // Used in tool_result blocks
	Name      string          `json:"name,omitempty"`
	Input     json.RawMessage `json:"input,omitempty"`
}

ContentBlock represents a content block in the response.

type ContextEdit 

type ContextEdit struct {
	Type            string      `json:"type"` // e.g. "clear_tool_uses_20250919"
	Trigger         *Trigger    `json:"trigger,omitempty"`
	Keep            *KeepConfig `json:"keep,omitempty"`              // which tool uses to protect
	ExcludeTools    []string    `json:"exclude_tools,omitempty"`     // tool names to never clear
	ClearToolInputs bool        `json:"clear_tool_inputs,omitempty"` // also clear tool_use input params
}

ContextEdit is a single context editing strategy.

type ContextManagement 

type ContextManagement struct {
	Edits []ContextEdit `json:"edits"`
}

ContextManagement configures server-side context editing strategies. See: https://platform.claude.com/docs/en/build-with-claude/context-editing

type HealthCheckResult 

type HealthCheckResult struct {
	ProviderName string
	OK           bool
	Latency      time.Duration
	Error        string
	Model        string // model used for the test
}

HealthCheckResult holds the result of a provider connectivity test.

type ImageSource 

type ImageSource struct {
	Type      string `json:"type"`       // "base64"
	MediaType string `json:"media_type"` // "image/png", "image/jpeg", "image/gif", "image/webp"
	Data      string `json:"data"`       // base64-encoded image data
}

ImageSource describes the source of an image for the API.

type KeepConfig 

type KeepConfig struct {
	Type  string `json:"type"`            // "tool_uses"
	Value int    `json:"value,omitempty"` // number to keep
}

KeepConfig specifies how many recent tool uses to preserve.

type Message 

type Message struct {
	Role    string          `json:"role"` // "user", "assistant"
	Content json.RawMessage `json:"content"`
}

Message represents a conversation message.

type MessageResp 

type MessageResp struct {
	ID         string         `json:"id"`
	Type       string         `json:"type"`
	Role       string         `json:"role"`
	Content    []ContentBlock `json:"content"`
	Model      string         `json:"model"`
	StopReason string         `json:"stop_reason"`
	Usage      Usage          `json:"usage"`
}

MessageResp is the full message response.

type MessagesRequest 

type MessagesRequest struct {
	Model        string          `json:"model"`
	MaxTokens    int             `json:"max_tokens"`
	Messages     []Message       `json:"messages"`
	System       string          `json:"-"`                // Set by callers as plain string, marshaled by custom logic
	SystemRaw    json.RawMessage `json:"system,omitempty"` // Actual JSON sent to API (string or array of blocks)
	Stream       bool            `json:"stream,omitempty"`
	Tools        json.RawMessage `json:"tools,omitempty"`
	Temperature  *float64        `json:"temperature,omitempty"`
	StopReason   string          `json:"stop_reason,omitempty"`
	Thinking     *ThinkingConfig `json:"thinking,omitempty"`
	OutputConfig *OutputConfig   `json:"output_config,omitempty"`

	// ContextManagement enables server-side context editing (Anthropic only).
	// When set, the API strips old tool results from the cached prefix.
	ContextManagement *ContextManagement `json:"context_management,omitempty"`
}

MessagesRequest is the request body for /v1/messages.

type ModelInfo 

type ModelInfo struct {
	ID           string `json:"id"`
	OwnedBy      string `json:"owned_by,omitempty"`
	ProviderName string `json:"-"` // set by DiscoverModels, not part of API response
}

ModelInfo describes an available model from a provider.

type ModelLister 

type ModelLister interface {
	ListModels(ctx context.Context, httpClient *http.Client) ([]ModelInfo, error)
}

ModelLister is an optional interface that providers can implement to support model discovery. Type-assert a Provider to check if it supports listing.

type ModelPricing 

type ModelPricing struct {
	InputPerMillion      float64
	OutputPerMillion     float64
	CacheReadPerMillion  float64
	CacheWritePerMillion float64
}

ModelPricing holds cost per million tokens for a model.

type OutputConfig 

type OutputConfig struct {
	Effort string `json:"effort,omitempty"` // "low", "medium", "high"
}

OutputConfig configures output behavior including effort level.

type Provider 

type Provider interface {
	// StreamMessages sends a streaming request and returns channels for events and errors.
	StreamMessages(ctx context.Context, httpClient *http.Client, req *MessagesRequest) (<-chan StreamEvent, <-chan error)

	// SendMessage sends a non-streaming request and returns the response.
	SendMessage(ctx context.Context, httpClient *http.Client, req *MessagesRequest) (*MessageResp, error)
}

Provider handles sending requests to a specific API backend. Implementations translate between claudio's internal Anthropic-style types and whatever wire format the backend expects (e.g. OpenAI chat completions).

type ProviderModel 

type ProviderModel struct {
	ModelID      string // e.g. "llama-3.3-70b-versatile"
	ProviderName string // e.g. "groq"
}

ProviderModel describes a model available through a configured provider.

type StreamEvent 

type StreamEvent struct {
	Type         string          `json:"type"`
	Delta        json.RawMessage `json:"delta,omitempty"`
	Index        int             `json:"index,omitempty"`
	MessageField json.RawMessage `json:"message,omitempty"`       // For message_start
	ContentBlock json.RawMessage `json:"content_block,omitempty"` // For content_block_start
	Usage        *Usage          `json:"usage,omitempty"`         // For message_delta
}

StreamEvent represents a single SSE event from the streaming API.

type SystemBlock 

type SystemBlock struct {
	Type         string             `json:"type"`
	Text         string             `json:"text"`
	CacheControl *CacheControlBlock `json:"cache_control,omitempty"`
}

SystemBlock is a text block in the system prompt array.

type ThinkingConfig 

type ThinkingConfig struct {
	Type         string `json:"type"`                    // "adaptive", "enabled", "disabled"
	BudgetTokens int    `json:"budget_tokens,omitempty"` // Required when type is "enabled"
}

ThinkingConfig configures extended thinking for supported models.

type Trigger 

type Trigger struct {
	Type  string `json:"type"`            // "input_tokens" or "tool_uses"
	Value int    `json:"value,omitempty"` // threshold value
}

Trigger defines when a context edit activates.

type Usage 

type Usage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	CacheRead    int `json:"cache_read_input_tokens,omitempty"`
	CacheCreate  int `json:"cache_creation_input_tokens,omitempty"`
}

Usage tracks token consumption.

type UsageTracker 

type UsageTracker struct {
	InputTokens       int
	OutputTokens      int
	CacheRead         int
	CacheCreate       int
	TurnCount         int
	TotalCost         float64
	Budget            float64 // 0 = unlimited
	LastContextTokens int     // input+cacheRead+cacheCreate from the most recent turn (current context window size)
	// contains filtered or unexported fields
}

UsageTracker accumulates token usage and cost across a session.

func NewUsageTracker 

func NewUsageTracker(model string, budget float64) *UsageTracker

NewUsageTracker creates a tracker for the given model.

func (*UsageTracker) Add 

func (t *UsageTracker) Add(usage Usage)

Add records token usage from a turn.

func (*UsageTracker) Cost 

func (t *UsageTracker) Cost() float64

Cost returns the current estimated cost.

func (*UsageTracker) IsOverBudget 

func (t *UsageTracker) IsOverBudget() bool

IsOverBudget returns true if the budget has been exceeded.

func (*UsageTracker) Snapshot 

func (t *UsageTracker) Snapshot() (contextTokens int, cost float64)

Snapshot returns current values for display. contextTokens is the last turn's input+cacheRead+cacheCreate — this is the actual current context window usage as reported by the API, not a cumulative sum. Using the cumulative sum would overcount by N× after N turns.

func (*UsageTracker) Summary 

func (t *UsageTracker) Summary() string

Summary returns a human-readable summary of usage.

type UserContentBlock 

type UserContentBlock struct {
	Type   string       `json:"type"`             // "text" or "image"
	Text   string       `json:"text,omitempty"`   // for type="text"
	Source *ImageSource `json:"source,omitempty"` // for type="image"
}

UserContentBlock is a content block in a user message (text or image).

func NewImageBlock 

func NewImageBlock(mediaType, base64Data string) UserContentBlock

NewImageBlock creates an image content block for a user message.

func NewTextBlock 

func NewTextBlock(text string) UserContentBlock

NewTextBlock creates a text content block for a user message.

Source Files

View all Source files

Directories

Path Synopsis

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.