llm

Documentation

Index

• Variables
• type APIError
  • func (e *APIError) Error() string
  • func (e *APIError) Unwrap() error
• type ClaudeConfig
• type ClaudeProvider
  • func NewClaudeProvider(cfg ClaudeConfig) *ClaudeProvider
  • func (p *ClaudeProvider) IsConfigured() bool
  • func (p *ClaudeProvider) Name() string
  • func (p *ClaudeProvider) Send(ctx context.Context, req SendRequest) (*Response, error)
• type Client
  • func NewClient(cfg ClientConfig) *Client
  • func NewClientWithProvider(provider Provider) *Client
  • func (c *Client) IsConfigured() bool
  • func (c *Client) ProviderName() string
  • func (c *Client) Send(ctx context.Context, req SendRequest) (*Response, error)
• type ClientConfig
• type ContentBlock
• type Message
  • func NewAssistantMessage(blocks []ContentBlock) Message
  • func NewToolResultMessage(results []ToolResult) Message
  • func NewUserMessage(text string) Message
  • func (m Message) HasToolUse() bool
  • func (m Message) TextContent() string
  • func (m Message) ToolUseBlocks() []ContentBlock
• type OpenAIConfig
• type OpenAIProvider
  • func NewOpenAIProvider(cfg OpenAIConfig) *OpenAIProvider
  • func (p *OpenAIProvider) IsConfigured() bool
  • func (p *OpenAIProvider) Name() string
  • func (p *OpenAIProvider) Send(ctx context.Context, req SendRequest) (*Response, error)
• type Provider
• type ProviderType
• type Response
• type Role
• type SendRequest
• type StopReason
• type ToolResult
• type Usage

Variables

var (
	ErrBadRequest   = errors.New("bad request")
	ErrUnauthorized = errors.New("unauthorized")
	ErrAPIError     = errors.New("api error")
	ErrMaxRetries   = errors.New("max retries exceeded")
)

Types

type APIError

type APIError struct {
	StatusCode int    `json:"status_code"`
	ErrorMsg   string `json:"message"`
	Type       string `json:"type"`
}

APIError represents an error from an LLM API.

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

type ClaudeConfig

type ClaudeConfig struct {
	APIKey    string
	Model     string
	MaxTokens int
	Timeout   time.Duration
	BaseURL   string
}

ClaudeConfig configures the Claude provider.

type ClaudeProvider

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

ClaudeProvider implements the Anthropic Claude Messages API.

func NewClaudeProvider

func NewClaudeProvider(cfg ClaudeConfig) *ClaudeProvider

NewClaudeProvider creates a new Claude API provider.

func (*ClaudeProvider) IsConfigured

func (p *ClaudeProvider) IsConfigured() bool

func (*ClaudeProvider) Name

func (p *ClaudeProvider) Name() string

func (*ClaudeProvider) Send

func (p *ClaudeProvider) Send(ctx context.Context, req SendRequest) (*Response, error)

type Client

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

Client wraps an LLM Provider with a unified interface. This is the type that the rest of the agent code uses.

func NewClient

func NewClient(cfg ClientConfig) *Client

NewClient creates a new LLM client with the appropriate provider.

func NewClientWithProvider

func NewClientWithProvider(provider Provider) *Client

NewClientWithProvider creates a client from an existing provider.

func (*Client) IsConfigured

func (c *Client) IsConfigured() bool

IsConfigured delegates to the underlying provider.

func (*Client) ProviderName

func (c *Client) ProviderName() string

ProviderName returns the name of the underlying provider.

func (*Client) Send

func (c *Client) Send(ctx context.Context, req SendRequest) (*Response, error)

Send delegates to the underlying provider.

type ClientConfig

type ClientConfig struct {
	Provider  ProviderType
	APIKey    string
	Model     string
	MaxTokens int
	Timeout   time.Duration
	BaseURL   string
	Headers   map[string]string // extra headers (e.g., for OpenRouter)
}

ClientConfig configures the LLM client.

type ContentBlock

type ContentBlock struct {
	Type      string          `json:"type"`
	Text      string          `json:"text,omitempty"`
	ID        string          `json:"id,omitempty"`
	Name      string          `json:"name,omitempty"`
	Input     json.RawMessage `json:"input,omitempty"`
	ToolUseID string          `json:"tool_use_id,omitempty"`
	Content   string          `json:"content,omitempty"`
	IsError   bool            `json:"is_error,omitempty"`
}

ContentBlock represents a single block in a message's content array.

type Message

type Message struct {
	Role    Role           `json:"role"`
	Content []ContentBlock `json:"content"`
}

Message represents a single message in the conversation.

func NewAssistantMessage

func NewAssistantMessage(blocks []ContentBlock) Message

NewAssistantMessage creates an assistant message with the given content blocks.

func NewToolResultMessage

func NewToolResultMessage(results []ToolResult) Message

NewToolResultMessage creates a user message with tool_result blocks.

func NewUserMessage

func NewUserMessage(text string) Message

NewUserMessage creates a user message with a single text block.

func (Message) HasToolUse

func (m Message) HasToolUse() bool

HasToolUse returns true if any content block has type "tool_use".

func (Message) TextContent

func (m Message) TextContent() string

TextContent concatenates all text blocks' Text fields, separated by newlines.

func (Message) ToolUseBlocks

func (m Message) ToolUseBlocks() []ContentBlock

ToolUseBlocks returns only the content blocks with type "tool_use".

type OpenAIConfig

type OpenAIConfig struct {
	APIKey    string
	Model     string
	MaxTokens int
	Timeout   time.Duration
	BaseURL   string
	Headers   map[string]string // extra headers (e.g., "HTTP-Referer" for OpenRouter)
}

OpenAIConfig configures the OpenAI-compatible provider.

type OpenAIProvider

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

OpenAIProvider implements the OpenAI-compatible Chat Completions API. Works with OpenAI, OpenRouter, Codex CLI, and any OpenAI-compatible endpoint.

func NewOpenAIProvider

func NewOpenAIProvider(cfg OpenAIConfig) *OpenAIProvider

NewOpenAIProvider creates a new OpenAI-compatible API provider.

func (*OpenAIProvider) IsConfigured

func (p *OpenAIProvider) IsConfigured() bool

func (*OpenAIProvider) Name

func (p *OpenAIProvider) Name() string

func (*OpenAIProvider) Send

func (p *OpenAIProvider) Send(ctx context.Context, req SendRequest) (*Response, error)

type Provider

type Provider interface {
	// Send sends a conversation to the LLM and returns a parsed response.
	Send(ctx context.Context, req SendRequest) (*Response, error)
	// IsConfigured returns true if the provider has valid credentials.
	IsConfigured() bool
	// Name returns the provider identifier (e.g., "claude", "openai").
	Name() string
}

Provider is the interface for LLM API backends. Internal message format uses content blocks (tool_use, tool_result). Each provider converts to/from its wire format.

type ProviderType

type ProviderType string

ProviderType identifies the LLM provider backend.

const (
	ProviderClaude ProviderType = "claude"
	ProviderOpenAI ProviderType = "openai"
)

type Response

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

Response represents a parsed LLM response (provider-agnostic).

type Role

type Role string

Role represents the role of a message sender.

const (
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
)

type SendRequest

type SendRequest struct {
	System   string
	Messages []Message
	Tools    []map[string]any
}

SendRequest holds the parameters for an LLM API call.

type StopReason

type StopReason string

StopReason indicates why the model stopped generating.

const (
	StopReasonEndTurn      StopReason = "end_turn"
	StopReasonToolUse      StopReason = "tool_use"
	StopReasonMaxTokens    StopReason = "max_tokens"
	StopReasonStopSequence StopReason = "stop_sequence"
)

type ToolResult

type ToolResult struct {
	ToolUseID string `json:"tool_use_id"`
	Content   string `json:"content"`
	IsError   bool   `json:"is_error,omitempty"`
}

ToolResult represents the result of a tool execution.

type Usage

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

Usage represents token usage from an LLM response.