@soulcraft/sdk 1.6.2 → 2.0.0

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

@@ -0,0 +1,304 @@
+/**
+ * @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`.
+ */
+/**
+ * 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 const DEFAULT_MODELS = {
+    'claude-opus-4-5-20251101': {
+        id: 'claude-opus-4-5-20251101',
+        name: 'Claude Opus 4.5',
+        shortName: 'Opus 4.5',
+        pricing: { input: 15.00, output: 75.00, cacheHit: 1.50 },
+        supportsThinking: true,
+        maxTokens: 32000,
+        bestFor: ['complex architecture', 'deep reasoning', 'creative tasks'],
+    },
+    'claude-sonnet-4-20250514': {
+        id: 'claude-sonnet-4-20250514',
+        name: 'Claude Sonnet 4',
+        shortName: 'Sonnet 4',
+        pricing: { input: 3.00, output: 15.00, cacheHit: 0.30 },
+        supportsThinking: true,
+        maxTokens: 16000,
+        bestFor: ['planning', 'reasoning', 'analysis', 'multi-step tasks'],
+    },
+    'claude-3-5-haiku-latest': {
+        id: 'claude-3-5-haiku-latest',
+        name: 'Claude Haiku 3.5',
+        shortName: 'Haiku 3.5',
+        pricing: { input: 1.00, output: 5.00, cacheHit: 0.10 },
+        supportsThinking: true,
+        maxTokens: 8192,
+        bestFor: ['implementation', 'simple tasks', 'fast responses'],
+    },
+    'claude-haiku-3-20240307': {
+        id: 'claude-haiku-3-20240307',
+        name: 'Claude Haiku 3',
+        shortName: 'Haiku 3',
+        pricing: { input: 0.25, output: 1.25, cacheHit: 0.03 },
+        supportsThinking: false,
+        maxTokens: 4096,
+        bestFor: ['high-volume', 'simple queries', 'cost optimization'],
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Default Tier Assignments
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default model assignments for each tier role. */
+export const DEFAULT_MODEL_TIERS = {
+    planner: 'claude-opus-4-5-20251101',
+    triage: 'claude-sonnet-4-20250514',
+    executor: 'claude-3-5-haiku-latest',
+    fallback: 'claude-sonnet-4-20250514',
+};
+const ARCHITECTURE_KEYWORDS = [
+    'refactor', 'redesign', 'implement', 'create', 'build', 'add feature',
+    'restructure', 'migrate', 'integrate', 'connect', 'architecture',
+];
+const MULTI_FILE_PATTERNS = [
+    /create.*and.*update/i,
+    /add.*to.*and/i,
+    /multiple\s+(files?|slides?|entities)/i,
+    /all\s+(the\s+)?(files?|slides?|entities)/i,
+];
+const QUESTION_PATTERNS = [
+    /^what\s+(is|are|does)/i, /^how\s+(does|do|can|should)/i,
+    /^why\s+(is|are|does|do)/i, /^where\s+(is|are|can)/i,
+    /^when\s+(should|can|does)/i, /^can\s+(you|I|we)/i,
+    /^explain/i, /^describe/i,
+];
+const SINGLE_TOOL_PATTERNS = [
+    /^read\s+(the\s+)?/i, /^show\s+(me\s+)?/i,
+    /^list\s+/i, /^search\s+/i, /^find\s+/i, /^get\s+/i,
+];
+const CONDITIONAL_PATTERNS = [
+    /\bif\b.*\bthen\b/i, /\bwhen\b.*\belse\b/i,
+    /\botherwise\b/i, /\bdepending\s+on\b/i,
+    /\bbased\s+on\b.*\b(then|do)\b/i,
+];
+/**
+ * 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 function analyzeComplexity(message) {
+    const signals = {
+        multiFileOperations: 0,
+        architectureKeywords: 0,
+        questionWords: 0,
+        singleToolImplied: 0,
+        multipleEntities: 0,
+        conditionalLogic: 0,
+    };
+    const lowerMessage = message.toLowerCase();
+    for (const pattern of MULTI_FILE_PATTERNS) {
+        if (pattern.test(message)) {
+            signals.multiFileOperations = 3;
+            break;
+        }
+    }
+    for (const keyword of ARCHITECTURE_KEYWORDS) {
+        if (lowerMessage.includes(keyword)) {
+            signals.architectureKeywords = 2;
+            break;
+        }
+    }
+    for (const pattern of QUESTION_PATTERNS) {
+        if (pattern.test(message)) {
+            signals.questionWords = -2;
+            break;
+        }
+    }
+    for (const pattern of SINGLE_TOOL_PATTERNS) {
+        if (pattern.test(message)) {
+            signals.singleToolImplied = -1;
+            break;
+        }
+    }
+    const entityMentions = (message.match(/\b(slide|file|document|entity|concept|node)\s*\d*/gi) || []).length;
+    if (entityMentions >= 2)
+        signals.multipleEntities = 2;
+    for (const pattern of CONDITIONAL_PATTERNS) {
+        if (pattern.test(message)) {
+            signals.conditionalLogic = 2;
+            break;
+        }
+    }
+    return signals;
+}
+/**
+ * Sum all signal scores into a single complexity number.
+ *
+ * @param signals - Complexity signals from {@link analyzeComplexity}.
+ * @returns Total score (negative = simple, positive = complex).
+ */
+export function calculateComplexityScore(signals) {
+    return (signals.multiFileOperations +
+        signals.architectureKeywords +
+        signals.questionWords +
+        signals.singleToolImplied +
+        signals.multipleEntities +
+        signals.conditionalLogic);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Tiered Routing
+// ─────────────────────────────────────────────────────────────────────────────
+/** Complexity score at which auto plan-execute mode activates. */
+const COMPLEXITY_THRESHOLD = 3;
+/** Complexity score at which the engine recommends enabling Plan Mode. */
+const PLAN_RECOMMENDATION_THRESHOLD = 5;
+/**
+ * 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 function selectTieredRouting(message, planModeEnabled, modelOverrides) {
+    const tiers = { ...DEFAULT_MODEL_TIERS, ...modelOverrides };
+    const signals = analyzeComplexity(message);
+    const score = calculateComplexityScore(signals);
+    if (planModeEnabled) {
+        return {
+            planModeEnabled: true,
+            triageModel: tiers.planner,
+            executeModel: tiers.executor,
+            complexityScore: score,
+            shouldRecommendPlan: false,
+            reason: 'Plan Mode enabled — using Opus for planning, Haiku for execution',
+        };
+    }
+    const shouldRecommendPlan = score >= PLAN_RECOMMENDATION_THRESHOLD;
+    return {
+        planModeEnabled: false,
+        triageModel: tiers.triage,
+        executeModel: tiers.executor,
+        complexityScore: score,
+        shouldRecommendPlan,
+        reason: shouldRecommendPlan
+            ? `Complexity score ${score} >= ${PLAN_RECOMMENDATION_THRESHOLD} — recommend enabling Plan Mode`
+            : 'Using Sonnet for triage, Haiku for tasks',
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Default Model Selector
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 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 function createDefaultModelSelector(modelOverrides) {
+    return {
+        selectRouting(message, options) {
+            if (options.forcedModel) {
+                return {
+                    planModeEnabled: options.planModeEnabled ?? false,
+                    triageModel: options.forcedModel,
+                    executeModel: options.forcedModel,
+                    complexityScore: 0,
+                    shouldRecommendPlan: false,
+                    reason: `Forced model: ${options.forcedModel}`,
+                };
+            }
+            return selectTieredRouting(message, options.planModeEnabled ?? false, modelOverrides);
+        },
+    };
+}
+/**
+ * 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 function estimateCost(planInputTokens, planOutputTokens, executeInputTokens, executeOutputTokens, planModel = 'claude-sonnet-4-20250514', executeModel = 'claude-3-5-haiku-latest') {
+    const planPricing = getModelPricing(planModel);
+    const executePricing = getModelPricing(executeModel);
+    const planCost = (planInputTokens / 1_000_000) * planPricing.input +
+        (planOutputTokens / 1_000_000) * planPricing.output;
+    const executeCost = (executeInputTokens / 1_000_000) * executePricing.input +
+        (executeOutputTokens / 1_000_000) * executePricing.output;
+    const totalUSD = planCost + executeCost;
+    const singleModelCost = ((planInputTokens + executeInputTokens) / 1_000_000) * planPricing.input +
+        ((planOutputTokens + executeOutputTokens) / 1_000_000) * planPricing.output;
+    const savings = singleModelCost - totalUSD;
+    const savingsPercent = singleModelCost > 0 ? (savings / singleModelCost) * 100 : 0;
+    return {
+        planTokens: { input: planInputTokens, output: planOutputTokens },
+        executeTokens: { input: executeInputTokens, output: executeOutputTokens },
+        totalUSD,
+        breakdown: { planCost, executeCost },
+        comparisonSingleModel: singleModelCost,
+        savings,
+        savingsPercent,
+    };
+}
+/**
+ * Get pricing for a model, falling back to Sonnet pricing for unknown models.
+ *
+ * @param modelId - Model identifier.
+ * @returns Pricing per million tokens.
+ */
+export function getModelPricing(modelId) {
+    const model = DEFAULT_MODELS[modelId];
+    if (model)
+        return model.pricing;
+    return { input: 3.00, output: 15.00, cacheHit: 0.30 };
+}
+/**
+ * Get display name for a model, falling back to the raw ID.
+ *
+ * @param modelId - Model identifier.
+ * @returns Short display name.
+ */
+export function getModelShortName(modelId) {
+    return DEFAULT_MODELS[modelId]?.shortName ?? modelId;
+}
+/**
+ * Format a USD cost for display.
+ *
+ * @param cost - Cost in USD.
+ * @returns Formatted string (e.g. "$0.0032", "<$0.001").
+ */
+export function formatCost(cost) {
+    if (cost === 0)
+        return '$0.00';
+    if (cost < 0.001)
+        return '<$0.001';
+    if (cost < 0.01)
+        return `$${cost.toFixed(4)}`;
+    return `$${cost.toFixed(2)}`;
+}
+//# sourceMappingURL=models.js.map

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

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

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

@@ -0,0 +1,116 @@
+/**
+ * @module server/handlers/chat/planner
+ * @description Plan generation, storage, approval, and modification.
+ *
+ * When Plan Mode is enabled, the planner uses a smart model (Opus) to:
+ * 1. Analyze the user's request and identify the high-level strategy
+ * 2. Break it into discrete, dependency-ordered steps
+ * 3. Identify required tools, files, entities, and skills
+ * 4. Estimate execution cost
+ *
+ * Plans are stored as Brainy `collection` entities with `_aiDataType: 'plan'`,
+ * linked to their conversation via `contains` edges. Plans must be approved
+ * before the executor runs them.
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import type { ChatAIClient, ToolDefinition, AIPlan, PlanStep } from './types.js';
+/**
+ * Options for generating a plan.
+ */
+export interface GeneratePlanOptions {
+    /** The user's message to plan for. */
+    userMessage: string;
+    /** Conversation ID for linking the plan. */
+    conversationId: string;
+    /** AI client for calling Claude. */
+    aiClient: ChatAIClient;
+    /** Available tool definitions (included in the prompt for reference). */
+    tools: ToolDefinition[];
+    /** Product-specific context (e.g. selected files, active kit). */
+    productContext?: Record<string, unknown>;
+    /** Model for planning. Defaults to Opus. */
+    planModel?: string;
+    /** Model for execution. Defaults to Haiku (used in cost estimation). */
+    executeModel?: string;
+}
+/**
+ * Generate an execution plan from a user message.
+ *
+ * Uses the planning model (Opus by default) to analyze the request and
+ * produce a structured, dependency-ordered plan.
+ *
+ * @param options - Plan generation configuration.
+ * @returns The generated plan with cost estimates.
+ */
+export declare function generatePlan(options: GeneratePlanOptions): Promise<AIPlan>;
+/**
+ * Store a plan as a Brainy collection entity.
+ *
+ * Creates the entity and links it to the conversation via `contains`.
+ *
+ * @param brain - Brainy instance.
+ * @param plan - The plan to store.
+ * @returns The Brainy entity ID.
+ */
+export declare function storePlan(brain: Brainy, plan: AIPlan): Promise<string>;
+/**
+ * Load a plan from Brainy by entity ID.
+ *
+ * @param brain - Brainy instance.
+ * @param planId - Brainy entity ID.
+ * @returns The plan, or null if not found.
+ */
+export declare function loadPlan(brain: Brainy, planId: string): Promise<AIPlan | null>;
+/**
+ * Update a plan in Brainy.
+ *
+ * @param brain - Brainy instance.
+ * @param planId - Brainy entity ID.
+ * @param updates - Partial plan updates.
+ */
+export declare function updatePlan(brain: Brainy, planId: string, updates: Partial<AIPlan>): Promise<void>;
+/**
+ * Approve a pending plan for execution.
+ *
+ * @param brain - Brainy instance.
+ * @param planId - Brainy entity ID.
+ * @returns The approved plan.
+ */
+export declare function approvePlan(brain: Brainy, planId: string): Promise<AIPlan>;
+/**
+ * Cancel a plan.
+ *
+ * @param brain - Brainy instance.
+ * @param planId - Brainy entity ID.
+ */
+export declare function cancelPlan(brain: Brainy, planId: string): Promise<void>;
+/**
+ * Get all pending plans for a conversation.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation entity ID.
+ * @returns Array of pending plans.
+ */
+export declare function getPendingPlans(brain: Brainy, conversationId: string): Promise<AIPlan[]>;
+/**
+ * Add a step to a pending plan.
+ *
+ * @param brain - Brainy instance.
+ * @param planId - Brainy entity ID.
+ * @param step - Step to add (status is set to 'pending').
+ * @param afterStepId - Insert after this step ID. Appends if omitted.
+ * @returns Updated plan.
+ */
+export declare function addPlanStep(brain: Brainy, planId: string, step: Omit<PlanStep, 'status'>, afterStepId?: string): Promise<AIPlan>;
+/**
+ * Remove a step from a pending plan.
+ *
+ * Also cleans up dependency references to the removed step.
+ *
+ * @param brain - Brainy instance.
+ * @param planId - Brainy entity ID.
+ * @param stepId - Step to remove.
+ * @returns Updated plan.
+ */
+export declare function removePlanStep(brain: Brainy, planId: string, stepId: string): Promise<AIPlan>;
+//# sourceMappingURL=planner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/chat/planner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,MAAM,EACN,QAAQ,EACT,MAAM,YAAY,CAAA;AAmDnB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,4CAA4C;IAC5C,cAAc,EAAE,MAAM,CAAA;IACtB,oCAAoC;IACpC,QAAQ,EAAE,YAAY,CAAA;IACtB,yEAAyE;IACzE,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2IhF;AAMD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB5E;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIpF;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GACvB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAchF;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7E;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,EAAE,CAAC,CAanB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAC9B,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAcjB"}