cognitive-core 0.0.2 → 0.1.0

package/src/search/router.ts

@@ -0,0 +1,261 @@
+import type { Task, RouterConfig } from '../types/index.js';
+import type { MemorySystem, MemoryQueryResultV2 } from '../memory/system.js';
+import type { MetaLearner } from '../learning/meta-learner.js';
+
+/**
+ * Routing decision with context
+ */
+export interface RoutingDecision {
+  /** Selected strategy for solving */
+  strategy: 'direct' | 'adapt' | 'explore' | 'fallback';
+  /** Confidence in this routing (0-1) */
+  confidence: number;
+  /** Memory query results (playbook format) */
+  memoryContext: MemoryQueryResultV2;
+  /** Estimated compute budget (LLM calls) */
+  estimatedBudget: number;
+  /** Reasoning for the decision */
+  reasoning: string;
+  /** Meta-strategies that were applied */
+  appliedMetaStrategies?: string[];
+}
+
+/**
+ * Task Router
+ * Determines the best approach for solving a task based on memory
+ * Now with meta-learning integration for adaptive routing
+ */
+export class TaskRouter {
+  private memory: MemorySystem;
+  private config: RouterConfig;
+  private metaLearner?: MetaLearner;
+
+  constructor(
+    memory: MemorySystem,
+    config?: Partial<RouterConfig>,
+    metaLearner?: MetaLearner
+  ) {
+    this.memory = memory;
+    this.config = {
+      similarityThreshold: config?.similarityThreshold ?? 0.85,
+      useDomainRouting: config?.useDomainRouting ?? true,
+      defaultStrategy: config?.defaultStrategy ?? 'direct',
+    };
+    this.metaLearner = metaLearner;
+  }
+
+  /**
+   * Set the meta learner (can be set after construction)
+   */
+  setMetaLearner(metaLearner: MetaLearner): void {
+    this.metaLearner = metaLearner;
+  }
+
+  /**
+   * Route a task to determine solving strategy
+   * Uses playbook-based memory with meta-learning adjustments
+   */
+  async route(task: Task): Promise<RoutingDecision> {
+    // Query memory for relevant context
+    const memoryContext = await this.memory.queryV2(task.description, {
+      domains: task.domain ? [task.domain] : undefined,
+    });
+
+    // Compute base routing from playbook memory
+    let decision = this.computeBaseRouting(memoryContext);
+
+    // Apply meta-learning adjustments if available
+    if (this.metaLearner) {
+      const taskCharacteristics = this.extractTaskCharacteristics(task);
+      const memoryState = this.summarizeMemoryState(memoryContext);
+
+      try {
+        const adjusted = await this.metaLearner.adjustRouting(
+          {
+            strategy: decision.strategy,
+            confidence: decision.confidence,
+            estimatedBudget: decision.estimatedBudget,
+            reasoning: decision.reasoning,
+          },
+          taskCharacteristics,
+          memoryState
+        );
+
+        // Apply adjustments
+        if (adjusted.strategy !== decision.strategy || adjusted.confidence !== decision.confidence) {
+          decision.strategy = adjusted.strategy;
+          decision.confidence = adjusted.confidence;
+          decision.reasoning = adjusted.reasoning;
+          decision.appliedMetaStrategies = ['meta-learning adjustment'];
+        }
+      } catch (error) {
+        // Meta-learning failed, continue with base routing
+        console.error(
+          '[TaskRouter] Meta-learning adjustment failed, using base routing:',
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+
+    return decision;
+  }
+
+  /**
+   * Compute base routing decision from memory results
+   */
+  private computeBaseRouting(memoryContext: MemoryQueryResultV2): RoutingDecision {
+    // Check experience memory
+    const hasHighSimilarityExperience = memoryContext.experiences.some(
+      (e) => e.score >= this.config.similarityThreshold && e.experience.success
+    );
+
+    // Check playbook memory
+    const hasHighConfidencePlaybook = memoryContext.playbooks.some(
+      (p) => p.score >= this.config.similarityThreshold && p.playbook.confidence >= 0.7
+    );
+
+    const hasApplicablePlaybook = memoryContext.playbooks.some(
+      (p) => p.score >= this.config.similarityThreshold * 0.8
+    );
+
+    // Determine routing strategy
+    let strategy: RoutingDecision['strategy'];
+    let confidence: number;
+    let estimatedBudget: number;
+    let reasoning: string;
+
+    if (hasHighSimilarityExperience) {
+      strategy = 'adapt';
+      confidence = 0.9;
+      estimatedBudget = 1;
+      reasoning = 'Found highly similar successful experience to adapt from';
+    } else if (hasHighConfidencePlaybook) {
+      strategy = 'direct';
+      confidence = 0.8;
+      estimatedBudget = 2;
+      reasoning = 'Found high-confidence playbook for guidance';
+    } else if (hasApplicablePlaybook) {
+      strategy = 'direct';
+      confidence = 0.6;
+      estimatedBudget = 4;
+      reasoning = 'Found applicable playbook to guide solving';
+    } else if (memoryContext.experiences.length > 0) {
+      strategy = 'explore';
+      confidence = 0.4;
+      estimatedBudget = 10;
+      reasoning = 'Found some context but need exploration';
+    } else {
+      strategy = 'fallback';
+      confidence = 0.2;
+      estimatedBudget = 20;
+      reasoning = 'No relevant memory found, using fallback strategy';
+    }
+
+    return {
+      strategy,
+      confidence,
+      memoryContext,
+      estimatedBudget,
+      reasoning,
+    };
+  }
+
+  /**
+   * Extract task characteristics for meta-learning
+   */
+  private extractTaskCharacteristics(task: Task): string[] {
+    const characteristics: string[] = [];
+
+    // Domain
+    if (task.domain) {
+      characteristics.push(`domain: ${task.domain}`);
+    }
+
+    // Analyze description
+    const desc = task.description.toLowerCase();
+
+    if (desc.includes('bug') || desc.includes('fix') || desc.includes('error')) {
+      characteristics.push('bug fix');
+    }
+
+    if (desc.includes('test') || desc.includes('spec')) {
+      characteristics.push('testing');
+    }
+
+    if (desc.includes('refactor') || desc.includes('clean')) {
+      characteristics.push('refactoring');
+    }
+
+    if (desc.includes('implement') || desc.includes('create') || desc.includes('add')) {
+      characteristics.push('new feature');
+    }
+
+    if (desc.includes('multiple') || desc.includes('files') || desc.includes('across')) {
+      characteristics.push('multi-file change');
+    }
+
+    if (desc.length > 500) {
+      characteristics.push('complex task');
+    }
+
+    return characteristics;
+  }
+
+  /**
+   * Summarize memory state for meta-learning
+   */
+  private summarizeMemoryState(memoryContext: MemoryQueryResultV2): string[] {
+    const state: string[] = [];
+
+    // Experience state
+    if (memoryContext.experiences.length === 0) {
+      state.push('no similar experiences');
+    } else {
+      const maxScore = Math.max(...memoryContext.experiences.map((e) => e.score), 0);
+      if (maxScore >= 0.8) {
+        state.push('high similarity experience');
+      } else if (maxScore >= 0.5) {
+        state.push('moderate similarity experience');
+      } else {
+        state.push('low similarity experiences');
+      }
+    }
+
+    // Playbook state
+    if (memoryContext.playbooks.length === 0) {
+      state.push('no applicable playbooks');
+    } else {
+      const maxConfidence = Math.max(
+        ...memoryContext.playbooks.map((p) => p.playbook.confidence),
+        0
+      );
+      if (maxConfidence >= 0.8) {
+        state.push('high confidence playbook');
+      } else if (maxConfidence >= 0.5) {
+        state.push('moderate confidence playbook');
+      } else {
+        state.push('low confidence playbooks');
+      }
+    }
+
+    return state;
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<RouterConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+}
+
+/**
+ * Create a task router
+ */
+export function createRouter(
+  memory: MemorySystem,
+  config?: Partial<RouterConfig>,
+  metaLearner?: MetaLearner
+): TaskRouter {
+  return new TaskRouter(memory, config, metaLearner);
+}

package/src/search/solver.ts

@@ -0,0 +1,303 @@
+import type {
+  Task,
+  Trajectory,
+  Step,
+  Outcome,
+} from '../types/index.js';
+import {
+  createTrajectory,
+  createStep,
+  successOutcome,
+  failureOutcome,
+} from '../types/index.js';
+import type { MemorySystem } from '../memory/system.js';
+import type { LLMProvider, Message } from '../agents/types.js';
+import type { RoutingDecision } from './router.js';
+
+/**
+ * Solver configuration
+ */
+export interface SolverConfig {
+  maxSteps: number;
+  temperature: number;
+  agentId: string;
+}
+
+/**
+ * Solver result
+ */
+export interface SolverResult {
+  trajectory: Trajectory;
+  usedMemory: boolean;
+  strategy: string;
+}
+
+/**
+ * Direct Solver
+ * Solves tasks using memory-augmented LLM calls
+ *
+ * @deprecated Use AgentManager.spawn() instead. DirectSolver will be removed in v2.0.
+ * The AgentManager provides real action execution through configurable backends (ACP, subprocess).
+ *
+ * Migration example:
+ * ```typescript
+ * // Before (deprecated):
+ * const solver = createSolver(memory, provider);
+ * const result = await solver.solve(task, routing);
+ *
+ * // After (recommended):
+ * const manager = createAgentManager(memory);
+ * const result = await manager.spawn({
+ *   agentType: 'claude-code',
+ *   task,
+ *   injectedKnowledge: routing.memoryContext,
+ * });
+ * ```
+ */
+export class DirectSolver {
+  private memory: MemorySystem;
+  private provider: LLMProvider;
+  private config: SolverConfig;
+
+  constructor(
+    memory: MemorySystem,
+    provider: LLMProvider,
+    config?: Partial<SolverConfig>
+  ) {
+    this.memory = memory;
+    this.provider = provider;
+    this.config = {
+      maxSteps: config?.maxSteps ?? 10,
+      temperature: config?.temperature ?? 0.3,
+      agentId: config?.agentId ?? 'direct-solver',
+    };
+  }
+
+  /**
+   * Solve a task using the routing decision
+   */
+  async solve(task: Task, routing: RoutingDecision): Promise<SolverResult> {
+    const startTime = Date.now();
+    const steps: Step[] = [];
+    let llmCalls = 0;
+    let totalTokens = 0;
+
+    try {
+      // Build system prompt with memory context
+      const systemPrompt = this.buildSystemPrompt(task, routing);
+
+      // Execute solving loop
+      const messages: Message[] = [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: this.buildTaskPrompt(task) },
+      ];
+
+      let done = false;
+      let outcome: Outcome | null = null;
+
+      while (!done && steps.length < this.config.maxSteps) {
+        // Get LLM response
+        const response = await this.provider.complete(messages, {
+          temperature: this.config.temperature,
+        });
+        llmCalls++;
+
+        // Parse response into thought/action
+        const { thought, action, isDone, solution } =
+          this.parseResponse(response);
+
+        // Create step
+        const step = createStep({
+          thought,
+          action,
+          observation: isDone
+            ? 'Task completed'
+            : 'Awaiting next step',
+        });
+        steps.push(step);
+
+        // Check if done
+        if (isDone) {
+          done = true;
+          outcome = successOutcome(solution);
+        }
+
+        // Add to conversation
+        messages.push({ role: 'assistant', content: response });
+
+        if (!isDone) {
+          // In a real implementation, we'd execute the action and get observation
+          messages.push({
+            role: 'user',
+            content: 'Continue with the next step.',
+          });
+        }
+      }
+
+      // If we hit max steps without completing
+      if (!outcome) {
+        outcome = failureOutcome('Max steps reached without solution', 0.5);
+      }
+
+      const wallTimeSeconds = (Date.now() - startTime) / 1000;
+
+      const trajectory = createTrajectory({
+        task,
+        steps,
+        outcome,
+        agentId: this.config.agentId,
+        llmCalls,
+        totalTokens,
+        wallTimeSeconds,
+      });
+
+      return {
+        trajectory,
+        usedMemory: routing.memoryContext.experiences.length > 0,
+        strategy: routing.strategy,
+      };
+    } catch (error) {
+      const wallTimeSeconds = (Date.now() - startTime) / 1000;
+      const errorMessage =
+        error instanceof Error ? error.message : 'Unknown error';
+
+      const trajectory = createTrajectory({
+        task,
+        steps,
+        outcome: failureOutcome(errorMessage),
+        agentId: this.config.agentId,
+        llmCalls,
+        totalTokens,
+        wallTimeSeconds,
+      });
+
+      return {
+        trajectory,
+        usedMemory: routing.memoryContext.experiences.length > 0,
+        strategy: routing.strategy,
+      };
+    }
+  }
+
+  /**
+   * Build system prompt with memory context
+   */
+  private buildSystemPrompt(_task: Task, routing: RoutingDecision): string {
+    const parts: string[] = [
+      'You are a problem-solving agent. Your goal is to solve the given task step by step.',
+      '',
+      'For each step, provide:',
+      '1. THOUGHT: Your reasoning about what to do next',
+      '2. ACTION: The action to take',
+      '',
+      'When you have the final solution, output:',
+      'DONE: [your solution]',
+      '',
+    ];
+
+    // Add memory context
+    const memoryContext = this.memory.formatForPromptV2(routing.memoryContext);
+    if (memoryContext) {
+      parts.push('## Relevant Memory');
+      parts.push(memoryContext);
+      parts.push('');
+    }
+
+    // Add strategy-specific guidance
+    switch (routing.strategy) {
+      case 'adapt':
+        parts.push(
+          '## Guidance',
+          'A similar task has been solved successfully before. Adapt the previous solution to this task.',
+          ''
+        );
+        break;
+      case 'direct':
+        parts.push(
+          '## Guidance',
+          'Use the applicable strategies and skills from memory to guide your solution.',
+          ''
+        );
+        break;
+      case 'explore':
+        parts.push(
+          '## Guidance',
+          'Limited relevant memory found. Explore different approaches carefully.',
+          ''
+        );
+        break;
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Build task prompt
+   */
+  private buildTaskPrompt(task: Task): string {
+    const parts = [
+      `## Task`,
+      task.description,
+    ];
+
+    if (Object.keys(task.context).length > 0) {
+      parts.push('');
+      parts.push('## Context');
+      parts.push(JSON.stringify(task.context, null, 2));
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Parse LLM response into structured components
+   */
+  private parseResponse(response: string): {
+    thought: string | undefined;
+    action: string;
+    isDone: boolean;
+    solution: unknown;
+  } {
+    // Check for DONE
+    const doneMatch = response.match(/DONE:\s*(.+)/is);
+    if (doneMatch) {
+      return {
+        thought: undefined,
+        action: 'complete',
+        isDone: true,
+        solution: doneMatch[1].trim(),
+      };
+    }
+
+    // Parse THOUGHT and ACTION
+    const thoughtMatch = response.match(/THOUGHT:\s*(.+?)(?=ACTION:|$)/is);
+    const actionMatch = response.match(/ACTION:\s*(.+?)(?=THOUGHT:|$)/is);
+
+    return {
+      thought: thoughtMatch?.[1]?.trim(),
+      action: actionMatch?.[1]?.trim() ?? response.trim(),
+      isDone: false,
+      solution: null,
+    };
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<SolverConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+}
+
+/**
+ * Create a direct solver
+ *
+ * @deprecated Use createAgentManager() instead. See DirectSolver for migration guide.
+ */
+export function createSolver(
+  memory: MemorySystem,
+  provider: LLMProvider,
+  config?: Partial<SolverConfig>
+): DirectSolver {
+  return new DirectSolver(memory, provider, config);
+}