sdk

package module
v1.1.5 Latest Latest
Warning

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

 Go to latest Published: Dec 9, 2025 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package sdk provides a simple API for LLM conversations using PromptPack files.

SDK v2 is a pack-first SDK where everything starts from a .pack.json file. The pack contains prompts, variables, tools, validators, and model configuration. The SDK loads the pack and provides a minimal API to interact with LLMs.

Quick Start

The simplest possible usage is just 5 lines: 

conv, err := sdk.Open("./assistant.pack.json", "chat")
if err != nil {
    log.Fatal(err)
}
defer conv.Close()

resp, _ := conv.Send(ctx, "Hello!")
fmt.Println(resp.Text())

Core Concepts

Opening a Conversation:

Use Open to load a pack file and create a conversation for a specific prompt: 

// Minimal - provider auto-detected from environment
conv, _ := sdk.Open("./demo.pack.json", "troubleshooting")

// With options - override model, provider, etc.
conv, _ := sdk.Open("./demo.pack.json", "troubleshooting",
    sdk.WithModel("gpt-4o"),
    sdk.WithAPIKey(os.Getenv("MY_OPENAI_KEY")),
)

Variables:

Variables defined in the pack are populated at runtime: 

conv.SetVar("customer_id", "acme-corp")
conv.SetVars(map[string]any{
    "customer_name": "ACME Corporation",
    "tier": "premium",
})

Tools:

Tools defined in the pack just need implementation handlers: 

conv.OnTool("list_devices", func(args map[string]any) (any, error) {
    return myAPI.ListDevices(args["customer_id"].(string))
})

Streaming:

Stream responses chunk by chunk: 

for chunk := range conv.Stream(ctx, "Tell me a story") {
    fmt.Print(chunk.Text)
}

Design Principles

  1. Pack is the Source of Truth - The .pack.json file defines prompts, tools, validators, and pipeline configuration. The SDK configures itself automatically.
  2. Convention Over Configuration - API keys from environment, provider auto-detection, model defaults from pack. Override only when needed.
  3. Progressive Disclosure - Simple things are simple, advanced features available but not required.
  4. Same Runtime, Same Behavior - SDK v2 uses the same runtime pipeline as Arena. Pack-defined behaviors work identically.
  5. Thin Wrapper - No type duplication. Core types like Message, ContentPart, CostInfo come directly from runtime/types.

Package Structure

The SDK is organized into sub-packages for specific functionality:

  • sdk (this package): Entry point, Open, Conversation, Response
  • sdk/tools: Typed tool handlers, HITL support
  • sdk/stream: Streaming response handling
  • sdk/message: Multimodal message building
  • sdk/hooks: Event subscription and lifecycle hooks
  • sdk/validation: Validator registration and error handling

Most users only need to import the root sdk package.

Runtime Types

The SDK uses runtime types directly - no duplication: 

import "github.com/AltairaLabs/PromptKit/runtime/types"

msg := &types.Message{Role: "user"}
msg.AddTextPart("Hello")

Key runtime types: types.Message, types.ContentPart, types.MediaContent, types.CostInfo, types.ValidationResult.

Schema Reference

All pack examples conform to the PromptPack Specification v1.1.0: https://github.com/AltairaLabs/promptpack-spec/blob/main/schema/promptpack.schema.json

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrConversationClosed is returned when Send or Stream is called on a closed conversation.
	ErrConversationClosed = errors.New("conversation is closed")

	// ErrConversationNotFound is returned by Resume when the conversation ID doesn't exist.
	ErrConversationNotFound = errors.New("conversation not found")

	// ErrNoStateStore is returned by Resume when no state store is configured.
	ErrNoStateStore = errors.New("no state store configured")

	// ErrPromptNotFound is returned when the specified prompt doesn't exist in the pack.
	ErrPromptNotFound = errors.New("prompt not found in pack")

	// ErrPackNotFound is returned when the pack file doesn't exist.
	ErrPackNotFound = errors.New("pack file not found")

	// ErrProviderNotDetected is returned when no provider could be auto-detected.
	ErrProviderNotDetected = errors.New("could not detect provider: no API keys found in environment")

	// ErrToolNotRegistered is returned when the LLM calls a tool that has no handler.
	ErrToolNotRegistered = errors.New("tool handler not registered")

	// ErrToolNotInPack is returned when trying to register a handler for a tool not in the pack.
	ErrToolNotInPack = errors.New("tool not defined in pack")
)

Sentinel errors for common failure cases.

Functions

This section is empty.

Types

type ChunkType added in v1.1.5 

type ChunkType int

ChunkType identifies the type of a streaming chunk. 

const (
	// ChunkText indicates the chunk contains text content.
	ChunkText ChunkType = iota

	// ChunkToolCall indicates the chunk contains a tool call.
	ChunkToolCall

	// ChunkMedia indicates the chunk contains media content.
	ChunkMedia

	// ChunkDone indicates streaming is complete.
	ChunkDone
)

func (ChunkType) String added in v1.1.5 

func (t ChunkType) String() string

String returns the string representation of the chunk type.

type Conversation 

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

Conversation represents an active LLM conversation.

A conversation maintains:

  • Connection to the LLM provider
  • Message history (context)
  • Variable state for template substitution
  • Tool handlers for function calling
  • Validation state

Conversations are created via Open or Resume and are safe for concurrent use. Each Open call creates an independent conversation with isolated state.

Basic usage: 

conv, _ := sdk.Open("./assistant.pack.json", "chat")
conv.SetVar("user_name", "Alice")

resp, _ := conv.Send(ctx, "Hello!")
fmt.Println(resp.Text())

resp, _ = conv.Send(ctx, "What's my name?")  // Remembers context
fmt.Println(resp.Text())  // "Your name is Alice"

func Open added in v1.1.5 

func Open(packPath, promptName string, opts ...Option) (*Conversation, error)

Open loads a pack file and creates a new conversation for the specified prompt.

This is the primary entry point for SDK v2. It:

  • Loads and parses the pack file
  • Auto-detects the provider from environment (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
  • Configures the runtime pipeline based on pack settings
  • Creates an isolated conversation with its own state

Basic usage: 

conv, err := sdk.Open("./assistant.pack.json", "chat")
if err != nil {
    log.Fatal(err)
}
defer conv.Close()

resp, _ := conv.Send(ctx, "Hello!")
fmt.Println(resp.Text())

With options: 

conv, err := sdk.Open("./assistant.pack.json", "chat",
    sdk.WithModel("gpt-4o"),
    sdk.WithAPIKey(os.Getenv("MY_KEY")),
    sdk.WithStateStore(redisStore),
)

The packPath can be:

The promptName must match a prompt ID defined in the pack's "prompts" section.

func Resume added in v1.1.5 

func Resume(conversationID, packPath, promptName string, opts ...Option) (*Conversation, error)

Resume loads an existing conversation from state storage.

Use this to continue a conversation that was previously persisted: 

store := statestore.NewRedisStore("redis://localhost:6379")
conv, err := sdk.Resume("session-123", "./chat.pack.json", "assistant",
    sdk.WithStateStore(store),
)
if errors.Is(err, sdk.ErrConversationNotFound) {
    // Start new conversation
    conv, _ = sdk.Open("./chat.pack.json", "assistant",
        sdk.WithStateStore(store),
        sdk.WithConversationID("session-123"),
    )
}

Resume requires a state store to be configured. If no state store is provided, it returns ErrNoStateStore.

func (*Conversation) CheckPending added in v1.1.5 

func (c *Conversation) CheckPending(
	name string,
	args map[string]any,
) (*sdktools.PendingToolCall, bool)

CheckPending checks if a tool call should be pending and creates it if so. Returns (pending call, should wait) - if should wait is true, the tool shouldn't execute yet.

This method is used internally when processing tool calls from the LLM. It can also be useful for testing HITL workflows: 

pending, shouldWait := conv.CheckPending("risky_tool", args)
if shouldWait {
    // Tool requires approval
}

func (*Conversation) Clear added in v1.1.5 

func (c *Conversation) Clear()

Clear removes all messages from the conversation history.

This keeps the system prompt and variables but removes all user/assistant messages. Useful for starting fresh within the same conversation session.

func (*Conversation) Close added in v1.1.5 

func (c *Conversation) Close() error

Close releases resources associated with the conversation.

After Close is called, Send and Stream will return ErrConversationClosed. It's safe to call Close multiple times.

func (*Conversation) Continue 

func (c *Conversation) Continue(ctx context.Context) (*Response, error)

Continue resumes conversation after resolving pending tools.

Call this after approving/rejecting all pending tools to continue the conversation with the tool results: 

resp, _ := conv.Send(ctx, "Process refund")
for _, pending := range resp.PendingTools() {
    conv.ResolveTool(pending.ID)
}
resp, _ = conv.Continue(ctx) // LLM receives tool results

func (*Conversation) EventBus added in v1.1.5 

func (c *Conversation) EventBus() *events.EventBus

EventBus returns the conversation's event bus for observability.

Use this to subscribe to runtime events like tool calls, validations, and provider requests: 

conv.EventBus().Subscribe(events.EventToolCallStarted, func(e *events.Event) {
    log.Printf("Tool call: %s", e.Data.(*events.ToolCallStartedData).ToolName)
})

For convenience methods, see the [hooks] package.

func (*Conversation) Fork added in v1.1.5 

func (c *Conversation) Fork() *Conversation

Fork creates a copy of the current conversation state.

Use this to explore alternative conversation branches: 

conv.Send(ctx, "I want to plan a trip")
conv.Send(ctx, "What cities should I visit?")

// Fork to explore different paths
branch := conv.Fork()

conv.Send(ctx, "Tell me about Tokyo")     // Original path
branch.Send(ctx, "Tell me about Kyoto")   // Branch path

The forked conversation is completely independent - changes to one do not affect the other.

func (*Conversation) GetVar added in v1.1.5 

func (c *Conversation) GetVar(name string) string

GetVar returns the current value of a template variable. Returns empty string if the variable is not set.

func (*Conversation) ID added in v1.1.5 

func (c *Conversation) ID() string

ID returns the conversation's unique identifier.

func (*Conversation) Messages added in v1.1.5 

func (c *Conversation) Messages() []types.Message

Messages returns the conversation history.

The returned slice is a copy - modifying it does not affect the conversation.

func (*Conversation) OnTool added in v1.1.5 

func (c *Conversation) OnTool(name string, handler ToolHandler)

OnTool registers a handler for a tool defined in the pack.

The tool name must match a tool defined in the pack's tools section. When the LLM calls the tool, your handler receives the parsed arguments and returns a result. 

conv.OnTool("get_weather", func(args map[string]any) (any, error) {
    city := args["city"].(string)
    return weatherAPI.GetCurrent(city)
})

The handler's return value is automatically serialized to JSON and sent back to the LLM as the tool result.

func (*Conversation) OnToolAsync added in v1.1.5 

func (c *Conversation) OnToolAsync(
	name string,
	checkFunc func(args map[string]any) sdktools.PendingResult,
	execFunc ToolHandler,
)

OnToolAsync registers a handler that may require approval before execution.

Use this for Human-in-the-Loop (HITL) workflows where certain actions require human approval before proceeding: 

conv.OnToolAsync("process_refund", func(args map[string]any) sdk.PendingResult {
    amount := args["amount"].(float64)
    if amount > 1000 {
        return sdk.PendingResult{
            Reason:  "high_value_refund",
            Message: fmt.Sprintf("Refund of $%.2f requires approval", amount),
        }
    }
    return sdk.PendingResult{} // Proceed immediately
}, func(args map[string]any) (any, error) {
    // Execute the actual refund
    return refundAPI.Process(args)
})

The first function checks if approval is needed, the second executes the action.

func (*Conversation) OnToolCtx added in v1.1.5 

func (c *Conversation) OnToolCtx(name string, handler ToolHandlerCtx)

OnToolCtx registers a context-aware handler for a tool.

Use this when your tool implementation needs the request context for cancellation, deadlines, or tracing: 

conv.OnToolCtx("search_db", func(ctx context.Context, args map[string]any) (any, error) {
    return db.SearchWithContext(ctx, args["query"].(string))
})

func (*Conversation) OnToolExecutor added in v1.1.5 

func (c *Conversation) OnToolExecutor(name string, executor tools.Executor)

OnToolExecutor registers a custom executor for tools.

Use this when you need full control over tool execution or want to use a runtime executor directly: 

executor := &MyCustomExecutor{}
conv.OnToolExecutor("custom_tool", executor)

The executor must implement the runtime/tools.Executor interface.

func (*Conversation) OnToolHTTP added in v1.1.5 

func (c *Conversation) OnToolHTTP(name string, config *sdktools.HTTPToolConfig)

OnToolHTTP registers a tool that makes HTTP requests.

This is a convenience method for tools that call external APIs: 

conv.OnToolHTTP("create_ticket", sdktools.NewHTTPToolConfig(
    "https://api.tickets.example.com/tickets",
    sdktools.WithMethod("POST"),
    sdktools.WithHeader("Authorization", "Bearer "+apiKey),
    sdktools.WithTimeout(5000),
))

The tool arguments from the LLM are serialized to JSON and sent as the request body. The response is parsed and returned to the LLM.

func (*Conversation) OnTools added in v1.1.5 

func (c *Conversation) OnTools(handlers map[string]ToolHandler)

OnTools registers multiple tool handlers at once. 

conv.OnTools(map[string]sdk.ToolHandler{
    "get_weather":   getWeatherHandler,
    "search_docs":   searchDocsHandler,
    "send_email":    sendEmailHandler,
})

func (*Conversation) PendingTools added in v1.1.5 

func (c *Conversation) PendingTools() []*sdktools.PendingToolCall

PendingTools returns all pending tool calls awaiting approval.

func (*Conversation) RejectTool added in v1.1.5 

func (c *Conversation) RejectTool(id, reason string) (*sdktools.ToolResolution, error)

RejectTool rejects a pending tool call.

Use this when the human reviewer decides not to approve the tool: 

resp, _ := conv.RejectTool(pending.ID, "Not authorized for this amount")

func (*Conversation) ResolveTool added in v1.1.5 

func (c *Conversation) ResolveTool(id string) (*sdktools.ToolResolution, error)

ResolveTool approves and executes a pending tool call.

After calling Send() and receiving pending tools in the response, use this to approve and execute them: 

resp, _ := conv.Send(ctx, "Process refund for order #12345")
if len(resp.PendingTools()) > 0 {
    pending := resp.PendingTools()[0]
    // ... get approval ...
    result, _ := conv.ResolveTool(pending.ID)
    // Continue the conversation with the result
    resp, _ = conv.Continue(ctx)
}

func (*Conversation) Send 

func (c *Conversation) Send(ctx context.Context, message any, opts ...SendOption) (*Response, error)

Send sends a message to the LLM and returns the response.

The message can be a simple string or a *types.Message for multimodal content. Variables are substituted into the system prompt template before sending.

Basic usage: 

resp, err := conv.Send(ctx, "Hello!")
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.Text())

With message options: 

resp, err := conv.Send(ctx, "What's in this image?",
    sdk.WithImageFile("/path/to/image.jpg"),
)

Send automatically:

  • Substitutes variables into the system prompt
  • Runs any registered validators
  • Handles tool calls if tools are defined
  • Persists state if a state store is configured

func (*Conversation) SetVar added in v1.1.5 

func (c *Conversation) SetVar(name, value string)

SetVar sets a single template variable.

Variables are substituted into the system prompt template: 

conv.SetVar("customer_name", "Alice")
// Template: "You are helping {{customer_name}}"
// Becomes: "You are helping Alice"

func (*Conversation) SetVars added in v1.1.5 

func (c *Conversation) SetVars(vars map[string]any)

SetVars sets multiple template variables at once. 

conv.SetVars(map[string]any{
    "customer_name": "Alice",
    "customer_tier": "premium",
    "max_discount": 20,
})

func (*Conversation) SetVarsFromEnv added in v1.1.5 

func (c *Conversation) SetVarsFromEnv(prefix string)

SetVarsFromEnv sets variables from environment variables with a given prefix.

Environment variables matching the prefix are added as template variables with the prefix stripped and converted to lowercase: 

// If PROMPTKIT_CUSTOMER_NAME=Alice is set:
conv.SetVarsFromEnv("PROMPTKIT_")
// Sets variable "customer_name" = "Alice"

func (*Conversation) Stream added in v1.1.5 

func (c *Conversation) Stream(ctx context.Context, message any, opts ...SendOption) <-chan StreamChunk

Stream sends a message and returns a channel of response chunks.

Use this for real-time streaming of LLM responses: 

for chunk := range conv.Stream(ctx, "Tell me a story") {
    if chunk.Error != nil {
        log.Printf("Error: %v", chunk.Error)
        break
    }
    fmt.Print(chunk.Text)
}

The channel is closed when the response is complete or an error occurs. The final chunk (Type == ChunkDone) contains the complete Response.

func (*Conversation) StreamRaw added in v1.1.5 

func (c *Conversation) StreamRaw(ctx context.Context, message any) (<-chan streamPkg.Chunk, error)

StreamRaw returns a channel of streaming chunks for use with the stream package. This is a lower-level API that returns stream.Chunk types.

Most users should use Conversation.Stream instead. StreamRaw is useful when working with [stream.Process] or [stream.CollectText]. 

err := stream.Process(ctx, conv, "Hello", func(chunk stream.Chunk) error {
    fmt.Print(chunk.Text)
    return nil
})

func (*Conversation) ToolRegistry added in v1.1.5 

func (c *Conversation) ToolRegistry() *tools.Registry

ToolRegistry returns the underlying tool registry.

This is a power-user method for direct registry access. Tool descriptors are loaded from the pack; this allows inspecting them or registering custom executors. 

registry := conv.ToolRegistry().(*tools.Registry)
for _, desc := range registry.Descriptors() {
    fmt.Printf("Tool: %s\n", desc.Name)
}

type MCPServerBuilder added in v1.1.5 

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

MCPServerBuilder provides a fluent interface for configuring MCP servers.

func NewMCPServer added in v1.1.5 

func NewMCPServer(name, command string, args ...string) *MCPServerBuilder

NewMCPServer creates a new MCP server configuration builder. 

server := sdk.NewMCPServer("github", "npx", "@modelcontextprotocol/server-github").
    WithEnv("GITHUB_TOKEN", os.Getenv("GITHUB_TOKEN"))

conv, _ := sdk.Open("./assistant.pack.json", "assistant",
    sdk.WithMCPServer(server),
)

func (*MCPServerBuilder) Build added in v1.1.5 

func (b *MCPServerBuilder) Build() mcp.ServerConfig

Build returns the configured server config.

func (*MCPServerBuilder) WithArgs added in v1.1.5 

func (b *MCPServerBuilder) WithArgs(args ...string) *MCPServerBuilder

WithArgs appends additional arguments to the MCP server command.

func (*MCPServerBuilder) WithEnv added in v1.1.5 

func (b *MCPServerBuilder) WithEnv(key, value string) *MCPServerBuilder

WithEnv adds an environment variable to the MCP server.

type Option added in v1.1.5 

type Option func(*config) error

Option configures a Conversation.

func WithAPIKey added in v1.1.5 

func WithAPIKey(key string) Option

WithAPIKey provides an explicit API key instead of reading from environment. 

conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithAPIKey(os.Getenv("MY_CUSTOM_KEY")),
)

func WithConversationID added in v1.1.5 

func WithConversationID(id string) Option

WithConversationID sets the conversation identifier.

If not set, a unique ID is auto-generated. Set this when you want to use a specific ID for state persistence or tracking. 

conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithStateStore(store),
    sdk.WithConversationID("user-123-session-456"),
)

func WithDisabledValidators added in v1.1.5 

func WithDisabledValidators(names ...string) Option

WithDisabledValidators disables specific validators by name. 

conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithDisabledValidators("max_length", "banned_words"),
)

func WithEventBus added in v1.1.4 

func WithEventBus(bus *events.EventBus) Option

WithEventBus provides a shared event bus for observability.

When set, the conversation emits events to this bus. Use this to share an event bus across multiple conversations for centralized logging, metrics, or debugging. 

bus := events.NewEventBus()
bus.SubscribeAll(myMetricsCollector)

conv1, _ := sdk.Open("./chat.pack.json", "assistant", sdk.WithEventBus(bus))
conv2, _ := sdk.Open("./chat.pack.json", "assistant", sdk.WithEventBus(bus))

func WithMCP added in v1.1.5 

func WithMCP(name, command string, args ...string) Option

WithMCP adds an MCP (Model Context Protocol) server for tool execution.

MCP servers provide external tools that can be called by the LLM. The server is started automatically when the conversation opens and stopped when the conversation is closed.

Basic usage: 

conv, _ := sdk.Open("./assistant.pack.json", "assistant",
    sdk.WithMCP("filesystem", "npx", "@modelcontextprotocol/server-filesystem", "/path"),
)

With environment variables: 

conv, _ := sdk.Open("./assistant.pack.json", "assistant",
    sdk.WithMCP("github", "npx", "@modelcontextprotocol/server-github").
        WithEnv("GITHUB_TOKEN", os.Getenv("GITHUB_TOKEN")),
)

Multiple servers: 

conv, _ := sdk.Open("./assistant.pack.json", "assistant",
    sdk.WithMCP("filesystem", "npx", "@modelcontextprotocol/server-filesystem", "/path"),
    sdk.WithMCP("memory", "npx", "@modelcontextprotocol/server-memory"),
)

func WithMCPServer added in v1.1.5 

func WithMCPServer(builder *MCPServerBuilder) Option

WithMCPServer adds a pre-configured MCP server. 

server := sdk.NewMCPServer("github", "npx", "@modelcontextprotocol/server-github").
    WithEnv("GITHUB_TOKEN", os.Getenv("GITHUB_TOKEN"))

conv, _ := sdk.Open("./assistant.pack.json", "assistant",
    sdk.WithMCPServer(server),
)

func WithModel added in v1.1.5 

func WithModel(model string) Option

WithModel overrides the default model specified in the pack. 

conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithModel("gpt-4o"),
)

func WithProvider 

func WithProvider(p providers.Provider) Option

WithProvider uses a custom provider instance.

This bypasses auto-detection and uses the provided provider directly. Use this for custom provider implementations or when you need full control over provider configuration. 

provider := openai.NewProvider(openai.Config{...})
conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithProvider(provider),
)

func WithSkipSchemaValidation added in v1.1.5 

func WithSkipSchemaValidation() Option

WithSkipSchemaValidation disables JSON schema validation during pack loading.

By default, packs are validated against the PromptPack JSON schema to ensure they are well-formed. Use this option to skip validation, for example when loading legacy packs or during development. 

conv, _ := sdk.Open("./legacy.pack.json", "assistant",
    sdk.WithSkipSchemaValidation(),
)

func WithStateStore 

func WithStateStore(store statestore.Store) Option

WithStateStore configures persistent state storage.

When configured, conversation state (messages, metadata) is automatically persisted after each turn and can be resumed later via Resume. 

store := statestore.NewRedisStore("redis://localhost:6379")
conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithStateStore(store),
)

func WithStrictValidation added in v1.1.5 

func WithStrictValidation() Option

WithStrictValidation makes all validators fail on violation.

Normally, validators respect their fail_on_violation setting from the pack. With strict validation, all validators will cause errors on failure. 

conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithStrictValidation(),
)

func WithTokenBudget added in v1.1.5 

func WithTokenBudget(tokens int) Option

WithTokenBudget sets the maximum tokens for context (prompt + history).

When the conversation history exceeds this budget, older messages are truncated according to the truncation strategy. 

conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithTokenBudget(8000),
)

func WithToolRegistry 

func WithToolRegistry(registry *tools.Registry) Option

WithToolRegistry provides a pre-configured tool registry.

This is a power-user option for scenarios requiring direct registry access. Tool descriptors are still loaded from the pack; this allows providing custom executors or middleware. 

registry := tools.NewRegistry()
registry.RegisterExecutor(&myCustomExecutor{})
conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithToolRegistry(registry),
)

func WithTruncation added in v1.1.5 

func WithTruncation(strategy string) Option

WithTruncation sets the truncation strategy for context management.

Strategies:

  • "sliding": Remove oldest messages first (default)

  • "summarize": Summarize old messages before removing

    conv, _ := sdk.Open("./chat.pack.json", "assistant", sdk.WithTokenBudget(8000), sdk.WithTruncation("summarize"), )

func WithValidationMode added in v1.1.5 

func WithValidationMode(mode ValidationMode) Option

WithValidationMode sets how validation failures are handled. 

// Suppress validation errors (useful for testing)
conv, _ := sdk.Open("./chat.pack.json", "assistant",
    sdk.WithValidationMode(sdk.ValidationModeWarn),
)

type PackError added in v1.1.5 

type PackError struct {
	// Path is the pack file path.
	Path string

	// Cause is the underlying error.
	Cause error
}

PackError represents an error loading or parsing a pack file.

func (*PackError) Error added in v1.1.5 

func (e *PackError) Error() string

Error implements the error interface.

func (*PackError) Unwrap added in v1.1.5 

func (e *PackError) Unwrap() error

Unwrap returns the underlying error.

type PendingTool added in v1.1.5 

type PendingTool struct {
	// Unique identifier for this pending call
	ID string

	// Tool name
	Name string

	// Arguments passed to the tool
	Arguments map[string]any

	// Reason the tool requires approval
	Reason string

	// Human-readable message about why approval is needed
	Message string
}

PendingTool represents a tool call that requires external approval.

type ProviderError added in v1.1.5 

type ProviderError struct {
	// Provider name (e.g., "openai", "anthropic").
	Provider string

	// StatusCode is the HTTP status code if available.
	StatusCode int

	// Message is the error message from the provider.
	Message string

	// Cause is the underlying error.
	Cause error
}

ProviderError represents an error from the LLM provider.

func (*ProviderError) Error added in v1.1.5 

func (e *ProviderError) Error() string

Error implements the error interface.

func (*ProviderError) Unwrap added in v1.1.5 

func (e *ProviderError) Unwrap() error

Unwrap returns the underlying error.

type Response 

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

Response represents the result of a conversation turn.

Response wraps the assistant's message with convenience methods and additional metadata like timing and validation results.

Basic usage: 

resp, _ := conv.Send(ctx, "Hello!")
fmt.Println(resp.Text())           // Text content
fmt.Println(resp.TokensUsed())     // Total tokens
fmt.Println(resp.Cost())           // Total cost in USD

For multimodal responses: 

if resp.HasMedia() {
    for _, part := range resp.Parts() {
        if part.Media != nil {
            fmt.Printf("Media: %s\n", part.Media.URL)
        }
    }
}

func (*Response) Cost 

func (r *Response) Cost() float64

Cost returns the total cost in USD for this response.

func (*Response) Duration added in v1.1.5 

func (r *Response) Duration() time.Duration

Duration returns how long the request took.

func (*Response) HasMedia added in v1.1.5 

func (r *Response) HasMedia() bool

HasMedia returns true if the response contains any media content.

func (*Response) HasToolCalls added in v1.1.5 

func (r *Response) HasToolCalls() bool

HasToolCalls returns true if the response contains tool calls.

func (*Response) InputTokens added in v1.1.5 

func (r *Response) InputTokens() int

InputTokens returns the number of input (prompt) tokens used.

func (*Response) Message added in v1.1.5 

func (r *Response) Message() *types.Message

Message returns the underlying runtime Message.

Use this when you need direct access to the message structure, such as for serialization or passing to other runtime components.

func (*Response) OutputTokens added in v1.1.5 

func (r *Response) OutputTokens() int

OutputTokens returns the number of output (completion) tokens used.

func (*Response) Parts added in v1.1.5 

func (r *Response) Parts() []types.ContentPart

Parts returns all content parts in the response.

Use this for multimodal responses that may contain text, images, audio, or other content types.

func (*Response) PendingTools 

func (r *Response) PendingTools() []PendingTool

PendingTools returns tools that are awaiting external approval.

This is used for Human-in-the-Loop (HITL) workflows where certain tools require approval before execution.

func (*Response) Text added in v1.1.5 

func (r *Response) Text() string

Text returns the text content of the response.

This is a convenience method that extracts all text parts and joins them. For responses with only text content, this returns the full response. For multimodal responses, use Response.Parts to access all content.

func (*Response) TokensUsed 

func (r *Response) TokensUsed() int

TokensUsed returns the total number of tokens used (input + output).

func (*Response) ToolCalls 

func (r *Response) ToolCalls() []types.MessageToolCall

ToolCalls returns the tool calls made during this turn.

Tool calls are requests from the LLM to execute functions. If you have registered handlers via Conversation.OnTool, they will be executed automatically and the results sent back to the LLM.

func (*Response) Validations 

func (r *Response) Validations() []types.ValidationResult

Validations returns the results of all validators that ran.

Validators are defined in the pack and run automatically on responses. Check this to see which validators passed or failed.

type SendOption added in v1.1.5 

type SendOption func(*sendConfig) error

SendOption configures a single Send call.

func WithAudioFile added in v1.1.5 

func WithAudioFile(path string) SendOption

WithAudioFile attaches audio from a file path. 

resp, _ := conv.Send(ctx, "Transcribe this audio",
    sdk.WithAudioFile("/path/to/audio.mp3"),
)

func WithFile added in v1.1.5 

func WithFile(name string, data []byte) SendOption

WithFile attaches a file with the given name and content. 

resp, _ := conv.Send(ctx, "Analyze this data",
    sdk.WithFile("data.csv", csvBytes),
)

func WithImageData added in v1.1.5 

func WithImageData(data []byte, mimeType string, detail ...*string) SendOption

WithImageData attaches an image from raw bytes. 

resp, _ := conv.Send(ctx, "What's in this image?",
    sdk.WithImageData(imageBytes, "image/png"),
)

func WithImageFile added in v1.1.5 

func WithImageFile(path string, detail ...*string) SendOption

WithImageFile attaches an image from a file path. 

resp, _ := conv.Send(ctx, "What's in this image?",
    sdk.WithImageFile("/path/to/image.jpg"),
)

func WithImageURL added in v1.1.5 

func WithImageURL(url string, detail ...*string) SendOption

WithImageURL attaches an image from a URL. 

resp, _ := conv.Send(ctx, "What's in this image?",
    sdk.WithImageURL("https://example.com/photo.jpg"),
)

type StreamChunk added in v1.1.5 

type StreamChunk struct {
	// Type of this chunk
	Type ChunkType

	// Text content (for ChunkText type)
	Text string

	// Tool call (for ChunkToolCall type)
	ToolCall *types.MessageToolCall

	// Media content (for ChunkMedia type)
	Media *types.MediaContent

	// Complete response (for ChunkDone type)
	Message *Response

	// Error (if any occurred)
	Error error
}

StreamChunk represents a single chunk in a streaming response.

type ToolError added in v1.1.5 

type ToolError struct {
	// ToolName is the name of the tool that failed.
	ToolName string

	// Cause is the underlying error from the tool handler.
	Cause error
}

ToolError represents an error executing a tool.

func (*ToolError) Error added in v1.1.5 

func (e *ToolError) Error() string

Error implements the error interface.

func (*ToolError) Unwrap added in v1.1.5 

func (e *ToolError) Unwrap() error

Unwrap returns the underlying error.

type ToolHandler added in v1.1.5 

type ToolHandler func(args map[string]any) (any, error)

ToolHandler is a function that executes a tool call. It receives the parsed arguments from the LLM and returns a result.

The args map contains the arguments as specified in the tool's schema. The return value should be JSON-serializable. 

conv.OnTool("get_weather", func(args map[string]any) (any, error) {
    city := args["city"].(string)
    return weatherAPI.GetCurrent(city)
})

type ToolHandlerCtx added in v1.1.5 

type ToolHandlerCtx func(ctx context.Context, args map[string]any) (any, error)

ToolHandlerCtx is like ToolHandler but receives a context. Use this when your tool implementation needs context for cancellation or deadlines. 

conv.OnToolCtx("search_db", func(ctx context.Context, args map[string]any) (any, error) {
    return db.SearchWithContext(ctx, args["query"].(string))
})

type ValidationError added in v1.1.5 

type ValidationError struct {
	// ValidatorType is the type of validator that failed (e.g., "banned_words").
	ValidatorType string

	// Message describes what validation rule was violated.
	Message string

	// Details contains validator-specific information about the failure.
	Details map[string]any
}

ValidationError represents a validation failure.

func AsValidationError added in v1.1.5 

func AsValidationError(err error) (*ValidationError, bool)

AsValidationError checks if an error is a ValidationError and returns it. 

resp, err := conv.Send(ctx, message)
if err != nil {
    if vErr, ok := sdk.AsValidationError(err); ok {
        fmt.Printf("Validation failed: %s\n", vErr.ValidatorType)
    }
}

func (*ValidationError) Error added in v1.1.5 

func (e *ValidationError) Error() string

Error implements the error interface.

type ValidationMode added in v1.1.5 

type ValidationMode int

ValidationMode controls how validation failures are handled. 

const (
	// ValidationModeError causes validation failures to return errors (default).
	ValidationModeError ValidationMode = iota

	// ValidationModeWarn logs validation failures but doesn't return errors.
	ValidationModeWarn

	// ValidationModeDisabled skips validation entirely.
	ValidationModeDisabled
)

Source Files

View all Source files

Directories

Path Synopsis
examples
hello command
Package main demonstrates the simplest PromptKit SDK usage.
 Package main demonstrates the simplest PromptKit SDK usage.
hitl command
Package main demonstrates Human-in-the-Loop (HITL) tool approval with the PromptKit SDK.
 Package main demonstrates Human-in-the-Loop (HITL) tool approval with the PromptKit SDK.
multimodal command
Package main demonstrates multimodal capabilities with the PromptKit SDK.
 Package main demonstrates multimodal capabilities with the PromptKit SDK.
streaming command
Package main demonstrates streaming responses with the PromptKit SDK.
 Package main demonstrates streaming responses with the PromptKit SDK.
tools command
Package main demonstrates tool handling with the PromptKit SDK.
 Package main demonstrates tool handling with the PromptKit SDK.
Package hooks provides convenience methods for subscribing to SDK events.
 Package hooks provides convenience methods for subscribing to SDK events.
internal
pack
Package pack provides internal pack loading functionality.
 Package pack provides internal pack loading functionality.
pipeline
Package pipeline provides internal pipeline construction for the SDK.
 Package pipeline provides internal pipeline construction for the SDK.
provider
Package provider provides internal provider detection and initialization.
 Package provider provides internal provider detection and initialization.
Package stream provides streaming support for SDK v2.
 Package stream provides streaming support for SDK v2.
Package tools provides HITL (Human-in-the-Loop) tool support.
 Package tools provides HITL (Human-in-the-Loop) tool support.

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.