dspy 0.18.1 → 0.19.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d46ecbbc5bd53e71019b021fb9003dacc64ca73b4928664f2a4da559b3f1d008
-  data.tar.gz: 9906abf9a4db852adf007679b85673910eac36028b61cd7b7ef34da189e9809f
+  metadata.gz: d76e6cfecee3a85c7d8cd389b39eb0401e2051644e0f3ada98ab03645414f35e
+  data.tar.gz: fe078c869c9ee45237916dd10bd12a5d9bb80ea629c1bb6b0a29ae6ff5249b73
 SHA512:
-  metadata.gz: 66d209c295b82a67f7fe0768fd326500ec1be2e79a6947e9322a78c8fee27db7bec6ba253f12efd76b6db1abc3d7587ee3247109b766f92539a0a0ca8045fc33
-  data.tar.gz: 56b5fe4bcb77e5a322bfc7b87703c82c95da838940a6727d64afd0f3f4b0e18618dbe3faa48b16c3b239208c8421168dbca874c89bceb090270b7262aa0c9f20
+  metadata.gz: 56565be338d06d517daa931d7ebfb32f259b92d9b8a55140783bcf34f635ace57213909d74003ad33b6e8761d5c1fae950f1f6332ee55131d8a7ffd5c4a58183
+  data.tar.gz: 3e36f838fbba8e06428397611f1f2e2476f789c7f4714a98ce2198f38bf5632a0f4e12cf5be56282c48d31071c9b784959f0095f27bc8f42c44472ad43111d41

data/lib/dspy/error_formatter.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  # Utility class for formatting complex error messages into human-readable format
+  class ErrorFormatter
+    extend T::Sig
+
+    # Main entry point for formatting errors
+    sig { params(error_message: String, context: T.nilable(String)).returns(String) }
+    def self.format_error(error_message, context = nil)
+      # Try different error patterns in order of specificity
+      if sorbet_type_error?(error_message)
+        format_sorbet_type_error(error_message)
+      elsif argument_error?(error_message)
+        format_argument_error(error_message)
+      else
+        # Fallback to original message with minor cleanup
+        clean_error_message(error_message)
+      end
+    end
+
+    private
+
+    # Check if this is a Sorbet runtime type validation error
+    sig { params(message: String).returns(T::Boolean) }
+    def self.sorbet_type_error?(message)
+      message.match?(/Can't set \.(\w+) to .* \(instance of (\w+)\) - need a (.+)/)
+    end
+
+    # Check if this is an ArgumentError (missing required fields, etc.)
+    sig { params(message: String).returns(T::Boolean) }
+    def self.argument_error?(message)
+      message.match?(/missing keyword/i) || message.match?(/unknown keyword/i)
+    end
+
+    # Format Sorbet type validation errors
+    sig { params(message: String).returns(String) }
+    def self.format_sorbet_type_error(message)
+      # Parse the Sorbet error pattern
+      match = message.match(/Can't set \.(\w+) to (.+?) \(instance of (\w+)\) - need a (.+?)(?:\n|$)/)
+      return clean_error_message(message) unless match
+
+      field_name = match[1]
+      raw_value = match[2]
+      actual_type = match[3]
+      expected_type = match[4]
+
+      # Extract sample data for display (truncate if too long)
+      sample_data = if raw_value.length > 100
+        "#{raw_value[0..100]}..."
+      else
+        raw_value
+      end
+
+      <<~ERROR.strip
+        Type Mismatch in '#{field_name}'
+
+        Expected: #{expected_type}
+        Received: #{actual_type} (plain Ruby #{actual_type.downcase})
+
+        #{generate_type_specific_explanation(actual_type, expected_type)}
+
+        Suggestions:
+        #{generate_suggestions(field_name, actual_type, expected_type)}
+
+        Sample data received: #{sample_data}
+      ERROR
+    end
+
+    # Format ArgumentError messages (missing/unknown keywords)
+    sig { params(message: String).returns(String) }
+    def self.format_argument_error(message)
+      if message.match(/missing keyword: (.+)/i)
+        missing_fields = $1.split(', ')
+        format_missing_fields_error(missing_fields)
+      elsif message.match(/unknown keyword: (.+)/i)
+        unknown_fields = $1.split(', ')
+        format_unknown_fields_error(unknown_fields)
+      else
+        clean_error_message(message)
+      end
+    end
+
+    # Format missing required fields error
+    sig { params(fields: T::Array[String]).returns(String) }
+    def self.format_missing_fields_error(fields)
+      field_list = fields.map { |f| "• #{f}" }.join("\n")
+      
+      <<~ERROR.strip
+        Missing Required Fields
+
+        The following required fields were not provided:
+        #{field_list}
+
+        Suggestions:
+        • Check your signature definition - these fields should be marked as optional if they're not always provided
+        • Ensure your LLM prompt asks for all required information
+        • Consider providing default values in your signature
+
+        This usually happens when the LLM response doesn't include all expected fields.
+      ERROR
+    end
+
+    # Format unknown fields error
+    sig { params(fields: T::Array[String]).returns(String) }
+    def self.format_unknown_fields_error(fields)
+      field_list = fields.map { |f| "• #{f}" }.join("\n")
+      
+      <<~ERROR.strip
+        Unknown Fields in Response
+
+        The LLM response included unexpected fields:
+        #{field_list}
+
+        Suggestions:
+        • Check if these fields should be added to your signature definition
+        • Review your prompt to ensure it only asks for expected fields
+        • Consider if the LLM is hallucinating extra information
+
+        Extra fields are ignored, but this might indicate a prompt or signature mismatch.
+      ERROR
+    end
+
+    # Generate type-specific explanations
+    sig { params(actual_type: String, expected_type: String).returns(String) }
+    def self.generate_type_specific_explanation(actual_type, expected_type)
+      case actual_type
+      when 'Array'
+        if expected_type.match(/T::Array\[(.+)\]/)
+          struct_type = $1
+          "The LLM returned a plain Ruby array with hash elements, but your signature requires an array of #{struct_type} struct objects."
+        else
+          "The LLM returned a #{actual_type}, but your signature requires #{expected_type}."
+        end
+      when 'Hash'
+        if expected_type != 'Hash' && !expected_type.include?('T::Hash')
+          "The LLM returned a plain Ruby hash, but your signature requires a #{expected_type} struct object."
+        else
+          "The LLM returned a #{actual_type}, but your signature requires #{expected_type}."
+        end
+      when 'String'
+        if expected_type.include?('T::Enum')
+          "The LLM returned a string, but your signature requires an enum value."
+        else
+          "The LLM returned a #{actual_type}, but your signature requires #{expected_type}."
+        end
+      else
+        "The LLM returned a #{actual_type}, but your signature requires #{expected_type}."
+      end
+    end
+
+    # Generate field and type-specific suggestions
+    sig { params(field_name: String, actual_type: String, expected_type: String).returns(String) }
+    def self.generate_suggestions(field_name, actual_type, expected_type)
+      suggestions = []
+      
+      # Type-specific suggestions
+      case actual_type
+      when 'Array'
+        if expected_type.match(/T::Array\[(.+)\]/)
+          struct_type = $1
+          suggestions << "Check your signature uses proper T::Array[#{struct_type}] typing"
+          suggestions << "Verify the LLM response format matches your expected structure"
+          suggestions << "Ensure your struct definitions are correct and accessible"
+        else
+          suggestions << "Check your signature definition for the '#{field_name}' field"
+          suggestions << "Verify the LLM prompt asks for the correct data type"
+        end
+      when 'Hash'
+        if expected_type != 'Hash' && !expected_type.include?('T::Hash')
+          suggestions << "Check your signature uses proper #{expected_type} typing"
+          suggestions << "Verify the LLM response contains the expected fields"
+        else
+          suggestions << "Check your signature definition for the '#{field_name}' field"
+          suggestions << "Verify the LLM prompt asks for the correct data type"
+        end
+      when 'String'
+        if expected_type.include?('T::Enum')
+          suggestions << "Check your enum definition and available values"
+          suggestions << "Ensure your prompt specifies valid enum options"
+        else
+          suggestions << "Check your signature definition for the '#{field_name}' field"
+          suggestions << "Verify the LLM prompt asks for the correct data type"
+        end
+      else
+        suggestions << "Check your signature definition for the '#{field_name}' field"
+        suggestions << "Verify the LLM prompt asks for the correct data type"
+      end
+      
+      # General suggestions
+      suggestions << "Consider if your prompt needs clearer type instructions"
+      suggestions << "Check if the LLM model supports structured output for complex types"
+      
+      suggestions.map { |s| "• #{s}" }.join("\n")
+    end
+
+    # Clean up error messages by removing internal stack traces and formatting
+    sig { params(message: String).returns(String) }
+    def self.clean_error_message(message)
+      # Remove caller information that's not useful to end users
+      cleaned = message.gsub(/\nCaller:.*$/m, '')
+      
+      # Remove excessive newlines and clean up formatting
+      cleaned.gsub(/\n+/, "\n").strip
+    end
+  end
+end

data/lib/dspy/predict.rb

@@ -5,20 +5,40 @@ require_relative 'module'
 require_relative 'prompt'
 require_relative 'mixins/struct_builder'
 require_relative 'mixins/type_coercion'
+require_relative 'error_formatter'
 
 module DSPy
   # Exception raised when prediction fails validation
   class PredictionInvalidError < StandardError
     extend T::Sig
 
-    sig { params(errors: T::Hash[T.untyped, T.untyped]).void }
-    def initialize(errors)
+    sig { params(errors: T::Hash[T.untyped, T.untyped], context: T.nilable(String)).void }
+    def initialize(errors, context: nil)
       @errors = errors
-      super("Prediction validation failed: #{errors}")
+      @context = context
+      
+      # Format the error message using ErrorFormatter for better readability
+      formatted_message = if errors.key?(:output) && errors[:output].is_a?(String)
+        # This is likely a type validation error from Sorbet
+        formatted = DSPy::ErrorFormatter.format_error(errors[:output], context)
+        "Prediction validation failed:\n\n#{formatted}"
+      elsif errors.key?(:input) && errors[:input].is_a?(String)
+        # This is an input validation error
+        formatted = DSPy::ErrorFormatter.format_error(errors[:input], context)
+        "Input validation failed:\n\n#{formatted}"
+      else
+        # Fallback to original format for any other error structure
+        "Prediction validation failed: #{errors}"
+      end
+      
+      super(formatted_message)
     end
 
     sig { returns(T::Hash[T.untyped, T.untyped]) }
     attr_reader :errors
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :context
   end
 
   class Predict < DSPy::Module

data/lib/dspy/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.18.1
+  version: 0.19.1
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 bindir: bin
 cert_chain: []
-date: 2025-08-10 00:00:00.000000000 Z
+date: 2025-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -175,6 +175,7 @@ files:
 - lib/dspy/chain_of_thought.rb
 - lib/dspy/code_act.rb
 - lib/dspy/context.rb
+- lib/dspy/error_formatter.rb
 - lib/dspy/errors.rb
 - lib/dspy/evaluate.rb
 - lib/dspy/example.rb