Emotion Types
VAD, AppraisalVector, State, AgentResponse, and emotion sub-system types.
Emotion Types
Core emotion types returned by the molroo API. These represent the heart of molroo's psychology-based emotion simulation.
import type {
VAD,
AppraisalVector,
AgentResponse,
State,
SoulStage,
NeedState,
CatastropheState,
Episode,
} from '@molroo-ai/sdk';VAD
Valence-Arousal-Dominance vector -- the core emotion representation. All emotional states in molroo are represented in this 3D space.
interface VAD {
/** Valence: negative (-1) to positive (+1) */
V: number;
/** Arousal: calm (0) to activated (1) */
A: number;
/** Dominance: submissive (-1) to dominant (+1) */
D: number;
}| Dimension | Range | Low | High |
|---|---|---|---|
V (Valence) | -1 to +1 | Negative (sad, angry) | Positive (happy, content) |
A (Arousal) | 0 to 1 | Calm, relaxed | Activated, excited |
D (Dominance) | -1 to +1 | Submissive, powerless | Dominant, in control |
Example values:
| Emotion | V | A | D |
|---|---|---|---|
| Joy | +0.7 | +0.5 | +0.4 |
| Anger | -0.6 | +0.8 | +0.5 |
| Sadness | -0.7 | -0.3 | -0.5 |
| Fear | -0.6 | +0.7 | -0.6 |
| Calm | +0.2 | -0.4 | +0.1 |
AppraisalVector
Cognitive appraisal vector based on the Scherer component process model. Describes how a persona evaluates an incoming stimulus along 6 dimensions. The LLM generates these values during chat, or you provide them manually in emotion-only mode.
interface AppraisalVector {
/** How relevant is this to the persona's goals? [-1, 1] */
goal_relevance: number;
/** Does this help (+1) or hinder (-1) goals? [-1, 1] */
goal_congruence: number;
/** How expected was this? [0, 1] */
expectedness: number;
/** How much control does the persona have? [0, 1] */
controllability: number;
/** Who caused this — self (+1) or other (-1)? [-1, 1] */
agency: number;
/** Compatible with the persona's norms? [-1, 1] */
norm_compatibility: number;
}| Dimension | Range | Description |
|---|---|---|
goal_relevance | -1 to +1 | How relevant to the persona's current goals |
goal_congruence | -1 to +1 | Whether this helps (+) or hinders (-) goals |
expectedness | 0 to 1 | How expected/predictable this was |
controllability | 0 to 1 | How much control the persona has over the situation |
agency | -1 to +1 | Who is responsible: self (+1) or other (-1) |
norm_compatibility | -1 to +1 | Whether this fits the persona's moral/social norms |
AgentResponse
Response from the emotion engine for a single entity interaction. This is the primary result type returned within ChatResult and EventResult.
interface AgentResponse {
emotion: {
vad: VAD;
discrete: {
primary: string;
secondary?: string;
intensity: number;
};
};
mood?: {
vad: VAD;
valence: 'negative' | 'neutral' | 'positive';
arousal: 'calm' | 'moderate' | 'activated';
dominance: 'submissive' | 'balanced' | 'dominant';
};
somatic?: string[];
narrative?: {
tone: number; // -1 (decline) to +1 (recovery)
agency: number; // -1 (reactive) to +1 (agentic)
coherence: number; // 0 to 1
};
text?: string;
action?: string;
memoryEpisode?: Episode;
socialUpdates?: SocialUpdate[];
reflectionPrompt?: ReflectionPrompt;
stageTransition?: boolean;
maskExposure?: { integrity: number; state: string };
goalChanges?: { achieved: string[]; blocked: string[] };
}emotion
| Field | Type | Description |
|---|---|---|
emotion.vad | VAD | Current emotion in VAD space |
emotion.discrete.primary | string | Primary discrete emotion label (e.g., 'joy', 'anger', 'fear') |
emotion.discrete.secondary | string? | Optional secondary emotion label |
emotion.discrete.intensity | number | Emotion intensity (0 to 1) |
mood
Background mood (changes more slowly than emotion):
| Field | Type | Description |
|---|---|---|
mood.vad | VAD | Mood in VAD space |
mood.valence | 'negative' | 'neutral' | 'positive' | Valence category |
mood.arousal | 'calm' | 'moderate' | 'activated' | Arousal category |
mood.dominance | 'submissive' | 'balanced' | 'dominant' | Dominance category |
somatic
Array of body sensation strings (e.g., ['chest_warmth', 'stomach_butterflies']).
narrative
Self-narrative perception:
| Field | Range | Description |
|---|---|---|
tone | -1 to +1 | Narrative tone: decline (-1) to recovery (+1) |
agency | -1 to +1 | Perceived agency: reactive (-1) to agentic (+1) |
coherence | 0 to 1 | How coherent the persona's self-narrative is |
Side effects
| Field | Type | Description |
|---|---|---|
text | string? | LLM-generated response text (empty in emotion-only mode) |
action | string? | Suggested action |
memoryEpisode | Episode | Memory episode recorded during this interaction |
socialUpdates | SocialUpdate[] | Relationship changes triggered by this interaction |
reflectionPrompt | ReflectionPrompt | Prompt for LLM-generated reflection (used with MemoryAdapter) |
stageTransition | boolean? | Whether a soul stage transition occurred |
maskExposure | { integrity, state } | Mask integrity drop (persona facade cracking) |
goalChanges | { achieved, blocked } | Goals that changed status this turn |
State
Complete internal emotion state of a persona, including all sub-systems. Returned when includeState: true is set in chat options.
interface State {
emotion: VAD;
velocity: Velocity;
emotion_history: Array<VAD & { timestamp: number }>;
body_budget: number;
soul_stage: SoulStage;
prediction_model: AppraisalVector;
prev_emotion_delta?: VAD;
need_state?: NeedState;
lastUpdated?: number;
catastrophe: CatastropheState;
metacog: MetacogState;
affect_dynamics: AffectDynamicsState;
interpersonal: InterpersonalState;
regulation: RegulationState;
prevMaskIntegrity?: number;
}| Field | Type | Description |
|---|---|---|
emotion | VAD | Current emotion coordinates |
velocity | Velocity | Rate of change in VAD space |
emotion_history | Array<VAD & { timestamp }> | Recent emotion history |
body_budget | number | Body budget (0 to 1) -- overall physiological resource |
soul_stage | SoulStage | Current soul stage (psychological development level) |
prediction_model | AppraisalVector | Learned appraisal expectations |
need_state | NeedState | Self-Determination Theory needs |
catastrophe | CatastropheState | Zeeman catastrophe model state |
metacog | MetacogState | Metacognitive state (self-awareness, regulation history) |
affect_dynamics | AffectDynamicsState | Affect variability, instability, inertia |
interpersonal | InterpersonalState | Interpersonal circumplex position (dominance, affiliation) |
regulation | RegulationState | Emotion regulation strategies and effectiveness |
SoulStage
Psychological development stage. The persona progresses through 15 stages reflecting psychological growth or decline.
interface SoulStage {
id: number; // [1, 15]
name: string;
tolerance: number;
stress_modifier: number;
appraisal_bias: Partial<AppraisalVector>;
avoidance_mod: number;
blend_table: { rational: number; irrational: number };
cumulative_load: number;
turns_in_stage: number;
}| Field | Type | Description |
|---|---|---|
id | number | Stage number (1-15) |
name | string | Stage name |
tolerance | number | Stress tolerance threshold |
stress_modifier | number | How stress affects this stage |
appraisal_bias | Partial<AppraisalVector> | Appraisal biases at this stage |
avoidance_mod | number | Avoidance behavior modifier |
blend_table | { rational, irrational } | Rational vs irrational response blend |
cumulative_load | number | Accumulated psychological load |
turns_in_stage | number | How many turns spent in this stage |
NeedState
Self-Determination Theory needs.
interface NeedState {
autonomy: number; // [0, 1]
competence: number; // [0, 1]
relatedness: number; // [0, 1]
}CatastropheState
Zeeman catastrophe model state. Models sudden emotional shifts (e.g., going from calm to rage).
interface CatastropheState {
alpha: number; // Asymmetry factor
beta: number; // Bifurcation factor
z: number; // State variable
hysteresis_bound: number;
}Episode
A memory episode recorded during an interaction.
interface Episode {
id: string;
timestamp: number;
sourceEntity?: string;
context?: string;
appraisal: AppraisalVector;
emotionSnapshot: VAD;
intensity: number;
importance: number;
}| Field | Type | Description |
|---|---|---|
id | string | Unique episode ID |
timestamp | number | Epoch milliseconds |
sourceEntity | string? | Entity that caused this episode |
context | string? | Context/description of what happened |
appraisal | AppraisalVector | The appraisal that produced this episode |
emotionSnapshot | VAD | Emotion at the time of the episode |
intensity | number | Emotional intensity of the episode |
importance | number | How important this episode is for memory recall |
SocialUpdate
A relationship change triggered during an interaction.
interface SocialUpdate {
entityId: string;
field: string;
oldValue: number;
newValue: number;
}PersonaSnapshot
Complete serialized state of a persona, included in WorldSnapshot entities. Contains the full internal state, relationships, goals, and all sub-system data.
interface PersonaSnapshot {
state: State;
relationships: Record<string, Relationship>;
goals: Goal[];
selfConcept?: string;
mood?: VAD;
moodHistory?: Array<{ emotion: VAD; intensity: number }>;
somatic?: {
regions: {
head: number; neck: number; chest: number;
stomach: number; upperBack: number; hands: number; legs: number;
};
interoception: number;
};
narrative?: {
tone: number;
coherence: { temporal: number; causal: number; thematic: number };
agency: number;
communion: number;
arcs: Array<{
id: string;
type: 'decline' | 'recovery' | 'stability' | 'growth';
strength: number;
episodeIds: string[];
theme: string;
}>;
};
tmt?: {
mortalitySalience: number;
deathAnxiety: number;
proximity: 'immediate' | 'near' | 'distant' | 'abstract';
proximalDefense: boolean;
distalDefense: boolean;
defenseTarget: 'in_group' | 'out_group' | 'values' | 'self_esteem' | null;
defenseStrength: number;
lastReminderTime: number;
};
selfEsteem?: { global: number; contingencies: Record<string, number> };
motivationContexts?: Record<string, MotivationContext>;
}Key sub-systems:
- state -- full emotion
Stateincluding all sub-systems - relationships -- map of entity ID to
Relationshipdata - goals -- array of active/achieved/abandoned goals
- somatic -- body region activation map and interoception level
- narrative -- self-narrative arcs (decline, recovery, stability, growth)
- tmt -- Terror Management Theory state (mortality salience, defense mechanisms)
- selfEsteem -- global self-esteem and contingencies
- motivationContexts -- Self-Determination Theory motivation per context