dspy 0.27.1 → 0.27.3

data/lib/dspy/re_act.rb

@@ -66,6 +66,13 @@ module DSPy
     extend T::Sig
     include Mixins::StructBuilder
 
+    # AvailableTool struct for better type safety in ReAct agents
+    class AvailableTool < T::Struct
+      const :name, String
+      const :description, String
+      const :schema, T::Hash[Symbol, T.untyped]
+    end
+
     FINISH_ACTION = "finish"
     sig { returns(T.class_of(DSPy::Signature)) }
     attr_reader :original_signature_class
@@ -87,6 +94,9 @@ module DSPy
       tools.each { |tool| @tools[tool.name.downcase] = tool }
       @max_iterations = max_iterations
 
+      # Create dynamic ActionEnum class with tool names + finish
+      @action_enum_class = create_action_enum_class
+
       # Create dynamic signature classes that include the original input fields
       thought_signature = create_thought_signature(signature_class)
       observation_signature = create_observation_signature(signature_class)
@@ -143,9 +153,34 @@ module DSPy
 
     private
 
+    # Creates a dynamic ActionEnum class with tool names and "finish"
+    sig { returns(T.class_of(T::Enum)) }
+    def create_action_enum_class
+      tool_names = @tools.keys
+      all_actions = tool_names + [FINISH_ACTION]
+      
+      # Create a dynamic enum class using proper T::Enum pattern
+      enum_class = Class.new(T::Enum)
+      
+      # Build the enums block code dynamically
+      enum_definitions = all_actions.map do |action_name|
+        const_name = action_name.upcase.gsub(/[^A-Z0-9_]/, '_')
+        "#{const_name} = new(#{action_name.inspect})"
+      end.join("\n        ")
+      
+      enum_class.class_eval <<~RUBY
+        enums do
+          #{enum_definitions}
+        end
+      RUBY
+      
+      enum_class
+    end
+
     # Creates a dynamic Thought signature that includes the original input fields
     sig { params(signature_class: T.class_of(DSPy::Signature)).returns(T.class_of(DSPy::Signature)) }
     def create_thought_signature(signature_class)
+      action_enum_class = @action_enum_class
       # Create new class that inherits from DSPy::Signature
       Class.new(DSPy::Signature) do
         # Set description
@@ -154,21 +189,21 @@ module DSPy
         # Define input fields
         input do
           const :input_context, String,
-            desc: "Serialized representation of all input fields"
+            description: "Serialized representation of all input fields"
           const :history, T::Array[HistoryEntry],
-            desc: "Previous thoughts and actions, including observations from tools."
-          const :available_tools, T::Array[T::Hash[String, T.untyped]],
-            desc: "Array of available tools with their JSON schemas."
+            description: "Previous thoughts and actions, including observations from tools."
+          const :available_tools, T::Array[AvailableTool],
+            description: "Array of available tools with their JSON schemas."
         end
 
         # Define output fields (same as ThoughtBase)
         output do
           const :thought, String,
-            desc: "Reasoning about what to do next, considering the history and observations."
-          const :action, String,
-            desc: "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."
+            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]),
-            desc: "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."
+            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
     end
@@ -184,19 +219,19 @@ module DSPy
         # Define input fields
         input do
           const :input_context, String,
-            desc: "Serialized representation of all input fields"
+            description: "Serialized representation of all input fields"
           const :history, T::Array[HistoryEntry],
-            desc: "Previous thoughts, actions, and observations."
+            description: "Previous thoughts, actions, and observations."
           const :observation, String,
-            desc: "The result from the last action"
+            description: "The result from the last action"
         end
 
         # Define output fields (same as ReActObservationBase)
         output do
           const :interpretation, String,
-            desc: "Interpretation of the observation"
+            description: "Interpretation of the observation"
           const :next_step, NextStep,
-            desc: "What to do next: '#{NextStep::Continue}' or '#{NextStep::Finish}'"
+            description: "What to do next: '#{NextStep::Continue}' or '#{NextStep::Finish}'"
         end
       end
     end
@@ -205,7 +240,14 @@ 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| JSON.parse(tool.schema) }
+      available_tools_desc = @tools.map { |name, tool| 
+        schema = JSON.parse(tool.schema)
+        AvailableTool.new(
+          name: name,
+          description: tool.description,
+          schema: schema.transform_keys(&:to_sym)
+        )
+      }
       final_answer = T.let(nil, T.nilable(String))
       iterations_count = 0
       last_observation = T.let(nil, T.nilable(String))
@@ -239,11 +281,12 @@ module DSPy
     end
 
     # 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]) }
+    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]) }
     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,
@@ -271,12 +314,15 @@ module DSPy
           thought_obj.action, thought_obj.action_input, iteration
         )
 
+        # Convert action enum to string for processing and storage
+        action_str = thought_obj.action.respond_to?(:serialize) ? thought_obj.action.serialize : thought_obj.action.to_s
+        
         # Track tools used
-        tools_used << thought_obj.action.downcase if valid_tool?(thought_obj.action)
+        tools_used << action_str.downcase if valid_tool?(thought_obj.action)
 
         # Add to history
         history << create_history_entry(
-          iteration, thought_obj.thought, thought_obj.action,
+          iteration, thought_obj.thought, action_str,
           thought_obj.action_input, observation
         )
 
@@ -290,7 +336,7 @@ module DSPy
         end
 
         emit_iteration_complete_event(
-          iteration, thought_obj.thought, thought_obj.action,
+          iteration, thought_obj.thought, action_str,
           thought_obj.action_input, observation, tools_used
         )
 
@@ -340,30 +386,39 @@ module DSPy
       final_answer.nil? && (@max_iterations.nil? || iterations_count < @max_iterations)
     end
 
-    sig { params(action: T.nilable(String)).returns(T::Boolean) }
+    sig { params(action: T.nilable(T.any(String, T::Enum))).returns(T::Boolean) }
     def finish_action?(action)
-      action&.downcase == FINISH_ACTION
+      return false unless action
+      action_str = action.respond_to?(:serialize) ? action.serialize : action.to_s
+      action_str.downcase == FINISH_ACTION
     end
 
-    sig { params(action: T.nilable(String)).returns(T::Boolean) }
+    sig { params(action: T.nilable(T.any(String, T::Enum))).returns(T::Boolean) }
     def valid_tool?(action)
-      !!(action && @tools[action.downcase])
+      return false unless action
+      action_str = action.respond_to?(:serialize) ? action.serialize : action.to_s
+      !!@tools[action_str.downcase]
     end
 
-    sig { params(action: T.nilable(String), 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(String) }
     def execute_tool_with_instrumentation(action, action_input, iteration)
-      if action && @tools[action.downcase]
+      return "Unknown action: #{action}. Available actions: #{@tools.keys.join(', ')}, finish" 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.downcase,
+          'tool.name' => action_str.downcase,
           'tool.input' => action_input
         ) do
-          execute_action(action, action_input)
+          execute_action(action_str, action_input)
         end
       else
-        "Unknown action: #{action}. Available actions: #{@tools.keys.join(', ')}, finish"
+        "Unknown action: #{action_str}. Available actions: #{@tools.keys.join(', ')}, finish"
       end
     end
 
@@ -378,7 +433,7 @@ module DSPy
       )
     end
 
-    sig { params(input_struct: T.untyped, history: T::Array[HistoryEntry], observation: String, available_tools_desc: T::Array[T::Hash[String, T.untyped]], iteration: Integer).returns(T::Hash[Symbol, T.untyped]) }
+    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]) }
     def process_observation_and_decide_next_step(input_struct, history, observation, available_tools_desc, iteration)
       return { should_finish: false } if observation.include?("Unknown action")
 
@@ -397,7 +452,7 @@ 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[T::Hash[String, T.untyped]], 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(String) }
     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,
@@ -405,7 +460,8 @@ module DSPy
         available_tools: available_tools_desc
       )
 
-      if final_thought.action&.downcase != FINISH_ACTION
+      action_str = final_thought.action.respond_to?(:serialize) ? final_thought.action.serialize : final_thought.action.to_s
+      if action_str.downcase != FINISH_ACTION
         forced_answer = if observation_result.interpretation && !observation_result.interpretation.empty?
                           observation_result.interpretation
                         else
@@ -419,7 +475,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 +488,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,
@@ -514,7 +570,7 @@ module DSPy
       example
     end
 
-    sig { params(action_input: T.untyped, last_observation: T.nilable(String), step: Integer, thought: String, action: String, history: T::Array[HistoryEntry]).returns(String) }
+    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) }
     def handle_finish_action(action_input, last_observation, step, thought, action, history)
       final_answer = action_input.to_s
 
@@ -523,11 +579,14 @@ module DSPy
         final_answer = last_observation
       end
 
+      # Convert action enum to string for storage in history
+      action_str = action.respond_to?(:serialize) ? action.serialize : action.to_s
+
       # Always add the finish action to history
       history << HistoryEntry.new(
         step: step,
         thought: thought,
-        action: action,
+        action: action_str,
         action_input: final_answer,
         observation: nil  # No observation for finish action
       )

data/lib/dspy/signature.rb

@@ -207,6 +207,12 @@ module DSPy
             { type: "number" }
           elsif type == Numeric
             { type: "number" }
+          elsif type == Date
+            { type: "string", format: "date" }
+          elsif type == DateTime
+            { type: "string", format: "date-time" }
+          elsif type == Time
+            { type: "string", format: "date-time" }
           elsif [TrueClass, FalseClass].include?(type)
             { type: "boolean" }
           elsif type < T::Struct
@@ -225,6 +231,12 @@ module DSPy
             { type: "number" }
           when "Numeric"
             { type: "number" }
+          when "Date"
+            { type: "string", format: "date" }
+          when "DateTime"
+            { type: "string", format: "date-time" }
+          when "Time"
+            { type: "string", format: "date-time" }
           when "TrueClass", "FalseClass"
             { type: "boolean" }
           when "T::Boolean"

data/lib/dspy/tools/base.rb

@@ -2,6 +2,8 @@
 
 require 'sorbet-runtime'
 require 'json'
+require_relative '../type_system/sorbet_json_schema'
+require_relative '../mixins/type_coercion'
 
 module DSPy
   module Tools
@@ -9,6 +11,7 @@ module DSPy
     class Base
       extend T::Sig
       extend T::Helpers
+      include DSPy::Mixins::TypeCoercion
 
       class << self
         extend T::Sig
@@ -30,14 +33,14 @@ module DSPy
 
         # Get the JSON schema for the call method based on its Sorbet signature
         sig { returns(T::Hash[Symbol, T.untyped]) }
-        def call_schema
+        def call_schema_object
           method_obj = instance_method(:call)
           sig_info = T::Utils.signature_for_method(method_obj)
 
           if sig_info.nil?
             # Fallback for methods without signatures
             return {
-              type: :object,
+              type: "object",
               properties: {},
               required: []
             }
@@ -50,10 +53,8 @@ module DSPy
           sig_info.arg_types.each do |param_name, param_type|
             next if param_name == :block # Skip block parameters
 
-            properties[param_name] = {
-              type: sorbet_type_to_json_schema(param_type)[:type],
-              description: "Parameter #{param_name}"
-            }
+            schema = DSPy::TypeSystem::SorbetJsonSchema.type_to_json_schema(param_type)
+            properties[param_name] = schema.merge({ description: "Parameter #{param_name}" })
 
             # Check if parameter is required (not nilable)
             unless param_type.class.name.include?('Union') && param_type.name.include?('NilClass')
@@ -65,10 +66,8 @@ module DSPy
           sig_info.kwarg_types.each do |param_name, param_type|
             next if param_name == :block # Skip block parameters
 
-            properties[param_name] = {
-              type: sorbet_type_to_json_schema(param_type)[:type],
-              description: "Parameter #{param_name}"
-            }
+            schema = DSPy::TypeSystem::SorbetJsonSchema.type_to_json_schema(param_type)
+            properties[param_name] = schema.merge({ description: "Parameter #{param_name}" })
 
             # Check if parameter is required by looking at required kwarg names
             if sig_info.req_kwarg_names.include?(param_name)
@@ -79,54 +78,25 @@ module DSPy
           end
 
           {
-            type: :object,
+            type: "object",
             properties: properties,
             required: required
           }
         end
 
-        private
-
-        # Convert Sorbet types to JSON Schema types
-        sig { params(sorbet_type: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
-        def sorbet_type_to_json_schema(sorbet_type)
-          if sorbet_type.is_a?(T::Types::Simple)
-            raw_type = sorbet_type.raw_type
-
-            if raw_type == String
-              { type: :string }
-            elsif raw_type == Integer
-              { type: :integer }
-            elsif raw_type == Float
-              { type: :number }
-            elsif raw_type == Numeric
-              { type: :number }
-            elsif raw_type == TrueClass || raw_type == FalseClass
-              { type: :boolean }
-            elsif raw_type == T::Boolean
-              { type: :boolean }
-            else
-              { type: :string, description: "#{raw_type} (converted to string)" }
-            end
-          elsif sorbet_type.is_a?(T::Types::Union)
-            # Handle nilable types
-            non_nil_types = sorbet_type.types.reject { |t| t == T::Utils.coerce(NilClass) }
-            if non_nil_types.length == 1
-              result = sorbet_type_to_json_schema(non_nil_types.first)
-              result[:description] = "#{result[:description] || ''} (optional)".strip
-              result
-            else
-              { type: :string, description: "Union type (converted to string)" }
-            end
-          elsif sorbet_type.is_a?(T::Types::TypedArray)
-            {
-              type: :array,
-              items: sorbet_type_to_json_schema(sorbet_type.type)
+        # Get the full tool schema for LLM tools format
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def call_schema
+          {
+            type: 'function',
+            function: {
+              name: 'call',
+              description: "Call the #{self.name} tool",
+              parameters: call_schema_object
             }
-          else
-            { type: :string, description: "#{sorbet_type} (converted to string)" }
-          end
+          }
         end
+
       end
 
       # Instance methods that tools can use
@@ -143,7 +113,7 @@ module DSPy
       # Get the JSON schema string for the tool, formatted for LLM consumption
       sig { returns(String) }
       def schema
-        schema_obj = self.class.call_schema
+        schema_obj = self.class.call_schema_object
         tool_info = {
           name: name,
           description: description,
@@ -152,11 +122,17 @@ module DSPy
         JSON.generate(tool_info)
       end
 
+      # Get the full call schema compatible with LLM tools format
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def call_schema
+        self.class.call_schema
+      end
+
       # Dynamic call method for ReAct agent - parses JSON arguments and calls the typed method
       sig { params(args_json: T.untyped).returns(T.untyped) }
       def dynamic_call(args_json)
         # Parse arguments based on the call schema
-        schema = self.class.call_schema
+        schema = self.class.call_schema_object
 
         if schema[:properties].empty?
           # No parameters - call without arguments
@@ -178,12 +154,34 @@ module DSPy
 
           # Convert string keys to symbols and validate types
           kwargs = {}
-          schema[:properties].each do |param_name, param_schema|
-            key = param_name.to_s
-            if args.key?(key)
-              kwargs[param_name] = convert_argument_type(args[key], param_schema)
-            elsif schema[:required].include?(key)
-              return "Error: Missing required parameter: #{key}"
+          
+          # Get method signature for type information
+          method_obj = self.class.instance_method(:call)
+          sig_info = T::Utils.signature_for_method(method_obj)
+          
+          if sig_info
+            # Handle kwargs using type signature information
+            sig_info.kwarg_types.each do |param_name, param_type|
+              next if param_name == :block
+              
+              key = param_name.to_s
+              if args.key?(key)
+                kwargs[param_name] = coerce_value_to_type(args[key], param_type)
+              elsif schema[:required].include?(key)
+                return "Error: Missing required parameter: #{key}"
+              end
+            end
+            
+            # Handle positional args if any
+            sig_info.arg_types.each do |param_name, param_type|
+              next if param_name == :block
+              
+              key = param_name.to_s
+              if args.key?(key)
+                kwargs[param_name] = coerce_value_to_type(args[key], param_type)
+              elsif schema[:required].include?(key)
+                return "Error: Missing required parameter: #{key}"
+              end
             end
           end
 
@@ -195,32 +193,6 @@ module DSPy
 
       # Subclasses must implement their own call method with their own signature
 
-      protected
-
-      # Convert argument to the expected type based on JSON schema
-      sig { params(value: T.untyped, schema: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
-      def convert_argument_type(value, schema)
-        case schema[:type]
-        when :integer
-          value.is_a?(Integer) ? value : value.to_i
-        when :number
-          # Always convert to Float for :number types to ensure compatibility with strict Float signatures
-          value.to_f
-        when :boolean
-          case value
-          when true, false
-            value
-          when "true", "1", 1
-            true
-          when "false", "0", 0
-            false
-          else
-            !!value
-          end
-        else
-          value.to_s
-        end
-      end
     end
   end
 end