dspy 0.6.3 → 0.8.0

data/lib/dspy/lm/retry_handler.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module DSPy
+  class LM
+    # Handles retry logic with progressive fallback strategies
+    class RetryHandler
+      extend T::Sig
+
+      MAX_RETRIES = 3
+      BACKOFF_BASE = 0.5 # seconds
+
+      sig { params(adapter: DSPy::LM::Adapter, signature_class: T.class_of(DSPy::Signature)).void }
+      def initialize(adapter, signature_class)
+        @adapter = adapter
+        @signature_class = signature_class
+        @attempt = 0
+      end
+
+      # Execute a block with retry logic and progressive fallback
+      sig do
+        type_parameters(:T)
+          .params(
+            initial_strategy: Strategies::BaseStrategy,
+            block: T.proc.params(strategy: Strategies::BaseStrategy).returns(T.type_parameter(:T))
+          )
+          .returns(T.type_parameter(:T))
+      end
+      def with_retry(initial_strategy, &block)
+        strategies = build_fallback_chain(initial_strategy)
+        last_error = nil
+
+        strategies.each do |strategy|
+          retry_count = 0
+          
+          begin
+            @attempt += 1
+            DSPy.logger.debug("Attempting with strategy: #{strategy.name} (attempt #{@attempt})")
+            
+            result = yield(strategy)
+            
+            # Success! Reset attempt counter for next time
+            @attempt = 0
+            return result
+            
+          rescue JSON::ParserError, StandardError => e
+            last_error = e
+            
+            # Let strategy handle the error first
+            if strategy.handle_error(e)
+              DSPy.logger.info("Strategy #{strategy.name} handled error, will try next strategy")
+              next # Try next strategy
+            end
+            
+            # Try retrying with the same strategy
+            if retry_count < max_retries_for_strategy(strategy)
+              retry_count += 1
+              backoff_time = calculate_backoff(retry_count)
+              
+              DSPy.logger.warn(
+                "Retrying #{strategy.name} after error (attempt #{retry_count}/#{max_retries_for_strategy(strategy)}): #{e.message}"
+              )
+              
+              sleep(backoff_time) if backoff_time > 0
+              retry
+            else
+              DSPy.logger.info("Max retries reached for #{strategy.name}, trying next strategy")
+              next # Try next strategy
+            end
+          end
+        end
+
+        # All strategies exhausted
+        DSPy.logger.error("All strategies exhausted after #{@attempt} total attempts")
+        raise last_error || StandardError.new("All JSON extraction strategies failed")
+      end
+
+      private
+
+      # Build a chain of strategies to try in order
+      sig { params(initial_strategy: Strategies::BaseStrategy).returns(T::Array[Strategies::BaseStrategy]) }
+      def build_fallback_chain(initial_strategy)
+        selector = StrategySelector.new(@adapter, @signature_class)
+        all_strategies = selector.available_strategies.sort_by(&:priority).reverse
+        
+        # Start with the requested strategy, then try others
+        chain = [initial_strategy]
+        chain.concat(all_strategies.reject { |s| s.name == initial_strategy.name })
+        
+        chain
+      end
+
+      # Different strategies get different retry counts
+      sig { params(strategy: Strategies::BaseStrategy).returns(Integer) }
+      def max_retries_for_strategy(strategy)
+        case strategy.name
+        when "openai_structured_output"
+          1 # Structured outputs rarely benefit from retries
+        when "anthropic_extraction"
+          2 # Anthropic can be a bit more variable
+        else
+          MAX_RETRIES # Enhanced prompting might need more attempts
+        end
+      end
+
+      # Calculate exponential backoff with jitter
+      sig { params(attempt: Integer).returns(Float) }
+      def calculate_backoff(attempt)
+        return 0.0 if DSPy.config.test_mode # No sleep in tests
+        
+        base_delay = BACKOFF_BASE * (2 ** (attempt - 1))
+        jitter = rand * 0.1 * base_delay
+        
+        [base_delay + jitter, 10.0].min # Cap at 10 seconds
+      end
+    end
+  end
+end

data/lib/dspy/lm/strategies/anthropic_extraction_strategy.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "base_strategy"
+
+module DSPy
+  class LM
+    module Strategies
+      # Strategy for using Anthropic's enhanced JSON extraction patterns
+      class AnthropicExtractionStrategy < BaseStrategy
+        extend T::Sig
+
+        sig { override.returns(T::Boolean) }
+        def available?
+          adapter.is_a?(DSPy::LM::AnthropicAdapter)
+        end
+
+        sig { override.returns(Integer) }
+        def priority
+          90 # High priority - Anthropic's extraction is very reliable
+        end
+
+        sig { override.returns(String) }
+        def name
+          "anthropic_extraction"
+        end
+
+        sig { override.params(messages: T::Array[T::Hash[Symbol, String]], request_params: T::Hash[Symbol, T.untyped]).void }
+        def prepare_request(messages, request_params)
+          # Anthropic adapter already handles JSON optimization in prepare_messages_for_json
+          # No additional preparation needed here
+        end
+
+        sig { override.params(response: DSPy::LM::Response).returns(T.nilable(String)) }
+        def extract_json(response)
+          # Use Anthropic's specialized extraction method if available
+          if adapter.respond_to?(:extract_json_from_response)
+            adapter.extract_json_from_response(response.content)
+          else
+            # Fallback to basic extraction
+            extract_json_fallback(response.content)
+          end
+        end
+
+        private
+
+        sig { params(content: T.nilable(String)).returns(T.nilable(String)) }
+        def extract_json_fallback(content)
+          return nil if content.nil?
+
+          # Try the 4 patterns Anthropic adapter uses
+          # Pattern 1: ```json blocks
+          if content.include?('```json')
+            return content.split('```json').last.split('```').first.strip
+          end
+
+          # Pattern 2: ## Output values header
+          if content.include?('## Output values')
+            json_part = content.split('## Output values').last
+            if json_part.include?('```')
+              return json_part.split('```')[1].strip
+            end
+          end
+
+          # Pattern 3: Generic code blocks
+          if content.include?('```')
+            code_block = content.split('```')[1]
+            if code_block && (code_block.strip.start_with?('{') || code_block.strip.start_with?('['))
+              return code_block.strip
+            end
+          end
+
+          # Pattern 4: Already valid JSON
+          content.strip if content.strip.start_with?('{') || content.strip.start_with?('[')
+        end
+      end
+    end
+  end
+end

data/lib/dspy/lm/strategies/base_strategy.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module DSPy
+  class LM
+    module Strategies
+      # Base class for JSON extraction strategies
+      class BaseStrategy
+        extend T::Sig
+        extend T::Helpers
+        abstract!
+
+        sig { params(adapter: DSPy::LM::Adapter, signature_class: T.class_of(DSPy::Signature)).void }
+        def initialize(adapter, signature_class)
+          @adapter = adapter
+          @signature_class = signature_class
+        end
+
+        # Check if this strategy is available for the given adapter/model
+        sig { abstract.returns(T::Boolean) }
+        def available?; end
+
+        # Priority for this strategy (higher = preferred)
+        sig { abstract.returns(Integer) }
+        def priority; end
+
+        # Name of the strategy for logging/debugging
+        sig { abstract.returns(String) }
+        def name; end
+
+        # Prepare the request for JSON extraction
+        sig { abstract.params(messages: T::Array[T::Hash[Symbol, String]], request_params: T::Hash[Symbol, T.untyped]).void }
+        def prepare_request(messages, request_params); end
+
+        # Extract JSON from the response
+        sig { abstract.params(response: DSPy::LM::Response).returns(T.nilable(String)) }
+        def extract_json(response); end
+
+        # Handle errors specific to this strategy
+        sig { params(error: StandardError).returns(T::Boolean) }
+        def handle_error(error)
+          # By default, don't handle errors - let them propagate
+          false
+        end
+
+        protected
+
+        attr_reader :adapter, :signature_class
+      end
+    end
+  end
+end

data/lib/dspy/lm/strategies/enhanced_prompting_strategy.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "base_strategy"
+
+module DSPy
+  class LM
+    module Strategies
+      # Enhanced prompting strategy that works with any LLM
+      # Adds explicit JSON formatting instructions to improve reliability
+      class EnhancedPromptingStrategy < BaseStrategy
+        extend T::Sig
+
+        sig { override.returns(T::Boolean) }
+        def available?
+          # This strategy is always available as a fallback
+          true
+        end
+
+        sig { override.returns(Integer) }
+        def priority
+          50 # Medium priority - use when native methods aren't available
+        end
+
+        sig { override.returns(String) }
+        def name
+          "enhanced_prompting"
+        end
+
+        sig { override.params(messages: T::Array[T::Hash[Symbol, String]], request_params: T::Hash[Symbol, T.untyped]).void }
+        def prepare_request(messages, request_params)
+          # Enhance the user message with explicit JSON instructions
+          return if messages.empty?
+
+          # Get the output schema
+          output_schema = signature_class.output_json_schema
+          
+          # Find the last user message
+          last_user_idx = messages.rindex { |msg| msg[:role] == "user" }
+          return unless last_user_idx
+
+          # Add JSON formatting instructions
+          original_content = messages[last_user_idx][:content]
+          enhanced_content = enhance_prompt_with_json_instructions(original_content, output_schema)
+          messages[last_user_idx][:content] = enhanced_content
+
+          # Add system instructions if no system message exists
+          if messages.none? { |msg| msg[:role] == "system" }
+            messages.unshift({
+              role: "system",
+              content: "You are a helpful assistant that always responds with valid JSON when requested."
+            })
+          end
+        end
+
+        sig { override.params(response: DSPy::LM::Response).returns(T.nilable(String)) }
+        def extract_json(response)
+          return nil if response.content.nil?
+
+          content = response.content.strip
+
+          # Try multiple extraction patterns
+          # 1. Check for markdown code blocks
+          if content.include?('```json')
+            json_content = content.split('```json').last.split('```').first.strip
+            return json_content if valid_json?(json_content)
+          elsif content.include?('```')
+            code_block = content.split('```')[1]
+            if code_block
+              json_content = code_block.strip
+              return json_content if valid_json?(json_content)
+            end
+          end
+
+          # 2. Check if the entire response is JSON
+          return content if valid_json?(content)
+
+          # 3. Look for JSON-like structures in the content
+          json_match = content.match(/\{[\s\S]*\}|\[[\s\S]*\]/)
+          if json_match
+            json_content = json_match[0]
+            return json_content if valid_json?(json_content)
+          end
+
+          nil
+        end
+
+        private
+
+        sig { params(prompt: String, schema: T::Hash[Symbol, T.untyped]).returns(String) }
+        def enhance_prompt_with_json_instructions(prompt, schema)
+          json_example = generate_example_from_schema(schema)
+          
+          <<~ENHANCED
+            #{prompt}
+
+            IMPORTANT: You must respond with valid JSON that matches this structure:
+            ```json
+            #{JSON.pretty_generate(json_example)}
+            ```
+
+            Required fields: #{schema[:required]&.join(', ') || 'none'}
+            
+            Ensure your response:
+            1. Is valid JSON (properly quoted strings, no trailing commas)
+            2. Includes all required fields
+            3. Uses the correct data types for each field
+            4. Is wrapped in ```json``` markdown code blocks
+          ENHANCED
+        end
+
+        sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Hash[String, T.untyped]) }
+        def generate_example_from_schema(schema)
+          return {} unless schema[:properties]
+
+          example = {}
+          schema[:properties].each do |field_name, field_schema|
+            example[field_name.to_s] = case field_schema[:type]
+            when "string"
+              field_schema[:description] || "example string"
+            when "integer"
+              42
+            when "number"
+              3.14
+            when "boolean"
+              true
+            when "array"
+              ["example item"]
+            when "object"
+              { "nested" => "object" }
+            else
+              "example value"
+            end
+          end
+          example
+        end
+
+        sig { params(content: String).returns(T::Boolean) }
+        def valid_json?(content)
+          JSON.parse(content)
+          true
+        rescue JSON::ParserError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/dspy/lm/strategies/openai_structured_output_strategy.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base_strategy"
+
+module DSPy
+  class LM
+    module Strategies
+      # Strategy for using OpenAI's native structured output feature
+      class OpenAIStructuredOutputStrategy < BaseStrategy
+        extend T::Sig
+
+        sig { override.returns(T::Boolean) }
+        def available?
+          # Check if adapter is OpenAI and supports structured outputs
+          return false unless adapter.is_a?(DSPy::LM::OpenAIAdapter)
+          return false unless adapter.instance_variable_get(:@structured_outputs_enabled)
+          
+          DSPy::LM::Adapters::OpenAI::SchemaConverter.supports_structured_outputs?(adapter.model)
+        end
+
+        sig { override.returns(Integer) }
+        def priority
+          100 # Highest priority - native structured outputs are most reliable
+        end
+
+        sig { override.returns(String) }
+        def name
+          "openai_structured_output"
+        end
+
+        sig { override.params(messages: T::Array[T::Hash[Symbol, String]], request_params: T::Hash[Symbol, T.untyped]).void }
+        def prepare_request(messages, request_params)
+          # Add structured output format to request
+          response_format = DSPy::LM::Adapters::OpenAI::SchemaConverter.to_openai_format(signature_class)
+          request_params[:response_format] = response_format
+        end
+
+        sig { override.params(response: DSPy::LM::Response).returns(T.nilable(String)) }
+        def extract_json(response)
+          # With structured outputs, the response should already be valid JSON
+          # Just return the content as-is
+          response.content
+        end
+
+        sig { override.params(error: StandardError).returns(T::Boolean) }
+        def handle_error(error)
+          # Handle OpenAI-specific structured output errors
+          if error.message.include?("response_format") || error.message.include?("Invalid schema")
+            # Log the error and return true to indicate we handled it
+            # This allows fallback to another strategy
+            DSPy.logger.warn("OpenAI structured output failed: #{error.message}")
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dspy/lm/strategy_selector.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require_relative "strategies/base_strategy"
+require_relative "strategies/openai_structured_output_strategy"
+require_relative "strategies/anthropic_extraction_strategy"
+require_relative "strategies/enhanced_prompting_strategy"
+
+module DSPy
+  class LM
+    # Selects the best JSON extraction strategy based on the adapter and capabilities
+    class StrategySelector
+      extend T::Sig
+
+      # Available strategies in order of registration
+      STRATEGIES = [
+        Strategies::OpenAIStructuredOutputStrategy,
+        Strategies::AnthropicExtractionStrategy,
+        Strategies::EnhancedPromptingStrategy
+      ].freeze
+
+      sig { params(adapter: DSPy::LM::Adapter, signature_class: T.class_of(DSPy::Signature)).void }
+      def initialize(adapter, signature_class)
+        @adapter = adapter
+        @signature_class = signature_class
+        @strategies = build_strategies
+      end
+
+      # Select the best available strategy
+      sig { returns(Strategies::BaseStrategy) }
+      def select
+        # Allow manual override via configuration
+        if DSPy.config.structured_outputs.strategy
+          strategy = find_strategy_by_name(DSPy.config.structured_outputs.strategy)
+          return strategy if strategy&.available?
+          
+          DSPy.logger.warn("Requested strategy '#{DSPy.config.structured_outputs.strategy}' is not available")
+        end
+
+        # Select the highest priority available strategy
+        available_strategies = @strategies.select(&:available?)
+        
+        if available_strategies.empty?
+          raise "No JSON extraction strategies available for #{@adapter.class}"
+        end
+
+        selected = available_strategies.max_by(&:priority)
+        
+        DSPy.logger.debug("Selected JSON extraction strategy: #{selected.name}")
+        selected
+      end
+
+      # Get all available strategies
+      sig { returns(T::Array[Strategies::BaseStrategy]) }
+      def available_strategies
+        @strategies.select(&:available?)
+      end
+
+      # Check if a specific strategy is available
+      sig { params(strategy_name: String).returns(T::Boolean) }
+      def strategy_available?(strategy_name)
+        strategy = find_strategy_by_name(strategy_name)
+        strategy&.available? || false
+      end
+
+      private
+
+      sig { returns(T::Array[Strategies::BaseStrategy]) }
+      def build_strategies
+        STRATEGIES.map { |klass| klass.new(@adapter, @signature_class) }
+      end
+
+      sig { params(name: String).returns(T.nilable(Strategies::BaseStrategy)) }
+      def find_strategy_by_name(name)
+        @strategies.find { |s| s.name == name }
+      end
+    end
+  end
+end

data/lib/dspy/lm.rb

@@ -14,19 +14,23 @@ require_relative 'instrumentation/token_tracker'
 require_relative 'lm/adapters/openai_adapter'
 require_relative 'lm/adapters/anthropic_adapter'
 
+# Load strategy system
+require_relative 'lm/strategy_selector'
+require_relative 'lm/retry_handler'
+
 module DSPy
   class LM
     attr_reader :model_id, :api_key, :model, :provider, :adapter
 
-    def initialize(model_id, api_key: nil)
+    def initialize(model_id, api_key: nil, **options)
       @model_id = model_id
       @api_key = api_key
       
       # Parse provider and model from model_id
       @provider, @model = parse_model_id(model_id)
       
-      # Create appropriate adapter
-      @adapter = AdapterFactory.create(model_id, api_key: api_key)
+      # Create appropriate adapter with options
+      @adapter = AdapterFactory.create(model_id, api_key: api_key, **options)
     end
 
     def chat(inference_module, input_values, &block)
@@ -54,7 +58,7 @@ module DSPy
           adapter_class: adapter.class.name,
           input_size: input_size
         }) do
-          adapter.chat(messages: messages, &block)
+          chat_with_strategy(messages, signature_class, &block)
         end
         
         # Extract actual token usage from response (more accurate than estimation)
@@ -79,7 +83,7 @@ module DSPy
         end
       else
         # Consolidated mode: execute without nested instrumentation
-        response = adapter.chat(messages: messages, &block)
+        response = chat_with_strategy(messages, signature_class, &block)
         token_usage = Instrumentation::TokenTracker.extract_token_usage(response, provider)
         parsed_result = parse_response(response, input_values, signature_class)
       end
@@ -89,6 +93,53 @@ module DSPy
 
     private
 
+    def chat_with_strategy(messages, signature_class, &block)
+      # Select the best strategy for JSON extraction
+      strategy_selector = StrategySelector.new(adapter, signature_class)
+      initial_strategy = strategy_selector.select
+      
+      if DSPy.config.structured_outputs.retry_enabled && signature_class
+        # Use retry handler for JSON responses
+        retry_handler = RetryHandler.new(adapter, signature_class)
+        
+        retry_handler.with_retry(initial_strategy) do |strategy|
+          execute_chat_with_strategy(messages, signature_class, strategy, &block)
+        end
+      else
+        # No retry logic, just execute once
+        execute_chat_with_strategy(messages, signature_class, initial_strategy, &block)
+      end
+    end
+
+    def execute_chat_with_strategy(messages, signature_class, strategy, &block)
+      # Prepare request with strategy-specific modifications
+      request_params = {}
+      strategy.prepare_request(messages.dup, request_params)
+      
+      # Make the request
+      response = if request_params.any?
+        # Pass additional parameters if strategy added them
+        adapter.chat(messages: messages, signature: signature_class, **request_params, &block)
+      else
+        adapter.chat(messages: messages, signature: signature_class, &block)
+      end
+      
+      # Let strategy handle JSON extraction if needed
+      if signature_class && response.content
+        extracted_json = strategy.extract_json(response)
+        if extracted_json && extracted_json != response.content
+          # Create a new response with extracted JSON
+          response = Response.new(
+            content: extracted_json,
+            usage: response.usage,
+            metadata: response.metadata
+          )
+        end
+      end
+      
+      response
+    end
+
     # Determines if LM-level events should be emitted using smart consolidation
     def should_emit_lm_events?
       # Emit LM events only if we're not in a nested context (smart consolidation)
@@ -139,18 +190,6 @@ module DSPy
       # Try to parse the response as JSON
       content = response.content
 
-      # Let adapters handle their own extraction logic if available
-      if adapter && adapter.respond_to?(:extract_json_from_response, true)
-        content = adapter.send(:extract_json_from_response, content)
-      else
-        # Fallback: Extract JSON if it's in a code block (legacy behavior)
-        if content.include?('```json')
-          content = content.split('```json').last.split('```').first.strip
-        elsif content.include?('```')
-          content = content.split('```').last.split('```').first.strip
-        end
-      end
-
       begin
         json_payload = JSON.parse(content)
 
@@ -161,7 +200,6 @@ module DSPy
         # Enhanced error message with debugging information
         error_details = {
           original_content: response.content,
-          extracted_content: content,
           provider: provider,
           model: model
         }

data/lib/dspy/predict.rb

@@ -115,6 +115,9 @@ module DSPy
       output_attributes = output_attributes.transform_keys(&:to_sym)
       output_props = @signature_class.output_struct_class.props
       
+      # Apply defaults for missing fields
+      output_attributes = apply_defaults_to_output(output_attributes)
+      
       coerce_output_attributes(output_attributes, output_props)
     end
 
@@ -143,5 +146,22 @@ module DSPy
         output: output_props
       })
     end
+
+    # Applies default values to missing output fields
+    sig { params(output_attributes: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def apply_defaults_to_output(output_attributes)
+      return output_attributes unless @signature_class.respond_to?(:output_field_descriptors)
+      
+      field_descriptors = @signature_class.output_field_descriptors
+      
+      field_descriptors.each do |field_name, descriptor|
+        # Only apply default if field is missing and has a default
+        if !output_attributes.key?(field_name) && descriptor.has_default
+          output_attributes[field_name] = descriptor.default_value
+        end
+      end
+      
+      output_attributes
+    end
   end
 end