Documentation
¶
Index ¶
- Constants
- Variables
- func FlattenCanonicalText(blocks []ContentBlock) string
- func FlattenText(blocks []ContentBlock) string
- func HasImage(blocks []ContentBlock) bool
- func HasImageRef(blocks []ContentBlock) bool
- func MarshalContentBlocks(blocks []ContentBlock) ([]byte, error)
- func ValidateCanonicalContentBlocks(blocks []ContentBlock) error
- func ValidateImageBaselineText(text string) error
- type Api
- type AssistantEvent
- type AssistantMessage
- type CacheRetention
- type CompleteOptions
- type ContentBlock
- type ContentBlockJSON
- 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 ImageBaseline
- type ImageCapability
- type ImageContent
- type ImageRefContent
- type Message
- type Model
- type ModelCost
- type Provider
- 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
Constants ¶
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 )
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 ¶
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
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 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 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 ¶
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 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 ¶
ThinkingBudgets maps thinking levels to token budgets (token-based providers only).
type ThinkingContent ¶
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 ToolDefinition ¶
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 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 ¶
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.