@molroo-io/sdk 0.8.4 → 0.9.1

package/dist/cjs/persona.js

@@ -34,11 +34,13 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MolrooPersona = void 0;
+exports.buildPrompt = buildPrompt;
 const resolve_1 = require("./llm/resolve");
 const errors_1 = require("./errors");
 const api_client_1 = require("./api-client");
 const memory_pipeline_1 = require("./persona/memory-pipeline");
 const chat_orchestrator_1 = require("./persona/chat-orchestrator");
+const conversation_1 = require("./persona/conversation");
 // ── SDK Persona Types ──
 const DEFAULT_BASE_URL = 'https://api.molroo.io';
 // ── MolrooPersona ──
@@ -57,12 +59,13 @@ class MolrooPersona {
         this.events = config.events ?? null;
         this.memoryAdapter = config.memory ?? null;
         this.memoryRecallConfig = config.recall;
-        this.appraisalMode = config.appraisalMode ?? 'direct';
     }
     // ── Properties ──
+    /** Unique persona instance ID. */
     get id() {
         return this._personaId;
     }
+    /** @deprecated Use {@link id} instead. */
     get personaId() {
         return this._personaId;
     }
@@ -71,7 +74,7 @@ class MolrooPersona {
         if (typeof input === 'string') {
             if (!config.llm) {
                 throw new errors_1.MolrooApiError('LLM adapter is required when using description string. ' +
-                    'Provide llm option or use explicit PersonaConfigData.', 'LLM_REQUIRED', 400);
+                    'Provide llm option or use explicit PersonaConfigData.', errors_1.MolrooErrorCode.LLM_REQUIRED, 400);
             }
             const { generatePersona } = await Promise.resolve().then(() => __importStar(require('./generate/persona')));
             const llm = await (0, resolve_1.resolveLLM)(config.llm);
@@ -106,6 +109,23 @@ class MolrooPersona {
     static async generate(config, description) {
         return MolrooPersona.create(config, description);
     }
+    /**
+     * Connect to an existing persona by ID.
+     *
+     * @param config - Connection configuration (apiKey required).
+     * @param personaId - The persona instance ID to connect to.
+     * @returns A connected MolrooPersona instance.
+     *
+     * @deprecated Use {@link Molroo.connectPersona} instead.
+     *
+     * @example
+     * ```typescript
+     * const sera = await MolrooPersona.connect(
+     *   { apiKey: 'mk_...', llm: openaiAdapter },
+     *   'persona_abc123'
+     * );
+     * ```
+     */
     static async connect(config, personaId) {
         const [llm, engineLlm] = await Promise.all([
             config.llm ? (0, resolve_1.resolveLLM)(config.llm) : undefined,
@@ -118,6 +138,12 @@ class MolrooPersona {
         });
         return persona;
     }
+    /**
+     * List all personas for the authenticated tenant.
+     *
+     * @param config - API connection config.
+     * @returns Paginated list of persona summaries.
+     */
     static async listPersonas(config) {
         const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
         const client = (0, api_client_1.createApiClient)(baseUrl, config.apiKey);
@@ -125,6 +151,14 @@ class MolrooPersona {
         return (0, api_client_1.unwrap)(data);
     }
     // ── Runtime ──
+    /**
+     * Send a stimulus to the persona's emotion engine and get the updated emotional response.
+     * This is the low-level API — for common cases, prefer {@link hear}, {@link experience}, or {@link chat}.
+     *
+     * @param message - The stimulus text (user message, event description, etc.).
+     * @param options - Appraisal, source, relationship context, and other options.
+     * @returns Emotion engine response with VAD, discrete emotion, and side effects.
+     */
     async perceive(message, options) {
         const eventType = options?.type ?? 'chat_message';
         const sourceName = typeof options?.from === 'string'
@@ -161,9 +195,118 @@ class MolrooPersona {
         }
         return response;
     }
+    /**
+     * Send a custom event with a required appraisal vector.
+     *
+     * @param type - Custom event type (e.g., 'gift_received', 'argument').
+     * @param description - Human-readable event description.
+     * @param options - Must include a pre-computed appraisal vector.
+     * @returns Emotion engine response.
+     */
     async event(type, description, options) {
         return this.perceive(description, { ...options, type });
     }
+    /**
+     * Register a received message with the emotion engine and update the persona's emotional state.
+     *
+     * This is the **core API** for the `hear() + getState()` pattern. Apps that build their own
+     * LLM prompts should call `hear()` after each user message to keep the emotion engine in sync,
+     * then call `getState()` to read updated state for prompt assembly.
+     *
+     * Use {@link chat} when you want the SDK to handle prompt assembly and LLM orchestration.
+     * Use `hear()` + `getState()` when your app owns the LLM call.
+     *
+     * @param message - The incoming message text (user utterance, narration, etc.).
+     * @param from - Who sent the message. A plain string is used as the source entity name.
+     *   Pass an {@link InterlocutorContext} object for richer context (description, extensions).
+     * @returns Emotion engine response with updated VAD, discrete emotion, and any side effects
+     *   (memory episodes, social updates, stage transitions, etc.).
+     *
+     * @example Basic hear + getState pattern
+     * ```typescript
+     * // Step 1: register message with emotion engine
+     * await persona.hear('You did a great job today!', 'Alice');
+     *
+     * // Step 2: read updated psychological state
+     * const state = await persona.getState();
+     *
+     * // Step 3: assemble your own system prompt
+     * const systemPrompt = buildPrompt(myPersonaConfig, state);
+     * const { text } = await myLLM.generate({ system: systemPrompt, messages });
+     * ```
+     *
+     * @example With structured interlocutor context
+     * ```typescript
+     * await persona.hear('I need your help', {
+     *   name: 'Alice',
+     *   description: 'A regular customer, slightly anxious',
+     *   extensions: { mood: 'stressed' },
+     * });
+     * ```
+     */
+    async hear(message, from) {
+        return this.perceive(message, { from, type: 'chat_message' });
+    }
+    /**
+     * Perceive an environmental or narrative event with a pre-computed appraisal.
+     *
+     * @param description - What happened (e.g., 'The sun set over the ocean').
+     * @param appraisal - 9-dimensional Scherer CPM appraisal vector.
+     * @returns Emotion engine response.
+     *
+     * @example
+     * ```typescript
+     * const response = await persona.experience('Received a surprise gift', {
+     *   goal_relevance: 0.8, goal_congruence: 0.9, expectedness: 0.2,
+     *   controllability: 0.5, agency: 0.3, norm_compatibility: 0.8,
+     *   internal_standards: 0.7, adjustment_potential: 0.6, urgency: 0.3,
+     * });
+     * ```
+     */
+    async experience(description, appraisal) {
+        return this.perceive(description, { appraisal, type: 'environment' });
+    }
+    /**
+     * Perceive a social interaction with relationship context for trust/intimacy computation.
+     *
+     * @param message - The interaction message.
+     * @param from - Who the interaction is from.
+     * @param relationship - Current relationship state (closeness, trust, familiarity).
+     * @returns Emotion engine response including socialUpdates.
+     *
+     * @example
+     * ```typescript
+     * const response = await persona.socialize('I missed you!', 'Bob', {
+     *   closeness: 0.7, trust: 0.8, familiarity: 0.9, type: 'friend',
+     * });
+     * console.log(response.socialUpdates); // trust/intimacy deltas
+     * ```
+     */
+    async socialize(message, from, relationship) {
+        return this.perceive(message, { from, relationshipContext: relationship, type: 'chat_message' });
+    }
+    /**
+     * Send a message and get an LLM-generated response with emotion processing.
+     * This is the primary method for conversational interactions.
+     *
+     * The system prompt is assembled server-side via {@link getPromptContext} and includes:
+     * identity, behavioral instructions, current psychological state, expression style,
+     * and consumerSuffix. Do NOT duplicate these in consumerSuffix.
+     *
+     * @param message - User message to respond to.
+     * @param options - Conversation history, source entity, and app-specific suffix.
+     * @returns LLM response text, emotion data, and updated conversation history.
+     *
+     * @example
+     * ```typescript
+     * const result = await persona.chat('Tell me about yourself', {
+     *   from: 'Alice',
+     *   history: previousMessages,
+     * });
+     * console.log(result.text);            // LLM response
+     * console.log(result.response.emotion); // updated VAD
+     * ```
+     */
     async chat(message, options) {
         const llm = this.requireLLM();
         const deps = {
@@ -173,12 +316,18 @@ class MolrooPersona {
             memoryAdapter: this.memoryAdapter,
             memoryRecallConfig: this.memoryRecallConfig,
             events: this.events,
-            appraisalMode: this.appraisalMode,
-            getPromptContext: (suffix, source) => this.getPromptContext(suffix, source),
+            getPromptContext: (opts) => this.getPromptContext(opts),
             perceive: (msg, opts) => this.perceive(msg, opts),
         };
         return (0, chat_orchestrator_1.chat)(deps, message, options);
     }
+    /**
+     * Advance persona simulation time. Triggers idle decay, body budget recovery,
+     * need regression, and timeline advancement.
+     *
+     * @param seconds - Number of seconds to advance (must be >= 1).
+     * @returns Any pending internal events generated by threshold checks.
+     */
     async tick(seconds) {
         const { data } = await this.client.POST('/personas/{id}/tick', {
             params: { path: { id: this._personaId } },
@@ -186,6 +335,12 @@ class MolrooPersona {
         });
         return (0, api_client_1.unwrap)(data);
     }
+    /**
+     * Override the persona's current emotion to a specific VAD point.
+     * Useful for testing or narrative-driven emotion control.
+     *
+     * @param vad - Partial VAD values to set (V: valence, A: arousal, D: dominance).
+     */
     async setEmotion(vad) {
         await this.client.POST('/personas/{id}/emotion', {
             params: { path: { id: this._personaId } },
@@ -217,6 +372,13 @@ class MolrooPersona {
      * Once set, expression constraints (promptText) are automatically
      * included in getPromptContext() and modulated by current emotion.
      */
+    /**
+     * Set a StyleProfile for expression-aware prompt generation.
+     * Once set, expression constraints are automatically included in
+     * {@link getPromptContext} and modulated by current emotion.
+     *
+     * @param profile - StyleProfile object (lexical, structural, register features, etc.).
+     */
     async setStyleProfile(profile) {
         await this.client.POST('/personas/{id}/style-profile', {
             params: { path: { id: this._personaId } },
@@ -240,18 +402,87 @@ class MolrooPersona {
         return result.styleProfile;
     }
     // ── State ──
+    /**
+     * Fetch the full psychological state of this persona from the emotion engine.
+     *
+     * Returns all active subsystems: emotion, soul stage, mask, mood, somatic sensations,
+     * narrative self-perception, emotion regulation, self-esteem, TMT state, and relationship.
+     *
+     * This is the primary data source for apps that build their own LLM prompts. Combine with
+     * `hear()` to implement the recommended `hear() + getState()` pattern:
+     *
+     * ```
+     * user message → hear() → emotion engine updates state → getState() → build prompt → LLM
+     * ```
+     *
+     * @returns All psychological subsystems as a {@link PersonaState} object.
+     *
+     * @example Building a custom system prompt
+     * ```typescript
+     * const state = await persona.getState();
+     *
+     * const lines: string[] = [
+     *   `You are ${name}.`,
+     *   `Emotion: ${state.emotion.discrete.primary} (${state.emotion.discrete.intensity.toFixed(2)})`,
+     * ];
+     *
+     * if (state.mood) {
+     *   lines.push(`Mood: valence=${state.mood.V.toFixed(2)} arousal=${state.mood.A.toFixed(2)}`);
+     * }
+     * if (state.narrative) {
+     *   lines.push(`Narrative: agency=${state.narrative.agency.toFixed(2)} tone=${state.narrative.tone.toFixed(2)}`);
+     * }
+     * if (state.selfEsteem) {
+     *   lines.push(`Self-esteem: ${state.selfEsteem.global.toFixed(2)}`);
+     * }
+     * if (state.tmt && state.tmt.mortalitySalience > 0.5) {
+     *   lines.push(`Existential tension is high. Defense mode: ${state.tmt.defenseMode}`);
+     * }
+     *
+     * const systemPrompt = lines.join('\n');
+     * ```
+     */
     async getState() {
         const { data } = await this.client.GET('/personas/{id}/state', {
             params: { path: { id: this._personaId } },
         });
         return (0, api_client_1.unwrap)(data);
     }
+    /**
+     * Fetch this persona's identity config (identity, personality, goals).
+     *
+     * Returns a {@link PersonaIdentity} suitable for passing to {@link buildPrompt}
+     * when assembling system prompts entirely client-side.
+     */
+    async getIdentity() {
+        const { data } = await this.client.GET('/personas/{id}', {
+            params: { path: { id: this._personaId } },
+        });
+        const result = (0, api_client_1.unwrap)(data);
+        const config = result?.persona?.config ?? {};
+        return {
+            identity: config.identity ?? { name: 'Unknown' },
+            personality: config.personality ?? { O: 0.5, C: 0.5, E: 0.5, A: 0.5, N: 0.5, H: 0.5 },
+            goals: config.goals,
+        };
+    }
+    /**
+     * Get a full snapshot of the persona (config + engine state).
+     * Useful for backup, migration, or debugging.
+     *
+     * @returns Full persona snapshot including config and internal state.
+     */
     async getSnapshot() {
         const { data } = await this.client.GET('/personas/{id}/snapshot', {
             params: { path: { id: this._personaId } },
         });
         return (0, api_client_1.unwrap)(data);
     }
+    /**
+     * Restore a persona from a snapshot. Overwrites current state entirely.
+     *
+     * @param snapshot - Full persona snapshot to restore.
+     */
     async putSnapshot(snapshot) {
         await this.client.PUT('/personas/{id}/snapshot', {
             params: { path: { id: this._personaId } },
@@ -259,6 +490,11 @@ class MolrooPersona {
         });
     }
     // ── Config ──
+    /**
+     * Partially update persona configuration (identity, personality, goals, etc.).
+     *
+     * @param updates - Fields to update. Only provided fields are changed.
+     */
     async patch(updates) {
         await this.client.PATCH('/personas/{id}', {
             params: { path: { id: this._personaId } },
@@ -266,6 +502,9 @@ class MolrooPersona {
         });
     }
     // ── Lifecycle ──
+    /**
+     * Soft-delete this persona. Can be restored within retention period via {@link restore}.
+     */
     async destroy() {
         if (this._personaId) {
             await this.client.DELETE('/personas/{id}', {
@@ -273,6 +512,7 @@ class MolrooPersona {
             });
         }
     }
+    /** Restore a soft-deleted persona. */
     async restore() {
         if (this._personaId) {
             await this.client.POST('/personas/{id}/restore', {
@@ -281,16 +521,84 @@ class MolrooPersona {
         }
     }
     // ── Prompt / Memory ──
-    async getPromptContext(consumerSuffix, sourceEntity) {
+    /**
+     * Fetch the server-assembled system prompt for this persona.
+     *
+     * The server builds a complete system prompt from the persona's live state. It includes:
+     * 1. **Identity** — name, role, core values, speaking style, description
+     * 2. **Behavioral instructions** — stay in character, embody state, match language
+     * 3. **Psychological state** — emotion, mood, somatic, narrative, goals (from live engine)
+     * 4. **Expression constraints** — message length, formality, patterns (only if StyleProfile set)
+     * 5. **consumerRules** — behavioral constraints and absolute rules (e.g., "Never break character")
+     * 6. **consumerExamples** — few-shot example messages for style/behavior reference
+     * 7. **consumerSuffix** — your app-specific context, appended last
+     *
+     * This is a **middle-tier API** — between the low-level `getState()` (raw data) and the
+     * high-level `chat()` (full orchestration). Use it when you want to drive the LLM yourself
+     * but still benefit from server-side prompt assembly.
+     *
+     * Called automatically by {@link chat}. Call directly when:
+     * - You use a custom LLM framework not supported by the SDK
+     * - You need to inspect or transform the system prompt before sending
+     * - You need prompt + state in a single round-trip (avoids a separate `getState()` call)
+     *
+     * **Do NOT** include identity, personality, or emotion in `consumerSuffix` — those are
+     * already present. Duplicating them wastes tokens and may confuse the LLM.
+     *
+     * @param options - Prompt context options.
+     * @param options.consumerSuffix - Free-form app-specific context appended to the system prompt as-is.
+     *   Examples: scene description, available actions, current quest objective.
+     * @param options.consumerRules - Behavioral constraints and absolute rules.
+     *   Examples: "Never break character", "Always respond in Korean", "Do not discuss competitors".
+     * @param options.consumerExamples - Few-shot example messages for style/behavior reference.
+     *   Helps the LLM match a specific tone or response format.
+     * @param options.sourceEntity - Name of the conversation partner for interlocutor-aware rendering.
+     * @returns `systemPrompt` (ready to pass to LLM), `personaPrompt` (structured breakdown),
+     *   and optional `tools` (if the persona has tools configured).
+     *
+     * @example Custom LLM call with server-assembled prompt
+     * ```typescript
+     * const { systemPrompt } = await persona.getPromptContext({
+     *   consumerSuffix: 'Available actions: [flee, fight, negotiate]',
+     *   consumerRules: 'Always respond in English. Never break character.',
+     *   sourceEntity: 'Alice',
+     * });
+     * const response = await myLLM.complete({ system: systemPrompt, messages });
+     * await persona.hear(userMessage, 'Alice');
+     * ```
+     */
+    async getPromptContext(options) {
+        const { consumerSuffix, consumerRules, consumerExamples, sourceEntity } = options ?? {};
         const { data } = await this.client.POST('/personas/{id}/prompt-context', {
             params: { path: { id: this._personaId } },
             body: {
                 ...(consumerSuffix ? { consumerSuffix } : {}),
+                ...(consumerRules ? { consumerRules } : {}),
+                ...(consumerExamples ? { consumerExamples } : {}),
                 ...(sourceEntity ? { sourceEntity } : {}),
             },
         });
         return (0, api_client_1.unwrap)(data);
     }
+    // ── Conversation ──
+    /**
+     * Create a conversation session that auto-manages message history.
+     * Each `.send()` call automatically appends to the history.
+     *
+     * @param options - Max messages or custom chat options.
+     * @returns A new Conversation instance bound to this persona.
+     *
+     * @example
+     * ```typescript
+     * const conv = persona.conversation({ maxMessages: 20 });
+     * const r1 = await conv.send('Hello!');
+     * const r2 = await conv.send('Tell me more');  // history auto-managed
+     * console.log(conv.messages);                  // full conversation
+     * ```
+     */
+    conversation(options) {
+        return new conversation_1.Conversation(this, options);
+    }
     // ── Private ──
     get memoryPipelineDeps() {
         return {
@@ -303,9 +611,113 @@ class MolrooPersona {
     }
     requireLLM() {
         if (!this.llm) {
-            throw new errors_1.MolrooApiError('LLM adapter is required for chat(). Provide llm option, or use perceive() directly.', 'LLM_NOT_CONFIGURED', 400);
+            throw new errors_1.MolrooApiError('LLM adapter is required for chat(). Provide llm option, or use perceive() directly.', errors_1.MolrooErrorCode.LLM_NOT_CONFIGURED, 400);
         }
         return this.llm;
     }
 }
 exports.MolrooPersona = MolrooPersona;
+// ── Client-side Prompt Assembly ──
+/**
+ * Assemble a system prompt entirely client-side from a {@link PersonaIdentity} and
+ * {@link PersonaState}.
+ *
+ * Use this with the `hear() + getState()` pattern when you own the LLM call:
+ * ```
+ * await persona.hear(userMessage);
+ * const [identity, state] = await Promise.all([persona.getIdentity(), persona.getState()]);
+ * const systemPrompt = buildPrompt(identity, state, { consumerSuffix: 'Scene: coffee shop.' });
+ * ```
+ *
+ * @param identity - Persona config from {@link MolrooPersona.getIdentity}.
+ * @param state - Live emotional state from {@link MolrooPersona.getState}.
+ * @param options - Optional consumer-provided context appended to the prompt.
+ */
+function buildPrompt(identity, state, options) {
+    const { identity: id } = identity;
+    const lines = [];
+    // ── Identity ──
+    lines.push(`Name: ${id.name}`);
+    if (id.role)
+        lines.push(`Role: ${id.role}`);
+    if (id.coreValues?.length)
+        lines.push(`Core values: ${id.coreValues.join(', ')}`);
+    if (id.speakingStyle)
+        lines.push(`Speaking style: ${id.speakingStyle}`);
+    if (id.description)
+        lines.push(id.description);
+    if (id.backstory) {
+        lines.push('', '## Backstory', id.backstory);
+    }
+    if (id.relationships && Object.keys(id.relationships).length) {
+        lines.push('', '## Key Relationships');
+        for (const [k, v] of Object.entries(id.relationships))
+            lines.push(`- ${k}: ${v}`);
+    }
+    if (id.interests?.length) {
+        lines.push('', `Interests: ${id.interests.join(', ')}`);
+    }
+    if (id.speechPatterns?.length) {
+        lines.push('', '## Speech Patterns');
+        for (const p of id.speechPatterns)
+            lines.push(`- ${p}`);
+    }
+    if (id.emotionalPatterns && Object.keys(id.emotionalPatterns).length) {
+        lines.push('', '## Emotional Patterns');
+        for (const [k, v] of Object.entries(id.emotionalPatterns))
+            lines.push(`- ${k}: ${v}`);
+    }
+    if (id.quirks?.length) {
+        lines.push('', '## Quirks');
+        for (const q of id.quirks)
+            lines.push(`- ${q}`);
+    }
+    if (id.extensions && Object.keys(id.extensions).length) {
+        for (const [k, v] of Object.entries(id.extensions)) {
+            lines.push('', `## ${k}`, v);
+        }
+    }
+    // ── Behavioral Instructions ──
+    lines.push('', 'Stay in character.', 'Embody your psychological state naturally in your responses.', 'Respond in the same language as the user.');
+    // ── Psychological State ──
+    lines.push('', '## Current Psychological State');
+    const { primary, secondary, intensity } = state.emotion.discrete;
+    const emotionLabel = secondary ? `${primary} / ${secondary}` : primary;
+    lines.push(`Emotion: ${emotionLabel} (intensity: ${intensity.toFixed(2)})`);
+    const { V, A, D } = state.emotion.vad;
+    lines.push(`VAD: V=${V.toFixed(2)} A=${A.toFixed(2)} D=${D.toFixed(2)}`);
+    if (state.mood) {
+        lines.push(`Mood: V=${state.mood.V.toFixed(2)} A=${state.mood.A.toFixed(2)} D=${state.mood.D.toFixed(2)}`);
+    }
+    if (state.somatic) {
+        const active = Object.entries(state.somatic).filter(([, v]) => v >= 0.1);
+        if (active.length) {
+            const somaticStr = active.map(([k, v]) => `${k} (${v.toFixed(2)})`).join(', ');
+            lines.push(`Somatic: ${somaticStr}. These bodily sensations unconsciously color your responses.`);
+        }
+    }
+    if (state.narrative) {
+        const n = state.narrative;
+        lines.push(`Narrative self-perception: tone=${n.tone.toFixed(2)} agency=${n.agency.toFixed(2)} coherence=${n.coherence.toFixed(2)}`);
+    }
+    lines.push(`Soul stage: ${state.soulStage.name}`);
+    if (state.relationship) {
+        const r = state.relationship;
+        const attachment = r.attachmentStyle ? ` attachment=${r.attachmentStyle}` : '';
+        lines.push(`Relationship: trust=${r.trust.toFixed(2)} intimacy=${r.intimacy.toFixed(2)}${attachment}`);
+    }
+    if (state.mask.state !== 'stable') {
+        lines.push(`Mask: ${state.mask.state} (integrity=${state.mask.integrity.toFixed(2)})`);
+    }
+    // ── Consumer Context ──
+    if (options?.consumerRules) {
+        lines.push('', '## Rules', options.consumerRules);
+    }
+    if (options?.consumerExamples) {
+        lines.push('', '## Examples', options.consumerExamples);
+    }
+    if (options?.consumerSuffix) {
+        lines.push('', options.consumerSuffix);
+    }
+    return lines.join('\n');
+}

package/dist/cjs/shared/errors.d.ts

@@ -3,14 +3,44 @@
  *
  * `instanceof MolrooApiError` catches ALL API errors (persona + world).
  * `instanceof WorldApiError` catches world-only errors.
+ *
+ * @example
+ * ```typescript
+ * import { MolrooApiError, MolrooErrorCode } from '@molroo-io/sdk';
+ *
+ * try {
+ *   await persona.chat('hello');
+ * } catch (e) {
+ *   if (e instanceof MolrooApiError && e.code === MolrooErrorCode.LLM_NOT_CONFIGURED) {
+ *     console.log('Please provide an LLM adapter');
+ *   }
+ * }
+ * ```
  */
+/** Machine-readable error codes for programmatic error handling. */
+export declare enum MolrooErrorCode {
+    /** LLM adapter is required for this operation (e.g., description-based create). */
+    LLM_REQUIRED = "LLM_REQUIRED",
+    /** LLM adapter was not configured at initialization (e.g., calling chat() without llm). */
+    LLM_NOT_CONFIGURED = "LLM_NOT_CONFIGURED",
+    /** Requested entity (persona, world, etc.) was not found. */
+    ENTITY_NOT_FOUND = "ENTITY_NOT_FOUND",
+    /** Authentication failed — invalid or missing API key. */
+    UNAUTHORIZED = "UNAUTHORIZED",
+    /** API returned an unexpected error not covered by other codes. */
+    API_ERROR = "API_ERROR",
+    /** Feature is not yet implemented. */
+    NOT_IMPLEMENTED = "NOT_IMPLEMENTED",
+    /** Memory pipeline operation failed (fire-and-forget, non-blocking). */
+    PIPELINE_ERROR = "PIPELINE_ERROR"
+}
 export declare class MolrooApiError extends Error {
-    /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
+    /** Machine-readable error code. Use {@link MolrooErrorCode} for type-safe matching. */
     readonly code: string;
     /** HTTP status code. */
     readonly status: number;
     constructor(message: string, 
-    /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
+    /** Machine-readable error code. Use {@link MolrooErrorCode} for type-safe matching. */
     code: string, 
     /** HTTP status code. */
     status: number);

package/dist/cjs/shared/errors.d.ts.map

@@ -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"}
+{"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"}

package/dist/cjs/shared/errors.js

@@ -4,12 +4,43 @@
  *
  * `instanceof MolrooApiError` catches ALL API errors (persona + world).
  * `instanceof WorldApiError` catches world-only errors.
+ *
+ * @example
+ * ```typescript
+ * import { MolrooApiError, MolrooErrorCode } from '@molroo-io/sdk';
+ *
+ * try {
+ *   await persona.chat('hello');
+ * } catch (e) {
+ *   if (e instanceof MolrooApiError && e.code === MolrooErrorCode.LLM_NOT_CONFIGURED) {
+ *     console.log('Please provide an LLM adapter');
+ *   }
+ * }
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WorldApiError = exports.MolrooApiError = void 0;
+exports.WorldApiError = exports.MolrooApiError = exports.MolrooErrorCode = void 0;
+/** Machine-readable error codes for programmatic error handling. */
+var MolrooErrorCode;
+(function (MolrooErrorCode) {
+    /** LLM adapter is required for this operation (e.g., description-based create). */
+    MolrooErrorCode["LLM_REQUIRED"] = "LLM_REQUIRED";
+    /** LLM adapter was not configured at initialization (e.g., calling chat() without llm). */
+    MolrooErrorCode["LLM_NOT_CONFIGURED"] = "LLM_NOT_CONFIGURED";
+    /** Requested entity (persona, world, etc.) was not found. */
+    MolrooErrorCode["ENTITY_NOT_FOUND"] = "ENTITY_NOT_FOUND";
+    /** Authentication failed — invalid or missing API key. */
+    MolrooErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    /** API returned an unexpected error not covered by other codes. */
+    MolrooErrorCode["API_ERROR"] = "API_ERROR";
+    /** Feature is not yet implemented. */
+    MolrooErrorCode["NOT_IMPLEMENTED"] = "NOT_IMPLEMENTED";
+    /** Memory pipeline operation failed (fire-and-forget, non-blocking). */
+    MolrooErrorCode["PIPELINE_ERROR"] = "PIPELINE_ERROR";
+})(MolrooErrorCode || (exports.MolrooErrorCode = MolrooErrorCode = {}));
 class MolrooApiError extends Error {
     constructor(message, 
-    /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
+    /** Machine-readable error code. Use {@link MolrooErrorCode} for type-safe matching. */
     code, 
     /** HTTP status code. */
     status) {