schema

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Feb 15, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EventAssistant = "assistant" // Streamed text chunk from the assistant
	EventThinking  = "thinking"  // Streamed thinking/reasoning chunk
	EventTool      = "tool"      // Tool call feedback (name, description)
	EventUsage     = "usage"     // Token usage update
	EventError     = "error"     // Error during processing
	EventResult    = "result"    // Final complete response
)
View Source 
const (
	RoleUser      = "user"
	RoleAssistant = "assistant"
	RoleSystem    = "system"
	RoleThinking  = "thinking"
	RoleTool      = "tool"
)

Message role constants

View Source 
const (
	Gemini    = "gemini"
	Anthropic = "anthropic"
	Mistral   = "mistral"
)

Provider name constants

View Source 
const DefaultMaxIterations = 10

DefaultMaxIterations is the default maximum number of tool-calling iterations per chat turn.

View Source 
const (
	EmbeddingTaskTypeDefault = "DEFAULT"
)
View Source 
const ResultOK = ResultStop

ResultOK is an alias for ResultStop (normal completion).

Variables

This section is empty.

Functions

func WithAttachment 

func WithAttachment(r io.Reader) opt.Opt

WithAttachmentURL creates an attachment from data read from the provided reader The MIME type is detected from the data. This is suitable for small attachments the caller is responsible for closing the reader after the data is read.

func WithAttachmentURL 

func WithAttachmentURL(u string, mimetype string) opt.Opt

WithAttachmentURL creates an attachment from a URL and explicit MIME type

Types

type AskRequest 

type AskRequest struct {
	GeneratorMeta
	Text        string       `json:"text" arg:"" help:"User input text"`
	Attachments []Attachment `json:"attachments,omitempty" help:"File attachments" optional:""`
}

AskRequest represents a stateless request to generate content.

func (AskRequest) String 

func (r AskRequest) String() string

type AskResponse 

type AskResponse struct {
	CompletionResponse
	Usage *Usage `json:"usage,omitempty"`
}

AskResponse represents the response from an ask request.

func (AskResponse) String 

func (r AskResponse) String() string

type Attachment 

type Attachment struct {
	Type string   `json:"type"`           // MIME type: "image/png", "application/pdf", etc.
	Data []byte   `json:"data,omitempty"` // Raw binary data
	URL  *url.URL `json:"url,omitempty"`  // URL reference (http, https, gs, file, etc.)
}

Attachment represents binary or URI-referenced media (images, documents, etc.)

func (Attachment) IsText 

func (a Attachment) IsText() bool

IsText returns true if the attachment has a text/* MIME type (e.g. text/plain, text/html, text/csv). Handles MIME parameters like charset gracefully. Such attachments can be converted to text blocks when providers don't support them as media uploads.

func (Attachment) TextContent 

func (a Attachment) TextContent() string

TextContent returns the attachment's data as a string, optionally prefixed with the filename and content type for context. Only meaningful when IsText() returns true.

type ChatRequest 

type ChatRequest struct {
	Session       string       `json:"session" help:"Session ID"`
	Text          string       `json:"text" arg:"" help:"User input text"`
	Attachments   []Attachment `json:"attachments,omitempty" help:"File attachments" optional:""`
	Tools         []string     `json:"tools,omitempty" help:"Tool names to include (empty means all)" optional:""`
	MaxIterations uint         `json:"max_iterations,omitempty" help:"Maximum tool-calling iterations (0 uses default)" optional:""`
	SystemPrompt  string       `json:"system_prompt,omitempty" help:"Per-request system prompt appended to the session prompt" optional:""`
}

ChatRequest represents a stateful chat request within a session.

func (ChatRequest) String 

func (r ChatRequest) String() string

type ChatResponse 

type ChatResponse struct {
	CompletionResponse
	Session string `json:"session"`
	Usage   *Usage `json:"usage,omitempty"`
}

ChatResponse represents the response from a chat request.

func (ChatResponse) String 

func (r ChatResponse) String() string

type CompletionResponse 

type CompletionResponse struct {
	Role    string         `json:"role"`
	Content []ContentBlock `json:"content"`
	Result  ResultType     `json:"result"`
}

CompletionResponse represents a response from a completion request.

func (CompletionResponse) String 

func (r CompletionResponse) String() string

type ContentBlock 

type ContentBlock struct {
	Text       *string     `json:"text,omitempty"`        // Text content
	Thinking   *string     `json:"thinking,omitempty"`    // Thinking/reasoning content
	Attachment *Attachment `json:"attachment,omitempty"`  // Image, document, audio, etc.
	ToolCall   *ToolCall   `json:"tool_call,omitempty"`   // Tool invocation (assistant → user)
	ToolResult *ToolResult `json:"tool_result,omitempty"` // Tool response (user → assistant)
}

ContentBlock represents a single piece of content within a message. Exactly one of the fields should be non-nil/non-empty.

func NewToolError 

func NewToolError(id, name string, err error) ContentBlock

NewToolError creates a content block containing a tool error result

func NewToolResult 

func NewToolResult(id, name string, v any) ContentBlock

NewToolResult creates a content block containing a successful tool result

type Conversation 

type Conversation []*Message

Conversation is a sequence of messages exchanged with an LLM

func (*Conversation) Append 

func (s *Conversation) Append(message Message)

Append adds a message to the conversation

func (*Conversation) AppendWithOuput 

func (s *Conversation) AppendWithOuput(message Message, input, output uint)

AppendWithOutput adds a message to the conversation, attributing token counts to individual messages. The last message in the conversation (typically the just-appended user message) receives an estimated token count based on its content rather than absorbing overhead such as tool schemas and system prompts. The response message receives the actual output token count from the provider.

func (Conversation) String 

func (s Conversation) String() string

func (Conversation) Tokens 

func (s Conversation) Tokens() uint

Return the total number of tokens in the conversation

type EmbeddingRequest 

type EmbeddingRequest struct {
	Provider             string   `json:"provider,omitempty" help:"Provider name" optional:""`
	Model                string   `json:"model,omitempty" help:"Model name" optional:""`
	Input                []string `json:"input,omitempty" arg:"" help:"Text inputs to embed"`
	TaskType             string   `` /* 244-byte string literal not displayed */
	Title                string   `json:"title,omitempty" help:"Document title, used with RETRIEVAL_DOCUMENT task type (Google-specific)"`
	OutputDimensionality uint     `json:"output_dimensionality,omitempty" help:"Truncate embedding to this many dimensions (Google-specific)"`
}

EmbeddingRequest represents a request to embed text

func (EmbeddingRequest) String 

func (r EmbeddingRequest) String() string

type EmbeddingResponse 

type EmbeddingResponse struct {
	EmbeddingRequest
	Output [][]float64 `json:"output,omitempty"`
}

EmbeddingResponse represents a response from an embedding request

func (EmbeddingResponse) String 

func (r EmbeddingResponse) String() string

type GeneratorMeta 

type GeneratorMeta struct {
	Provider       string          `json:"provider,omitempty" help:"Provider name" optional:""`
	Model          string          `json:"model,omitempty" help:"Model name" optional:""`
	SystemPrompt   string          `json:"system_prompt,omitempty" help:"System prompt" optional:""`
	Format         json.RawMessage `json:"format,omitempty" help:"JSON schema for structured output" optional:""`
	Thinking       *bool           `json:"thinking,omitempty" help:"Enable thinking/reasoning" optional:""`
	ThinkingBudget uint            `json:"thinking_budget,omitempty" help:"Thinking token budget (required for Anthropic, optional for Google)" optional:""`
}

GeneratorMeta represents the metadata needed to invoke a generator model.

func (GeneratorMeta) String 

func (r GeneratorMeta) String() string

type GetModelRequest 

type GetModelRequest struct {
	Provider string `json:"provider,omitempty" help:"Filter by provider name" optional:""`
	Name     string `json:"name,omitempty" help:"Model name"`
}

GetModelRequest represents a request to get a model

func (GetModelRequest) String 

func (r GetModelRequest) String() string

type ListModelsRequest 

type ListModelsRequest struct {
	Provider string `json:"provider,omitempty" help:"Filter by provider name" optional:""`
	Limit    *uint  `json:"limit,omitempty" help:"Maximum number of models to return"`
	Offset   uint   `json:"offset,omitempty" help:"Offset for pagination"`
}

ListModelsRequest represents a request to list models

func (ListModelsRequest) String 

func (r ListModelsRequest) String() string

type ListModelsResponse 

type ListModelsResponse struct {
	Count    uint     `json:"count"`
	Offset   uint     `json:"offset,omitzero"`
	Limit    *uint    `json:"limit,omitzero"`
	Provider []string `json:"provider,omitempty"`
	Body     []Model  `json:"body,omitzero"`
}

ListModelsResponse represents a response containing a list of models and providers

func (ListModelsResponse) String 

func (r ListModelsResponse) String() string

type ListSessionRequest 

type ListSessionRequest struct {
	Limit  *uint    `json:"limit,omitempty" help:"Maximum number of sessions to return"`
	Offset uint     `json:"offset,omitempty" help:"Offset for pagination"`
	Label  []string `json:"label,omitempty" help:"Filter by labels (key:value)"`
}

ListSessionRequest represents a request to list sessions

func (ListSessionRequest) String 

func (r ListSessionRequest) String() string

type ListSessionResponse 

type ListSessionResponse struct {
	Count  uint       `json:"count"`
	Offset uint       `json:"offset,omitzero"`
	Limit  *uint      `json:"limit,omitzero"`
	Body   []*Session `json:"body,omitzero"`
}

ListSessionResponse represents a response containing a list of sessions

func (ListSessionResponse) String 

func (r ListSessionResponse) String() string

type ListToolRequest 

type ListToolRequest struct {
	Limit  *uint `json:"limit,omitempty" help:"Maximum number of tools to return"`
	Offset uint  `json:"offset,omitempty" help:"Offset for pagination"`
}

ListToolRequest represents a request to list tools

func (ListToolRequest) String 

func (r ListToolRequest) String() string

type ListToolResponse 

type ListToolResponse struct {
	Count  uint       `json:"count"`
	Offset uint       `json:"offset,omitzero"`
	Limit  *uint      `json:"limit,omitzero"`
	Body   []ToolMeta `json:"body,omitzero"`
}

ListToolResponse represents a response containing a list of tools

func (ListToolResponse) String 

func (r ListToolResponse) String() string

type Message 

type Message struct {
	Role    string         `json:"role"`             // "user", "assistant", "system"
	Content []ContentBlock `json:"content"`          // Array of content blocks
	Tokens  uint           `json:"tokens,omitempty"` // Number of tokens
	Result  ResultType     `json:"result"`           // Result type
	Meta    map[string]any `json:"meta,omitzero"`    // Provider-specific metadata
}

Message represents a message in a conversation with an LLM. It uses a universal content block representation that can be marshaled to any provider's format.

func NewMessage 

func NewMessage(role string, text string, opts ...opt.Opt) (*Message, error)

Create a new message with the given role and text content

func (Message) EstimateTokens 

func (m Message) EstimateTokens() uint

EstimateTokens returns a rough token count for the message content. It estimates ~4 characters per token for text, plus a fixed cost per non-text block (attachments, tool calls/results). This is useful for attributing per-message token costs without a provider-specific tokeniser.

func (Message) String 

func (m Message) String() string

func (Message) Text 

func (m Message) Text() string

Text returns the concatenated text content from all text blocks in the message

func (Message) ToolCalls 

func (m Message) ToolCalls() []ToolCall

ToolCalls returns all tool call blocks in the message

type Model 

type Model struct {
	Name        string                 `json:"name,omitzero"`
	Description string                 `json:"description,omitzero"`
	Created     time.Time              `json:"created,omitzero"`
	OwnedBy     string                 `json:"owned_by,omitzero"` // Model provider
	Aliases     []string               `json:"aliases,omitzero"`  // Model aliases
	Meta        map[string]interface{} `json:"meta,omitzero"`     // Provider-specific metadata
}

Represents an LLM model

func (Model) String 

func (m Model) String() string

type MultipartAskRequest 

type MultipartAskRequest struct {
	AskRequest
	File gomultipart.File `json:"file,omitempty" help:"File attachment (multipart upload)" optional:""`
}

MultipartAskRequest is the HTTP-layer request type supporting both JSON (with base64 attachments) and multipart/form-data file uploads.

func (*MultipartAskRequest) FileAttachment 

func (r *MultipartAskRequest) FileAttachment() (*Attachment, error)

FileAttachment reads the multipart file (if present) and returns it as an Attachment with auto-detected MIME type. Returns nil if no file was uploaded.

type MultipartChatRequest 

type MultipartChatRequest struct {
	ChatRequest
	File gomultipart.File `json:"file,omitempty" help:"File attachment (multipart upload)" optional:""`
}

MultipartChatRequest is the HTTP-layer request type supporting both JSON (with base64 attachments) and multipart/form-data file uploads for chat.

func (*MultipartChatRequest) FileAttachment 

func (r *MultipartChatRequest) FileAttachment() (*Attachment, error)

FileAttachment reads the multipart file (if present) and returns it as an Attachment with auto-detected MIME type. Returns nil if no file was uploaded.

type ResultType 

type ResultType uint

The result of generating a message (stopped, error, etc.) 

const (
	ResultStop          ResultType = iota // Normal completion
	ResultMaxTokens                       // Truncated due to max tokens
	ResultBlocked                         // Blocked by safety, recitation, or content filter
	ResultToolCall                        // Model requested a tool call
	ResultError                           // Generation error
	ResultOther                           // Other/unknown finish reason
	ResultMaxIterations                   // Tool-calling loop exhausted max iterations
)

func (ResultType) MarshalJSON 

func (r ResultType) MarshalJSON() ([]byte, error)

func (ResultType) String 

func (r ResultType) String() string

func (*ResultType) UnmarshalJSON 

func (r *ResultType) UnmarshalJSON(data []byte) error

type Session 

type Session struct {
	ID string `json:"id"`
	SessionMeta
	Messages Conversation `json:"messages,omitempty"`
	Overhead uint         `json:"overhead,omitempty"` // Constant token cost per turn (tools, system prompt)
	Created  time.Time    `json:"created"`
	Modified time.Time    `json:"modified"`
}

Session represents a stored conversation with an LLM.

func (*Session) Append 

func (s *Session) Append(message Message)

Append adds a message to the session and updates the modified timestamp.

func (*Session) Conversation 

func (s *Session) Conversation() *Conversation

Conversation returns a pointer to the underlying message slice, compatible with agent.WithSession.

func (*Session) String 

func (s *Session) String() string

func (*Session) Tokens 

func (s *Session) Tokens() uint

Tokens returns the total token count across all messages.

func (*Session) Validate 

func (s *Session) Validate() error

Validate returns an error if the session is missing required fields.

type SessionMeta 

type SessionMeta struct {
	GeneratorMeta
	Name   string            `json:"name,omitempty" help:"Session name" optional:""`
	Labels map[string]string `json:"labels,omitempty" help:"User-defined labels for UI storage" optional:""`
}

SessionMeta represents the metadata for a session.

func (SessionMeta) String 

func (r SessionMeta) String() string

type Store 

type Store interface {
	// Create creates a new session from the given metadata,
	// returning the session with a unique ID assigned.
	Create(ctx context.Context, meta SessionMeta) (*Session, error)

	// Get retrieves an existing session by ID.
	// Returns an error if the session does not exist.
	Get(ctx context.Context, id string) (*Session, error)

	// List returns sessions matching the request, with pagination support.
	// Returns offset, limit and total count in the response.
	List(ctx context.Context, req ListSessionRequest) (*ListSessionResponse, error)

	// Delete removes a session by ID.
	// Returns an error if the session does not exist.
	Delete(ctx context.Context, id string) error

	// Update applies non-zero fields from the given metadata to an existing session.
	// Returns the updated session or an error if the session does not exist.
	Update(ctx context.Context, id string, meta SessionMeta) (*Session, error)

	// Write persists the current state of a session.
	Write(s *Session) error
}

Store is the interface for session storage backends.

type StreamDelta 

type StreamDelta struct {
	Role string `json:"role"`
	Text string `json:"text"`
}

StreamDelta represents a single streamed text chunk in an SSE stream.

type StreamError 

type StreamError struct {
	Error string `json:"error"`
}

StreamError represents an error event in an SSE stream.

type ToolCall 

type ToolCall struct {
	ID    string          `json:"id,omitempty"`    // Provider-assigned call ID
	Name  string          `json:"name"`            // Tool function name
	Input json.RawMessage `json:"input,omitempty"` // JSON-encoded arguments
}

ToolCall represents a tool invocation requested by the model

type ToolMeta 

type ToolMeta struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Schema      json.RawMessage `json:"schema,omitempty"`
}

ToolMeta represents a tool's metadata

func (ToolMeta) String 

func (r ToolMeta) String() string

type ToolResult 

type ToolResult struct {
	ID      string          `json:"id,omitempty"`      // Matches the ToolCall ID
	Name    string          `json:"name,omitempty"`    // Tool function name
	Content json.RawMessage `json:"content,omitempty"` // JSON-encoded result
	IsError bool            `json:"is_error,omitempty"`
}

ToolResult represents the result of running a tool

type Usage 

type Usage struct {
	InputTokens  uint `json:"input_tokens,omitempty"`
	OutputTokens uint `json:"output_tokens,omitempty"`
}

Usage represents the token usage for a single request/response.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.