@molroo-io/sdk 0.9.0 → 0.10.0

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

@@ -7,8 +7,9 @@
  * WorldPersona는 Persona SDK와 동일한 DX(getState, getPromptContext, react)를
  * 제공하되, 내부적으로 World API 엔드포인트를 사용한다.
  */
-import { unwrap } from './client';
-import { toWireAppraisal } from '../shared/appraisal';
+import { unwrap } from './client.js';
+import { toWireAppraisal } from '../shared/appraisal.js';
+import { MolrooApiError, MolrooErrorCode } from '../shared/errors.js';
 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>;
     /**

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

@@ -1,7 +1,8 @@
 // INFO: @F001 Top-level SDK entry point — see plan step 4
-import { createWorldClient, unwrap } from './client';
-import { World } from './world-domain';
-import { MolrooPersona } from '../persona';
+import { createWorldClient, unwrap } from './client.js';
+import { World } from './world-domain.js';
+import { MolrooPersona } from '../persona.js';
+import { MolrooApiError, MolrooErrorCode } from '../shared/errors.js';
 // ---------------------------------------------------------------------------
 // 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.10.0",
   "description": "Unified SDK for molroo emotion engine — persona, world, LLM integration",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -41,7 +41,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.esm.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.esm.json && node scripts/fix-esm-extensions.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -51,7 +51,7 @@
     "format:check": "prettier --check 'src/**/*.ts'",
     "clean": "rm -rf dist",
     "docs": "typedoc",
-    "gen:types": "node ../../molroo-io/api/persona/scripts/dump-spec.mjs && openapi-typescript ../../molroo-io/api/persona/dist/openapi.json -o src/generated/api.d.ts"
+    "gen:types": "node ../api/scripts/dump-spec.mjs ../api/dist/openapi.json && openapi-typescript ../api/dist/openapi.json -o src/generated/api.d.ts"
   },
   "keywords": [
     "emotion",

package/dist/cjs/defaults/persona.json

@@ -1,17 +0,0 @@
-{
-    "personality": {
-        "O": 0.5,
-        "C": 0.5,
-        "E": 0.5,
-        "A": 0.5,
-        "N": 0.5,
-        "H": 0.5
-    },
-    "identity": {
-        "name": "Persona",
-        "role": "A person with a neutral, balanced personality.",
-        "speakingStyle": "Natural, conversational tone.",
-        "coreValues": ["honesty", "kindness"]
-    },
-    "goals": []
-}

package/dist/esm/defaults/persona.json

@@ -1,17 +0,0 @@
-{
-    "personality": {
-        "O": 0.5,
-        "C": 0.5,
-        "E": 0.5,
-        "A": 0.5,
-        "N": 0.5,
-        "H": 0.5
-    },
-    "identity": {
-        "name": "Persona",
-        "role": "A person with a neutral, balanced personality.",
-        "speakingStyle": "Natural, conversational tone.",
-        "coreValues": ["honesty", "kindness"]
-    },
-    "goals": []
-}