@braingrid/prompts

Prompt management with context interpolation, token calculation, and metrics.

Features

• Pluggable Storage - Memory, filesystem, or custom backends
• Token Calculation - Accurate token counting with tiktoken
• Context Interpolation - {{variable}} template syntax
• Metrics - Track tokens, characters, words, lines
• Caching - Performance optimization for repeated access

Installation

pnpm add @braingrid/prompts

Quick Start

import { PromptService, MemoryPromptStorage } from '@braingrid/prompts';

// 1. Create storage
const storage = new MemoryPromptStorage({
  chat_system: 'You are a helpful assistant for {{userName}}.',
  research_system: 'You are a research assistant for {{userName}} at {{companyName}}.',
});

// 2. Create service
const prompts = new PromptService({ storage });

// 3. Get prompt
const prompt = await prompts.getPrompt('chat_system');

// 4. Get prompt with context
const interpolated = await prompts.getPromptWithContext('chat_system', {
  userName: 'Alice',
});
// => "You are a helpful assistant for Alice."

// 5. Get metrics
const metrics = await prompts.getPromptWithMetrics('chat_system');
console.log(metrics);
// => { name: 'chat_system', content: '...', tokens: 12, characters: 45, words: 8, lines: 1 }

Storage Backends

MemoryPromptStorage

import { MemoryPromptStorage } from '@braingrid/prompts';

const storage = new MemoryPromptStorage({
  chat_system: 'You are a chat assistant.',
  research_system: 'You are a research assistant.',
});

storage.set('new_prompt', 'You are...');
storage.has('chat_system'); // true
storage.list(); // ['chat_system', 'research_system', 'new_prompt']

FileSystemPromptStorage

import { FileSystemPromptStorage } from '@braingrid/prompts';

const storage = new FileSystemPromptStorage('./prompts');

// Reads from:
// ./prompts/chat_system.txt
// ./prompts/chat_system.md
// ./prompts/research_system.txt
// etc.

Custom Storage

import { type PromptStorage } from '@braingrid/prompts';

class DatabasePromptStorage implements PromptStorage {
  async get(name: string): Promise<string | undefined> {
    const row = await db.query('SELECT content FROM prompts WHERE name = $1', [name]);
    return row?.content;
  }

  async list(): Promise<string[]> {
    const rows = await db.query('SELECT name FROM prompts');
    return rows.map(r => r.name);
  }
}

const storage = new DatabasePromptStorage(db);
const service = new PromptService({ storage });

Token Calculation

import { PromptService, TiktokenCalculator, ApproximateTokenCalculator } from '@braingrid/prompts';

// Accurate token counting (requires tiktoken)
const service = new PromptService({
  storage,
  tokenCalculator: new TiktokenCalculator('gpt-4'),
});

// Fast approximation (no dependencies)
const service2 = new PromptService({
  storage,
  tokenCalculator: new ApproximateTokenCalculator(),
});

Context Interpolation

const storage = new MemoryPromptStorage({
  greeting: 'Hello {{userName}}, welcome to {{companyName}}!',
  nested: 'User {{user.firstName}} {{user.lastName}} from {{user.company.name}}',
});

const service = new PromptService({ storage });

const prompt1 = await service.getPromptWithContext('greeting', {
  userName: 'Alice',
  companyName: 'ACME Corp',
});
// => "Hello Alice, welcome to ACME Corp!"

const prompt2 = await service.getPromptWithContext('nested', {
  user: {
    firstName: 'Bob',
    lastName: 'Smith',
    company: { name: 'TechCo' },
  },
});
// => "User Bob Smith from TechCo"

Integration with Agents

import { PromptService, FileSystemPromptStorage } from '@braingrid/prompts';
import { PromptManager } from '@braingrid/agents';

const storage = new FileSystemPromptStorage('./prompts');
const promptService = new PromptService({ storage });

// Use with PromptManager
const manager = new PromptManager({
  agentType: 'chat',
  storage,
});

const prompt = await manager.getPrompt({ userName: 'Alice' });

License

MIT