dspy 0.30.0 → 0.30.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e59fde98eb918cca54822bc6af704100c51b71081d8ac77e17e8df3cddcb016
-  data.tar.gz: f8ff81ef1873fc1bffac8a209ddb4172586295e6ef1f46d6bb598045148fc3eb
+  metadata.gz: 0bdf656ce5715a455d3fb36427878ae507d8d4bd9a7f092a6b9752196f9ebc4b
+  data.tar.gz: cd21540e0eea82c1567c085b9ef2fd5c2d9742cd1ff08f855a16f4109893ebb2
 SHA512:
-  metadata.gz: dc880712e317a8e88c188527b5e1ff906da8c03fe1cbc4251e265bd87c141e52a16b4498f2f9316c33543f3428fb3067fd80a0728ce33de81575f111b93d4553
-  data.tar.gz: 7d1899b7e8a61b5d2c80fb8f237085171e9b64407f99135b22c341076e11867ee0c323d15c67c5428337606c869702ec9e6ada13edf27c38a6a40d8c83ef4f3b
+  metadata.gz: 992c191cbc6bbdd1bc770a83d4a1151869c4f57a20d7236a19b0add9c50329ec2dea901fe440488b2194fe96951d729c4509d33a9df8fb6c2dc7154c570e9c00
+  data.tar.gz: 82e67a674db952801adf40407d34daf0e2808f4c1b4d99da60f63c33fd2033b7f5a2deaefe63ea91bf4bcc7129e7580772877df3ca3b69bf9894d2454a5bdf38

data/README.md

@@ -47,23 +47,67 @@ and
 bundle install
 ```
 
-### Optional Sibling Gems
+### Your First Reliable Predictor
+
+```ruby
+
+# Configure DSPy globablly to use your fave LLM - you can override this on an instance levle. 
+DSPy.configure do |c|
+  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
+                      api_key: ENV['OPENAI_API_KEY'],
+                      structured_outputs: true)  # Enable OpenAI's native JSON mode
+end
+
+# Define a signature for sentiment classification - instead of writing a full prompt!
+class Classify < DSPy::Signature
+  description "Classify sentiment of a given sentence." # sets the goal of the underlying prompt
+
+  class Sentiment < T::Enum
+    enums do
+      Positive = new('positive')
+      Negative = new('negative')
+      Neutral = new('neutral')
+    end
+  end
+  
+  # Structured Inputs: makes sure you are sending only valid prompt inputs to your model
+  input do
+    const :sentence, String, description: 'The sentence to analyze'
+  end
+
+  # Structured Outputs: your predictor will validate the output of the model too.
+  output do
+    const :sentiment, Sentiment, description: 'The sentiment of the sentence'
+    const :confidence, Float, description: 'A number between 0.0 and 1.0'
+  end
+end
+
+# Wire it to the simplest prompting technique - a Predictn.
+classify = DSPy::Predict.new(Classify)
+# it may raise an error if you mess the inputs or your LLM messes the outputs.
+result = classify.call(sentence: "This book was super fun to read!")
+
+puts result.sentiment    # => #<Sentiment::Positive>  
+puts result.confidence   # => 0.85
+```
+
+### Sibling Gems
 
-DSPy.rb ships multiple gems from this monorepo so you only install what you need. Add these alongside `dspy`:
+DSPy.rb ships multiple gems from this monorepo so you can opt into features with heavier dependency trees (e.g., datasets pull in Polars/Arrow, MIPROv2 requires `numo-*` BLAS bindings) only when you need them. Add these alongside `dspy`:
 
 | Gem | Description | Status |
 | --- | --- | --- |
-| `dspy-schema` | Exposes `DSPy::TypeSystem::SorbetJsonSchema` for downstream reuse. | **Stable** (v1.0.0) |
-| `dspy-code_act` | Think-Code-Observe agents that synthesize and execute Ruby safely. | Preview (0.x) |
-| `dspy-datasets` | Dataset helpers plus Parquet/Polars tooling for richer evaluation corpora. | Preview (0.x) |
-| `dspy-evals` | High-throughput evaluation harness with metrics, callbacks, and regression fixtures. | Preview (0.x) |
-| `dspy-miprov2` | Bayesian optimization + Gaussian Process backend for the MIPROv2 teleprompter. | Preview (0.x) |
-| `dspy-gepa` | `DSPy::Teleprompt::GEPA`, reflection loops, experiment tracking, telemetry adapters. | Preview (mirrors `dspy` version) |
-| `gepa` | GEPA optimizer core (Pareto engine, telemetry, reflective proposer). | Preview (mirrors `dspy` version) |
-| `dspy-o11y` | Core observability APIs: `DSPy::Observability`, async span processor, observation types. | **Stable** (v1.0.0) |
-| `dspy-o11y-langfuse` | Auto-configures DSPy observability to stream spans to Langfuse via OTLP. | **Stable** (v1.0.0) |
-
-Set the matching `DSPY_WITH_*` environment variables (see `Gemfile`) to include or exclude each sibling gem when running Bundler locally (for example `DSPY_WITH_GEPA=1` or `DSPY_WITH_O11Y_LANGFUSE=1`). Refer to `docs/core-concepts/dependency-tree.md` for the full dependency map and roadmap.
+| `dspy-schema` | Exposes `DSPy::TypeSystem::SorbetJsonSchema` for downstream reuse. (Still required by the core `dspy` gem; extraction lets other projects depend on it directly.) | **Stable** (v1.0.0) |
+| `dspy-code_act` | Think-Code-Observe agents that synthesize and execute Ruby safely. (Add the gem or set `DSPY_WITH_CODE_ACT=1` before requiring `dspy/code_act`.) | **Stable** (v1.0.0) |
+| `dspy-datasets` | Dataset helpers plus Parquet/Polars tooling for richer evaluation corpora. (Toggle via `DSPY_WITH_DATASETS`.) | **Stable** (v1.0.0) |
+| `dspy-evals` | High-throughput evaluation harness with metrics, callbacks, and regression fixtures. (Toggle via `DSPY_WITH_EVALS`.) | **Stable** (v1.0.0) |
+| `dspy-miprov2` | Bayesian optimization + Gaussian Process backend for the MIPROv2 teleprompter. (Install or export `DSPY_WITH_MIPROV2=1` before requiring the teleprompter.) | **Stable** (v1.0.0) |
+| `dspy-gepa` | `DSPy::Teleprompt::GEPA`, reflection loops, experiment tracking, telemetry adapters. (Install or set `DSPY_WITH_GEPA=1`.) | **Stable** (v1.0.0) |
+| `gepa` | GEPA optimizer core (Pareto engine, telemetry, reflective proposer). | **Stable** (v1.0.0) |
+| `dspy-o11y` | Core observability APIs: `DSPy::Observability`, async span processor, observation types. (Install or set `DSPY_WITH_O11Y=1`.) | **Stable** (v1.0.0) |
+| `dspy-o11y-langfuse` | Auto-configures DSPy observability to stream spans to Langfuse via OTLP. (Install or set `DSPY_WITH_O11Y_LANGFUSE=1`.) | **Stable** (v1.0.0) |
+
+Set the matching `DSPY_WITH_*` environment variables (see `Gemfile`) to include or exclude each sibling gem when running Bundler locally (for example `DSPY_WITH_GEPA=1` or `DSPY_WITH_O11Y_LANGFUSE=1`). Refer to `adr/013-dependency-tree.md` for the full dependency map and roadmap.
 ### Your First Reliable Predictor
 
 ```ruby

data/lib/dspy/callbacks.rb

@@ -259,15 +259,34 @@ module DSPy
     # Executes method with around callbacks
     def execute_with_around_callbacks(method_name, original_method, *args, **kwargs, &block)
       callbacks = self.class.send(:callbacks_for, method_name)[:around]
+      args_copy = args.dup
+      kwargs_copy = kwargs.dup
 
       # Build callback chain from innermost (original method) to outermost
       chain = callbacks.reverse.inject(
         -> { original_method.bind(self).call(*args, **kwargs, &block) }
       ) do |inner, callback|
         if callback.is_a?(Proc)
-          -> { instance_exec(-> { inner.call }, &callback) }
+          -> do
+            next_proc = -> { inner.call }
+            proc_arity = callback.arity
+            expects_extra = proc_arity.abs > 1
+
+            if expects_extra
+              instance_exec(next_proc, args_copy, kwargs_copy, &callback)
+            else
+              instance_exec(next_proc, &callback)
+            end
+          end
         else
-          -> { send(callback) { inner.call } }
+          -> do
+            method_obj = method(callback)
+            if method_obj.arity.zero?
+              send(callback) { inner.call }
+            else
+              send(callback, args_copy, kwargs_copy) { inner.call }
+            end
+          end
         end
       end
 

data/lib/dspy/context.rb

@@ -33,7 +33,8 @@ module DSPy
         context = {
           trace_id: SecureRandom.uuid,
           span_stack: [],
-          otel_span_stack: []
+          otel_span_stack: [],
+          module_stack: []
         }
         
         # Set in both Thread and Fiber storage
@@ -158,6 +159,48 @@ module DSPy
           end
         end
       end
+
+      def with_module(module_instance, label: nil)
+        stack = module_stack
+        entry = build_module_entry(module_instance, label)
+        stack.push(entry)
+        yield
+      ensure
+        if stack.last.equal?(entry)
+          stack.pop
+        else
+          stack.delete(entry)
+        end
+      end
+
+      def module_stack
+        current[:module_stack] ||= []
+      end
+
+      def module_context_attributes
+        stack = module_stack
+        return {} if stack.empty?
+
+        path = stack.map do |entry|
+          {
+            id: entry[:id],
+            class: entry[:class],
+            label: entry[:label]
+          }
+        end
+
+        ancestry_token = path.map { |node| node[:id] }.join('>')
+
+        {
+          module_path: path,
+          module_root: path.first,
+          module_leaf: path.last,
+          module_scope: {
+            ancestry_token: ancestry_token,
+            depth: path.length
+          }
+        }
+      end
       
       def clear!
         # Clear both the thread-specific key and the legacy key
@@ -218,6 +261,14 @@ module DSPy
           end
         end
       end
+
+      def build_module_entry(module_instance, explicit_label)
+        {
+          id: (module_instance.respond_to?(:module_scope_id) ? module_instance.module_scope_id : SecureRandom.uuid),
+          class: module_instance.class.name,
+          label: explicit_label || (module_instance.respond_to?(:module_scope_label) ? module_instance.module_scope_label : nil)
+        }
+      end
     end
   end
 end

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/version.rb

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

data/lib/dspy.rb

@@ -75,6 +75,10 @@ module DSPy
       create_event_span(event_name, attributes)
     end
 
+    attributes = attributes.dup
+    module_metadata = DSPy::Context.module_context_attributes
+    attributes.merge!(module_metadata) unless module_metadata.empty?
+
     # Perform the actual logging (original DSPy.log behavior)
     # emit_log(event_name, attributes)
 
@@ -100,6 +104,8 @@ module DSPy
     # Merge context automatically (but don't include span_stack)
     context = Context.current.dup
     context.delete(:span_stack)
+    context.delete(:otel_span_stack)
+    context.delete(:module_stack)
     attributes = context.merge(attributes)
     attributes[:event] = event_name
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.30.1
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-10-25 00:00:00.000000000 Z
+date: 2025-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-configurable