dspy 0.34.2 → 0.34.4

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
@@ -223,21 +261,64 @@ module DSPy
     def instrument_forward_call(call_args, call_kwargs)
       ensure_module_subscriptions!
 
+      input_json = serialize_module_input(call_args, call_kwargs)
+      root_call = DSPy::Context.current[:span_stack].empty?
+
       DSPy::Context.with_module(self) do
         observation_type = DSPy::ObservationType.for_module_class(self.class)
         span_attributes = observation_type.langfuse_attributes.merge(
-          'langfuse.observation.input' => serialize_module_input(call_args, call_kwargs),
+          'langfuse.observation.input' => input_json,
           'dspy.module' => self.class.name
         )
+        operation_name = "#{self.class.name}.forward"
+        span_attributes.merge!(root_trace_attributes(call_args, call_kwargs, input_json)) if root_call
+
+        if self.class.name == 'DSPy::Predict' && respond_to?(:signature_class)
+          signature_name = signature_class&.name
+          span_attributes['dspy.signature'] = signature_name || 'anonymous'
+          span_attributes['dspy.signature_kind'] = infer_signature_kind(signature_name)
+          span_attributes['dspy.predictor_label'] = module_scope_label if module_scope_label
+          operation_name = "DSPy::Predict(#{signature_name}).forward" if signature_name
+        end
 
         DSPy::Context.with_span(
-          operation: "#{self.class.name}.forward",
+          operation: operation_name,
           **span_attributes
         ) do |span|
-          yield.tap do |result|
-            if span && result
-              span.set_attribute('langfuse.observation.output', serialize_module_output(result))
+          begin
+            yield.tap do |result|
+              if span && !result.nil?
+                span.set_attribute('langfuse.observation.output', serialize_module_output(result))
+                span.set_attribute('langfuse.observation.status', 'completed')
+                span.set_attribute('dspy.status', 'completed')
+                if root_call
+                  span.set_attribute('langfuse.trace.output', serialize_module_output(result))
+                  span.set_attribute('langfuse.trace.status', 'completed')
+                end
+              end
+            end
+          rescue StandardError => e
+            if span
+              span.set_attribute('langfuse.observation.output', serialize_module_error_output(e))
+              span.set_attribute('langfuse.observation.status', 'error')
+              span.set_attribute('dspy.error.class', e.class.name)
+              span.set_attribute('dspy.error.message', e.message.to_s[0, 2000]) if e.message
+              span.set_attribute('dspy.status', 'error')
+              if root_call
+                span.set_attribute('langfuse.trace.output', serialize_module_error_output(e))
+                span.set_attribute('langfuse.trace.status', 'error')
+              end
+              if e.respond_to?(:iterations)
+                span.set_attribute('dspy.error.iterations', e.iterations.to_i) unless e.iterations.nil?
+              end
+              if e.respond_to?(:max_iterations)
+                span.set_attribute('dspy.error.max_iterations', e.max_iterations.to_i) unless e.max_iterations.nil?
+              end
+              if e.respond_to?(:tools_used)
+                span.set_attribute('dspy.error.tools_used', Array(e.tools_used).map(&:to_s))
+              end
             end
+            raise
           end
         end
       end
@@ -265,7 +346,91 @@ module DSPy
       result.to_s
     end
 
-    private :instrument_forward_call, :serialize_module_input, :serialize_module_output
+    def serialize_module_error_output(error)
+      payload = {
+        error: {
+          class: error.class.name,
+          message: error.message.to_s
+        }
+      }
+
+      if error.respond_to?(:iterations) || error.respond_to?(:max_iterations) || error.respond_to?(:tools_used)
+        payload[:react] = {}
+        payload[:react][:iterations] = error.iterations if error.respond_to?(:iterations)
+        payload[:react][:max_iterations] = error.max_iterations if error.respond_to?(:max_iterations)
+        payload[:react][:tools_used] = Array(error.tools_used) if error.respond_to?(:tools_used)
+      end
+
+      serialized = DSPy::TypeSerializer.serialize(payload)
+      JSON.generate(serialized)
+    rescue StandardError
+      "#{error.class}: #{error.message}"
+    end
+
+    def root_trace_attributes(call_args, call_kwargs, input_json)
+      metadata = {
+        module: self.class.name,
+        signature: (respond_to?(:signature_class) ? signature_class&.name : nil),
+        signature_kind: (respond_to?(:signature_class) ? infer_signature_kind(signature_class&.name) : nil),
+        predictor_label: module_scope_label
+      }.compact
+      conversation_id, conversation_id_source = resolve_conversation_id(call_args, call_kwargs)
+      metadata[:conversation_id_source] = conversation_id_source if conversation_id_source
+
+      {
+        'langfuse.trace.name' => "#{self.class.name}.forward",
+        'langfuse.trace.input' => input_json,
+        'langfuse.trace.metadata' => JSON.generate(metadata),
+        'langfuse.trace.output' => '{"status":"in_progress"}',
+        'conversation_id' => conversation_id,
+        'dspy.conversation_id' => conversation_id
+      }
+    rescue StandardError
+      {}
+    end
+
+    # Conversation ID precedence is deterministic:
+    # 1. top-level kwargs[:conversation_id]
+    # 2. first positional hash arg[:conversation_id]
+    # 3. kwargs[:input_context][:conversation_id]
+    # 4. DSPy::Context.current[:conversation_id]
+    def resolve_conversation_id(call_args, call_kwargs)
+      direct = fetch_hash_value(call_kwargs, :conversation_id)
+      return [direct.to_s, 'kwargs.conversation_id'] if present_value?(direct)
+
+      first_arg = call_args.first if call_args.is_a?(Array) && call_args.first.is_a?(Hash)
+      arg_value = fetch_hash_value(first_arg, :conversation_id)
+      return [arg_value.to_s, 'args[0].conversation_id'] if present_value?(arg_value)
+
+      input_context = fetch_hash_value(call_kwargs, :input_context)
+      nested = fetch_hash_value(input_context, :conversation_id)
+      return [nested.to_s, 'kwargs.input_context.conversation_id'] if present_value?(nested)
+
+      context_value = fetch_hash_value(DSPy::Context.current, :conversation_id)
+      return [context_value.to_s, 'context.conversation_id'] if present_value?(context_value)
+
+      [nil, nil]
+    end
+
+    def fetch_hash_value(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      hash[key] || hash[key.to_s]
+    end
+
+    def present_value?(value)
+      !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def infer_signature_kind(signature_name)
+      return 'custom' unless signature_name
+      return 'thought' if signature_name.match?(/thought/i)
+      return 'observation' if signature_name.match?(/observation/i)
+
+      'custom'
+    end
+
+    private :instrument_forward_call, :serialize_module_input, :serialize_module_output, :serialize_module_error_output, :root_trace_attributes, :resolve_conversation_id, :fetch_hash_value, :present_value?, :infer_signature_kind
 
     sig { returns(String) }
     def module_scope_id
@@ -294,8 +459,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 +507,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)
@@ -277,7 +304,7 @@ module DSPy
         next unless prop_type
 
         # For nilable fields with nil values, ensure proper handling
-        if value.nil? && is_nilable_type?(prop_type)
+        if value.nil? && nilable_type?(prop_type)
           # For nilable fields, nil is valid - keep it as is
           next
         elsif value.nil? && prop_info[:fully_optional]

data/lib/dspy/prediction.rb

@@ -1,6 +1,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+require_relative 'utils/serialization'
+
 module DSPy
   class Prediction
     extend T::Sig
@@ -54,7 +56,14 @@ module DSPy
 
     sig { returns(T::Hash[Symbol, T.untyped]) }
     def to_h
-      @_struct.serialize
+      hash = DSPy::Utils::Serialization.deep_serialize(@_struct.serialize)
+      hash.delete('_prediction_marker')
+      hash
+    end
+
+    sig { params(args: T.untyped).returns(String) }
+    def to_json(*args)
+      to_h.to_json(*args)
     end
 
     private
@@ -122,9 +131,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 +198,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 +349,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 +452,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 +504,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)