@molroo-io/sdk 0.5.2

package/dist/esm/world/village.js

@@ -0,0 +1,274 @@
+// INFO: @F001 Domain class wrapping village API — see plan step 3
+import { unwrap } from './client';
+import { WorldPersona } from './world-persona';
+// ---------------------------------------------------------------------------
+// Internal helpers (not exported)
+// ---------------------------------------------------------------------------
+function toApiAppraisal(v) {
+    return {
+        goal_relevance: v.goalRelevance,
+        goal_congruence: v.goalCongruence,
+        expectedness: v.expectedness,
+        controllability: v.controllability,
+        agency: v.agency,
+        norm_compatibility: v.normCompatibility,
+        internal_standards: v.internalStandards,
+        adjustment_potential: v.adjustmentPotential,
+        urgency: v.urgency,
+    };
+}
+function fromApiAppraisal(raw) {
+    return {
+        goalRelevance: raw.goal_relevance,
+        goalCongruence: raw.goal_congruence,
+        expectedness: raw.expectedness,
+        controllability: raw.controllability,
+        agency: raw.agency,
+        normCompatibility: raw.norm_compatibility,
+        internalStandards: raw.internal_standards,
+        adjustmentPotential: raw.adjustment_potential,
+        urgency: raw.urgency,
+    };
+}
+// ---------------------------------------------------------------------------
+// Village class
+// ---------------------------------------------------------------------------
+/**
+ * Represents a village and exposes domain methods for personas, actions,
+ * relationships, interactions, and events.
+ *
+ * Instances are obtained via {@link World.createVillage} or {@link World.getVillage}.
+ */
+export class Village {
+    /** @internal — use World.createVillage / World.getVillage instead. */
+    constructor(client, data) {
+        this._client = client;
+        this._data = { ...data };
+    }
+    // -- Getters --------------------------------------------------------------
+    get id() {
+        return this._data.id;
+    }
+    get name() {
+        return this._data.name;
+    }
+    get description() {
+        return this._data.description;
+    }
+    get accessPolicy() {
+        return this._data.accessPolicy;
+    }
+    get responseRule() {
+        return this._data.responseRule;
+    }
+    /** Returns a readonly snapshot of the village data. */
+    get data() {
+        return this._data;
+    }
+    // -- Village CRUD ---------------------------------------------------------
+    /**
+     * Update village properties. Applies an optimistic local update on success.
+     */
+    async update(options) {
+        await this._client.PATCH('/villages/{id}', {
+            params: { path: { id: this.id } },
+            body: {
+                name: options.name,
+                description: options.description,
+                access_policy: options.accessPolicy,
+                response_rule: options.responseRule,
+            },
+        });
+        // Optimistic local update
+        if (options.name !== undefined)
+            this._data.name = options.name;
+        if (options.description !== undefined)
+            this._data.description = options.description;
+        if (options.accessPolicy !== undefined)
+            this._data.accessPolicy = options.accessPolicy;
+        if (options.responseRule !== undefined)
+            this._data.responseRule = options.responseRule;
+    }
+    /** Soft-delete this village. */
+    async delete() {
+        await this._client.DELETE('/villages/{id}', {
+            params: { path: { id: this.id } },
+        });
+    }
+    async addPersona(input) {
+        let body;
+        // MolrooPersona instance — reference mode
+        if (typeof input.id === 'string' && typeof input.chat === 'function') {
+            const persona = input;
+            body = { persona_id: persona.id };
+        }
+        else {
+            const opts = input;
+            if ('personaId' in opts) {
+                // Reference mode via options
+                body = {
+                    persona_id: opts.personaId,
+                    persona_config_id: opts.configId,
+                    display_name: opts.displayName,
+                };
+            }
+            else {
+                // Inline mode
+                body = {
+                    persona_config_id: opts.configId,
+                    display_name: opts.displayName,
+                    config: opts.config,
+                };
+            }
+        }
+        const { data } = await this._client.POST('/villages/{id}/personas', {
+            params: { path: { id: this.id } },
+            body: body,
+        });
+        const raw = unwrap(data);
+        return {
+            id: raw.id,
+            personaConfigId: raw.persona_config_id,
+            createdAt: raw.created_at,
+        };
+    }
+    /** List all personas in this village. */
+    async listPersonas() {
+        const { data } = await this._client.GET('/villages/{id}/personas', {
+            params: { path: { id: this.id } },
+        });
+        const raw = unwrap(data);
+        return raw.personas ?? [];
+    }
+    /** Get a single persona by ID. */
+    async getPersona(personaId) {
+        const { data } = await this._client.GET('/villages/{id}/personas/{pid}', {
+            params: { path: { id: this.id, pid: personaId } },
+        });
+        return unwrap(data);
+    }
+    /** Remove a persona from this village. */
+    async removePersona(personaId) {
+        await this._client.DELETE('/villages/{id}/personas/{pid}', {
+            params: { path: { id: this.id, pid: personaId } },
+        });
+    }
+    // -- Persona handle -------------------------------------------------------
+    /**
+     * Get a persona handle for LLM-powered interactions.
+     *
+     * The returned {@link WorldPersona} provides Persona-SDK-like DX
+     * (getState, getPromptContext, react) backed by the World API.
+     *
+     * @example
+     * ```typescript
+     * const mina = village.persona('mina', { llm: adapter });
+     * const r = await mina.react('flirt', {
+     *   actor: 'yongjun',
+     *   prompt: '거실에서 용준이 민아에게 윙크했다.',
+     * });
+     * ```
+     */
+    persona(personaId, options) {
+        return new WorldPersona(this._client, this.id, personaId, options);
+    }
+    // -- Actions --------------------------------------------------------------
+    /** Create a custom action in this village. */
+    async createAction(options) {
+        const { data } = await this._client.POST('/villages/{id}/actions', {
+            params: { path: { id: this.id } },
+            body: {
+                name: options.name,
+                description: options.description,
+                appraisal_vector: toApiAppraisal(options.appraisalVector),
+            },
+        });
+        const raw = unwrap(data);
+        return { id: raw.id, name: raw.name };
+    }
+    /** List all actions (defaults + custom) in this village. */
+    async listActions() {
+        const { data } = await this._client.GET('/villages/{id}/actions', {
+            params: { path: { id: this.id } },
+        });
+        const raw = unwrap(data);
+        return (raw.actions ?? []).map((a) => ({
+            name: a.name,
+            description: a.description,
+            appraisalVector: fromApiAppraisal(a.appraisal_vector),
+            isDefault: a.is_default,
+        }));
+    }
+    /** Delete a custom action from this village. */
+    async deleteAction(actionId) {
+        await this._client.DELETE('/villages/{id}/actions/{aid}', {
+            params: { path: { id: this.id, aid: actionId } },
+        });
+    }
+    // -- Relationships --------------------------------------------------------
+    /** Set (upsert) a relationship in this village. */
+    async setRelationship(options) {
+        await this._client.PUT('/villages/{id}/relationships', {
+            params: { path: { id: this.id } },
+            body: {
+                source_type: options.source.type,
+                source_id: options.source.id,
+                target_type: options.target.type,
+                target_id: options.target.id,
+                relationship_type: options.relationshipType,
+                description: options.description,
+                strength: options.strength,
+                trust: options.trust,
+            },
+        });
+    }
+    /** List all relationships in this village. */
+    async listRelationships() {
+        const { data } = await this._client.GET('/villages/{id}/relationships', {
+            params: { path: { id: this.id } },
+        });
+        const raw = unwrap(data);
+        return raw.relationships ?? [];
+    }
+    /** Delete a relationship by ID. */
+    async deleteRelationship(relationshipId) {
+        await this._client.DELETE('/villages/{id}/relationships/{rid}', {
+            params: { path: { id: this.id, rid: relationshipId } },
+        });
+    }
+    // -- Interaction ----------------------------------------------------------
+    /** Execute an interaction in this village. */
+    async interact(options) {
+        const { data } = await this._client.POST('/villages/{id}/interact', {
+            params: { path: { id: this.id } },
+            body: {
+                target_persona_id: options.target,
+                action_name: options.action,
+                action_label: options.actionLabel,
+                stimulus_description: options.stimulusDescription,
+                appraisal_vector: options.appraisal ? toApiAppraisal(options.appraisal) : undefined,
+                actor_id: options.actor,
+                actor_type: options.actorType,
+            },
+        });
+        return unwrap(data);
+    }
+    // -- Events ---------------------------------------------------------------
+    /** Retrieve the event log for this village. */
+    async getEvents(options) {
+        const { data } = await this._client.GET('/villages/{id}/events', {
+            params: {
+                path: { id: this.id },
+                query: {
+                    limit: options?.limit?.toString(),
+                    cursor: options?.cursor,
+                },
+            },
+        });
+        const raw = unwrap(data);
+        return {
+            events: raw.events ?? [],
+            nextCursor: raw.nextCursor ?? null,
+        };
+    }
+}

package/dist/esm/world/world-persona.d.ts

@@ -0,0 +1,182 @@
+/**
+ * WorldPersona — a persona handle within a village.
+ *
+ * "누가 말하는가? 페르소나가 말한다."
+ *
+ * World SDK는 LLM을 모른다. 다만 LLM을 아는 페르소나를 꺼내줄 수 있다.
+ * WorldPersona는 Persona SDK와 동일한 DX(getState, getPromptContext, react)를
+ * 제공하되, 내부적으로 World API 엔드포인트를 사용한다.
+ */
+import { type ApiClient } from './client';
+import type { AppraisalVector } from './types';
+import type { LLMAdapter } from '../llm/adapter';
+export type LLMMessage = {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+};
+/**
+ * @deprecated Use LLMAdapter instead
+ */
+export type WorldLLM = LLMAdapter;
+export interface PersonaEmotion {
+    vad: {
+        V: number;
+        A: number;
+        D: number;
+    };
+    discrete?: {
+        primary: string;
+        secondary?: string;
+        intensity: number;
+    };
+    delta?: {
+        V: number;
+        A: number;
+        D: number;
+    };
+}
+export interface PersonaState {
+    emotion: PersonaEmotion;
+    mood?: {
+        vad: {
+            V: number;
+            A: number;
+            D: number;
+        };
+    };
+    somatic?: string[];
+}
+export interface PromptContext {
+    systemPrompt: string;
+    promptContext: Record<string, string>;
+}
+export interface PersonaDetail {
+    id: string;
+    personaConfigId: string;
+    displayName: string;
+    config: {
+        personality?: Record<string, number>;
+        identity?: {
+            name?: string;
+            role?: string;
+            speakingStyle?: string;
+            description?: string;
+            extensions?: Record<string, string>;
+            [key: string]: unknown;
+        };
+        goals?: unknown[];
+        [key: string]: unknown;
+    };
+    state: PersonaState | null;
+}
+export interface ReactOptions {
+    /** Who is performing the action (e.g. 'yongjun'). */
+    actor?: string;
+    actorType?: 'user' | 'persona';
+    /** User message to send to the LLM after the system prompt. */
+    prompt: string;
+    /** Prior conversation turns for context. */
+    history?: LLMMessage[];
+    /** Zod schema for structured output. Omit for plain text. */
+    schema?: unknown;
+    temperature?: number;
+}
+export interface ReactResult<T = string> {
+    /** Updated emotion state after interaction. */
+    emotion: PersonaEmotion;
+    mood?: {
+        vad: {
+            V: number;
+            A: number;
+            D: number;
+        };
+    };
+    somatic?: string[];
+    /** LLM-generated narrative — typed T if schema provided, string otherwise. */
+    narrative: T;
+}
+export interface WorldPersonaOptions {
+    llm?: LLMAdapter;
+}
+export declare class WorldPersona {
+    private readonly _client;
+    private readonly _villageId;
+    private readonly _personaId;
+    private readonly _llm?;
+    /** Cached persona detail (config + state). Invalidated on interact(). */
+    private _detailCache;
+    /** @internal — use Village.persona() instead. */
+    constructor(client: ApiClient, villageId: string, personaId: string, options?: WorldPersonaOptions);
+    get id(): string;
+    /** Fetch full persona detail (config + state). Cached per-instance. */
+    getDetail(): Promise<PersonaDetail>;
+    /** Get current emotion/mood/somatic state. */
+    getState(): Promise<PersonaState>;
+    /** Get speaking style from persona config (identity.speakingStyle). */
+    getSpeakingStyle(): Promise<string | undefined>;
+    /** Get LLM system prompt assembled from all persona subsystems + world context. */
+    getPromptContext(sourceEntity?: string): Promise<PromptContext>;
+    /**
+     * Send a predefined action to this persona's emotion engine.
+     * Invalidates cached state.
+     */
+    interact(action: string, options?: {
+        actor?: string;
+        actorType?: 'user' | 'persona';
+        appraisal?: AppraisalVector;
+        stimulusDescription?: string;
+    }): Promise<{
+        emotion: PersonaEmotion;
+        mood?: {
+            vad: {
+                V: number;
+                A: number;
+                D: number;
+            };
+        };
+        somatic?: string[];
+    }>;
+    /**
+     * Advance persona simulation time by the specified number of seconds.
+     * Triggers idle decay (emotion → baseline), body budget recovery,
+     * SDT need regression, and TMT timeline advancement.
+     *
+     * @param seconds - Number of seconds to advance (must be ≥ 1).
+     * @returns Any pending internal events generated by threshold checks.
+     */
+    tick(seconds: number): Promise<{
+        pendingEvents?: unknown[];
+    }>;
+    /**
+     * Combined flow: interact (emotion) → getPromptContext → LLM → narrative.
+     *
+     * This is the World equivalent of Persona SDK's `chat()`.
+     * The persona speaks — the world just provides context.
+     *
+     * @example
+     * ```typescript
+     * const mina = village.persona('mina', { llm: adapter });
+     *
+     * // Plain text reaction
+     * const r1 = await mina.react('flirt', {
+     *   actor: 'yongjun',
+     *   prompt: '거실에서 용준이 민아에게 윙크했다.',
+     * });
+     * console.log(r1.narrative); // string
+     *
+     * // Structured reaction
+     * const r2 = await mina.react('flirt', {
+     *   actor: 'yongjun',
+     *   prompt: '거실에서 용준이 민아에게 윙크했다.',
+     *   schema: z.object({
+     *     action: z.string(),
+     *     dialogue: z.string(),
+     *     innerThought: z.string(),
+     *   }),
+     * });
+     * console.log(r2.narrative.dialogue); // typed
+     * ```
+     */
+    react<T = string>(action: string, options: ReactOptions): Promise<ReactResult<T>>;
+}
+//# sourceMappingURL=world-persona.d.ts.map

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

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

package/dist/esm/world/world-persona.js

@@ -0,0 +1,188 @@
+/**
+ * WorldPersona — a persona handle within a village.
+ *
+ * "누가 말하는가? 페르소나가 말한다."
+ *
+ * World SDK는 LLM을 모른다. 다만 LLM을 아는 페르소나를 꺼내줄 수 있다.
+ * WorldPersona는 Persona SDK와 동일한 DX(getState, getPromptContext, react)를
+ * 제공하되, 내부적으로 World API 엔드포인트를 사용한다.
+ */
+import { unwrap } from './client';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function toApiAppraisal(v) {
+    return {
+        goal_relevance: v.goalRelevance,
+        goal_congruence: v.goalCongruence,
+        expectedness: v.expectedness,
+        controllability: v.controllability,
+        agency: v.agency,
+        norm_compatibility: v.normCompatibility,
+        internal_standards: v.internalStandards,
+        adjustment_potential: v.adjustmentPotential,
+        urgency: v.urgency,
+    };
+}
+export class WorldPersona {
+    /** @internal — use Village.persona() instead. */
+    constructor(client, villageId, personaId, options) {
+        /** Cached persona detail (config + state). Invalidated on interact(). */
+        this._detailCache = null;
+        this._client = client;
+        this._villageId = villageId;
+        this._personaId = personaId;
+        this._llm = options?.llm;
+    }
+    get id() {
+        return this._personaId;
+    }
+    // -- State queries --------------------------------------------------------
+    /** Fetch full persona detail (config + state). Cached per-instance. */
+    async getDetail() {
+        if (this._detailCache)
+            return this._detailCache;
+        const { data } = await this._client.GET('/villages/{id}/personas/{pid}', {
+            params: { path: { id: this._villageId, pid: this._personaId } },
+        });
+        const raw = unwrap(data);
+        const config = typeof raw.config === 'string' ? JSON.parse(raw.config) : raw.config;
+        this._detailCache = {
+            id: raw.id,
+            personaConfigId: raw.persona_config_id,
+            displayName: raw.display_name,
+            config,
+            state: raw.state,
+        };
+        return this._detailCache;
+    }
+    /** Get current emotion/mood/somatic state. */
+    async getState() {
+        const detail = await this.getDetail();
+        return detail.state ?? { emotion: { vad: { V: 0, A: 0.5, D: 0 } } };
+    }
+    /** Get speaking style from persona config (identity.speakingStyle). */
+    async getSpeakingStyle() {
+        const detail = await this.getDetail();
+        return detail.config?.identity?.speakingStyle;
+    }
+    /** Get LLM system prompt assembled from all persona subsystems + world context. */
+    async getPromptContext(sourceEntity) {
+        const { data } = await this._client.POST('/villages/{id}/personas/{pid}/prompt-context', {
+            params: { path: { id: this._villageId, pid: this._personaId } },
+            body: sourceEntity ? { sourceEntity } : {},
+        });
+        return unwrap(data);
+    }
+    // -- Interaction ----------------------------------------------------------
+    /**
+     * Send a predefined action to this persona's emotion engine.
+     * Invalidates cached state.
+     */
+    async interact(action, options) {
+        this._detailCache = null; // invalidate
+        const { data } = await this._client.POST('/villages/{id}/interact', {
+            params: { path: { id: this._villageId } },
+            body: {
+                target_persona_id: this._personaId,
+                action_name: action || undefined,
+                action_label: action || undefined,
+                stimulus_description: options?.stimulusDescription,
+                appraisal_vector: options?.appraisal ? toApiAppraisal(options.appraisal) : undefined,
+                actor_id: options?.actor,
+                actor_type: options?.actorType,
+            },
+        });
+        const raw = unwrap(data);
+        return raw;
+    }
+    // -- Tick -----------------------------------------------------------------
+    /**
+     * Advance persona simulation time by the specified number of seconds.
+     * Triggers idle decay (emotion → baseline), body budget recovery,
+     * SDT need regression, and TMT timeline advancement.
+     *
+     * @param seconds - Number of seconds to advance (must be ≥ 1).
+     * @returns Any pending internal events generated by threshold checks.
+     */
+    async tick(seconds) {
+        this._detailCache = null; // invalidate — state changes after tick
+        const { data } = await this._client.POST('/villages/{id}/personas/{pid}/tick', {
+            params: { path: { id: this._villageId, pid: this._personaId } },
+            body: { seconds },
+        });
+        return unwrap(data);
+    }
+    // -- LLM-powered reaction -------------------------------------------------
+    /**
+     * Combined flow: interact (emotion) → getPromptContext → LLM → narrative.
+     *
+     * This is the World equivalent of Persona SDK's `chat()`.
+     * The persona speaks — the world just provides context.
+     *
+     * @example
+     * ```typescript
+     * const mina = village.persona('mina', { llm: adapter });
+     *
+     * // Plain text reaction
+     * const r1 = await mina.react('flirt', {
+     *   actor: 'yongjun',
+     *   prompt: '거실에서 용준이 민아에게 윙크했다.',
+     * });
+     * console.log(r1.narrative); // string
+     *
+     * // Structured reaction
+     * const r2 = await mina.react('flirt', {
+     *   actor: 'yongjun',
+     *   prompt: '거실에서 용준이 민아에게 윙크했다.',
+     *   schema: z.object({
+     *     action: z.string(),
+     *     dialogue: z.string(),
+     *     innerThought: z.string(),
+     *   }),
+     * });
+     * console.log(r2.narrative.dialogue); // typed
+     * ```
+     */
+    async react(action, options) {
+        if (!this._llm) {
+            throw new Error('WorldPersona.react() requires an LLM adapter. Pass { llm } to village.persona().');
+        }
+        // 1. Interact — emotion engine processes the action
+        const interactResult = await this.interact(action, {
+            actor: options.actor,
+            actorType: options.actorType,
+        });
+        // 2. Get prompt context — now reflects updated emotion
+        const ctx = await this.getPromptContext(options.actor);
+        // 3. LLM generates narrative
+        const messages = [
+            ...(options.history ?? []),
+            { role: 'user', content: options.prompt },
+        ];
+        let narrative;
+        if (options.schema) {
+            const result = await this._llm.generateObject({
+                system: ctx.systemPrompt,
+                messages,
+                schema: options.schema,
+                temperature: options.temperature,
+            });
+            narrative = result.object;
+        }
+        else {
+            const result = await this._llm.generateText({
+                system: ctx.systemPrompt,
+                messages,
+                temperature: options.temperature,
+            });
+            narrative = result.text;
+        }
+        return {
+            emotion: interactResult.emotion,
+            mood: interactResult.mood,
+            somatic: interactResult.somatic,
+            narrative,
+        };
+    }
+}

package/dist/esm/world/world.d.ts

@@ -0,0 +1,41 @@
+import { type ApiClient } from './client';
+import { Village } from './village';
+import type { VillageData, CreateVillageOptions, PaginationOptions } from './types';
+export interface WorldOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+/**
+ * Entry point for the World SDK.
+ *
+ * @example
+ * ```typescript
+ * import { World } from '@molroo-io/sdk';
+ *
+ * const world = new World({ apiKey: 'mk_live_...' });
+ * const village = await world.createVillage({ name: 'My Village' });
+ * const result = await village.interact({ target: 'sera', action: 'greet' });
+ * ```
+ */
+export declare class World {
+    /** @internal — exposed for advanced use only. */
+    readonly _client: ApiClient;
+    constructor(options: WorldOptions);
+    /**
+     * Create a new village and return a {@link Village} instance.
+     */
+    createVillage(options: CreateVillageOptions): Promise<Village>;
+    /**
+     * Fetch an existing village by ID and return a {@link Village} instance.
+     */
+    getVillage(id: string): Promise<Village>;
+    /**
+     * List villages. Returns raw data objects (not Village instances) for
+     * efficiency when only metadata is needed.
+     */
+    listVillages(options?: PaginationOptions): Promise<{
+        villages: VillageData[];
+        nextCursor: string | null;
+    }>;
+}
+//# sourceMappingURL=world.d.ts.map