dspy 0.29.0 → 0.30.0

data/lib/dspy/datasets/ade.rb

@@ -1,90 +0,0 @@
-# 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/observability/async_span_processor.rb

@@ -1,250 +0,0 @@
-# frozen_string_literal: true
-
-require 'concurrent-ruby'
-require 'thread'
-require 'opentelemetry/sdk'
-require 'opentelemetry/sdk/trace/export'
-
-module DSPy
-  class Observability
-    # 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
-      DEFAULT_QUEUE_SIZE = 1000
-      DEFAULT_EXPORT_INTERVAL = 60.0  # seconds
-      DEFAULT_EXPORT_BATCH_SIZE = 100
-      DEFAULT_SHUTDOWN_TIMEOUT = 10.0  # seconds
-      DEFAULT_MAX_RETRIES = 3
-
-      def initialize(
-        exporter,
-        queue_size: DEFAULT_QUEUE_SIZE,
-        export_interval: DEFAULT_EXPORT_INTERVAL,
-        export_batch_size: DEFAULT_EXPORT_BATCH_SIZE,
-        shutdown_timeout: DEFAULT_SHUTDOWN_TIMEOUT,
-        max_retries: DEFAULT_MAX_RETRIES
-      )
-        @exporter = exporter
-        @queue_size = queue_size
-        @export_interval = export_interval
-        @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
-        @shutdown_requested = false
-        @timer_thread = nil
-
-        start_export_task
-      end
-
-      def on_start(span, parent_context)
-        # Non-blocking - no operation needed on span start
-      end
-
-      def on_finish(span)
-        # Only process sampled spans to match BatchSpanProcessor behavior
-        return unless span.context.trace_flags.sampled?
-
-        # Non-blocking enqueue with overflow protection
-        # Note: on_finish is only called for already ended spans
-        begin
-          # Check queue size (non-blocking)
-          if @queue.size >= @queue_size
-            # Drop oldest span
-            begin
-              dropped_span = @queue.pop(true) # non-blocking pop
-              DSPy.log('observability.span_dropped',
-                       reason: 'queue_full',
-                       queue_size: @queue_size)
-            rescue ThreadError
-              # Queue was empty, continue
-            end
-          end
-
-          @queue.push(span)
-          
-          # Log span queuing activity
-          DSPy.log('observability.span_queued', queue_size: @queue.size)
-
-          # Trigger immediate export if batch size reached
-          trigger_export_if_batch_full
-        rescue => e
-          DSPy.log('observability.enqueue_error', error: e.message)
-        end
-      end
-
-      def shutdown(timeout: nil)
-        timeout ||= @shutdown_timeout
-        @shutdown_requested = true
-
-        begin
-          # Export any remaining spans
-          result = export_remaining_spans(timeout: timeout, export_all: true)
-
-          future = Concurrent::Promises.future_on(@export_executor) do
-            @exporter.shutdown(timeout: timeout)
-          end
-          future.value!(timeout)
-
-          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(timeout: timeout, export_all: true)
-      end
-
-      private
-
-      def start_export_task
-        return if @export_interval <= 0 # Disable timer for testing
-        return if ENV['DSPY_DISABLE_OBSERVABILITY'] == 'true' # Skip in tests
-
-        @timer_thread = Thread.new do
-          loop do
-            break if @shutdown_requested
-
-            sleep(@export_interval)
-            break if @shutdown_requested
-            next if @queue.empty?
-
-            schedule_async_export(export_all: true)
-          end
-        rescue => e
-          DSPy.log('observability.export_task_error', error: e.message, class: e.class.name)
-        end
-      end
-
-      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
-
-      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 schedule_async_export(export_all: false)
-        return if @shutdown_requested
-
-        @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?
-
-          result = export_spans_with_retry(spans)
-          break if result == OpenTelemetry::SDK::Trace::Export::FAILURE
-
-          break unless export_all || @queue.size >= @export_batch_size
-        end
-
-        result
-      end
-
-      def dequeue_spans(limit)
-        spans = []
-
-        limit.times do
-          begin
-            spans << @queue.pop(true) # non-blocking pop
-          rescue ThreadError
-            break
-          end
-        end
-
-        spans
-      end
-
-      def export_spans_with_retry(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
-          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)
-              # Exponential backoff
-              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/observation_type.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-require 'sorbet-runtime'
-
-module DSPy
-  # Langfuse observation types as a T::Enum for type safety
-  # Maps to the official Langfuse observation types: https://langfuse.com/docs/observability/features/observation-types
-  class ObservationType < T::Enum
-    enums do
-      # LLM generation calls - used for direct model inference
-      Generation = new('generation')
-      
-      # Agent operations - decision-making processes using tools/LLM guidance
-      Agent = new('agent')
-      
-      # External tool calls (APIs, functions, etc.)
-      Tool = new('tool')
-      
-      # Chains linking different application steps/components
-      Chain = new('chain')
-      
-      # Data retrieval operations (vector stores, databases, memory search)
-      Retriever = new('retriever')
-      
-      # Embedding generation calls
-      Embedding = new('embedding')
-      
-      # Functions that assess quality/relevance of outputs
-      Evaluator = new('evaluator')
-      
-      # Generic spans for durations of work units
-      Span = new('span')
-      
-      # Discrete events/moments in time
-      Event = new('event')
-    end
-
-    # Get the appropriate observation type for a DSPy module class
-    sig { params(module_class: T.class_of(DSPy::Module)).returns(ObservationType) }
-    def self.for_module_class(module_class)
-      case module_class.name
-      when /ReAct/, /CodeAct/
-        Agent
-      when /ChainOfThought/
-        Chain
-      when /Evaluator/
-        Evaluator
-      else
-        Span
-      end
-    end
-
-    # Returns the langfuse attribute key and value as an array
-    sig { returns([String, String]) }
-    def langfuse_attribute
-      ['langfuse.observation.type', serialize]
-    end
-
-    # Returns a hash with the langfuse attribute for easy merging
-    sig { returns(T::Hash[String, String]) }
-    def langfuse_attributes
-      { 'langfuse.observation.type' => serialize }
-    end
-  end
-end

data/lib/dspy/optimizers/gaussian_process.rb

@@ -1,141 +0,0 @@
-# typed: strict
-# frozen_string_literal: true
-
-require 'numo/narray'
-require 'sorbet-runtime'
-
-module DSPy
-  module Optimizers
-    # Pure Ruby Gaussian Process implementation for Bayesian optimization
-    # No external LAPACK/BLAS dependencies required
-    class GaussianProcess
-      extend T::Sig
-
-      sig { params(length_scale: Float, signal_variance: Float, noise_variance: Float).void }
-      def initialize(length_scale: 1.0, signal_variance: 1.0, noise_variance: 1e-6)
-        @length_scale = length_scale
-        @signal_variance = signal_variance
-        @noise_variance = noise_variance
-        @fitted = T.let(false, T::Boolean)
-      end
-
-      sig { params(x1: T::Array[T::Array[Float]], x2: T::Array[T::Array[Float]]).returns(Numo::DFloat) }
-      def rbf_kernel(x1, x2)
-        # Convert to Numo arrays
-        x1_array = Numo::DFloat[*x1]
-        x2_array = Numo::DFloat[*x2]
-        
-        # Compute squared Euclidean distances manually
-        n1, n2 = x1_array.shape[0], x2_array.shape[0]
-        sqdist = Numo::DFloat.zeros(n1, n2)
-        
-        (0...n1).each do |i|
-          (0...n2).each do |j|
-            diff = x1_array[i, true] - x2_array[j, true]
-            sqdist[i, j] = (diff ** 2).sum
-          end
-        end
-        
-        # RBF kernel: σ² * exp(-0.5 * d² / ℓ²)
-        @signal_variance * Numo::NMath.exp(-0.5 * sqdist / (@length_scale ** 2))
-      end
-
-      sig { params(x_train: T::Array[T::Array[Float]], y_train: T::Array[Float]).void }
-      def fit(x_train, y_train)
-        @x_train = x_train
-        @y_train = Numo::DFloat[*y_train]
-        
-        # Compute kernel matrix
-        k_matrix = rbf_kernel(x_train, x_train)
-        
-        # Add noise to diagonal for numerical stability
-        n = k_matrix.shape[0]
-        (0...n).each { |i| k_matrix[i, i] += @noise_variance }
-        
-        # Store inverted kernel matrix using simple LU decomposition
-        @k_inv = matrix_inverse(k_matrix)
-        @alpha = @k_inv.dot(@y_train)
-        
-        @fitted = true
-      end
-
-      sig { params(x_test: T::Array[T::Array[Float]], return_std: T::Boolean).returns(T.any(Numo::DFloat, [Numo::DFloat, Numo::DFloat])) }
-      def predict(x_test, return_std: false)
-        raise "Gaussian Process not fitted" unless @fitted
-        
-        # Kernel between training and test points
-        k_star = rbf_kernel(T.must(@x_train), x_test)
-        
-        # Predictive mean
-        mean = k_star.transpose.dot(@alpha)
-        
-        return mean unless return_std
-        
-        # Predictive variance (simplified for small matrices)
-        k_star_star = rbf_kernel(x_test, x_test)
-        var_matrix = k_star_star - k_star.transpose.dot(@k_inv).dot(k_star)
-        var = var_matrix.diagonal
-        
-        # Ensure positive variance (element-wise maximum)
-        var = var.map { |v| [v, 1e-12].max }
-        std = Numo::NMath.sqrt(var)
-        
-        [mean, std]
-      end
-
-      private
-
-      sig { returns(T.nilable(T::Array[T::Array[Float]])) }
-      attr_reader :x_train
-
-      sig { returns(T.nilable(Numo::DFloat)) }
-      attr_reader :y_train, :k_inv, :alpha
-
-      # Simple matrix inversion using Gauss-Jordan elimination
-      # Only suitable for small matrices (< 100x100)
-      sig { params(matrix: Numo::DFloat).returns(Numo::DFloat) }
-      def matrix_inverse(matrix)
-        n = matrix.shape[0]
-        raise "Matrix must be square" unless matrix.shape[0] == matrix.shape[1]
-        
-        # Create augmented matrix [A|I]
-        augmented = Numo::DFloat.zeros(n, 2*n)
-        augmented[true, 0...n] = matrix.copy
-        (0...n).each { |i| augmented[i, n+i] = 1.0 }
-        
-        # Gauss-Jordan elimination
-        (0...n).each do |i|
-          # Find pivot
-          max_row = i
-          (i+1...n).each do |k|
-            if augmented[k, i].abs > augmented[max_row, i].abs
-              max_row = k
-            end
-          end
-          
-          # Swap rows if needed
-          if max_row != i
-            temp = augmented[i, true].copy
-            augmented[i, true] = augmented[max_row, true]
-            augmented[max_row, true] = temp
-          end
-          
-          # Make diagonal element 1
-          pivot = augmented[i, i]
-          raise "Matrix is singular" if pivot.abs < 1e-12
-          augmented[i, true] /= pivot
-          
-          # Eliminate column
-          (0...n).each do |j|
-            next if i == j
-            factor = augmented[j, i]
-            augmented[j, true] -= factor * augmented[i, true]
-          end
-        end
-        
-        # Extract inverse matrix
-        augmented[true, n...2*n]
-      end
-    end
-  end
-end