cognitive-core 0.2.4 → 0.3.1

package/src/search/refinement-loop.ts

@@ -1,457 +0,0 @@
-/**
- * Refinement Loop
- *
- * Implements ReMem-style iterative refinement that improves solutions
- * using memory-augmented feedback. The loop:
- * 1. Evaluates solution quality
- * 2. If not acceptable, injects failure context and retries
- * 3. Continues until acceptable or max iterations reached
- */
-
-import type { Task } from '../types/task.js';
-import type { Trajectory } from '../types/trajectory.js';
-import type { AgentManager } from '../runtime/manager.js';
-import type { MemorySystem, MemoryQueryResultV2 } from '../memory/system.js';
-import type { AgentSpawnConfig } from '../runtime/types.js';
-import type { AgenticTaskRunner } from '../workspace/runner.js';
-import { refinementAnalysisTemplate, type RefinementPlan } from '../workspace/templates/refinement-analysis.js';
-import {
-  type RefinementResult,
-  type EvaluationResult,
-  type FailureContext,
-} from './refinement-types.js';
-import { SolutionEvaluator, type EvaluatorConfig } from './evaluator.js';
-
-/**
- * Configuration for the refinement loop
- */
-export interface RefinementLoopConfig {
-  /** Maximum number of refinement iterations (default: 3) */
-  maxIterations?: number;
-  /** Minimum acceptable quality score (default: 0.7) */
-  minAcceptableScore?: number;
-  /** Whether to inject previous failure context (default: true) */
-  injectFailureContext?: boolean;
-  /** Whether to query memory for similar failures (default: true) */
-  queryFailureMemory?: boolean;
-  /** Evaluator configuration */
-  evaluatorConfig?: EvaluatorConfig;
-  /** Task strategies that should trigger refinement */
-  triggerOnStrategies?: Array<'direct' | 'adapt' | 'explore' | 'fallback'>;
-  /** Minimum confidence to skip refinement */
-  confidenceThreshold?: number;
-}
-
-/**
- * Default refinement configuration
- */
-const DEFAULT_CONFIG: Required<RefinementLoopConfig> = {
-  maxIterations: 3,
-  minAcceptableScore: 0.7,
-  injectFailureContext: true,
-  queryFailureMemory: true,
-  evaluatorConfig: {},
-  triggerOnStrategies: ['explore', 'fallback'],
-  confidenceThreshold: 0.85,
-};
-
-/**
- * RefinementLoop - Iteratively improves solutions using feedback
- */
-export class RefinementLoop {
-  private agentManager: AgentManager;
-  private memory: MemorySystem;
-  private taskRunner: AgenticTaskRunner | null = null;
-  private evaluator: SolutionEvaluator;
-  private config: Required<RefinementLoopConfig>;
-
-  constructor(
-    agentManager: AgentManager,
-    memory: MemorySystem,
-    config: RefinementLoopConfig = {}
-  ) {
-    this.agentManager = agentManager;
-    this.memory = memory;
-    this.config = { ...DEFAULT_CONFIG, ...config };
-    this.evaluator = new SolutionEvaluator(
-      agentManager,
-      this.config.evaluatorConfig
-    );
-  }
-
-  /**
-   * Set the task runner for workspace-based analysis.
-   * Enables structured refinement plans via refinementAnalysisTemplate,
-   * and delegates evaluation to solutionEvaluationTemplate.
-   */
-  setTaskRunner(runner: AgenticTaskRunner): void {
-    this.taskRunner = runner;
-    this.evaluator.setTaskRunner(runner);
-  }
-
-  /**
-   * Get the evaluator for registering domain verifiers
-   */
-  getEvaluator(): SolutionEvaluator {
-    return this.evaluator;
-  }
-
-  /**
-   * Check if refinement should be triggered based on strategy and confidence
-   */
-  shouldTriggerRefinement(
-    strategy: 'direct' | 'adapt' | 'explore' | 'fallback',
-    confidence?: number
-  ): boolean {
-    // Check if strategy is in trigger list
-    if (!this.config.triggerOnStrategies.includes(strategy)) {
-      return false;
-    }
-
-    // If confidence is high enough, skip refinement
-    if (
-      confidence !== undefined &&
-      confidence >= this.config.confidenceThreshold
-    ) {
-      return false;
-    }
-
-    return true;
-  }
-
-  /**
-   * Run the refinement loop on an initial trajectory
-   */
-  async refine(
-    initialTrajectory: Trajectory,
-    spawnConfig: AgentSpawnConfig
-  ): Promise<RefinementResult> {
-    const evaluations: EvaluationResult[] = [];
-    let currentTrajectory = initialTrajectory;
-    let bestTrajectory = initialTrajectory;
-    let bestScore = 0;
-    let improved = false;
-
-    // Evaluate initial trajectory
-    const initialEval = await this.evaluator.evaluate(
-      currentTrajectory,
-      spawnConfig.task
-    );
-    evaluations.push(initialEval);
-    bestScore = initialEval.score;
-
-    // If initial is acceptable, return early
-    if (initialEval.acceptable && initialEval.score >= this.config.minAcceptableScore) {
-      return {
-        trajectory: currentTrajectory,
-        success: true,
-        iterations: 0,
-        evaluations,
-        improved: false,
-        bestScore: initialEval.score,
-      };
-    }
-
-    // Refinement loop
-    for (let iteration = 0; iteration < this.config.maxIterations; iteration++) {
-      // Build failure context
-      const failureContext: FailureContext = {
-        attemptedSolution: currentTrajectory.outcome.solution,
-        evaluation: evaluations[evaluations.length - 1],
-        stepsAttempted: currentTrajectory.steps.length,
-        previousAttempts: iteration + 1,
-      };
-
-      // Get refinement strategy: workspace-based when runner available
-      let refinementAdditions: string;
-      const plan = await this.getRefinementPlan(
-        currentTrajectory,
-        spawnConfig.task,
-        evaluations[evaluations.length - 1],
-        iteration + 1,
-      );
-
-      if (plan) {
-        // Use structured plan from template
-        refinementAdditions = this.formatRefinementPlan(plan, failureContext);
-      } else {
-        // Fallback: build prompt with memory-based context
-        let failureMemory: MemoryQueryResultV2 | undefined;
-        if (this.config.queryFailureMemory) {
-          failureMemory = await this.queryFailurePatterns(
-            spawnConfig.task,
-            failureContext
-          );
-        }
-        refinementAdditions = this.buildRefinementPrompt(
-          failureContext,
-          failureMemory
-        );
-      }
-
-      // Spawn refined agent
-      const refinedConfig: AgentSpawnConfig = {
-        ...spawnConfig,
-        systemPromptAdditions: [
-          spawnConfig.systemPromptAdditions,
-          refinementAdditions,
-        ]
-          .filter(Boolean)
-          .join('\n\n'),
-      };
-
-      const result = await this.agentManager.spawn(refinedConfig);
-      currentTrajectory = result.trajectory;
-
-      // Evaluate refined trajectory
-      const evaluation = await this.evaluator.evaluate(
-        currentTrajectory,
-        spawnConfig.task
-      );
-      evaluations.push(evaluation);
-
-      // Track best
-      if (evaluation.score > bestScore) {
-        bestScore = evaluation.score;
-        bestTrajectory = currentTrajectory;
-        improved = true;
-      }
-
-      // Check if acceptable
-      if (evaluation.acceptable && evaluation.score >= this.config.minAcceptableScore) {
-        return {
-          trajectory: currentTrajectory,
-          success: true,
-          iterations: iteration + 1,
-          evaluations,
-          improved,
-          bestScore,
-        };
-      }
-    }
-
-    // Return best trajectory after all iterations
-    return {
-      trajectory: bestTrajectory,
-      success: bestScore >= this.config.minAcceptableScore,
-      iterations: this.config.maxIterations,
-      evaluations,
-      improved,
-      bestScore,
-    };
-  }
-
-  /**
-   * Get a structured refinement plan via the workspace template.
-   * Returns null if taskRunner is unavailable or the template fails.
-   */
-  private async getRefinementPlan(
-    trajectory: Trajectory,
-    task: Task,
-    evaluation: EvaluationResult,
-    previousAttempts: number,
-  ): Promise<RefinementPlan | null> {
-    if (!this.taskRunner) return null;
-
-    try {
-      const result = await this.taskRunner.run(refinementAnalysisTemplate, {
-        trajectory,
-        task,
-        evaluation,
-        previousAttempts,
-      });
-      return result.output;
-    } catch (error) {
-      console.warn(
-        'Workspace-based refinement analysis failed, falling back to heuristic:',
-        error instanceof Error ? error.message : String(error)
-      );
-      return null;
-    }
-  }
-
-  /**
-   * Format a structured RefinementPlan into prompt additions for the retry agent.
-   */
-  private formatRefinementPlan(
-    plan: RefinementPlan,
-    failureContext: FailureContext,
-  ): string {
-    const parts: string[] = [];
-
-    parts.push('## Root Cause Analysis');
-    parts.push('');
-    parts.push(`Previous attempt #${failureContext.previousAttempts} failed. Root causes identified:`);
-    for (const cause of plan.rootCauses) {
-      parts.push(`- ${cause}`);
-    }
-
-    parts.push('');
-    parts.push('## Recommended Strategy');
-    parts.push('');
-    parts.push(plan.strategy);
-
-    if (plan.steps.length > 0) {
-      parts.push('');
-      parts.push('## Specific Steps');
-      for (let i = 0; i < plan.steps.length; i++) {
-        parts.push(`${i + 1}. ${plan.steps[i]}`);
-      }
-    }
-
-    if (plan.avoidPatterns.length > 0) {
-      parts.push('');
-      parts.push('## Patterns to Avoid');
-      for (const pattern of plan.avoidPatterns) {
-        parts.push(`- DO NOT: ${pattern}`);
-      }
-    }
-
-    return parts.join('\n');
-  }
-
-  /**
-   * Query memory for similar failure patterns
-   */
-  private async queryFailurePatterns(
-    task: Task,
-    failureContext: FailureContext
-  ): Promise<MemoryQueryResultV2> {
-    // Build query from task and failure
-    const failureDescription = failureContext.evaluation.issues
-      .map((issue) => issue.description)
-      .join('; ');
-
-    const query = `${task.description} - failed with: ${failureDescription}`;
-
-    // Query memory for similar experiences and playbooks
-    const results = await this.memory.queryV2(query, {
-      domains: task.domain ? [task.domain] : undefined,
-      includeExperiences: true,
-      includePlaybooks: true,
-    });
-
-    // Filter to experiences that eventually succeeded after similar failures
-    // This gives us recovery strategies
-    const recoveryExperiences = results.experiences.filter(
-      (exp) =>
-        exp.experience.success &&
-        this.hasSimilarInitialFailure(exp.experience, failureContext)
-    );
-
-    return {
-      ...results,
-      experiences: recoveryExperiences.length > 0 ? recoveryExperiences : results.experiences,
-    };
-  }
-
-  /**
-   * Check if an experience had a similar initial failure pattern
-   */
-  private hasSimilarInitialFailure(
-    experience: { steps?: Array<{ observation?: string }>; solutionOutput: string },
-    failureContext: FailureContext
-  ): boolean {
-    // Look for similar error patterns in the experience's early steps
-    const failureKeywords = failureContext.evaluation.issues
-      .map((issue) => issue.description.toLowerCase().split(' '))
-      .flat()
-      .filter((word) => word.length > 4);
-
-    const experienceText = (
-      (experience.steps ?? [])
-        .map((s) => s.observation ?? '')
-        .join(' ') +
-      ' ' +
-      experience.solutionOutput
-    ).toLowerCase();
-
-    const matchCount = failureKeywords.filter((kw) =>
-      experienceText.includes(kw)
-    ).length;
-
-    return matchCount >= Math.min(2, failureKeywords.length / 2);
-  }
-
-  /**
-   * Build refinement prompt with failure context and memory
-   */
-  private buildRefinementPrompt(
-    failureContext: FailureContext,
-    failureMemory?: MemoryQueryResultV2
-  ): string {
-    const parts: string[] = [];
-
-    if (this.config.injectFailureContext) {
-      parts.push('## Previous Attempt Feedback');
-      parts.push('');
-      parts.push(
-        `Your previous attempt (iteration ${failureContext.previousAttempts}) had issues:`
-      );
-      parts.push('');
-
-      for (const issue of failureContext.evaluation.issues) {
-        const severity = issue.severity.toUpperCase();
-        parts.push(`- **[${severity}]** ${issue.type}: ${issue.description}`);
-        if (issue.suggestion) {
-          parts.push(`  *Suggestion:* ${issue.suggestion}`);
-        }
-      }
-
-      parts.push('');
-      parts.push(`Quality score: ${(failureContext.evaluation.score * 100).toFixed(0)}%`);
-      parts.push(`Assessment: ${failureContext.evaluation.quality}`);
-      parts.push('');
-    }
-
-    if (failureMemory && this.config.queryFailureMemory) {
-      // Add recovery playbooks from memory
-      if (failureMemory.playbooks.length > 0) {
-        parts.push('## Recovery Playbooks from Memory');
-        parts.push('');
-        for (const { playbook, score } of failureMemory.playbooks.slice(0, 3)) {
-          parts.push(
-            `- **${playbook.name}** (${(score * 100).toFixed(0)}% relevant)`
-          );
-          parts.push(`  Strategy: ${playbook.guidance.strategy}`);
-          if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
-            parts.push(`  Steps: ${playbook.guidance.steps.slice(0, 3).join(' → ')}`);
-          }
-        }
-        parts.push('');
-      }
-
-      // Add successful recovery experiences
-      if (failureMemory.experiences.length > 0) {
-        parts.push('## Similar Problems Successfully Solved');
-        parts.push('');
-        for (const { experience } of failureMemory.experiences.slice(0, 2)) {
-          parts.push(`- Task: ${experience.taskInput.slice(0, 150)}...`);
-          parts.push(`  Solution approach: ${experience.solutionOutput.slice(0, 200)}...`);
-        }
-        parts.push('');
-      }
-    }
-
-    parts.push('## Instructions for This Attempt');
-    parts.push('');
-    parts.push('Please address the issues identified above and try a different approach.');
-    parts.push('Focus on:');
-    parts.push('1. Avoiding the specific errors from the previous attempt');
-    parts.push('2. Using the recovery playbooks if applicable');
-    parts.push('3. Taking a more thorough or alternative approach');
-
-    return parts.join('\n');
-  }
-}
-
-/**
- * Create a refinement loop
- */
-export function createRefinementLoop(
-  agentManager: AgentManager,
-  memory: MemorySystem,
-  config?: RefinementLoopConfig
-): RefinementLoop {
-  return new RefinementLoop(agentManager, memory, config);
-}

package/src/search/refinement-types.ts

@@ -1,159 +0,0 @@
-/**
- * Refinement Types
- *
- * Types for the ReMem-style refinement loop that iteratively
- * improves solutions using memory-augmented feedback.
- */
-
-import { z } from 'zod';
-
-/**
- * Issue type found during evaluation
- */
-export const IssueTypeSchema = z.enum([
-  'incomplete',
-  'incorrect',
-  'inefficient',
-  'off_topic',
-  'error',
-]);
-
-export type IssueType = z.infer<typeof IssueTypeSchema>;
-
-/**
- * Severity of an issue
- */
-export const IssueSeveritySchema = z.enum(['critical', 'major', 'minor']);
-
-export type IssueSeverity = z.infer<typeof IssueSeveritySchema>;
-
-/**
- * An issue found during solution evaluation
- */
-export const EvaluationIssueSchema = z.object({
-  type: IssueTypeSchema,
-  description: z.string(),
-  severity: IssueSeveritySchema,
-  suggestion: z.string().optional(),
-});
-
-export type EvaluationIssue = z.infer<typeof EvaluationIssueSchema>;
-
-/**
- * Quality assessment level
- */
-export const QualityLevelSchema = z.enum([
-  'excellent',
-  'good',
-  'needs_work',
-  'poor',
-]);
-
-export type QualityLevel = z.infer<typeof QualityLevelSchema>;
-
-/**
- * How the evaluation was performed
- */
-export const EvaluationMethodSchema = z.enum([
-  'verification',
-  'agent',
-  'heuristic',
-]);
-
-export type EvaluationMethod = z.infer<typeof EvaluationMethodSchema>;
-
-/**
- * Result of evaluating a solution's quality
- */
-export const EvaluationResultSchema = z.object({
-  /** Overall quality assessment */
-  quality: QualityLevelSchema,
-  /** Numeric score (0-1) */
-  score: z.number().min(0).max(1),
-  /** Whether this solution is acceptable */
-  acceptable: z.boolean(),
-  /** Specific issues found */
-  issues: z.array(EvaluationIssueSchema),
-  /** How the evaluation was performed */
-  method: EvaluationMethodSchema,
-  /** Raw response from evaluator (for debugging) */
-  rawResponse: z.string().optional(),
-});
-
-export type EvaluationResult = z.infer<typeof EvaluationResultSchema>;
-
-/**
- * Context about why a solution failed
- */
-export interface FailureContext {
-  /** The solution that was attempted */
-  attemptedSolution: unknown;
-  /** Evaluation result */
-  evaluation: EvaluationResult;
-  /** Number of steps taken in the attempt */
-  stepsAttempted: number;
-  /** Number of previous refinement attempts */
-  previousAttempts: number;
-}
-
-/**
- * Result of the refinement loop
- */
-export interface RefinementResult {
-  /** Final trajectory after refinement */
-  trajectory: import('../types/trajectory.js').Trajectory;
-  /** Whether the final solution is acceptable */
-  success: boolean;
-  /** Number of refinement iterations performed */
-  iterations: number;
-  /** Evaluation results from each iteration */
-  evaluations: EvaluationResult[];
-  /** Whether refinement improved the solution */
-  improved: boolean;
-  /** Best score achieved during refinement */
-  bestScore: number;
-}
-
-/**
- * Create an evaluation result
- */
-export function createEvaluationResult(params: {
-  quality: QualityLevel;
-  score: number;
-  acceptable: boolean;
-  issues?: EvaluationIssue[];
-  method: EvaluationMethod;
-  rawResponse?: string;
-}): EvaluationResult {
-  return EvaluationResultSchema.parse({
-    quality: params.quality,
-    score: params.score,
-    acceptable: params.acceptable,
-    issues: params.issues ?? [],
-    method: params.method,
-    rawResponse: params.rawResponse,
-  });
-}
-
-/**
- * Determine quality level from a numeric score
- */
-export function scoreToQuality(score: number): QualityLevel {
-  if (score >= 0.85) return 'excellent';
-  if (score >= 0.7) return 'good';
-  if (score >= 0.4) return 'needs_work';
-  return 'poor';
-}
-
-/**
- * Check if a quality level is acceptable
- */
-export function isQualityAcceptable(
-  quality: QualityLevel,
-  minAcceptable: QualityLevel = 'good'
-): boolean {
-  const levels: QualityLevel[] = ['poor', 'needs_work', 'good', 'excellent'];
-  const qualityIndex = levels.indexOf(quality);
-  const minIndex = levels.indexOf(minAcceptable);
-  return qualityIndex >= minIndex;
-}