dspy 0.30.0 → 0.31.0

data/lib/dspy/module.rb

@@ -2,8 +2,11 @@
 
 require 'sorbet-runtime'
 require 'dry-configurable'
+require 'securerandom'
 require_relative 'context'
 require_relative 'callbacks'
+require_relative 'type_serializer'
+require 'json'
 
 module DSPy
   class Module
@@ -12,10 +15,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 +106,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 +178,139 @@ 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
+
+      serialized = DSPy::TypeSerializer.serialize(payload)
+      JSON.generate(serialized)
+    rescue StandardError
+      payload.to_s
+    end
+
+    def serialize_module_output(result)
+      serialized = DSPy::TypeSerializer.serialize(result)
+      JSON.generate(serialized)
+    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/prompt.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'sorbet-runtime'
+require 'sorbet/toon'
+
 require_relative 'few_shot_example'
+require_relative 'schema/sorbet_toon_adapter'
 
 module DSPy
   class Prompt
@@ -33,6 +37,15 @@ module DSPy
       DSPy.config.lm&.schema_format || @schema_format || :json
     end
 
+    sig { returns(Symbol) }
+    def data_format
+      return @data_format if @data_format && @data_format != :json
+
+      lm = DSPy.config.lm
+      lm_format = lm&.respond_to?(:data_format) ? lm.data_format : nil
+      lm_format || @data_format || :json
+    end
+
     sig { returns(T.nilable(T.class_of(Signature))) }
     attr_reader :signature_class
 
@@ -44,10 +57,11 @@ module DSPy
         few_shot_examples: T::Array[FewShotExample],
         signature_class_name: T.nilable(String),
         schema_format: Symbol,
-        signature_class: T.nilable(T.class_of(Signature))
+        signature_class: T.nilable(T.class_of(Signature)),
+        data_format: Symbol
       ).void
     end
-    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil, schema_format: :json, signature_class: nil)
+    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil, schema_format: :json, signature_class: nil, data_format: :json)
       @instruction = instruction
       @few_shot_examples = few_shot_examples.freeze
       @input_schema = input_schema.freeze
@@ -55,6 +69,7 @@ module DSPy
       @signature_class_name = signature_class_name
       @schema_format = schema_format
       @signature_class = signature_class
+      @data_format = data_format
     end
 
     # Immutable update methods for optimization
@@ -67,7 +82,8 @@ module DSPy
         few_shot_examples: @few_shot_examples,
         signature_class_name: @signature_class_name,
         schema_format: @schema_format,
-        signature_class: @signature_class
+        signature_class: @signature_class,
+        data_format: @data_format
       )
     end
 
@@ -80,7 +96,8 @@ module DSPy
         few_shot_examples: new_examples,
         signature_class_name: @signature_class_name,
         schema_format: @schema_format,
-        signature_class: @signature_class
+        signature_class: @signature_class,
+        data_format: @data_format
       )
     end
 
@@ -106,7 +123,13 @@ module DSPy
         sections << "```baml"
         sections << render_baml_schema(@output_schema, :output)
         sections << "```"
-      else  # :json (default)
+      when :toon
+        sections << "Your input schema fields (TOON order) are:"
+        sections << Sorbet::Toon::SignatureFormatter.describe_signature(@signature_class, :input)
+        sections << ""
+        sections << "Your output schema fields (TOON order) are:"
+        sections << Sorbet::Toon::SignatureFormatter.describe_signature(@signature_class, :output)
+      else
         sections << "Your input schema fields are:"
         sections << "```json"
         sections << JSON.pretty_generate(@input_schema)
@@ -117,11 +140,10 @@ module DSPy
         sections << JSON.pretty_generate(@output_schema)
         sections << "```"
       end
-      
+
       sections << ""
       sections << "All interactions will be structured in the following way, with the appropriate values filled in."
-      
-      # Add few-shot examples if present
+
       if @few_shot_examples.any?
         sections << ""
         sections << "Here are some examples:"
@@ -133,36 +155,59 @@ module DSPy
         end
       end
 
-      sections << "## Input values"
-      sections << "```json"
-      sections << "{input_values}"
-      sections << "```"
-      
-      sections << "## Output values"
-      sections << "Respond exclusively with the output schema fields in the json block below."
-      sections << "```json"
-      sections << "{output_values}"
-      sections << "```"
-      
+      if data_format == :toon && @signature_class
+        sections << "## Input values"
+        sections << "```toon"
+        sections << "{input_values}"
+        sections << "```"
+        sections << ""
+        sections << "## Output values"
+        sections << "Respond exclusively with a ```toon``` block containing only the output fields defined above, in the same order."
+        sections << "```toon"
+        sections << "{output_values}"
+        sections << "```"
+      else
+        sections << "## Input values"
+        sections << "```json"
+        sections << "{input_values}"
+        sections << "```"
+
+        sections << "## Output values"
+        sections << "Respond exclusively with the output schema fields in the json block below."
+        sections << "```json"
+        sections << "{output_values}"
+        sections << "```"
+      end
+
       sections << ""
       sections << "In adhering to this structure, your objective is: #{@instruction}"
-      
+
       sections.join("\n")
     end
 
     sig { params(input_values: T::Hash[Symbol, T.untyped]).returns(String) }
     def render_user_prompt(input_values)
       sections = []
-      
-      sections << "## Input Values"
-      sections << "```json"
-      sections << JSON.pretty_generate(serialize_for_json(input_values))
-      sections << "```"
-      
-      sections << ""
-      sections << "Respond with the corresponding output schema fields wrapped in a ```json ``` block,"
-      sections << "starting with the heading `## Output values`."
-      
+
+      if data_format == :toon && @signature_class
+        toon_payload = DSPy::Schema::SorbetToonAdapter.render_input(@signature_class, input_values)
+
+        sections << "## Input Values"
+        sections << "```toon"
+        sections << toon_payload
+        sections << "```"
+        sections << ""
+        sections << "Respond with the corresponding output schema fields encoded as TOON inside a ```toon``` block starting with the heading `## Output values`."
+      else
+        sections << "## Input Values"
+        sections << "```json"
+        sections << JSON.pretty_generate(serialize_for_json(input_values))
+        sections << "```"
+        sections << ""
+        sections << "Respond with the corresponding output schema fields wrapped in a ```json ``` block,"
+        sections << "starting with the heading `## Output values`."
+      end
+
       sections.join("\n")
     end
 
@@ -184,7 +229,8 @@ module DSPy
         input_schema: @input_schema,
         output_schema: @output_schema,
         signature_class_name: @signature_class_name,
-        schema_format: @schema_format
+        schema_format: @schema_format,
+        data_format: @data_format
       }
     end
 
@@ -198,13 +244,24 @@ module DSPy
         output_schema: hash[:output_schema] || {},
         few_shot_examples: examples,
         signature_class_name: hash[:signature_class_name],
-        schema_format: hash[:schema_format] || :json
+        schema_format: hash[:schema_format] || :json,
+        data_format: hash[:data_format] || :json
       )
     end
 
     # Create prompt from signature class
-    sig { params(signature_class: T.class_of(Signature), schema_format: Symbol).returns(Prompt) }
-    def self.from_signature(signature_class, schema_format: :json)
+    sig do
+      params(
+        signature_class: T.class_of(Signature),
+        schema_format: T.nilable(Symbol),
+        data_format: T.nilable(Symbol)
+      ).returns(Prompt)
+    end
+    def self.from_signature(signature_class, schema_format: nil, data_format: nil)
+      lm = DSPy.config.lm
+      schema_format ||= lm&.schema_format || :json
+      data_format ||= (lm&.respond_to?(:data_format) ? lm.data_format : nil) || :json
+
       new(
         instruction: signature_class.description || "Complete this task.",
         input_schema: signature_class.input_json_schema,
@@ -212,7 +269,8 @@ module DSPy
         few_shot_examples: [],
         signature_class_name: signature_class.name,
         schema_format: schema_format,
-        signature_class: signature_class
+        signature_class: signature_class,
+        data_format: data_format
       )
     end
 
@@ -336,4 +394,4 @@ module DSPy
       result
     end
   end
-end
+end

data/lib/dspy/re_act.rb

@@ -98,13 +98,14 @@ module DSPy
       @tools = T.let({}, T::Hash[String, T.untyped])
       tools.each { |tool| @tools[tool.name.downcase] = tool }
       @max_iterations = max_iterations
+      @data_format = T.let(DSPy.config.lm&.data_format || :json, Symbol)
 
       # Create dynamic ActionEnum class with tool names + finish
       @action_enum_class = create_action_enum_class
 
       # Create dynamic signature classes that include the original input fields
-      thought_signature = create_thought_signature(signature_class)
-      observation_signature = create_observation_signature(signature_class)
+      thought_signature = create_thought_signature(signature_class, @data_format)
+      observation_signature = create_observation_signature(signature_class, @data_format)
 
       # Create thought generator using Predict to preserve field descriptions
       @thought_generator = T.let(DSPy::Predict.new(thought_signature), DSPy::Predict)
@@ -216,6 +217,28 @@ module DSPy
       end
     end
 
+    sig { params(input_struct: T.untyped).returns(T.untyped) }
+    def format_input_context(input_struct)
+      return input_struct if toon_data_format?
+
+      DSPy::TypeSerializer.serialize(input_struct).to_json
+    end
+
+    sig { params(history: T::Array[HistoryEntry]).returns(T.untyped) }
+    def format_history(history)
+      toon_data_format? ? history : serialize_history_for_llm(history)
+    end
+
+    sig { params(observation: T.untyped).returns(T.untyped) }
+    def format_observation(observation)
+      toon_data_format? ? observation : serialize_for_llm(observation)
+    end
+
+    sig { returns(T::Boolean) }
+    def toon_data_format?
+      @data_format == :toon
+    end
+
     # Creates a dynamic ActionEnum class with tool names and "finish"
     sig { returns(T.class_of(T::Enum)) }
     def create_action_enum_class
@@ -241,9 +264,14 @@ module DSPy
     end
 
     # Creates a dynamic Thought signature that includes the original input fields
-    sig { params(signature_class: T.class_of(DSPy::Signature)).returns(T.class_of(DSPy::Signature)) }
-    def create_thought_signature(signature_class)
+    sig { params(signature_class: T.class_of(DSPy::Signature), data_format: Symbol).returns(T.class_of(DSPy::Signature)) }
+    def create_thought_signature(signature_class, data_format)
       action_enum_class = @action_enum_class
+      input_context_type = if data_format == :toon
+        signature_class.input_struct_class || String
+      else
+        String
+      end
       # Create new class that inherits from DSPy::Signature
       Class.new(DSPy::Signature) do
         # Set description
@@ -251,8 +279,8 @@ module DSPy
 
         # Define input fields
         input do
-          const :input_context, String,
-            description: "Serialized representation of all input fields"
+          const :input_context, input_context_type,
+            description: data_format == :toon ? "All original input fields with their typed values" : "Serialized representation of all input fields"
           const :history, T::Array[HistoryEntry],
             description: "Previous thoughts and actions, including observations from tools."
           const :available_tools, T::Array[AvailableTool],
@@ -272,8 +300,13 @@ module DSPy
     end
 
     # Creates a dynamic observation signature that includes the original input fields
-    sig { params(signature_class: T.class_of(DSPy::Signature)).returns(T.class_of(DSPy::Signature)) }
-    def create_observation_signature(signature_class)
+    sig { params(signature_class: T.class_of(DSPy::Signature), data_format: Symbol).returns(T.class_of(DSPy::Signature)) }
+    def create_observation_signature(signature_class, data_format)
+      input_context_type = if data_format == :toon
+        signature_class.input_struct_class || String
+      else
+        String
+      end
       # Create new class that inherits from DSPy::Signature
       Class.new(DSPy::Signature) do
         # Set description
@@ -281,8 +314,8 @@ module DSPy
 
         # Define input fields
         input do
-          const :input_context, String,
-            description: "Serialized representation of all input fields"
+          const :input_context, input_context_type,
+            description: data_format == :toon ? "All original input fields with their typed values" : "Serialized representation of all input fields"
           const :history, T::Array[HistoryEntry],
             description: "Previous thoughts, actions, and observations."
           const :observation, T.untyped,
@@ -358,8 +391,8 @@ module DSPy
       ) do
         # Generate thought and action
         thought_obj = @thought_generator.forward(
-          input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
-          history: serialize_history_for_llm(history),
+          input_context: format_input_context(input_struct),
+          history: format_history(history),
           available_tools: available_tools_desc
         )
 
@@ -617,9 +650,9 @@ module DSPy
     sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], observation: T.untyped, available_tools_desc: T::Array[AvailableTool], iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
     def process_observation_and_decide_next_step(input_struct, history, observation, available_tools_desc, iteration)
       observation_result = @observation_processor.forward(
-        input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
-        history: serialize_history_for_llm(history),
-        observation: serialize_for_llm(observation)
+        input_context: format_input_context(input_struct),
+        history: format_history(history),
+        observation: format_observation(observation)
       )
 
       return { should_finish: false } unless observation_result.next_step == NextStep::Finish
@@ -634,8 +667,8 @@ module DSPy
     sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], available_tools_desc: T::Array[AvailableTool], observation_result: T.untyped, iteration: Integer).returns(T.untyped) }
     def generate_forced_final_answer(input_struct, history, available_tools_desc, observation_result, iteration)
       final_thought = @thought_generator.forward(
-        input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
-        history: serialize_history_for_llm(history),
+        input_context: format_input_context(input_struct),
+        history: format_history(history),
         available_tools: available_tools_desc
       )
 

data/lib/dspy/schema/sorbet_json_schema.rb

@@ -254,10 +254,13 @@ module DSPy
                                        "DSPy uses _type for automatic type detection in union types."
         end
 
+        struct_name = struct_class.name || "Struct#{format('%x', struct_class.object_id)}"
+        simple_name = struct_name.split('::').last || struct_name
+
         # Add automatic _type field for type detection
         properties[:_type] = {
           type: "string",
-          const: struct_class.name.split('::').last  # Use the simple class name
+          const: simple_name  # Use the simple class name
         }
         required << "_type"
 
@@ -280,7 +283,7 @@ module DSPy
           type: "object",
           properties: properties,
           required: required,
-          description: "#{struct_class.name} struct"
+          description: "#{struct_name} struct"
         }
       end