@space3-npm/cybersoul-client 1.1.0 → 1.1.1

package/README.md

@@ -19,6 +19,8 @@ Cyber-Soul Service transforms static text-based virtual companions into fully re
 
 ## Installation
 
+**Prerequisites:** This SDK uses the native `fetch` API and requires **Node.js 18 or higher** (or a modern browser environment).
+
 You can install the SDK locally or via npm:
 
 ```bash
@@ -34,7 +36,7 @@ import { CyberSoulClient } from '@space3-npm/cybersoul-client';
 
 const client = new CyberSoulClient({
   characterKey: 'YOUR_CHARACTER_KEY_HASH', // Ties requests to your specific Cyber-Soul persona
-  backendUrl: 'http://localhost:3002',     // The Cyber-Soul core service URL
+  backendUrl: 'https://space3.cloud',      // The Cyber-Soul core service URL (e.g., http://localhost:3002 for local dev)
   llmConfig: {
     provider: 'minimax',
     apiKey: 'YOUR_MINIMAX_API_KEY',
@@ -104,4 +106,6 @@ The SDK perfectly mirrors the underlying Cyber-Soul backend capabilities via typ
 - `giftOutfit(descriptionText)`: Provisions a new explicit outfit descriptor to the character's backend inventory.
 - `bootstrapCharacter(workspaceFiles)`: Automates character profile and prompt setup directly from local markdown configuration files.
 - `generateDailyScript()`: Cron-job helper instructing the AI scheduling system to compute the next block of dynamic events and plans.
-- `interact(params)`: The primary orchestrated multi-modal dialogue endpoint processing standard human <-> agent chat requests.
+- `interact(params)`: The primary orchestrated multi-modal dialogue endpoint processing standard human <-> agent chat requests.
+- `ondemandEvent(params)`: Evaluates and triggers an on-demand event, using the LLM to intelligently decide if the character accepts the event and whether an outfit change is appropriate.
+- `consolidateCoreMemory(input)`: Uses edge LLM logic to merge recent events with the character's core memory and synchronizes the updated memory to the remote database.

package/dist/client.d.ts

@@ -1,7 +1,9 @@
-import { CyberSoulClientConfig, InteractParams, DispatcherIntent, InteractResponse, CharacterState, CoreMemory } from "./types.js";
+import { CyberSoulClientConfig, InteractParams, OndemandEventParams, OndemandEventResponse, DispatcherIntent, InteractResponse, CharacterState, CoreMemory } from "./types.js";
 export declare class CyberSoulClient {
     private config;
     private llm;
+    private cachedWardrobeStr;
+    private cachedWardrobeTime;
     constructor(config: CyberSoulClientConfig);
     /**
      * Internal wrapper for fetch that automatically injects the backend URL and Character Auth token.
@@ -27,6 +29,10 @@ export declare class CyberSoulClient {
      * If the payload is already the inner args object (no voiceArgs wrapper), uses it as-is.
      */
     private extractVoiceArgsFromLlmResponse;
+    /**
+     * Evaluates and triggers an on-demand event, intelligently deciding if an outfit change is needed.
+     */
+    ondemandEvent(params: OndemandEventParams): Promise<OndemandEventResponse>;
     /**
      * Fetches the current dynamic context and daily state.
      */
@@ -68,6 +74,7 @@ export declare class CyberSoulClient {
      */
     generateDailyScript(): Promise<void>;
     private fetchRemoteState;
+    private getWardrobePromptStr;
     private _updateDynamicContextInternal;
     private generatePrimitive;
     private normalizeRequestTypes;

package/dist/client.js

@@ -4,6 +4,8 @@ import { MinimaxProvider } from "./providers/minimax.provider.js";
 export class CyberSoulClient {
     config;
     llm;
+    cachedWardrobeStr = null;
+    cachedWardrobeTime = 0;
     constructor(config) {
         this.config = config;
         // Setup Provider
@@ -61,7 +63,7 @@ EMOTIONAL INERTIA RULES:
     getImageSchemaParams() {
         return `"imageParams": {
     "mode": "structured | full-prompt (use 'full-prompt' for highly dynamic actions)",
-    "full_prompt": "Use only if mode is full-prompt. Highly detailed visual description in ENGLISH.",
+    "full_prompt": "Use only if mode is full-prompt. Highly detailed visual description in ENGLISH. MUST align with the character's current Active Wardrobe unless the context/exposure explicitly demands otherwise (e.g., naked for intimate scenes).",
     "expression": "seductive | cute | happy | sleepy | dazed | pleased | default (Strictly choose ONE from this exact list. DO NOT invent new words like 'shy'.)",
     "condition": "normal | sweaty | wet | messy | oily (Strictly choose ONE from this exact list.)",
     "view_angle": "front | side | high_angle | from_below | boyfriend_view | selfie | mirror (Strictly choose ONE from this exact list.)",
@@ -122,6 +124,95 @@ EMOTIONAL INERTIA RULES:
         }
         return payload;
     }
+    /**
+     * Evaluates and triggers an on-demand event, intelligently deciding if an outfit change is needed.
+     */
+    async ondemandEvent(params) {
+        try {
+            // 1. Fetch current state and wardrobe items
+            const [state, availableOutfits] = await Promise.all([
+                this.fetchRemoteState(),
+                this.getWardrobePromptStr()
+            ]);
+            // 2. Build local Prompt
+            const systemPrompt = `${this.buildStateContextPrompt(state, params.interactParams?.localContext)}
+
+The user proposes a new event for you to participate in: "${params.eventDescription}".
+Evaluate this based on your current state and relationship stage.
+Decide if you will accept the event, and whether it requires changing your outfit.
+
+Available Wardrobe Outfits:
+${availableOutfits || "None available"}
+
+You MUST output ONLY a valid JSON object matching this exact structure:
+{
+  "acceptEvent": true,
+  "reason": "string (Why you accepted or declined, speaking in character)",
+  "requiresOutfitChange": false,
+  "selectedOutfitId": null
+}
+
+Example Valid Answer:
+{
+  "acceptEvent": true,
+  "reason": "Sure, I'd love to go to the cafe. It sounds relaxing.",
+  "requiresOutfitChange": false,
+  "selectedOutfitId": null
+}
+
+CRITICAL: Output MUST be ONLY valid JSON with no markdown block wrappers. Do NOT wrap the JSON in \`\`\`json or add conversational text.`;
+            const promptMessages = [
+                { role: "system", content: systemPrompt },
+                ...(params.interactParams?.history || []).map((msg) => ({
+                    role: msg.role,
+                    content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
+                })),
+                {
+                    role: "user",
+                    content: `${params.interactParams?.userMessage || `Event Proposal: ${params.eventDescription}`}\n\n**CRITICAL REMINDER**: You MUST output your final response exactly in the JSON format specified in the system prompt. DO NOT output plain text directly.`,
+                },
+            ];
+            // 3. Evaluate with LLM
+            const rawLlmResponse = await this.llm.generate(promptMessages, 800, 0.5);
+            // console.debug("[CyberSoulClient ondemandEvent] Raw LLM Response:", rawLlmResponse);
+            let decisionData = {};
+            try {
+                decisionData = robustJsonParse(rawLlmResponse, "OndemandEvent fallback");
+            }
+            catch (e) {
+                throw new Error(`Failed to parse LLM decision for ondemandEvent. Raw response: ${rawLlmResponse}`);
+            }
+            // 4. API call if accepted
+            if (decisionData.acceptEvent === true) {
+                const payload = {
+                    eventDescription: params.eventDescription,
+                    durationMins: params.durationMins || 60,
+                    outfitId: decisionData.requiresOutfitChange ? decisionData.selectedOutfitId : undefined,
+                };
+                const backendRes = await this.apiFetch("/api/v1/cyber-soul/characters/ondemand-event", {
+                    method: "POST",
+                    body: JSON.stringify(payload),
+                });
+                if (!backendRes.ok) {
+                    throw new Error("Backend failed to schedule the on-demand event");
+                }
+            }
+            return {
+                status: "success",
+                acceptEvent: decisionData.acceptEvent,
+                reason: decisionData.reason,
+                requiresOutfitChange: decisionData.requiresOutfitChange,
+                selectedOutfitId: decisionData.selectedOutfitId,
+            };
+        }
+        catch (error) {
+            console.error("[CyberSoulClient] ondemandEvent Error: ", error);
+            return {
+                status: "error",
+                error: error.message,
+            };
+        }
+    }
     /**
      * Fetches the current dynamic context and daily state.
      */
@@ -156,7 +247,7 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
             },
         ];
         const llmRes = await this.llm.generate(promptMessages, 800, 0.4);
-        console.log("[CyberSoulClient ImageGen] Raw LLM Response:", llmRes);
+        // console.debug("[CyberSoulClient ImageGen] Raw LLM Response:", llmRes);
         try {
             const parsedImageArgs = robustJsonParse(llmRes, "generateImage args fallback");
             imageParams = parsedImageArgs.imageParams || parsedImageArgs;
@@ -191,7 +282,7 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
             },
         ];
         const llmRes = await this.llm.generate(promptMessages, 800, 0.3);
-        console.log("[CyberSoulClient VoiceGen] Raw LLM Response:", llmRes);
+        // console.debug("[CyberSoulClient VoiceGen] Raw LLM Response:", llmRes);
         try {
             const parsedVoicePayload = robustJsonParse(llmRes, "generateVoice args fallback");
             dynamicArgs = this.extractVoiceArgsFromLlmResponse(parsedVoicePayload);
@@ -248,6 +339,33 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
         const json = await res.json();
         return json.data;
     }
+    async getWardrobePromptStr() {
+        const now = Date.now();
+        if (this.cachedWardrobeStr && (now - this.cachedWardrobeTime <= 5 * 60 * 1000)) {
+            return this.cachedWardrobeStr;
+        }
+        let availableOutfits = "None available";
+        try {
+            const wardrobeRes = await this.apiFetch("/api/v1/cyber-soul/wardrobe");
+            if (wardrobeRes.ok) {
+                let wardrobesPayload = {};
+                try {
+                    wardrobesPayload = await wardrobeRes.json();
+                }
+                catch (e) { }
+                const wardrobes = wardrobesPayload.data || [];
+                if (wardrobes.length > 0) {
+                    availableOutfits = wardrobes
+                        .map((w) => `- ID: ${w.id} | Name: ${w.itemName} | Category: ${w.category}`)
+                        .join("\n");
+                }
+            }
+        }
+        catch (e) { }
+        this.cachedWardrobeStr = availableOutfits;
+        this.cachedWardrobeTime = now;
+        return availableOutfits;
+    }
     async _updateDynamicContextInternal(stateUpdate) {
         if (!stateUpdate)
             return;
@@ -267,8 +385,17 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
             method: "POST",
             body: JSON.stringify(payload),
         });
-        if (!res.ok)
-            throw new Error(`Failed to generate ${type}`);
+        if (!res.ok) {
+            let errData;
+            try {
+                errData = await res.json();
+            }
+            catch (e) { }
+            const msg = errData?.message || errData?.error || `Status ${res.status}`;
+            const err = new Error(`Failed to generate ${type}: ${msg}`);
+            err.code = errData?.code || "UNKNOWN_ERROR";
+            throw err;
+        }
         return res.json();
     }
     normalizeRequestTypes(requestTypes) {
@@ -284,13 +411,19 @@ Output strictly valid JSON ONLY. No markdown, no conversational filler. Return e
     }
     async interact(params) {
         try {
-            // 1. Sync remote context
-            const state = await this.fetchRemoteState();
+            // 1. Sync remote context and wardrobe (for event triggering)
+            //    We cache the wardrobe payload for 5 minutes to avoid huge payloads on every chat turn
+            const [state, availableOutfits] = await Promise.all([
+                this.fetchRemoteState(),
+                this.getWardrobePromptStr()
+            ]);
             // 2. Build local Prompt
             const types = this.normalizeRequestTypes(params.requestTypes);
             const isAuto = types.includes(InteractRequestType.AUTO);
             // Combine state info into a clean descriptive context
             const systemPrompt = `${this.buildStateContextPrompt(state, params.localContext)}
+Available Wardrobe Outfits (For event triggers):
+${availableOutfits}
 
 The user has sent a message. You must evaluate the context and the user's message, and return a JSON object (no markdown formatting) that dictates the character's multi-modal response.
 
@@ -298,7 +431,8 @@ ${isAuto
                 ? `Analyze the user's message to determine the appropriate response modalities (text, image, voice).
   - Always include 'textResponse'.
   - If the user explicitly asks to see a photo, look at you, or describing an action that warrants a photo, include 'imageParams'.
-  - If the user wants to hear you, or if appropriate for a voice message, include 'voiceArgs'.`
+  - If the user wants to hear you, or if appropriate for a voice message, include 'voiceArgs'.
+  - If the user proposes a new activity or hangout (e.g., "let's go to the cafe", "do you want to watch a movie?"), include 'triggerEvent' to schedule it.`
                 : `Requested types to fulfill: ${types.join(", ")}`}
 If the user's message shifts the emotional mood, establishes new nicknames, or warrants a relationship temperature change, you MUST include a 'stateUpdate' block. Temperature goes from 0 (cold/angry) to 100 (obsessively in love).
 Voice direction for voiceArgs: ${this.getVoiceDirectorInstruction(state)}
@@ -307,10 +441,11 @@ Output JSON Schema:
 {
   "textResponse": "The direct spoken dialogue in Chinese",
   "stateUpdate": { "temperatureDelta": "+1 to -1", "userNickname": "What you now call the user", "agentNickname": "What the user calls you", "talkingStyle": "Current mood/style of talking" },
+  "triggerEvent": { "eventDescription": "Going to a cafe", "durationMins": 60, "outfitId": "optional wardrobe ID to change into if appropriate" },
   ${this.getImageSchemaParams()},
   ${this.getVoiceSchemaFromState(state)}
 }
-Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their values to null instead of omitting the keys completely (e.g., "imageParams": null). Output MUST be ONLY valid JSON with no markdown block wrappers. CRITICAL: Ensure your JSON has exactly one root object \`{\` and ends with exactly one \`}\` without any trailing garbage or extra brackets.`;
+Note: If "imageParams", "voiceArgs", "stateUpdate", or "triggerEvent" are not needed, set their values to null instead of omitting the keys completely (e.g., "imageParams": null). Output MUST be ONLY valid JSON with no markdown block wrappers. CRITICAL: Ensure your JSON has exactly one root object \`{\` and ends with exactly one \`}\` without any trailing garbage or extra brackets.`;
             const promptMessages = [
                 { role: "system", content: systemPrompt },
                 ...(params.history || []),
@@ -322,7 +457,7 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
             ];
             // 3. Local Execute LLM
             const rawLlmResponse = await this.llm.generate(promptMessages, 1500, 0.7);
-            console.log("[CyberSoulClient] Raw LLM Response:", rawLlmResponse);
+            // console.debug("[CyberSoulClient] Raw LLM Response:", rawLlmResponse);
             let parsedIntent;
             try {
                 parsedIntent = robustJsonParse(rawLlmResponse, "Dispatcher fallback");
@@ -334,7 +469,7 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
                     textResponse: rawLlmResponse.replace(/^[\`\s]+|[\`\s]+$/g, "").trim(),
                 };
             }
-            console.log("[CyberSoulClient] Parsed Intent:", parsedIntent);
+            // console.debug("[CyberSoulClient] Parsed Intent:", parsedIntent);
             // 4. Update Backend State async
             if (parsedIntent && parsedIntent.stateUpdate) {
                 this._updateDynamicContextInternal(parsedIntent.stateUpdate);
@@ -348,6 +483,17 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
             let finalImageUrl = undefined;
             let finalAudioUrl = undefined;
             let finalDurationSec = undefined;
+            // Output Event Trigger
+            if (isAuto && parsedIntent.triggerEvent) {
+                mediaTasks.push(this.apiFetch("/api/v1/cyber-soul/characters/ondemand-event", {
+                    method: "POST",
+                    body: JSON.stringify({
+                        eventDescription: parsedIntent.triggerEvent.eventDescription,
+                        durationMins: parsedIntent.triggerEvent.durationMins || 60,
+                        outfitId: parsedIntent.triggerEvent.outfitId || undefined,
+                    }),
+                }).catch(e => console.error("[CyberSoulClient] Auto-triggered ondemandEvent failed:", e)));
+            }
             const shouldGenerateImage = types.includes(InteractRequestType.IMAGE) ||
                 (isAuto && !!parsedIntent.imageParams);
             if (shouldGenerateImage) {
@@ -377,6 +523,7 @@ Note: If "imageParams", "voiceArgs", or "stateUpdate" are not needed, set their
                 imageUrl: finalImageUrl,
                 audioUrl: finalAudioUrl,
                 durationSec: finalDurationSec,
+                triggeredEvent: parsedIntent.triggerEvent || undefined,
             };
         }
         catch (error) {

package/dist/providers/minimax.provider.js

@@ -28,7 +28,7 @@ export class MinimaxProvider {
             throw new Error(`MiniMax API returned status: ${response.status}`);
         }
         const data = await response.json();
-        console.log("[MinimaxProvider] API Response Payload:", data);
+        // console.debug("[MinimaxProvider] API Response Payload:", data);
         if (data?.base_resp?.status_code && data.base_resp.status_code !== 0) {
             throw new Error(`MiniMax SDK Error [${data.base_resp.status_code}]: ${data.base_resp.status_msg}`);
         }

package/dist/types.d.ts

@@ -24,12 +24,36 @@ export interface InteractParams {
     }[];
     onTextReady?: (textResponse: string) => void;
 }
+export interface OndemandEventParams {
+    eventDescription: string;
+    durationMins?: number;
+    interactParams?: InteractParams;
+}
+export interface OndemandEventResponse {
+    status: 'success' | 'error';
+    acceptEvent?: boolean;
+    reason?: string;
+    requiresOutfitChange?: boolean;
+    selectedOutfitId?: string;
+    error?: string;
+}
+export interface WardrobeItem {
+    id: string;
+    itemName: string;
+    category: string;
+    promptModifier: string;
+}
 export interface InteractResponse {
     status: 'success' | 'error';
     textResponse: string;
     imageUrl?: string;
     audioUrl?: string;
     durationSec?: number;
+    triggeredEvent?: {
+        eventDescription: string;
+        durationMins?: number;
+        outfitId?: string | null;
+    };
     error?: string;
 }
 export interface DispatcherIntent {
@@ -42,6 +66,11 @@ export interface DispatcherIntent {
         agentNickname?: string;
         talkingStyle?: string;
     };
+    triggerEvent?: {
+        eventDescription: string;
+        durationMins?: number;
+        outfitId?: string | null;
+    } | null;
 }
 export interface CoreMemory {
     relationshipStatus: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@space3-npm/cybersoul-client",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -28,6 +28,9 @@
   "author": "Space3 Digital Media Tech Studio",
   "license": "MIT",
   "description": "Cyber-Soul multimodal character interaction SDK by Space3 Digital Media Tech Studio",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "ts-node": "^10.9.2",