dspy 0.34.2 → 0.34.4

data/lib/dspy/lm/usage.rb

@@ -45,11 +45,34 @@ module DSPy
       end
     end
     
+    # Anthropic-specific usage information with cache token fields
+    class AnthropicUsage < T::Struct
+      extend T::Sig
+
+      const :input_tokens, Integer
+      const :output_tokens, Integer
+      const :total_tokens, Integer
+      const :cache_creation_input_tokens, T.nilable(Integer), default: nil
+      const :cache_read_input_tokens, T.nilable(Integer), default: nil
+
+      sig { returns(Hash) }
+      def to_h
+        base = {
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          total_tokens: total_tokens
+        }
+        base[:cache_creation_input_tokens] = cache_creation_input_tokens unless cache_creation_input_tokens.nil?
+        base[:cache_read_input_tokens] = cache_read_input_tokens unless cache_read_input_tokens.nil?
+        base
+      end
+    end
+
     # Factory for creating appropriate usage objects
     module UsageFactory
       extend T::Sig
       
-      sig { params(provider: String, usage_data: T.untyped).returns(T.nilable(T.any(Usage, OpenAIUsage))) }
+      sig { params(provider: String, usage_data: T.untyped).returns(T.nilable(T.any(Usage, OpenAIUsage, AnthropicUsage))) }
       def self.create(provider, usage_data)
         return nil if usage_data.nil?
         
@@ -99,7 +122,7 @@ module DSPy
           prompt_tokens_details: prompt_details,
           completion_tokens_details: completion_details
         )
-      rescue => e
+      rescue StandardError => e
         DSPy.logger.debug("Failed to create OpenAI usage: #{e.message}")
         nil
       end
@@ -121,19 +144,21 @@ module DSPy
         nil
       end
       
-      sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.nilable(Usage)) }
+      sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.nilable(AnthropicUsage)) }
       def self.create_anthropic_usage(data)
         # Anthropic uses input_tokens/output_tokens
         input_tokens = data[:input_tokens] || 0
         output_tokens = data[:output_tokens] || 0
         total_tokens = data[:total_tokens] || (input_tokens + output_tokens)
-        
-        Usage.new(
+
+        AnthropicUsage.new(
           input_tokens: input_tokens,
           output_tokens: output_tokens,
-          total_tokens: total_tokens
+          total_tokens: total_tokens,
+          cache_creation_input_tokens: data[:cache_creation_input_tokens],
+          cache_read_input_tokens: data[:cache_read_input_tokens]
         )
-      rescue => e
+      rescue StandardError => e
         DSPy.logger.debug("Failed to create Anthropic usage: #{e.message}")
         nil
       end
@@ -150,7 +175,7 @@ module DSPy
           output_tokens: output_tokens,
           total_tokens: total_tokens
         )
-      rescue => e
+      rescue StandardError => e
         DSPy.logger.debug("Failed to create Gemini usage: #{e.message}")
         nil
       end
@@ -167,10 +192,10 @@ module DSPy
           output_tokens: output_tokens,
           total_tokens: total_tokens
         )
-      rescue => e
+      rescue StandardError => e
         DSPy.logger.debug("Failed to create generic usage: #{e.message}")
         nil
       end
     end
   end
-end
+end

data/lib/dspy/lm.rb

@@ -146,7 +146,7 @@ module DSPy
 
       # Determine if structured outputs will be used and wrap prompt if so
       base_prompt = inference_module.prompt
-      prompt = if will_use_structured_outputs?(inference_module.signature_class)
+      prompt = if will_use_structured_outputs?(inference_module.signature_class, data_format: base_prompt.data_format)
         StructuredOutputsPrompt.new(**base_prompt.to_h)
       else
         base_prompt
@@ -171,8 +171,9 @@ module DSPy
       messages
     end
 
-    def will_use_structured_outputs?(signature_class)
+    def will_use_structured_outputs?(signature_class, data_format: nil)
       return false unless signature_class
+      return false if data_format == :toon
 
       adapter_class_name = adapter.class.name
 
@@ -304,6 +305,12 @@ module DSPy
             span.set_attribute('gen_ai.usage.prompt_tokens', usage.input_tokens) if usage.input_tokens
             span.set_attribute('gen_ai.usage.completion_tokens', usage.output_tokens) if usage.output_tokens
             span.set_attribute('gen_ai.usage.total_tokens', usage.total_tokens) if usage.total_tokens
+            if usage.respond_to?(:cache_creation_input_tokens) && !usage.cache_creation_input_tokens.nil?
+              span.set_attribute('gen_ai.usage.cache_creation_input_tokens', usage.cache_creation_input_tokens)
+            end
+            if usage.respond_to?(:cache_read_input_tokens) && !usage.cache_read_input_tokens.nil?
+              span.set_attribute('gen_ai.usage.cache_read_input_tokens', usage.cache_read_input_tokens)
+            end
           end
         end
 
@@ -327,8 +334,9 @@ module DSPy
         })
         
         # Add timing and request correlation if available
-        request_id = Thread.current[:dspy_request_id]
-        start_time = Thread.current[:dspy_request_start_time]
+        context = DSPy::Context.current
+        request_id = context[:request_id]
+        start_time = context[:request_start_time]
         
         if request_id
           event_attributes['request_id'] = request_id
@@ -354,11 +362,16 @@ module DSPy
       
       # Handle Usage struct objects
       if response.usage.respond_to?(:input_tokens)
-        return {
+        result = {
           input_tokens: response.usage.input_tokens,
           output_tokens: response.usage.output_tokens,
           total_tokens: response.usage.total_tokens
-        }.compact
+        }
+        if response.usage.respond_to?(:cache_creation_input_tokens)
+          result[:cache_creation_input_tokens] = response.usage.cache_creation_input_tokens
+          result[:cache_read_input_tokens] = response.usage.cache_read_input_tokens
+        end
+        return result.compact
       end
       
       # Handle hash-based usage (for VCR compatibility)
@@ -384,63 +397,21 @@ module DSPy
       end
     end
 
-    public
-
-    def validate_messages!(messages)
-      unless messages.is_a?(Array)
-        raise ArgumentError, "messages must be an array"
-      end
-      
-      messages.each_with_index do |message, index|
-        # Accept both Message objects and hash format for backward compatibility
-        if message.is_a?(Message)
-          # Already validated by type system
-          next
-        elsif message.is_a?(Hash) || message.respond_to?(:to_h)
-          data = message.is_a?(Hash) ? message : message.to_h
-          unless data.is_a?(Hash)
-            raise ArgumentError, "Message at index #{index} must be a Message object or hash with :role and :content"
-          end
-
-          normalized = data.transform_keys(&:to_sym)
-          unless normalized.key?(:role) && normalized.key?(:content)
-            raise ArgumentError, "Message at index #{index} must have :role and :content"
-          end
-
-          role = normalized[:role].to_s
-          valid_roles = %w[system user assistant]
-          unless valid_roles.include?(role)
-            raise ArgumentError, "Invalid role at index #{index}: #{normalized[:role]}. Must be one of: #{valid_roles.join(', ')}"
-          end
-        else
-          raise ArgumentError, "Message at index #{index} must be a Message object or hash with :role and :content"
-        end
-      end
-    end
-
     def execute_raw_chat(messages, &streaming_block)
       # Generate unique request ID for tracking
       request_id = SecureRandom.hex(8)
       start_time = Time.now
-      
-      # Store request context for correlation
-      Thread.current[:dspy_request_id] = request_id
-      Thread.current[:dspy_request_start_time] = start_time
-      
-      begin
+
+      DSPy::Context.with_request(request_id, start_time) do
         response = instrument_lm_request(messages, 'RawPrompt') do
           # Convert messages to hash format for adapter
           hash_messages = messages_to_hash_array(messages)
           # Direct adapter call, no strategies or JSON parsing
           adapter.chat(messages: hash_messages, signature: nil, &streaming_block)
         end
-        
+
         # Return raw response content, not parsed JSON
         response.content
-      ensure
-        # Clean up thread-local storage
-        Thread.current[:dspy_request_id] = nil
-        Thread.current[:dspy_request_start_time] = nil
       end
     end
     

data/lib/dspy/mixins/type_coercion.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require 'sorbet-runtime'
+require 'yaml'
 
 module DSPy
   module Mixins
@@ -9,6 +10,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
@@ -32,6 +89,15 @@ module DSPy
         case prop_type
         when ->(type) { union_type?(type) }
           coerce_union_value(value, prop_type)
+        when ->(type) { nilable_type?(type) }
+          # Unwrap T.nilable(X) to coerce as X (nil already handled above)
+          non_nil_types = prop_type.types.reject { |t| t == T::Utils.coerce(NilClass) }
+          if non_nil_types.size == 1
+            coerce_value_to_type(value, non_nil_types.first)
+          else
+            # T.any(A, B, NilClass) — rebuild as T.any(A, B) and coerce as union
+            coerce_union_value(value, T::Types::Union.new(non_nil_types))
+          end
         when ->(type) { array_type?(type) }
           coerce_array_value(value, prop_type)
         when ->(type) { hash_type?(type) }
@@ -57,32 +123,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)
@@ -121,15 +171,131 @@ module DSPy
       # Checks if a type is a union type (T.any)
       sig { params(type: T.untyped).returns(T::Boolean) }
       def union_type?(type)
-        type.is_a?(T::Types::Union) && !is_nilable_type?(type)
+        type.is_a?(T::Types::Union) && !nilable_type?(type)
       end
 
       # Checks if a type is nilable (contains NilClass)
       sig { params(type: T.untyped).returns(T::Boolean) }
-      def is_nilable_type?(type)
+      def nilable_type?(type)
         type.is_a?(T::Types::Union) && type.types.any? { |t| t == T::Utils.coerce(NilClass) }
       end
 
+      # Checks if a union type is a simple nilable struct (T.nilable(SomeStruct))
+      # Returns true only if the union has exactly 2 types: NilClass and a Struct
+      sig { params(union_type: T.untyped).returns(T::Boolean) }
+      def nilable_struct_union?(union_type)
+        return false unless union_type.is_a?(T::Types::Union)
+
+        types = union_type.types
+        return false unless types.size == 2
+
+        # One type must be NilClass, the other must be a struct
+        has_nil = types.any? { |t| t == T::Utils.coerce(NilClass) }
+        struct_type = types.find { |t| t != T::Utils.coerce(NilClass) && struct_type?(t) }
+
+        has_nil && !struct_type.nil?
+      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)
@@ -143,16 +309,18 @@ module DSPy
       # Coerces a hash value, converting keys and values as needed
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_hash_value(value, prop_type)
-        return value unless value.is_a?(Hash)
         return value unless prop_type.is_a?(T::Types::TypedHash)
-        
+
+        value = try_parse_string_to_hash(value)
+        return value unless value.is_a?(Hash)
+
         key_type = prop_type.keys
         value_type = prop_type.values
         
         # 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) }
@@ -162,9 +330,41 @@ module DSPy
         result.transform_values { |v| coerce_value_to_type(v, value_type) }
       end
 
+      # Attempts to parse a string into a Hash.
+      # Returns the parsed Hash on success, or the original value otherwise.
+      sig { params(value: T.untyped).returns(T.untyped) }
+      def try_parse_string_to_hash(value)
+        return value unless value.is_a?(String)
+
+        parsed = begin
+          JSON.parse(value)
+        rescue JSON::ParserError
+          YAML.safe_load(value, permitted_classes: [Symbol, Date, Time])
+        end
+
+        parsed.is_a?(Hash) ? parsed : value
+      rescue Psych::SyntaxError
+        value
+      end
+
+      # Attempts to parse a JSON string into a Hash.
+      # Returns the parsed Hash on success, or the original value otherwise.
+      sig { params(value: T.untyped).returns(T.untyped) }
+      def try_parse_json_to_hash(value)
+        return value unless value.is_a?(String)
+
+        parsed = JSON.parse(value)
+        parsed.is_a?(Hash) ? parsed : value
+      rescue JSON::ParserError
+        value
+      end
+
       # Coerces a struct value from a hash
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_struct_value(value, prop_type)
+        # Anthropic tool use may return struct fields as JSON strings
+        value = try_parse_json_to_hash(value)
+
         return value unless value.is_a?(Hash)
 
         struct_class = if prop_type.is_a?(Class)
@@ -197,7 +397,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]
+          !nilable_type?(prop_type) && has_default
+        end
+
         # Create the struct instance
         struct_class.new(**coerced_hash)
       rescue ArgumentError => e
@@ -209,9 +421,22 @@ 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.
+        value = try_parse_json_to_hash(value)
+
         return value unless value.is_a?(Hash)
 
-        # Check for _type discriminator field
+        # Handle nilable struct unions (T.nilable(SomeStruct)) without _type discriminator
+        # LLMs don't provide _type for simple nilable structs, so we can directly coerce
+        if nilable_struct_union?(union_type)
+          struct_type = union_type.types.find { |t|
+            t != T::Utils.coerce(NilClass) && struct_type?(t)
+          }
+          return coerce_struct_value(value, struct_type) if struct_type
+        end
+
+        # Check for _type discriminator field (required for true multi-type unions)
         type_name = value[:_type] || value["_type"]
         return value unless type_name
 
@@ -311,14 +536,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