assistant

Documentation

Overview

Package assistant provides AI provider abstraction for chat completions.

Index

• Constants
• Variables
• func IsAuthError(err error) bool
• func IsRateLimited(err error) bool
• func ParseErrorResponse(resp *http.Response) error
• type APIError
  • func (e *APIError) Error() string
• type Assistant
• type Backend
• type ChatRequest
• type ChatResponse
• type EventType
• type Items
• type Message
  • func NewAssistantMessage(content string) Message
  • func NewAssistantToolCallMessage(content string, toolCalls []ToolCall) Message
  • func NewSystemMessage(content string) Message
  • func NewToolResultMessage(toolCallID, result string) Message
  • func NewUserMessage(content string) Message
• type Parameters
• type Property
• type StreamEvent
• type StreamReader
  • func NewStreamReader(r io.ReadCloser, parseEvent func(data string) (*StreamEvent, error)) *StreamReader
  • func (s *StreamReader) Close() error
  • func (s *StreamReader) Collect() (*ChatResponse, error)
  • func (s *StreamReader) Content() string
  • func (s *StreamReader) Done() bool
  • func (s *StreamReader) Err() error
  • func (s *StreamReader) Next() *StreamEvent
  • func (s *StreamReader) ToolCalls() []ToolCall
• type Tool
• type ToolBuilder
  • func NewTool(name, description string) *ToolBuilder
  • func (b *ToolBuilder) Array(name, description, itemType string, required bool) *ToolBuilder
  • func (b *ToolBuilder) Bool(name, description string, required bool) *ToolBuilder
  • func (b *ToolBuilder) Build() Tool
  • func (b *ToolBuilder) Enum(name, description string, values []string, required bool) *ToolBuilder
  • func (b *ToolBuilder) Int(name, description string, required bool) *ToolBuilder
  • func (b *ToolBuilder) Number(name, description string, required bool) *ToolBuilder
  • func (b *ToolBuilder) String(name, description string, required bool) *ToolBuilder
• type ToolCall
  • func (tc *ToolCall) ParseArguments(v any) error
• type Usage

Constants

const (
	RoleSystem    = "system"
	RoleUser      = "user"
	RoleAssistant = "assistant"
	RoleTool      = "tool"
)

Message roles

Variables

var (
	// ErrNoAPIKey is returned when no API key is provided.
	ErrNoAPIKey = errors.New("API key is required")

	// ErrRateLimited is returned when rate limited by the API.
	ErrRateLimited = errors.New("rate limited")

	// ErrEmptyResponse is returned when the API returns an empty response.
	ErrEmptyResponse = errors.New("empty response")
)

Functions

func IsAuthError

func IsAuthError(err error) bool

IsAuthError returns true if the error is an authentication error.

func IsRateLimited

func IsRateLimited(err error) bool

IsRateLimited returns true if the error is a rate limit error.

func ParseErrorResponse

func ParseErrorResponse(resp *http.Response) error

ParseErrorResponse reads an HTTP error response body and constructs an APIError. Both Anthropic and OpenAI use the same {"error": {"type": "...", "message": "..."}} shape. If the body cannot be parsed, the raw body text is used as the error message.

This is provider-facing: used by provider subpackages to handle API errors.

Types

type APIError

type APIError struct {
	StatusCode int    // HTTP status code
	Type       string // Error type from the API
	Message    string // Error message
}

APIError represents an error from the AI provider's API.

func (*APIError) Error

func (e *APIError) Error() string

Error returns a formatted error string including the status code and message.

type Assistant

type Assistant struct {
	Backend
}

Assistant provides AI chat operations. Use providers to create: mock.New(), openai.New(), anthropic.New()

type Backend

type Backend interface {
	// Chat sends a request and returns the complete response.
	Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)

	// Stream sends a request and returns a stream reader for SSE.
	Stream(ctx context.Context, req ChatRequest) (*StreamReader, error)
}

Backend is the interface that providers implement.

type ChatRequest

type ChatRequest struct {
	Model       string    // Model identifier (e.g., "gpt-4", "claude-3-opus")
	Messages    []Message // Conversation history
	Tools       []Tool    // Available tools
	MaxTokens   int       // Maximum tokens in response
	Temperature *float64  // Sampling temperature (0-2), nil means provider default
	System      string    // System prompt
}

ChatRequest configures a chat completion request.

type ChatResponse

type ChatResponse struct {
	Content      string     // Text content of the response
	ToolCalls    []ToolCall // Tool calls requested by the model
	FinishReason string     // Why generation stopped: "stop", "tool_calls", "length"
	Usage        Usage      // Token usage statistics
}

ChatResponse is the result of a chat completion.

type EventType

type EventType int

EventType represents the type of streaming event.

const (
	EventContentDelta  EventType = iota // Text content chunk
	EventToolCallStart                  // Tool call started
	EventToolCallDelta                  // Tool call argument chunk
	EventDone                           // Stream complete
	EventError                          // Error occurred
)

Streaming event types used by StreamReader to classify incoming SSE events.

type Items

type Items struct {
	Type string `json:"type"`
}

Items describes array item type. This is provider-facing: used by provider subpackages to serialize tool definitions.

type Message

type Message struct {
	Role       string     // "system", "user", "assistant", or "tool"
	Content    string     // Message text content
	ToolCalls  []ToolCall // Tool calls (assistant messages only)
	ToolCallID string     // ID of the tool call this is a result for (tool messages only)
}

Message represents a chat message.

func NewAssistantMessage

func NewAssistantMessage(content string) Message

NewAssistantMessage creates an assistant message.

func NewAssistantToolCallMessage

func NewAssistantToolCallMessage(content string, toolCalls []ToolCall) Message

NewAssistantToolCallMessage creates an assistant message with tool calls.

func NewSystemMessage

func NewSystemMessage(content string) Message

NewSystemMessage creates a system message.

func NewToolResultMessage

func NewToolResultMessage(toolCallID, result string) Message

NewToolResultMessage creates a tool result message.

func NewUserMessage

func NewUserMessage(content string) Message

NewUserMessage creates a user message.

type Parameters

type Parameters struct {
	Type       string              `json:"type"` // Always "object"
	Properties map[string]Property `json:"properties,omitempty"`
	Required   []string            `json:"required,omitempty"`
}

Parameters describes the JSON schema for tool parameters. This is provider-facing: used by provider subpackages to serialize tool definitions.

type Property

type Property struct {
	Type        string   `json:"type"` // "string", "number", "boolean", "array", "object"
	Description string   `json:"description,omitempty"`
	Enum        []string `json:"enum,omitempty"`  // For string enums
	Items       *Items   `json:"items,omitempty"` // For arrays
}

Property describes a single parameter. This is provider-facing: used by provider subpackages to serialize tool definitions.

type StreamEvent

type StreamEvent struct {
	Type      EventType
	Content   string    // For ContentDelta
	ToolCall  *ToolCall // For ToolCallStart/ToolCallDelta (partial)
	ToolIndex int       // Index of tool call being updated
	Error     error     // For Error events
	Usage     *Usage    // For Done events (optional)
}

StreamEvent represents a single event in the stream.

type StreamReader

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

StreamReader reads events from an SSE stream.

func NewStreamReader

func NewStreamReader(r io.ReadCloser, parseEvent func(data string) (*StreamEvent, error)) *StreamReader

NewStreamReader creates a stream reader from an io.ReadCloser. This is provider-facing: used by provider subpackages to wire SSE parsing.

func (*StreamReader) Close

func (s *StreamReader) Close() error

Close closes the underlying reader.

func (*StreamReader) Collect

func (s *StreamReader) Collect() (*ChatResponse, error)

Collect reads all events and returns the final response.

func (*StreamReader) Content

func (s *StreamReader) Content() string

Content returns all accumulated content.

func (*StreamReader) Done

func (s *StreamReader) Done() bool

Done returns true if the stream is complete.

func (*StreamReader) Err

func (s *StreamReader) Err() error

Err returns any error that occurred during streaming.

func (*StreamReader) Next

func (s *StreamReader) Next() *StreamEvent

Next returns the next event in the stream. Returns nil when the stream is complete or on error.

func (*StreamReader) ToolCalls

func (s *StreamReader) ToolCalls() []ToolCall

ToolCalls returns all accumulated tool calls.

type Tool

type Tool struct {
	Name        string      `json:"name"`
	Description string      `json:"description"`
	Parameters  *Parameters `json:"parameters,omitempty"`
}

Tool represents a function the model can call.

type ToolBuilder

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

ToolBuilder provides a fluent interface for building tools.

func NewTool

func NewTool(name, description string) *ToolBuilder

NewTool creates a new ToolBuilder.

func (*ToolBuilder) Array

func (b *ToolBuilder) Array(name, description, itemType string, required bool) *ToolBuilder

Array adds an array parameter.

func (*ToolBuilder) Bool

func (b *ToolBuilder) Bool(name, description string, required bool) *ToolBuilder

Bool adds a boolean parameter.

func (*ToolBuilder) Build

func (b *ToolBuilder) Build() Tool

Build creates the Tool.

func (*ToolBuilder) Enum

func (b *ToolBuilder) Enum(name, description string, values []string, required bool) *ToolBuilder

Enum adds a string enum parameter.

func (*ToolBuilder) Int

func (b *ToolBuilder) Int(name, description string, required bool) *ToolBuilder

Int adds an integer parameter.

func (*ToolBuilder) Number

func (b *ToolBuilder) Number(name, description string, required bool) *ToolBuilder

Number adds a number parameter.

func (*ToolBuilder) String

func (b *ToolBuilder) String(name, description string, required bool) *ToolBuilder

String adds a string parameter.

type ToolCall

type ToolCall struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"` // JSON string
}

ToolCall represents a tool invocation requested by the model.

func (*ToolCall) ParseArguments

func (tc *ToolCall) ParseArguments(v any) error

ParseArguments parses the JSON arguments into the provided struct.

type Usage

type Usage struct {
	PromptTokens     int // Tokens in the request
	CompletionTokens int // Tokens in the response
	TotalTokens      int // Total tokens used
}

Usage tracks token consumption.