groundswell 0.0.2 → 1.0.0

package/examples/examples/09-reflection.ts

@@ -1,573 +0,0 @@
-/**
- * Example 9: Multi-level Reflection
- *
- * Demonstrates:
- * - Prompt-level reflection (enableReflection on prompt)
- * - Agent-level reflection (agent.reflect() method)
- * - Workflow-level reflection (step failure retry)
- * - Reflection events in tree output
- * - Error recovery with revised prompts
- */
-
-import { z } from 'zod';
-import {
-  Workflow,
-  Step,
-  ObservedState,
-  WorkflowTreeDebugger,
-  ReflectionManager,
-  executeWithReflection,
-  DEFAULT_REFLECTION_CONFIG,
-  createReflectionConfig,
-} from 'groundswell';
-import type {
-  ReflectionConfig,
-  ReflectionEntry,
-  ReflectionContext,
-  WorkflowNode,
-} from 'groundswell';
-import { printHeader, printSection, sleep, simulateUnreliableTask } from '../utils/helpers.js';
-
-// ============================================================================
-// Response Schemas
-// ============================================================================
-
-const StrictAnswerSchema = z.object({
-  answer: z.string().min(10, 'Answer must be at least 10 characters'),
-  confidence: z.number().min(0.8, 'Confidence must be at least 0.8'),
-  reasoning: z.string().min(20, 'Reasoning must be detailed'),
-});
-
-const AnalysisSchema = z.object({
-  summary: z.string(),
-  keyPoints: z.array(z.string()).min(2, 'Must have at least 2 key points'),
-  recommendation: z.string(),
-});
-
-type StrictAnswer = z.infer<typeof StrictAnswerSchema>;
-type Analysis = z.infer<typeof AnalysisSchema>;
-
-// ============================================================================
-// Simulated Responses (for demonstration without API calls)
-// ============================================================================
-
-/**
- * Simulate a response that might fail schema validation
- */
-async function simulateStrictResponse(
-  attemptNumber: number
-): Promise<StrictAnswer> {
-  await sleep(50);
-
-  // First attempt might fail validation
-  if (attemptNumber === 1 && Math.random() > 0.3) {
-    return {
-      answer: 'Short', // Too short - will fail validation
-      confidence: 0.5, // Too low - will fail validation
-      reasoning: 'Brief', // Too short
-    };
-  }
-
-  // Subsequent attempts return valid data
-  return {
-    answer: 'This is a comprehensive answer that meets the minimum length requirement',
-    confidence: 0.92,
-    reasoning: 'Based on careful analysis of the input data and consideration of multiple factors',
-  };
-}
-
-/**
- * Simulate an analysis response
- */
-async function simulateAnalysis(): Promise<Analysis> {
-  await sleep(75);
-
-  return {
-    summary: 'The analysis shows positive trends across all metrics',
-    keyPoints: [
-      'Revenue increased by 15%',
-      'Customer satisfaction improved',
-      'Operational efficiency gains',
-    ],
-    recommendation: 'Continue current strategy with minor adjustments',
-  };
-}
-
-// ============================================================================
-// Workflow Definitions
-// ============================================================================
-
-/**
- * Prompt-level reflection demonstration
- */
-class PromptReflectionWorkflow extends Workflow {
-  @ObservedState()
-  attemptCount: number = 0;
-
-  @ObservedState()
-  validationErrors: string[] = [];
-
-  @ObservedState()
-  finalResult: StrictAnswer | null = null;
-
-  private reflectionManager: ReflectionManager;
-
-  constructor(name: string) {
-    super(name);
-    this.reflectionManager = new ReflectionManager(
-      createReflectionConfig({ enabled: true, maxAttempts: 3 })
-    );
-  }
-
-  @Step({ trackTiming: true, snapshotState: true })
-  async executeWithSchemaValidation(): Promise<StrictAnswer> {
-    this.logger.info('Attempting prompt with strict schema validation');
-
-    // Simulate multiple attempts until schema validates
-    for (let attempt = 1; attempt <= 3; attempt++) {
-      this.attemptCount = attempt;
-      this.logger.info(`Attempt ${attempt}/3`);
-
-      const response = await simulateStrictResponse(attempt);
-
-      // Validate against schema
-      const result = StrictAnswerSchema.safeParse(response);
-
-      if (result.success) {
-        this.logger.info('Schema validation passed!');
-        this.finalResult = result.data;
-        return result.data;
-      }
-
-      // Collect validation errors
-      const errors = result.error.errors.map((e) => `${e.path.join('.')}: ${e.message}`);
-      this.validationErrors.push(...errors);
-      this.logger.warn(`Validation failed: ${errors.join(', ')}`);
-
-      if (attempt < 3) {
-        this.logger.info('Reflecting on error and retrying...');
-        await sleep(100); // Reflection delay
-      }
-    }
-
-    throw new Error('Max reflection attempts exceeded - schema validation failed');
-  }
-
-  async run(): Promise<StrictAnswer | null> {
-    this.setStatus('running');
-    this.logger.info('Starting prompt-level reflection demo');
-
-    try {
-      const result = await this.executeWithSchemaValidation();
-      this.setStatus('completed');
-      return result;
-    } catch (error) {
-      this.logger.error(`Failed after ${this.attemptCount} attempts`);
-      this.setStatus('failed');
-      return null;
-    }
-  }
-}
-
-/**
- * Agent-level reflection demonstration
- */
-class AgentReflectionWorkflow extends Workflow {
-  @ObservedState()
-  reflectionHistory: Array<{
-    attempt: number;
-    action: string;
-    result: string;
-  }> = [];
-
-  @ObservedState()
-  analysisResult: Analysis | null = null;
-
-  constructor(name: string) {
-    super(name);
-  }
-
-  @Step({ trackTiming: true, snapshotState: true, name: 'reflect-analysis' })
-  async reflectOnAnalysis(): Promise<Analysis> {
-    this.logger.info('Agent reflecting on analysis approach');
-
-    // Step 1: Initial reasoning
-    this.reflectionHistory.push({
-      attempt: 1,
-      action: 'Initial reasoning',
-      result: 'Considering multiple analysis angles',
-    });
-    await sleep(50);
-
-    // Step 2: Self-correction
-    this.reflectionHistory.push({
-      attempt: 2,
-      action: 'Self-correction',
-      result: 'Identified potential bias in initial approach',
-    });
-    await sleep(50);
-
-    // Step 3: Revised approach
-    this.reflectionHistory.push({
-      attempt: 3,
-      action: 'Revised analysis',
-      result: 'Applied broader perspective for balanced view',
-    });
-    await sleep(50);
-
-    // Final result after reflection
-    const result = await simulateAnalysis();
-    this.analysisResult = result;
-
-    return result;
-  }
-
-  @Step({ snapshotState: true })
-  async summarizeReflection(): Promise<string> {
-    const summary = `
-Reflection Summary:
-  Total steps: ${this.reflectionHistory.length}
-  ${this.reflectionHistory.map((r) => `  - ${r.action}: ${r.result}`).join('\n')}
-    `.trim();
-
-    this.logger.info('Reflection process complete');
-    return summary;
-  }
-
-  async run(): Promise<Analysis | null> {
-    this.setStatus('running');
-    this.logger.info('Starting agent-level reflection demo');
-
-    // System prompt would include reflection instructions:
-    // "Before answering, reflect on your reasoning step by step.
-    //  Consider alternative approaches and potential errors.
-    //  Then provide your final answer."
-
-    const result = await this.reflectOnAnalysis();
-    await this.summarizeReflection();
-
-    this.setStatus('completed');
-    return result;
-  }
-}
-
-/**
- * Workflow-level reflection demonstration
- */
-class WorkflowReflectionWorkflow extends Workflow {
-  @ObservedState()
-  stepAttempts: Record<string, number> = {};
-
-  @ObservedState()
-  failureReasons: string[] = [];
-
-  @ObservedState()
-  successfulSteps: string[] = [];
-
-  private reflectionManager: ReflectionManager;
-
-  constructor(name: string) {
-    super(name);
-    this.reflectionManager = new ReflectionManager(
-      createReflectionConfig({ enabled: true, maxAttempts: 3, retryDelayMs: 100 })
-    );
-
-    // Set event emitter for reflection events
-    this.reflectionManager.setEventEmitter((event) => {
-      if (event.type === 'reflectionStart') {
-        this.logger.info(`Reflection started at ${event.level} level`);
-      } else if (event.type === 'reflectionEnd') {
-        this.logger.info(`Reflection ended: ${event.success ? 'will retry' : 'will abort'}`);
-      }
-    });
-  }
-
-  @Step({ trackTiming: true, snapshotState: true })
-  async unreliableStep(): Promise<string> {
-    const stepName = 'unreliableStep';
-    this.stepAttempts[stepName] = (this.stepAttempts[stepName] ?? 0) + 1;
-    const attempt = this.stepAttempts[stepName];
-
-    this.logger.info(`Executing unreliable step (attempt ${attempt})`);
-
-    // Simulate failure on first 2 attempts
-    if (attempt < 3) {
-      const reason = `Transient failure on attempt ${attempt}`;
-      this.failureReasons.push(reason);
-      throw new Error(reason);
-    }
-
-    this.successfulSteps.push(stepName);
-    return `Success on attempt ${attempt}`;
-  }
-
-  @Step({ trackTiming: true, snapshotState: true })
-  async reliableStep(): Promise<string> {
-    const stepName = 'reliableStep';
-    this.stepAttempts[stepName] = 1;
-    this.logger.info('Executing reliable step');
-    await sleep(50);
-    this.successfulSteps.push(stepName);
-    return 'Reliable step completed';
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.logger.info('Starting workflow-level reflection demo');
-
-    // Create mock node for reflection context
-    const mockNode: WorkflowNode = {
-      id: this.id,
-      name: this.name,
-      status: 'running',
-      children: [],
-      events: [],
-    };
-
-    // Execute unreliable step with reflection wrapper
-    try {
-      await executeWithReflection(
-        () => this.unreliableStep(),
-        this.reflectionManager,
-        (error, attempt, history) => ({
-          level: 'workflow',
-          failedNode: mockNode,
-          error,
-          attemptNumber: attempt,
-          previousAttempts: history,
-        })
-      );
-    } catch (error) {
-      this.logger.error(`Step failed after max attempts: ${(error as Error).message}`);
-    }
-
-    // Execute reliable step
-    await this.reliableStep();
-
-    this.logger.info(`Completed steps: ${this.successfulSteps.join(', ')}`);
-    this.logger.info(`Total failures: ${this.failureReasons.length}`);
-
-    this.setStatus('completed');
-  }
-}
-
-/**
- * Combined multi-level reflection demonstration
- */
-class MultiLevelReflectionWorkflow extends Workflow {
-  @ObservedState()
-  reflectionEvents: Array<{
-    level: string;
-    type: string;
-    timestamp: number;
-  }> = [];
-
-  private reflectionManager: ReflectionManager;
-
-  constructor(name: string) {
-    super(name);
-    this.reflectionManager = new ReflectionManager(
-      createReflectionConfig({ enabled: true, maxAttempts: 3 })
-    );
-
-    this.reflectionManager.setEventEmitter((event) => {
-      if (event.type === 'reflectionStart' || event.type === 'reflectionEnd') {
-        this.reflectionEvents.push({
-          level: (event as { level: string }).level,
-          type: event.type,
-          timestamp: Date.now(),
-        });
-      }
-    });
-  }
-
-  @Step({ trackTiming: true, snapshotState: true, name: 'prompt-level' })
-  async promptLevelReflection(): Promise<void> {
-    this.logger.info('Prompt-level: Schema validation with retry');
-    this.reflectionEvents.push({
-      level: 'prompt',
-      type: 'validation',
-      timestamp: Date.now(),
-    });
-    await sleep(50);
-  }
-
-  @Step({ trackTiming: true, snapshotState: true, name: 'agent-level' })
-  async agentLevelReflection(): Promise<void> {
-    this.logger.info('Agent-level: Self-correction before final answer');
-    this.reflectionEvents.push({
-      level: 'agent',
-      type: 'self-correction',
-      timestamp: Date.now(),
-    });
-    await sleep(50);
-  }
-
-  @Step({ trackTiming: true, snapshotState: true, name: 'workflow-level' })
-  async workflowLevelReflection(): Promise<void> {
-    this.logger.info('Workflow-level: Step retry on failure');
-    this.reflectionEvents.push({
-      level: 'workflow',
-      type: 'step-retry',
-      timestamp: Date.now(),
-    });
-    await sleep(50);
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.logger.info('Starting multi-level reflection demonstration');
-
-    await this.promptLevelReflection();
-    await this.agentLevelReflection();
-    await this.workflowLevelReflection();
-
-    this.logger.info(`Total reflection events: ${this.reflectionEvents.length}`);
-    this.setStatus('completed');
-  }
-}
-
-// ============================================================================
-// Main Example Runner
-// ============================================================================
-
-/**
- * Run the Multi-level Reflection example
- */
-export async function runReflectionExample(): Promise<void> {
-  printHeader('Example 9: Multi-level Reflection');
-
-  // Part 1: Prompt-Level Reflection
-  printSection('Part 1: Prompt-Level Reflection (Schema Validation)');
-  {
-    console.log('Demonstrates: enableReflection on prompt config');
-    console.log('Behavior: Auto-retry when schema validation fails\n');
-
-    const workflow = new PromptReflectionWorkflow('PromptReflection');
-    const debugger_ = new WorkflowTreeDebugger(workflow);
-
-    const result = await workflow.run();
-
-    console.log('\nExecution summary:');
-    console.log(`  Attempts: ${workflow.attemptCount}`);
-    console.log(`  Validation errors: ${workflow.validationErrors.length}`);
-    if (workflow.validationErrors.length > 0) {
-      console.log(`  Errors encountered:`);
-      for (const error of workflow.validationErrors) {
-        console.log(`    - ${error}`);
-      }
-    }
-
-    if (result) {
-      console.log(`\nFinal result:`);
-      console.log(`  Answer: ${result.answer.slice(0, 50)}...`);
-      console.log(`  Confidence: ${result.confidence}`);
-    }
-
-    console.log('\nTree:');
-    console.log(debugger_.toTreeString());
-  }
-
-  // Part 2: Agent-Level Reflection
-  printSection('Part 2: Agent-Level Reflection (Self-Correction)');
-  {
-    console.log('Demonstrates: agent.reflect() method with system prompt prefix');
-    console.log('Behavior: Agent reviews reasoning before final answer\n');
-
-    const workflow = new AgentReflectionWorkflow('AgentReflection');
-    const debugger_ = new WorkflowTreeDebugger(workflow);
-
-    const result = await workflow.run();
-
-    console.log('Reflection history:');
-    for (const entry of workflow.reflectionHistory) {
-      console.log(`  ${entry.attempt}. ${entry.action}: ${entry.result}`);
-    }
-
-    if (result) {
-      console.log(`\nAnalysis result:`);
-      console.log(`  Summary: ${result.summary}`);
-      console.log(`  Key points: ${result.keyPoints.length}`);
-      console.log(`  Recommendation: ${result.recommendation}`);
-    }
-
-    console.log('\nTree:');
-    console.log(debugger_.toTreeString());
-  }
-
-  // Part 3: Workflow-Level Reflection
-  printSection('Part 3: Workflow-Level Reflection (Step Retry)');
-  {
-    console.log('Demonstrates: executeWithReflection() wrapper');
-    console.log('Behavior: Retry failed steps with reflection analysis\n');
-
-    const workflow = new WorkflowReflectionWorkflow('WorkflowReflection');
-    const debugger_ = new WorkflowTreeDebugger(workflow);
-
-    await workflow.run();
-
-    console.log('\nStep attempt summary:');
-    for (const [step, attempts] of Object.entries(workflow.stepAttempts)) {
-      console.log(`  ${step}: ${attempts} attempt(s)`);
-    }
-
-    console.log(`\nFailure reasons:`);
-    for (const reason of workflow.failureReasons) {
-      console.log(`  - ${reason}`);
-    }
-
-    console.log(`\nSuccessful steps: ${workflow.successfulSteps.join(', ')}`);
-
-    // Show reflection history
-    const history = workflow['reflectionManager'].getReflectionHistory();
-    console.log(`\nReflection history entries: ${history.length}`);
-    for (const entry of history) {
-      console.log(`  [${entry.level}] ${entry.reason} -> ${entry.resolution}`);
-    }
-
-    console.log('\nTree:');
-    console.log(debugger_.toTreeString());
-  }
-
-  // Part 4: Multi-Level Combined
-  printSection('Part 4: Multi-Level Reflection Overview');
-  {
-    console.log('All three levels working together:\n');
-
-    const workflow = new MultiLevelReflectionWorkflow('MultiLevelReflection');
-    const debugger_ = new WorkflowTreeDebugger(workflow);
-
-    await workflow.run();
-
-    console.log('Reflection events by level:');
-    const byLevel = workflow.reflectionEvents.reduce(
-      (acc, event) => {
-        acc[event.level] = (acc[event.level] ?? 0) + 1;
-        return acc;
-      },
-      {} as Record<string, number>
-    );
-
-    for (const [level, count] of Object.entries(byLevel)) {
-      console.log(`  ${level}: ${count} event(s)`);
-    }
-
-    console.log('\nReflection configuration defaults:');
-    console.log(`  Enabled: ${DEFAULT_REFLECTION_CONFIG.enabled}`);
-    console.log(`  Max attempts: ${DEFAULT_REFLECTION_CONFIG.maxAttempts}`);
-    console.log(`  Retry delay: ${DEFAULT_REFLECTION_CONFIG.retryDelayMs}ms`);
-
-    console.log('\nTree:');
-    console.log(debugger_.toTreeString());
-
-    const stats = debugger_.getStats();
-    console.log('\nFinal statistics:', stats);
-  }
-
-  console.log('\n=== Example 9 Complete ===');
-}
-
-// Allow direct execution
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runReflectionExample().catch(console.error);
-}