@molroo-io/sdk 0.9.0 → 0.9.1

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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molroo-io/sdk",
-  "version": "0.9.0",
+  "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",