dspy 0.17.0 → 0.18.0

data/lib/dspy/observability.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module DSPy
+  class Observability
+    class << self
+      attr_reader :enabled, :tracer, :endpoint
+
+      def configure!
+        @enabled = false
+        
+        # Check for required Langfuse environment variables
+        public_key = ENV['LANGFUSE_PUBLIC_KEY']
+        secret_key = ENV['LANGFUSE_SECRET_KEY']
+        
+        unless public_key && secret_key
+          return
+        end
+
+        # Determine endpoint based on host
+        host = ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+        @endpoint = "#{host}/api/public/otel"
+
+        begin
+          # Load OpenTelemetry gems
+          require 'opentelemetry/sdk'
+          require 'opentelemetry/exporter/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
+            config.add_span_processor(
+              OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+                OpenTelemetry::Exporter::OTLP::Exporter.new(
+                  endpoint: @endpoint,
+                  headers: {
+                    'Authorization' => "Basic #{auth_string}",
+                    'Content-Type' => 'application/x-protobuf'
+                  },
+                  compression: 'gzip'
+                )
+              )
+            )
+            
+            # 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 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
+
+      def finish_span(span)
+        return unless span
+        
+        span.finish
+      rescue StandardError => e
+        DSPy.log('observability.span_finish_error', error: e.message)
+      end
+
+      def reset!
+        @enabled = false
+        @tracer = nil
+        @endpoint = nil
+      end
+    end
+  end
+end

data/lib/dspy/predict.rb

@@ -2,11 +2,9 @@
 
 require 'sorbet-runtime'
 require_relative 'module'
-require_relative 'instrumentation'
 require_relative 'prompt'
 require_relative 'mixins/struct_builder'
 require_relative 'mixins/type_coercion'
-require_relative 'mixins/instrumentation_helpers'
 
 module DSPy
   # Exception raised when prediction fails validation
@@ -27,7 +25,6 @@ module DSPy
     extend T::Sig
     include Mixins::StructBuilder
     include Mixins::TypeCoercion
-    include Mixins::InstrumentationHelpers
 
     sig { returns(T.class_of(Signature)) }
     attr_reader :signature_class
@@ -85,12 +82,23 @@ module DSPy
 
     sig { params(input_values: T.untyped).returns(T.untyped) }
     def forward_untyped(**input_values)
-      instrument_prediction('dspy.predict', @signature_class, input_values) do
+      # Wrap prediction in span tracking
+      DSPy::Context.with_span(
+        operation: "#{self.class.name}.forward",
+        'dspy.module' => self.class.name,
+        'dspy.signature' => @signature_class.name
+      ) do
         # Validate input
         validate_input_struct(input_values)
         
+        # Check if LM is configured
+        current_lm = lm
+        if current_lm.nil?
+          raise DSPy::ConfigurationError.missing_lm(self.class.name)
+        end
+        
         # Call LM and process response
-        output_attributes = lm.chat(self, input_values)
+        output_attributes = current_lm.chat(self, input_values)
         processed_output = process_lm_output(output_attributes)
         
         # Create combined result struct
@@ -105,7 +113,11 @@ module DSPy
     def validate_input_struct(input_values)
       @signature_class.input_struct_class.new(**input_values)
     rescue ArgumentError => e
-      emit_validation_error(@signature_class, 'input', e.message)
+      DSPy.log('prediction.validation_error', **{
+        'dspy.signature' => @signature_class.name,
+        'prediction.validation_type' => 'input',
+        'prediction.validation_errors' => { input: e.message }
+      })
       raise PredictionInvalidError.new({ input: e.message })
     end
 

data/lib/dspy/propose/grounded_proposer.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'sorbet-runtime'
-require_relative '../instrumentation'
 require_relative '../signature'
 require_relative '../predict'
 
@@ -104,12 +103,14 @@ module DSPy
         ).returns(ProposalResult)
       end
       def propose_instructions(signature_class, examples, few_shot_examples: nil, current_instruction: nil)
-        Instrumentation.instrument('dspy.optimization.instruction_proposal_start', {
-          signature_class: signature_class.name,
-          num_examples: examples.size,
-          has_few_shot: !few_shot_examples.nil?,
-          has_current_instruction: !current_instruction.nil?
-        }) do
+        DSPy::Context.with_span(
+          operation: 'optimization.instruction_proposal',
+          'dspy.module' => 'GroundedProposer',
+          'proposal.signature' => signature_class.name,
+          'proposal.num_examples' => examples.size,
+          'proposal.has_few_shot' => !few_shot_examples.nil?,
+          'proposal.has_current_instruction' => !current_instruction.nil?
+        ) do
           # Analyze the task and training data
           analysis = analyze_task(signature_class, examples, few_shot_examples)
           
@@ -548,11 +549,11 @@ module DSPy
       # Emit instruction proposal completion event
       sig { params(result: ProposalResult).void }
       def emit_proposal_complete_event(result)
-        Instrumentation.emit('dspy.optimization.instruction_proposal_complete', {
-          num_candidates: result.num_candidates,
-          best_instruction_length: result.best_instruction.length,
-          analysis_themes: result.analysis[:common_themes] || [],
-          model_used: @config.proposal_model
+        DSPy.log('optimization.instruction_proposal_complete', **{
+          'proposal.num_candidates' => result.num_candidates,
+          'proposal.best_instruction_length' => result.best_instruction.length,
+          'proposal.analysis_themes' => result.analysis[:common_themes] || [],
+          'proposal.model_used' => @config.proposal_model
         })
       end
     end

data/lib/dspy/re_act.rb

@@ -6,9 +6,7 @@ require_relative 'predict'
 require_relative 'signature'
 require_relative 'chain_of_thought'
 require 'json'
-require_relative 'instrumentation'
 require_relative 'mixins/struct_builder'
-require_relative 'mixins/instrumentation_helpers'
 
 module DSPy
   # Define a simple struct for history entries with proper type annotations
@@ -67,7 +65,6 @@ module DSPy
   class ReAct < Predict
     extend T::Sig
     include Mixins::StructBuilder
-    include Mixins::InstrumentationHelpers
 
     FINISH_ACTION = "finish"
     sig { returns(T.class_of(DSPy::Signature)) }
@@ -129,22 +126,14 @@ module DSPy
       lm = config.lm || DSPy.config.lm
       available_tools = @tools.keys
 
-      # Instrument the entire ReAct agent lifecycle
-      result = instrument_prediction('dspy.react', @original_signature_class, kwargs, {
-        max_iterations: @max_iterations,
-        available_tools: available_tools
-      }) do
-        # Validate input
-        input_struct = @original_signature_class.input_struct_class.new(**kwargs)
+      # Validate input
+      input_struct = @original_signature_class.input_struct_class.new(**kwargs)
 
-        # Execute ReAct reasoning loop
-        reasoning_result = execute_react_reasoning_loop(input_struct)
+      # Execute ReAct reasoning loop
+      reasoning_result = execute_react_reasoning_loop(input_struct)
 
-        # Create enhanced output with all ReAct data
-        create_enhanced_result(kwargs, reasoning_result)
-      end
-
-      result
+      # Create enhanced output with all ReAct data
+      create_enhanced_result(kwargs, reasoning_result)
     end
 
     private
@@ -247,13 +236,15 @@ module DSPy
     # Executes a single iteration of the ReAct loop
     sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], available_tools_desc: T::Array[T::Hash[String, T.untyped]], iteration: Integer, tools_used: T::Array[String], last_observation: T.nilable(String)).returns(T::Hash[Symbol, T.untyped]) }
     def execute_single_iteration(input_struct, history, available_tools_desc, iteration, tools_used, last_observation)
-      # Instrument each iteration
-      Instrumentation.instrument('dspy.react.iteration', {
-        iteration: iteration,
-        max_iterations: @max_iterations,
-        history_length: history.length,
-        tools_used_so_far: tools_used.uniq
-      }) do
+      # Track each iteration with span
+      DSPy::Context.with_span(
+        operation: 'react.iteration',
+        'dspy.module' => 'ReAct',
+        'react.iteration' => iteration,
+        'react.max_iterations' => @max_iterations,
+        'react.history_length' => history.length,
+        'react.tools_used' => tools_used.uniq
+      ) do
         # Generate thought and action
         thought_obj = @thought_generator.forward(
           input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
@@ -357,11 +348,13 @@ module DSPy
     sig { params(action: T.nilable(String), action_input: T.untyped, iteration: Integer).returns(String) }
     def execute_tool_with_instrumentation(action, action_input, iteration)
       if action && @tools[action.downcase]
-        Instrumentation.instrument('dspy.react.tool_call', {
-          iteration: iteration,
-          tool_name: action.downcase,
-          tool_input: action_input
-        }) do
+        DSPy::Context.with_span(
+          operation: 'react.tool_call',
+          'dspy.module' => 'ReAct',
+          'react.iteration' => iteration,
+          'tool.name' => action.downcase,
+          'tool.input' => action_input
+        ) do
           execute_action(action, action_input)
         end
       else
@@ -421,24 +414,24 @@ module DSPy
 
     sig { params(iteration: Integer, thought: String, action: String, action_input: T.untyped, observation: String, tools_used: T::Array[String]).void }
     def emit_iteration_complete_event(iteration, thought, action, action_input, observation, tools_used)
-      Instrumentation.emit('dspy.react.iteration_complete', {
-        iteration: iteration,
-        thought: thought,
-        action: action,
-        action_input: action_input,
-        observation: observation,
-        tools_used: tools_used.uniq
+      DSPy.log('react.iteration_complete', **{
+        'react.iteration' => iteration,
+        'react.thought' => thought,
+        'react.action' => action,
+        'react.action_input' => action_input,
+        'react.observation' => observation,
+        'react.tools_used' => tools_used.uniq
       })
     end
 
     sig { params(iterations_count: Integer, final_answer: T.nilable(String), tools_used: T::Array[String], history: T::Array[HistoryEntry]).void }
     def handle_max_iterations_if_needed(iterations_count, final_answer, tools_used, history)
       if iterations_count >= @max_iterations && final_answer.nil?
-        Instrumentation.emit('dspy.react.max_iterations', {
-          iteration_count: iterations_count,
-          max_iterations: @max_iterations,
-          tools_used: tools_used.uniq,
-          final_history_length: history.length
+        DSPy.log('react.max_iterations', **{
+          'react.iteration_count' => iterations_count,
+          'react.max_iterations' => @max_iterations,
+          'react.tools_used' => tools_used.uniq,
+          'react.final_history_length' => history.length
         })
       end
     end

data/lib/dspy/registry/registry_manager.rb

@@ -482,21 +482,19 @@ module DSPy
 
       sig { params(signature_name: String, version: String).void }
       def emit_auto_deployment_event(signature_name, version)
-        DSPy::Instrumentation.emit('dspy.registry.auto_deployment', {
-          signature_name: signature_name,
-          version: version,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.auto_deployment', **{
+          'registry.signature_name' => signature_name,
+          'registry.version' => version
         })
       end
 
       sig { params(signature_name: String, current_score: Float, previous_score: Float).void }
       def emit_automatic_rollback_event(signature_name, current_score, previous_score)
-        DSPy::Instrumentation.emit('dspy.registry.automatic_rollback', {
-          signature_name: signature_name,
-          current_score: current_score,
-          previous_score: previous_score,
-          performance_drop: previous_score - current_score,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.automatic_rollback', **{
+          'registry.signature_name' => signature_name,
+          'registry.current_score' => current_score,
+          'registry.previous_score' => previous_score,
+          'registry.performance_drop' => previous_score - current_score
         })
       end
     end

data/lib/dspy/registry/signature_registry.rb

@@ -611,113 +611,101 @@ module DSPy
       # Event emission methods
       sig { params(signature_name: String, version: T.nilable(String)).void }
       def emit_register_start_event(signature_name, version)
-        DSPy::Instrumentation.emit('dspy.registry.register_start', {
-          signature_name: signature_name,
-          version: version,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.register_start', **{
+          'registry.signature_name' => signature_name,
+          'registry.version' => version
         })
       end
 
       sig { params(version: SignatureVersion).void }
       def emit_register_complete_event(version)
-        DSPy::Instrumentation.emit('dspy.registry.register_complete', {
-          signature_name: version.signature_name,
-          version: version.version,
-          version_hash: version.version_hash,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.register_complete', **{
+          'registry.signature_name' => version.signature_name,
+          'registry.version' => version.version,
+          'registry.version_hash' => version.version_hash
         })
       end
 
       sig { params(signature_name: String, version: T.nilable(String), error: Exception).void }
       def emit_register_error_event(signature_name, version, error)
-        DSPy::Instrumentation.emit('dspy.registry.register_error', {
-          signature_name: signature_name,
-          version: version,
-          error: error.message,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.register_error', **{
+          'registry.signature_name' => signature_name,
+          'registry.version' => version,
+          'registry.error' => error.message
         })
       end
 
       sig { params(signature_name: String, version: String).void }
       def emit_deploy_start_event(signature_name, version)
-        DSPy::Instrumentation.emit('dspy.registry.deploy_start', {
-          signature_name: signature_name,
-          version: version,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.deploy_start', **{
+          'registry.signature_name' => signature_name,
+          'registry.version' => version
         })
       end
 
       sig { params(version: SignatureVersion).void }
       def emit_deploy_complete_event(version)
-        DSPy::Instrumentation.emit('dspy.registry.deploy_complete', {
-          signature_name: version.signature_name,
-          version: version.version,
-          performance_score: version.performance_score,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.deploy_complete', **{
+          'registry.signature_name' => version.signature_name,
+          'registry.version' => version.version,
+          'registry.performance_score' => version.performance_score
         })
       end
 
       sig { params(signature_name: String, version: String, error: Exception).void }
       def emit_deploy_error_event(signature_name, version, error)
-        DSPy::Instrumentation.emit('dspy.registry.deploy_error', {
-          signature_name: signature_name,
-          version: version,
-          error: error.message,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.deploy_error', **{
+          'registry.signature_name' => signature_name,
+          'registry.version' => version,
+          'registry.error' => error.message
         })
       end
 
       sig { params(signature_name: String).void }
       def emit_rollback_start_event(signature_name)
-        DSPy::Instrumentation.emit('dspy.registry.rollback_start', {
-          signature_name: signature_name,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.rollback_start', **{
+          'registry.signature_name' => signature_name
         })
       end
 
       sig { params(version: SignatureVersion).void }
       def emit_rollback_complete_event(version)
-        DSPy::Instrumentation.emit('dspy.registry.rollback_complete', {
-          signature_name: version.signature_name,
-          version: version.version,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.rollback_complete', **{
+          'registry.signature_name' => version.signature_name,
+          'registry.version' => version.version
         })
       end
 
       sig { params(signature_name: String, error_message: String).void }
       def emit_rollback_error_event(signature_name, error_message)
-        DSPy::Instrumentation.emit('dspy.registry.rollback_error', {
-          signature_name: signature_name,
-          error: error_message,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.rollback_error', **{
+          'registry.signature_name' => signature_name,
+          'registry.error' => error_message
         })
       end
 
       sig { params(version: SignatureVersion).void }
       def emit_performance_update_event(version)
-        DSPy::Instrumentation.emit('dspy.registry.performance_update', {
-          signature_name: version.signature_name,
-          version: version.version,
-          performance_score: version.performance_score,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.performance_update', **{
+          'registry.signature_name' => version.signature_name,
+          'registry.version' => version.version,
+          'registry.performance_score' => version.performance_score
         })
       end
 
       sig { params(export_path: String, signature_count: Integer).void }
       def emit_export_event(export_path, signature_count)
-        DSPy::Instrumentation.emit('dspy.registry.export', {
-          export_path: export_path,
-          signature_count: signature_count,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.export', **{
+          'registry.export_path' => export_path,
+          'registry.signature_count' => signature_count
         })
       end
 
       sig { params(import_path: String, signature_count: Integer).void }
       def emit_import_event(import_path, signature_count)
-        DSPy::Instrumentation.emit('dspy.registry.import', {
-          import_path: import_path,
-          signature_count: signature_count,
-          timestamp: Time.now.iso8601
+        DSPy.log('registry.import', **{
+          'registry.import_path' => import_path,
+          'registry.signature_count' => signature_count
         })
       end
     end

data/lib/dspy/storage/program_storage.rb

@@ -357,84 +357,75 @@ module DSPy
       # Event emission methods
       sig { params(program_id: T.nilable(String)).void }
       def emit_save_start_event(program_id)
-        DSPy::Instrumentation.emit('dspy.storage.save_start', {
-          program_id: program_id,
-          storage_path: @storage_path,
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.save_start', **{
+          'storage.program_id' => program_id,
+          'storage.path' => @storage_path
         })
       end
 
       sig { params(saved_program: SavedProgram).void }
       def emit_save_complete_event(saved_program)
-        DSPy::Instrumentation.emit('dspy.storage.save_complete', {
-          program_id: saved_program.program_id,
-          best_score: saved_program.optimization_result[:best_score_value],
-          file_size_bytes: File.size(program_file_path(saved_program.program_id)),
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.save_complete', **{
+          'storage.program_id' => saved_program.program_id,
+          'storage.best_score' => saved_program.optimization_result[:best_score_value],
+          'storage.file_size' => File.size(program_file_path(saved_program.program_id))
         })
       end
 
       sig { params(program_id: T.nilable(String), error: Exception).void }
       def emit_save_error_event(program_id, error)
-        DSPy::Instrumentation.emit('dspy.storage.save_error', {
-          program_id: program_id,
-          error: error.message,
-          error_class: error.class.name,
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.save_error', **{
+          'storage.program_id' => program_id,
+          'storage.error' => error.message,
+          'storage.error_class' => error.class.name
         })
       end
 
       sig { params(program_id: String).void }
       def emit_load_start_event(program_id)
-        DSPy::Instrumentation.emit('dspy.storage.load_start', {
-          program_id: program_id,
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.load_start', **{
+          'storage.program_id' => program_id
         })
       end
 
       sig { params(saved_program: SavedProgram).void }
       def emit_load_complete_event(saved_program)
-        DSPy::Instrumentation.emit('dspy.storage.load_complete', {
-          program_id: saved_program.program_id,
-          saved_at: saved_program.saved_at.iso8601,
-          age_hours: ((Time.now - saved_program.saved_at) / 3600).round(2),
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.load_complete', **{
+          'storage.program_id' => saved_program.program_id,
+          'storage.saved_at' => saved_program.saved_at.iso8601,
+          'storage.age_hours' => ((Time.now - saved_program.saved_at) / 3600).round(2)
         })
       end
 
       sig { params(program_id: String, error: T.any(String, Exception)).void }
       def emit_load_error_event(program_id, error)
         error_message = error.is_a?(Exception) ? error.message : error.to_s
-        DSPy::Instrumentation.emit('dspy.storage.load_error', {
-          program_id: program_id,
-          error: error_message,
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.load_error', **{
+          'storage.program_id' => program_id,
+          'storage.error' => error_message
         })
       end
 
       sig { params(program_id: String).void }
       def emit_delete_event(program_id)
-        DSPy::Instrumentation.emit('dspy.storage.delete', {
-          program_id: program_id,
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.delete', **{
+          'storage.program_id' => program_id
         })
       end
 
       sig { params(export_path: String, program_count: Integer).void }
       def emit_export_event(export_path, program_count)
-        DSPy::Instrumentation.emit('dspy.storage.export', {
-          export_path: export_path,
-          program_count: program_count,
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.export', **{
+          'storage.export_path' => export_path,
+          'storage.program_count' => program_count
         })
       end
 
       sig { params(import_path: String, program_count: Integer).void }
       def emit_import_event(import_path, program_count)
-        DSPy::Instrumentation.emit('dspy.storage.import', {
-          import_path: import_path,
-          program_count: program_count,
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.import', **{
+          'storage.import_path' => import_path,
+          'storage.program_count' => program_count
         })
       end
     end

data/lib/dspy/storage/storage_manager.rb

@@ -250,10 +250,9 @@ module DSPy
           end
         end
         
-        DSPy::Instrumentation.emit('dspy.storage.cleanup', {
-          deleted_count: deleted_count,
-          remaining_count: @config.max_stored_programs,
-          timestamp: Time.now.iso8601
+        DSPy.log('storage.cleanup', **{
+          'storage.deleted_count' => deleted_count,
+          'storage.remaining_count' => @config.max_stored_programs
         })
         
         deleted_count