api

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExtractText 

func ExtractText(parts []ContentPart) string

ExtractText returns the concatenated text of all text-type parts.

func ExtractThinking 

func ExtractThinking(parts []ContentPart) string

ExtractThinking returns the concatenated text of all thinking-type parts.

Types

type Agent 

type Agent struct {
	Name         string
	SystemPrompt string
	Toolbox      []ToolSpec
}

Agent represents a configured agent with its properties.

func (*Agent) HasFileSystemTool added in v0.7.0 

func (a *Agent) HasFileSystemTool() bool

HasFileSystemTool returns true if the agent's toolbox includes at least one filesystem tool (Read, Write, Edit, Grep, or Glob).

func (*Agent) HasTool added in v0.7.0 

func (a *Agent) HasTool(name string) bool

HasTool returns true if the agent's toolbox includes a tool with the given name.

type ChatCompletionProvider 

type ChatCompletionProvider interface {
	// CreateChatCompletion generates a chat completion response to the
	// provided messages.
	CreateChatCompletion(
		ctx context.Context,
		params RequestParameters,
		messages []Message,
	) (*Message, error)

	// CreateChatCompletionStream streams the response via the output callback.
	CreateChatCompletionStream(
		ctx context.Context,
		params RequestParameters,
		messages []Message,
		output func(Chunk),
	) (*Message, error)
}

ChatCompletionProvider is the interface for LLM chat completion backends.

type Chunk 

type Chunk struct {
	Kind       ChunkKind
	Text       string
	TokenCount uint
}

Chunk represents a streaming token or content fragment from a LLM response.

type ChunkKind added in v0.6.2 

type ChunkKind int

ChunkKind identifies the variant of a streaming response chunk. 

const (
	ChunkContent  ChunkKind = iota // text content
	ChunkThinking                  // reasoning / thinking
	ChunkToolUse                   // tool call partial JSON
)

type ContentPart 

type ContentPart struct {
	Type     ContentPartType `json:"type"`
	Text     string          `json:"text,omitempty"`     // text and thinking parts
	MIMEType string          `json:"mimeType,omitempty"` // image parts (e.g. "image/png")
	Data     []byte          `json:"data,omitempty"`     // raw bytes - base64 encoded when serialized
}

ContentPart represents a single part of a message's content. Messages are composed of one or more content parts — text, thinking (reasoning), or image data. This mirrors the multi-part content model used by Anthropic and OpenAI APIs.

func BuildContentParts 

func BuildContentParts(content, reasoning string) []ContentPart

BuildContentParts builds a Parts slice from legacy Content and ReasoningContent strings.

func NewImagePart 

func NewImagePart(mimeType string, data []byte) ContentPart

NewImagePart returns an image content part with the given MIME type and raw image bytes.

func NewTextPart 

func NewTextPart(text string) ContentPart

NewTextPart returns a text content part.

func NewThinkingPart 

func NewThinkingPart(text string) ContentPart

NewThinkingPart returns a thinking/reasoning content part.

type ContentPartType 

type ContentPartType string

ContentPartType identifies the kind of a single content part within a message. 

const (
	ContentPartText     ContentPartType = "text"
	ContentPartThinking ContentPartType = "thinking"
	ContentPartImage    ContentPartType = "image"
)

type Event 

type Event struct {
	Type    EventType
	Chunk   Chunk    // EventChunk
	Message *Message // EventResponseComplete
	Error   error    // EventError
}

Event represents a single event emitted during a completion step. Only the fields relevant to the EventType are populated; the rest are zero-valued. Message is a pointer so that chunk events (the most frequent) carry no weight from it.

type EventType 

type EventType int

EventType identifies the kind of event emitted during a completion step. 

const (
	EventChunk            EventType = iota // Streaming chunk received
	EventResponseComplete                  // Full response message (may contain tool calls)
	EventError                             // An error occurred
)

type Items 

type Items struct {
	Type string `json:"type"` // e.g. "string"
}

Items describes the element type for array tool parameters.

type Message 

type Message struct {
	Role        MessageRole
	Parts       []ContentPart
	ToolCalls   []ToolCall
	ToolResults []ToolResult
	Metadata    MessageMeta
}

func NewMessageWithAssistant 

func NewMessageWithAssistant(content string, reasoning string) *Message

func NewMessageWithToolCalls 

func NewMessageWithToolCalls(content string, toolCalls []ToolCall) *Message

func (*Message) HasContent added in v0.7.0 

func (m *Message) HasContent() bool

func (*Message) TextContent 

func (m *Message) TextContent() string

TextContent returns the concatenated text of all text-type parts.

func (*Message) ThinkingContent 

func (m *Message) ThinkingContent() string

ThinkingContent returns the concatenated text of all thinking-type parts.

type MessageBuilder 

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

MessageBuilder accumulates streaming content for a message The accumulated content is presented as []ContentPart via Parts().

func NewMessageBuilder 

func NewMessageBuilder(role MessageRole) *MessageBuilder

NewMessageBuilder creates a builder for a message with the given role.

func (*MessageBuilder) AppendContent 

func (b *MessageBuilder) AppendContent(chunk string)

AppendContent appends a streaming text chunk.

func (*MessageBuilder) AppendReasoning 

func (b *MessageBuilder) AppendReasoning(chunk string)

AppendReasoning appends a streaming reasoning/thinking chunk.

func (*MessageBuilder) Build 

func (b *MessageBuilder) Build() *Message

Build finalizes the builder into a Message.

func (*MessageBuilder) InitFromParts 

func (b *MessageBuilder) InitFromParts(parts []ContentPart)

InitFromParts seeds the builder with existing content parts. Used when continuing to stream into an existing assistant message (prefill).

func (*MessageBuilder) Parts 

func (b *MessageBuilder) Parts() []ContentPart

Parts returns the accumulated content as a parts slice. The slice is constructed fresh on each call (from the internal string builders), so callers can use it directly without copying.

func (*MessageBuilder) Reset 

func (b *MessageBuilder) Reset()

Reset clears the builder for reuse.

type MessageMeta 

type MessageMeta struct {
	GenerationProvider *string         `json:"generation_provider,omitempty"`
	GenerationModel    *string         `json:"generation_model,omitempty"`
	TimeToFirstToken   *time.Duration  `json:"time_to_first_token,omitempty"`
	TotalDuration      *time.Duration  `json:"total_duration,omitempty"`
	Tokens             int             `json:"completion_tokens,omitzero"`
	ThinkingSignature  *string         `json:"thinking_signature,omitempty"`
	ReasoningDetails   json.RawMessage `json:"reasoning_details,omitempty"` // preserved reasoning_detail blocks (OpenRouter)
}

MessageMeta contains metadata about a message's generation.

func (*MessageMeta) Scan 

func (m *MessageMeta) Scan(value any) error

Scan implements sql.Scanner for MessageMeta.

func (MessageMeta) Value 

func (m MessageMeta) Value() (driver.Value, error)

Value implements driver.Valuer for MessageMeta.

type MessageRole 

type MessageRole string
const (
	MessageRoleSystem     MessageRole = "system"
	MessageRoleUser       MessageRole = "user"
	MessageRoleAssistant  MessageRole = "assistant"
	MessageRoleToolCall   MessageRole = "tool_call"
	MessageRoleToolResult MessageRole = "tool_result"
)

func (MessageRole) FriendlyRole 

func (m MessageRole) FriendlyRole() string

FriendlyRole returns a human friendly signifier for the message's role.

func (MessageRole) IsAssistant 

func (m MessageRole) IsAssistant() bool

func (MessageRole) IsSystem 

func (m MessageRole) IsSystem() bool

func (MessageRole) IsUser 

func (m MessageRole) IsUser() bool

type Model 

type Model struct {
	Name        string
	Provider    *Provider
	MaxTokens   *int
	Temperature *float32
}

Model represents a resolved model ready for making completion requests. It references its Provider for the client connection.

type PermissionMode added in v0.7.0 

type PermissionMode int

PermissionMode controls which tools are allowed to run without user confirmation. 

const (
	PermNone  PermissionMode = 0 // prompt for every tool call
	PermRead  PermissionMode = 1 // auto-approve read tools (r--)
	PermWrite PermissionMode = 2 // auto-approve read + write tools (rw-)
	PermExec  PermissionMode = 3 // auto-approve all tools (rwx)
)

func ParsePermissionMode added in v0.7.0 

func ParsePermissionMode(s string) (PermissionMode, error)

ParsePermissionMode parses a permission mode string ("none", "r", "w", "x").

func (PermissionMode) String added in v0.7.0 

func (m PermissionMode) String() string

String returns the short rwx string for a permission mode.

type Provider 

type Provider struct {
	Name    string
	Display string
	Client  ChatCompletionProvider
	Models  []Model
}

Provider holds a fully initialized provider backend with its resolved models.

type ReasoningEffort 

type ReasoningEffort string

ReasoningEffort controls how much reasoning the model should perform. 

const (
	XHigh   ReasoningEffort = "xhigh"
	High    ReasoningEffort = "high"
	Medium  ReasoningEffort = "medium"
	Low     ReasoningEffort = "low"
	Minimal ReasoningEffort = "minimal"
	None    ReasoningEffort = "none"
)

type RequestParameters 

type RequestParameters struct {
	Model       *Model
	Agent       *Agent
	Effort      ReasoningEffort
	Temperature float32
	MaxTokens   int
}

RequestParameters contains everything needed for a single completion request.

func NewRequestParameters 

func NewRequestParameters(model *Model, agent *Agent, effort ReasoningEffort, temperature float32, maxTokens int) RequestParameters

NewRequestParameters builds RequestParameters for a completion request.

type TokenCounter added in v0.7.0 

type TokenCounter interface {
	// CountTokens counts the input tokens for the given messages and
	// configuration, without generating a completion.
	CountTokens(ctx context.Context, params RequestParameters, messages []Message) (int, error)
}

TokenCounter is an interface to provide token counting for prompts.

type ToolCall 

type ToolCall struct {
	ID         string         `json:"id"`
	Name       string         `json:"name"`
	Parameters map[string]any `json:"parameters"`
}

type ToolConfirmation 

type ToolConfirmation struct {
	Approved bool
	Reason   string
}

ToolConfirmation represents the user's decision for a single tool call. Approved must be set for every tool call (the slice length must match). When Approved is false, Reason is optionally included in the rejection message sent back to the model, giving the user a way to steer the agent.

type ToolEnvelope added in v0.7.0 

type ToolEnvelope struct {
	Tool ToolInfo       `json:"tool"`
	Call map[string]any `json:"call"`
}

ToolEnvelope is the JSON structure sent on stdin to every out-of-process tool invocation (both built-in via lmcli tool and custom executables).

type ToolImpl added in v0.7.0 

type ToolImpl func(ctx context.Context, tool *ToolSpec, args map[string]any) (string, error)

ToolImpl is the signature for a tool's in-process implementation. ctx provides cancellation; tool is the spec for the tool being called; args are the parsed tool call parameters.

type ToolInfo added in v0.7.0 

type ToolInfo struct {
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	Config      map[string]any    `json:"config,omitempty"`
	Environment map[string]string `json:"environment,omitempty"`
}

ToolInfo describes the static tool definition part of the envelope.

type ToolParameter 

type ToolParameter struct {
	Name        string   `json:"name" yaml:"name"`
	Type        string   `json:"type" yaml:"type"` // "string", "integer", "boolean", "array"
	Required    bool     `json:"required" yaml:"required"`
	Description string   `json:"description" yaml:"description"`
	Enum        []string `json:"enum,omitempty" yaml:"enum"`
	Items       *Items   `json:"items,omitempty" yaml:"items"` // for array types
}

type ToolPermission 

type ToolPermission string

ToolPermission classifies the kind of access a tool performs. 

const (
	ToolPermRead  ToolPermission = "read"  // read-only (Read, Grep, Glob)
	ToolPermWrite ToolPermission = "write" // write (Write, Edit)
	ToolPermExec  ToolPermission = "exec"  // execute (Bash)
)

func ParseToolPermission added in v0.7.0 

func ParseToolPermission(s string) ToolPermission

ParseToolPermission parses a permission string into a ToolPermission. Accepts "read", "write", "exec". Defaults to ToolPermExec on invalid input.

type ToolPermissionCheck added in v0.7.0 

type ToolPermissionCheck struct {
	ToolCall     ToolCall
	NeedsConfirm bool
}

ToolPermissionCheck records whether a specific tool call needs user confirmation under the caller's permission mode.

func CheckToolPermissions added in v0.7.0 

func CheckToolPermissions(toolCalls []ToolCall, toolbox []ToolSpec, mode PermissionMode) []ToolPermissionCheck

CheckToolPermissions evaluates each tool call against the permission mode and returns a per-tool status slice. When toolbox is nil or empty, unknown tool calls are treated as requiring confirmation.

type ToolResult 

type ToolResult struct {
	ToolCallID string `json:"toolCallID"`
	ToolName   string `json:"toolName,omitempty"`
	Result     string `json:"result,omitempty"`
}

type ToolSpec 

type ToolSpec struct {
	Name        string
	Description string
	Permission  ToolPermission
	Parameters  []ToolParameter
	InProcess   bool // execute Impl directly instead of shelling out
	Config      any  // tool-specific configuration from lmcli config
	Impl        ToolImpl
	ExecPath    string   // custom executable path; empty for built-in tools
	Environment []string // env vars for out-of-process execution ("KEY=val")
}

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.