dspy 0.32.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3f15cdf0298a37b8ddf1ffb484e15e01e9bb8f794154d2a993dd91beaa4d22e
-  data.tar.gz: f6d0376e92a84d0086257546111e3f456043d814f9dd051a18ce84569e30ff1e
+  metadata.gz: 52dc686ff0347f7844a3b6fc476b31737f3467d5d179974f34a98b8dbbd12073
+  data.tar.gz: 0e39c94a4766c481167268f49e42277d297b688ee9f960181785062e69f91572
 SHA512:
-  metadata.gz: 5c26922fcf7fd867b6469bdcae24f3c2937a2f2e89b0583026a478c766c4138896709d98d598814d09220a8becd7f624bc824ad3a9f569bbac60abf7ec4e49d7
-  data.tar.gz: a251452f69f157a026e0c23bc912f9ddc2252d4e977e2ebbc3f2276ffd293fe7ff4af7aaa97c7807c21e5cdd805fd50d54046016c44664fb153b87788e5a9a16
+  metadata.gz: bb4fb2ce89ed600e971a07cfabe3eb9edd344563aa77df57304dbec565121eeb9c8a53ba4cdd66f04c81cb3b1231d222a59fb4a15962680051c07de49c080dca
+  data.tar.gz: 2543dd3bc228c98a1ab82c14ce8fffbed86342fa661af674976b90b10752334a5606257401f9ff953bd82f36aa29fe816895acec9e30a5219e8c8dc2d3ea1727

data/lib/dspy/mixins/type_coercion.rb

@@ -37,7 +37,7 @@ module DSPy
         when ->(type) { hash_type?(type) }
           coerce_hash_value(value, prop_type)
         when ->(type) { type == String || simple_type_match?(type, String) }
-          value.to_s
+          coerce_to_string(value)
         when ->(type) { enum_type?(type) }
           coerce_enum_value(value, prop_type)
         when ->(type) { type == Float || simple_type_match?(type, Float) }
@@ -295,6 +295,18 @@ module DSPy
         nil
       end
 
+      # Coerces a value to String with strict type checking
+      # Only allows String (passthrough) and Symbol (to_s) - rejects other types
+      sig { params(value: T.untyped).returns(String) }
+      def coerce_to_string(value)
+        case value
+        when String then value
+        when Symbol then value.to_s
+        else
+          raise TypeError, "Cannot coerce #{value.class} to String - expected String or Symbol"
+        end
+      end
+
       # Coerces a value to an enum, handling both strings and existing enum instances
       sig { params(value: T.untyped, prop_type: T.untyped).returns(T.untyped) }
       def coerce_enum_value(value, prop_type)

data/lib/dspy/module.rb

@@ -179,6 +179,47 @@ module DSPy
       named_predictors.map { |(_, predictor)| predictor }
     end
 
+    # Override Dry::Configurable's configure to propagate LM to child predictors
+    # When you configure an agent's LM, it automatically propagates to all child predictors
+    # returned by named_predictors, recursively.
+    #
+    # @example Basic usage
+    #   agent.configure { |c| c.lm = DSPy::LM.new('openai/gpt-4o') }
+    #   # All internal predictors now use gpt-4o
+    #
+    # @example Fine-grained control (configure then override)
+    #   agent.configure { |c| c.lm = cheap_lm }
+    #   agent.configure_predictor('thought_generator') { |c| c.lm = expensive_lm }
+    #
+    # @return [self] for method chaining
+    sig { params(block: T.proc.params(config: T.untyped).void).returns(T.self_type) }
+    def configure(&block)
+      super(&block)
+      propagate_lm_to_children(config.lm) if config.lm
+      self
+    end
+
+    # Configure a specific child predictor by name
+    # Use this for fine-grained control when different predictors need different LMs
+    #
+    # @param predictor_name [String] The name of the predictor (e.g., 'thought_generator')
+    # @yield [config] Configuration block
+    # @return [self] for method chaining
+    # @raise [ArgumentError] if predictor_name is not found
+    #
+    # @example
+    #   agent.configure_predictor('thought_generator') { |c| c.lm = expensive_lm }
+    sig { params(predictor_name: String, block: T.proc.params(config: T.untyped).void).returns(T.self_type) }
+    def configure_predictor(predictor_name, &block)
+      _, predictor = named_predictors.find { |name, _| name == predictor_name }
+      unless predictor
+        available = named_predictors.map(&:first).join(', ')
+        raise ArgumentError, "Unknown predictor: #{predictor_name}. Available: #{available}"
+      end
+      predictor.configure(&block)
+      self
+    end
+
     def instrument_forward_call(call_args, call_kwargs)
       ensure_module_subscriptions!
 
@@ -255,6 +296,21 @@ module DSPy
 
     private
 
+    # Propagate LM configuration to child predictors recursively
+    # Skips children that already have an explicit LM configured
+    sig { params(lm: T.untyped).void }
+    def propagate_lm_to_children(lm)
+      named_predictors.each do |(name, predictor)|
+        next if predictor == self # Skip self-references (Predict returns [['self', self]])
+
+        # Only propagate if child doesn't have explicit LM configured
+        unless predictor.config.lm
+          # Recursive: configure calls propagate_lm_to_children on the child too
+          predictor.configure { |c| c.lm = lm }
+        end
+      end
+    end
+
     def ensure_module_subscriptions!
       return if @module_subscriptions_registered
 

data/lib/dspy/re_act.rb

@@ -9,23 +9,28 @@ require 'json'
 require_relative 'mixins/struct_builder'
 
 module DSPy
+  # Type alias for tool input parameters - provides semantic meaning in schemas
+  ToolInput = T.type_alias { T.nilable(T::Hash[String, T.untyped]) }
+
   # Define a simple struct for history entries with proper type annotations
   class HistoryEntry < T::Struct
     const :step, Integer
     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 :tool_input, ToolInput
     prop :observation, T.untyped
 
     # Custom serialization to ensure compatibility with the rest of the code
+    # Note: We don't use .compact here to ensure tool_input is always present as a key,
+    # even when nil, for consistent history entry structure
     def to_h
       {
         step: step,
         thought: thought,
         action: action,
-        action_input: action_input,
+        tool_input: tool_input,
         observation: observation
-      }.compact
+      }
     end
   end
   # Base class for ReAct thought generation - will be customized per input type
@@ -37,8 +42,10 @@ 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.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."
+      const :tool_input, ToolInput,
+        description: "Input for the chosen tool action. Required when action is a tool name. MUST be a JSON object matching the tool's parameter schema. Set to null when action is \"finish\"."
+      const :final_answer, T.nilable(String),
+        description: "The final answer to return. Required when action is \"finish\". Must match the expected output type. Set to null when action is a tool name."
     end
   end
 
@@ -72,10 +79,12 @@ module DSPy
     class TypeMismatchError < StandardError; end
 
     # AvailableTool struct for better type safety in ReAct agents
+    # Schema is stored as a pre-serialized string (JSON or BAML) to avoid
+    # T.untyped issues during schema format conversion
     class AvailableTool < T::Struct
       const :name, String
       const :description, String
-      const :schema, T::Hash[Symbol, T.untyped]
+      const :schema, String
     end
 
     FINISH_ACTION = "finish"
@@ -211,7 +220,7 @@ module DSPy
           step: entry.step,
           thought: entry.thought,
           action: entry.action,
-          action_input: serialize_for_llm(entry.action_input),
+          tool_input: serialize_for_llm(entry.tool_input),
           observation: serialize_for_llm(entry.observation)
         }.compact
       end
@@ -244,22 +253,26 @@ module DSPy
     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)
-      
+
+      # Give the anonymous class a proper name for BAML schema rendering
+      # This overrides the default behavior that returns #<Class:0x...>
+      enum_class.define_singleton_method(:name) { 'ActionEnum' }
+
       # 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
 
@@ -272,6 +285,11 @@ module DSPy
       else
         String
       end
+
+      # Get the output field type for the final_answer field
+      output_field_name = signature_class.output_struct_class.props.keys.first
+      output_field_type = signature_class.output_struct_class.props[output_field_name][:type_object]
+
       # Create new class that inherits from DSPy::Signature
       Class.new(DSPy::Signature) do
         # Set description
@@ -287,14 +305,16 @@ module DSPy
             description: "Array of available tools with their JSON schemas."
         end
 
-        # Define output fields (same as ThoughtBase)
+        # Define output fields with separate tool_input and final_answer
         output do
           const :thought, String,
             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.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."
+          const :tool_input, ToolInput,
+            description: "Input for the chosen tool action. Required when action is a tool name. MUST be a JSON object matching the tool's parameter schema. Set to null when action is \"finish\"."
+          const :final_answer, T.nilable(output_field_type),
+            description: "The final answer to return. Required when action is \"finish\". Must match the expected output type. Set to null when action is a tool name."
         end
       end
     end
@@ -337,11 +357,10 @@ module DSPy
     def execute_react_reasoning_loop(input_struct)
       history = T.let([], T::Array[HistoryEntry])
       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)
+          schema: tool.schema
         )
       }
       final_answer = T.let(nil, T.untyped)
@@ -399,7 +418,7 @@ module DSPy
         # Process thought result
         if finish_action?(thought_obj.action)
           final_answer = handle_finish_action(
-            thought_obj.action_input, last_observation, iteration,
+            thought_obj.final_answer, last_observation, iteration,
             thought_obj.thought, thought_obj.action, history
           )
           return { should_finish: true, final_answer: final_answer }
@@ -407,19 +426,19 @@ module DSPy
 
         # Execute tool action
         observation = execute_tool_with_instrumentation(
-          thought_obj.action, thought_obj.action_input, iteration
+          thought_obj.action, thought_obj.tool_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 << action_str.downcase if valid_tool?(thought_obj.action)
 
         # Add to history
         history << create_history_entry(
           iteration, thought_obj.thought, action_str,
-          thought_obj.action_input, observation
+          thought_obj.tool_input, observation
         )
 
         # Process observation and decide next step
@@ -433,7 +452,7 @@ module DSPy
 
         emit_iteration_complete_event(
           iteration, thought_obj.thought, action_str,
-          thought_obj.action_input, observation, tools_used
+          thought_obj.tool_input, observation, tools_used
         )
 
         {
@@ -613,8 +632,8 @@ module DSPy
       !!@tools[action_str.downcase]
     end
 
-    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)
+    sig { params(action: T.nilable(T.any(String, T::Enum)), tool_input: ToolInput, iteration: Integer).returns(T.untyped) }
+    def execute_tool_with_instrumentation(action, tool_input, iteration)
       raise InvalidActionError, "No action provided" unless action
 
       action_str = action.respond_to?(:serialize) ? action.serialize : action.to_s
@@ -630,19 +649,19 @@ module DSPy
         'dspy.module' => 'ReAct',
         'react.iteration' => iteration,
         'tool.name' => action_str.downcase,
-        'tool.input' => action_input
+        'tool.input' => tool_input
       ) do
-        execute_action(action_str, action_input)
+        execute_action(action_str, tool_input)
       end
     end
 
-    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)
+    sig { params(step: Integer, thought: String, action: String, tool_input: ToolInput, observation: T.untyped).returns(HistoryEntry) }
+    def create_history_entry(step, thought, action, tool_input, observation)
       HistoryEntry.new(
         step: step,
         thought: thought,
         action: action,
-        action_input: action_input,
+        tool_input: tool_input,
         observation: observation
       )
     end
@@ -684,17 +703,17 @@ module DSPy
                         end
         handle_finish_action(forced_answer, history.last&.observation, iteration + 1, final_thought.thought, FINISH_ACTION, history)
       else
-        handle_finish_action(final_thought.action_input, history.last&.observation, iteration + 1, final_thought.thought, final_thought.action, history)
+        handle_finish_action(final_thought.final_answer, history.last&.observation, iteration + 1, final_thought.thought, final_thought.action, history)
       end
     end
 
-    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)
+    sig { params(iteration: Integer, thought: String, action: String, tool_input: ToolInput, observation: T.untyped, tools_used: T::Array[String]).void }
+    def emit_iteration_complete_event(iteration, thought, action, tool_input, observation, tools_used)
       DSPy.event('react.iteration_complete', {
         'react.iteration' => iteration,
         'react.thought' => thought,
         'react.action' => action,
-        'react.action_input' => action_input,
+        'react.tool_input' => tool_input,
         'react.observation' => observation,
         'react.tools_used' => tools_used.uniq
       })
@@ -820,8 +839,8 @@ module DSPy
     end
 
     # Tool execution method
-    sig { params(action: String, action_input: T.untyped).returns(T.untyped) }
-    def execute_action(action, action_input)
+    sig { params(action: String, tool_input: ToolInput).returns(T.untyped) }
+    def execute_action(action, tool_input)
       tool_name = action.downcase
       tool = @tools[tool_name]
 
@@ -829,10 +848,10 @@ module DSPy
       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?)
+      if tool_input.nil? || tool_input.empty?
         tool.dynamic_call({})
       else
-        tool.dynamic_call(action_input)
+        tool.dynamic_call(tool_input)
       end
     end
 
@@ -872,7 +891,7 @@ module DSPy
           step: 1,
           thought: "I need to think about this question...",
           action: "some_tool",
-          action_input: "input for tool",
+          tool_input: { "param" => "value" },
           observation: "result from tool"
         }
       ]
@@ -881,9 +900,9 @@ module DSPy
       example
     end
 
-    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
+    sig { params(final_answer_value: 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(final_answer_value, last_observation, step, thought, action, history)
+      final_answer = final_answer_value
 
       # 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
@@ -893,12 +912,12 @@ module DSPy
       # 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
+      # Always add the finish action to history (tool_input is nil for finish actions)
       history << HistoryEntry.new(
         step: step,
         thought: thought,
         action: action_str,
-        action_input: final_answer,
+        tool_input: nil,
         observation: nil  # No observation for finish action
       )
 

data/lib/dspy/schema/sorbet_json_schema.rb

@@ -113,16 +113,17 @@ module DSPy
         elsif type.is_a?(T::Types::TypedHash)
           # Handle hashes as objects with additionalProperties
           # TypedHash has keys and values methods to access its key and value types
-          key_schema = self.type_to_json_schema(type.keys, visited)
+          # Note: propertyNames is NOT supported by OpenAI structured outputs, so we omit it
           value_schema = self.type_to_json_schema(type.values, visited)
-          
-          # Create a more descriptive schema for nested structures
+          key_type_desc = type.keys.respond_to?(:raw_type) ? type.keys.raw_type.to_s : "string"
+          value_type_desc = value_schema[:description] || value_schema[:type].to_s
+
+          # Create a schema compatible with OpenAI structured outputs
           {
             type: "object",
-            propertyNames: key_schema,  # Describe key constraints
             additionalProperties: value_schema,
-            # Add a more explicit description of the expected structure
-            description: "A mapping where keys are #{key_schema[:type]}s and values are #{value_schema[:description] || value_schema[:type]}s"
+            # Description explains the expected structure without using propertyNames
+            description: "A mapping where keys are #{key_type_desc}s and values are #{value_type_desc}s"
           }
         elsif type.is_a?(T::Types::FixedHash)
           # Handle fixed hashes (from type aliases like { "key" => Type })

data/lib/dspy/tools/schema.rb

@@ -0,0 +1,39 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module DSPy
+  module Tools
+    # Represents a single parameter in a tool's schema
+    # Maps to JSON Schema property definitions used by LLM tool calling
+    class ToolParameterSchema < T::Struct
+      const :type, String
+      const :description, T.nilable(String), default: nil
+      const :enum, T.nilable(T::Array[String]), default: nil
+    end
+
+    # Represents the complete schema for a tool's parameters
+    # This is the "parameters" field in LLM tool definitions
+    class ToolSchema < T::Struct
+      const :type, String, default: 'object'
+      const :properties, T::Hash[Symbol, ToolParameterSchema], default: {}
+      const :required, T::Array[String], default: []
+
+      # Convert to hash format for JSON serialization
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        {
+          type: type,
+          properties: properties.transform_values do |param|
+            h = { type: param.type }
+            h[:description] = param.description if param.description
+            h[:enum] = param.enum if param.enum
+            h
+          end,
+          required: required
+        }
+      end
+    end
+  end
+end

data/lib/dspy/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dspy
 version: !ruby/object:Gem::Version
-  version: 0.32.0
+  version: 0.33.0
 platform: ruby
 authors:
 - Vicente Reig Rincón de Arellano
@@ -99,14 +99,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: sorbet-toon
   requirement: !ruby/object:Gem::Requirement
@@ -234,6 +234,7 @@ files:
 - lib/dspy/tools/base.rb
 - lib/dspy/tools/github_cli_toolset.rb
 - lib/dspy/tools/memory_toolset.rb
+- lib/dspy/tools/schema.rb
 - lib/dspy/tools/text_processing_toolset.rb
 - lib/dspy/tools/toolset.rb
 - lib/dspy/type_serializer.rb