cognitive-core 0.2.4 → 0.3.1

package/src/learning/reflexion-generator.ts

@@ -1,273 +0,0 @@
-/**
- * ReflexionGenerator — Generates structured self-reflection from completed trajectories.
- *
- * Two modes:
- * - **heuristic** (default, no LLM): Extracts patterns, tool names, file paths,
- *   error messages, and strategy assessments from trajectory data.
- * - **agentic** (optional): Uses LLM via ComputeProvider for deeper analysis.
- *   Falls back to heuristic if LLM is unavailable.
- */
-
-import type { Trajectory, ReflexionEpisode } from '../types/index.js';
-import type { PlaybookMatch } from '../memory/playbook.js';
-import { classifyErrorType } from '../utils/error-classifier.js';
-import { detectRepeatedActions, extractToolNames } from '../utils/trajectory-helpers.js';
-
-/**
- * Configuration for ReflexionGenerator
- */
-export interface ReflexionGeneratorConfig {
-  /** Generation mode: 'heuristic' (default) or 'agentic' */
-  mode?: 'heuristic' | 'agentic';
-  /** Max length for taskSummary (default: 200) */
-  maxSummaryLength?: number;
-  /** Max number of key insights to extract (default: 5) */
-  maxInsights?: number;
-}
-
-/**
- * ReflexionGenerator — creates ReflexionEpisode from trajectory + matched playbooks
- */
-export class ReflexionGenerator {
-  private config: Required<ReflexionGeneratorConfig>;
-
-  constructor(config?: ReflexionGeneratorConfig) {
-    this.config = {
-      mode: config?.mode ?? 'heuristic',
-      maxSummaryLength: config?.maxSummaryLength ?? 200,
-      maxInsights: config?.maxInsights ?? 5,
-    };
-  }
-
-  /**
-   * Generate a reflexion episode from a completed trajectory.
-   */
-  async generate(
-    trajectory: Trajectory,
-    matchedPlaybooks?: PlaybookMatch[]
-  ): Promise<ReflexionEpisode> {
-    // Currently only heuristic mode is implemented
-    return this.generateHeuristic(trajectory, matchedPlaybooks ?? []);
-  }
-
-  /**
-   * Heuristic mode — no LLM calls, pure pattern extraction.
-   */
-  private generateHeuristic(
-    trajectory: Trajectory,
-    matchedPlaybooks: PlaybookMatch[]
-  ): ReflexionEpisode {
-    const outcome = this.mapOutcome(trajectory);
-    const taskSummary = trajectory.task.description.slice(0, this.config.maxSummaryLength);
-    const selfCritique = this.extractSelfCritique(trajectory);
-    const keyInsights = this.extractKeyInsights(trajectory);
-    const strategyAssessment = this.assessStrategy(trajectory, matchedPlaybooks);
-    const suggestedPlaybookUpdates = this.suggestPlaybookUpdates(
-      trajectory,
-      matchedPlaybooks
-    );
-
-    return {
-      id: crypto.randomUUID(),
-      trajectoryId: trajectory.id,
-      taskSummary,
-      outcome,
-      selfCritique,
-      keyInsights,
-      strategyAssessment,
-      suggestedPlaybookUpdates,
-      domain: trajectory.task.domain ?? 'general',
-      createdAt: new Date(),
-    };
-  }
-
-  /**
-   * Map trajectory outcome to reflexion outcome label.
-   */
-  private mapOutcome(trajectory: Trajectory): 'success' | 'partial' | 'failure' {
-    if (trajectory.outcome.success) return 'success';
-    if (
-      trajectory.outcome.partialScore !== undefined &&
-      trajectory.outcome.partialScore > 0
-    ) {
-      return 'partial';
-    }
-    return 'failure';
-  }
-
-  /**
-   * Extract self-critique from the trajectory.
-   * Looks at failed steps, error messages, and wasted actions.
-   */
-  private extractSelfCritique(trajectory: Trajectory): string {
-    const parts: string[] = [];
-
-    if (!trajectory.outcome.success) {
-      // Summarize what went wrong
-      if (trajectory.outcome.errorInfo) {
-        parts.push(`Failed with: ${trajectory.outcome.errorInfo.slice(0, 150)}`);
-      }
-
-      // Count steps with low attribution scores (wasted effort)
-      const lowAttributionSteps = trajectory.steps.filter(
-        (s) => s.attributionScore !== undefined && s.attributionScore < 0.2
-      );
-      if (lowAttributionSteps.length > 0) {
-        parts.push(
-          `${lowAttributionSteps.length} of ${trajectory.steps.length} steps had low attribution (wasted effort)`
-        );
-      }
-    } else {
-      // Successful — note efficiency
-      const stepCount = trajectory.steps.length;
-      if (stepCount > 10) {
-        parts.push(`Succeeded but took ${stepCount} steps — may be overcomplicating`);
-      } else {
-        parts.push(`Completed efficiently in ${stepCount} steps`);
-      }
-    }
-
-    // Look for repeated actions (potential thrashing)
-    const repeated = detectRepeatedActions(trajectory.steps, 3);
-    if (repeated.length > 0) {
-      parts.push(
-        `Repeated actions detected: ${repeated.map(({ action, count }) => `"${action.slice(0, 30)}..." (${count}x)`).join(', ')}`
-      );
-    }
-
-    return parts.join('. ') || 'No specific critique identified';
-  }
-
-  /**
-   * Extract key insights from the trajectory.
-   * Pulls tool names, file paths, and notable observations.
-   */
-  private extractKeyInsights(trajectory: Trajectory): string[] {
-    const insights: string[] = [];
-
-    // Extract tool names from steps
-    const toolNames = extractToolNames(trajectory.steps);
-    if (toolNames.size > 0) {
-      insights.push(`Tools used: ${[...toolNames].join(', ')}`);
-    }
-
-    // Extract file paths from observations
-    const filePaths = new Set<string>();
-    for (const step of trajectory.steps) {
-      const pathMatches = step.observation?.match(
-        /(?:\/[\w.-]+)+(?:\.[\w]+)/g
-      );
-      if (pathMatches) {
-        for (const p of pathMatches.slice(0, 5)) {
-          filePaths.add(p);
-        }
-      }
-    }
-    if (filePaths.size > 0) {
-      insights.push(`Key files: ${[...filePaths].slice(0, 5).join(', ')}`);
-    }
-
-    // Note error patterns for failed trajectories
-    if (!trajectory.outcome.success && trajectory.outcome.errorInfo) {
-      const errorType = classifyErrorType(trajectory.outcome.errorInfo);
-      if (errorType) {
-        insights.push(`Error pattern: ${errorType}`);
-      }
-    }
-
-    // Note step count and efficiency
-    const highAttributionSteps = trajectory.steps.filter(
-      (s) => s.attributionScore !== undefined && s.attributionScore > 0.7
-    );
-    if (highAttributionSteps.length > 0) {
-      insights.push(
-        `${highAttributionSteps.length} high-impact steps identified`
-      );
-    }
-
-    return insights.slice(0, this.config.maxInsights);
-  }
-
-
-  /**
-   * Assess the strategy by comparing matched playbooks against the outcome.
-   */
-  private assessStrategy(
-    trajectory: Trajectory,
-    matchedPlaybooks: PlaybookMatch[]
-  ): string {
-    if (matchedPlaybooks.length === 0) {
-      if (trajectory.outcome.success) {
-        return 'Succeeded without playbook guidance — potential new playbook candidate';
-      }
-      return 'Failed without playbook guidance — no applicable playbooks found';
-    }
-
-    const topMatch = matchedPlaybooks[0];
-    const matchScore = Math.round(topMatch.score * 100);
-
-    if (trajectory.outcome.success) {
-      return `Succeeded with playbook "${topMatch.playbook.name}" (${matchScore}% match). Strategy confirmed.`;
-    }
-
-    // Failure with a matched playbook
-    return `Failed despite playbook "${topMatch.playbook.name}" (${matchScore}% match). Playbook may need refinement for this context.`;
-  }
-
-  /**
-   * Suggest playbook updates based on the trajectory outcome.
-   */
-  private suggestPlaybookUpdates(
-    trajectory: Trajectory,
-    matchedPlaybooks: PlaybookMatch[]
-  ): string[] {
-    const suggestions: string[] = [];
-
-    if (trajectory.outcome.success && matchedPlaybooks.length === 0) {
-      // Successful without playbooks — suggest creating one
-      suggestions.push(
-        `Create new playbook for: ${trajectory.task.description.slice(0, 100)}`
-      );
-    }
-
-    if (!trajectory.outcome.success) {
-      // Failed — suggest updates to matched playbooks
-      for (const match of matchedPlaybooks) {
-        if (trajectory.outcome.errorInfo) {
-          suggestions.push(
-            `Add anti-pattern to "${match.playbook.name}": ${trajectory.outcome.errorInfo.slice(0, 80)}`
-          );
-        }
-
-        // Suggest refinement based on error context
-        const domain = trajectory.task.domain;
-        if (domain) {
-          suggestions.push(
-            `Add refinement to "${match.playbook.name}" for domain "${domain}"`
-          );
-        }
-      }
-
-      // If no playbooks matched a failure, suggest broader coverage
-      if (matchedPlaybooks.length === 0 && trajectory.outcome.errorInfo) {
-        const errorType = classifyErrorType(trajectory.outcome.errorInfo);
-        if (errorType) {
-          suggestions.push(
-            `Create error-handling playbook for pattern: ${errorType}`
-          );
-        }
-      }
-    }
-
-    return suggestions;
-  }
-}
-
-/**
- * Create a ReflexionGenerator instance
- */
-export function createReflexionGenerator(
-  config?: ReflexionGeneratorConfig
-): ReflexionGenerator {
-  return new ReflexionGenerator(config);
-}