Quick Start

Build an AI character with authentic emotions in under 5 minutes.

Prerequisites

Node.js 18+ installed
A molroo API key from the dashboard
An LLM provider API key (OpenAI, Anthropic, Google, or OpenRouter) if you want LLM-generated responses

Install

npm install @molroo-io/sdk ai

You also need a Vercel AI SDK provider for your chosen LLM:

# Pick one (or more)
npm install @ai-sdk/openai       # OpenAI (GPT-4o, GPT-4o-mini, ...)
npm install @ai-sdk/anthropic    # Anthropic (Claude Sonnet, Haiku, Opus)
npm install @ai-sdk/google-vertex # Google Vertex AI (Gemini)

OpenRouter can be accessed via the @ai-sdk/openai package with a custom baseURL, giving you access to 100+ models from a single API key.

Create the client

Molroo is the unified entry point for all SDK operations -- personas, worlds, and more. The baseUrl defaults to https://api.molroo.io.

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

const molroo = new Molroo({ apiKey: 'mk_live_...' });

// Create your LLM provider
const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });

Create a persona

A persona is an AI character with a full emotion engine -- personality, mood, somatic markers, and memory. Each persona runs as an isolated instance on the server.

const sera = await molroo.createPersona(
  {
    identity: {
      name: 'Sera',
      role: 'friendly 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') },
);

You can also create a persona from a natural language description:

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

The personality object uses a 6-factor model: Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism, Honesty-Humility. Values range from 0 to 1.

For other providers (Anthropic, Google Vertex AI, OpenRouter) and advanced configuration, see the LLM Adapter guide and the LLM Adapter Reference.

Rich character identity

For immersive scenarios, use description for freeform backstory and extensions for structured character details:

const sera = await molroo.createPersona(
  {
    identity: {
      name: 'Jaehwa Lee',
      role: '45-year-old woman',
      description: 'Born in Seoul, Yonsei law degree. Partner at a top law firm...',
      extensions: {
        'Speaking patterns': 'Formal endings (~해요/~이에요), measured pace...',
        'Emotional regulation': 'Cognitive reappraisal: reframes situations...',
        'Inner contradictions': 'Perfectionism vs. need for approval...',
      },
    },
    personality: { O: 0.5, C: 0.9, E: 0.4, A: 0.3, N: 0.6, H: 0.7 },
  },
  { llm: openai('gpt-4o-mini') },
);

Chat with a persona

Send a message and get back an emotion-aware response. Manage conversation history externally using updatedHistory:

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

let history: Message[] = [];

const result = await sera.chat('Hi! What do you recommend today?', { history });

console.log(result.text);
// "Oh hey! You've gotta try our new lavender latte — it's been flying off the shelf!"

console.log(result.response.emotion);
// { V: 0.65, A: 0.42, D: 0.38 }

// Save history for the next call
history = result.updatedHistory;

// Continue the conversation
const result2 = await sera.chat('Sounds great, I will take one!', { history });
history = result2.updatedHistory;

The result contains the LLM-generated text, the full engine response with VAD coordinates, discrete emotion, mood, somatic markers, and the updatedHistory for external history management.

Connect to an existing persona

If you already created a persona and want to reconnect later:

const sera = await molroo.connectPersona('existing-persona-id', {
  llm: openai('gpt-4o-mini'),
});

Emotion-only mode (no LLM)

You can skip LLM integration entirely and provide manual appraisal values. This is useful for game engines or systems that already have their own dialogue generation:

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

In emotion-only mode, use perceive() to send events to the emotion engine. No LLM calls are made -- you get pure emotion computation.

Two LLM modes

Combined mode (default)

A single LLM call returns both response text and appraisal:

const sera = await molroo.createPersona(personaConfig, {
  llm: openai('gpt-4o-mini'),
});

Split mode

Use a cheap model for appraisal and a quality model for the response. The appraisal runs first, the engine updates the emotion, then the response is generated with the new emotional state:

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

Quick Start

Quick Start

Prerequisites

Install

Create the client

Create a persona

Rich character identity

Chat with a persona

Connect to an existing persona

Emotion-only mode (no LLM)

Two LLM modes

Combined mode (default)

Split mode

Next steps

Core Concepts

Emotion Pipeline

LLM Adapter

Memory

On this page