models

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.

Index

• type CacheControl
• type ContentBlock
• type LLMResponse
  • func (r *LLMResponse) HasToolCalls() bool
• type Message
  • func (m *Message) IsValid() bool
• type MessageMeta
• type ResponseData
  • func (r *ResponseData) IsValid() bool
• type SessionData
• type ToolCall
  • func (tc ToolCall) ArgumentsJSON() string
• type ToolDefinition
• type ToolFunctionDef
• type ToolResult
• type UsageInfo

Types

type CacheControl

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

CacheControl for Anthropic KV cache optimization.

type ContentBlock

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 LLMResponse

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

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).
}

Message representa uma mensagem trocada com o modelo de linguagem.

func (*Message) IsValid

func (m *Message) IsValid() bool

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

type MessageMeta

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
}

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

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

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

func (tc ToolCall) ArgumentsJSON() string

ArgumentsJSON returns the arguments as a JSON string.

type ToolDefinition

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

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

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

type UsageInfo struct {
	PromptTokens     int // Tokens usados no prompt
	CompletionTokens int // Tokens usados na resposta
	TotalTokens      int // Total de tokens usados
}

UsageInfo representa informações de uso de tokens retornadas pelas APIs