dspy 0.34.1 → 0.34.3

data/lib/dspy/mixins/type_coercion.rb

@@ -9,6 +9,62 @@ module DSPy
     module TypeCoercion
       extend T::Sig
 
+      # Centralized enum deserialization with case-insensitive fallback.
+      # Uses try_deserialize for O(1) exact match, then a lazily-built
+      # case-insensitive lookup hash as fallback for LLM casing variations.
+      #
+      # Returns the enum instance on match, or nil if no match found.
+      sig { params(enum_class: T.untyped, value: T.untyped).returns(T.nilable(T::Enum)) }
+      def self.deserialize_enum(enum_class, value)
+        return value if value.is_a?(enum_class)
+
+        str = value.to_s
+        result = enum_class.try_deserialize(str)
+        return result if result
+
+        @ci_enum_cache ||= {}
+        ci_map = (@ci_enum_cache[enum_class] ||=
+          enum_class.values.each_with_object({}) { |v, h| h[v.serialize.downcase.freeze] = v }.freeze)
+
+        ci_map[str.downcase]
+      end
+
+      # Module-level enum type detection (delegates to instance method)
+      sig { params(type: T.untyped).returns(T::Boolean) }
+      def self.enum_type?(type)
+        return false unless type
+
+        case type
+        when Class
+          !!(type < T::Enum)
+        when T::Types::Simple
+          type.raw_type.is_a?(Class) && !!(type.raw_type < T::Enum)
+        when T::Types::Union
+          non_nil = type.types.reject { |t| t.is_a?(T::Types::Simple) && t.raw_type == NilClass }
+          non_nil.size == 1 && enum_type?(non_nil.first)
+        else
+          false
+        end
+      rescue StandardError
+        false
+      end
+
+      # Module-level enum class extraction (delegates to instance method)
+      sig { params(prop_type: T.untyped).returns(T.class_of(T::Enum)) }
+      def self.extract_enum_class(prop_type)
+        case prop_type
+        when Class
+          return prop_type if prop_type < T::Enum
+        when T::Types::Simple
+          return prop_type.raw_type if prop_type.raw_type.is_a?(Class) && prop_type.raw_type < T::Enum
+        when T::Types::Union
+          non_nil = prop_type.types.reject { |t| t.is_a?(T::Types::Simple) && t.raw_type == NilClass }
+          return extract_enum_class(non_nil.first) if non_nil.size == 1
+        end
+
+        raise ArgumentError, "Not an enum type: #{prop_type.inspect}"
+      end
+
       private
 
       # Coerces output attributes to match their expected types
@@ -57,32 +113,16 @@ module DSPy
         end
       end
 
-      # Checks if a type is an enum type
+      # Checks if a type is an enum type (handles Class, Simple, and nilable unions)
       sig { params(type: T.untyped).returns(T::Boolean) }
       def enum_type?(type)
-        return false unless type
-        
-        if type.is_a?(Class)
-          !!(type < T::Enum)
-        elsif type.is_a?(T::Types::Simple)
-          !!(type.raw_type < T::Enum)
-        else
-          false
-        end
-      rescue StandardError
-        false
+        DSPy::Mixins::TypeCoercion.enum_type?(type)
       end
 
-      # Extracts the enum class from a type
+      # Extracts the enum class from a type (handles Class, Simple, and nilable unions)
       sig { params(prop_type: T.untyped).returns(T.class_of(T::Enum)) }
       def extract_enum_class(prop_type)
-        if prop_type.is_a?(Class) && prop_type < T::Enum
-          prop_type
-        elsif prop_type.is_a?(T::Types::Simple) && prop_type.raw_type < T::Enum
-          prop_type.raw_type
-        else
-          T.cast(prop_type, T.class_of(T::Enum))
-        end
+        DSPy::Mixins::TypeCoercion.extract_enum_class(prop_type)
       end
 
       # Checks if a type matches a simple type (like Float, Integer)
@@ -130,6 +170,106 @@ module DSPy
         type.is_a?(T::Types::Union) && type.types.any? { |t| t == T::Utils.coerce(NilClass) }
       end
 
+      # Checks if a type is a scalar (primitives that don't need special serialization)
+      sig { params(type_object: T.untyped).returns(T::Boolean) }
+      def scalar_type?(type_object)
+        case type_object
+        when T::Types::Simple
+          scalar_classes = [String, Integer, Float, Numeric, TrueClass, FalseClass]
+          scalar_classes.any? { |klass| type_object.raw_type == klass || type_object.raw_type <= klass }
+        when T::Types::Union
+          # Union is scalar if all its types are scalars
+          type_object.types.all? { |t| scalar_type?(t) }
+        else
+          false
+        end
+      end
+
+      # Checks if a type is structured (arrays, hashes, structs that need type preservation)
+      sig { params(type_object: T.untyped).returns(T::Boolean) }
+      def structured_type?(type_object)
+        return true if type_object.is_a?(T::Types::TypedArray)
+        return true if type_object.is_a?(T::Types::TypedHash)
+
+        if type_object.is_a?(T::Types::Simple)
+          raw_type = type_object.raw_type
+          return true if raw_type.respond_to?(:<=) && raw_type <= T::Struct
+        end
+
+        # For union types (like T.nilable(T::Array[...])), check if any non-nil type is structured
+        if type_object.is_a?(T::Types::Union)
+          non_nil_types = type_object.types.reject { |t| t.is_a?(T::Types::Simple) && t.raw_type == NilClass }
+          return non_nil_types.any? { |t| structured_type?(t) }
+        end
+
+        false
+      end
+
+      # Checks if a type is String or compatible with String (e.g., T.any(String, ...) or T.nilable(String))
+      sig { params(type_object: T.untyped).returns(T::Boolean) }
+      def string_type?(type_object)
+        case type_object
+        when T::Types::Simple
+          type_object.raw_type == String
+        when T::Types::Union
+          # Check if any of the union types is String
+          type_object.types.any? { |t| t.is_a?(T::Types::Simple) && t.raw_type == String }
+        else
+          false
+        end
+      end
+
+      # Get a readable type name from a Sorbet type object
+      sig { params(type_object: T.untyped).returns(String) }
+      def type_name(type_object)
+        case type_object
+        when T::Types::TypedArray
+          element_type = type_object.type
+          "T::Array[#{type_name(element_type)}]"
+        when T::Types::TypedHash
+          "T::Hash"
+        when T::Types::Simple
+          type_object.raw_type.to_s
+        when T::Types::Union
+          types_str = type_object.types.map { |t| type_name(t) }.join(', ')
+          "T.any(#{types_str})"
+        else
+          type_object.to_s
+        end
+      end
+
+      # Returns an appropriate default value for a given Sorbet type
+      # This is used when max iterations is reached without a successful completion
+      sig { params(type_object: T.untyped).returns(T.untyped) }
+      def default_value_for_type(type_object)
+        # Handle TypedArray (T::Array[...])
+        return [] if type_object.is_a?(T::Types::TypedArray)
+
+        # Handle TypedHash (T::Hash[...])
+        return {} if type_object.is_a?(T::Types::TypedHash)
+
+        # Handle simple types
+        case type_object
+        when T::Types::Simple
+          raw_type = type_object.raw_type
+          case raw_type.to_s
+          when 'String' then ''
+          when 'Integer' then 0
+          when 'Float' then 0.0
+          when 'TrueClass', 'FalseClass' then false
+          else
+            # For T::Struct types, return nil as fallback
+            nil
+          end
+        when T::Types::Union
+          # For unions, return nil (assuming it's nilable) or first non-nil default
+          nil
+        else
+          # Default fallback for unknown types
+          nil
+        end
+      end
+
       # Coerces an array value, converting each element as needed
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_array_value(value, prop_type)
@@ -152,7 +292,7 @@ module DSPy
         # Convert string keys to enum instances if key_type is an enum
         result = if enum_type?(key_type)
           enum_class = extract_enum_class(key_type)
-          value.transform_keys { |k| enum_class.deserialize(k.to_s) }
+          value.transform_keys { |k| DSPy::Mixins::TypeCoercion.deserialize_enum(enum_class, k) || k }
         else
           # For non-enum keys, coerce them to the expected type
           value.transform_keys { |k| coerce_value_to_type(k, key_type) }
@@ -197,7 +337,19 @@ module DSPy
             [key, val]
           end
         end.to_h
-        
+
+        # Strip nil values for non-nilable fields that have defaults.
+        # LLMs in advisory mode may return null for unused fields.
+        # Removing the key lets Sorbet use the field's default value.
+        coerced_hash.reject! do |key, val|
+          next false unless val.nil?
+          prop_info = struct_props[key]
+          next false unless prop_info
+          prop_type = prop_info[:type_object] || prop_info[:type]
+          has_default = prop_info.key?(:default) || prop_info[:fully_optional]
+          !is_nilable_type?(prop_type) && has_default
+        end
+
         # Create the struct instance
         struct_class.new(**coerced_hash)
       rescue ArgumentError => e
@@ -209,6 +361,17 @@ module DSPy
       # Coerces a union value by using _type discriminator
       sig { params(value: T.untyped, union_type: T.untyped).returns(T.untyped) }
       def coerce_union_value(value, union_type)
+        # Anthropic tool use may return complex oneOf union fields as JSON strings
+        # instead of nested objects. Parse them back into Hashes for coercion.
+        if value.is_a?(String)
+          begin
+            parsed = JSON.parse(value)
+            value = parsed if parsed.is_a?(Hash)
+          rescue JSON::ParserError
+            # Not JSON — fall through
+          end
+        end
+
         return value unless value.is_a?(Hash)
 
         # Check for _type discriminator field
@@ -311,14 +474,10 @@ module DSPy
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_enum_value(value, prop_type)
         enum_class = extract_enum_class(prop_type)
-        
-        # If value is already an instance of the enum class, return it as-is
-        return value if value.is_a?(enum_class)
-        
-        # Otherwise, try to deserialize from string
-        enum_class.deserialize(value.to_s)
-      rescue ArgumentError, KeyError => e
-        DSPy.logger.debug("Failed to coerce to enum #{enum_class}: #{e.message}")
+        result = DSPy::Mixins::TypeCoercion.deserialize_enum(enum_class, value)
+        return result if result
+
+        DSPy.logger.debug("Failed to coerce to enum #{enum_class}: no match for #{value.inspect}")
         value
       end
     end

data/lib/dspy/module.rb

@@ -3,6 +3,7 @@
 require 'sorbet-runtime'
 require 'dry-configurable'
 require 'securerandom'
+require 'weakref'
 require_relative 'context'
 require_relative 'callbacks'
 require_relative 'type_serializer'
@@ -24,15 +25,20 @@ module DSPy
 
     DEFAULT_MODULE_SUBSCRIPTION_SCOPE = SubcriptionScope::Descendants
 
+    # Hook to wrap forward methods with instrumentation.
+    # Uses a Set-based guard (not boolean) to prevent re-wrapping when
+    # other hooks (like Callbacks) also use define_method.
     module ForwardOverrideHooks
       def method_added(method_name)
         super
 
         return unless method_name == :forward
         return if self == DSPy::Module
-        return if @_wrapping_forward
 
-        @_wrapping_forward = true
+        # Use Set-based guard - persists across hook invocations
+        @_forward_instrumented ||= Set.new
+        return if @_forward_instrumented.include?(object_id)
+        @_forward_instrumented << object_id
 
         original = instance_method(:forward)
         define_method(:forward) do |*args, **kwargs, &block|
@@ -40,8 +46,6 @@ module DSPy
             original.bind(self).call(*args, **kwargs, &block)
           end
         end
-      ensure
-        @_wrapping_forward = false
       end
     end
 
@@ -71,6 +75,35 @@ module DSPy
 
       private
 
+      def build_subscription_callback(weakref, subscription_id_ref, spec)
+        scope = spec[:scope] || DEFAULT_MODULE_SUBSCRIPTION_SCOPE
+        handler = spec[:handler]
+        block = spec[:block]
+
+        ->(event_name, attributes) do
+          target = begin
+            weakref.__getobj__
+          rescue WeakRef::RefError
+            nil
+          end
+
+          unless target
+            subscription_id = subscription_id_ref[:id]
+            DSPy.events.unsubscribe(subscription_id) if subscription_id
+            DSPy.logger&.debug(event: 'module.subscription.auto_unsubscribe', subscription_id: subscription_id)
+            return
+          end
+
+          return unless target.send(:module_event_within_scope?, attributes, scope)
+
+          if handler
+            target.send(handler, event_name, attributes)
+          else
+            target.instance_exec(event_name, attributes, &block)
+          end
+        end
+      end
+
       def validate_subscription_scope!(scope)
         T.must(scope)
       end
@@ -97,7 +130,8 @@ module DSPy
     create_after_callback :forward
     create_around_callback :forward
 
-    # The main forward method that users will call is generic and type parameterized
+    # The main forward method that users will call is generic and type parameterized.
+    # Instrument here only when subclasses don't override forward.
     sig do
       type_parameters(:I, :O)
         .params(
@@ -106,10 +140,14 @@ module DSPy
         .returns(T.type_parameter(:O))
     end
     def forward(**input_values)
-      instrument_forward_call([], input_values) do
-        result = forward_untyped(**input_values)
-        T.cast(result, T.type_parameter(:O))
+      result = if self.class.instance_method(:forward).owner == DSPy::Module
+        instrument_forward_call([], input_values) do
+          forward_untyped(**input_values)
+        end
+      else
+        forward_untyped(**input_values)
       end
+      T.cast(result, T.type_parameter(:O))
     end
 
     # The implementation method that subclasses must override
@@ -294,8 +332,28 @@ module DSPy
       @module_subscriptions_registered = false
     end
 
+    sig { returns(T.self_type) }
+    def dup_for_thread
+      cloned = dup
+      cloned.instance_variable_set(:@module_subscription_ids, [])
+      cloned.instance_variable_set(:@module_subscriptions_registered, false)
+      cloned.instance_variable_set(:@module_scope_id, SecureRandom.uuid)
+      cloned.send(:reset_thread_state)
+      cloned
+    end
+
     private
 
+    def reset_thread_state
+      instance_variables.each do |ivar|
+        value = instance_variable_get(ivar)
+        case value
+        when Array, Hash, Set
+          instance_variable_set(ivar, value.dup)
+        end
+      end
+    end
+
     # Propagate LM configuration to child predictors recursively
     # Skips children that already have an explicit LM configured
     sig { params(lm: T.untyped).void }
@@ -322,30 +380,17 @@ module DSPy
 
       @module_subscription_ids ||= []
       specs.each do |spec|
-        callback = build_subscription_callback(spec)
+        weakref = WeakRef.new(self)
+        subscription_id_ref = { id: nil }
+        callback = self.class.send(:build_subscription_callback, weakref, subscription_id_ref, spec)
         subscription_id = DSPy.events.subscribe(spec[:pattern], &callback)
+        subscription_id_ref[:id] = subscription_id
         @module_subscription_ids << subscription_id
       end
 
       @module_subscriptions_registered = true
     end
 
-    def build_subscription_callback(spec)
-      scope = spec[:scope] || DEFAULT_MODULE_SUBSCRIPTION_SCOPE
-      handler = spec[:handler]
-      block = spec[:block]
-
-      proc do |event_name, attributes|
-        next unless module_event_within_scope?(attributes, scope)
-
-        if handler
-          send(handler, event_name, attributes)
-        else
-          instance_exec(event_name, attributes, &block)
-        end
-      end
-    end
-
     def module_event_within_scope?(attributes, scope)
       metadata = extract_module_metadata(attributes)
       return false unless metadata

data/lib/dspy/predict.rb

@@ -64,8 +64,7 @@ module DSPy
       super()
       @signature_class = signature_class
 
-      # Prompt will read schema_format from config automatically
-      @prompt = Prompt.from_signature(signature_class)
+      @prompt = build_prompt_from_signature
       @demos = nil
     end
 
@@ -146,6 +145,13 @@ module DSPy
       instance
     end
 
+    sig { override.params(block: T.proc.params(config: T.untyped).void).returns(T.self_type) }
+    def configure(&block)
+      super(&block)
+      sync_prompt_formats_from_lm(config.lm) if config.lm
+      self
+    end
+
     sig { override.returns(T::Array[[String, DSPy::Module]]) }
     def named_predictors
       [["self", self]]
@@ -166,9 +172,6 @@ module DSPy
       input_props = @signature_class.input_struct_class.props
       coerced_input_values = coerce_output_attributes(input_values, input_props)
       
-      # Store coerced input values for optimization
-      @last_input_values = coerced_input_values.clone
-      
       # Validate input with coerced values
       validate_input_struct(coerced_input_values)
       
@@ -190,6 +193,30 @@ module DSPy
 
     private
 
+    def reset_thread_state
+      super
+    end
+
+    def build_prompt_from_signature
+      lm_source = lm
+      schema_format = lm_source&.schema_format
+      data_format = lm_source&.respond_to?(:data_format) ? lm_source.data_format : nil
+
+      Prompt.from_signature(@signature_class, schema_format: schema_format, data_format: data_format)
+    end
+
+    def sync_prompt_formats_from_lm(lm_source)
+      return unless lm_source
+
+      schema_format = lm_source&.schema_format
+      data_format = lm_source&.respond_to?(:data_format) ? lm_source.data_format : nil
+
+      prompt = @prompt
+      prompt = prompt.with_schema_format(schema_format) if schema_format
+      prompt = prompt.with_data_format(data_format) if data_format
+      @prompt = prompt
+    end
+
     # Validates input using signature struct (assumes input is already coerced)
     sig { params(input_values: T::Hash[Symbol, T.untyped]).void }
     def validate_input_struct(input_values)

data/lib/dspy/prediction.rb

@@ -122,9 +122,10 @@ module DSPy
               converted[key] = nil
             end
           elsif is_enum_type?(prop_type) && value.is_a?(String)
-            # Convert string to enum
+            # Convert string to enum (case-insensitive for structured_outputs: false)
             enum_class = extract_enum_class(prop_type)
-            converted[key] = enum_class.deserialize(value)
+            result = DSPy::Mixins::TypeCoercion.deserialize_enum(enum_class, value)
+            converted[key] = result || 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)
@@ -188,60 +189,12 @@ module DSPy
 
     sig { params(type: T.untyped).returns(T::Boolean) }
     def is_enum_type?(type)
-      return false if type.nil?
-      
-      case type
-      when T::Types::Simple
-        # Handle regular enum types
-        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
-      when T::Private::Types::SimplePairUnion, T::Types::Union
-        # Handle T.nilable enum types
-        # Find the non-nil type and check if it's an enum
-        non_nil_types = if type.respond_to?(:types)
-          type.types.reject { |t| t.respond_to?(:raw_type) && t.raw_type == NilClass }
-        else
-          []
-        end
-        
-        # For nilable types, we expect exactly one non-nil type
-        return false unless non_nil_types.size == 1
-        
-        non_nil_type = non_nil_types.first
-        return is_enum_type?(non_nil_type) # Recursively check
-      else
-        return false
-      end
+      DSPy::Mixins::TypeCoercion.enum_type?(type)
     end
 
     sig { params(type: T.untyped).returns(T.untyped) }
     def extract_enum_class(type)
-      case type
-      when T::Types::Simple
-        # Regular enum type
-        type.raw_type
-      when T::Private::Types::SimplePairUnion, T::Types::Union
-        # Nilable enum type - find the non-nil type
-        non_nil_types = if type.respond_to?(:types)
-          type.types.reject { |t| t.respond_to?(:raw_type) && t.raw_type == NilClass }
-        else
-          []
-        end
-        
-        if non_nil_types.size == 1
-          extract_enum_class(non_nil_types.first)
-        else
-          raise ArgumentError, "Unable to extract enum class from complex union type: #{type.inspect}"
-        end
-      else
-        raise ArgumentError, "Not an enum type: #{type.inspect}"
-      end
+      DSPy::Mixins::TypeCoercion.extract_enum_class(type)
     end
 
     sig { params(union_type: T::Types::Union, discriminator_type: T.untyped).returns(T::Hash[String, T.untyped]) }
@@ -387,8 +340,10 @@ module DSPy
           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)
+              # Convert string to enum (case-insensitive for structured_outputs: false)
+              enum_class = extract_enum_class(prop_type)
+              result = DSPy::Mixins::TypeCoercion.deserialize_enum(enum_class, v)
+              converted_hash[k] = result || 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)
@@ -488,8 +443,9 @@ module DSPy
             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)
+          # Convert string to enum (case-insensitive for structured_outputs: false)
+          enum_class = extract_enum_class(element_type)
+          DSPy::Mixins::TypeCoercion.deserialize_enum(enum_class, element) || element
         else
           element
         end
@@ -539,7 +495,9 @@ module DSPy
                 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)
+                    enum_class = extract_enum_class(prop_type)
+                    result = DSPy::Mixins::TypeCoercion.deserialize_enum(enum_class, v)
+                    converted_hash[k] = result || 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)