@hyperchimp/persona-factory

Hybrid persona engine — SDK + Service for HyperChimp products.

Architecture

+-------------------+       +---------------------+       +-----------+
|   HyperBot /      |       |   PersonaFactory    |       |  Claude / |
|   HyperLine       | ----> |   SDK               | ----> |  GPT      |
|   (consumer app)  |       |   (prompt assembly,  |       |  (LLM)    |
|                   |       |    memory, tools)    |       |           |
+-------------------+       +----------+----------+       +-----------+
                                       |
                                       v
                            +----------+----------+
                            |  PersonaFactory     |
                            |  Service (REST API) |
                            |  (CRUD, versioning, |
                            |   usage tracking)   |
                            +---------------------+

Quick Start: HyperBot Integration

import { HyperBotAdapter } from "@hyperchimp/persona-factory";

// 1. Create adapter
const bot = new HyperBotAdapter({
  serviceUrl: "http://localhost:3100",
  apiKey: process.env.PF_API_KEY!,
  personaId: "pf_your_persona_id",
  toolHandler: async (call) => {
    // Implement your tools here
    if (call.name === "searchKnowledgeBase") {
      return myKB.search(call.args.query as string);
    }
  },
});

// 2. Initialize (preloads persona, starts cache)
await bot.init();

// 3. Reply to messages — memory + usage built in
const response = await bot.reply("session-123", "What are your hours?");
console.log(response.text);

HyperBotAdapter auto-registers these tool stubs (provide implementations via toolHandler):

• searchKnowledgeBase — Search knowledge base articles
• createTicket — Create support tickets
• escalateToHuman — Hand off to human agent
• getCustomerInfo — Look up customer data

Quick Start: HyperLine Integration

import { HyperLineAdapter } from "@hyperchimp/persona-factory";

// 1. Create adapter with role
const ea = new HyperLineAdapter({
  serviceUrl: "http://localhost:3100",
  apiKey: process.env.PF_API_KEY!,
  personaId: "pf_your_persona_id",
  role: "ea", // "ea" | "cs" | "sales"
  toolHandler: async (call) => {
    if (call.name === "searchInbox") {
      return myEmail.search(call.args.query as string);
    }
  },
});

await ea.init();

// 2. General assistance
const response = await ea.assist("user-456", "Schedule a meeting with Sarah tomorrow");

// 3. Email triage
const triageResult = await ea.triage("user-456", {
  from: "[email protected]",
  subject: "Invoice #1234",
  body: "Please find attached invoice for March services.",
});

HyperLineAdapter tool stubs:

• draftEmail — Draft email messages
• searchInbox — Search email inbox
• scheduleEvent — Schedule calendar events
• lookupContact — Look up contacts
• triageEmail — Classify and prioritize emails

Migration Guide: Zo Personas to PersonaFactory

Prerequisites

• Zo API credentials (URL + key)
• PersonaFactory service running
• PersonaFactory API key

Step 1: Dry Run

Preview what will be migrated without making changes:

bun run packages/cli/src/index.ts migrate \
  --source zo \
  --target http://localhost:3100 \
  --api-key $PF_API_KEY \
  --zo-api-url $ZO_API_URL \
  --zo-api-key $ZO_API_KEY \
  --dry-run

Step 2: Migrate

bun run packages/cli/src/index.ts migrate \
  --source zo \
  --target http://localhost:3100 \
  --api-key $PF_API_KEY \
  --zo-api-url $ZO_API_URL \
  --zo-api-key $ZO_API_KEY

Step 3: Verify

Compare a migrated persona against its Zo source:

bun run packages/cli/src/index.ts diff \
  --persona-id pf_migrated_id \
  --zo-name "Original Zo Name" \
  --service-url http://localhost:3100 \
  --api-key $PF_API_KEY \
  --zo-api-url $ZO_API_URL \
  --zo-api-key $ZO_API_KEY

What Gets Migrated

| Zo Field | PersonaFactory Field | Notes | |----------|---------------------|-------| | name | name | Direct mapping | | instructions | identity.role | All in Block 1 | | model | model.modelId | Auto-detects provider | | tools | tools (stubs) | Interface only | | — | knowledge.static | Empty — populate manually | | — | workflow.steps | Empty — populate manually |

Post-Migration TODO

After migration, manually review each persona to:

1. Split long identity.role into knowledge blocks (Block 2)
2. Add workflow steps if the persona has a process
3. Configure memory settings
4. Set up tool access rules
5. Test with real traffic before cutting over

SDK API Reference

PersonaClient

Core client — use directly for full control:

import { PersonaClient } from "@hyperchimp/persona-factory";

const client = new PersonaClient({
  serviceUrl: "http://localhost:3100",
  apiKey: "your-key",
});

await client.init();
const response = await client.chat({
  personaId: "pf_xxx",
  messages: [{ role: "user", content: "Hello" }],
  conversationId: "conv-1",
});

Adapters vs PersonaClient

• Use adapters for standard HyperBot/HyperLine integrations
• Use PersonaClient for custom products or advanced workflows
• Adapters delegate to PersonaClient — no logic duplication