ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/tool.rb

@@ -38,8 +38,16 @@ module RubyLLM
   # or ::parameters when arguments need explicit types, descriptions, or
   # structure.
   class Tool
+    include Support::Rescuable
+
     KEYWORD_PARAMETER_KINDS = %i[keyreq key].freeze # :nodoc:
     TOOL_CALL_KEYWORD = :tool_call # :nodoc:
+    ASKING = :ruby_llm_tool_asking # :nodoc:
+    HALT = :ruby_llm_tool_halt # :nodoc:
+
+    # A result that ends the turn, from #halt.
+    Halt = Data.define(:content) # :nodoc:
+    RESUMING = :ruby_llm_tool_resuming # :nodoc:
 
     DUPED_INHERITED_CONFIG = {
       :@declared_parameters => {},
@@ -47,15 +55,73 @@ module RubyLLM
     }.freeze
     COPIED_INHERITED_CONFIG = %i[
       @description
+      @namespace
+      @namespace_description
       @parameters_schema_definition
       @requires_approval
       @approval_resolver
       @deferred
+      @exclusive
+      @max_run_time
+      @inline_limit
     ].freeze
     private_constant :DUPED_INHERITED_CONFIG, :COPIED_INHERITED_CONFIG
 
+    ##
+    # :singleton-method: rescue_from
+    # :call-seq: rescue_from(*exception_classes, with: nil, &block)
+    #
+    # Registers a handler for exceptions a call raises when a chat runs
+    # the tool, from #execute, #resume, or a #call the tool overrides. Name
+    # the handler with +with:+ or pass a block; either runs on the tool
+    # instance. The handler's return value becomes the call's result, as
+    # if #execute had returned it, so the model reads it and the chat
+    # goes on. Re-raise inside a handler to stop the chat with the
+    # exception, as an unhandled one does. Handlers only run for calls a
+    # chat makes. Calling #call or #execute yourself is supported and
+    # runs without handlers, so exceptions reach you.
+    #
+    #   class ApplicationTool < RubyLLM::Tool
+    #     rescue_from StandardError, with: :report_failure
+    #
+    #     rescue_from Faraday::Error do |error|
+    #       { error: "The service didn't answer (#{error.class.name.split("::").last}). Try again later." }
+    #     end
+    #
+    #     private
+    #
+    #     def report_failure(error)
+    #       Rails.error.report(error, context: { tool: name })
+    #       { error: "This tool failed unexpectedly. Trying the same call again won't help." }
+    #     end
+    #   end
+    #
+    # Handlers are searched in reverse declaration order, a class's own
+    # before its parent's, so the last matching one wins. Subclasses use
+    # their parents' handlers, including ones declared after the subclass,
+    # so a handler on Tool itself also covers RubyLLM's own tools, such as
+    # CodeExecution. Declare handlers for a server's tools on its MCP
+    # class. A question from Tool#ask and a cancelled chat never reach a
+    # handler.
+    #
+    # Exception classes may be named as Strings, which defers constant
+    # lookup until an exception is raised. A class that can never match a
+    # StandardError, such as Interrupt, raises ArgumentError.
+
     class << self
-      attr_reader :parameters_schema_definition, :approval_resolver # :nodoc:
+      attr_reader :parameters_schema_definition, :approval_resolver, :namespace_description # :nodoc:
+
+      # Opens the questions of the call a chat makes of +tool+, with
+      # +input+, the answers Chat saved for it, so the call and its
+      # ::rescue_from handler ask in turn and each reads its answers when
+      # the call runs again.
+      def asking(tool, input) # :nodoc:
+        previous = Fiber[ASKING]
+        Fiber[ASKING] = { 'input' => input, 'asked' => 0, 'tool' => tool }
+        yield
+      ensure
+        Fiber[ASKING] = previous
+      end
 
       def inherited(subclass) # :nodoc:
         super
@@ -102,6 +168,29 @@ module RubyLLM
         @description = text
       end
 
+      # Puts the tool in a namespace, or returns its namespace. Tools in
+      # different namespaces can share a name. +description:+ tells the
+      # model what the namespace's tools are for, on APIs that describe
+      # namespaces. Pass +nil+ to remove an inherited namespace.
+      #
+      #   class CustomerLookup < RubyLLM::Tool
+      #     namespace "crm", description: "Customer records and orders"
+      #   end
+      #
+      # A native client toolset, such as Anthropic's computer toolset, calls
+      # the tools in its own namespace:
+      #
+      #   class Screenshot < RubyLLM::Tool
+      #     namespace "computer"
+      #   end
+      def namespace(value = (get = true), description: nil)
+        return @namespace if get
+
+        @namespace = value&.to_s
+        @namespace_description = description
+        @namespace
+      end
+
       # Declares a parameter for the tool. +options+ accepts +type:+
       # (defaults to <tt>'string'</tt>), +description:+, and +required:+
       # (defaults to +true+).
@@ -149,7 +238,7 @@ module RubyLLM
 
       # 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
+      # Chat#approve or Chat#decline, 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.
       #
@@ -182,6 +271,34 @@ module RubyLLM
         @requires_approval || false
       end
 
+      # Declares that this tool runs by itself. When a chat runs a round of
+      # tool calls concurrently (see Chat#with_tool_options), an exclusive
+      # call waits for the calls before it to finish, and the calls after
+      # it wait for it, while the other tools still run in parallel. Use it
+      # for tools that share state, such as a browser page. When an
+      # exclusive call waits for an approval or a Task, the calls after it
+      # stay pending until it finishes.
+      #
+      #   class BrowserClick < RubyLLM::Tool
+      #     exclusive
+      #   end
+      #
+      def exclusive
+        @exclusive = true
+      end
+
+      # Returns whether this tool was declared with ::exclusive.
+      def exclusive?
+        @exclusive || false
+      end
+
+      # Seconds a run of this tool may take before a persisted chat treats
+      # it as crashed, overriding Configuration#max_run_time.
+      def max_run_time(seconds = nil) # :nodoc:
+        @max_run_time = seconds if seconds
+        @max_run_time
+      end
+
       # :call-seq:
       #   provider_options(options) -> self
       #   provider_options -> hash
@@ -219,6 +336,32 @@ module RubyLLM
         @deferred || false
       end
 
+      # :call-seq:
+      #   inline_limit(characters) -> characters
+      #   inline_limit(false) -> false
+      #   inline_limit -> characters, false, or nil
+      #
+      # Sets how many characters this tool's results may have and still go
+      # to the model whole. In a chat with a file store, a longer result is
+      # saved as a file, and the model gets its start and the file's path.
+      # It overrides the chat's own limit (see Chat#with_file_store).
+      # +false+ always sends results whole, for tools that already return
+      # what they find in pages. Without an argument,
+      # returns the declared value, or +nil+.
+      #
+      #   class ExportOrders < RubyLLM::Tool
+      #     inline_limit 50_000
+      #   end
+      #
+      def inline_limit(characters = (get = true))
+        return @inline_limit if get
+        unless characters == false || (characters.is_a?(Integer) && characters.positive?)
+          raise ArgumentError, 'inline_limit takes a positive number of characters or false'
+        end
+
+        @inline_limit = characters
+      end
+
       def split_result(result) # :nodoc:
         case result
         when Attachment then ['', [result]]
@@ -260,13 +403,29 @@ module RubyLLM
       self.class.tool_name
     end
 
+    # Returns the tool's namespace, or +nil+ when it has none. See
+    # ::namespace.
+    def namespace
+      self.class.namespace
+    end
+
+    def namespace_description # :nodoc:
+      self.class.namespace_description
+    end
+
+    def qualified_name # :nodoc:
+      namespace ? "#{namespace}_#{name}" : name
+    end
+
     # Returns the tool description declared on the class with ::description.
     def description
       self.class.description
     end
 
-    # Returns whether this tool was declared with ::requires_approval.
-    def requires_approval?
+    # Returns whether +tool_call+ must be approved before it runs: whether
+    # this tool was declared with ::requires_approval. A subclass may
+    # override it to decide from the call's arguments.
+    def requires_approval?(tool_call = nil) # rubocop:disable Lint/UnusedMethodArgument
       self.class.requires_approval?
     end
 
@@ -274,6 +433,22 @@ module RubyLLM
       self.class.approval_resolver
     end
 
+    # Returns whether this tool runs by itself in a concurrent round of
+    # tool calls: whether its class was declared with ::exclusive.
+    def exclusive?
+      self.class.exclusive?
+    end
+
+    # Returns the limit declared on the class with ::inline_limit: a number
+    # of characters, +false+, or +nil+ to use the chat's.
+    def inline_limit
+      self.class.inline_limit
+    end
+
+    def max_run_time # :nodoc:
+      self.class.max_run_time
+    end
+
     def declared_parameters # :nodoc:
       self.class.declared_parameters
     end
@@ -283,9 +458,39 @@ module RubyLLM
       self.class.provider_options
     end
 
+    # Keeps this tool, and no other of its class, out of the model's
+    # context until tool search loads it, as ::defer does for the class.
+    # Returns +self+. Chat#with_tools and Chat#with_mcp take +defer:+ to
+    # decide for every tool they register instead.
+    #
+    #   chat.with_tools(CurrentTime.new, *connector_tools.map(&:defer))
+    #
+    def defer
+      @deferred = true
+      self
+    end
+
+    # Returns whether this tool waits to be found by tool search: whether
+    # it was deferred with #defer, or its class with ::defer.
+    def deferred?
+      @deferred || self.class.deferred?
+    end
+
     class Deferred < SimpleDelegator # :nodoc:
     end
 
+    class Flattened < SimpleDelegator # :nodoc:
+      def self.wrap(tool)
+        return Deferred.new(new(tool.__getobj__)) if tool.is_a?(Deferred)
+
+        new(tool)
+      end
+
+      def name = __getobj__.qualified_name
+      def namespace = nil
+      def qualified_name = name
+    end
+
     # Returns the JSON Schema for the tool's arguments, whether declared
     # explicitly or inferred from the +execute+ signature.
     def parameters_schema
@@ -317,11 +522,61 @@ module RubyLLM
 
       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)
+      result = asking { halting { execute(**normalized_args) } }
       RubyLLM.logger.debug { "Tool #{name} returned: #{result.inspect}" }
       result
     end
 
+    # Asks the person who runs the chat +message+ while #execute runs, and
+    # returns their answer. The call pauses until they answer (see
+    # Chat#pending_questions), then #execute runs again from the top, and
+    # this time +ask+ returns the answer:
+    #
+    #   def execute(destination:)
+    #     seat = ask("Window or aisle?", choices: %w[window aisle]) or return "No seat chosen."
+    #     Flights.book!(destination, seat:)
+    #   end
+    #
+    # Code before +ask+ runs again too, so make it safe to repeat: ask
+    # first, then act. A call may ask several questions, one after
+    # another, and each run asks them in the same order.
+    #
+    # Without options, +ask+ takes free text and returns the String. With
+    # +choices:+ it returns the one the person picked. With a block, it
+    # asks for the fields the block declares, in the DSL of
+    # Tool.parameters, and returns their values by name. With +url:+, it
+    # asks the person to visit a page, such as to connect an account, and
+    # returns +true+ once they say they did.
+    #
+    #   passenger = ask("Who is flying?") do
+    #     string :name, description: "As on the passport"
+    #     integer :age, required: false
+    #   end
+    #   passenger # => {name: "Ada Lovelace", age: 36}
+    #
+    #   ask("Connect your calendar", url: authorization_url)
+    #
+    # Returns +nil+ when the person declines. Outside a chat, nothing can
+    # pause the call, so +ask+ raises InputRequiredError. Raises
+    # ArgumentError when given more than one of +choices:+, +url:+, and a
+    # block.
+    def ask(message, choices: nil, url: nil, &fields)
+      if [choices, url, fields].compact.size > 1
+        raise ArgumentError, 'ask takes choices:, url:, or a block of fields: one kind of answer at a time'
+      end
+
+      state = (Fiber[ASKING] ||= { 'input' => nil, 'asked' => 0 })
+      index = state['asked']
+      state['asked'] += 1
+      requests = Array(state['input']&.[]('requests'))
+      return Question.from_h(requests[index]).asked_answer(fields) if requests[index]&.[]('response')
+
+      schema = SchemaDefinition.new(block: fields).json_schema if fields
+      asked = requests.first(index).map { |data| Question.from_h(data) }
+      question = Question.asked(index, message, choices:, url:, schema:)
+      raise InputRequiredError.new(name, { 'requests' => [*asked, question] })
+    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.
@@ -341,6 +596,55 @@ module RubyLLM
       raise NotImplementedError, 'Subclasses must implement #execute'
     end
 
+    # Carries on a call that paused on +task+, the Task #execute returned,
+    # with the call's +arguments+. Each Chat#complete calls it once for
+    # every paused call of the round. Return the call's result to finish
+    # it, or a Task, +task+ itself or a new one, to keep it paused. Tools
+    # that return a Task must implement this method; the base
+    # implementation raises NotImplementedError.
+    #
+    #   def resume(task, **)
+    #     envelope = Signatures.find(task.data["envelope_id"])
+    #     envelope.signed? ? "Signed on #{envelope.signed_on}" : task
+    #   end
+    #
+    def resume(task, **arguments)
+      raise NotImplementedError, "#{self.class} returned a Task, so it must implement #resume"
+    end
+
+    # Returns the Task that +tool_call+ paused on, from +state+, the Hash
+    # Task#to_h returned. Override it to return a Task subclass.
+    #
+    #   def task(state, tool_call: nil)
+    #     SignatureTask.load(state, tool_call:)
+    #   end
+    #
+    def task(state, tool_call: nil)
+      Task.load(state, tool_call:)
+    end
+
+    def resume_call(state, arguments, tool_call:) # :nodoc:
+      return answered(state, arguments, tool_call:) unless state.key?('task')
+
+      halting { resume(task(state, tool_call:), **arguments.transform_keys(&:to_sym)) }
+    end
+
+    # Ends the turn with +result+ as this call's result: the model is not
+    # asked to respond once the round's other calls finish. It stops
+    # #execute where it is called, so call it, or return it, when the tool
+    # has said the last word, such as filing a ticket a triage turn exists
+    # for. The result reaches the conversation as any other, and the next
+    # Chat#ask starts a new turn. See Chat#complete?.
+    #
+    #   def execute(category:)
+    #     ticket.update!(category:)
+    #     halt "Filed as #{category}"
+    #   end
+    #
+    def halt(result = nil)
+      throw HALT, Halt.new(result)
+    end
+
     # Reports what the tool is doing while #execute runs, so an application
     # can show it before the result arrives. Chat#after_tool_progress
     # callbacks receive it as a Progress. Pass +value:+ and +total:+ when
@@ -376,6 +680,36 @@ module RubyLLM
       nil
     end
 
+    # A call's questions are counted from its start; one resumed keeps the
+    # answers it was given (#answered), and a call it makes of another tool
+    # neither sees them nor moves its count.
+    # A fresh Hash each time: fibers inherit their parent's storage, and
+    # parallel calls mustn't share a count.
+    def halting(&) # :nodoc:
+      catch(HALT, &)
+    end
+
+    # The call a chat makes of a tool takes the questions Tool.asking
+    # opened for it, which its handler then shares.
+    def asking # :nodoc:
+      previous = Fiber[ASKING]
+      input = Fiber[RESUMING]
+      Fiber[RESUMING] = nil
+      Fiber[ASKING] = previous&.delete('tool') == self ? previous : { 'input' => input, 'asked' => 0 }
+      yield
+    ensure
+      Fiber[ASKING] = previous
+    end
+
+    # Runs a call again that paused on its questions (#ask), now answered or
+    # declined, with +input+, the state Chat saved for it.
+    def answered(input, arguments, tool_call:) # :nodoc:
+      Fiber[RESUMING] = input
+      call(**arguments, tool_call:)
+    ensure
+      Fiber[RESUMING] = nil
+    end
+
     def execute_accepts_tool_call? # :nodoc:
       method(:execute).parameters.any? do |kind, name|
         name == TOOL_CALL_KEYWORD && KEYWORD_PARAMETER_KINDS.include?(kind)

data/lib/ruby_llm/tool_call/collection.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class ToolCall
+    # The tool calls of a Message: an Enumerable of ToolCall objects in the
+    # order the provider returned them, also readable by call ID. Empty on
+    # a message without calls.
+    #
+    #   response.tool_calls.first
+    #   response.tool_calls.map(&:name) # => ["search_issues"]
+    #   response.tool_calls["call_1"]
+    #
+    class Collection
+      include Enumerable
+      include Support::Inspectable
+
+      def initialize(calls = {}) # :nodoc:
+        @calls = calls.to_h
+      end
+
+      # Yields each ToolCall, in provider order.
+      #
+      #   response.tool_calls.each { |call| puts call.name }
+      #
+      def each(&)
+        return enum_for(__method__) { size } unless block_given?
+
+        @calls.each_value(&)
+        self
+      end
+      alias each_value each
+
+      # Yields each key, in provider order: the call ID on a complete message,
+      # and on a streamed Chunk the stream index when the provider sends one.
+      def each_key(&)
+        return enum_for(__method__) { size } unless block_given?
+
+        @calls.each_key(&)
+        self
+      end
+
+      # Returns the ToolCall with the ID +id+, or +nil+.
+      def [](id)
+        @calls[key_for(id)]
+      end
+
+      def []=(id, call) # :nodoc:
+        @calls[id] = call
+      end
+
+      # Returns the ToolCall with the ID +id+. Without a default or a block,
+      # raises KeyError when there is none.
+      def fetch(id, ...)
+        @calls.fetch(key_for(id), ...)
+      end
+
+      # Returns the number of tool calls.
+      def size
+        @calls.size
+      end
+      alias length size
+
+      # Returns +true+ when there are no tool calls.
+      def empty?
+        @calls.empty?
+      end
+
+      # Returns the tool calls as an Array.
+      def values
+        @calls.values
+      end
+
+      # Returns the keys as an Array, as #each_key yields them.
+      def keys
+        @calls.keys
+      end
+
+      # Returns +true+ when there is a tool call with the ID +id+.
+      def key?(id)
+        @calls.key?(key_for(id))
+      end
+
+      # Returns a Hash of what the block returns for each ToolCall, keyed by
+      # call ID.
+      def transform_values(&)
+        @calls.transform_values(&)
+      end
+
+      # Returns a Collection without the calls with the given IDs.
+      def except(*ids)
+        self.class.new(@calls.except(*ids.map { |id| key_for(id) }))
+      end
+
+      # Returns the tool calls as a new Hash of ToolCall objects keyed by call
+      # ID. With a block, returns the Hash of the pairs it makes from each ID
+      # and ToolCall.
+      def to_h(&block)
+        block ? @calls.to_h(&block) : @calls.dup
+      end
+      alias to_hash to_h
+
+      # Returns +true+ when +other+ is a Collection or Hash of the same calls
+      # under the same IDs.
+      def ==(other)
+        other.respond_to?(:to_hash) && @calls == other.to_hash
+      end
+
+      # Returns the JSON of #to_h.
+      def to_json(*)
+        @calls.to_json(*)
+      end
+
+      # Returns the JSON-ready form of #to_h, where Active Support provides
+      # one, or #to_h.
+      def as_json(*)
+        @calls.respond_to?(:as_json) ? @calls.as_json(*) : to_h
+      end
+
+      private
+
+      def key_for(id)
+        return id if id.nil? || @calls.key?(id)
+
+        @calls.find(-> { [id] }) { |_, call| call.id == id }.first
+      end
+
+      def inspect_attributes
+        { calls: map(&:name) }
+      end
+    end
+  end
+end

data/lib/ruby_llm/tool_call.rb

@@ -4,7 +4,8 @@ module RubyLLM
   # 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.
+  # +true+ from #remote?, and their approvals appear among
+  # Chat#pending_questions.
   #
   #   chat.before_tool_call do |tool_call|
   #     puts "Calling tool: #{tool_call.name}"
@@ -14,13 +15,31 @@ module RubyLLM
   class ToolCall
     include Support::Inspectable
 
-    # The unique identifier for this call. The tool result message
-    # answering this call carries the same id.
+    def self.index(calls, by: :id) # :nodoc:
+      calls.each_with_object({}) do |call, indexed|
+        id = call.public_send(by) || call.provider_call_id
+        raise Error, "Duplicate tool call ID in one response: #{id.inspect}" if indexed.key?(id)
+
+        indexed[id] = call
+      end
+    end
+
+    # The RubyLLM identifier for this invocation. The tool result message
+    # answering this call carries the same id, including after a reload.
+    # This is independent of the ID in the provider's response.
     attr_reader :id
 
     # The name of the tool the model wants to invoke.
     attr_reader :name
 
+    # The namespace of the tool the model wants to invoke, or +nil+ for a
+    # tool without one. See Tool.namespace.
+    attr_reader :namespace
+
+    def qualified_name # :nodoc:
+      namespace ? "#{namespace}_#{name}" : name
+    end
+
     # The arguments the model supplied for the invocation, as a Hash. Keys
     # are ordered the way PostgreSQL +jsonb+ and MySQL +json+ store them,
     # shorter keys first, so a call reloaded from the database renders the
@@ -35,24 +54,67 @@ module RubyLLM
     # RubyLLM replays it to the provider on later requests.
     attr_accessor :thought_signature
 
-    def initialize(id:, name:, arguments: {}, thought_signature: nil, remote: false) # :nodoc:
+    def self.parse_arguments(text, response: nil, finish_reason: nil) # :nodoc:
+      return { arguments: text } if text.is_a?(Hash)
+
+      text = JSON.generate(text) unless text.nil? || text.is_a?(String)
+      return { arguments: {} } if text.nil? || text.empty?
+
+      { arguments: Hash(JSON.parse(text)) }
+    rescue JSON::ParserError, TypeError => e
+      raise ToolCallTruncatedError.new(response:), cause: e if finish_reason == :max_tokens
+
+      { malformed_arguments: text }
+    end
+
+    def initialize(name:, id: nil, provider_call_id: nil, arguments: {}, thought_signature: nil,
+                   remote: false, namespace: nil, malformed_arguments: nil) # :nodoc:
       @id = id
+      @provider_call_id = provider_call_id
       @name = name
-      @arguments = canonical_arguments(arguments)
+      @namespace = namespace&.to_s
+      @malformed_arguments = malformed_arguments
+      @arguments = malformed_arguments ? {} : canonical_arguments(arguments)
       @thought_signature = thought_signature
       @remote = remote
     end
 
+    # The provider's argument text when it was not a JSON object, or +nil+.
+    # A call with such text has empty #arguments and never runs.
+    attr_reader :malformed_arguments # :nodoc:
+
+    def malformed_arguments? = !@malformed_arguments.nil? # :nodoc:
+
+    def malformed_arguments_problem # :nodoc:
+      JSON.parse(@malformed_arguments)
+      'not a JSON object'
+    rescue JSON::ParserError => e
+      "not valid JSON (#{e.message})"
+    end
+
+    def provider_call_id = @provider_call_id || id # :nodoc:
+
+    def with_id(id) # :nodoc:
+      dup.tap do |call|
+        call.instance_variable_set(:@provider_call_id, provider_call_id)
+        call.instance_variable_set(:@id, id)
+      end
+    end
+
     def inspect_attributes # :nodoc:
-      { id: id, name: name, arguments: arguments, remote: remote? || nil }.compact
+      { id: id, name: name, namespace: namespace, arguments: arguments, remote: remote? || nil,
+        malformed_arguments: malformed_arguments }.compact
     end
 
     # Returns the call as a Hash, omitting +nil+ values.
     def to_h
       {
         id: @id,
+        provider_call_id: @provider_call_id,
         name: @name,
+        namespace: @namespace,
         arguments: @arguments,
+        malformed_arguments: @malformed_arguments,
         remote: remote? || nil,
         thought_signature: @thought_signature
       }.compact