dspy 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44671af9a40e3f452983f616a3df0770babbe5d9cde85c18c9ace6fe618fcfe5
-  data.tar.gz: e3ba107fed63ba58dfa9b3f707d682acc88a6e7a1c8a72a89a46fbb19c82347c
+  metadata.gz: cc32a4fe2ec14d442c2a0603b69992528ab81c67c4e61ceed6a6d337278d0220
+  data.tar.gz: f901d0336e0a4c912dfb37428bdd0e359b74de35b340eb769edcb5e811e257fe
 SHA512:
-  metadata.gz: bda31c209ff68af39500de5b8f562fb173e08a5fc41863cd96b89f4f0e8be62cadbc73fc31fc61567d8d8e2e0afce86e4710028fbdeba8a4e6709811be73c754
-  data.tar.gz: a4823fcc2341684b7c0b98b00e2c7dbe9847b61d3b3fde69e3cd31767478659e75fd8c432be6de44290a557f30e382836f671e7fe83edc0cab07f037ab2f6e7c
+  metadata.gz: db9477a7f7900559bb7c362104d9921d79c12b84f18ccfe0e51006adafd6e478624d20a930184e9e3dfacf9d1c88321ef54b6688f89ddf627fa0ecef3da12c53
+  data.tar.gz: 5ef621dfd8a8ef83f2bf0d3eabb32b07ae881636fe4c1826fddc3e544d3b5193448ff96bd28f970046d499dca69d23affa42596d41315e8c3245c4e7db5be0b3

data/README.md

@@ -25,6 +25,9 @@ The result? LLM applications that actually scale and don't break when you sneeze
 - **Basic Optimization** - Simple prompt optimization techniques
 
 **Production Features:**
+- **Reliable JSON Extraction** - Automatic strategy selection for OpenAI structured outputs, Anthropic patterns, and fallback modes
+- **Smart Retry Logic** - Progressive fallback with exponential backoff for handling transient failures
+- **Performance Caching** - Schema and capability caching for faster repeated operations
 - **File-based Storage** - Basic optimization result persistence
 - **Multi-Platform Observability** - OpenTelemetry, New Relic, and Langfuse integration
 - **Basic Instrumentation** - Event tracking and logging
@@ -78,7 +81,9 @@ end
 
 # Configure DSPy with your LLM
 DSPy.configure do |c|
-  c.lm = DSPy::LM.new('openai/gpt-4o-mini', api_key: ENV['OPENAI_API_KEY'])
+  c.lm = DSPy::LM.new('openai/gpt-4o-mini', 
+                      api_key: ENV['OPENAI_API_KEY'],
+                      structured_outputs: true)  # Enable OpenAI's native JSON mode
 end
 
 # Create the predictor and run inference

data/lib/dspy/lm/adapter.rb

@@ -14,9 +14,10 @@ module DSPy
 
       # Chat interface that all adapters must implement
       # @param messages [Array<Hash>] Array of message hashes with :role and :content
+      # @param signature [DSPy::Signature, nil] Optional signature for structured outputs
       # @param block [Proc] Optional streaming block
       # @return [DSPy::LM::Response] Normalized response
-      def chat(messages:, &block)
+      def chat(messages:, signature: nil, &block)
         raise NotImplementedError, "Subclasses must implement #chat method"
       end
 

data/lib/dspy/lm/adapter_factory.rb

@@ -14,12 +14,17 @@ module DSPy
         # Creates an adapter instance based on model_id
         # @param model_id [String] Full model identifier (e.g., "openai/gpt-4")
         # @param api_key [String] API key for the provider
+        # @param options [Hash] Additional adapter-specific options
         # @return [DSPy::LM::Adapter] Appropriate adapter instance
-        def create(model_id, api_key:)
+        def create(model_id, api_key:, **options)
           provider, model = parse_model_id(model_id)
           adapter_class = get_adapter_class(provider)
           
-          adapter_class.new(model: model, api_key: api_key)
+          # Pass provider-specific options
+          adapter_options = { model: model, api_key: api_key }
+          adapter_options.merge!(options) if provider == 'openai' # Only OpenAI accepts structured_outputs for now
+          
+          adapter_class.new(**adapter_options)
         end
 
         private

data/lib/dspy/lm/adapters/anthropic_adapter.rb

@@ -11,7 +11,7 @@ module DSPy
         @client = Anthropic::Client.new(api_key: api_key)
       end
 
-      def chat(messages:, &block)
+      def chat(messages:, signature: nil, **extra_params, &block)
         # Anthropic requires system message to be separate from messages
         system_message, user_messages = extract_system_message(normalize_messages(messages))
         

data/lib/dspy/lm/adapters/openai/schema_converter.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require_relative "../../cache_manager"
+
+module DSPy
+  class LM
+    module Adapters
+      module OpenAI
+        # Converts DSPy signatures to OpenAI structured output format
+        class SchemaConverter
+          extend T::Sig
+
+          # Models that support structured outputs as of July 2025
+          STRUCTURED_OUTPUT_MODELS = T.let([
+            "gpt-4o-mini",
+            "gpt-4o-2024-08-06",
+            "gpt-4o",
+            "gpt-4-turbo",
+            "gpt-4-turbo-2024-04-09"
+          ].freeze, T::Array[String])
+
+          sig { params(signature_class: T.class_of(DSPy::Signature), name: T.nilable(String), strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+          def self.to_openai_format(signature_class, name: nil, strict: true)
+            # Build cache params from the method parameters
+            cache_params = { strict: strict }
+            cache_params[:name] = name if name
+            
+            # Check cache first
+            cache_manager = DSPy::LM.cache_manager
+            cached_schema = cache_manager.get_schema(signature_class, "openai", cache_params)
+            
+            if cached_schema
+              DSPy.logger.debug("Using cached schema for #{signature_class.name}")
+              return cached_schema
+            end
+            
+            # Get the output JSON schema from the signature class
+            output_schema = signature_class.output_json_schema
+            
+            # Build the complete schema
+            dspy_schema = {
+              "$schema": "http://json-schema.org/draft-06/schema#",
+              type: "object",
+              properties: output_schema[:properties] || {},
+              required: output_schema[:required] || []
+            }
+
+            # Generate a schema name if not provided
+            schema_name = name || generate_schema_name(signature_class)
+
+            # Remove the $schema field as OpenAI doesn't use it
+            openai_schema = dspy_schema.except(:$schema)
+
+            # Add additionalProperties: false for strict mode
+            if strict
+              openai_schema = add_additional_properties_recursively(openai_schema)
+            end
+
+            # Wrap in OpenAI's required format
+            result = {
+              type: "json_schema",
+              json_schema: {
+                name: schema_name,
+                strict: strict,
+                schema: openai_schema
+              }
+            }
+            
+            # Cache the result with same params
+            cache_manager.cache_schema(signature_class, "openai", result, cache_params)
+            
+            result
+          end
+
+          sig { params(model: String).returns(T::Boolean) }
+          def self.supports_structured_outputs?(model)
+            # Check cache first
+            cache_manager = DSPy::LM.cache_manager
+            cached_result = cache_manager.get_capability(model, "structured_outputs")
+            
+            if !cached_result.nil?
+              DSPy.logger.debug("Using cached capability check for #{model}")
+              return cached_result
+            end
+            
+            # Extract base model name without provider prefix
+            base_model = model.sub(/^openai\//, "")
+            
+            # Check if it's a supported model or a newer version
+            result = STRUCTURED_OUTPUT_MODELS.any? { |supported| base_model.start_with?(supported) }
+            
+            # Cache the result
+            cache_manager.cache_capability(model, "structured_outputs", result)
+            
+            result
+          end
+
+          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Array[String]) }
+          def self.validate_compatibility(schema)
+            issues = []
+
+            # Check for deeply nested objects (OpenAI has depth limits)
+            depth = calculate_depth(schema)
+            if depth > 5
+              issues << "Schema depth (#{depth}) exceeds recommended limit of 5 levels"
+            end
+
+            # Check for unsupported JSON Schema features
+            if contains_pattern_properties?(schema)
+              issues << "Pattern properties are not supported in OpenAI structured outputs"
+            end
+
+            if contains_conditional_schemas?(schema)
+              issues << "Conditional schemas (if/then/else) are not supported"
+            end
+
+            issues
+          end
+
+          private
+
+          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+          def self.add_additional_properties_recursively(schema)
+            return schema unless schema.is_a?(Hash)
+            
+            result = schema.dup
+            
+            # Add additionalProperties: false if this is an object
+            if result[:type] == "object"
+              result[:additionalProperties] = false
+            end
+            
+            # Process properties recursively
+            if result[:properties].is_a?(Hash)
+              result[:properties] = result[:properties].transform_values do |prop|
+                if prop.is_a?(Hash)
+                  processed = add_additional_properties_recursively(prop)
+                  # Special handling for arrays - ensure their items have additionalProperties if they're objects
+                  if processed[:type] == "array" && processed[:items].is_a?(Hash)
+                    processed[:items] = add_additional_properties_recursively(processed[:items])
+                  end
+                  processed
+                else
+                  prop
+                end
+              end
+            end
+            
+            # Process array items
+            if result[:items].is_a?(Hash)
+              processed_items = add_additional_properties_recursively(result[:items])
+              # OpenAI requires additionalProperties on all objects, even in array items
+              if processed_items.is_a?(Hash) && processed_items[:type] == "object" && !processed_items.key?(:additionalProperties)
+                processed_items[:additionalProperties] = false
+              end
+              result[:items] = processed_items
+            elsif result[:items].is_a?(Array)
+              # Handle tuple validation
+              result[:items] = result[:items].map do |item|
+                processed = item.is_a?(Hash) ? add_additional_properties_recursively(item) : item
+                if processed.is_a?(Hash) && processed[:type] == "object" && !processed.key?(:additionalProperties)
+                  processed[:additionalProperties] = false
+                end
+                processed
+              end
+            end
+            
+            # Process oneOf/anyOf/allOf
+            [:oneOf, :anyOf, :allOf].each do |key|
+              if result[key].is_a?(Array)
+                result[key] = result[key].map do |sub_schema|
+                  sub_schema.is_a?(Hash) ? add_additional_properties_recursively(sub_schema) : sub_schema
+                end
+              end
+            end
+            
+            result
+          end
+
+          sig { params(signature_class: T.class_of(DSPy::Signature)).returns(String) }
+          def self.generate_schema_name(signature_class)
+            # Use the signature class name
+            class_name = signature_class.name&.split("::")&.last
+            if class_name
+              class_name.gsub(/[^a-zA-Z0-9_]/, "_").downcase
+            else
+              # Fallback to a generic name
+              "dspy_output_#{Time.now.to_i}"
+            end
+          end
+
+          sig { params(schema: T::Hash[Symbol, T.untyped], current_depth: Integer).returns(Integer) }
+          def self.calculate_depth(schema, current_depth = 0)
+            return current_depth unless schema.is_a?(Hash)
+
+            max_depth = current_depth
+
+            # Check properties
+            if schema[:properties].is_a?(Hash)
+              schema[:properties].each_value do |prop|
+                if prop.is_a?(Hash)
+                  prop_depth = calculate_depth(prop, current_depth + 1)
+                  max_depth = [max_depth, prop_depth].max
+                end
+              end
+            end
+
+            # Check array items
+            if schema[:items].is_a?(Hash)
+              items_depth = calculate_depth(schema[:items], current_depth + 1)
+              max_depth = [max_depth, items_depth].max
+            end
+
+            # Check oneOf/anyOf/allOf
+            [:oneOf, :anyOf, :allOf].each do |key|
+              if schema[key].is_a?(Array)
+                schema[key].each do |sub_schema|
+                  if sub_schema.is_a?(Hash)
+                    sub_depth = calculate_depth(sub_schema, current_depth + 1)
+                    max_depth = [max_depth, sub_depth].max
+                  end
+                end
+              end
+            end
+
+            max_depth
+          end
+
+          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
+          def self.contains_pattern_properties?(schema)
+            return true if schema[:patternProperties]
+
+            # Recursively check nested schemas
+            [:properties, :items, :oneOf, :anyOf, :allOf].each do |key|
+              value = schema[key]
+              case value
+              when Hash
+                return true if contains_pattern_properties?(value)
+              when Array
+                return true if value.any? { |v| v.is_a?(Hash) && contains_pattern_properties?(v) }
+              end
+            end
+
+            false
+          end
+
+          sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
+          def self.contains_conditional_schemas?(schema)
+            return true if schema[:if] || schema[:then] || schema[:else]
+
+            # Recursively check nested schemas
+            [:properties, :items, :oneOf, :anyOf, :allOf].each do |key|
+              value = schema[key]
+              case value
+              when Hash
+                return true if contains_conditional_schemas?(value)
+              when Array
+                return true if value.any? { |v| v.is_a?(Hash) && contains_conditional_schemas?(v) }
+              end
+            end
+
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dspy/lm/adapters/openai_adapter.rb

@@ -1,23 +1,34 @@
 # frozen_string_literal: true
 
 require 'openai'
+require_relative 'openai/schema_converter'
 
 module DSPy
   class LM
     class OpenAIAdapter < Adapter
-      def initialize(model:, api_key:)
-        super
+      def initialize(model:, api_key:, structured_outputs: false)
+        super(model: model, api_key: api_key)
         validate_api_key!(api_key, 'openai')
         @client = OpenAI::Client.new(api_key: api_key)
+        @structured_outputs_enabled = structured_outputs
       end
 
-      def chat(messages:, &block)
+      def chat(messages:, signature: nil, response_format: nil, &block)
         request_params = {
           model: model,
           messages: normalize_messages(messages),
           temperature: 0.0 # DSPy default for deterministic responses
         }
 
+        # Add response format if provided by strategy
+        if response_format
+          request_params[:response_format] = response_format
+        elsif @structured_outputs_enabled && signature && supports_structured_outputs?
+          # Legacy behavior for backward compatibility
+          response_format = DSPy::LM::Adapters::OpenAI::SchemaConverter.to_openai_format(signature)
+          request_params[:response_format] = response_format
+        end
+
         # Add streaming if block provided
         if block_given?
           request_params[:stream] = proc do |chunk, _bytesize|
@@ -32,9 +43,15 @@ module DSPy
             raise AdapterError, "OpenAI API error: #{response.error}"
           end
 
-          content = response.choices.first.message.content
+          message = response.choices.first.message
+          content = message.content
           usage = response.usage
 
+          # Handle structured output refusals
+          if message.respond_to?(:refusal) && message.refusal
+            raise AdapterError, "OpenAI refused to generate output: #{message.refusal}"
+          end
+
           Response.new(
             content: content,
             usage: usage.respond_to?(:to_h) ? usage.to_h : usage,
@@ -42,13 +59,20 @@ module DSPy
               provider: 'openai',
               model: model,
               response_id: response.id,
-              created: response.created
+              created: response.created,
+              structured_output: @structured_outputs_enabled && signature && supports_structured_outputs?
             }
           )
         rescue => e
           raise AdapterError, "OpenAI adapter error: #{e.message}"
         end
       end
+
+      private
+
+      def supports_structured_outputs?
+        DSPy::LM::Adapters::OpenAI::SchemaConverter.supports_structured_outputs?(model)
+      end
     end
   end
 end

data/lib/dspy/lm/cache_manager.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module DSPy
+  class LM
+    # Manages caching for schemas and capability detection
+    class CacheManager
+      extend T::Sig
+      
+      # Cache entry with TTL
+      class CacheEntry < T::Struct
+        extend T::Sig
+        
+        const :value, T.untyped
+        const :expires_at, Time
+        
+        sig { returns(T::Boolean) }
+        def expired?
+          Time.now > expires_at
+        end
+      end
+      
+      DEFAULT_TTL = 3600 # 1 hour
+      
+      sig { void }
+      def initialize
+        @schema_cache = {}
+        @capability_cache = {}
+        @mutex = Mutex.new
+      end
+      
+      # Cache a schema for a signature class
+      sig { params(signature_class: T.class_of(DSPy::Signature), provider: String, schema: T.untyped, cache_params: T::Hash[Symbol, T.untyped]).void }
+      def cache_schema(signature_class, provider, schema, cache_params = {})
+        key = schema_key(signature_class, provider, cache_params)
+        
+        @mutex.synchronize do
+          @schema_cache[key] = CacheEntry.new(
+            value: schema,
+            expires_at: Time.now + DEFAULT_TTL
+          )
+        end
+        
+        DSPy.logger.debug("Cached schema for #{signature_class.name} (#{provider})")
+      end
+      
+      # Get cached schema if available
+      sig { params(signature_class: T.class_of(DSPy::Signature), provider: String, cache_params: T::Hash[Symbol, T.untyped]).returns(T.nilable(T.untyped)) }
+      def get_schema(signature_class, provider, cache_params = {})
+        key = schema_key(signature_class, provider, cache_params)
+        
+        @mutex.synchronize do
+          entry = @schema_cache[key]
+          
+          if entry.nil?
+            nil
+          elsif entry.expired?
+            @schema_cache.delete(key)
+            nil
+          else
+            entry.value
+          end
+        end
+      end
+      
+      # Cache capability detection result
+      sig { params(model: String, capability: String, result: T::Boolean).void }
+      def cache_capability(model, capability, result)
+        key = capability_key(model, capability)
+        
+        @mutex.synchronize do
+          @capability_cache[key] = CacheEntry.new(
+            value: result,
+            expires_at: Time.now + DEFAULT_TTL * 24 # Capabilities change less frequently
+          )
+        end
+        
+        DSPy.logger.debug("Cached capability #{capability} for #{model}: #{result}")
+      end
+      
+      # Get cached capability if available
+      sig { params(model: String, capability: String).returns(T.nilable(T::Boolean)) }
+      def get_capability(model, capability)
+        key = capability_key(model, capability)
+        
+        @mutex.synchronize do
+          entry = @capability_cache[key]
+          
+          if entry.nil?
+            nil
+          elsif entry.expired?
+            @capability_cache.delete(key)
+            nil
+          else
+            entry.value
+          end
+        end
+      end
+      
+      # Clear all caches
+      sig { void }
+      def clear!
+        @mutex.synchronize do
+          @schema_cache.clear
+          @capability_cache.clear
+        end
+        
+        DSPy.logger.debug("Cleared all caches")
+      end
+      
+      # Get cache statistics
+      sig { returns(T::Hash[Symbol, Integer]) }
+      def stats
+        @mutex.synchronize do
+          {
+            schema_entries: @schema_cache.size,
+            capability_entries: @capability_cache.size,
+            total_entries: @schema_cache.size + @capability_cache.size
+          }
+        end
+      end
+      
+      private
+      
+      sig { params(signature_class: T.class_of(DSPy::Signature), provider: String, cache_params: T::Hash[Symbol, T.untyped]).returns(String) }
+      def schema_key(signature_class, provider, cache_params = {})
+        params_str = cache_params.sort.map { |k, v| "#{k}:#{v}" }.join(":")
+        base_key = "schema:#{provider}:#{signature_class.name}"
+        params_str.empty? ? base_key : "#{base_key}:#{params_str}"
+      end
+      
+      sig { params(model: String, capability: String).returns(String) }
+      def capability_key(model, capability)
+        "capability:#{model}:#{capability}"
+      end
+    end
+    
+    # Global cache instance
+    @cache_manager = T.let(nil, T.nilable(CacheManager))
+    
+    class << self
+      extend T::Sig
+      
+      sig { returns(CacheManager) }
+      def cache_manager
+        @cache_manager ||= CacheManager.new
+      end
+    end
+  end
+end

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DSPy
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/dspy.rb

@@ -21,6 +21,19 @@ module DSPy
   setting :lm
   setting :logger, default: Dry.Logger(:dspy, formatter: :string)
   
+  # Structured output configuration for LLM providers
+  setting :structured_outputs do
+    setting :openai, default: false
+    setting :anthropic, default: false  # Reserved for future use
+    setting :strategy, default: nil  # Can be 'openai_structured_output', 'anthropic_extraction', 'enhanced_prompting', or nil for auto
+    setting :retry_enabled, default: true
+    setting :max_retries, default: 3
+    setting :fallback_enabled, default: true
+  end
+  
+  # Test mode disables sleeps in retry logic
+  setting :test_mode, default: false
+  
   # Nested instrumentation configuration using proper dry-configurable syntax
   setting :instrumentation do
     # Core settings

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.13.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.13.0
 - !ruby/object:Gem::Dependency
   name: anthropic
   requirement: !ruby/object:Gem::Requirement
@@ -171,9 +171,17 @@ files:
 - lib/dspy/lm/adapter.rb
 - lib/dspy/lm/adapter_factory.rb
 - lib/dspy/lm/adapters/anthropic_adapter.rb
+- lib/dspy/lm/adapters/openai/schema_converter.rb
 - lib/dspy/lm/adapters/openai_adapter.rb
+- lib/dspy/lm/cache_manager.rb
 - lib/dspy/lm/errors.rb
 - lib/dspy/lm/response.rb
+- lib/dspy/lm/retry_handler.rb
+- lib/dspy/lm/strategies/anthropic_extraction_strategy.rb
+- lib/dspy/lm/strategies/base_strategy.rb
+- lib/dspy/lm/strategies/enhanced_prompting_strategy.rb
+- lib/dspy/lm/strategies/openai_structured_output_strategy.rb
+- lib/dspy/lm/strategy_selector.rb
 - lib/dspy/memory.rb
 - lib/dspy/memory/embedding_engine.rb
 - lib/dspy/memory/in_memory_store.rb