Documentation
¶
Index ¶
- Constants
- func WithAttachment(r io.Reader) opt.Opt
- func WithAttachmentURL(u string, mimetype string) opt.Opt
- type Agent
- type AgentMeta
- type AgentStore
- type AgentTable
- type AskRequest
- type AskResponse
- type Attachment
- type ChatRequest
- type ChatResponse
- type CompletionResponse
- type ContentBlock
- type Conversation
- type CreateAgentSessionRequest
- type CreateAgentSessionResponse
- type EmbeddingRequest
- type EmbeddingResponse
- type GeneratorMeta
- type GetModelRequest
- type JSONSchema
- type ListAgentRequest
- type ListAgentResponse
- type ListModelsRequest
- type ListModelsResponse
- type ListSessionRequest
- type ListSessionResponse
- type ListToolRequest
- type ListToolResponse
- type Message
- type Model
- type ModelTable
- type MultipartAskRequest
- type MultipartChatRequest
- type ProviderTable
- type ResultType
- type Session
- type SessionMeta
- type SessionStore
- type SessionTable
- type StreamDelta
- type StreamError
- type ToolCall
- type ToolMeta
- type ToolResult
- type ToolTable
- type Usage
Constants ¶
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 )
const ( RoleUser = "user" RoleAssistant = "assistant" RoleSystem = "system" RoleThinking = "thinking" RoleTool = "tool" )
Message role constants
const ( Gemini = "gemini" Anthropic = "anthropic" Mistral = "mistral" Eliza = "eliza" )
Provider name constants
const DefaultMaxIterations = 10
DefaultMaxIterations is the default maximum number of tool-calling iterations per chat turn.
const (
EmbeddingTaskTypeDefault = "DEFAULT"
)
const ResultOK = ResultStop
ResultOK is an alias for ResultStop (normal completion).
Variables ¶
This section is empty.
Functions ¶
func WithAttachment ¶
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.
Types ¶
type Agent ¶ added in v0.3.0
type Agent struct {
ID string `json:"id"`
Created time.Time `json:"created"`
Version uint `json:"version"`
AgentMeta
}
Agent is a versioned, stored agent definition.
type AgentMeta ¶ added in v0.3.0
type AgentMeta struct {
GeneratorMeta `yaml:",inline"`
Name string `json:"name" yaml:"name" help:"Unique agent name"`
Title string `json:"title,omitempty" yaml:"title" help:"Human-readable title" optional:""`
Description string `json:"description,omitempty" yaml:"description" help:"Agent description" optional:""`
Template string `json:"template,omitempty" yaml:"-" help:"Go template for the user message" optional:""`
Input JSONSchema `json:"input,omitempty" yaml:"input" help:"JSON schema for agent input" optional:""`
Tools []string `json:"tools,omitempty" yaml:"tools" help:"Tool names the agent is allowed to use" optional:""`
}
AgentMeta describes the definition of an agent, including which model and provider to use and the schemas that govern its input and output.
type AgentStore ¶ added in v0.3.0
type AgentStore interface {
// CreateAgent creates a new agent from the given metadata,
// returning the agent with a unique ID and version 1.
CreateAgent(ctx context.Context, meta AgentMeta) (*Agent, error)
// GetAgent retrieves an existing agent by ID or name.
// Returns an error if the agent does not exist.
GetAgent(ctx context.Context, id string) (*Agent, error)
// ListAgents returns agents matching the request, with pagination support.
// Returns offset, limit and total count in the response.
ListAgents(ctx context.Context, req ListAgentRequest) (*ListAgentResponse, error)
// DeleteAgent removes an agent by ID or name. When a name is provided,
// all versions of the agent are deleted. Returns an error if no matching
// agent exists.
DeleteAgent(ctx context.Context, id string) error
// UpdateAgent applies non-zero fields from the given metadata to an existing
// agent and increments the version. Returns the updated agent.
UpdateAgent(ctx context.Context, id string, meta AgentMeta) (*Agent, error)
}
AgentStore is the interface for agent storage backends.
type AgentTable ¶ added in v0.3.0
type AgentTable []*Agent
AgentTable implements table.TableData for a list of agents.
func (AgentTable) Header ¶ added in v0.3.0
func (t AgentTable) Header() []string
func (AgentTable) Len ¶ added in v0.3.0
func (t AgentTable) Len() int
func (AgentTable) Row ¶ added in v0.3.0
func (t AgentTable) Row(i int) []any
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 CreateAgentSessionRequest ¶ added in v0.3.0
type CreateAgentSessionRequest struct {
Parent string `json:"parent,omitempty" help:"Parent session ID for traceability" optional:""`
Input json.RawMessage `json:"input,omitempty" help:"Input data for the agent template" optional:""`
}
CreateAgentSessionRequest represents the body of a request to create a session from an agent definition. The agent is identified by path/query parameters (agent ID or name, optional version) — not included here. The agent's template is executed with Input, and a new session is created with the merged GeneratorMeta and agent labels. If Parent is set, the parent session's GeneratorMeta is used as defaults (agent fields take precedence). The caller can then use the returned text and tools with the Chat endpoint.
func (CreateAgentSessionRequest) String ¶ added in v0.3.0
func (r CreateAgentSessionRequest) String() string
type CreateAgentSessionResponse ¶ added in v0.3.0
type CreateAgentSessionResponse struct {
Session string `json:"session"` // Created session ID
Text string `json:"text"` // Rendered template text (first user message)
Tools []string `json:"tools,omitempty"` // Tool names the agent is allowed to use
}
CreateAgentSessionResponse is the result of creating a session from an agent. It contains the session ID plus the prepared text and tools, which can be passed directly to a ChatRequest.
func (CreateAgentSessionResponse) String ¶ added in v0.3.0
func (r CreateAgentSessionResponse) String() string
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" yaml:"provider" help:"Provider name" optional:""`
Model string `json:"model,omitempty" yaml:"model" help:"Model name" optional:""`
SystemPrompt string `json:"system_prompt,omitempty" yaml:"system_prompt" help:"System prompt" optional:""`
Format JSONSchema `json:"format,omitempty" yaml:"format" help:"JSON schema for structured output" optional:""`
Thinking *bool `json:"thinking,omitempty" yaml:"thinking" help:"Enable thinking/reasoning" optional:""`
ThinkingBudget uint `` /* 142-byte string literal not displayed */
}
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 JSONSchema ¶ added in v0.3.0
type JSONSchema json.RawMessage
JSONSchema is a JSON-encoded schema that supports unmarshalling from both JSON and YAML sources. When unmarshalling from YAML, the YAML node is first decoded to a native Go value and then marshalled to JSON bytes.
func NewJSONSchema ¶ added in v0.3.0
func NewJSONSchema(data json.RawMessage) JSONSchema
NewJSONSchema creates a JSONSchema from raw JSON bytes.
func (JSONSchema) Bytes ¶ added in v0.3.0
func (s JSONSchema) Bytes() []byte
Bytes returns the underlying JSON bytes.
func (JSONSchema) MarshalJSON ¶ added in v0.3.0
func (s JSONSchema) MarshalJSON() ([]byte, error)
func (*JSONSchema) UnmarshalJSON ¶ added in v0.3.0
func (s *JSONSchema) UnmarshalJSON(data []byte) error
func (*JSONSchema) UnmarshalYAML ¶ added in v0.3.0
func (s *JSONSchema) UnmarshalYAML(node *yaml.Node) error
type ListAgentRequest ¶ added in v0.3.0
type ListAgentRequest struct {
Name string `json:"name,omitempty" help:"Filter by agent name" optional:""`
Version *uint `json:"version,omitempty" help:"Filter by version number (requires name)" optional:""`
Limit *uint `json:"limit,omitempty" help:"Maximum number of agents to return"`
Offset uint `json:"offset,omitempty" help:"Offset for pagination"`
}
ListAgentRequest represents a request to list agents
func (ListAgentRequest) String ¶ added in v0.3.0
func (r ListAgentRequest) String() string
type ListAgentResponse ¶ added in v0.3.0
type ListAgentResponse struct {
Count uint `json:"count"`
Offset uint `json:"offset,omitzero"`
Limit *uint `json:"limit,omitzero"`
Body []*Agent `json:"body,omitzero"`
}
ListAgentResponse represents a response containing a list of agents
func (ListAgentResponse) String ¶ added in v0.3.0
func (r ListAgentResponse) 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 ¶
Create a new message with the given role and text content
func (Message) EstimateTokens ¶
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.
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
type ModelTable ¶ added in v0.3.0
ModelTable implements table.TableData for a list of models.
func (ModelTable) Header ¶ added in v0.3.0
func (t ModelTable) Header() []string
func (ModelTable) Len ¶ added in v0.3.0
func (t ModelTable) Len() int
func (ModelTable) Row ¶ added in v0.3.0
func (t ModelTable) Row(i int) []any
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 ProviderTable ¶ added in v0.3.0
type ProviderTable []string
ProviderTable implements table.TableData for a list of provider names.
func (ProviderTable) Header ¶ added in v0.3.0
func (t ProviderTable) Header() []string
func (ProviderTable) Len ¶ added in v0.3.0
func (t ProviderTable) Len() int
func (ProviderTable) Row ¶ added in v0.3.0
func (t ProviderTable) Row(i int) []any
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) Conversation ¶
func (s *Session) Conversation() *Conversation
Conversation returns a pointer to the underlying message slice, compatible with generator.WithSession.
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 SessionStore ¶ added in v0.3.0
type SessionStore interface {
// CreateSession creates a new session from the given metadata,
// returning the session with a unique ID assigned.
CreateSession(ctx context.Context, meta SessionMeta) (*Session, error)
// GetSession retrieves an existing session by ID.
// Returns an error if the session does not exist.
GetSession(ctx context.Context, id string) (*Session, error)
// ListSessions returns sessions matching the request, with pagination support.
// Returns offset, limit and total count in the response.
ListSessions(ctx context.Context, req ListSessionRequest) (*ListSessionResponse, error)
// DeleteSession removes a session by ID.
// Returns an error if the session does not exist.
DeleteSession(ctx context.Context, id string) error
// UpdateSession 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.
UpdateSession(ctx context.Context, id string, meta SessionMeta) (*Session, error)
// WriteSession persists the current state of a session.
WriteSession(s *Session) error
}
SessionStore is the interface for session storage backends.
type SessionTable ¶ added in v0.3.0
SessionTable implements table.TableData for a list of sessions.
func (SessionTable) Header ¶ added in v0.3.0
func (t SessionTable) Header() []string
func (SessionTable) Len ¶ added in v0.3.0
func (t SessionTable) Len() int
func (SessionTable) Row ¶ added in v0.3.0
func (t SessionTable) Row(i int) []any
type StreamDelta ¶
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
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