ai

package
v0.62.0 Latest Latest
Warning

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

Go to latest
Published: Aug 5, 2026 License: AGPL-3.0 Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// MaxImageInputBytes is the largest original image accepted for canonical
	// session ingestion before it is converted to a provider payload.
	MaxImageInputBytes = 30 * 1024 * 1024
	// MaxImagesPerMessage and MaxAggregateImageBytes bound one image-bearing
	// message before decoding or persistence allocates its originals.
	MaxImagesPerMessage    = 8
	MaxAggregateImageBytes = 60 * 1024 * 1024
)
View Source
const UnavailableImageProjection = "[Image baseline unavailable.]"

UnavailableImageProjection is deliberately independent of a renderer, timestamp, and error body. It is the only durable text for an image whose original bytes persisted but whose baseline could not be produced.

Variables

View Source
var (
	ErrRawImageContent           = errors.New("raw image content cannot be stored canonically")
	ErrUnsupportedCanonicalBlock = errors.New("content block cannot be stored canonically")
)

Functions

func FlattenCanonicalText added in v0.61.0

func FlattenCanonicalText(blocks []ContentBlock) string

FlattenCanonicalText is the stable text projection for durable blocks. It never exposes provider-ready bytes and gives unavailable images one fixed marker so compaction and storage do not acquire backend-specific errors.

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.

func HasImageRef added in v0.61.0

func HasImageRef(blocks []ContentBlock) bool

HasImageRef reports whether content contains durable session media.

func MarshalContentBlocks added in v0.60.3

func MarshalContentBlocks(blocks []ContentBlock) ([]byte, error)

MarshalContentBlocks serializes text and legacy inline image blocks. It remains compatible with group history while ordinary session history moves to the explicit canonical codec below.

func ValidateCanonicalContentBlocks added in v0.61.0

func ValidateCanonicalContentBlocks(blocks []ContentBlock) error

ValidateCanonicalContentBlocks rejects provider-ready bytes and block kinds that cannot be represented by durable message parts.

func ValidateImageBaselineText added in v0.61.0

func ValidateImageBaselineText(text string) error

ValidateImageBaselineText validates the stable OCR-and-scene storage shape. OCR text may contain headings; only the exact blank-line Scene delimiter is structural. Once Scene starts, another markdown section would make the canonical shape ambiguous and is rejected.

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.

func CloneContentBlocks added in v0.61.0

func CloneContentBlocks(blocks []ContentBlock) []ContentBlock

CloneContentBlocks returns a storage-safe copy. Content values are immutable except ToolCall.Arguments, which may contain nested maps or slices owned by a caller that mutates them after an asynchronous handoff.

func UnmarshalContentBlocks added in v0.60.3

func UnmarshalContentBlocks(data []byte) ([]ContentBlock, error)

UnmarshalContentBlocks is the compatibility decoder. Legacy inline images remain ImageContent, while image_ref records retain their canonical type. Unknown kinds are skipped so old readers tolerate newer payloads.

type ContentBlockJSON added in v0.60.3

type ContentBlockJSON struct {
	Kind     string `json:"kind"`
	Text     string `json:"text,omitempty"`
	Data     string `json:"data,omitempty"`
	MimeType string `json:"mime_type,omitempty"`
}

ContentBlockJSON is the compatibility serialization for deferred group history. Canonical ordinary-session references live only in message parts.

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 ImageBaseline added in v0.61.0

type ImageBaseline struct {
	Text string
}

ImageBaseline is the immutable provider projection for one session image. The zero value is the stable unavailable marker; ready values use the sole V1 text contract validated by Validate.

func ParseImageBaseline added in v0.61.0

func ParseImageBaseline(projection string) (ImageBaseline, error)

ParseImageBaseline reconstructs a baseline from its exact durable projection.

func (ImageBaseline) Projection added in v0.61.0

func (b ImageBaseline) Projection() string

Projection returns the bounded stable text used by durable history.

func (ImageBaseline) Validate added in v0.61.0

func (b ImageBaseline) Validate() error

type ImageCapability added in v0.61.0

type ImageCapability int

ImageCapability describes what the configuration says about a model's ability to accept image input. It is deliberately three-valued: "we know it cannot" and "we were never told" are different facts, and callers decide how to treat the latter.

const (
	// ImageUnknown means no input modalities were declared, so the capability
	// was never stated. It is the zero value: an undeclared model is unknown,
	// never implicitly unsupported — callers that must choose treat it as
	// "cannot see", but the distinction stays visible here.
	ImageUnknown ImageCapability = iota
	// ImageSupported means the declared input modalities include images.
	ImageSupported
	// ImageUnsupported means input modalities were declared and images are not
	// among them.
	ImageUnsupported
)

type ImageContent

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

ImageContent represents ephemeral, base64-encoded provider or tool input. It must not be written to new ordinary-session history.

func (ImageContent) DataURI

func (ic ImageContent) DataURI() string

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

type ImageRefContent added in v0.61.0

type ImageRefContent struct {
	MediaID  string
	Baseline ImageBaseline
}

ImageRefContent is a canonical reference to immutable session media. MIME is owned by the media row and resolved only during authorized hydration.

func (ImageRefContent) Validate added in v0.61.0

func (r ImageRefContent) Validate() error

Validate checks the storage invariants for a canonical image reference.

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.

func (Model) ImageCapability added in v0.61.0

func (m Model) ImageCapability() ImageCapability

ImageCapability reports what the model's declared input modalities say about image input. Callers choose the policy for ImageUnknown.

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 StopReason

type StopReason string

StopReason normalizes provider-specific stop signals.

const (
	// StopReasonUnknown is an unrecognized or omitted provider finish reason.
	// Consumers that require a complete response must fail closed on it.
	StopReasonUnknown StopReason = ""
	StopReasonStop    StopReason = "stop"
	StopReasonLength  StopReason = "length"
	StopReasonToolUse StopReason = "toolUse"
	StopReasonError   StopReason = "error"
	StopReasonAborted StopReason = "aborted"
)

type StreamOptions

type StreamOptions struct {
	Temperature     *float64
	MaxTokens       *int
	Reasoning       ThinkingLevel
	ThinkingBudgets *ThinkingBudgets
	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 | ImageRefContent
	Details    any
	IsError    bool
	Timestamp  time.Time
	References []renderrefs.Reference
}

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

func (UserMessage) TimestampedContent

func (m UserMessage) TimestampedContent() any

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

Jump to

Keyboard shortcuts

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