npm package: @hyperchimp/persona-factory
Description: PersonaFactory SDK — define, cache, and invoke AI personas with structured identity, memory, security, and tool access
Latest version: 0.3.1

# @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

```typescript
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

```typescript
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: "vendor@example.com",
  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:

```bash
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

```bash
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:

```bash
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:

```typescript
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