dspy 0.24.2 → 0.25.0

data/lib/dspy/teleprompt/gepa.rb

@@ -24,7 +24,7 @@ module DSPy
         end
       end
 
-      # Enum for crossover operation types  
+      # Enum for crossover operation types
       class CrossoverType < T::Enum
         enums do
           Uniform = new
@@ -59,6 +59,7 @@ module DSPy
             metadata: T.nilable(MetadataHash)
           ).void
         end
+
         def initialize(trace_id:, event_name:, timestamp:, span_id: nil, attributes: {}, metadata: nil)
           # Freeze nested structures for true immutability
           frozen_attributes = attributes.freeze
@@ -236,7 +237,7 @@ module DSPy
         def summary
           confidence_pct = (confidence * 100).round
           mutation_list = suggested_mutations.map(&:to_s).join(', ')
-          
+
           "#{diagnosis.split('.').first}. " \
           "Confidence: #{confidence_pct}%. " \
           "#{improvements.size} improvements suggested. " \
@@ -289,7 +290,7 @@ module DSPy
         def collect_trace(event_name, event_data)
           @traces_mutex.synchronize do
             trace_id = event_data['trace_id'] || event_data[:trace_id] || generate_trace_id
-            
+
             # Avoid duplicates
             return if @traces.any? { |t| t.trace_id == trace_id }
 
@@ -350,7 +351,7 @@ module DSPy
             collect_trace(name, attrs)
           end
 
-          # Subscribe to module events  
+          # Subscribe to module events
           self.class.add_subscription('*.reasoning_complete') do |name, attrs|
             collect_trace(name, attrs)
           end
@@ -394,7 +395,7 @@ module DSPy
               reasoning: 'Cannot provide reflection without execution traces',
               suggested_mutations: [],
               metadata: {
-                reflection_model: @config.reflection_lm,
+                reflection_model: @config.reflection_lm&.model,
                 analysis_timestamp: Time.now,
                 trace_count: 0
               }
@@ -404,7 +405,7 @@ module DSPy
           patterns = analyze_execution_patterns(traces)
           improvements = generate_improvement_suggestions(patterns)
           mutations = suggest_mutations(patterns)
-          
+
           # For Phase 1, we generate a simple rule-based analysis
           # Future phases will use LLM-based reflection
           diagnosis = generate_diagnosis(patterns)
@@ -419,7 +420,7 @@ module DSPy
             reasoning: reasoning,
             suggested_mutations: mutations,
             metadata: {
-              reflection_model: @config.reflection_lm,
+              reflection_model: @config.reflection_lm&.model,
               analysis_timestamp: Time.now,
               trace_count: traces.size,
               token_usage: 0 # Phase 1 doesn't use actual LLM reflection
@@ -485,326 +486,17 @@ module DSPy
           mutations << :combine if llm_count > 2
           mutations << :rewrite if llm_count == 1
           mutations << :rephrase if mutations.empty?
-          
-          mutations.uniq
-        end
-
-        private
-
-        # Generate unique reflection ID
-        sig { returns(String) }
-        def generate_reflection_id
-          "reflection-#{SecureRandom.hex(4)}"
-        end
-
-        # Generate diagnosis text
-        sig { params(patterns: T::Hash[Symbol, T.untyped]).returns(String) }
-        def generate_diagnosis(patterns)
-          if patterns[:total_tokens] > 400
-            'High token usage indicates potential inefficiency in prompt design'
-          elsif patterns[:llm_traces_count] == 0
-            'No LLM interactions found - execution may not be working as expected'
-          elsif patterns[:avg_response_length] < 10
-            'Responses are unusually brief which may indicate prompt clarity issues'
-          else
-            'Execution patterns appear normal with room for optimization'
-          end
-        end
-
-        # Generate reasoning text
-        sig { params(patterns: T::Hash[Symbol, T.untyped], traces: T::Array[ExecutionTrace]).returns(String) }
-        def generate_reasoning(patterns, traces)
-          reasoning_parts = []
-          
-          reasoning_parts << "Analyzed #{traces.size} execution traces"
-          reasoning_parts << "#{patterns[:llm_traces_count]} LLM interactions"
-          reasoning_parts << "#{patterns[:module_traces_count]} module operations"
-          reasoning_parts << "Total token usage: #{patterns[:total_tokens]}"
-          
-          reasoning_parts.join('. ') + '.'
-        end
 
-        # Calculate confidence based on patterns
-        sig { params(patterns: T::Hash[Symbol, T.untyped]).returns(Float) }
-        def calculate_confidence(patterns)
-          base_confidence = 0.7
-          
-          # More traces = higher confidence
-          trace_bonus = [patterns[:llm_traces_count] + patterns[:module_traces_count], 10].min * 0.02
-          
-          # Reasonable token usage = higher confidence
-          token_penalty = patterns[:total_tokens] > 1000 ? -0.1 : 0.0
-          
-          [(base_confidence + trace_bonus + token_penalty), 1.0].min
-        end
-
-        # Calculate average response length from LLM traces
-        sig { params(llm_traces: T::Array[ExecutionTrace]).returns(Integer) }
-        def calculate_avg_response_length(llm_traces)
-          return 0 if llm_traces.empty?
-          
-          total_length = llm_traces.sum do |trace|
-            response = trace.response_text
-            response ? response.length : 0
-          end
-          
-          total_length / llm_traces.size
+          mutations.uniq
         end
 
-        # Calculate timespan of traces
-        sig { params(traces: T::Array[ExecutionTrace]).returns(Float) }
-        def calculate_timespan(traces)
-          return 0.0 if traces.size < 2
-          
-          timestamps = traces.map(&:timestamp).sort
-          (timestamps.last - timestamps.first).to_f
-        end
-        
-        # LLM-based reflection methods for Phase 2
-        
         public
-        
-        # Perform LLM-based reflection on execution traces using DSPy::Predict
-        sig { params(traces: T::Array[ExecutionTrace]).returns(ReflectionResult) }
-        def reflect_with_llm(traces)
-          return reflect_on_traces(traces) if traces.empty?
-          
-          begin
-            # Use DSPy::Predict for analysis instead of raw prompts
-            prediction = analyze_traces_with_dspy(traces)
-            convert_prediction_to_reflection_result(prediction, traces)
-          rescue => e
-            # Fallback to rule-based analysis on LLM failure
-            fallback_result = reflect_on_traces(traces)
-            fallback_result.class.new(
-              trace_id: fallback_result.trace_id,
-              diagnosis: "LLM reflection failed (#{e.message}), using fallback analysis: #{fallback_result.diagnosis}",
-              improvements: fallback_result.improvements,
-              confidence: [fallback_result.confidence * 0.5, 0.5].min,
-              reasoning: "Fallback to rule-based analysis after LLM error: #{fallback_result.reasoning}",
-              suggested_mutations: fallback_result.suggested_mutations,
-              metadata: fallback_result.metadata.merge(
-                llm_error: e.message,
-                fallback_used: true
-              )
-            )
-          end
-        end
-        
-        # Generate structured reflection prompt for LLM (public API)
-        sig { params(traces: T::Array[ExecutionTrace]).returns(String) }
-        def generate_reflection_prompt(traces)
-          if traces.empty?
-            return <<~PROMPT
-              You are analyzing execution traces for a genetic algorithm-based prompt optimization system called GEPA.
-              
-              **Task**: Analyze execution patterns and provide optimization recommendations.
-              
-              **Context**: No execution traces available.
-              
-              Please provide your analysis in the following JSON format:
-              {
-                "diagnosis": "Brief description of what you observed",
-                "improvements": ["List of actionable improvement suggestions"],
-                "confidence": 0.0,
-                "reasoning": "Your reasoning process",
-                "suggested_mutations": ["expand", "rewrite", "simplify", "combine", "rephrase"],
-                "insights": {
-                  "pattern_detected": "no_data",
-                  "optimization_opportunity": "data_collection"
-                }
-              }
-            PROMPT
-          end
-          
-          summary = trace_summary_for_reflection(traces)
-          insights = extract_optimization_insights(traces)
-          
-          <<~PROMPT
-            You are analyzing execution traces for a genetic algorithm-based prompt optimization system called GEPA.
-            
-            **Task**: Analyze execution patterns and provide optimization recommendations for prompt evolution.
-            
-            **Execution Summary**:
-            #{summary}
-            
-            **Optimization Context**:
-            - This is part of a genetic algorithm for prompt optimization
-            - Available mutation types: rewrite, expand, simplify, combine, rephrase
-            - Goal is to improve prompt effectiveness through iterative evolution
-            - Focus on actionable insights that can guide mutation and crossover operations
-            
-            **Key Optimization Insights**:
-            #{insights.map { |k, v| "- #{k}: #{v.is_a?(Hash) ? v.values.join(', ') : v}" }.join("\n")}
-            
-            **Sample Traces**:
-            #{format_traces_for_prompt(traces.take(3))}
-            
-            Please analyze these execution patterns and provide optimization recommendations in the following JSON format:
-            {
-              "diagnosis": "Brief description of execution patterns and issues identified",
-              "improvements": ["List of 2-4 specific, actionable improvement suggestions"],
-              "confidence": 0.85,
-              "reasoning": "Your detailed reasoning process for the analysis",
-              "suggested_mutations": ["List of 2-3 mutation types that would be most beneficial"],
-              "insights": {
-                "pattern_detected": "primary_pattern_identified", 
-                "optimization_opportunity": "key_area_for_improvement"
-              }
-            }
-            
-            Focus on practical recommendations that will improve prompt performance through genetic algorithm evolution.
-          PROMPT
-        end
-        
-        # Parse LLM reflection response into ReflectionResult (public API)
-        sig { params(response_text: String, original_traces: T::Array[ExecutionTrace]).returns(ReflectionResult) }
-        def parse_llm_reflection(response_text, original_traces)
-          reflection_id = generate_reflection_id
-          
-          begin
-            parsed = JSON.parse(response_text)
-            
-            # Extract and validate components
-            diagnosis = parsed['diagnosis'] || 'LLM reflection analysis'
-            improvements = Array(parsed['improvements']).select { |i| i.is_a?(String) && !i.strip.empty? }
-            confidence = [parsed['confidence'].to_f, 1.0].min
-            reasoning = parsed['reasoning'] || 'LLM-based analysis of execution traces'
-            
-            # Validate and sanitize mutation suggestions
-            raw_mutations = Array(parsed['suggested_mutations'])
-            valid_mutations = raw_mutations.filter_map do |mut|
-              mutation_symbol = mut.to_s.downcase.to_sym
-              if [:rewrite, :expand, :simplify, :combine, :rephrase].include?(mutation_symbol)
-                mutation_symbol
-              end
-            end.uniq
-            
-            # Ensure we have at least one valid mutation suggestion
-            valid_mutations = [:rewrite] if valid_mutations.empty?
-            
-            ReflectionResult.new(
-              trace_id: reflection_id,
-              diagnosis: diagnosis,
-              improvements: improvements,
-              confidence: confidence,
-              reasoning: reasoning,
-              suggested_mutations: valid_mutations,
-              metadata: {
-                reflection_model: @config.reflection_lm,
-                analysis_timestamp: Time.now,
-                trace_count: original_traces.size,
-                token_usage: estimate_token_usage(response_text),
-                llm_based: true,
-                insights: parsed['insights'] || {}
-              }
-            )
-            
-          rescue JSON::ParserError => e
-            # Handle malformed JSON response
-            ReflectionResult.new(
-              trace_id: reflection_id,
-              diagnosis: "LLM reflection JSON parsing error: #{e.message}",
-              improvements: ['Review prompt structure and LLM response format'],
-              confidence: 0.3,
-              reasoning: "Failed to parse LLM reflection response as valid JSON",
-              suggested_mutations: [:rewrite],
-              metadata: {
-                reflection_model: @config.reflection_lm,
-                analysis_timestamp: Time.now,
-                trace_count: original_traces.size,
-                token_usage: 0,
-                parsing_error: e.message,
-                raw_response: response_text.length > 500 ? "#{response_text[0..500]}..." : response_text
-              }
-            )
-          end
-        end
-        
-        # Create comprehensive trace summary for reflection (public API)
-        sig { params(traces: T::Array[ExecutionTrace]).returns(String) }
-        def trace_summary_for_reflection(traces)
-          return "No execution traces available" if traces.empty?
-          
-          llm_traces = traces.select(&:llm_trace?)
-          module_traces = traces.select(&:module_trace?)
-          
-          total_tokens = llm_traces.sum(&:token_usage)
-          unique_models = llm_traces.map(&:model_name).compact.uniq
-          timespan = calculate_timespan(traces)
-          
-          avg_response_length = if llm_traces.any?
-            total_length = llm_traces.sum { |t| t.response_text&.length || 0 }
-            total_length / llm_traces.size
-          else
-            0
-          end
-          
-          <<~SUMMARY
-            Total traces: #{traces.size}
-            LLM interactions: #{llm_traces.size}
-            Module calls: #{module_traces.size}
-            Total tokens: #{total_tokens}
-            Models used: #{unique_models.join(', ')}
-            Average response length: #{avg_response_length} characters
-            Execution timespan: #{timespan.round(2)} seconds
-          SUMMARY
-        end
-        
-        # Extract optimization insights from trace analysis (public API)
-        sig { params(traces: T::Array[ExecutionTrace]).returns(T::Hash[Symbol, T.untyped]) }
-        def extract_optimization_insights(traces)
-          llm_traces = traces.select(&:llm_trace?)
-          
-          insights = {
-            token_efficiency: analyze_token_efficiency(llm_traces),
-            response_quality: analyze_response_quality(llm_traces),
-            model_consistency: analyze_model_consistency(llm_traces)
-          }
-          
-          insights
-        end
-        
-        # Reflection with optimization context (public API)
-        sig { params(traces: T::Array[ExecutionTrace], context: T::Hash[Symbol, T.untyped]).returns(ReflectionResult) }
-        def reflection_with_context(traces, context)
-          base_result = reflect_with_llm(traces)
-          
-          # Incorporate context into reasoning
-          context_reasoning = "Generation #{context[:generation] || 'unknown'} analysis. "
-          context_reasoning += "Population size: #{context[:population_size] || 'unknown'}. "
-          
-          if context[:current_best_score]
-            context_reasoning += "Current best score: #{context[:current_best_score]}. "
-          end
-          
-          # Adjust mutation suggestions based on history
-          adjusted_mutations = adjust_mutations_for_history(
-            base_result.suggested_mutations,
-            context[:mutation_history] || [],
-            context[:recent_performance_trend]
-          )
-          
-          ReflectionResult.new(
-            trace_id: base_result.trace_id,
-            diagnosis: base_result.diagnosis,
-            improvements: base_result.improvements,
-            confidence: base_result.confidence,
-            reasoning: context_reasoning + base_result.reasoning,
-            suggested_mutations: adjusted_mutations,
-            metadata: base_result.metadata.merge(optimization_context: context)
-          )
-        end
-        
-        # LLM-based reflection methods for Phase 2
-        
-        public
-        
+
         # Perform LLM-based reflection on execution traces using DSPy::Predict
         sig { params(traces: T::Array[ExecutionTrace]).returns(ReflectionResult) }
         def reflect_with_llm(traces)
           return reflect_on_traces(traces) if traces.empty?
-          
+
           begin
             # Use DSPy::Predict for analysis instead of raw prompts
             prediction = analyze_traces_with_dspy(traces)
@@ -826,7 +518,7 @@ module DSPy
             )
           end
         end
-        
+
         # Generate structured reflection prompt for LLM (public API)
         sig { params(traces: T::Array[ExecutionTrace]).returns(String) }
         def generate_reflection_prompt(traces)
@@ -852,10 +544,10 @@ module DSPy
               }
             PROMPT
           end
-          
+
           summary = trace_summary_for_reflection(traces)
           insights = extract_optimization_insights(traces)
-          
+
           <<~PROMPT
             You are analyzing execution traces for a genetic algorithm-based prompt optimization system called GEPA.
             
@@ -892,21 +584,21 @@ module DSPy
             Focus on practical recommendations that will improve prompt performance through genetic algorithm evolution.
           PROMPT
         end
-        
+
         # Parse LLM reflection response into ReflectionResult (public API)
         sig { params(response_text: String, original_traces: T::Array[ExecutionTrace]).returns(ReflectionResult) }
         def parse_llm_reflection(response_text, original_traces)
           reflection_id = generate_reflection_id
-          
+
           begin
             parsed = JSON.parse(response_text)
-            
+
             # Extract and validate components
             diagnosis = parsed['diagnosis'] || 'LLM reflection analysis'
             improvements = Array(parsed['improvements']).select { |i| i.is_a?(String) && !i.strip.empty? }
             confidence = [parsed['confidence'].to_f, 1.0].min
             reasoning = parsed['reasoning'] || 'LLM-based analysis of execution traces'
-            
+
             # Validate and sanitize mutation suggestions
             raw_mutations = Array(parsed['suggested_mutations'])
             valid_mutations = raw_mutations.filter_map do |mut|
@@ -915,10 +607,10 @@ module DSPy
                 mutation_symbol
               end
             end.uniq
-            
+
             # Ensure we have at least one valid mutation suggestion
             valid_mutations = [:rewrite] if valid_mutations.empty?
-            
+
             ReflectionResult.new(
               trace_id: reflection_id,
               diagnosis: diagnosis,
@@ -927,7 +619,7 @@ module DSPy
               reasoning: reasoning,
               suggested_mutations: valid_mutations,
               metadata: {
-                reflection_model: @config.reflection_lm,
+                reflection_model: @config.reflection_lm&.model,
                 analysis_timestamp: Time.now,
                 trace_count: original_traces.size,
                 token_usage: estimate_token_usage(response_text),
@@ -935,7 +627,7 @@ module DSPy
                 insights: parsed['insights'] || {}
               }
             )
-            
+
           rescue JSON::ParserError => e
             # Handle malformed JSON response
             ReflectionResult.new(
@@ -946,7 +638,7 @@ module DSPy
               reasoning: "Failed to parse LLM reflection response as valid JSON",
               suggested_mutations: [:rewrite],
               metadata: {
-                reflection_model: @config.reflection_lm,
+                reflection_model: @config.reflection_lm&.model,
                 analysis_timestamp: Time.now,
                 trace_count: original_traces.size,
                 token_usage: 0,
@@ -956,26 +648,26 @@ module DSPy
             )
           end
         end
-        
+
         # Create comprehensive trace summary for reflection (public API)
         sig { params(traces: T::Array[ExecutionTrace]).returns(String) }
         def trace_summary_for_reflection(traces)
           return "No execution traces available" if traces.empty?
-          
+
           llm_traces = traces.select(&:llm_trace?)
           module_traces = traces.select(&:module_trace?)
-          
+
           total_tokens = llm_traces.sum(&:token_usage)
           unique_models = llm_traces.map(&:model_name).compact.uniq
           timespan = calculate_timespan(traces)
-          
+
           avg_response_length = if llm_traces.any?
             total_length = llm_traces.sum { |t| t.response_text&.length || 0 }
             total_length / llm_traces.size
           else
             0
           end
-          
+
           <<~SUMMARY
             Total traces: #{traces.size}
             LLM interactions: #{llm_traces.size}
@@ -986,41 +678,41 @@ module DSPy
             Execution timespan: #{timespan.round(2)} seconds
           SUMMARY
         end
-        
+
         # Extract optimization insights from trace analysis (public API)
         sig { params(traces: T::Array[ExecutionTrace]).returns(T::Hash[Symbol, T.untyped]) }
         def extract_optimization_insights(traces)
           llm_traces = traces.select(&:llm_trace?)
-          
+
           insights = {
             token_efficiency: analyze_token_efficiency(llm_traces),
             response_quality: analyze_response_quality(llm_traces),
             model_consistency: analyze_model_consistency(llm_traces)
           }
-          
+
           insights
         end
-        
+
         # Reflection with optimization context (public API)
         sig { params(traces: T::Array[ExecutionTrace], context: T::Hash[Symbol, T.untyped]).returns(ReflectionResult) }
         def reflection_with_context(traces, context)
           base_result = reflect_with_llm(traces)
-          
+
           # Incorporate context into reasoning
           context_reasoning = "Generation #{context[:generation] || 'unknown'} analysis. "
           context_reasoning += "Population size: #{context[:population_size] || 'unknown'}. "
-          
+
           if context[:current_best_score]
             context_reasoning += "Current best score: #{context[:current_best_score]}. "
           end
-          
+
           # Adjust mutation suggestions based on history
           adjusted_mutations = adjust_mutations_for_history(
             base_result.suggested_mutations,
             context[:mutation_history] || [],
             context[:recent_performance_trend]
           )
-          
+
           ReflectionResult.new(
             trace_id: base_result.trace_id,
             diagnosis: base_result.diagnosis,
@@ -1031,22 +723,22 @@ module DSPy
             metadata: base_result.metadata.merge(optimization_context: context)
           )
         end
-        
+
         public
-        
+
         # Create signature for trace reflection analysis (public API)
         sig { returns(T.class_of(DSPy::Signature)) }
         def create_trace_reflection_signature
           @trace_reflection_signature ||= Class.new(DSPy::Signature) do
             description "Analyze execution traces from GEPA optimization system and provide actionable optimization insights"
-            
+
             input do
               const :execution_summary, String, description: "Summary of execution traces and performance patterns"
               const :optimization_context, String, description: "Context about the genetic algorithm optimization goals"
-              const :key_insights, String, description: "Key insights extracted from trace analysis" 
+              const :key_insights, String, description: "Key insights extracted from trace analysis"
               const :sample_traces, String, description: "Representative execution trace samples"
             end
-            
+
             output do
               const :diagnosis, String, description: "Brief description of execution patterns and issues identified"
               const :improvements, T::Array[String], description: "List of 2-4 specific actionable improvement suggestions"
@@ -1060,35 +752,40 @@ module DSPy
         end
 
         # Perform LLM analysis using DSPy::Predict (public API)
-        sig { params(traces: T::Array[ExecutionTrace]).returns(DSPy::Prediction) }
+        sig { params(traces: T::Array[ExecutionTrace]).returns(T.untyped) }
         def analyze_traces_with_dspy(traces)
+          raise ArgumentError, "reflection_lm must be configured on GEPAConfig for LLM-based reflection" unless @config.reflection_lm
+
           predictor = DSPy::Predict.new(create_trace_reflection_signature)
-          
+
+          # Configure predictor to use reflection-specific LM
+          predictor.config.lm = @config.reflection_lm
+
           # Prepare input data
           summary = trace_summary_for_reflection(traces)
           insights = extract_optimization_insights(traces)
           insights_text = insights.map { |k, v| "- #{k}: #{v.is_a?(Hash) ? v.values.join(', ') : v}" }.join("\n")
-          
+
           # Get LLM analysis
-          predictor.call(
+          T.unsafe(predictor.call(
             execution_summary: summary,
             optimization_context: "GEPA genetic algorithm for prompt optimization. Available mutations: rewrite, expand, simplify, combine, rephrase. Goal: improve prompt effectiveness through iterative evolution.",
             key_insights: insights_text,
             sample_traces: format_traces_for_prompt(traces.take(3))
-          )
+          ))
         end
 
         # Convert DSPy prediction to ReflectionResult (public API)
-        sig { params(prediction: DSPy::Prediction, original_traces: T::Array[ExecutionTrace]).returns(ReflectionResult) }
+        sig { params(prediction: T.untyped, original_traces: T::Array[ExecutionTrace]).returns(ReflectionResult) }
         def convert_prediction_to_reflection_result(prediction, original_traces)
           reflection_id = generate_reflection_id
-          
+
           # Extract and validate prediction results
           diagnosis = prediction.diagnosis || 'DSPy reflection analysis'
           improvements = Array(prediction.improvements).select { |i| i.is_a?(String) && !i.strip.empty? }
           confidence = [[prediction.confidence&.to_f || 0.0, 1.0].min, 0.0].max
           reasoning = prediction.reasoning || 'DSPy-based analysis of execution traces'
-          
+
           # Validate mutation suggestions
           valid_mutations = Array(prediction.suggested_mutations).filter_map do |mut|
             mutation_symbol = mut.to_s.downcase.to_sym
@@ -1096,10 +793,10 @@ module DSPy
               mutation_symbol
             end
           end.uniq
-          
+
           # Ensure we have at least one valid mutation suggestion
           valid_mutations = [:rewrite] if valid_mutations.empty?
-          
+
           ReflectionResult.new(
             trace_id: reflection_id,
             diagnosis: diagnosis,
@@ -1108,7 +805,7 @@ module DSPy
             reasoning: reasoning,
             suggested_mutations: valid_mutations,
             metadata: {
-              reflection_model: @config.reflection_lm,
+              reflection_model: @config.reflection_lm&.model,
               analysis_timestamp: Time.now,
               trace_count: original_traces.size,
               token_usage: estimate_token_usage(prediction.to_s),
@@ -1121,9 +818,9 @@ module DSPy
             }
           )
         end
-        
+
         private
-        
+
         # Generate unique reflection ID
         sig { returns(String) }
         def generate_reflection_id
@@ -1148,12 +845,12 @@ module DSPy
         sig { params(patterns: T::Hash[Symbol, T.untyped], traces: T::Array[ExecutionTrace]).returns(String) }
         def generate_reasoning(patterns, traces)
           reasoning_parts = []
-          
+
           reasoning_parts << "Analyzed #{traces.size} execution traces"
           reasoning_parts << "#{patterns[:llm_traces_count]} LLM interactions"
           reasoning_parts << "#{patterns[:module_traces_count]} module operations"
           reasoning_parts << "Total token usage: #{patterns[:total_tokens]}"
-          
+
           reasoning_parts.join('. ') + '.'
         end
 
@@ -1161,13 +858,13 @@ module DSPy
         sig { params(patterns: T::Hash[Symbol, T.untyped]).returns(Float) }
         def calculate_confidence(patterns)
           base_confidence = 0.7
-          
+
           # More traces = higher confidence
           trace_bonus = [patterns[:llm_traces_count] + patterns[:module_traces_count], 10].min * 0.02
-          
+
           # Reasonable token usage = higher confidence
           token_penalty = patterns[:total_tokens] > 1000 ? -0.1 : 0.0
-          
+
           [(base_confidence + trace_bonus + token_penalty), 1.0].min
         end
 
@@ -1175,12 +872,12 @@ module DSPy
         sig { params(llm_traces: T::Array[ExecutionTrace]).returns(Integer) }
         def calculate_avg_response_length(llm_traces)
           return 0 if llm_traces.empty?
-          
+
           total_length = llm_traces.sum do |trace|
             response = trace.response_text
             response ? response.length : 0
           end
-          
+
           total_length / llm_traces.size
         end
 
@@ -1188,11 +885,11 @@ module DSPy
         sig { params(traces: T::Array[ExecutionTrace]).returns(Float) }
         def calculate_timespan(traces)
           return 0.0 if traces.size < 2
-          
+
           timestamps = traces.map(&:timestamp).sort
           (timestamps.last - timestamps.first).to_f
         end
-        
+
 
         # Format traces for inclusion in prompt
         sig { params(traces: T::Array[ExecutionTrace]).returns(String) }
@@ -1203,22 +900,22 @@ module DSPy
             "#{idx + 1}. [#{trace.event_name}] #{prompt_preview} → #{response_preview}"
           end.join("\n")
         end
-        
+
         # Estimate token usage from response
         sig { params(text: String).returns(Integer) }
         def estimate_token_usage(text)
           # Rough estimation: ~4 characters per token
           (text.length / 4.0).ceil
         end
-        
+
         # Analyze token efficiency patterns
         sig { params(llm_traces: T::Array[ExecutionTrace]).returns(T::Hash[Symbol, T.untyped]) }
         def analyze_token_efficiency(llm_traces)
           return { status: 'no_data', suggestions: [] } if llm_traces.empty?
-          
+
           total_tokens = llm_traces.sum(&:token_usage)
           avg_tokens = total_tokens.to_f / llm_traces.size
-          
+
           if avg_tokens > 400
             {
               status: 'poor',
@@ -1239,15 +936,15 @@ module DSPy
             }
           end
         end
-        
+
         # Analyze response quality patterns
         sig { params(llm_traces: T::Array[ExecutionTrace]).returns(T::Hash[Symbol, T.untyped]) }
         def analyze_response_quality(llm_traces)
           return { consistency: 'no_data', recommendations: [] } if llm_traces.empty?
-          
+
           response_lengths = llm_traces.map { |t| t.response_text&.length || 0 }
           length_variance = calculate_variance(response_lengths)
-          
+
           if length_variance > 1000
             {
               consistency: 'inconsistent',
@@ -1265,50 +962,50 @@ module DSPy
             }
           end
         end
-        
+
         # Analyze model consistency
         sig { params(llm_traces: T::Array[ExecutionTrace]).returns(T::Hash[Symbol, T.untyped]) }
         def analyze_model_consistency(llm_traces)
           models = llm_traces.map(&:model_name).compact.uniq
-          
+
           {
             unique_models: models.size,
             models_used: models,
             recommendation: models.size > 1 ? 'Consider using single model for consistency' : 'Model usage is consistent'
           }
         end
-        
+
         # Adjust mutations based on history to avoid repetition
         sig { params(suggested: T::Array[Symbol], history: T::Array[Symbol], trend: T.nilable(String)).returns(T::Array[Symbol]) }
         def adjust_mutations_for_history(suggested, history, trend)
           # Count recent usage of each mutation type
           recent_usage = history.last(5).tally
-          
+
           # Filter out overused mutations
           adjusted = suggested.reject do |mutation|
             recent_usage[mutation] && recent_usage[mutation] >= 2
           end
-          
+
           # If trend is declining, prefer different strategies
           if trend == 'declining'
             adjusted = adjusted.reject { |m| m == :expand } # Avoid expansion if performance declining
             adjusted += [:simplify, :rephrase] unless adjusted.include?(:simplify) || adjusted.include?(:rephrase)
           end
-          
+
           # Ensure we always have at least one suggestion
           adjusted.empty? ? [:rewrite] : adjusted.uniq
         end
-        
+
         # Calculate variance for array of numbers
         sig { params(values: T::Array[Integer]).returns(Float) }
         def calculate_variance(values)
           return 0.0 if values.size < 2
-          
+
           mean = values.sum.to_f / values.size
           sum_squared_diff = values.sum { |v| (v - mean) ** 2 }
           sum_squared_diff / values.size
         end
-        
+
         # Truncate text to specified length with ellipsis
         sig { params(text: String, length: Integer).returns(String) }
         def truncate_text(text, length)
@@ -1325,8 +1022,8 @@ module DSPy
         sig { returns(GEPAConfig) }
         attr_reader :config
 
-        sig { returns(T.proc.params(arg0: T.untyped, arg1: T.untyped).returns(T.untyped)) }
-        attr_reader :metric
+        sig { returns(FitnessEvaluator) }
+        attr_reader :fitness_evaluator
 
         sig { returns(T::Array[T.untyped]) }
         attr_reader :population
@@ -1334,59 +1031,69 @@ module DSPy
         sig { returns(Integer) }
         attr_reader :generation
 
-        sig { params(config: GEPAConfig, metric: T.proc.params(arg0: T.untyped, arg1: T.untyped).returns(T.untyped)).void }
-        def initialize(config:, metric:)
+        sig { params(config: GEPAConfig, fitness_evaluator: FitnessEvaluator).void }
+        def initialize(config:, fitness_evaluator:)
           @config = config
-          @metric = metric
+          @fitness_evaluator = fitness_evaluator
           @population = T.let([], T::Array[T.untyped])
           @generation = 0
-          @fitness_scores = T.let([], T::Array[Float])
+          @fitness_scores = T.let([], T::Array[FitnessScore])
         end
 
         # Initialize population with diverse instruction variants
         sig { params(program: T.untyped).void }
         def initialize_population(program)
           @population = []
-          
+
           # Start with original program
           @population << program
-          
-          # Generate instruction variants to fill population
-          original_instruction = program.signature_class.description
-          variants = generate_instruction_variants(original_instruction)
-          
+
+          # Generate instruction variants to fill population if program has signature_class
+          if program.respond_to?(:signature_class) && program.signature_class.respond_to?(:description)
+            original_instruction = program.signature_class.description
+            if original_instruction && !original_instruction.empty?
+              variants = generate_instruction_variants(original_instruction)
+            else
+              variants = []
+            end
+          else
+            variants = []
+          end
+
           # Create program copies with different instructions
           variants.take(@config.population_size - 1).each do |variant|
             variant_program = create_program_with_instruction(program, variant)
             @population << variant_program
           end
-          
+
           # If we need more candidates, duplicate and mutate
           while @population.size < @config.population_size
             base_program = @population.sample
-            mutated = create_program_with_instruction(base_program, 
-              generate_instruction_variants(base_program.signature_class.description).first)
-            @population << mutated
+            if base_program.respond_to?(:signature_class) && base_program.signature_class.respond_to?(:description)
+              instruction_variants = generate_instruction_variants(base_program.signature_class.description)
+              if instruction_variants.any?
+                mutated = create_program_with_instruction(base_program, instruction_variants.first)
+                @population << mutated
+              else
+                # If no variants available, just duplicate the base program
+                @population << base_program
+              end
+            else
+              # If no signature_class available, just duplicate the base program
+              @population << base_program
+            end
           end
-          
+
           @generation = 0
         end
 
         # Evaluate all population members on the training set
-        sig { params(trainset: T::Array[T.untyped]).returns(T::Array[Float]) }
+        sig { params(trainset: T::Array[T.untyped]).returns(T::Array[FitnessScore]) }
         def evaluate_population(trainset)
           @fitness_scores = @population.map do |candidate|
-            scores = trainset.map do |example|
-              prediction = candidate.call(**example.input_values)
-              @metric.call(example, prediction).to_f
-            rescue => e
-              # Handle evaluation errors gracefully
-              0.0
-            end
-            
-            scores.sum / scores.size
+            @fitness_evaluator.evaluate_candidate(candidate, trainset)
           end
-          
+
           @fitness_scores
         end
 
@@ -1394,27 +1101,32 @@ module DSPy
         sig { params(trainset: T::Array[T.untyped]).void }
         def evolve_generation(trainset)
           current_scores = evaluate_population(trainset)
-          
+
           # Simple selection: keep top 50% and mutate them
-          sorted_indices = (0...@population.size).sort_by { |i| -current_scores[i] }
-          survivors = sorted_indices.take(@config.population_size / 2)
-          
+          sorted_indices = (0...@population.size).sort_by { |i| -current_scores[i].overall_score }
+          survivors = sorted_indices.take([@config.population_size / 2, 1].max)
+
           new_population = []
-          
+
           # Keep best performers
           survivors.each { |i| new_population << @population[i] }
-          
+
           # Fill rest with mutations of survivors
           while new_population.size < @config.population_size
             parent_index = survivors.sample
             parent = @population[parent_index]
-            
-            # Generate mutation
-            variants = generate_instruction_variants(parent.signature_class.description)
-            mutated = create_program_with_instruction(parent, variants.first || parent.signature_class.description)
-            new_population << mutated
+
+            # Generate mutation if parent has signature_class
+            if parent.respond_to?(:signature_class) && parent.signature_class.respond_to?(:description)
+              variants = generate_instruction_variants(parent.signature_class.description)
+              mutated = create_program_with_instruction(parent, variants.first || parent.signature_class.description)
+              new_population << mutated
+            else
+              # If no signature_class, just duplicate the parent
+              new_population << parent
+            end
           end
-          
+
           @population = new_population
           @generation += 1
         end
@@ -1423,35 +1135,46 @@ module DSPy
         sig { params(program: T.untyped, trainset: T::Array[T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
         def run_evolution(program, trainset)
           initialize_population(program)
-          
+
           history = []
-          
+
           # Initial evaluation
           initial_scores = evaluate_population(trainset)
+          best_initial = initial_scores.max_by(&:overall_score)
+          avg_initial = initial_scores.map(&:overall_score).sum / initial_scores.size
           history << {
             generation: 0,
-            best_fitness: initial_scores.max,
-            avg_fitness: initial_scores.sum / initial_scores.size,
+            best_fitness: best_initial.overall_score,
+            avg_fitness: avg_initial,
             diversity: population_diversity
           }
-          
+
           # Evolution loop
           @config.num_generations.times do
             evolve_generation(trainset)
             scores = evaluate_population(trainset)
-            
+            best_score = scores.max_by(&:overall_score)
+            avg_score = scores.map(&:overall_score).sum / scores.size
+
             history << {
               generation: @generation,
-              best_fitness: scores.max,
-              avg_fitness: scores.sum / scores.size,
+              best_fitness: best_score.overall_score,
+              avg_fitness: avg_score,
               diversity: population_diversity
             }
           end
-          
+
+          best_fitness_score = @fitness_scores.max_by(&:overall_score)
           {
             best_candidate: get_best_candidate,
-            best_fitness: @fitness_scores.max,
+            best_fitness: best_fitness_score || FitnessScore.new(
+              primary_score: 0.0,
+              secondary_scores: {},
+              overall_score: 0.0,
+              metadata: {}
+            ),
             generation_history: history,
+            generation_count: @generation,
             final_population: @population.dup
           }
         end
@@ -1460,8 +1183,8 @@ module DSPy
         sig { returns(T.untyped) }
         def get_best_candidate
           return @population.first if @fitness_scores.empty?
-          
-          best_index = @fitness_scores.each_with_index.max_by { |score, _| score }[1]
+
+          best_index = @fitness_scores.each_with_index.max_by { |score, _| score.overall_score }[1]
           @population[best_index]
         end
 
@@ -1469,11 +1192,20 @@ module DSPy
         sig { returns(Float) }
         def population_diversity
           return 0.0 if @population.empty?
-          
-          instructions = @population.map(&:signature_class).map(&:description)
+
+          # Only calculate diversity for programs that have signature_class
+          instructions = @population.filter_map do |program|
+            if program.respond_to?(:signature_class) && program.signature_class.respond_to?(:description)
+              program.signature_class.description
+            else
+              nil
+            end
+          end
+
+          return 0.0 if instructions.empty?
+
           unique_instructions = instructions.uniq.size
-          
-          unique_instructions.to_f / @population.size.to_f
+          unique_instructions.to_f / instructions.size.to_f
         end
 
         private
@@ -1482,32 +1214,32 @@ module DSPy
         sig { params(original_instruction: String).returns(T::Array[String]) }
         def generate_instruction_variants(original_instruction)
           variants = []
-          
+
           # Add "step by step" variant
           unless original_instruction.include?("step")
             variants << "#{original_instruction} Think step by step."
           end
-          
+
           # Add "detailed" variant
           unless original_instruction.include?("detail")
             variants << "#{original_instruction} Provide detailed reasoning."
           end
-          
+
           # Add "careful" variant
           unless original_instruction.include?("careful")
             variants << "Be careful and accurate. #{original_instruction}"
           end
-          
+
           # Add "examples" variant
           unless original_instruction.include?("example")
             variants << "#{original_instruction} Use examples in your response."
           end
-          
+
           # Add "precise" variant
           unless original_instruction.include?("precise")
             variants << "Be precise and specific. #{original_instruction}"
           end
-          
+
           variants.shuffle.take(5) # Return up to 5 variants, shuffled
         end
 
@@ -1545,11 +1277,11 @@ module DSPy
           begin
             # Create a new instance of the same class
             new_module = original_module.class.new
-            
+
             # Try to find and update any internal predictors
             original_module.instance_variables.each do |var_name|
               var_value = original_module.instance_variable_get(var_name)
-              
+
               if var_value.is_a?(DSPy::Predict)
                 # Update the instruction for internal predictors
                 modified_predictor = var_value.with_instruction(new_instruction)
@@ -1559,7 +1291,7 @@ module DSPy
                 new_module.instance_variable_set(var_name, var_value)
               end
             end
-            
+
             new_module
           rescue => e
             # Fallback to original module
@@ -1571,6 +1303,7 @@ module DSPy
       # FitnessScore represents multi-dimensional evaluation results
       class FitnessScore < T::Struct
         extend T::Sig
+        include Comparable
 
         const :primary_score, Float
         const :secondary_scores, T::Hash[Symbol, Float]
@@ -1607,6 +1340,13 @@ module DSPy
           )
         end
 
+        # Comparison method for Comparable module
+        sig { params(other: FitnessScore).returns(T.nilable(Integer)) }
+        def <=>(other)
+          return nil unless other.is_a?(FitnessScore)
+          overall_score <=> other.overall_score
+        end
+
         # Check if this score is dominated by another (for Pareto analysis)
         sig { params(other: FitnessScore).returns(T::Boolean) }
         def dominated_by?(other)
@@ -1692,7 +1432,7 @@ module DSPy
 
           # Calculate secondary metrics
           secondary_scores = {}
-          
+
           # Token efficiency (mock data for now - will be replaced with real trace collection)
           mock_traces = predictions.map.with_index do |pred, i|
             OpenStruct.new(token_usage: 50 + rand(100))
@@ -1784,7 +1524,7 @@ module DSPy
 
           # Simple consistency measure: average word overlap between responses
           word_sets = responses.map { |response| response.downcase.split.to_set }
-          
+
           total_similarity = 0.0
           comparisons = 0
 
@@ -1792,7 +1532,7 @@ module DSPy
             word_sets[(i+1)..-1].each do |set2|
               intersection = set1 & set2
               union = set1 | set2
-              
+
               similarity = union.empty? ? 0.0 : intersection.size.to_f / union.size
               total_similarity += similarity
               comparisons += 1
@@ -1808,7 +1548,7 @@ module DSPy
           return 1.0 if latencies.empty?
 
           avg_latency = latencies.sum / latencies.size
-          
+
           # Penalize high latencies (assume 2 seconds is baseline for 0.5 score)
           baseline_latency = 2.0
           latency_score = baseline_latency / (baseline_latency + avg_latency)
@@ -1930,10 +1670,10 @@ module DSPy
           if llm_traces.any?
             token_usage = llm_traces.sum(&:token_usage)
             avg_response_length = llm_traces.map { |t| t.attributes['response']&.to_s&.length || 0 }.sum / llm_traces.size
-            
+
             analysis << "- Total tokens used: #{token_usage}"
             analysis << "- Average response length: #{avg_response_length} characters"
-            
+
             # Identify models used
             models = llm_traces.map { |t| t.attributes['gen_ai.request.model'] }.compact.uniq
             analysis << "- Models used: #{models.join(', ')}" if models.any?
@@ -2001,14 +1741,14 @@ module DSPy
 
           begin
             original_instruction = extract_instruction(program)
-            
+
             # Use LLM-based instruction proposal instead of hardcoded mutations
             improved_instruction = @instruction_proposer.propose_instruction(
               original_instruction: original_instruction,
               execution_traces: execution_traces,
               failed_examples: failed_examples
             )
-            
+
             create_mutated_program(program, improved_instruction)
           rescue => e
             emit_event('mutation_error', {
@@ -2024,7 +1764,7 @@ module DSPy
         sig { params(programs: T::Array[T.untyped], execution_traces: T::Array[ExecutionTrace], failed_examples: T::Array[T.untyped]).returns(T::Array[T.untyped]) }
         def batch_mutate(programs, execution_traces: [], failed_examples: [])
           return [] if programs.empty?
-          
+
           programs.map { |program| mutate_program(program, execution_traces: execution_traces, failed_examples: failed_examples) }
         end
 
@@ -2075,7 +1815,7 @@ module DSPy
             -> (inst) { "Please #{inst.downcase}" },
             -> (inst) { "#{inst} with precision" }
           ]
-          
+
           patterns.sample.call(instruction)
         end
 
@@ -2088,7 +1828,7 @@ module DSPy
             "Consider all aspects carefully.",
             "Explain your thought process."
           ]
-          
+
           "#{instruction} #{expansions.sample}"
         end
 
@@ -2099,7 +1839,7 @@ module DSPy
           simplified = instruction.gsub(/\b(carefully|detailed|comprehensive|thorough)\b/i, '')
                                   .gsub(/\s+/, ' ')
                                   .strip
-          
+
           simplified.empty? ? instruction : simplified
         end
 
@@ -2112,12 +1852,12 @@ module DSPy
             "Apply domain knowledge.",
             "Consider edge cases."
           ]
-          
+
           "#{instruction} #{strategies.sample}"
         end
 
         # Rephrase instruction with synonyms
-        sig { params(instruction: String).returns(String) }  
+        sig { params(instruction: String).returns(String) }
         def apply_rephrase_mutation(instruction)
           # Simple synonym replacement - in full implementation would use LLM
           synonyms = {
@@ -2127,12 +1867,12 @@ module DSPy
             'calculate' => 'compute',
             'determine' => 'identify'
           }
-          
+
           result = instruction.dup
           synonyms.each do |original, replacement|
             result.gsub!(/\b#{original}\b/i, replacement) if rand < 0.3
           end
-          
+
           result
         end
 
@@ -2183,11 +1923,11 @@ module DSPy
           begin
             # Create a new instance of the same class
             new_module = original_module.class.new
-            
+
             # Try to find and update any internal predictors
             original_module.instance_variables.each do |var_name|
               var_value = original_module.instance_variable_get(var_name)
-              
+
               if var_value.is_a?(DSPy::Predict)
                 # Update the instruction for internal predictors
                 mutated_predictor = var_value.with_instruction(new_instruction)
@@ -2197,7 +1937,7 @@ module DSPy
                 new_module.instance_variable_set(var_name, var_value)
               end
             end
-            
+
             new_module
           rescue => e
             emit_event('module_mutation_error', {
@@ -2229,10 +1969,10 @@ module DSPy
         sig { params(mutations: T::Array[MutationType]).returns(Float) }
         def mutation_diversity(mutations)
           return 0.0 if mutations.empty?
-          
+
           unique_types = mutations.uniq.size
           total_types = @config.mutation_types.size
-          
+
           unique_types.to_f / total_types
         end
       end
@@ -2263,15 +2003,15 @@ module DSPy
           begin
             instruction_a = extract_instruction(parent_a)
             instruction_b = extract_instruction(parent_b)
-            
+
             crossover_type = select_crossover_type(instruction_a, instruction_b)
             offspring_instructions = apply_crossover(instruction_a, instruction_b, crossover_type)
-            
+
             offspring = [
               create_crossover_program(parent_a, offspring_instructions[0]),
               create_crossover_program(parent_b, offspring_instructions[1])
             ]
-            
+
             offspring
           rescue => e
             # Return original parents on crossover failure
@@ -2284,9 +2024,9 @@ module DSPy
         def batch_crossover(population)
           return [] if population.empty?
           return [population.first] if population.size == 1
-          
+
           offspring = []
-          
+
           # Pair up population for crossover
           population.each_slice(2) do |pair|
             if pair.size == 2
@@ -2296,7 +2036,7 @@ module DSPy
               offspring << pair[0] # Unpaired individual passes through
             end
           end
-          
+
           offspring
         end
 
@@ -2331,20 +2071,20 @@ module DSPy
         sig { params(instruction_a: String, instruction_b: String).returns(T::Array[String]) }
         def uniform_crossover(instruction_a, instruction_b)
           return [instruction_a, instruction_b] if instruction_a == instruction_b
-          
+
           words_a = instruction_a.split
           words_b = instruction_b.split
-          
+
           # Create offspring by randomly selecting words from parents
           offspring_a_words = []
           offspring_b_words = []
-          
+
           max_length = [words_a.size, words_b.size].max
-          
+
           max_length.times do |i|
             word_a = words_a[i]
             word_b = words_b[i]
-            
+
             if rand < 0.5
               offspring_a_words << (word_a || word_b)
               offspring_b_words << (word_b || word_a)
@@ -2353,7 +2093,7 @@ module DSPy
               offspring_b_words << (word_a || word_b)
             end
           end
-          
+
           [
             offspring_a_words.compact.join(' '),
             offspring_b_words.compact.join(' ')
@@ -2370,9 +2110,9 @@ module DSPy
             -> (a, b) { "#{b} while #{a.downcase}" },
             -> (a, b) { "Combine #{a.downcase} with #{b.downcase}" }
           ]
-          
+
           pattern = patterns.sample
-          
+
           [
             pattern.call(instruction_a, instruction_b),
             pattern.call(instruction_b, instruction_a)
@@ -2385,11 +2125,11 @@ module DSPy
           # Extract structural components
           components_a = extract_components(instruction_a)
           components_b = extract_components(instruction_b)
-          
+
           # Cross structural components
           offspring_a = combine_components(components_a.action, components_b.modifiers)
           offspring_b = combine_components(components_b.action, components_a.modifiers)
-          
+
           [offspring_a, offspring_b]
         end
 
@@ -2397,10 +2137,10 @@ module DSPy
         sig { params(instruction: String).returns(InstructionComponents) }
         def extract_components(instruction)
           words = instruction.split
-          
+
           # Simple heuristic: first verb-like word is action, rest are modifiers
           action_idx = words.find_index { |word| verb_like?(word) } || 0
-          
+
           InstructionComponents.new(
             action: words[action_idx] || words.first || "complete",
             modifiers: (words - [words[action_idx]]).join(' ')
@@ -2438,7 +2178,7 @@ module DSPy
           # Adaptive selection based on instruction characteristics
           if instruction_a && instruction_b
             combined_length = instruction_a.length + instruction_b.length
-            
+
             if combined_length < 40
               # Short instructions benefit from blending
               [CrossoverType::Blend, CrossoverType::Uniform].sample
@@ -2458,10 +2198,10 @@ module DSPy
         sig { params(crossovers: T::Array[CrossoverType]).returns(Float) }
         def crossover_diversity(crossovers)
           return 0.0 if crossovers.empty?
-          
+
           unique_types = crossovers.uniq.size
           total_types = @config.crossover_types.size
-          
+
           unique_types.to_f / total_types
         end
       end
@@ -2487,15 +2227,15 @@ module DSPy
         def select_parents(population_with_scores, count:)
           return [] if population_with_scores.empty?
           return population_with_scores.map(&:first) if count >= population_with_scores.size
-          
+
           # Combine tournament and Pareto-based selection for parent selection
           selected = []
-          
+
           count.times do
             parent = tournament_selection(population_with_scores)
             selected << parent
           end
-          
+
           selected
         end
 
@@ -2504,14 +2244,14 @@ module DSPy
         def select_survivors(population_with_scores, count:)
           return [] if population_with_scores.empty?
           return population_with_scores.map(&:first) if count >= population_with_scores.size
-          
+
           scores = population_with_scores.map(&:last)
-          
+
           # Find Pareto frontier first
           pareto_frontier = find_pareto_frontier(scores)
           frontier_indices = scores.each_index.select { |i| pareto_frontier.include?(scores[i]) }
           frontier_programs = frontier_indices.map { |i| population_with_scores[i].first }
-          
+
           if frontier_programs.size >= count
             # Use diversity selection within frontier
             frontier_with_scores = frontier_indices.map { |i| population_with_scores[i] }
@@ -2520,7 +2260,7 @@ module DSPy
             # Include all frontier + fill remaining with elite selection
             remaining_count = count - frontier_programs.size
             remaining_population = population_with_scores.reject.with_index { |_, i| frontier_indices.include?(i) }
-            
+
             additional = elite_selection(remaining_population, count: remaining_count)
             frontier_programs + additional
           end
@@ -2533,18 +2273,18 @@ module DSPy
         def find_pareto_frontier(fitness_scores)
           return [] if fitness_scores.empty?
           return fitness_scores if fitness_scores.size == 1
-          
+
           frontier = []
-          
+
           fitness_scores.each do |candidate|
             # Check if candidate is dominated by any other solution
             is_dominated = fitness_scores.any? do |other|
               other != candidate && candidate.dominated_by?(other)
             end
-            
+
             frontier << candidate unless is_dominated
           end
-          
+
           frontier
         end
 
@@ -2552,17 +2292,17 @@ module DSPy
         sig { params(fitness_scores: T::Array[FitnessScore]).returns(T::Hash[FitnessScore, Float]) }
         def calculate_crowding_distance(fitness_scores)
           distances = {}
-          
+
           # Initialize distances for all solutions
           fitness_scores.each { |score| distances[score] = 0.0 }
-          
+
           return distances if fitness_scores.size <= 2
-          
+
           # Calculate crowding distance for each objective
           objectives = [:primary_score, :overall_score]
           secondary_objectives = fitness_scores.first.secondary_scores.keys
           all_objectives = objectives + secondary_objectives
-          
+
           all_objectives.each do |objective|
             # Sort by current objective
             sorted_scores = fitness_scores.sort_by do |score|
@@ -2575,29 +2315,29 @@ module DSPy
                 score.secondary_scores[objective] || 0.0
               end
             end
-            
+
             # Set boundary solutions to high distance
             distances[sorted_scores.first] = Float::INFINITY if sorted_scores.size > 0
             distances[sorted_scores.last] = Float::INFINITY if sorted_scores.size > 1
-            
+
             next if sorted_scores.size <= 2
-            
+
             # Calculate range for normalization
             min_val = get_objective_value(sorted_scores.first, objective)
             max_val = get_objective_value(sorted_scores.last, objective)
             range = max_val - min_val
-            
+
             next if range <= 0
-            
+
             # Calculate crowding distance for intermediate solutions
             (1...(sorted_scores.size - 1)).each do |i|
               prev_val = get_objective_value(sorted_scores[i - 1], objective)
               next_val = get_objective_value(sorted_scores[i + 1], objective)
-              
+
               distances[sorted_scores[i]] += (next_val - prev_val) / range
             end
           end
-          
+
           distances
         end
 
@@ -2618,13 +2358,13 @@ module DSPy
         sig { params(population_with_scores: T::Array[T::Array[T.untyped]]).returns(T.untyped) }
         def tournament_selection(population_with_scores)
           return population_with_scores.first.first if population_with_scores.size == 1
-          
+
           tournament_size = [3, population_with_scores.size].min
           tournament = population_with_scores.sample(tournament_size)
-          
+
           # Select best from tournament based on Pareto dominance and crowding
           best_program, best_score = tournament.first
-          
+
           tournament[1..].each do |program, score|
             if score.dominated_by?(best_score)
               # Current best dominates this candidate, keep current
@@ -2639,7 +2379,7 @@ module DSPy
               end
             end
           end
-          
+
           best_program
         end
 
@@ -2647,13 +2387,13 @@ module DSPy
         sig { params(population_with_scores: T::Array[T::Array[T.untyped]], count: Integer).returns(T::Array[T.untyped]) }
         def diversity_selection(population_with_scores, count:)
           return population_with_scores.map(&:first) if count >= population_with_scores.size
-          
+
           scores = population_with_scores.map(&:last)
           distances = calculate_crowding_distance(scores)
-          
+
           # Sort by crowding distance (descending - prefer more diverse)
           sorted_pairs = population_with_scores.sort_by { |_, score| -distances[score] }
-          
+
           sorted_pairs.take(count).map(&:first)
         end
 
@@ -2661,10 +2401,10 @@ module DSPy
         sig { params(population_with_scores: T::Array[T::Array[T.untyped]], count: Integer).returns(T::Array[T.untyped]) }
         def elite_selection(population_with_scores, count:)
           return population_with_scores.map(&:first) if count >= population_with_scores.size
-          
+
           # Sort by overall score (descending - best first)
           sorted_pairs = population_with_scores.sort_by { |_, score| -score.overall_score }
-          
+
           sorted_pairs.take(count).map(&:first)
         end
       end
@@ -2673,7 +2413,7 @@ module DSPy
       class GEPAConfig < Config
         extend T::Sig
 
-        sig { returns(String) }
+        sig { returns(DSPy::LM) }
         attr_accessor :reflection_lm
 
         sig { returns(Integer) }
@@ -2688,8 +2428,6 @@ module DSPy
         sig { returns(T::Boolean) }
         attr_accessor :use_pareto_selection
 
-        sig { returns(T::Boolean) }
-        attr_accessor :simple_mode
         sig { returns(T::Array[MutationType]) }
         attr_accessor :mutation_types
         sig { returns(Float) }
@@ -2700,12 +2438,12 @@ module DSPy
         sig { void }
         def initialize
           super
-          @reflection_lm = 'gpt-4o'
+          # reflection_lm must be explicitly set by user - no default provided
+          @reflection_lm = nil
           @num_generations = 10
           @population_size = 8
           @mutation_rate = 0.7
           @use_pareto_selection = true
-          @simple_mode = false
           @mutation_types = [MutationType::Rewrite, MutationType::Expand, MutationType::Simplify, MutationType::Combine, MutationType::Rephrase]
           @crossover_rate = 0.6
           @crossover_types = [CrossoverType::Uniform, CrossoverType::Blend, CrossoverType::Structured]
@@ -2714,12 +2452,11 @@ module DSPy
         sig { returns(T::Hash[Symbol, T.untyped]) }
         def to_h
           super.merge({
-            reflection_lm: @reflection_lm,
+            reflection_lm: @reflection_lm&.model,  # Serialize the model name for hash representation
             num_generations: @num_generations,
             population_size: @population_size,
             mutation_rate: @mutation_rate,
             use_pareto_selection: @use_pareto_selection,
-            simple_mode: @simple_mode,
             mutation_types: @mutation_types,
             crossover_rate: @crossover_rate,
             crossover_types: @crossover_types
@@ -2738,6 +2475,12 @@ module DSPy
       end
       def initialize(metric: nil, config: nil)
         @config = config || GEPAConfig.new
+
+        # Validate that reflection_lm is configured
+        unless @config.reflection_lm
+          raise ArgumentError, "reflection_lm must be configured for GEPA optimization. Set config.reflection_lm to a DSPy::LM instance."
+        end
+
         super(metric: metric, config: @config)
       end
 
@@ -2749,6 +2492,7 @@ module DSPy
           valset: T.nilable(T::Array[T.untyped])
         ).returns(OptimizationResult)
       end
+
       def compile(program, trainset:, valset: nil)
         validate_inputs(program, trainset, valset)
 
@@ -2758,200 +2502,13 @@ module DSPy
           num_generations: @config.num_generations,
           population_size: @config.population_size
         }) do
-          # Simple optimization for Phase 1.5 - basic instruction optimization
-          if @config.simple_mode
-            perform_simple_optimization(program, trainset, valset)
-          else
-            # Phase 2 - Full GEPA genetic algorithm implementation
-            perform_gepa_optimization(program, trainset, valset)
-          end
+          # Always perform full GEPA genetic algorithm optimization
+          perform_gepa_optimization(program, trainset, valset)
         end
       end
 
       private
 
-      # Simple optimization implementation for testing
-      sig do
-        params(
-          program: T.untyped,
-          trainset: T::Array[T.untyped],
-          valset: T.nilable(T::Array[T.untyped])
-        ).returns(OptimizationResult)
-      end
-      def perform_simple_optimization(program, trainset, valset)
-        return basic_result(program) unless program.respond_to?(:signature_class)
-        
-        original_description = program.signature_class.description
-        best_program = program
-        best_score = simple_evaluate_program(program, trainset)
-        
-        # Try different instruction variations
-        instruction_variants = generate_instruction_variants(original_description)
-        
-        instruction_variants.each_with_index do |variant, index|
-          emit_event('instruction_variant_test', {
-            variant: variant,
-            iteration: index + 1,
-            total_variants: instruction_variants.size
-          })
-          
-          # Create modified program
-          modified_program = create_program_with_instruction(program, variant)
-          score = simple_evaluate_program(modified_program, trainset)
-          
-          if score > best_score
-            best_program = modified_program
-            best_score = score
-            
-            emit_event('improvement_found', {
-              new_score: score,
-              previous_score: best_score,
-              instruction: variant
-            })
-          end
-        end
-        
-        OptimizationResult.new(
-          optimized_program: best_program,
-          scores: { accuracy: best_score },
-          history: {
-            original_score: simple_evaluate_program(program, trainset),
-            variants_tested: instruction_variants.size,
-            best_instruction: best_program.signature_class.description
-          },
-          best_score_name: 'accuracy',
-          best_score_value: best_score,
-          metadata: {
-            optimizer: 'GEPA',
-            mode: 'Simple Optimization',
-            reflection_lm: @config.reflection_lm
-          }
-        )
-      end
-
-      # Generate variations of the instruction
-      sig { params(original_instruction: String).returns(T::Array[String]) }
-      def generate_instruction_variants(original_instruction)
-        variants = []
-        
-        # Add "step by step" variant
-        unless original_instruction.include?("step")
-          variants << "#{original_instruction} Think step by step."
-        end
-        
-        # Add "detailed" variant  
-        unless original_instruction.include?("detail")
-          variants << "#{original_instruction} Provide detailed reasoning."
-        end
-        
-        # Add "careful" variant
-        unless original_instruction.include?("careful")
-          variants << "Be careful and accurate. #{original_instruction}"
-        end
-        
-        variants.take(3) # Limit to 3 variants for simple mode
-      end
-
-      # Create a new program instance with modified instruction using DSPy.rb dynamic capabilities
-      sig { params(original_program: T.untyped, new_instruction: String).returns(T.untyped) }
-      def create_program_with_instruction(original_program, new_instruction)
-        case original_program
-        when DSPy::Predict
-          # DSPy::Predict has built-in support for instruction modification
-          original_program.with_instruction(new_instruction)
-        when DSPy::Module
-          # For custom DSPy::Module classes, create new instance with updated predictors
-          create_modified_module_instance(original_program, new_instruction)
-        else
-          # For other types (like test doubles), check available methods
-          if original_program.respond_to?(:with_instruction)
-            original_program.with_instruction(new_instruction)
-          elsif original_program.respond_to?(:signature_class)
-            # Create new DSPy::Predict with the same signature but new instruction
-            signature_class = original_program.signature_class
-            DSPy::Predict.new(signature_class).with_instruction(new_instruction)
-          else
-            # Fallback: return original if we can't modify
-            emit_event('program_modification_fallback', {
-              program_type: original_program.class.name,
-              reason: 'No modification method available'
-            })
-            original_program
-          end
-        end
-      rescue => e
-        emit_event('program_modification_error', {
-          error: e.message,
-          program_type: original_program.class.name
-        })
-        # Return original program on error
-        original_program
-      end
-
-      # Create modified version of custom DSPy::Module instance (for main GEPA class)
-      sig { params(original_module: DSPy::Module, new_instruction: String).returns(DSPy::Module) }
-      def create_modified_module_instance(original_module, new_instruction)
-        begin
-          # Create a new instance of the same class
-          new_module = original_module.class.new
-          
-          # Try to find and update any internal predictors
-          original_module.instance_variables.each do |var_name|
-            var_value = original_module.instance_variable_get(var_name)
-            
-            if var_value.is_a?(DSPy::Predict)
-              # Update the instruction for internal predictors
-              modified_predictor = var_value.with_instruction(new_instruction)
-              new_module.instance_variable_set(var_name, modified_predictor)
-            else
-              # Copy other instance variables as-is
-              new_module.instance_variable_set(var_name, var_value)
-            end
-          end
-          
-          new_module
-        rescue => e
-          emit_event('module_modification_error', {
-            error: e.message,
-            module_class: original_module.class.name
-          })
-          # Fallback to original module
-          original_module
-        end
-      end
-
-      # Simple evaluation for testing (different from base class evaluate_program)
-      sig { params(program: T.untyped, trainset: T::Array[T.untyped]).returns(Float) }
-      def simple_evaluate_program(program, trainset)
-        return 0.0 unless @metric
-        
-        scores = trainset.map do |example|
-          prediction = program.call(**example.input_values)
-          @metric.call(example, prediction).to_f
-        rescue => e
-          emit_event('evaluation_error', { error: e.message, example_id: example.object_id.to_s })
-          0.0
-        end
-        
-        scores.sum / scores.size
-      end
-
-      # Return basic result when simple optimization isn't applicable
-      sig { params(program: T.untyped).returns(OptimizationResult) }
-      def basic_result(program)
-        OptimizationResult.new(
-          optimized_program: program,
-          scores: { gepa_score: 0.0 },
-          history: { phase: 'Phase 1 - Basic Structure' },
-          best_score_name: 'gepa_score',
-          best_score_value: 0.0,
-          metadata: {
-            optimizer: 'GEPA',
-            implementation_status: 'Phase 1 - Infrastructure Complete'
-          }
-        )
-      end
-      
       # Complete GEPA genetic algorithm optimization
       sig do
         params(
@@ -2968,11 +2525,11 @@ module DSPy
         mutation_engine = create_mutation_engine
         crossover_engine = create_crossover_engine
         pareto_selector = create_pareto_selector(fitness_evaluator)
-        
+
         # Initialize trace collection for reflection
         trace_collector = TraceCollector.new
         optimization_run_id = "gepa-run-#{SecureRandom.hex(4)}"
-        
+
         emit_event('gepa_optimization_start', {
           optimization_run_id: optimization_run_id,
           num_generations: @config.num_generations,
@@ -2980,17 +2537,17 @@ module DSPy
           mutation_rate: @config.mutation_rate,
           crossover_rate: @config.crossover_rate
         })
-        
+
         begin
           # Run the complete genetic algorithm evolution
           evolution_result = genetic_engine.run_evolution(program, trainset)
-          
+
           # Collect traces for reflection analysis
           execution_traces = trace_collector.traces_for_run(optimization_run_id)
-          
+
           # Generate reflection insights on the optimization process
           reflection_result = reflection_engine.reflect_with_llm(execution_traces)
-          
+
           # Evaluate final candidate on validation set if provided
           final_validation_score = if valset && !valset.empty?
             validation_fitness = fitness_evaluator.evaluate_candidate(evolution_result[:best_candidate], valset)
@@ -2998,7 +2555,7 @@ module DSPy
           else
             evolution_result[:best_fitness].overall_score
           end
-          
+
           emit_event('gepa_optimization_complete', {
             optimization_run_id: optimization_run_id,
             best_fitness: evolution_result[:best_fitness].overall_score,
@@ -3006,7 +2563,7 @@ module DSPy
             validation_score: final_validation_score,
             reflection_confidence: reflection_result.confidence
           })
-          
+
           # Create comprehensive optimization result
           OptimizationResult.new(
             optimized_program: evolution_result[:best_candidate],
@@ -3030,7 +2587,7 @@ module DSPy
             best_score_value: evolution_result[:best_fitness].overall_score,
             metadata: {
               optimizer: 'GEPA',
-              reflection_lm: @config.reflection_lm,
+              reflection_lm: @config.reflection_lm&.model,
               implementation_status: 'Phase 2 - Complete Implementation',
               optimization_run_id: optimization_run_id,
               reflection_insights: {
@@ -3047,7 +2604,7 @@ module DSPy
               },
               component_versions: {
                 genetic_engine: 'v2.0',
-                fitness_evaluator: 'v2.0', 
+                fitness_evaluator: 'v2.0',
                 reflection_engine: 'v2.0',
                 mutation_engine: 'v2.0',
                 crossover_engine: 'v2.0',
@@ -3055,20 +2612,20 @@ module DSPy
               }
             }
           )
-          
+
         rescue => e
           emit_event('gepa_optimization_error', {
             optimization_run_id: optimization_run_id,
             error: e.message,
             backtrace: e.backtrace&.take(5)
           })
-          
+
           # Return fallback result on optimization failure
           fallback_fitness = fitness_evaluator.evaluate_candidate(program, trainset)
-          
+
           OptimizationResult.new(
             optimized_program: program,
-            scores: { 
+            scores: {
               fitness_score: fallback_fitness.overall_score,
               primary_score: fallback_fitness.primary_score,
               **fallback_fitness.secondary_scores
@@ -3079,11 +2636,11 @@ module DSPy
               phase: 'Phase 2 - Error Recovery',
               error: e.message
             },
-            best_score_name: 'fitness_score', 
+            best_score_name: 'fitness_score',
             best_score_value: fallback_fitness.overall_score,
             metadata: {
               optimizer: 'GEPA',
-              reflection_lm: @config.reflection_lm,
+              reflection_lm: @config.reflection_lm&.model,
               implementation_status: 'Phase 2 - Error Recovery',
               optimization_run_id: optimization_run_id,
               error_details: {
@@ -3095,48 +2652,48 @@ module DSPy
           )
         end
       end
-      
+
       # Create and configure fitness evaluator
       sig { returns(FitnessEvaluator) }
       def create_fitness_evaluator
         FitnessEvaluator.new(primary_metric: @metric, config: @config)
       end
-      
+
       # Create and configure genetic engine
       sig { params(fitness_evaluator: FitnessEvaluator).returns(GeneticEngine) }
       def create_genetic_engine(fitness_evaluator)
-        GeneticEngine.new(config: @config, metric: @metric)
+        GeneticEngine.new(config: @config, fitness_evaluator: fitness_evaluator)
       end
-      
+
       # Create and configure reflection engine
       sig { returns(ReflectionEngine) }
       def create_reflection_engine
         ReflectionEngine.new(@config)
       end
-      
-      # Create and configure mutation engine  
+
+      # Create and configure mutation engine
       sig { returns(MutationEngine) }
       def create_mutation_engine
         MutationEngine.new(config: @config)
       end
-      
+
       # Create and configure crossover engine
       sig { returns(CrossoverEngine) }
       def create_crossover_engine
         CrossoverEngine.new(config: @config)
       end
-      
+
       # Create and configure pareto selector
       sig { params(fitness_evaluator: FitnessEvaluator).returns(ParetoSelector) }
       def create_pareto_selector(fitness_evaluator)
         ParetoSelector.new(evaluator: fitness_evaluator, config: @config)
       end
-      
+
       # Calculate execution timespan from traces
       sig { params(traces: T::Array[ExecutionTrace]).returns(Float) }
       def calculate_execution_timespan(traces)
         return 0.0 if traces.size < 2
-        
+
         timestamps = traces.map(&:timestamp).sort
         (timestamps.last - timestamps.first).to_f
       end
@@ -3147,9 +2704,9 @@ module DSPy
     module GEPAFeedbackMetric
       extend T::Sig
       extend T::Helpers
-      
+
       interface!
-      
+
       # Evaluates prediction and provides score with optional feedback
       sig do
         abstract
@@ -3166,11 +2723,11 @@ module DSPy
     # Extended prediction result with score and feedback
     class ScoreWithFeedback < T::Struct
       extend T::Sig
-      
+
       const :score, Float
       const :feedback, T.nilable(String)
       const :prediction, DSPy::Prediction
-      
+
       sig { params(score: Float, prediction: DSPy::Prediction, feedback: T.nilable(String)).void }
       def initialize(score:, prediction:, feedback: nil)
         super
@@ -3180,7 +2737,7 @@ module DSPy
     # Module Evaluator - Evaluates DSPy modules with metrics and feedback
     class ModuleEvaluator
       extend T::Sig
-      
+
       sig do
         params(
           student: T.untyped, # DSPy::Module or similar callable
@@ -3224,9 +2781,9 @@ module DSPy
       def evaluate_batch(batch, candidate_instruction, capture_traces: true)
         program = build_program(candidate_instruction)
         results = []
-        
+
         batch.each do |example|
-          begin            
+          begin
             # Execute program on example
             prediction = if program.respond_to?(:call)
                           program.call(**example.input_values)
@@ -3235,11 +2792,11 @@ module DSPy
                         else
                           raise "Program must respond to :call or :forward"
                         end
-            
+
             # Get collected traces (if trace collection is enabled)
             # Note: TraceCollector automatically collects via event subscriptions
             traces = capture_traces ? @trace_collector.traces : []
-            
+
             # Evaluate with metric
             # Try with traces first (for GEPAFeedbackMetric), fallback to standard metric
             begin
@@ -3257,7 +2814,7 @@ module DSPy
                 raise arg_error
               end
             end
-            
+
             # Ensure we always have a ScoreWithFeedback object
             if score_result.is_a?(ScoreWithFeedback)
               results << score_result
@@ -3269,14 +2826,14 @@ module DSPy
                 feedback: nil
               )
             end
-            
+
           rescue => e
             DSPy.logger.error("Evaluation error: #{e.message}")
             # Return zero score on failure
             results << 0.0
           end
         end
-        
+
         results
       end
 
@@ -3292,21 +2849,21 @@ module DSPy
       end
       def make_reflective_dataset(examples, predictions, scores, threshold: 0.5)
         reflective_data = []
-        
+
         examples.zip(predictions, scores).each do |example, prediction, score|
           # Extract score value
           score_value = score.is_a?(ScoreWithFeedback) ? score.score : score
-          
+
           # Include failed predictions (below threshold)
           next if score_value >= threshold
-          
+
           # Extract feedback if available
           feedback = if score.is_a?(ScoreWithFeedback) && score.feedback
                       score.feedback
                     else
                       "Low performance (score: #{score_value.round(2)})"
                     end
-          
+
           reflective_data << {
             'input' => example.input_values,
             'expected' => example.expected_values,
@@ -3315,7 +2872,7 @@ module DSPy
             'feedback' => feedback
           }
         end
-        
+
         reflective_data
       end
 
@@ -3358,32 +2915,32 @@ module DSPy
       end
       def analyze_failures_and_propose(current_instruction, reflective_dataset)
         return [current_instruction] if reflective_dataset.empty?
-        
+
         # Extract common failure patterns
         feedback_texts = reflective_dataset.map { |data| data['feedback'] }.compact
-        
+
         # Simple heuristic-based proposals
         proposals = []
-        
+
         # If many failures, suggest more detailed instruction
         if reflective_dataset.size >= 3
           proposals << "#{current_instruction} Please provide step-by-step reasoning."
         end
-        
+
         # If feedback mentions specific issues, address them
         if feedback_texts.any? { |fb| fb.include?('unclear') || fb.include?('ambiguous') }
           proposals << "#{current_instruction} Be specific and clear in your response."
         end
-        
+
         if feedback_texts.any? { |fb| fb.include?('incomplete') || fb.include?('missing') }
           proposals << "#{current_instruction} Ensure your answer is complete and addresses all aspects."
         end
-        
+
         # Always include at least one proposal
         proposals << "#{current_instruction.strip}. Think carefully before responding." if proposals.empty?
-        
+
         proposals.uniq.take(3) # Return up to 3 proposals
       end
     end
   end
-end
+end