lmsdk

package module
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Apr 19, 2026 License: GPL-3.0 Imports: 34 Imported by: 0

README

lm-agent-sdk-go

Go SDK for building agentic applications backed by a local LM Studio server — the OpenAI-compatible /v1/* surface plus LM Studio's native /api/v0/* endpoints for richer model metadata, performance stats, and llama.cpp-era sampling controls.

  • Package: lmsdk
  • Default backend: http://127.0.0.1:1234/v1

Install

go get github.com/ethpandaops/lm-agent-sdk-go

Configuration

The SDK resolves configuration from explicit options first, then environment variables, then defaults.

Environment Variables
Variable Description Default
LM_BASE_URL LM Studio server base URL http://127.0.0.1:1234/v1
LM_API_KEY Bearer auth token (optional, only if your server enforces auth) (none)
LM_MODEL Model name (none — must be set via env or WithModel())
LM_AGENT_SESSION_STORE_PATH Local session store directory (none)
Option Precedence
  1. Explicit option (e.g. WithBaseURL(...), WithAPIKey(...), WithModel(...))
  2. Environment variable (LM_BASE_URL, LM_API_KEY, LM_MODEL)
  3. Built-in default (where applicable)
LM Studio server setup

Run the server via the Developer tab of the LM Studio desktop app, or headless:

lms server start
# or headless daemon
lms daemon up

API authentication is off by default. To enable bearer auth, toggle "Require Authentication" in Developer → Server Settings and generate a token in "Manage Tokens".

Developer Workflow

The repo ships a sibling-style Makefile:

  • make test runs race-enabled package tests with coverage output.
  • make test-integration runs ./integration/... with -tags=integration.
  • make audit runs the aggregate quality gate.

Integration setup:

  • Set LM_BASE_URL or default to http://127.0.0.1:1234/v1.
  • Set LM_MODEL to a model loaded (or JIT-loadable) in LM Studio.
  • Set LM_API_KEY if auth is enabled.
  • Integration tests skip when the local LM Studio server is unavailable.

Quick Start

package main

import (
	"context"
	"fmt"
	"time"

	lmsdk "github.com/ethpandaops/lm-agent-sdk-go"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()

	for msg, err := range lmsdk.Query(
		ctx,
		lmsdk.Text("Write a two-line haiku about Go concurrency."),
		// lmsdk.WithModel("qwen/qwen3.6-35b-a3b"),
	) {
		if err != nil {
			panic(err)
		}

		if result, ok := msg.(*lmsdk.ResultMessage); ok && result.Result != nil {
			fmt.Println(*result.Result)
		}
	}
}

Surface

  • Query(ctx, content, ...opts) and QueryStream(...) return iter.Seq2[Message, error].
  • NewClient() exposes Start, StartWithContent, StartWithStream, Query, ReceiveMessages, ReceiveResponse, Interrupt, SetPermissionMode, SetModel, ListModels, ListModelsResponse, GetMCPStatus, RewindFiles, and Close.
  • Agent.Act(ctx, prompt, ...) mirrors the .act() multi-round tool loop from the official lmstudio-python/lmstudio-js SDKs.
  • NativeChatCompletions(ctx, prompt, ...) hits LM Studio's native /api/v0/chat/completions endpoint, returning Stats (tokens/sec, TTFT, stop reason, draft acceptance), ModelInfo (arch, quant, context length), and Runtime information alongside the usual assistant response.
  • UserMessageContent is the canonical input shape. Use Text(...) for text-only calls and Blocks(...) with ImageInput(...), FileInput(...), AudioInput(...), or VideoInput(...) for multimodal chat-completions requests.
  • WithSDKTools(...) registers high-level in-process tools under mcp__sdk__<name>.
  • WithOnUserInput(...) handles SDK-owned user-input prompts built on top of tool calling.
  • ListModels(...) and ListModelsResponse(...) use LM Studio's native /api/v0/models discovery (falls back to /v1/models if unavailable).
  • StatSession(...), ListSessions(...), and GetSessionMessages(...) operate on the SDK's local persisted session store.

LM Studio-specific options

Option Effect
WithTTL(duration) Sets ttl (seconds) — how long a JIT-loaded model stays resident after the request.
WithDraftModel(id) Enables speculative decoding via a same-family draft model.
WithMinP(v) llama.cpp min_p sampling.
WithRepeatPenalty(v) llama.cpp repeat_penalty.
WithStreamUsage(bool) Toggles stream_options.include_usage (defaults to true).

Model Discovery

  • Discovery uses /api/v0/models, falling back to /v1/models if the native path is unavailable.
  • ModelInfo exposes LM-Studio-specific fields (Publisher, Quantization, CompatibilityType, State, Capabilities) alongside the generic helpers such as SupportsToolCalling(), SupportsStructuredOutput(), SupportsReasoning(), SupportsImageInput(), MaxContextLength(), and parsed pricing helpers.

Multimodal Input

content := lmsdk.Blocks(
	lmsdk.TextInput("Describe these two screenshots."),
	lmsdk.ImageInput("https://example.com/before.png"),
	lmsdk.ImageInput("data:image/png;base64,..."),
)

for msg, err := range lmsdk.Query(ctx, content) {
	_ = msg
	_ = err
}

Image formats: JPEG, PNG, WebP. PDFs passed via image_url are rejected by LM Studio — pre-render to image client-side.

Agent.Act

agent := &lmsdk.Agent{
    Model:     "qwen/qwen3.6-35b-a3b",
    Tools:     []lmsdk.Tool{sqrtTool, addTool},
    MaxRounds: 6,
}
result, err := agent.Act(ctx, "Compute sqrt(144) then add 7.")
// result.Text: "The final number is 19."
// result.ToolCalls: 2

See examples/agent_act for the full calculator demo.

Session Semantics

Session APIs are local SDK APIs, not remote server sessions.

  • They read from the SDK session store configured with WithSessionStorePath(...) or LM_AGENT_SESSION_STORE_PATH.
  • They do not derive from chat session_id.
  • They are independent of LM Studio's stateful /api/v1/chat endpoint.

Observability

The SDK provides opt-in OpenTelemetry metrics and distributed tracing. When no provider is configured all recording is a pure noop — zero overhead.

Options
Option Description
WithMeterProvider(mp) Sets an OTel metric.MeterProvider for SDK metrics
WithTracerProvider(tp) Sets an OTel trace.TracerProvider for SDK spans
WithPrometheusRegisterer(reg) Convenience: creates an OTel MeterProvider backed by a Prometheus Registerer
Metrics

GenAI semantic convention metrics:

Metric Type Description
gen_ai.client.operation.duration Histogram (s) Duration of query operations
gen_ai.client.token.usage Counter Token usage by type (input/output)
gen_ai.client.time_to_first_token Histogram (s) Time to first content token
gen_ai.client.time_per_output_token Histogram (s) Inter-token arrival time

SDK-specific metrics (namespace: lmstudio.*):

Metric Type Description
lmstudio.http.requests Counter HTTP requests by status class and retry
lmstudio.tool.calls Counter Tool calls by name and outcome
lmstudio.tool.duration Histogram (s) Tool call duration
lmstudio.checkpoint.operations Counter Checkpoint create/restore operations
lmstudio.hook.duration Histogram (s) Hook execution duration by event
Prometheus Example
reg := prometheus.NewRegistry()

for msg, err := range lmsdk.Query(ctx,
    lmsdk.Text("Hello"),
    lmsdk.WithPrometheusRegisterer(reg),
    lmsdk.WithModel("qwen/qwen3.6-35b-a3b"),
) {
    // ...
}

// Serve metrics
http.Handle("/metrics", promhttp.HandlerFor(reg, promhttp.HandlerOpts{}))

See examples/prometheus_observability for a complete working example.

Known LM Studio quirks the SDK handles

  • Bug #619: LM Studio serves the currently-loaded model regardless of the model field when only one is loaded. Validate via ListModelsResponse if you need strict model selection.
  • Bug #618: A 200 OK may still carry {"error": ...}. The transport detects this and surfaces it as an error.
  • 0.3.23 rename: The reasoning_content field was renamed to reasoning. The event mapper accepts both.
  • Default 300s server timeout: Prefer streaming for long completions.

Examples

Runnable examples live under examples. Highlights:

  • quick_start — minimal one-shot query
  • client_multi_turn — stateful client
  • agent_act — multi-round autonomous tool loop
  • lmstudio_sampling — LM Studio-flavoured sampling + TTL
  • lmstudio_native_stats — /api/v0 stats, model_info, runtime surface
  • mcp_calculator, sdk_tools, memory_tool — MCP + in-process tools
  • sessions_local — persist/resume SDK sessions
  • prometheus_observability — OTel + Prometheus export

Documentation

Overview

Package lmsdk provides agent ergonomics backed by LM Studio.

Index

Constants

View Source 
const (
	ReasoningOff    = lmstudio.ReasoningOff
	ReasoningLow    = lmstudio.ReasoningLow
	ReasoningMedium = lmstudio.ReasoningMedium
	ReasoningHigh   = lmstudio.ReasoningHigh
	ReasoningOn     = lmstudio.ReasoningOn
)

Reasoning effort levels. Availability per model is advertised in `capabilities.reasoning.allowed_options` on /api/v1/models.

View Source 
const (
	// EffortLow uses minimal thinking.
	EffortLow = config.EffortLow
	// EffortMedium uses moderate thinking.
	EffortMedium = config.EffortMedium
	// EffortHigh uses deep thinking.
	EffortHigh = config.EffortHigh
	// EffortMax uses maximum thinking depth.
	EffortMax = config.EffortMax
)
View Source 
const (
	// AssistantMessageErrorAuthFailed indicates authentication failure.
	AssistantMessageErrorAuthFailed = message.AssistantMessageErrorAuthFailed
	// AssistantMessageErrorBilling indicates a billing error.
	AssistantMessageErrorBilling = message.AssistantMessageErrorBilling
	// AssistantMessageErrorRateLimit indicates rate limiting.
	AssistantMessageErrorRateLimit = message.AssistantMessageErrorRateLimit
	// AssistantMessageErrorInvalidReq indicates an invalid request.
	AssistantMessageErrorInvalidReq = message.AssistantMessageErrorInvalidReq
	// AssistantMessageErrorServer indicates a server error.
	AssistantMessageErrorServer = message.AssistantMessageErrorServer
	// AssistantMessageErrorUnknown indicates an unknown error.
	AssistantMessageErrorUnknown = message.AssistantMessageErrorUnknown
)
View Source 
const (
	// BlockTypeText contains plain text content.
	BlockTypeText = message.BlockTypeText
	// BlockTypeImage contains generated image output content.
	BlockTypeImage = message.BlockTypeImage
	// BlockTypeImageURL contains input image URL or data-url content.
	BlockTypeImageURL = message.BlockTypeImageURL
	// BlockTypeFile contains input file content.
	BlockTypeFile = message.BlockTypeFile
	// BlockTypeInputAudio contains input audio content.
	BlockTypeInputAudio = message.BlockTypeInputAudio
	// BlockTypeVideoURL contains input video URL or data-url content.
	BlockTypeVideoURL = message.BlockTypeVideoURL
	// BlockTypeThinking contains model reasoning content.
	BlockTypeThinking = message.BlockTypeThinking
	// BlockTypeToolUse contains tool-call content.
	BlockTypeToolUse = message.BlockTypeToolUse
	// BlockTypeToolResult contains tool-result content.
	BlockTypeToolResult = message.BlockTypeToolResult
)
View Source 
const (
	// HookEventPreToolUse is triggered before a tool is used.
	HookEventPreToolUse = hook.EventPreToolUse
	// HookEventPostToolUse is triggered after a tool is used.
	HookEventPostToolUse = hook.EventPostToolUse
	// HookEventUserPromptSubmit is triggered when a user submits a prompt.
	HookEventUserPromptSubmit = hook.EventUserPromptSubmit
	// HookEventStop is triggered when a session stops.
	HookEventStop = hook.EventStop
	// HookEventSubagentStop is triggered when a subagent stops.
	HookEventSubagentStop = hook.EventSubagentStop
	// HookEventPreCompact is triggered before compaction.
	HookEventPreCompact = hook.EventPreCompact
	// HookEventPostToolUseFailure is triggered after a tool use fails.
	HookEventPostToolUseFailure = hook.EventPostToolUseFailure
	// HookEventNotification is triggered when a notification is sent.
	HookEventNotification = hook.EventNotification
	// HookEventSubagentStart is triggered when a subagent starts.
	HookEventSubagentStart = hook.EventSubagentStart
	// HookEventPermissionRequest is triggered when a permission is requested.
	HookEventPermissionRequest = hook.EventPermissionRequest
)
View Source 
const (
	// PermissionModeDefault uses standard permission prompts.
	PermissionModeDefault = permission.ModeDefault
	// PermissionModeAcceptEdits automatically accepts file edits.
	PermissionModeAcceptEdits = permission.ModeAcceptEdits
	// PermissionModePlan enables plan mode for implementation planning.
	PermissionModePlan = permission.ModePlan
	// PermissionModeBypassPermissions bypasses all permission checks.
	PermissionModeBypassPermissions = permission.ModeBypassPermissions
)
View Source 
const (
	// PermissionUpdateTypeAddRules adds new permission rules.
	PermissionUpdateTypeAddRules = permission.UpdateTypeAddRules
	// PermissionUpdateTypeReplaceRules replaces existing permission rules.
	PermissionUpdateTypeReplaceRules = permission.UpdateTypeReplaceRules
	// PermissionUpdateTypeRemoveRules removes permission rules.
	PermissionUpdateTypeRemoveRules = permission.UpdateTypeRemoveRules
	// PermissionUpdateTypeSetMode sets the permission mode.
	PermissionUpdateTypeSetMode = permission.UpdateTypeSetMode
	// PermissionUpdateTypeAddDirectories adds accessible directories.
	PermissionUpdateTypeAddDirectories = permission.UpdateTypeAddDirectories
	// PermissionUpdateTypeRemoveDirectories removes accessible directories.
	PermissionUpdateTypeRemoveDirectories = permission.UpdateTypeRemoveDirectories
)
View Source 
const (
	// PermissionUpdateDestUserSettings stores in user-level settings.
	PermissionUpdateDestUserSettings = permission.UpdateDestUserSettings
	// PermissionUpdateDestProjectSettings stores in project-level settings.
	PermissionUpdateDestProjectSettings = permission.UpdateDestProjectSettings
	// PermissionUpdateDestLocalSettings stores in local-level settings.
	PermissionUpdateDestLocalSettings = permission.UpdateDestLocalSettings
	// PermissionUpdateDestSession stores in the current session only.
	PermissionUpdateDestSession = permission.UpdateDestSession
)
View Source 
const (
	// PermissionBehaviorAllow automatically allows the operation.
	PermissionBehaviorAllow = permission.BehaviorAllow
	// PermissionBehaviorDeny automatically denies the operation.
	PermissionBehaviorDeny = permission.BehaviorDeny
	// PermissionBehaviorAsk prompts the user for permission.
	PermissionBehaviorAsk = permission.BehaviorAsk
)
View Source 
const (
	// MCPServerTypeStdio uses stdio for communication.
	MCPServerTypeStdio = mcp.ServerTypeStdio
	// MCPServerTypeSSE uses Server-Sent Events.
	MCPServerTypeSSE = mcp.ServerTypeSSE
	// MCPServerTypeHTTP uses HTTP for communication.
	MCPServerTypeHTTP = mcp.ServerTypeHTTP
	// MCPServerTypeSDK uses the SDK interface.
	MCPServerTypeSDK = mcp.ServerTypeSDK
)
View Source 
const Version = "0.1.0"

Version is the SDK version.

Variables

View Source 
var (
	// ErrClientNotConnected indicates the client is not connected.
	ErrClientNotConnected = internalerrors.ErrClientNotConnected

	// ErrClientAlreadyConnected indicates the client is already connected.
	ErrClientAlreadyConnected = internalerrors.ErrClientAlreadyConnected

	// ErrClientClosed indicates the client has been closed and cannot be reused.
	ErrClientClosed = internalerrors.ErrClientClosed

	// ErrTransportNotConnected indicates the transport is not connected.
	ErrTransportNotConnected = internalerrors.ErrTransportNotConnected

	// ErrRequestTimeout indicates a request timed out.
	ErrRequestTimeout = internalerrors.ErrRequestTimeout

	// ErrSessionNotFound indicates a requested local session does not exist.
	ErrSessionNotFound = internalerrors.ErrSessionNotFound

	// ErrUnsupportedFeature indicates an API-compatible feature that is not implemented by this backend.
	ErrUnsupportedFeature = errors.New("unsupported feature in LM Studio backend")

	// ErrUnsupportedControl indicates a control-plane operation is not supported by backend.
	ErrUnsupportedControl = controlplane.ErrUnsupportedControl

	// ErrNoCheckpoint indicates rewind was requested without an available checkpoint.
	ErrNoCheckpoint = session.ErrNoCheckpoint
)

Re-export sentinel errors from internal package.

View Source 
var NewUserMessageContent = message.NewUserMessageContent

NewUserMessageContent creates UserMessageContent from a string.

View Source 
var NewUserMessageContentBlocks = message.NewUserMessageContentBlocks

NewUserMessageContentBlocks creates UserMessageContent from blocks.

Functions

func ErrorResult 

func ErrorResult(message string) *mcp.CallToolResult

ErrorResult creates a CallToolResult indicating an error.

func ImageResult 

func ImageResult(data []byte, mimeType string) *mcp.CallToolResult

ImageResult creates a CallToolResult with image content.

func MessagesFromChannel 

func MessagesFromChannel(ch <-chan StreamingMessage) iter.Seq[StreamingMessage]

MessagesFromChannel creates a MessageStream from a channel. This is useful for dynamic message generation where messages are produced over time. The iterator completes when the channel is closed.

func MessagesFromContent 

func MessagesFromContent(content UserMessageContent) iter.Seq[StreamingMessage]

MessagesFromContent creates a single-message stream from user content.

func MessagesFromSlice 

func MessagesFromSlice(msgs []StreamingMessage) iter.Seq[StreamingMessage]

MessagesFromSlice creates a MessageStream from a slice of StreamingMessages. This is useful for sending a fixed set of messages in streaming mode.

func NewMcpTool 

func NewMcpTool(name, description string, inputSchema *jsonschema.Schema) *mcp.Tool

NewMcpTool creates an mcp.Tool with the given parameters. This is useful when you need direct access to the MCP Tool type.

func NopLogger 

func NopLogger() *slog.Logger

NopLogger returns a logger that discards all output. Use this when you want silent operation with no logging overhead.

func ParseArguments 

func ParseArguments(req *mcp.CallToolRequest) (map[string]any, error)

ParseArguments unmarshals CallToolRequest arguments into a map. This is a convenience function for extracting tool input.

func Query 

func Query(
	ctx context.Context,
	content UserMessageContent,
	opts ...Option,
) iter.Seq2[Message, error]

Query executes a one-shot query and returns a message iterator.

func QueryStream 

func QueryStream(
	ctx context.Context,
	messages iter.Seq[StreamingMessage],
	opts ...Option,
) iter.Seq2[Message, error]

QueryStream executes a one-shot query from a stream of user messages.

func SimpleSchema 

func SimpleSchema(props map[string]string) *jsonschema.Schema

SimpleSchema creates a jsonschema.Schema from a simple type map.

Input format: {"a": "float64", "b": "string"}

Type mappings:

  • "string" → {"type": "string"}
  • "int", "int64" → {"type": "integer"}
  • "float64", "float" → {"type": "number"}
  • "bool" → {"type": "boolean"}
  • "[]string" → {"type": "array", "items": {"type": "string"}}
  • "any", "object" → {"type": "object"}

func SingleMessage 

func SingleMessage(content UserMessageContent) iter.Seq[StreamingMessage]

SingleMessage creates a MessageStream with a single user message.

func TextResult 

func TextResult(text string) *mcp.CallToolResult

TextResult creates a CallToolResult with text content.

func UnloadModel 

func UnloadModel(ctx context.Context, instanceID string, opts ...Option) error

UnloadModel unloads a previously-loaded instance via POST /api/v1/models/unload. The ID is the value returned from LoadModel or present in ListModelsResponse's loaded-instance payload.

func Validate 

func Validate(schema, input map[string]any) error

Validate checks if the input matches the schema requirements. Returns an error if required fields are missing.

func WithClient 

func WithClient(ctx context.Context, fn func(Client) error, opts ...Option) error

WithClient manages client lifecycle with automatic cleanup.

This helper creates a client, starts it with the provided options, executes the callback function, and ensures proper cleanup via Close() when done.

The callback receives a fully initialized Client that is ready for use. If the callback returns an error, it is returned to the caller. If Close() fails, a warning is logged but does not override the callback's error.

Example usage: 

err := lmsdk.WithClient(ctx, func(c lmsdk.Client) error {
    if err := c.Query(ctx, Text("Hello")); err != nil {
        return err
    }
    for msg, err := range c.ReceiveResponse(ctx) {
        if err != nil {
            return err
        }
        // process message...
    }
    return nil
},
    lmsdk.WithLogger(log),
    lmsdk.WithPermissionMode("acceptEdits"),
)

Types

type ActResult 

type ActResult struct {
	// Text is the final assistant text. Empty if the agent stopped without
	// emitting text (e.g. tool-only turns or errors).
	Text string
	// ToolCalls counts the total tool invocations during the run.
	ToolCalls int
	// Rounds counts the number of assistant messages observed.
	Rounds int
	// StopReason carries the terminal finish_reason when available.
	StopReason string
}

ActResult summarizes the outcome of an Agent.Act call.

type Agent 

type Agent struct {
	// Model is the target LM Studio model ID. Required.
	Model string
	// Tools are SDK tools registered as an in-process MCP server.
	Tools []Tool
	// MaxRounds caps the number of tool-use loops. Zero means use the
	// SDK default (MaxToolIterations, currently 8).
	MaxRounds int
	// ExtraOptions are passed through verbatim to Query on every Act call,
	// allowing callers to set temperature/stop/etc. once at construction.
	ExtraOptions []Option
}

Agent wraps a minimal multi-round tool loop — the `.act()` shape familiar to users of the official lmstudio-python and lmstudio-js SDKs. It drives the existing SDK tool loop until the model stops emitting tool calls.

Agent.Act is a thin convenience on top of Query + WithSDKTools and is appropriate for single-shot agent runs. For long-lived multi-turn conversations, use NewClient directly.

func (*Agent) Act 

func (a *Agent) Act(ctx context.Context, prompt string, opts ...Option) (*ActResult, error)

Act runs a single agent turn starting from the given prompt. The agent will iterate through tool calls up to MaxRounds times, returning once the model produces a terminal (non-tool) assistant response. Tool output is surfaced through the registered Tool.Execute callbacks and fed back to the model automatically.

type AgentOptions 

type AgentOptions = config.Options

AgentOptions configures SDK and LM Studio request behavior.

type AssistantMessage 

type AssistantMessage = message.AssistantMessage

AssistantMessage represents a message from the model.

type AssistantMessageError 

type AssistantMessageError = message.AssistantMessageError

AssistantMessageError represents error types from the assistant.

type AsyncHookJSONOutput 

type AsyncHookJSONOutput = hook.AsyncJSONOutput

AsyncHookJSONOutput represents an async hook output.

type BaseHookInput 

type BaseHookInput = hook.BaseInput

BaseHookInput contains common fields for all hook inputs.

type CallToolRequest 

type CallToolRequest = mcp.CallToolRequest

CallToolRequest is the request passed to tool handlers.

type CallToolResult 

type CallToolResult = mcp.CallToolResult

CallToolResult is the server's response to a tool call. Use TextResult, ErrorResult, or ImageResult helpers to create results.

type ChatRequest 

type ChatRequest = config.ChatRequest

ChatRequest is the normalized request sent through a Transport.

type Client 

type Client interface {
	// Start initializes the client runtime.
	// Must be called before any other methods.
	// Returns a transport/runtime error on failure.
	Start(ctx context.Context, opts ...Option) error

	// StartWithContent initializes the runtime and immediately sends initial user content.
	// Equivalent to calling Start() followed by Query(ctx, content).
	// The content is sent to the "default" session.
	// Returns a transport/runtime error on failure.
	StartWithContent(ctx context.Context, content UserMessageContent, opts ...Option) error

	// StartWithStream initializes the runtime and consumes the provided input iterator
	// as the initial message stream for the active session.
	// The iterator is consumed in a separate goroutine; use context cancellation to abort.
	// Returns a transport/runtime error on failure.
	StartWithStream(ctx context.Context, messages iter.Seq[StreamingMessage], opts ...Option) error

	// Query sends user content to the active session.
	// Returns immediately after sending; use ReceiveMessages() or ReceiveResponse() to get responses.
	// Optional sessionID defaults to "default" for multi-session support.
	Query(ctx context.Context, content UserMessageContent, sessionID ...string) error

	// ReceiveMessages returns an iterator that yields messages indefinitely.
	// Messages are yielded as they arrive until EOF, an error occurs, or context is cancelled.
	// Unlike ReceiveResponse, this iterator does not stop at ResultMessage.
	// Use iter.Pull2 if you need pull-based iteration instead of range.
	ReceiveMessages(ctx context.Context) iter.Seq2[Message, error]

	// ReceiveResponse returns an iterator that yields messages until a ResultMessage is received.
	// Messages are yielded as they arrive for streaming consumption.
	// The iterator stops after yielding the ResultMessage.
	// Use iter.Pull2 if you need pull-based iteration instead of range.
	// To collect all messages into a slice, use slices.Collect or a simple loop.
	ReceiveResponse(ctx context.Context) iter.Seq2[Message, error]

	// Interrupt cancels the current in-flight request.
	Interrupt(ctx context.Context) error

	// SetPermissionMode changes the permission mode during conversation.
	// Valid modes: "default", "acceptEdits", "plan", "bypassPermissions"
	SetPermissionMode(ctx context.Context, mode string) error

	// SetModel changes the AI model during conversation.
	// Pass nil to use the default model.
	SetModel(ctx context.Context, model *string) error

	// ListModels returns the available LM Studio models using the current client options.
	ListModels(ctx context.Context) ([]ModelInfo, error)

	// ListModelsResponse returns the full LM Studio model discovery payload.
	ListModelsResponse(ctx context.Context) (*ModelListResponse, error)

	// GetServerInfo returns runtime metadata for the active client session.
	// Returns nil when the client is not connected.
	GetServerInfo() map[string]any

	// GetMCPStatus returns MCP server connection status for the current runtime.
	// Returns the status of all configured MCP servers.
	GetMCPStatus(ctx context.Context) (*MCPStatus, error)

	// ReconnectMCPServer reconnects a disconnected or failed MCP server.
	ReconnectMCPServer(ctx context.Context, serverName string) error

	// ToggleMCPServer enables or disables an MCP server.
	ToggleMCPServer(ctx context.Context, serverName string, enabled bool) error

	// StopTask stops a running task by task ID.
	StopTask(ctx context.Context, taskID string) error

	// RewindFiles rewinds tracked files to their state at a specific user message.
	// The userMessageID should be the ID of a previous user message in the conversation.
	// Requires EnableFileCheckpointing=true in AgentOptions.
	RewindFiles(ctx context.Context, userMessageID string) error

	// SendToolResult sends a tool result for a pending tool call.
	SendToolResult(ctx context.Context, toolUseID, content string, isError bool) error

	// Close terminates the session and cleans up resources.
	// After Close(), the client cannot be reused. Safe to call multiple times.
	Close() error
}

Client provides an interactive, stateful interface for multi-turn LM Studio conversations.

Unlike the one-shot Query() function, Client maintains session state across multiple exchanges. It supports interruption, tool loops, and local session state.

Lifecycle: clients are single-use. After Close(), create a new client with NewClient().

Example usage: 

client := NewClient()
defer func() { _ = client.Close() }()

err := client.Start(ctx,
    WithLogger(slog.Default()),
    WithPermissionMode("acceptEdits"),
)
if err != nil {
    log.Fatal(err)
}

// Send a query
err = client.Query(ctx, NewUserMessageContent("What is 2+2?"))
if err != nil {
    log.Fatal(err)
}

// Receive all messages for this response (stops at ResultMessage)
for msg, err := range client.ReceiveResponse(ctx) {
    if err != nil {
        log.Fatal(err)
    }
    // Process message...
}

// Or receive messages indefinitely (for continuous streaming)
for msg, err := range client.ReceiveMessages(ctx) {
    if err != nil {
        break
    }
    // Process message...
}

func NewClient 

func NewClient() Client

NewClient creates a new interactive client.

Call Start() with options to begin a session: 

client := NewClient()
err := client.Start(ctx,
    WithLogger(slog.Default()),
    WithPermissionMode("acceptEdits"),
)

type ContentBlock 

type ContentBlock = message.ContentBlock

ContentBlock represents a block of content within a message.

type DownloadRequest 

type DownloadRequest = lmstudio.DownloadRequest

DownloadRequest is the request body for DownloadModel.

type DownloadResponse 

type DownloadResponse = lmstudio.DownloadResponse

DownloadResponse is returned by DownloadModel with the job ID for polling.

func DownloadModel 

func DownloadModel(ctx context.Context, req DownloadRequest, opts ...Option) (*DownloadResponse, error)

DownloadModel starts an async download from LM Studio's catalog or Hugging Face via POST /api/v1/models/download. Returns the job ID; poll DownloadStatusFor to watch progress.

type DownloadStatus 

type DownloadStatus = lmstudio.DownloadStatus

DownloadStatus reports progress for an in-flight download.

func DownloadStatusFor 

func DownloadStatusFor(ctx context.Context, jobID string, opts ...Option) (*DownloadStatus, error)

DownloadStatusFor polls a download job's progress via GET /api/v1/models/download/status?job_id=...

type Effort 

type Effort = config.Effort

Effort controls thinking depth.

type HookCallback 

type HookCallback = hook.Callback

HookCallback is the function signature for hook callbacks.

type HookContext 

type HookContext = hook.Context

HookContext provides context for hook execution.

type HookEvent 

type HookEvent = hook.Event

HookEvent represents the type of event that triggers a hook.

type HookInput 

type HookInput = hook.Input

HookInput is the interface for all hook input types.

type HookJSONOutput 

type HookJSONOutput = hook.JSONOutput

HookJSONOutput is the interface for hook output types.

type HookMatcher 

type HookMatcher = hook.Matcher

HookMatcher configures which tools/events a hook applies to.

type HookSpecificOutput 

type HookSpecificOutput = hook.SpecificOutput

HookSpecificOutput is the interface for hook-specific outputs.

type ImageBlock 

type ImageBlock = message.ImageBlock

ImageBlock contains a generated image reference.

type InputAudioBlock 

type InputAudioBlock = message.InputAudioBlock

InputAudioBlock contains an input audio payload for multimodal prompts.

func AudioInput 

func AudioInput(format, data string) *InputAudioBlock

AudioInput creates an input audio block from base64 audio plus its format.

type InputAudioRef 

type InputAudioRef = message.InputAudioRef

InputAudioRef contains base64-encoded input audio plus its format.

type InputFileBlock 

type InputFileBlock = message.InputFileBlock

InputFileBlock contains an input file reference for multimodal prompts.

func FileInput 

func FileInput(filename, fileData string) *InputFileBlock

FileInput creates an input file block from a URL or data URL.

type InputFileRef 

type InputFileRef = message.InputFileRef

InputFileRef identifies an input file URL or data URL.

type InputImageBlock 

type InputImageBlock = message.InputImageBlock

InputImageBlock contains an input image reference for multimodal prompts.

func ImageInput 

func ImageInput(url string) *InputImageBlock

ImageInput creates an input image block from a URL or data URL.

type InputImageRef 

type InputImageRef = message.InputImageRef

InputImageRef identifies an input image URL or data URL.

type InputVideoBlock 

type InputVideoBlock = message.InputVideoBlock

InputVideoBlock contains an input video reference for multimodal prompts.

func VideoInput 

func VideoInput(url string) *InputVideoBlock

VideoInput creates an input video block from a URL or data URL.

type InputVideoRef 

type InputVideoRef = message.InputVideoRef

InputVideoRef identifies an input video URL or data URL.

type LoadConfig 

type LoadConfig = lmstudio.LoadConfig

LoadConfig mirrors the LM Studio `/api/v1/models/load` configuration surface. Fields are passthrough — see internal/lmstudio.LoadConfig for per-field docs.

type LoadRequest 

type LoadRequest = lmstudio.LoadRequest

LoadRequest is the request body for LoadModel.

type LoadResponse 

type LoadResponse = lmstudio.LoadResponse

LoadResponse describes a successfully loaded model instance.

func LoadModel 

func LoadModel(ctx context.Context, req LoadRequest, opts ...Option) (*LoadResponse, error)

LoadModel loads a model into LM Studio via POST /api/v1/models/load. Returns the loaded instance ID, which is required to later call UnloadModel.

type MCPHTTPServerConfig 

type MCPHTTPServerConfig = mcp.HTTPServerConfig

MCPHTTPServerConfig configures an HTTP-based MCP server.

type MCPSSEServerConfig 

type MCPSSEServerConfig = mcp.SSEServerConfig

MCPSSEServerConfig configures a Server-Sent Events MCP server.

type MCPSdkServerConfig 

type MCPSdkServerConfig = mcp.SdkServerConfig

MCPSdkServerConfig configures an SDK-provided MCP server.

func CreateSdkMcpServer 

func CreateSdkMcpServer(name, version string, tools ...*SdkMcpTool) *MCPSdkServerConfig

CreateSdkMcpServer creates an in-process MCP server configuration with SdkMcpTool tools.

This function creates an MCP server that runs within your application, providing better performance than external MCP servers.

The returned config can be used directly in AgentOptions.MCPServers: 

addTool := lmsdk.NewSdkMcpTool("add", "Add two numbers",
    lmsdk.SimpleSchema(map[string]string{"a": "float64", "b": "float64"}),
    func(ctx context.Context, req *lmsdk.CallToolRequest) (*lmsdk.CallToolResult, error) {
        args, _ := lmsdk.ParseArguments(req)
        a, b := args["a"].(float64), args["b"].(float64)
        return lmTextResult(fmt.Sprintf("Result: %v", a+b)), nil
    },
)

calculator := lmsdk.CreateSdkMcpServer("calculator", "1.0.0", addTool)

options := &lmsdk.AgentOptions{
    MCPServers: map[string]lmsdk.MCPServerConfig{
        "calculator": calculator,
    },
    AllowedTools: []string{"mcp__calculator__add"},
}

Parameters:

  • name: Server name (also used as key in MCPServers map, determines tool naming: mcp__<name>__<toolName>)
  • version: Server version string
  • tools: SdkMcpTool instances to register with the server

type MCPServerConfig 

type MCPServerConfig = mcp.ServerConfig

MCPServerConfig is the interface for MCP server configurations.

type MCPServerStatus 

type MCPServerStatus = mcp.ServerStatus

MCPServerStatus represents the connection status of a single MCP server.

type MCPServerType 

type MCPServerType = mcp.ServerType

MCPServerType represents the type of MCP server.

type MCPStatus 

type MCPStatus = mcp.Status

MCPStatus represents the connection status of all configured MCP servers.

type MCPStdioServerConfig 

type MCPStdioServerConfig = mcp.StdioServerConfig

MCPStdioServerConfig configures a stdio-based MCP server.

type McpAudioContent 

type McpAudioContent = mcp.AudioContent

McpAudioContent represents audio content in a tool result.

type McpContent 

type McpContent = mcp.Content

McpContent is the interface for content types in tool results.

type McpImageContent 

type McpImageContent = mcp.ImageContent

McpImageContent represents image content in a tool result.

type McpTextContent 

type McpTextContent = mcp.TextContent

McpTextContent represents text content in a tool result.

type McpTool 

type McpTool = mcp.Tool

McpTool represents an MCP tool definition from the official SDK.

type McpToolAnnotations 

type McpToolAnnotations = mcp.ToolAnnotations

McpToolAnnotations describes optional hints about tool behavior. Fields include ReadOnlyHint, DestructiveHint, IdempotentHint, OpenWorldHint, and Title.

type McpToolHandler 

type McpToolHandler = mcp.ToolHandler

McpToolHandler is the function signature for low-level tool handlers.

type Message 

type Message = message.Message

Message represents any message in the conversation.

func GetSessionMessages 

func GetSessionMessages(ctx context.Context, sessionID string, opts ...Option) ([]Message, error)

GetSessionMessages returns persisted local session messages.

type MessageParseError 

type MessageParseError = internalerrors.MessageParseError

MessageParseError indicates message parsing failed.

type MessageStream 

type MessageStream = iter.Seq[StreamingMessage]

MessageStream is an iterator that yields streaming messages.

type Model 

type Model = model.Model

Model is a stable provider-neutral projection of a discovered model.

type ModelArchitecture 

type ModelArchitecture = model.Architecture

ModelArchitecture describes the underlying model family where available.

type ModelEndpoint 

type ModelEndpoint = model.Endpoint

ModelEndpoint identifies an endpoint a model supports.

type ModelInfo 

type ModelInfo = model.Info

ModelInfo describes a model available from LM Studio discovery endpoints.

func ListModels 

func ListModels(ctx context.Context, opts ...Option) ([]ModelInfo, error)

ListModels returns the available vLLM-served models.

type ModelListResponse 

type ModelListResponse = model.ListResponse

ModelListResponse contains the full model discovery payload.

func ListModelsResponse 

func ListModelsResponse(ctx context.Context, opts ...Option) (*ModelListResponse, error)

ListModelsResponse returns the full vLLM model discovery payload.

type ModelPerRequestLimits 

type ModelPerRequestLimits = model.PerRequestLimits

ModelPerRequestLimits captures request limits where available.

type ModelPricing 

type ModelPricing = model.Pricing

ModelPricing contains pricing fields as returned by discovery endpoints.

type ModelSupportedParameters 

type ModelSupportedParameters = model.SupportedParameters

ModelSupportedParameters records provider-supported request parameters.

type ModelTopProvider 

type ModelTopProvider = model.TopProvider

ModelTopProvider describes provider-side limits and moderation behavior.

type NativeChoice 

type NativeChoice = lmstudio.NativeChoice

NativeChoice is a single choice in a NativeResponse.

type NativeMessage 

type NativeMessage = lmstudio.NativeMessage

NativeMessage is an assistant message inside a NativeChoice.

type NativeModelInfo 

type NativeModelInfo = lmstudio.NativeModelInfo

NativeModelInfo surfaces LM Studio's `/api/v0` response `model_info` object with architecture, quantization, and context length.

type NativeResponse 

type NativeResponse = lmstudio.NativeResponse

NativeResponse is the full response returned by NativeChatCompletions.

func NativeChatCompletions 

func NativeChatCompletions(ctx context.Context, prompt string, opts ...Option) (*NativeResponse, error)

NativeChatCompletions sends a non-streaming chat completion to LM Studio's native `/api/v0/chat/completions` endpoint. Unlike the OpenAI-compatible path, the response includes Stats (tokens/sec, TTFT), ModelInfo (arch, quant), and Runtime information — useful for observability and benchmarking without wiring OpenTelemetry.

type NativeRuntime 

type NativeRuntime = lmstudio.NativeRuntime

NativeRuntime surfaces LM Studio's `/api/v0` response `runtime` object describing the llama.cpp/MLX engine build in use.

type NativeStats 

type NativeStats = lmstudio.NativeStats

NativeStats surfaces LM Studio's `/api/v0` response `stats` object, exposing runtime performance metrics like tokens-per-second and time-to-first-token. When speculative decoding is enabled the draft acceptance counters are also populated.

type NativeUsage 

type NativeUsage = lmstudio.NativeUsage

NativeUsage is the usage block inside a NativeResponse.

type NotificationHookInput 

type NotificationHookInput = hook.NotificationInput

NotificationHookInput is the input for Notification hooks.

type NotificationHookSpecificOutput 

type NotificationHookSpecificOutput = hook.NotificationSpecificOutput

NotificationHookSpecificOutput is the hook-specific output for Notification.

type Option 

type Option func(*AgentOptions)

Option configures AgentOptions using the functional options pattern. This is the primary option type for configuring clients and queries.

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey sets the LM Studio API key directly.

func WithAllowedTools 

func WithAllowedTools(tools ...string) Option

WithAllowedTools sets pre-approved tools that can be used without prompting.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the LM Studio base URL.

func WithCanUseTool 

func WithCanUseTool(callback ToolPermissionCallback) Option

WithCanUseTool sets a callback for permission checking before each tool use.

func WithCwd 

func WithCwd(cwd string) Option

WithCwd sets the working directory used by local session and tool features.

func WithDisallowedTools 

func WithDisallowedTools(tools ...string) Option

WithDisallowedTools sets tools that are explicitly blocked.

func WithDraftModel 

func WithDraftModel(model string) Option

WithDraftModel sets the `draft_model` field enabling speculative decoding. The draft model must share the same vocabulary/tokenizer family as the primary model. See LM Studio's Speculative Decoding docs.

func WithEffort 

func WithEffort(effort config.Effort) Option

WithEffort sets the thinking effort level.

func WithEnableFileCheckpointing 

func WithEnableFileCheckpointing(enable bool) Option

WithEnableFileCheckpointing enables file change tracking and rewinding.

func WithExtra 

func WithExtra(extra map[string]any) Option

WithExtra merges raw request fields into the outgoing payload. Use for fields not covered by dedicated With* options.

func WithFallbackModel 

func WithFallbackModel(model string) Option

WithFallbackModel specifies a model to use if the primary model fails.

func WithForceTool 

func WithForceTool(name string) Option

WithForceTool forces the model to invoke a specific tool on the next turn. This is the LM-Studio-supported workaround for OpenAI's object-form tool_choice (see WithToolChoice): the SDK sets `tool_choice: "required"` and filters `tools[]` down to just the named tool for the outgoing request, so the model has no other function to call.

The tool must already be registered via WithSDKTools, WithMCPServers, or WithMCPConfig. Pass the full public name (e.g. `"mcp__sdk__add"`). Pass an empty string to clear a previously-set force.

func WithForkSession 

func WithForkSession(fork bool) Option

WithForkSession indicates whether to fork the resumed session to a new ID.

func WithFrequencyPenalty 

func WithFrequencyPenalty(v float64) Option

WithFrequencyPenalty sets frequency penalty.

func WithHTTPReferer 

func WithHTTPReferer(referer string) Option

WithHTTPReferer sets the HTTP-Referer header on outgoing requests.

func WithHooks 

func WithHooks(hooks map[HookEvent][]*HookMatcher) Option

WithHooks configures event hooks for tool interception.

func WithIncludePartialMessages 

func WithIncludePartialMessages(include bool) Option

WithIncludePartialMessages enables streaming of partial message updates.

func WithLogger 

func WithLogger(logger *slog.Logger) Option

WithLogger sets the logger for debug output. If not set, logging is disabled (silent operation).

func WithLogprobs 

func WithLogprobs(enable bool) Option

WithLogprobs enables token log probabilities where supported.

func WithMCPConfig 

func WithMCPConfig(config string) Option

WithMCPConfig sets a path to an MCP config file or a raw JSON string. If set, this takes precedence over WithMCPServers.

func WithMCPServers 

func WithMCPServers(servers map[string]MCPServerConfig) Option

WithMCPServers configures external MCP servers to connect to. Map key is the server name, value is the server configuration.

func WithMaxBudgetUSD 

func WithMaxBudgetUSD(budget float64) Option

WithMaxBudgetUSD sets a cost limit for the session in USD.

func WithMaxTokens 

func WithMaxTokens(max int) Option

WithMaxTokens sets chat max_tokens.

func WithMaxToolCalls 

func WithMaxToolCalls(max int) Option

WithMaxToolCalls sets the max_tool_calls field on outgoing requests.

func WithMaxToolIterations 

func WithMaxToolIterations(max int) Option

WithMaxToolIterations sets maximum tool-call loops per query.

func WithMaxTurns 

func WithMaxTurns(maxTurns int) Option

WithMaxTurns limits the maximum number of conversation turns.

func WithMeterProvider 

func WithMeterProvider(mp metric.MeterProvider) Option

WithMeterProvider sets an OpenTelemetry MeterProvider for recording SDK metrics. When nil (the default) all metric recording is a noop.

func WithMinP 

func WithMinP(minP float64) Option

WithMinP sets the llama.cpp min_p sampling parameter.

func WithModel 

func WithModel(model string) Option

WithModel specifies which LM Studio model to use.

func WithOnUserInput 

func WithOnUserInput(callback UserInputCallback) Option

WithOnUserInput sets a callback for handling SDK user-input tool prompts.

func WithOutputFormat 

func WithOutputFormat(format map[string]any) Option

WithOutputFormat specifies a JSON schema for structured output.

The canonical format uses a wrapper object: 

lmsdk.WithOutputFormat(map[string]any{
    "type": "json_schema",
    "schema": map[string]any{
        "type":       "object",
        "properties": map[string]any{...},
        "required":   []string{...},
    },
})

Raw JSON schemas (without the wrapper) are also accepted and auto-wrapped: 

lmsdk.WithOutputFormat(map[string]any{
    "type":       "object",
    "properties": map[string]any{...},
    "required":   []string{...},
})

Structured output is available on ResultMessage.StructuredOutput (parsed) or ResultMessage.Result (JSON string).

func WithParallelToolCalls 

func WithParallelToolCalls(enable bool) Option

WithParallelToolCalls sets parallel_tool_calls.

func WithPermissionMode 

func WithPermissionMode(mode string) Option

WithPermissionMode controls how permissions are handled. Valid values: "default", "acceptEdits", "plan", "bypassPermissions".

func WithPermissionPromptToolName 

func WithPermissionPromptToolName(name string) Option

WithPermissionPromptToolName specifies the tool name to use for permission prompts.

func WithPlugins 

func WithPlugins(plugins ...*SdkPluginConfig) Option

WithPlugins configures plugins to load.

func WithPresencePenalty 

func WithPresencePenalty(v float64) Option

WithPresencePenalty sets presence penalty.

func WithPrometheusRegisterer 

func WithPrometheusRegisterer(reg prometheus.Registerer) Option

WithPrometheusRegisterer configures the OTel-to-Prometheus bridge. When set, the SDK automatically creates a Prometheus-backed MeterProvider. If a MeterProvider is also set via WithMeterProvider, it takes precedence.

func WithReasoning 

func WithReasoning(reasoning map[string]any) Option

WithReasoning sets reasoning configuration passed through as the `reasoning` field.

func WithRepeatPenalty 

func WithRepeatPenalty(penalty float64) Option

WithRepeatPenalty sets the llama.cpp repeat_penalty parameter.

func WithRequestTimeout 

func WithRequestTimeout(timeout time.Duration) Option

WithRequestTimeout sets HTTP request timeout for LM Studio calls.

func WithResume 

func WithResume(sessionID string) Option

WithResume sets a session ID to resume from.

func WithSDKTools 

func WithSDKTools(tools ...Tool) Option

WithSDKTools registers high-level Tool instances as an in-process MCP server. Tools are exposed under the "sdk" MCP server name (tool names: mcp__sdk__<name>). Each tool is automatically added to AllowedTools.

func WithSeed 

func WithSeed(seed int64) Option

WithSeed sets deterministic seed where supported.

func WithSessionStorePath 

func WithSessionStorePath(path string) Option

WithSessionStorePath enables durable session persistence at a JSON file path. When set, resume/fork state can survive process restarts.

func WithStop 

func WithStop(stop ...string) Option

WithStop sets stop sequences.

func WithStreamUsage 

func WithStreamUsage(enable bool) Option

WithStreamUsage controls whether stream_options.include_usage is set on streaming requests. Defaults to true; set to false to opt out.

func WithSystemPrompt 

func WithSystemPrompt(prompt string) Option

WithSystemPrompt sets the system message to send to the model.

func WithSystemPromptPreset 

func WithSystemPromptPreset(preset *SystemPromptPreset) Option

WithSystemPromptPreset sets a preset system prompt configuration. If set, this takes precedence over WithSystemPrompt.

func WithTTL 

func WithTTL(ttl time.Duration) Option

WithTTL sets the `ttl` field (in seconds) controlling how long a JIT-loaded model stays in memory after the request. See LM Studio's JIT and Auto-Evict documentation for details.

func WithTemperature 

func WithTemperature(temperature float64) Option

WithTemperature sets sampling temperature.

func WithThinking 

func WithThinking(thinking config.ThinkingConfig) Option

WithThinking sets the thinking configuration.

func WithToolChoice 

func WithToolChoice(choice any) Option

WithToolChoice sets the tool_choice payload.

LM Studio only accepts the string forms "none", "auto", and "required" — the OpenAI object form `{"type": "function", "function": {"name": ...}}` is rejected with HTTP 400. Use WithForceTool to force a specific function instead.

func WithTools 

func WithTools(tools config.ToolsConfig) Option

WithTools specifies which tools are available. Accepts ToolsList (tool names) or *ToolsPreset.

func WithTopK 

func WithTopK(topK float64) Option

WithTopK sets top-k sampling.

func WithTopLogprobs 

func WithTopLogprobs(v int) Option

WithTopLogprobs sets top_logprobs where supported.

func WithTopP 

func WithTopP(topP float64) Option

WithTopP sets nucleus sampling probability.

func WithTracerProvider 

func WithTracerProvider(tp trace.TracerProvider) Option

WithTracerProvider sets an OpenTelemetry TracerProvider for recording SDK spans. When nil (the default) all span creation is a noop.

func WithTransport 

func WithTransport(transport Transport) Option

WithTransport injects a custom transport implementation. The transport must implement the Transport interface.

func WithUser 

func WithUser(user string) Option

WithUser sets a user identifier for tracking purposes.

func WithXTitle 

func WithXTitle(title string) Option

WithXTitle sets the X-Title header on outgoing requests.

type PermissionBehavior 

type PermissionBehavior = permission.Behavior

PermissionBehavior represents the permission behavior for a rule.

type PermissionMode 

type PermissionMode = permission.Mode

PermissionMode represents different permission handling modes.

type PermissionRequestHookInput 

type PermissionRequestHookInput = hook.PermissionRequestInput

PermissionRequestHookInput is the input for PermissionRequest hooks.

type PermissionRequestHookSpecificOutput 

type PermissionRequestHookSpecificOutput = hook.PermissionRequestSpecificOutput

PermissionRequestHookSpecificOutput is the hook-specific output for PermissionRequest.

type PermissionResult 

type PermissionResult = permission.Result

PermissionResult is the interface for permission decision results.

type PermissionResultAllow 

type PermissionResultAllow = permission.ResultAllow

PermissionResultAllow represents an allow decision.

type PermissionResultDeny 

type PermissionResultDeny = permission.ResultDeny

PermissionResultDeny represents a deny decision.

type PermissionRuleValue 

type PermissionRuleValue = permission.RuleValue

PermissionRuleValue represents a permission rule.

type PermissionUpdate 

type PermissionUpdate = permission.Update

PermissionUpdate represents a permission update request.

type PermissionUpdateDestination 

type PermissionUpdateDestination = permission.UpdateDestination

PermissionUpdateDestination represents where permission updates are stored.

type PermissionUpdateType 

type PermissionUpdateType = permission.UpdateType

PermissionUpdateType represents the type of permission update.

type PostToolUseFailureHookInput 

type PostToolUseFailureHookInput = hook.PostToolUseFailureInput

PostToolUseFailureHookInput is the input for PostToolUseFailure hooks.

type PostToolUseFailureHookSpecificOutput 

type PostToolUseFailureHookSpecificOutput = hook.PostToolUseFailureSpecificOutput

PostToolUseFailureHookSpecificOutput is the hook-specific output for PostToolUseFailure.

type PostToolUseHookInput 

type PostToolUseHookInput = hook.PostToolUseInput

PostToolUseHookInput is the input for PostToolUse hooks.

type PostToolUseHookSpecificOutput 

type PostToolUseHookSpecificOutput = hook.PostToolUseSpecificOutput

PostToolUseHookSpecificOutput is the hook-specific output for PostToolUse.

type PreCompactHookInput 

type PreCompactHookInput = hook.PreCompactInput

PreCompactHookInput is the input for PreCompact hooks.

type PreToolUseHookInput 

type PreToolUseHookInput = hook.PreToolUseInput

PreToolUseHookInput is the input for PreToolUse hooks.

type PreToolUseHookSpecificOutput 

type PreToolUseHookSpecificOutput = hook.PreToolUseSpecificOutput

PreToolUseHookSpecificOutput is the hook-specific output for PreToolUse.

type ReasoningEffort 

type ReasoningEffort = lmstudio.ReasoningEffort

ReasoningEffort controls the `reasoning` field on StatefulChat requests.

type ResultMessage 

type ResultMessage = message.ResultMessage

ResultMessage represents the final result of a query.

type SDKError 

type SDKError = internalerrors.SDKError

SDKError is the base interface for all SDK errors.

type Schema 

type Schema = jsonschema.Schema

Schema is a JSON Schema object for tool input validation.

type SchemaBuilder 

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

SchemaBuilder provides a fluent interface for building JSON schemas.

func NewSchemaBuilder 

func NewSchemaBuilder() *SchemaBuilder

NewSchemaBuilder creates a new SchemaBuilder.

func (*SchemaBuilder) Build 

func (b *SchemaBuilder) Build() map[string]any

Build returns the complete JSON Schema.

func (*SchemaBuilder) OptionalProperty 

func (b *SchemaBuilder) OptionalProperty(name, goType string) *SchemaBuilder

OptionalProperty adds an optional property (not in required list).

func (*SchemaBuilder) OptionalPropertyWithDescription 

func (b *SchemaBuilder) OptionalPropertyWithDescription(name, goType, description string) *SchemaBuilder

OptionalPropertyWithDescription adds an optional property with description.

func (*SchemaBuilder) Property 

func (b *SchemaBuilder) Property(name, goType string) *SchemaBuilder

Property adds a property with the given name and Go type. The property is marked as required by default.

func (*SchemaBuilder) PropertyWithDescription 

func (b *SchemaBuilder) PropertyWithDescription(name, goType, description string) *SchemaBuilder

PropertyWithDescription adds a property with type and description.

type SdkMcpServerInstance 

type SdkMcpServerInstance = mcp.ServerInstance

SdkMcpServerInstance is the interface that SDK MCP servers must implement.

type SdkMcpTool 

type SdkMcpTool struct {
	ToolName        string
	ToolDescription string
	ToolSchema      *jsonschema.Schema
	ToolHandler     SdkMcpToolHandler
	ToolAnnotations *mcp.ToolAnnotations
}

SdkMcpTool represents a tool created with NewSdkMcpTool.

func NewSdkMcpTool 

func NewSdkMcpTool(
	name, description string,
	inputSchema *jsonschema.Schema,
	handler SdkMcpToolHandler,
	opts ...SdkMcpToolOption,
) *SdkMcpTool

NewSdkMcpTool creates an SdkMcpTool with optional configuration.

The inputSchema should be a *jsonschema.Schema. Use SimpleSchema for convenience or create a full Schema struct for more control.

Use WithAnnotations to set MCP tool annotations (hints about tool behavior).

Example with SimpleSchema: 

addTool := lmsdk.NewSdkMcpTool("add", "Add two numbers",
    lmsdk.SimpleSchema(map[string]string{"a": "float64", "b": "float64"}),
    func(ctx context.Context, req *lmsdk.CallToolRequest) (*lmsdk.CallToolResult, error) {
        args, _ := lmsdk.ParseArguments(req)
        a, b := args["a"].(float64), args["b"].(float64)
        return lmTextResult(fmt.Sprintf("Result: %v", a+b)), nil
    },
    lmsdk.WithAnnotations(&lmsdk.McpToolAnnotations{
        ReadOnlyHint: true,
    }),
)

func (*SdkMcpTool) Annotations 

func (t *SdkMcpTool) Annotations() *mcp.ToolAnnotations

Annotations returns the tool annotations, or nil if not set.

func (*SdkMcpTool) Description 

func (t *SdkMcpTool) Description() string

Description returns the tool description.

func (*SdkMcpTool) Handler 

func (t *SdkMcpTool) Handler() SdkMcpToolHandler

Handler returns the tool handler function.

func (*SdkMcpTool) InputSchema 

func (t *SdkMcpTool) InputSchema() *jsonschema.Schema

InputSchema returns the JSON Schema for the tool input.

func (*SdkMcpTool) Name 

func (t *SdkMcpTool) Name() string

Name returns the tool name.

type SdkMcpToolHandler 

type SdkMcpToolHandler = mcp.ToolHandler

SdkMcpToolHandler is the function signature for SdkMcpTool handlers. It receives the context and request, and returns the result.

Use ParseArguments to extract input as map[string]any from the request. Use TextResult, ErrorResult, or ImageResult helpers to create results.

Example: 

func(ctx context.Context, req *lmsdk.CallToolRequest) (*lmsdk.CallToolResult, error) {
    args, err := lmsdk.ParseArguments(req)
    if err != nil {
        return lmsdk.ErrorResult(err.Error()), nil
    }
    a := args["a"].(float64)
    return lmTextResult(fmt.Sprintf("Result: %v", a)), nil
}

type SdkMcpToolOption 

type SdkMcpToolOption func(*SdkMcpTool)

SdkMcpToolOption configures an SdkMcpTool during construction.

func WithAnnotations 

func WithAnnotations(annotations *mcp.ToolAnnotations) SdkMcpToolOption

WithAnnotations sets MCP tool annotations (hints about tool behavior). Annotations describe properties like whether a tool is read-only, destructive, idempotent, or operates in an open world.

type SdkPluginConfig 

type SdkPluginConfig = config.PluginConfig

SdkPluginConfig configures a plugin to load.

type SessionStat 

type SessionStat struct {
	SessionID           string
	CreatedAt           string
	UpdatedAt           string
	MessageCount        int
	UserTurns           int
	CheckpointCount     int
	FileCheckpointCount int
}

SessionStat contains metadata about a locally persisted SDK session.

func ListSessions 

func ListSessions(ctx context.Context, opts ...Option) ([]SessionStat, error)

ListSessions returns local SDK sessions from the configured session store.

func StatSession 

func StatSession(ctx context.Context, sessionID string, opts ...Option) (*SessionStat, error)

StatSession returns metadata for a locally persisted SDK session.

type StatefulChatRequest 

type StatefulChatRequest = lmstudio.StatefulChatRequest

StatefulChatRequest is the body of a POST /api/v1/chat call.

type StatefulChatResponse 

type StatefulChatResponse = lmstudio.StatefulChatResponse

StatefulChatResponse is the response from StatefulChat.

func StatefulChat 

func StatefulChat(ctx context.Context, req StatefulChatRequest, opts ...Option) (*StatefulChatResponse, error)

StatefulChat calls LM Studio's native stateful chat endpoint (POST /api/v1/chat). Unlike the OpenAI-compatible path, this endpoint:

  • Takes `input` (string or content array) instead of `messages[]`.
  • Supports a first-class `reasoning` effort knob (off/low/medium/high/on).
  • Can thread conversation state via `previous_response_id` when the prior turn was created with Store=true — no need to send history back.
  • Accepts per-request MCP integrations via `integrations[]`.
  • Returns richer stats: `reasoning_output_tokens`, TTFT, model load time.

This is a one-shot non-streaming call. Use the main Query/QueryStream surface for OpenAI-compat streaming with MCP server registration.

type StatefulIntegration 

type StatefulIntegration = lmstudio.StatefulIntegration

StatefulIntegration configures a per-request MCP server or plugin for StatefulChat via `integrations[]`.

type StatefulOutput 

type StatefulOutput = lmstudio.StatefulOutput

StatefulOutput is one element of a stateful chat response's output[] list.

type StatefulStats 

type StatefulStats = lmstudio.StatefulStats

StatefulStats is the stats block on a stateful chat response.

type StopHookInput 

type StopHookInput = hook.StopInput

StopHookInput is the input for Stop hooks.

type StreamEvent 

type StreamEvent = message.StreamEvent

StreamEvent represents a raw streaming event from the LM Studio backend.

type StreamingMessage 

type StreamingMessage = message.StreamingMessage

StreamingMessage represents a message sent in streaming mode.

func NewUserMessage 

func NewUserMessage(content UserMessageContent) StreamingMessage

NewUserMessage creates a StreamingMessage with type "user". This is a convenience constructor for creating user messages.

type StreamingMessageContent 

type StreamingMessageContent = message.StreamingMessageContent

StreamingMessageContent represents the content of a streaming message.

type SubagentStartHookInput 

type SubagentStartHookInput = hook.SubagentStartInput

SubagentStartHookInput is the input for SubagentStart hooks.

type SubagentStartHookSpecificOutput 

type SubagentStartHookSpecificOutput = hook.SubagentStartSpecificOutput

SubagentStartHookSpecificOutput is the hook-specific output for SubagentStart.

type SubagentStopHookInput 

type SubagentStopHookInput = hook.SubagentStopInput

SubagentStopHookInput is the input for SubagentStop hooks.

type SyncHookJSONOutput 

type SyncHookJSONOutput = hook.SyncJSONOutput

SyncHookJSONOutput represents a sync hook output.

type SystemMessage 

type SystemMessage = message.SystemMessage

SystemMessage represents a system message.

type SystemPromptPreset 

type SystemPromptPreset = config.SystemPromptPreset

SystemPromptPreset defines a system prompt preset configuration.

type TextBlock 

type TextBlock = message.TextBlock

TextBlock contains plain text content.

func TextInput 

func TextInput(text string) *TextBlock

TextInput creates a text block for block-based multimodal user content.

type ThinkingBlock 

type ThinkingBlock = message.ThinkingBlock

ThinkingBlock contains model reasoning or thinking output.

type ThinkingConfig 

type ThinkingConfig = config.ThinkingConfig

ThinkingConfig controls extended thinking behavior.

type ThinkingConfigAdaptive 

type ThinkingConfigAdaptive = config.ThinkingConfigAdaptive

ThinkingConfigAdaptive enables adaptive thinking mode.

type ThinkingConfigDisabled 

type ThinkingConfigDisabled = config.ThinkingConfigDisabled

ThinkingConfigDisabled disables extended thinking.

type ThinkingConfigEnabled 

type ThinkingConfigEnabled = config.ThinkingConfigEnabled

ThinkingConfigEnabled enables thinking with a specific token budget.

type Tool 

type Tool interface {
	// Name returns the unique identifier for this tool.
	Name() string

	// Description returns a human-readable description for the model.
	Description() string

	// InputSchema returns a JSON schema describing expected input.
	// The schema should follow JSON Schema Draft 7 specification.
	InputSchema() map[string]any

	// Execute runs the tool with the provided input.
	// The input will be validated against InputSchema before execution.
	Execute(ctx context.Context, input map[string]any) (map[string]any, error)
}

Tool represents a custom tool that the SDK can invoke through VLLM tool calling.

Tools allow users to extend agent capabilities with domain-specific functionality. When registered, the model can discover and execute these tools during a session.

Example: 

tool := lmsdk.NewTool(
    "calculator",
    "Performs basic arithmetic operations",
    map[string]any{
        "type": "object",
        "properties": map[string]any{
            "operation": map[string]any{
                "type": "string",
                "enum": []string{"add", "subtract", "multiply", "divide"},
            },
            "a": map[string]any{"type": "number"},
            "b": map[string]any{"type": "number"},
        },
        "required": []string{"operation", "a", "b"},
    },
    func(ctx context.Context, input map[string]any) (map[string]any, error) {
        op := input["operation"].(string)
        a := input["a"].(float64)
        b := input["b"].(float64)

        var result float64
        switch op {
        case "add":
            result = a + b
        case "subtract":
            result = a - b
        case "multiply":
            result = a * b
        case "divide":
            if b == 0 {
                return nil, fmt.Errorf("division by zero")
            }
            result = a / b
        }

        return map[string]any{"result": result}, nil
    },
)

func NewTool 

func NewTool(name, description string, schema map[string]any, fn ToolFunc) Tool

NewTool creates a Tool from a function.

This is a convenience constructor for creating tools without implementing the full Tool interface.

Parameters:

  • name: Unique identifier for the tool (e.g., "calculator", "search_database")
  • description: Human-readable description of what the tool does
  • schema: JSON Schema defining the expected input structure
  • fn: Function that executes the tool logic

type ToolFunc 

type ToolFunc func(ctx context.Context, input map[string]any) (map[string]any, error)

ToolFunc is a function-based tool implementation.

type ToolPermissionCallback 

type ToolPermissionCallback = permission.Callback

ToolPermissionCallback is called before each tool use for permission checking.

type ToolPermissionContext 

type ToolPermissionContext = permission.Context

ToolPermissionContext provides context for tool permission callbacks.

type ToolPermissionDeniedError 

type ToolPermissionDeniedError = internalerrors.ToolPermissionDeniedError

ToolPermissionDeniedError indicates a tool execution was denied by permission policy.

type ToolResultBlock 

type ToolResultBlock = message.ToolResultBlock

ToolResultBlock contains the result of a tool execution.

type ToolUseBlock 

type ToolUseBlock = message.ToolUseBlock

ToolUseBlock represents the model invoking a tool.

type ToolsConfig 

type ToolsConfig = config.ToolsConfig

ToolsConfig is an interface for configuring available tools. It represents either a list of tool names or a preset configuration.

type ToolsList 

type ToolsList = config.ToolsList

ToolsList is a list of tool names to make available.

type ToolsPreset 

type ToolsPreset = config.ToolsPreset

ToolsPreset represents a preset configuration for available tools.

type Transport 

type Transport interface {
	Start(ctx context.Context) error
	CreateStream(ctx context.Context, req *ChatRequest) (<-chan map[string]any, <-chan error)
	Close() error
}

Transport defines the runtime transport interface.

type UnsupportedControlError 

type UnsupportedControlError = controlplane.UnsupportedControlError

UnsupportedControlError indicates a control-plane operation is unsupported by this backend.

type UnsupportedHookEventError 

type UnsupportedHookEventError = internalerrors.UnsupportedHookEventError

UnsupportedHookEventError indicates a configured hook event is not supported by this backend.

type UnsupportedHookOutputError 

type UnsupportedHookOutputError = internalerrors.UnsupportedHookOutputError

UnsupportedHookOutputError indicates a hook output field is unsupported by this backend.

type Usage 

type Usage = message.Usage

Usage contains token usage information.

type UserInputAnswer 

type UserInputAnswer = userinput.Answer

UserInputAnswer contains the user's response(s) to a single question.

type UserInputCallback 

type UserInputCallback = userinput.Callback

UserInputCallback handles user-input requests and returns answers.

type UserInputQuestion 

type UserInputQuestion = userinput.Question

UserInputQuestion represents a single user-input prompt.

type UserInputQuestionOption 

type UserInputQuestionOption = userinput.QuestionOption

UserInputQuestionOption represents a selectable choice in a user-input question.

type UserInputRequest 

type UserInputRequest = userinput.Request

UserInputRequest contains parsed user-input payload data.

type UserInputResponse 

type UserInputResponse = userinput.Response

UserInputResponse contains answers keyed by question ID.

type UserMessage 

type UserMessage = message.UserMessage

UserMessage represents a message from the user.

type UserMessageContent 

type UserMessageContent = message.UserMessageContent

UserMessageContent represents content that can be either a string or []ContentBlock.

func Blocks 

func Blocks(blocks ...ContentBlock) UserMessageContent

Blocks creates block-based user content.

func Text 

func Text(text string) UserMessageContent

Text creates text-only user content.

type UserPromptSubmitHookInput 

type UserPromptSubmitHookInput = hook.UserPromptSubmitInput

UserPromptSubmitHookInput is the input for UserPromptSubmit hooks.

type UserPromptSubmitHookSpecificOutput 

type UserPromptSubmitHookSpecificOutput = hook.UserPromptSubmitSpecificOutput

UserPromptSubmitHookSpecificOutput is the hook-specific output for UserPromptSubmit.

Source Files

View all Source files

Directories

Path Synopsis
examples
agent_act command
bash_tool command
Package main demonstrates a bash/shell execution tool driven by the model.
 Package main demonstrates a bash/shell execution tool driven by the model.
cancellation command
Package main demonstrates cancellation and graceful shutdown patterns.
 Package main demonstrates cancellation and graceful shutdown patterns.
client_multi_turn command
error_handling command
extended_thinking command
Package main demonstrates extended thinking capabilities with LM Studio.
 Package main demonstrates extended thinking capabilities with LM Studio.
force_tool command
Package main demonstrates WithForceTool — the LM-Studio-supported way to force a specific function since the OpenAI object form of tool_choice is rejected.
 Package main demonstrates WithForceTool — the LM-Studio-supported way to force a specific function since the OpenAI object form of tool_choice is rejected.
hooks command
include_partial_messages command
Package main demonstrates partial message streaming where incremental assistant updates are received as the model generates responses.
 Package main demonstrates partial message streaming where incremental assistant updates are received as the model generates responses.
internal/exampleutil
interrupt command
lmstudio_extra command
lmstudio_native_stats command
lmstudio_sampling command
max_budget_usd command
Package main demonstrates API cost control with budget limits.
 Package main demonstrates API cost control with budget limits.
mcp_calculator command
Package main demonstrates how to create calculator tools using MCP servers.
 Package main demonstrates how to create calculator tools using MCP servers.
mcp_status command
Package main demonstrates querying MCP server connection status.
 Package main demonstrates querying MCP server connection status.
memory_tool command
Package main demonstrates a filesystem-backed memory tool for agent state persistence.
 Package main demonstrates a filesystem-backed memory tool for agent state persistence.
model_discovery command
model_lifecycle command
Package main demonstrates LM Studio's /api/v1/models lifecycle surface — read-only operations (ListModelsResponse) only, so this example is safe to run without disturbing the currently-loaded model.
 Package main demonstrates LM Studio's /api/v1/models lifecycle surface — read-only operations (ListModelsResponse) only, so this example is safe to run without disturbing the currently-loaded model.
on_user_input command
parallel_queries command
Package main demonstrates running multiple Query() calls concurrently.
 Package main demonstrates running multiple Query() calls concurrently.
permissions command
pipeline command
Package main demonstrates multi-step LLM orchestration with Go control flow.
 Package main demonstrates multi-step LLM orchestration with Go control flow.
prometheus_observability command
query_stream command
quick_start command
sdk_tools command
sessions_local command
stateful_chat command
Package main demonstrates LM Studio's native stateful chat endpoint (/api/v1/chat) — reasoning effort control + previous_response_id continuation without re-sending history.
 Package main demonstrates LM Studio's native stateful chat endpoint (/api/v1/chat) — reasoning effort control + previous_response_id continuation without re-sending history.
structured_output command
system_prompt command
Package main demonstrates configuring system prompts.
 Package main demonstrates configuring system prompts.
internal
config
controlplane
errors
hook
Package hook provides hook types for intercepting runtime events.
 Package hook provides hook types for intercepting runtime events.
lmstudio
mcp
message
Package message provides internal message and content block types.
 Package message provides internal message and content block types.
model
observability
Package observability provides OpenTelemetry metrics and tracing for the SDK.
 Package observability provides OpenTelemetry metrics and tracing for the SDK.
permission
Package permission provides permission handling types.
 Package permission provides permission handling types.
runtime
session
tools
userinput
util
scripts
example_verifier command

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.