dspy 0.23.0 → 0.24.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a74fa7e459b97d25d515492a9c8ef786981ca5212dcfe970b9f8311e5a2b7be4
-  data.tar.gz: 7cf45b5f12849e55b1a180f3b39e9054357a23477bbc8dacad4b85be35bc234a
+  metadata.gz: '0946116ac08ee09e62d204db418f2d45f62eb4d4b1eff8306de1780a8cdfba8f'
+  data.tar.gz: a294c49d86d084940738ebb39da6c7d3b8fef15064ff2c2cb15c07a90acdec8f
 SHA512:
-  metadata.gz: d7610ab7261fb039264acf5c2de69b70c7cc33932335faf70b97ba65e459a0d2048a428e8b1f49b6ccd73de3455ad4adc9351bb2e5dc58acfac47323086b7c3d
-  data.tar.gz: de8c212916e2135c27e881be529f12121439b12bbc8effca7dd98d6aa912f6057ae304e9d1aa5eee6c2dd2fafee904b3665cde4569f61d91360cacb6acbc2e43
+  metadata.gz: 91141a65593592604c301f3c51f48fac2c29b654c871c3155a055202d25efdcf7511ff4fda0372021f686b864f1e078e89fed27d245300f20966de62e3e295c5
+  data.tar.gz: e4885370fde056ff4dda5464901f0f3e460bbf0cf2985e079088adf67d091718fe72e8ee0efc34999b021bb3e238649a782f12c3fec1162a8b6b13576bd25dc0

data/README.md

@@ -5,16 +5,15 @@
 [![Build Status](https://img.shields.io/github/actions/workflow/status/vicentereig/dspy.rb/ruby.yml?branch=main&label=build)](https://github.com/vicentereig/dspy.rb/actions/workflows/ruby.yml)
 [![Documentation](https://img.shields.io/badge/docs-vicentereig.github.io%2Fdspy.rb-blue)](https://vicentereig.github.io/dspy.rb/)
 
-**Build reliable LLM applications in Ruby using composable, type-safe modules.**
+**Build reliable LLM applications in idiomatic Ruby using composable, type-safe modules.**
 
-DSPy.rb brings structured LLM programming to Ruby developers. Instead of wrestling with prompt strings and parsing 
-responses, you define typed signatures and compose them into pipelines that just work.
+The Ruby framework for programming with large language models. DSPy.rb brings structured LLM programming to Ruby developers. Instead of wrestling with prompt strings and parsing responses, you define typed signatures using idiomatic Ruby to compose and decompose AI Worklows and AI Agents.
 
-Traditional prompting is like writing code with string concatenation: it works until it doesn't. DSPy.rb brings you 
+**Prompts are the just Functions.** Traditional prompting is like writing code with string concatenation: it works until it doesn't. DSPy.rb brings you 
 the programming approach pioneered by [dspy.ai](https://dspy.ai/): instead of crafting fragile prompts, you define modular 
 signatures and let the framework handle the messy details.
 
-DSPy.rb is an idiomatic Ruby port of Stanford's [DSPy framework](https://github.com/stanfordnlp/dspy). While implementing 
+DSPy.rb is an idiomatic Ruby surgical port of Stanford's [DSPy framework](https://github.com/stanfordnlp/dspy). While implementing 
 the core concepts of signatures, predictors, and optimization from the original Python library, DSPy.rb embraces Ruby 
 conventions and adds Ruby-specific innovations like CodeAct agents and enhanced production instrumentation.
 
@@ -192,6 +191,7 @@ DSPy.rb has rapidly evolved from experimental to production-ready:
 - ✅ **Optimization Framework** - MIPROv2 algorithm with storage & persistence
 
 ### Recent Advances  
+- ✅ **Enhanced Langfuse Integration (v0.24.1)** - Comprehensive OpenTelemetry span reporting with proper input/output, hierarchical nesting, accurate timing, and observation types
 - ✅ **Comprehensive Multimodal Framework** - Complete image analysis with `DSPy::Image`, type-safe bounding boxes, vision model integration
 - ✅ **Advanced Type System** - `T::Enum` integration, union types for agentic workflows, complex type coercion
 - ✅ **Production-Ready Evaluation** - Multi-factor metrics beyond accuracy, error-resilient evaluation pipelines

data/lib/dspy/chain_of_thought.rb

@@ -82,16 +82,45 @@ module DSPy
     sig { returns(T.class_of(DSPy::Signature)) }
     attr_reader :original_signature
 
-    # Override forward_untyped to add ChainOfThought-specific analysis
+    # Override forward_untyped to add ChainOfThought-specific analysis and tracing
     sig { override.params(input_values: T.untyped).returns(T.untyped) }
     def forward_untyped(**input_values)
-      # Call parent prediction logic
-      prediction_result = super(**input_values)
-      
-      # Analyze reasoning if present
-      analyze_reasoning(prediction_result)
-      
-      prediction_result
+      # Wrap in chain-specific span tracking (overrides parent's span attributes)
+      DSPy::Context.with_span(
+        operation: "ChainOfThought.forward",
+        'langfuse.observation.type' => 'chain',
+        'langfuse.observation.input' => input_values.to_json,
+        'dspy.module' => 'ChainOfThought',
+        'dspy.signature' => @original_signature.name
+      ) do |span|
+        # Call parent prediction logic (which will create its own nested span)
+        prediction_result = super(**input_values)
+        
+        # Enhance span with reasoning data
+        if span && prediction_result
+          # Include reasoning in output for chain observation
+          output_with_reasoning = if prediction_result.respond_to?(:reasoning) && prediction_result.reasoning
+            output_hash = prediction_result.respond_to?(:to_h) ? prediction_result.to_h : {}
+            output_hash.merge(reasoning: prediction_result.reasoning)
+          else
+            prediction_result.respond_to?(:to_h) ? prediction_result.to_h : prediction_result.to_s
+          end
+          
+          span.set_attribute('langfuse.observation.output', output_with_reasoning.to_json)
+          
+          # Add reasoning metrics
+          if prediction_result.respond_to?(:reasoning) && prediction_result.reasoning
+            span.set_attribute('cot.reasoning_length', prediction_result.reasoning.length)
+            span.set_attribute('cot.has_reasoning', true)
+            span.set_attribute('cot.reasoning_steps', count_reasoning_steps(prediction_result.reasoning))
+          end
+        end
+        
+        # Analyze reasoning (emits events for backwards compatibility)
+        analyze_reasoning(prediction_result)
+        
+        prediction_result
+      end
     end
 
     private

data/lib/dspy/context.rb

@@ -26,37 +26,45 @@ module DSPy
           **attributes
         }
         
-        # Log span start with proper hierarchy
+        # Log span start with proper hierarchy (internal logging only)
         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
+        # Push to stack for child spans tracking
         current[:span_stack].push(span_id)
         
         begin
-          result = yield
+          # Use OpenTelemetry's proper context management for nesting
+          if DSPy::Observability.enabled? && DSPy::Observability.tracer
+            # Prepare attributes and add trace name for root spans
+            span_attributes = attributes.transform_keys(&:to_s).reject { |k, v| v.nil? }
+            
+            # Set trace name if this is likely a root span (no parent in our stack)
+            if current[:span_stack].length == 1  # This will be the first span
+              span_attributes['langfuse.trace.name'] = operation
+            end
+            
+            DSPy::Observability.tracer.in_span(
+              operation,
+              attributes: span_attributes,
+              kind: :internal
+            ) do |span|
+              yield(span)
+            end
+          else
+            yield(nil)
+          end
         ensure
           # Pop from stack
           current[:span_stack].pop
           
-          # Log span end with duration
+          # Log span end with duration (internal logging only)
           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!

data/lib/dspy/lm/adapters/openai_adapter.rb

@@ -16,18 +16,26 @@ module DSPy
 
       def chat(messages:, signature: nil, response_format: nil, &block)
         normalized_messages = normalize_messages(messages)
-        
+
         # Validate vision support if images are present
         if contains_images?(normalized_messages)
           VisionModels.validate_vision_support!('openai', model)
           # Convert messages to OpenAI format with proper image handling
           normalized_messages = format_multimodal_messages(normalized_messages)
         end
-        
+
+        # Set temperature based on model capabilities
+        temperature = case model
+        when /^gpt-5/, /^gpt-4o/
+          1.0 # GPT-5 and GPT-4o models only support default temperature of 1.0
+        else
+          0.0 # Near-deterministic for other models (0.0 no longer universally supported)
+        end
+
         request_params = {
           model: model,
           messages: normalized_messages,
-          temperature: 0.0 # DSPy default for deterministic responses
+          temperature: temperature
         }
 
         # Add response format if provided by strategy
@@ -48,7 +56,7 @@ module DSPy
 
         begin
           response = @client.chat.completions.create(**request_params)
-          
+
           if response.respond_to?(:error) && response.error
             raise AdapterError, "OpenAI API error: #{response.error}"
           end
@@ -65,7 +73,7 @@ module DSPy
 
           # Convert usage data to typed struct
           usage_struct = UsageFactory.create('openai', usage)
-          
+
           # Create typed metadata
           metadata = ResponseMetadataFactory.create('openai', {
             model: model,
@@ -75,7 +83,7 @@ module DSPy
             system_fingerprint: response.system_fingerprint,
             finish_reason: choice.finish_reason
           })
-          
+
           Response.new(
             content: content,
             usage: usage_struct,
@@ -84,14 +92,14 @@ module DSPy
         rescue => e
           # Check for specific error types and messages
           error_msg = e.message.to_s
-          
+
           # Try to parse error body if it looks like JSON
           error_body = if error_msg.start_with?('{')
                          JSON.parse(error_msg) rescue nil
                        elsif e.respond_to?(:response) && e.response
                          e.response[:body] rescue nil
                        end
-          
+
           # Check for specific image-related errors
           if error_msg.include?('image_parse_error') || error_msg.include?('unsupported image')
             raise AdapterError, "Image processing failed: #{error_msg}. Ensure your image is a valid PNG, JPEG, GIF, or WebP format and under 5MB."
@@ -113,7 +121,7 @@ module DSPy
       def supports_structured_outputs?
         DSPy::LM::Adapters::OpenAI::SchemaConverter.supports_structured_outputs?(model)
       end
-      
+
       def format_multimodal_messages(messages)
         messages.map do |msg|
           if msg[:content].is_a?(Array)
@@ -130,7 +138,7 @@ module DSPy
                 item
               end
             end
-            
+
             {
               role: msg[:role],
               content: formatted_content

data/lib/dspy/lm.rb

@@ -209,35 +209,48 @@ module DSPy
 
     # Common instrumentation method for LM requests
     def instrument_lm_request(messages, signature_class_name, &execution_block)
-      # Handle both Message objects and hash format
-      input_text = messages.map do |m|
+      # Prepare input for tracing - convert messages to JSON for input tracking
+      input_messages = messages.map do |m|
         if m.is_a?(Message)
-          m.content
+          { role: m.role, content: m.content }
         else
-          m[:content]
+          m
         end
-      end.join(' ')
-      input_size = input_text.length
+      end
+      input_json = input_messages.to_json
       
       # Wrap LLM call in span tracking
       response = DSPy::Context.with_span(
         operation: 'llm.generate',
+        'langfuse.observation.type' => 'generation',
+        'langfuse.observation.input' => input_json,
         'gen_ai.system' => provider,
         'gen_ai.request.model' => model,
+        'gen_ai.prompt' => input_json,
         'dspy.signature' => signature_class_name
-      ) do
+      ) do |span|
         result = 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.metadata.model,
-            'gen_ai.usage.prompt_tokens' => usage.input_tokens,
-            'gen_ai.usage.completion_tokens' => usage.output_tokens,
-            'gen_ai.usage.total_tokens' => usage.total_tokens
-          )
+        # Add output and usage data directly to span
+        if span && result
+          # Add completion output
+          if result.content
+            span.set_attribute('langfuse.observation.output', result.content)
+            span.set_attribute('gen_ai.completion', result.content)
+          end
+          
+          # Add response model if available
+          if result.respond_to?(:metadata) && result.metadata&.model
+            span.set_attribute('gen_ai.response.model', result.metadata.model)
+          end
+          
+          # Add token usage
+          if result.respond_to?(:usage) && result.usage
+            usage = result.usage
+            span.set_attribute('gen_ai.usage.prompt_tokens', usage.input_tokens) if usage.input_tokens
+            span.set_attribute('gen_ai.usage.completion_tokens', usage.output_tokens) if usage.output_tokens
+            span.set_attribute('gen_ai.usage.total_tokens', usage.total_tokens) if usage.total_tokens
+          end
         end
         
         result

data/lib/dspy/observability.rb

@@ -20,7 +20,7 @@ module DSPy
 
         # Determine endpoint based on host
         host = ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
-        @endpoint = "#{host}/api/public/otel"
+        @endpoint = "#{host}/api/public/otel/v1/traces"
 
         begin
           # Load OpenTelemetry gems
@@ -73,6 +73,10 @@ module DSPy
         @enabled == true
       end
 
+      def tracer
+        @tracer
+      end
+
       def start_span(operation_name, attributes = {})
         return nil unless enabled? && tracer
 

data/lib/dspy/predict.rb

@@ -141,9 +141,11 @@ module DSPy
       # Wrap prediction in span tracking
       DSPy::Context.with_span(
         operation: "#{self.class.name}.forward",
+        'langfuse.observation.type' => 'span',
+        'langfuse.observation.input' => input_values.to_json,
         'dspy.module' => self.class.name,
         'dspy.signature' => @signature_class.name
-      ) do
+      ) do |span|
         # Validate input
         validate_input_struct(input_values)
         
@@ -158,7 +160,15 @@ module DSPy
         processed_output = process_lm_output(output_attributes)
         
         # Create combined result struct
-        create_prediction_result(input_values, processed_output)
+        prediction_result = create_prediction_result(input_values, processed_output)
+        
+        # Add output to span
+        if span && prediction_result
+          output_hash = prediction_result.respond_to?(:to_h) ? prediction_result.to_h : prediction_result.to_s
+          span.set_attribute('langfuse.observation.output', output_hash.to_json)
+        end
+        
+        prediction_result
       end
     end
 

data/lib/dspy/teleprompt/gepa.rb

@@ -1699,8 +1699,17 @@ module DSPy
           end
           secondary_scores[:token_efficiency] = calculate_token_efficiency(mock_traces, predictions.size)
 
-          # Response consistency
-          response_texts = predictions.map { |p| p[:prediction]&.answer&.to_s || '' }
+          # Response consistency - use first output field for any signature
+          response_texts = predictions.map do |p|
+            pred = p[:prediction]
+            if pred && pred.respond_to?(:class) && pred.class.respond_to?(:props)
+              # Get first output field name and value
+              first_field = pred.class.props.keys.first
+              first_field ? (pred.send(first_field)&.to_s || '') : ''
+            else
+              ''
+            end
+          end
           secondary_scores[:consistency] = calculate_consistency(response_texts)
 
           # Latency performance

data/lib/dspy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DSPy
-  VERSION = "0.23.0"
+  VERSION = "0.24.1"
 end

data/lib/dspy.rb

@@ -99,8 +99,21 @@ module DSPy
     logger.info(attributes)
   end
 
+  # Internal events that should not create OpenTelemetry spans
+  INTERNAL_EVENTS = [
+    'span.start', 
+    'span.end', 
+    'span.attributes',
+    'observability.disabled',
+    'observability.error',
+    'observability.span_error',
+    'observability.span_finish_error',
+    'event.span_creation_error'
+  ].freeze
+
   def self.create_event_span(event_name, attributes)
     return unless DSPy::Observability.enabled?
+    return if INTERNAL_EVENTS.include?(event_name)
     
     begin
       # Flatten nested hashes for OpenTelemetry span attributes

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.1
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.16.0
+        version: 0.22.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.16.0
+        version: 0.22.0
 - !ruby/object:Gem::Dependency
   name: anthropic
   requirement: !ruby/object:Gem::Requirement
@@ -177,8 +177,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.30'
-description: The Ruby framework for programming with large language models. Includes
-  event-driven observability system with OpenTelemetry integration and Langfuse export.
+description: The Ruby framework for programming with large language models. DSPy.rb
+  brings structured LLM programming to Ruby developers. Instead of wrestling with
+  prompt strings and parsing responses, you define typed signatures using idiomatic
+  Ruby to compose and decompose AI Worklows and AI Agents.
 email:
 - hey@vicente.services
 executables: []