dspy 0.27.0 → 0.27.2

data/lib/dspy/lm/adapters/openai/schema_converter.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "sorbet-runtime"
-require_relative "../../cache_manager"
 
 module DSPy
   class LM
@@ -22,22 +21,12 @@ module DSPy
 
           sig { params(signature_class: T.class_of(DSPy::Signature), name: T.nilable(String), strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
           def self.to_openai_format(signature_class, name: nil, strict: true)
-            # Build cache params from the method parameters
-            cache_params = { strict: strict }
-            cache_params[:name] = name if name
-            
-            # Check cache first
-            cache_manager = DSPy::LM.cache_manager
-            cached_schema = cache_manager.get_schema(signature_class, "openai", cache_params)
-            
-            if cached_schema
-              DSPy.logger.debug("Using cached schema for #{signature_class.name}")
-              return cached_schema
-            end
-            
             # Get the output JSON schema from the signature class
             output_schema = signature_class.output_json_schema
             
+            # Convert oneOf to anyOf where safe, or raise error for unsupported cases
+            output_schema = convert_oneof_to_anyof_if_safe(output_schema)
+            
             # Build the complete schema with OpenAI-specific modifications
             dspy_schema = {
               "$schema": "http://json-schema.org/draft-06/schema#",
@@ -59,7 +48,7 @@ module DSPy
             end
 
             # Wrap in OpenAI's required format
-            result = {
+            {
               type: "json_schema",
               json_schema: {
                 name: schema_name,
@@ -67,34 +56,75 @@ module DSPy
                 schema: openai_schema
               }
             }
+          end
+
+          # Convert oneOf to anyOf if safe (discriminated unions), otherwise raise error
+          sig { params(schema: T.untyped).returns(T.untyped) }
+          def self.convert_oneof_to_anyof_if_safe(schema)
+            return schema unless schema.is_a?(Hash)
+            
+            result = schema.dup
+            
+            # Check if this schema has oneOf that we can safely convert
+            if result[:oneOf]
+              if all_have_discriminators?(result[:oneOf])
+                # Safe to convert - discriminators ensure mutual exclusivity
+                result[:anyOf] = result.delete(:oneOf).map { |s| convert_oneof_to_anyof_if_safe(s) }
+              else
+                # Unsafe conversion - raise error
+                raise DSPy::UnsupportedSchemaError.new(
+                  "OpenAI structured outputs do not support oneOf schemas without discriminator fields. " \
+                  "The schema contains union types that cannot be safely converted to anyOf. " \
+                  "Please use enhanced_prompting strategy instead or add discriminator fields to union types."
+                )
+              end
+            end
+            
+            # Recursively process nested schemas
+            if result[:properties].is_a?(Hash)
+              result[:properties] = result[:properties].transform_values { |v| convert_oneof_to_anyof_if_safe(v) }
+            end
             
-            # Cache the result with same params
-            cache_manager.cache_schema(signature_class, "openai", result, cache_params)
+            if result[:items].is_a?(Hash)
+              result[:items] = convert_oneof_to_anyof_if_safe(result[:items])
+            end
+            
+            # Process arrays of schema items
+            if result[:items].is_a?(Array)
+              result[:items] = result[:items].map { |item| 
+                item.is_a?(Hash) ? convert_oneof_to_anyof_if_safe(item) : item 
+              }
+            end
+            
+            # Process anyOf arrays (in case there are nested oneOf within anyOf)
+            if result[:anyOf].is_a?(Array)
+              result[:anyOf] = result[:anyOf].map { |item| 
+                item.is_a?(Hash) ? convert_oneof_to_anyof_if_safe(item) : item 
+              }
+            end
             
             result
           end
+          
+          # Check if all schemas in a oneOf array have discriminator fields (const properties)
+          sig { params(schemas: T::Array[T.untyped]).returns(T::Boolean) }
+          def self.all_have_discriminators?(schemas)
+            schemas.all? do |schema|
+              next false unless schema.is_a?(Hash)
+              next false unless schema[:properties].is_a?(Hash)
+              
+              # Check if any property has a const value (our discriminator pattern)
+              schema[:properties].any? { |_, prop| prop.is_a?(Hash) && prop[:const] }
+            end
+          end
 
           sig { params(model: String).returns(T::Boolean) }
           def self.supports_structured_outputs?(model)
-            # Check cache first
-            cache_manager = DSPy::LM.cache_manager
-            cached_result = cache_manager.get_capability(model, "structured_outputs")
-            
-            if !cached_result.nil?
-              DSPy.logger.debug("Using cached capability check for #{model}")
-              return cached_result
-            end
-            
             # Extract base model name without provider prefix
             base_model = model.sub(/^openai\//, "")
             
             # Check if it's a supported model or a newer version
-            result = STRUCTURED_OUTPUT_MODELS.any? { |supported| base_model.start_with?(supported) }
-            
-            # Cache the result
-            cache_manager.cache_capability(model, "structured_outputs", result)
-            
-            result
+            STRUCTURED_OUTPUT_MODELS.any? { |supported| base_model.start_with?(supported) }
           end
 
           sig { params(schema: T::Hash[Symbol, T.untyped]).returns(T::Array[String]) }
@@ -226,8 +256,8 @@ module DSPy
               end
             end
             
-            # Process oneOf/anyOf/allOf
-            [:oneOf, :anyOf, :allOf].each do |key|
+            # Process anyOf/allOf (oneOf should be converted to anyOf by this point)
+            [:anyOf, :allOf].each do |key|
               if result[key].is_a?(Array)
                 result[key] = result[key].map do |sub_schema|
                   sub_schema.is_a?(Hash) ? add_additional_properties_recursively(sub_schema) : sub_schema
@@ -272,8 +302,8 @@ module DSPy
               max_depth = [max_depth, items_depth].max
             end
 
-            # Check oneOf/anyOf/allOf
-            [:oneOf, :anyOf, :allOf].each do |key|
+            # Check anyOf/allOf (oneOf should be converted to anyOf by this point)
+            [:anyOf, :allOf].each do |key|
               if schema[key].is_a?(Array)
                 schema[key].each do |sub_schema|
                   if sub_schema.is_a?(Hash)
@@ -291,8 +321,8 @@ module DSPy
           def self.contains_pattern_properties?(schema)
             return true if schema[:patternProperties]
 
-            # Recursively check nested schemas
-            [:properties, :items, :oneOf, :anyOf, :allOf].each do |key|
+            # Recursively check nested schemas (oneOf should be converted to anyOf by this point)
+            [:properties, :items, :anyOf, :allOf].each do |key|
               value = schema[key]
               case value
               when Hash
@@ -309,8 +339,8 @@ module DSPy
           def self.contains_conditional_schemas?(schema)
             return true if schema[:if] || schema[:then] || schema[:else]
 
-            # Recursively check nested schemas
-            [:properties, :items, :oneOf, :anyOf, :allOf].each do |key|
+            # Recursively check nested schemas (oneOf should be converted to anyOf by this point) 
+            [:properties, :items, :anyOf, :allOf].each do |key|
               value = schema[key]
               case value
               when Hash

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