@bernierllc/chat-agent-persona-manager

Persona configuration and management for chat agents with baseline personas and custom persona support.

Installation

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

Features

• Baseline Personas - Pre-configured personas (customer-support, internal-help, developer-support)
• Custom Personas - Define personas via markdown files or API endpoints
• Persona Resolution - Hierarchy-based resolution (location → persona → global → default)
• Inheritance Tracking - Shows which level provided the persona
• Full CRUD Operations - Create, read, update, delete personas
• Validation - Built-in persona configuration validation

Usage

Basic Setup

import { PersonaManager } from '@bernierllc/chat-agent-persona-manager';

const manager = new PersonaManager();
await manager.initialize();

// List baseline personas
const baselines = manager.listBaselinePersonas();
console.log(baselines); // [{ id: 'customer-support', ... }, ...]

Persona Resolution

The manager resolves personas using a hierarchy: location → user → global → default

// Resolve persona for a specific context
const resolved = await manager.resolvePersona({
  locationId: 'store-123',     // Most specific
  userId: 'user-456',          // User-specific
  globalPersona: 'global-id'   // Global fallback
});

console.log(resolved.persona);      // The resolved persona config
console.log(resolved.source);       // 'location' | 'persona' | 'global' | 'default'
console.log(resolved.inheritedFrom); // "Location: store-123"

Custom Personas

From Markdown Files

// Load persona from markdown file
const persona = await manager.loadPersonaFromFile('./personas/custom-support.md');

// Register it
await manager.registerCustomPersona(persona);

Markdown File Format:

---
name: Custom Support Agent
description: Specialized support persona
id: custom-support
---

# Custom Support Agent

You are a specialized support agent...

From API Endpoints

// Load persona from API
const persona = await manager.loadPersonaFromApi(
  'https://api.example.com/personas/custom'
);

// Register it
await manager.registerCustomPersona(persona);

API Response Format:

{
  "id": "custom-support",
  "name": "Custom Support Agent",
  "description": "Specialized support persona",
  "promptApi": "https://api.example.com/personas/custom/prompt",
  "metadata": {
    "version": "1.0",
    "tags": ["support", "specialized"]
  }
}

CRUD Operations

// Get persona by ID
const persona = await manager.getPersona('customer-support');

// List all personas (baseline + custom)
const allPersonas = await manager.listPersonas();

// List only custom personas
const customPersonas = await manager.listCustomPersonas();

// Update persona
const updated = await manager.updatePersona('custom-support', {
  name: 'Updated Name',
  description: 'New description'
});

// Delete custom persona (baseline personas cannot be deleted)
await manager.deletePersona('custom-support');

Validation

const result = manager.validatePersona({
  id: 'test-persona',
  name: 'Test Persona',
  prompt: './personas/test.md'
});

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

API Reference

PersonaManager

Constructor

new PersonaManager(config?: PersonaManagerConfig)

Config Options:

• baselinePersonas?: Record<string, PersonaConfig> - Override default baseline personas
• customPersonasPath?: string - Path to custom personas directory
• enableNeverHub?: boolean - Enable NeverHub integration (optional)
• logger?: Logger - Optional logger instance

Methods

• initialize(): Promise<void> - Initialize the manager
• registerBaselinePersona(persona: PersonaConfig): void - Register baseline persona
• registerCustomPersona(persona: PersonaConfig): Promise<void> - Register custom persona
• loadPersonaFromFile(filePath: string): Promise<PersonaConfig> - Load from markdown file
• loadPersonaFromApi(apiUrl: string): Promise<PersonaConfig> - Load from API endpoint
• resolvePersona(context: PersonaResolutionContext): Promise<ResolvedPersona> - Resolve persona
• getPersona(personaId: string): Promise<PersonaConfig | null> - Get persona by ID
• listPersonas(): Promise<PersonaConfig[]> - List all personas
• listBaselinePersonas(): PersonaConfig[] - List baseline personas
• listCustomPersonas(): Promise<PersonaConfig[]> - List custom personas
• updatePersona(personaId: string, updates: Partial<PersonaConfig>): Promise<PersonaConfig> - Update persona
• deletePersona(personaId: string): Promise<void> - Delete custom persona
• validatePersona(persona: PersonaConfig): ValidationResult - Validate persona config

Types

PersonaConfig

interface PersonaConfig {
  id: string;
  name: string;
  description?: string;
  prompt?: string;         // Path to markdown file
  promptApi?: string;      // API endpoint URL
  metadata?: Record<string, any>;
  createdAt?: Date;
  updatedAt?: Date;
}

PersonaResolutionContext

interface PersonaResolutionContext {
  locationId?: string;     // Most specific (store, region, etc.)
  userId?: string;         // User-specific persona
  globalPersona?: string;  // Global fallback
}

ResolvedPersona

interface ResolvedPersona {
  persona: PersonaConfig;
  source: 'location' | 'persona' | 'global' | 'default';
  locationId?: string;
  inheritedFrom?: string;
}

Baseline Personas

The package includes three pre-configured baseline personas:

1. Customer Support (customer-support)

• Purpose: External customer support
• Tone: Friendly, empathetic, professional
• Use Case: Customer service chatbots, help desk

2. Internal Help Desk (internal-help)

• Purpose: Internal employee support
• Tone: Technical, efficient, direct
• Use Case: IT help desk, employee support

3. Developer Support (developer-support)

• Purpose: Technical developer assistance
• Tone: Precise, detailed, educational
• Use Case: API documentation, SDK support

Advanced Usage

With Logger Integration

import { PersonaManager } from '@bernierllc/chat-agent-persona-manager';

const logger = {
  info: (msg: string) => console.log('[INFO]', msg),
  warn: (msg: string) => console.warn('[WARN]', msg),
  error: (msg: string) => console.error('[ERROR]', msg),
  debug: (msg: string) => console.log('[DEBUG]', msg)
};

const manager = new PersonaManager({ logger });
await manager.initialize();

Custom Baseline Personas

const manager = new PersonaManager({
  baselinePersonas: {
    'my-custom-baseline': {
      id: 'my-custom-baseline',
      name: 'My Custom Baseline',
      description: 'Custom baseline persona',
      prompt: './personas/my-custom.md'
    }
  }
});

await manager.initialize();

Integration Status

• Logger: Optional - Supports @bernierllc/logger for operation logging
• Docs-Suite: Ready - Complete API documentation with examples
• NeverHub: Optional - Can integrate for service discovery (config: enableNeverHub: true)

Error Handling

All async methods throw descriptive errors:

try {
  const persona = await manager.loadPersonaFromFile('./nonexistent.md');
} catch (error) {
  console.error(error.message);
  // "Persona file not found: ./nonexistent.md"
}

try {
  await manager.deletePersona('customer-support');
} catch (error) {
  console.error(error.message);
  // "Cannot delete baseline persona: customer-support"
}

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests once (no watch)
npm run test:run

Building

# Build TypeScript
npm run build

# Clean build artifacts
npm run clean

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

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.

See Also

• @bernierllc/chat-agent-orchestrator - Uses this package for persona resolution
• @bernierllc/logger - Optional logging integration
• @bernierllc/neverhub-adapter - Optional service discovery