dspy 0.9.1 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 306fa376ea024edd2fc75d7bc1af6a42e60770e9566b4dd114414a40c685f2a7
-  data.tar.gz: 74f321fdd09a5761d17481af846dcd85dc3a372f573f79659c4fcfc761e92a18
+  metadata.gz: b721c6c31be4c7a18cb488a7646ff356d658618a5a64ff36f50be9f731d9755a
+  data.tar.gz: 2e13ea6bf39e6a89872d604f22c7b197bf50924058824ff2a3483d859f1ba744
 SHA512:
-  metadata.gz: 5efb12df9c365114696857067bb4f869ce2329c0977666331846a5f070aca050312992c176fddb60ab701b5d31b017d23182d7a4e813e80cba152d155fc2091c
-  data.tar.gz: 2fd7f831b6fab1624d2de7702d54d6377a4a96fff4cb0230eb810285828b764033288bc3180e2aa2cf92b1a1026fa6552cdbf851174216a3fc1a651419accc59
+  metadata.gz: b6966d789e0ebad1e6ee6c65deaef2dec1d67d483908e7c0847df84998b4f167ad346d20de974af7194db890fcccabe38f3b38ab33dde95b430fdcd3b86a6045
+  data.tar.gz: 373e489777b036968ad5152aabc01141212c0409c849d89337075f1b2000de7504b8e2eaccca9755c4e52195b1d05d0667f9e4a8fe54c621cd90ba37b18837b0

data/README.md

@@ -67,6 +67,30 @@ Then run:
 bundle install
 ```
 
+#### System Dependencies for Ubuntu/Pop!_OS
+
+If you need to compile the `polars-df` dependency from source (used for data processing in evaluations), install these system packages:
+
+```bash
+# Update package list
+sudo apt-get update
+
+# Install Ruby development files (if not already installed)
+sudo apt-get install ruby-full ruby-dev
+
+# Install essential build tools
+sudo apt-get install build-essential
+
+# Install Rust and Cargo (required for polars-df compilation)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source $HOME/.cargo/env
+
+# Install CMake (often needed for Rust projects)
+sudo apt-get install cmake
+```
+
+**Note**: The `polars-df` gem compilation can take 15-20 minutes. Pre-built binaries are available for most platforms, so compilation is only needed if a pre-built binary isn't available for your system.
+
 ### Your First DSPy Program
 
 ```ruby

data/lib/dspy/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DSPy
+  class Error < StandardError; end
+  
+  class ConfigurationError < Error
+    def self.missing_lm(module_name)
+      new(<<~MESSAGE)
+        No language model configured for #{module_name} module.
+
+        To fix this, configure a language model either globally:
+
+          DSPy.configure do |config|
+            config.lm = DSPy::LM.new("openai/gpt-4", api_key: ENV["OPENAI_API_KEY"])
+          end
+
+        Or on the module instance:
+
+          module_instance.configure do |config|
+            config.lm = DSPy::LM.new("anthropic/claude-3", api_key: ENV["ANTHROPIC_API_KEY"])
+          end
+      MESSAGE
+    end
+  end
+end

data/lib/dspy/example.rb

@@ -192,8 +192,28 @@ module DSPy
     # String representation for debugging
     sig { returns(String) }
     def to_s
-      "DSPy::Example(#{@signature_class.name}) input=#{input_values} expected=#{expected_values}"
+      "DSPy::Example(#{@signature_class.name}) input=#{format_hash(input_values)} expected=#{format_hash(expected_values)}"
     end
+    
+    private
+    
+    # Format hash without escaping Unicode characters
+    sig { params(hash: T::Hash[Symbol, T.untyped]).returns(String) }
+    def format_hash(hash)
+      pairs = hash.map do |k, v|
+        value_str = case v
+                    when String
+                      # Don't escape Unicode characters
+                      "\"#{v}\""
+                    else
+                      v.inspect
+                    end
+        ":#{k} => #{value_str}"
+      end
+      "{#{pairs.join(", ")}}"
+    end
+    
+    public
 
     sig { returns(String) }
     def inspect

data/lib/dspy/mixins/instrumentation_helpers.rb

@@ -15,6 +15,9 @@ module DSPy
       # Prepares base instrumentation payload for prediction-based modules
       sig { params(signature_class: T.class_of(DSPy::Signature), input_values: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
       def prepare_base_instrumentation_payload(signature_class, input_values)
+        # Validate LM is configured before accessing its properties
+        raise DSPy::ConfigurationError.missing_lm(self.class.name) if lm.nil?
+        
         {
           signature_class: signature_class.name,
           model: lm.model,

data/lib/dspy/prediction.rb

@@ -0,0 +1,464 @@
+# typed: strict
+# frozen_string_literal: true
+
+module DSPy
+  class Prediction
+    extend T::Sig
+    extend T::Generic
+    include T::Props
+    include T::Props::Serializable
+
+    # The underlying struct that holds the actual data
+    sig { returns(T.untyped) }
+    attr_reader :_struct
+
+    # Schema information for type conversion
+    sig { returns(T.nilable(T::Class[T::Struct])) }
+    attr_reader :_schema
+
+    sig do
+      params(
+        schema: T.nilable(T.any(T::Class[T::Struct], T::Types::Base)),
+        attributes: T.untyped
+      ).void
+    end
+    def initialize(schema = nil, **attributes)
+      @_schema = extract_struct_class(schema)
+      
+      # Convert attributes based on schema if provided
+      converted_attributes = if @_schema
+        convert_attributes_with_schema(attributes)
+      else
+        attributes
+      end
+
+      # Create a dynamic struct to hold the data
+      struct_class = create_dynamic_struct(converted_attributes)
+      @_struct = struct_class.new(**converted_attributes)
+    end
+
+    # Delegate all method calls to the underlying struct
+    sig { params(method: Symbol, args: T.untyped, block: T.untyped).returns(T.untyped) }
+    def method_missing(method, *args, &block)
+      if @_struct.respond_to?(method)
+        @_struct.send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    sig { params(method: Symbol, include_all: T::Boolean).returns(T::Boolean) }
+    def respond_to_missing?(method, include_all = false)
+      @_struct.respond_to?(method, include_all) || super
+    end
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      @_struct.to_h
+    end
+
+    private
+
+    sig { params(schema: T.untyped).returns(T.nilable(T::Class[T::Struct])) }
+    def extract_struct_class(schema)
+      case schema
+      when Class
+        schema if schema < T::Struct
+      when T::Types::Simple
+        schema.raw_type if schema.raw_type < T::Struct
+      else
+        nil
+      end
+    end
+
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def convert_attributes_with_schema(attributes)
+      return attributes unless @_schema
+
+      converted = {}
+      
+      # Get discriminator mappings for T.any() fields
+      discriminator_mappings = detect_discriminator_fields(@_schema)
+
+      # First, add all the fields from the schema with defaults if not provided
+      @_schema.props.each do |field_name, prop_info|
+        # Skip if attribute was provided
+        next if attributes.key?(field_name)
+        
+        # Apply default value if available
+        default_value = prop_info[:default]
+        if !default_value.nil?
+          if default_value.is_a?(Proc)
+            converted[field_name] = default_value.call
+          else
+            converted[field_name] = default_value
+          end
+        elsif prop_info[:fully_optional]
+          # For optional fields without defaults, set to nil
+          converted[field_name] = nil
+        end
+      end
+
+      attributes.each do |key, value|
+        prop_info = @_schema.props[key]
+        
+        if prop_info && discriminator_mappings[key]
+          # This is a T.any() field with a discriminator
+          discriminator_field, type_mapping = discriminator_mappings[key]
+          discriminator_value = attributes[discriminator_field]
+          prop_type = prop_info[:type_object] || prop_info[:type]
+          
+          converted[key] = convert_union_type(value, discriminator_value, type_mapping, prop_type)
+        elsif prop_info
+          prop_type = prop_info[:type_object] || prop_info[:type]
+          
+          # Handle nil values explicitly
+          if value.nil?
+            # Check if there's a default value
+            default_value = prop_info[:default]
+            if !default_value.nil?
+              converted[key] = default_value.is_a?(Proc) ? default_value.call : default_value
+            else
+              converted[key] = nil
+            end
+          elsif is_enum_type?(prop_type) && value.is_a?(String)
+            # Convert string to enum
+            converted[key] = prop_type.raw_type.deserialize(value)
+          elsif value.is_a?(Hash) && needs_struct_conversion?(prop_type)
+            # Regular struct field that needs conversion
+            converted[key] = convert_to_struct(value, prop_type)
+          elsif value.is_a?(Array) && needs_array_conversion?(prop_type)
+            # Array field that might contain structs
+            converted[key] = convert_array_elements(value, prop_type)
+          else
+            converted[key] = value
+          end
+        else
+          converted[key] = value
+        end
+      end
+
+      converted
+    end
+
+    sig { params(schema: T::Class[T::Struct]).returns(T::Hash[Symbol, [Symbol, T::Hash[String, T.untyped]]]) }
+    def detect_discriminator_fields(schema)
+      discriminator_mappings = {}
+      props = schema.props.to_a
+
+      props.each_with_index do |(prop_name, prop_info), index|
+        prop_type = prop_info[:type_object] || prop_info[:type]
+        next unless is_union_type?(prop_type)
+
+        # Look for preceding String or Enum field as potential discriminator
+        if index > 0
+          prev_prop_name, prev_prop_info = props[index - 1]
+          prev_prop_type = prev_prop_info[:type_object] || prev_prop_info[:type]
+          if prev_prop_type && (is_string_type?(prev_prop_type) || is_enum_type?(prev_prop_type))
+            # This String/Enum field might be a discriminator
+            type_mapping = build_type_mapping_from_union(prop_type, prev_prop_type)
+            discriminator_mappings[prop_name] = [prev_prop_name, type_mapping]
+          end
+        end
+      end
+
+      discriminator_mappings
+    end
+
+    sig { params(type: T.untyped).returns(T::Boolean) }
+    def is_union_type?(type)
+      type.is_a?(T::Types::Union) && !is_nilable_type?(type)
+    end
+
+    sig { params(type: T.untyped).returns(T::Boolean) }
+    def is_nilable_type?(type)
+      type.is_a?(T::Types::Union) && type.types.any? { |t| t == T::Utils.coerce(NilClass) }
+    end
+
+    sig { params(type: T.untyped).returns(T::Boolean) }
+    def is_string_type?(type)
+      case type
+      when T::Types::Simple
+        type.raw_type == String
+      else
+        false
+      end
+    end
+
+    sig { params(type: T.untyped).returns(T::Boolean) }
+    def is_enum_type?(type)
+      return false if type.nil?
+      return false unless type.is_a?(T::Types::Simple)
+      
+      begin
+        raw_type = type.raw_type
+        return false unless raw_type.is_a?(Class)
+        result = raw_type < T::Enum
+        return result == true # Force conversion to boolean
+      rescue StandardError
+        return false
+      end
+    end
+
+    sig { params(union_type: T::Types::Union, discriminator_type: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def build_type_mapping_from_union(union_type, discriminator_type)
+      mapping = {}
+      
+      if is_enum_type?(discriminator_type)
+        # For enum discriminators, try to map enum values to struct types
+        enum_class = discriminator_type.raw_type
+        union_type.types.each do |type|
+          next if type == T::Utils.coerce(NilClass)
+          
+          if type.is_a?(T::Types::Simple) && type.raw_type < T::Struct
+            struct_class = type.raw_type
+            struct_name = struct_class.name.split("::").last
+            
+            # Try to find matching enum value by name
+            enum_class.values.each do |enum_value|
+              enum_name = enum_value.instance_variable_get(:@const_name).to_s
+              if enum_name == struct_name
+                # Exact match
+                mapping[enum_value.serialize] = struct_class
+              elsif enum_name.downcase == struct_name.downcase
+                # Case-insensitive match
+                mapping[enum_value.serialize] = struct_class
+              end
+            end
+            
+            # Also add snake_case mapping as fallback
+            discriminator_value = struct_name
+              .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .downcase
+            mapping[discriminator_value] = struct_class
+          end
+        end
+      else
+        # String discriminators use snake_case convention
+        union_type.types.each do |type|
+          next if type == T::Utils.coerce(NilClass)
+          
+          if type.is_a?(T::Types::Simple) && type.raw_type < T::Struct
+            struct_class = type.raw_type
+            # Convert class name to snake_case for discriminator value
+            discriminator_value = struct_class.name
+              .split("::").last
+              .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .downcase
+            
+            mapping[discriminator_value] = struct_class
+          end
+        end
+      end
+
+      mapping
+    end
+
+    sig do
+      params(
+        value: T.untyped,
+        discriminator_value: T.untyped,
+        type_mapping: T::Hash[String, T.untyped],
+        union_type: T.untyped
+      ).returns(T.untyped)
+    end
+    def convert_union_type(value, discriminator_value, type_mapping, union_type)
+      return value unless value.is_a?(Hash)
+      
+      # Handle enum discriminators
+      discriminator_str = case discriminator_value
+      when T::Enum
+        discriminator_value.serialize
+      when String
+        discriminator_value
+      else
+        return value
+      end
+
+      struct_class = type_mapping[discriminator_str]
+      return value unless struct_class
+
+      # Convert the Hash to the appropriate struct type
+      struct_class.new(**value)
+    rescue TypeError, ArgumentError
+      # If conversion fails, return the original value
+      value
+    end
+
+    sig { params(type: T.untyped).returns(T::Boolean) }
+    def needs_struct_conversion?(type)
+      case type
+      when T::Types::Simple
+        type.raw_type < T::Struct
+      when T::Types::Union
+        # Check if any type in the union is a struct
+        type.types.any? { |t| needs_struct_conversion?(t) }
+      else
+        false
+      end
+    end
+
+    sig { params(value: T::Hash[Symbol, T.untyped], type: T.untyped).returns(T.untyped) }
+    def convert_to_struct(value, type)
+      case type
+      when T::Types::Simple
+        struct_class = type.raw_type
+        # Convert nested hash values to structs if needed
+        converted_hash = {}
+        
+        # First, apply defaults for missing fields
+        struct_class.props.each do |field_name, prop_info|
+          next if value.key?(field_name)
+          
+          default_value = prop_info[:default]
+          if !default_value.nil?
+            converted_hash[field_name] = default_value.is_a?(Proc) ? default_value.call : default_value
+          end
+        end
+        
+        value.each do |k, v|
+          prop_info = struct_class.props[k]
+          if prop_info
+            prop_type = prop_info[:type_object] || prop_info[:type]
+            if v.is_a?(String) && is_enum_type?(prop_type)
+              # Convert string to enum
+              converted_hash[k] = prop_type.raw_type.deserialize(v)
+            elsif v.is_a?(Hash) && needs_struct_conversion?(prop_type)
+              converted_hash[k] = convert_to_struct(v, prop_type)
+            elsif v.is_a?(Array) && needs_array_conversion?(prop_type)
+              converted_hash[k] = convert_array_elements(v, prop_type)
+            else
+              converted_hash[k] = v
+            end
+          else
+            converted_hash[k] = v
+          end
+        end
+        begin
+          struct_class.new(**converted_hash)
+        rescue => e
+          # Return original value if conversion fails
+          value
+        end
+      when T::Types::Union
+        # For unions without discriminator, try each type
+        type.types.each do |t|
+          next if t == T::Utils.coerce(NilClass)
+          
+          begin
+            return convert_to_struct(value, t) if needs_struct_conversion?(t)
+          rescue TypeError, ArgumentError
+            # Try next type
+          end
+        end
+        value
+      else
+        value
+      end
+    rescue TypeError, ArgumentError
+      value
+    end
+
+    sig { params(type: T.untyped).returns(T::Boolean) }
+    def needs_array_conversion?(type)
+      case type
+      when T::Types::TypedArray
+        needs_struct_conversion?(type.type)
+      else
+        false
+      end
+    end
+
+    sig { params(array: T::Array[T.untyped], type: T.untyped).returns(T::Array[T.untyped]) }
+    def convert_array_elements(array, type)
+      return array unless type.is_a?(T::Types::TypedArray)
+
+      element_type = type.type
+      # Check if elements need any conversion (structs or enums)
+      return array unless needs_struct_conversion?(element_type) || is_enum_type?(element_type)
+
+      array.map do |element|
+        if element.is_a?(Hash)
+          # For union types, we need to infer which struct type based on the hash structure
+          if is_union_type?(element_type) && !is_nilable_type?(element_type)
+            convert_hash_to_union_struct(element, element_type)
+          else
+            convert_to_struct(element, element_type)
+          end
+        elsif element.is_a?(String) && is_enum_type?(element_type)
+          # Convert string to enum
+          element_type.raw_type.deserialize(element)
+        else
+          element
+        end
+      end
+    end
+
+    sig { params(hash: T::Hash[Symbol, T.untyped], union_type: T::Types::Union).returns(T.untyped) }
+    def convert_hash_to_union_struct(hash, union_type)
+      # Try to match the hash structure to one of the union types
+      union_type.types.each do |type|
+        next if type == T::Utils.coerce(NilClass)
+        
+        if type.is_a?(T::Types::Simple) && type.raw_type < T::Struct
+          struct_class = type.raw_type
+          
+          # Check if all required fields of this struct are present in the hash
+          required_fields = struct_class.props.reject { |_, info| info[:fully_optional] }.keys
+          if required_fields.all? { |field| hash.key?(field) }
+            begin
+              # Need to convert nested values too
+              converted_hash = {}
+              hash.each do |k, v|
+                prop_info = struct_class.props[k]
+                if prop_info
+                  prop_type = prop_info[:type_object] || prop_info[:type]
+                  if v.is_a?(String) && is_enum_type?(prop_type)
+                    converted_hash[k] = prop_type.raw_type.deserialize(v)
+                  elsif v.is_a?(Hash) && needs_struct_conversion?(prop_type)
+                    converted_hash[k] = convert_to_struct(v, prop_type)
+                  elsif v.is_a?(Array) && needs_array_conversion?(prop_type)
+                    converted_hash[k] = convert_array_elements(v, prop_type)
+                  else
+                    converted_hash[k] = v
+                  end
+                else
+                  converted_hash[k] = v
+                end
+              end
+              return struct_class.new(**converted_hash)
+            rescue TypeError, ArgumentError
+              # This struct didn't match, try the next one
+            end
+          end
+        end
+      end
+      
+      # If no struct matched, return the original hash
+      hash
+    end
+
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(T::Class[T::Struct]) }
+    def create_dynamic_struct(attributes)
+      # If we have a schema, include all fields from it in the dynamic struct
+      all_fields = if @_schema
+        # Merge schema fields with provided attributes
+        schema_fields = @_schema.props.keys.to_h { |k| [k, nil] }
+        schema_fields.merge(attributes)
+      else
+        attributes
+      end
+      
+      Class.new(T::Struct) do
+        const :_prediction_marker, T::Boolean, default: true
+        
+        all_fields.each do |key, value|
+          # Use T.untyped for dynamic properties
+          const key, T.untyped
+        end
+      end
+    end
+  end
+end

data/lib/dspy/signature.rb

@@ -147,6 +147,11 @@ module DSPy
         }
       end
 
+      sig { returns(T.nilable(T.class_of(T::Struct))) }
+      def input_schema
+        @input_struct_class
+      end
+
       sig { returns(T::Hash[Symbol, T.untyped]) }
       def output_json_schema
         return {} unless @output_struct_class
@@ -169,6 +174,11 @@ module DSPy
         }
       end
 
+      sig { returns(T.nilable(T.class_of(T::Struct))) }
+      def output_schema
+        @output_struct_class
+      end
+
       private
 
       sig { params(type: T.untyped).returns(T::Hash[Symbol, T.untyped]) }

data/lib/dspy/version.rb

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

data/lib/dspy.rb

@@ -5,6 +5,7 @@ require 'dry/logger'
 require 'securerandom'
 
 require_relative 'dspy/version'
+require_relative 'dspy/errors'
 
 module DSPy
   extend Dry::Configurable
@@ -123,6 +124,7 @@ require_relative 'dspy/prompt'
 require_relative 'dspy/example'
 require_relative 'dspy/lm'
 require_relative 'dspy/strategy'
+require_relative 'dspy/prediction'
 require_relative 'dspy/predict'
 require_relative 'dspy/chain_of_thought'
 require_relative 'dspy/re_act'
@@ -144,3 +146,20 @@ require_relative 'dspy/registry/signature_registry'
 require_relative 'dspy/registry/registry_manager'
 
 # LoggerSubscriber will be lazy-initialized when first accessed
+
+# Detect potential gem conflicts and warn users
+# DSPy uses the official openai gem, warn if ruby-openai (community version) is detected
+if defined?(OpenAI) && defined?(OpenAI::Client) && !defined?(OpenAI::Internal)
+  warn <<~WARNING
+    WARNING: ruby-openai gem detected. This may cause conflicts with DSPy's OpenAI integration.
+    
+    DSPy uses the official 'openai' gem. The community 'ruby-openai' gem uses the same
+    OpenAI namespace and will cause conflicts.
+    
+    To fix this, remove 'ruby-openai' from your Gemfile and use the official gem instead:
+    - Remove: gem 'ruby-openai'
+    - Keep: gem 'openai' (official SDK that DSPy uses)
+    
+    The official gem provides better compatibility and is actively maintained by OpenAI.
+  WARNING
+end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.1
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-07-16 00:00:00.000000000 Z
+date: 2025-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -161,6 +162,7 @@ files:
 - lib/dspy.rb
 - lib/dspy/chain_of_thought.rb
 - lib/dspy/code_act.rb
+- lib/dspy/errors.rb
 - lib/dspy/evaluate.rb
 - lib/dspy/example.rb
 - lib/dspy/few_shot_example.rb
@@ -196,6 +198,7 @@ files:
 - lib/dspy/mixins/type_coercion.rb
 - lib/dspy/module.rb
 - lib/dspy/predict.rb
+- lib/dspy/prediction.rb
 - lib/dspy/prompt.rb
 - lib/dspy/propose/grounded_proposer.rb
 - lib/dspy/re_act.rb
@@ -225,6 +228,7 @@ homepage: https://github.com/vicentereig/dspy.rb
 licenses:
 - MIT
 metadata: {}
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -239,7 +243,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.5.22
+signing_key: 
 specification_version: 4
 summary: Ruby port of DSPy 2.6
 test_files: []