Prompt Auto-Optimizer MCP

Instructions

Implementation Reference

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

  Main handler implementation for 'gepa_reflect' tool. Loads trajectories from store, calls ReflectionEngine.analyzeBatch for analysis, generates improvements, and formats the response.
  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:176-204 (schema)

  JSON schema definition for the 'gepa_reflect' tool input parameters, used for MCP 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-537 (registration)

  Registration of the gepa_reflect tool handler in the MCP request handler switch statement.
  case 'gepa_reflect': return await this.reflect(args as unknown as ReflectParams);
• src/types/gepa.ts:258-263 (schema)

  TypeScript interface defining the input parameters for the gepa_reflect tool.
  export interface ReflectParams { trajectoryIds: string[]; targetPromptId: string; analysisDepth?: 'shallow' | 'deep'; focusAreas?: string[]; }
• src/core/reflection-engine.ts:162-390 (helper)

  Core helper method analyzeBatch in ReflectionEngine class, performing batched trajectory analysis with optimizations, called directly by the tool handler.
  async analyzeBatch(trajectories: ExecutionTrajectory[]): Promise<BatchAnalysisResult> { if (trajectories.length === 0) { throw new Error('At least one trajectory is required for batch analysis'); } // OPTIMIZATION: Parallel validation and preprocessing const validationPromises = trajectories.map(trajectory => Promise.resolve().then(() => this.validateTrajectory(trajectory)) ); await Promise.all(validationPromises); const trajectoryIds = trajectories.map(t => t.id); // OPTIMIZATION: Use optimized batch processor with parallel processing const batchResults = await this.batchProcessor.processTrajectories( trajectories, this.config.batchSize ); // OPTIMIZATION: Enhanced aggregation with pattern deduplication return this.aggregateBatchResultsOptimized(trajectoryIds, batchResults); } /** * Find patterns for trajectories related to a specific prompt (OPTIMIZED) */ async findPatternsForPrompt(promptId: string): Promise<FailurePattern[]> { try { // OPTIMIZATION: Check cache first const cacheKey = `patterns-${promptId}`; const cached = this.memoryManager.getCachedPatterns(cacheKey); if (cached) { return cached; } // OPTIMIZATION: Stream trajectories to avoid loading all at once const trajectories = await this.trajectoryStore.query({ promptId, limit: 100, }); if (trajectories.length === 0) { return []; } // OPTIMIZATION: Use pattern matcher for pre-filtering const relevantTrajectories = this.patternMatcher.filterRelevantTrajectories(trajectories); if (relevantTrajectories.length === 0) { return []; } const batchAnalysis = await this.analyzeBatch(relevantTrajectories); // OPTIMIZATION: Cache the results this.memoryManager.cachePatterns(cacheKey, batchAnalysis.commonPatterns); return batchAnalysis.commonPatterns; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); throw new Error(`Failed to query trajectories: ${errorMessage}`); } } /** * Validate trajectory data integrity */ private validateTrajectory(trajectory: ExecutionTrajectory): void { if (!isExecutionTrajectory(trajectory)) { throw new Error('Invalid trajectory data'); } // Additional validation if (!trajectory.id || !trajectory.promptId || !trajectory.taskId) { throw new Error('Invalid trajectory data'); } if (!trajectory.finalResult || typeof trajectory.finalResult.success !== 'boolean') { throw new Error('Invalid trajectory data'); } } /** * Validate analysis response from LLM */ private validateAnalysisResponse(analysis: unknown): void { if (!analysis || typeof analysis !== 'object') { throw new Error('Invalid analysis response from LLM'); } const analysisObj = analysis as Record<string, unknown>; if (!analysisObj.trajectoryId || !analysisObj.promptId || !analysisObj.diagnosis) { throw new Error('Invalid analysis response from LLM'); } if (!analysisObj.suggestions || !Array.isArray(analysisObj.suggestions)) { throw new Error('Invalid analysis response from LLM'); } if (typeof analysisObj.confidence !== 'number') { throw new Error('Invalid analysis response from LLM'); } } /** * Get cached analysis if available and not expired */ private getCachedAnalysis(trajectoryId: string): ReflectionAnalysis | null { const cached = this.analysisCache.get(trajectoryId); if (!cached) { return null; } const isExpired = Date.now() - cached.timestamp > this.config.cacheTimeout; if (isExpired) { this.analysisCache.delete(trajectoryId); return null; } return cached.analysis; } /** * Cache analysis result */ private cacheAnalysis(trajectoryId: string, analysis: ReflectionAnalysis): void { this.analysisCache.set(trajectoryId, { analysis, timestamp: Date.now(), }); } /** * Aggregate batch results with enhanced optimization */ private aggregateBatchResultsOptimized(trajectoryIds: string[], batchResults: unknown[]): BatchAnalysisResult { const patternMap = new Map<string, { pattern: FailurePattern; trajectorySet: Set<string>; }>(); const allRecommendations: Array<PromptImprovement & { priority: 'low' | 'medium' | 'high' | 'critical'; affectedTrajectories: string[]; }> = []; let totalConfidence = 0; let totalWeight = 0; // Process each batch result for (const result of batchResults) { // Type guard to ensure result is an object with expected properties if (!result || typeof result !== 'object') { continue; } const batchResult = result as { commonPatterns?: Array<{ type: string; frequency: number; description: string; examples: string[]; trajectoryIds?: string[]; }>; recommendations?: Array<PromptImprovement & { priority: 'low' | 'medium' | 'high' | 'critical'; affectedTrajectories: string[]; }>; overallConfidence?: number; }; if (batchResult.commonPatterns) { for (const pattern of batchResult.commonPatterns) { const key = `${pattern.type}:${this.normalizePatternDescription(pattern.description)}`; if (patternMap.has(key)) { const existing = patternMap.get(key); if (!existing) continue; existing.pattern.frequency += pattern.frequency; existing.pattern.examples.push(...pattern.examples.slice(0, 2)); pattern.trajectoryIds?.forEach((id: string) => existing.trajectorySet.add(id)); } else { patternMap.set(key, { pattern: { ...pattern }, trajectorySet: new Set(pattern.trajectoryIds || []) }); } } } if (batchResult.recommendations) { allRecommendations.push(...batchResult.recommendations); } if (typeof batchResult.overallConfidence === 'number') { totalConfidence += batchResult.overallConfidence; totalWeight += 1; } } // Convert patterns and deduplicate const mergedPatterns: FailurePattern[] = Array.from(patternMap.values()).map(({ pattern, trajectorySet }) => ({ ...pattern, examples: pattern.examples.slice(0, 3), // Limit examples trajectoryIds: Array.from(trajectorySet) })); // Filter patterns by minimum frequency const filteredPatterns = mergedPatterns.filter( pattern => pattern.frequency >= this.config.patternMinFrequency ); // Deduplicate and prioritize recommendations const deduplicatedRecommendations = this.deduplicateRecommendations(allRecommendations); // Calculate weighted average confidence const overallConfidence = totalWeight > 0 ? totalConfidence / totalWeight : 0.5; return { trajectoryIds, commonPatterns: filteredPatterns.sort((a, b) => b.frequency - a.frequency), recommendations: deduplicatedRecommendations, overallConfidence, };