Skip to content
PromptKit Logo PromptKit

SDK Reference

Complete reference documentation for the PromptKit SDK API.

Overview

Section titled “Overview”

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

Core Functions

Section titled “Core Functions”

sdk.Open

Section titled “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

Section titled “Options”

WithModel

Section titled “WithModel”

Override the model.

sdk.WithModel("gpt-4o")

WithTemperature

Section titled “WithTemperature”

Override temperature.

sdk.WithTemperature(0.8)

WithMaxTokens

Section titled “WithMaxTokens”

Override max tokens.

sdk.WithMaxTokens(2000)

WithImageFile

Section titled “WithImageFile”

Attach an image from a file.

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

WithImageURL

Section titled “WithImageURL”

Attach an image from a URL.

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

WithImageData

Section titled “WithImageData”

Attach image from raw bytes.

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

WithDocumentFile

Section titled “WithDocumentFile”

Attach a PDF document from a file.

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

WithDocumentData

Section titled “WithDocumentData”

Attach a PDF document from raw bytes.

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

WithAudioFile

Section titled “WithAudioFile”

Attach an audio file.

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

WithVideoFile

Section titled “WithVideoFile”

Attach a video file.

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

Conversation Type

Section titled “Conversation Type”

Send

Section titled “Send”

Send a message and get a response.

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

Stream

Section titled “Stream”

Stream a response.

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

SetVar

Section titled “SetVar”

Set a template variable.

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

GetVar

Section titled “GetVar”

Get a template variable.

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

SetVars

Section titled “SetVars”

Set multiple variables.

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

OnTool

Section titled “OnTool”

Register a tool handler.

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

OnToolCtx

Section titled “OnToolCtx”

Register a tool handler with context.

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

OnTools

Section titled “OnTools”

Register multiple tool handlers.

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

OnToolAsync

Section titled “OnToolAsync”

Register a tool with approval workflow.

func (c *Conversation) OnToolAsync(name string, check CheckFunc, execute ToolHandler)

OnToolHTTP

Section titled “OnToolHTTP”

Register an HTTP tool.

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

Subscribe

Section titled “Subscribe”

Subscribe to events.

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

Messages

Section titled “Messages”

Get conversation history.

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

Clear

Section titled “Clear”

Clear conversation history.

func (c *Conversation) Clear()

Fork

Section titled “Fork”

Create an isolated copy.

func (c *Conversation) Fork() *Conversation

Close

Section titled “Close”

Close the conversation.

func (c *Conversation) Close() error

ID

Section titled “ID”

Get conversation ID.

func (c *Conversation) ID() string

ResolveTool

Section titled “ResolveTool”

Approve a pending tool.

func (c *Conversation) ResolveTool(id string) (*ToolResult, error)

RejectTool

Section titled “RejectTool”

Reject a pending tool.

func (c *Conversation) RejectTool(id string, reason string) (*ToolResult, error)

Response Type

Section titled “Response Type”

Text

Section titled “Text”

Get response text.

func (r *Response) Text() string

HasToolCalls

Section titled “HasToolCalls”

Check for tool calls.

func (r *Response) HasToolCalls() bool

ToolCalls

Section titled “ToolCalls”

Get tool calls.

func (r *Response) ToolCalls() []ToolCall

PendingTools

Section titled “PendingTools”

Get pending approvals.

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

StreamChunk Type

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

ChunkType Constants

Section titled “ChunkType Constants”
const (
    ChunkText     ChunkType = "text"
    ChunkToolCall ChunkType = "tool_call"
    ChunkDone     ChunkType = "done"
)

Handler Types

Section titled “Handler Types”

ToolHandler

Section titled “ToolHandler”
type ToolHandler func(args map[string]any) (any, error)

ToolHandlerCtx

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

Error Types

Section titled “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

Section titled “Package Import”
import (
    "github.com/AltairaLabs/PromptKit/sdk"
    "github.com/AltairaLabs/PromptKit/sdk/hooks"
    "github.com/AltairaLabs/PromptKit/sdk/tools"
)

Additional References

Section titled “Additional References”

Audio & Voice

Section titled “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

Section titled “Dynamic Variables”
Section titled “Related”

See Also

Section titled “See Also”