dspy 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78e01258a3b9b5a1bccddad913a1d0aa45ecb145a65adb3e691986cadbea6e23
-  data.tar.gz: 9a778ea689150002e0766357dd4aa4af526be81979378b9996ba9067c2cdbd42
+  metadata.gz: e7897711c81ee7a4b72dd86a8fbeee9faf4cdf3e398b9878435e0da5750b0fc1
+  data.tar.gz: '079cfdea700a852a94d08415bbdbbe2ff4c4e7d61e4dfae5e739fb88dec29c79'
 SHA512:
-  metadata.gz: 7ba1376b844e5c5e61215b961142a70f82d758db41e061bf2e7404f4ffdbae867197b0c38254a92b25892beb51922fb3c3b963ab2474494c9d490b83814bba5d
-  data.tar.gz: 4a543e0b954469f316f003f36c5a55b97b0794ef1cbf395180ac5197acf5d4091bfe3ea87e342473c190d96adf5761baff59532502a20778edea23a83a9e5253
+  metadata.gz: b81f7fefb5727bbdbc5f94b6618ba7de9cbea26de78324d2ed5f29f6aa1722f5a4e0191d99e3a1393962f5fe224198e25fe3b73fe34b59e99bd486f08bab1189
+  data.tar.gz: 89515f64f64e681ae9cee83ffdad853b7e29409381351528324047b9a60627ed4721b79dd1943cee1ab3300996521aeb595e7a3ce57c90ad09cda47489acca77

data/lib/dspy/events/subscribers.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DSPy
+  module Events
+    # Base subscriber class for event-driven patterns
+    # This provides the foundation for creating custom event subscribers
+    # 
+    # Example usage:
+    #   class MySubscriber < DSPy::Events::BaseSubscriber
+    #     def subscribe
+    #       add_subscription('llm.*') do |event_name, attributes|
+    #         # Handle LLM events
+    #       end
+    #     end
+    #   end
+    #
+    #   subscriber = MySubscriber.new
+    #   # subscriber will start receiving events
+    #   subscriber.unsubscribe # Clean up when done
+    class BaseSubscriber
+      def initialize
+        @subscriptions = []
+      end
+      
+      def subscribe
+        raise NotImplementedError, "Subclasses must implement #subscribe"
+      end
+      
+      def unsubscribe
+        @subscriptions.each { |id| DSPy.events.unsubscribe(id) }
+        @subscriptions.clear
+      end
+      
+      protected
+      
+      def add_subscription(pattern, &block)
+        subscription_id = DSPy.events.subscribe(pattern, &block)
+        @subscriptions << subscription_id
+        subscription_id
+      end
+    end
+  end
+end

data/lib/dspy/events/types.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  module Events
+    # Base event structure using Sorbet T::Struct
+    class Event < T::Struct
+      const :name, String
+      const :timestamp, Time
+      const :attributes, T::Hash[T.any(String, Symbol), T.untyped], default: {}
+      
+      def initialize(name:, timestamp: Time.now, attributes: {})
+        super(name: name, timestamp: timestamp, attributes: attributes)
+      end
+      
+      def to_attributes
+        result = attributes.dup
+        result[:timestamp] = timestamp
+        result
+      end
+    end
+
+    # Token usage structure for LLM events
+    class TokenUsage < T::Struct
+      const :prompt_tokens, Integer
+      const :completion_tokens, Integer
+      
+      def total_tokens
+        prompt_tokens + completion_tokens
+      end
+    end
+
+    # LLM operation events with semantic conventions
+    class LLMEvent < T::Struct
+      VALID_PROVIDERS = T.let(
+        ['openai', 'anthropic', 'google', 'azure', 'ollama', 'together', 'groq', 'cohere'].freeze,
+        T::Array[String]
+      )
+      
+      # Common event fields
+      const :name, String
+      const :timestamp, Time
+      
+      # LLM-specific fields
+      const :provider, String
+      const :model, String
+      const :usage, T.nilable(TokenUsage), default: nil
+      const :duration_ms, T.nilable(Numeric), default: nil
+      const :temperature, T.nilable(Float), default: nil
+      const :max_tokens, T.nilable(Integer), default: nil
+      const :stream, T.nilable(T::Boolean), default: nil
+      
+      def initialize(name:, provider:, model:, timestamp: Time.now, usage: nil, duration_ms: nil, temperature: nil, max_tokens: nil, stream: nil)
+        unless VALID_PROVIDERS.include?(provider.downcase)
+          raise ArgumentError, "Invalid provider '#{provider}'. Must be one of: #{VALID_PROVIDERS.join(', ')}"
+        end
+        super(
+          name: name, 
+          timestamp: timestamp,
+          provider: provider.downcase, 
+          model: model,
+          usage: usage,
+          duration_ms: duration_ms,
+          temperature: temperature,
+          max_tokens: max_tokens,
+          stream: stream
+        )
+      end
+      
+      def to_otel_attributes
+        attrs = {
+          'gen_ai.system' => provider,
+          'gen_ai.request.model' => model
+        }
+        
+        if usage
+          attrs['gen_ai.usage.prompt_tokens'] = usage.prompt_tokens
+          attrs['gen_ai.usage.completion_tokens'] = usage.completion_tokens
+          attrs['gen_ai.usage.total_tokens'] = usage.total_tokens
+        end
+        
+        attrs['gen_ai.request.temperature'] = temperature if temperature
+        attrs['gen_ai.request.max_tokens'] = max_tokens if max_tokens
+        attrs['gen_ai.request.stream'] = stream if stream
+        attrs['duration_ms'] = duration_ms if duration_ms
+        
+        attrs
+      end
+      
+      def to_attributes
+        result = to_otel_attributes.dup
+        result[:timestamp] = timestamp
+        result[:provider] = provider
+        result[:model] = model
+        result[:duration_ms] = duration_ms if duration_ms
+        result
+      end
+    end
+
+    # DSPy module execution events
+    class ModuleEvent < T::Struct
+      # Common event fields
+      const :name, String
+      const :timestamp, Time
+      
+      # Module-specific fields
+      const :module_name, String
+      const :signature_name, T.nilable(String), default: nil
+      const :input_fields, T.nilable(T::Array[String]), default: nil
+      const :output_fields, T.nilable(T::Array[String]), default: nil
+      const :duration_ms, T.nilable(Numeric), default: nil
+      const :success, T.nilable(T::Boolean), default: nil
+      
+      def initialize(name:, module_name:, timestamp: Time.now, signature_name: nil, input_fields: nil, output_fields: nil, duration_ms: nil, success: nil)
+        super(
+          name: name,
+          timestamp: timestamp,
+          module_name: module_name,
+          signature_name: signature_name,
+          input_fields: input_fields,
+          output_fields: output_fields,
+          duration_ms: duration_ms,
+          success: success
+        )
+      end
+      
+      def to_attributes
+        result = { timestamp: timestamp }
+        result[:module_name] = module_name
+        result[:signature_name] = signature_name if signature_name
+        result[:input_fields] = input_fields if input_fields
+        result[:output_fields] = output_fields if output_fields
+        result[:duration_ms] = duration_ms if duration_ms
+        result[:success] = success if success
+        result
+      end
+    end
+
+    # Optimization and training events
+    class OptimizationEvent < T::Struct
+      # Common event fields
+      const :name, String
+      const :timestamp, Time
+      
+      # Optimization-specific fields
+      const :optimizer_name, String
+      const :trial_number, T.nilable(Integer), default: nil
+      const :score, T.nilable(Float), default: nil
+      const :best_score, T.nilable(Float), default: nil
+      const :parameters, T.nilable(T::Hash[T.any(String, Symbol), T.untyped]), default: nil
+      const :duration_ms, T.nilable(Numeric), default: nil
+      
+      def initialize(name:, optimizer_name:, timestamp: Time.now, trial_number: nil, score: nil, best_score: nil, parameters: nil, duration_ms: nil)
+        super(
+          name: name,
+          timestamp: timestamp,
+          optimizer_name: optimizer_name,
+          trial_number: trial_number,
+          score: score,
+          best_score: best_score,
+          parameters: parameters,
+          duration_ms: duration_ms
+        )
+      end
+      
+      def to_attributes
+        result = { timestamp: timestamp }
+        result[:optimizer_name] = optimizer_name
+        result[:trial_number] = trial_number if trial_number
+        result[:score] = score if score
+        result[:best_score] = best_score if best_score
+        result[:parameters] = parameters if parameters
+        result[:duration_ms] = duration_ms if duration_ms
+        result
+      end
+    end
+
+    # Evaluation events
+    class EvaluationEvent < T::Struct
+      # Common event fields
+      const :name, String
+      const :timestamp, Time
+      
+      # Evaluation-specific fields
+      const :evaluator_name, String
+      const :metric_name, T.nilable(String), default: nil
+      const :score, T.nilable(Float), default: nil
+      const :total_examples, T.nilable(Integer), default: nil
+      const :passed_examples, T.nilable(Integer), default: nil
+      const :duration_ms, T.nilable(Numeric), default: nil
+      
+      def initialize(name:, evaluator_name:, timestamp: Time.now, metric_name: nil, score: nil, total_examples: nil, passed_examples: nil, duration_ms: nil)
+        super(
+          name: name,
+          timestamp: timestamp,
+          evaluator_name: evaluator_name,
+          metric_name: metric_name,
+          score: score,
+          total_examples: total_examples,
+          passed_examples: passed_examples,
+          duration_ms: duration_ms
+        )
+      end
+      
+      def to_attributes
+        result = { timestamp: timestamp }
+        result[:evaluator_name] = evaluator_name
+        result[:metric_name] = metric_name if metric_name
+        result[:score] = score if score
+        result[:total_examples] = total_examples if total_examples
+        result[:passed_examples] = passed_examples if passed_examples
+        result[:duration_ms] = duration_ms if duration_ms
+        result
+      end
+    end
+  end
+end

data/lib/dspy/events.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module DSPy
+  # Events module to hold typed event structures
+  module Events
+    # Will be defined in events/types.rb
+  end
+  
+  class EventRegistry
+    def initialize
+      @listeners = {}
+      @subscription_counter = 0
+      @mutex = Mutex.new
+    end
+
+    def subscribe(pattern, &block)
+      return unless block_given?
+      
+      subscription_id = SecureRandom.uuid
+      @mutex.synchronize do
+        @listeners[subscription_id] = {
+          pattern: pattern,
+          block: block
+        }
+      end
+      
+      subscription_id
+    end
+
+    def unsubscribe(subscription_id)
+      @mutex.synchronize do
+        @listeners.delete(subscription_id)
+      end
+    end
+
+    def clear_listeners
+      @mutex.synchronize do
+        @listeners.clear
+      end
+    end
+
+    def notify(event_name, attributes)
+      # Take a snapshot of current listeners to avoid holding the mutex during execution
+      # This allows listeners to be modified while others are executing
+      matching_listeners = @mutex.synchronize do
+        @listeners.select do |id, listener|
+          pattern_matches?(listener[:pattern], event_name)
+        end.dup  # Create a copy to avoid shared state
+      end
+
+      matching_listeners.each do |id, listener|
+        begin
+          listener[:block].call(event_name, attributes)
+        rescue => e
+          # Log the error but continue processing other listeners
+          # Use emit_log directly to avoid infinite recursion
+          DSPy.send(:emit_log, 'event.listener.error', {
+            subscription_id: id,
+            error_class: e.class.name,
+            error_message: e.message,
+            event_name: event_name
+          })
+        end
+      end
+    end
+
+    private
+
+    def pattern_matches?(pattern, event_name)
+      if pattern.include?('*')
+        # Convert wildcard pattern to regex
+        # llm.* becomes ^llm\..*$
+        regex_pattern = "^#{Regexp.escape(pattern).gsub('\\*', '.*')}$"
+        Regexp.new(regex_pattern).match?(event_name)
+      else
+        # Exact match
+        pattern == event_name
+      end
+    end
+  end
+end

data/lib/dspy/version.rb

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

data/lib/dspy.rb

@@ -9,6 +9,8 @@ require_relative 'dspy/errors'
 require_relative 'dspy/type_serializer'
 require_relative 'dspy/observability'
 require_relative 'dspy/context'
+require_relative 'dspy/events'
+require_relative 'dspy/events/types'
 
 module DSPy
   extend Dry::Configurable
@@ -34,18 +36,105 @@ module DSPy
   end
 
   def self.log(event, **attributes)
+    # Return nil early if logger is not configured (backward compatibility)
+    return nil unless logger
+    
+    # Forward to event system - this maintains backward compatibility
+    # while providing all new event system benefits
+    event(event, attributes)
+    
+    # Return nil to maintain backward compatibility
+    nil
+  end
+
+  def self.event(event_name_or_object, attributes = {})
+    # Handle typed event objects
+    if event_name_or_object.respond_to?(:name) && event_name_or_object.respond_to?(:to_attributes)
+      event_obj = event_name_or_object
+      event_name = event_obj.name
+      attributes = event_obj.to_attributes
+      
+      # For LLM events, use OpenTelemetry semantic conventions for spans
+      if event_obj.is_a?(DSPy::Events::LLMEvent)
+        otel_attributes = event_obj.to_otel_attributes
+        create_event_span(event_name, otel_attributes)
+      else
+        create_event_span(event_name, attributes)
+      end
+    else
+      # Handle string event names (backward compatibility)
+      event_name = event_name_or_object
+      raise ArgumentError, "Event name cannot be nil" if event_name.nil?
+      
+      # Handle nil attributes
+      attributes = {} if attributes.nil?
+      
+      # Create OpenTelemetry span for the event if observability is enabled
+      create_event_span(event_name, attributes)
+    end
+    
+    # Perform the actual logging (original DSPy.log behavior)
+    emit_log(event_name, attributes)
+    
+    # Notify event listeners
+    events.notify(event_name, attributes)
+  end
+
+  def self.events
+    @event_registry ||= DSPy::EventRegistry.new
+  end
+
+  private
+
+  def self.emit_log(event_name, attributes)
     return unless logger
     
     # Merge context automatically (but don't include span_stack)
     context = Context.current.dup
     context.delete(:span_stack)
     attributes = context.merge(attributes)
-    attributes[:event] = event
+    attributes[:event] = event_name
     
     # Use Dry::Logger's structured logging
     logger.info(attributes)
   end
 
+  def self.create_event_span(event_name, attributes)
+    return unless DSPy::Observability.enabled?
+    
+    begin
+      # Flatten nested hashes for OpenTelemetry span attributes
+      flattened_attributes = flatten_attributes(attributes)
+      
+      # Create and immediately finish a span for this event
+      # Events are instant moments in time, not ongoing operations
+      span = DSPy::Observability.start_span(event_name, flattened_attributes)
+      DSPy::Observability.finish_span(span) if span
+    rescue => e
+      # Log error but don't let it break the event system
+      # Use emit_log directly to avoid infinite recursion
+      emit_log('event.span_creation_error', {
+        error_class: e.class.name,
+        error_message: e.message,
+        event_name: event_name
+      })
+    end
+  end
+
+  def self.flatten_attributes(attributes, parent_key = '', result = {})
+    attributes.each do |key, value|
+      new_key = parent_key.empty? ? key.to_s : "#{parent_key}.#{key}"
+      
+      if value.is_a?(Hash)
+        flatten_attributes(value, new_key, result)
+      else
+        result[new_key] = value
+      end
+    end
+    
+    result
+  end
+
   def self.create_logger
     env = ENV['RACK_ENV'] || ENV['RAILS_ENV'] || 'development'
     log_output = ENV['DSPY_LOG'] # Allow override
@@ -101,6 +190,7 @@ require_relative 'dspy/image'
 require_relative 'dspy/strategy'
 require_relative 'dspy/prediction'
 require_relative 'dspy/predict'
+require_relative 'dspy/events/subscribers'
 require_relative 'dspy/chain_of_thought'
 require_relative 'dspy/re_act'
 require_relative 'dspy/code_act'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 bindir: bin
 cert_chain: []
-date: 2025-09-01 00:00:00.000000000 Z
+date: 2025-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable
@@ -192,6 +192,9 @@ files:
 - lib/dspy/error_formatter.rb
 - lib/dspy/errors.rb
 - lib/dspy/evaluate.rb
+- lib/dspy/events.rb
+- lib/dspy/events/subscribers.rb
+- lib/dspy/events/types.rb
 - lib/dspy/example.rb
 - lib/dspy/few_shot_example.rb
 - lib/dspy/field.rb