cognitive-core 0.2.5 → 0.3.1

package/src/learning/meta-learner.ts

@@ -1,552 +0,0 @@
-/**
- * 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';
-import { detectRepeatedActions, extractToolNames } from '../utils/trajectory-helpers.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;
-
-    // Collect tools used
-    const toolsUsed = extractToolNames(steps);
-
-    // Check for backtracking (similar actions repeated)
-    const backtrackingOccurred = detectRepeatedActions(steps, 3).length > 0;
-
-    // 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);
-}