@space3-npm/cybersoul-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Space3 Digital Media Tech Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# cybersoul-client
+
+`cybersoul-client` is the official TypeScript client SDK for interacting with the Cyber-Soul backend service. It acts as the "Brain" orchestrator on the client side, converting your local text inputs into rich, multi-modal outputs (text, voice, and image) driven by an LLM architecture.
+
+## Overview
+
+Cyber-Soul Service transforms static text-based virtual companions into fully realized, multi-modal emotional personas. The `cybersoul-client` sits between your user-facing application (or OpenClaw agent) and the Cyber-Soul backend infrastructure.
+
+### The Role of the SDK in the Architecture
+
+1. **Context Management & Synchronization**: The client synchronizes the character's remote state (relationship stage, active daily events, current wardrobe) and merges it with local context.
+2. **Local LLM Execution (BYOK)**: It securely utilizes the developer's provided LLM API key (e.g., MiniMax) locally. This keeps the heaviest cognitive lifting decoupled from the core database backend, letting the user control the underlying intelligence layer.
+3. **Intent Parsing**: The LLM evaluates the chat context and returns a structured JSON intent determining what modalities are necessary (e.g., if a user asked for a photo, the LLM sets `imageParams`; if the relationship progressed, it creates a `stateUpdate`).
+4. **Primitive Orchestration**: The SDK orchestrates low-level generation operations in parallel against the Cyber-Soul backend:
+   - Evaluates `stateUpdate` and fires a `PATCH` request to persist emotional inertia remotely.
+   - Generates images via `/api/v1/cyber-soul/image/generate`.
+   - Synthesizes speech via `/api/v1/cyber-soul/voice/generate`.
+5. **Consolidated Delivery**: Once all operations complete, it returns a clean, unified payload ready for UI rendering.
+
+## Installation
+
+You can install the SDK locally or via npm (when published):
+
+```bash
+npm install cybersoul-client
+```
+
+## Quick Start
+
+Initialize the client with your Character Key (provided by your Cyber-Soul Dashboard) and your local LLM configuration:
+
+```typescript
+import { CyberSoulClient } from '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
+  llmConfig: {
+    provider: 'minimax',
+    apiKey: 'YOUR_MINIMAX_API_KEY',
+    model: 'MiniMax-M2.7'
+  }
+});
+
+// Interact with your Cyber-Soul
+const response = await client.interact({
+  userMessage: "Good morning! Can you send me a quick selfie before work?",
+  requestTypes: ['auto'], // Can force 'text', 'image', or 'voice'. 'auto' lets the LLM decide.
+  history: [
+    { role: 'user', content: 'See you tomorrow!' },
+    { role: 'assistant', content: 'Goodnight! Sweet dreams.' }
+  ],
+  onTextReady: (text) => {
+    // Fired immediately as soon as the text intent is parsed from the LLM, 
+    // before waiting for heavy media generations (voice/image) to complete.
+    console.log("Instant text response:", text);
+  }
+});
+
+if (response.status === 'success') {
+  console.log("Final text:", response.textResponse);
+  if (response.imageUrl) console.log("Image attached:", response.imageUrl);
+  if (response.audioUrl) console.log("Audio attached:", response.audioUrl, "Duration:", response.durationSec);
+}
+```
+
+## How It Works Under The Hood
+
+```mermaid
+flowchart TD
+    App[User App / Chatbot] -- "interact(msg)" --> SDK[cybersoul-client SDK]
+    SDK -- "1. Sync Context" --> CSBackend[Cyber-Soul Backend]
+    CSBackend -. "State Profile (Wardrobe, Mood)" .-> SDK
+    SDK -- "2. Build System Prompt & Run LLM" --> LLM[Local LLM / provider]
+    LLM -. "JSON Intent (Text, Media args)" .-> SDK
+    
+    SDK -- "3. Trigger text ready callback" --> App
+    SDK -- "4. Commit state updates" --> CSBackend
+    
+    subgraph ParallelMedia [Parallel Media Generation]
+        SDK -- "5a. Fetch Image Primitive" --> GenImage[Backend: /image/generate]
+        SDK -- "5b. Fetch Audio Primitive" --> GenAudio[Backend: /voice/generate]
+    end
+    
+    GenImage -. "Image URL" .-> SDK
+    GenAudio -. "Audio URL" .-> SDK
+    SDK -- "6. Consolidated Promise resolves" --> App
+```
+
+## Usage in Custom Applications (OpenClaw / Frontend)
+
+When plugging this SDK into an existing bot framework like OpenClaw, you will generally bootstrap the system once with your config files, then call `.interact()` on every new message event. 
+
+Because `interact` acts as an all-in-one state-machine adapter, it isolates multi-modal state tracking—you simply provide the raw user string and the array of recent history, and the SDK takes care of API generation, prompt construction, and relationship temperature updates implicitly.

package/dist/client.d.ts

@@ -0,0 +1,10 @@
+import { CyberSoulClientConfig, InteractParams, InteractResponse } from "./types";
+export declare class CyberSoulClient {
+    private config;
+    private llm;
+    constructor(config: CyberSoulClientConfig);
+    private fetchRemoteState;
+    private updateDynamicContext;
+    private generatePrimitive;
+    interact(params: InteractParams): Promise<InteractResponse>;
+}

package/dist/client.js

@@ -0,0 +1,207 @@
+import { robustJsonParse } from "./utils/json.utils";
+import { MinimaxProvider } from "./providers/minimax.provider";
+export class CyberSoulClient {
+    config;
+    llm;
+    constructor(config) {
+        this.config = config;
+        // Setup Provider
+        if (config.llmConfig.provider === "minimax") {
+            this.llm = new MinimaxProvider(config.llmConfig);
+        }
+        else {
+            throw new Error(`Unsupported LLM provider: ${config.llmConfig.provider}`);
+        }
+    }
+    async fetchRemoteState() {
+        const url = `${this.config.backendUrl}/api/v1/cyber-soul/state`;
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.config.characterKey}` },
+        });
+        if (!res.ok)
+            throw new Error("Failed to fetch character state");
+        const json = await res.json();
+        return json.data;
+    }
+    async updateDynamicContext(stateUpdate) {
+        if (!stateUpdate)
+            return;
+        // Map TS schema intent (temperatureDelta) to match Backend payload schema (temperature)
+        const payload = { ...stateUpdate };
+        if (payload.temperatureDelta !== undefined) {
+            payload.temperature = payload.temperatureDelta;
+            delete payload.temperatureDelta;
+        }
+        const url = `${this.config.backendUrl}/api/v1/cyber-soul/characters/dynamic-context`;
+        await fetch(url, {
+            method: "PATCH",
+            headers: {
+                Authorization: `Bearer ${this.config.characterKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        }).catch((e) => console.error("Failed to update dynamic context", e)); // non-blocking error handler
+    }
+    async generatePrimitive(type, payload) {
+        const url = `${this.config.backendUrl}/api/v1/cyber-soul/${type}/generate`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.config.characterKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!res.ok)
+            throw new Error(`Failed to generate ${type}`);
+        return res.json();
+    }
+    async interact(params) {
+        try {
+            // 1. Sync remote context
+            const state = await this.fetchRemoteState();
+            // 2. Build local Prompt
+            const types = params.requestTypes && params.requestTypes.length > 0 ? params.requestTypes : ["auto"];
+            const isAuto = types.includes("auto");
+            // Combine state info into a clean descriptive context
+            const contextParts = [];
+            if (state.active_event) {
+                contextParts.push(`- Active Event: ${state.active_event.title} (${state.active_event.narrative_context})`);
+            }
+            if (state.next_event) {
+                contextParts.push(`- Next Event: ${state.next_event.title} at ${state.next_event.start_time} (in ${state.next_event.time_until_mins} mins)`);
+            }
+            if (state.active_wardrobe) {
+                contextParts.push(`- Wardrobe: ${state.active_wardrobe.name || state.active_wardrobe.id || "Current"}`);
+            }
+            const dyn = state.dynamic_context || {};
+            const stage = state.relationship_stage || "NEUTRAL";
+            contextParts.push(`- Relationship Info (Stage: ${stage}): You call the user '${dyn.userNickname || "User"}'. The user calls you '${dyn.agentNickname || "Agent"}'. Mood: ${dyn.talkingStyle || "Normal"}. Temp (0-100): ${dyn.temperature || 50}.`);
+            if (params.localContext) {
+                contextParts.push(`- Additional Context: ${params.localContext}`);
+            }
+            const scenarioContext = contextParts.join("\n");
+            const systemPrompt = `You are ${state.name}, acting as a virtual companion.
+  Demographics: Age ${state.age || 'unknown'}, Gender ${state.gender || 'unknown'}, Occupation ${state.occupation || 'unknown'}
+Current time: ${new Date(state.current_time).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" })}
+Current context/schedule: ${scenarioContext}
+Relationship stage: ${state.relationship_stage}
+Personality Traits: ${state.personality_traits || 'None'}
+Interaction Boundaries: ${state.interaction_boundaries || 'None'}
+Communication Style: ${state.communication_style || 'None'}
+
+EMOTIONAL INERTIA RULES:
+1. You must act strictly according to the current Relationship Stage (${state.relationship_stage || 'NEUTRAL'}).
+2. If the user expresses sudden high affection (e.g. "I miss you") but your stage is COLD, you MUST react with skepticism, coldness, or appropriately distanced deflection. Do NOT instantly become warm.
+3. Emotional mood changes must be slow. The 'temperatureDelta' should rarely exceed +/- 5 points per turn.
+
+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.
+
+${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'.`
+                : `Requested types to fulfill: ${(params.requestTypes ?? []).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).
+
+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" },
+  "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.",
+    "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.)",
+    "exposure": "normal | cleavage | see_through | half_naked | naked | intimate (Strictly choose ONE from this exact list.)",
+    "pose": "e.g., sitting on bed, leaning forward (ENGLISH ONLY)",
+    "scene": "e.g., cozy bedroom, morning light (ENGLISH ONLY)",
+    "outfit": "auto | ondemand",
+    "ondemandOutfit": "e.g., silk robe (ENGLISH ONLY)",
+    "style": "e.g., photorealistic (ENGLISH ONLY)"
+  },
+  "voiceArgs": { "style_instruction": "How the line should be spoken (Qwen3 format)", "emotion": "e.g., happy (MiniMax format, MUST BE ENGLISH, no Chinese)" }
+}
+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.`;
+            const promptMessages = [
+                { role: "system", content: systemPrompt },
+                ...(params.history || []),
+                {
+                    role: "user",
+                    content: params.userMessage +
+                        "\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 dialogue directly. For 'imageParams', ALL values MUST be in ENGLISH ONLY without exception, and you MUST use the exact English enum strings provided.",
+                },
+            ];
+            // 3. Local Execute LLM
+            const rawLlmResponse = await this.llm.generate(promptMessages, 1500, 0.7);
+            console.log("[CyberSoulClient] Raw LLM Response:", rawLlmResponse);
+            let parsedIntent;
+            try {
+                parsedIntent = robustJsonParse(rawLlmResponse, "Dispatcher fallback");
+            }
+            catch (e) {
+                console.warn("[CyberSoulClient] JSON parse failed, falling back to raw text:", e);
+                // Fallback robust mode - just text if completely broken
+                parsedIntent = {
+                    textResponse: rawLlmResponse.replace(/^[\`\s]+|[\`\s]+$/g, "").trim(),
+                };
+            }
+            console.log("[CyberSoulClient] Parsed Intent:", parsedIntent);
+            // 4. Update Backend State async
+            if (parsedIntent.stateUpdate) {
+                this.updateDynamicContext(parsedIntent.stateUpdate);
+            }
+            // Fire text ready callback if provided
+            if (params.onTextReady && parsedIntent.textResponse) {
+                params.onTextReady(parsedIntent.textResponse);
+            }
+            // 5. Build Final Media Calls parallel
+            const mediaTasks = [];
+            let finalImageUrl = undefined;
+            let finalAudioUrl = undefined;
+            let finalDurationSec = undefined;
+            const shouldGenerateImage = types.includes("image") || (isAuto && !!parsedIntent.imageParams);
+            if (shouldGenerateImage) {
+                mediaTasks.push(this.generatePrimitive("image", {
+                    ...parsedIntent.imageParams,
+                    ...(params.imageOverrides || {}),
+                }).then((res) => {
+                    finalImageUrl = res.image_url;
+                }));
+            }
+            const shouldGenerateVoice = types.includes("voice") || (isAuto && !!parsedIntent.voiceArgs);
+            if (shouldGenerateVoice) {
+                const dynamicArgs = { ...(parsedIntent.voiceArgs || {}) };
+                if (params.voiceStyleOverride) {
+                    dynamicArgs.style_instruction = params.voiceStyleOverride;
+                }
+                mediaTasks.push(this.generatePrimitive("voice", {
+                    text: parsedIntent.textResponse,
+                    dynamicArgs,
+                }).then((res) => {
+                    finalAudioUrl = res.audio_url;
+                    finalDurationSec = res.duration_sec;
+                }));
+            }
+            // Wait for image/voice gens to return successfully
+            await Promise.all(mediaTasks);
+            return {
+                status: "success",
+                textResponse: parsedIntent.textResponse || "...",
+                imageUrl: finalImageUrl,
+                audioUrl: finalAudioUrl,
+                durationSec: finalDurationSec,
+            };
+        }
+        catch (error) {
+            console.error("[CyberSoulClient] Interface Error: ", error);
+            return {
+                status: "error",
+                textResponse: "System Error...",
+                error: error.message,
+            };
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './client';
+export * from './providers/minimax.provider';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './client';
+export * from './providers/minimax.provider';

package/dist/providers/minimax.provider.d.ts

@@ -0,0 +1,9 @@
+import { LLMConfig, BaseLLMProvider } from '../types';
+export declare class MinimaxProvider implements BaseLLMProvider {
+    private config;
+    constructor(config: LLMConfig);
+    generate(messages: {
+        role: string;
+        content: string;
+    }[], maxTokens?: number, temperature?: number): Promise<string>;
+}

package/dist/providers/minimax.provider.js

@@ -0,0 +1,45 @@
+export class MinimaxProvider {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async generate(messages, maxTokens = 1500, temperature = 0.7) {
+        if (!this.config.apiKey) {
+            throw new Error("Missing MiniMax API Key");
+        }
+        // Ensure we handle correct minimax URL
+        const host = 'https://api.minimaxi.com';
+        const payload = {
+            model: this.config.model || 'MiniMax-M2.7',
+            messages,
+            temperature,
+            max_tokens: maxTokens,
+            tokens_to_generate: maxTokens
+        };
+        const response = await fetch(`${host}/v1/text/chatcompletion_v2`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.config.apiKey}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(payload)
+        });
+        if (!response.ok) {
+            throw new Error(`MiniMax API returned status: ${response.status}`);
+        }
+        const data = await response.json();
+        console.log("[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}`);
+        }
+        const choices = data?.choices || [];
+        if (choices.length > 0) {
+            const msg = choices[0].message;
+            if (!msg || typeof msg.content !== 'string') {
+                throw new Error("Invalid response format from MiniMax API: missing message content.");
+            }
+            return msg.content;
+        }
+        throw new Error("MiniMax API returned no choices.");
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export interface LLMConfig {
+    provider: 'minimax' | 'openai';
+    apiKey: string;
+    model: string;
+}
+export interface CyberSoulClientConfig {
+    characterKey: string;
+    backendUrl: string;
+    llmConfig: LLMConfig;
+}
+export interface InteractParams {
+    userMessage: string;
+    localContext?: string;
+    requestTypes?: string[];
+    history?: {
+        role: string;
+        content: string;
+    }[];
+    imageOverrides?: any;
+    voiceStyleOverride?: string;
+    onTextReady?: (textResponse: string) => void;
+}
+export interface InteractResponse {
+    status: 'success' | 'error';
+    textResponse: string;
+    imageUrl?: string;
+    audioUrl?: string;
+    durationSec?: number;
+    error?: string;
+}
+export interface DispatcherIntent {
+    textResponse?: string;
+    imageParams?: any;
+    voiceArgs?: any;
+    stateUpdate?: {
+        temperatureDelta?: string | number;
+        userNickname?: string;
+        agentNickname?: string;
+        talkingStyle?: string;
+    };
+}
+export interface BaseLLMProvider {
+    generate(messages: {
+        role: string;
+        content: string;
+    }[], maxTokens?: number, temperature?: number): Promise<string>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/json.utils.d.ts

@@ -0,0 +1 @@
+export declare function robustJsonParse<T>(jsonString: string, contextMessage?: string): T;

package/dist/utils/json.utils.js

@@ -0,0 +1,67 @@
+export function robustJsonParse(jsonString, contextMessage = 'throwing original error') {
+    let cleanJson = jsonString.trim();
+    const jsonMatch = cleanJson.match(/```json\n?([\s\S]*?)\n?```/i) || cleanJson.match(/```\n?([\s\S]*?)\n?```/);
+    if (jsonMatch) {
+        cleanJson = jsonMatch[1].trim();
+    }
+    cleanJson = cleanJson.replace(/,(\s*[}\]])/g, '$1');
+    cleanJson = cleanJson.replace(/,\s*$/, '');
+    // Extract the first complete JSON object by brace counting if it looks like there's trailing garbage
+    function extractFirstJsonObject(str) {
+        let braceCount = 0;
+        let startIdx = str.indexOf('{');
+        if (startIdx === -1)
+            return str;
+        let inString = false;
+        let escape = false;
+        for (let i = startIdx; i < str.length; i++) {
+            const char = str[i];
+            if (!escape && char === '"') {
+                inString = !inString;
+            }
+            escape = (char === '\\' && !escape);
+            if (!inString) {
+                if (char === '{')
+                    braceCount++;
+                else if (char === '}') {
+                    braceCount--;
+                    if (braceCount === 0) {
+                        return str.substring(startIdx, i + 1);
+                    }
+                }
+            }
+        }
+        return str;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(cleanJson);
+    }
+    catch (e) {
+        if (e instanceof SyntaxError) {
+            const extracted = extractFirstJsonObject(cleanJson);
+            if (extracted !== cleanJson) {
+                try {
+                    parsed = JSON.parse(extracted);
+                    return parsed;
+                }
+                catch (innerE) {
+                    // ignore and let fallback chain continue
+                }
+            }
+        }
+        try {
+            parsed = JSON.parse(cleanJson + '}');
+        }
+        catch (e2) {
+            try {
+                parsed = JSON.parse(cleanJson + '}}');
+            }
+            catch (e3) {
+                console.warn(`Failed to parse Dispatcher Intent: ${contextMessage}. Falling back to plain text.`);
+                throw e;
+            }
+        }
+    }
+    return parsed;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@space3-npm/cybersoul-client",
+  "version": "1.0.0",
+  "type": "module", "main": "dist/index.js", "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "cybersoul",
+    "sdk",
+    "ai",
+    "multimodal"
+  ],
+  "author": "Space3 Digital Media Tech Studio",
+  "license": "MIT",
+  "description": "Cyber-Soul multimodal character interaction SDK by Space3 Digital Media Tech Studio",
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.2"
+  }
+}