@valuya/bot-channel-core 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valuya
+
+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,12 @@
+# @valuya/bot-channel-core
+
+Shared helpers for gated bot-channel packages.
+
+This package holds the channel-agnostic pieces that both WhatsApp and Telegram
+bot-channel examples need:
+
+- schema-driven soul runtime
+- file-backed soul memory
+- mentor soul helper
+- support soul helper
+- concierge soul helper

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+export type SoulResponseSchema = {
+    format: "json";
+    replyKey: string;
+    followUpQuestionKey?: string;
+    followUpQuestionsKey?: string;
+    nextStepKey?: string;
+    summaryKey?: string;
+    userProfileKey?: string;
+    rootPatternKey?: string;
+};
+export type ChannelSoulDefinition = {
+    id: string;
+    name: string;
+    systemPrompt: string;
+    locale?: string;
+    memoryPolicy?: {
+        keepRecentTurns: number;
+        summarizeAfterTurns: number;
+    };
+    tools?: string[];
+    responseSchema?: SoulResponseSchema;
+};
+export type SoulMemoryTurn = {
+    role: "user" | "assistant";
+    content: string;
+    createdAt: string;
+};
+export type SoulMemory = {
+    recentTurns: SoulMemoryTurn[];
+    summaries: string[];
+    userProfile?: Record<string, unknown>;
+    updatedAt: string;
+};
+export type SoulResponse = {
+    reply: string;
+    memory?: SoulMemory;
+    metadata?: Record<string, unknown>;
+};
+export type StructuredCompletionResult = string | SoulResponse | Record<string, unknown>;
+export type StructuredCompletionRunner = (args: {
+    system: string;
+    user: string;
+    locale?: string;
+    soul: ChannelSoulDefinition;
+    schema?: SoulResponseSchema;
+}) => Promise<StructuredCompletionResult>;
+export type SoulRuntimeLike = {
+    run(args: {
+        soul: ChannelSoulDefinition;
+        message: string;
+        memory: SoulMemory;
+        protocolSubjectHeader: string;
+        locale?: string;
+    }): Promise<SoulResponse>;
+};
+export declare class SchemaDrivenSoulRuntime implements SoulRuntimeLike {
+    private readonly deps;
+    constructor(deps: {
+        runCompletion: StructuredCompletionRunner;
+    });
+    run(args: {
+        soul: ChannelSoulDefinition;
+        message: string;
+        memory: SoulMemory;
+        protocolSubjectHeader: string;
+        locale?: string;
+    }): Promise<SoulResponse>;
+}
+export declare class FileSoulMemoryStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    load(args: {
+        userId?: string;
+        whatsappUserId?: string;
+        telegramUserId?: string;
+        soulId: string;
+    }): Promise<SoulMemory>;
+    save(args: {
+        userId?: string;
+        whatsappUserId?: string;
+        telegramUserId?: string;
+        soulId: string;
+        memory: SoulMemory;
+    }): Promise<void>;
+    private key;
+    private readState;
+}
+export declare function createMentorSoulDefinition(args?: {
+    id?: string;
+    name?: string;
+    locale?: string;
+    systemPrompt?: string;
+}): ChannelSoulDefinition;
+export declare function createSupportSoulDefinition(args?: {
+    id?: string;
+    name?: string;
+    locale?: string;
+    systemPrompt?: string;
+}): ChannelSoulDefinition;
+export declare function createConciergeSoulDefinition(args?: {
+    id?: string;
+    name?: string;
+    locale?: string;
+    systemPrompt?: string;
+}): ChannelSoulDefinition;

package/dist/index.js

@@ -0,0 +1,278 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export class SchemaDrivenSoulRuntime {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run(args) {
+        const schema = args.soul.responseSchema;
+        const result = await this.deps.runCompletion({
+            system: buildSystemPrompt(args.soul, schema, args.locale),
+            user: buildUserPrompt(args.message, args.memory, args.protocolSubjectHeader),
+            locale: args.locale || args.soul.locale,
+            soul: args.soul,
+            schema,
+        });
+        const normalized = normalizeCompletionResult(result, schema);
+        return {
+            reply: normalized.reply,
+            memory: mergeMemory({
+                memory: args.memory,
+                userMessage: args.message,
+                assistantReply: normalized.reply,
+                schema,
+                payload: normalized.payload,
+            }),
+            metadata: normalized.payload || undefined,
+        };
+    }
+}
+export class FileSoulMemoryStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async load(args) {
+        const state = await this.readState();
+        return state[this.key(args)] || emptyMemory();
+    }
+    async save(args) {
+        const state = await this.readState();
+        state[this.key(args)] = args.memory;
+        await mkdir(path.dirname(this.filePath), { recursive: true });
+        await writeFile(this.filePath, JSON.stringify(state, null, 2), "utf8");
+    }
+    key(args) {
+        const userId = readString(args.userId)
+            || readString(args.whatsappUserId)
+            || readString(args.telegramUserId)
+            || "unknown";
+        return `${userId}::${String(args.soulId).trim()}`;
+    }
+    async readState() {
+        try {
+            const raw = await readFile(this.filePath, "utf8");
+            const parsed = JSON.parse(raw);
+            return parsed && typeof parsed === "object" ? parsed : {};
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return {};
+            throw error;
+        }
+    }
+}
+export function createMentorSoulDefinition(args) {
+    return {
+        id: args?.id || "mentor",
+        name: args?.name || "Mentor",
+        locale: args?.locale || "de",
+        systemPrompt: args?.systemPrompt || [
+            "Du bist ein ganzheitlicher Mentor fuer persoenliches Wachstum.",
+            "Du antwortest ruhig, klar, praezise und menschlich.",
+            "Du hilfst dem Nutzer, Muster zu erkennen, die eigentliche Frage zu schaerfen und einen hilfreichen naechsten Schritt zu sehen.",
+            "Du stellst lieber eine gute weiterfuehrende Frage als vorschnell allgemeine Ratschlaege zu geben.",
+            "Du vermeidest Floskeln, Pathos und leere Motivation.",
+            "Deine Antworten sollen sich natuerlich wie ein hilfreicher, aufmerksamer Mentor anfuehlen.",
+        ].join(" "),
+        responseSchema: {
+            format: "json",
+            replyKey: "mentor_reply",
+            followUpQuestionKey: "deep_question",
+            followUpQuestionsKey: "follow_up_questions",
+            nextStepKey: "next_step",
+            summaryKey: "conversation_summary",
+            userProfileKey: "user_profile",
+            rootPatternKey: "root_pattern",
+        },
+    };
+}
+export function createSupportSoulDefinition(args) {
+    return {
+        id: args?.id || "support",
+        name: args?.name || "Support",
+        locale: args?.locale || "de",
+        systemPrompt: args?.systemPrompt || [
+            "Du bist ein ruhiger, klarer Premium-Support-Assistent.",
+            "Du hilfst dem Nutzer, sein Problem strukturiert zu beschreiben, das eigentliche Hindernis zu erkennen und den naechsten sinnvollen Schritt zu sehen.",
+            "Du antwortest freundlich, konkret und ohne Support-Floskeln.",
+            "Wenn etwas unklar ist, stellst du genau eine gute Rueckfrage statt viele auf einmal.",
+            "Du formulierst so, dass sich die Hilfe natuerlich und menschlich anfuehlt.",
+        ].join(" "),
+        responseSchema: {
+            format: "json",
+            replyKey: "support_reply",
+            followUpQuestionKey: "clarifying_question",
+            nextStepKey: "next_step",
+            summaryKey: "case_summary",
+            userProfileKey: "customer_context",
+            rootPatternKey: "issue_pattern",
+        },
+    };
+}
+export function createConciergeSoulDefinition(args) {
+    return {
+        id: args?.id || "concierge",
+        name: args?.name || "Concierge",
+        locale: args?.locale || "de",
+        systemPrompt: args?.systemPrompt || [
+            "Du bist ein persoenlicher Premium-Concierge.",
+            "Du antwortest aufmerksam, diskret, loesungsorientiert und natuerlich.",
+            "Du hilfst dem Nutzer, seinen Wunsch klarer zu machen, passende Optionen zu erkennen und mit wenig Aufwand weiterzukommen.",
+            "Du stellst gezielte Rueckfragen, wenn sie wirklich helfen, und gibst am Ende eine klare Empfehlung oder einen naechsten Schritt.",
+        ].join(" "),
+        responseSchema: {
+            format: "json",
+            replyKey: "concierge_reply",
+            followUpQuestionKey: "clarifying_question",
+            followUpQuestionsKey: "option_questions",
+            nextStepKey: "recommended_next_step",
+            summaryKey: "preference_summary",
+            userProfileKey: "user_preferences",
+            rootPatternKey: "decision_style",
+        },
+    };
+}
+function emptyMemory() {
+    return {
+        recentTurns: [],
+        summaries: [],
+        userProfile: {},
+        updatedAt: new Date(0).toISOString(),
+    };
+}
+function buildSystemPrompt(soul, schema, locale) {
+    if (!schema)
+        return soul.systemPrompt;
+    return [
+        soul.systemPrompt,
+        "",
+        `Antworte in ${locale || soul.locale || "de"}.`,
+        "Liefere eine natuerliche, hilfreiche Antwort.",
+        "Gib strikt JSON zurueck.",
+        `Pflichtfeld fuer die Hauptantwort: ${schema.replyKey}.`,
+        schema.followUpQuestionKey ? `Optionales naechstes Fragefeld: ${schema.followUpQuestionKey}.` : null,
+        schema.followUpQuestionsKey ? `Optionales Feld fuer weitere Fragen: ${schema.followUpQuestionsKey}.` : null,
+        schema.nextStepKey ? `Optionales Feld fuer den naechsten Schritt: ${schema.nextStepKey}.` : null,
+        schema.summaryKey ? `Optionales Feld fuer eine kurze Memory-Zusammenfassung: ${schema.summaryKey}.` : null,
+        schema.userProfileKey ? `Optionales Feld fuer strukturierte Nutzerhinweise: ${schema.userProfileKey}.` : null,
+        schema.rootPatternKey ? `Optionales Feld fuer ein erkanntes Grundmuster: ${schema.rootPatternKey}.` : null,
+    ].filter(Boolean).join("\n");
+}
+function buildUserPrompt(message, memory, protocolSubjectHeader) {
+    const summary = memory.summaries.join("\n") || "(keine Zusammenfassung)";
+    const turns = memory.recentTurns.map((turn) => `${turn.role}: ${turn.content}`).join("\n") || "(kein Verlauf)";
+    return [
+        `Protocol subject: ${protocolSubjectHeader}`,
+        `Memory summary:\n${summary}`,
+        `Recent turns:\n${turns}`,
+        `Current message:\n${message}`,
+    ].join("\n\n");
+}
+function normalizeCompletionResult(result, schema) {
+    if (typeof result === "string") {
+        if (!schema)
+            return { reply: result.trim() };
+        const parsed = tryParseJson(result);
+        if (parsed)
+            return composeStructuredReply(parsed, schema);
+        return { reply: result.trim() };
+    }
+    if (isSoulResponse(result)) {
+        return {
+            reply: String(result.reply || "").trim(),
+            payload: result.metadata && typeof result.metadata === "object"
+                ? result.metadata
+                : undefined,
+        };
+    }
+    if (result && typeof result === "object") {
+        return schema
+            ? composeStructuredReply(result, schema)
+            : { reply: String(result.reply || "").trim(), payload: result };
+    }
+    return { reply: "" };
+}
+function composeStructuredReply(payload, schema) {
+    const parts = [];
+    const main = readString(payload[schema.replyKey]);
+    if (main)
+        parts.push(main);
+    const followUpQuestion = schema.followUpQuestionKey ? readString(payload[schema.followUpQuestionKey]) : undefined;
+    if (followUpQuestion)
+        parts.push(followUpQuestion);
+    const followUpQuestions = schema.followUpQuestionsKey ? readStringList(payload[schema.followUpQuestionsKey]) : [];
+    if (followUpQuestions.length)
+        parts.push(followUpQuestions.join("\n"));
+    const nextStep = schema.nextStepKey ? readString(payload[schema.nextStepKey]) : undefined;
+    if (nextStep)
+        parts.push(nextStep);
+    return {
+        reply: parts.filter(Boolean).join("\n\n").trim(),
+        payload,
+    };
+}
+function mergeMemory(args) {
+    const base = appendMemory(args.memory, args.userMessage, args.assistantReply);
+    const payload = args.payload;
+    const schema = args.schema;
+    if (!payload || !schema)
+        return base;
+    const summaries = [...base.summaries];
+    const summary = schema.summaryKey ? readString(payload[schema.summaryKey]) : undefined;
+    if (summary && !summaries.includes(summary))
+        summaries.push(summary);
+    const userProfile = {
+        ...(base.userProfile || {}),
+        ...(schema.userProfileKey && payload[schema.userProfileKey] && typeof payload[schema.userProfileKey] === "object"
+            ? payload[schema.userProfileKey]
+            : {}),
+    };
+    const rootPattern = schema.rootPatternKey ? readString(payload[schema.rootPatternKey]) : undefined;
+    if (rootPattern) {
+        const existing = Array.isArray(userProfile.recurringPatterns)
+            ? userProfile.recurringPatterns
+            : [];
+        if (!existing.includes(rootPattern)) {
+            userProfile.recurringPatterns = [...existing, rootPattern];
+        }
+    }
+    return {
+        ...base,
+        summaries: summaries.slice(-8),
+        userProfile,
+    };
+}
+function appendMemory(memory, userMessage, assistantReply) {
+    const nextTurns = [
+        ...memory.recentTurns,
+        { role: "user", content: userMessage, createdAt: new Date().toISOString() },
+        { role: "assistant", content: assistantReply, createdAt: new Date().toISOString() },
+    ].slice(-12);
+    return {
+        ...memory,
+        recentTurns: nextTurns,
+        updatedAt: new Date().toISOString(),
+    };
+}
+function isSoulResponse(value) {
+    return Boolean(value) && typeof value === "object" && typeof value.reply === "string";
+}
+function tryParseJson(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function readStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((entry) => readString(entry)).filter((entry) => Boolean(entry));
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@valuya/bot-channel-core",
+  "version": "0.2.0-beta.1",
+  "description": "Shared soul, memory, and mentor helpers for gated bot-channel packages",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.0.10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "pnpm run build && node --test dist/*.test.js"
+  }
+}