@bernierllc/chat-agent-prompt-manager

Prompt management with versioning, templating, multi-language support, and multiple source types for chat agents.

Features

• ✅ Semantic Versioning - Track prompt versions with automatic version bumping
• ✅ Variable Templating - Use {{variable}} syntax with automatic substitution
• ✅ Multi-language Support - Language-aware resolution with fallbacks
• ✅ Multiple Sources - Load prompts from files, APIs, or inline configuration
• ✅ Resolution Hierarchy - location → persona → global → default
• ✅ Type-Safe - Full TypeScript support with strict typing
• ✅ Validation - Built-in prompt configuration validation
• ✅ Zero Dependencies - Uses @bernierllc/ai-prompt-builder for templating

Installation

npm install @bernierllc/chat-agent-prompt-manager

Quick Start

import { PromptManager } from '@bernierllc/chat-agent-prompt-manager';

// Initialize manager
const manager = new PromptManager({
  promptsPath: './prompts',
  defaultLanguage: 'en',
  enableVersioning: true
});

await manager.initialize();

// Register a prompt
await manager.registerPrompt({
  id: 'greeting',
  name: 'Customer Greeting',
  content: 'Hello {{name}}, welcome to {{company}}!',
  version: '1.0.0',
  language: 'en',
  variables: ['name', 'company'],
  source: 'inline'
});

// Resolve and use the prompt
const resolved = await manager.resolvePrompt({
  promptId: 'greeting',
  variables: { name: 'Alice', company: 'Acme Corp' }
});

console.log(resolved.resolvedContent);
// Output: "Hello Alice, welcome to Acme Corp!"

Usage

Creating Prompts

Inline Prompts

import { InlineLoader } from '@bernierllc/chat-agent-prompt-manager';

const prompt = InlineLoader.createFromInline({
  name: 'Support Greeting',
  content: 'Hello {{customerName}}! How can I help you with {{issue}}?',
  version: '1.0.0',
  language: 'en'
});

await manager.registerPrompt(prompt);

From Markdown Files

Create a prompt file:

---
id: customer-support
name: Customer Support Prompt
version: 1.0.0
language: en
---

Hello {{customerName}}!

Thank you for contacting {{companyName}} support.

Load it:

const prompt = await manager.loadPromptFromFile('./prompts/customer-support.md');

From API

const prompt = await manager.loadPromptFromApi('https://api.example.com/prompts/greeting');

Variable Substitution

// Extract variables from a template
const variables = manager.extractVariables('Hello {{name}}, you are {{age}} years old');
// Returns: ['name', 'age']

// Substitute variables
const result = manager.substituteVariables(
  'Hello {{name}}!',
  { name: 'World' }
);
// Returns: "Hello World!"

Version Management

// Get latest version
const latest = await manager.getLatestPrompt('greeting');

// Get specific version
const specific = await manager.getPrompt('greeting', '1.0.0');

// Update prompt (creates new version)
const updated = await manager.updatePrompt(
  'greeting',
  { content: 'Updated greeting: Hello {{name}}!' },
  'minor' // major | minor | patch
);

// Get version history
const history = await manager.getPromptVersions('greeting');

Multi-language Support

// Register prompts in different languages
await manager.registerPrompt({
  id: 'greeting',
  name: 'English Greeting',
  content: 'Hello {{name}}!',
  version: '1.0.0',
  language: 'en',
  source: 'inline'
});

await manager.registerPrompt({
  id: 'greeting',
  name: 'Spanish Greeting',
  content: '¡Hola {{name}}!',
  version: '1.0.0',
  language: 'es',
  source: 'inline'
});

// Resolve with language preference
const resolved = await manager.resolvePrompt({
  promptId: 'greeting',
  language: 'es',
  variables: { name: 'Maria' }
});
// Returns: "¡Hola Maria!"

Resolution Hierarchy

The PromptManager uses a hierarchical resolution system:

1. Location-specific - Prompts scoped to a specific location
2. Persona-specific - Prompts scoped to a specific persona
3. Global - Prompts available globally
4. Default - Fallback prompts

// Register location-specific prompt
await manager.registerPrompt(prompt, { locationId: 'store-123' });

// Register persona-specific prompt
await manager.registerPrompt(prompt, { personaId: 'support-agent' });

// Resolve with context
const resolved = await manager.resolvePrompt({
  promptId: 'greeting',
  locationId: 'store-123',
  personaId: 'support-agent',
  language: 'en',
  variables: { name: 'Customer' }
});

Validation

const result = manager.validatePrompt({
  id: 'test',
  name: 'Test Prompt',
  content: 'Hello {{name}}!',
  version: '1.0.0',
  language: 'en',
  source: 'inline'
});

if (!result.valid) {
  console.error('Validation errors:', result.errors);
}

if (result.warnings?.length) {
  console.warn('Warnings:', result.warnings);
}

Listing Prompts

// List all prompts
const allPrompts = await manager.listPrompts();

// Filter by language
const englishPrompts = await manager.listPrompts({ language: 'en' });

// Filter by source
const filePrompts = await manager.listPrompts({ source: 'file' });

// Filter by version
const v1Prompts = await manager.listPrompts({ version: '1.0.0' });

API Reference

PromptManager

Constructor

new PromptManager(config?: PromptManagerConfig)

Configuration options:

• promptsPath: Base path for file-based prompts (default: './prompts')
• defaultLanguage: Default language code (default: 'en')
• enableVersioning: Enable version management (default: true)
• enableNeverHub: Enable NeverHub integration (default: false)
• logger: Optional logger instance

Methods

• initialize(): Initialize the manager
• registerPrompt(prompt, scope?): Register a prompt with optional scope
• loadPromptFromFile(filePath, options?): Load from markdown file
• loadPromptFromApi(apiUrl, options?): Load from API endpoint
• resolvePrompt(context): Resolve prompt with context
• getPrompt(id, version?): Get prompt by ID and optional version
• getLatestPrompt(id): Get latest version of a prompt
• getPromptVersions(id): Get version history
• listPrompts(filters?): List all prompts with optional filters
• updatePrompt(id, updates, versionBump?): Update prompt (creates new version)
• deletePrompt(id): Delete prompt and all versions
• validatePrompt(prompt): Validate prompt configuration
• substituteVariables(template, variables): Substitute variables in template
• extractVariables(template): Extract variable names from template

InlineLoader

• createFromInline(config): Create prompt from inline configuration
• createManyFromInline(configs): Create multiple prompts
• createSimple(name, content, options?): Create simple prompt
• validateConfig(config): Validate inline configuration

FileLoader

• loadFromFile(filePath, options?): Load single prompt from file
• loadFromDirectory(directoryPath, options?): Load all prompts from directory
• saveToFile(prompt, filePath?): Save prompt to file
• fileExists(filePath): Check if file exists
• listFiles(directoryPath?): List all prompt files in directory

ApiLoader

• loadFromApi(apiUrl, options?): Load single prompt from API
• loadManyFromApi(apiUrl, options?): Load multiple prompts from API
• saveToApi(prompt, apiUrl?): Save prompt to API
• setAuthHeader(token, type?): Set authentication header
• setHeader(key, value): Set custom header

Type Definitions

interface PromptConfig {
  id: string;
  name: string;
  description?: string;
  content: string;
  version: string;
  language: string;
  variables?: string[];
  source: 'file' | 'api' | 'inline';
  sourcePath?: string;
  metadata?: Record<string, any>;
  createdAt?: Date;
  updatedAt?: Date;
}

interface PromptResolutionContext {
  promptId?: string;
  personaId?: string;
  locationId?: string;
  language?: string;
  variables?: Record<string, string | number | boolean>;
}

interface ResolvedPrompt {
  prompt: PromptConfig;
  resolvedContent: string;
  source: 'persona' | 'location' | 'global' | 'default';
  version: string;
  language: string;
  inheritedFrom?: string;
}

Integration Status

• Logger: Optional - Can use @bernierllc/logger for logging operations
• Docs-Suite: Ready - Full API documentation available
• NeverHub: Optional - Can integrate with NeverHub for service discovery

Examples

See the examples directory for more detailed examples:

• Basic usage
• Multi-language prompts
• Version management
• Custom loaders
• API integration

Contributing

This package follows BernierLLC quality standards:

• 90%+ test coverage (core package requirement)
• Zero TypeScript errors in strict mode
• Zero linting errors or warnings
• Complete API documentation

License

Copyright (c) 2025 Bernier LLC

This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.