Documentation
¶
Overview ¶
Package llm provides LLM client capabilities.
Package llm provides LLM agent capabilities.
Package llm provides internal components for LLM provider management.
Index ¶
- Constants
- func FetchModels(ctx context.Context, baseURL, apiKey string) ([]string, error)
- func RunAgentLoop(ctx context.Context, cfg AgentConfig) <-chan AgentEvent
- func ValidateBaseURL(baseURL string) error
- type AgentConfig
- type AgentEvent
- type AgentEventType
- type AgentMessage
- type ColumnInfo
- type DebugLogger
- type Message
- type Registry
- type ResolvedConfig
- type SchemaContext
- type SchemaObject
- type ToolCall
- type ToolDef
- type ToolExecutor
- type ToolResult
Constants ¶
const ( // DefaultMaxTurns is how many LLM calls one agent loop may make before it // gives up. Reaching it is an error, never a silent partial answer. DefaultMaxTurns = 6 // DefaultMaxConversationBytes caps the conversation the loop keeps in memory // and resends on every turn. A single tool result can be arbitrarily large, // so without a cap the context grows by that much per turn. DefaultMaxConversationBytes = 4 << 20 )
Variables ¶
This section is empty.
Functions ¶
func FetchModels ¶
FetchModels calls the provider's /v1/models endpoint and returns the list of model IDs. apiKey may be empty for providers that don't require authentication for model listing.
func RunAgentLoop ¶
func RunAgentLoop(ctx context.Context, cfg AgentConfig) <-chan AgentEvent
RunAgentLoop runs the agent loop: LLM ↔ tool calls until completion. It emits events to the channel and closes it when done.
func ValidateBaseURL ¶
ValidateBaseURL checks that a provider base URL is an absolute http(s) URL with a host. Without it an empty value built a relative path and a non-HTTP scheme was handed to the HTTP client, both surfacing as confusing transport errors instead of a rejected input.
Types ¶
type AgentConfig ¶
type AgentConfig struct {
// Provider configuration for LLM calls.
Provider ResolvedConfig
// SystemPrompt is prepended to the conversation.
SystemPrompt string
// UserPrompt is the initial user message.
UserPrompt string
// Tools available to the LLM.
Tools []ToolDef
// Executor runs tool calls.
Executor ToolExecutor
// MaxTurns limits the number of LLM calls (default DefaultMaxTurns).
MaxTurns int
// MaxConversationBytes limits the conversation kept in memory (default
// DefaultMaxConversationBytes).
MaxConversationBytes int
// DebugLogger, when set, logs every LLM request/response.
DebugLogger DebugLogger
}
AgentConfig configures a single run of the agent loop.
type AgentEvent ¶
type AgentEvent struct {
// Type identifies the event kind.
Type AgentEventType
// Content is a text delta from the LLM stream.
Content string
// ToolCall contains info about a tool being executed (tool_start / tool_end).
ToolCall *ToolCall
// ToolResult is the result of a completed tool call (tool_end).
ToolResult string
// ToolError is set when a tool execution fails.
ToolError string
// Error is a fatal error that stopped the loop.
Error error
// Turn is the current turn number (1-based).
Turn int
}
AgentEvent is emitted by the agent loop to report progress.
type AgentEventType ¶
type AgentEventType string
AgentEventType identifies the kind of agent event.
const ( AgentEventTurnStart AgentEventType = "turn_start" AgentEventContent AgentEventType = "content" AgentEventToolStart AgentEventType = "tool_start" AgentEventToolEnd AgentEventType = "tool_end" AgentEventAgentEnd AgentEventType = "agent_end" AgentEventError AgentEventType = "error" )
type AgentMessage ¶
type AgentMessage struct {
Role string // "system" | "user" | "assistant" | "toolResult"
Content string // text content (for user/assistant/toolResult)
ToolCalls []ToolCall // for assistant role
ToolCallID string // for toolResult role
ToolName string // for toolResult role
}
AgentMessage is the internal message type used throughout the agent loop. It is richer than the raw LLM Message and is converted to Message at the LLM boundary.
type ColumnInfo ¶
ColumnInfo describes a column.
type DebugLogger ¶
DebugLogger receives full request/response bodies for debugging.
func NewDBDebugLogger ¶
func NewDBDebugLogger(st *store.Store, provider, model string) DebugLogger
NewDBDebugLogger returns a DebugLogger that persists request/response to the llm_debug_log table. Only call this when runtime debug is enabled. Writes are handed to a bounded worker pool; when the queue is full the entry is dropped with a warning rather than spawning another goroutine.
type Message ¶
type Message struct {
Role string `json:"role"`
Content string `json:"content,omitempty"`
ToolCalls []ToolCall `json:"tool_calls,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"`
Name string `json:"name,omitempty"`
}
Message represents a chat message sent to the LLM API.
func ConvertToLlm ¶
func ConvertToLlm(msgs []AgentMessage) []Message
ConvertToLlm transforms AgentMessage[] to LLM-compatible Message[]. This is the boundary between internal transcript and model input.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry provides access to configured LLM providers for internal consumers.
func NewRegistry ¶
NewRegistry creates a new Registry.
func (*Registry) DebugEnabled ¶
DebugEnabled returns whether the system is in debug mode.
func (*Registry) Invalidate ¶
func (r *Registry) Invalidate()
Invalidate drops the cached provider list. Profile writes must call it so a new or edited profile is visible immediately.
func (*Registry) ListEnabled ¶
func (r *Registry) ListEnabled(ctx context.Context) ([]ResolvedConfig, error)
ListEnabled returns all (profile + enabled model) combinations.
The result is cached briefly: every ExplainSQL request needs the provider and model for its cache key, and a miss costs a database round trip plus an AES-256-GCM decryption of every profile's API key.
type ResolvedConfig ¶
type ResolvedConfig struct {
ProfileName string
ProfileTitle string
Type storepb.LLMProviderType
BaseURL string
APIKey string // decrypted
ModelName string
}
ResolvedConfig is a ready-to-use provider + model combination.
type SchemaContext ¶
type SchemaContext struct {
Objects []SchemaObject
}
SchemaContext holds pre-built schema information about database objects that the LLM can query via tools.
func BuildContextFromMetadata ¶
func BuildContextFromMetadata(metas []*storepb.StoredMetadata, guids []string) *SchemaContext
BuildContextFromMetadata builds schema context from the list of metadata objects.
type SchemaObject ¶
type SchemaObject struct {
GUID string
Name string
SchemaName string
DBName string
MetaType storepb.MetaType
SQLText string // DDL or definition
Columns []ColumnInfo
Indexes []string
}
SchemaObject describes a database object (table, view, procedure, etc.).
type ToolCall ¶
type ToolCall struct {
ID string `json:"id"`
Type string `json:"type"`
Function struct {
Name string `json:"name"`
Arguments string `json:"arguments"`
} `json:"function"`
}
ToolCall is a function call requested by the LLM.
type ToolDef ¶
type ToolDef struct {
Type string `json:"type"`
Function struct {
Name string `json:"name"`
Description string `json:"description"`
Parameters any `json:"parameters"`
} `json:"function"`
}
ToolDef defines a tool available to the LLM.
func ExplainSQLTools ¶
func ExplainSQLTools() []ToolDef
ExplainSQLTools returns the tool definitions available for SQL explanation.
type ToolExecutor ¶
type ToolExecutor func(toolCall ToolCall) ([]ToolResult, error)
ToolExecutor executes tool calls and returns results.
type ToolResult ¶
ToolResult is the result of executing a tool call.
Source Files