QUICK_REFERENCE.md•14.3 kB
# GEPA Quick Reference
*Essential Commands, Patterns, and Troubleshooting for GEPA*
## Table of Contents
1. [Quick Start Commands](#quick-start-commands)
2. [MCP Tool Reference](#mcp-tool-reference)
3. [Common Patterns](#common-patterns)
4. [Configuration Quick Setup](#configuration-quick-setup)
5. [Troubleshooting Checklist](#troubleshooting-checklist)
6. [Performance Optimization](#performance-optimization-cheat-sheet)
7. [Best Practice Recipes](#best-practice-recipes)
8. [Emergency Procedures](#emergency-procedures)
9. [FAQ Quick Answers](#faq-quick-answers)
## Quick Start Commands
### Installation and Setup
```bash
# Clone and install
git clone <repository-url>
cd gepa-mcp-server
npm install
# Quick build and test
npm run build
npm test
# Start development server
npm run dev
# Start production server
npm run start
```
### Essential Environment Variables
```bash
# Basic setup
export NODE_OPTIONS='--max-old-space-size=8192'
export GEPA_DATA_DIR=./data
export GEPA_LOG_LEVEL=info
# Performance tuning
export GEPA_MAX_CONCURRENT_PROCESSES=3
export GEPA_DEFAULT_POPULATION_SIZE=20
export GEPA_ENABLE_CACHING=true
```
### Claude Code Integration
```bash
# Add GEPA to Claude Code
claude mcp add gepa-mcp-server npx gepa-mcp-server
# Verify connection
claude mcp list
```
## MCP Tool Reference
### Core Evolution Tools
#### `gepa_start_evolution`
**Purpose**: Start genetic evolution process
```json
{
"taskDescription": "Improve customer service prompts",
"seedPrompt": "You are a helpful customer service agent",
"config": {
"populationSize": 20,
"generations": 10,
"mutationRate": 0.15
}
}
```
#### `gepa_evaluate_prompt`
**Purpose**: Test prompt performance
```json
{
"promptId": "candidate_123",
"taskIds": ["customer_service", "technical_support"],
"rolloutCount": 5,
"parallel": true
}
```
#### `gepa_record_trajectory`
**Purpose**: Record execution results
```json
{
"promptId": "candidate_123",
"taskId": "customer_service_task",
"executionSteps": [
{
"action": "analyze_request",
"timestamp": "2024-01-01T10:00:00Z",
"success": true
}
],
"result": {
"success": true,
"score": 0.85
}
}
```
### Analysis Tools
#### `gepa_reflect`
**Purpose**: Analyze failures and generate improvements
```json
{
"trajectoryIds": ["traj_1", "traj_2", "traj_3"],
"targetPromptId": "candidate_123",
"analysisDepth": "deep",
"focusAreas": ["clarity", "specificity"]
}
```
#### `gepa_get_pareto_frontier`
**Purpose**: Get optimal candidates
```json
{
"minPerformance": 0.7,
"taskFilter": ["customer_service"],
"limit": 10
}
```
#### `gepa_select_optimal`
**Purpose**: Choose best candidate for context
```json
{
"taskContext": "High-volume customer support",
"performanceWeight": 0.8,
"diversityWeight": 0.2
}
```
### Recovery Tools
#### `gepa_create_backup`
**Purpose**: Create system backup
```json
{
"label": "pre-production-backup",
"includeTrajectories": true
}
```
#### `gepa_recovery_status`
**Purpose**: Check system health
```json
{
"includeMetrics": true
}
```
## Common Patterns
### Pattern 1: Basic Optimization
```javascript
// 1. Start evolution
await gepa_start_evolution({
taskDescription: "Generate engaging blog posts",
seedPrompt: "Write a blog post about...",
config: { populationSize: 15, generations: 8 }
});
// 2. Get best results
const frontier = await gepa_get_pareto_frontier({
minPerformance: 0.7,
limit: 5
});
// 3. Select optimal
const optimal = await gepa_select_optimal({
performanceWeight: 0.8,
diversityWeight: 0.2
});
```
### Pattern 2: Iterative Improvement
```javascript
// 1. Initial evolution
const firstEvolution = await gepa_start_evolution(initialConfig);
// 2. Analyze failures
const reflection = await gepa_reflect({
trajectoryIds: failedTrajectoryIds,
targetPromptId: bestCandidateId,
analysisDepth: "deep"
});
// 3. Second evolution with insights
const improvedEvolution = await gepa_start_evolution({
...initialConfig,
seedPrompt: improvedPromptFromReflection,
mutationRate: 0.2 // Higher for more exploration
});
```
### Pattern 3: Multi-Objective Optimization
```javascript
// Configure for balanced optimization
const balancedConfig = {
taskDescription: "Create technical documentation",
config: {
populationSize: 25,
generations: 12,
mutationRate: 0.15
}
};
// Evaluate with multiple criteria
await gepa_evaluate_prompt({
promptId: candidateId,
taskIds: ["accuracy", "clarity", "completeness"],
rolloutCount: 8
});
// Select based on weighted objectives
const optimal = await gepa_select_optimal({
taskContext: "Technical documentation for developers",
performanceWeight: 0.6, // Accuracy and functionality
diversityWeight: 0.4 // Clarity and style variety
});
```
### Pattern 4: Production Workflow
```javascript
// 1. Create backup before changes
await gepa_create_backup({
label: `production-backup-${Date.now()}`,
includeTrajectories: true
});
// 2. Conservative evolution
const productionEvolution = {
populationSize: 20,
generations: 10,
mutationRate: 0.1, // Conservative
elitismPercentage: 0.2 // Preserve good candidates
};
// 3. Thorough evaluation
await gepa_evaluate_prompt({
promptId: candidateId,
taskIds: allProductionTasks,
rolloutCount: 10, // More thorough testing
parallel: true
});
// 4. Health check before deployment
await gepa_recovery_status({ includeMetrics: true });
```
## Configuration Quick Setup
### Development Environment
```bash
# .env.development
NODE_ENV=development
NODE_OPTIONS='--max-old-space-size=4096'
GEPA_LOG_LEVEL=debug
GEPA_DEFAULT_POPULATION_SIZE=10
GEPA_DEFAULT_GENERATIONS=5
GEPA_ENABLE_PERFORMANCE_MONITORING=true
```
### Production Environment
```bash
# .env.production
NODE_ENV=production
NODE_OPTIONS='--max-old-space-size=16384'
GEPA_LOG_LEVEL=info
GEPA_DEFAULT_POPULATION_SIZE=20
GEPA_DEFAULT_GENERATIONS=10
GEPA_MAX_CONCURRENT_PROCESSES=3
GEPA_ENABLE_CACHING=true
GEPA_ENABLE_CONTENT_FILTERING=true
```
### Memory-Optimized Setup
```bash
# For resource-constrained environments
NODE_OPTIONS='--max-old-space-size=2048 --optimize-for-size'
GEPA_DEFAULT_POPULATION_SIZE=10
GEPA_MAX_CONCURRENT_PROCESSES=1
GEPA_CACHE_MAX_SIZE=100
```
### High-Performance Setup
```bash
# For high-throughput environments
NODE_OPTIONS='--max-old-space-size=32768'
GEPA_DEFAULT_POPULATION_SIZE=50
GEPA_MAX_CONCURRENT_PROCESSES=8
GEPA_ENABLE_PARALLEL_EVALUATION=true
```
## Troubleshooting Checklist
### Performance Issues
**Symptoms**: Slow evolution, high memory usage, timeouts
**Quick Checks**:
```bash
# Check memory usage
npm run profile:memory
# Check system health
curl -X POST http://localhost:3000 -d '{"tool": "gepa_recovery_status"}'
# Verify configuration
echo $NODE_OPTIONS
echo $GEPA_MAX_CONCURRENT_PROCESSES
```
**Quick Fixes**:
- Reduce population size: `GEPA_DEFAULT_POPULATION_SIZE=10`
- Decrease concurrency: `GEPA_MAX_CONCURRENT_PROCESSES=1`
- Enable caching: `GEPA_ENABLE_CACHING=true`
- Increase memory: `NODE_OPTIONS='--max-old-space-size=8192'`
### Evolution Not Improving
**Symptoms**: Fitness scores plateau, no improvement over generations
**Quick Checks**:
```bash
# Check diversity metrics
# Look for: low mutation rate, small population, insufficient generations
# Verify task description clarity
# Check if evaluation criteria are too strict
```
**Quick Fixes**:
- Increase mutation rate: `mutationRate: 0.25`
- Increase population size: `populationSize: 30`
- Add more generations: `generations: 15`
- Use reflection analysis: `gepa_reflect` with failed trajectories
### Memory Leaks
**Symptoms**: Increasing memory usage, eventual crashes
**Quick Checks**:
```bash
# Enable memory tracking
export GEPA_ENABLE_MEMORY_TRACKING=true
# Run leak detection test
npm run test:memory-leak
# Check object pools
# Look for: circular references, unclosed resources
```
**Quick Fixes**:
- Enable garbage collection: `NODE_OPTIONS='--expose-gc'`
- Force cleanup: Call `global.gc()` periodically
- Reduce cache sizes: `GEPA_CACHE_MAX_SIZE=100`
- Enable auto-cleanup: `GEPA_AUTO_CLEANUP_ENABLED=true`
### Connection Issues
**Symptoms**: MCP connection failures, tool call errors
**Quick Checks**:
```bash
# Verify server is running
ps aux | grep gepa
# Check port availability
netstat -tulpn | grep 3000
# Test MCP connection
claude mcp test gepa-mcp-server
```
**Quick Fixes**:
- Restart server: `npm run start`
- Check firewall settings
- Verify Claude Code configuration
- Use stdio transport instead of port-based
## Performance Optimization Cheat Sheet
### Memory Optimization
```bash
# Enable memory optimizations
export NODE_OPTIONS='--optimize-for-size --max-old-space-size=8192'
export GEPA_ENABLE_OBJECT_POOLING=true
export GEPA_GC_STRATEGY=aggressive
export GEPA_AUTO_CLEANUP_ENABLED=true
```
### CPU Optimization
```bash
# Optimize for CPU-bound tasks
export GEPA_MAX_CONCURRENT_PROCESSES=4 # Match CPU cores
export GEPA_ENABLE_PARALLEL_EVALUATION=true
export GEPA_BATCH_SIZE=10
```
### I/O Optimization
```bash
# Optimize disk and network I/O
export GEPA_ENABLE_CACHING=true
export GEPA_CACHE_COMPRESSION=true
export GEPA_PARALLEL_TRAJECTORIES=true
```
### Network Optimization
```bash
# Optimize for network-bound operations
export GEPA_CONNECTION_POOL_SIZE=10
export GEPA_REQUEST_TIMEOUT=30000
export GEPA_RETRY_ATTEMPTS=3
```
## Best Practice Recipes
### Recipe 1: Content Creation Optimization
```javascript
const contentOptimization = {
taskDescription: "Create engaging, informative content for blog posts",
seedPrompt: "Write a compelling blog post that educates and engages readers",
config: {
populationSize: 25,
generations: 12,
mutationRate: 0.18, // Higher for creativity
crossoverRate: 0.8 // Combine successful elements
}
};
// Focus on creativity and engagement
const contentSelection = {
performanceWeight: 0.6, // Quality is important
diversityWeight: 0.4 // But creativity matters too
};
```
### Recipe 2: Code Generation Optimization
```javascript
const codeOptimization = {
taskDescription: "Generate clean, efficient, well-documented code",
seedPrompt: "Create a function that is readable, efficient, and follows best practices",
config: {
populationSize: 20,
generations: 10,
mutationRate: 0.12, // Conservative for code
elitismPercentage: 0.15 // Preserve working solutions
}
};
// Prioritize functionality and reliability
const codeSelection = {
performanceWeight: 0.85, // Correctness is critical
diversityWeight: 0.15 // Some variety in approach
};
```
### Recipe 3: Customer Service Optimization
```javascript
const customerServiceOptimization = {
taskDescription: "Provide helpful, empathetic customer support responses",
seedPrompt: "Respond to customer inquiries with empathy, clarity, and actionable solutions",
config: {
populationSize: 30,
generations: 15,
mutationRate: 0.15,
crossoverRate: 0.75
}
};
// Balance helpfulness with consistency
const serviceSelection = {
performanceWeight: 0.7, // Effectiveness is key
diversityWeight: 0.3 // But adaptability matters
};
```
### Recipe 4: Data Analysis Optimization
```javascript
const dataAnalysisOptimization = {
taskDescription: "Analyze data comprehensively and provide actionable insights",
seedPrompt: "Examine the data systematically and identify key patterns and recommendations",
config: {
populationSize: 20,
generations: 8,
mutationRate: 0.1, // Conservative for accuracy
crossoverRate: 0.9 // Combine analytical approaches
}
};
// Prioritize accuracy and thoroughness
const analysisSelection = {
performanceWeight: 0.9, // Accuracy is paramount
diversityWeight: 0.1 // Limited variety needed
};
```
## Emergency Procedures
### System Recovery
```bash
# 1. Check system status
npm run health-check
# 2. Create emergency backup
curl -X POST localhost:3000 -d '{
"tool": "gepa_create_backup",
"arguments": {"label": "emergency-backup"}
}'
# 3. Restart components
npm run restart
# 4. Verify recovery
npm run test:integration
```
### Memory Emergency
```bash
# 1. Force garbage collection
kill -USR2 $(pgrep node) # Trigger GC signal
# 2. Reduce memory usage
export GEPA_DEFAULT_POPULATION_SIZE=5
export GEPA_MAX_CONCURRENT_PROCESSES=1
# 3. Restart with lower limits
NODE_OPTIONS='--max-old-space-size=2048' npm run start
```
### Data Recovery
```bash
# 1. List available backups
curl -X POST localhost:3000 -d '{
"tool": "gepa_list_backups"
}'
# 2. Restore from latest backup
curl -X POST localhost:3000 -d '{
"tool": "gepa_restore_backup",
"arguments": {"backupId": "latest-backup-id"}
}'
# 3. Verify data integrity
curl -X POST localhost:3000 -d '{
"tool": "gepa_integrity_check",
"arguments": {"component": "all"}
}'
```
## FAQ Quick Answers
**Q: Evolution is too slow, what can I do?**
A: Reduce population size to 10-15, enable caching, use parallel evaluation sparingly.
**Q: Results aren't improving after many generations?**
A: Increase mutation rate to 0.2-0.3, use reflection analysis, check task description clarity.
**Q: Memory usage keeps growing?**
A: Enable auto-cleanup, reduce cache sizes, use `--optimize-for-size` flag, monitor for leaks.
**Q: How do I know when evolution is done?**
A: Look for fitness plateau (no improvement for 3-5 generations), diversity convergence, or reached target performance.
**Q: Best settings for production use?**
A: Population size 20, generations 10, mutation rate 0.15, enable caching, conservative elitism.
**Q: How to optimize for multiple objectives?**
A: Use Pareto frontier, adjust performance/diversity weights, evaluate across multiple task types.
**Q: System crashed, how to recover?**
A: Check `gepa_recovery_status`, restore from backup if needed, verify with `gepa_integrity_check`.
**Q: Evolution results are inconsistent?**
A: Increase rollout count to 8-10, check evaluation criteria, use more diverse test cases.
---
This quick reference provides essential information for daily GEPA usage. For detailed explanations, see the [User Guide](./USER_GUIDE.md) and [Configuration Guide](./CONFIGURATION.md).