dspy 0.27.5 → 0.28.0

data/lib/dspy/re_act.rb

@@ -15,7 +15,7 @@ module DSPy
     prop :thought, T.nilable(String)
     prop :action, T.nilable(String)
     prop :action_input, T.nilable(T.any(String, Numeric, T::Hash[T.untyped, T.untyped], T::Array[T.untyped]))
-    prop :observation, T.nilable(String)
+    prop :observation, T.untyped
 
     # Custom serialization to ensure compatibility with the rest of the code
     def to_h
@@ -37,7 +37,7 @@ module DSPy
         description: "Reasoning about what to do next, considering the history and observations."
       const :action, String,
         description: "The action to take. MUST be one of the tool names listed in `available_tools` input, or the literal string \"finish\" to provide the final answer."
-      const :action_input, T.any(String, T::Hash[T.untyped, T.untyped]),
+      const :action_input, T.untyped,
         description: "Input for the chosen action. If action is a tool name, this MUST be a JSON object matching the tool's schema. If action is \"finish\", this field MUST contain the final result based on processing the input data. This result MUST be directly taken from the relevant Observation in the history if available."
     end
   end
@@ -66,6 +66,11 @@ module DSPy
     extend T::Sig
     include Mixins::StructBuilder
 
+    # Custom error classes
+    class MaxIterationsError < StandardError; end
+    class InvalidActionError < StandardError; end
+    class TypeMismatchError < StandardError; end
+
     # AvailableTool struct for better type safety in ReAct agents
     class AvailableTool < T::Struct
       const :name, String
@@ -153,6 +158,30 @@ module DSPy
 
     private
 
+    # Serialize value for LLM display
+    sig { params(value: T.untyped).returns(T.untyped) }
+    def serialize_for_llm(value)
+      return value if value.nil?
+      return value if value.is_a?(String) || value.is_a?(Numeric) || value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      # For structured data, serialize to JSON-compatible format
+      TypeSerializer.serialize(value)
+    end
+
+    # Serialize history for LLM consumption
+    sig { params(history: T::Array[HistoryEntry]).returns(T::Array[T::Hash[Symbol, T.untyped]]) }
+    def serialize_history_for_llm(history)
+      history.map do |entry|
+        {
+          step: entry.step,
+          thought: entry.thought,
+          action: entry.action,
+          action_input: serialize_for_llm(entry.action_input),
+          observation: serialize_for_llm(entry.observation)
+        }.compact
+      end
+    end
+
     # Creates a dynamic ActionEnum class with tool names and "finish"
     sig { returns(T.class_of(T::Enum)) }
     def create_action_enum_class
@@ -202,7 +231,7 @@ module DSPy
             description: "Reasoning about what to do next, considering the history and observations."
           const :action, action_enum_class,
             description: "The action to take. MUST be one of the tool names listed in `available_tools` input, or the literal string \"finish\" to provide the final answer."
-          const :action_input, T.any(String, T::Hash[T.untyped, T.untyped]),
+          const :action_input, T.untyped,
             description: "Input for the chosen action. If action is a tool name, this MUST be a JSON object matching the tool's schema. If action is \"finish\", this field MUST contain the final result based on processing the input data."
         end
       end
@@ -222,7 +251,7 @@ module DSPy
             description: "Serialized representation of all input fields"
           const :history, T::Array[HistoryEntry],
             description: "Previous thoughts, actions, and observations."
-          const :observation, String,
+          const :observation, T.untyped,
             description: "The result from the last action"
         end
 
@@ -240,7 +269,7 @@ module DSPy
     sig { params(input_struct: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
     def execute_react_reasoning_loop(input_struct)
       history = T.let([], T::Array[HistoryEntry])
-      available_tools_desc = @tools.map { |name, tool| 
+      available_tools_desc = @tools.map { |name, tool|
         schema = JSON.parse(tool.schema)
         AvailableTool.new(
           name: name,
@@ -248,9 +277,9 @@ module DSPy
           schema: schema.transform_keys(&:to_sym)
         )
       }
-      final_answer = T.let(nil, T.nilable(String))
+      final_answer = T.let(nil, T.untyped)
       iterations_count = 0
-      last_observation = T.let(nil, T.nilable(String))
+      last_observation = T.let(nil, T.untyped)
       tools_used = []
 
       while should_continue_iteration?(iterations_count, final_answer)
@@ -276,12 +305,12 @@ module DSPy
         history: history,
         iterations: iterations_count,
         tools_used: tools_used.uniq,
-        final_answer: final_answer || default_no_answer_message
+        final_answer: final_answer
       }
     end
 
     # Executes a single iteration of the ReAct loop
-    sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], available_tools_desc: T::Array[AvailableTool], iteration: Integer, tools_used: T::Array[String], last_observation: T.nilable(String)).returns(T::Hash[Symbol, T.untyped]) }
+    sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], available_tools_desc: T::Array[AvailableTool], iteration: Integer, tools_used: T::Array[String], last_observation: T.untyped).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 agent span
       DSPy::Context.with_span(
@@ -296,7 +325,7 @@ module DSPy
         # Generate thought and action
         thought_obj = @thought_generator.forward(
           input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
-          history: history,
+          history: serialize_history_for_llm(history),
           available_tools: available_tools_desc
         )
 
@@ -371,26 +400,134 @@ module DSPy
       output_field_name = @original_signature_class.output_struct_class.props.keys.first
       final_answer = reasoning_result[:final_answer]
 
+      # If final_answer is nil, max iterations was reached without completion
+      if final_answer.nil?
+        iterations = reasoning_result[:iterations]
+        tools_used = reasoning_result[:tools_used]
+        raise MaxIterationsError, "Agent reached maximum iterations (#{iterations}) without producing a final answer. Tools used: #{tools_used.join(', ')}"
+      end
+
       output_data = input_kwargs.merge({
         history: reasoning_result[:history].map(&:to_h),
         iterations: reasoning_result[:iterations],
         tools_used: reasoning_result[:tools_used]
       })
 
-      # Check if final_answer is a String but the expected type is NOT String
-      # This happens when max iterations is reached or the LLM generates an error message
+      # Get the expected output type
       output_field_type = @original_signature_class.output_struct_class.props[output_field_name][:type_object]
-      if final_answer.is_a?(String) && !string_compatible_type?(output_field_type)
-        output_data[output_field_name] = default_value_for_type(output_field_type)
+
+      # Try to deserialize final_answer to match the expected output type
+      deserialized_value = deserialize_final_answer(final_answer, output_field_type, reasoning_result[:history])
+
+      output_data[output_field_name] = deserialized_value
+
+      @enhanced_output_struct.new(**output_data)
+    end
+
+    # Find the most recent non-nil tool observation in history
+    sig { params(history: T::Array[HistoryEntry]).returns(T.untyped) }
+    def find_last_tool_observation(history)
+      history.reverse.find { |entry| !entry.observation.nil? }&.observation
+    end
+
+    # Deserialize final answer to match expected output type
+    # Routes to appropriate deserialization based on type classification
+    sig { params(final_answer: T.untyped, output_field_type: T.untyped, history: T::Array[HistoryEntry]).returns(T.untyped) }
+    def deserialize_final_answer(final_answer, output_field_type, history)
+      if scalar_type?(output_field_type)
+        deserialize_scalar(final_answer, output_field_type)
+      elsif structured_type?(output_field_type)
+        deserialize_structured(final_answer, output_field_type, history)
       else
-        output_data[output_field_name] = final_answer
+        # Fallback for unknown types
+        return final_answer if type_matches?(final_answer, output_field_type)
+        convert_to_expected_type(final_answer, output_field_type)
       end
+    end
 
-      @enhanced_output_struct.new(**output_data)
+    # Deserialize scalar types (String, Integer, Boolean, etc.)
+    # Scalars: Trust LLM synthesis, minimal conversion
+    sig { params(final_answer: T.untyped, output_field_type: T.untyped).returns(T.untyped) }
+    def deserialize_scalar(final_answer, output_field_type)
+      # If already matches, return as-is (even if empty string for String types)
+      return final_answer if type_matches?(final_answer, output_field_type)
+
+      # Try basic conversion
+      converted = convert_to_expected_type(final_answer, output_field_type)
+      return converted if type_matches?(converted, output_field_type)
+
+      # Type mismatch - raise error with helpful message
+      expected_type = type_name(output_field_type)
+      actual_type = final_answer.class.name
+      raise TypeMismatchError, "Cannot convert final answer from #{actual_type} to #{expected_type}. Value: #{final_answer.inspect}"
+    end
+
+    # Deserialize structured types (arrays, hashes, structs)
+    # Structured: Prefer tool observation to preserve type information
+    sig { params(final_answer: T.untyped, output_field_type: T.untyped, history: T::Array[HistoryEntry]).returns(T.untyped) }
+    def deserialize_structured(final_answer, output_field_type, history)
+      # First, try to use the last tool observation if it matches the expected type
+      # This preserves type information that would be lost in LLM synthesis
+      last_tool_observation = find_last_tool_observation(history)
+      if last_tool_observation && type_matches?(last_tool_observation, output_field_type)
+        return last_tool_observation
+      end
+
+      # If final_answer already matches, use it
+      return final_answer if type_matches?(final_answer, output_field_type)
+
+      # Try to convert based on expected type
+      converted = convert_to_expected_type(final_answer, output_field_type)
+      return converted if type_matches?(converted, output_field_type)
+
+      # Type mismatch - raise error with helpful message
+      expected_type = type_name(output_field_type)
+      actual_type = final_answer.class.name
+      raise TypeMismatchError, "Cannot convert final answer from #{actual_type} to #{expected_type}. Value: #{final_answer.inspect}"
+    end
+
+    # Convert value to expected type
+    sig { params(value: T.untyped, type_object: T.untyped).returns(T.untyped) }
+    def convert_to_expected_type(value, type_object)
+      case type_object
+      when T::Types::TypedArray
+        return value unless value.is_a?(Array)
+        element_type = type_object.type
+        value.map { |item| convert_to_expected_type(item, element_type) }
+      when T::Types::Simple
+        struct_class = type_object.raw_type
+        if struct_class < T::Struct && value.is_a?(Hash)
+          # Convert string keys to symbol keys
+          symbolized = value.transform_keys(&:to_sym)
+          struct_class.new(**symbolized)
+        else
+          value
+        end
+      else
+        value
+      end
+    end
+
+    # Check if a value matches the expected type
+    sig { params(value: T.untyped, type_object: T.untyped).returns(T::Boolean) }
+    def type_matches?(value, type_object)
+      case type_object
+      when T::Types::TypedArray
+        value.is_a?(Array) && (value.empty? || value.first.is_a?(T::Struct))
+      when T::Types::TypedHash
+        value.is_a?(Hash)
+      when T::Types::Simple
+        value.is_a?(type_object.raw_type)
+      when T::Types::Union
+        # For union types, check if value matches any of the types
+        type_object.types.any? { |t| type_matches?(value, t) }
+      else
+        false
+      end
     end
 
     # Helper methods for ReAct logic
-    sig { params(iterations_count: Integer, final_answer: T.nilable(String)).returns(T::Boolean) }
+    sig { params(iterations_count: Integer, final_answer: T.untyped).returns(T::Boolean) }
     def should_continue_iteration?(iterations_count, final_answer)
       final_answer.nil? && (@max_iterations.nil? || iterations_count < @max_iterations)
     end
@@ -409,29 +546,30 @@ module DSPy
       !!@tools[action_str.downcase]
     end
 
-    sig { params(action: T.nilable(T.any(String, T::Enum)), action_input: T.untyped, iteration: Integer).returns(String) }
+    sig { params(action: T.nilable(T.any(String, T::Enum)), action_input: T.untyped, iteration: Integer).returns(T.untyped) }
     def execute_tool_with_instrumentation(action, action_input, iteration)
-      return "Unknown action: #{action}. Available actions: #{@tools.keys.join(', ')}, finish" unless action
-      
+      raise InvalidActionError, "No action provided" unless action
+
       action_str = action.respond_to?(:serialize) ? action.serialize : action.to_s
-      
-      if @tools[action_str.downcase]
-        DSPy::Context.with_span(
-          operation: 'react.tool_call',
-          **DSPy::ObservationType::Tool.langfuse_attributes,
-          'dspy.module' => 'ReAct',
-          'react.iteration' => iteration,
-          'tool.name' => action_str.downcase,
-          'tool.input' => action_input
-        ) do
-          execute_action(action_str, action_input)
-        end
-      else
-        "Unknown action: #{action_str}. Available actions: #{@tools.keys.join(', ')}, finish"
+
+      unless @tools[action_str.downcase]
+        available = @tools.keys.join(', ')
+        raise InvalidActionError, "Unknown action: #{action_str}. Available actions: #{available}, finish"
+      end
+
+      DSPy::Context.with_span(
+        operation: 'react.tool_call',
+        **DSPy::ObservationType::Tool.langfuse_attributes,
+        'dspy.module' => 'ReAct',
+        'react.iteration' => iteration,
+        'tool.name' => action_str.downcase,
+        'tool.input' => action_input
+      ) do
+        execute_action(action_str, action_input)
       end
     end
 
-    sig { params(step: Integer, thought: String, action: String, action_input: T.untyped, observation: String).returns(HistoryEntry) }
+    sig { params(step: Integer, thought: String, action: String, action_input: T.untyped, observation: T.untyped).returns(HistoryEntry) }
     def create_history_entry(step, thought, action, action_input, observation)
       HistoryEntry.new(
         step: step,
@@ -442,14 +580,12 @@ module DSPy
       )
     end
 
-    sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], observation: String, available_tools_desc: T::Array[AvailableTool], iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
+    sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], observation: T.untyped, available_tools_desc: T::Array[AvailableTool], iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
     def process_observation_and_decide_next_step(input_struct, history, observation, available_tools_desc, iteration)
-      return { should_finish: false } if observation.include?("Unknown action")
-
       observation_result = @observation_processor.forward(
         input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
-        history: history,
-        observation: observation
+        history: serialize_history_for_llm(history),
+        observation: serialize_for_llm(observation)
       )
 
       return { should_finish: false } unless observation_result.next_step == NextStep::Finish
@@ -461,20 +597,23 @@ module DSPy
       { should_finish: true, final_answer: final_answer }
     end
 
-    sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], available_tools_desc: T::Array[AvailableTool], observation_result: T.untyped, iteration: Integer).returns(String) }
+    sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], available_tools_desc: T::Array[AvailableTool], observation_result: T.untyped, iteration: Integer).returns(T.untyped) }
     def generate_forced_final_answer(input_struct, history, available_tools_desc, observation_result, iteration)
       final_thought = @thought_generator.forward(
         input_context: DSPy::TypeSerializer.serialize(input_struct).to_json,
-        history: history,
+        history: serialize_history_for_llm(history),
         available_tools: available_tools_desc
       )
 
       action_str = final_thought.action.respond_to?(:serialize) ? final_thought.action.serialize : final_thought.action.to_s
       if action_str.downcase != FINISH_ACTION
+        # Use interpretation if available, otherwise use last observation
         forced_answer = if observation_result.interpretation && !observation_result.interpretation.empty?
                           observation_result.interpretation
+                        elsif history.last&.observation
+                          history.last.observation
                         else
-                          history.last&.observation || "No answer available"
+                          raise MaxIterationsError, "Observation processor indicated finish but no answer is available"
                         end
         handle_finish_action(forced_answer, history.last&.observation, iteration + 1, final_thought.thought, FINISH_ACTION, history)
       else
@@ -482,7 +621,7 @@ module DSPy
       end
     end
 
-    sig { params(iteration: Integer, thought: String, action: String, action_input: T.untyped, observation: String, tools_used: T::Array[String]).void }
+    sig { params(iteration: Integer, thought: String, action: String, action_input: T.untyped, observation: T.untyped, tools_used: T::Array[String]).void }
     def emit_iteration_complete_event(iteration, thought, action, action_input, observation, tools_used)
       DSPy.event('react.iteration_complete', {
         'react.iteration' => iteration,
@@ -494,7 +633,7 @@ module DSPy
       })
     end
 
-    sig { params(iterations_count: Integer, final_answer: T.nilable(String), tools_used: T::Array[String], history: T::Array[HistoryEntry]).void }
+    sig { params(iterations_count: Integer, final_answer: T.untyped, 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.event('react.max_iterations', {
@@ -506,14 +645,44 @@ module DSPy
       end
     end
 
-    sig { returns(String) }
-    def default_no_answer_message
-      "No answer reached within #{@max_iterations} iterations"
+    # Checks if a type is a scalar (primitives that don't need special serialization)
+    sig { params(type_object: T.untyped).returns(T::Boolean) }
+    def scalar_type?(type_object)
+      case type_object
+      when T::Types::Simple
+        scalar_classes = [String, Integer, Float, Numeric, TrueClass, FalseClass]
+        scalar_classes.any? { |klass| type_object.raw_type == klass || type_object.raw_type <= klass }
+      when T::Types::Union
+        # Union is scalar if all its types are scalars
+        type_object.types.all? { |t| scalar_type?(t) }
+      else
+        false
+      end
+    end
+
+    # Checks if a type is structured (arrays, hashes, structs that need type preservation)
+    sig { params(type_object: T.untyped).returns(T::Boolean) }
+    def structured_type?(type_object)
+      return true if type_object.is_a?(T::Types::TypedArray)
+      return true if type_object.is_a?(T::Types::TypedHash)
+
+      if type_object.is_a?(T::Types::Simple)
+        raw_type = type_object.raw_type
+        return true if raw_type.respond_to?(:<=) && raw_type <= T::Struct
+      end
+
+      # For union types (like T.nilable(T::Array[...])), check if any non-nil type is structured
+      if type_object.is_a?(T::Types::Union)
+        non_nil_types = type_object.types.reject { |t| t.is_a?(T::Types::Simple) && t.raw_type == NilClass }
+        return non_nil_types.any? { |t| structured_type?(t) }
+      end
+
+      false
     end
 
     # Checks if a type is String or compatible with String (e.g., T.any(String, ...) or T.nilable(String))
     sig { params(type_object: T.untyped).returns(T::Boolean) }
-    def string_compatible_type?(type_object)
+    def string_type?(type_object)
       case type_object
       when T::Types::Simple
         type_object.raw_type == String
@@ -525,6 +694,28 @@ module DSPy
       end
     end
 
+    # Alias for backward compatibility
+    alias string_compatible_type? string_type?
+
+    # Get a readable type name from a Sorbet type object
+    sig { params(type_object: T.untyped).returns(String) }
+    def type_name(type_object)
+      case type_object
+      when T::Types::TypedArray
+        element_type = type_object.type
+        "T::Array[#{type_name(element_type)}]"
+      when T::Types::TypedHash
+        "T::Hash"
+      when T::Types::Simple
+        type_object.raw_type.to_s
+      when T::Types::Union
+        types_str = type_object.types.map { |t| type_name(t) }.join(', ')
+        "T.any(#{types_str})"
+      else
+        type_object.to_s
+      end
+    end
+
     # Returns an appropriate default value for a given Sorbet type
     # This is used when max iterations is reached without a successful completion
     sig { params(type_object: T.untyped).returns(T.untyped) }
@@ -562,25 +753,19 @@ module DSPy
     end
 
     # Tool execution method
-    sig { params(action: String, action_input: T.untyped).returns(String) }
+    sig { params(action: String, action_input: T.untyped).returns(T.untyped) }
     def execute_action(action, action_input)
       tool_name = action.downcase
       tool = @tools[tool_name]
-      return "Tool '#{action}' not found. Available tools: #{@tools.keys.join(', ')}" unless tool
 
-      begin
-        result = if action_input.nil? ||
-                   (action_input.is_a?(String) && action_input.strip.empty?)
-          # No input provided
-          tool.dynamic_call({})
-        else
-          # Pass the action_input directly to dynamic_call, which can handle
-          # either a Hash or a JSON string
-          tool.dynamic_call(action_input)
-        end
-        result.to_s
-      rescue => e
-        "Error executing tool '#{action}': #{e.message}"
+      # This should not happen since we check in execute_tool_with_instrumentation
+      raise InvalidActionError, "Tool '#{action}' not found" unless tool
+
+      # Execute tool - let errors propagate
+      if action_input.nil? || (action_input.is_a?(String) && action_input.strip.empty?)
+        tool.dynamic_call({})
+      else
+        tool.dynamic_call(action_input)
       end
     end
 
@@ -629,12 +814,12 @@ module DSPy
       example
     end
 
-    sig { params(action_input: T.untyped, last_observation: T.nilable(String), step: Integer, thought: String, action: T.any(String, T::Enum), history: T::Array[HistoryEntry]).returns(String) }
+    sig { params(action_input: T.untyped, last_observation: T.untyped, step: Integer, thought: String, action: T.any(String, T::Enum), history: T::Array[HistoryEntry]).returns(T.untyped) }
     def handle_finish_action(action_input, last_observation, step, thought, action, history)
-      final_answer = action_input.to_s
+      final_answer = action_input
 
-      # If final_answer is empty but we have a last observation, use it
-      if (final_answer.nil? || final_answer.empty?) && last_observation
+      # If final_answer is empty/nil but we have a last observation, use it
+      if (final_answer.nil? || (final_answer.is_a?(String) && final_answer.empty?)) && last_observation
         final_answer = last_observation
       end