Skip to main content

​
PromptFormat

Output format for the generated prompt. Choose different formats based on your token optimization needs and readability requirements.

​
Type Definition

export type PromptFormat = "markdown" | "toon" | "compact";

​
Formats

​
markdown
literal
Standard markdown format (default). Human-readable with headers and formatting. Best for development and debugging.
​
toon
literal
TOON format (Token-Oriented Object Notation). Optimized format that reduces tokens by 30-60%. Best for production when token usage is a concern.
​
compact
literal
Minimal whitespace variant of markdown. Optimized for token usage while maintaining markdown structure.

​
Usage Example

import { PromptSmith } from 'promptsmith';

// Use TOON format for token optimization
const prompt = new PromptSmith()
  .withIdentity("Research Assistant")
  .withFormat('toon');

// Use standard markdown (default)
const prompt2 = new PromptSmith()
  .withIdentity("Research Assistant")
  .withFormat('markdown');

// Use compact markdown
const prompt3 = new PromptSmith()
  .withIdentity("Research Assistant")
  .withFormat('compact');

​
Format Comparison

FormatToken SavingsReadabilityUse Case
markdown0% (baseline)HighDevelopment, debugging
compact10-20%MediumProduction with some optimization
toon30-60%LowProduction with maximum optimization

​
When to Use Each Format

  • markdown: During development, testing, and when you need to inspect the generated prompt
  • compact: In production when you want some token savings but need to maintain markdown compatibility
  • toon: In production when token usage is critical and you’re optimizing for cost/performance

​
AiSdkConfig

Configuration object returned by .toAiSdk() for Vercel AI SDK integration. This interface defines the structure of the object that includes both the system prompt and tools formatted for use with Vercel’s AI SDK. The object can be spread directly into generateText, streamText, or other AI SDK function calls for seamless integration.

​
Type Definition

export type AiSdkConfig = {
  system: string;
  tools: Record<
    string,
    {
      description: string;
      parameters: z.ZodType;
      execute?: (args: unknown) => Promise<unknown> | unknown;
    }
  >;
};

​
Properties

​
system
string
required
The system prompt string generated by the builder. This is the same string returned by .build(), containing the complete markdown-formatted system prompt with identity, capabilities, tools documentation, constraints, and formatting guidelines.
​
tools
Record<string, ToolObject>
required
Tools in Vercel AI SDK format. A record mapping tool names to their AI SDK-compatible definitions.

​
Usage Example

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { PromptSmith } from 'promptsmith';
import { z } from 'zod';

// Create prompt with tools
const builder = new PromptSmith()
  .withIdentity("Weather Assistant")
  .withTool({
    name: "get_weather",
    description: "Get current weather for a location",
    schema: z.object({
      location: z.string().describe("City name")
    }),
    execute: async ({ location }) => {
      const response = await fetch(`https://api.weather.com/${location}`);
      return response.json();
    }
  });

// Get AI SDK config
const config = builder.toAiSdk();

// Use with Vercel AI SDK
const response = await generateText({
  model: openai('gpt-4'),
  ...config,  // Spreads system and tools
  prompt: "What's the weather in Paris?"
});

​
Streaming Example

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

const config = builder.toAiSdk();

const stream = await streamText({
  model: openai('gpt-4'),
  ...config,
  prompt: "What's the weather in London and Tokyo?"
});

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

​
Working with Tools

// Access the system prompt
console.log(config.system);

// Access tools
const toolNames = Object.keys(config.tools);
console.log('Available tools:', toolNames);

// Get specific tool
const weatherTool = config.tools['get_weather'];
console.log(weatherTool.description);
console.log(weatherTool.parameters);

// Call tool directly (if execute is defined)
if (weatherTool.execute) {
  const result = await weatherTool.execute({ location: 'Paris' });
  console.log(result);
}

​
Documentation-Only Tools

Tools without execution logic are supported: 
const builder = new PromptSmith()
  .withTool({
    name: "search_database",
    description: "Search the product database",
    schema: z.object({
      query: z.string()
    })
    // No execute function
  });

const config = builder.toAiSdk();

// Tool will be in config.tools but execute will be undefined
console.log(config.tools['search_database'].execute); // undefined
This is useful when:
  • You want to document available tools in the prompt
  • Tool execution happens client-side or through a different mechanism
  • You’re using a custom tool handling system

Build docs developers (and LLMs) love

Get started for freeTalk to us