Configuration Types
PersonaConfigData, Identity, PersonalityTraits, Goal, and related persona setup types.
Configuration Types
Types used when creating and configuring molroo personas.
import type {
PersonaConfigData,
PersonalityTraits,
Identity,
Goal,
SimConfig,
CalibrationConfig,
} from '@molroo-io/sdk';PersonaConfigData
Configuration data for creating or updating a persona via molroo.createPersona() or persona.patch().
interface PersonaConfigData {
personality?: PersonalityTraits;
identity?: Identity;
goals?: Goal[];
[key: string]: unknown;
}| Field | Type | Required | Description |
|---|---|---|---|
personality | PersonalityTraits | No | Personality factor scores (0-1) |
identity | Identity | No | Name, role, speaking style, values |
goals | Goal[] | No | Persona's goals and motivations |
[key] | unknown | -- | Extensible with custom fields |
Example:
const molroo = new Molroo({ apiKey: 'mk_live_xxx' });
const persona = await molroo.createPersona(
{
identity: {
name: 'Sera',
role: 'barista at a cozy cafe',
speakingStyle: 'warm and casual, uses coffee metaphors',
coreValues: ['kindness', 'creativity', 'authenticity'],
},
personality: { O: 0.7, C: 0.6, E: 0.8, A: 0.9, N: 0.3, H: 0.8 },
goals: [
{ content: 'Make every customer feel welcome', priority: 1 },
{ content: 'Perfect the art of latte art', priority: 0.7 },
],
},
{ llm },
);PersonalityTraits
Personality factor scores. Each factor ranges from 0 to 1.
type PersonalityTraits = {
O: number;
C: number;
E: number;
A: number;
N: number;
H: number;
};| Key | Factor | Range | Description |
|---|---|---|---|
O | Openness to Experience | 0 - 1 | Curiosity, creativity, openness to new ideas |
C | Conscientiousness | 0 - 1 | Organization, discipline, reliability |
E | Extraversion | 0 - 1 | Sociability, assertiveness, positive emotionality |
A | Agreeableness | 0 - 1 | Cooperativeness, tolerance, gentleness |
N | Neuroticism | 0 - 1 | Emotional volatility, anxiety, sensitivity |
H | Honesty-Humility | 0 - 1 | Sincerity, fairness, modesty |
Example:
// A cheerful, open, and agreeable persona
const personality: PersonalityTraits = {
O: 0.8, // Very open and creative
C: 0.5, // Moderately organized
E: 0.7, // Fairly extroverted
A: 0.9, // Highly agreeable
N: 0.2, // Emotionally stable
H: 0.8, // Very honest and humble
};Identity
Persona identity information used for system prompt construction and character consistency.
interface Identity {
name: string;
role?: string;
speakingStyle?: string;
coreValues?: string[];
culturalIdentity?: string;
description?: string;
extensions?: Record<string, string>;
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Persona display name |
role | string? | No | Character role or occupation (e.g., 'barista', 'knight') |
speakingStyle | string? | No | Description of how the persona speaks (e.g., 'warm and casual') |
coreValues | string[]? | No | Core values that guide the persona's behavior |
culturalIdentity | string? | No | Cultural background or identity |
description | string? | No | Free-form description of the persona |
extensions | Record<string, string>? | No | Arbitrary key-value pairs rendered as subsections in the system prompt |
Goal
A persona's goal or motivation. Goals are included in the system prompt and influence emotional appraisal.
interface Goal {
id?: string;
content: string;
priority?: number;
mutable?: boolean;
status?: 'active' | 'achieved' | 'abandoned';
}| Field | Type | Default | Description |
|---|---|---|---|
id | string? | auto-generated | Unique goal identifier |
content | string | -- | Goal description (e.g., 'Protect the village') |
priority | number? | 1 | Priority weight (0 to 1). Higher priority goals have more influence on emotion |
mutable | boolean? | true | Whether the goal can be modified or removed during interaction |
status | string? | 'active' | Goal status: 'active', 'achieved', or 'abandoned' |
Example:
const goals: Goal[] = [
{
content: 'Make every customer feel welcome',
priority: 1,
mutable: false, // Core goal, never changes
},
{
content: 'Learn to make the perfect cappuccino',
priority: 0.6,
mutable: true, // Can evolve through interaction
status: 'active',
},
];SimConfig
Simulation configuration for tuning engine physics. Passed as simConfig in PersonaConfigData.
interface SimConfig {
calibration?: CalibrationConfig;
}| Field | Type | Required | Description |
|---|---|---|---|
calibration | CalibrationConfig | No | Body budget physics constants |
CalibrationConfig
Controls body budget recovery, depletion, and per-turn intensity scaling. See the Calibration guide for usage examples.
interface CalibrationConfig {
budgetRecoveryPerHour?: number;
budgetMinimum?: number;
turnScale?: number;
baselineIntensityWeight?: number;
}| Field | Type | Description |
|---|---|---|
budgetRecoveryPerHour | number? | Controls how fast body budget recovers over time. Higher = faster recovery. |
budgetMinimum | number? | Floor for the body budget. Prevents complete depletion. |
turnScale | number? | Multiplier for per-turn emotion intensity. Higher = more dramatic reactions. |
baselineIntensityWeight | number? | How much personality baseline contributes vs. situational appraisal. |
All fields are optional. Omitted fields use engine defaults.