cognitive-core 0.1.2 → 0.2.1

package/src/learning/reflexion-generator.ts

@@ -0,0 +1,273 @@
+/**
+ * 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);
+}

package/src/learning/trajectory-sources/entire.ts

@@ -9,31 +9,36 @@ import type { Task } from '../../types/task.js';
 import type { Outcome } from '../../types/outcome.js';
 import type { Step } from '../../types/step.js';
 
-// ─── EntireTrajectorySource ─────────────────────────────────────────
-// Bridges session-bank (Entire checkpoint data) into cognitive-core's
-// learning pipeline by implementing the TrajectorySource interface.
+// ─── SessionTrajectorySource ────────────────────────────────────────
+// Bridges session-bank checkpoint data (SessionLog) into
+// cognitive-core's learning pipeline via the TrajectorySource
+// interface.
 //
 // Synthesis converts SessionRecord → Trajectory:
 //   - Task description from summary.intent or first user message
 //   - Steps from assistant tool_use blocks (ReAct pattern)
 //   - Outcome inferred from summary.outcome keywords or heuristic
-//   - Token counts direct from Entire's metadata
+//   - Token counts direct from checkpoint metadata
 // ─────────────────────────────────────────────────────────────────────
 
-export interface EntireSynthesisOptions {
+export interface SessionSynthesisOptions {
   /** Domain to assign (default: inferred from files) */
   domain?: string;
   /** How to determine success/failure (default: 'summary') */
   outcomeStrategy?: 'summary' | 'heuristic';
+  /** Source name for trajectory IDs and metadata (default: auto-detected from branch) */
+  sourceName?: string;
 }
 
-export class EntireTrajectorySource implements TrajectorySource {
-  readonly name = 'entire';
+export class SessionTrajectorySource implements TrajectorySource {
+  readonly name: string;
 
   constructor(
     private sessionBank: SessionBank,
-    private options?: EntireSynthesisOptions,
-  ) {}
+    private options?: SessionSynthesisOptions,
+  ) {
+    this.name = options?.sourceName ?? 'session';
+  }
 
   async load(
     options?: TrajectoryLoadOptions,
@@ -66,11 +71,12 @@ export class EntireTrajectorySource implements TrajectorySource {
   }
 
   /**
-   * Convert an Entire SessionRecord into a cognitive-core Trajectory.
+   * Convert a SessionRecord into a cognitive-core Trajectory.
    */
   synthesize(session: SessionRecord): Trajectory {
+    const sourceName = this.resolveSourceName(session);
     return {
-      id: `entire-${session.checkpointId}-${session.sessionId}`,
+      id: `${sourceName}-${session.checkpointId}-${session.sessionId}`,
       task: this.extractTask(session),
       steps: this.extractSteps(session),
       outcome: this.inferOutcome(session),
@@ -80,7 +86,7 @@ export class EntireTrajectorySource implements TrajectorySource {
       totalTokens: session.tokenUsage.total,
       wallTimeSeconds: 0,
       metadata: {
-        source: 'entire',
+        source: sourceName,
         checkpointId: session.checkpointId,
         sessionId: session.sessionId,
         branch: session.metadata.branch,
@@ -93,6 +99,11 @@ export class EntireTrajectorySource implements TrajectorySource {
 
   // ── Private helpers ──────────────────────────────────────────
 
+  private resolveSourceName(_session: SessionRecord): string {
+    if (this.options?.sourceName) return this.options.sourceName;
+    return 'sessionlog';
+  }
+
   private extractTask(session: SessionRecord): Task {
     const description =
       session.summary?.intent ??
@@ -182,7 +193,7 @@ export class EntireTrajectorySource implements TrajectorySource {
         success,
         partialScore: success ? 1.0 : 0.0,
         verificationDetails: {
-          entireOutcome: session.summary.outcome,
+          sessionOutcome: session.summary.outcome,
           frictionPoints: session.summary.frictionPoints,
           openItems: session.summary.openItems,
         },

package/src/learning/trajectory-sources/index.ts

@@ -2,8 +2,8 @@ export { InMemoryTrajectorySource } from './in-memory.js';
 export { FileTrajectorySource } from './file.js';
 export { PipelineTrajectorySource } from './pipeline.js';
 export {
-  EntireTrajectorySource,
-  type EntireSynthesisOptions,
+  SessionTrajectorySource,
+  type SessionSynthesisOptions,
 } from './entire.js';
 export {
   DataclawTrajectorySource,

package/src/learning/trajectory-sources/pipeline.ts

@@ -3,13 +3,13 @@ import type {
   TrajectoryWithAnalysis,
   TrajectoryLoadOptions,
 } from '../../types/trajectory-source.js';
-import type { LearningPipeline } from '../pipeline.js';
+import type { UnifiedLearningPipeline } from '../unified-pipeline.js';
 
 /**
- * PipelineTrajectorySource — reads from LearningPipeline's accumulated trajectories.
+ * PipelineTrajectorySource — reads from UnifiedLearningPipeline's accumulated trajectories.
  *
  * Read-only view: does not clear the pipeline's accumulator.
- * The pipeline's `runBatchLearning()` or `clearAccumulated()` controls clearing.
+ * The pipeline's `runBatch()` controls clearing.
  *
  * @example
  * ```typescript
@@ -20,9 +20,9 @@ import type { LearningPipeline } from '../pipeline.js';
  */
 export class PipelineTrajectorySource implements TrajectorySource {
   readonly name = 'pipeline';
-  private pipeline: LearningPipeline;
+  private pipeline: UnifiedLearningPipeline;
 
-  constructor(pipeline: LearningPipeline) {
+  constructor(pipeline: UnifiedLearningPipeline) {
     this.pipeline = pipeline;
   }