dspy 0.28.1 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b377060443eeb9c3c5d975e76750d6c519d1b93cf6f20dc6ad20bcda08d1ca4
-  data.tar.gz: 4580845b3fd9991b531c8c2bd809595cbd3328da57a23e58307cdbe52e3822bc
+  metadata.gz: 747119ce407283e4d8ed5f01014262f24a94418ad2cbef4305a28b21cb58c8bc
+  data.tar.gz: 3693faccd1fca98015864fd4404491b619b2aa600ab83a78dd3fc7d9e3342ef1
 SHA512:
-  metadata.gz: 444a5e08364b2e996bf49d230cb9a94a1930e26d2ea796cd0104ea4888b45ade4099cec502b92c08752631adff47b1d9d1897da9209e9faabbb28fb6761935b0
-  data.tar.gz: c1b3a83482c861923304c463d6f0b1c9042fbc31da920526ec18ed0f5148b4408a9023d312eded9263ca2d706e4779b78526e28dc50a17458cbbac9afa56b024
+  metadata.gz: 7fecac3bc3389e11bdb2328234455cbbbcbf6c7544518cbf94082e75a3f0bde489339b70f91dfd31a43bbd87b17451bfb5a78387c90f5b669aefa09e8af73500
+  data.tar.gz: 01feee252179dd66016a8633658631dacc2262f5598ee07d4f78ec2947ebbb57cd15b19b433b8ea9a87b7120fbf5afa984fd929677de0fcfaf7a4368e5b29d85

data/README.md

@@ -112,7 +112,6 @@ end
 - **Typed Examples** - Type-safe training data with automatic validation
 - **Evaluation Framework** - Advanced metrics beyond simple accuracy with error-resilient pipelines
 - **MIPROv2 Optimization** - Advanced Bayesian optimization with Gaussian Processes, multiple optimization strategies, and storage persistence
-- **GEPA Optimization** - Genetic-Pareto optimization for multi-objective prompt improvement
 
 **Production Features:**
 - **Reliable JSON Extraction** - Native structured outputs for OpenAI and Gemini, Anthropic tool-based extraction, and automatic strategy selection with fallback
@@ -168,11 +167,11 @@ For LLMs and AI assistants working with DSPy.rb:
 - **[Evaluation Framework](docs/src/optimization/evaluation.md)** - Advanced metrics beyond simple accuracy
 - **[Prompt Optimization](docs/src/optimization/prompt-optimization.md)** - Manipulate prompts as objects
 - **[MIPROv2 Optimizer](docs/src/optimization/miprov2.md)** - Advanced Bayesian optimization with Gaussian Processes
-- **[GEPA Optimizer](docs/src/optimization/gepa.md)** - Genetic-Pareto optimization for multi-objective prompt optimization
+- **[GEPA Optimizer](docs/src/optimization/gepa.md)** *(beta)* - Reflective mutation with optional reflection LMs
 
 ### Production Features
 - **[Storage System](docs/src/production/storage.md)** - Persistence and optimization result storage
-- **[Observability](docs/src/production/observability.md)** - Zero-config Langfuse integration and structured logging
+- **[Observability](docs/src/production/observability.md)** - Zero-config Langfuse integration with a dedicated export worker that never blocks your LLMs
 
 ### Advanced Usage
 - **[Complex Types](docs/src/advanced/complex-types.md)** - Sorbet type integration with automatic coercion for structs, enums, and arrays

data/lib/dspy/callbacks.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  # Provides Rails-style callback hooks for DSPy modules
+  #
+  # @example Define callbacks in base class
+  #   class DSPy::Module
+  #     include DSPy::Callbacks
+  #
+  #     create_before_callback :forward
+  #     create_after_callback :forward
+  #     create_around_callback :forward
+  #   end
+  #
+  # @example Use callbacks in subclasses
+  #   class MyAgent < DSPy::Module
+  #     before :setup_context
+  #     after :log_metrics
+  #     around :manage_memory
+  #
+  #     private
+  #
+  #     def setup_context
+  #       @start_time = Time.now
+  #     end
+  #
+  #     def log_metrics
+  #       puts "Duration: #{Time.now - @start_time}"
+  #     end
+  #
+  #     def manage_memory
+  #       load_context
+  #       yield
+  #       save_context
+  #     end
+  #   end
+  module Callbacks
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Creates a before callback hook for the specified method
+      #
+      # @param method_name [Symbol] the method to add callback support to
+      def create_before_callback(method_name)
+        mark_method_has_callbacks(method_name)
+        ensure_callback_method_defined(:before, method_name)
+        wrap_method_with_callbacks(method_name)
+      end
+
+      # Creates an after callback hook for the specified method
+      #
+      # @param method_name [Symbol] the method to add callback support to
+      def create_after_callback(method_name)
+        mark_method_has_callbacks(method_name)
+        ensure_callback_method_defined(:after, method_name)
+        wrap_method_with_callbacks(method_name)
+      end
+
+      # Creates an around callback hook for the specified method
+      #
+      # @param method_name [Symbol] the method to add callback support to
+      def create_around_callback(method_name)
+        mark_method_has_callbacks(method_name)
+        ensure_callback_method_defined(:around, method_name)
+        wrap_method_with_callbacks(method_name)
+      end
+
+      private
+
+      # Ensures the callback registration method exists
+      def ensure_callback_method_defined(type, target_method_name)
+        return if singleton_class.method_defined?(type)
+
+        define_singleton_method(type) do |callback_method|
+          register_callback(type, target_method_name, callback_method)
+        end
+      end
+
+      # Registers a callback for execution
+      def register_callback(type, method_name, callback_method)
+        own_callbacks_for(method_name)[type] ||= []
+        own_callbacks_for(method_name)[type] << callback_method
+      end
+
+      # Returns own callbacks (not including parent)
+      def own_callbacks_for(method_name)
+        @callbacks ||= {}
+        @callbacks[method_name] ||= {}
+      end
+
+      # Marks that a method has callback support (even if no callbacks registered yet)
+      def mark_method_has_callbacks(method_name)
+        own_callbacks_for(method_name)
+      end
+
+      # Returns the callback registry for a method
+      # Includes callbacks from parent classes
+      def callbacks_for(method_name)
+        own_callbacks = own_callbacks_for(method_name)
+
+        # Merge parent callbacks if this is a subclass
+        if superclass.respond_to?(:callbacks_for, true)
+          parent_callbacks = superclass.send(:callbacks_for, method_name)
+
+          # Merge each callback type, with own callbacks coming after parent callbacks
+          merged_callbacks = {}
+          [:before, :after, :around].each do |type|
+            parent_list = parent_callbacks[type] || []
+            own_list = own_callbacks[type] || []
+            merged_callbacks[type] = parent_list + own_list if parent_list.any? || own_list.any?
+          end
+
+          merged_callbacks
+        else
+          own_callbacks
+        end
+      end
+
+      # Wraps a method with callback execution logic
+      def wrap_method_with_callbacks(method_name)
+        return if method_wrapped?(method_name)
+
+        # Defer wrapping if method doesn't exist yet
+        return unless method_defined?(method_name)
+
+        # Mark as wrapped BEFORE define_method to prevent infinite recursion
+        mark_method_wrapped(method_name)
+
+        original_method = instance_method(method_name)
+
+        define_method(method_name) do |*args, **kwargs, &block|
+          # Execute before callbacks
+          run_callbacks(:before, method_name)
+
+          # Execute around callbacks or original method
+          result = if self.class.send(:has_around_callbacks?, method_name)
+            execute_with_around_callbacks(method_name, original_method, *args, **kwargs, &block)
+          else
+            original_method.bind(self).call(*args, **kwargs, &block)
+          end
+
+          # Execute after callbacks
+          run_callbacks(:after, method_name)
+
+          result
+        end
+      end
+
+      # Checks if method has around callbacks
+      def has_around_callbacks?(method_name)
+        callbacks_for(method_name)[:around]&.any?
+      end
+
+      # Hook into method_added to wrap methods when they're defined
+      def method_added(method_name)
+        super
+
+        # Check if this method or any parent has callback support (even if no callbacks registered yet)
+        has_callback_support = method_has_callback_support?(method_name)
+
+        return unless has_callback_support
+        return if method_wrapped?(method_name)
+
+        wrap_method_with_callbacks(method_name)
+      end
+
+      # Checks if a method has callback support in this class or parents
+      def method_has_callback_support?(method_name)
+        # Check own callbacks registry
+        return true if @callbacks&.key?(method_name)
+
+        # Check parent class
+        if superclass.respond_to?(:method_has_callback_support?, true)
+          superclass.send(:method_has_callback_support?, method_name)
+        else
+          false
+        end
+      end
+
+      # Marks a method as wrapped
+      def mark_method_wrapped(method_name)
+        @wrapped_methods ||= []
+        @wrapped_methods << method_name
+      end
+
+      # Checks if method is already wrapped
+      def method_wrapped?(method_name)
+        @wrapped_methods&.include?(method_name)
+      end
+    end
+
+    private
+
+    # Executes callbacks of a specific type
+    def run_callbacks(type, method_name)
+      callbacks = self.class.send(:callbacks_for, method_name)[type]
+      return unless callbacks
+
+      callbacks.each do |callback_method|
+        send(callback_method)
+      end
+    end
+
+    # 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]
+
+      # Build callback chain from innermost (original method) to outermost
+      chain = callbacks.reverse.inject(
+        -> { original_method.bind(self).call(*args, **kwargs, &block) }
+      ) do |inner, callback_method|
+        -> { send(callback_method) { inner.call } }
+      end
+
+      chain.call
+    end
+  end
+end

data/lib/dspy/chain_of_thought.rb

@@ -46,7 +46,8 @@ module DSPy
         input_schema: @signature_class.input_json_schema,
         output_schema: @signature_class.output_json_schema,
         few_shot_examples: new_prompt.few_shot_examples,
-        signature_class_name: @signature_class.name
+        signature_class_name: @signature_class.name,
+        schema_format: new_prompt.schema_format
       )
       
       instance.instance_variable_set(:@prompt, enhanced_prompt)

data/lib/dspy/code_act.rb

@@ -146,6 +146,19 @@ module DSPy
       super(enhanced_signature)
     end
 
+    sig { override.returns(T::Array[[String, DSPy::Module]]) }
+    def named_predictors
+      pairs = T.let([], T::Array[[String, DSPy::Module]])
+      pairs << ["code_generator", @code_generator]
+      pairs << ["observation_processor", @observation_processor]
+      pairs
+    end
+
+    sig { override.returns(T::Array[DSPy::Module]) }
+    def predictors
+      named_predictors.map { |(_, predictor)| predictor }
+    end
+
     sig { params(kwargs: T.untyped).returns(T.untyped).override }
     def forward(**kwargs)
       # Validate input and serialize all fields as task context
@@ -461,4 +474,4 @@ module DSPy
       example
     end
   end
-end
+end

data/lib/dspy/datasets/ade.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require 'cgi'
+require 'fileutils'
+
+module DSPy
+  module Datasets
+    module ADE
+      extend self
+
+      DATASET = 'ade-benchmark-corpus/ade_corpus_v2'
+      CLASSIFICATION_CONFIG = 'Ade_corpus_v2_classification'
+      BASE_URL = 'https://datasets-server.huggingface.co'
+
+      DEFAULT_CACHE_DIR = File.expand_path('../../../tmp/dspy_datasets/ade', __dir__)
+
+      MAX_BATCH_SIZE = 100
+
+      def examples(split: 'train', limit: 200, offset: 0, cache_dir: default_cache_dir)
+        remaining = limit
+        current_offset = offset
+        collected = []
+
+        while remaining.positive?
+          batch_size = [remaining, MAX_BATCH_SIZE].min
+          rows = fetch_rows(
+            split: split,
+            limit: batch_size,
+            offset: current_offset,
+            cache_dir: cache_dir
+          )
+
+          break if rows.empty?
+
+          collected.concat(rows.map do |row|
+            {
+              'text' => row.fetch('text', ''),
+              'label' => row.fetch('label', 0).to_i
+            }
+          end)
+
+          current_offset += batch_size
+          remaining -= batch_size
+        end
+
+        collected
+      end
+
+      def fetch_rows(split:, limit:, offset:, cache_dir:)
+        FileUtils.mkdir_p(cache_dir)
+        cache_path = File.join(cache_dir, "#{CLASSIFICATION_CONFIG}_#{split}_#{offset}_#{limit}.json")
+
+        if File.exist?(cache_path)
+          return JSON.parse(File.read(cache_path))
+        end
+
+        rows = request_rows(split: split, limit: limit, offset: offset)
+        File.write(cache_path, JSON.pretty_generate(rows))
+        rows
+      end
+
+      private
+
+      def request_rows(split:, limit:, offset:)
+        uri = URI("#{BASE_URL}/rows")
+        params = {
+          dataset: DATASET,
+          config: CLASSIFICATION_CONFIG,
+          split: split,
+          offset: offset,
+          length: limit
+        }
+        uri.query = URI.encode_www_form(params)
+
+        response = Net::HTTP.get_response(uri)
+        raise "ADE dataset request failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        body = JSON.parse(response.body)
+        body.fetch('rows', []).map { |row| row.fetch('row', {}) }
+      end
+
+      def default_cache_dir
+        ENV['DSPY_DATASETS_CACHE'] ? File.expand_path('ade', ENV['DSPY_DATASETS_CACHE']) : DEFAULT_CACHE_DIR
+      end
+    end
+  end
+end

data/lib/dspy/datasets.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'datasets/ade'
+
+module DSPy
+  module Datasets
+  end
+end

data/lib/dspy/lm.rb

@@ -31,15 +31,16 @@ require_relative 'structured_outputs_prompt'
 module DSPy
   class LM
     extend T::Sig
-    attr_reader :model_id, :api_key, :model, :provider, :adapter
+    attr_reader :model_id, :api_key, :model, :provider, :adapter, :schema_format
 
-    def initialize(model_id, api_key: nil, **options)
+    def initialize(model_id, api_key: nil, schema_format: :json, **options)
       @model_id = model_id
       @api_key = api_key
-      
+      @schema_format = schema_format
+
       # Parse provider and model from model_id
       @provider, @model = parse_model_id(model_id)
-      
+
       # Create appropriate adapter with options
       @adapter = AdapterFactory.create(model_id, api_key: api_key, **options)
     end
@@ -66,9 +67,6 @@ module DSPy
           chat_with_strategy(messages, signature_class, &block)
         end
 
-        # Emit the standard lm.tokens event (consistent with raw_chat)
-        emit_token_usage(response, signature_class.name)
-
         # Parse response (no longer needs separate instrumentation)
         parsed_result = parse_response(response, input_values, signature_class)
         
@@ -270,7 +268,7 @@ module DSPy
         'dspy.signature' => signature_class_name
       ) do |span|
         result = execution_block.call
-        
+
         # Add output and usage data directly to span
         if span && result
           # Add completion output
@@ -292,7 +290,9 @@ module DSPy
             span.set_attribute('gen_ai.usage.total_tokens', usage.total_tokens) if usage.total_tokens
           end
         end
-        
+
+        emit_token_usage(result, signature_class_name)
+
         result
       end
       
@@ -409,9 +409,6 @@ module DSPy
           adapter.chat(messages: hash_messages, signature: nil, &streaming_block)
         end
         
-        # Emit the standard lm.tokens event (consistent with other LM calls)
-        emit_token_usage(response, 'RawPrompt')
-        
         # Return raw response content, not parsed JSON
         response.content
       ensure

data/lib/dspy/mixins/struct_builder.rb

@@ -19,20 +19,20 @@ module DSPy
         
         Class.new(T::Struct) do
           extend T::Sig
+          define_field = lambda do |name, type, options|
+            const_kwargs = {}
+            const_kwargs[:default] = options[:default] if options.key?(:default)
+            const_kwargs[:factory] = options[:factory] if options.key?(:factory)
+            const_kwargs[:override] = true if props.key?(name)
+            const name, type, **const_kwargs
+          end
           
           # Add properties from each source
           property_sources.each do |_source_name, props|
             props.each do |name, prop|
               type = builder.send(:extract_type_from_prop, prop)
               options = builder.send(:extract_options_from_prop, prop)
-              
-              if options[:default]
-                const name, type, default: options[:default]
-              elsif options[:factory]
-                const name, type, factory: options[:factory]
-              else
-                const name, type
-              end
+              define_field.call(name, type, options)
             end
           end
           
@@ -40,14 +40,7 @@ module DSPy
           additional_fields.each do |name, field_config|
             type = builder.send(:extract_type_from_prop, field_config)
             options = builder.send(:extract_options_from_prop, field_config)
-            
-            if options[:default]
-              const name, type, default: options[:default]
-            elsif options[:factory]
-              const name, type, factory: options[:factory]
-            else
-              const name, type
-            end
+            define_field.call(name, type, options)
           end
           
           include StructSerialization
@@ -65,14 +58,13 @@ module DSPy
       def build_single_property(name, prop)
         type = extract_type_from_prop(prop)
         options = extract_options_from_prop(prop)
-        
-        if options[:default]
-          const name, type, default: options[:default]
-        elsif options[:factory]
-          const name, type, factory: options[:factory]
-        else
-          const name, type
-        end
+
+        const_kwargs = {}
+        const_kwargs[:default] = options[:default] if options.key?(:default)
+        const_kwargs[:factory] = options[:factory] if options.key?(:factory)
+        const_kwargs[:override] = true if respond_to?(:props) && props.key?(name)
+
+        const name, type, **const_kwargs
       end
 
       # Extracts type from property configuration
@@ -142,4 +134,4 @@ module DSPy
       end
     end
   end
-end
+end

data/lib/dspy/module.rb

@@ -3,16 +3,23 @@
 require 'sorbet-runtime'
 require 'dry-configurable'
 require_relative 'context'
+require_relative 'callbacks'
 
 module DSPy
   class Module
     extend T::Sig
     extend T::Generic
     include Dry::Configurable
+    include DSPy::Callbacks
 
     # Per-instance LM configuration
     setting :lm, default: nil
 
+    # Define callback hooks for forward method
+    create_before_callback :forward
+    create_after_callback :forward
+    create_around_callback :forward
+
     # The main forward method that users will call is generic and type parameterized
     sig do
       type_parameters(:I, :O)
@@ -72,5 +79,42 @@ module DSPy
     def lm
       config.lm || DSPy.current_lm
     end
+
+    # Save the module state to a JSON file
+    # Lightweight serialization for intermediate optimization trials
+    #
+    # @param path [String] Path to save the module state (JSON format)
+    sig { params(path: String).void }
+    def save(path)
+      require 'json'
+      require 'fileutils'
+
+      # Ensure parent directory exists
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+
+      # Serialize module to JSON
+      File.write(path, JSON.pretty_generate(to_h))
+    end
+
+    # Default serialization method - subclasses can override
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      {
+        class_name: self.class.name,
+        state: {}
+      }
+    end
+
+    # Discover nested predictor modules (Python parity helper)
+    sig { returns(T::Array[[String, DSPy::Module]]) }
+    def named_predictors
+      []
+    end
+
+    sig { returns(T::Array[DSPy::Module]) }
+    def predictors
+      named_predictors.map { |(_, predictor)| predictor }
+    end
   end
-end
+end