@molroo-io/sdk 0.8.4 → 0.9.1

package/dist/esm/shared/errors.js

@@ -3,10 +3,41 @@
  *
  * `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 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 || (MolrooErrorCode = {}));
 export 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) {

package/dist/esm/types.d.ts

@@ -21,6 +21,19 @@ export interface InterlocutorContext {
     /** Arbitrary key-value extensions rendered as subsections. */
     extensions?: Record<string, string>;
 }
+/** Relationship state between two entities, used for social update computation. */
+export interface RelationshipContext {
+    /** Overall closeness/intimacy (0–1). */
+    closeness?: number;
+    /** Mutual trust level (0–1). */
+    trust?: number;
+    /** How well they know each other (0–1). */
+    familiarity?: number;
+    /** Relationship type label. */
+    type?: 'friend' | 'romantic' | 'authority' | 'stranger' | string;
+    /** Additional relationship-specific fields. */
+    [key: string]: unknown;
+}
 type PerceiveBody = RequestBody<'/personas/{id}/perceive', 'post'>;
 export type PerceiveEvent = PerceiveBody['event'];
 export type PerceiveContext = NonNullable<PerceiveBody['context']>;
@@ -38,7 +51,7 @@ export interface PerceiveOptions {
     type?: string;
     /** Low-level stimulus overrides (bodyBudgetDelta, vadOverride, etc.). */
     stimulus?: PerceiveEvent['stimulus'];
-    /** Extra payload fields merged into event.payload alongside message. */
+    /** Extra payload fields merged into event.payload alongside message (app-specific data). */
     payload?: Record<string, unknown>;
     /** Prior episodic memories for context-aware appraisal. */
     priorEpisodes?: Episode[];
@@ -46,7 +59,7 @@ export interface PerceiveOptions {
      *  When provided, the engine computes trust/intimacy/proximity deltas
      *  and emits socialUpdates in the response.
      *  Typically sourced from World-level storage (D1). */
-    relationshipContext?: Record<string, unknown>;
+    relationshipContext?: RelationshipContext;
     /** Skip saving memoryEpisode to the episode store. Default: false. */
     skipMemory?: boolean;
 }
@@ -58,7 +71,34 @@ export interface EventAppraisal {
     relationship: 'friend' | 'romantic' | 'authority' | 'stranger';
     intensity: number;
 }
-export type PersonaDynamicState = Record<string, unknown>;
+/** Full dynamic state returned by the persona state endpoint. */
+export interface PersonaDynamicState {
+    emotion: {
+        vad: VAD;
+        discrete?: {
+            primary: string;
+            secondary?: string;
+            intensity: number;
+        };
+    };
+    mood?: {
+        vad: VAD;
+    };
+    somatic?: string[];
+    narrative?: {
+        tone: number;
+        agency: number;
+        coherence: number;
+    };
+    goals?: Goal[];
+    bodyBudget?: number;
+    soulStage?: {
+        id: number;
+        name: string;
+    };
+    /** Additional engine-specific fields. */
+    [key: string]: unknown;
+}
 export type BlendRatio = Record<string, number>;
 export interface AgentResponse {
     text?: string;
@@ -143,7 +183,14 @@ export interface SocialUpdate {
     dimension: string;
     delta: number;
 }
-export type PersonaSnapshot = Record<string, unknown>;
+/** Full persona snapshot including engine state, config, and metadata. */
+export interface PersonaSnapshot {
+    config?: PersonaConfigData;
+    state?: State;
+    engineVersion?: string;
+    /** Additional engine-specific fields. */
+    [key: string]: unknown;
+}
 /**
  * HEXACO-PI-R personality domain traits (Ashton & Lee, 2007).
  * Each value ranges from 0 (low) to 1 (high).
@@ -175,6 +222,18 @@ export interface Identity {
     coreValues?: string[];
     culturalIdentity?: string;
     description?: string;
+    /** Character backstory or personal history. */
+    backstory?: string;
+    /** Key relationships and how the persona perceives them. e.g. {"mom": "strict but loving"} */
+    relationships?: Record<string, string>;
+    /** Interests, hobbies, or topics the persona cares about. */
+    interests?: string[];
+    /** Characteristic speech patterns or verbal tics. e.g. ["ends sentences with ~잖아", "says 진짜 when surprised"] */
+    speechPatterns?: string[];
+    /** Emotional reaction patterns. e.g. {"angry": "goes quiet and terse", "happy": "talks fast"} */
+    emotionalPatterns?: Record<string, string>;
+    /** Distinctive habits or quirks. e.g. ["taps fingers when thinking", "avoids eye contact when lying"] */
+    quirks?: string[];
     extensions?: Record<string, string>;
 }
 export interface Goal {
@@ -190,6 +249,12 @@ export interface PersonaConfigData {
     goals?: Goal[];
     [key: string]: unknown;
 }
+/** Persona identity config as returned by {@link MolrooPersona.getIdentity}. */
+export interface PersonaIdentity {
+    identity: Identity;
+    personality: PersonalityTraits;
+    goals?: Goal[];
+}
 export interface MotivationContext {
     goals: Goal[];
     activeGoal?: Goal;
@@ -272,5 +337,5 @@ export interface State {
     regulation: RegulationState;
     prevMaskIntegrity?: number;
 }
-export { MolrooApiError } from './errors';
+export { MolrooApiError, MolrooErrorCode } from './errors';
 //# sourceMappingURL=types.d.ts.map

package/dist/esm/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/types.js

@@ -8,4 +8,4 @@
 // Pipeline: Engine Zod schemas → @hono/zod-openapi → OpenAPI JSON → openapi-typescript → api.d.ts
 // ============================================================================
 // ── Error (re-exported from errors.ts) ──
-export { MolrooApiError } from './errors';
+export { MolrooApiError, MolrooErrorCode } from './errors';

package/dist/esm/world/world-persona.d.ts

@@ -10,6 +10,7 @@
 import { type ApiClient } from './client';
 import type { Appraisal } from './types';
 import type { LLMAdapter } from '../llm/adapter';
+import type { ZodSchema } from 'zod';
 export type LLMMessage = {
     role: 'user' | 'assistant' | 'system';
     content: string;
@@ -71,7 +72,7 @@ export interface PersonaDetail {
     };
     state: WorldPersonaState | null;
 }
-export interface ReactOptions {
+export interface ReactOptions<T = string> {
     /** Who is performing the action (e.g. 'yongjun'). */
     actor?: string;
     actorType?: 'user' | 'persona';
@@ -80,7 +81,7 @@ export interface ReactOptions {
     /** Prior conversation turns for context. */
     history?: LLMMessage[];
     /** Zod schema for structured output. Omit for plain text. */
-    schema?: unknown;
+    schema?: ZodSchema<T>;
     temperature?: number;
 }
 export interface ReactResult<T = string> {
@@ -117,8 +118,22 @@ export declare class WorldPersona {
     getState(): Promise<WorldPersonaState>;
     /** Get speaking style from persona config (identity.speakingStyle). */
     getSpeakingStyle(): Promise<string | undefined>;
-    /** Get LLM system prompt assembled from all persona subsystems + world context. */
-    getPromptContext(sourceEntity?: string): Promise<PromptContext>;
+    /**
+     * Get LLM system prompt assembled from all persona subsystems + world context.
+     *
+     * @param options - Prompt context options.
+     * @param options.sourceEntity - Name of the conversation partner for interlocutor-aware rendering.
+     * @param options.consumerSuffix - Free-form app-specific context appended to the system prompt as-is.
+     * @param options.consumerRules - Behavioral constraints and absolute rules.
+     *   Examples: "Never break character", "Always respond in Korean".
+     * @param options.consumerExamples - Few-shot example messages for style/behavior reference.
+     */
+    getPromptContext(options?: {
+        sourceEntity?: string;
+        consumerSuffix?: string;
+        consumerRules?: string;
+        consumerExamples?: string;
+    }): Promise<PromptContext>;
     /**
      * Send a predefined action to this persona's emotion engine.
      * Invalidates cached state.
@@ -183,6 +198,6 @@ export declare class WorldPersona {
      * console.log(r2.narrative.dialogue); // typed
      * ```
      */
-    react<T = string>(action: string, options: ReactOptions): Promise<ReactResult<T>>;
+    react<T = string>(action: string, options: ReactOptions<T>): Promise<ReactResult<T>>;
 }
 //# sourceMappingURL=world-persona.d.ts.map

package/dist/esm/world/world-persona.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world-persona.d.ts","sourceRoot":"","sources":["../../../src/world/world-persona.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"world-persona.d.ts","sourceRoot":"","sources":["../../../src/world/world-persona.ts"],"names":[],"mappings":"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"}

package/dist/esm/world/world-persona.js

@@ -9,6 +9,7 @@
  */
 import { unwrap } from './client';
 import { toWireAppraisal } from '../shared/appraisal';
+import { MolrooApiError, MolrooErrorCode } from '../shared/errors';
 export class WorldPersona {
     /** @internal — use World.persona() instead. */
     constructor(client, worldId, personaId, options) {
@@ -54,11 +55,26 @@ export class WorldPersona {
         const detail = await this.getDetail();
         return detail.config?.identity?.speakingStyle;
     }
-    /** Get LLM system prompt assembled from all persona subsystems + world context. */
-    async getPromptContext(sourceEntity) {
+    /**
+     * Get LLM system prompt assembled from all persona subsystems + world context.
+     *
+     * @param options - Prompt context options.
+     * @param options.sourceEntity - Name of the conversation partner for interlocutor-aware rendering.
+     * @param options.consumerSuffix - Free-form app-specific context appended to the system prompt as-is.
+     * @param options.consumerRules - Behavioral constraints and absolute rules.
+     *   Examples: "Never break character", "Always respond in Korean".
+     * @param options.consumerExamples - Few-shot example messages for style/behavior reference.
+     */
+    async getPromptContext(options) {
+        const { sourceEntity, consumerSuffix, consumerRules, consumerExamples } = options ?? {};
         const { data } = await this._client.POST('/worlds/{id}/personas/{pid}/prompt-context', {
             params: { path: { id: this._worldId, pid: this._personaId } },
-            body: sourceEntity ? { sourceEntity } : {},
+            body: {
+                ...(sourceEntity ? { sourceEntity } : {}),
+                ...(consumerSuffix ? { consumerSuffix } : {}),
+                ...(consumerRules ? { consumerRules } : {}),
+                ...(consumerExamples ? { consumerExamples } : {}),
+            },
         });
         return unwrap(data);
     }
@@ -134,7 +150,7 @@ export class WorldPersona {
      */
     async react(action, options) {
         if (!this._llm) {
-            throw new Error('WorldPersona.react() requires an LLM adapter. Pass { llm } to world.persona().');
+            throw new MolrooApiError('WorldPersona.react() requires an LLM adapter. Pass { llm } to world.persona().', MolrooErrorCode.LLM_NOT_CONFIGURED, 400);
         }
         // 1. Interact — emotion engine processes the action
         const interactResult = await this.interact(action, {
@@ -142,7 +158,7 @@ export class WorldPersona {
             actorType: options.actorType,
         });
         // 2. Get prompt context — now reflects updated emotion
-        const ctx = await this.getPromptContext(options.actor);
+        const ctx = await this.getPromptContext({ sourceEntity: options.actor });
         // 3. LLM generates narrative
         const messages = [
             ...(options.history ?? []),

package/dist/esm/world/world.d.ts

@@ -2,7 +2,7 @@ import { type ApiClient } from './client';
 import { World } from './world-domain';
 import { MolrooPersona } from '../persona';
 import type { PersonaSummary } from '../persona';
-import type { AppraisalMode, PersonaConfigData } from '../types';
+import type { PersonaConfigData } from '../types';
 import type { LLMInput } from '../llm/resolve';
 import type { MemoryAdapter, RecallLimits } from '../memory/types';
 import type { EventAdapter } from '../events/types';
@@ -18,8 +18,6 @@ export interface PersonaOptions {
     memory?: MemoryAdapter;
     recall?: RecallLimits;
     events?: EventAdapter;
-    /** Appraisal generation mode for `chat()`. `'direct'` (default) generates raw appraisal vectors; `'event'` classifies into ontology events and converts server-side. */
-    appraisalMode?: AppraisalMode;
 }
 /**
  * Unified entry point for the molroo SDK.
@@ -74,6 +72,28 @@ export declare class Molroo {
     createPersona(personaConfig: PersonaConfigData, options?: PersonaOptions): Promise<MolrooPersona>;
     /**
      * Connect to an existing persona by ID.
+     *
+     * LLM adapter is optional. Without it, {@link MolrooPersona.chat | chat()} will throw,
+     * but emotion/state APIs ({@link MolrooPersona.hear | hear()},
+     * {@link MolrooPersona.getState | getState()},
+     * {@link MolrooPersona.getEngineState | getEngineState()},
+     * {@link MolrooPersona.perceive | perceive()},
+     * {@link MolrooPersona.tick | tick()}) work without LLM.
+     *
+     * This is the recommended pattern for hybrid apps that build their own prompts
+     * and only need SDK for emotion/psychological state computation.
+     *
+     * @example
+     * ```typescript
+     * // Hybrid: emotion engine only (no LLM needed)
+     * const persona = await molroo.connectPersona('persona_abc123');
+     * const state = await persona.getEngineState(elapsed);
+     * const emotion = await persona.hear(userMessage, 'Alice');
+     *
+     * // Full: SDK handles everything (LLM required)
+     * const persona = await molroo.connectPersona('persona_abc123', { llm });
+     * const result = await persona.chat('Hello!');
+     * ```
      */
     connectPersona(personaId: string, options?: PersonaOptions): Promise<MolrooPersona>;
     /**
@@ -99,8 +119,11 @@ export declare class Molroo {
      */
     getWorld(id: string): Promise<World>;
     /**
-     * List worlds. Returns raw data objects (not World instances) for
-     * efficiency when only metadata is needed.
+     * List worlds for the authenticated tenant.
+     * Returns raw data objects (not World instances) for efficiency when only metadata is needed.
+     *
+     * @param options - Pagination options (limit, cursor).
+     * @returns Paginated list of world data and next cursor.
      */
     listWorlds(options?: PaginationOptions): Promise<{
         worlds: WorldData[];

package/dist/esm/world/world.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../src/world/world.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EACV,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAiCjB,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,wKAAwK;IACxK,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAM;IACjB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,aAAa;IAalC;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GAAG;QAAE,GAAG,EAAE,QAAQ,CAAA;KAAE,GAC1C,OAAO,CAAC,aAAa,CAAC;IAEzB;;;;;;;;;;OAUG;IACG,aAAa,CACjB,aAAa,EAAE,iBAAiB,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC;IAuBzB;;OAEG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC;IAOzB;;;OAGG;IACG,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GAAG;QAAE,GAAG,EAAE,QAAQ,CAAA;KAAE,GAC1C,OAAO,CAAC,aAAa,CAAC;IAIzB;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAWlF;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,KAAK,CAAC;IAwB9D;;OAEG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAmB1C;;;OAGG;IACG,UAAU,CACd,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;QAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CA6B/D"}
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../src/world/world.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EACV,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAiCjB,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAM;IACjB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,aAAa;IAalC;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GAAG;QAAE,GAAG,EAAE,QAAQ,CAAA;KAAE,GAC1C,OAAO,CAAC,aAAa,CAAC;IAEzB;;;;;;;;;;OAUG;IACG,aAAa,CACjB,aAAa,EAAE,iBAAiB,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC;IA2BzB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC;IAOzB;;;OAGG;IACG,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GAAG;QAAE,GAAG,EAAE,QAAQ,CAAA;KAAE,GAC1C,OAAO,CAAC,aAAa,CAAC;IAIzB;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAWlF;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,KAAK,CAAC;IAwB9D;;OAEG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAmB1C;;;;;;OAMG;IACG,UAAU,CACd,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;QAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CA6B/D"}

package/dist/esm/world/world.js

@@ -2,6 +2,7 @@
 import { createWorldClient, unwrap } from './client';
 import { World } from './world-domain';
 import { MolrooPersona } from '../persona';
+import { MolrooApiError, MolrooErrorCode } from '../shared/errors';
 // ---------------------------------------------------------------------------
 // Internal helper
 // ---------------------------------------------------------------------------
@@ -53,7 +54,7 @@ export class Molroo {
         if (typeof input === 'string') {
             // Description path - requires llm
             if (!options?.llm) {
-                throw new Error('LLM adapter is required when using description string');
+                throw new MolrooApiError('LLM adapter is required when using description string', MolrooErrorCode.LLM_REQUIRED, 400);
             }
             return MolrooPersona.create({ baseUrl: this._baseUrl, apiKey: this._apiKey, ...options, llm: options.llm }, input);
         }
@@ -62,6 +63,28 @@ export class Molroo {
     }
     /**
      * Connect to an existing persona by ID.
+     *
+     * LLM adapter is optional. Without it, {@link MolrooPersona.chat | chat()} will throw,
+     * but emotion/state APIs ({@link MolrooPersona.hear | hear()},
+     * {@link MolrooPersona.getState | getState()},
+     * {@link MolrooPersona.getEngineState | getEngineState()},
+     * {@link MolrooPersona.perceive | perceive()},
+     * {@link MolrooPersona.tick | tick()}) work without LLM.
+     *
+     * This is the recommended pattern for hybrid apps that build their own prompts
+     * and only need SDK for emotion/psychological state computation.
+     *
+     * @example
+     * ```typescript
+     * // Hybrid: emotion engine only (no LLM needed)
+     * const persona = await molroo.connectPersona('persona_abc123');
+     * const state = await persona.getEngineState(elapsed);
+     * const emotion = await persona.hear(userMessage, 'Alice');
+     *
+     * // Full: SDK handles everything (LLM required)
+     * const persona = await molroo.connectPersona('persona_abc123', { llm });
+     * const result = await persona.chat('Hello!');
+     * ```
      */
     async connectPersona(personaId, options) {
         return MolrooPersona.connect({ baseUrl: this._baseUrl, apiKey: this._apiKey, ...options }, personaId);
@@ -111,8 +134,11 @@ export class Molroo {
         return new World(this._client, toWorldData(raw));
     }
     /**
-     * List worlds. Returns raw data objects (not World instances) for
-     * efficiency when only metadata is needed.
+     * List worlds for the authenticated tenant.
+     * Returns raw data objects (not World instances) for efficiency when only metadata is needed.
+     *
+     * @param options - Pagination options (limit, cursor).
+     * @returns Paginated list of world data and next cursor.
      */
     async listWorlds(options) {
         const { data } = await this._client.GET('/worlds', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molroo-io/sdk",
-  "version": "0.8.4",
+  "version": "0.9.1",
   "description": "Unified SDK for molroo emotion engine — persona, world, LLM integration",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",