API Reference

Toolpack Class

The main entry point for the SDK.

Initialization

import { Toolpack } from 'toolpack-sdk';

const toolpack = await Toolpack.init(config: ToolpackInitConfig);

ToolpackInitConfig

interface ToolpackInitConfig {
    // Single provider (shorthand)
    provider?: string;           // 'openai' | 'anthropic' | 'gemini' | 'ollama'
    apiKey?: string;             // API key for the provider
    model?: string;              // Default model
    
    // Multi-provider
    providers?: Record<string, ProviderOptions>;
    defaultProvider?: string;
    
    // Custom providers
    customProviders?: ProviderAdapter[] | Record<string, ProviderAdapter>;
    
    // Tools
    tools?: boolean;             // Enable built-in tools
    customTools?: ToolProject[]; // Custom tool projects
    
    // Modes
    customModes?: ModeConfig[];  // Custom modes
    defaultMode?: string;        // Default mode name
    modeOverrides?: Record<string, { systemPrompt?: string }>;
}

Methods

generate()

Generate a completion (non-streaming).

// Full request
const response = await toolpack.generate({
    messages: [{ role: 'user', content: 'Hello' }],
    model: 'gpt-4o',
});

// Shorthand
const response = await toolpack.generate('Hello');

// With specific provider
const response = await toolpack.generate(request, 'anthropic');

stream()

Stream a completion.

const stream = toolpack.stream({
    messages: [{ role: 'user', content: 'Hello' }],
    model: 'gpt-4o',
});

for await (const chunk of stream) {
    process.stdout.write(chunk.delta);
}

embed()

Generate embeddings.

const response = await toolpack.embed({
    input: 'Hello world',
    model: 'text-embedding-3-small',
});

console.log(response.embeddings); // number[][]

setProvider()

Switch the active provider.

toolpack.setProvider('anthropic');

getProvider()

Get the current provider adapter.

const provider = toolpack.getProvider();

loadToolProject()

Load a custom tool project dynamically at runtime.

import { myCustomTools } from './my-tools';

await toolpack.loadToolProject(myCustomTools);

listProviders()

List all configured providers and their models.

const providers = await toolpack.listProviders();
// [{ name, displayName, type, models }]

listModels()

Get a flat list of all models.

const models = await toolpack.listModels();
// [{ id, displayName, capabilities, provider }]

setMode()

Switch the active mode.

toolpack.setMode('chat');

getMode()

Get the current mode configuration.

const mode = toolpack.getMode();

getModes()

Get all registered modes.

const modes = toolpack.getModes();

cycleMode()

Cycle to the next mode.

const nextMode = toolpack.cycleMode();

registerMode()

Register a custom mode at runtime.

toolpack.registerMode(modeConfig);

getClient()

Get the underlying AIClient instance.

const client = toolpack.getClient();
client.on('tool:progress', handler);

getWorkflowExecutor()

Get the workflow executor.

const executor = toolpack.getWorkflowExecutor();

disconnect()

Disconnect the active provider.

await toolpack.disconnect();

Types

Message

interface Message {
    role: 'system' | 'user' | 'assistant' | 'tool';
    content: string | MessageContent[] | null;
    name?: string;
    tool_call_id?: string;
    tool_calls?: ToolCallMessage[];
}

CompletionRequest

interface CompletionRequest {
    messages: Message[];
    model: string;
    temperature?: number;
    max_tokens?: number;
    top_p?: number;
    response_format?: 'text' | 'json_object';
    stream?: boolean;
    tools?: ToolCallRequest[];
    tool_choice?: 'auto' | 'none' | 'required';
    signal?: AbortSignal;
}

CompletionResponse

interface CompletionResponse {
    content: string | null;
    usage?: Usage;
    finish_reason?: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
    tool_calls?: ToolCallResult[];
}

CompletionChunk

interface CompletionChunk {
    delta: string;
    usage?: Usage;
    finish_reason?: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
    tool_calls?: ToolCallResult[];
    workflowStep?: { number: number; description: string };
}

ModeConfig

interface ModeConfig {
    name: string;
    displayName: string;
    description: string;
    systemPrompt: string;
    allowedToolCategories: string[];
    blockedToolCategories: string[];
    allowedTools: string[];
    blockedTools: string[];
    blockAllTools: boolean;
    baseContext?: { ... } | false;
    workflow?: WorkflowConfig;
}

ProviderAdapter

abstract class ProviderAdapter {
    name?: string;
    abstract generate(request: CompletionRequest): Promise<CompletionResponse>;
    abstract stream(request: CompletionRequest): AsyncGenerator<CompletionChunk>;
    abstract embed(request: EmbeddingRequest): Promise<EmbeddingResponse>;
    async getModels(): Promise<ProviderModelInfo[]>;
    getDisplayName(): string;
}

ToolContext

Context passed to custom tools during execution.

interface ToolContext {
    workspaceRoot: string;
    config: Record<string, any>; // from toolpack.config.json
    log: (msg: string) => void;
}

createToolProject

Factory function to build and validate a ToolProject.

import { createToolProject, ToolDefinition, ToolProject } from 'toolpack-sdk';

const myToolProject: ToolProject = createToolProject({
    key: 'my-project',
    name: 'My Custom Tools',
    displayName: 'My Custom Tools Package',
    version: '1.0.0',
    description: 'Example custom tool project',
    category: 'custom',
    tools: [ /* ToolDefinition objects */ ]
});

Events

Toolpack Events

toolpack.on('status', (message: string) => {});
toolpack.on('workflow:plan_created', (plan) => {});
toolpack.on('workflow:started', (plan) => {});
toolpack.on('workflow:step_start', (step, plan) => {});
toolpack.on('workflow:step_complete', (step, plan) => {});
toolpack.on('workflow:step_failed', (step, error, plan) => {});
toolpack.on('workflow:progress', (progress) => {});
toolpack.on('workflow:completed', (plan, result) => {});
toolpack.on('workflow:failed', (plan, error) => {});

Client Events

const client = toolpack.getClient();
client.on('tool:progress', (event: ToolProgressEvent) => {});
client.on('tool:log', (event: ToolLogEvent) => {});