dspy 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63f9d02616c10429f0d409e08036fbf25e2557ba02d48785271ffd7b90aec464
-  data.tar.gz: 46eb23dd11cc7e81ec2c58ee13beca5d36cbfc8c221ec1ae1b70b59cf3e56f36
+  metadata.gz: '080e190ff2991ff97869bad95117f30a9e17a79b264285e1f122b1de6df4bbaf'
+  data.tar.gz: d3b47ff7e835a22111466e9c3e9a3be445e0a39c77a18c109482814c2804104e
 SHA512:
-  metadata.gz: d53d4a72482146cf692304f82a0c273ebc06925dc66042d461e600e77fa99f79fda88f67282b5497a4625275d7311b1d10ea255814085883e15a323a7c4d56e9
-  data.tar.gz: b2f63c03a162101345589732a192267a55464c7ebed524274a175b66ee872501ec36386d4fd7995005d4726fa0181bb82a9d48b32b09ed722e0662e39fd6958b
+  metadata.gz: 2aa3f3222b7e8c2039003e7acf724f32c9c5b5ad45d226fd93e74d2ca484a1be5332be96058b30ff1a5509e702ad4321dd9e1194b273820c897492277356efcc
+  data.tar.gz: 592266d28de856aad7da0481b62bf3ad9a6ce7ac06013ea1c8c980b1dc964267a3d85a930db8945a516f1265a0c0a38dbbf27206d1243eda7cf4a978468f0754

data/lib/dspy/chain_of_thought.rb

@@ -105,6 +105,8 @@ module DSPy
     # Creates signature class with enhanced description and reasoning field
     sig { params(signature_class: T.class_of(DSPy::Signature), enhanced_output_struct: T.class_of(T::Struct)).returns(T.class_of(DSPy::Signature)) }
     def create_signature_class(signature_class, enhanced_output_struct)
+      original_name = signature_class.name
+      
       Class.new(DSPy::Signature) do
         description "#{signature_class.description} Think step by step."
 
@@ -125,8 +127,16 @@ module DSPy
         # Add reasoning field descriptor (ChainOfThought always provides this)
         @output_field_descriptors[:reasoning] = FieldDescriptor.new(String, "Step by step reasoning process")
 
+        # Store the original signature name for tracking/logging
+        @original_signature_name = original_name
+
         class << self
-          attr_reader :input_struct_class, :output_struct_class
+          attr_reader :input_struct_class, :output_struct_class, :original_signature_name
+          
+          # Override name to return the original signature name for tracking
+          def name
+            @original_signature_name || super
+          end
         end
       end
     end

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.0"
+  VERSION = "0.19.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 bindir: bin
 cert_chain: []
-date: 2025-08-08 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