models

package
v1.156.0 Latest Latest
Warning

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

 Go to latest Published: Jul 10, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package models defines the shared data types used across all ChatCLI components — CLI, server, operator, and LLM providers.

Core Types

  • Message: A single conversation message with role, content, and metadata.
  • SessionData: Complete session state including chat history, agent history, and tool call scoped history.
  • ToolDefinition: Describes a tool available to the LLM (name, description, parameters as JSON Schema).
  • ToolCall: A tool invocation requested by the LLM.
  • LLMResponse: The response from an LLM provider including content, tool calls, and usage statistics.

These types form the contract between LLM providers, the CLI interface, the gRPC server, and the Kubernetes operator.

  • ChatCLI - Command Line Interface for LLM interaction
  • Copyright (c) 2024 Edilson Freitas
  • License: Apache-2.0

Index

Constants

View Source 
const (
	ConvRoleUser        = "user"         // a user message, from any channel
	ConvRoleAssistant   = "assistant"    // an assistant final reply
	ConvRoleToolSummary = "tool_summary" // compact textual summary of tool activity (not replayable)
	ConvRoleCheckpoint  = "checkpoint"   // a compaction summary standing in for older events
)

Conversation event roles for the cross-channel conversation log held by the Hub. They are intentionally distinct from Message.Role: a Hub event describes a turn in the shared dialog, not an executable LLM message.

Variables

This section is empty.

Functions

func DetectImageMediaType added in v1.143.0 

func DetectImageMediaType(data []byte) (string, bool)

DetectImageMediaType sniffs the media type from the leading bytes and reports whether it is a supported image. Used when an attachment has no declared MIME (local file read, raw paste).

func EstimateImageTokens added in v1.143.0 

func EstimateImageTokens(ic ImageContent) int

EstimateImageTokens approximates the prompt-token cost of an image.

When the bytes are present and decodable we use Anthropic's documented heuristic, tokens ≈ (width × height) / 750, after clamping the longest edge to 1568px (providers downscale larger images server-side). When we cannot decode dimensions (URL-only, or a webp we did not register a decoder for), we fall back to a coarse byte-size estimate so token accounting never silently reports zero for a real image.

func NormalizeImageMediaType added in v1.143.0 

func NormalizeImageMediaType(mime string) (string, bool)

NormalizeImageMediaType lowercases and strips any parameters (e.g. "image/jpeg; charset=binary" -> "image/jpeg") and reports whether the result is a supported image type. Also folds the common "image/jpg" alias onto the canonical "image/jpeg".

func SupportedImageMediaTypes added in v1.143.0 

func SupportedImageMediaTypes() []string

SupportedImageMediaTypes returns a copy of the accepted MIME types, for callers that surface the list to the user (errors, help text).

Types

type CacheControl added in v1.66.0 

type CacheControl struct {
	Type string `json:"type"` // "ephemeral"
}

CacheControl for Anthropic KV cache optimization.

type ContentBlock added in v1.66.0 

type ContentBlock struct {
	Type         string        `json:"type"` // "text", "tool_use", "tool_result"
	Text         string        `json:"text,omitempty"`
	CacheControl *CacheControl `json:"cache_control,omitempty"`
}

ContentBlock supports multi-part content (text + tool_use).

type ConversationEvent added in v1.123.0 

type ConversationEvent struct {
	ConvID      string    `json:"conv_id"`
	Seq         int64     `json:"seq"`                     // server-assigned, monotonic per conversation; 0 until appended
	Principal   string    `json:"principal"`               // owning principal (the identity shared across channels)
	Channel     string    `json:"channel"`                 // origin channel: "telegram", "slack", "local", ...
	Role        string    `json:"role"`                    // one of the ConvRole* constants
	Content     string    `json:"content"`                 // the dialog text (prose or tool summary)
	ClientMsgID string    `json:"client_msg_id,omitempty"` // idempotency key: a repeat append with the same id is a no-op
	Timestamp   time.Time `json:"timestamp"`
}

ConversationEvent is one entry in the append-only, cross-channel conversation log maintained by the Hub.

Unlike SessionData — a snapshot blob saved/loaded as a whole — events are appended individually with a server-assigned monotonic Seq. That lets concurrent writers (e.g. a Telegram adapter on the server and a notebook CLI) extend the same conversation without clobbering one another, and lets a reconnecting client tail from the last Seq it saw.

func (ConversationEvent) ToMessage added in v1.123.0 

func (e ConversationEvent) ToMessage() Message

ToMessage projects a conversation event onto the Message type used to build LLM history when a frontend hydrates the shared conversation.

tool_summary and checkpoint events become system context rather than tool messages: tool execution stays local to whichever frontend produced it, so the other machines receive only a portable textual summary — never a tool-call to replay.

type HubBinding added in v1.123.0 

type HubBinding struct {
	Platform  string `json:"platform"`
	UserID    string `json:"user_id"`
	Principal string `json:"principal"`
}

HubBinding maps a per-platform channel identity to a principal, as exchanged between the CLI and the hub. Shared here so neither the cli nor the remote client package needs to import the other.

type ImageContent added in v1.143.0 

type ImageContent struct {
	MediaType string `json:"media_type"`          // canonical MIME: image/png|image/jpeg|image/gif|image/webp
	Data      []byte `json:"data,omitempty"`      // raw bytes (NOT base64); adapters encode on the wire
	URL       string `json:"url,omitempty"`       // remote URL alternative to Data
	FileName  string `json:"file_name,omitempty"` // original filename, for display/persistence
}

ImageContent is a single image attached to a Message, enabling vision-capable providers to "see" it. Exactly one of Data or URL carries the bytes; provider adapters convert to whatever their wire format needs (inline base64, a URL reference, or the AWS SDK image block). Carrying images on the Message (rather than mangling Content string) keeps the text path byte-identical for every provider that does not opt in to vision.

func (ImageContent) IsValid added in v1.143.0 

func (ic ImageContent) IsValid() bool

IsValid reports whether the image carries usable bytes (Data or URL) and a supported media type.

type LLMResponse added in v1.66.0 

type LLMResponse struct {
	Content    string     `json:"content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	Usage      *UsageInfo `json:"usage,omitempty"`
	StopReason string     `json:"stop_reason,omitempty"`
}

LLMResponse is the structured response from tool-aware providers.

func (*LLMResponse) HasToolCalls added in v1.66.0 

func (r *LLMResponse) HasToolCalls() bool

HasToolCalls returns true if the response contains tool calls.

type Message 

type Message struct {
	Role        string         `json:"role"`                   // O papel da mensagem: "user", "assistant", "system", "tool".
	Content     string         `json:"content"`                // O conteúdo da mensagem.
	Meta        *MessageMeta   `json:"meta,omitempty"`         // Optional metadata for history compaction.
	ToolCalls   []ToolCall     `json:"tool_calls,omitempty"`   // Tool calls from assistant (native API).
	ToolCallID  string         `json:"tool_call_id,omitempty"` // ID when this message is a tool result.
	SystemParts []ContentBlock `json:"system_parts,omitempty"` // Structured system prompt parts (for cache control).

	// Images carries vision input attached to this turn. Populated for
	// user messages (an attached/pasted/forwarded image) and consumed by
	// vision-capable provider adapters, which serialize each entry into
	// their native image block. Providers without vision ignore it (the
	// gateway/CLI may instead route through the describe-fallback). The
	// text in Content still applies — an image usually rides with a caption.
	Images []ImageContent `json:"images,omitempty"`

	// IsError marks this tool-result message as a business-level
	// failure (the tool ran, but reported an error: command exit code,
	// HTTP 4xx, missing file). Provider adapters use it to set the
	// native is_error wire field (Anthropic) or prefix the content
	// with a marker the model can read (OpenAI-family).
	//
	// Only meaningful when Role == "tool". Default false (success).
	IsError bool `json:"is_error,omitempty"`

	// ErrorCode is the stable, locale-independent classification of
	// the failure (ENOENT, EACCES, Timeout, ExitCode:2, NetworkError,
	// etc). Surfaced to the LLM so it can reason about retryability
	// without parsing English. Empty when IsError is false; carried
	// inside the content marker for providers without native support.
	ErrorCode string `json:"error_code,omitempty"`
}

Message representa uma mensagem trocada com o modelo de linguagem.

func NewToolResultMessage added in v1.118.0 

func NewToolResultMessage(toolCallID, content string, isError bool, errorCode string) Message

NewToolResultMessage builds a properly-shaped tool-result message from the agent layer. Centralizing the construction here keeps every caller in lock-step: ToolCallID always set, role always "tool", IsError/ErrorCode coherent with whatever the executor reported.

func (*Message) IsValid 

func (m *Message) IsValid() bool

IsValid valida se a mensagem tem um papel e conteúdo válidos.

type MessageMeta added in v1.65.2 

type MessageMeta struct {
	IsSummary bool   `json:"is_summary,omitempty"` // true if this message is a compacted summary
	SummaryOf int    `json:"summary_of,omitempty"` // how many original messages were summarized
	Mode      string `json:"mode,omitempty"`       // "chat", "agent", "coder" — which mode produced this message

	// PreserveVerbatim marks a message whose content must never be reduced
	// during history compaction. Set, for example, on tool feedback that
	// carries @recall output: the model explicitly asked to see that original
	// in full, so re-trimming it would discard the detail and force another
	// recall. A structural flag avoids coupling the trimmer to any content
	// format. See cli.MessageTrimmer.trimMessage.
	PreserveVerbatim bool `json:"preserve_verbatim,omitempty"`
}

MessageMeta carries non-content metadata for history management.

type ResponseData 

type ResponseData struct {
	Status   string `json:"status"`   // O status da resposta: "processing", "completed", ou "error".
	Response string `json:"response"` // A resposta da LLM, se o status for "completed".
	Message  string `json:"message"`  // Mensagem de erro, se o status for "error".
}

ResponseData representa os dados de resposta da LLM.

func (*ResponseData) IsValid 

func (r *ResponseData) IsValid() bool

IsValid valida se o status da resposta é um dos valores esperados.

type SessionData added in v1.65.2 

type SessionData struct {
	Version      int       `json:"version"` // 2 for the new format
	ChatHistory  []Message `json:"chat_history"`
	AgentHistory []Message `json:"agent_history,omitempty"`
	CoderHistory []Message `json:"coder_history,omitempty"`
	SharedMemory []Message `json:"shared_memory,omitempty"`
}

SessionData is the v2 session format that supports scoped histories. It is backward-compatible with the legacy format (plain []Message).

type ToolCall added in v1.66.0 

type ToolCall struct {
	ID        string                 `json:"id"`
	Type      string                 `json:"type"` // "function"
	Name      string                 `json:"name"`
	Arguments map[string]interface{} `json:"arguments"`
	Raw       string                 `json:"raw,omitempty"` // Original text if parsed from XML
}

ToolCall represents a tool invocation from the LLM response.

func (ToolCall) ArgumentsJSON added in v1.66.0 

func (tc ToolCall) ArgumentsJSON() string

ArgumentsJSON returns the arguments as a JSON string.

type ToolDefinition added in v1.66.0 

type ToolDefinition struct {
	Type     string          `json:"type"` // "function"
	Function ToolFunctionDef `json:"function"`
}

ToolDefinition describes a tool the LLM can call via native API.

type ToolFunctionDef added in v1.66.0 

type ToolFunctionDef struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description"`
	Parameters  map[string]interface{} `json:"parameters"`
}

ToolFunctionDef is the function schema within a tool definition.

type ToolResult added in v1.66.0 

type ToolResult struct {
	ToolCallID string `json:"tool_call_id"`
	Content    string `json:"content"`
	IsError    bool   `json:"is_error,omitempty"`
}

ToolResult is sent back after executing a tool.

type UsageInfo added in v1.49.0 

type UsageInfo struct {
	// Core token counts (reported by all providers)
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`

	// Anthropic prompt caching (reduces cost for repeated prefixes).
	// OpenAI cached prompt tokens are also reported here under
	// CacheReadInputTokens — semantically the same thing (repeated input
	// served at a discount). CacheCreationInputTokens stays Anthropic-only.
	CacheCreationInputTokens int `json:"cache_creation_input_tokens,omitempty"`
	CacheReadInputTokens     int `json:"cache_read_input_tokens,omitempty"`

	// Reasoning tokens emitted by o-series / GPT-5 reasoning models.
	// Reported by OpenAI under usage.completion_tokens_details.reasoning_tokens
	// (Chat Completions) or usage.output_tokens_details.reasoning_tokens
	// (Responses API). Billed as output tokens and already counted in
	// CompletionTokens — this field is informational only.
	ReasoningTokens int `json:"reasoning_tokens,omitempty"`

	// Whether these values came from the API (true) or were estimated (false).
	// Callers can use this to decide display precision and cost accuracy.
	IsReal bool `json:"-"`
}

UsageInfo represents token usage information returned by LLM APIs. All fields are optional — providers populate what they report.

func EstimateFromChars added in v1.99.0 

func EstimateFromChars(inputChars, outputChars int) *UsageInfo

EstimateFromChars creates a UsageInfo estimated from character counts. Uses 4 chars per token heuristic. Marked as IsReal=false.

func (*UsageInfo) Merge added in v1.99.0 

func (u *UsageInfo) Merge(other *UsageInfo)

Merge adds the token counts from other into this UsageInfo. Useful for aggregating usage across multiple API calls in a session.

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.