ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/tool.rb

@@ -1,175 +1,350 @@
 # frozen_string_literal: true
 
-require 'ruby_llm/schema'
+require 'schematist'
 
 module RubyLLM
-  # Parameter definition for Tool methods.
-  class Parameter
+  class Parameter # :nodoc:
     attr_reader :name, :type, :description, :required
 
-    def initialize(name, type: 'string', desc: nil, description: nil, required: true)
+    def initialize(name, type: 'string', description: nil, required: true)
       @name = name
       @type = type
-      @description = desc || description
+      @description = description
       @required = required
     end
   end
 
-  # Base class for creating tools that AI models can use
+  # A Tool is an action an AI model can call during a chat. Subclasses
+  # describe themselves with ::description, declare their arguments, and
+  # implement #execute:
+  #
+  #   class Weather < RubyLLM::Tool
+  #     description "Gets current weather for a location"
+  #
+  #     def execute(latitude:, longitude:)
+  #       response = Faraday.get "https://api.open-meteo.com/v1/forecast",
+  #                              latitude: latitude, longitude: longitude,
+  #                              current: "temperature_2m,wind_speed_10m"
+  #       JSON.parse(response.body)
+  #     end
+  #   end
+  #
+  #   chat.with_tools(Weather).ask "What's the weather in Berlin?"
+  #
+  # When no parameters are declared, the argument schema is inferred from
+  # #execute's keyword arguments: required keywords become required string
+  # parameters and optional keywords become optional ones. Use ::parameter
+  # or ::parameters when arguments need explicit types, descriptions, or
+  # structure.
   class Tool
-    # Stops conversation continuation after tool execution
-    class Halt
-      attr_reader :content
+    KEYWORD_PARAMETER_KINDS = %i[keyreq key].freeze # :nodoc:
+    TOOL_CALL_KEYWORD = :tool_call # :nodoc:
+
+    DUPED_INHERITED_CONFIG = {
+      :@declared_parameters => {},
+      :@provider_options => {}
+    }.freeze
+    COPIED_INHERITED_CONFIG = %i[
+      @description
+      @parameters_schema_definition
+      @requires_approval
+      @approval_resolver
+    ].freeze
+    private_constant :DUPED_INHERITED_CONFIG, :COPIED_INHERITED_CONFIG
 
-      def initialize(content)
-        @content = content
-      end
+    class << self
+      attr_reader :parameters_schema_definition, :approval_resolver # :nodoc:
 
-      def to_s
-        @content.to_s
-      end
-    end
+      def inherited(subclass) # :nodoc:
+        super
+        DUPED_INHERITED_CONFIG.each do |ivar, default|
+          value = instance_variable_defined?(ivar) ? instance_variable_get(ivar) : default
+          subclass.instance_variable_set(ivar, value.dup)
+        end
 
-    POSITIONAL_PARAMETER_KINDS = %i[req opt rest].freeze
+        COPIED_INHERITED_CONFIG.each do |ivar|
+          subclass.instance_variable_set(ivar, instance_variable_get(ivar))
+        end
+      end
 
-    class << self
-      attr_reader :params_schema_definition
+      # Returns the name the model calls this tool by, derived from the class
+      # name: underscored, reduced to ASCII, with a trailing "_tool" removed.
+      # Override this method to choose a different name.
+      #
+      #   WeatherLookup.tool_name  # => "weather_lookup"
+      #
+      def tool_name
+        normalized = name.to_s.dup.force_encoding('UTF-8').unicode_normalize(:nfkd)
+        ascii_name = normalized.encode('ASCII', replace: '').gsub(/[^a-zA-Z0-9_-]/, '-')
+        Support::Utils.underscore(ascii_name).delete_suffix('_tool')
+      end
 
+      # :call-seq:
+      #   description(text) -> text
+      #   description -> string or nil
+      #
+      # Sets the description the model sees for this tool, or returns the
+      # current description when called without an argument.
+      #
+      #   class Weather < RubyLLM::Tool
+      #     description "Gets current weather for a location"
+      #   end
+      #
       def description(text = nil)
         return @description unless text
 
         @description = text
       end
-      alias desc description
 
-      def param(name, **options)
-        parameters[name] = Parameter.new(name, **options)
+      # Declares a parameter for the tool. +options+ accepts +type:+
+      # (defaults to <tt>'string'</tt>), +description:+, and +required:+
+      # (defaults to +true+).
+      #
+      #   class Distance < RubyLLM::Tool
+      #     description "Calculates distance between two cities"
+      #     parameter :origin, description: "Origin city name"
+      #     parameter :destination, description: "Destination city name"
+      #     parameter :units, type: :string, description: "metric or imperial", required: false
+      #   end
+      #
+      def parameter(name, **options)
+        declared_parameters[name] = Parameter.new(name, **options)
       end
 
-      def parameters
-        @parameters ||= {}
+      def declared_parameters # :nodoc:
+        @declared_parameters ||= {}
       end
 
-      def params(schema = nil, &block)
-        @params_schema_definition = SchemaDefinition.new(schema:, block:)
+      # Sets the JSON Schema for the tool's arguments. Accepts a schema hash,
+      # a Schematist::Schema class or instance, or a block written in the
+      # schematist DSL. Returns +self+.
+      #
+      #   class Scheduler < RubyLLM::Tool
+      #     description "Books a meeting"
+      #
+      #     parameters do
+      #       object :window, description: "Time window to reserve" do
+      #         string :start, description: "ISO8601 start time"
+      #         string :finish, description: "ISO8601 end time"
+      #       end
+      #       array :participants, of: :string
+      #     end
+      #   end
+      #
+      # Raises ArgumentError when called without a schema or a block.
+      def parameters(schema = nil, &block)
+        if schema.nil? && block.nil?
+          raise ArgumentError, 'parameters requires a schema or a block; declare single arguments with parameter'
+        end
+
+        @parameters_schema_definition = SchemaDefinition.new(schema:, block:)
         self
       end
 
-      def with_params(**params)
-        @provider_params = params
+      # Declares that this tool must be approved before it executes. The
+      # conversation loop pauses the tool call until a decision is recorded with
+      # Chat#approve or Chat#deny, so Chat#complete returns cleanly and
+      # can be called again once the decision exists. In Rails the decision
+      # persists on the tool call record and survives process restarts.
+      #
+      #   class IssueRefund < RubyLLM::Tool
+      #     requires_approval
+      #
+      #     def execute(order_id:)
+      #       Refunds.issue!(order_id)
+      #     end
+      #   end
+      #
+      # Pass a block to resolve the decision yourself instead of using the
+      # recorded one. The block receives the ToolCall and returns +true+ to
+      # execute, +false+ to deny, or +nil+ while the decision is pending.
+      #
+      # The block never runs at class definition. The loop consults it
+      # whenever it needs the decision, which can be several times while
+      # the call is pending, including after a crashed job resumes, so
+      # write it as an idempotent read. If it also creates the approval
+      # request, make that a find-or-create.
+      #
+      #   requires_approval { |tool_call| Approvals.status(tool_call.id) }
+      #
+      def requires_approval(&resolver)
+        @requires_approval = true
+        @approval_resolver = resolver
+      end
+
+      def requires_approval? # :nodoc:
+        @requires_approval || false
+      end
+
+      # :call-seq:
+      #   provider_options(options) -> self
+      #   provider_options -> hash
+      #
+      # Sets provider-specific metadata, such as Anthropic's +cache_control+
+      # hints, merged verbatim into the tool payload sent to the provider.
+      # Without an argument, returns the current options.
+      #
+      #   provider_options cache_control: { type: "ephemeral" }
+      #
+      # Raises ArgumentError if +options+ is +nil+.
+      def provider_options(options = (get = true))
+        return @provider_options ||= {} if get
+        raise ArgumentError, 'provider_options does not accept nil' if options.nil?
+
+        @provider_options = options.to_h
         self
       end
 
-      def provider_params
-        @provider_params ||= {}
+      def split_result(result) # :nodoc:
+        case result
+        when Attachment then ['', [result]]
+        when Array then split_array_result(result)
+        else [result_content(result), []]
+        end
+      end
+
+      private
+
+      def split_array_result(result)
+        parts = result.flatten.compact
+        return [result_content(result), []] if parts.none?(Attachment)
+
+        texts, attachments = parts.partition { |part| part.is_a?(String) }
+        unless attachments.all?(Attachment)
+          raise ArgumentError, 'Tool results mixing attachments can only contain Strings and RubyLLM::Attachments'
+        end
+
+        [texts.join("\n\n"), attachments]
+      end
+
+      def result_content(result)
+        case result
+        when String then result
+        when Hash, Array, SearchResults then result.to_json
+        else result.to_s
+        end
       end
     end
 
+    # Returns the name the model calls this tool by, delegating to
+    # ::tool_name. Override either one to choose a different name.
+    #
+    #   WeatherLookup.new.name  # => "weather_lookup"
+    #
     def name
-      klass_name = self.class.name
-      normalized = klass_name.to_s.dup.force_encoding('UTF-8').unicode_normalize(:nfkd)
-      normalized.encode('ASCII', replace: '')
-                .gsub(/[^a-zA-Z0-9_-]/, '-')
-                .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-                .downcase
-                .delete_suffix('_tool')
+      self.class.tool_name
     end
 
+    # Returns the tool description declared on the class with ::description.
     def description
       self.class.description
     end
 
-    def parameters
-      self.class.parameters
+    # Returns whether this tool was declared with ::requires_approval.
+    def requires_approval?
+      self.class.requires_approval?
     end
 
-    def provider_params
-      self.class.provider_params
+    def approval_resolver # :nodoc:
+      self.class.approval_resolver
     end
 
-    def params_schema
-      return @params_schema if defined?(@params_schema)
+    def declared_parameters # :nodoc:
+      self.class.declared_parameters
+    end
 
-      @params_schema = begin
-        definition = self.class.params_schema_definition
+    # Returns the provider-specific tool metadata declared on the class.
+    def provider_options
+      self.class.provider_options
+    end
+
+    # Returns the JSON Schema for the tool's arguments, whether declared
+    # explicitly or inferred from the +execute+ signature.
+    def parameters_schema
+      return @parameters_schema if defined?(@parameters_schema)
+
+      @parameters_schema = begin
+        definition = self.class.parameters_schema_definition
         if definition&.present?
           definition.json_schema
-        elsif parameters.any?
-          SchemaDefinition.from_parameters(parameters)&.json_schema
+        elsif declared_parameters.any?
+          SchemaDefinition.from_parameters(declared_parameters)&.json_schema
         else
           SchemaDefinition.from_parameters(inferred_parameters, allow_empty: true)&.json_schema
         end
       end
     end
 
-    def call(args)
-      normalized_args = normalize_args(args)
+    # Runs the tool with keyword arguments, validating them against the
+    # #execute signature before invoking it. RubyLLM supplies +tool_call:+
+    # when the call comes from a chat; pass it yourself only when you need
+    # the ToolCall in a direct invocation.
+    #
+    #   Weather.new.call(latitude: 52.52, longitude: 13.405)
+    #
+    def call(tool_call: nil, **arguments)
+      normalized_args = arguments.transform_keys(&:to_sym)
       validation_error = validate_keyword_arguments(normalized_args)
       return { error: "Invalid tool arguments: #{validation_error}" } if validation_error
 
       RubyLLM.logger.debug { "Tool #{name} called with: #{normalized_args.inspect}" }
+      normalized_args[TOOL_CALL_KEYWORD] = tool_call if execute_accepts_tool_call?
       result = execute(**normalized_args)
       RubyLLM.logger.debug { "Tool #{name} returned: #{result.inspect}" }
       result
     end
 
+    # Runs the tool with the arguments chosen by the model. Subclasses must
+    # implement this method; the base implementation raises
+    # NotImplementedError. The return value is sent back to the model.
+    # Return a Hash like <tt>{ error: "..." }</tt> to report a recoverable
+    # failure.
+    #
+    # Declare an optional +tool_call:+ keyword to receive the ToolCall being
+    # executed. The keyword is reserved: it never appears in the tool's
+    # argument schema and is filled in by RubyLLM, not by the model.
+    #
+    #   def execute(query:, tool_call: nil)
+    #     AuditLog.create!(tool_call_id: tool_call&.id)
+    #     Search.run(query)
+    #   end
+    #
     def execute(...)
       raise NotImplementedError, 'Subclasses must implement #execute'
     end
 
     protected
 
-    def halt(message)
-      Halt.new(message)
-    end
-
-    def normalize_args(args)
-      return {} if args.nil?
-      return args.transform_keys(&:to_sym) if args.respond_to?(:transform_keys)
-
-      {}
-    end
-
-    def validate_keyword_arguments(arguments)
-      required_keywords, optional_keywords, accepts_extra_keywords, accepts_positional_arguments =
-        execute_keyword_signature
-
-      return nil if required_keywords.empty? && optional_keywords.empty? && accepts_positional_arguments
+    def validate_keyword_arguments(arguments) # :nodoc:
+      required_keywords, optional_keywords, accepts_extra_keywords = execute_keyword_signature
 
       argument_keys = arguments.keys
-      missing_keyword = first_missing_keyword(required_keywords, argument_keys)
+      missing_keyword = (required_keywords - argument_keys).first
       return "missing keyword: #{missing_keyword}" if missing_keyword
       return nil if accepts_extra_keywords
 
-      allowed_keywords = required_keywords + optional_keywords
-      unknown_keyword = first_unknown_keyword(argument_keys, allowed_keywords)
+      unknown_keyword = (argument_keys - (required_keywords + optional_keywords)).first
       return "unknown keyword: #{unknown_keyword}" if unknown_keyword
 
       nil
     end
 
-    def execute_keyword_signature
-      keyword_signature = method(:execute).parameters
-      required_keywords = keyword_signature.filter_map { |kind, name| name if kind == :keyreq }
-      optional_keywords = keyword_signature.filter_map { |kind, name| name if kind == :key }
-      accepts_extra_keywords = keyword_signature.any? { |kind, _| kind == :keyrest }
-      accepts_positional_arguments = keyword_signature.any? do |kind, _|
-        POSITIONAL_PARAMETER_KINDS.include?(kind)
+    def execute_accepts_tool_call? # :nodoc:
+      method(:execute).parameters.any? do |kind, name|
+        name == TOOL_CALL_KEYWORD && KEYWORD_PARAMETER_KINDS.include?(kind)
       end
-
-      [required_keywords, optional_keywords, accepts_extra_keywords, accepts_positional_arguments]
     end
 
-    def first_missing_keyword(required_keywords, argument_keys)
-      (required_keywords - argument_keys).first
-    end
+    def execute_keyword_signature # :nodoc:
+      keyword_signature = method(:execute).parameters.reject { |_, name| name == TOOL_CALL_KEYWORD }
+      required_keywords = keyword_signature.filter_map { |kind, name| name if kind == :keyreq }
+      optional_keywords = keyword_signature.filter_map { |kind, name| name if kind == :key }
+      accepts_extra_keywords = keyword_signature.any? { |kind, _| kind == :keyrest }
 
-    def first_unknown_keyword(argument_keys, allowed_keywords)
-      (argument_keys - allowed_keywords).first
+      [required_keywords, optional_keywords, accepts_extra_keywords]
     end
 
-    def inferred_parameters
+    def inferred_parameters # :nodoc:
       required_keywords, optional_keywords, = execute_keyword_signature
 
       (required_keywords + optional_keywords).to_h do |name|
@@ -177,9 +352,7 @@ module RubyLLM
       end
     end
 
-    # Wraps schema handling for tool parameters, supporting JSON Schema hashes,
-    # RubyLLM::Schema instances/classes, and DSL blocks.
-    class SchemaDefinition
+    class SchemaDefinition # :nodoc:
       def self.from_parameters(parameters, allow_empty: false)
         return nil if parameters.nil? || (parameters.empty? && !allow_empty)
 
@@ -233,7 +406,9 @@ module RubyLLM
       end
 
       def json_schema
-        @json_schema ||= RubyLLM::Utils.deep_stringify_keys(resolve_schema)
+        @json_schema ||= RubyLLM::Support::Utils.strip_schema_metadata(
+          RubyLLM::Support::Utils.deep_stringify_keys(resolve_schema)
+        )
       end
 
       private
@@ -247,7 +422,7 @@ module RubyLLM
 
       def resolve_direct_schema(schema)
         return extract_schema(schema.to_json_schema) if schema.respond_to?(:to_json_schema)
-        return RubyLLM::Utils.deep_dup(schema) if schema.is_a?(Hash)
+        return RubyLLM::Support::Utils.deep_dup(schema) if schema.is_a?(Hash)
         if schema.is_a?(Class) && schema.method_defined?(:to_json_schema)
           return extract_schema(schema.new.to_json_schema)
         end
@@ -256,7 +431,7 @@ module RubyLLM
       end
 
       def build_from_block(&)
-        schema_class = RubyLLM::Schema.create(&)
+        schema_class = Schematist::Schema.create(&)
         extract_schema(schema_class.new.to_json_schema)
       end
 
@@ -264,7 +439,7 @@ module RubyLLM
         return nil unless schema_hash.is_a?(Hash)
 
         schema = schema_hash[:schema] || schema_hash['schema'] || schema_hash
-        RubyLLM::Utils.deep_dup(schema)
+        RubyLLM::Support::Utils.deep_dup(schema)
       end
     end
   end

data/lib/ruby_llm/tool_call.rb

@@ -1,23 +1,56 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  # Represents a function call from an AI model to a Tool.
+  # A ToolCall is a request to run a tool with specific arguments. Instances
+  # appear in Message#tool_calls. Local calls are yielded to tool callbacks
+  # such as Chat#before_tool_call. Remote calls awaiting approval return
+  # +true+ from #remote? and appear in Chat#pending_approvals.
+  #
+  #   chat.before_tool_call do |tool_call|
+  #     puts "Calling tool: #{tool_call.name}"
+  #     puts "Arguments: #{tool_call.arguments}"
+  #   end
+  #
   class ToolCall
-    attr_reader :id, :name, :arguments
+    include Support::Inspectable
+
+    # The unique identifier for this call. The tool result message
+    # answering this call carries the same id.
+    attr_reader :id
+
+    # The name of the tool the model wants to invoke.
+    attr_reader :name
+
+    # The arguments the model supplied for the invocation, as a Hash.
+    attr_reader :arguments
+
+    # Returns +true+ if the provider executes this call after approval.
+    # Local tools executed by the application return +false+.
+    def remote? = @remote
+
+    # The Gemini thought signature attached to this call, or +nil+.
+    # RubyLLM replays it to the provider on later requests.
     attr_accessor :thought_signature
 
-    def initialize(id:, name:, arguments: {}, thought_signature: nil)
+    def initialize(id:, name:, arguments: {}, thought_signature: nil, remote: false) # :nodoc:
       @id = id
       @name = name
       @arguments = arguments
       @thought_signature = thought_signature
+      @remote = remote
+    end
+
+    def inspect_attributes # :nodoc:
+      { id: id, name: name, arguments: arguments, remote: remote? || nil }.compact
     end
 
+    # Returns the call as a Hash, omitting +nil+ values.
     def to_h
       {
         id: @id,
         name: @name,
         arguments: @arguments,
+        remote: remote? || nil,
         thought_signature: @thought_signature
       }.compact
     end

data/lib/ruby_llm/tools/server_tools.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Tools # :nodoc:
+    # Normalizes and resolves the server tools a chat enabled with
+    # Chat#with_server_tools. Protocols declare an alias table mapping portable
+    # names such as +:web_search+ to their wire format; raw Hashes pass through
+    # verbatim so new provider tools work without a gem update. :nodoc:
+    module ServerTools # :nodoc: all
+      # The result of resolving a chat's server tools against a protocol's
+      # alias table: tool entries for the payload's tools slot, extra payload
+      # fields to merge, and request headers to add.
+      class Resolution
+        attr_reader :tools, :payload, :headers
+
+        def initialize
+          @tools = []
+          @payload = {}
+          @headers = {}
+        end
+
+        def add(spec, options)
+          entry = spec.is_a?(Proc) ? spec.call(options || {}) : merge_tool_options(spec, options)
+          @tools << entry[:tool] if entry[:tool]
+          merge_payload(entry[:payload]) if entry[:payload]
+          merge_headers(entry[:headers]) if entry[:headers]
+          self
+        end
+
+        def add_raw(hash)
+          @tools << hash
+          self
+        end
+
+        private
+
+        def merge_tool_options(spec, options)
+          return spec if options.nil? || options.empty?
+
+          { tool: Support::Utils.deep_merge(spec.fetch(:tool, spec), Support::Utils.deep_symbolize_keys(options)) }
+            .merge(spec.slice(:payload, :headers))
+        end
+
+        # Payload arrays accumulate: every entry contributes its own MCP server.
+        def merge_payload(payload)
+          @payload = @payload.merge(payload) do |_key, current, addition|
+            next current | addition if current.is_a?(Array) && addition.is_a?(Array)
+            next Support::Utils.deep_merge(current, addition) if current.is_a?(Hash) && addition.is_a?(Hash)
+
+            addition
+          end
+        end
+
+        # Anthropic-style beta headers combine as comma-separated values.
+        def merge_headers(headers)
+          headers.each do |key, value|
+            @headers[key] = [@headers[key], value].compact.uniq.join(',')
+          end
+        end
+      end
+
+      module_function
+
+      # Normalizes with_server_tools arguments into entry hashes:
+      # {name:, options:} for aliases and {raw:} for verbatim tool specs.
+      def normalize(tools, tools_with_options)
+        entries = tools.compact.map { |tool| normalize_positional(tool) }
+        entries + tools_with_options.map { |name, options| { name: name.to_sym, options: options.to_h } }
+      end
+
+      def normalize_positional(tool)
+        case tool
+        when Symbol, String then { name: tool.to_sym, options: {} }
+        when Hash then normalized_entry?(tool) ? tool : { raw: tool }
+        else
+          raise ArgumentError,
+                "Server tools must be Symbols or Hashes, got #{tool.class}. " \
+                'Pass :web_search for a portable alias or the provider\'s tool definition as a Hash.'
+        end
+      end
+
+      # Entries that already went through normalize (an Agent's declared
+      # server_tools, for example) pass through unchanged.
+      def normalized_entry?(hash)
+        hash.key?(:raw) ? hash.size == 1 : hash.size == 2 && hash.key?(:name) && hash.key?(:options)
+      end
+
+      # Resolves normalized entries against a protocol's alias table.
+      def resolve(entries, aliases:, owner:)
+        entries.each_with_object(Resolution.new) do |entry, resolution|
+          if entry[:raw]
+            resolution.add_raw(entry[:raw])
+          else
+            spec = aliases[entry[:name]]
+            raise_unknown_alias(entry[:name], aliases, owner) unless spec
+            resolution.add(spec, entry[:options])
+          end
+        end
+      end
+
+      def raise_unknown_alias(name, aliases, owner)
+        known = aliases.keys.map { |key| ":#{key}" }.join(', ')
+        raise UnsupportedServerToolError,
+              "#{owner} has no server tool alias :#{name}. Known aliases: #{known}. " \
+              'New or unlisted tools work by passing the provider\'s tool definition as a Hash.'
+      end
+    end
+  end
+end