@molroo-io/sdk 0.5.2 → 0.6.2

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

@@ -1,40 +1,84 @@
 import { type ApiClient } from './client';
-import { Village } from './village';
-import type { VillageData, CreateVillageOptions, PaginationOptions } from './types';
-export interface WorldOptions {
+import { World } from './world-domain';
+import { MolrooPersona } from '../persona';
+import type { PersonaSummary } from '../persona';
+import type { PersonaConfigData } from '../types';
+import type { LLMInput } from '../llm/resolve';
+import type { MemoryAdapter, MemoryConfig, RecallLimits } from '../memory/types';
+import type { EventAdapter } from '../events/types';
+import type { WorldData, CreateWorldOptions, PaginationOptions } from './types';
+export interface MolrooOptions {
     apiKey: string;
     baseUrl?: string;
 }
+/** Per-persona options passed when creating/connecting personas via the Molroo client. */
+export interface PersonaOptions {
+    llm?: LLMInput;
+    engineLlm?: LLMInput;
+    memory?: MemoryAdapter | MemoryConfig;
+    recall?: RecallLimits;
+    events?: EventAdapter;
+}
 /**
- * Entry point for the World SDK.
+ * Unified entry point for the molroo SDK.
  *
  * @example
  * ```typescript
- * import { World } from '@molroo-io/sdk';
+ * import { Molroo } from '@molroo-io/sdk/world';
+ *
+ * const molroo = new Molroo({ apiKey: 'mk_live_...' });
+ *
+ * // Persona
+ * const sera = await molroo.createPersona({ identity: { name: 'Sera' }, ... }, { llm });
+ * await sera.chat('Hello!');
  *
- * const world = new World({ apiKey: 'mk_live_...' });
- * const village = await world.createVillage({ name: 'My Village' });
- * const result = await village.interact({ target: 'sera', action: 'greet' });
+ * // World
+ * const world = await molroo.createWorld({ name: 'Cafe' });
+ * await world.addPersona({ personaConfigId: sera.id, config: {...} });
  * ```
  */
-export declare class World {
+export declare class Molroo {
     /** @internal — exposed for advanced use only. */
     readonly _client: ApiClient;
-    constructor(options: WorldOptions);
+    private readonly _baseUrl;
+    private readonly _apiKey;
+    constructor(options: MolrooOptions);
+    /**
+     * Create a new persona and return a connected {@link MolrooPersona} instance.
+     */
+    createPersona(personaConfig: PersonaConfigData, options?: PersonaOptions): Promise<MolrooPersona>;
+    /**
+     * Connect to an existing persona by ID.
+     */
+    connectPersona(personaId: string, options?: PersonaOptions): Promise<MolrooPersona>;
+    /**
+     * Generate a persona from a natural-language description, create it on the API,
+     * and return a connected {@link MolrooPersona} instance.
+     */
+    generatePersona(description: string, options: PersonaOptions & {
+        llm: LLMInput;
+    }): Promise<MolrooPersona>;
+    /**
+     * List all personas for the authenticated tenant.
+     */
+    listPersonas(): Promise<{
+        personas: PersonaSummary[];
+        nextCursor?: string;
+    }>;
     /**
-     * Create a new village and return a {@link Village} instance.
+     * Create a new world and return a {@link World} instance.
      */
-    createVillage(options: CreateVillageOptions): Promise<Village>;
+    createWorld(options: CreateWorldOptions): Promise<World>;
     /**
-     * Fetch an existing village by ID and return a {@link Village} instance.
+     * Fetch an existing world by ID and return a {@link World} instance.
      */
-    getVillage(id: string): Promise<Village>;
+    getWorld(id: string): Promise<World>;
     /**
-     * List villages. Returns raw data objects (not Village instances) for
+     * List worlds. Returns raw data objects (not World instances) for
      * efficiency when only metadata is needed.
      */
-    listVillages(options?: PaginationOptions): Promise<{
-        villages: VillageData[];
+    listWorlds(options?: PaginationOptions): Promise<{
+        worlds: WorldData[];
         nextCursor: string | null;
     }>;
 }

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,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAiCjB,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD;;;;;;;;;;;GAWG;AACH,qBAAa,KAAK;IAChB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;gBAEhB,OAAO,EAAE,YAAY;IAOjC;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBpE;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmB9C;;;OAGG;IACG,YAAY,CAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CA6BnE"}
+{"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,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACjF,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,GAAG,YAAY,CAAC;IACtC,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;;OAEG;IACG,aAAa,CACjB,aAAa,EAAE,iBAAiB,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC;IAOzB;;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;IAOzB;;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"}

package/dist/esm/world/world.js

@@ -1,11 +1,12 @@
-// INFO: @F001 Top-level domain class — see plan step 4
+// INFO: @F001 Top-level SDK entry point — see plan step 4
 import { createWorldClient, unwrap } from './client';
-import { Village } from './village';
+import { World } from './world-domain';
+import { MolrooPersona } from '../persona';
 // ---------------------------------------------------------------------------
 // Internal helper
 // ---------------------------------------------------------------------------
-/** Map raw snake_case API village object to camelCase VillageData. */
-function toVillageData(raw) {
+/** Map raw snake_case API response to camelCase WorldData. */
+function toWorldData(raw) {
     return {
         id: raw.id,
         tenantId: raw.tenant_id,
@@ -19,32 +20,74 @@ function toVillageData(raw) {
 }
 const DEFAULT_BASE_URL = 'https://api.molroo.io';
 // ---------------------------------------------------------------------------
-// World class
+// Molroo class
 // ---------------------------------------------------------------------------
 /**
- * Entry point for the World SDK.
+ * Unified entry point for the molroo SDK.
  *
  * @example
  * ```typescript
- * import { World } from '@molroo-io/sdk';
+ * import { Molroo } from '@molroo-io/sdk/world';
  *
- * const world = new World({ apiKey: 'mk_live_...' });
- * const village = await world.createVillage({ name: 'My Village' });
- * const result = await village.interact({ target: 'sera', action: 'greet' });
+ * const molroo = new Molroo({ apiKey: 'mk_live_...' });
+ *
+ * // Persona
+ * const sera = await molroo.createPersona({ identity: { name: 'Sera' }, ... }, { llm });
+ * await sera.chat('Hello!');
+ *
+ * // World
+ * const world = await molroo.createWorld({ name: 'Cafe' });
+ * await world.addPersona({ personaConfigId: sera.id, config: {...} });
  * ```
  */
-export class World {
+export class Molroo {
     constructor(options) {
+        this._baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this._apiKey = options.apiKey;
         this._client = createWorldClient({
-            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
-            apiKey: options.apiKey,
+            baseUrl: this._baseUrl,
+            apiKey: this._apiKey,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Persona
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a new persona and return a connected {@link MolrooPersona} instance.
+     */
+    async createPersona(personaConfig, options) {
+        return MolrooPersona.create({ baseUrl: this._baseUrl, apiKey: this._apiKey, ...options }, personaConfig);
+    }
+    /**
+     * Connect to an existing persona by ID.
+     */
+    async connectPersona(personaId, options) {
+        return MolrooPersona.connect({ baseUrl: this._baseUrl, apiKey: this._apiKey, ...options }, personaId);
+    }
+    /**
+     * Generate a persona from a natural-language description, create it on the API,
+     * and return a connected {@link MolrooPersona} instance.
+     */
+    async generatePersona(description, options) {
+        return MolrooPersona.generate({ baseUrl: this._baseUrl, apiKey: this._apiKey, ...options }, description);
+    }
+    /**
+     * List all personas for the authenticated tenant.
+     */
+    async listPersonas() {
+        return MolrooPersona.listPersonas({
+            baseUrl: this._baseUrl,
+            apiKey: this._apiKey,
         });
     }
+    // ---------------------------------------------------------------------------
+    // World
+    // ---------------------------------------------------------------------------
     /**
-     * Create a new village and return a {@link Village} instance.
+     * Create a new world and return a {@link World} instance.
      */
-    async createVillage(options) {
-        const { data } = await this._client.POST('/villages', {
+    async createWorld(options) {
+        const { data } = await this._client.POST('/worlds', {
             body: {
                 name: options.name,
                 description: options.description,
@@ -53,24 +96,24 @@ export class World {
             },
         });
         const raw = unwrap(data);
-        return new Village(this._client, toVillageData(raw));
+        return new World(this._client, toWorldData(raw));
     }
     /**
-     * Fetch an existing village by ID and return a {@link Village} instance.
+     * Fetch an existing world by ID and return a {@link World} instance.
      */
-    async getVillage(id) {
-        const { data } = await this._client.GET('/villages/{id}', {
+    async getWorld(id) {
+        const { data } = await this._client.GET('/worlds/{id}', {
             params: { path: { id } },
         });
         const raw = unwrap(data);
-        return new Village(this._client, toVillageData(raw));
+        return new World(this._client, toWorldData(raw));
     }
     /**
-     * List villages. Returns raw data objects (not Village instances) for
+     * List worlds. Returns raw data objects (not World instances) for
      * efficiency when only metadata is needed.
      */
-    async listVillages(options) {
-        const { data } = await this._client.GET('/villages', {
+    async listWorlds(options) {
+        const { data } = await this._client.GET('/worlds', {
             params: {
                 query: {
                     limit: options?.limit?.toString(),
@@ -80,7 +123,7 @@ export class World {
         });
         const raw = unwrap(data);
         return {
-            villages: (raw.villages ?? []).map(toVillageData),
+            worlds: (raw.worlds ?? []).map(toWorldData),
             nextCursor: raw.nextCursor ?? null,
         };
     }

package/package.json

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

package/dist/cjs/world/village.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"village.d.ts","sourceRoot":"","sources":["../../../src/world/village.ts"],"names":[],"mappings":"AACA,OAAO,EAAU,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAEjB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,UAAU,EACV,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAsCjB;;;;;GAKG;AACH,qBAAa,OAAO;IAClB,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,KAAK,CAAc;IAE3B,sEAAsE;gBAC1D,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW;IAOhD,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,uDAAuD;IACvD,IAAI,IAAI,IAAI,QAAQ,CAAC,WAAW,CAAC,CAEhC;IAID;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB1D,gCAAgC;IAC1B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ7B,sFAAsF;IAChF,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAC9D,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwCxE,yCAAyC;IACnC,YAAY,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IASxC,kCAAkC;IAC5B,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQrD,0CAA0C;IACpC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,YAAY;IAMvE,8CAA8C;IACxC,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAcpE,4DAA4D;IACtD,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAsB1C,gDAAgD;IAC1C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,mDAAmD;IAC7C,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrE,8CAA8C;IACxC,iBAAiB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAS7C,mCAAmC;IAC7B,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/D,8CAA8C;IACxC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAmBjE,+CAA+C;IACzC,SAAS,CACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;QAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAiBhE"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"village.d.ts","sourceRoot":"","sources":["../../../src/world/village.ts"],"names":[],"mappings":"AACA,OAAO,EAAU,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAEjB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,UAAU,EACV,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAsCjB;;;;;GAKG;AACH,qBAAa,OAAO;IAClB,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,KAAK,CAAc;IAE3B,sEAAsE;gBAC1D,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW;IAOhD,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,uDAAuD;IACvD,IAAI,IAAI,IAAI,QAAQ,CAAC,WAAW,CAAC,CAEhC;IAID;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB1D,gCAAgC;IAC1B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ7B,sFAAsF;IAChF,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAC9D,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwCxE,yCAAyC;IACnC,YAAY,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IASxC,kCAAkC;IAC5B,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQrD,0CAA0C;IACpC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,YAAY;IAMvE,8CAA8C;IACxC,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAcpE,4DAA4D;IACtD,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAsB1C,gDAAgD;IAC1C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,mDAAmD;IAC7C,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrE,8CAA8C;IACxC,iBAAiB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAS7C,mCAAmC;IAC7B,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/D,8CAA8C;IACxC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAmBjE,+CAA+C;IACzC,SAAS,CACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;QAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAiBhE"}