Skip to main content
Glama

Prompt Auto-Optimizer MCP

by sloth-wq
CONFIGURATION.md26.3 kB
# GEPA Configuration Guide *Complete Reference for Configuring the Genetic Evolutionary Prompt Adaptation System* ## Table of Contents 1. [Configuration Overview](#configuration-overview) 2. [Environment Variables](#environment-variables) 3. [Core Component Configuration](#core-component-configuration) 4. [Performance Tuning](#performance-tuning) 5. [Memory Optimization](#memory-optimization) 6. [Security Configuration](#security-configuration) 7. [Monitoring and Logging](#monitoring-and-logging) 8. [Advanced Configuration](#advanced-configuration) 9. [Deployment Configurations](#deployment-configurations) 10. [Configuration Validation](#configuration-validation) ## Configuration Overview GEPA uses a hierarchical configuration system that supports: - **Environment variables** for runtime settings - **Configuration files** for structured settings - **Programmatic configuration** for dynamic adjustments - **Default values** for rapid deployment ### Configuration Priority Settings are applied in this order (highest to lowest priority): 1. **Runtime parameters** (passed to functions) 2. **Environment variables** (system/container level) 3. **Configuration files** (gepa.config.json, .env) 4. **Default values** (built-in defaults) ### Configuration Structure ```typescript interface GepaConfiguration { // Core system settings system: SystemConfig; // Component-specific settings evolution: EvolutionConfig; pareto: ParetoConfig; reflection: ReflectionConfig; mutator: MutatorConfig; llmAdapter: LLMAdapterConfig; trajectoryStore: TrajectoryStoreConfig; // Performance and resource settings performance: PerformanceConfig; memory: MemoryConfig; // Monitoring and observability monitoring: MonitoringConfig; logging: LoggingConfig; // Security and reliability security: SecurityConfig; resilience: ResilienceConfig; } ``` ## Environment Variables ### Core System Variables ```bash # Node.js and Runtime Configuration NODE_OPTIONS='--max-old-space-size=16384' # Memory allocation (16GB) NODE_ENV=production # Environment: development|test|production # GEPA Core Configuration GEPA_DATA_DIR=./data # Data storage directory GEPA_BACKUP_DIR=./data/backups # Backup storage directory GEPA_LOG_LEVEL=info # Logging level: error|warn|info|debug|trace GEPA_LOG_FORMAT=json # Log format: json|text|structured ``` ### Performance Configuration ```bash # Concurrency and Processing GEPA_MAX_CONCURRENT_PROCESSES=3 # LLM adapter concurrency GEPA_PROCESS_TIMEOUT=30000 # Process timeout (ms) GEPA_MAX_RETRIES=3 # Maximum retry attempts GEPA_RETRY_BASE_DELAY=1000 # Base retry delay (ms) # Resource Limits GEPA_MAX_MEMORY_USAGE=8192 # Max memory usage (MB) GEPA_MAX_FILE_SIZE=10485760 # Max trajectory file size (10MB) GEPA_MAX_POPULATION_SIZE=100 # Maximum evolution population GEPA_MAX_GENERATIONS=50 # Maximum evolution generations ``` ### Evolution Configuration ```bash # Default Evolution Parameters GEPA_DEFAULT_POPULATION_SIZE=20 # Default population size GEPA_DEFAULT_GENERATIONS=10 # Default generation count GEPA_DEFAULT_MUTATION_RATE=0.15 # Default mutation rate (0.0-1.0) GEPA_DEFAULT_CROSSOVER_RATE=0.7 # Default crossover rate (0.0-1.0) GEPA_DEFAULT_ELITISM_PERCENTAGE=0.1 # Default elitism percentage (0.0-1.0) # Convergence and Stopping Criteria GEPA_CONVERGENCE_THRESHOLD=0.001 # Fitness improvement threshold GEPA_CONVERGENCE_GENERATIONS=5 # Generations without improvement to stop GEPA_MIN_DIVERSITY_THRESHOLD=0.1 # Minimum diversity to continue ``` ### Caching Configuration ```bash # Cache Settings GEPA_ENABLE_CACHING=true # Enable result caching GEPA_CACHE_TIMEOUT=3600000 # Cache timeout (1 hour) GEPA_CACHE_MAX_SIZE=1000 # Maximum cache entries GEPA_CACHE_STORAGE_TYPE=memory # Storage type: memory|disk|redis # Cache-specific Settings GEPA_REDIS_URL=redis://localhost:6379 # Redis connection (if using Redis) GEPA_CACHE_COMPRESSION=true # Enable cache compression ``` ### Monitoring Configuration ```bash # Performance Monitoring GEPA_ENABLE_PERFORMANCE_MONITORING=true # Enable performance tracking GEPA_METRICS_COLLECTION_INTERVAL=60000 # Metrics collection interval (ms) GEPA_ENABLE_MEMORY_TRACKING=true # Enable memory usage tracking GEPA_ENABLE_REAL_TIME_MONITORING=false # Real-time monitoring (expensive) # Health Checks GEPA_HEALTH_CHECK_INTERVAL=300000 # Health check interval (5 minutes) GEPA_HEALTH_CHECK_TIMEOUT=10000 # Health check timeout GEPA_ENABLE_AUTO_RECOVERY=true # Enable automatic recovery ``` ### Security Configuration ```bash # Input Validation GEPA_MAX_PROMPT_LENGTH=4000 # Maximum prompt length GEPA_MIN_PROMPT_LENGTH=20 # Minimum prompt length GEPA_ENABLE_CONTENT_FILTERING=true # Enable content safety checks GEPA_PROHIBITED_TERMS="harmful,dangerous" # Comma-separated prohibited terms # Rate Limiting GEPA_RATE_LIMIT_ENABLED=false # Enable rate limiting GEPA_RATE_LIMIT_REQUESTS=100 # Requests per window GEPA_RATE_LIMIT_WINDOW=60000 # Rate limit window (ms) ``` ## Core Component Configuration ### Evolution Engine Configuration ```typescript interface EvolutionConfig { // Basic Parameters taskDescription: string; seedPrompt?: string; targetModules?: string[]; // Population Management populationSize: number; // Default: 20 maxGenerations: number; // Default: 10 elitismPercentage: number; // Default: 0.1 // Genetic Operators mutationRate: number; // Default: 0.15 crossoverRate: number; // Default: 0.7 adaptiveRateEnabled: boolean; // Default: true // Convergence Control convergenceThreshold: number; // Default: 0.001 maxGenerationsWithoutImprovement: number; // Default: 5 minDiversityThreshold: number; // Default: 0.1 // Performance Settings enableParallelEvaluation: boolean; // Default: true maxConcurrentEvaluations: number; // Default: 3 evaluationTimeout: number; // Default: 30000 } ``` **Configuration Examples**: ```typescript // Conservative Configuration (Reliable) const conservativeConfig: EvolutionConfig = { populationSize: 15, maxGenerations: 8, mutationRate: 0.1, crossoverRate: 0.8, elitismPercentage: 0.2, enableParallelEvaluation: false }; // Aggressive Configuration (Exploratory) const aggressiveConfig: EvolutionConfig = { populationSize: 30, maxGenerations: 20, mutationRate: 0.25, crossoverRate: 0.6, elitismPercentage: 0.05, enableParallelEvaluation: true }; // Production Configuration (Balanced) const productionConfig: EvolutionConfig = { populationSize: 20, maxGenerations: 10, mutationRate: 0.15, crossoverRate: 0.7, elitismPercentage: 0.1, enableParallelEvaluation: true, maxConcurrentEvaluations: 2 }; ``` ### Pareto Frontier Configuration ```typescript interface ParetoConfig { // Frontier Management maxSize: number; // Default: 100 archiveEnabled: boolean; // Default: true archiveMaxSize: number; // Default: 500 // Objectives Definition objectives: ParetoObjective[]; // Sampling Strategy samplingStrategy: { name: 'uniform' | 'ucb' | 'epsilon-greedy'; parameters: Record<string, number>; }; // Performance Optimization enableCaching: boolean; // Default: true indexingEnabled: boolean; // Default: true batchProcessingSize: number; // Default: 10 } ``` **Objective Configuration Examples**: ```typescript // Code Generation Objectives const codeObjectives: ParetoObjective[] = [ { name: 'functionality', weight: 0.4, direction: 'maximize', extractor: (candidate) => candidate.taskPerformance.get('functionality') || 0 }, { name: 'readability', weight: 0.3, direction: 'maximize', extractor: (candidate) => candidate.taskPerformance.get('readability') || 0 }, { name: 'efficiency', weight: 0.3, direction: 'maximize', extractor: (candidate) => candidate.taskPerformance.get('efficiency') || 0 } ]; // Content Creation Objectives const contentObjectives: ParetoObjective[] = [ { name: 'quality', weight: 0.5, direction: 'maximize', extractor: (candidate) => candidate.averageScore }, { name: 'creativity', weight: 0.3, direction: 'maximize', extractor: (candidate) => candidate.taskPerformance.get('creativity') || 0 }, { name: 'consistency', weight: 0.2, direction: 'maximize', extractor: (candidate) => 1 - (candidate.performanceVariance || 0) } ]; ``` ### LLM Adapter Configuration ```typescript interface LLMAdapterConfig { // Provider Settings provider: 'claude' | 'openai' | 'custom'; model: string; // Model identifier apiKey?: string; // API key (prefer env var) baseUrl?: string; // Custom API endpoint // Performance Settings maxConcurrentProcesses: number; // Default: 3 processTimeout: number; // Default: 30000 maxRetries: number; // Default: 3 retryBaseDelay: number; // Default: 1000 // Execution Environment executable: string; // Default: 'claude' workingDir: string; // Default: process.cwd() env: Record<string, string>; // Environment variables // Request Configuration temperature?: number; // Model temperature maxTokens?: number; // Maximum response tokens topP?: number; // Nucleus sampling // Safety and Validation enableContentFiltering: boolean; // Default: true validateResponses: boolean; // Default: true sanitizeInputs: boolean; // Default: true } ``` ## Performance Tuning ### Memory Optimization Strategies ```typescript interface MemoryConfig { // Heap Management maxHeapSize: number; // Default: 16384 (MB) gcOptimizationEnabled: boolean; // Default: true gcStrategy: 'aggressive' | 'balanced' | 'conservative'; // Object Pooling enableObjectPooling: boolean; // Default: true poolSizes: { candidates: number; // Default: 100 trajectories: number; // Default: 50 evaluations: number; // Default: 200 }; // Memory Monitoring memoryTrackingEnabled: boolean; // Default: true leakDetectionEnabled: boolean; // Default: true alertThreshold: number; // Default: 80 (% of max heap) // Cleanup Strategies autoCleanupEnabled: boolean; // Default: true cleanupInterval: number; // Default: 300000 (5 minutes) forceGcEnabled: boolean; // Default: false } ``` **Memory Optimization Examples**: ```typescript // High-Performance Configuration const highPerformanceMemory: MemoryConfig = { maxHeapSize: 32768, // 32GB gcStrategy: 'aggressive', enableObjectPooling: true, poolSizes: { candidates: 500, trajectories: 200, evaluations: 1000 }, memoryTrackingEnabled: true, autoCleanupEnabled: true, cleanupInterval: 180000 // 3 minutes }; // Resource-Constrained Configuration const constrainedMemory: MemoryConfig = { maxHeapSize: 4096, // 4GB gcStrategy: 'conservative', enableObjectPooling: true, poolSizes: { candidates: 50, trajectories: 20, evaluations: 100 }, alertThreshold: 70, cleanupInterval: 60000 // 1 minute }; ``` ### Concurrency Configuration ```typescript interface ConcurrencyConfig { // Evolution Parallelism parallelGenerations: boolean; // Default: false parallelEvaluations: boolean; // Default: true maxConcurrentEvaluations: number; // Default: 3 // Component Parallelism parallelMutations: boolean; // Default: true parallelReflection: boolean; // Default: true batchSize: number; // Default: 10 // Resource Management cpuBoundPoolSize: number; // Default: CPU cores ioBoundPoolSize: number; // Default: CPU cores * 2 memoryBoundPoolSize: number; // Default: 1 // Queue Management maxQueueSize: number; // Default: 1000 queueTimeoutMs: number; // Default: 60000 } ``` ### Caching Strategies ```typescript interface CacheConfig { // Cache Types reflectionCache: { enabled: boolean; // Default: true maxSize: number; // Default: 1000 ttl: number; // Default: 3600000 (1 hour) }; evaluationCache: { enabled: boolean; // Default: true maxSize: number; // Default: 5000 ttl: number; // Default: 1800000 (30 minutes) }; mutationCache: { enabled: boolean; // Default: false maxSize: number; // Default: 500 ttl: number; // Default: 900000 (15 minutes) }; // Cache Storage storageType: 'memory' | 'disk' | 'redis'; persistCache: boolean; // Default: false compressionEnabled: boolean; // Default: true } ``` ## Memory Optimization ### Garbage Collection Tuning ```bash # V8 Garbage Collection Options NODE_OPTIONS=" --max-old-space-size=16384 --max-new-space-size=2048 --optimize-for-size --gc-interval=1000 " # Memory-Specific Flags NODE_OPTIONS=" --expose-gc --trace-gc --trace-gc-verbose --max-old-space-size=16384 " ``` ### Memory Leak Prevention ```typescript interface LeakPreventionConfig { // Detection Settings enableLeakDetection: boolean; // Default: true heapSnapshotInterval: number; // Default: 600000 (10 minutes) alertThreshold: number; // Default: 80 (% growth) // Prevention Strategies weakReferencesEnabled: boolean; // Default: true automaticCleanup: boolean; // Default: true circularReferenceDetection: boolean; // Default: true // Resource Limits maxObjectAge: number; // Default: 3600000 (1 hour) maxCacheSize: number; // Default: 1000 forceCleanupThreshold: number; // Default: 90 (% memory usage) } ``` ### Memory Monitoring Configuration ```typescript interface MemoryMonitoringConfig { // Monitoring Intervals basicMonitoringInterval: number; // Default: 60000 (1 minute) detailedMonitoringInterval: number; // Default: 300000 (5 minutes) heapSnapshotInterval: number; // Default: 3600000 (1 hour) // Alert Thresholds memoryAlertThreshold: number; // Default: 80 (%) memoryWarningThreshold: number; // Default: 70 (%) gcPressureThreshold: number; // Default: 0.8 // Reporting enableDetailedReports: boolean; // Default: false reportingInterval: number; // Default: 86400000 (24 hours) retainReports: number; // Default: 7 (days) } ``` ## Security Configuration ### Input Validation ```typescript interface SecurityConfig { // Content Validation enableContentFiltering: boolean; // Default: true maxPromptLength: number; // Default: 4000 minPromptLength: number; // Default: 20 prohibitedTerms: string[]; // Default: ['harmful', 'dangerous'] // Injection Prevention enableSqlInjectionPrevention: boolean; // Default: true enableXssPreventio: boolean; // Default: true enableCommandInjectionPrevention: boolean; // Default: true // Rate Limiting rateLimitEnabled: boolean; // Default: false maxRequestsPerMinute: number; // Default: 60 maxRequestsPerHour: number; // Default: 1000 // Access Control enableApiKeyValidation: boolean; // Default: false allowedOrigins: string[]; // Default: ['*'] enableCors: boolean; // Default: true } ``` ### Data Protection ```typescript interface DataProtectionConfig { // Encryption encryptSensitiveData: boolean; // Default: false encryptionAlgorithm: string; // Default: 'aes-256-gcm' keyRotationInterval: number; // Default: 2592000000 (30 days) // Data Retention dataRetentionDays: number; // Default: 90 autoDeleteOldData: boolean; // Default: true backupRetentionDays: number; // Default: 365 // Privacy anonymizeData: boolean; // Default: false excludeSensitiveFields: string[]; // Default: [] enableDataMasking: boolean; // Default: false } ``` ## Monitoring and Logging ### Logging Configuration ```typescript interface LoggingConfig { // Basic Settings level: 'error' | 'warn' | 'info' | 'debug' | 'trace'; // Default: 'info' format: 'json' | 'text' | 'structured'; // Default: 'json' outputFile?: string; // Optional log file // Component Logging components: { evolution: boolean; // Default: true pareto: boolean; // Default: true reflection: boolean; // Default: true performance: boolean; // Default: true memory: boolean; // Default: false }; // Advanced Logging enableCorrelationIds: boolean; // Default: true enableStackTraces: boolean; // Default: true (dev), false (prod) maxLogFileSize: number; // Default: 104857600 (100MB) maxLogFiles: number; // Default: 5 // External Logging enableElk: boolean; // Default: false elkConfig?: ElkConfig; enableSplunk: boolean; // Default: false splunkConfig?: SplunkConfig; } ``` ### Metrics Configuration ```typescript interface MetricsConfig { // Collection Settings enableMetrics: boolean; // Default: true collectionInterval: number; // Default: 60000 (1 minute) retentionDays: number; // Default: 30 // Metric Categories categories: { performance: boolean; // Default: true memory: boolean; // Default: true evolution: boolean; // Default: true errors: boolean; // Default: true business: boolean; // Default: false }; // Export Configuration exportFormat: 'prometheus' | 'json' | 'csv'; // Default: 'json' exportInterval: number; // Default: 300000 (5 minutes) exportPath?: string; // Default: './metrics' // Alerting enableAlerts: boolean; // Default: false alertThresholds: AlertThresholds; } ``` ## Advanced Configuration ### Custom Component Configuration ```typescript interface CustomComponentConfig { // Custom Mutators customMutators: { [name: string]: { enabled: boolean; weight: number; config: Record<string, any>; }; }; // Custom Objectives customObjectives: { [name: string]: { weight: number; direction: 'maximize' | 'minimize'; extractor: string; // Function as string }; }; // Custom Evaluators customEvaluators: { [name: string]: { enabled: boolean; weight: number; timeout: number; config: Record<string, any>; }; }; } ``` ### Plugin Configuration ```typescript interface PluginConfig { // Plugin Management enablePlugins: boolean; // Default: false pluginDirectory: string; // Default: './plugins' autoLoadPlugins: boolean; // Default: false // Plugin Security sandboxPlugins: boolean; // Default: true pluginTimeout: number; // Default: 30000 maxPluginMemory: number; // Default: 512 (MB) // Specific Plugins plugins: { [pluginName: string]: { enabled: boolean; config: Record<string, any>; }; }; } ``` ## Deployment Configurations ### Development Configuration ```typescript const developmentConfig: GepaConfiguration = { system: { logLevel: 'debug', enableDebugMode: true, dataDirectory: './dev-data' }, evolution: { populationSize: 10, maxGenerations: 5, enableParallelEvaluation: false }, performance: { enablePerformanceMonitoring: true, enableMemoryTracking: true }, memory: { maxHeapSize: 4096, gcStrategy: 'balanced' } }; ``` ### Testing Configuration ```typescript const testingConfig: GepaConfiguration = { system: { logLevel: 'warn', enableDebugMode: false, dataDirectory: './test-data' }, evolution: { populationSize: 5, maxGenerations: 3, processTimeout: 10000 }, caching: { reflectionCache: { enabled: false }, evaluationCache: { enabled: false } }, memory: { maxHeapSize: 2048, leakDetectionEnabled: true } }; ``` ### Production Configuration ```typescript const productionConfig: GepaConfiguration = { system: { logLevel: 'info', enableDebugMode: false, dataDirectory: '/opt/gepa/data' }, evolution: { populationSize: 20, maxGenerations: 10, enableParallelEvaluation: true, maxConcurrentEvaluations: 3 }, performance: { enablePerformanceMonitoring: true, metricsCollectionInterval: 300000 }, memory: { maxHeapSize: 16384, gcStrategy: 'aggressive', enableObjectPooling: true }, security: { enableContentFiltering: true, rateLimitEnabled: true, enableApiKeyValidation: true }, resilience: { enableCircuitBreaker: true, enableGracefulDegradation: true, enableAutoRecovery: true } }; ``` ### High-Availability Configuration ```typescript const haConfig: GepaConfiguration = { system: { enableClusterMode: true, maxWorkers: 4, loadBalancingStrategy: 'round-robin' }, resilience: { enableCircuitBreaker: true, enableGracefulDegradation: true, enableAutoRecovery: true, healthCheckInterval: 30000, maxFailures: 3, recoveryTimeout: 60000 }, backup: { enableAutoBackup: true, backupInterval: 3600000, // 1 hour maxBackups: 24, compressionEnabled: true }, monitoring: { enableRealTimeMonitoring: true, enableAlerting: true, alertWebhooks: ['https://alerts.company.com/webhook'] } }; ``` ## Configuration Validation ### Validation Schema ```typescript import Joi from 'joi'; const configSchema = Joi.object({ system: Joi.object({ logLevel: Joi.string().valid('error', 'warn', 'info', 'debug', 'trace'), dataDirectory: Joi.string().required(), enableDebugMode: Joi.boolean() }), evolution: Joi.object({ populationSize: Joi.number().min(5).max(1000), maxGenerations: Joi.number().min(1).max(100), mutationRate: Joi.number().min(0).max(1), crossoverRate: Joi.number().min(0).max(1) }), memory: Joi.object({ maxHeapSize: Joi.number().min(512).max(65536), gcStrategy: Joi.string().valid('aggressive', 'balanced', 'conservative') }) }); ``` ### Configuration Loading and Validation ```typescript class ConfigurationManager { static loadConfiguration( configPath?: string, environment?: string ): GepaConfiguration { // Load from multiple sources const envConfig = this.loadFromEnvironment(); const fileConfig = this.loadFromFile(configPath); const defaultConfig = this.getDefaults(); // Merge configurations const mergedConfig = this.mergeConfigurations( defaultConfig, fileConfig, envConfig ); // Validate configuration this.validateConfiguration(mergedConfig); return mergedConfig; } static validateConfiguration(config: GepaConfiguration): void { const { error } = configSchema.validate(config); if (error) { throw new ConfigurationError( `Invalid configuration: ${error.message}` ); } // Additional business logic validation this.validateBusinessRules(config); } private static validateBusinessRules(config: GepaConfiguration): void { // Ensure population size is reasonable for generation count if (config.evolution.populationSize > config.evolution.maxGenerations * 10) { throw new ConfigurationError( 'Population size too large for generation count' ); } // Ensure memory allocation is sufficient const minMemory = config.evolution.populationSize * 10; // MB if (config.memory.maxHeapSize < minMemory) { throw new ConfigurationError( `Insufficient memory allocation: need at least ${minMemory}MB` ); } // Validate concurrency settings if (config.performance.maxConcurrentProcesses > require('os').cpus().length * 2) { console.warn('Concurrent processes exceed CPU cores * 2, may cause performance issues'); } } } ``` ### Configuration Examples ```bash # Example .env file for production NODE_ENV=production NODE_OPTIONS='--max-old-space-size=16384' GEPA_DATA_DIR=/opt/gepa/data GEPA_LOG_LEVEL=info GEPA_LOG_FORMAT=json GEPA_DEFAULT_POPULATION_SIZE=20 GEPA_DEFAULT_GENERATIONS=10 GEPA_MAX_CONCURRENT_PROCESSES=3 GEPA_ENABLE_CACHING=true GEPA_CACHE_TIMEOUT=3600000 GEPA_ENABLE_PERFORMANCE_MONITORING=true GEPA_ENABLE_CONTENT_FILTERING=true GEPA_MAX_PROMPT_LENGTH=4000 ``` ```json // Example gepa.config.json { "system": { "logLevel": "info", "dataDirectory": "./data", "enableDebugMode": false }, "evolution": { "populationSize": 20, "maxGenerations": 10, "mutationRate": 0.15, "crossoverRate": 0.7, "enableParallelEvaluation": true }, "pareto": { "maxSize": 100, "samplingStrategy": { "name": "ucb", "parameters": { "confidence": 1.96 } } }, "performance": { "enablePerformanceMonitoring": true, "maxConcurrentProcesses": 3 }, "memory": { "maxHeapSize": 16384, "gcStrategy": "balanced", "enableObjectPooling": true } } ``` This configuration guide provides comprehensive coverage of all GEPA configuration options, from basic setup to advanced production deployments. For implementation examples, see the [User Guide](./USER_GUIDE.md) and [Developer Guide](./DEVELOPER_GUIDE.md).

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sloth-wq/prompt-auto-optimizer-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server