gepa_select_optimal

Instructions

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',