cognitive-core 0.1.0 → 0.2.0

package/src/search/moe-gate.ts

@@ -0,0 +1,304 @@
+/**
+ * MoEGate — Mixture-of-Experts inspired gating for task routing.
+ *
+ * Learns per-domain weight vectors over routing strategies from outcome
+ * feedback. Replaces threshold-based strategy selection with a learned
+ * linear gate:
+ *
+ *   gate(features) = softmax(W · features)
+ *
+ * where W is a weight matrix (one row per strategy), and features are
+ * extracted from the task + memory state.
+ *
+ * Online gradient update:
+ *   w[chosen] += learningRate * reward * features
+ *   w[others] -= learningRate * (1 - reward) * features / (numStrategies - 1)
+ *
+ * Cold start: uniform weights → falls back to existing threshold logic.
+ */
+
+/**
+ * Serialized gate state for persistence
+ */
+export interface MoEGateState {
+  strategies: string[];
+  featureSize: number;
+  globalWeights: number[][];
+  domainWeights: Record<string, number[][]>;
+  updateCount: number;
+}
+
+/**
+ * MoE-inspired gating function over routing strategies
+ */
+export class MoEGate {
+  private strategies: string[];
+  private featureSize: number;
+  private globalWeights: number[][];
+  private domainWeights: Map<string, number[][]> = new Map();
+  private updateCount = 0;
+
+  constructor(strategies: string[], featureSize: number) {
+    this.strategies = strategies;
+    this.featureSize = featureSize;
+
+    // Initialize global weights to small random values (near-uniform gate)
+    this.globalWeights = strategies.map(() =>
+      Array.from({ length: featureSize }, () => (Math.random() - 0.5) * 0.01)
+    );
+  }
+
+  /**
+   * Compute gate weights for a task given its feature vector.
+   * Returns a map of strategy → probability.
+   */
+  gate(features: number[], domain?: string): Map<string, number> {
+    const weights = this.getWeights(domain);
+    const logits = this.computeLogits(weights, features);
+    const probs = this.softmax(logits);
+
+    const result = new Map<string, number>();
+    for (let i = 0; i < this.strategies.length; i++) {
+      result.set(this.strategies[i], probs[i]);
+    }
+    return result;
+  }
+
+  /**
+   * Select the best strategy (argmax of gate output).
+   */
+  selectStrategy(features: number[], domain?: string): string {
+    const gateOutput = this.gate(features, domain);
+
+    let bestStrategy = this.strategies[0];
+    let bestProb = -1;
+    for (const [strategy, prob] of gateOutput) {
+      if (prob > bestProb) {
+        bestProb = prob;
+        bestStrategy = strategy;
+      }
+    }
+
+    return bestStrategy;
+  }
+
+  /**
+   * Update weights from outcome feedback (online gradient).
+   *
+   * Positive reward → increase weight for chosen strategy's features.
+   * Negative reward → decrease weight.
+   */
+  update(
+    features: number[],
+    chosenStrategy: string,
+    reward: number,
+    learningRate = 0.01,
+    domain?: string
+  ): void {
+    const chosenIdx = this.strategies.indexOf(chosenStrategy);
+    if (chosenIdx === -1) return;
+
+    // Update global weights
+    this.updateWeightMatrix(this.globalWeights, features, chosenIdx, reward, learningRate);
+
+    // Update domain-specific weights if domain provided
+    if (domain) {
+      if (!this.domainWeights.has(domain)) {
+        // Initialize domain weights as copy of global
+        this.domainWeights.set(
+          domain,
+          this.globalWeights.map((row) => [...row])
+        );
+      }
+      const domainW = this.domainWeights.get(domain)!;
+      this.updateWeightMatrix(domainW, features, chosenIdx, reward, learningRate);
+    }
+
+    this.updateCount++;
+  }
+
+  /**
+   * Whether the gate has been trained (has seen any updates).
+   */
+  get isTrained(): boolean {
+    return this.updateCount > 0;
+  }
+
+  /**
+   * Number of updates the gate has seen.
+   */
+  get totalUpdates(): number {
+    return this.updateCount;
+  }
+
+  /**
+   * Serialize for persistence.
+   */
+  toJSON(): MoEGateState {
+    const domainWeights: Record<string, number[][]> = {};
+    for (const [domain, weights] of this.domainWeights) {
+      domainWeights[domain] = weights;
+    }
+
+    return {
+      strategies: this.strategies,
+      featureSize: this.featureSize,
+      globalWeights: this.globalWeights,
+      domainWeights,
+      updateCount: this.updateCount,
+    };
+  }
+
+  /**
+   * Deserialize from persisted state.
+   */
+  static fromJSON(data: MoEGateState): MoEGate {
+    const gate = new MoEGate(data.strategies, data.featureSize);
+    gate.globalWeights = data.globalWeights;
+    gate.updateCount = data.updateCount;
+
+    for (const [domain, weights] of Object.entries(data.domainWeights)) {
+      gate.domainWeights.set(domain, weights);
+    }
+
+    return gate;
+  }
+
+  // === Internal ===
+
+  /**
+   * Get the weight matrix for a domain (with fallback to global).
+   */
+  private getWeights(domain?: string): number[][] {
+    if (domain && this.domainWeights.has(domain)) {
+      return this.domainWeights.get(domain)!;
+    }
+    return this.globalWeights;
+  }
+
+  /**
+   * Compute logits = W · features for each strategy.
+   */
+  private computeLogits(weights: number[][], features: number[]): number[] {
+    return weights.map((row) => {
+      let sum = 0;
+      for (let j = 0; j < Math.min(row.length, features.length); j++) {
+        sum += row[j] * features[j];
+      }
+      return sum;
+    });
+  }
+
+  /**
+   * Softmax with numerical stability (subtract max).
+   */
+  private softmax(logits: number[]): number[] {
+    const max = Math.max(...logits);
+    const exps = logits.map((l) => Math.exp(l - max));
+    const sum = exps.reduce((a, b) => a + b, 0);
+    return exps.map((e) => e / sum);
+  }
+
+  /**
+   * Online gradient update on a weight matrix.
+   *
+   * Uses centered reward (reward - 0.5) so that:
+   *   reward=1 → positive update for chosen, negative for others
+   *   reward=0 → negative update for chosen, positive for others
+   */
+  private updateWeightMatrix(
+    weights: number[][],
+    features: number[],
+    chosenIdx: number,
+    reward: number,
+    learningRate: number
+  ): void {
+    const numStrategies = this.strategies.length;
+    const centered = reward - 0.5; // range: [-0.5, 0.5]
+
+    for (let i = 0; i < numStrategies; i++) {
+      for (let j = 0; j < this.featureSize; j++) {
+        if (i === chosenIdx) {
+          // Positive reward → boost chosen; negative → penalize chosen
+          weights[i][j] += learningRate * centered * features[j];
+        } else {
+          // Opposite direction for unchosen strategies
+          weights[i][j] -=
+            learningRate * centered * features[j] / (numStrategies - 1);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Extract feature vector from a task and memory context for the MoE gate.
+ *
+ * Features (8 dimensions):
+ * 0: task description length (normalized)
+ * 1: domain familiarity (experience count, normalized)
+ * 2: best experience match score
+ * 3: best playbook match score
+ * 4: best playbook confidence
+ * 5: is bug fix (0/1)
+ * 6: is new feature (0/1)
+ * 7: task complexity proxy (word count, normalized)
+ */
+export function extractTaskFeatures(
+  taskDescription: string,
+  memoryContext: {
+    experiences: Array<{ score: number }>;
+    playbooks: Array<{ score: number; playbook: { confidence: number } }>;
+  },
+  experienceCountInDomain = 0
+): number[] {
+  const desc = taskDescription.toLowerCase();
+
+  const bestExpScore = memoryContext.experiences.length > 0
+    ? Math.max(...memoryContext.experiences.map((e) => e.score))
+    : 0;
+
+  const bestPlaybookScore = memoryContext.playbooks.length > 0
+    ? Math.max(...memoryContext.playbooks.map((p) => p.score))
+    : 0;
+
+  const bestPlaybookConfidence = memoryContext.playbooks.length > 0
+    ? Math.max(...memoryContext.playbooks.map((p) => p.playbook.confidence))
+    : 0;
+
+  const isBugFix =
+    desc.includes('bug') || desc.includes('fix') || desc.includes('error')
+      ? 1
+      : 0;
+
+  const isNewFeature =
+    desc.includes('implement') || desc.includes('create') || desc.includes('add')
+      ? 1
+      : 0;
+
+  const wordCount = taskDescription.split(/\s+/).length;
+
+  return [
+    Math.min(taskDescription.length / 1000, 1),     // [0] length, normalized
+    Math.min(experienceCountInDomain / 100, 1),      // [1] domain familiarity
+    bestExpScore,                                     // [2] best experience match
+    bestPlaybookScore,                                // [3] best playbook match
+    bestPlaybookConfidence,                           // [4] best playbook confidence
+    isBugFix,                                         // [5] bug fix indicator
+    isNewFeature,                                     // [6] new feature indicator
+    Math.min(wordCount / 100, 1),                     // [7] complexity proxy
+  ];
+}
+
+/** Default feature size for the MoE gate */
+export const MOE_FEATURE_SIZE = 8;
+
+/** Default strategies for the MoE gate */
+export const MOE_STRATEGIES = ['direct', 'adapt', 'explore', 'fallback'] as const;
+
+/**
+ * Create a MoEGate with default settings
+ */
+export function createMoEGate(): MoEGate {
+  return new MoEGate([...MOE_STRATEGIES], MOE_FEATURE_SIZE);
+}

package/src/search/refinement-loop.ts

@@ -13,6 +13,8 @@ import type { Trajectory } from '../types/trajectory.js';
 import type { AgentManager } from '../runtime/manager.js';
 import type { MemorySystem, MemoryQueryResultV2 } from '../memory/system.js';
 import type { AgentSpawnConfig } from '../runtime/types.js';
+import type { AgenticTaskRunner } from '../workspace/runner.js';
+import { refinementAnalysisTemplate, type RefinementPlan } from '../workspace/templates/refinement-analysis.js';
 import {
   type RefinementResult,
   type EvaluationResult,
@@ -59,6 +61,7 @@ const DEFAULT_CONFIG: Required<RefinementLoopConfig> = {
 export class RefinementLoop {
   private agentManager: AgentManager;
   private memory: MemorySystem;
+  private taskRunner: AgenticTaskRunner | null = null;
   private evaluator: SolutionEvaluator;
   private config: Required<RefinementLoopConfig>;
 
@@ -76,6 +79,16 @@ export class RefinementLoop {
     );
   }
 
+  /**
+   * Set the task runner for workspace-based analysis.
+   * Enables structured refinement plans via refinementAnalysisTemplate,
+   * and delegates evaluation to solutionEvaluationTemplate.
+   */
+  setTaskRunner(runner: AgenticTaskRunner): void {
+    this.taskRunner = runner;
+    this.evaluator.setTaskRunner(runner);
+  }
+
   /**
    * Get the evaluator for registering domain verifiers
    */
@@ -149,21 +162,33 @@ export class RefinementLoop {
         previousAttempts: iteration + 1,
       };
 
-      // Query memory for similar failures if enabled
-      let failureMemory: MemoryQueryResultV2 | undefined;
-      if (this.config.queryFailureMemory) {
-        failureMemory = await this.queryFailurePatterns(
-          spawnConfig.task,
-          failureContext
+      // Get refinement strategy: workspace-based when runner available
+      let refinementAdditions: string;
+      const plan = await this.getRefinementPlan(
+        currentTrajectory,
+        spawnConfig.task,
+        evaluations[evaluations.length - 1],
+        iteration + 1,
+      );
+
+      if (plan) {
+        // Use structured plan from template
+        refinementAdditions = this.formatRefinementPlan(plan, failureContext);
+      } else {
+        // Fallback: build prompt with memory-based context
+        let failureMemory: MemoryQueryResultV2 | undefined;
+        if (this.config.queryFailureMemory) {
+          failureMemory = await this.queryFailurePatterns(
+            spawnConfig.task,
+            failureContext
+          );
+        }
+        refinementAdditions = this.buildRefinementPrompt(
+          failureContext,
+          failureMemory
         );
       }
 
-      // Build refinement prompt
-      const refinementAdditions = this.buildRefinementPrompt(
-        failureContext,
-        failureMemory
-      );
-
       // Spawn refined agent
       const refinedConfig: AgentSpawnConfig = {
         ...spawnConfig,
@@ -216,6 +241,75 @@ export class RefinementLoop {
     };
   }
 
+  /**
+   * Get a structured refinement plan via the workspace template.
+   * Returns null if taskRunner is unavailable or the template fails.
+   */
+  private async getRefinementPlan(
+    trajectory: Trajectory,
+    task: Task,
+    evaluation: EvaluationResult,
+    previousAttempts: number,
+  ): Promise<RefinementPlan | null> {
+    if (!this.taskRunner) return null;
+
+    try {
+      const result = await this.taskRunner.run(refinementAnalysisTemplate, {
+        trajectory,
+        task,
+        evaluation,
+        previousAttempts,
+      });
+      return result.output;
+    } catch (error) {
+      console.warn(
+        'Workspace-based refinement analysis failed, falling back to heuristic:',
+        error instanceof Error ? error.message : String(error)
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Format a structured RefinementPlan into prompt additions for the retry agent.
+   */
+  private formatRefinementPlan(
+    plan: RefinementPlan,
+    failureContext: FailureContext,
+  ): string {
+    const parts: string[] = [];
+
+    parts.push('## Root Cause Analysis');
+    parts.push('');
+    parts.push(`Previous attempt #${failureContext.previousAttempts} failed. Root causes identified:`);
+    for (const cause of plan.rootCauses) {
+      parts.push(`- ${cause}`);
+    }
+
+    parts.push('');
+    parts.push('## Recommended Strategy');
+    parts.push('');
+    parts.push(plan.strategy);
+
+    if (plan.steps.length > 0) {
+      parts.push('');
+      parts.push('## Specific Steps');
+      for (let i = 0; i < plan.steps.length; i++) {
+        parts.push(`${i + 1}. ${plan.steps[i]}`);
+      }
+    }
+
+    if (plan.avoidPatterns.length > 0) {
+      parts.push('');
+      parts.push('## Patterns to Avoid');
+      for (const pattern of plan.avoidPatterns) {
+        parts.push(`- DO NOT: ${pattern}`);
+      }
+    }
+
+    return parts.join('\n');
+  }
+
   /**
    * Query memory for similar failure patterns
    */

package/src/search/router.ts

@@ -1,6 +1,13 @@
 import type { Task, RouterConfig } from '../types/index.js';
 import type { MemorySystem, MemoryQueryResultV2 } from '../memory/system.js';
 import type { MetaLearner } from '../learning/meta-learner.js';
+import type { SqlitePersistence } from '../persistence/index.js';
+import {
+  MoEGate,
+  extractTaskFeatures,
+  createMoEGate,
+  type MoEGateState,
+} from './moe-gate.js';
 
 /**
  * Routing decision with context
@@ -29,11 +36,15 @@ export class TaskRouter {
   private memory: MemorySystem;
   private config: RouterConfig;
   private metaLearner?: MetaLearner;
+  private moeGate: MoEGate;
+  private persistence?: SqlitePersistence;
+  private gateUpdatesSinceLastPersist = 0;
 
   constructor(
     memory: MemorySystem,
     config?: Partial<RouterConfig>,
-    metaLearner?: MetaLearner
+    metaLearner?: MetaLearner,
+    persistence?: SqlitePersistence
   ) {
     this.memory = memory;
     this.config = {
@@ -42,6 +53,16 @@ export class TaskRouter {
       defaultStrategy: config?.defaultStrategy ?? 'direct',
     };
     this.metaLearner = metaLearner;
+    this.persistence = persistence;
+    this.moeGate = createMoEGate();
+
+    // Load persisted gate state if available
+    if (persistence?.isInitialized) {
+      const saved = persistence.getSystemState<MoEGateState>('moe_gate');
+      if (saved) {
+        this.moeGate = MoEGate.fromJSON(saved);
+      }
+    }
   }
 
   /**
@@ -61,9 +82,30 @@ export class TaskRouter {
       domains: task.domain ? [task.domain] : undefined,
     });
 
-    // Compute base routing from playbook memory
+    // Compute base routing from playbook memory (threshold heuristics)
     let decision = this.computeBaseRouting(memoryContext);
 
+    // If MoE gate is trained, use it to override the base strategy
+    if (this.moeGate.isTrained) {
+      try {
+        const features = extractTaskFeatures(
+          task.description,
+          memoryContext,
+        );
+        const gateStrategy = this.moeGate.selectStrategy(features, task.domain);
+        if (this.isValidStrategy(gateStrategy)) {
+          decision.strategy = gateStrategy as RoutingDecision['strategy'];
+          decision.reasoning = `MoE gate selected strategy (${this.moeGate.totalUpdates} updates). ${decision.reasoning}`;
+          decision.appliedMetaStrategies = [
+            ...(decision.appliedMetaStrategies ?? []),
+            'moe-gate',
+          ];
+        }
+      } catch {
+        // Gate failed — continue with base routing
+      }
+    }
+
     // Apply meta-learning adjustments if available
     if (this.metaLearner) {
       const taskCharacteristics = this.extractTaskCharacteristics(task);
@@ -241,12 +283,76 @@ export class TaskRouter {
     return state;
   }
 
+  /**
+   * Update MoE gate weights after a trajectory completes.
+   * reward: 1 = success, 0.5 = partial, 0 = failure
+   */
+  updateGate(
+    task: Task,
+    memoryContext: MemoryQueryResultV2,
+    chosenStrategy: string,
+    reward: number
+  ): void {
+    const features = extractTaskFeatures(task.description, memoryContext);
+    this.moeGate.update(features, chosenStrategy, reward, 0.01, task.domain);
+
+    // Persist gate state every 10 updates
+    this.gateUpdatesSinceLastPersist++;
+    if (this.persistence && this.gateUpdatesSinceLastPersist >= 10) {
+      this.persistence.setSystemState('moe_gate', this.moeGate.toJSON());
+      this.gateUpdatesSinceLastPersist = 0;
+    }
+  }
+
+  /**
+   * Flush gate state to persistence (e.g., on shutdown).
+   */
+  persistGateState(): void {
+    if (this.persistence && this.moeGate.isTrained) {
+      this.persistence.setSystemState('moe_gate', this.moeGate.toJSON());
+      this.gateUpdatesSinceLastPersist = 0;
+    }
+  }
+
+  /**
+   * Load persisted gate state. Call after persistence is initialized.
+   */
+  loadPersistedState(): void {
+    if (this.persistence?.isInitialized) {
+      const saved = this.persistence.getSystemState<MoEGateState>('moe_gate');
+      if (saved) {
+        this.moeGate = MoEGate.fromJSON(saved);
+      }
+    }
+  }
+
+  /**
+   * Get the MoE gate (for persistence or inspection).
+   */
+  getMoEGate(): MoEGate {
+    return this.moeGate;
+  }
+
+  /**
+   * Load MoE gate state from persisted data.
+   */
+  loadGateState(state: MoEGateState): void {
+    this.moeGate = MoEGate.fromJSON(state);
+  }
+
   /**
    * Update configuration
    */
   updateConfig(config: Partial<RouterConfig>): void {
     this.config = { ...this.config, ...config };
   }
+
+  /**
+   * Check if a string is a valid routing strategy.
+   */
+  private isValidStrategy(s: string): boolean {
+    return ['direct', 'adapt', 'explore', 'fallback'].includes(s);
+  }
 }
 
 /**
@@ -255,7 +361,8 @@ export class TaskRouter {
 export function createRouter(
   memory: MemorySystem,
   config?: Partial<RouterConfig>,
-  metaLearner?: MetaLearner
+  metaLearner?: MetaLearner,
+  persistence?: SqlitePersistence
 ): TaskRouter {
-  return new TaskRouter(memory, config, metaLearner);
+  return new TaskRouter(memory, config, metaLearner, persistence);
 }