SDK Overview
Overview of @molroo-ai/sdk — the client SDK for the molroo emotion platform.
SDK Overview
@molroo-ai/sdk is the official client SDK for the molroo emotion simulation platform. It provides a high-level interface for creating worlds, chatting with emotion-aware personas, dispatching events, and managing world state — all backed by the molroo API.
Installation
npm install @molroo-ai/sdkTo use LLM-powered responses, install the Vercel AI adapter and a provider:
npm install @molroo-ai/adapter-llm @ai-sdk/openaiBasic Usage
import { MolrooWorld } from '@molroo-ai/sdk';
import { VercelAIAdapter } from '@molroo-ai/adapter-llm';
import { openai } from '@ai-sdk/openai';
// 1. Create an LLM adapter (optional — skip for emotion-only mode)
const llm = new VercelAIAdapter({ model: openai('gpt-4o-mini') });
// 2. Create a world with a persona
const world = await MolrooWorld.create(
{ baseUrl: 'https://api.molroo.io', apiKey: 'your-api-key', llm },
{
definition: { identity: { name: 'Cafe World', tone: 'warm' } },
entities: [
{ name: 'user', type: 'user' },
{ name: 'Sera', type: 'persona' },
],
personaConfigs: {
Sera: {
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 },
},
},
},
);
// 3. Chat — the SDK handles context fetching, LLM calls, and emotion processing
const result = await world.chat('Sera', 'What do you recommend today?');
console.log(result.response.text);
// "Oh hey! You should try our new lavender latte!"
console.log(result.response.emotion.discrete.primary);
// 'joy'
console.log(result.response.emotion.vad);
// { V: 0.65, A: 0.42, D: 0.38 }Two Modes of Operation
With LLM adapter — The SDK fetches world context, generates a response via your LLM, and sends it to the API for emotion processing. This is the standard chat flow.
Without LLM adapter (emotion-only) — You provide manual appraisal values. The API computes emotions without any LLM calls. Useful for game engines or systems with their own dialogue generation.
// Emotion-only: no LLM needed
const result = await world.chat('Sera', 'Hello', {
appraisal: {
goal_relevance: 0.5,
goal_congruence: 0.8,
expectedness: 0.6,
controllability: 0.5,
agency: 0,
norm_compatibility: 0.7,
},
});Package Exports
The SDK exports a single main class and supporting types:
| Export | Description |
|---|---|
MolrooWorld | Main entry point — world creation, chat, events, ticking, mutations, snapshots |
MolrooApiError | Error class with machine-readable error codes |
LLMAdapter | Interface for LLM integration (implemented by @molroo-ai/adapter-llm) |
Plugin, compose, createPlugin | Plugin system for extending world behavior |
withHistory | Built-in history management plugin |
| Types | TypeScript interfaces for all inputs, results, and state |
Architecture
┌─────────────────────────────────────┐
│ Your Application │
│ ┌─────────────────────────────┐ │
│ │ @molroo-ai/sdk │ │
│ │ MolrooWorld.chat() │ │
│ │ ┌──────────┐ ┌──────────┐ │ │
│ │ │LLMAdapter│ │ Plugins │ │ │
│ │ └──────────┘ └──────────┘ │ │
│ └──────────────┬──────────────┘ │
└──────────────────┼──────────────────┘
│ HTTPS (X-API-Key)
┌──────────────────┼──────────────────┐
│ api.molroo.io │
│ ┌──────────────┴──────────────┐ │
│ │ WorldDO │ │
│ │ core + persona + world │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘Next Steps
- MolrooWorld — Full API reference for the main class
- LLM Adapter — Configure or build a custom LLM adapter
- Plugin System — Extend world behavior with plugins
- Configuration Types — World setup and configuration types