ai

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Mar 17, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrProviderNotFound = errors.New("provider not found")

ErrProviderNotFound indicates missing provider registration.

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 AssistantEventStream

type AssistantEventStream interface {
	Events() <-chan AssistantEvent
	Close() error
	Wait() error
}

AssistantEventStream provides ordered assistant events.

func Stream

func Stream(model Model, ctx Context, opts StreamOptions, providers ProviderGetter) (AssistantEventStream, error)

Stream dispatches request to the registered API provider.

func StreamSimple

func StreamSimple(model Model, ctx Context, opts SimpleStreamOptions, providers ProviderGetter) (AssistantEventStream, error)

StreamSimple dispatches simplified streaming to provider.

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.

func Complete

func Complete(model Model, ctx Context, opts CompleteOptions, providers ProviderGetter) (AssistantMessage, error)

Complete consumes a full stream and assembles an assistant message.

type CacheRetention

type CacheRetention = string

CacheRetention controls prompt cache retention preference.

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

type ChannelEventStream

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

ChannelEventStream is a channel-backed AssistantEventStream.

func NewChannelEventStream

func NewChannelEventStream(buffer int) *ChannelEventStream

NewChannelEventStream returns a writable channel stream.

func (*ChannelEventStream) Close

func (s *ChannelEventStream) Close() error

Close closes the event stream.

func (*ChannelEventStream) Emit

func (s *ChannelEventStream) Emit(event AssistantEvent)

Emit sends one event to subscribers.

func (*ChannelEventStream) Events

func (s *ChannelEventStream) Events() <-chan AssistantEvent

Events returns read-only event channel.

func (*ChannelEventStream) Finish

func (s *ChannelEventStream) Finish(err error)

Finish closes stream and stores terminal error if any.

func (*ChannelEventStream) Wait

func (s *ChannelEventStream) Wait() error

Wait returns terminal stream error.

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    []toolspec.Definition
	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 ModelLister

type ModelLister interface {
	ListModels(ctx context.Context) ([]Model, error)
}

ModelLister is an optional interface providers can implement to list available models.

type Provider

type Provider = string

Provider identifies the upstream service.

type ProviderAdapter

type ProviderAdapter interface {
	API() string
	Stream(model Model, ctx Context, opts StreamOptions) (AssistantEventStream, error)
	StreamSimple(model Model, ctx Context, opts SimpleStreamOptions) (AssistantEventStream, error)
}

Provider defines the provider adapter contract.

type ProviderGetter

type ProviderGetter interface {
	Get(api string) (ProviderAdapter, bool)
}

ProviderGetter provides provider lookup.

type Registry

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

Registry stores providers by API name.

func DefaultRegistry

func DefaultRegistry() *Registry

DefaultRegistry returns the process-wide provider registry singleton.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty provider registry.

func (*Registry) Get

func (r *Registry) Get(api string) (ProviderAdapter, bool)

Get resolves a provider by API key.

func (*Registry) Register

func (r *Registry) Register(provider ProviderAdapter)

Register stores a provider by API key.

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 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).

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL