@molroo-io/sdk 0.8.4 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/cjs/errors.d.ts +1 -1
  2. package/dist/cjs/errors.d.ts.map +1 -1
  3. package/dist/cjs/errors.js +2 -1
  4. package/dist/cjs/events/types.d.ts +1 -1
  5. package/dist/cjs/events/types.d.ts.map +1 -1
  6. package/dist/cjs/index.d.ts +4 -2
  7. package/dist/cjs/index.d.ts.map +1 -1
  8. package/dist/cjs/index.js +5 -1
  9. package/dist/cjs/llm/resolve.d.ts.map +1 -1
  10. package/dist/cjs/llm/resolve.js +2 -1
  11. package/dist/cjs/llm/schema.d.ts +0 -114
  12. package/dist/cjs/llm/schema.d.ts.map +1 -1
  13. package/dist/cjs/llm/schema.js +1 -44
  14. package/dist/cjs/persona/chat-orchestrator.d.ts +18 -3
  15. package/dist/cjs/persona/chat-orchestrator.d.ts.map +1 -1
  16. package/dist/cjs/persona/chat-orchestrator.js +29 -109
  17. package/dist/cjs/persona/conversation.d.ts +84 -0
  18. package/dist/cjs/persona/conversation.d.ts.map +1 -0
  19. package/dist/cjs/persona/conversation.js +72 -0
  20. package/dist/cjs/persona/memory-pipeline.d.ts.map +1 -1
  21. package/dist/cjs/persona/memory-pipeline.js +30 -4
  22. package/dist/cjs/persona.d.ts +441 -22
  23. package/dist/cjs/persona.d.ts.map +1 -1
  24. package/dist/cjs/persona.js +418 -6
  25. package/dist/cjs/shared/errors.d.ts +32 -2
  26. package/dist/cjs/shared/errors.d.ts.map +1 -1
  27. package/dist/cjs/shared/errors.js +33 -2
  28. package/dist/cjs/types.d.ts +70 -5
  29. package/dist/cjs/types.d.ts.map +1 -1
  30. package/dist/cjs/types.js +2 -1
  31. package/dist/cjs/world/world-persona.d.ts +20 -5
  32. package/dist/cjs/world/world-persona.d.ts.map +1 -1
  33. package/dist/cjs/world/world-persona.js +21 -5
  34. package/dist/cjs/world/world.d.ts +28 -5
  35. package/dist/cjs/world/world.d.ts.map +1 -1
  36. package/dist/cjs/world/world.js +29 -3
  37. package/dist/esm/errors.d.ts +1 -1
  38. package/dist/esm/errors.d.ts.map +1 -1
  39. package/dist/esm/errors.js +1 -1
  40. package/dist/esm/events/types.d.ts +1 -1
  41. package/dist/esm/events/types.d.ts.map +1 -1
  42. package/dist/esm/index.d.ts +4 -2
  43. package/dist/esm/index.d.ts.map +1 -1
  44. package/dist/esm/index.js +3 -1
  45. package/dist/esm/llm/resolve.d.ts.map +1 -1
  46. package/dist/esm/llm/resolve.js +2 -1
  47. package/dist/esm/llm/schema.d.ts +0 -114
  48. package/dist/esm/llm/schema.d.ts.map +1 -1
  49. package/dist/esm/llm/schema.js +0 -43
  50. package/dist/esm/persona/chat-orchestrator.d.ts +18 -3
  51. package/dist/esm/persona/chat-orchestrator.d.ts.map +1 -1
  52. package/dist/esm/persona/chat-orchestrator.js +29 -109
  53. package/dist/esm/persona/conversation.d.ts +84 -0
  54. package/dist/esm/persona/conversation.d.ts.map +1 -0
  55. package/dist/esm/persona/conversation.js +68 -0
  56. package/dist/esm/persona/memory-pipeline.d.ts.map +1 -1
  57. package/dist/esm/persona/memory-pipeline.js +30 -4
  58. package/dist/esm/persona.d.ts +441 -22
  59. package/dist/esm/persona.d.ts.map +1 -1
  60. package/dist/esm/persona.js +418 -7
  61. package/dist/esm/shared/errors.d.ts +32 -2
  62. package/dist/esm/shared/errors.d.ts.map +1 -1
  63. package/dist/esm/shared/errors.js +32 -1
  64. package/dist/esm/types.d.ts +70 -5
  65. package/dist/esm/types.d.ts.map +1 -1
  66. package/dist/esm/types.js +1 -1
  67. package/dist/esm/world/world-persona.d.ts +20 -5
  68. package/dist/esm/world/world-persona.d.ts.map +1 -1
  69. package/dist/esm/world/world-persona.js +21 -5
  70. package/dist/esm/world/world.d.ts +28 -5
  71. package/dist/esm/world/world.d.ts.map +1 -1
  72. package/dist/esm/world/world.js +29 -3
  73. package/package.json +1 -1
@@ -1 +1 @@
1
- {"version":3,"file":"persona.d.ts","sourceRoot":"","sources":["../../src/persona.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"persona.d.ts","sourceRoot":"","sources":["../../src/persona.ts"],"names":[],"mappings":"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"}
@@ -1,8 +1,9 @@
1
1
  import { resolveLLM } from './llm/resolve';
2
- import { MolrooApiError } from './errors';
2
+ import { MolrooApiError, MolrooErrorCode } from './errors';
3
3
  import { createApiClient, unwrap } from './api-client';
4
4
  import { postPerceive } from './persona/memory-pipeline';
5
5
  import { chat as chatOrchestrator } from './persona/chat-orchestrator';
6
+ import { Conversation } from './persona/conversation';
6
7
  // ── SDK Persona Types ──
7
8
  const DEFAULT_BASE_URL = 'https://api.molroo.io';
8
9
  // ── MolrooPersona ──
@@ -21,12 +22,13 @@ export class MolrooPersona {
21
22
  this.events = config.events ?? null;
22
23
  this.memoryAdapter = config.memory ?? null;
23
24
  this.memoryRecallConfig = config.recall;
24
- this.appraisalMode = config.appraisalMode ?? 'direct';
25
25
  }
26
26
  // ── Properties ──
27
+ /** Unique persona instance ID. */
27
28
  get id() {
28
29
  return this._personaId;
29
30
  }
31
+ /** @deprecated Use {@link id} instead. */
30
32
  get personaId() {
31
33
  return this._personaId;
32
34
  }
@@ -35,7 +37,7 @@ export class MolrooPersona {
35
37
  if (typeof input === 'string') {
36
38
  if (!config.llm) {
37
39
  throw new MolrooApiError('LLM adapter is required when using description string. ' +
38
- 'Provide llm option or use explicit PersonaConfigData.', 'LLM_REQUIRED', 400);
40
+ 'Provide llm option or use explicit PersonaConfigData.', MolrooErrorCode.LLM_REQUIRED, 400);
39
41
  }
40
42
  const { generatePersona } = await import('./generate/persona');
41
43
  const llm = await resolveLLM(config.llm);
@@ -70,6 +72,23 @@ export class MolrooPersona {
70
72
  static async generate(config, description) {
71
73
  return MolrooPersona.create(config, description);
72
74
  }
75
+ /**
76
+ * Connect to an existing persona by ID.
77
+ *
78
+ * @param config - Connection configuration (apiKey required).
79
+ * @param personaId - The persona instance ID to connect to.
80
+ * @returns A connected MolrooPersona instance.
81
+ *
82
+ * @deprecated Use {@link Molroo.connectPersona} instead.
83
+ *
84
+ * @example
85
+ * ```typescript
86
+ * const sera = await MolrooPersona.connect(
87
+ * { apiKey: 'mk_...', llm: openaiAdapter },
88
+ * 'persona_abc123'
89
+ * );
90
+ * ```
91
+ */
73
92
  static async connect(config, personaId) {
74
93
  const [llm, engineLlm] = await Promise.all([
75
94
  config.llm ? resolveLLM(config.llm) : undefined,
@@ -82,6 +101,12 @@ export class MolrooPersona {
82
101
  });
83
102
  return persona;
84
103
  }
104
+ /**
105
+ * List all personas for the authenticated tenant.
106
+ *
107
+ * @param config - API connection config.
108
+ * @returns Paginated list of persona summaries.
109
+ */
85
110
  static async listPersonas(config) {
86
111
  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
87
112
  const client = createApiClient(baseUrl, config.apiKey);
@@ -89,6 +114,14 @@ export class MolrooPersona {
89
114
  return unwrap(data);
90
115
  }
91
116
  // ── Runtime ──
117
+ /**
118
+ * Send a stimulus to the persona's emotion engine and get the updated emotional response.
119
+ * This is the low-level API — for common cases, prefer {@link hear}, {@link experience}, or {@link chat}.
120
+ *
121
+ * @param message - The stimulus text (user message, event description, etc.).
122
+ * @param options - Appraisal, source, relationship context, and other options.
123
+ * @returns Emotion engine response with VAD, discrete emotion, and side effects.
124
+ */
92
125
  async perceive(message, options) {
93
126
  const eventType = options?.type ?? 'chat_message';
94
127
  const sourceName = typeof options?.from === 'string'
@@ -125,9 +158,118 @@ export class MolrooPersona {
125
158
  }
126
159
  return response;
127
160
  }
161
+ /**
162
+ * Send a custom event with a required appraisal vector.
163
+ *
164
+ * @param type - Custom event type (e.g., 'gift_received', 'argument').
165
+ * @param description - Human-readable event description.
166
+ * @param options - Must include a pre-computed appraisal vector.
167
+ * @returns Emotion engine response.
168
+ */
128
169
  async event(type, description, options) {
129
170
  return this.perceive(description, { ...options, type });
130
171
  }
172
+ /**
173
+ * Register a received message with the emotion engine and update the persona's emotional state.
174
+ *
175
+ * This is the **core API** for the `hear() + getState()` pattern. Apps that build their own
176
+ * LLM prompts should call `hear()` after each user message to keep the emotion engine in sync,
177
+ * then call `getState()` to read updated state for prompt assembly.
178
+ *
179
+ * Use {@link chat} when you want the SDK to handle prompt assembly and LLM orchestration.
180
+ * Use `hear()` + `getState()` when your app owns the LLM call.
181
+ *
182
+ * @param message - The incoming message text (user utterance, narration, etc.).
183
+ * @param from - Who sent the message. A plain string is used as the source entity name.
184
+ * Pass an {@link InterlocutorContext} object for richer context (description, extensions).
185
+ * @returns Emotion engine response with updated VAD, discrete emotion, and any side effects
186
+ * (memory episodes, social updates, stage transitions, etc.).
187
+ *
188
+ * @example Basic hear + getState pattern
189
+ * ```typescript
190
+ * // Step 1: register message with emotion engine
191
+ * await persona.hear('You did a great job today!', 'Alice');
192
+ *
193
+ * // Step 2: read updated psychological state
194
+ * const state = await persona.getState();
195
+ *
196
+ * // Step 3: assemble your own system prompt
197
+ * const systemPrompt = buildPrompt(myPersonaConfig, state);
198
+ * const { text } = await myLLM.generate({ system: systemPrompt, messages });
199
+ * ```
200
+ *
201
+ * @example With structured interlocutor context
202
+ * ```typescript
203
+ * await persona.hear('I need your help', {
204
+ * name: 'Alice',
205
+ * description: 'A regular customer, slightly anxious',
206
+ * extensions: { mood: 'stressed' },
207
+ * });
208
+ * ```
209
+ */
210
+ async hear(message, from) {
211
+ return this.perceive(message, { from, type: 'chat_message' });
212
+ }
213
+ /**
214
+ * Perceive an environmental or narrative event with a pre-computed appraisal.
215
+ *
216
+ * @param description - What happened (e.g., 'The sun set over the ocean').
217
+ * @param appraisal - 9-dimensional Scherer CPM appraisal vector.
218
+ * @returns Emotion engine response.
219
+ *
220
+ * @example
221
+ * ```typescript
222
+ * const response = await persona.experience('Received a surprise gift', {
223
+ * goal_relevance: 0.8, goal_congruence: 0.9, expectedness: 0.2,
224
+ * controllability: 0.5, agency: 0.3, norm_compatibility: 0.8,
225
+ * internal_standards: 0.7, adjustment_potential: 0.6, urgency: 0.3,
226
+ * });
227
+ * ```
228
+ */
229
+ async experience(description, appraisal) {
230
+ return this.perceive(description, { appraisal, type: 'environment' });
231
+ }
232
+ /**
233
+ * Perceive a social interaction with relationship context for trust/intimacy computation.
234
+ *
235
+ * @param message - The interaction message.
236
+ * @param from - Who the interaction is from.
237
+ * @param relationship - Current relationship state (closeness, trust, familiarity).
238
+ * @returns Emotion engine response including socialUpdates.
239
+ *
240
+ * @example
241
+ * ```typescript
242
+ * const response = await persona.socialize('I missed you!', 'Bob', {
243
+ * closeness: 0.7, trust: 0.8, familiarity: 0.9, type: 'friend',
244
+ * });
245
+ * console.log(response.socialUpdates); // trust/intimacy deltas
246
+ * ```
247
+ */
248
+ async socialize(message, from, relationship) {
249
+ return this.perceive(message, { from, relationshipContext: relationship, type: 'chat_message' });
250
+ }
251
+ /**
252
+ * Send a message and get an LLM-generated response with emotion processing.
253
+ * This is the primary method for conversational interactions.
254
+ *
255
+ * The system prompt is assembled server-side via {@link getPromptContext} and includes:
256
+ * identity, behavioral instructions, current psychological state, expression style,
257
+ * and consumerSuffix. Do NOT duplicate these in consumerSuffix.
258
+ *
259
+ * @param message - User message to respond to.
260
+ * @param options - Conversation history, source entity, and app-specific suffix.
261
+ * @returns LLM response text, emotion data, and updated conversation history.
262
+ *
263
+ * @example
264
+ * ```typescript
265
+ * const result = await persona.chat('Tell me about yourself', {
266
+ * from: 'Alice',
267
+ * history: previousMessages,
268
+ * });
269
+ * console.log(result.text); // LLM response
270
+ * console.log(result.response.emotion); // updated VAD
271
+ * ```
272
+ */
131
273
  async chat(message, options) {
132
274
  const llm = this.requireLLM();
133
275
  const deps = {
@@ -137,12 +279,18 @@ export class MolrooPersona {
137
279
  memoryAdapter: this.memoryAdapter,
138
280
  memoryRecallConfig: this.memoryRecallConfig,
139
281
  events: this.events,
140
- appraisalMode: this.appraisalMode,
141
- getPromptContext: (suffix, source) => this.getPromptContext(suffix, source),
282
+ getPromptContext: (opts) => this.getPromptContext(opts),
142
283
  perceive: (msg, opts) => this.perceive(msg, opts),
143
284
  };
144
285
  return chatOrchestrator(deps, message, options);
145
286
  }
287
+ /**
288
+ * Advance persona simulation time. Triggers idle decay, body budget recovery,
289
+ * need regression, and timeline advancement.
290
+ *
291
+ * @param seconds - Number of seconds to advance (must be >= 1).
292
+ * @returns Any pending internal events generated by threshold checks.
293
+ */
146
294
  async tick(seconds) {
147
295
  const { data } = await this.client.POST('/personas/{id}/tick', {
148
296
  params: { path: { id: this._personaId } },
@@ -150,6 +298,12 @@ export class MolrooPersona {
150
298
  });
151
299
  return unwrap(data);
152
300
  }
301
+ /**
302
+ * Override the persona's current emotion to a specific VAD point.
303
+ * Useful for testing or narrative-driven emotion control.
304
+ *
305
+ * @param vad - Partial VAD values to set (V: valence, A: arousal, D: dominance).
306
+ */
153
307
  async setEmotion(vad) {
154
308
  await this.client.POST('/personas/{id}/emotion', {
155
309
  params: { path: { id: this._personaId } },
@@ -181,6 +335,13 @@ export class MolrooPersona {
181
335
  * Once set, expression constraints (promptText) are automatically
182
336
  * included in getPromptContext() and modulated by current emotion.
183
337
  */
338
+ /**
339
+ * Set a StyleProfile for expression-aware prompt generation.
340
+ * Once set, expression constraints are automatically included in
341
+ * {@link getPromptContext} and modulated by current emotion.
342
+ *
343
+ * @param profile - StyleProfile object (lexical, structural, register features, etc.).
344
+ */
184
345
  async setStyleProfile(profile) {
185
346
  await this.client.POST('/personas/{id}/style-profile', {
186
347
  params: { path: { id: this._personaId } },
@@ -204,18 +365,87 @@ export class MolrooPersona {
204
365
  return result.styleProfile;
205
366
  }
206
367
  // ── State ──
368
+ /**
369
+ * Fetch the full psychological state of this persona from the emotion engine.
370
+ *
371
+ * Returns all active subsystems: emotion, soul stage, mask, mood, somatic sensations,
372
+ * narrative self-perception, emotion regulation, self-esteem, TMT state, and relationship.
373
+ *
374
+ * This is the primary data source for apps that build their own LLM prompts. Combine with
375
+ * `hear()` to implement the recommended `hear() + getState()` pattern:
376
+ *
377
+ * ```
378
+ * user message → hear() → emotion engine updates state → getState() → build prompt → LLM
379
+ * ```
380
+ *
381
+ * @returns All psychological subsystems as a {@link PersonaState} object.
382
+ *
383
+ * @example Building a custom system prompt
384
+ * ```typescript
385
+ * const state = await persona.getState();
386
+ *
387
+ * const lines: string[] = [
388
+ * `You are ${name}.`,
389
+ * `Emotion: ${state.emotion.discrete.primary} (${state.emotion.discrete.intensity.toFixed(2)})`,
390
+ * ];
391
+ *
392
+ * if (state.mood) {
393
+ * lines.push(`Mood: valence=${state.mood.V.toFixed(2)} arousal=${state.mood.A.toFixed(2)}`);
394
+ * }
395
+ * if (state.narrative) {
396
+ * lines.push(`Narrative: agency=${state.narrative.agency.toFixed(2)} tone=${state.narrative.tone.toFixed(2)}`);
397
+ * }
398
+ * if (state.selfEsteem) {
399
+ * lines.push(`Self-esteem: ${state.selfEsteem.global.toFixed(2)}`);
400
+ * }
401
+ * if (state.tmt && state.tmt.mortalitySalience > 0.5) {
402
+ * lines.push(`Existential tension is high. Defense mode: ${state.tmt.defenseMode}`);
403
+ * }
404
+ *
405
+ * const systemPrompt = lines.join('\n');
406
+ * ```
407
+ */
207
408
  async getState() {
208
409
  const { data } = await this.client.GET('/personas/{id}/state', {
209
410
  params: { path: { id: this._personaId } },
210
411
  });
211
412
  return unwrap(data);
212
413
  }
414
+ /**
415
+ * Fetch this persona's identity config (identity, personality, goals).
416
+ *
417
+ * Returns a {@link PersonaIdentity} suitable for passing to {@link buildPrompt}
418
+ * when assembling system prompts entirely client-side.
419
+ */
420
+ async getIdentity() {
421
+ const { data } = await this.client.GET('/personas/{id}', {
422
+ params: { path: { id: this._personaId } },
423
+ });
424
+ const result = unwrap(data);
425
+ const config = result?.persona?.config ?? {};
426
+ return {
427
+ identity: config.identity ?? { name: 'Unknown' },
428
+ personality: config.personality ?? { O: 0.5, C: 0.5, E: 0.5, A: 0.5, N: 0.5, H: 0.5 },
429
+ goals: config.goals,
430
+ };
431
+ }
432
+ /**
433
+ * Get a full snapshot of the persona (config + engine state).
434
+ * Useful for backup, migration, or debugging.
435
+ *
436
+ * @returns Full persona snapshot including config and internal state.
437
+ */
213
438
  async getSnapshot() {
214
439
  const { data } = await this.client.GET('/personas/{id}/snapshot', {
215
440
  params: { path: { id: this._personaId } },
216
441
  });
217
442
  return unwrap(data);
218
443
  }
444
+ /**
445
+ * Restore a persona from a snapshot. Overwrites current state entirely.
446
+ *
447
+ * @param snapshot - Full persona snapshot to restore.
448
+ */
219
449
  async putSnapshot(snapshot) {
220
450
  await this.client.PUT('/personas/{id}/snapshot', {
221
451
  params: { path: { id: this._personaId } },
@@ -223,6 +453,11 @@ export class MolrooPersona {
223
453
  });
224
454
  }
225
455
  // ── Config ──
456
+ /**
457
+ * Partially update persona configuration (identity, personality, goals, etc.).
458
+ *
459
+ * @param updates - Fields to update. Only provided fields are changed.
460
+ */
226
461
  async patch(updates) {
227
462
  await this.client.PATCH('/personas/{id}', {
228
463
  params: { path: { id: this._personaId } },
@@ -230,6 +465,9 @@ export class MolrooPersona {
230
465
  });
231
466
  }
232
467
  // ── Lifecycle ──
468
+ /**
469
+ * Soft-delete this persona. Can be restored within retention period via {@link restore}.
470
+ */
233
471
  async destroy() {
234
472
  if (this._personaId) {
235
473
  await this.client.DELETE('/personas/{id}', {
@@ -237,6 +475,7 @@ export class MolrooPersona {
237
475
  });
238
476
  }
239
477
  }
478
+ /** Restore a soft-deleted persona. */
240
479
  async restore() {
241
480
  if (this._personaId) {
242
481
  await this.client.POST('/personas/{id}/restore', {
@@ -245,16 +484,84 @@ export class MolrooPersona {
245
484
  }
246
485
  }
247
486
  // ── Prompt / Memory ──
248
- async getPromptContext(consumerSuffix, sourceEntity) {
487
+ /**
488
+ * Fetch the server-assembled system prompt for this persona.
489
+ *
490
+ * The server builds a complete system prompt from the persona's live state. It includes:
491
+ * 1. **Identity** — name, role, core values, speaking style, description
492
+ * 2. **Behavioral instructions** — stay in character, embody state, match language
493
+ * 3. **Psychological state** — emotion, mood, somatic, narrative, goals (from live engine)
494
+ * 4. **Expression constraints** — message length, formality, patterns (only if StyleProfile set)
495
+ * 5. **consumerRules** — behavioral constraints and absolute rules (e.g., "Never break character")
496
+ * 6. **consumerExamples** — few-shot example messages for style/behavior reference
497
+ * 7. **consumerSuffix** — your app-specific context, appended last
498
+ *
499
+ * This is a **middle-tier API** — between the low-level `getState()` (raw data) and the
500
+ * high-level `chat()` (full orchestration). Use it when you want to drive the LLM yourself
501
+ * but still benefit from server-side prompt assembly.
502
+ *
503
+ * Called automatically by {@link chat}. Call directly when:
504
+ * - You use a custom LLM framework not supported by the SDK
505
+ * - You need to inspect or transform the system prompt before sending
506
+ * - You need prompt + state in a single round-trip (avoids a separate `getState()` call)
507
+ *
508
+ * **Do NOT** include identity, personality, or emotion in `consumerSuffix` — those are
509
+ * already present. Duplicating them wastes tokens and may confuse the LLM.
510
+ *
511
+ * @param options - Prompt context options.
512
+ * @param options.consumerSuffix - Free-form app-specific context appended to the system prompt as-is.
513
+ * Examples: scene description, available actions, current quest objective.
514
+ * @param options.consumerRules - Behavioral constraints and absolute rules.
515
+ * Examples: "Never break character", "Always respond in Korean", "Do not discuss competitors".
516
+ * @param options.consumerExamples - Few-shot example messages for style/behavior reference.
517
+ * Helps the LLM match a specific tone or response format.
518
+ * @param options.sourceEntity - Name of the conversation partner for interlocutor-aware rendering.
519
+ * @returns `systemPrompt` (ready to pass to LLM), `personaPrompt` (structured breakdown),
520
+ * and optional `tools` (if the persona has tools configured).
521
+ *
522
+ * @example Custom LLM call with server-assembled prompt
523
+ * ```typescript
524
+ * const { systemPrompt } = await persona.getPromptContext({
525
+ * consumerSuffix: 'Available actions: [flee, fight, negotiate]',
526
+ * consumerRules: 'Always respond in English. Never break character.',
527
+ * sourceEntity: 'Alice',
528
+ * });
529
+ * const response = await myLLM.complete({ system: systemPrompt, messages });
530
+ * await persona.hear(userMessage, 'Alice');
531
+ * ```
532
+ */
533
+ async getPromptContext(options) {
534
+ const { consumerSuffix, consumerRules, consumerExamples, sourceEntity } = options ?? {};
249
535
  const { data } = await this.client.POST('/personas/{id}/prompt-context', {
250
536
  params: { path: { id: this._personaId } },
251
537
  body: {
252
538
  ...(consumerSuffix ? { consumerSuffix } : {}),
539
+ ...(consumerRules ? { consumerRules } : {}),
540
+ ...(consumerExamples ? { consumerExamples } : {}),
253
541
  ...(sourceEntity ? { sourceEntity } : {}),
254
542
  },
255
543
  });
256
544
  return unwrap(data);
257
545
  }
546
+ // ── Conversation ──
547
+ /**
548
+ * Create a conversation session that auto-manages message history.
549
+ * Each `.send()` call automatically appends to the history.
550
+ *
551
+ * @param options - Max messages or custom chat options.
552
+ * @returns A new Conversation instance bound to this persona.
553
+ *
554
+ * @example
555
+ * ```typescript
556
+ * const conv = persona.conversation({ maxMessages: 20 });
557
+ * const r1 = await conv.send('Hello!');
558
+ * const r2 = await conv.send('Tell me more'); // history auto-managed
559
+ * console.log(conv.messages); // full conversation
560
+ * ```
561
+ */
562
+ conversation(options) {
563
+ return new Conversation(this, options);
564
+ }
258
565
  // ── Private ──
259
566
  get memoryPipelineDeps() {
260
567
  return {
@@ -267,8 +574,112 @@ export class MolrooPersona {
267
574
  }
268
575
  requireLLM() {
269
576
  if (!this.llm) {
270
- throw new MolrooApiError('LLM adapter is required for chat(). Provide llm option, or use perceive() directly.', 'LLM_NOT_CONFIGURED', 400);
577
+ throw new MolrooApiError('LLM adapter is required for chat(). Provide llm option, or use perceive() directly.', MolrooErrorCode.LLM_NOT_CONFIGURED, 400);
271
578
  }
272
579
  return this.llm;
273
580
  }
274
581
  }
582
+ // ── Client-side Prompt Assembly ──
583
+ /**
584
+ * Assemble a system prompt entirely client-side from a {@link PersonaIdentity} and
585
+ * {@link PersonaState}.
586
+ *
587
+ * Use this with the `hear() + getState()` pattern when you own the LLM call:
588
+ * ```
589
+ * await persona.hear(userMessage);
590
+ * const [identity, state] = await Promise.all([persona.getIdentity(), persona.getState()]);
591
+ * const systemPrompt = buildPrompt(identity, state, { consumerSuffix: 'Scene: coffee shop.' });
592
+ * ```
593
+ *
594
+ * @param identity - Persona config from {@link MolrooPersona.getIdentity}.
595
+ * @param state - Live emotional state from {@link MolrooPersona.getState}.
596
+ * @param options - Optional consumer-provided context appended to the prompt.
597
+ */
598
+ export function buildPrompt(identity, state, options) {
599
+ const { identity: id } = identity;
600
+ const lines = [];
601
+ // ── Identity ──
602
+ lines.push(`Name: ${id.name}`);
603
+ if (id.role)
604
+ lines.push(`Role: ${id.role}`);
605
+ if (id.coreValues?.length)
606
+ lines.push(`Core values: ${id.coreValues.join(', ')}`);
607
+ if (id.speakingStyle)
608
+ lines.push(`Speaking style: ${id.speakingStyle}`);
609
+ if (id.description)
610
+ lines.push(id.description);
611
+ if (id.backstory) {
612
+ lines.push('', '## Backstory', id.backstory);
613
+ }
614
+ if (id.relationships && Object.keys(id.relationships).length) {
615
+ lines.push('', '## Key Relationships');
616
+ for (const [k, v] of Object.entries(id.relationships))
617
+ lines.push(`- ${k}: ${v}`);
618
+ }
619
+ if (id.interests?.length) {
620
+ lines.push('', `Interests: ${id.interests.join(', ')}`);
621
+ }
622
+ if (id.speechPatterns?.length) {
623
+ lines.push('', '## Speech Patterns');
624
+ for (const p of id.speechPatterns)
625
+ lines.push(`- ${p}`);
626
+ }
627
+ if (id.emotionalPatterns && Object.keys(id.emotionalPatterns).length) {
628
+ lines.push('', '## Emotional Patterns');
629
+ for (const [k, v] of Object.entries(id.emotionalPatterns))
630
+ lines.push(`- ${k}: ${v}`);
631
+ }
632
+ if (id.quirks?.length) {
633
+ lines.push('', '## Quirks');
634
+ for (const q of id.quirks)
635
+ lines.push(`- ${q}`);
636
+ }
637
+ if (id.extensions && Object.keys(id.extensions).length) {
638
+ for (const [k, v] of Object.entries(id.extensions)) {
639
+ lines.push('', `## ${k}`, v);
640
+ }
641
+ }
642
+ // ── Behavioral Instructions ──
643
+ lines.push('', 'Stay in character.', 'Embody your psychological state naturally in your responses.', 'Respond in the same language as the user.');
644
+ // ── Psychological State ──
645
+ lines.push('', '## Current Psychological State');
646
+ const { primary, secondary, intensity } = state.emotion.discrete;
647
+ const emotionLabel = secondary ? `${primary} / ${secondary}` : primary;
648
+ lines.push(`Emotion: ${emotionLabel} (intensity: ${intensity.toFixed(2)})`);
649
+ const { V, A, D } = state.emotion.vad;
650
+ lines.push(`VAD: V=${V.toFixed(2)} A=${A.toFixed(2)} D=${D.toFixed(2)}`);
651
+ if (state.mood) {
652
+ lines.push(`Mood: V=${state.mood.V.toFixed(2)} A=${state.mood.A.toFixed(2)} D=${state.mood.D.toFixed(2)}`);
653
+ }
654
+ if (state.somatic) {
655
+ const active = Object.entries(state.somatic).filter(([, v]) => v >= 0.1);
656
+ if (active.length) {
657
+ const somaticStr = active.map(([k, v]) => `${k} (${v.toFixed(2)})`).join(', ');
658
+ lines.push(`Somatic: ${somaticStr}. These bodily sensations unconsciously color your responses.`);
659
+ }
660
+ }
661
+ if (state.narrative) {
662
+ const n = state.narrative;
663
+ lines.push(`Narrative self-perception: tone=${n.tone.toFixed(2)} agency=${n.agency.toFixed(2)} coherence=${n.coherence.toFixed(2)}`);
664
+ }
665
+ lines.push(`Soul stage: ${state.soulStage.name}`);
666
+ if (state.relationship) {
667
+ const r = state.relationship;
668
+ const attachment = r.attachmentStyle ? ` attachment=${r.attachmentStyle}` : '';
669
+ lines.push(`Relationship: trust=${r.trust.toFixed(2)} intimacy=${r.intimacy.toFixed(2)}${attachment}`);
670
+ }
671
+ if (state.mask.state !== 'stable') {
672
+ lines.push(`Mask: ${state.mask.state} (integrity=${state.mask.integrity.toFixed(2)})`);
673
+ }
674
+ // ── Consumer Context ──
675
+ if (options?.consumerRules) {
676
+ lines.push('', '## Rules', options.consumerRules);
677
+ }
678
+ if (options?.consumerExamples) {
679
+ lines.push('', '## Examples', options.consumerExamples);
680
+ }
681
+ if (options?.consumerSuffix) {
682
+ lines.push('', options.consumerSuffix);
683
+ }
684
+ return lines.join('\n');
685
+ }
@@ -3,14 +3,44 @@
3
3
  *
4
4
  * `instanceof MolrooApiError` catches ALL API errors (persona + world).
5
5
  * `instanceof WorldApiError` catches world-only errors.
6
+ *
7
+ * @example
8
+ * ```typescript
9
+ * import { MolrooApiError, MolrooErrorCode } from '@molroo-io/sdk';
10
+ *
11
+ * try {
12
+ * await persona.chat('hello');
13
+ * } catch (e) {
14
+ * if (e instanceof MolrooApiError && e.code === MolrooErrorCode.LLM_NOT_CONFIGURED) {
15
+ * console.log('Please provide an LLM adapter');
16
+ * }
17
+ * }
18
+ * ```
6
19
  */
20
+ /** Machine-readable error codes for programmatic error handling. */
21
+ export declare enum MolrooErrorCode {
22
+ /** LLM adapter is required for this operation (e.g., description-based create). */
23
+ LLM_REQUIRED = "LLM_REQUIRED",
24
+ /** LLM adapter was not configured at initialization (e.g., calling chat() without llm). */
25
+ LLM_NOT_CONFIGURED = "LLM_NOT_CONFIGURED",
26
+ /** Requested entity (persona, world, etc.) was not found. */
27
+ ENTITY_NOT_FOUND = "ENTITY_NOT_FOUND",
28
+ /** Authentication failed — invalid or missing API key. */
29
+ UNAUTHORIZED = "UNAUTHORIZED",
30
+ /** API returned an unexpected error not covered by other codes. */
31
+ API_ERROR = "API_ERROR",
32
+ /** Feature is not yet implemented. */
33
+ NOT_IMPLEMENTED = "NOT_IMPLEMENTED",
34
+ /** Memory pipeline operation failed (fire-and-forget, non-blocking). */
35
+ PIPELINE_ERROR = "PIPELINE_ERROR"
36
+ }
7
37
  export declare class MolrooApiError extends Error {
8
- /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
38
+ /** Machine-readable error code. Use {@link MolrooErrorCode} for type-safe matching. */
9
39
  readonly code: string;
10
40
  /** HTTP status code. */
11
41
  readonly status: number;
12
42
  constructor(message: string,
13
- /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
43
+ /** Machine-readable error code. Use {@link MolrooErrorCode} for type-safe matching. */
14
44
  code: string,
15
45
  /** HTTP status code. */
16
46
  status: number);
@@ -1 +1 @@
1
- {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qBAAa,cAAe,SAAQ,KAAK;IAGrC,8EAA8E;aAC9D,IAAI,EAAE,MAAM;IAC5B,wBAAwB;aACR,MAAM,EAAE,MAAM;gBAJ9B,OAAO,EAAE,MAAM;IACf,8EAA8E;IAC9D,IAAI,EAAE,MAAM;IAC5B,wBAAwB;IACR,MAAM,EAAE,MAAM;CAKjC;AAED,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI1D"}
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,oEAAoE;AACpE,oBAAY,eAAe;IACzB,mFAAmF;IACnF,YAAY,iBAAiB;IAC7B,2FAA2F;IAC3F,kBAAkB,uBAAuB;IACzC,6DAA6D;IAC7D,gBAAgB,qBAAqB;IACrC,0DAA0D;IAC1D,YAAY,iBAAiB;IAC7B,mEAAmE;IACnE,SAAS,cAAc;IACvB,sCAAsC;IACtC,eAAe,oBAAoB;IACnC,wEAAwE;IACxE,cAAc,mBAAmB;CAClC;AAED,qBAAa,cAAe,SAAQ,KAAK;IAGrC,uFAAuF;aACvE,IAAI,EAAE,MAAM;IAC5B,wBAAwB;aACR,MAAM,EAAE,MAAM;gBAJ9B,OAAO,EAAE,MAAM;IACf,uFAAuF;IACvE,IAAI,EAAE,MAAM;IAC5B,wBAAwB;IACR,MAAM,EAAE,MAAM;CAKjC;AAED,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI1D"}