dspy 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7d6061a3dd63f61bd9b5078694218b2a26b56da974da4c42b29f654efb3c08c
-  data.tar.gz: 3d8277e907c953c3577d3da3de5182c47665a1d105a131753aa6d0f25481d0ff
+  metadata.gz: 63f9d02616c10429f0d409e08036fbf25e2557ba02d48785271ffd7b90aec464
+  data.tar.gz: 46eb23dd11cc7e81ec2c58ee13beca5d36cbfc8c221ec1ae1b70b59cf3e56f36
 SHA512:
-  metadata.gz: ea762ce55ffcd24e3462c98ff14e5e29169889e73befd45abbb7bd84cce55b2ae0adf000e3af945a462538ef16fd78bd8a98bf941f3dc550c1188fda0eb266b4
-  data.tar.gz: 4f4e0be0529e942fadf1edd7fc4b0132732384715dd7e7f68889139b6bd39fc9c5b1701bb2b1fd27b166314d9a164a07b43a78d899efadc0a518dcf2bc24da7d
+  metadata.gz: d53d4a72482146cf692304f82a0c273ebc06925dc66042d461e600e77fa99f79fda88f67282b5497a4625275d7311b1d10ea255814085883e15a323a7c4d56e9
+  data.tar.gz: b2f63c03a162101345589732a192267a55464c7ebed524274a175b66ee872501ec36386d4fd7995005d4726fa0181bb82a9d48b32b09ed722e0662e39fd6958b

data/README.md

@@ -71,10 +71,10 @@ puts result.confidence   # => 0.85
 - **Reliable JSON Extraction** - Native OpenAI structured outputs, Anthropic extraction patterns, and automatic strategy selection with fallback
 - **Type-Safe Configuration** - Strategy enums with automatic provider optimization (Strict/Compatible modes)
 - **Smart Retry Logic** - Progressive fallback with exponential backoff for handling transient failures
+- **Zero-Config Langfuse Integration** - Set env vars and get automatic OpenTelemetry traces in Langfuse
 - **Performance Caching** - Schema and capability caching for faster repeated operations
 - **File-based Storage** - Optimization result persistence with versioning
-- **Multi-Platform Observability** - OpenTelemetry, New Relic, and Langfuse integration
-- **Comprehensive Instrumentation** - Event tracking, performance monitoring, and detailed logging
+- **Structured Logging** - JSON and key=value formats with span tracking
 
 **Developer Experience:**
 - LLM provider support using official Ruby clients:
@@ -163,7 +163,7 @@ For LLMs and AI assistants working with DSPy.rb:
 
 ### Production Features
 - **[Storage System](docs/src/production/storage.md)** - Basic file-based persistence
-- **[Observability](docs/src/production/observability.md)** - Multi-platform monitoring and metrics
+- **[Observability](docs/src/production/observability.md)** - Zero-config Langfuse integration and structured logging
 
 ### Advanced Usage
 - **[Complex Types](docs/src/advanced/complex-types.md)** - Sorbet type integration with automatic coercion for structs, enums, and arrays

data/lib/dspy/chain_of_thought.rb

@@ -4,7 +4,6 @@
 require 'sorbet-runtime'
 require_relative 'predict'
 require_relative 'signature'
-require_relative 'instrumentation'
 require_relative 'mixins/struct_builder'
 
 module DSPy
@@ -82,18 +81,16 @@ module DSPy
     sig { returns(T.class_of(DSPy::Signature)) }
     attr_reader :original_signature
 
-    # Override forward_untyped to add ChainOfThought-specific instrumentation
+    # Override forward_untyped to add ChainOfThought-specific analysis
     sig { override.params(input_values: T.untyped).returns(T.untyped) }
     def forward_untyped(**input_values)
-      instrument_prediction('dspy.chain_of_thought', @original_signature, input_values) do
-        # Call parent prediction logic
-        prediction_result = super(**input_values)
-        
-        # Analyze reasoning if present
-        analyze_reasoning(prediction_result)
-        
-        prediction_result
-      end
+      # Call parent prediction logic
+      prediction_result = super(**input_values)
+      
+      # Analyze reasoning if present
+      analyze_reasoning(prediction_result)
+      
+      prediction_result
     end
 
     private
@@ -165,11 +162,11 @@ module DSPy
     # Emits reasoning analysis instrumentation event
     sig { params(reasoning_content: String).void }
     def emit_reasoning_analysis(reasoning_content)
-      Instrumentation.emit('dspy.chain_of_thought.reasoning_complete', {
-        signature_class: @original_signature.name,
-        reasoning_steps: count_reasoning_steps(reasoning_content),
-        reasoning_length: reasoning_content.length,
-        has_reasoning: true
+      DSPy.log('chain_of_thought.reasoning_complete', **{
+        'dspy.signature' => @original_signature.name,
+        'cot.reasoning_steps' => count_reasoning_steps(reasoning_content),
+        'cot.reasoning_length' => reasoning_content.length,
+        'cot.has_reasoning' => true
       })
     end
 

data/lib/dspy/code_act.rb

@@ -6,9 +6,7 @@ require_relative 'predict'
 require_relative 'signature'
 require 'json'
 require 'stringio'
-require_relative 'instrumentation'
 require_relative 'mixins/struct_builder'
-require_relative 'mixins/instrumentation_helpers'
 require_relative 'type_serializer'
 
 module DSPy
@@ -91,7 +89,6 @@ module DSPy
   class CodeAct < Predict
     extend T::Sig
     include Mixins::StructBuilder
-    include Mixins::InstrumentationHelpers
 
     sig { returns(T.class_of(DSPy::Signature)) }
     attr_reader :original_signature_class
@@ -145,22 +142,15 @@ module DSPy
     def forward(**kwargs)
       lm = config.lm || DSPy.config.lm
 
-      # Instrument the entire CodeAct agent lifecycle
-      result = instrument_prediction('dspy.codeact', @original_signature_class, kwargs, {
-        max_iterations: @max_iterations
-      }) do
-        # Validate input and serialize all fields as task context
-        input_struct = @original_signature_class.input_struct_class.new(**kwargs)
-        task = DSPy::TypeSerializer.serialize(input_struct).to_json
+      # Validate input and serialize all fields as task context
+      input_struct = @original_signature_class.input_struct_class.new(**kwargs)
+      task = DSPy::TypeSerializer.serialize(input_struct).to_json
 
-        # Execute CodeAct reasoning loop
-        reasoning_result = execute_codeact_reasoning_loop(task)
+      # Execute CodeAct reasoning loop
+      reasoning_result = execute_codeact_reasoning_loop(task)
 
-        # Create enhanced output with all CodeAct data
-        create_enhanced_result(kwargs, reasoning_result)
-      end
-
-      result
+      # Create enhanced output with all CodeAct data
+      create_enhanced_result(kwargs, reasoning_result)
     end
 
     private
@@ -202,11 +192,13 @@ module DSPy
     # Executes a single iteration of the Think-Code-Observe loop
     sig { params(task: String, history: T::Array[CodeActHistoryEntry], context: String, iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
     def execute_single_iteration(task, history, context, iteration)
-      Instrumentation.instrument('dspy.codeact.iteration', {
-        iteration: iteration,
-        max_iterations: @max_iterations,
-        history_length: history.length
-      }) do
+      DSPy::Context.with_span(
+        operation: 'codeact.iteration',
+        'dspy.module' => 'CodeAct',
+        'codeact.iteration' => iteration,
+        'codeact.max_iterations' => @max_iterations,
+        'codeact.history_length' => history.length
+      ) do
         execution_state = execute_think_code_step(task, context, history, iteration)
         
         observation_decision = process_observation_and_decide_next_step(
@@ -305,10 +297,12 @@ module DSPy
 
     sig { params(ruby_code: String, iteration: Integer).returns([T.nilable(String), String]) }
     def execute_ruby_code_with_instrumentation(ruby_code, iteration)
-      Instrumentation.instrument('dspy.codeact.code_execution', {
-        iteration: iteration,
-        code_length: ruby_code.length
-      }) do
+      DSPy::Context.with_span(
+        operation: 'codeact.code_execution',
+        'dspy.module' => 'CodeAct',
+        'codeact.iteration' => iteration,
+        'code.length' => ruby_code.length
+      ) do
         execute_ruby_code_safely(ruby_code)
       end
     end
@@ -355,23 +349,23 @@ module DSPy
 
     sig { params(iteration: Integer, thought: String, ruby_code: String, execution_result: T.nilable(String), error_message: T.nilable(String)).void }
     def emit_iteration_complete_event(iteration, thought, ruby_code, execution_result, error_message)
-      Instrumentation.emit('dspy.codeact.iteration_complete', {
-        iteration: iteration,
-        thought: thought,
-        ruby_code: ruby_code,
-        execution_result: execution_result,
-        error_message: error_message,
-        success: error_message.nil?
+      DSPy.log('codeact.iteration_complete', **{
+        'codeact.iteration' => iteration,
+        'codeact.thought' => thought,
+        'codeact.ruby_code' => ruby_code,
+        'codeact.execution_result' => execution_result,
+        'codeact.error_message' => error_message,
+        'codeact.success' => error_message.nil?
       })
     end
 
     sig { params(iterations_count: Integer, final_answer: T.nilable(String), history: T::Array[CodeActHistoryEntry]).void }
     def handle_max_iterations_if_needed(iterations_count, final_answer, history)
       if iterations_count >= @max_iterations && final_answer.nil?
-        Instrumentation.emit('dspy.codeact.max_iterations', {
-          iteration_count: iterations_count,
-          max_iterations: @max_iterations,
-          final_history_length: history.length
+        DSPy.log('codeact.max_iterations', **{
+          'codeact.iteration_count' => iterations_count,
+          'codeact.max_iterations' => @max_iterations,
+          'codeact.final_history_length' => history.length
         })
       end
     end

data/lib/dspy/context.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module DSPy
+  class Context
+    class << self
+      def current
+        Thread.current[:dspy_context] ||= {
+          trace_id: SecureRandom.uuid,
+          span_stack: []
+        }
+      end
+      
+      def with_span(operation:, **attributes)
+        span_id = SecureRandom.uuid
+        parent_span_id = current[:span_stack].last
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        
+        # Prepare attributes with context information
+        span_attributes = {
+          trace_id: current[:trace_id],
+          span_id: span_id,
+          parent_span_id: parent_span_id,
+          operation: operation,
+          **attributes
+        }
+        
+        # Log span start with proper hierarchy
+        DSPy.log('span.start', **span_attributes)
+        
+        # Create OpenTelemetry span if observability is enabled
+        otel_span = nil
+        if DSPy::Observability.enabled?
+          otel_span = DSPy::Observability.start_span(operation, span_attributes)
+        end
+        
+        # Push to stack for child spans
+        current[:span_stack].push(span_id)
+        
+        begin
+          result = yield
+        ensure
+          # Pop from stack
+          current[:span_stack].pop
+          
+          # Log span end with duration
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+          DSPy.log('span.end',
+            trace_id: current[:trace_id],
+            span_id: span_id,
+            duration_ms: duration_ms
+          )
+          
+          # Finish OpenTelemetry span
+          DSPy::Observability.finish_span(otel_span) if otel_span
+        end
+        
+        result
+      end
+      
+      def clear!
+        Thread.current[:dspy_context] = nil
+      end
+    end
+  end
+end

data/lib/dspy/evaluate.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'sorbet-runtime'
-require_relative 'instrumentation'
 require_relative 'example'
 
 module DSPy
@@ -138,10 +137,12 @@ module DSPy
     # Evaluate program on a single example
     sig { params(example: T.untyped, trace: T.nilable(T.untyped)).returns(EvaluationResult) }
     def call(example, trace: nil)
-      Instrumentation.instrument('dspy.evaluation.example', {
-        program_class: @program.class.name,
-        has_metric: !@metric.nil?
-      }) do
+      DSPy::Context.with_span(
+        operation: 'evaluation.example',
+        'dspy.module' => 'Evaluator',
+        'evaluation.program' => @program.class.name,
+        'evaluation.has_metric' => !@metric.nil?
+      ) do
         begin
           # Extract input from example - support both hash and object formats
           input_values = extract_input_values(example)
@@ -209,12 +210,14 @@ module DSPy
       ).returns(BatchEvaluationResult)
     end
     def evaluate(devset, display_progress: true, display_table: false, return_outputs: true)
-      Instrumentation.instrument('dspy.evaluation.batch', {
-        program_class: @program.class.name,
-        num_examples: devset.length,
-        has_metric: !@metric.nil?,
-        num_threads: @num_threads
-      }) do
+      DSPy::Context.with_span(
+        operation: 'evaluation.batch',
+        'dspy.module' => 'Evaluator',
+        'evaluation.program' => @program.class.name,
+        'evaluation.num_examples' => devset.length,
+        'evaluation.has_metric' => !@metric.nil?,
+        'evaluation.num_threads' => @num_threads
+      ) do
         results = []
         errors = 0
         
@@ -266,12 +269,12 @@ module DSPy
         end
         
         # Emit batch completion event
-        Instrumentation.emit('dspy.evaluation.batch_complete', {
-          program_class: @program.class.name,
-          total_examples: batch_result.total_examples,
-          passed_examples: batch_result.passed_examples,
-          pass_rate: batch_result.pass_rate,
-          aggregated_metrics: aggregated_metrics
+        DSPy.log('evaluation.batch_complete', **{
+          'evaluation.program_class' => @program.class.name,
+          'evaluation.total_examples' => batch_result.total_examples,
+          'evaluation.passed_examples' => batch_result.passed_examples,
+          'evaluation.pass_rate' => batch_result.pass_rate,
+          'evaluation.aggregated_metrics' => aggregated_metrics
         })
         
         if display_progress

data/lib/dspy/lm.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'sorbet-runtime'
+
 # Load adapter infrastructure
 require_relative 'lm/errors'
 require_relative 'lm/response'
@@ -7,8 +9,6 @@ require_relative 'lm/adapter'
 require_relative 'lm/adapter_factory'
 
 # Load instrumentation
-require_relative 'instrumentation'
-require_relative 'instrumentation/token_tracker'
 
 # Load adapters
 require_relative 'lm/adapters/openai_adapter'
@@ -25,6 +25,7 @@ require_relative 'lm/message_builder'
 
 module DSPy
   class LM
+    extend T::Sig
     attr_reader :model_id, :api_key, :model, :provider, :adapter
 
     def initialize(model_id, api_key: nil, **options)
@@ -49,18 +50,8 @@ module DSPy
         chat_with_strategy(messages, signature_class, &block)
       end
       
-      # Instrument response parsing
-      if should_emit_lm_events?
-        parsed_result = Instrumentation.instrument('dspy.lm.response.parsed', {
-          signature_class: signature_class.name,
-          provider: provider,
-          response_length: response.content&.length || 0
-        }) do
-          parse_response(response, input_values, signature_class)
-        end
-      else
-        parsed_result = parse_response(response, input_values, signature_class)
-      end
+      # Parse response (no longer needs separate instrumentation)
+      parsed_result = parse_response(response, input_values, signature_class)
       
       parsed_result
     end
@@ -227,25 +218,28 @@ module DSPy
       end.join(' ')
       input_size = input_text.length
       
-      response = nil
-      
-      if should_emit_lm_events?
-        # Emit dspy.lm.request event
-        response = Instrumentation.instrument('dspy.lm.request', {
-          gen_ai_operation_name: 'chat',
-          gen_ai_system: provider,
-          gen_ai_request_model: model,
-          signature_class: signature_class_name,
-          provider: provider,
-          adapter_class: adapter.class.name,
-          input_size: input_size
-        }, &execution_block)
+      # Wrap LLM call in span tracking
+      response = DSPy::Context.with_span(
+        operation: 'llm.generate',
+        'gen_ai.system' => provider,
+        'gen_ai.request.model' => model,
+        'dspy.signature' => signature_class_name
+      ) do
+        result = execution_block.call
         
-        # Extract and emit token usage
-        emit_token_usage(response, signature_class_name)
-      else
-        # Consolidated mode: execute without instrumentation
-        response = execution_block.call
+        # Add usage data if available
+        if result.respond_to?(:usage) && result.usage
+          usage = result.usage
+          DSPy.log('span.attributes',
+            span_id: DSPy::Context.current[:span_stack].last,
+            'gen_ai.response.model' => result.respond_to?(:model) ? result.model : nil,
+            'gen_ai.usage.prompt_tokens' => usage.respond_to?(:input_tokens) ? usage.input_tokens : nil,
+            'gen_ai.usage.completion_tokens' => usage.respond_to?(:output_tokens) ? usage.output_tokens : nil,
+            'gen_ai.usage.total_tokens' => usage.respond_to?(:total_tokens) ? usage.total_tokens : nil
+          )
+        end
+        
+        result
       end
       
       response
@@ -253,19 +247,60 @@ module DSPy
 
     # Common method to emit token usage events
     def emit_token_usage(response, signature_class_name)
-      token_usage = Instrumentation::TokenTracker.extract_token_usage(response, provider)
+      token_usage = extract_token_usage(response)
       
       if token_usage.any?
-        Instrumentation.emit('dspy.lm.tokens', token_usage.merge({
-          gen_ai_system: provider,
-          gen_ai_request_model: model,
-          signature_class: signature_class_name
+        DSPy.log('lm.tokens', **token_usage.merge({
+          'gen_ai.system' => provider,
+          'gen_ai.request.model' => model,
+          'dspy.signature' => signature_class_name
         }))
       end
       
       token_usage
     end
 
+    private
+
+    # Extract token usage from API responses
+    sig { params(response: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+    def extract_token_usage(response)
+      return {} unless response&.usage
+      
+      # Handle Usage struct objects
+      if response.usage.respond_to?(:input_tokens)
+        return {
+          input_tokens: response.usage.input_tokens,
+          output_tokens: response.usage.output_tokens,
+          total_tokens: response.usage.total_tokens
+        }.compact
+      end
+      
+      # Handle hash-based usage (for VCR compatibility)
+      usage = response.usage
+      return {} unless usage.is_a?(Hash)
+      
+      case provider.to_s.downcase
+      when 'openai'
+        {
+          input_tokens: usage[:prompt_tokens] || usage['prompt_tokens'],
+          output_tokens: usage[:completion_tokens] || usage['completion_tokens'], 
+          total_tokens: usage[:total_tokens] || usage['total_tokens']
+        }.compact
+      when 'anthropic'
+        {
+          input_tokens: usage[:input_tokens] || usage['input_tokens'],
+          output_tokens: usage[:output_tokens] || usage['output_tokens'],
+          total_tokens: (usage[:input_tokens] || usage['input_tokens'] || 0) +
+                       (usage[:output_tokens] || usage['output_tokens'] || 0)
+        }.compact
+      else
+        {}
+      end
+    end
+
+    public
+
     def validate_messages!(messages)
       unless messages.is_a?(Array)
         raise ArgumentError, "messages must be an array"

data/lib/dspy/memory/memory_compactor.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'sorbet-runtime'
-require_relative '../instrumentation'
 
 module DSPy
   module Memory
@@ -51,7 +50,7 @@ module DSPy
       # Main compaction entry point - checks all triggers and compacts if needed
       sig { params(store: MemoryStore, embedding_engine: EmbeddingEngine, user_id: T.nilable(String)).returns(T::Hash[Symbol, T.untyped]) }
       def compact_if_needed!(store, embedding_engine, user_id: nil)
-        DSPy::Instrumentation.instrument('dspy.memory.compaction_check', { user_id: user_id }) do
+        DSPy::Context.with_span(operation: 'memory.compaction_check', 'memory.user_id' => user_id) do
           results = {}
           
           # Check triggers in order of impact
@@ -143,7 +142,7 @@ module DSPy
       # Remove oldest memories when over size limit
       sig { params(store: MemoryStore, user_id: T.nilable(String)).returns(T::Hash[Symbol, T.untyped]) }
       def perform_size_compaction!(store, user_id)
-        DSPy::Instrumentation.instrument('dspy.memory.size_compaction', { user_id: user_id }) do
+        DSPy::Context.with_span(operation: 'memory.size_compaction', 'memory.user_id' => user_id) do
           current_count = store.count(user_id: user_id)
           target_count = (@max_memories * 0.8).to_i  # Remove to 80% of limit
           remove_count = current_count - target_count
@@ -182,7 +181,7 @@ module DSPy
       # Remove memories older than age limit
       sig { params(store: MemoryStore, user_id: T.nilable(String)).returns(T::Hash[Symbol, T.untyped]) }
       def perform_age_compaction!(store, user_id)
-        DSPy::Instrumentation.instrument('dspy.memory.age_compaction', { user_id: user_id }) do
+        DSPy::Context.with_span(operation: 'memory.age_compaction', 'memory.user_id' => user_id) do
           cutoff_time = Time.now - (@max_age_days * 24 * 60 * 60)
           all_memories = store.list(user_id: user_id)
           old_memories = all_memories.select { |m| m.created_at < cutoff_time }
@@ -206,7 +205,7 @@ module DSPy
       # Remove near-duplicate memories using embedding similarity
       sig { params(store: MemoryStore, embedding_engine: EmbeddingEngine, user_id: T.nilable(String)).returns(T::Hash[Symbol, T.untyped]) }
       def perform_deduplication!(store, embedding_engine, user_id)
-        DSPy::Instrumentation.instrument('dspy.memory.deduplication', { user_id: user_id }) do
+        DSPy::Context.with_span(operation: 'memory.deduplication', 'memory.user_id' => user_id) do
           memories = store.list(user_id: user_id)
           memories_with_embeddings = memories.select(&:embedding)
           
@@ -259,7 +258,7 @@ module DSPy
       # Remove memories with low relevance (low access patterns)
       sig { params(store: MemoryStore, user_id: T.nilable(String)).returns(T::Hash[Symbol, T.untyped]) }
       def perform_relevance_pruning!(store, user_id)
-        DSPy::Instrumentation.instrument('dspy.memory.relevance_pruning', { user_id: user_id }) do
+        DSPy::Context.with_span(operation: 'memory.relevance_pruning', 'memory.user_id' => user_id) do
           memories = store.list(user_id: user_id)
           total_access = memories.sum(&:access_count)
           return { removed_count: 0, trigger: 'no_access_data' } if total_access == 0

data/lib/dspy/memory/memory_manager.rb

@@ -216,10 +216,11 @@ module DSPy
       # Force memory compaction (useful for testing or manual cleanup)
       sig { params(user_id: T.nilable(String)).returns(T::Hash[Symbol, T.untyped]) }
       def force_compact!(user_id = nil)
-        DSPy::Instrumentation.instrument('dspy.memory.compaction_complete', { 
-          user_id: user_id, 
-          forced: true 
-        }) do
+        DSPy::Context.with_span(
+          operation: 'memory.compaction_complete',
+          'memory.user_id' => user_id,
+          'memory.forced' => true
+        ) do
           results = {}
           
           # Run all compaction strategies regardless of thresholds