gepa_get_pareto_frontier

Instructions

Implementation Reference

• src/mcp/server.ts:1012-1087 (handler)

  The handler function that implements the core logic for the 'gepa_get_pareto_frontier' tool. It fetches the Pareto frontier, applies optional filters for minimum performance and task types, limits the results, and returns formatted statistics and top candidates.

    private async getParetoFrontier(params: GetParetoFrontierParams): Promise<{
      content: { type: string; text: string; }[];
    }> {
      const { minPerformance, taskFilter, limit = 10 } = params;
  
      try {
        // Get current Pareto frontier
        const frontierCandidates = this.paretoFrontier.getFrontier();
        
        // Apply filters
        let filteredCandidates = frontierCandidates;
  
        if (minPerformance !== undefined) {
          filteredCandidates = filteredCandidates.filter(
            frontierPoint => frontierPoint.candidate.averageScore >= minPerformance
          );
        }
  
        if (taskFilter && taskFilter.length > 0) {
          filteredCandidates = filteredCandidates.filter(
            _candidate => {
              // Trajectory ID would be available from candidate.candidate.id if needed
              // In a real implementation, you'd check which tasks the trajectory covered
              return true; // Simplified for now
            }
          );
        }
  
        // Sort by fitness and limit results
        const limitedCandidates = filteredCandidates
          .sort((a, b) => b.candidate.averageScore - a.candidate.averageScore)
          .slice(0, limit);
  
        // Get frontier statistics
        const stats = this.paretoFrontier.getStatistics();
  
        return {
          content: [
            {
              type: 'text',
              text: `# Pareto Frontier Results
  
  ## Query Parameters
  - **Minimum Performance**: ${minPerformance ?? 'None'}
  - **Task Filter**: ${taskFilter?.join(', ') || 'None'}
  - **Limit**: ${limit}
  
  ## Frontier Statistics
  - **Total Candidates**: ${frontierCandidates.length}
  - **Filtered Candidates**: ${filteredCandidates.length}
  - **Returned**: ${limitedCandidates.length}
  - **Frontend Size**: ${stats.frontierSize}
  - **Average Rank**: ${stats.averageRank.toFixed(3)}
  
  ## Top Candidates
  ${limitedCandidates.map((frontierPoint, idx) => 
    `### ${idx + 1}. Candidate ${frontierPoint.candidate.id}
  - **Fitness Score**: ${frontierPoint.candidate.averageScore.toFixed(3)}
  - **Generation**: ${frontierPoint.candidate.generation}
  - **Parent ID**: ${frontierPoint.candidate.parentId || 'None'}
  - **Mutation Type**: ${frontierPoint.candidate.mutationType || 'Unknown'}`
  ).join('\n\n')}
  
  ## Frontier Quality Metrics
  - **Total Candidates**: ${stats.totalCandidates}
  - **Frontend Size**: ${stats.frontierSize}
  - **Average Rank**: ${stats.averageRank.toFixed(3)}
  
  Use \`gepa_select_optimal\` to choose the best candidate for your specific context.`,
            },
          ],
        };
      } catch (error) {
        throw new Error(`Failed to retrieve Pareto frontier: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }

• src/mcp/server.ts:205-227 (schema)

  The tool schema definition including input schema for parameters: minPerformance, taskFilter, and limit. This defines the expected input structure for the MCP tool.

  {
    name: 'gepa_get_pareto_frontier',
    description: 'Retrieve optimal candidates from Pareto frontier',
    inputSchema: {
      type: 'object',
      properties: {
        minPerformance: {
          type: 'number',
          description: 'Minimum performance threshold for candidates (optional)'
        },
        taskFilter: {
          type: 'array',
          items: { type: 'string' },
          description: 'Filter candidates by specific task types (optional)'
        },
        limit: {
          type: 'number',
          default: 10,
          description: 'Maximum number of candidates to return'
        }
      }
    }
  },

• src/mcp/server.ts:538-539 (registration)

  Registration of the tool handler in the MCP request handler switch statement, mapping the tool name to the getParetoFrontier method.

  case 'gepa_get_pareto_frontier':
    return await this.getParetoFrontier(args as unknown as GetParetoFrontierParams);

• src/types/gepa.ts:265-269 (schema)

  TypeScript interface defining the input parameters for the getParetoFrontier handler.

  export interface GetParetoFrontierParams {
    minPerformance?: number;
    taskFilter?: string[];
    limit?: number;
  }

• src/core/pareto-frontier.ts:204-205 (helper)

  Core helper method in ParetoFrontier class that returns the current non-dominated candidates, used by the tool handler.

  getFrontier(): ParetoPoint[] {
    return [...this.frontier];

• src/mcp/server.ts:412-431 (helper)

  Initialization of the ParetoFrontier instance used by the tool, defining objectives for performance and diversity.

  // Initialize Pareto frontier
  this.paretoFrontier = new ParetoFrontier({
    maxSize: 100,
    objectives: [
      { 
        name: 'performance', 
        direction: 'maximize', 
        weight: 0.7,
        extractor: (candidate: GEPAPromptCandidate) => candidate.averageScore
      },
      { 
        name: 'diversity', 
        direction: 'maximize', 
        weight: 0.3,
        extractor: (candidate: GEPAPromptCandidate) => candidate.generation / 10 // Simple diversity metric
      }
    ],
    archiveEnabled: true,
    samplingStrategy: { name: 'ucb', parameters: { exploration: 1.4 } }
  });