gepa_reflect

Instructions

Implementation Reference

• src/mcp/server.ts:924-1007 (handler)

  The main handler function that executes the gepa_reflect tool logic. Loads execution trajectories, performs batch analysis using ReflectionEngine, processes failure patterns into prioritized improvements, and returns a comprehensive Markdown analysis report.

    private async reflect(params: ReflectParams): Promise<{
      content: { type: string; text: string; }[];
    }> {
      const { trajectoryIds, targetPromptId, analysisDepth = 'deep', focusAreas } = params;
  
      // Validate required parameters
      if (!trajectoryIds || trajectoryIds.length === 0 || !targetPromptId) {
        throw new Error('trajectoryIds and targetPromptId are required');
      }
  
      const reflectionId = `reflection_${Date.now()}_${Math.random().toString(36).substring(7)}`;
  
      try {
        // Load trajectories for analysis
        const trajectories = [];
        for (const trajectoryId of trajectoryIds) {
          try {
            const trajectory = await this.trajectoryStore.load(trajectoryId);
            if (trajectory) {
              trajectories.push(trajectory);
            }
          } catch (error) {
            // eslint-disable-next-line no-console
      console.warn(`Failed to load trajectory ${trajectoryId}:`, error);
          }
        }
  
        if (trajectories.length === 0) {
          throw new Error('No valid trajectories found for analysis');
        }
  
        // Perform failure analysis using reflection engine
        const analysisResult = await this.reflectionEngine.analyzeBatch(trajectories);
  
        // Generate improvement suggestions
        const improvements = analysisResult.commonPatterns.map(pattern => ({
          issue: pattern.description,
          frequency: pattern.frequency,
          severity: pattern.frequency,
          suggestion: `Address ${pattern.type} by improving prompt clarity and specificity`,
          priority: pattern.frequency > 0.7 ? 'High' : pattern.frequency > 0.4 ? 'Medium' : 'Low',
        }));
  
        return {
          content: [
            {
              type: 'text',
              text: `# Reflection Analysis Complete
  
  ## Analysis Details
  - **Reflection ID**: ${reflectionId}
  - **Target Prompt**: ${targetPromptId}
  - **Trajectories Analyzed**: ${trajectories.length}/${trajectoryIds.length}
  - **Analysis Depth**: ${analysisDepth}
  - **Focus Areas**: ${focusAreas?.join(', ') || 'Default'}
  
  ## Failure Pattern Analysis
  - **Patterns Detected**: ${analysisResult.commonPatterns.length}
  - **Recommendations**: ${analysisResult.recommendations.length}
  - **Confidence**: ${(analysisResult.overallConfidence * 100).toFixed(1)}%
  
  ## Key Findings
  ${analysisResult.commonPatterns.slice(0, 5).map((pattern, idx) => 
    `${idx + 1}. **${pattern.type}** (${(pattern.frequency * 100).toFixed(1)}% frequency)
     - Severity: ${(pattern.frequency * 100).toFixed(1)}%
     - Description: ${pattern.description}`
  ).join('\n')}
  
  ## Improvement Recommendations
  ${improvements.slice(0, 5).map((imp, idx) => 
    `${idx + 1}. **${imp.priority} Priority**: ${imp.suggestion}
     - Issue: ${imp.issue}
     - Frequency: ${(imp.frequency * 100).toFixed(1)}%`
  ).join('\n')}
  
  ## Summary
  The analysis identified ${analysisResult.commonPatterns.length} distinct failure patterns across ${trajectories.length} trajectories. Focus on addressing high-priority issues first to maximize improvement impact.`,
            },
          ],
        };
      } catch (error) {
        throw new Error(`Failed to perform reflection analysis: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }

• src/mcp/server.ts:175-204 (schema)

  MCP tool schema definition including name, description, and input validation schema for gepa_reflect, used for tool listing and validation.

  {
    name: 'gepa_reflect',
    description: 'Analyze failures and generate prompt improvements',
    inputSchema: {
      type: 'object',
      properties: {
        trajectoryIds: {
          type: 'array',
          items: { type: 'string' },
          description: 'List of trajectory IDs to analyze for failure patterns'
        },
        targetPromptId: {
          type: 'string',
          description: 'Prompt ID to generate improvements for'
        },
        analysisDepth: {
          type: 'string',
          enum: ['shallow', 'deep'],
          default: 'deep',
          description: 'Depth of failure analysis to perform'
        },
        focusAreas: {
          type: 'array',
          items: { type: 'string' },
          description: 'Specific areas to focus analysis on (optional)'
        }
      },
      required: ['trajectoryIds', 'targetPromptId']
    }
  },

• src/mcp/server.ts:535-536 (registration)

  Tool handler registration in the MCP CallToolRequestSchema switch statement, dispatching calls to the reflect method.

  case 'gepa_reflect':
    return await this.reflect(args as unknown as ReflectParams);

• src/types/gepa.ts:258-263 (schema)

  TypeScript type definition for ReflectParams, providing compile-time validation for the tool's input parameters.

  export interface ReflectParams {
    trajectoryIds: string[];
    targetPromptId: string;
    analysisDepth?: 'shallow' | 'deep';
    focusAreas?: string[];
  }

• src/mcp/types.ts:268-268 (helper)

  TOOL_NAMES constant providing the exact string identifier 'gepa_reflect' for type-safe tool name references.

  REFLECT: 'gepa_reflect',