Prompt Auto-Optimizer MCP

# GEPA Migration Guide *Upgrading and Migration Strategies for GEPA MCP Server* ## Table of Contents 1. [Migration Overview](#migration-overview) 2. [Version Compatibility](#version-compatibility) 3. [Pre-Migration Checklist](#pre-migration-checklist) 4. [Migration Procedures](#migration-procedures) 5. [Data Migration](#data-migration) 6. [Configuration Migration](#configuration-migration) 7. [Breaking Changes](#breaking-changes) 8. [Rollback Procedures](#rollback-procedures) 9. [Testing Migration](#testing-migration) 10. [Post-Migration Validation](#post-migration-validation) ## Migration Overview ### Migration Types GEPA supports several migration scenarios: 1. **Version Upgrades**: Moving to newer GEPA versions 2. **Environment Migration**: Dev → Staging → Production 3. **Infrastructure Migration**: Different servers or cloud providers 4. **Configuration Migration**: Updating settings and parameters 5. **Data Migration**: Moving trajectories, candidates, and metrics ### Migration Philosophy - **Zero Downtime**: Migrations should minimize service interruption - **Data Integrity**: All evolution data must be preserved - **Backward Compatibility**: Gradual transition support - **Rollback Capability**: Quick reversion if issues arise - **Validation**: Comprehensive testing at each step ## Version Compatibility ### Supported Migration Paths ``` v0.x → v1.0 (Major upgrade with breaking changes) v1.0 → v1.1 (Minor upgrade, backward compatible) v1.1 → v1.2 (Minor upgrade, backward compatible) v1.x → v2.0 (Major upgrade with breaking changes) ``` ### Version Compatibility Matrix | From Version | To Version | Migration Type | Complexity | Data Migration Required | |--------------|------------|----------------|------------|------------------------| | v0.9.x | v1.0.x | Major | High | Yes | | v1.0.x | v1.1.x | Minor | Low | No | | v1.1.x | v1.2.x | Minor | Low | No | | v1.x.x | v2.0.x | Major | High | Yes | ### Deprecation Timeline | Feature | Deprecated In | Removed In | Migration Path | |---------|---------------|------------|----------------| | Legacy evolution API | v1.0 | v2.0 | Use new evolution tools | | Old config format | v1.1 | v1.3 | Update config schema | | Synchronous evaluation | v1.2 | v1.4 | Use async evaluation | ## Pre-Migration Checklist ### Environment Assessment ```bash # Check current version npm list gepa-mcp-server # Verify system requirements node --version # Should be >= 18.0.0 npm --version # Should be >= 8.0.0 # Check available disk space df -h # Check memory availability free -h # Verify backup storage ls -la ./backups/ ``` ### Data Inventory ```bash # Check data directory size du -sh ./data/ # Count trajectory files find ./data/trajectories -name "*.json" | wc -l # Check evolution state ls -la ./data/evolution/ # Verify backup integrity npm run verify-backups ``` ### System Health Check ```bash # Run comprehensive health check npm run health-check # Check for memory leaks npm run test:memory-leak # Verify component integrity npm run test:integration # Performance baseline npm run benchmark > pre-migration-benchmark.txt ``` ### Backup Creation ```bash # Create full system backup npm run create-backup -- --label "pre-migration-$(date +%Y%m%d)" # Verify backup integrity npm run verify-backup -- --latest # Test backup restoration (in test environment) npm run test-restore -- --backup-id latest ``` ## Migration Procedures ### Procedure 1: Minor Version Upgrade (v1.x to v1.y) **Complexity**: Low **Downtime**: < 5 minutes **Risk**: Low ```bash # Step 1: Create backup npm run create-backup -- --label "upgrade-to-v1.$(date +%m%d)" # Step 2: Stop services gracefully npm run stop # Step 3: Update package npm update gepa-mcp-server # Step 4: Verify installation npm run verify-installation # Step 5: Start services npm run start # Step 6: Validate functionality npm run test:smoke ``` ### Procedure 2: Major Version Upgrade (v1.x to v2.x) **Complexity**: High **Downtime**: 30-60 minutes **Risk**: Medium ```bash # Step 1: Comprehensive backup npm run create-backup -- --full --label "major-upgrade-$(date +%Y%m%d)" # Step 2: Export current data npm run export-data -- --format=migration --output=./migration-data/ # Step 3: Stop all services npm run stop-all # Step 4: Install new version npm install gepa-mcp-server@2.0.0 # Step 5: Run migration scripts npm run migrate -- --from=v1 --to=v2 # Step 6: Validate migration npm run validate-migration # Step 7: Start services npm run start # Step 8: Comprehensive testing npm run test:post-migration ``` ### Procedure 3: Environment Migration **Complexity**: Medium **Downtime**: Variable **Risk**: Medium ```bash # Source Environment (Export) # Step 1: Create migration package npm run export-environment -- --target=production --output=./migration-package/ # Step 2: Verify export integrity npm run verify-export -- --package=./migration-package/ # Target Environment (Import) # Step 3: Prepare target environment npm run prepare-environment -- --config=production # Step 4: Import migration package npm run import-environment -- --package=./migration-package/ # Step 5: Update configuration for target npm run update-config -- --environment=production # Step 6: Validate import npm run validate-import # Step 7: Start services npm run start -- --environment=production ``` ## Data Migration ### Evolution Data Migration ```bash # Migrate evolution state npm run migrate-evolution-data -- \ --source=./data/evolution/ \ --target=./new-data/evolution/ \ --format=v2 # Migrate prompt candidates npm run migrate-candidates -- \ --source=./data/candidates/ \ --target=./new-data/candidates/ \ --validate=true # Migrate Pareto frontiers npm run migrate-pareto-frontiers -- \ --source=./data/pareto/ \ --target=./new-data/pareto/ \ --recompute=true ``` ### Trajectory Migration ```bash # Migrate trajectory files npm run migrate-trajectories -- \ --source=./data/trajectories/ \ --target=./new-data/trajectories/ \ --batch-size=100 \ --parallel=true # Update trajectory indexes npm run rebuild-trajectory-indexes -- \ --data-dir=./new-data/trajectories/ # Validate trajectory integrity npm run validate-trajectories -- \ --data-dir=./new-data/trajectories/ ``` ### Configuration Data Migration ```bash # Migrate system configuration npm run migrate-config -- \ --source=./config/gepa.config.json \ --target=./new-config/gepa.config.json \ --schema=v2 # Migrate environment settings npm run migrate-env -- \ --source=./.env \ --target=./new-config/.env \ --format=v2 # Validate configuration npm run validate-config -- \ --config=./new-config/gepa.config.json ``` ### Performance Data Migration ```bash # Migrate performance metrics npm run migrate-metrics -- \ --source=./data/metrics/ \ --target=./new-data/metrics/ \ --aggregate=true # Migrate benchmark data npm run migrate-benchmarks -- \ --source=./data/benchmarks/ \ --target=./new-data/benchmarks/ \ --format=v2 ``` ## Configuration Migration ### Configuration Schema Changes #### v1.0 to v2.0 Schema Migration **Old Configuration (v1.0)**: ```json { "evolution": { "population_size": 20, "max_generations": 10, "mutation_rate": 0.15 }, "llm": { "provider": "claude", "concurrent_processes": 3 } } ``` **New Configuration (v2.0)**: ```json { "evolution": { "populationSize": 20, "maxGenerations": 10, "mutationRate": 0.15, "adaptiveRateEnabled": true }, "llmAdapter": { "provider": "claude", "maxConcurrentProcesses": 3, "processTimeout": 30000 }, "memory": { "maxHeapSize": 16384, "gcStrategy": "balanced" } } ``` **Migration Script**: ```bash # Automatic schema migration npm run migrate-config-schema -- \ --from=v1.0 \ --to=v2.0 \ --input=./config/gepa.config.json \ --output=./config/gepa.v2.config.json ``` ### Environment Variable Migration #### Legacy Environment Variables ```bash # v1.0 Environment Variables (deprecated) GEPA_POPULATION_SIZE=20 GEPA_MAX_GENERATIONS=10 GEPA_LLM_PROVIDER=claude GEPA_CONCURRENT_PROCESSES=3 # v2.0 Environment Variables (current) GEPA_DEFAULT_POPULATION_SIZE=20 GEPA_DEFAULT_GENERATIONS=10 GEPA_LLM_ADAPTER_PROVIDER=claude GEPA_MAX_CONCURRENT_PROCESSES=3 GEPA_PROCESS_TIMEOUT=30000 GEPA_ENABLE_ADAPTIVE_RATES=true ``` **Environment Migration Script**: ```bash # Generate new environment file npm run migrate-env-vars -- \ --source=./.env.v1 \ --target=./.env.v2 \ --schema=v2.0 ``` ## Breaking Changes ### Major Breaking Changes by Version #### v1.0 Breaking Changes 1. **API Schema Changes**: - Tool parameter names changed from snake_case to camelCase - New required parameters added - Response format updated 2. **Configuration Changes**: - Configuration file schema updated - Environment variable names changed - New configuration sections added 3. **Data Format Changes**: - Trajectory storage format updated - Candidate representation changed - Performance metrics schema updated #### v2.0 Breaking Changes 1. **Evolution Engine Rewrite**: - New evolution algorithm implementation - Different parameter interpretation - Enhanced performance tracking 2. **Memory Management Overhaul**: - New garbage collection strategies - Updated memory leak detection - Changed memory configuration options 3. **MCP Protocol Updates**: - Updated to latest MCP specification - New tool definitions - Enhanced error handling ### Compatibility Shims ```typescript // Legacy API compatibility layer class LegacyAPICompatibility { static translateLegacyParams(oldParams: any): any { return { // Translate snake_case to camelCase populationSize: oldParams.population_size, maxGenerations: oldParams.max_generations, mutationRate: oldParams.mutation_rate, // Add new required parameters with defaults adaptiveRateEnabled: true, elitismPercentage: 0.1 }; } static translateLegacyResponse(newResponse: any): any { // Convert new response format to legacy format return { success: newResponse.success, data: newResponse.content[0].text, legacy_format: true }; } } ``` ## Rollback Procedures ### Automated Rollback ```bash # Quick rollback to previous version npm run rollback -- --to-version=v1.0.0 # Rollback with data restoration npm run rollback -- \ --to-version=v1.0.0 \ --restore-data \ --backup-id=pre-migration-20240101 # Validate rollback npm run validate-rollback ``` ### Manual Rollback Procedure ```bash # Step 1: Stop current services npm run stop-all # Step 2: Restore previous version npm install gepa-mcp-server@1.0.0 # Step 3: Restore configuration cp ./config/gepa.v1.config.json ./config/gepa.config.json cp ./.env.v1 ./.env # Step 4: Restore data npm run restore-backup -- --backup-id pre-migration-backup # Step 5: Start services npm run start # Step 6: Validate rollback npm run test:rollback-validation ``` ### Rollback Validation ```bash # Check system health after rollback npm run health-check # Verify data integrity npm run verify-data-integrity # Test core functionality npm run test:core-functionality # Compare with pre-migration baseline npm run benchmark-compare -- --baseline=pre-migration-benchmark.txt ``` ## Testing Migration ### Migration Testing Strategy 1. **Unit Tests**: Test individual migration functions 2. **Integration Tests**: Test complete migration workflows 3. **Performance Tests**: Ensure migration doesn't degrade performance 4. **Data Integrity Tests**: Verify no data loss or corruption 5. **Rollback Tests**: Ensure rollback procedures work correctly ### Test Environment Setup ```bash # Create isolated test environment npm run create-test-environment -- --name=migration-test # Populate with test data npm run populate-test-data -- --environment=migration-test # Configure for migration testing npm run configure-test-migration -- --from=v1.0 --to=v2.0 ``` ### Migration Test Execution ```bash # Run migration test suite npm run test:migration # Run specific migration scenarios npm run test:migration -- --scenario=major-upgrade npm run test:migration -- --scenario=environment-migration npm run test:migration -- --scenario=data-migration # Run rollback tests npm run test:rollback ``` ### Performance Impact Testing ```bash # Baseline performance before migration npm run benchmark -- --output=pre-migration-perf.json # Run migration npm run migrate -- --test-mode # Measure performance after migration npm run benchmark -- --output=post-migration-perf.json # Compare performance npm run compare-performance -- \ --before=pre-migration-perf.json \ --after=post-migration-perf.json ``` ## Post-Migration Validation ### Comprehensive Validation Checklist ```bash # System Health Validation npm run health-check -- --comprehensive # Data Integrity Validation npm run validate-data-integrity -- --full # Performance Validation npm run validate-performance -- --compare-baseline # Functionality Validation npm run test:post-migration-functionality # Configuration Validation npm run validate-configuration -- --strict ``` ### Functional Testing ```bash # Test core evolution functionality npm run test:evolution-workflow # Test MCP tool integration npm run test:mcp-tools # Test backup and recovery npm run test:backup-recovery # Test performance monitoring npm run test:performance-monitoring ``` ### Performance Validation ```bash # Memory usage validation npm run validate-memory-usage # Response time validation npm run validate-response-times # Throughput validation npm run validate-throughput # Resource utilization validation npm run validate-resource-usage ``` ### Data Validation ```bash # Validate evolution data npm run validate-evolution-data # Validate trajectory data npm run validate-trajectory-data # Validate configuration data npm run validate-configuration-data # Validate performance metrics npm run validate-performance-metrics ``` ### Integration Validation ```bash # Test Claude Code integration npm run test:claude-code-integration # Test external API integrations npm run test:external-apis # Test monitoring integrations npm run test:monitoring-integration ``` ## Migration Best Practices ### Planning and Preparation 1. **Thorough Testing**: Always test migrations in non-production environments first 2. **Backup Strategy**: Create comprehensive backups before any migration 3. **Rollback Plan**: Always have a tested rollback procedure ready 4. **Monitoring**: Monitor system health throughout the migration process 5. **Documentation**: Document all migration steps and decisions ### Execution Best Practices 1. **Gradual Migration**: Use blue-green or rolling deployments when possible 2. **Validation at Each Step**: Validate data integrity at each migration stage 3. **Performance Monitoring**: Monitor performance throughout the process 4. **Communication**: Keep stakeholders informed of migration progress 5. **Error Handling**: Have procedures for handling migration failures ### Post-Migration Best Practices 1. **Comprehensive Testing**: Test all functionality after migration 2. **Performance Baseline**: Establish new performance baselines 3. **Monitoring Setup**: Ensure monitoring systems are working correctly 4. **Documentation Update**: Update all documentation to reflect changes 5. **Team Training**: Train team members on any new features or changes --- This migration guide provides comprehensive procedures for upgrading and migrating GEPA systems. For additional support during migration, consult the [User Guide](./USER_GUIDE.md), [Configuration Guide](./CONFIGURATION.md), and [Developer Guide](./DEVELOPER_GUIDE.md).