molroo docsSDK ReferenceTypes
Input Types
InterlocutorContext, PerceiveOptions, ChatOptions, and other operation input types.
Input Types
Types used as inputs to SDK operations.
import type {
InterlocutorContext,
PerceiveOptions,
} from '@molroo-io/sdk';InterlocutorContext
Structured context about the conversation partner (interlocutor). When passed as from in persona.chat() or persona.perceive(), the SDK injects the description and extensions into the system prompt automatically.
interface InterlocutorContext {
name: string;
description?: string;
extensions?: Record<string, string>;
}| Field | Type | Description |
|---|---|---|
name | string | Display name of the interlocutor (also used as the source entity for memory recall) |
description | string? | Free-form description of the interlocutor |
extensions | Record<string, string>? | Arbitrary key-value pairs rendered as subsections in the system prompt |
Example:
const result = await persona.chat('Good morning!', {
from: {
name: 'Kim',
description: 'A weary traveler who just arrived at the tavern.',
extensions: {
inventory: 'sword, healing potion',
quest: 'Find the lost artifact of Eldoria',
},
},
});The from option on persona.chat() and persona.perceive() accepts either a plain string (treated as the sender name) or an InterlocutorContext object. When a string is passed, it is equivalent to { name: theString }.
PerceiveOptions
Options for persona.perceive().
interface PerceiveOptions {
from?: string | InterlocutorContext;
appraisal?: AppraisalVector;
type?: string;
stimulus?: {
bodyBudgetDelta?: number;
vadOverride?: Partial<VAD>;
vadDelta?: Partial<VAD>;
needsDelta?: Partial<{ autonomy: number; competence: number; relatedness: number }>;
};
payload?: Record<string, unknown>;
priorEpisodes?: Episode[];
relationshipContext?: { trust: number; familiarity: number };
skipMemory?: boolean;
}| Field | Type | Default | Description |
|---|---|---|---|
from | string | InterlocutorContext | 'user' | Source entity — a name string or structured InterlocutorContext |
appraisal | AppraisalVector | -- | Pre-computed appraisal vector for emotion computation |
type | string? | 'chat_message' | Event type identifier (e.g., 'news_event', 'environment_change') |
stimulus | object? | -- | Low-level state overrides that bypass the appraisal pipeline |
payload | Record<string, unknown>? | -- | Extra event data merged into the event payload alongside the message |
priorEpisodes | Episode[] | -- | Context memories for appraisal-aware processing |
relationshipContext | { trust, familiarity }? | -- | Relationship info between source entity and persona for appraisal bias |
skipMemory | boolean? | false | Skip saving the generated memoryEpisode to the episode store |
stimulus
Direct state adjustments for simulating environmental effects (fatigue, rest, mood shifts).
| Field | Type | Description |
|---|---|---|
bodyBudgetDelta | number? | Change to body budget (negative for fatigue, positive for rest) |
vadOverride | Partial<VAD>? | Force-set emotion coordinates |
vadDelta | Partial<VAD>? | Add to current emotion coordinates |
needsDelta | Partial<NeedState>? | Change to psychological needs (autonomy, competence, relatedness) |
Example (appraisal-based):
const response = await persona.perceive('The test results came back positive!', {
from: 'Doctor',
appraisal: {
goal_relevance: 0.9,
goal_congruence: 0.8,
expectedness: 0.4,
controllability: 0.2,
agency: -0.8,
norm_compatibility: 0.7,
internal_standards: 0,
adjustment_potential: 0.6,
urgency: 0.3,
},
});Example (stimulus-based):
const response = await persona.perceive('You feel a wave of exhaustion.', {
type: 'exhaustion',
stimulus: {
bodyBudgetDelta: -0.3,
vadDelta: { A: -0.4, V: -0.1 },
needsDelta: { competence: -0.2 },
},
});ChatOptions
Options for persona.chat().
interface ChatOptions {
from?: string | InterlocutorContext;
history?: Message[];
consumerSuffix?: string;
onToolCall?: (call: { name: string; args: Record<string, unknown>; result: unknown }) => void;
}| Field | Type | Default | Description |
|---|---|---|---|
from | string | InterlocutorContext | 'user' | Source entity -- a name string or structured InterlocutorContext with description/extensions injected into the system prompt |
history | Message[]? | -- | Conversation history for LLM context. Pass the updatedHistory from the previous chat() call. |
consumerSuffix | string? | -- | Extra text appended to the server-assembled system prompt |
onToolCall | function? | -- | Callback invoked when the LLM requests a tool call during generation |
The chat() method returns updatedHistory in the result, which should be saved and passed back on the next call for conversation continuity:
Example:
let history: Message[] = [];
const result = await persona.chat('Do you remember what we talked about?', {
from: 'Alex',
history,
consumerSuffix: 'Keep the response under 100 words.',
});
// Save history for next call
history = result.updatedHistory;
const result2 = await persona.chat('Tell me more!', { from: 'Alex', history });
history = result2.updatedHistory;