ai

Documentation

Index

• func FlattenText(blocks []ContentBlock) string
• func HasImage(blocks []ContentBlock) bool
• type Api
• type AssistantEvent
• type AssistantMessage
• type CacheRetention
• type CompleteOptions
• type ContentBlock
• type Context
• type EventDone
• type EventError
• type EventStart
• type EventStop
• type EventTextDelta
• type EventTextEnd
• type EventTextStart
• type EventThinkingDelta
• type EventThinkingEnd
• type EventThinkingStart
• type EventToolCallDelta
• type EventToolCallEnd
• type EventToolCallStart
• type EventUsage
• type ImageContent
  • func (ic ImageContent) DataURI() string
• type Message
  • func TransformMessages(messages []Message) []Message
• type Model
• type ModelCost
• type Provider
• type SimpleStreamOptions
• type StopReason
• type StreamOptions
• type TextContent
• type TextSignatureV1
• type ThinkingBudgets
• type ThinkingContent
• type ThinkingLevel
• type ToolCall
• type ToolDefinition
• type ToolResultMessage
• type Transport
• type Usage
• type UsageCost
• type UserMessage
  • func (m UserMessage) TimestampedContent() any

Functions

func FlattenText

func FlattenText(blocks []ContentBlock) string

FlattenText extracts and joins all TextContent values from content blocks.

func HasImage

func HasImage(blocks []ContentBlock) bool

HasImage reports whether the given content blocks contain at least one ImageContent.

Types

type Api

type Api = string

Api identifies the wire protocol family.

const (
	ApiOpenAICompletions     Api = "openai-completions"
	ApiOpenAIResponses       Api = "openai-responses"
	ApiAnthropicMessages     Api = "anthropic-messages"
	ApiBedrockConverseStream Api = "bedrock-converse-stream"
	ApiGoogleGenerativeAI    Api = "google-generative-ai"
	ApiGoogleVertex          Api = "google-vertex"
)

Common API constants.

type AssistantEvent

type AssistantEvent interface {
	// contains filtered or unexported methods
}

AssistantEvent is the normalized event emitted by providers during generation.

type AssistantMessage

type AssistantMessage struct {
	Content      []ContentBlock
	Api          string
	Provider     string
	Model        string
	Usage        Usage
	StopReason   StopReason
	ErrorMessage string
	Timestamp    time.Time
}

AssistantMessage contains assistant output and metadata.

type CacheRetention

type CacheRetention = string

CacheRetention controls prompt cache retention preference.

const (
	CacheNone  CacheRetention = "none"
	CacheShort CacheRetention = "short"
	CacheLong  CacheRetention = "long"
)

type CompleteOptions

type CompleteOptions struct {
	StreamOptions
}

CompleteOptions configures non-streaming requests.

type ContentBlock

type ContentBlock interface {
	// contains filtered or unexported methods
}

ContentBlock is the normalized assistant content unit.

type Context

type Context struct {
	System   string
	Messages []Message
	Tools    []ToolDefinition
	Metadata map[string]string
}

Context carries all conversation and tool state for a model request.

type EventDone

type EventDone struct{}

EventDone signals stream completion.

type EventError

type EventError struct {
	Err   error
	Error *AssistantMessage
}

EventError reports terminal provider errors.

type EventStart

type EventStart struct {
	Time    time.Time
	Partial *AssistantMessage
}

EventStart signals the beginning of an assistant turn.

type EventStop

type EventStop struct {
	Reason  StopReason
	Message *AssistantMessage
}

EventStop signals end of generation with reason.

type EventTextDelta

type EventTextDelta struct {
	ContentIndex int
	Text         string
	Partial      *AssistantMessage
}

EventTextDelta carries incremental text output.

type EventTextEnd

type EventTextEnd struct {
	ContentIndex int
	Content      string
	Partial      *AssistantMessage
}

EventTextEnd signals the end of a text content block.

type EventTextStart

type EventTextStart struct {
	ContentIndex int
	Partial      *AssistantMessage
}

EventTextStart signals the start of a text content block.

type EventThinkingDelta

type EventThinkingDelta struct {
	ContentIndex int
	Thinking     string
	Partial      *AssistantMessage
}

EventThinkingDelta carries incremental reasoning output.

type EventThinkingEnd

type EventThinkingEnd struct {
	ContentIndex int
	Content      string
	Partial      *AssistantMessage
}

EventThinkingEnd signals the end of a thinking content block.

type EventThinkingStart

type EventThinkingStart struct {
	ContentIndex int
	Partial      *AssistantMessage
}

EventThinkingStart signals the start of a thinking content block.

type EventToolCallDelta

type EventToolCallDelta struct {
	ContentIndex int
	ID           string
	Name         string
	Arguments    string
	Partial      *AssistantMessage
}

EventToolCallDelta carries incremental tool-call updates.

type EventToolCallEnd

type EventToolCallEnd struct {
	ContentIndex int
	ToolCall     ToolCall
	Partial      *AssistantMessage
}

EventToolCallEnd signals the end of a tool call content block.

type EventToolCallStart

type EventToolCallStart struct {
	ContentIndex int
	Partial      *AssistantMessage
}

EventToolCallStart signals the start of a tool call content block.

type EventUsage

type EventUsage struct {
	Usage Usage
}

EventUsage reports token usage.

type ImageContent

type ImageContent struct {
	Data     string // base64 encoded
	MimeType string // e.g. "image/jpeg", "image/png"
}

ImageContent represents base64-encoded image data.

func (ImageContent) DataURI

func (ic ImageContent) DataURI() string

DataURI returns the image as a data URI string (e.g. "data:image/jpeg;base64,...").

type Message

type Message interface {
	// contains filtered or unexported methods
}

Message is the base conversation entry.

func TransformMessages

func TransformMessages(messages []Message) []Message

TransformMessages applies compatibility normalization needed by provider adapters.

type Model

type Model struct {
	ID            string
	Name          string
	API           string
	Provider      string
	BaseURL       string
	Reasoning     bool
	Input         []string // e.g. ["text", "image"]
	Cost          ModelCost
	ContextWindow int
	MaxTokens     int
	Headers       map[string]string
}

Model identifies a concrete model and its capabilities.

type ModelCost

type ModelCost struct {
	Input      float64
	Output     float64
	CacheRead  float64
	CacheWrite float64
}

ModelCost describes per-million-token pricing.

type Provider

type Provider = string

Provider identifies the upstream service.

type SimpleStreamOptions

type SimpleStreamOptions struct {
	StreamOptions
	Reasoning       ThinkingLevel
	ThinkingBudgets *ThinkingBudgets
}

SimpleStreamOptions extends StreamOptions with reasoning controls.

type StopReason

type StopReason string

StopReason normalizes provider-specific stop signals.

const (
	StopReasonStop    StopReason = "stop"
	StopReasonLength  StopReason = "length"
	StopReasonToolUse StopReason = "toolUse"
	StopReasonError   StopReason = "error"
	StopReasonAborted StopReason = "aborted"
)

type StreamOptions

type StreamOptions struct {
	Temperature     *float64
	MaxTokens       *int
	APIKey          string
	BaseURL         string
	Transport       Transport
	CacheRetention  CacheRetention
	SessionID       string
	Headers         map[string]string
	Metadata        map[string]any
	MaxRetryDelayMS *int
	Timeout         time.Duration
}

StreamOptions configures provider-level streaming behavior.

type TextContent

type TextContent struct {
	Text          string
	TextSignature string // legacy id string or TextSignatureV1 JSON
}

TextContent represents plain text output.

type TextSignatureV1

type TextSignatureV1 struct {
	V     int    `json:"v"`
	ID    string `json:"id"`
	Phase string `json:"phase,omitempty"` // "commentary" | "final_answer"
}

TextSignatureV1 carries model-generated text signature metadata.

type ThinkingBudgets

type ThinkingBudgets struct {
	Minimal *int
	Low     *int
	Medium  *int
	High    *int
}

ThinkingBudgets maps thinking levels to token budgets (token-based providers only).

type ThinkingContent

type ThinkingContent struct {
	Thinking  string
	Signature string
	Redacted  bool
}

ThinkingContent stores provider reasoning metadata.

type ThinkingLevel

type ThinkingLevel = string

ThinkingLevel controls provider reasoning depth.

const (
	ThinkingMinimal ThinkingLevel = "minimal"
	ThinkingLow     ThinkingLevel = "low"
	ThinkingMedium  ThinkingLevel = "medium"
	ThinkingHigh    ThinkingLevel = "high"
	ThinkingXHigh   ThinkingLevel = "xhigh"
)

type ToolCall

type ToolCall struct {
	ID               string
	Name             string
	Arguments        map[string]any
	ThoughtSignature string
}

ToolCall represents a tool invocation emitted by an assistant.

type ToolDefinition

type ToolDefinition struct {
	Name        string
	Description string
	InputSchema map[string]any
}

ToolDefinition describes a callable tool exposed to a model.

type ToolResultMessage

type ToolResultMessage struct {
	ToolCallID string
	ToolName   string
	Content    []ContentBlock // TextContent | ImageContent
	Details    any
	IsError    bool
	Timestamp  time.Time
}

ToolResultMessage links a tool response to a tool call.

type Transport

type Transport = string

Transport selects the streaming transport.

const (
	TransportSSE       Transport = "sse"
	TransportWebSocket Transport = "websocket"
	TransportAuto      Transport = "auto"
)

type Usage

type Usage struct {
	InputTokens  int
	OutputTokens int
	CacheRead    int
	CacheWrite   int
	TotalTokens  int
	Cost         UsageCost
}

Usage tracks token accounting returned by providers.

type UsageCost

type UsageCost struct {
	Input      float64
	Output     float64
	CacheRead  float64
	CacheWrite float64
	Total      float64
}

UsageCost tracks monetary cost per token category.

type UserMessage

type UserMessage struct {
	Content   any
	Timestamp time.Time
}

UserMessage contains user-provided content. Content is string or []ContentBlock (TextContent | ImageContent).

func (UserMessage) TimestampedContent

func (m UserMessage) TimestampedContent() any

TimestampedContent returns Content with a "ts:<unix>\n" prefix when Timestamp is set.