import "github.com/mwiater/induction"
Package induction provides a Go client and terminal-oriented helpers for llama.cpp-compatible inference servers, including chat, streaming, model inspection, telemetry snapshots, and MCP tool execution.
DefaultAttachmentMaxBytes is the default maximum attachment size, in bytes, used by applications that need a conservative 10 MiB upload limit.
const DefaultAttachmentMaxBytes int64 = 10 << 20
var (
// ErrModelNotFound indicates that the requested model is unknown to the server.
ErrModelNotFound = errors.New("model not found")
// ErrRuntimeUnsupported indicates that the endpoint does not expose runtime management.
ErrRuntimeUnsupported = errors.New("runtime model management unsupported")
// ErrModelLoadFailed indicates that a model could not be loaded successfully.
ErrModelLoadFailed = errors.New("model load failed")
// ErrModelUnloadFailed indicates that a model could not be unloaded successfully.
ErrModelUnloadFailed = errors.New("model unload failed")
// ErrRuntimeStateTimeout indicates that a requested lifecycle transition timed out.
ErrRuntimeStateTimeout = errors.New("runtime state wait timed out")
)
DefaultUnicode provides the standard rich UI experience.
var DefaultUnicode = IconSet{
PointerRight: "❯",
PointerLeft: "❮",
PointerUp: "⌃",
PointerDown: "⌄",
ArrowUp: "↑",
ArrowDown: "↓",
ArrowRight: "→",
ArrowLeft: "←",
ChevronUp: "˄",
ChevronDown: "˅",
ChevronRight: "›",
ChevronLeft: "‹",
TriangleUp: "▲",
TriangleDown: "▼",
TriangleRight: "▶",
TriangleLeft: "◀",
DoubleArrowRight: "»",
DoubleArrowLeft: "«",
Home: "⌂",
End: "⌁",
Check: "✔",
Cross: "✘",
Warning: "!",
Info: "ℹ",
Question: "?",
Success: "✓",
Failure: "✗",
Pending: "…",
Error: "⊗",
Sparkle: "✦",
Lightning: "ϟ",
Plus: "+",
Minus: "−",
Dot: "·",
Ellipsis: "...",
Started: "◌",
Complete: "☑",
Muted: "⊖",
Blocked: "⊘",
Neutral: "•",
SeparatorVertical: "│",
SeparatorHorizontal: "─",
SeparatorDoubleVertical: "║",
SeparatorDoubleHorizontal: "═",
CornerTopLeft: "┌",
CornerTopRight: "┐",
CornerBottomLeft: "└",
CornerBottomRight: "┘",
CornerTopLeftRounded: "╭",
CornerTopRightRounded: "╮",
CornerBottomLeftRounded: "╰",
CornerBottomRightRounded: "╯",
JunctionLeft: "┤",
JunctionRight: "├",
JunctionTop: "┴",
JunctionBottom: "┬",
JunctionCross: "┼",
TLeft: "┬",
TRight: "┴",
TTop: "┤",
Bullet: "●",
BulletHollow: "○",
RadioOn: "◉",
RadioOff: "◯",
CheckboxOn: "☒",
CheckboxOff: "☐",
Square: "■",
SquareHollow: "□",
Diamond: "◆",
DiamondHollow: "◇",
Star: "★",
StarHollow: "☆",
Selected: "☑",
Unselected: "☐",
Pin: "⌖",
Bookmark: "▮",
Flag: "⚑",
FlagHollow: "⚐",
Handle: "⋮⋮",
Grip: "⠿",
BlockFull: "█",
BlockDark: "▓",
BlockMedium: "▒",
BlockLight: "░",
BlockLeft: "▌",
BlockRight: "▐",
BlockUpper: "▀",
BlockLower: "▄",
BarHorizontal: "━",
BarVertical: "┃",
BarEmpty: "╌",
Refresh: "↻",
Reload: "⟳",
Hourglass: "⧖",
Clock: "◷",
TrendUp: "↗",
TrendDown: "↘",
ChartBar: "▂▅▇",
ChartLine: "╱╲╱",
ChartArea: "▁▃▆",
}
func CheckHealth(endpoint string, options ...ClientOption) error
CheckHealth probes the server health endpoint for the provided endpoint.
func Cleanup(out io.Writer)
Cleanup removes any live metrics overlays and prints the application cleanup status. Applications should call Cleanup before fatal exits because Cleanup stops active terminal overlays and restores normal terminal output. It is safe to call even when no overlay is active.
func ExtractPDFText(path string, maxBytes int64) (string, error)
ExtractPDFText extracts text operators from a small, local PDF. It supports the common Flate-compressed streams used by generated reports and avoids adding a heavyweight PDF dependency to the client library.
func FileDataURL(path string, maxBytes int64) (dataURL string, filename string, err error)
FileDataURL reads a local document and returns a base64 data URL. The filename is retained separately because some servers require it in the file content part.
func ImageDataURL(path string, maxBytes int64) (string, error)
ImageDataURL reads a local image and returns an OpenAI-compatible data URL. Empty, unsupported, and oversized files are rejected before they are sent.
func InferChat(ctx context.Context, req *ChatRequest, in io.Reader, out io.Writer, options ...ClientOption) error
InferChat runs a multi-turn, non-streaming chat session. It prompts for the first user message before sending a request, then retains the accumulated transcript on every turn. Cancel ctx (normally with Ctrl-C) to end the session.
func InferMCPChat(ctx context.Context, req *ChatRequest, in io.Reader, out io.Writer, options ...ClientOption) error
InferMCPChat runs a multi-turn, non-streaming chat session with the MCP tools enabled in induction.yaml. Read-only tools run automatically.
func InferMCPChatWithApproval(ctx context.Context, req *ChatRequest, in io.Reader, out io.Writer, approve MCPApprovalFunc, options ...ClientOption) error
InferMCPChatWithApproval is InferMCPChat with an explicit approval callback for tools that are not annotated as read-only by their MCP server.
func InferMCPStream(ctx context.Context, req *ChatRequest, out io.Writer, options ...ClientOption) error
InferMCPStream runs the configured MCP tool loop with streaming model responses and writes generated reasoning/content to out as it arrives.
func InferMCPStreamWithApproval(ctx context.Context, req *ChatRequest, out io.Writer, approve MCPApprovalFunc, options ...ClientOption) error
InferMCPStreamWithApproval is InferMCPStream with an explicit approval hook for MCP tools that are not annotated as read-only.
func InferStream(ctx context.Context, req *ChatRequest, out io.Writer, options ...ClientOption) error
InferStream runs a streaming inference request and writes only generated content to out, suitable for displaying directly in a chat interface.
func InferStreamChat(ctx context.Context, req *ChatRequest, in io.Reader, out io.Writer, options ...ClientOption) error
InferStreamChat runs a multi-turn streaming chat session. It has the same transcript and cancellation behavior as InferChat, but writes each assistant response as it arrives.
func InferStreamChunks(ctx context.Context, req *ChatRequest, yield func(InferenceStreamChunk) error, options ...ClientOption) error
InferStreamChunks runs a streaming inference request and calls yield for each typed OpenAI-compatible chunk object. SSE framing is consumed internally.
func ListLoadedModels(endpoint string, options ...ClientOption) error
ListLoadedModels fetches /v1/models and logs only loaded models.
func ListModels(endpoint string, options ...ClientOption) error
ListModels fetches /v1/models from the provided endpoint and prints a table.
func RunConsoleThemePreview(ctx context.Context, in io.Reader, out io.Writer) error
RunConsoleThemePreview displays one sample of every console theme element and exits when the user presses a key.
ChatRequest defines the payload sent to llama.cpp-compatible completion endpoints. It supports both /v1/chat/completions and completion-style requests.
type ChatRequest struct {
// Messages carries a chat transcript for chat-completion-style requests.
Messages []Message `json:"messages,omitempty"`
// Prompt accepts a string or an array of token IDs for completion requests.
Prompt any `json:"prompt,omitempty"`
Model string `json:"model,omitempty"`
Stream *bool `json:"stream,omitempty"`
MaxTokens *int `json:"max_tokens,omitempty"`
MaxCompletionTokens *int `json:"max_completion_tokens,omitempty"`
NPredict *int `json:"n_predict,omitempty"`
// Stop accepts either a string or an array of strings.
Stop any `json:"stop,omitempty"`
Seed *int `json:"seed,omitempty"`
NProbs *int `json:"n_probs,omitempty"`
IgnoreEOS *bool `json:"ignore_eos,omitempty"`
Temperature *float64 `json:"temperature,omitempty"`
TopP *float64 `json:"top_p,omitempty"`
TopK *int `json:"top_k,omitempty"`
MinP *float64 `json:"min_p,omitempty"`
PresencePenalty *float64 `json:"presence_penalty,omitempty"`
FrequencyPenalty *float64 `json:"frequency_penalty,omitempty"`
RepeatPenalty *float64 `json:"repeat_penalty,omitempty"`
RepeatLastN *int `json:"repeat_last_n,omitempty"`
PenalizeNL *bool `json:"penalize_nl,omitempty"`
LogitBias map[string]float64 `json:"logit_bias,omitempty"`
TfsZ *float64 `json:"tfs_z,omitempty"`
TypicalP *float64 `json:"typical_p,omitempty"`
Mirostat *int `json:"mirostat,omitempty"`
MirostatTau *float64 `json:"mirostat_tau,omitempty"`
MirostatEta *float64 `json:"mirostat_eta,omitempty"`
Samplers []string `json:"samplers,omitempty"`
XTCThreshold *float64 `json:"xtc_threshold,omitempty"`
XTCProbability *float64 `json:"xtc_probability,omitempty"`
DryMultiplier *float64 `json:"dry_multiplier,omitempty"`
DryBase *float64 `json:"dry_base,omitempty"`
DryAllowedLength *int `json:"dry_allowed_length,omitempty"`
DryPenaltyLastN *int `json:"dry_penalty_last_n,omitempty"`
DrySequenceBreakers []string `json:"dry_sequence_breakers,omitempty"`
DynatempRange *float64 `json:"dynatemp_range,omitempty"`
DynatempExponent *float64 `json:"dynatemp_exponent,omitempty"`
ResponseFormat *ResponseFormat `json:"response_format,omitempty"`
Grammar string `json:"grammar,omitempty"`
JSONSchema any `json:"json_schema,omitempty"`
Tools []Tool `json:"tools,omitempty"`
// ToolChoice accepts "auto", "none", or a specific tool choice object.
ToolChoice any `json:"tool_choice,omitempty"`
CachePrompt *bool `json:"cache_prompt,omitempty"`
SlotID *int `json:"slot_id,omitempty"`
NKeep *int `json:"n_keep,omitempty"`
ImageData []ImageData `json:"image_data,omitempty"`
}
ChatSession is the persisted transcript and snapshot history for one chat.
type ChatSession struct {
Version int `json:"version"`
ID string `json:"id"`
Type string `json:"type"`
Title string `json:"title"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
Model string `json:"model"`
Messages []Message `json:"messages"`
Snapshots []*ModelSnapshot `json:"snapshots"`
}
ChatSessionSummary contains the metadata shown when listing saved chats.
type ChatSessionSummary struct {
ID string
Title string
Model string
CreatedAt time.Time
UpdatedAt time.Time
MessageCount int
Path string
}
Client orchestrates interactions with a local llama.cpp-compatible server.
type Client struct {
// contains filtered or unexported fields
}
func NewClient(ctx context.Context, endpoint string, options ...ClientOption) *Client
NewClient initializes and returns a configured Induction client.
func NewClientFromConfig(ctx context.Context, options ...ClientOption) (*Client, error)
NewClientFromConfig loads induction.yaml and constructs a client using its server and interval settings. Additional options override YAML settings.
func (c *Client) Chat(ctx context.Context, req *ChatRequest) (*Interaction, error)
Chat runs a chat-completion request against the explicit chat endpoint.
func (c *Client) CheckHealth() error
CheckHealth probes the server health endpoints for the client endpoint.
func (c *Client) Complete(ctx context.Context, req *ChatRequest) (*Interaction, error)
Complete runs a plain completion request against the explicit completion endpoint.
func (c *Client) DeleteFile(ctx context.Context, id string) error
DeleteFile removes a previously uploaded file by server-assigned ID.
func (c *Client) GenerateSnapshot(ctx context.Context, req *ChatRequest) (*ModelSnapshot, error)
GenerateSnapshot executes an inference request and collects related telemetry.
func (c *Client) GenerateStreamingSnapshot(ctx context.Context, req *ChatRequest, yield func(InferenceStreamChunk) error) (*ModelSnapshot, error)
GenerateStreamingSnapshot streams an inference response while collecting the same telemetry as GenerateSnapshot.
func (c *Client) GetRuntimeStatus(ctx context.Context) (*RuntimeStatus, error)
GetRuntimeStatus returns the server-authoritative runtime state.
func (c *Client) InspectModel(ctx context.Context, model string) (*ModelInspection, error)
InspectModel collects runtime, capability, and telemetry data for model.
func (c *Client) InspectServer(ctx context.Context) (*ServerInspection, error)
InspectServer collects health, role, and model metadata from the endpoint.
func (c *Client) ListLoadedModels() error
ListLoadedModels fetches /v1/models and sends the loaded-model table to the configured logger.
func (c *Client) ListModels() error
ListModels fetches /v1/models and sends its table to the configured logger.
func (c *Client) LoadModel(ctx context.Context, model string) (*RuntimeOperation, error)
LoadModel asks the server to load model and waits for its resulting state.
func (c *Client) ServerRole(ctx context.Context) (ServerRole, error)
ServerRole returns the role reported or inferred for the client’s endpoint.
func (c *Client) StreamChat(ctx context.Context, req *ChatRequest, out io.Writer) (*Interaction, error)
StreamChat runs a streaming chat-completion request and writes the streamed text to out.
func (c *Client) StreamComplete(ctx context.Context, req *ChatRequest, out io.Writer) (*Interaction, error)
StreamComplete runs a streaming completion request and writes the streamed text to out.
func (c *Client) SwitchModel(ctx context.Context, target string, options ...SwitchOption) (*SwitchResult, error)
SwitchModel optionally unloads other loaded models and loads target.
func (c *Client) UnloadModel(ctx context.Context, model string) (*RuntimeOperation, error)
UnloadModel asks the server to unload model and waits for its resulting state.
func (c *Client) UploadFile(ctx context.Context, filename string, content io.Reader) (*UploadedFile, error)
UploadFile uploads a document through the OpenAI-compatible /v1/files API. The endpoint is optional across llama.cpp-compatible servers; callers should treat a 404 as an unsupported file feature and may use FileDataURL instead.
ClientOption mutates a ClientOptions value during client construction.
type ClientOption func(*ClientOptions)
func WithHTTPClient(c *http.Client) ClientOption
WithHTTPClient injects a custom HTTP client into the Induction client.
func WithLiveMetricsOverlay(enabled bool) ClientOption
WithLiveMetricsOverlay controls the terminal overlay shown while snapshots are collecting an inference response.
func WithLoadWaitInterval(d time.Duration) ClientOption
WithLoadWaitInterval sets the wait interval used while a model is loading.
func WithLogger(logger Logger) ClientOption
WithLogger routes Induction messages through the application’s logger. Induction is silent unless a logger is supplied.
func WithPollInterval(d time.Duration) ClientOption
WithPollInterval sets how often /slots is sampled while inference is active.
ClientOptions stores runtime configuration for a Client.
type ClientOptions struct {
// contains filtered or unexported fields
}
Config contains runtime settings loaded from induction.yaml.
type Config struct {
Server string `yaml:"server"`
Timeout Duration `yaml:"timeout"`
PollInterval Duration `yaml:"poll_interval"`
LoadWaitInterval Duration `yaml:"load_wait_interval"`
EnableLiveMetricsOverlay bool `yaml:"enableLiveMetricsOverlay"`
PersistSnapshots bool `yaml:"persistSnapshots"`
SidebarWidth int `yaml:"sidebarWidth"`
MCPServers []MCPServerConfig `yaml:"MCPServers"`
Log LogConfig `yaml:"log"`
ModelManager ModelManagerConfig `yaml:"ModelManager" mapstructure:"ModelManager"`
}
func LoadConfig(path ...string) (*Config, error)
LoadConfig loads induction.yaml once and returns the process-wide config. Without an explicit path, induction.yaml must exist in the current working directory (normally the project root). An optional path may be supplied; the path from the first call is the one used for the lifetime of the process.
func (c *Config) Validate() error
Validate normalizes and validates all configuration fields.
ContentPart is one item in a multimodal message. Set exactly one of Text, ImageURL, or File for the corresponding Type (“text”, “image_url”, or “file”). It intentionally models the OpenAI-compatible content shape so callers do not need to build raw maps.
type ContentPart struct {
Type string `json:"type"`
Text string `json:"text,omitempty"`
ImageURL *ImageURLPart `json:"image_url,omitempty"`
File *FileContentPart `json:"file,omitempty"`
}
Duration is a time.Duration that is represented by strings such as “2s” or “20m” in induction.yaml.
type Duration time.Duration
func (d *Duration) UnmarshalYAML(value *yaml.Node) error
UnmarshalYAML parses a Go duration string from YAML.
FileContentPart identifies an attached document. Servers commonly support one of FileID, FileURL, or FileData; Filename is required with FileData.
type FileContentPart struct {
FileID string `json:"file_id,omitempty"`
FileURL string `json:"file_url,omitempty"`
FileData string `json:"file_data,omitempty"`
Filename string `json:"filename,omitempty"`
}
IconSet defines a collection of monochrome symbols for terminal dashboards.
type IconSet struct {
// Navigation & Pointers
PointerRight, PointerLeft, PointerUp, PointerDown string
ArrowUp, ArrowDown, ArrowRight, ArrowLeft string
ChevronUp, ChevronDown, ChevronRight, ChevronLeft string
TriangleUp, TriangleDown, TriangleRight, TriangleLeft string
DoubleArrowRight, DoubleArrowLeft, Home, End string
// Status & Validation
Check, Cross, Warning, Info, Question string
Success, Failure, Pending, Error string
Sparkle, Lightning, Plus, Minus string
Dot, Ellipsis string
Started, Complete, Muted, Blocked, Neutral string
// Structure & Borders
SeparatorVertical, SeparatorHorizontal string
SeparatorDoubleVertical, SeparatorDoubleHorizontal string
CornerTopLeft, CornerTopRight, CornerBottomLeft, CornerBottomRight string
CornerTopLeftRounded, CornerTopRightRounded string
CornerBottomLeftRounded, CornerBottomRightRounded string
JunctionLeft, JunctionRight, JunctionTop, JunctionBottom string
JunctionCross, TLeft, TRight string
TTop string
// Toggles & Selection
Bullet, BulletHollow, RadioOn, RadioOff, CheckboxOn, CheckboxOff string
Square, SquareHollow, Diamond, DiamondHollow, Star, StarHollow string
Selected, Unselected, Pin, Bookmark string
Flag, FlagHollow, Handle, Grip string
// Progress & Charts
BlockFull, BlockDark, BlockMedium, BlockLight string
BlockLeft, BlockRight, BlockUpper, BlockLower string
BarHorizontal, BarVertical, BarEmpty string
Refresh, Reload, Hourglass, Clock string
TrendUp, TrendDown, ChartBar, ChartLine string
ChartArea string
}
ImageData carries a base64-encoded image for multimodal inference.
type ImageData struct {
Data string `json:"data"`
ID int `json:"id"`
}
ImageURLPart identifies a public image URL or a data URL. Detail is an optional server-dependent hint such as “low”, “high”, or “auto”.
type ImageURLPart struct {
URL string `json:"url"`
Detail string `json:"detail,omitempty"`
}
InferenceChoice is one generated choice from a chat or completion response.
type InferenceChoice struct {
Index int `json:"index"`
Message *InferenceResponseMessage `json:"message,omitempty"`
Text string `json:"text,omitempty"`
Logprobs json.RawMessage `json:"logprobs,omitempty"`
FinishReason *string `json:"finish_reason,omitempty"`
}
InferenceFunctionCall contains a requested function name and JSON arguments.
type InferenceFunctionCall struct {
Name string `json:"name"`
Arguments string `json:"arguments"`
}
InferenceResponse is the OpenAI-compatible response returned by Infer. Choices supports both chat-completion messages and completion text.
type InferenceResponse struct {
ID string `json:"id"`
Object string `json:"object"`
Created int64 `json:"created"`
Model string `json:"model"`
SystemFingerprint string `json:"system_fingerprint,omitempty"`
Choices []InferenceChoice `json:"choices"`
Usage *InferenceUsage `json:"usage,omitempty"`
}
func Infer(ctx context.Context, req *ChatRequest, options ...ClientOption) (*InferenceResponse, error)
Infer runs a standard OpenAI-compatible inference request using the model, server, and timeout configured in induction.yaml.
func InferMCP(ctx context.Context, req *ChatRequest, options ...ClientOption) (*InferenceResponse, error)
InferMCP runs an application-managed MCP tool loop using the servers enabled in induction.yaml. Read-only tools run automatically; potentially side-effecting tools are denied. Use InferMCPWithApproval when an application needs to approve such calls explicitly.
func InferMCPWithApproval(ctx context.Context, req *ChatRequest, approve MCPApprovalFunc, options ...ClientOption) (*InferenceResponse, error)
InferMCPWithApproval is InferMCP with an explicit approval callback for tools that are not annotated as read-only by their MCP server.
InferenceResponseMessage is an assistant message returned by the model.
type InferenceResponseMessage struct {
Role string `json:"role"`
Content string `json:"content"`
ReasoningContent string `json:"reasoning_content,omitempty"`
Refusal string `json:"refusal,omitempty"`
ToolCalls []InferenceToolCall `json:"tool_calls,omitempty"`
}
InferenceStreamChoice contains a chat delta or completion text fragment.
type InferenceStreamChoice struct {
Index int `json:"index"`
Delta InferenceStreamDelta `json:"delta,omitempty"`
Text string `json:"text,omitempty"`
Logprobs json.RawMessage `json:"logprobs,omitempty"`
FinishReason *string `json:"finish_reason,omitempty"`
}
InferenceStreamChunk is one OpenAI-compatible streaming response object.
type InferenceStreamChunk struct {
ID string `json:"id"`
Object string `json:"object"`
Created int64 `json:"created"`
Model string `json:"model"`
SystemFingerprint string `json:"system_fingerprint,omitempty"`
Choices []InferenceStreamChoice `json:"choices"`
Usage *InferenceUsage `json:"usage,omitempty"`
}
InferenceStreamDelta contains incremental assistant content and tool calls.
type InferenceStreamDelta struct {
Role string `json:"role,omitempty"`
Content string `json:"content,omitempty"`
ReasoningContent string `json:"reasoning_content,omitempty"`
Refusal string `json:"refusal,omitempty"`
ToolCalls []InferenceStreamToolCall `json:"tool_calls,omitempty"`
}
InferenceStreamToolCall contains an incremental tool-call update.
type InferenceStreamToolCall struct {
Index int `json:"index"`
ID string `json:"id,omitempty"`
Type string `json:"type,omitempty"`
Function InferenceFunctionCall `json:"function,omitempty"`
}
InferenceToolCall describes a function call requested by the model.
type InferenceToolCall struct {
ID string `json:"id"`
Type string `json:"type"`
Function InferenceFunctionCall `json:"function"`
}
InferenceUsage contains OpenAI-compatible token counts.
type InferenceUsage struct {
PromptTokens int `json:"prompt_tokens"`
CompletionTokens int `json:"completion_tokens"`
TotalTokens int `json:"total_tokens"`
}
Interaction stores the response body and best-effort extracted text content.
type Interaction struct {
// Content stores the extracted assistant text when it can be parsed.
Content string `json:"content"`
// ReasoningContent stores separately returned model reasoning when present.
ReasoningContent string `json:"reasoning_content,omitempty"`
// Response stores the raw response body returned by the server.
Response string `json:"response"`
}
func Chat(ctx context.Context, endpoint string, req *ChatRequest, options ...ClientOption) (*Interaction, error)
Chat sends a chat-completion request using a convenience client.
func Complete(ctx context.Context, endpoint string, req *ChatRequest, options ...ClientOption) (*Interaction, error)
Complete sends a completion request using a convenience client.
func StreamChat(ctx context.Context, endpoint string, req *ChatRequest, out io.Writer, options ...ClientOption) (*Interaction, error)
StreamChat sends a streaming chat-completion request and writes streamed text to out.
func StreamComplete(ctx context.Context, endpoint string, req *ChatRequest, out io.Writer, options ...ClientOption) (*Interaction, error)
StreamComplete sends a streaming completion request and writes streamed text to out.
LogConfig controls application log destination and formatting.
type LogConfig struct {
Path string `yaml:"path"`
Console bool `yaml:"console"`
Prefix string `yaml:"prefix"`
Microseconds bool `yaml:"microseconds"`
}
Logger is the logging contract used by Induction. The standard library’s log.Logger satisfies this interface, as do many application log adapters.
type Logger interface {
Printf(format string, args ...interface{})
}
MCPApprovalFunc decides whether a potentially side-effecting MCP tool may be called. Read-only tools do not invoke this hook.
type MCPApprovalFunc func(context.Context, MCPTool, json.RawMessage) (bool, error)
MCPServerConfig describes a remote Model Context Protocol server. Allow is an explicit server-level allowlist switch; disabled entries are never contacted or exposed to a model. MCPServerConfig describes one configured Model Context Protocol server.
type MCPServerConfig struct {
Allow bool `yaml:"MCPServerAllow"`
Name string `yaml:"MCPServerName"`
URL string `yaml:"MCPServerURL"`
}
MCPTool describes a discovered MCP tool presented for side-effect approval.
type MCPTool struct {
ServerName string
Name string
Description string
}
Message represents a single chat message sent to a completion endpoint.
type Message struct {
// Role identifies the speaker, such as "system", "user", or "assistant".
Role string `json:"role"`
// Content accepts either text or an array of multimodal content objects.
Content any `json:"content"`
// ToolCalls carries function calls requested by an assistant message.
ToolCalls []InferenceToolCall `json:"tool_calls,omitempty"`
// ToolCallID associates a tool result with the assistant call that requested it.
ToolCallID string `json:"tool_call_id,omitempty"`
// Name identifies the function that produced a tool result.
Name string `json:"name,omitempty"`
}
MetricsData holds the raw Prometheus text and parsed metric entries.
type MetricsData struct {
// Raw keeps the original metrics payload.
Raw string `json:"raw"`
// Entries stores parsed metric values keyed by metric name.
Entries map[string]interface{} `json:"entries"`
}
ModelCapabilities contains capabilities explicitly reported by the server.
type ModelCapabilities struct {
TextInput bool `json:"textInput"`
ImageInput bool `json:"imageInput"`
AudioInput bool `json:"audioInput"`
TextOutput bool `json:"textOutput"`
}
ModelInspection is a read-only snapshot of one runtime model.
type ModelInspection struct {
ID string `json:"id"`
State ModelRuntimeState `json:"state"`
Failed bool `json:"failed,omitempty"`
ExitCode *int `json:"exitCode,omitempty"`
Path string `json:"path,omitempty"`
Args []string `json:"args,omitempty"`
Capabilities ModelCapabilities `json:"capabilities"`
Runtime ModelRuntimeConfig `json:"runtime"`
Props *PropsData `json:"props,omitempty"`
Slots SlotsData `json:"slots,omitempty"`
RawModel json.RawMessage `json:"rawModel,omitempty"`
CollectedAt time.Time `json:"collectedAt"`
}
ModelLifecycleEvent is a UI-independent representation of a model SSE event.
type ModelLifecycleEvent struct {
Model string `json:"model"`
Event string `json:"event,omitempty"`
State ModelRuntimeState `json:"state"`
Progress ModelLoadProgress `json:"progress,omitempty"`
}
ModelLoadProgress is the server-reported progress of a model lifecycle event.
type ModelLoadProgress = modelLoadProgress
ModelManagerConfig controls model discovery and local model storage.
type ModelManagerConfig struct {
SearchResults int `yaml:"SearchResults" mapstructure:"SearchResults" json:"searchResults"`
PreferredProviders []string `yaml:"PreferredProviders" mapstructure:"PreferredProviders" json:"preferredProviders"`
ModelsPath string `yaml:"ModelsPath" mapstructure:"ModelsPath" json:"modelsPath"`
PreferredQuantizations []string `yaml:"PreferredQuantizations" mapstructure:"PreferredQuantizations" json:"preferredQuantizations,omitempty"`
IncludePatterns []string `yaml:"IncludePatterns" mapstructure:"IncludePatterns" json:"includePatterns,omitempty"`
ExcludePatterns []string `yaml:"ExcludePatterns" mapstructure:"ExcludePatterns" json:"excludePatterns,omitempty"`
AvailableRAM string `yaml:"AvailableRAM" mapstructure:"AvailableRAM" json:"availableRAM,omitempty"`
AvailableVRAM string `yaml:"AvailableVRAM" mapstructure:"AvailableVRAM" json:"availableVRAM,omitempty"`
}
func (c *ModelManagerConfig) NormalizeAndValidate() error
NormalizeAndValidate applies defaults and validates model-manager settings.
ModelRuntimeConfig contains normalized, optional runtime settings.
type ModelRuntimeConfig struct {
ContextSize *int `json:"contextSize,omitempty"`
BatchSize *int `json:"batchSize,omitempty"`
UBatchSize *int `json:"ubatchSize,omitempty"`
Parallel *int `json:"parallel,omitempty"`
CacheTypeK string `json:"cacheTypeK,omitempty"`
CacheTypeV string `json:"cacheTypeV,omitempty"`
FlashAttention *bool `json:"flashAttention,omitempty"`
Temperature *float64 `json:"temperature,omitempty"`
TopK *int `json:"topK,omitempty"`
TopP *float64 `json:"topP,omitempty"`
RepeatLastN *int `json:"repeatLastN,omitempty"`
RepeatPenalty *float64 `json:"repeatPenalty,omitempty"`
}
ModelRuntimeError reports a failed model lifecycle transition and preserves the underlying cause for errors.Is and errors.As inspection.
type ModelRuntimeError struct {
Model string
State ModelRuntimeState
ExitCode *int
Err error
}
func (e *ModelRuntimeError) Error() string
Error returns a human-readable description of the failed model transition.
func (e *ModelRuntimeError) Unwrap() error
Unwrap returns the underlying lifecycle error.
ModelRuntimeState describes the server-reported lifecycle state of a model.
type ModelRuntimeState string
const (
// ModelRuntimeUnknown indicates that the server did not report a recognized state.
ModelRuntimeUnknown ModelRuntimeState = "unknown"
// ModelRuntimeUnloaded indicates that the model is not resident in memory.
ModelRuntimeUnloaded ModelRuntimeState = "unloaded"
// ModelRuntimeLoading indicates that the server is loading the model.
ModelRuntimeLoading ModelRuntimeState = "loading"
// ModelRuntimeLoaded indicates that the model is resident and ready.
ModelRuntimeLoaded ModelRuntimeState = "loaded"
// ModelRuntimeSleeping indicates that the server has put the model to sleep.
ModelRuntimeSleeping ModelRuntimeState = "sleeping"
)
ModelSnapshot aggregates all telemetry and inference data for a request.
type ModelSnapshot struct {
// ModelID identifies the model used for the snapshot.
ModelID string
// LoadTime records how long the load gate took before inference began.
LoadTime time.Duration
// CollectedAt records when the snapshot was finished.
CollectedAt time.Time
// Interaction stores the inference responses represented by this snapshot.
Interaction []Interaction
// Messages stores the complete chat history represented by this snapshot.
Messages []Message `json:"messages"`
// Props stores the /props response when available.
Props *PropsData
// Slots stores the /slots response when available.
Slots SlotsData
// Metrics stores parsed metric data when available.
Metrics *MetricsData
}
func GenerateSnapshot(ctx context.Context, endpoint string, req *ChatRequest, options ...ClientOption) (*ModelSnapshot, error)
GenerateSnapshot fetches telemetry for the requested model using a convenience client.
func InferMCPSnapshot(ctx context.Context, req *ChatRequest, options ...ClientOption) (*ModelSnapshot, error)
InferMCPSnapshot runs the configured MCP tool loop and returns telemetry for the final inference turn. Read-only tools run automatically.
func InferMCPSnapshotWithApproval(ctx context.Context, req *ChatRequest, approve MCPApprovalFunc, options ...ClientOption) (*ModelSnapshot, error)
InferMCPSnapshotWithApproval is InferMCPSnapshot with an explicit approval callback for tools that are not annotated as read-only by their MCP server.
func InferSnapshot(ctx context.Context, req *ChatRequest, options ...ClientOption) (*ModelSnapshot, error)
InferSnapshot loads induction.yaml from the current working directory, applies its model and timeout, and runs inference with telemetry collection.
func InferSnapshotChat(ctx context.Context, req *ChatRequest, in io.Reader, out io.Writer, options ...ClientOption) ([]*ModelSnapshot, error)
InferSnapshotChat runs a multi-turn, non-streaming chat session and returns one telemetry snapshot for every completed assistant response. The returned slice remains available when the session ends through cancellation or EOF.
PropsData represents the server’s /props response payload.
type PropsData struct {
// Raw keeps the full unmodified response body.
Raw string `json:"raw,omitempty"`
// TotalSlots reports the number of slots exposed by the server.
TotalSlots int `json:"total_slots,omitempty"`
// DefaultGenerationSettings holds the parsed generation settings map.
DefaultGenerationSettings map[string]interface{} `json:"default_generation_settings,omitempty"`
}
ResponseFormat configures JSON-object or JSON-schema constrained output.
type ResponseFormat struct {
Type string `json:"type"`
JSONSchema any `json:"json_schema,omitempty"`
}
RuntimeModel is the normalized runtime state and metadata for one model.
type RuntimeModel struct {
ID string `json:"id"`
State ModelRuntimeState `json:"state"`
Failed bool `json:"failed,omitempty"`
ExitCode *int `json:"exitCode,omitempty"`
Args []string `json:"args,omitempty"`
Path string `json:"path,omitempty"`
LastUsed *int64 `json:"lastUsed,omitempty"`
InputModes []string `json:"inputModalities,omitempty"`
OutputModes []string `json:"outputModalities,omitempty"`
Raw json.RawMessage `json:"raw,omitempty"`
}
RuntimeOperation records one model load or unload transition.
type RuntimeOperation struct {
Model string `json:"model"`
From ModelRuntimeState `json:"from"`
To ModelRuntimeState `json:"to"`
Changed bool `json:"changed"`
Duration time.Duration `json:"duration"`
CompletedAt time.Time `json:"completedAt"`
}
func LoadModel(ctx context.Context, endpoint, model string, options ...ClientOption) (*RuntimeOperation, error)
LoadModel asks endpoint to load model using a convenience client.
func UnloadModel(ctx context.Context, endpoint, model string, options ...ClientOption) (*RuntimeOperation, error)
UnloadModel asks endpoint to unload model using a convenience client.
RuntimeStatus is a point-in-time view of all models known to the server.
type RuntimeStatus struct {
ServerRole ServerRole `json:"serverRole"`
Models []RuntimeModel `json:"models"`
Loaded []string `json:"loaded"`
Loading []string `json:"loading"`
CollectedAt time.Time `json:"collectedAt"`
}
func GetRuntimeStatus(ctx context.Context, endpoint string, options ...ClientOption) (*RuntimeStatus, error)
GetRuntimeStatus returns runtime state using a convenience client for endpoint.
ServerInspection is a read-only snapshot of a llama.cpp server.
type ServerInspection struct {
Endpoint string `json:"endpoint"`
Role ServerRole `json:"role"`
Healthy bool `json:"healthy"`
Models []RuntimeModel `json:"models"`
LoadedModels []string `json:"loadedModels"`
Props *PropsData `json:"props,omitempty"`
CollectedAt time.Time `json:"collectedAt"`
}
ServerRole identifies whether the endpoint acts as a router or a model server.
type ServerRole string
const (
// ServerRoleUnknown indicates that the endpoint role could not be determined.
ServerRoleUnknown ServerRole = "unknown"
// ServerRoleRouter identifies a router or multi-model endpoint.
ServerRoleRouter ServerRole = "router"
// ServerRoleModel identifies an endpoint serving model inference directly.
ServerRoleModel ServerRole = "model"
)
SlotsData is a slice alias for slot telemetry records.
type SlotsData []map[string]interface{}
SwitchOption modifies the options used by SwitchModel.
type SwitchOption func(*SwitchOptions)
func WithUnloadOthers(enabled bool) SwitchOption
WithUnloadOthers controls whether SwitchModel unloads other loaded models before loading its target. It is enabled by default.
SwitchOptions controls the behavior of SwitchModel.
type SwitchOptions struct{ UnloadOthers bool }
SwitchResult describes the operations performed while switching models.
type SwitchResult struct {
Target string `json:"target"`
Unloaded []RuntimeOperation `json:"unloaded,omitempty"`
Load *RuntimeOperation `json:"load,omitempty"`
Duration time.Duration `json:"duration"`
}
Tool describes a tool available to the model.
type Tool struct {
Type string `json:"type"`
Function ToolFunction `json:"function"`
}
ToolFunction describes a callable function and its JSON Schema parameters.
type ToolFunction struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Parameters any `json:"parameters,omitempty"`
}
UploadedFile identifies a document accepted by the server’s file API.
type UploadedFile struct {
// ID is the server-assigned identifier used to reference the uploaded file.
ID string `json:"id"`
// Object identifies the API resource type returned by the server.
Object string `json:"object,omitempty"`
// Filename is the basename associated with the uploaded content.
Filename string `json:"filename,omitempty"`
}
import "github.com/mwiater/induction/cmd/induction"
Command induction provides the command-line interface for the Induction client and model manager.
import "github.com/mwiater/induction/examples/infer"
Command infer demonstrates the default, streaming, chat, and snapshot inference output modes.
import "github.com/mwiater/induction/examples/infer_document"
Command infer_document demonstrates attaching a local PDF as inline data.
import "github.com/mwiater/induction/examples/infer_image"
Command infer_image demonstrates ordered text and local data-URL image parts.
import "github.com/mwiater/induction/examples/infer_mcp"
Command infer_mcp demonstrates the supported MCP inference output modes.
import "github.com/mwiater/induction/examples/infer_snapshot_parameters"
Command infer_snapshot_parameters sends a parameterized chat request and prints the resulting model snapshot.
import "github.com/mwiater/induction/examples/infer_tools"
Command infer_tools demonstrates an application-managed function-calling loop.
import "github.com/mwiater/induction/examples/list_models"
Command list_models prints the models exposed by the configured server.
import "github.com/mwiater/induction/internal/cli"
Package cli implements the induction command-line interface.
func Execute() int
Execute runs the root command and returns a process exit status.
func NewRootCommand() *cobra.Command
NewRootCommand constructs the induction CLI.
import "github.com/mwiater/induction/internal/modelmanager"
Package modelmanager discovers, downloads, verifies, and updates local model artifacts obtained from Hugging Face.
InteractionLogPath is the local audit-log filename used by the model manager.
const InteractionLogPath = "induction-model-manager.log"
func DetectQuantization(name string) string
DetectQuantization recognizes common GGUF quantization tokens without excluding unfamiliar artifact names.
func DetectRAM() int64
DetectRAM returns host physical memory in bytes, or zero when unavailable.
func DownloadURL(repository, revision, filename string) (string, error)
DownloadURL returns a revision-pinned, safely escaped Hugging Face URL.
func HashFile(ctx context.Context, path string) (string, error)
HashFile computes the SHA-256 digest of path while honoring ctx cancellation.
func InstallationMatches(item Installation, model string) bool
InstallationMatches reports whether item identifies model.
func InstallationModelID(item Installation) string
InstallationModelID returns the stable repository/model identifier for item.
func LogInteraction(event string, fields ...string) error
LogInteraction appends a sanitized, timestamped model-manager event.
func ParseByteSize(value string) (int64, error)
ParseByteSize parses decimal or binary byte units such as MB, GB, MiB, and GiB.
func RecoverTransactions(modelsPath string) error
RecoverTransactions completes or rolls back interrupted updates below modelsPath.
func RemoveInstallation(modelsPath string, item Installation) error
RemoveInstallation removes the artifacts and manifest belonging to item.
func RunInstalledInteractive(ctx context.Context, in io.Reader, out io.Writer, client *HFCLIClient, options InteractiveOptions, action InstalledAction, initial string) error
RunInstalledInteractive runs an installed-model operation UI.
func RunInteractive(ctx context.Context, in io.Reader, out io.Writer, client HubClient, options InteractiveOptions, initialQuery string) error
RunInteractive runs the model-manager UI until completion or cancellation.
func WriteManifestAtomic(path string, manifest Manifest) error
WriteManifestAtomic writes manifest through a synced temporary file and atomic rename so an interrupted write cannot leave a partial manifest.
Destination contains the confined paths used for one repository artifact.
type Destination struct {
Directory string
Artifact string
Manifest string
}
func ResolveDestination(modelsPath, repository, filename string) (Destination, error)
ResolveDestination maps a repository-relative filename into modelsPath after rejecting traversal and absolute-path escapes.
DiskPreflight reports whether enough space is available for an installation.
type DiskPreflight struct {
AvailableBytes uint64 `json:"availableBytes"`
RequiredBytes uint64 `json:"requiredBytes"`
SizeKnown bool `json:"sizeKnown"`
Sufficient bool `json:"sufficient"`
}
func CheckDisk(path string, size int64) (DiskPreflight, error)
CheckDisk creates path if needed and estimates the space required for a download.
DownloadRequest specifies one Hugging Face artifact download.
type DownloadRequest struct {
Repository, File, Revision, ModelsPath string
Size int64
ETag, LFSOID string
Overwrite bool
}
FileInstallState describes whether a requested model file is installed.
type FileInstallState string
const (
// FileNotInstalled indicates that the requested artifact is absent.
FileNotInstalled FileInstallState = "NOT INSTALLED"
// FileInstalled indicates that the artifact and revision match.
FileInstalled FileInstallState = "INSTALLED"
// FileDifferentRevision indicates that the artifact exists at another revision.
FileDifferentRevision FileInstallState = "INSTALLED (different revision)"
// FileUntracked indicates that a file exists without a matching manifest.
FileUntracked FileInstallState = "FILE EXISTS (untracked)"
)
FitClass is the advisory classification produced by EstimateFit.
type FitClass string
const (
// FitLikely indicates that the estimate leaves a 10% memory margin.
FitLikely FitClass = "LIKELY FITS"
// FitMarginal indicates that the estimate fits without the 10% margin.
FitMarginal FitClass = "MARGINAL"
// FitTooLarge indicates that the estimate exceeds available memory.
FitTooLarge FitClass = "TOO LARGE"
// FitUnknown indicates that artifact or memory size is unavailable.
FitUnknown FitClass = "UNKNOWN"
)
FitEstimate contains the advisory memory-fit calculation for an artifact.
type FitEstimate struct {
Classification FitClass `json:"classification"`
ArtifactBytes int64 `json:"artifactBytes"`
EstimatedRequiredBytes int64 `json:"estimatedRequiredBytes"`
AvailableRAMBytes int64 `json:"availableRamBytes,omitempty"`
AvailableVRAMBytes int64 `json:"availableVramBytes,omitempty"`
RuntimeOverhead float64 `json:"runtimeOverhead"`
Advisory bool `json:"advisory"`
}
func EstimateFit(artifact, ram, vram int64, overhead float64) FitEstimate
EstimateFit classifies whether an artifact is likely to fit after overhead.
HFCLIClient invokes the modern Hugging Face hf executable.
type HFCLIClient struct {
Path string
HTTPClient *http.Client
APIBaseURL string
}
func NewHFCLIClient() (*HFCLIClient, error)
NewHFCLIClient locates hf and returns actionable installation guidance.
func (c *HFCLIClient) ListFiles(ctx context.Context, modelID string) (string, []ModelFile, error)
ListFiles returns the immutable revision and downloadable files for modelID.
func (c *HFCLIClient) Search(ctx context.Context, query string, limit int, provider string) ([]SearchResult, error)
Search returns repositories matching query, optionally scoped to provider.
HubClient abstracts Hugging Face access for deterministic tests.
type HubClient interface {
Search(ctx context.Context, query string, limit int, provider string) ([]SearchResult, error)
ListFiles(ctx context.Context, modelID string) (revision string, files []ModelFile, err error)
}
Installation pairs a validated manifest with the artifact paths it describes.
type Installation struct {
Manifest Manifest `json:"manifest"`
ArtifactPath string `json:"artifactPath"`
ArtifactPaths []string `json:"artifactPaths,omitempty"`
ManifestPath string `json:"manifestPath"`
}
func FindInstallation(index InstalledIndex, model string) (Installation, error)
FindInstallation returns the installation matching a repository or model ID.
InstalledAction selects the operation offered for an installed model.
type InstalledAction string
const (
// ActionDetails displays installation metadata.
ActionDetails InstalledAction = "details"
// ActionVerify checks the installed artifact digest.
ActionVerify InstalledAction = "verify"
// ActionUpdate downloads a newer artifact revision.
ActionUpdate InstalledAction = "update"
// ActionRemove deletes the selected installation.
ActionRemove InstalledAction = "remove"
)
InstalledIndex contains valid installations and warnings from a model scan.
type InstalledIndex struct {
Installations []Installation `json:"installations"`
Warnings []string `json:"warnings,omitempty"`
}
func BuildInstalledIndex(modelsPath string) (InstalledIndex, error)
BuildInstalledIndex scans modelsPath and returns only installations with safe paths and present artifacts.
func (i InstalledIndex) FileState(modelsPath, repository, file, revision string) FileInstallState
FileState compares a requested file with the indexed installation state.
func (i InstalledIndex) RepositoryCount(repository string) int
RepositoryCount returns the number of installations belonging to repository.
InstalledModel is the Bubble Tea model for managing local installations.
type InstalledModel struct {
// contains filtered or unexported fields
}
func NewInstalledModel(ctx context.Context, client *HFCLIClient, options InteractiveOptions, action InstalledAction, index InstalledIndex, initial string) InstalledModel
NewInstalledModel creates an installed-model management UI.
func (m InstalledModel) Init() tea.Cmd
Init implements tea.Model and performs no startup command.
func (m InstalledModel) Update(msg tea.Msg) (tea.Model, tea.Cmd)
Update implements tea.Model and advances the installed-model workflow.
func (m InstalledModel) View() string
View implements tea.Model and renders the installed-model workflow.
InteractiveOptions configures the interactive model-manager screens.
type InteractiveOptions struct {
SearchResults int
PreferredProviders, PreferredQuantizations, IncludePatterns, ExcludePatterns []string
ModelsPath, HFPath string
}
Manifest records immutable metadata and integrity information for an installed model artifact or shard set.
type Manifest struct {
SchemaVersion int `json:"schemaVersion"`
ModelFile string `json:"modelFile,omitempty"`
RepositoryID string `json:"repositoryId"`
Revision string `json:"revision"`
DownloadURL string `json:"downloadUrl,omitempty"`
DownloadedAt time.Time `json:"downloadedAt"`
SizeBytes int64 `json:"sizeBytes,omitempty"`
ETag string `json:"etag,omitempty"`
LFSOID string `json:"lfsOid,omitempty"`
SHA256 string `json:"sha256,omitempty"`
Files []ManifestFile `json:"files,omitempty"`
}
func Download(ctx context.Context, hfPath string, request DownloadRequest) (Manifest, error)
Download retrieves, verifies, and records one model artifact.
func DownloadHTTP(ctx context.Context, client *http.Client, request DownloadRequest, progress ProgressFunc) (Manifest, error)
DownloadHTTP streams one immutable Hub artifact into a same-directory staging file, reports byte progress, validates it, and atomically installs the artifact before writing its provenance manifest.
func DownloadMulti(ctx context.Context, hfPath, modelsPath, repository, revision string, files []ModelFile) (Manifest, string, error)
DownloadMulti downloads and verifies a selected model file or complete shard set.
func DownloadMultiHTTP(ctx context.Context, client *http.Client, modelsPath, repository, revision string, files []ModelFile, overwrite bool, progress ProgressFunc) (Manifest, string, error)
DownloadMultiHTTP applies the same measured transfer and validation path to every shard and then writes one schema-v2 logical-installation manifest.
func UpdateInstallation(ctx context.Context, hfPath, modelsPath string, installed Installation, revision string, remote ModelFile) (Manifest, error)
UpdateInstallation downloads a replacement artifact and atomically installs its verified artifact and manifest.
ManifestFile records metadata for one file in a multi-file model install.
type ManifestFile struct {
ModelFile string `json:"modelFile"`
DownloadURL string `json:"downloadUrl"`
SizeBytes int64 `json:"sizeBytes"`
SHA256 string `json:"sha256"`
ETag string `json:"etag,omitempty"`
LFSOID string `json:"lfsOid,omitempty"`
}
Model is the Bubble Tea state for the interactive model-manager workflow.
type Model struct {
Screen Screen
Query textinput.Model
Repositories, Files list.Model
Spinner spinner.Model
Progress progress.Model
Help help.Model
// contains filtered or unexported fields
}
func NewInteractiveModel(ctx context.Context, client HubClient, options InteractiveOptions, initialQuery string) Model
NewInteractiveModel creates a model-manager UI with an optional initial query.
func NewModel(ctx context.Context, client HubClient, limit int, providers []string, initialQuery string) Model
NewModel creates the model-manager UI with explicit search settings.
func (m Model) Init() tea.Cmd
Init implements tea.Model and starts the initial repository search when configured.
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)
Update implements tea.Model and advances the model-manager workflow.
func (m Model) View() string
View implements tea.Model and renders the current model-manager screen.
ModelFile describes one exact repository artifact.
type ModelFile struct {
Path string `json:"path"`
Size int64 `json:"sizeBytes"`
ETag string `json:"etag,omitempty"`
LFSOID string `json:"lfsOid,omitempty"`
Quantization string `json:"quantization,omitempty"`
}
func FilterFiles(files []ModelFile, include, exclude, preferred []string, revealAll bool) []ModelFile
FilterFiles applies configured globs, defaults to GGUF when available, and stably promotes preferred quantizations.
func ShardSet(selected ModelFile, files []ModelFile) (string, []ModelFile, error)
ShardSet returns the common stem and complete shard set for selected. A non-sharded file is returned as a one-file set.
ProgressFunc receives download progress updates.
type ProgressFunc func(ProgressUpdate)
ProgressUpdate reports transfer progress for one artifact.
type ProgressUpdate struct {
Phase TransferPhase
CompletedBytes, TotalBytes int64
}
Screen identifies the current page in the interactive model manager.
type Screen int
const (
// ScreenQuery is the repository search page.
ScreenQuery Screen = iota
// ScreenSearching indicates that a repository search is in progress.
ScreenSearching
// ScreenRepositories displays matching repositories.
ScreenRepositories
// ScreenLoadingFiles indicates that repository files are being fetched.
ScreenLoadingFiles
// ScreenFiles displays selectable model files.
ScreenFiles
// ScreenConfirm asks for download confirmation.
ScreenConfirm
// ScreenDownloading indicates that selected files are being downloaded.
ScreenDownloading
// ScreenComplete indicates a successful download.
ScreenComplete
// ScreenError displays an operation error.
ScreenError
)
SearchResult is a stable project-owned representation of a Hub repository.
type SearchResult struct {
SchemaVersion int `json:"schemaVersion"`
ID string `json:"id"`
Revision string `json:"revision,omitempty"`
Provider string `json:"provider"`
Downloads int64 `json:"downloads"`
Likes int64 `json:"likes"`
LastModified time.Time `json:"lastModified,omitempty"`
Gated bool `json:"gated"`
Private bool `json:"private"`
}
func SearchRanked(ctx context.Context, client HubClient, query string, limit int, providers []string) ([]SearchResult, error)
SearchRanked performs bounded searches and stably promotes preferred authors.
TransferPhase identifies the stage represented by a ProgressUpdate.
type TransferPhase string
const (
// PhaseDownloading indicates that artifact bytes are being transferred.
PhaseDownloading TransferPhase = "downloading"
// PhaseValidating indicates that a downloaded artifact is being hashed.
PhaseValidating TransferPhase = "validating"
)
UpdateState describes whether an installed artifact has a newer remote revision.
type UpdateState string
const (
// Current indicates that the installed revision matches the remote revision.
Current UpdateState = "CURRENT"
// UpdateAvailable indicates that a newer remote revision exists.
UpdateAvailable UpdateState = "UPDATE AVAILABLE"
// RemoteMissing indicates that the installed file is absent remotely.
RemoteMissing UpdateState = "REMOTE MISSING"
// UpdateUnknown indicates that the remote revision could not be compared.
UpdateUnknown UpdateState = "UNKNOWN"
)
func CheckUpdate(installed Installation, revision string, files []ModelFile) UpdateState
CheckUpdate compares an installed artifact with the selected remote files.
Verification contains the result of checking an installed artifact digest.
type Verification struct {
SchemaVersion int `json:"schemaVersion"`
Model string `json:"model"`
ExpectedSHA256 string `json:"expectedSha256"`
ActualSHA256 string `json:"actualSha256,omitempty"`
Status string `json:"status"`
SizeBytes int64 `json:"sizeBytes"`
}
func Verify(ctx context.Context, installation Installation) (Verification, error)
Verify hashes installation and compares it with the recorded manifest digest.
Generated by gomarkdoc