dspy 0.27.1 → 0.27.2

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

@@ -24,20 +24,27 @@ module DSPy
           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)
+        # Handle O1 model restrictions - convert system messages to user messages
+        if o1_model?(model)
+          normalized_messages = handle_o1_messages(normalized_messages)
         end
 
         request_params = {
           model: model,
-          messages: normalized_messages,
-          temperature: temperature
+          messages: normalized_messages
         }
 
+        # Add temperature based on model capabilities  
+        unless o1_model?(model)
+          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[:temperature] = temperature
+        end
+
         # Add response format if provided by strategy
         if response_format
           request_params[:response_format] = response_format
@@ -148,6 +155,26 @@ module DSPy
           end
         end
       end
+
+      # Check if model is an O1 reasoning model (includes O1, O3, O4 series)
+      def o1_model?(model_name)
+        model_name.match?(/^o[134](-.*)?$/)
+      end
+
+      # Handle O1 model message restrictions
+      def handle_o1_messages(messages)
+        messages.map do |msg|
+          # Convert system messages to user messages for O1 models
+          if msg[:role] == 'system'
+            {
+              role: 'user',
+              content: "Instructions: #{msg[:content]}"
+            }
+          else
+            msg
+          end
+        end
+      end
     end
   end
 end

data/lib/dspy/lm/retry_handler.rb

@@ -55,7 +55,7 @@ module DSPy
             
             # Let strategy handle the error first
             if strategy.handle_error(e)
-              DSPy.logger.info("Strategy #{strategy.name} handled error, will try next strategy")
+              DSPy.logger.debug("Strategy #{strategy.name} handled error, trying next strategy")
               next # Try next strategy
             end
             
@@ -64,9 +64,18 @@ module DSPy
               retry_count += 1
               backoff_time = calculate_backoff(retry_count)
               
-              DSPy.logger.warn(
-                "Retrying #{strategy.name} after error (attempt #{retry_count}/#{max_retries_for_strategy(strategy)}): #{e.message}"
-              )
+              # Use debug for structured output strategies since they often have expected failures
+              log_level = ["openai_structured_output", "gemini_structured_output"].include?(strategy.name) ? :debug : :warn
+              
+              if log_level == :debug
+                DSPy.logger.debug(
+                  "Retrying #{strategy.name} after error (attempt #{retry_count}/#{max_retries_for_strategy(strategy)}): #{e.message}"
+                )
+              else
+                DSPy.logger.warn(
+                  "Retrying #{strategy.name} after error (attempt #{retry_count}/#{max_retries_for_strategy(strategy)}): #{e.message}"
+                )
+              end
               
               Async::Task.current.sleep(backoff_time) if backoff_time > 0
               retry
@@ -101,8 +110,8 @@ module DSPy
       sig { params(strategy: Strategies::BaseStrategy).returns(Integer) }
       def max_retries_for_strategy(strategy)
         case strategy.name
-        when "openai_structured_output"
-          1 # Structured outputs rarely benefit from retries
+        when "openai_structured_output", "gemini_structured_output"
+          1 # Structured outputs rarely benefit from retries, most errors are permanent
         when "anthropic_extraction"
           2 # Anthropic can be a bit more variable
         else

data/lib/dspy/lm/strategies/gemini_structured_output_strategy.rb

@@ -31,13 +31,13 @@ module DSPy
 
         sig { override.params(messages: T::Array[T::Hash[Symbol, String]], request_params: T::Hash[Symbol, T.untyped]).void }
         def prepare_request(messages, request_params)
-          # Convert signature to Gemini schema format
+          # Convert signature to Gemini JSON Schema format (supports oneOf/anyOf for unions)
           schema = DSPy::LM::Adapters::Gemini::SchemaConverter.to_gemini_format(signature_class)
           
-          # Add generation_config for structured output
+          # Add generation_config for structured output using JSON Schema format
           request_params[:generation_config] = {
             response_mime_type: "application/json",
-            response_schema: schema
+            response_json_schema: schema  # Use JSON Schema format for proper union support
           }
         end
 
@@ -52,12 +52,25 @@ module DSPy
         def handle_error(error)
           # Handle Gemini-specific structured output errors
           error_msg = error.message.to_s.downcase
-          if error_msg.include?("schema") || error_msg.include?("generation_config") || error_msg.include?("response_schema")
-            # Log the error and return true to indicate we handled it
-            # This allows fallback to another strategy
-            DSPy.logger.warn("Gemini structured output failed: #{error.message}")
-            true
+          
+          # Check for permanent errors that shouldn't be retried
+          permanent_error_patterns = [
+            "schema",
+            "generation_config", 
+            "response_schema",
+            "unknown name \"response_mime_type\"",
+            "unknown name \"response_schema\"",
+            "invalid json payload",
+            "no matching sse interaction found",  # VCR test configuration issue
+            "cannot find field"
+          ]
+          
+          if permanent_error_patterns.any? { |pattern| error_msg.include?(pattern) }
+            # These are permanent errors - no point retrying
+            DSPy.logger.debug("Gemini structured output failed (permanent error, skipping retries): #{error.message}")
+            true # Skip retries and try next strategy
           else
+            # Unknown error - let retry logic handle it
             false
           end
         end

data/lib/dspy/lm.rb

@@ -2,6 +2,7 @@
 
 require 'sorbet-runtime'
 require 'async'
+require 'securerandom'
 
 # Load adapter infrastructure
 require_relative 'lm/errors'
@@ -42,7 +43,17 @@ module DSPy
     end
 
     def chat(inference_module, input_values, &block)
+      # Capture the current DSPy context before entering Sync block
+      parent_context = DSPy::Context.current.dup
+      
       Sync do
+        # Properly restore the context in the new fiber created by Sync
+        # We need to set both thread and fiber storage for the new context system
+        thread_key = :"dspy_context_#{Thread.current.object_id}"
+        Thread.current[thread_key] = parent_context
+        Thread.current[:dspy_context] = parent_context  # Keep for backward compatibility
+        Fiber[:dspy_context] = parent_context
+        
         signature_class = inference_module.signature_class
         
         # Build messages from inference module
@@ -225,7 +236,7 @@ module DSPy
       # Wrap LLM call in span tracking
       response = DSPy::Context.with_span(
         operation: 'llm.generate',
-        'langfuse.observation.type' => 'generation',
+        **DSPy::ObservationType::Generation.langfuse_attributes,
         'langfuse.observation.input' => input_json,
         'gen_ai.system' => provider,
         'gen_ai.request.model' => model,
@@ -267,11 +278,26 @@ module DSPy
       token_usage = extract_token_usage(response)
       
       if token_usage.any?
-        DSPy.log('lm.tokens', **token_usage.merge({
+        event_attributes = token_usage.merge({
           'gen_ai.system' => provider,
           'gen_ai.request.model' => model,
           'dspy.signature' => signature_class_name
-        }))
+        })
+        
+        # Add timing and request correlation if available
+        request_id = Thread.current[:dspy_request_id]
+        start_time = Thread.current[:dspy_request_start_time]
+        
+        if request_id
+          event_attributes['request_id'] = request_id
+        end
+        
+        if start_time
+          duration = Time.now - start_time
+          event_attributes['duration'] = duration
+        end
+        
+        DSPy.event('lm.tokens', event_attributes)
       end
       
       token_usage
@@ -341,15 +367,32 @@ module DSPy
     end
 
     def execute_raw_chat(messages, &streaming_block)
-      response = instrument_lm_request(messages, 'RawPrompt') do
-        # Convert messages to hash format for adapter
-        hash_messages = messages_to_hash_array(messages)
-        # Direct adapter call, no strategies or JSON parsing
-        adapter.chat(messages: hash_messages, signature: nil, &streaming_block)
-      end
+      # Generate unique request ID for tracking
+      request_id = SecureRandom.hex(8)
+      start_time = Time.now
+      
+      # Store request context for correlation
+      Thread.current[:dspy_request_id] = request_id
+      Thread.current[:dspy_request_start_time] = start_time
       
-      # Return raw response content, not parsed JSON
-      response.content
+      begin
+        response = instrument_lm_request(messages, 'RawPrompt') do
+          # Convert messages to hash format for adapter
+          hash_messages = messages_to_hash_array(messages)
+          # Direct adapter call, no strategies or JSON parsing
+          adapter.chat(messages: hash_messages, signature: nil, &streaming_block)
+        end
+        
+        # Emit the standard lm.tokens event (consistent with other LM calls)
+        emit_token_usage(response, 'RawPrompt')
+        
+        # Return raw response content, not parsed JSON
+        response.content
+      ensure
+        # Clean up thread-local storage
+        Thread.current[:dspy_request_id] = nil
+        Thread.current[:dspy_request_start_time] = nil
+      end
     end
     
     # Convert messages to normalized Message objects

data/lib/dspy/memory/local_embedding_engine.rb

@@ -36,17 +36,33 @@ module DSPy
 
       sig { override.params(text: String).returns(T::Array[Float]) }
       def embed(text)
-        ensure_ready!
-        
-        # Preprocess text
-        cleaned_text = preprocess_text(text)
-        
-        # Generate embedding
-        result = @model.call(cleaned_text)
-        
-        # Extract embedding array and normalize
-        embedding = result.first.to_a
-        normalize_vector(embedding)
+        DSPy::Context.with_span(
+          operation: 'embedding.generate',
+          **DSPy::ObservationType::Embedding.langfuse_attributes,
+          'embedding.model' => @model_name,
+          'embedding.input' => text[0..200], # Truncate for logging
+          'embedding.input_length' => text.length
+        ) do |span|
+          ensure_ready!
+          
+          # Preprocess text
+          cleaned_text = preprocess_text(text)
+          
+          # Generate embedding
+          result = @model.call(cleaned_text)
+          
+          # Extract embedding array and normalize
+          embedding = result.first.to_a
+          normalized = normalize_vector(embedding)
+          
+          # Add embedding metadata to span
+          if span
+            span.set_attribute('embedding.dimension', normalized.length)
+            span.set_attribute('embedding.magnitude', Math.sqrt(normalized.sum { |x| x * x }))
+          end
+          
+          normalized
+        end
       end
 
       sig { override.params(texts: T::Array[String]).returns(T::Array[T::Array[Float]]) }

data/lib/dspy/memory/memory_manager.rb

@@ -95,15 +95,32 @@ module DSPy
       # Semantic search using embeddings
       sig { params(query: String, user_id: T.nilable(String), limit: T.nilable(Integer), threshold: T.nilable(Float)).returns(T::Array[MemoryRecord]) }
       def search_memories(query, user_id: nil, limit: 10, threshold: 0.5)
-        # Generate embedding for the query
-        query_embedding = @embedding_engine.embed(query)
-        
-        # Perform vector search if supported
-        if @store.supports_vector_search?
-          @store.vector_search(query_embedding, user_id: user_id, limit: limit, threshold: threshold)
-        else
-          # Fallback to text search
-          @store.search(query, user_id: user_id, limit: limit)
+        DSPy::Context.with_span(
+          operation: 'memory.search',
+          **DSPy::ObservationType::Retriever.langfuse_attributes,
+          'retriever.query' => query,
+          'retriever.user_id' => user_id,
+          'retriever.limit' => limit,
+          'retriever.threshold' => threshold
+        ) do |span|
+          # Generate embedding for the query
+          query_embedding = @embedding_engine.embed(query)
+          
+          # Perform vector search if supported
+          results = if @store.supports_vector_search?
+            @store.vector_search(query_embedding, user_id: user_id, limit: limit, threshold: threshold)
+          else
+            # Fallback to text search
+            @store.search(query, user_id: user_id, limit: limit)
+          end
+          
+          # Add retrieval results to span
+          if span
+            span.set_attribute('retriever.results_count', results.length)
+            span.set_attribute('retriever.results', results.map { |r| { id: r.id, content: r.content[0..100] } }.to_json)
+          end
+          
+          results
         end
       end
 

data/lib/dspy/mixins/type_coercion.rb

@@ -34,6 +34,8 @@ module DSPy
           coerce_union_value(value, prop_type)
         when ->(type) { array_type?(type) }
           coerce_array_value(value, prop_type)
+        when ->(type) { hash_type?(type) }
+          coerce_hash_value(value, prop_type)
         when ->(type) { enum_type?(type) }
           extract_enum_class(prop_type).deserialize(value)
         when Float, ->(type) { simple_type_match?(type, Float) }
@@ -88,6 +90,12 @@ module DSPy
         true
       end
 
+      # Checks if a type is a hash type
+      sig { params(type: T.untyped).returns(T::Boolean) }
+      def hash_type?(type)
+        type.is_a?(T::Types::TypedHash)
+      end
+
       # Checks if a type is a struct type
       sig { params(type: T.untyped).returns(T::Boolean) }
       def struct_type?(type)
@@ -124,6 +132,28 @@ module DSPy
         value.map { |element| coerce_value_to_type(element, element_type) }
       end
 
+      # Coerces a hash value, converting keys and values as needed
+      sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
+      def coerce_hash_value(value, prop_type)
+        return value unless value.is_a?(Hash)
+        return value unless prop_type.is_a?(T::Types::TypedHash)
+        
+        key_type = prop_type.keys
+        value_type = prop_type.values
+        
+        # Convert string keys to enum instances if key_type is an enum
+        result = if enum_type?(key_type)
+          enum_class = extract_enum_class(key_type)
+          value.transform_keys { |k| enum_class.deserialize(k.to_s) }
+        else
+          # For non-enum keys, coerce them to the expected type
+          value.transform_keys { |k| coerce_value_to_type(k, key_type) }
+        end
+        
+        # Coerce values to their expected types
+        result.transform_values { |v| coerce_value_to_type(v, value_type) }
+      end
+
       # Coerces a struct value from a hash
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_struct_value(value, prop_type)

data/lib/dspy/module.rb

@@ -2,6 +2,7 @@
 
 require 'sorbet-runtime'
 require 'dry-configurable'
+require_relative 'context'
 
 module DSPy
   class Module
@@ -21,8 +22,25 @@ module DSPy
         .returns(T.type_parameter(:O))
     end
     def forward(**input_values)
-      # Cast the result of forward_untyped to the expected output type
-      T.cast(forward_untyped(**input_values), T.type_parameter(:O))
+      # Create span for this module's execution
+      observation_type = DSPy::ObservationType.for_module_class(self.class)
+      DSPy::Context.with_span(
+        operation: "#{self.class.name}.forward",
+        **observation_type.langfuse_attributes,
+        'langfuse.observation.input' => input_values.to_json,
+        'dspy.module' => self.class.name
+      ) do |span|
+        result = forward_untyped(**input_values)
+        
+        # Add output to span
+        if span && result
+          output_json = result.respond_to?(:to_h) ? result.to_h.to_json : result.to_json rescue result.to_s
+          span.set_attribute('langfuse.observation.output', output_json)
+        end
+        
+        # Cast the result of forward_untyped to the expected output type
+        T.cast(result, T.type_parameter(:O))
+      end
     end
 
     # The implementation method that subclasses must override

data/lib/dspy/observability/observation_type.rb

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

@@ -15,6 +15,13 @@ module DSPy
         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
         end

data/lib/dspy/predict.rb

@@ -131,46 +131,32 @@ module DSPy
       with_prompt(@prompt.add_examples(examples))
     end
 
-    sig { override.params(kwargs: T.untyped).returns(T.type_parameter(:O)) }
-    def forward(**kwargs)
-      @last_input_values = kwargs.clone
-      T.cast(forward_untyped(**kwargs), T.type_parameter(:O))
-    end
+    # Remove forward override to let Module#forward handle span creation
 
     sig { params(input_values: T.untyped).returns(T.untyped) }
     def forward_untyped(**input_values)
-      # 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 |span|
-        # 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 = current_lm.chat(self, input_values)
-        processed_output = process_lm_output(output_attributes)
-        
-        # Create combined result struct
-        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', DSPy::Utils::Serialization.to_json(output_hash))
-        end
-        
-        prediction_result
+      # Module#forward handles span creation, we just do the prediction logic
+      
+      # Store input values for optimization
+      @last_input_values = input_values.clone
+      
+      # 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 = current_lm.chat(self, input_values)
+      processed_output = process_lm_output(output_attributes)
+      
+      # Create combined result struct
+      prediction_result = create_prediction_result(input_values, processed_output)
+      
+      prediction_result
     end
 
     private

data/lib/dspy/re_act.rb

@@ -241,9 +241,10 @@ 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)
-      # Track each iteration with span
+      # Track each iteration with agent span
       DSPy::Context.with_span(
         operation: 'react.iteration',
+        **DSPy::ObservationType::Agent.langfuse_attributes,
         'dspy.module' => 'ReAct',
         'react.iteration' => iteration,
         'react.max_iterations' => @max_iterations,
@@ -355,6 +356,7 @@ module DSPy
       if action && @tools[action.downcase]
         DSPy::Context.with_span(
           operation: 'react.tool_call',
+          **DSPy::ObservationType::Tool.langfuse_attributes,
           'dspy.module' => 'ReAct',
           'react.iteration' => iteration,
           'tool.name' => action.downcase,
@@ -419,7 +421,7 @@ 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)
-      DSPy.log('react.iteration_complete', **{
+      DSPy.event('react.iteration_complete', {
         'react.iteration' => iteration,
         'react.thought' => thought,
         'react.action' => action,
@@ -432,7 +434,7 @@ module DSPy
     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?
-        DSPy.log('react.max_iterations', **{
+        DSPy.event('react.max_iterations', {
           'react.iteration_count' => iterations_count,
           'react.max_iterations' => @max_iterations,
           'react.tools_used' => tools_used.uniq,