cognitive-core 0.1.2 → 0.2.1

package/src/runtime/flows/learning.ts

@@ -1,6 +1,10 @@
 import type { Task } from '../../types/index.js';
 import type { MemorySystem } from '../../memory/system.js';
-import type { LearningPipeline, ProcessResult, BatchResult } from '../../learning/index.js';
+import type {
+  UnifiedLearningPipeline,
+  ImmediateResult,
+  UnifiedBatchResult,
+} from '../../learning/unified-pipeline.js';
 import type { AgentManager } from '../manager.js';
 import type { AgentResult, AgentSession, AgentObserverCallbacks } from '../types.js';
 
@@ -10,9 +14,7 @@ import type { AgentResult, AgentSession, AgentObserverCallbacks } from '../types
 export interface LearningFlowConfig {
   /** Agent type to use for execution */
   agentType: string;
-  /** Minimum trajectories before running batch learning */
-  batchThreshold?: number;
-  /** Whether to auto-run batch learning when threshold is reached */
+  /** Whether to auto-run batch learning when energy threshold is reached */
   autoBatch?: boolean;
   /** Observer callbacks for real-time monitoring */
   observer?: AgentObserverCallbacks;
@@ -24,10 +26,10 @@ export interface LearningFlowConfig {
 export interface LearningFlowResult {
   /** The agent result */
   agentResult: AgentResult;
-  /** Processing result from learning pipeline */
-  processResult: ProcessResult;
-  /** Batch result if batch learning was triggered */
-  batchResult?: BatchResult;
+  /** Processing result from learning pipeline (immediate phase) */
+  immediateResult: ImmediateResult;
+  /** Batch result if batch learning was triggered (included in immediateResult) */
+  batchResult?: UnifiedBatchResult;
 }
 
 /**
@@ -41,19 +43,18 @@ export interface LearningFlowResult {
  */
 export class LearningFlow {
   private manager: AgentManager;
-  private pipeline: LearningPipeline;
+  private pipeline: UnifiedLearningPipeline;
   private config: LearningFlowConfig;
 
   constructor(
     manager: AgentManager,
-    pipeline: LearningPipeline,
+    pipeline: UnifiedLearningPipeline,
     _memory: MemorySystem,
     config: LearningFlowConfig
   ) {
     this.manager = manager;
     this.pipeline = pipeline;
     this.config = {
-      batchThreshold: 10,
       autoBatch: true,
       ...config,
     };
@@ -75,24 +76,15 @@ export class LearningFlow {
       captureToolCalls: true,
     });
 
-    // 2. Process trajectory through learning pipeline
-    const processResult = await this.pipeline.processTrajectory(
+    // 2. Process trajectory through unified pipeline (immediate + optional batch)
+    const immediateResult = await this.pipeline.processTrajectory(
       agentResult.trajectory
     );
 
-    // 3. Run batch learning if threshold reached
-    let batchResult: BatchResult | undefined;
-    if (
-      this.config.autoBatch &&
-      this.pipeline.getAccumulatedCount() >= (this.config.batchThreshold ?? 10)
-    ) {
-      batchResult = await this.pipeline.runBatchLearning();
-    }
-
     return {
       agentResult,
-      processResult,
-      batchResult,
+      immediateResult,
+      batchResult: immediateResult.batchResult,
     };
   }
 
@@ -119,17 +111,8 @@ export class LearningFlow {
     // Extract trajectory from session
     const trajectory = await this.manager.observeAndLearn(session, task);
 
-    // Process through learning pipeline
-    const processResult = await this.pipeline.processTrajectory(trajectory);
-
-    // Check for batch learning
-    let batchResult: BatchResult | undefined;
-    if (
-      this.config.autoBatch &&
-      this.pipeline.getAccumulatedCount() >= (this.config.batchThreshold ?? 10)
-    ) {
-      batchResult = await this.pipeline.runBatchLearning();
-    }
+    // Process through unified pipeline
+    const immediateResult = await this.pipeline.processTrajectory(trajectory);
 
     return {
       agentResult: {
@@ -144,16 +127,16 @@ export class LearningFlow {
           messageCount: session.messages.length,
         },
       },
-      processResult,
-      batchResult,
+      immediateResult,
+      batchResult: immediateResult.batchResult,
     };
   }
 
   /**
    * Force batch learning
    */
-  async runBatchLearning(): Promise<BatchResult> {
-    return this.pipeline.runBatchLearning();
+  async runBatchLearning(): Promise<UnifiedBatchResult> {
+    return this.pipeline.runBatch();
   }
 
   /**
@@ -161,11 +144,11 @@ export class LearningFlow {
    */
   getStats(): {
     pendingTrajectories: number;
-    batchThreshold: number;
+    pipelineStats: ReturnType<UnifiedLearningPipeline['getStats']>;
   } {
     return {
       pendingTrajectories: this.pipeline.getAccumulatedCount(),
-      batchThreshold: this.config.batchThreshold ?? 10,
+      pipelineStats: this.pipeline.getStats(),
     };
   }
 }
@@ -175,7 +158,7 @@ export class LearningFlow {
  */
 export function createLearningFlow(
   manager: AgentManager,
-  pipeline: LearningPipeline,
+  pipeline: UnifiedLearningPipeline,
   memory: MemorySystem,
   config: LearningFlowConfig
 ): LearningFlow {

package/src/search/index.ts

@@ -4,6 +4,16 @@ export {
   type RoutingDecision,
 } from './router.js';
 
+// MoE-inspired routing gate
+export {
+  MoEGate,
+  createMoEGate,
+  extractTaskFeatures,
+  MOE_FEATURE_SIZE,
+  MOE_STRATEGIES,
+  type MoEGateState,
+} from './moe-gate.js';
+
 export {
   DirectSolver,
   createSolver,

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/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);
 }