optimization-tools.md•13.1 kB
# Optimization Tools Reference
This document provides detailed specifications for GEPA MCP tools focused on multi-objective optimization, Pareto frontier management, and optimal candidate selection.
## Table of Contents
- [gepa_get_pareto_frontier](#gepa_get_pareto_frontier)
- [gepa_select_optimal](#gepa_select_optimal)
---
## gepa_get_pareto_frontier
Retrieves optimal prompt candidates from the Pareto frontier based on multi-objective optimization criteria.
### Purpose
The Pareto frontier represents the set of non-dominated solutions in multi-objective optimization. This tool allows you to query the current frontier to understand the trade-offs between different objectives (performance vs. diversity) and retrieve the best candidates for your specific needs.
### Multi-Objective Optimization Concepts
The GEPA system optimizes prompts across multiple objectives simultaneously:
1. **Performance Objective**: Task success rate and quality scores
2. **Diversity Objective**: Population diversity and exploration coverage
3. **Efficiency Objective**: Token usage and execution time (future)
A candidate is **Pareto optimal** if no other candidate performs better on all objectives simultaneously.
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `minPerformance` | `number` | ❌ | Minimum performance threshold (0.0-1.0) |
| `taskFilter` | `string[]` | ❌ | Filter candidates by specific task types |
| `limit` | `number` | ❌ | Maximum number of candidates to return (default: 10) |
### Request Example
```typescript
const response = await mcpClient.callTool('gepa_get_pareto_frontier', {
minPerformance: 0.75,
taskFilter: ['code_generation', 'documentation'],
limit: 15
});
```
### Response Example
```markdown
# Pareto Frontier Results
## Query Parameters
- **Minimum Performance**: 0.75
- **Task Filter**: code_generation, documentation
- **Limit**: 15
## Frontier Statistics
- **Total Candidates**: 47
- **Filtered Candidates**: 23
- **Returned**: 15
- **Frontend Size**: 23
- **Average Rank**: 0.782
## Top Candidates
### 1. Candidate evolution_1733140800_candidate_23
- **Fitness Score**: 0.924
- **Generation**: 8
- **Parent ID**: evolution_1733140800_candidate_19
- **Mutation Type**: reflection
### 2. Candidate evolution_1733140800_candidate_31
- **Fitness Score**: 0.912
- **Generation**: 9
- **Parent ID**: evolution_1733140800_candidate_23
- **Mutation Type**: crossover
### 3. Candidate evolution_1733140800_candidate_28
- **Fitness Score**: 0.897
- **Generation**: 8
- **Parent ID**: evolution_1733140800_candidate_15
- **Mutation Type**: random
### 4. Candidate evolution_1733140800_candidate_35
- **Fitness Score**: 0.889
- **Generation**: 10
- **Parent ID**: evolution_1733140800_candidate_28
- **Mutation Type**: reflection
### 5. Candidate evolution_1733140800_candidate_26
- **Fitness Score**: 0.876
- **Generation**: 7
- **Parent ID**: None
- **Mutation Type**: initial
## Frontier Quality Metrics
- **Total Candidates**: 47
- **Frontend Size**: 23
- **Average Rank**: 0.782
Use `gepa_select_optimal` to choose the best candidate for your specific context.
```
### Frontier Statistics Explained
| Metric | Description | Interpretation |
|--------|-------------|----------------|
| **Total Candidates** | All candidates ever evaluated | Population diversity indicator |
| **Filtered Candidates** | Candidates meeting filter criteria | Relevant solution space size |
| **Frontier Size** | Non-dominated candidates in frontier | Quality of optimization |
| **Average Rank** | Mean performance rank of frontier | Overall solution quality |
### Filtering Options
#### Performance Filtering
```typescript
// Get only high-performing candidates
const highPerformers = await mcpClient.callTool('gepa_get_pareto_frontier', {
minPerformance: 0.9,
limit: 5
});
```
#### Task-Specific Filtering
```typescript
// Get candidates optimized for specific tasks
const taskSpecific = await mcpClient.callTool('gepa_get_pareto_frontier', {
taskFilter: ['api_documentation', 'code_review'],
limit: 20
});
```
#### Large Sample Retrieval
```typescript
// Get comprehensive frontier view
const fullFrontier = await mcpClient.callTool('gepa_get_pareto_frontier', {
limit: 50
});
```
### Error Cases
| Error | Cause | Solution |
|-------|-------|----------|
| `Empty frontier` | No candidates meet criteria | Lower minPerformance threshold |
| `Invalid performance threshold` | Value outside 0.0-1.0 range | Use normalized performance values |
| `No matching tasks` | TaskFilter has no matches | Verify task names exist in system |
| `Limit too large` | Requesting too many results | Reduce limit to ≤ 100 |
---
## gepa_select_optimal
Selects the best prompt candidate for a given context using configurable objective weights and selection strategies.
### Purpose
While the Pareto frontier shows all optimal trade-offs, this tool helps you select the single best candidate for your specific use case by applying context-aware selection criteria and objective weighting.
### Selection Strategies
The system supports multiple selection strategies:
1. **Upper Confidence Bound (UCB)**: Balances exploitation vs. exploration
2. **Weighted Sum**: Linear combination of objectives
3. **Lexicographic**: Priority-ordered objective satisfaction
4. **Interactive**: User-guided selection (future)
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `taskContext` | `string` | ❌ | Context description for selection |
| `performanceWeight` | `number` | ❌ | Weight for performance objective (default: 0.7) |
| `diversityWeight` | `number` | ❌ | Weight for diversity objective (default: 0.3) |
### Weight Configuration Guidelines
| Scenario | Performance Weight | Diversity Weight | Use Case |
|----------|-------------------|------------------|----------|
| **Production Deployment** | 0.9 | 0.1 | Maximum reliability |
| **Exploration Phase** | 0.5 | 0.5 | Balanced optimization |
| **Research & Development** | 0.3 | 0.7 | Novel solution discovery |
| **Incremental Improvement** | 0.8 | 0.2 | Safe optimization |
### Request Example
```typescript
const response = await mcpClient.callTool('gepa_select_optimal', {
taskContext: 'Production API documentation generation with strict quality requirements',
performanceWeight: 0.85,
diversityWeight: 0.15
});
```
### Response Example
```markdown
# Optimal Candidate Selected
## Selection Context
- **Task Context**: Production API documentation generation with strict quality requirements
- **Performance Weight**: 85.0%
- **Diversity Weight**: 15.0%
- **Selection Strategy**: Upper Confidence Bound (UCB)
## Selected Candidate
- **Candidate ID**: evolution_1733140800_candidate_23
- **Fitness Score**: 0.924
- **Combined Score**: 0.891
## Performance Breakdown
- **Performance Score**: 0.924 (92.4%)
- **Diversity Score**: 0.267 (26.7%)
## Candidate Metadata
- **Generation**: 8
- **Parent ID**: evolution_1733140800_candidate_19
- **Mutation Type**: reflection
## Frontier Context
- **Total Candidates**: 47
- **Frontend Size**: 23
- **Average Rank**: 0.782
- **Position in Frontier**: Top 2
## Recommendation
This candidate represents the optimal balance between performance (85.0%) and diversity (15.0%) for the given context. Use this prompt for your target task.
```
### Selection Context Examples
#### High-Stakes Production
```typescript
const productionCandidate = await mcpClient.callTool('gepa_select_optimal', {
taskContext: 'Critical system deployment with zero-tolerance for errors',
performanceWeight: 0.95,
diversityWeight: 0.05
});
```
#### Research Exploration
```typescript
const explorationCandidate = await mcpClient.callTool('gepa_select_optimal', {
taskContext: 'Novel approach discovery for experimental features',
performanceWeight: 0.3,
diversityWeight: 0.7
});
```
#### Balanced Development
```typescript
const balancedCandidate = await mcpClient.callTool('gepa_select_optimal', {
taskContext: 'General-purpose development with moderate risk tolerance',
performanceWeight: 0.6,
diversityWeight: 0.4
});
```
### Advanced Selection Patterns
#### Adaptive Weight Selection
```typescript
// Adjust weights based on system performance
const currentSuccessRate = await getSystemSuccessRate();
const performanceWeight = currentSuccessRate > 0.8 ? 0.5 : 0.9;
const candidate = await mcpClient.callTool('gepa_select_optimal', {
taskContext: 'Adaptive optimization based on current performance',
performanceWeight,
diversityWeight: 1.0 - performanceWeight
});
```
#### Multi-Context Selection
```typescript
// Select different candidates for different contexts
const contexts = [
{ name: 'production', performance: 0.9, diversity: 0.1 },
{ name: 'testing', performance: 0.7, diversity: 0.3 },
{ name: 'research', performance: 0.4, diversity: 0.6 }
];
const selections = await Promise.all(
contexts.map(ctx => mcpClient.callTool('gepa_select_optimal', {
taskContext: `${ctx.name} environment optimization`,
performanceWeight: ctx.performance,
diversityWeight: ctx.diversity
}))
);
```
### Selection Quality Metrics
The selection process provides several quality indicators:
| Metric | Description | Interpretation |
|--------|-------------|----------------|
| **Combined Score** | Weighted sum of objectives | Overall candidate quality |
| **Confidence Interval** | UCB confidence bounds | Selection certainty |
| **Frontier Position** | Rank within Pareto frontier | Relative quality |
| **Generation Depth** | Evolution generation number | Optimization maturity |
### Error Cases
| Error | Cause | Solution |
|-------|-------|----------|
| `Weights don't sum to 1.0` | Invalid weight combination | Ensure weights sum to exactly 1.0 |
| `Empty frontier` | No candidates available | Run evolution and evaluation first |
| `Selection failed` | Algorithm couldn't converge | Try different weight combinations |
| `Invalid context` | Context string too long | Limit context to reasonable length |
---
## Optimization Workflows
### Complete Optimization Cycle
```typescript
// 1. Start with frontier analysis
const frontier = await mcpClient.callTool('gepa_get_pareto_frontier', {
limit: 20
});
// 2. Analyze trade-offs and select based on requirements
if (productionDeployment) {
const optimal = await mcpClient.callTool('gepa_select_optimal', {
taskContext: 'Production deployment',
performanceWeight: 0.9,
diversityWeight: 0.1
});
} else {
const optimal = await mcpClient.callTool('gepa_select_optimal', {
taskContext: 'Development exploration',
performanceWeight: 0.6,
diversityWeight: 0.4
});
}
```
### Multi-Objective Analysis
```typescript
// Analyze frontier composition
const highPerformance = await mcpClient.callTool('gepa_get_pareto_frontier', {
minPerformance: 0.9,
limit: 10
});
const balanced = await mcpClient.callTool('gepa_get_pareto_frontier', {
minPerformance: 0.7,
limit: 20
});
// Compare frontier regions for insights
console.log('High performance candidates:', highPerformance);
console.log('Balanced candidates:', balanced);
```
### Dynamic Selection Strategy
```typescript
class AdaptiveSelector {
async selectForContext(context: string, metrics: SystemMetrics) {
// Adapt weights based on system state
const performanceWeight = this.calculatePerformanceWeight(metrics);
const diversityWeight = 1.0 - performanceWeight;
return await mcpClient.callTool('gepa_select_optimal', {
taskContext: context,
performanceWeight,
diversityWeight
});
}
private calculatePerformanceWeight(metrics: SystemMetrics): number {
// Higher performance weight when system is stable
const stabilityFactor = metrics.errorRate < 0.05 ? 0.8 : 0.5;
const loadFactor = metrics.systemLoad < 0.7 ? 0.8 : 0.6;
return Math.min(0.95, stabilityFactor * loadFactor);
}
}
```
## Best Practices
### Frontier Management
- **Regular Updates**: Keep frontier fresh with new evaluations
- **Size Management**: Monitor frontier size to prevent memory issues
- **Quality Thresholds**: Use appropriate performance filters
- **Diversity Preservation**: Balance exploitation vs. exploration
### Selection Strategy
- **Context Specificity**: Provide detailed context descriptions
- **Weight Calibration**: Test different weight combinations
- **Validation**: Verify selections with real-world testing
- **Adaptation**: Adjust strategy based on results
### Performance Optimization
- **Caching**: Cache frontier queries for repeated access
- **Filtering**: Use specific filters to reduce query scope
- **Batch Operations**: Group related selections together
- **Monitoring**: Track selection quality over time
### Integration Patterns
- **Pipeline Integration**: Embed selection in deployment pipelines
- **A/B Testing**: Compare different selection strategies
- **Monitoring**: Track real-world performance of selected candidates
- **Feedback Loops**: Use deployment results to refine selection criteria