@molroo-io/sdk 0.6.2 → 0.7.1

package/README.md

@@ -1,228 +1,134 @@
 # @molroo-io/sdk
 
-[![version](https://img.shields.io/badge/version-0.6.0-e94560)](package.json)
-[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6)](tsconfig.json)
-[![tests](https://img.shields.io/badge/tests-148-brightgreen)](src/__tests__)
+**Thin Client SDK for molroo emotion engine**
 
-Client SDK for the [molroo](https://molroo.io) emotion engine API. One client for personas and worlds — handles prompt assembly, LLM orchestration, and memory recall.
-
-## Install
-
-```bash
-npm install @molroo-io/sdk
-```
+Simplified API client with LLM integration for the molroo emotion engine.
 
 ## Quick Start
 
-```ts
-import { Molroo, createVercelAIAdapter } from '@molroo-io/sdk';
+```typescript
+import { Molroo } from '@molroo-io/sdk';
+import { createOpenAI } from '@ai-sdk/openai';
 
 const molroo = new Molroo({ apiKey: 'mk_live_...' });
 
-const llm = createVercelAIAdapter({
-  provider: 'openai',
-  apiKey: process.env.OPENAI_API_KEY!,
-});
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });
 
-// Create a persona
+// Create persona from description
 const sera = await molroo.createPersona(
-  { identity: { name: 'Sera', coreValues: ['honesty', 'warmth'] },
-    personality: { O: 0.7, C: 0.6, E: 0.8, A: 0.5, N: 0.3, H: 0.6 } },
-  { llm },
+  'A kind and curious barista named Sera who remembers customer names',
+  { llm: openai }
 );
 
-const result = await sera.chat('Hello!');
-console.log(result.text);            // "Hey! It's great to meet you..."
-console.log(result.response.emotion); // { V: 0.4, A: 0.5, D: 0.2 }
-
-// Create a world with multiple personas
-const world = await molroo.createWorld({ name: 'Cafe' });
-await world.addPersona({ personaConfigId: sera.id, config: {...} });
-```
-
-## How It Works
-
-```
-   Your App                    SDK                          API (PersonaDO)
-      |                         |                               |
-      |  persona.chat(msg)      |                               |
-      |------------------------>|                               |
-      |                         |  POST /personas/:id/prompt-context
-      |                         |------------------------------>|
-      |                         |  { systemPrompt, tools }      |
-      |                         |<------------------------------|
-      |                         |                               |
-      |                         |  LLM call (your API key)      |
-      |                         |  system: systemPrompt         |
-      |                         |  -> { response, appraisal }   |
-      |                         |                               |
-      |                         |  POST /personas/:id/perceive  |
-      |                         |  { appraisal }                |
-      |                         |------------------------------>|
-      |                         |  { emotion, state }           |
-      |                         |<------------------------------|
-      |                         |                               |
-      |  { text, response }     |                               |
-      |<------------------------|                               |
-```
-
-1. **Get prompt context** — API builds system prompt from live emotional state (identity + personality + mood + somatic + narrative + memory)
-2. **LLM call** — SDK calls your LLM with assembled prompt. Returns response text + appraisal vector.
-3. **Perceive** — SDK sends appraisal to API. Engine processes emotion pipeline -> new VAD state.
-4. **Post-chat** — Episode saved, reflection triggered if needed, events emitted.
-
-The API does all emotion computation. The SDK just connects it to your LLM.
-
-## Molroo Client
-
-The unified entry point. One client, one API key.
-
-```ts
-const molroo = new Molroo({ apiKey: 'mk_live_...' });
+// Chat
+let history: Message[] = [];
+const result = await sera.chat('Hello!', { history });
+console.log(result.text);  // "Hello! Welcome to our cafe."
+history = result.updatedHistory;  // Manage externally
 ```
 
-### Persona Methods
-
-| Method | Description |
-|--------|-------------|
-| `createPersona(config, options?)` | Create a new persona |
-| `connectPersona(id, options?)` | Connect to an existing persona |
-| `generatePersona(description, options)` | Generate persona from description via LLM |
-| `listPersonas()` | List all personas |
-
-### World Methods
-
-| Method | Description |
-|--------|-------------|
-| `createWorld(options)` | Create a new world |
-| `getWorld(id)` | Get an existing world |
-| `listWorlds(options?)` | List all worlds |
-
-## Two LLM Modes
-
-### Combined Mode (default)
-
-Single LLM call returns both response text and appraisal in one `generateObject()` call:
-
-```ts
-const sera = await molroo.createPersona(personaConfig, { llm });
-```
-
-### Split Mode
-
-Separate LLM for appraisal (cheap/fast model) and response (quality model). Appraisal runs first -> engine updates emotion -> response generated with updated emotional state:
+## Installation
 
-```ts
-const sera = await molroo.createPersona(personaConfig, {
-  llm: responseModel,        // quality model for response text
-  engineLlm: appraisalModel, // cheap model for appraisal vector
-});
+```bash
+npm install @molroo-io/sdk
+npm install ai @ai-sdk/openai  # or @ai-sdk/anthropic, @ai-sdk/google-vertex
 ```
 
-## MolrooPersona API
-
-Returned by `molroo.createPersona()`, `molroo.connectPersona()`, or `molroo.generatePersona()`.
+## Features
 
-| Method | Description |
-|--------|-------------|
-| `chat(message, options?)` | Full LLM orchestration: prompt -> LLM -> perceive -> result |
-| `perceive(message, options?)` | Send event to emotion engine (no LLM call) |
-| `tick(seconds)` | Advance time (mood decay, body recovery) |
-| `getState()` | Get current emotional state |
-| `setEmotion(vad)` | Direct VAD override |
-| `getPromptContext(suffix?, source?)` | Get server-assembled system prompt |
-| `searchMemory(query, options?)` | Search episodic memory |
-| `getSnapshot()` | Get full persona snapshot |
-| `putSnapshot(snapshot)` | Load persona snapshot |
-| `patch(config)` | Update persona config |
-| `destroy()` | Soft-delete the persona |
-| `restore()` | Restore a soft-deleted persona |
+- **Unified API** — `Molroo` class for persona and world management
+- **Vercel AI SDK Integration** — Use any LLM provider (OpenAI, Anthropic, Google, etc.)
+- **External History Management** — Simple mode: manage conversation history yourself
+- **Advanced Memory (Optional)** — Implement `MemoryAdapter` for semantic search, reflections
+- **World Simulation** — Multi-agent environments with channels and interactions
 
-## Adapters
+## Usage Modes
 
-### LLM Adapter
+### 1. Simple Mode (External History)
 
-Required for `chat()`. Built into `@molroo-io/sdk`:
+```typescript
+const molroo = new Molroo({ apiKey: 'mk_...' });
+const sera = await molroo.createPersona('...', { llm: openai });
 
-```ts
-import { createVercelAIAdapter } from '@molroo-io/sdk';
-
-const llm = createVercelAIAdapter({
-  provider: 'openai',        // or 'anthropic', 'google'
-  apiKey: process.env.OPENAI_API_KEY!,
-  model: 'gpt-4o-mini',      // optional
-});
+let history = [];
+const result = await sera.chat('Hello', { history });
+history = result.updatedHistory;
 ```
 
-### Memory
-
-Client-side memory for episodic recall and semantic search. Optional — when not provided, memory recall is skipped.
-
-**Single adapter (recommended)** — pass one `MemoryAdapter` that handles everything:
-
-```ts
-import { SqliteMemoryAdapter } from '@molroo-io/sdk/memory/sqlite';
-
-const sera = await molroo.createPersona(personaConfig, {
-  llm,
-  memory: new SqliteMemoryAdapter({ dbPath: './memory.db' }),
-  recall: { episodicLimit: 5, semanticLimit: 3 },
-});
-```
-
-Built-in `InMemoryEpisodeAdapter` also works as a single adapter (for demos/testing):
-
-```ts
-import { InMemoryEpisodeAdapter } from '@molroo-io/sdk';
-
-const sera = await molroo.createPersona(personaConfig, {
-  llm,
-  memory: new InMemoryEpisodeAdapter(),
+### 2. Advanced Mode (MemoryAdapter)
+
+```typescript
+class MyPostgresAdapter implements MemoryAdapter {
+  async saveEpisode(episode: Episode): Promise<void> {
+    // Save to PostgreSQL
+  }
+  
+  async recall(query: RecallQuery): Promise<Episode[]> {
+    // Query by filters
+  }
+  
+  async semanticRecall(query: string): Promise<Episode[]> {
+    // Vector similarity search
+  }
+}
+
+const sera = await molroo.createPersona('...', {
+  llm: openai,
+  memory: new MyPostgresAdapter()
 });
 ```
 
-### Events
+## World Simulation
 
-Optional event emission for logging, webhooks, or custom integrations:
-
-```ts
-import { ConsoleEventAdapter, WebhookEventAdapter } from '@molroo-io/sdk';
-
-// Console logging
-const events = new ConsoleEventAdapter();
-
-// Webhook
-const events = new WebhookEventAdapter({ url: 'https://...', secret: '...' });
-```
-
-## Persona Generation
-
-Generate a persona from a description — no manual config needed:
-
-```ts
-const sera = await molroo.generatePersona(
-  'A cheerful companion who loves music',
-  { llm },
-);
-await sera.chat('Play me something!');
-```
-
-## Build & Test
-
-```bash
-npm run build      # tsc -> dist/cjs + dist/esm
-npm run test       # Vitest (148 tests)
-npm run lint       # ESLint
-npm run gen:types  # openapi-typescript -> src/generated/api.d.ts
-npm run docs       # TypeDoc -> SDK API reference
+```typescript
+const world = await molroo.createWorld({ name: 'Cafe' });
+const sera = await molroo.createPersona('Barista Sera', { llm: openai });
+await world.addPersona({ personaConfigId: sera.id, config: {...} });
 ```
 
-## Links
-
-- [Documentation](https://docs.molroo.io)
-- [Dashboard](https://molroo.io/dashboard)
-- [API Reference](https://api.molroo.io/docs)
+## Migration from v0.5.x
+
+### Breaking Changes
+
+1. **Unified `create()` method**
+   ```typescript
+   // Before
+   await MolrooPersona.create({...}, {personality: {...}});
+   await MolrooPersona.generate({...}, "description");
+   
+   // After
+   await molroo.createPersona({personality: {...}}, {llm});
+   await molroo.createPersona("description", {llm});
+   ```
+
+2. **External history management**
+   ```typescript
+   // Before
+   await persona.chat("Hello");  // MemoryAdapter required
+   
+   // After
+   let history = [];
+   const result = await persona.chat("Hello", {history});
+   history = result.updatedHistory;
+   ```
+
+3. **Vercel AI SDK directly**
+   ```typescript
+   // Before
+   createVercelAIAdapter({provider: 'openai', ...})
+   
+   // After
+   createOpenAI({...})  // Pass directly
+   ```
+
+4. **Removed adapter implementations**
+   - SQLite, Supabase, Pinecone adapters removed
+   - Implement `MemoryAdapter` interface yourself
+   - Or wait for API-hosted memory (coming soon)
+
+## API Reference
+
+See [API documentation](https://docs.molroo.io/sdk) for full reference.
 
 ## License
 

package/dist/cjs/api-client.d.ts

@@ -1,4 +1,5 @@
 import type { paths } from './generated/api';
+import { unwrap } from './shared/client-factory';
 /**
  * Create a typed openapi-fetch client for the molroo API.
  *
@@ -8,16 +9,5 @@ import type { paths } from './generated/api';
  */
 export declare function createApiClient(baseUrl: string, apiKey: string): import("openapi-fetch").Client<paths, `${string}/${string}`>;
 export type ApiClient = ReturnType<typeof createApiClient>;
-/**
- * Unwrap the `{ result: T }` envelope from API responses.
- *
- * Many API endpoints return `ResultWrapper` (typed as `{ result?: unknown }`)
- * in the OpenAPI spec. This helper extracts the `result` field and casts it
- * to the expected type.
- *
- * For endpoints with properly-typed response schemas, use `data.result` directly.
- */
-export declare function unwrap<T>(data: {
-    result?: unknown;
-} | undefined): T;
+export { unwrap };
 //# sourceMappingURL=api-client.d.ts.map

package/dist/cjs/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/api-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAwB7C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,gEAU9D;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GAAG,CAAC,CAEnE"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAqB,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,gEAE9D;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAE3D,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/cjs/api-client.js

@@ -1,28 +1,10 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrap = void 0;
 exports.createApiClient = createApiClient;
-exports.unwrap = unwrap;
-const openapi_fetch_1 = __importDefault(require("openapi-fetch"));
 const errors_1 = require("./errors");
-/**
- * Middleware: throw MolrooApiError on non-OK responses.
- *
- * Reads the error body `{ error: { code, message } }` and converts it
- * into a typed MolrooApiError before openapi-fetch processes the response.
- */
-const errorMiddleware = {
-    async onResponse({ response }) {
-        if (!response.ok) {
-            const body = await response.clone().json().catch(() => ({}));
-            const err = body;
-            throw new errors_1.MolrooApiError(err.error?.message ?? `API error ${response.status}`, err.error?.code ?? 'UNKNOWN', response.status);
-        }
-        // Return undefined to let openapi-fetch handle the response unchanged
-    },
-};
+const client_factory_1 = require("./shared/client-factory");
+Object.defineProperty(exports, "unwrap", { enumerable: true, get: function () { return client_factory_1.unwrap; } });
 /**
  * Create a typed openapi-fetch client for the molroo API.
  *
@@ -31,25 +13,5 @@ const errorMiddleware = {
  * @returns A fully-typed openapi-fetch client instance.
  */
 function createApiClient(baseUrl, apiKey) {
-    const client = (0, openapi_fetch_1.default)({
-        baseUrl: baseUrl.replace(/\/$/, ''),
-        headers: {
-            'Content-Type': 'application/json',
-            'X-API-Key': apiKey,
-        },
-    });
-    client.use(errorMiddleware);
-    return client;
-}
-/**
- * Unwrap the `{ result: T }` envelope from API responses.
- *
- * Many API endpoints return `ResultWrapper` (typed as `{ result?: unknown }`)
- * in the OpenAPI spec. This helper extracts the `result` field and casts it
- * to the expected type.
- *
- * For endpoints with properly-typed response schemas, use `data.result` directly.
- */
-function unwrap(data) {
-    return (data?.result ?? {});
+    return (0, client_factory_1.createTypedClient)({ baseUrl, apiKey, ErrorClass: errors_1.MolrooApiError });
 }

package/dist/cjs/errors.d.ts

@@ -1,17 +1,2 @@
-/**
- * Error thrown when the molroo API returns a non-OK response.
- *
- * Contains the API error code and HTTP status for programmatic handling.
- */
-export declare class MolrooApiError extends Error {
-    /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
-    code: string;
-    /** HTTP status code. */
-    status: number;
-    constructor(message: string, 
-    /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
-    code: string, 
-    /** HTTP status code. */
-    status: number);
-}
+export { MolrooApiError } from './shared/errors';
 //# sourceMappingURL=errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IAGrC,8EAA8E;IACvE,IAAI,EAAE,MAAM;IACnB,wBAAwB;IACjB,MAAM,EAAE,MAAM;gBAJrB,OAAO,EAAE,MAAM;IACf,8EAA8E;IACvE,IAAI,EAAE,MAAM;IACnB,wBAAwB;IACjB,MAAM,EAAE,MAAM;CAKxB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/cjs/errors.js

@@ -1,21 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MolrooApiError = void 0;
-/**
- * Error thrown when the molroo API returns a non-OK response.
- *
- * Contains the API error code and HTTP status for programmatic handling.
- */
-class MolrooApiError extends Error {
-    constructor(message, 
-    /** Machine-readable error code (e.g., 'ENTITY_NOT_FOUND', 'UNAUTHORIZED'). */
-    code, 
-    /** HTTP status code. */
-    status) {
-        super(message);
-        this.code = code;
-        this.status = status;
-        this.name = 'MolrooApiError';
-    }
-}
-exports.MolrooApiError = MolrooApiError;
+var errors_1 = require("./shared/errors");
+Object.defineProperty(exports, "MolrooApiError", { enumerable: true, get: function () { return errors_1.MolrooApiError; } });

package/dist/cjs/events/types.d.ts

@@ -1,28 +1,21 @@
 /**
- * Event Adapter interface for molroo SDK.
- *
- * Abstracts event emission so consumers can:
- * - Log emotion changes, relationship updates, stage transitions
- * - Send webhooks, push notifications, analytics events
- * - Build reactive UIs that respond to persona state changes
- *
- * Events are derived from API response data (AgentResponse fields).
- * Implementations are provided by the consumer — SDK only defines the interface.
+ * Event adapter interface for emitting persona-scoped events.
+ * Consumers can implement this to react to emotion changes, memory events, etc.
  */
-/** Persona-scoped event types — emitted from persona state changes. */
-export type PersonaEventType = 'emotion_changed' | 'relationship_changed' | 'memory_consolidated' | 'reflection_generated' | 'stage_transition' | 'mask_exposure' | 'goal_changed';
-export type SDKEventType = PersonaEventType;
-export interface SDKEvent {
-    type: SDKEventType;
-    /** Present for persona-scoped events. Absent for world-scoped events. */
-    personaId?: string;
-    timestamp: number;
-    payload: Record<string, unknown>;
-}
 export interface EventAdapter {
-    /** Emit a single event. */
     emit(event: SDKEvent): Promise<void>;
-    /** Emit multiple events in batch. Optional — falls back to sequential emit(). */
+    /** Optional batch emit for efficiency. Falls back to individual emit() if not provided. */
     emitBatch?(events: SDKEvent[]): Promise<void>;
 }
+/** Base event shape. */
+export interface SDKEvent {
+    type: string;
+    personaId?: string;
+    timestamp: number;
+    payload?: Record<string, unknown>;
+}
+/** Event type categories. */
+export type SDKEventType = 'emotion_changed' | 'memory_consolidated' | 'reflection_generated' | PersonaEventType;
+/** Persona-specific event types. */
+export type PersonaEventType = 'chat' | 'perceive' | 'emotion_update' | 'state_change' | 'memory_created' | 'reflection_created';
 //# sourceMappingURL=types.d.ts.map

package/dist/cjs/events/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/events/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uEAAuE;AACvE,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,sBAAsB,GACtB,qBAAqB,GACrB,sBAAsB,GACtB,kBAAkB,GAClB,eAAe,GACf,cAAc,CAAC;AAEnB,MAAM,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE5C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC,iFAAiF;IACjF,SAAS,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/events/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,2FAA2F;IAC3F,SAAS,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,wBAAwB;AACxB,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,6BAA6B;AAC7B,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,qBAAqB,GAAG,sBAAsB,GAAG,gBAAgB,CAAC;AAEjH,oCAAoC;AACpC,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,UAAU,GACV,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,oBAAoB,CAAC"}

package/dist/cjs/events/types.js

@@ -1,13 +1,2 @@
 "use strict";
-/**
- * Event Adapter interface for molroo SDK.
- *
- * Abstracts event emission so consumers can:
- * - Log emotion changes, relationship updates, stage transitions
- * - Send webhooks, push notifications, analytics events
- * - Build reactive UIs that respond to persona state changes
- *
- * Events are derived from API response data (AgentResponse fields).
- * Implementations are provided by the consumer — SDK only defines the interface.
- */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/index.d.ts

@@ -1,68 +1,46 @@
 /**
  * @molroo-io/sdk - Thin Client SDK for molroo emotion engine
  *
- * ## Boundary — this is where LLM orchestration lives:
- * - **LLM calls happen HERE** — consumer's API key, consumer's model.
- * - **Appraisal generation happens HERE** — LLM produces appraisal, SDK sends to API.
- * - **Memory recall happens HERE** — episodic/semantic/reflections from client stores.
- * - **Prompt composition**: API returns persona fragment → SDK adds memory context.
+ * ## Quick Start
  *
- * The API/engine never call LLM. This SDK is the bridge.
- *
- * @example
  * ```typescript
- * import { MolrooPersona } from '@molroo-io/sdk';
- * import { createVercelAIAdapter } from '@molroo-io/sdk';
+ * import { Molroo } from '@molroo-io/sdk';
+ * import { createOpenAI } from '@ai-sdk/openai';
+ *
+ * const molroo = new Molroo({ apiKey: 'mk_live_...' });
+ *
+ * const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });
  *
- * const llm = createVercelAIAdapter({
- *   provider: 'openai',
- *   apiKey: process.env.OPENAI_API_KEY!,
- * });
+ * // Create persona from description
+ * const sera = await molroo.createPersona(
+ *   'A kind and curious barista named Sera',
+ *   { llm: openai }
+ * );
  *
- * const persona = await MolrooPersona.create({
- *   baseUrl: 'https://api.molroo.io',
- *   apiKey: 'your_api_key',
- *   llm,
- * }, {
- *   config: { identity: { name: 'Sera' }, personality: { O: 0.7, C: 0.6, E: 0.8, A: 0.5, N: 0.3, H: 0.6 } },
- * });
+ * const result = await sera.chat('Hello!');
+ * ```
+ *
+ * ## Advanced: World Simulation
  *
- * const result = await persona.chat('Hello!');
+ * ```typescript
+ * const world = await molroo.createWorld({ name: 'Cafe' });
+ * const sera = await molroo.createPersona('Barista Sera', { llm: openai });
+ * await world.addPersona({ personaConfigId: sera.id, config: {...} });
  * ```
  */
 export { Molroo } from './world/world';
 export type { MolrooOptions, PersonaOptions } from './world/world';
-export { MolrooPersona } from './persona';
-export { MolrooApiError } from './types';
+export { MolrooApiError, WorldApiError } from './shared/errors';
+export { NEUTRAL_APPRAISAL, toWireAppraisal, fromWireAppraisal } from './shared/appraisal';
+export type { Appraisal } from './shared/appraisal';
 export type { LLMAdapter, Message, GenerateTextOptions, GenerateObjectOptions, } from './llm/adapter';
-export type { LLMShorthand, LLMInput } from './llm/resolve';
-export { VercelAIAdapter, createVercelAIAdapter } from './llm/vercel-ai';
-export type { VercelAIConfig } from './llm/vercel-ai';
-export type { MemoryAdapter, RecallQuery, SemanticRecallOptions, RecallLimits, } from './memory/types';
-export { isMemoryConfig } from './memory/types';
-export type { EpisodeAdapter, EpisodeQuery, SemanticAdapter, SemanticEntry, SemanticQuery, SemanticResult, EmbeddingAdapter, MemoryConfig, Reflection, } from './memory/types';
-export { InMemoryEpisodeAdapter } from './memory/in-memory';
-export type { RecallConfig } from './memory/recall';
-export type { SemanticMemory, SearchOptions, SearchResult } from './memory/semantic';
-export { InMemorySemanticMemory } from './memory/in-memory-semantic';
-export type { EpisodeStore, SemanticStore, EmbeddingProvider } from './memory/types';
-export { InMemoryEpisodeStore } from './memory/in-memory';
-export type { EventAdapter, SDKEvent, SDKEventType, PersonaEventType } from './events/types';
-export { ConsoleEventAdapter } from './events/console';
-export type { ConsoleEventAdapterOptions } from './events/console';
-export { WebhookEventAdapter } from './events/webhook';
-export type { WebhookEventAdapterOptions } from './events/webhook';
-export { generatePersona } from './generate/persona';
-export { GeneratePersonaSchema } from './generate/schema';
-export type { GeneratePersonaSchemaOutput } from './generate/schema';
-export type { MolrooPersonaConfig, PersonaSummary, PersonaState, PersonaChatResult, } from './persona';
+export type { LLMInput } from './llm/resolve';
+export type { MemoryAdapter, RecallQuery, SemanticRecallOptions, RecallLimits, Reflection, } from './memory/types';
+export type { PersonaSummary, PersonaState, PersonaChatResult, } from './persona';
 export type { InterlocutorContext, PerceiveOptions, PerceiveEvent, PerceiveContext, } from './types';
 export type { AgentResponse, VAD, Velocity, AppraisalVector, State, SoulStage, CatastropheState, MetacogState, AffectDynamicsState, InterpersonalState, RegulationState, RegulationStrategy, RegulationPhase, ActiveRegulation, RegulationRecord, EffectivenessRecord, NeedState, Episode, SocialUpdate, ReflectionPrompt, } from './types';
 export type { PersonaSnapshot, PersonaConfigData, PersonalityTraits, Identity, Goal, MotivationContext, } from './types';
 export type { ApiResponse, ApiErrorResponse, PersonaDynamicState, } from './types';
-export { AppraisalVectorSchema, LLMResponseSchema, LLMResponseWithToolsSchema, } from './llm/schema';
-export type { LLMResponseOutput, LLMResponseWithToolsOutput } from './llm/schema';
 export type { LLMPrompt, LLMResponse, } from './llm/types';
-export type { ChatMessage } from './llm/types';
 export { DEFAULT_PERSONA, withDefaults } from './defaults';
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC3F,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGpD,YAAY,EACV,UAAU,EACV,OAAO,EACP,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C,YAAY,EACV,aAAa,EACb,WAAW,EACX,qBAAqB,EACrB,YAAY,EACZ,UAAU,GACX,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EACV,cAAc,EACd,YAAY,EACZ,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAGnB,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,eAAe,GAChB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,aAAa,EACb,GAAG,EACH,QAAQ,EACR,eAAe,EACf,KAAK,EACL,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,SAAS,EACT,OAAO,EACP,YAAY,EACZ,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,EACR,IAAI,EACJ,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,SAAS,EACT,WAAW,GACZ,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}