gepa_select_optimal
Selects the best prompt candidate for a given context by balancing performance and diversity criteria, optimizing AI prompt effectiveness through evolutionary algorithms.
Instructions
Select best prompt candidate for given context
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| taskContext | No | Context description for prompt selection (optional) | |
| performanceWeight | No | Weight for performance in selection criteria | |
| diversityWeight | No | Weight for diversity in selection criteria |
Implementation Reference
- src/mcp/server.ts:1092-1172 (handler)The core handler function for the 'gepa_select_optimal' tool. It retrieves candidates from the Pareto frontier, samples using UCB strategy, computes weighted scores, and returns detailed selection information including metrics and recommendation.private async selectOptimal(params: SelectOptimalParams): Promise<{ content: { type: string; text: string; }[]; }> { const { taskContext, performanceWeight = 0.7, diversityWeight = 0.3 } = params; // Validate weights sum to 1 if (Math.abs(performanceWeight + diversityWeight - 1.0) > 0.001) { throw new Error('performanceWeight and diversityWeight must sum to 1.0'); } try { // Get current Pareto frontier const frontierCandidates = this.paretoFrontier.getFrontier(); if (frontierCandidates.length === 0) { throw new Error('No candidates available in Pareto frontier'); } // Sample candidate using the specified strategy const selectedCandidate = await this.paretoFrontier.sampleCandidate({ name: 'ucb', parameters: { confidence: 1.96 } }); if (!selectedCandidate) { throw new Error('Failed to select optimal candidate'); } // TypeScript assertion: selectedCandidate is not null after the check above const candidate = selectedCandidate as GEPAPromptCandidate; // Calculate selection metrics const performanceScore = candidate.averageScore; const diversityScore = candidate.generation / 10; // Simple diversity metric const combinedScore = ( performanceScore * performanceWeight + diversityScore * diversityWeight ); // Get frontier statistics for context const stats = this.paretoFrontier.getStatistics(); return { content: [ { type: 'text', text: `# Optimal Candidate Selected ## Selection Context - **Task Context**: ${taskContext || 'General optimization'} - **Performance Weight**: ${(performanceWeight * 100).toFixed(1)}% - **Diversity Weight**: ${(diversityWeight * 100).toFixed(1)}% - **Selection Strategy**: Upper Confidence Bound (UCB) ## Selected Candidate - **Candidate ID**: ${candidate.id} - **Fitness Score**: ${candidate.averageScore.toFixed(3)} - **Combined Score**: ${combinedScore.toFixed(3)} ## Performance Breakdown - **Performance Score**: ${performanceScore.toFixed(3)} (${(performanceScore * 100).toFixed(1)}%) - **Diversity Score**: ${diversityScore.toFixed(3)} (${(diversityScore * 100).toFixed(1)}%) ## Candidate Metadata - **Generation**: ${candidate.generation} - **Parent ID**: ${candidate.parentId || 'None'} - **Mutation Type**: ${candidate.mutationType || 'Unknown'} ## Frontier Context - **Total Candidates**: ${frontierCandidates.length} - **Frontend Size**: ${stats.frontierSize} - **Average Rank**: ${stats.averageRank.toFixed(3)} - **Position in Frontier**: Top ${Math.ceil((1 - candidate.averageScore) * frontierCandidates.length)} ## Recommendation This candidate represents the optimal balance between performance (${(performanceWeight * 100).toFixed(1)}%) and diversity (${(diversityWeight * 100).toFixed(1)}%) for the given context. Use this prompt for your target task.`, }, ], }; } catch (error) { throw new Error(`Failed to select optimal candidate: ${error instanceof Error ? error.message : 'Unknown error'}`); } }
- src/mcp/server.ts:228-250 (schema)The input schema and metadata registration for the gepa_select_optimal tool in the TOOLS array used for MCP list tools endpoint.{ name: 'gepa_select_optimal', description: 'Select best prompt candidate for given context', inputSchema: { type: 'object', properties: { taskContext: { type: 'string', description: 'Context description for prompt selection (optional)' }, performanceWeight: { type: 'number', default: 0.7, description: 'Weight for performance in selection criteria' }, diversityWeight: { type: 'number', default: 0.3, description: 'Weight for diversity in selection criteria' } } } },
- src/mcp/server.ts:541-542 (registration)The switch case registration that routes calls to the gepa_select_optimal tool to its handler method.case 'gepa_select_optimal': return await this.selectOptimal(args as unknown as SelectOptimalParams);
- src/types/gepa.ts:271-275 (schema)TypeScript interface defining the input parameters for the selectOptimal handler.export interface SelectOptimalParams { taskContext?: string; performanceWeight?: number; diversityWeight?: number; }
- src/mcp/types.ts:270-270 (registration)Constant tool name definition in TOOL_NAMES enum/object for type-safe references.SELECT_OPTIMAL: 'gepa_select_optimal',