@molroo-io/sdk 0.5.2

package/dist/esm/memory/types.d.ts

@@ -0,0 +1,231 @@
+import type { Episode, VAD } from '../types';
+export type { Episode, VAD };
+/**
+ * Single-interface memory adapter for the SDK.
+ *
+ * Duck-type compatible with `@molroo-io/persona`'s `MemoryAdapter`.
+ * Implementations (SqliteMemoryAdapter, SupabaseMemoryAdapter, etc.) provide
+ * a single object that handles episode storage, recall, and optionally
+ * semantic/vector search internally.
+ *
+ * @example
+ * ```typescript
+ * import { MolrooPersona } from '@molroo-io/sdk';
+ *
+ * const persona = await MolrooPersona.create({
+ *   baseUrl: 'https://api.molroo.io',
+ *   apiKey: 'key',
+ *   llm,
+ *   memory: myMemoryAdapter,
+ * });
+ * ```
+ */
+export interface MemoryAdapter {
+    /** Save an episode returned by the API's AgentResponse. */
+    saveEpisode(episode: Episode): Promise<void>;
+    /**
+     * Recall relevant episodes by structured query.
+     * Accepts both SDK `RecallQuery` and `EpisodeQuery` shapes.
+     */
+    recall(query: RecallQuery): Promise<Episode[]>;
+    /** Save a reflection generated by LLM. Optional — omit for episode-only storage. */
+    saveReflection?(reflection: Reflection): Promise<void>;
+    /** Retrieve reflections for a source entity. Optional. */
+    getReflections?(sourceEntity?: string): Promise<Reflection[]>;
+    /**
+     * Vector/semantic similarity search. Optional.
+     * When provided, the adapter handles embedding internally — no separate
+     * EmbeddingAdapter needed.
+     */
+    semanticRecall?(query: string, options?: SemanticRecallOptions): Promise<Episode[]>;
+    /** Retrieve episodes by IDs. Optional — used for hydrating search results. */
+    getByIds?(ids: string[]): Promise<Episode[]>;
+}
+/**
+ * Query for recalling episodes from a MemoryAdapter.
+ *
+ * Compatible with both persona engine's `RecallQuery` (`context` field)
+ * and the SDK's `EpisodeQuery` (`contextContains` field).
+ */
+export interface RecallQuery {
+    /** Filter by source entity name. */
+    sourceEntity?: string;
+    /** Search keyword or vector query text (persona engine compatibility). */
+    context?: string;
+    /** Max episodes to return. Default: implementation-specific. */
+    limit?: number;
+    /** Minimum importance score to include. */
+    minImportance?: number;
+    /** Epoch ms range [from, to]. */
+    timeRange?: [number, number];
+    /** Filter by episode type. Single string or array (OR match). */
+    type?: string | string[];
+    /** Valence range [min, max]. */
+    valenceRange?: [number, number];
+}
+/** Options for semantic/vector recall. */
+export interface SemanticRecallOptions {
+    /** Number of results to return. Default: 5. */
+    topK?: number;
+    /** Minimum similarity score to include. */
+    minScore?: number;
+    /** Additional structured filters. */
+    filter?: Partial<RecallQuery>;
+}
+/** Recall limit configuration, extracted for reuse. */
+export interface RecallLimits {
+    /** Max episodic memories per recall. Default: 5. */
+    episodicLimit?: number;
+    /** Max semantic results per recall. Default: 3. */
+    semanticLimit?: number;
+    /** Max reflections per recall. Default: 3. */
+    reflectionLimit?: number;
+    /** Minimum importance threshold. Default: 0. */
+    minImportance?: number;
+}
+/**
+ * Type guard: returns true if the memory config is a `MemoryConfig` (split adapters),
+ * false if it's a `MemoryAdapter` (single adapter).
+ *
+ * Discriminates by checking for `saveEpisode` — present on MemoryAdapter, absent on MemoryConfig.
+ */
+export declare function isMemoryConfig(m: MemoryAdapter | MemoryConfig): m is MemoryConfig;
+/**
+ * EpisodeAdapter — RDB-backed structured episode storage.
+ *
+ * Required adapter for the split `MemoryConfig` approach. Handles saving and
+ * recalling episodic memories (conversation episodes + reflections).
+ *
+ * Implementations: InMemoryEpisodeAdapter (built-in), or consumer-provided
+ * (SQLite, PostgreSQL, Supabase, etc.).
+ */
+export interface EpisodeAdapter {
+    /** Save an episode returned by the API's AgentResponse. */
+    saveEpisode(episode: Episode): Promise<void>;
+    /** Recall relevant episodes by structured query (time-ordered). */
+    recall(query: EpisodeQuery): Promise<Episode[]>;
+    /** Retrieve episodes by IDs — used for hydrating SemanticStore results. */
+    getByIds?(ids: string[]): Promise<Episode[]>;
+    /** Save a reflection generated by LLM. */
+    saveReflection(reflection: Reflection): Promise<void>;
+    /** Retrieve reflections for a source entity. */
+    getReflections(sourceEntity?: string, limit?: number): Promise<Reflection[]>;
+}
+/** Structured query for episodic recall (RDB-style filtering). */
+export interface EpisodeQuery {
+    /** Filter by source entity name. */
+    sourceEntity?: string;
+    /** LIKE search on episode context (not semantic). */
+    contextContains?: string;
+    /** Filter by episode type. Single string or array (OR match). */
+    type?: string | string[];
+    /** Max episodes to return. Default: 10. */
+    limit?: number;
+    /** Minimum importance score to include. */
+    minImportance?: number;
+    /** Epoch ms range [from, to]. */
+    timeRange?: [number, number];
+    /** Valence range [min, max]. */
+    valenceRange?: [number, number];
+}
+/**
+ * SemanticAdapter — Vector DB-backed semantic search.
+ *
+ * Optional adapter for similarity-based memory recall.
+ * Requires an EmbeddingAdapter to be configured alongside.
+ *
+ * Implementations: consumer-provided (Pinecone, pgvector, ChromaDB, etc.).
+ */
+export interface SemanticAdapter {
+    /** Index a semantic entry (episode or reflection embedding). */
+    index(entry: SemanticEntry): Promise<void>;
+    /** Search for semantically similar entries. */
+    search(query: SemanticQuery): Promise<SemanticResult[]>;
+}
+/** Entry to index in the vector store. */
+export interface SemanticEntry {
+    id: string;
+    embedding: number[];
+    metadata: {
+        type: 'episode' | 'reflection';
+        sourceEntity?: string;
+        timestamp: number;
+        importance?: number;
+        /** Episode type tag (e.g. 'chat_message', 'attack', 'gift'). */
+        episodeType?: string;
+    };
+}
+/** Query for semantic similarity search. */
+export interface SemanticQuery {
+    embedding: number[];
+    /** Number of results to return. Default: 5. */
+    topK?: number;
+    filter?: {
+        type?: 'episode' | 'reflection';
+        sourceEntity?: string;
+        minImportance?: number;
+        /** Filter by episode type tag. */
+        episodeType?: string;
+    };
+}
+/** Result from semantic similarity search. */
+export interface SemanticResult {
+    id: string;
+    score: number;
+    metadata: SemanticEntry['metadata'];
+}
+/**
+ * EmbeddingAdapter — generates vector embeddings from text.
+ *
+ * Required when using SemanticAdapter. Consumer provides their own
+ * embedding model (OpenAI, Cohere, local, etc.).
+ */
+export interface EmbeddingAdapter {
+    /** Generate an embedding vector from text. */
+    embed(text: string): Promise<number[]>;
+    /** Dimensionality of the embedding vectors. */
+    readonly dimension: number;
+}
+/**
+ * MemoryConfig — split-adapter configuration for the SDK memory system.
+ *
+ * At minimum, provide an `episodes` adapter. Optionally add `semantic`
+ * + `embedding` for similarity-based recall.
+ *
+ * For simpler setup, pass a single `MemoryAdapter` instead of `MemoryConfig`.
+ */
+export interface MemoryConfig {
+    /** Required: structured episode storage (RDB-backed). */
+    episodes: EpisodeAdapter;
+    /** Optional: vector similarity search. Requires `embedding` to be set. */
+    semantic?: SemanticAdapter;
+    /** Optional: embedding adapter. Required when `semantic` is set. */
+    embedding?: EmbeddingAdapter;
+    /** Optional: recall tuning parameters. */
+    recall?: RecallLimits;
+}
+export interface Reflection {
+    id: string;
+    timestamp: number;
+    sourceEntity?: string;
+    content: string;
+    trigger: string;
+    emotionSnapshot: VAD;
+}
+/** @deprecated Use EpisodeAdapter */
+export type EpisodeStore = EpisodeAdapter;
+/** @deprecated Use SemanticAdapter */
+export type SemanticStore = SemanticAdapter;
+/** @deprecated Use EmbeddingAdapter */
+export type EmbeddingProvider = EmbeddingAdapter;
+export interface EpisodePatch {
+    importance?: number;
+    intensity?: number;
+    emotionSnapshot?: VAD;
+}
+export interface CountQuery {
+    sourceEntity?: string;
+    context?: string;
+    timeRange?: [number, number];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/memory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/memory/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory/types.js

@@ -0,0 +1,9 @@
+/**
+ * Type guard: returns true if the memory config is a `MemoryConfig` (split adapters),
+ * false if it's a `MemoryAdapter` (single adapter).
+ *
+ * Discriminates by checking for `saveEpisode` — present on MemoryAdapter, absent on MemoryConfig.
+ */
+export function isMemoryConfig(m) {
+    return !('saveEpisode' in m);
+}

package/dist/esm/persona.d.ts

@@ -0,0 +1,326 @@
+import type { LLMAdapter } from './llm/adapter';
+import type { Message } from './llm/adapter';
+import { type LLMInput } from './llm/resolve';
+import type { MemoryConfig, MemoryAdapter, RecallLimits } from './memory/types';
+import type { EventAdapter } from './events/types';
+import type { AgentResponse, AppraisalVector, InterlocutorContext, PersonaSnapshot, PersonaConfigData, PerceiveOptions } from './types';
+/** Configuration for connecting to a standalone persona instance. */
+export interface MolrooPersonaConfig {
+    /** Base URL of the molroo API (e.g., 'https://api.molroo.io'). */
+    baseUrl: string;
+    /** API key for authentication. */
+    apiKey: string;
+    /** Persona instance ID. Set automatically by {@link MolrooPersona.create}. */
+    personaId?: string;
+    /**
+     * Memory configuration.
+     *
+     * Pass a single `MemoryAdapter` for the simplest setup:
+     * ```typescript
+     * memory: new SqliteMemoryAdapter({ dbPath: './memory.db' })
+     * ```
+     *
+     * Or pass a `MemoryConfig` for split-adapter setup:
+     * ```typescript
+     * memory: { episodes: adapter, semantic: vectorStore, embedding: embeddingProvider }
+     * ```
+     */
+    memory?: MemoryAdapter | MemoryConfig;
+    /**
+     * Recall limits when using a single MemoryAdapter.
+     * Ignored when memory is a MemoryConfig (use `memory.recall` instead).
+     */
+    recall?: RecallLimits;
+    /**
+     * Event adapter for emitting persona-scoped events (emotion_changed,
+     * memory_consolidated, reflection_generated, etc.).
+     */
+    events?: EventAdapter;
+}
+/** Summary of a persona instance, returned by list operations. */
+export interface PersonaSummary {
+    id: string;
+    tenantId: string;
+    config: PersonaConfigData;
+    engineVersion: string;
+    createdAt: number;
+}
+/** Current emotional and psychological state of a persona. */
+export interface PersonaState {
+    /** Current emotion in VAD (Valence-Arousal-Dominance) space with discrete label. */
+    emotion: {
+        vad: {
+            V: number;
+            A: number;
+            D: number;
+        };
+        discrete?: {
+            primary: string;
+            secondary?: string;
+            intensity: number;
+        };
+    };
+    /** Background mood (slower-changing than emotion). */
+    mood?: {
+        vad: {
+            V: number;
+            A: number;
+            D: number;
+        };
+    };
+    /** Active somatic (body) sensations. */
+    somatic?: string[];
+    /** Narrative self-perception (tone, agency, coherence). */
+    narrative?: {
+        tone: number;
+        agency: number;
+        coherence: number;
+    };
+}
+/** Result of a persona chat interaction, including LLM text and emotion data. */
+export interface PersonaChatResult {
+    /** LLM-generated response text. */
+    text: string;
+    /** Emotion engine response with VAD, discrete emotion, and side effects. */
+    response: AgentResponse;
+    /** Persona state at the time of interaction (if available). */
+    state?: PersonaState;
+}
+/**
+ * SDK client for interacting with a standalone molroo persona instance.
+ *
+ * @example
+ * ```typescript
+ * // Single adapter (recommended)
+ * const persona = await MolrooPersona.create(
+ *   { baseUrl: 'https://api.molroo.io', apiKey: 'key', llm,
+ *     memory: new SqliteMemoryAdapter({ dbPath: './memory.db' }) },
+ *   { identity: { name: 'Sera' }, personality: { O: 0.8, C: 0.6, E: 0.7 } },
+ * );
+ *
+ * // Split adapters (advanced)
+ * const persona = await MolrooPersona.create(
+ *   { baseUrl: 'https://api.molroo.io', apiKey: 'key', llm,
+ *     memory: { episodes: episodeStore, semantic: vectorStore, embedding: embedProvider } },
+ *   { identity: { name: 'Sera' }, personality: { O: 0.8, C: 0.6, E: 0.7 } },
+ * );
+ * ```
+ */
+export declare class MolrooPersona {
+    private client;
+    private llm;
+    private engineLlm;
+    private memoryAdapter;
+    private episodeStore;
+    private semanticStore;
+    private embeddingProvider;
+    private memoryRecallConfig;
+    private events;
+    private _personaId;
+    constructor(config: MolrooPersonaConfig & {
+        llm?: LLMAdapter;
+        engineLlm?: LLMAdapter;
+    });
+    /** Unique identifier for this persona instance. */
+    get id(): string;
+    /** Unique identifier for this persona instance (alias for {@link id}). */
+    get personaId(): string;
+    /**
+     * Create a new persona on the molroo API and return a connected instance.
+     *
+     * @param config - API connection config and optional LLM adapter.
+     *   Accepts a full {@link LLMAdapter} or a shorthand config object:
+     *   ```typescript
+     *   llm: { provider: 'openai', apiKey: '...' }
+     *   ```
+     * @param personaConfig - Persona identity, personality, and goals.
+     * @returns A connected MolrooPersona instance.
+     */
+    static create(config: {
+        baseUrl: string;
+        apiKey: string;
+        llm?: LLMInput;
+        engineLlm?: LLMInput;
+        memory?: MemoryAdapter | MemoryConfig;
+        recall?: RecallLimits;
+        events?: EventAdapter;
+    }, personaConfig: PersonaConfigData): Promise<MolrooPersona>;
+    /**
+     * Connect to an existing persona by ID.
+     *
+     * Verifies the persona exists and fetches its configuration.
+     *
+     * @param config - API connection config and optional LLM adapter.
+     *   Accepts a full {@link LLMAdapter} or a shorthand config object:
+     *   ```typescript
+     *   llm: { provider: 'openai', apiKey: '...' }
+     *   ```
+     * @param personaId - The ID of the persona to connect to.
+     * @returns A connected MolrooPersona instance.
+     */
+    static connect(config: {
+        baseUrl: string;
+        apiKey: string;
+        llm?: LLMInput;
+        engineLlm?: LLMInput;
+        memory?: MemoryAdapter | MemoryConfig;
+        recall?: RecallLimits;
+        events?: EventAdapter;
+    }, personaId: string): Promise<MolrooPersona>;
+    /**
+     * List all personas for the authenticated tenant.
+     *
+     * @param config - API connection config (baseUrl + apiKey).
+     * @returns List of persona summaries with optional pagination cursor.
+     */
+    static listPersonas(config: {
+        baseUrl: string;
+        apiKey: string;
+    }): Promise<{
+        personas: PersonaSummary[];
+        nextCursor?: string;
+    }>;
+    /**
+     * Send a message to the persona and get an emotion-processed response.
+     *
+     * Internally converts the SDK-friendly options into the API wire format
+     * (`{ event: PerceiveEvent, context?: PerceiveContext }`).
+     */
+    perceive(message: string, options?: PerceiveOptions): Promise<AgentResponse>;
+    /**
+     * Fire a non-chat event and process through the emotion engine.
+     *
+     * Unlike chat(), this does not involve LLM generation — it directly
+     * sends an event to the perceive endpoint with a required appraisal vector.
+     * The resulting episode is saved to memory and can be recalled during chat().
+     *
+     * @param type - Event type identifier (e.g. 'attack', 'gift', 'rest').
+     * @param description - Human-readable event description (used as message context).
+     * @param options - Must include `appraisal`. Optionally `from`, `stimulus`, `payload`.
+     * @returns Emotion engine response.
+     *
+     * @example
+     * ```typescript
+     * await persona.event('attack', 'goblin attacks with sword', {
+     *   from: 'goblin',
+     *   appraisal: {
+     *     goal_relevance: 0.8,
+     *     goal_congruence: -0.9,
+     *     expectedness: 0.3,
+     *     controllability: 0.4,
+     *     agency: -0.6,
+     *     norm_compatibility: -0.5,
+     *   },
+     * });
+     * ```
+     */
+    event(type: string, description: string, options: Omit<PerceiveOptions, 'type'> & {
+        appraisal: AppraisalVector;
+    }): Promise<AgentResponse>;
+    /**
+     * High-level chat: getState → LLM generate → perceive with appraisal.
+     *
+     * 1. Calls `getPromptContext()` for the server-assembled system prompt
+     * 2. Recalls episodic + semantic memories from client-side stores
+     * 3. Sends to LLM adapter for text generation + appraisal
+     * 4. Sends the appraisal to the API via `perceive()` for emotion computation
+     * 5. Runs post-chat pipeline (episode save, reflection, events)
+     *
+     * Requires {@link LLMAdapter}. Without one, use {@link perceive} directly
+     * for emotion-only interaction.
+     */
+    chat(message: string, options?: {
+        /** Source entity — a name string or structured {@link InterlocutorContext} with description/extensions injected into the system prompt. Default: `'user'`. */
+        from?: string | InterlocutorContext;
+        history?: Message[];
+        consumerSuffix?: string;
+        /** Optional callback invoked when the LLM requests a tool call during generation. */
+        onToolCall?: (call: {
+            name: string;
+            args: Record<string, unknown>;
+            result: unknown;
+        }) => void;
+    }): Promise<PersonaChatResult>;
+    /**
+     * Advance persona time by the specified number of seconds.
+     *
+     * @param seconds - Number of seconds to advance.
+     * @returns Any pending events that were processed.
+     */
+    tick(seconds: number): Promise<{
+        pendingEvents?: unknown[];
+    }>;
+    /**
+     * Directly set the persona's emotion state in VAD space.
+     *
+     * @param vad - Partial VAD values to set (V: -1..1, A: 0..1, D: -1..1).
+     */
+    setEmotion(vad: Partial<{
+        V: number;
+        A: number;
+        D: number;
+    }>): Promise<void>;
+    /**
+     * Get the current emotional and psychological state of the persona.
+     *
+     * @returns Current emotion, mood, somatic, and narrative state.
+     */
+    getState(): Promise<PersonaState>;
+    /**
+     * Get a full snapshot of the persona's internal state.
+     *
+     * @returns Complete persona snapshot for backup/restore.
+     */
+    getSnapshot(): Promise<PersonaSnapshot>;
+    /**
+     * Restore the persona's internal state from a snapshot.
+     *
+     * @param snapshot - The snapshot to restore.
+     */
+    putSnapshot(snapshot: PersonaSnapshot): Promise<void>;
+    /**
+     * Patch the persona's configuration (identity, personality, goals).
+     *
+     * @param updates - Configuration updates to apply.
+     */
+    patch(updates: {
+        config?: PersonaConfigData;
+    }): Promise<void>;
+    /** Soft-delete this persona. Can be restored with {@link restore}. */
+    destroy(): Promise<void>;
+    /** Restore a previously soft-deleted persona. */
+    restore(): Promise<void>;
+    /** Whether memory is available (either single adapter or split stores). */
+    private get hasMemory();
+    /**
+     * Lightweight pipeline for perceive()-only interactions (non-chat events).
+     * Saves the episode and emits events, but skips LLM reflection.
+     */
+    private postPerceivePipeline;
+    private postChatPipeline;
+    private handleReflection;
+    private emitResponseEvents;
+    private buildAppraisalHint;
+    private requireLLM;
+    getPromptContext(consumerSuffix?: string, sourceEntity?: string): Promise<{
+        systemPrompt: string;
+        personaPrompt: Record<string, unknown>;
+        tools?: Array<Record<string, unknown>>;
+    }>;
+    /**
+     * Search persona's episodic memory via the API.
+     * Used internally by the tool-use loop.
+     */
+    searchMemory(query: string, options?: {
+        topK?: number;
+        minImportance?: number;
+    }): Promise<Array<Record<string, unknown>>>;
+    /**
+     * LLM generation loop with tool-use support for standalone persona.
+     * Uses LLMResponseWithToolsSchema which allows the LLM to request
+     * memory searches via the search_memory field. Capped at 3 iterations.
+     */
+    private generateWithToolLoop;
+    private buildContextBlock;
+}
+//# sourceMappingURL=persona.d.ts.map

package/dist/esm/persona.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona.d.ts","sourceRoot":"","sources":["../../src/persona.ts"],"names":[],"mappings":"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"}