soulbridge 0.0.10 → 0.0.12

package/dist/packages/core/src/index.d.ts

@@ -31,6 +31,14 @@ export interface SoulOptions {
     deviceId?: string;
     /** Defaults to the lexicon analyzer; pass an LLM-backed one to opt in (ADR 0015). */
     analyzer?: AffectAnalyzer;
+    /**
+     * Optional model access, injected the same way as `analyzer`. Adapters supply
+     * it from their host's own model (an in-process service, a CLI subprocess, an
+     * HTTP endpoint). Omit it and every verb stays rule-only.
+     */
+    llm?: LlmFn;
+    /** Messages longer than this are not sent to the model. Defaults to 2000. */
+    llmMaxChars?: number;
 }
 export declare class Soul {
     readonly store: SoulStore;
@@ -39,6 +47,8 @@ export declare class Soul {
     readonly name: string;
     readonly deviceId: string;
     readonly analyzer: AffectAnalyzer;
+    readonly llm?: LlmFn;
+    readonly llmMaxChars: number;
     constructor(options: SoulOptions);
     /** Verb 1: session start. */
     context(request?: Partial<ContextRequest>): ContextResult;
@@ -68,7 +78,6 @@ export declare class Soul {
     }): string;
     /** Verb 4: session end. */
     reflect(turns: Turn[], options?: {
-        llm?: LlmFn;
         updateEmotion?: boolean;
     }): Promise<ReflectResult>;
     stats(): {

package/dist/packages/core/src/index.js

@@ -19,6 +19,7 @@ import { buildContext } from './context.js';
 import { reflect, ruleExtract, nextEmotion } from './reflect.js';
 import { rank, tokenize } from './scoring.js';
 import { analyzeAffect, emptyAffect, lexiconAnalyzer } from './affect/analyze.js';
+import { llmExtractTurn } from './reflect.js';
 export class Soul {
     store;
     soulId;
@@ -26,6 +27,8 @@ export class Soul {
     name;
     deviceId;
     analyzer;
+    llm;
+    llmMaxChars;
     constructor(options) {
         this.store = options.store;
         this.soulId = options.soulId;
@@ -33,6 +36,8 @@ export class Soul {
         this.name = options.name ?? '小灵';
         this.deviceId = options.deviceId ?? 'dev_local';
         this.analyzer = options.analyzer ?? lexiconAnalyzer;
+        this.llm = options.llm;
+        this.llmMaxChars = options.llmMaxChars ?? 2000;
         if (!this.store.identity(this.soulId)) {
             this.store.ensureSoul({
                 soulId: this.soulId,
@@ -82,13 +87,34 @@ export class Soul {
     async observe(turn) {
         const now = turn.at ?? Date.now();
         const affect = turn.role === 'user' ? await this.analyzeTurn(turn.content) : emptyAffect();
-        const drafts = ruleExtract([turn]);
+        // Rules first: they are precise and cheap. Only when they find nothing does
+        // the optional model get a chance, so it can add recall without overriding
+        // a rule that already fired.
+        let drafts = ruleExtract([turn]);
+        let extractedBy = drafts.length > 0 ? 'rules' : 'none';
+        if (drafts.length === 0 && turn.role === 'user' && this.llm) {
+            if (turn.content.length <= this.llmMaxChars) {
+                try {
+                    const draft = await llmExtractTurn(turn.content, this.llm);
+                    if (draft) {
+                        drafts = [draft];
+                        extractedBy = 'llm';
+                    }
+                }
+                catch {
+                    // The model is an enhancement; a transport or parse failure leaves the
+                    // rule result (nothing) in place.
+                }
+            }
+        }
         // observe runs every turn; repeating a sentence must not create a second row.
         const seen = new Set(this.store.query({ soulId: this.soulId, userId: this.userId, limit: 10_000 }).map((m) => m.content.trim()));
+        let written = 0;
         for (const draft of drafts) {
             if (seen.has(draft.content.trim()))
                 continue;
             seen.add(draft.content.trim());
+            written += 1;
             this.store.put({
                 id: `mem_${now.toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
                 soulId: this.soulId,
@@ -116,7 +142,7 @@ export class Soul {
         }
         const emotion = nextEmotion(this.store.emotion(this.soulId, this.userId), [turn]);
         this.store.saveEmotion(this.soulId, this.userId, emotion, now);
-        return { written: drafts.length, emotion, affect };
+        return { written, emotion, affect, extractedBy: written > 0 ? extractedBy : 'none' };
     }
     /**
      * Explicit form of `observe`: the host decided this is worth keeping.
@@ -149,7 +175,7 @@ export class Soul {
             soulId: this.soulId,
             userId: this.userId,
             turns,
-            llm: options.llm,
+            llm: this.llm,
             updateEmotion: options.updateEmotion,
         });
     }

package/dist/packages/core/src/reflect.d.ts

@@ -44,4 +44,18 @@ export interface ReflectOptions {
     llm?: LlmFn;
 }
 export declare function reflect(store: SoulStore, options: ReflectOptions): Promise<ReflectResult>;
+/** Only these types travel over the port; episodic/relationship stay host-local. */
+export declare const LLM_MEMORY_TYPES: MemoryType[];
+export declare const LLM_PROMPT: string;
+export interface LlmDraft {
+    type: MemoryType;
+    content: string;
+    importance: number;
+}
+/**
+ * Ask the model for one memory. Returns null when the model deliberately says
+ * "nothing worth storing"; throws when the transport or the output is unusable,
+ * so the caller can fall back to rules.
+ */
+export declare function llmExtractTurn(text: string, llm: LlmFn): Promise<LlmDraft | null>;
 export {};

package/dist/packages/core/src/reflect.js

@@ -118,7 +118,26 @@ export function nextEmotion(current, turns) {
 }
 export async function reflect(store, options) {
     const now = options.now ?? Date.now();
-    const drafts = ruleExtract(options.turns);
+    const drafts = [];
+    if (options.llm) {
+        for (const turn of options.turns) {
+            if (turn.role !== 'user')
+                continue;
+            try {
+                const draft = await llmExtractTurn(turn.content, options.llm);
+                // A deliberate null means the model decided this is not worth storing.
+                if (draft)
+                    drafts.push(draft);
+            }
+            catch {
+                // Transport or parse failure: fall back to rules for this turn.
+                drafts.push(...ruleExtract([turn]));
+            }
+        }
+    }
+    else {
+        drafts.push(...ruleExtract(options.turns));
+    }
     const existing = store.query({ soulId: options.soulId, userId: options.userId });
     const seen = new Set(existing.map((m) => m.content));
     let written = 0;
@@ -151,3 +170,60 @@ export async function reflect(store, options) {
     }
     return { memories: written, superseded: 0, emotion };
 }
+/* ------------------------------------------------------------------ *
+ * LLM distillation port (optional)
+ *
+ * Core owns the prompt, the JSON contract and the fallback; adapters own the
+ * transport. A DSH adapter wraps `ctx.llm.stream`, a CLI adapter calls an
+ * OpenAI-compatible endpoint, and both satisfy the same `LlmFn`.
+ * ------------------------------------------------------------------ */
+/** Only these types travel over the port; episodic/relationship stay host-local. */
+export const LLM_MEMORY_TYPES = ['strategy', 'trait', 'fact', 'cognition'];
+export const LLM_PROMPT = [
+    '你是记忆提炼器。输入是用户的一段话，判断其中有没有值得长期记住的内容。',
+    '只输出 JSON，二选一：',
+    '{"type":"strategy|trait|fact|cognition|null","text":"不超过 40 字的记忆"}',
+    '规则：',
+    '1. 只保留长期有效的要求、偏好或事实；一次性的抱怨、讨论、玩笑都输出 null；',
+    '2. 保留条件（什么时候）和动作（做什么）；',
+    '3. 不要解释，不要编造原文没有的内容。',
+].join('\n');
+function parseLlmJson(raw) {
+    const trimmed = raw.trim().replace(/^```(?:json)?/i, '').replace(/```$/, '').trim();
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start < 0 || end < start)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed.slice(start, end + 1));
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ask the model for one memory. Returns null when the model deliberately says
+ * "nothing worth storing"; throws when the transport or the output is unusable,
+ * so the caller can fall back to rules.
+ */
+export async function llmExtractTurn(text, llm) {
+    const raw = await llm(`${LLM_PROMPT}\n\n用户：${text}`);
+    const parsed = parseLlmJson(String(raw));
+    if (!parsed)
+        throw new Error('llm returned no JSON');
+    const type = parsed.type;
+    if (type === 'null' || parsed.text === undefined || parsed.text === null)
+        return null;
+    if (typeof type !== 'string' || !LLM_MEMORY_TYPES.includes(type)) {
+        throw new Error(`llm returned an unsupported type: ${String(type)}`);
+    }
+    const content = String(parsed.text).trim();
+    if (content.length === 0)
+        return null;
+    return {
+        type: type,
+        content: content.slice(0, 120),
+        importance: type === 'strategy' ? 7 : 6,
+    };
+}

package/dist/packages/core/src/types.d.ts

@@ -108,6 +108,8 @@ export interface ObserveResult {
     emotion: Emotion;
     /** Analysis of the user turn. Empty signal for assistant turns or on failure. */
     affect: AffectSignal;
+    /** Which extractor produced the memory, for measurement. */
+    extractedBy: 'rules' | 'llm' | 'none';
 }
 /** Injected by the caller. `core` never imports a model SDK. */
 export type LlmFn = (prompt: string) => Promise<string> | string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soulbridge",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "A personality layer for any agent: continuity, forgetting, and growth across tools.",
   "license": "Apache-2.0",
   "type": "module",