dspy 0.28.1 → 0.29.0

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

@@ -53,11 +53,18 @@ module DSPy
     sig { returns(Prompt) }
     attr_reader :prompt
 
+    # Mutable demos attribute for MIPROv2 compatibility
+    sig { returns(T.nilable(T::Array[FewShotExample])) }
+    attr_accessor :demos
+
     sig { params(signature_class: T.class_of(Signature)).void }
     def initialize(signature_class)
       super()
       @signature_class = signature_class
+
+      # Prompt will read schema_format from config automatically
       @prompt = Prompt.from_signature(signature_class)
+      @demos = nil
     end
 
     # Reconstruct program from serialized hash
@@ -131,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/prompt.rb

@@ -22,21 +22,39 @@ module DSPy
     sig { returns(T.nilable(String)) }
     attr_reader :signature_class_name
 
+    # Returns the effective schema format
+    # Precedence: instance variable (if not :json default) > config.lm > :json
+    sig { returns(Symbol) }
+    def schema_format
+      # If @schema_format was explicitly set to something other than :json, respect it
+      return @schema_format if @schema_format && @schema_format != :json
+
+      # Otherwise, read from config if available
+      DSPy.config.lm&.schema_format || @schema_format || :json
+    end
+
+    sig { returns(T.nilable(T.class_of(Signature))) }
+    attr_reader :signature_class
+
     sig do
       params(
         instruction: String,
         input_schema: T::Hash[Symbol, T.untyped],
         output_schema: T::Hash[Symbol, T.untyped],
         few_shot_examples: T::Array[FewShotExample],
-        signature_class_name: T.nilable(String)
+        signature_class_name: T.nilable(String),
+        schema_format: Symbol,
+        signature_class: T.nilable(T.class_of(Signature))
       ).void
     end
-    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil)
+    def initialize(instruction:, input_schema:, output_schema:, few_shot_examples: [], signature_class_name: nil, schema_format: :json, signature_class: nil)
       @instruction = instruction
       @few_shot_examples = few_shot_examples.freeze
       @input_schema = input_schema.freeze
       @output_schema = output_schema.freeze
       @signature_class_name = signature_class_name
+      @schema_format = schema_format
+      @signature_class = signature_class
     end
 
     # Immutable update methods for optimization
@@ -47,7 +65,9 @@ module DSPy
         input_schema: @input_schema,
         output_schema: @output_schema,
         few_shot_examples: @few_shot_examples,
-        signature_class_name: @signature_class_name
+        signature_class_name: @signature_class_name,
+        schema_format: @schema_format,
+        signature_class: @signature_class
       )
     end
 
@@ -58,7 +78,9 @@ module DSPy
         input_schema: @input_schema,
         output_schema: @output_schema,
         few_shot_examples: new_examples,
-        signature_class_name: @signature_class_name
+        signature_class_name: @signature_class_name,
+        schema_format: @schema_format,
+        signature_class: @signature_class
       )
     end
 
@@ -72,16 +94,29 @@ module DSPy
     sig { returns(String) }
     def render_system_prompt
       sections = []
-      
-      sections << "Your input schema fields are:"
-      sections << "```json"
-      sections << JSON.pretty_generate(@input_schema)
-      sections << "```"
-      
-      sections << "Your output schema fields are:"
-      sections << "```json"
-      sections << JSON.pretty_generate(@output_schema)
-      sections << "```"
+
+      case schema_format
+      when :baml
+        sections << "Your input schema fields are:"
+        sections << "```baml"
+        sections << render_baml_schema(@input_schema, :input)
+        sections << "```"
+
+        sections << "Your output schema fields are:"
+        sections << "```baml"
+        sections << render_baml_schema(@output_schema, :output)
+        sections << "```"
+      else  # :json (default)
+        sections << "Your input schema fields are:"
+        sections << "```json"
+        sections << JSON.pretty_generate(@input_schema)
+        sections << "```"
+
+        sections << "Your output schema fields are:"
+        sections << "```json"
+        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."
@@ -148,32 +183,36 @@ module DSPy
         few_shot_examples: @few_shot_examples.map(&:to_h),
         input_schema: @input_schema,
         output_schema: @output_schema,
-        signature_class_name: @signature_class_name
+        signature_class_name: @signature_class_name,
+        schema_format: @schema_format
       }
     end
 
     sig { params(hash: T::Hash[Symbol, T.untyped]).returns(Prompt) }
     def self.from_h(hash)
       examples = (hash[:few_shot_examples] || []).map { |ex| FewShotExample.from_h(ex) }
-      
+
       new(
         instruction: hash[:instruction] || "",
         input_schema: hash[:input_schema] || {},
         output_schema: hash[:output_schema] || {},
         few_shot_examples: examples,
-        signature_class_name: hash[:signature_class_name]
+        signature_class_name: hash[:signature_class_name],
+        schema_format: hash[:schema_format] || :json
       )
     end
 
     # Create prompt from signature class
-    sig { params(signature_class: T.class_of(Signature)).returns(Prompt) }
-    def self.from_signature(signature_class)
+    sig { params(signature_class: T.class_of(Signature), schema_format: Symbol).returns(Prompt) }
+    def self.from_signature(signature_class, schema_format: :json)
       new(
         instruction: signature_class.description || "Complete this task.",
         input_schema: signature_class.input_json_schema,
         output_schema: signature_class.output_json_schema,
         few_shot_examples: [],
-        signature_class_name: signature_class.name
+        signature_class_name: signature_class.name,
+        schema_format: schema_format,
+        signature_class: signature_class
       )
     end
 
@@ -221,6 +260,37 @@ module DSPy
 
     private
 
+    # Render BAML schema for input or output
+    sig { params(schema: T::Hash[Symbol, T.untyped], type: Symbol).returns(String) }
+    def render_baml_schema(schema, type)
+      # If we have a signature_class, use sorbet-baml's to_baml method with custom name
+      if @signature_class
+        begin
+          require 'sorbet_baml'
+
+          struct_class = type == :input ? @signature_class.input_struct_class : @signature_class.output_struct_class
+          if struct_class
+            # Generate a proper class name from signature class name
+            base_name = @signature_class_name || @signature_class.name || "Schema"
+            class_name = type == :input ? "#{base_name}Input" : "#{base_name}Output"
+
+            # Get raw BAML and replace the ugly class name
+            raw_baml = struct_class.to_baml
+            # Replace the class definition line with a proper name
+            return raw_baml.sub(/^class #<Class:0x[0-9a-f]+>/, "class #{class_name}")
+          end
+        rescue LoadError
+          # Fall back to manual BAML generation if sorbet_baml is not available
+        end
+      end
+
+      # Fallback: generate BAML manually from schema
+      # This is a simple implementation that handles basic types
+      # For production use, sorbet-baml should be available
+      "# BAML schema generation requires sorbet-baml gem\n" \
+      "# Please install: gem install sorbet-baml"
+    end
+
     # Recursively serialize complex objects for JSON representation
     sig { params(obj: T.untyped).returns(T.untyped) }
     def serialize_for_json(obj)