dspy 0.29.1 → 0.30.1

data/lib/dspy/module.rb

@@ -2,6 +2,7 @@
 
 require 'sorbet-runtime'
 require 'dry-configurable'
+require 'securerandom'
 require_relative 'context'
 require_relative 'callbacks'
 
@@ -12,10 +13,84 @@ module DSPy
     include Dry::Configurable
     include DSPy::Callbacks
 
+    class SubcriptionScope < T::Enum
+      enums do
+        Descendants = new('descendants')
+        SelfOnly    = new('self')
+      end
+    end
+
+    DEFAULT_MODULE_SUBSCRIPTION_SCOPE = SubcriptionScope::Descendants
+
+    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
+
+        original = instance_method(:forward)
+        define_method(:forward) do |*args, **kwargs, &block|
+          instrument_forward_call(args, kwargs) do
+            original.bind(self).call(*args, **kwargs, &block)
+          end
+        end
+      ensure
+        @_wrapping_forward = false
+      end
+    end
+
+    class << self
+      def inherited(subclass)
+        super
+        specs_copy = module_subscription_specs.map(&:dup)
+        subclass.instance_variable_set(:@module_subscription_specs, specs_copy)
+        subclass.extend(ForwardOverrideHooks)
+      end
+
+      def subscribe(pattern, handler = nil, scope: DEFAULT_MODULE_SUBSCRIPTION_SCOPE, &block)
+        scope = normalize_scope(scope)
+        raise ArgumentError, 'Provide a handler method or block' if handler.nil? && block.nil?
+
+        module_subscription_specs << {
+          pattern: pattern,
+          handler: handler,
+          block: block,
+          scope: scope
+        }
+      end
+
+      def module_subscription_specs
+        @module_subscription_specs ||= []
+      end
+
+      private
+
+      def validate_subscription_scope!(scope)
+        T.must(scope)
+      end
+
+      def normalize_scope(scope)
+        return scope if scope.is_a?(SubcriptionScope)
+
+        case scope
+        when :descendants
+          SubcriptionScope::Descendants
+        when :self
+          SubcriptionScope::SelfOnly
+        else
+          raise ArgumentError, "Unsupported subscription scope: #{scope.inspect}"
+        end
+      end
+    end
+
     # Per-instance LM configuration
     setting :lm, default: nil
 
-    # Define callback hooks for forward method
+    # Enable callback hooks for forward method
     create_before_callback :forward
     create_after_callback :forward
     create_around_callback :forward
@@ -29,23 +104,8 @@ module DSPy
         .returns(T.type_parameter(:O))
     end
     def forward(**input_values)
-      # Create span for this module's execution
-      observation_type = DSPy::ObservationType.for_module_class(self.class)
-      DSPy::Context.with_span(
-        operation: "#{self.class.name}.forward",
-        **observation_type.langfuse_attributes,
-        'langfuse.observation.input' => input_values.to_json,
-        'dspy.module' => self.class.name
-      ) do |span|
+      instrument_forward_call([], input_values) do
         result = forward_untyped(**input_values)
-        
-        # Add output to span
-        if span && result
-          output_json = result.respond_to?(:to_h) ? result.to_h.to_json : result.to_json rescue result.to_s
-          span.set_attribute('langfuse.observation.output', output_json)
-        end
-        
-        # Cast the result of forward_untyped to the expected output type
         T.cast(result, T.type_parameter(:O))
       end
     end
@@ -116,5 +176,141 @@ module DSPy
     def predictors
       named_predictors.map { |(_, predictor)| predictor }
     end
+
+    def instrument_forward_call(call_args, call_kwargs)
+      ensure_module_subscriptions!
+
+      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),
+          'dspy.module' => self.class.name
+        )
+
+        DSPy::Context.with_span(
+          operation: "#{self.class.name}.forward",
+          **span_attributes
+        ) do |span|
+          yield.tap do |result|
+            if span && result
+              span.set_attribute('langfuse.observation.output', serialize_module_output(result))
+            end
+          end
+        end
+      end
+    end
+
+    def serialize_module_input(call_args, call_kwargs)
+      payload = if call_kwargs && !call_kwargs.empty?
+        call_kwargs
+      elsif call_args && !call_args.empty?
+        call_args
+      else
+        {}
+      end
+
+      payload.to_json
+    rescue StandardError
+      payload.to_s
+    end
+
+    def serialize_module_output(result)
+      if result.respond_to?(:to_h)
+        result.to_h.to_json
+      else
+        result.to_json
+      end
+    rescue StandardError
+      result.to_s
+    end
+
+    private :instrument_forward_call, :serialize_module_input, :serialize_module_output
+
+    sig { returns(String) }
+    def module_scope_id
+      @module_scope_id ||= SecureRandom.uuid
+    end
+
+    sig { returns(T.nilable(String)) }
+    def module_scope_label
+      @module_scope_label
+    end
+
+    sig { params(label: T.nilable(String)).void }
+    def module_scope_label=(label)
+      @module_scope_label = label
+    end
+
+    sig { returns(T::Array[String]) }
+    def registered_module_subscriptions
+      Array(@module_subscription_ids).dup
+    end
+
+    sig { void }
+    def unsubscribe_module_events
+      Array(@module_subscription_ids).each { |id| DSPy.events.unsubscribe(id) }
+      @module_subscription_ids = []
+      @module_subscriptions_registered = false
+    end
+
+    private
+
+    def ensure_module_subscriptions!
+      return if @module_subscriptions_registered
+
+      specs = self.class.module_subscription_specs
+      if specs.empty?
+        @module_subscriptions_registered = true
+        return
+      end
+
+      @module_subscription_ids ||= []
+      specs.each do |spec|
+        callback = build_subscription_callback(spec)
+        subscription_id = DSPy.events.subscribe(spec[:pattern], &callback)
+        @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
+
+      case scope
+      when SubcriptionScope::SelfOnly
+        metadata[:leaf_id] == module_scope_id
+      else
+        metadata[:path_ids].include?(module_scope_id)
+      end
+    end
+
+    def extract_module_metadata(attributes)
+      path = attributes[:module_path] || attributes['module_path']
+      leaf = attributes[:module_leaf] || attributes['module_leaf']
+      return nil unless path.is_a?(Array)
+
+      {
+        path_ids: path.map { |entry| entry[:id] || entry['id'] }.compact,
+        leaf_id: leaf&.dig(:id) || leaf&.dig('id')
+      }
+    end
   end
 end

data/lib/dspy/observability.rb

@@ -1,196 +1,54 @@
+# typed: false
 # frozen_string_literal: true
 
-require 'base64'
-require_relative 'observability/async_span_processor'
-
-module DSPy
-  class Observability
-    class << self
-      attr_reader :enabled, :tracer, :endpoint
-
-      def configure!
-        @enabled = false
-        
-        # Check for explicit disable flag first
-        if ENV['DSPY_DISABLE_OBSERVABILITY'] == 'true'
-          DSPy.log('observability.disabled', reason: 'Explicitly disabled via DSPY_DISABLE_OBSERVABILITY')
-          return
-        end
-        
-        # Check for required Langfuse environment variables
-        public_key = ENV['LANGFUSE_PUBLIC_KEY']
-        secret_key = ENV['LANGFUSE_SECRET_KEY']
-        
-        # Skip OTLP configuration in test environment UNLESS Langfuse credentials are explicitly provided
-        # This allows observability tests to run while protecting general tests from network calls
-        if (ENV['RACK_ENV'] == 'test' || ENV['RAILS_ENV'] == 'test' || defined?(RSpec)) && !(public_key && secret_key)
-          DSPy.log('observability.disabled', reason: 'Test environment detected - OTLP disabled')
-          return
-        end
-        
-        unless public_key && secret_key
-          return
+begin
+  require 'dspy/o11y'
+rescue LoadError
+  require 'sorbet-runtime'
+
+  module DSPy
+    class Observability
+      class << self
+        def register_configurator(*); end
+        def configure!(*); false; end
+        def enabled?; false; end
+        def enable!(*); false; end
+        def disable!(*); nil; end
+        def start_span(*); nil; end
+        def finish_span(*); nil; end
+        def flush!; nil; end
+        def reset!; nil; end
+        def require_dependency(lib)
+          require lib
+        rescue LoadError
+          raise
         end
-
-        # Determine endpoint based on host
-        host = ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
-        @endpoint = "#{host}/api/public/otel/v1/traces"
-
-        begin
-          # Load OpenTelemetry gems
-          require 'opentelemetry/sdk'
-          require 'opentelemetry/exporter/otlp'
-
-          patch_frozen_ssl_context_for_otlp!
-
-          # Generate Basic Auth header
-          auth_string = Base64.strict_encode64("#{public_key}:#{secret_key}")
-          
-          # Configure OpenTelemetry SDK
-          OpenTelemetry::SDK.configure do |config|
-            config.service_name = 'dspy-ruby'
-            config.service_version = DSPy::VERSION
-            
-            # Add OTLP exporter for Langfuse using AsyncSpanProcessor
-            exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
-              endpoint: @endpoint,
-              headers: {
-                'Authorization' => "Basic #{auth_string}",
-                'Content-Type' => 'application/x-protobuf'
-              },
-              compression: 'gzip'
-            )
-            
-            # Configure AsyncSpanProcessor with environment variables
-            async_config = {
-              queue_size: (ENV['DSPY_TELEMETRY_QUEUE_SIZE'] || AsyncSpanProcessor::DEFAULT_QUEUE_SIZE).to_i,
-              export_interval: (ENV['DSPY_TELEMETRY_EXPORT_INTERVAL'] || AsyncSpanProcessor::DEFAULT_EXPORT_INTERVAL).to_f,
-              export_batch_size: (ENV['DSPY_TELEMETRY_BATCH_SIZE'] || AsyncSpanProcessor::DEFAULT_EXPORT_BATCH_SIZE).to_i,
-              shutdown_timeout: (ENV['DSPY_TELEMETRY_SHUTDOWN_TIMEOUT'] || AsyncSpanProcessor::DEFAULT_SHUTDOWN_TIMEOUT).to_f
-            }
-            
-            config.add_span_processor(
-              AsyncSpanProcessor.new(exporter, **async_config)
-            )
-            
-            # Add resource attributes
-            config.resource = OpenTelemetry::SDK::Resources::Resource.create({
-              'service.name' => 'dspy-ruby',
-              'service.version' => DSPy::VERSION,
-              'telemetry.sdk.name' => 'opentelemetry',
-              'telemetry.sdk.language' => 'ruby'
-            })
-          end
-
-          # Create tracer
-          @tracer = OpenTelemetry.tracer_provider.tracer('dspy', DSPy::VERSION)
-          @enabled = true
-
-        rescue LoadError => e
-          DSPy.log('observability.disabled', reason: 'OpenTelemetry gems not available')
-        rescue StandardError => e
-          DSPy.log('observability.error', error: e.message, class: e.class.name)
-        end
-      end
-
-      def enabled?
-        @enabled == true
-      end
-
-      def tracer
-        @tracer
-      end
-
-      def start_span(operation_name, attributes = {})
-        return nil unless enabled? && tracer
-
-        # Convert attribute keys to strings and filter out nil values
-        string_attributes = attributes.transform_keys(&:to_s)
-                                     .reject { |k, v| v.nil? }
-        string_attributes['operation.name'] = operation_name
-        
-        tracer.start_span(
-          operation_name,
-          kind: :internal,
-          attributes: string_attributes
-        )
-      rescue StandardError => e
-        DSPy.log('observability.span_error', error: e.message, operation: operation_name)
-        nil
       end
+    end
 
-      def finish_span(span)
-        return unless span
-        
-        span.finish
-      rescue StandardError => e
-        DSPy.log('observability.span_finish_error', error: e.message)
+    class ObservationType < T::Enum
+      enums do
+        Generation = new('generation')
+        Agent = new('agent')
+        Tool = new('tool')
+        Chain = new('chain')
+        Retriever = new('retriever')
+        Embedding = new('embedding')
+        Evaluator = new('evaluator')
+        Span = new('span')
+        Event = new('event')
       end
 
-      def flush!
-        return unless enabled?
-        
-        # Force flush any pending spans
-        OpenTelemetry.tracer_provider.force_flush
-      rescue StandardError => e
-        DSPy.log('observability.flush_error', error: e.message)
+      def self.for_module_class(_module_class)
+        Span
       end
 
-      def reset!
-        @enabled = false
-        
-        # Shutdown OpenTelemetry if it's configured
-        if defined?(OpenTelemetry) && OpenTelemetry.tracer_provider
-          begin
-            OpenTelemetry.tracer_provider.shutdown(timeout: 1.0)
-          rescue => e
-            # Ignore shutdown errors in tests - log them but don't fail
-            DSPy.log('observability.shutdown_error', error: e.message) if respond_to?(:log)
-          end
-        end
-        
-        @tracer = nil
-        @endpoint = nil
+      def langfuse_attribute
+        ['langfuse.observation.type', serialize]
       end
 
-      private
-
-      def patch_frozen_ssl_context_for_otlp!
-        return unless defined?(OpenTelemetry::Exporter::OTLP::Exporter)
-
-        ssl_context_frozen = begin
-          http = Net::HTTP.new('example.com', 443)
-          http.use_ssl = true
-          http.ssl_context&.frozen?
-        rescue StandardError
-          false
-        end
-
-        return unless ssl_context_frozen
-
-        exporter = OpenTelemetry::Exporter::OTLP::Exporter
-        return if exporter.instance_variable_defined?(:@_dspy_ssl_patch_applied)
-
-        exporter.class_eval do
-          define_method(:http_connection) do |uri, ssl_verify_mode, certificate_file, client_certificate_file, client_key_file|
-            http = Net::HTTP.new(uri.host, uri.port)
-            use_ssl = uri.scheme == 'https'
-            http.use_ssl = use_ssl
-
-            if use_ssl && http.ssl_context&.frozen?
-              http.instance_variable_set(:@ssl_context, OpenSSL::SSL::SSLContext.new)
-            end
-
-            http.verify_mode = ssl_verify_mode
-            http.ca_file = certificate_file unless certificate_file.nil?
-            http.cert = OpenSSL::X509::Certificate.new(File.read(client_certificate_file)) unless client_certificate_file.nil?
-            http.key = OpenSSL::PKey::RSA.new(File.read(client_key_file)) unless client_key_file.nil?
-            http.keep_alive_timeout = KEEP_ALIVE_TIMEOUT
-            http
-          end
-        end
-
-        exporter.instance_variable_set(:@_dspy_ssl_patch_applied, true)
+      def langfuse_attributes
+        { 'langfuse.observation.type' => serialize }
       end
     end
   end

data/lib/dspy/predict.rb

@@ -6,6 +6,7 @@ require_relative 'prompt'
 require_relative 'utils/serialization'
 require_relative 'mixins/struct_builder'
 require_relative 'mixins/type_coercion'
+require_relative 'mixins/instruction_updatable'
 require_relative 'error_formatter'
 
 module DSPy
@@ -46,6 +47,7 @@ module DSPy
     extend T::Sig
     include Mixins::StructBuilder
     include Mixins::TypeCoercion
+    include Mixins::InstructionUpdatable
 
     sig { returns(T.class_of(Signature)) }
     attr_reader :signature_class
@@ -120,6 +122,7 @@ module DSPy
       # Create a new instance with the same signature but updated prompt
       instance = self.class.new(@signature_class)
       instance.instance_variable_set(:@prompt, new_prompt)
+      instance.instance_variable_set(:@demos, @demos&.map { |demo| demo })
       instance
     end
 
@@ -130,12 +133,17 @@ module DSPy
 
     sig { params(examples: T::Array[FewShotExample]).returns(Predict) }
     def with_examples(examples)
-      with_prompt(@prompt.with_examples(examples))
+      instance = with_prompt(@prompt.with_examples(examples))
+      instance.demos = examples.map { |example| example }
+      instance
     end
 
     sig { params(examples: T::Array[FewShotExample]).returns(Predict) }
     def add_examples(examples)
-      with_prompt(@prompt.add_examples(examples))
+      instance = with_prompt(@prompt.add_examples(examples))
+      combined = instance.prompt.few_shot_examples
+      instance.demos = combined.map { |example| example }
+      instance
     end
 
     sig { override.returns(T::Array[[String, DSPy::Module]]) }

data/lib/dspy/propose/dataset_summary_generator.rb

@@ -34,7 +34,7 @@ module DSPy
                    "It will be useful to make an educated guess as to the nature of the task this dataset will enable. Don't be afraid to be creative"
 
         input do
-          const :examples, String, description: "Sample data points from the dataset"
+          const :examples, T::Array[T::Hash[String, T.untyped]], description: "Sample data points from the dataset"
         end
 
         output do
@@ -50,7 +50,7 @@ module DSPy
                    "It will be useful to make an educated guess as to the nature of the task this dataset will enable. Don't be afraid to be creative"
 
         input do
-          const :examples, String, description: "Sample data points from the dataset"
+          const :examples, T::Array[T::Hash[String, T.untyped]], description: "Sample data points from the dataset"
           const :prior_observations, String, description: "Some prior observations I made about the data"
         end
 
@@ -124,9 +124,7 @@ module DSPy
           upper_lim = [trainset.length, view_data_batch_size].min
           batch_examples = trainset[0...upper_lim]
           predictor = DSPy::Predict.new(DatasetDescriptor)
-          examples_repr = format_examples_for_prompt(batch_examples)
-
-          observation = predictor.call(examples: examples_repr)
+          observation = predictor.call(examples: format_examples_for_prompt(batch_examples))
           observations = observation.observations
 
           # Iteratively refine observations with additional batches
@@ -145,11 +143,9 @@ module DSPy
 
               predictor = DSPy::Predict.new(DatasetDescriptorWithPriorObservations)
               batch_examples = trainset[b...upper_lim]
-              examples_repr = format_examples_for_prompt(batch_examples)
-
               output = predictor.call(
                 prior_observations: observations,
-                examples: examples_repr
+                examples: format_examples_for_prompt(batch_examples)
               )
 
               # Check if LLM indicates observations are complete
@@ -179,31 +175,45 @@ module DSPy
         end
       end
 
-      sig { params(examples: T::Array[T.untyped]).returns(String) }
+      sig { params(examples: T::Array[T.untyped]).returns(T::Array[T::Hash[String, T.untyped]]) }
       def self.format_examples_for_prompt(examples)
         serialized_examples = examples.map do |example|
           case example
           when DSPy::Example
             {
-              signature: example.signature_class.name,
-              input: DSPy::TypeSerializer.serialize(example.input),
-              expected: DSPy::TypeSerializer.serialize(example.expected)
+              'signature' => example.signature_class.name || example.signature_class.to_s,
+              'input' => stringify_keys(DSPy::TypeSerializer.serialize(example.input)),
+              'expected' => stringify_keys(DSPy::TypeSerializer.serialize(example.expected))
             }
           when DSPy::FewShotExample
             base = {
-              input: example.input,
-              output: example.output
+              'input' => stringify_keys(example.input),
+              'output' => stringify_keys(example.output)
             }
-            base[:reasoning] = example.reasoning if example.reasoning
+            base['reasoning'] = example.reasoning if example.reasoning
             base
           when Hash
-            example
+            stringify_keys(example)
           else
-            example.respond_to?(:to_h) ? example.to_h : { value: example }
+            stringify_keys(example.respond_to?(:to_h) ? example.to_h : { value: example })
           end
         end
 
-        JSON.pretty_generate(serialized_examples)
+        serialized_examples
+      end
+
+      sig { params(value: T.untyped).returns(T.untyped) }
+      def self.stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), result|
+            result[k.to_s] = stringify_keys(v)
+          end
+        when Array
+          value.map { |item| stringify_keys(item) }
+        else
+          value
+        end
       end
     end
   end

data/lib/dspy/re_act.rb

@@ -157,6 +157,27 @@ module DSPy
       named_predictors.map { |(_, predictor)| predictor }
     end
 
+    sig { returns(DSPy::Prompt) }
+    def prompt
+      @thought_generator.prompt
+    end
+
+    sig { params(instruction: String).returns(ReAct).override }
+    def with_instruction(instruction)
+      clone = self.class.new(@original_signature_class, tools: @tools.values, max_iterations: @max_iterations)
+      thought_generator = clone.instance_variable_get(:@thought_generator)
+      clone.instance_variable_set(:@thought_generator, thought_generator.with_instruction(instruction))
+      clone
+    end
+
+    sig { params(examples: T::Array[DSPy::FewShotExample]).returns(ReAct).override }
+    def with_examples(examples)
+      clone = self.class.new(@original_signature_class, tools: @tools.values, max_iterations: @max_iterations)
+      thought_generator = clone.instance_variable_get(:@thought_generator)
+      clone.instance_variable_set(:@thought_generator, thought_generator.with_examples(examples))
+      clone
+    end
+
     sig { params(kwargs: T.untyped).returns(T.untyped).override }
     def forward(**kwargs)
       # Validate input