cognitive-core 0.0.2 → 0.1.2

package/src/learning/analyzer.ts

@@ -0,0 +1,335 @@
+import type { Trajectory, CreditStrategy } from '../types/index.js';
+
+/**
+ * Analysis result from trajectory examination
+ */
+export interface AnalysisResult {
+  /** Whether the trajectory succeeded */
+  success: boolean;
+  /** Indices of key steps (above attribution threshold) */
+  keySteps: number[];
+  /** Attribution score for each step */
+  stepAttribution: number[];
+  /** Detected error patterns */
+  errorPatterns: ErrorPattern[];
+  /** Whether this trajectory is worth extracting patterns from */
+  abstractable: boolean;
+  /** Suggested training examples */
+  trainingExamples: TrainingExample[];
+}
+
+/**
+ * Detected error pattern
+ */
+export interface ErrorPattern {
+  type: string;
+  signature: string;
+  description: string;
+  suggestedFix?: string;
+}
+
+/**
+ * Training example extracted from trajectory
+ */
+export interface TrainingExample {
+  input: string;
+  output: string;
+  stepIndex: number;
+}
+
+/**
+ * Configuration for trajectory analyzer
+ */
+export interface AnalyzerConfig {
+  /** Credit decay factor for exponential decay (default: 0.5) */
+  creditDecayFactor: number;
+  /** Minimum action repetitions to flag as repetition pattern (default: 3) */
+  actionRepetitionThreshold: number;
+  /** Attribution threshold for key step identification (default: 0.15) */
+  attributionThreshold: number;
+}
+
+const DEFAULT_ANALYZER_CONFIG: AnalyzerConfig = {
+  creditDecayFactor: 0.5,
+  actionRepetitionThreshold: 3,
+  attributionThreshold: 0.15,
+};
+
+/**
+ * Credit assignment strategies
+ */
+export type CreditAssignmentFn = (
+  trajectory: Trajectory,
+  config: AnalyzerConfig
+) => Promise<number[]>;
+
+/**
+ * Simple exponential decay credit assignment
+ * Last step gets 1.0, decays exponentially backwards
+ */
+export function simpleCreditAssignment(
+  trajectory: Trajectory,
+  config: AnalyzerConfig
+): Promise<number[]> {
+  const n = trajectory.steps.length;
+  const scores: number[] = [];
+  const decay = config.creditDecayFactor;
+
+  for (let i = 0; i < n; i++) {
+    const distanceFromEnd = n - 1 - i;
+    scores.push(Math.pow(decay, distanceFromEnd));
+  }
+
+  return Promise.resolve(scores);
+}
+
+/**
+ * Outcome-based credit assignment
+ * Successful trajectories get higher credit for all steps
+ */
+export function outcomeCreditAssignment(
+  trajectory: Trajectory,
+  _config: AnalyzerConfig
+): Promise<number[]> {
+  const baseScores: number[] = trajectory.steps.map(() =>
+    trajectory.outcome.success ? 0.7 : 0.3
+  );
+
+  // Boost last step for successful trajectories
+  if (trajectory.outcome.success && baseScores.length > 0) {
+    baseScores[baseScores.length - 1] = 1.0;
+  }
+
+  return Promise.resolve(baseScores);
+}
+
+/**
+ * Get credit assignment function by strategy type
+ */
+export function getCreditAssignmentFn(
+  strategy: CreditStrategy
+): CreditAssignmentFn {
+  switch (strategy) {
+    case 'simple':
+      return simpleCreditAssignment;
+    case 'llm':
+      // LLM-based credit assignment would require an LLM client
+      // Fall back to simple for now
+      return simpleCreditAssignment;
+    case 'counterfactual':
+      // Counterfactual requires environment replay
+      // Fall back to outcome-based
+      return outcomeCreditAssignment;
+    default:
+      return simpleCreditAssignment;
+  }
+}
+
+/**
+ * Trajectory Analyzer
+ * Analyzes trajectories to extract learning signals
+ */
+export class TrajectoryAnalyzer {
+  private creditFn: CreditAssignmentFn;
+  private config: AnalyzerConfig;
+
+  constructor(strategy: CreditStrategy = 'simple', config?: Partial<AnalyzerConfig>) {
+    this.creditFn = getCreditAssignmentFn(strategy);
+    this.config = { ...DEFAULT_ANALYZER_CONFIG, ...config };
+  }
+
+  /**
+   * Analyze a trajectory
+   */
+  async analyze(trajectory: Trajectory): Promise<AnalysisResult> {
+    // Assign credit to steps
+    const stepAttribution = await this.creditFn(trajectory, this.config);
+
+    // Apply attribution to steps
+    for (let i = 0; i < trajectory.steps.length; i++) {
+      trajectory.steps[i].attributionScore = stepAttribution[i];
+    }
+
+    // Identify key steps
+    const keySteps = stepAttribution
+      .map((score, index) => ({ score, index }))
+      .filter(({ score }) => score >= this.config.attributionThreshold)
+      .map(({ index }) => index);
+
+    // Detect error patterns
+    const errorPatterns = this.detectErrorPatterns(trajectory);
+
+    // Assess abstractability
+    const abstractable = this.assessAbstractability(
+      trajectory,
+      keySteps,
+      errorPatterns
+    );
+
+    // Extract training examples
+    const trainingExamples = this.extractTrainingExamples(
+      trajectory,
+      keySteps
+    );
+
+    return {
+      success: trajectory.outcome.success,
+      keySteps,
+      stepAttribution,
+      errorPatterns,
+      abstractable,
+      trainingExamples,
+    };
+  }
+
+  /**
+   * Detect error patterns in failed trajectories
+   */
+  private detectErrorPatterns(trajectory: Trajectory): ErrorPattern[] {
+    const patterns: ErrorPattern[] = [];
+
+    if (!trajectory.outcome.success && trajectory.outcome.errorInfo) {
+      // Extract error type from error info
+      const errorInfo = trajectory.outcome.errorInfo;
+
+      // Common error patterns
+      const errorTypes: Array<[RegExp, string, string]> = [
+        [/timeout/i, 'timeout', 'Operation timed out'],
+        [/not found/i, 'not_found', 'Resource not found'],
+        [/permission denied/i, 'permission', 'Permission denied'],
+        [/syntax error/i, 'syntax', 'Syntax error in code'],
+        [/type error/i, 'type', 'Type mismatch error'],
+        [/assertion|assert/i, 'assertion', 'Assertion failed'],
+        [/exception|error/i, 'general', 'General error'],
+      ];
+
+      for (const [pattern, type, desc] of errorTypes) {
+        if (pattern.test(errorInfo)) {
+          patterns.push({
+            type,
+            signature: errorInfo.slice(0, 100),
+            description: desc,
+          });
+          break;
+        }
+      }
+    }
+
+    // Check for repeated failed actions
+    const actionCounts = new Map<string, number>();
+    for (const step of trajectory.steps) {
+      const count = (actionCounts.get(step.action) ?? 0) + 1;
+      actionCounts.set(step.action, count);
+    }
+
+    for (const [action, count] of actionCounts) {
+      if (count >= this.config.actionRepetitionThreshold) {
+        patterns.push({
+          type: 'repetition',
+          signature: action,
+          description: `Action repeated ${count} times`,
+          suggestedFix: 'Try a different approach',
+        });
+      }
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Assess whether a trajectory is worth abstracting patterns from
+   */
+  private assessAbstractability(
+    trajectory: Trajectory,
+    keySteps: number[],
+    errorPatterns: ErrorPattern[]
+  ): boolean {
+    // Successful trajectories are generally abstractable
+    if (trajectory.outcome.success) {
+      // Must have enough meaningful steps
+      return keySteps.length >= 2;
+    }
+
+    // Failed trajectories with clear error patterns might be useful
+    // for learning what NOT to do
+    if (errorPatterns.length > 0) {
+      return (
+        errorPatterns.some((p) => p.suggestedFix) ||
+        trajectory.outcome.partialScore >= 0.3
+      );
+    }
+
+    return false;
+  }
+
+  /**
+   * Extract training examples from trajectory
+   */
+  private extractTrainingExamples(
+    trajectory: Trajectory,
+    keySteps: number[]
+  ): TrainingExample[] {
+    const examples: TrainingExample[] = [];
+
+    // Extract from key steps
+    for (const index of keySteps) {
+      const step = trajectory.steps[index];
+      if (step.thought && step.action) {
+        examples.push({
+          input: step.thought,
+          output: step.action,
+          stepIndex: index,
+        });
+      }
+    }
+
+    // Add final step as input-output pair
+    if (trajectory.steps.length > 0 && trajectory.outcome.success) {
+      examples.push({
+        input: trajectory.task.description,
+        output: JSON.stringify(trajectory.outcome.solution),
+        stepIndex: trajectory.steps.length - 1,
+      });
+    }
+
+    return examples;
+  }
+
+  /**
+   * Set credit assignment strategy
+   */
+  setStrategy(strategy: CreditStrategy): void {
+    this.creditFn = getCreditAssignmentFn(strategy);
+  }
+
+  /**
+   * Set attribution threshold
+   */
+  setThreshold(threshold: number): void {
+    this.config.attributionThreshold = threshold;
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<AnalyzerConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): AnalyzerConfig {
+    return { ...this.config };
+  }
+}
+
+/**
+ * Create a trajectory analyzer
+ */
+export function createAnalyzer(
+  strategy: CreditStrategy = 'simple',
+  config?: Partial<AnalyzerConfig>
+): TrajectoryAnalyzer {
+  return new TrajectoryAnalyzer(strategy, config);
+}