dspy 0.28.2 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1cc0ac1e2e1dc27f6255b11ca70ff0ad0eb37b5ae50ff38b97ae7d35b7b69b8
-  data.tar.gz: 2399987757b4f037080632e646714e785328fbe3c1fd39138fe750336cdd7710
+  metadata.gz: 747119ce407283e4d8ed5f01014262f24a94418ad2cbef4305a28b21cb58c8bc
+  data.tar.gz: 3693faccd1fca98015864fd4404491b619b2aa600ab83a78dd3fc7d9e3342ef1
 SHA512:
-  metadata.gz: ea48762186d3de89a005e8eac27f57ca90b294c4ab096ec1c7985d06396216d719ca3a2144406d1f43af472a560670e502329a785d33b8923b5c9c4c0f83dfd1
-  data.tar.gz: 98fee1468f2692a0f7cc87622722f945dbc344fb299e71935ef592bc1d59e68e48e1390208981b6263998627dacb38dc325727cc191f81e1db79fff57c1537a4
+  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/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

@@ -67,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)
         
@@ -271,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
@@ -293,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
       
@@ -410,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

@@ -105,5 +105,16 @@ module DSPy
         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

data/lib/dspy/observability/async_span_processor.rb

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
-require 'async'
-require 'async/queue'
-require 'async/barrier'
+require 'concurrent-ruby'
+require 'thread'
 require 'opentelemetry/sdk'
 require 'opentelemetry/sdk/trace/export'
 
 module DSPy
   class Observability
-    # AsyncSpanProcessor provides truly non-blocking span export using Async gem.
-    # Spans are queued and exported using async tasks with fiber-based concurrency.
+    # AsyncSpanProcessor provides non-blocking span export using concurrent-ruby.
+    # Spans are queued and exported on a dedicated single-thread executor to avoid blocking clients.
     # Implements the same interface as OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor
     class AsyncSpanProcessor
       # Default configuration values
@@ -33,12 +32,12 @@ module DSPy
         @export_batch_size = export_batch_size
         @shutdown_timeout = shutdown_timeout
         @max_retries = max_retries
+        @export_executor = Concurrent::SingleThreadExecutor.new
 
         # Use thread-safe queue for cross-fiber communication
         @queue = Thread::Queue.new
-        @barrier = Async::Barrier.new
         @shutdown_requested = false
-        @export_task = nil
+        @timer_thread = nil
 
         start_export_task
       end
@@ -85,22 +84,35 @@ module DSPy
 
         begin
           # Export any remaining spans
-          export_remaining_spans
+          result = export_remaining_spans(timeout: timeout, export_all: true)
 
-          # Shutdown exporter
-          @exporter.shutdown(timeout: timeout)
+          future = Concurrent::Promises.future_on(@export_executor) do
+            @exporter.shutdown(timeout: timeout)
+          end
+          future.value!(timeout)
 
-          OpenTelemetry::SDK::Trace::Export::SUCCESS
+          result
         rescue => e
           DSPy.log('observability.shutdown_error', error: e.message, class: e.class.name)
           OpenTelemetry::SDK::Trace::Export::FAILURE
+        ensure
+          begin
+            @timer_thread&.join(timeout)
+            @timer_thread&.kill if @timer_thread&.alive?
+          rescue StandardError
+            # ignore timer shutdown issues
+          end
+          @export_executor.shutdown
+          unless @export_executor.wait_for_termination(timeout)
+            @export_executor.kill
+          end
         end
       end
 
       def force_flush(timeout: nil)
         return OpenTelemetry::SDK::Trace::Export::SUCCESS if @queue.empty?
 
-        export_remaining_spans
+        export_remaining_spans(timeout: timeout, export_all: true)
       end
 
       private
@@ -109,19 +121,15 @@ module DSPy
         return if @export_interval <= 0 # Disable timer for testing
         return if ENV['DSPY_DISABLE_OBSERVABILITY'] == 'true' # Skip in tests
 
-        # Start timer-based export task in background
-        Thread.new do
+        @timer_thread = Thread.new do
           loop do
             break if @shutdown_requested
 
             sleep(@export_interval)
+            break if @shutdown_requested
+            next if @queue.empty?
 
-            # Export queued spans in sync block
-            unless @queue.empty?
-              Sync do
-                export_queued_spans
-              end
-            end
+            schedule_async_export(export_all: true)
           end
         rescue => e
           DSPy.log('observability.export_task_error', error: e.message, class: e.class.name)
@@ -131,39 +139,56 @@ module DSPy
       def trigger_export_if_batch_full
         return if @queue.size < @export_batch_size
         return if ENV['DSPY_DISABLE_OBSERVABILITY'] == 'true' # Skip in tests
+        schedule_async_export(export_all: false)
+      end
 
-        # Trigger immediate export in background
-        Thread.new do
-          Sync do
-            export_queued_spans
-          end
-        rescue => e
-          DSPy.log('observability.batch_export_error', error: e.message)
+      def export_remaining_spans(timeout: nil, export_all: true)
+        return OpenTelemetry::SDK::Trace::Export::SUCCESS if @queue.empty?
+
+        future = Concurrent::Promises.future_on(@export_executor) do
+          export_queued_spans_internal(export_all: export_all)
         end
+
+        future.value!(timeout || @shutdown_timeout)
+      rescue => e
+        DSPy.log('observability.export_error', error: e.message, class: e.class.name)
+        OpenTelemetry::SDK::Trace::Export::FAILURE
       end
 
-      def export_remaining_spans
-        spans = []
+      def schedule_async_export(export_all: false)
+        return if @shutdown_requested
 
-        # Drain entire queue
-        until @queue.empty?
-          begin
-            spans << @queue.pop(true) # non-blocking pop
-          rescue ThreadError
-            break
-          end
+        @export_executor.post do
+          export_queued_spans_internal(export_all: export_all)
+        rescue => e
+          DSPy.log('observability.batch_export_error', error: e.message, class: e.class.name)
         end
+      end
+
+      def export_queued_spans
+        export_queued_spans_internal(export_all: false)
+      end
+
+      def export_queued_spans_internal(export_all: false)
+        result = OpenTelemetry::SDK::Trace::Export::SUCCESS
+
+        loop do
+          spans = dequeue_spans(export_all ? @queue_size : @export_batch_size)
+          break if spans.empty?
 
-        return OpenTelemetry::SDK::Trace::Export::SUCCESS if spans.empty?
+          result = export_spans_with_retry(spans)
+          break if result == OpenTelemetry::SDK::Trace::Export::FAILURE
 
-        export_spans_with_retry(spans)
+          break unless export_all || @queue.size >= @export_batch_size
+        end
+
+        result
       end
 
-      def export_queued_spans
+      def dequeue_spans(limit)
         spans = []
 
-        # Collect up to batch size
-        @export_batch_size.times do
+        limit.times do
           begin
             spans << @queue.pop(true) # non-blocking pop
           rescue ThreadError
@@ -171,12 +196,7 @@ module DSPy
           end
         end
 
-        return if spans.empty?
-
-        # Export using async I/O
-        Sync do
-          export_spans_with_retry_async(spans)
-        end
+        spans
       end
 
       def export_spans_with_retry(spans)
@@ -225,52 +245,6 @@ module DSPy
         OpenTelemetry::SDK::Trace::Export::FAILURE
       end
 
-      def export_spans_with_retry_async(spans)
-        retries = 0
-
-        # Convert spans to SpanData objects (required by OTLP exporter)
-        span_data_batch = spans.map(&:to_span_data)
-        
-        # Log export attempt
-        DSPy.log('observability.export_attempt',
-                 spans_count: span_data_batch.size,
-                 batch_size: span_data_batch.size)
-
-        loop do
-          # Use current async task for potentially non-blocking export
-          result = @exporter.export(span_data_batch, timeout: @shutdown_timeout)
-
-          case result
-          when OpenTelemetry::SDK::Trace::Export::SUCCESS
-            DSPy.log('observability.export_success',
-                     spans_count: span_data_batch.size,
-                     export_result: 'SUCCESS')
-            return result
-          when OpenTelemetry::SDK::Trace::Export::FAILURE
-            retries += 1
-            if retries <= @max_retries
-              backoff_seconds = 0.1 * (2 ** retries)
-              DSPy.log('observability.export_retry',
-                       attempt: retries,
-                       spans_count: span_data_batch.size,
-                       backoff_seconds: backoff_seconds)
-              # Async sleep for exponential backoff
-              Async::Task.current.sleep(backoff_seconds)
-              next
-            else
-              DSPy.log('observability.export_failed',
-                       spans_count: span_data_batch.size,
-                       retries: retries)
-              return result
-            end
-          else
-            return result
-          end
-        end
-      rescue => e
-        DSPy.log('observability.export_error', error: e.message, class: e.class.name)
-        OpenTelemetry::SDK::Trace::Export::FAILURE
-      end
     end
   end
 end

data/lib/dspy/observability.rb

@@ -41,6 +41,8 @@ module DSPy
           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}")
           
@@ -150,6 +152,46 @@ module DSPy
         @tracer = nil
         @endpoint = nil
       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)
+      end
     end
   end
-end
+end

data/lib/dspy/predict.rb

@@ -138,6 +138,16 @@ module DSPy
       with_prompt(@prompt.add_examples(examples))
     end
 
+    sig { override.returns(T::Array[[String, DSPy::Module]]) }
+    def named_predictors
+      [["self", self]]
+    end
+
+    sig { override.returns(T::Array[DSPy::Module]) }
+    def predictors
+      [self]
+    end
+
     # Remove forward override to let Module#forward handle span creation
 
     sig { params(input_values: T.untyped).returns(T.untyped) }

data/lib/dspy/propose/dataset_summary_generator.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require 'sorbet-runtime'
+require 'json'
 require_relative '../signature'
 require_relative '../predict'
+require_relative '../type_serializer'
+require_relative '../few_shot_example'
 
 module DSPy
   module Propose
@@ -119,9 +122,10 @@ module DSPy
         DSPy.with_lm(lm) do
           # Initial observation from first batch
           upper_lim = [trainset.length, view_data_batch_size].min
-          examples_repr = order_input_keys_in_string(trainset[0...upper_lim].inspect)
-
+          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)
           observations = observation.observations
 
@@ -138,9 +142,11 @@ module DSPy
               puts "Processing batch starting at index #{b}" if verbose
 
               upper_lim = [trainset.length, b + view_data_batch_size].min
-              examples_repr = order_input_keys_in_string(trainset[b...upper_lim].inspect)
 
               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
@@ -172,6 +178,33 @@ module DSPy
           strip_prefix(summary.summary)
         end
       end
+
+      sig { params(examples: T::Array[T.untyped]).returns(String) }
+      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)
+            }
+          when DSPy::FewShotExample
+            base = {
+              input: example.input,
+              output: example.output
+            }
+            base[:reasoning] = example.reasoning if example.reasoning
+            base
+          when Hash
+            example
+          else
+            example.respond_to?(:to_h) ? example.to_h : { value: example }
+          end
+        end
+
+        JSON.pretty_generate(serialized_examples)
+      end
     end
   end
 end