Overview of @molroo-io/sdk — the unified client SDK for the molroo emotion platform.

SDK Overview

@molroo-io/sdk is the official TypeScript client for the molroo emotion simulation platform. The unified Molroo class is the single entry point for creating personas, managing worlds, and orchestrating LLM-powered emotional interactions.

Installation

npm install @molroo-io/sdk ai

To use LLM-powered responses, install a Vercel AI SDK provider:

npm install @ai-sdk/openai

Quick Start

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

// Create a persona and chat
const sera = await molroo.createPersona(
  {
    identity: { name: 'Sera', role: 'barista', speakingStyle: 'warm and casual' },
    personality: { O: 0.7, C: 0.6, E: 0.8, A: 0.9, N: 0.3, H: 0.8 },
  },
  { llm: openai('gpt-4o-mini') },
);

// External history management
let history: Message[] = [];
const result = await sera.chat('What do you recommend today?', { history });
console.log(result.text);            // "Oh hey! You should try our new lavender latte!"
console.log(result.response.emotion); // { V: 0.65, A: 0.42, D: 0.38 }
history = result.updatedHistory;      // Save for next call

// Create a world with multiple personas
const world = await molroo.createWorld({ name: 'Cafe' });
await world.addPersona(sera);

Molroo

import { Molroo } from '@molroo-io/sdk';

Creates a unified SDK instance. No API call is made during construction.

Constructor

const molroo = new Molroo({
  apiKey: 'mk_live_...',
  baseUrl: 'https://api.molroo.io', // optional, this is the default
});

Option	Type	Description
`apiKey`	`string`	Your molroo API key
`baseUrl`	`string?`	API base URL. Default: `https://api.molroo.io`

Persona Methods

`createPersona(input, options?)`

Create a new persona and return a MolrooPersona instance. Accepts either a PersonaConfigData object or a natural language description string.

// From explicit config
const sera = await molroo.createPersona(
  {
    identity: { name: 'Sera', role: 'barista', speakingStyle: 'warm' },
    personality: { O: 0.7, C: 0.6, E: 0.8, A: 0.5, N: 0.3, H: 0.6 },
  },
  { llm: openai('gpt-4o-mini') },
);

// From description (requires llm)
const sera = await molroo.createPersona(
  'A warm and cheerful barista named Sera who loves coffee',
  { llm: openai('gpt-4o-mini') },
);

`connectPersona(id, options?)`

Connect to an existing persona by ID and return a MolrooPersona instance.

const sera = await molroo.connectPersona('prs_abc123', { llm: openai('gpt-4o-mini') });
await sera.chat('How are you today?', { history });

`listPersonas()`

List all personas for the authenticated tenant.

const { personas, nextCursor } = await molroo.listPersonas();

World Methods

`createWorld(options)`

Create a new world and return a World instance.

const world = await molroo.createWorld({
  name: 'My World',
  description: 'A test world',              // optional
  accessPolicy: 'closed',              // optional: 'closed' | 'open'
  responseRule: 'target',              // optional: 'target' | 'all' | 'ai'
});
console.log(world.id); // 'v-abc123'

`getWorld(id)`

Get an existing world by ID and return a World instance.

const world = await molroo.getWorld('v-abc123');

`listWorlds(options?)`

List worlds with optional pagination.

const { worlds, nextCursor } = await molroo.listWorlds({ limit: 10 });
// worlds: WorldData[] (plain objects, not World instances)

Persona Options

Options passed to createPersona() and connectPersona():

Option	Type	Description
`llm`	`LLMInput`	Vercel AI SDK `LanguageModel` or `LLMAdapter` for `chat()`
`engineLlm`	`LLMInput`	Separate LLM for appraisal (split mode)
`memory`	`MemoryAdapter`	Optional memory adapter for advanced features
`recall`	`RecallLimits`	Tune how many memories are recalled per `chat()`
`events`	`EventAdapter`	Event emission adapter
`appraisalMode`	`'direct' \| 'event'`	Appraisal generation mode. `'direct'` (default) generates raw appraisal vectors; `'event'` classifies messages into event categories and converts to appraisal server-side.

Two LLM Modes

Combined mode (default) -- A single LLM call returns both response text and appraisal in one generateObject() call.

Split mode -- A cheap model generates the appraisal first, the engine updates emotion, then a quality model generates the response with the updated emotional state.

const sera = await molroo.createPersona(personaConfig, {
  llm: openai('gpt-4o'),           // quality model for response
  engineLlm: openai('gpt-4o-mini'), // cheap model for appraisal
});

Emotion-only Mode

Skip LLM entirely by omitting the llm option. Use perceive() to send manual appraisal values directly:

const sera = await molroo.createPersona(personaConfig);

await sera.perceive('Hello', {
  appraisal: {
    goal_relevance: 0.5,
    goal_congruence: 0.8,
    expectedness: 0.6,
    controllability: 0.5,
    agency: 0,
    norm_compatibility: 0.7,
    internal_standards: 0,
    adjustment_potential: 0.5,
    urgency: 0.5,
  },
});

Package Exports

`@molroo-io/sdk` (main)

Export	Description
`Molroo`	Unified entry point -- personas and worlds
`MolrooApiError`	Error class for persona API errors
`WorldApiError`	Error class for world API errors
Types	TypeScript interfaces for all inputs, results, and state

`@molroo-io/sdk/expression` (subpath)

Export	Description
`StyleProfile`	Type definition for extracted speaking style profiles
`ExtractionOptions`	Options for style extraction

`@molroo-io/sdk/world` (subpath)

Export	Description
`Molroo`	Same unified entry point (re-exported)
`World`	Per-world operations -- personas, actions, relationships
`WorldApiError`	Error class for world API errors
`createWorldClient`	Low-level typed `openapi-fetch` client

Architecture

+-------------------------------------+
|           Your Application          |
|   +-----------------------------+   |
|   |     @molroo-io/sdk          |   |
|   |  const molroo = new Molroo()|   |
|   |  +----------+              |   |
|   |  | LLM (AI  |              |   |
|   |  | SDK)     |              |   |
|   |  +----------+              |   |
|   +--------------+--------------+   |
+------------------+------------------+
                   | HTTPS (X-API-Key)
+------------------+------------------+
|     api.molroo.io                   |
|   +--------------+--------------+   |
|   |       Emotion Engine         |   |
|   +-----------------------------+   |
+-------------------------------------+

Next Steps

MolrooPersona -- Full persona API reference
World -- World operations (multi-persona, actions, relationships)
LLM Adapter -- Configure LLM providers or build a custom adapter
Memory -- MemoryAdapter interface for advanced memory features
Configuration Types -- Persona setup and configuration types

SDK Overview

On this page