SDK Reference

Complete reference documentation for the PromptKit SDK API.

Overview

The SDK provides a pack-first API that reduces boilerplate by ~80%.

Core Functions

sdk.Open

Opens a conversation from a pack file.

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

Parameters:

• packPath - Path to the .pack.json file
• promptName - Name of the prompt from the pack
• opts - Optional configuration options

Returns:

• *Conversation - Ready-to-use conversation
• error - Error if pack or prompt not found

Example:

conv, err := sdk.Open("./app.pack.json", "assistant")

Options

WithModel

Override the model.

sdk.WithModel("gpt-4o")

WithUserID

Set a pseudonymous user identifier for cross-session correlation (e.g., memory, analytics). PromptKit does not manage user-to-session mapping — that is the operator’s concern.

sdk.WithUserID("virtual-user-abc")

WithSessionMetadata

Attach arbitrary key-value metadata to the session. Metadata is persisted in the state store and available to capabilities via CapabilityContext.

sdk.WithSessionMetadata(map[string]any{
    "tenant":  "acme-corp",
    "channel": "web-chat",
})

WithImageFile

Attach an image from a file.

sdk.WithImageFile("/path/to/image.png")

WithImageURL

Attach an image from a URL.

sdk.WithImageURL("https://example.com/image.jpg")

WithImageData

Attach image from raw bytes.

sdk.WithImageData(imageBytes, "image/png")

WithDocumentFile

Attach a PDF document from a file.

sdk.WithDocumentFile("/path/to/document.pdf")

WithDocumentData

Attach a PDF document from raw bytes.

sdk.WithDocumentData(pdfBytes, "application/pdf")

WithProviderHook

Register a hook that intercepts LLM provider calls (before/after). Multiple hooks execute in order; the first deny short-circuits.

sdk.WithProviderHook(guardrails.NewBannedWordsHook([]string{"hack"}))

WithToolHook

Register a hook that intercepts LLM-initiated tool calls (before/after).

sdk.WithToolHook(myToolAuditHook)

WithSessionHook

Register a hook for tracking session lifecycle (start, update, end).

sdk.WithSessionHook(mySessionLogger)

WithAudioFile

Attach an audio file.

sdk.WithAudioFile("/path/to/audio.mp3")

WithVideoFile

Attach a video file.

sdk.WithVideoFile("/path/to/video.mp4")

WithRecording

Enable session recording by inserting RecordingStages into the pipeline. These stages capture full binary content (images, audio, video) and publish events directly to the EventBus for session replay.

If cfg is nil, default settings are used (audio=true, video=false, images=true). An EventBus is automatically created if none was provided via WithEventBus.

// Use defaults
sdk.WithRecording(nil)

// Custom config
sdk.WithRecording(&sdk.RecordingConfig{
    IncludeAudio:  true,
    IncludeVideo:  true,
    IncludeImages: true,
})

Note

Without WithRecording, the emitter’s MessageCreated events strip binary data from content parts (keeping only metadata like MIMEType, SizeKB, dimensions). RecordingStages bypass the emitter and publish full binary data directly to the EventBus.

WithCompaction

Control context compaction in tool loops. Compaction is on by default — the context compactor folds stale tool results between rounds to prevent context overflow. Pass false to disable.

// Disable compaction (default: enabled)
sdk.WithCompaction(false)

WithMessageLog

Enable per-round write-through persistence during tool loops. When set, messages are appended to the log after each LLM round for durability:

sdk.WithMessageLog(myMessageLog)

The MessageLog interface is defined in runtime/statestore. MemoryStore implements it out of the box.

Conversation Type

Send

Send a message and get a response.

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

Stream

Stream a response.

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

SetVar

Set a template variable.

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

GetVar

Get a template variable.

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

SetVars

Set multiple variables.

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

OnTool

Register a tool handler.

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

OnToolCtx

Register a tool handler with context.

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

OnTools

Register multiple tool handlers.

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

OnToolAsync

Register a tool with approval workflow.

func (c *Conversation) OnToolAsync(name string, check func(args map[string]any) tools.PendingResult, execute ToolHandler)

OnToolHTTP

Register an HTTP tool.

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

EventBus

Get the event bus for subscribing to events via the hooks package.

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

Example:

hooks.On(conv, events.EventProviderCallCompleted, func(e *events.Event) {
    log.Printf("Provider call completed: %s", e.Type)
})

Messages

Get conversation history.

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

Clear

Clear conversation history.

func (c *Conversation) Clear() error

Fork

Create an isolated copy.

func (c *Conversation) Fork() *Conversation

Close

Close the conversation.

func (c *Conversation) Close() error

ID

Get conversation ID.

func (c *Conversation) ID() string

ResolveTool

Approve a pending tool.

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

RejectTool

Reject a pending tool.

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

Response Type

Text

Get response text.

func (r *Response) Text() string

HasToolCalls

Check for tool calls.

func (r *Response) HasToolCalls() bool

ToolCalls

Get tool calls.

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

PendingTools

Get pending approvals.

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

StreamChunk Type

type StreamChunk struct {
    Type     ChunkType              // ChunkText, ChunkToolCall, ChunkMedia, ChunkDone
    Text     string                 // Text content (for ChunkText)
    ToolCall *types.MessageToolCall // Tool call (for ChunkToolCall)
    Media    *types.MediaContent    // Media content (for ChunkMedia)
    Message  *Response              // Complete response (for ChunkDone)
    Error    error                  // Error if any
}

ChunkType Constants

const (
    ChunkText     ChunkType = iota // 0 - text content
    ChunkToolCall                  // 1 - tool call
    ChunkMedia                     // 2 - media content
    ChunkDone                      // 3 - streaming complete
)

Handler Types

ToolHandler

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

ToolHandlerCtx

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

Error Types

var (
    ErrConversationClosed  = errors.New("conversation is closed")
    ErrConversationNotFound = errors.New("conversation not found")
    ErrNoStateStore        = errors.New("no state store configured")
    ErrPromptNotFound      = errors.New("prompt not found in pack")
    ErrPackNotFound        = errors.New("pack file not found")
    ErrProviderNotDetected = errors.New("could not detect provider: no API keys found in environment")
    ErrToolNotRegistered   = errors.New("tool handler not registered")
    ErrToolNotInPack       = errors.New("tool not defined in pack")
)

Package Import

import (
    "github.com/AltairaLabs/PromptKit/sdk"
    "github.com/AltairaLabs/PromptKit/sdk/hooks"
    "github.com/AltairaLabs/PromptKit/sdk/tools"

    // Hooks & guardrails
    rthooks "github.com/AltairaLabs/PromptKit/runtime/hooks"
    "github.com/AltairaLabs/PromptKit/runtime/hooks/guardrails"
)

Additional References

Audio & Voice

• Audio API - VAD mode, ASM mode, turn detection, audio streaming
• TTS API - Text-to-speech services, voices, formats, providers
• Streaming Package - Bidirectional streaming utilities, response collection, audio streaming

Dynamic Variables

• Variable Providers - Dynamic variable resolution, built-in providers, custom providers

A2A Server

• A2A Server - A2AServer, A2ATaskStore, A2AConversationOpener

Related

• ConversationManager - Legacy conversation management

See Also

• Tutorials
• How-To Guides
• Examples