cognitive-core 0.0.2 → 0.1.2

package/src/learning/meta-learner.ts

@@ -0,0 +1,570 @@
+/**
+ * Meta Learner
+ * Learns about learning - analyzes trajectories to improve routing and retrieval
+ */
+
+import type {
+  MetaObservation,
+  MetaStrategy,
+  Trajectory,
+  MetaContext,
+  RoutingDecisionType,
+  RetrievalQuality,
+  OutcomeQuality,
+  Step,
+} from '../types/index.js';
+import { createMetaObservation, createMetaStrategy } from '../types/index.js';
+import type { MetaMemory } from '../memory/meta.js';
+import type { PlaybookMatch } from '../memory/playbook.js';
+import type { MetaReflectionOutput } from '../workspace/templates/meta-reflection.js';
+
+/**
+ * Routing decision from the router
+ */
+export interface RoutingDecision {
+  strategy: RoutingDecisionType;
+  confidence: number;
+  estimatedBudget: number;
+  reasoning: string;
+}
+
+/**
+ * Configuration for meta learner
+ */
+export interface MetaLearnerConfig {
+  /** Minimum observations before generating strategies */
+  minObservationsForStrategies: number;
+  /** How often to run strategy generation (in observations) */
+  strategyGenerationInterval: number;
+  /** Threshold for considering retrieval helpful */
+  helpfulRetrievalThreshold: number;
+  /** Minimum tactic word overlap to consider guidance followed (default: 2) */
+  tacticOverlapThreshold: number;
+}
+
+const DEFAULT_CONFIG: MetaLearnerConfig = {
+  minObservationsForStrategies: 10,
+  strategyGenerationInterval: 10,
+  helpfulRetrievalThreshold: 0.7,
+  tacticOverlapThreshold: 2,
+};
+
+/**
+ * Meta Learner
+ * Generates meta-observations and learns meta-strategies
+ */
+export class MetaLearner {
+  private meta: MetaMemory;
+  private config: MetaLearnerConfig;
+  private observationCount = 0;
+
+  constructor(meta: MetaMemory, config?: Partial<MetaLearnerConfig>) {
+    this.meta = meta;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Generate reflection from completed trajectory
+   */
+  async generateReflection(
+    trajectory: Trajectory,
+    routing: RoutingDecision,
+    playbooksUsed: PlaybookMatch[]
+  ): Promise<MetaObservation> {
+    // Analyze the trajectory
+    const wasSuccessful = trajectory.outcome.success;
+    const actualEffort = trajectory.llmCalls ?? trajectory.steps.length;
+
+    // Determine retrieval quality
+    const retrievalQuality = this.assessRetrievalQuality(
+      trajectory,
+      playbooksUsed,
+      wasSuccessful
+    );
+
+    // Determine outcome quality
+    const outcomeQuality = this.assessOutcomeQuality(trajectory, actualEffort, routing.estimatedBudget);
+
+    // Analyze execution path
+    const execution = this.analyzeExecution(trajectory);
+
+    // Generate lessons learned
+    const lessons = this.generateLessons(
+      trajectory,
+      routing,
+      playbooksUsed,
+      wasSuccessful
+    );
+
+    const observation = createMetaObservation({
+      trajectoryId: trajectory.id,
+      routing: {
+        decision: routing.strategy,
+        confidence: routing.confidence,
+        reasoning: routing.reasoning,
+      },
+      memoryUsage: {
+        experiencesRetrieved: 0, // TODO: Track from memory query
+        playbooksApplied: playbooksUsed.map((p) => p.playbook.id),
+        retrievalQuality,
+      },
+      execution,
+      outcome: {
+        success: wasSuccessful,
+        quality: outcomeQuality,
+        effortActual: actualEffort,
+        effortEstimate: routing.estimatedBudget,
+      },
+      lessons,
+    });
+
+    // Record the observation
+    await this.meta.recordObservation(observation);
+    this.observationCount++;
+
+    // Periodically generate new meta-strategies
+    if (this.observationCount % this.config.strategyGenerationInterval === 0) {
+      await this.learn();
+    }
+
+    return observation;
+  }
+
+  /**
+   * Record a meta-observation from workspace-based reflection output.
+   * Bridges MetaReflectionOutput (from the meta-reflection template)
+   * into the MetaObservation storage format.
+   */
+  async recordFromReflection(
+    reflection: MetaReflectionOutput,
+    trajectoryId: string,
+    routing: RoutingDecision,
+    playbookIds: string[],
+    actualEffort: number,
+  ): Promise<MetaObservation> {
+    const observation = createMetaObservation({
+      trajectoryId,
+      routing: {
+        decision: routing.strategy,
+        confidence: routing.confidence,
+        reasoning: routing.reasoning,
+      },
+      memoryUsage: {
+        experiencesRetrieved: 0,
+        playbooksApplied: playbookIds,
+        retrievalQuality: reflection.retrievalQuality,
+      },
+      execution: {
+        decompositionUsed: reflection.decompositionUsed,
+        refinementIterations: reflection.refinementIterations,
+        backtrackingOccurred: reflection.backtrackingOccurred,
+        toolsUsed: [],
+      },
+      outcome: {
+        success: reflection.outcomeQuality !== 'poor',
+        quality: reflection.outcomeQuality,
+        effortActual: actualEffort,
+        effortEstimate: routing.estimatedBudget,
+      },
+      lessons: {
+        whatWorked: reflection.whatWorked,
+        whatFailed: reflection.whatFailed,
+        suggestions: reflection.suggestions,
+      },
+    });
+
+    await this.meta.recordObservation(observation);
+    this.observationCount++;
+
+    if (this.observationCount % this.config.strategyGenerationInterval === 0) {
+      await this.learn();
+    }
+
+    return observation;
+  }
+
+  /**
+   * Analyze accumulated observations and generate meta-strategies
+   */
+  async learn(): Promise<MetaStrategy[]> {
+    const stats = await this.meta.getStats();
+
+    if (stats.totalObservations < this.config.minObservationsForStrategies) {
+      return [];
+    }
+
+    // Generate new meta-strategies based on patterns
+    const newStrategies = await this.meta.generateMetaStrategies();
+
+    // Additional strategy generation based on analysis
+    const routingAnalysis = await this.meta.analyzeRoutingEffectiveness();
+    const additionalStrategies = this.generateStrategiesFromAnalysis(routingAnalysis);
+
+    // Add and save additional strategies
+    for (const strategy of additionalStrategies) {
+      const existing = await this.meta.getStrategy(strategy.id);
+      if (!existing) {
+        await this.meta.addStrategy(strategy);
+        newStrategies.push(strategy);
+      }
+    }
+
+    return newStrategies;
+  }
+
+  /**
+   * Apply meta-strategies to adjust routing
+   */
+  async adjustRouting(
+    baseRouting: RoutingDecision,
+    taskCharacteristics: string[],
+    memoryState: string[]
+  ): Promise<RoutingDecision> {
+    const context: MetaContext = {
+      taskCharacteristics,
+      memoryState,
+    };
+
+    const applicableStrategies = await this.meta.getRoutingAdjustments(context);
+
+    if (applicableStrategies.length === 0) {
+      return baseRouting;
+    }
+
+    // Apply adjustments
+    let adjustedConfidence = baseRouting.confidence;
+    let adjustedStrategy = baseRouting.strategy;
+    const adjustmentReasons: string[] = [];
+
+    for (const strategy of applicableStrategies) {
+      // Apply routing bias
+      if (strategy.adjustment.routingBias) {
+        for (const [decision, bias] of Object.entries(strategy.adjustment.routingBias)) {
+          if (decision === baseRouting.strategy) {
+            adjustedConfidence += bias as number;
+          }
+        }
+
+        // Check if another strategy is strongly preferred
+        const biases = Object.entries(strategy.adjustment.routingBias);
+        for (const [decision, bias] of biases) {
+          if (
+            (bias as number) > 0.3 &&
+            decision !== baseRouting.strategy &&
+            baseRouting.confidence < 0.5
+          ) {
+            adjustedStrategy = decision as RoutingDecisionType;
+            adjustmentReasons.push(
+              `Meta-strategy '${strategy.name}' suggests ${decision}`
+            );
+          }
+        }
+      }
+
+      // Add execution hint to reasoning
+      if (strategy.adjustment.executionHint) {
+        adjustmentReasons.push(strategy.adjustment.executionHint);
+      }
+    }
+
+    // Clamp confidence
+    adjustedConfidence = Math.max(0.1, Math.min(0.95, adjustedConfidence));
+
+    return {
+      strategy: adjustedStrategy,
+      confidence: adjustedConfidence,
+      estimatedBudget: baseRouting.estimatedBudget,
+      reasoning:
+        adjustmentReasons.length > 0
+          ? `${baseRouting.reasoning}. Meta-adjustments: ${adjustmentReasons.join('; ')}`
+          : baseRouting.reasoning,
+    };
+  }
+
+  /**
+   * Assess retrieval quality based on trajectory outcome
+   */
+  private assessRetrievalQuality(
+    trajectory: Trajectory,
+    playbooksUsed: PlaybookMatch[],
+    wasSuccessful: boolean
+  ): RetrievalQuality {
+    if (playbooksUsed.length === 0) {
+      return 'neutral';
+    }
+
+    // Check if playbook guidance was followed
+    const guidanceFollowed = this.checkGuidanceFollowed(trajectory, playbooksUsed);
+
+    if (wasSuccessful && guidanceFollowed) {
+      return 'helpful';
+    } else if (!wasSuccessful && guidanceFollowed) {
+      // Followed guidance but still failed - might be misleading
+      return 'misleading';
+    } else {
+      return 'neutral';
+    }
+  }
+
+  /**
+   * Check if playbook guidance was followed in the trajectory
+   */
+  private checkGuidanceFollowed(
+    trajectory: Trajectory,
+    playbooksUsed: PlaybookMatch[]
+  ): boolean {
+    for (const { playbook } of playbooksUsed) {
+      const tactics = playbook.guidance.tactics;
+      if (tactics.length === 0) continue;
+
+      // Check if any tactics were reflected in the steps
+      let tacticsFollowed = 0;
+      for (const tactic of tactics) {
+        const tacticWords = tactic.toLowerCase().split(/\s+/);
+        for (const step of trajectory.steps) {
+          const actionWords = step.action.toLowerCase().split(/\s+/);
+          const overlap = tacticWords.filter((w) => actionWords.includes(w)).length;
+          if (overlap >= this.config.tacticOverlapThreshold) {
+            tacticsFollowed++;
+            break;
+          }
+        }
+      }
+
+      if (tacticsFollowed >= tactics.length * 0.5) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Assess outcome quality
+   */
+  private assessOutcomeQuality(
+    trajectory: Trajectory,
+    actualEffort: number,
+    estimatedEffort: number
+  ): OutcomeQuality {
+    if (!trajectory.outcome.success) {
+      return 'poor';
+    }
+
+    // Compare actual vs estimated effort
+    const effortRatio = actualEffort / estimatedEffort;
+
+    if (effortRatio <= 0.5) {
+      return 'excellent'; // Much less effort than expected
+    } else if (effortRatio <= 1.0) {
+      return 'good'; // Within estimate
+    } else if (effortRatio <= 2.0) {
+      return 'acceptable'; // Some overrun
+    } else {
+      return 'poor'; // Significant overrun
+    }
+  }
+
+  /**
+   * Analyze execution path
+   */
+  private analyzeExecution(trajectory: Trajectory): {
+    decompositionUsed: boolean;
+    refinementIterations: number;
+    backtrackingOccurred: boolean;
+    toolsUsed: string[];
+  } {
+    const steps = trajectory.steps;
+    const toolsUsed = new Set<string>();
+    let backtrackingOccurred = false;
+
+    // Collect tools used (extract from action)
+    for (const step of steps) {
+      // Try to extract tool name from action (e.g., "tool_use: Bash" or just "Bash")
+      const toolMatch = step.action.match(/^(?:tool_use:\s*)?(\w+)/);
+      if (toolMatch) {
+        toolsUsed.add(toolMatch[1]);
+      }
+    }
+
+    // Check for backtracking (similar actions repeated)
+    const actionCounts = new Map<string, number>();
+    for (const step of steps) {
+      const normalized = step.action.toLowerCase().slice(0, 50);
+      actionCounts.set(normalized, (actionCounts.get(normalized) ?? 0) + 1);
+    }
+
+    for (const count of actionCounts.values()) {
+      if (count > 2) {
+        backtrackingOccurred = true;
+        break;
+      }
+    }
+
+    // Check for decomposition (multiple sub-tasks)
+    const decompositionUsed =
+      steps.some(
+        (s: Step) =>
+          s.thought?.includes('break') ||
+          s.thought?.includes('decompose') ||
+          s.thought?.includes('step by step') ||
+          s.thought?.includes('first,')
+      ) ?? false;
+
+    // Estimate refinement iterations (failures followed by retries)
+    let refinementIterations = 0;
+    for (let i = 0; i < steps.length - 1; i++) {
+      if (
+        steps[i].observation?.includes('error') ||
+        steps[i].observation?.includes('failed')
+      ) {
+        if (steps[i + 1]?.thought?.includes('try') || steps[i + 1]?.thought?.includes('fix')) {
+          refinementIterations++;
+        }
+      }
+    }
+
+    return {
+      decompositionUsed,
+      refinementIterations,
+      backtrackingOccurred,
+      toolsUsed: Array.from(toolsUsed),
+    };
+  }
+
+  /**
+   * Generate lessons learned
+   */
+  private generateLessons(
+    trajectory: Trajectory,
+    routing: RoutingDecision,
+    playbooksUsed: PlaybookMatch[],
+    wasSuccessful: boolean
+  ): {
+    whatWorked: string[];
+    whatFailed: string[];
+    suggestions: string[];
+  } {
+    const whatWorked: string[] = [];
+    const whatFailed: string[] = [];
+    const suggestions: string[] = [];
+
+    if (wasSuccessful) {
+      whatWorked.push(`${routing.strategy} routing led to success`);
+
+      if (playbooksUsed.length > 0) {
+        whatWorked.push(
+          `Playbook guidance was applicable: ${playbooksUsed.map((p) => p.playbook.name).join(', ')}`
+        );
+      }
+
+      // Check what steps seemed most effective
+      const keySteps = trajectory.steps.filter(
+        (s: Step) =>
+          !s.observation?.includes('error') && !s.observation?.includes('failed')
+      );
+      if (keySteps.length > 0) {
+        whatWorked.push(
+          `Effective actions: ${keySteps
+            .slice(0, 3)
+            .map((s: Step) => s.action.slice(0, 50))
+            .join(', ')}`
+        );
+      }
+    } else {
+      whatFailed.push(`${routing.strategy} routing did not lead to success`);
+
+      // Check what went wrong
+      const errorSteps = trajectory.steps.filter(
+        (s: Step) =>
+          s.observation?.includes('error') || s.observation?.includes('failed')
+      );
+      if (errorSteps.length > 0) {
+        whatFailed.push(
+          `Errors encountered: ${errorSteps
+            .slice(0, 2)
+            .map((s: Step) => s.observation?.slice(0, 100))
+            .join('; ')}`
+        );
+      }
+
+      // Suggestions based on failure
+      if (routing.confidence > 0.7) {
+        suggestions.push('High confidence did not guarantee success - consider more exploration');
+      }
+
+      if (playbooksUsed.length > 0) {
+        suggestions.push('Review playbook applicability - guidance may need refinement');
+      } else {
+        suggestions.push('No playbooks were applied - consider extracting patterns from similar tasks');
+      }
+    }
+
+    return { whatWorked, whatFailed, suggestions };
+  }
+
+  /**
+   * Generate strategies from routing analysis
+   */
+  private generateStrategiesFromAnalysis(
+    analysis: {
+      byDecision: Record<string, { total: number; successful: number }>;
+      recommendations: string[];
+    }
+  ): MetaStrategy[] {
+    const strategies: MetaStrategy[] = [];
+
+    // Generate strategy based on success rates
+    for (const [decision, stats] of Object.entries(analysis.byDecision)) {
+      if (stats.total < 5) continue;
+
+      const successRate = stats.successful / stats.total;
+
+      if (successRate < 0.4) {
+        // This decision often fails
+        strategies.push(
+          createMetaStrategy({
+            name: `avoid-${decision}-low-success`,
+            condition: {
+              taskCharacteristics: [],
+              memoryState: [`${decision} suggested`],
+            },
+            adjustment: {
+              routingBias: { [decision]: -0.2 } as Record<RoutingDecisionType, number>,
+              retrievalModification: 'expand search',
+              executionHint: `Consider alternatives to ${decision}`,
+            },
+          })
+        );
+      } else if (successRate > 0.8 && stats.total >= 10) {
+        // This decision is highly effective
+        strategies.push(
+          createMetaStrategy({
+            name: `prefer-${decision}-high-success`,
+            condition: {
+              taskCharacteristics: [],
+              memoryState: [`${decision} applicable`],
+            },
+            adjustment: {
+              routingBias: { [decision]: 0.1 } as Record<RoutingDecisionType, number>,
+              retrievalModification: '',
+              executionHint: `${decision} has been effective`,
+            },
+          })
+        );
+      }
+    }
+
+    return strategies;
+  }
+}
+
+/**
+ * Create a meta learner
+ */
+export function createMetaLearner(
+  meta: MetaMemory,
+  config?: Partial<MetaLearnerConfig>
+): MetaLearner {
+  return new MetaLearner(meta, config);
+}