dspy 0.29.0 → 0.30.0

data/lib/dspy/observability.rb

@@ -1,196 +1,54 @@
+# typed: false
 # frozen_string_literal: true
 
-require 'base64'
-require_relative 'observability/async_span_processor'
-
-module DSPy
-  class Observability
-    class << self
-      attr_reader :enabled, :tracer, :endpoint
-
-      def configure!
-        @enabled = false
-        
-        # Check for explicit disable flag first
-        if ENV['DSPY_DISABLE_OBSERVABILITY'] == 'true'
-          DSPy.log('observability.disabled', reason: 'Explicitly disabled via DSPY_DISABLE_OBSERVABILITY')
-          return
-        end
-        
-        # Check for required Langfuse environment variables
-        public_key = ENV['LANGFUSE_PUBLIC_KEY']
-        secret_key = ENV['LANGFUSE_SECRET_KEY']
-        
-        # Skip OTLP configuration in test environment UNLESS Langfuse credentials are explicitly provided
-        # This allows observability tests to run while protecting general tests from network calls
-        if (ENV['RACK_ENV'] == 'test' || ENV['RAILS_ENV'] == 'test' || defined?(RSpec)) && !(public_key && secret_key)
-          DSPy.log('observability.disabled', reason: 'Test environment detected - OTLP disabled')
-          return
-        end
-        
-        unless public_key && secret_key
-          return
+begin
+  require 'dspy/o11y'
+rescue LoadError
+  require 'sorbet-runtime'
+
+  module DSPy
+    class Observability
+      class << self
+        def register_configurator(*); end
+        def configure!(*); false; end
+        def enabled?; false; end
+        def enable!(*); false; end
+        def disable!(*); nil; end
+        def start_span(*); nil; end
+        def finish_span(*); nil; end
+        def flush!; nil; end
+        def reset!; nil; end
+        def require_dependency(lib)
+          require lib
+        rescue LoadError
+          raise
         end
-
-        # Determine endpoint based on host
-        host = ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
-        @endpoint = "#{host}/api/public/otel/v1/traces"
-
-        begin
-          # Load OpenTelemetry gems
-          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}")
-          
-          # Configure OpenTelemetry SDK
-          OpenTelemetry::SDK.configure do |config|
-            config.service_name = 'dspy-ruby'
-            config.service_version = DSPy::VERSION
-            
-            # Add OTLP exporter for Langfuse using AsyncSpanProcessor
-            exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
-              endpoint: @endpoint,
-              headers: {
-                'Authorization' => "Basic #{auth_string}",
-                'Content-Type' => 'application/x-protobuf'
-              },
-              compression: 'gzip'
-            )
-            
-            # Configure AsyncSpanProcessor with environment variables
-            async_config = {
-              queue_size: (ENV['DSPY_TELEMETRY_QUEUE_SIZE'] || AsyncSpanProcessor::DEFAULT_QUEUE_SIZE).to_i,
-              export_interval: (ENV['DSPY_TELEMETRY_EXPORT_INTERVAL'] || AsyncSpanProcessor::DEFAULT_EXPORT_INTERVAL).to_f,
-              export_batch_size: (ENV['DSPY_TELEMETRY_BATCH_SIZE'] || AsyncSpanProcessor::DEFAULT_EXPORT_BATCH_SIZE).to_i,
-              shutdown_timeout: (ENV['DSPY_TELEMETRY_SHUTDOWN_TIMEOUT'] || AsyncSpanProcessor::DEFAULT_SHUTDOWN_TIMEOUT).to_f
-            }
-            
-            config.add_span_processor(
-              AsyncSpanProcessor.new(exporter, **async_config)
-            )
-            
-            # Add resource attributes
-            config.resource = OpenTelemetry::SDK::Resources::Resource.create({
-              'service.name' => 'dspy-ruby',
-              'service.version' => DSPy::VERSION,
-              'telemetry.sdk.name' => 'opentelemetry',
-              'telemetry.sdk.language' => 'ruby'
-            })
-          end
-
-          # Create tracer
-          @tracer = OpenTelemetry.tracer_provider.tracer('dspy', DSPy::VERSION)
-          @enabled = true
-
-        rescue LoadError => e
-          DSPy.log('observability.disabled', reason: 'OpenTelemetry gems not available')
-        rescue StandardError => e
-          DSPy.log('observability.error', error: e.message, class: e.class.name)
-        end
-      end
-
-      def enabled?
-        @enabled == true
-      end
-
-      def tracer
-        @tracer
-      end
-
-      def start_span(operation_name, attributes = {})
-        return nil unless enabled? && tracer
-
-        # Convert attribute keys to strings and filter out nil values
-        string_attributes = attributes.transform_keys(&:to_s)
-                                     .reject { |k, v| v.nil? }
-        string_attributes['operation.name'] = operation_name
-        
-        tracer.start_span(
-          operation_name,
-          kind: :internal,
-          attributes: string_attributes
-        )
-      rescue StandardError => e
-        DSPy.log('observability.span_error', error: e.message, operation: operation_name)
-        nil
       end
+    end
 
-      def finish_span(span)
-        return unless span
-        
-        span.finish
-      rescue StandardError => e
-        DSPy.log('observability.span_finish_error', error: e.message)
+    class ObservationType < T::Enum
+      enums do
+        Generation = new('generation')
+        Agent = new('agent')
+        Tool = new('tool')
+        Chain = new('chain')
+        Retriever = new('retriever')
+        Embedding = new('embedding')
+        Evaluator = new('evaluator')
+        Span = new('span')
+        Event = new('event')
       end
 
-      def flush!
-        return unless enabled?
-        
-        # Force flush any pending spans
-        OpenTelemetry.tracer_provider.force_flush
-      rescue StandardError => e
-        DSPy.log('observability.flush_error', error: e.message)
+      def self.for_module_class(_module_class)
+        Span
       end
 
-      def reset!
-        @enabled = false
-        
-        # Shutdown OpenTelemetry if it's configured
-        if defined?(OpenTelemetry) && OpenTelemetry.tracer_provider
-          begin
-            OpenTelemetry.tracer_provider.shutdown(timeout: 1.0)
-          rescue => e
-            # Ignore shutdown errors in tests - log them but don't fail
-            DSPy.log('observability.shutdown_error', error: e.message) if respond_to?(:log)
-          end
-        end
-        
-        @tracer = nil
-        @endpoint = nil
+      def langfuse_attribute
+        ['langfuse.observation.type', serialize]
       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)
+      def langfuse_attributes
+        { 'langfuse.observation.type' => serialize }
       end
     end
   end

data/lib/dspy/predict.rb

@@ -6,6 +6,7 @@ require_relative 'prompt'
 require_relative 'utils/serialization'
 require_relative 'mixins/struct_builder'
 require_relative 'mixins/type_coercion'
+require_relative 'mixins/instruction_updatable'
 require_relative 'error_formatter'
 
 module DSPy
@@ -46,6 +47,7 @@ module DSPy
     extend T::Sig
     include Mixins::StructBuilder
     include Mixins::TypeCoercion
+    include Mixins::InstructionUpdatable
 
     sig { returns(T.class_of(Signature)) }
     attr_reader :signature_class
@@ -120,6 +122,7 @@ module DSPy
       # Create a new instance with the same signature but updated prompt
       instance = self.class.new(@signature_class)
       instance.instance_variable_set(:@prompt, new_prompt)
+      instance.instance_variable_set(:@demos, @demos&.map { |demo| demo })
       instance
     end
 
@@ -130,12 +133,17 @@ module DSPy
 
     sig { params(examples: T::Array[FewShotExample]).returns(Predict) }
     def with_examples(examples)
-      with_prompt(@prompt.with_examples(examples))
+      instance = with_prompt(@prompt.with_examples(examples))
+      instance.demos = examples.map { |example| example }
+      instance
     end
 
     sig { params(examples: T::Array[FewShotExample]).returns(Predict) }
     def add_examples(examples)
-      with_prompt(@prompt.add_examples(examples))
+      instance = with_prompt(@prompt.add_examples(examples))
+      combined = instance.prompt.few_shot_examples
+      instance.demos = combined.map { |example| example }
+      instance
     end
 
     sig { override.returns(T::Array[[String, DSPy::Module]]) }

data/lib/dspy/propose/dataset_summary_generator.rb

@@ -34,7 +34,7 @@ module DSPy
                    "It will be useful to make an educated guess as to the nature of the task this dataset will enable. Don't be afraid to be creative"
 
         input do
-          const :examples, String, description: "Sample data points from the dataset"
+          const :examples, T::Array[T::Hash[String, T.untyped]], description: "Sample data points from the dataset"
         end
 
         output do
@@ -50,7 +50,7 @@ module DSPy
                    "It will be useful to make an educated guess as to the nature of the task this dataset will enable. Don't be afraid to be creative"
 
         input do
-          const :examples, String, description: "Sample data points from the dataset"
+          const :examples, T::Array[T::Hash[String, T.untyped]], description: "Sample data points from the dataset"
           const :prior_observations, String, description: "Some prior observations I made about the data"
         end
 
@@ -124,9 +124,7 @@ module DSPy
           upper_lim = [trainset.length, view_data_batch_size].min
           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)
+          observation = predictor.call(examples: format_examples_for_prompt(batch_examples))
           observations = observation.observations
 
           # Iteratively refine observations with additional batches
@@ -145,11 +143,9 @@ module DSPy
 
               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
+                examples: format_examples_for_prompt(batch_examples)
               )
 
               # Check if LLM indicates observations are complete
@@ -179,31 +175,45 @@ module DSPy
         end
       end
 
-      sig { params(examples: T::Array[T.untyped]).returns(String) }
+      sig { params(examples: T::Array[T.untyped]).returns(T::Array[T::Hash[String, T.untyped]]) }
       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)
+              'signature' => example.signature_class.name || example.signature_class.to_s,
+              'input' => stringify_keys(DSPy::TypeSerializer.serialize(example.input)),
+              'expected' => stringify_keys(DSPy::TypeSerializer.serialize(example.expected))
             }
           when DSPy::FewShotExample
             base = {
-              input: example.input,
-              output: example.output
+              'input' => stringify_keys(example.input),
+              'output' => stringify_keys(example.output)
             }
-            base[:reasoning] = example.reasoning if example.reasoning
+            base['reasoning'] = example.reasoning if example.reasoning
             base
           when Hash
-            example
+            stringify_keys(example)
           else
-            example.respond_to?(:to_h) ? example.to_h : { value: example }
+            stringify_keys(example.respond_to?(:to_h) ? example.to_h : { value: example })
           end
         end
 
-        JSON.pretty_generate(serialized_examples)
+        serialized_examples
+      end
+
+      sig { params(value: T.untyped).returns(T.untyped) }
+      def self.stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), result|
+            result[k.to_s] = stringify_keys(v)
+          end
+        when Array
+          value.map { |item| stringify_keys(item) }
+        else
+          value
+        end
       end
     end
   end

data/lib/dspy/re_act.rb

@@ -157,6 +157,27 @@ module DSPy
       named_predictors.map { |(_, predictor)| predictor }
     end
 
+    sig { returns(DSPy::Prompt) }
+    def prompt
+      @thought_generator.prompt
+    end
+
+    sig { params(instruction: String).returns(ReAct).override }
+    def with_instruction(instruction)
+      clone = self.class.new(@original_signature_class, tools: @tools.values, max_iterations: @max_iterations)
+      thought_generator = clone.instance_variable_get(:@thought_generator)
+      clone.instance_variable_set(:@thought_generator, thought_generator.with_instruction(instruction))
+      clone
+    end
+
+    sig { params(examples: T::Array[DSPy::FewShotExample]).returns(ReAct).override }
+    def with_examples(examples)
+      clone = self.class.new(@original_signature_class, tools: @tools.values, max_iterations: @max_iterations)
+      thought_generator = clone.instance_variable_get(:@thought_generator)
+      clone.instance_variable_set(:@thought_generator, thought_generator.with_examples(examples))
+      clone
+    end
+
     sig { params(kwargs: T.untyped).returns(T.untyped).override }
     def forward(**kwargs)
       # Validate input