dspy 0.15.2 → 0.15.3

data/lib/dspy/lm/message.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  class LM
+    # Type-safe representation of chat messages
+    class Message < T::Struct
+      extend T::Sig
+      
+      # Role enum for type safety
+      class Role < T::Enum
+        enums do
+          System = new('system')
+          User = new('user')
+          Assistant = new('assistant')
+        end
+      end
+      
+      const :role, Role
+      const :content, String
+      const :name, T.nilable(String), default: nil
+      
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        base = {
+          role: role.serialize,
+          content: content
+        }
+        base[:name] = name if name
+        base
+      end
+      
+      sig { returns(String) }
+      def to_s
+        name ? "#{role.serialize}(#{name}): #{content}" : "#{role.serialize}: #{content}"
+      end
+    end
+    
+    # Factory for creating Message objects from various formats
+    module MessageFactory
+      extend T::Sig
+      
+      sig { params(message_data: T.untyped).returns(T.nilable(Message)) }
+      def self.create(message_data)
+        return nil if message_data.nil?
+        
+        # Already a Message? Return as-is
+        return message_data if message_data.is_a?(Message)
+        
+        # Convert to hash if needed
+        if message_data.respond_to?(:to_h)
+          message_data = message_data.to_h
+        end
+        
+        return nil unless message_data.is_a?(Hash)
+        
+        # Normalize keys to symbols
+        normalized = message_data.transform_keys(&:to_sym)
+        
+        create_from_hash(normalized)
+      end
+      
+      sig { params(messages: T::Array[T.untyped]).returns(T::Array[Message]) }
+      def self.create_many(messages)
+        messages.compact.map { |m| create(m) }.compact
+      end
+      
+      private
+      
+      sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.nilable(Message)) }
+      def self.create_from_hash(data)
+        role_str = data[:role]&.to_s
+        content = data[:content]&.to_s
+        
+        return nil if role_str.nil? || content.nil?
+        
+        # Convert string role to enum
+        role = case role_str
+               when 'system' then Message::Role::System
+               when 'user' then Message::Role::User
+               when 'assistant' then Message::Role::Assistant
+               else
+                 DSPy.logger.debug("Unknown message role: #{role_str}")
+                 return nil
+               end
+        
+        Message.new(
+          role: role,
+          content: content,
+          name: data[:name]&.to_s
+        )
+      rescue => e
+        DSPy.logger.debug("Failed to create Message: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/dspy/lm/message_builder.rb

@@ -1,28 +1,51 @@
 # frozen_string_literal: true
 
+require_relative 'message'
+
 module DSPy
   class LM
     class MessageBuilder
+      extend T::Sig
+      
+      sig { returns(T::Array[Message]) }
       attr_reader :messages
 
       def initialize
         @messages = []
       end
 
+      sig { params(content: T.any(String, T.untyped)).returns(MessageBuilder) }
       def system(content)
-        @messages << { role: 'system', content: content.to_s }
+        @messages << Message.new(
+          role: Message::Role::System,
+          content: content.to_s
+        )
         self
       end
 
+      sig { params(content: T.any(String, T.untyped)).returns(MessageBuilder) }
       def user(content)
-        @messages << { role: 'user', content: content.to_s }
+        @messages << Message.new(
+          role: Message::Role::User,
+          content: content.to_s
+        )
         self
       end
 
+      sig { params(content: T.any(String, T.untyped)).returns(MessageBuilder) }
       def assistant(content)
-        @messages << { role: 'assistant', content: content.to_s }
+        @messages << Message.new(
+          role: Message::Role::Assistant,
+          content: content.to_s
+        )
         self
       end
+      
+      # For backward compatibility, allow conversion to hash array
+      sig { returns(T::Array[T::Hash[Symbol, T.untyped]]) }
+      def to_h
+        @messages.map(&:to_h)
+      end
     end
   end
 end

data/lib/dspy/lm/response.rb

@@ -1,29 +1,158 @@
 # frozen_string_literal: true
 
+require 'sorbet-runtime'
 require_relative 'usage'
 
 module DSPy
   class LM
-    # Normalized response format for all LM providers
-    class Response
-      attr_reader :content, :usage, :metadata
-
-      def initialize(content:, usage: nil, metadata: {})
-        @content = content
-        @usage = usage
-        @metadata = metadata
+    # Base metadata struct for common fields across providers
+    class ResponseMetadata < T::Struct
+      extend T::Sig
+      
+      const :provider, String
+      const :model, String
+      const :response_id, T.nilable(String), default: nil
+      const :created, T.nilable(Integer), default: nil
+      const :structured_output, T.nilable(T::Boolean), default: nil
+      
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        hash = {
+          provider: provider,
+          model: model
+        }
+        hash[:response_id] = response_id if response_id
+        hash[:created] = created if created
+        hash[:structured_output] = structured_output unless structured_output.nil?
+        hash
       end
-
+    end
+    
+    # OpenAI-specific metadata with additional fields
+    class OpenAIResponseMetadata < T::Struct
+      extend T::Sig
+      
+      const :provider, String
+      const :model, String
+      const :response_id, T.nilable(String), default: nil
+      const :created, T.nilable(Integer), default: nil
+      const :structured_output, T.nilable(T::Boolean), default: nil
+      const :system_fingerprint, T.nilable(String), default: nil
+      const :finish_reason, T.nilable(String), default: nil
+      
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        hash = {
+          provider: provider,
+          model: model
+        }
+        hash[:response_id] = response_id if response_id
+        hash[:created] = created if created
+        hash[:structured_output] = structured_output unless structured_output.nil?
+        hash[:system_fingerprint] = system_fingerprint if system_fingerprint
+        hash[:finish_reason] = finish_reason if finish_reason
+        hash
+      end
+    end
+    
+    # Anthropic-specific metadata with additional fields
+    class AnthropicResponseMetadata < T::Struct
+      extend T::Sig
+      
+      const :provider, String
+      const :model, String
+      const :response_id, T.nilable(String), default: nil
+      const :created, T.nilable(Integer), default: nil
+      const :structured_output, T.nilable(T::Boolean), default: nil
+      const :stop_reason, T.nilable(String), default: nil
+      const :stop_sequence, T.nilable(String), default: nil
+      const :tool_calls, T.nilable(T::Array[T::Hash[Symbol, T.untyped]]), default: nil
+      
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        hash = {
+          provider: provider,
+          model: model
+        }
+        hash[:response_id] = response_id if response_id
+        hash[:created] = created if created
+        hash[:structured_output] = structured_output unless structured_output.nil?
+        hash[:stop_reason] = stop_reason if stop_reason
+        hash[:stop_sequence] = stop_sequence if stop_sequence
+        hash[:tool_calls] = tool_calls if tool_calls
+        hash
+      end
+    end
+    
+    # Normalized response format for all LM providers
+    class Response < T::Struct
+      extend T::Sig
+      
+      const :content, String
+      const :usage, T.nilable(T.any(Usage, OpenAIUsage)), default: nil
+      const :metadata, T.any(ResponseMetadata, OpenAIResponseMetadata, AnthropicResponseMetadata, T::Hash[Symbol, T.untyped])
+      
+      sig { returns(String) }
       def to_s
         content
       end
-
+      
+      sig { returns(T::Hash[Symbol, T.untyped]) }
       def to_h
-        {
-          content: content,
-          usage: usage,
-          metadata: metadata
+        hash = {
+          content: content
+        }
+        hash[:usage] = usage.to_h if usage
+        hash[:metadata] = metadata.is_a?(Hash) ? metadata : metadata.to_h
+        hash
+      end
+    end
+    
+    # Factory for creating response metadata objects
+    module ResponseMetadataFactory
+      extend T::Sig
+      
+      sig { params(provider: String, metadata: T.nilable(T::Hash[Symbol, T.untyped])).returns(T.any(ResponseMetadata, OpenAIResponseMetadata, AnthropicResponseMetadata)) }
+      def self.create(provider, metadata)
+        # Handle nil metadata
+        metadata ||= {}
+        
+        # Normalize provider name
+        provider_name = provider.to_s.downcase
+        
+        # Extract common fields
+        common_fields = {
+          provider: provider,
+          model: metadata[:model] || 'unknown',
+          response_id: metadata[:response_id] || metadata[:id],
+          created: metadata[:created],
+          structured_output: metadata[:structured_output]
         }
+        
+        case provider_name
+        when 'openai'
+          OpenAIResponseMetadata.new(
+            **common_fields,
+            system_fingerprint: metadata[:system_fingerprint],
+            finish_reason: metadata[:finish_reason]&.to_s
+          )
+        when 'anthropic'
+          AnthropicResponseMetadata.new(
+            **common_fields,
+            stop_reason: metadata[:stop_reason]&.to_s,
+            stop_sequence: metadata[:stop_sequence]&.to_s,
+            tool_calls: metadata[:tool_calls]
+          )
+        else
+          ResponseMetadata.new(**common_fields)
+        end
+      rescue => e
+        DSPy.logger.debug("Failed to create response metadata: #{e.message}")
+        # Fallback to basic metadata
+        ResponseMetadata.new(
+          provider: provider,
+          model: metadata[:model] || 'unknown'
+        )
       end
     end
   end

data/lib/dspy/lm/strategies/anthropic_tool_use_strategy.rb

@@ -50,8 +50,8 @@ module DSPy
           # Extract JSON from tool use response
           begin
             # Check for tool calls in metadata first (this is the primary method)
-            if response.metadata && response.metadata[:tool_calls]
-              tool_calls = response.metadata[:tool_calls]
+            if response.metadata.respond_to?(:tool_calls) && response.metadata.tool_calls
+              tool_calls = response.metadata.tool_calls
               if tool_calls.is_a?(Array) && !tool_calls.empty?
                 first_call = tool_calls.first
                 if first_call[:name] == "json_output" && first_call[:input]

data/lib/dspy/lm.rb

@@ -19,7 +19,8 @@ require_relative 'lm/adapters/ollama_adapter'
 require_relative 'lm/strategy_selector'
 require_relative 'lm/retry_handler'
 
-# Load message builder
+# Load message builder and message types
+require_relative 'lm/message'
 require_relative 'lm/message_builder'
 
 module DSPy
@@ -78,8 +79,8 @@ module DSPy
         streaming_block = block
       end
       
-      # Validate messages format
-      validate_messages!(messages)
+      # Normalize and validate messages
+      messages = normalize_messages(messages)
       
       # Execute with instrumentation
       execute_raw_chat(messages, &streaming_block)
@@ -106,16 +107,19 @@ module DSPy
     end
 
     def execute_chat_with_strategy(messages, signature_class, strategy, &block)
+      # Convert messages to hash format for strategy and adapter
+      hash_messages = messages_to_hash_array(messages)
+      
       # Prepare request with strategy-specific modifications
       request_params = {}
-      strategy.prepare_request(messages.dup, request_params)
+      strategy.prepare_request(hash_messages.dup, request_params)
       
       # Make the request
       response = if request_params.any?
         # Pass additional parameters if strategy added them
-        adapter.chat(messages: messages, signature: signature_class, **request_params, &block)
+        adapter.chat(messages: hash_messages, signature: signature_class, **request_params, &block)
       else
-        adapter.chat(messages: messages, signature: signature_class, &block)
+        adapter.chat(messages: hash_messages, signature: signature_class, &block)
       end
       
       # Let strategy handle JSON extraction if needed
@@ -171,11 +175,19 @@ module DSPy
       
       # Add system message
       system_prompt = inference_module.system_signature
-      messages << { role: 'system', content: system_prompt } if system_prompt
+      if system_prompt
+        messages << Message.new(
+          role: Message::Role::System,
+          content: system_prompt
+        )
+      end
       
       # Add user message
       user_prompt = inference_module.user_signature(input_values)
-      messages << { role: 'user', content: user_prompt }
+      messages << Message.new(
+        role: Message::Role::User,
+        content: user_prompt
+      )
       
       messages
     end
@@ -205,7 +217,14 @@ module DSPy
 
     # Common instrumentation method for LM requests
     def instrument_lm_request(messages, signature_class_name, &execution_block)
-      input_text = messages.map { |m| m[:content] }.join(' ')
+      # Handle both Message objects and hash format
+      input_text = messages.map do |m|
+        if m.is_a?(Message)
+          m.content
+        else
+          m[:content]
+        end
+      end.join(' ')
       input_size = input_text.length
       
       response = nil
@@ -252,27 +271,84 @@ module DSPy
         raise ArgumentError, "messages must be an array"
       end
       
-      valid_roles = %w[system user assistant]
-      
-      messages.each do |message|
-        unless message.is_a?(Hash) && message.key?(:role) && message.key?(:content)
-          raise ArgumentError, "Each message must have :role and :content"
-        end
-        
-        unless valid_roles.include?(message[:role])
-          raise ArgumentError, "Invalid role: #{message[:role]}. Must be one of: #{valid_roles.join(', ')}"
+      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.key?(:role) && message.key?(:content)
+          # Legacy hash format - validate role
+          valid_roles = %w[system user assistant]
+          unless valid_roles.include?(message[:role])
+            raise ArgumentError, "Invalid role at index #{index}: #{message[: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)
       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: messages, signature: nil, &streaming_block)
+        adapter.chat(messages: hash_messages, signature: nil, &streaming_block)
       end
       
       # Return raw response content, not parsed JSON
       response.content
     end
+    
+    # Convert messages to normalized Message objects
+    def normalize_messages(messages)
+      # Validate array format first
+      unless messages.is_a?(Array)
+        raise ArgumentError, "messages must be an array"
+      end
+      
+      return messages if messages.all? { |m| m.is_a?(Message) }
+      
+      # Convert hash messages to Message objects
+      normalized = []
+      messages.each_with_index do |msg, index|
+        if msg.is_a?(Message)
+          normalized << msg
+        elsif msg.is_a?(Hash)
+          # Validate hash has required fields
+          unless msg.key?(:role) && msg.key?(:content)
+            raise ArgumentError, "Message at index #{index} must have :role and :content"
+          end
+          
+          # Validate role
+          valid_roles = %w[system user assistant]
+          unless valid_roles.include?(msg[:role])
+            raise ArgumentError, "Invalid role at index #{index}: #{msg[:role]}. Must be one of: #{valid_roles.join(', ')}"
+          end
+          
+          # Create Message object
+          message = MessageFactory.create(msg)
+          if message.nil?
+            raise ArgumentError, "Failed to create Message from hash at index #{index}"
+          end
+          normalized << message
+        else
+          raise ArgumentError, "Message at index #{index} must be a Message object or hash with :role and :content"
+        end
+      end
+      
+      normalized
+    end
+    
+    # Convert Message objects to hash array for adapters
+    def messages_to_hash_array(messages)
+      messages.map do |msg|
+        if msg.is_a?(Message)
+          msg.to_h
+        else
+          msg
+        end
+      end
+    end
   end
 end

data/lib/dspy/mixins/type_coercion.rb

@@ -30,6 +30,8 @@ module DSPy
         return value if value.nil?
 
         case prop_type
+        when ->(type) { union_type?(type) }
+          coerce_union_value(value, prop_type)
         when ->(type) { array_type?(type) }
           coerce_array_value(value, prop_type)
         when ->(type) { enum_type?(type) }
@@ -100,6 +102,18 @@ module DSPy
         false
       end
 
+      # 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)
+      end
+
+      # Checks if a type is nilable (contains NilClass)
+      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
+
       # 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)
@@ -133,6 +147,40 @@ module DSPy
         DSPy.logger.debug("Failed to coerce to struct #{struct_class}: #{e.message}")
         value
       end
+
+      # 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)
+        return value unless value.is_a?(Hash)
+        
+        # Check for _type discriminator field
+        type_name = value[:_type] || value["_type"]
+        return value unless type_name
+        
+        # Find matching struct type in the union
+        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_name = type.raw_type.name.split('::').last
+            if struct_name == type_name
+              # Convert string keys to symbols and remove _type
+              symbolized_hash = value.transform_keys(&:to_sym)
+              symbolized_hash.delete(:_type)
+              
+              # Create the struct instance
+              return type.raw_type.new(**symbolized_hash)
+            end
+          end
+        end
+        
+        # If no matching type found, return original value
+        value
+      rescue ArgumentError => e
+        # If struct creation fails, return the original value
+        DSPy.logger.debug("Failed to coerce union type: #{e.message}")
+        value
+      end
     end
   end
 end

data/lib/dspy/subscribers/otel_subscriber.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'sorbet-runtime'
+require_relative '../instrumentation/event_payloads'
 
 begin
   require 'opentelemetry/api'
@@ -402,10 +403,8 @@ module DSPy
             'dspy.lm.model' => payload[:gen_ai_request_model] || payload[:model],
             'dspy.lm.status' => payload[:status],
             'dspy.lm.duration_ms' => payload[:duration_ms],
-            'dspy.lm.tokens_total' => payload[:tokens_total],
-            'dspy.lm.tokens_input' => payload[:tokens_input],
-            'dspy.lm.tokens_output' => payload[:tokens_output],
-            'dspy.lm.cost' => payload[:cost]
+            'dspy.lm.adapter_class' => payload[:adapter_class],
+            'dspy.lm.input_size' => payload[:input_size]
           }
         ) do |span|
           if payload[:status] == 'error'

data/lib/dspy/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.15.2
+  version: 0.15.3
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-07-28 00:00:00.000000000 Z
+date: 2025-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -167,6 +166,8 @@ files:
 - lib/dspy/few_shot_example.rb
 - lib/dspy/field.rb
 - lib/dspy/instrumentation.rb
+- lib/dspy/instrumentation/event_payload_factory.rb
+- lib/dspy/instrumentation/event_payloads.rb
 - lib/dspy/instrumentation/token_tracker.rb
 - lib/dspy/lm.rb
 - lib/dspy/lm/adapter.rb
@@ -177,6 +178,7 @@ files:
 - lib/dspy/lm/adapters/openai_adapter.rb
 - lib/dspy/lm/cache_manager.rb
 - lib/dspy/lm/errors.rb
+- lib/dspy/lm/message.rb
 - lib/dspy/lm/message_builder.rb
 - lib/dspy/lm/response.rb
 - lib/dspy/lm/retry_handler.rb
@@ -232,7 +234,6 @@ homepage: https://github.com/vicentereig/dspy.rb
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -247,8 +248,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key: 
+rubygems_version: 3.6.5
 specification_version: 4
 summary: The Ruby framework for programming—rather than prompting—language models.
 test_files: []