@soulcraft/sdk 1.6.2 → 2.0.0

package/dist/server/handlers/chat/memory.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @module server/handlers/chat/memory
+ * @description Proactive memory retrieval, conversation learning, and user
+ * expertise profiling.
+ *
+ * The memory system gives the AI long-term recall by:
+ * 1. **Retrieving** relevant past conversations, preferences, entities, and
+ *    insights before each new message (proactive context enrichment).
+ * 2. **Learning** from completed conversations — extracting insights and
+ *    updating the user's expertise profile.
+ *
+ * All operations use Brainy's semantic search and entity graph — no external
+ * vector DB needed.
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import type { RetrievedMemory, UserExpertiseProfile } from './types.js';
+/**
+ * Retrieve memory items relevant to the current user message.
+ *
+ * Performs four parallel semantic searches:
+ * 1. Past conversation fragments matching the message
+ * 2. User preferences stored as entities
+ * 3. Knowledge graph entities related to the message
+ * 4. Insights derived from past conversations
+ *
+ * @param brain - Brainy instance with the user's knowledge graph.
+ * @param userMessage - The current message to find relevant context for.
+ * @returns Retrieved memory items grouped by type, or null on failure.
+ */
+export declare function retrieveRelevantMemory(brain: Brainy, userMessage: string): Promise<RetrievedMemory | null>;
+/**
+ * Learn from a completed conversation — extract insights and patterns.
+ *
+ * Analyzes the conversation messages to identify:
+ * - Topics discussed
+ * - User preferences expressed
+ * - Decisions made
+ * - Knowledge gaps identified
+ *
+ * Stores insights as entities for future memory retrieval.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to learn from.
+ * @param messages - The conversation messages.
+ * @returns Number of insights stored.
+ */
+export declare function learnFromConversation(brain: Brainy, conversationId: string, messages: Array<{
+    role: string;
+    content: string;
+}>): Promise<{
+    insightsStored: number;
+}>;
+/**
+ * Load the user's expertise profile from Brainy.
+ *
+ * The profile is stored as a single entity with `_aiDataType: 'expertise_profile'`.
+ * If no profile exists, returns the default profile.
+ *
+ * @param brain - Brainy instance.
+ * @returns The user's expertise profile.
+ */
+export declare function loadUserExpertiseProfile(brain: Brainy): Promise<UserExpertiseProfile>;
+/**
+ * Update the user's expertise profile based on recent conversation.
+ *
+ * Analyzes message patterns to detect:
+ * - Technical vocabulary usage → adjust technicalLevel
+ * - Question patterns → identify growth areas
+ * - Confident statements → identify strong areas
+ *
+ * @param brain - Brainy instance.
+ * @param messages - Recent conversation messages.
+ * @returns Whether the profile was updated.
+ */
+export declare function updateUserExpertiseProfile(brain: Brainy, messages: Array<{
+    role: string;
+    content: string;
+}>): Promise<{
+    profileUpdated: boolean;
+}>;
+/**
+ * Generate system prompt additions based on the user's expertise profile.
+ *
+ * Adapts the AI's communication style to match the user's demonstrated
+ * knowledge level.
+ *
+ * @param profile - The user's expertise profile.
+ * @returns A prompt fragment to append to the system prompt, or empty string.
+ */
+export declare function generateExpertisePromptAdditions(profile: UserExpertiseProfile): string;
+//# sourceMappingURL=memory.d.ts.map

package/dist/server/handlers/chat/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/chat/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAMvE;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA8DjC;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACjD,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC,CAsDrC;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,oBAAoB,CAAC,CAuB/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACjD,OAAO,CAAC;IAAE,cAAc,EAAE,OAAO,CAAA;CAAE,CAAC,CA0DtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CAoBR"}

package/dist/server/handlers/chat/memory.js

@@ -0,0 +1,293 @@
+/**
+ * @module server/handlers/chat/memory
+ * @description Proactive memory retrieval, conversation learning, and user
+ * expertise profiling.
+ *
+ * The memory system gives the AI long-term recall by:
+ * 1. **Retrieving** relevant past conversations, preferences, entities, and
+ *    insights before each new message (proactive context enrichment).
+ * 2. **Learning** from completed conversations — extracting insights and
+ *    updating the user's expertise profile.
+ *
+ * All operations use Brainy's semantic search and entity graph — no external
+ * vector DB needed.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Memory Retrieval
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Retrieve memory items relevant to the current user message.
+ *
+ * Performs four parallel semantic searches:
+ * 1. Past conversation fragments matching the message
+ * 2. User preferences stored as entities
+ * 3. Knowledge graph entities related to the message
+ * 4. Insights derived from past conversations
+ *
+ * @param brain - Brainy instance with the user's knowledge graph.
+ * @param userMessage - The current message to find relevant context for.
+ * @returns Retrieved memory items grouped by type, or null on failure.
+ */
+export async function retrieveRelevantMemory(brain, userMessage) {
+    try {
+        const [conversations, preferences, relatedEntities, insights] = await Promise.all([
+            // Past conversation fragments
+            brain.find({
+                query: userMessage,
+                where: { _aiDataType: { equals: 'message' } },
+                limit: 5,
+            }).then((results) => results.map((r) => ({
+                content: r.data?.content || r.data || '',
+                timestamp: r.data?.timestamp || r.metadata?.createdAt || '',
+            }))).catch(() => []),
+            // User preferences
+            brain.find({
+                where: { _aiDataType: { equals: 'preference' } },
+                limit: 10,
+            }).then((results) => results.map((r) => ({
+                key: r.data?.key || r.metadata?.name || '',
+                value: r.data?.value || r.data?.content || '',
+            }))).catch(() => []),
+            // Related knowledge graph entities
+            brain.find({
+                query: userMessage,
+                limit: 10,
+                excludeVFS: true,
+            }).then((results) => results
+                .filter((r) => {
+                const dt = r.metadata?._aiDataType;
+                return dt !== 'conversation' && dt !== 'message';
+            })
+                .slice(0, 5)
+                .map((r) => ({
+                id: r.id,
+                name: r.metadata?.name || r.data?.name || String(r.data || '').slice(0, 50),
+                type: r.type || r.metadata?.noun || 'concept',
+            }))).catch(() => []),
+            // Insights from past conversations
+            brain.find({
+                where: { _aiDataType: { equals: 'insight' } },
+                query: userMessage,
+                limit: 5,
+            }).then((results) => results.map((r) => ({
+                content: r.data?.content || r.data || '',
+                confidence: r.data?.confidence ?? r.metadata?.confidence ?? 0.5,
+            }))).catch(() => []),
+        ]);
+        return { conversations, preferences, relatedEntities, insights };
+    }
+    catch {
+        return null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Learning
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Learn from a completed conversation — extract insights and patterns.
+ *
+ * Analyzes the conversation messages to identify:
+ * - Topics discussed
+ * - User preferences expressed
+ * - Decisions made
+ * - Knowledge gaps identified
+ *
+ * Stores insights as entities for future memory retrieval.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to learn from.
+ * @param messages - The conversation messages.
+ * @returns Number of insights stored.
+ */
+export async function learnFromConversation(brain, conversationId, messages) {
+    if (messages.length < 2)
+        return { insightsStored: 0 };
+    // Extract user messages for topic analysis
+    const userMessages = messages
+        .filter(m => m.role === 'user')
+        .map(m => m.content);
+    if (userMessages.length === 0)
+        return { insightsStored: 0 };
+    // Simple keyword extraction for topics (no AI call needed)
+    const allText = userMessages.join(' ').toLowerCase();
+    const words = allText.split(/\s+/);
+    const wordFreq = new Map();
+    for (const word of words) {
+        if (word.length < 4)
+            continue;
+        wordFreq.set(word, (wordFreq.get(word) || 0) + 1);
+    }
+    // Find repeated topics (mentioned 2+ times)
+    const topics = [...wordFreq.entries()]
+        .filter(([, count]) => count >= 2)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([word]) => word);
+    if (topics.length === 0)
+        return { insightsStored: 0 };
+    // Store a conversation summary insight
+    let insightsStored = 0;
+    try {
+        await brain.add({
+            type: 'event',
+            data: {
+                content: `User discussed: ${topics.join(', ')}`,
+                topics,
+                messageCount: messages.length,
+                conversationId,
+                timestamp: new Date().toISOString(),
+            },
+            metadata: {
+                name: `Conversation insight: ${topics.slice(0, 3).join(', ')}`,
+                isAIManaged: true,
+                _aiDataType: 'insight',
+                confidence: 0.6,
+            },
+        });
+        insightsStored++;
+    }
+    catch {
+        // Non-fatal
+    }
+    return { insightsStored };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Expertise Profile
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default expertise profile for new users. */
+const DEFAULT_PROFILE = {
+    strongAreas: [],
+    growthAreas: [],
+    technicalLevel: 3,
+    preferredDetailLevel: 3,
+    communicationStyle: 'balanced',
+    domainExpertise: [],
+};
+/**
+ * Load the user's expertise profile from Brainy.
+ *
+ * The profile is stored as a single entity with `_aiDataType: 'expertise_profile'`.
+ * If no profile exists, returns the default profile.
+ *
+ * @param brain - Brainy instance.
+ * @returns The user's expertise profile.
+ */
+export async function loadUserExpertiseProfile(brain) {
+    try {
+        const results = await brain.find({
+            where: { _aiDataType: { equals: 'expertise_profile' } },
+            limit: 1,
+        });
+        if (results.length > 0) {
+            const data = results[0].data || {};
+            return {
+                strongAreas: data.strongAreas || [],
+                growthAreas: data.growthAreas || [],
+                technicalLevel: data.technicalLevel ?? 3,
+                preferredDetailLevel: data.preferredDetailLevel ?? 3,
+                communicationStyle: data.communicationStyle || 'balanced',
+                domainExpertise: data.domainExpertise || [],
+            };
+        }
+    }
+    catch {
+        // Fall through to default
+    }
+    return { ...DEFAULT_PROFILE };
+}
+/**
+ * Update the user's expertise profile based on recent conversation.
+ *
+ * Analyzes message patterns to detect:
+ * - Technical vocabulary usage → adjust technicalLevel
+ * - Question patterns → identify growth areas
+ * - Confident statements → identify strong areas
+ *
+ * @param brain - Brainy instance.
+ * @param messages - Recent conversation messages.
+ * @returns Whether the profile was updated.
+ */
+export async function updateUserExpertiseProfile(brain, messages) {
+    const userMessages = messages.filter(m => m.role === 'user').map(m => m.content);
+    if (userMessages.length < 2)
+        return { profileUpdated: false };
+    const profile = await loadUserExpertiseProfile(brain);
+    let changed = false;
+    // Simple heuristic: detect technical vocabulary density
+    const technicalTerms = [
+        'api', 'function', 'async', 'promise', 'interface', 'type', 'class',
+        'database', 'query', 'schema', 'deploy', 'runtime', 'algorithm',
+        'architecture', 'component', 'module', 'endpoint', 'middleware',
+    ];
+    const allText = userMessages.join(' ').toLowerCase();
+    const words = allText.split(/\s+/);
+    const techCount = words.filter(w => technicalTerms.includes(w)).length;
+    const techDensity = words.length > 0 ? techCount / words.length : 0;
+    // Adjust technical level based on vocabulary
+    if (techDensity > 0.05 && profile.technicalLevel < 5) {
+        profile.technicalLevel = Math.min(5, profile.technicalLevel + 0.5);
+        changed = true;
+    }
+    else if (techDensity < 0.01 && profile.technicalLevel > 1) {
+        profile.technicalLevel = Math.max(1, profile.technicalLevel - 0.3);
+        changed = true;
+    }
+    if (!changed)
+        return { profileUpdated: false };
+    // Persist updated profile
+    try {
+        const existing = await brain.find({
+            where: { _aiDataType: { equals: 'expertise_profile' } },
+            limit: 1,
+        });
+        if (existing.length > 0) {
+            await brain.update({
+                id: existing[0].id,
+                data: profile,
+            });
+        }
+        else {
+            await brain.add({
+                type: 'event',
+                data: profile,
+                metadata: {
+                    name: 'User Expertise Profile',
+                    isAIManaged: true,
+                    _aiDataType: 'expertise_profile',
+                },
+            });
+        }
+        return { profileUpdated: true };
+    }
+    catch {
+        return { profileUpdated: false };
+    }
+}
+/**
+ * Generate system prompt additions based on the user's expertise profile.
+ *
+ * Adapts the AI's communication style to match the user's demonstrated
+ * knowledge level.
+ *
+ * @param profile - The user's expertise profile.
+ * @returns A prompt fragment to append to the system prompt, or empty string.
+ */
+export function generateExpertisePromptAdditions(profile) {
+    if (!profile.strongAreas.length && !profile.growthAreas.length)
+        return '';
+    const parts = [];
+    if (profile.technicalLevel >= 4) {
+        parts.push('The user is technically advanced — use precise terminology, skip basic explanations.');
+    }
+    else if (profile.technicalLevel <= 2) {
+        parts.push('The user prefers clear, accessible explanations — avoid jargon, use analogies.');
+    }
+    if (profile.strongAreas.length > 0) {
+        parts.push(`Strong areas: ${profile.strongAreas.join(', ')}. Reference these confidently.`);
+    }
+    if (profile.growthAreas.length > 0) {
+        parts.push(`Growth areas: ${profile.growthAreas.join(', ')}. Be more explanatory here.`);
+    }
+    return parts.join('\n');
+}
+//# sourceMappingURL=memory.js.map

package/dist/server/handlers/chat/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../../src/server/handlers/chat/memory.ts"],"names":[],"mappings":"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"}

package/dist/server/handlers/chat/models.d.ts

@@ -0,0 +1,180 @@
+/**
+ * @module server/handlers/chat/models
+ * @description Model routing, complexity analysis, and cost estimation for
+ * the tiered AI strategy.
+ *
+ * The chat engine uses a multi-model approach:
+ * - **Plan Mode ON**: Opus (deep analysis, planning) → Haiku (fast execution)
+ * - **Plan Mode OFF**: Sonnet (triage, synthesis) → Haiku (task execution)
+ *
+ * Complexity analysis scores each user message on 6 signals (multi-file ops,
+ * architecture keywords, question patterns, single-tool hints, entity count,
+ * conditional logic) to decide whether to recommend Plan Mode.
+ *
+ * All model IDs and pricing are configurable — products can override defaults
+ * via the {@link ModelSelector} interface in `types.ts`.
+ */
+import type { TieredRouting, ModelSelector } from './types.js';
+/**
+ * Known Claude model configuration with pricing and capabilities.
+ *
+ * Pricing is per million tokens. Products can extend this with custom model
+ * entries via the {@link ModelConfig} type.
+ */
+export interface ModelConfig {
+    /** Model identifier sent to the API. */
+    id: string;
+    /** Display name for logs and UI. */
+    name: string;
+    /** Short display name for compact UI. */
+    shortName: string;
+    /** Pricing per million tokens. */
+    pricing: {
+        input: number;
+        output: number;
+        cacheHit: number;
+    };
+    /** Whether this model supports extended thinking. */
+    supportsThinking: boolean;
+    /** Maximum output tokens. */
+    maxTokens: number;
+    /** Best use cases for documentation. */
+    bestFor: string[];
+}
+/**
+ * Default model catalog — Anthropic Claude models with current pricing.
+ *
+ * Products can supplement this with additional models. The engine only needs
+ * model IDs; it doesn't validate against this catalog at runtime.
+ */
+export declare const DEFAULT_MODELS: Record<string, ModelConfig>;
+/** Default model assignments for each tier role. */
+export declare const DEFAULT_MODEL_TIERS: {
+    readonly planner: "claude-opus-4-5-20251101";
+    readonly triage: "claude-sonnet-4-20250514";
+    readonly executor: "claude-3-5-haiku-latest";
+    readonly fallback: "claude-sonnet-4-20250514";
+};
+/**
+ * Signal scores from complexity analysis.
+ *
+ * Each signal contributes a positive or negative score. The sum determines
+ * whether the message warrants plan mode or simple direct handling.
+ */
+export interface ComplexitySignals {
+    /** +3 if message mentions multi-file/multi-entity operations. */
+    multiFileOperations: number;
+    /** +2 if message contains architecture/design keywords. */
+    architectureKeywords: number;
+    /** -2 if message is a question (read-only, no mutation needed). */
+    questionWords: number;
+    /** -1 if message implies a single tool call. */
+    singleToolImplied: number;
+    /** +2 if message references 2+ entities by name. */
+    multipleEntities: number;
+    /** +2 if message contains conditional/branching logic. */
+    conditionalLogic: number;
+}
+/**
+ * Analyze a user message's complexity across 6 signal dimensions.
+ *
+ * @param message - The user's raw message text.
+ * @returns Signal scores (sum them for the total complexity score).
+ */
+export declare function analyzeComplexity(message: string): ComplexitySignals;
+/**
+ * Sum all signal scores into a single complexity number.
+ *
+ * @param signals - Complexity signals from {@link analyzeComplexity}.
+ * @returns Total score (negative = simple, positive = complex).
+ */
+export declare function calculateComplexityScore(signals: ComplexitySignals): number;
+/**
+ * Select the tiered routing strategy for a message.
+ *
+ * When Plan Mode is ON, uses Opus for planning and Haiku for execution.
+ * When OFF, uses Sonnet for triage and Haiku for tasks — and recommends
+ * Plan Mode if complexity exceeds the recommendation threshold.
+ *
+ * @param message - The user's message.
+ * @param planModeEnabled - Whether Plan Mode is explicitly enabled by the user.
+ * @param modelOverrides - Optional per-tier model overrides.
+ * @returns Complete routing decision.
+ */
+export declare function selectTieredRouting(message: string, planModeEnabled: boolean, modelOverrides?: Partial<typeof DEFAULT_MODEL_TIERS>): TieredRouting;
+/**
+ * Create the default {@link ModelSelector} implementation.
+ *
+ * Uses complexity analysis and the default tier assignments. Products can
+ * pass custom tier overrides or replace this entirely.
+ *
+ * @param modelOverrides - Optional per-tier model overrides.
+ * @returns A ModelSelector using complexity-based routing.
+ */
+export declare function createDefaultModelSelector(modelOverrides?: Partial<typeof DEFAULT_MODEL_TIERS>): ModelSelector;
+/**
+ * Cost estimate for a plan-execute flow.
+ */
+export interface CostEstimate {
+    /** Plan phase token usage. */
+    planTokens: {
+        input: number;
+        output: number;
+    };
+    /** Execute phase token usage. */
+    executeTokens: {
+        input: number;
+        output: number;
+    };
+    /** Total estimated cost in USD. */
+    totalUSD: number;
+    /** Breakdown by phase. */
+    breakdown: {
+        planCost: number;
+        executeCost: number;
+    };
+    /** What it would cost using a single model for everything. */
+    comparisonSingleModel: number;
+    /** Savings from tiered routing. */
+    savings: number;
+    /** Savings as a percentage. */
+    savingsPercent: number;
+}
+/**
+ * Estimate cost for a plan-execute flow based on token counts.
+ *
+ * @param planInputTokens - Input tokens for the planning phase.
+ * @param planOutputTokens - Output tokens for the planning phase.
+ * @param executeInputTokens - Input tokens for the execution phase.
+ * @param executeOutputTokens - Output tokens for the execution phase.
+ * @param planModel - Model used for planning.
+ * @param executeModel - Model used for execution.
+ * @returns Detailed cost estimate with savings comparison.
+ */
+export declare function estimateCost(planInputTokens: number, planOutputTokens: number, executeInputTokens: number, executeOutputTokens: number, planModel?: string, executeModel?: string): CostEstimate;
+/**
+ * Get pricing for a model, falling back to Sonnet pricing for unknown models.
+ *
+ * @param modelId - Model identifier.
+ * @returns Pricing per million tokens.
+ */
+export declare function getModelPricing(modelId: string): {
+    input: number;
+    output: number;
+    cacheHit: number;
+};
+/**
+ * Get display name for a model, falling back to the raw ID.
+ *
+ * @param modelId - Model identifier.
+ * @returns Short display name.
+ */
+export declare function getModelShortName(modelId: string): string;
+/**
+ * Format a USD cost for display.
+ *
+ * @param cost - Cost in USD.
+ * @returns Formatted string (e.g. "$0.0032", "<$0.001").
+ */
+export declare function formatCost(cost: number): string;
+//# sourceMappingURL=models.d.ts.map

package/dist/server/handlers/chat/models.d.ts.map

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