SDK v2 API Reference

Complete reference documentation for the PromptKit SDK v2 API.

Overview

The SDK v2 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:

Returns:

Example:

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

Options

WithModel

Override the model.

sdk.WithModel("gpt-4o")

WithTemperature

Override temperature.

sdk.WithTemperature(0.8)

WithMaxTokens

Override max tokens.

sdk.WithMaxTokens(2000)

Conversation Type

Send

Send a message and get a response.

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

Stream

Stream a response.

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

SetVar

Set a template variable.

func (c *Conversation) SetVar(key string, value any)

GetVar

Get a template variable.

func (c *Conversation) GetVar(key string) any

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 CheckFunc, execute ToolHandler)

OnToolHTTP

Register an HTTP tool.

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

Subscribe

Subscribe to events.

func (c *Conversation) Subscribe(event string, handler func(hooks.Event))

Messages

Get conversation history.

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

Clear

Clear conversation history.

func (c *Conversation) Clear()

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) (*ToolResult, error)

RejectTool

Reject a pending tool.

func (c *Conversation) RejectTool(id string, reason string) (*ToolResult, 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() []ToolCall

PendingTools

Get pending approvals.

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

StreamChunk Type

type StreamChunk struct {
    Type  ChunkType // ChunkText, ChunkToolCall, ChunkDone
    Text  string    // Text content
    Error error     // Error if any
}

ChunkType Constants

const (
    ChunkText     ChunkType = "text"
    ChunkToolCall ChunkType = "tool_call"
    ChunkDone     ChunkType = "done"
)

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 (
    ErrPackNotFound       = errors.New("pack file not found")
    ErrPromptNotFound     = errors.New("prompt not found in pack")
    ErrInvalidPack        = errors.New("invalid pack format")
    ErrProviderError      = errors.New("provider error")
    ErrConversationClosed = errors.New("conversation closed")
    ErrToolNotRegistered  = errors.New("tool not registered")
)

Package Import

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

Additional References

Audio & Voice

Dynamic Variables

See Also