ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/rerank.rb

@@ -13,6 +13,7 @@ module RubyLLM
   class Rerank
     include Support::Inspectable
     include Accounting::Usage::Result
+    include Accounting::Usage::ModelInfo
 
     # One reranked document: its +index+ in the input array, the
     # +document+ text, and the provider's relevance +score+.
@@ -27,11 +28,12 @@ module RubyLLM
     # The raw provider response body.
     attr_reader :raw
 
-    def initialize(results:, model:, raw: nil, input_tokens: nil, reported_cost: nil) # :nodoc:
+    def initialize(results:, model:, raw: nil, input_tokens: nil, search_units: nil, reported_cost: nil) # :nodoc:
       @results = results
       @model = model
       @raw = raw
       @input_tokens = input_tokens
+      @search_units = search_units
       @reported_cost = reported_cost
     end
 
@@ -39,7 +41,7 @@ module RubyLLM
     def tokens
       return ruby_llm_usage_tokens unless ruby_llm_usage_entries.empty?
 
-      Tokens.new(input: @input_tokens, reported_cost: @reported_cost)
+      Tokens.new(input: @input_tokens, search_units: @search_units, reported_cost: @reported_cost)
     end
 
     # Returns the rerank cost across every provider attempt.
@@ -49,14 +51,6 @@ module RubyLLM
       Cost.new(tokens:, model: model_info, category: :embeddings)
     end
 
-    attr_writer :model_info # :nodoc:
-
-    def model_info # :nodoc:
-      @model_info ||= RubyLLM.models.find(model)
-    rescue ModelNotFoundError
-      nil
-    end
-
     def inspect_attributes # :nodoc:
       { model: model, results: results.length }
     end
@@ -67,7 +61,7 @@ module RubyLLM
     # limits how many results come back. +provider_options:+ merges
     # options into the request in the provider's vocabulary.
     # +owner:+ attributes the usage to a record, such as a user, and wins
-    # over RubyLLM.with_usage_owner.
+    # over RubyLLM.with_owner.
     #
     #   RubyLLM.rerank "what is ruby", docs, model: "voyageai/rerank-2.5-lite", provider: :openrouter
     #
@@ -80,32 +74,11 @@ module RubyLLM
                     provider_options: {},
                     metadata: nil,
                     owner: nil)
-      config = context&.config || RubyLLM.config
-      model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
-                                                       config: config)
-      empty_tokens = Tokens.new
-      payload = {
-        provider: provider_instance.slug,
-        provider_class: provider_instance.name,
-        model: model.id,
-        model_info: model,
-        query: query,
-        document_count: documents.length,
-        top_n: top_n,
-        provider_options: provider_options,
-        metadata: metadata,
-        tokens: empty_tokens,
-        cost: Cost.new(tokens: empty_tokens, model:, category: :embeddings)
-      }
-
-      RubyLLM.instrument('rerank.ruby_llm', payload, config: config) do |event|
-        result = Accounting::Usage.owned_by(owner) do
-          provider_instance.rerank(query, documents, model:, top_n:, provider_options:)
-        end
-        event[:result] = result
-        event[:tokens] = result.tokens
-        event[:cost] = result.cost
-        result
+      Accounting::Operation.new(
+        'rerank', model, category: :embeddings, provider:, assume_model_exists:, context:, owner:
+      ).run(query:, document_count: documents.length, top_n:, provider_options:,
+            metadata:) do |provider_instance, model|
+        provider_instance.rerank(query, documents, model:, top_n:, provider_options:)
       end
     end
   end

data/lib/ruby_llm/research_job.rb

@@ -11,6 +11,7 @@ module RubyLLM
   #
   class ResearchJob
     include Support::Inspectable
+    include Support::DeprecatedJobPredicates
 
     class DeadlineExpired < StandardError; end # :nodoc:
     private_constant :DeadlineExpired
@@ -70,7 +71,7 @@ module RubyLLM
     # +provider_tools:+ accepts an array of aliases or a Hash of aliases
     # and their options, as on Chat#with_provider_tools. The job records
     # its usage, attributed to +owner:+ or the owner of
-    # RubyLLM.with_usage_owner, when it finishes.
+    # RubyLLM.with_owner, when it finishes.
     def self.research_later(prompt, provider:, agent:, with: nil, provider_tools: nil,
                             context: nil, provider_options: {}, metadata: nil, owner: nil)
       config = context&.config || RubyLLM.config
@@ -128,6 +129,7 @@ module RubyLLM
       @agent = agent
       @protocol = protocol
       @usage_owner = Accounting::Usage.owner
+      @usage_workflow = Accounting::Usage.workflow
       apply_state(state)
     end
 
@@ -135,10 +137,10 @@ module RubyLLM
     def pending? = status == :pending
 
     # Returns whether the task reached any terminal state.
-    def done? = !pending?
+    def complete? = !pending?
 
     # Returns whether the task finished with a complete report.
-    def completed? = status == :completed
+    def succeeded? = status == :completed
 
     # Returns whether the provider stopped before completing the report.
     def incomplete? = status == :incomplete
@@ -153,7 +155,7 @@ module RubyLLM
     # task finishes. +timeout:+ limits this request in seconds.
     def refresh(timeout: nil)
       self.class.validate_polling_options(timeout, 1) unless timeout.nil?
-      unless done?
+      unless complete?
         state = request_with_timeout(timeout) { @protocol.refresh_research_job(self, timeout:) }
         apply_state(state)
       end
@@ -166,7 +168,7 @@ module RubyLLM
     def wait(timeout: 600, interval: 5)
       self.class.validate_polling_options(timeout, interval)
       deadline = monotonic_time + timeout
-      until done?
+      until complete?
         remaining = deadline - monotonic_time
         raise TimeoutError.new("Research timed out (job #{id})", job: self) unless remaining.positive?
 
@@ -182,7 +184,7 @@ module RubyLLM
     # can confirm cancellation; this does not delete stored task data.
     def cancel(timeout: 5)
       self.class.validate_polling_options(timeout, 1)
-      unless done?
+      unless complete?
         state = request_with_timeout(timeout) { @protocol.cancel_research_job(self, timeout:) }
         apply_state(state)
       end
@@ -212,19 +214,29 @@ module RubyLLM
     def request_with_timeout(timeout, &)
       Timeout.timeout(timeout, DeadlineExpired, &)
     rescue DeadlineExpired, Faraday::TimeoutError => e
-      raise TimeoutError.new("Research request timed out (job #{id})", job: self), cause: e
+      raise request_timed_out, cause: e
     rescue Error
       raise
+    rescue ConnectionError => e
+      raise e.timeout? ? request_timed_out : request_failed(e), cause: e
     rescue RubyLLM::Error, Faraday::Error => e
-      response = e.response if e.respond_to?(:response)
+      raise request_failed(e), cause: e
+    end
+
+    def request_timed_out
+      TimeoutError.new("Research request timed out (job #{id})", job: self)
+    end
+
+    def request_failed(error)
+      response = error.response if error.respond_to?(:response)
       @raw = response.body if response.respond_to?(:body)
-      raise Error.new("Research request failed: #{e.message} (job #{id})", job: self, response:), cause: e
+      Error.new("Research request failed: #{error.message} (job #{id})", job: self, response:)
     end
 
-    # A job found by ID may have been submitted and recorded elsewhere, so
-    # only a finish this object observes records usage.
+    # Each object records its job's usage once: when it first sees the job
+    # finished, at construction or on a later refresh.
     def apply_state(state)
-      observed_finish = pending? && state.fetch(:status) != :pending
+      observed_finish = (@status.nil? || pending?) && state.fetch(:status) != :pending
       @status = state.fetch(:status)
       @raw = state[:raw]
       @error = state[:error]
@@ -236,7 +248,8 @@ module RubyLLM
     def record_usage
       status = { completed: :succeeded, incomplete: :succeeded, cancelled: :cancelled }.fetch(@status, :failed)
       entry = Accounting::Usage::Entry.new(operation: :research, provider:, model: agent, status:, tokens:, cost:,
-                                           owner: @usage_owner)
+                                           owner: @usage_owner,
+                                           workflow: @usage_workflow)
       Accounting::Usage.report(entry, config: @protocol.config)
     end
 

data/lib/ruby_llm/sandbox/landlock.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Sandbox
+    # Rewrites a policy for Landlock, which grants whole directory trees
+    # and cannot take part of one away. Each readable or writable path that
+    # holds a denied one is replaced by the entries around it, down to the
+    # denied path, so the policy hides the same paths without denying
+    # anything inside a granted tree. Entries added later to a directory
+    # granted entry by entry stay hidden. A writable path cannot be split
+    # that way, since creating files needs the directory itself, so a
+    # denied path inside one raises ConfigurationError. Paths compare by
+    # where they really lead, since that is what Landlock grants.
+    module Landlock # :nodoc:
+      module_function
+
+      def policy(sandbox)
+        denied, readable, writable = [sandbox.denied, sandbox.readable, sandbox.writable].map do |paths|
+          paths.map { |path| real(path) }
+        end
+        refuse_writable(writable, denied)
+        sandbox.dup
+               .with_readable(nil).with_readable(*around(readable, denied))
+               .with_writable(nil).with_writable(*around(writable, denied))
+               .with_denied(nil)
+               .with_denied(*denied.reject { |path| (readable + writable).any? { |root| inside?(path, root) } })
+               .with_backend(:landlock)
+      end
+
+      def refuse_writable(writable, denied)
+        writable.each do |path|
+          hidden = denied.find { |candidate| candidate != path && inside?(candidate, path) }
+          next unless hidden
+
+          raise ConfigurationError, "Landlock cannot hide #{hidden} inside the writable #{path}. " \
+                                    'Leave it out of the writable path, or run on Bubblewrap'
+        end
+      end
+
+      def around(paths, denied)
+        paths.flat_map { |path| entries(path, denied) }.uniq
+      end
+
+      def entries(path, denied)
+        return [] if hidden?(path, denied)
+
+        return [path] if denied.none? { |hidden| inside?(hidden, path) }
+        return [] unless File.directory?(path)
+
+        Dir.children(path).sort.flat_map { |child| entries(File.join(path, child), denied) }
+      end
+
+      def hidden?(path, denied)
+        denied.any? { |hidden| inside?(path, hidden) } || reaches?(path, denied)
+      end
+
+      def reaches?(path, denied)
+        return false unless File.symlink?(path)
+
+        target = File.realpath(path)
+        denied.any? { |hidden| inside?(target, hidden) || inside?(hidden, target) }
+      rescue SystemCallError
+        true
+      end
+
+      def real(path)
+        path = File.expand_path(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.join(real(File.dirname(path)), File.basename(path))
+      end
+
+      def inside?(path, root)
+        path == root || path.start_with?(File.join(root, ''))
+      end
+    end
+  end
+end

data/lib/ruby_llm/sandbox/mxc.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Sandbox
+    # Runs commands with an MXC::Sandbox class or instance from the mxc gem:
+    # Bubblewrap on Linux, unless Configuration#sandbox_backend or the
+    # sandbox asks for Landlock, Seatbelt on macOS, and process containers
+    # on Windows. Each run starts from a fresh copy of the sandbox's policy
+    # and adds only what RubyLLM passes for that run.
+    class MXC # :nodoc:
+      DOCS = 'https://rubyllm.com/sandboxes/#running-on-landlock'
+      NAMESPACES = /namespace/i
+      BUBBLEWRAP_REMEDIATION =
+        'Allow unprivileged user namespaces for Bubblewrap: on Ubuntu 23.10 and later, including 24.04, ' \
+        'give bwrap an AppArmor profile that allows userns, or, host-wide and weaker, run ' \
+        'sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0; on kernels with ' \
+        'kernel.unprivileged_userns_clone, set it to 1. In Docker, run with a seccomp profile that allows ' \
+        'namespaces: https://crmne.github.io/mxc/running-in-docker/. ' \
+        'See https://rubyllm.com/sandboxes/#running-on-linux'
+      LANDLOCK_OPT_IN = 'Or set config.sandbox_backend = :landlock to run on Landlock, which isolates less ' \
+                        "and has no network access: #{DOCS}".freeze
+      MINIMUM_VERSION = '0.4.1'
+      private_constant :MINIMUM_VERSION
+
+      attr_reader :policy, :libraries
+
+      # Raises ConfigurationError when the installed mxc is older than
+      # MINIMUM_VERSION.
+      def initialize(policy, backend: :bubblewrap, libraries: [])
+        require_minimum_version
+        @policy = policy
+        @backend = backend
+        @libraries = libraries
+      end
+
+      def supported?
+        sandbox.supported?
+      end
+
+      def reason
+        current = sandbox
+        availability = current.availability
+        return if availability.supported?
+
+        [availability.reason, *remediation(current.backend, availability)].compact.join(' ')
+      end
+
+      def backend = sandbox.backend
+      def readable = sandbox.readable
+      def writable = sandbox.writable
+      def network = sandbox.network
+      def directory = sandbox.directory
+      def timeout = sandbox.timeout
+      def limits = sandbox.respond_to?(:limits) ? sandbox.limits : {}
+
+      # Returns a runner for a sandbox with none of this one's access, on
+      # the same backend, for RubyLLM's own package installs.
+      def isolated
+        self.class.new(::MXC::Sandbox.new(backend: sandbox.backend), backend: @backend, libraries: @libraries)
+      end
+
+      # Returns a runner whose commands may load the libraries +binaries+
+      # link, such as an interpreter's extensions. mxc before 0.4 cannot
+      # grant them, and runs without.
+      def with_libraries_of(*binaries)
+        self.class.new(@policy, backend: @backend, libraries: [*@libraries, *binaries])
+      end
+
+      def run(*command, timeout:, readable: [], writable: [], denied: [], directory: nil, env: {}, network: nil, &)
+        run = sandbox.with_readable(*readable).with_writable(*writable).with_denied(*denied).with_timeout(timeout)
+        run.with_directory(directory) if run.directory.nil? && directory
+        run.with_env(env.reject { |name, _| run.env.key?(name) })
+        apply_network(run, network)
+        run.with_libraries_of(*@libraries) if run.respond_to?(:with_libraries_of)
+        run = Landlock.policy(run) if run.backend == :landlock
+        block_given? ? run_by_line(run, command, &) : run.run(*command)
+      end
+
+      def inspect
+        "#<#{self.class.name} #{sandbox.inspect}>"
+      end
+
+      private
+
+      def require_minimum_version
+        return unless defined?(::MXC::VERSION)
+
+        installed = ::MXC::VERSION
+        return if Gem::Version.new(installed) >= Gem::Version.new(MINIMUM_VERSION)
+
+        raise ConfigurationError,
+              "RubyLLM's sandbox needs mxc #{MINIMUM_VERSION} or later; you have #{installed}. Run bundle update mxc."
+      end
+
+      def run_by_line(run, command)
+        pending = Hash.new { |buffers, stream| buffers[stream] = String.new(encoding: Encoding::BINARY) }
+        result = run.run(*command) do |chunk|
+          buffer = pending[chunk.stream]
+          scanned = buffer.bytesize
+          buffer << chunk.content.b
+          while (newline = buffer.index("\n", scanned))
+            yield text(buffer.slice!(0..newline))
+            scanned = 0
+          end
+        end
+        pending.each_value { |rest| yield text(rest) unless rest.empty? }
+        result
+      end
+
+      def text(bytes)
+        bytes.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      def sandbox
+        sandbox = @policy.is_a?(Class) ? @policy.new : @policy.dup
+        sandbox.backend == :auto && linux? ? sandbox.with_backend(@backend) : sandbox
+      end
+
+      def remediation(backend, availability)
+        return availability.remediation unless backend == :bubblewrap
+
+        namespaces = [availability.reason, availability.remediation].join(' ').match?(NAMESPACES)
+        [namespaces ? BUBBLEWRAP_REMEDIATION : availability.remediation, LANDLOCK_OPT_IN]
+      end
+
+      def linux?
+        RUBY_PLATFORM.include?('linux')
+      end
+
+      def apply_network(run, network)
+        return if network.nil?
+
+        network.is_a?(Hash) ? run.with_network(**network) : run.with_network(network)
+      end
+    end
+  end
+end

data/lib/ruby_llm/sandbox.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A sandbox runs commands RubyLLM did not write, such as the code a model
+  # sends to Chat#with_code_execution, and holds the whole policy for them:
+  # what they may read and write, which hosts they reach, where they start,
+  # and how long they run. Define one as an MXC::Sandbox class from the mxc
+  # gem:
+  #
+  #   class ReadOnlySandbox < MXC::Sandbox
+  #     timeout 120
+  #   end
+  #
+  #   class WorkspaceSandbox < MXC::Sandbox
+  #     directory Rails.root.join("storage/workspace")
+  #     writable Rails.root.join("storage/workspace")
+  #     timeout 300
+  #   end
+  #
+  #   RubyLLM.configure do |config|
+  #     config.sandbox = "ReadOnlySandbox"
+  #   end
+  #
+  # A String names the class and is looked up whenever a chat needs it,
+  # so in Rails the classes live in +app/sandboxes+, autoload, and reload
+  # like the rest of the application.
+  #
+  # A sandbox may be an MXC::Sandbox class or instance, or any other class
+  # or object whose instances answer two methods:
+  #
+  #   class RemoteSandbox
+  #     def supported?
+  #       true
+  #     end
+  #
+  #     def run(*command, timeout:, readable: [], writable: [], denied: [], directory: nil, env: {}, network: nil)
+  #       # Runs +command+ and returns an object answering stdout, stderr,
+  #       # exit_code, and timed_out?
+  #     end
+  #   end
+  #
+  # +run+ takes the command like Kernel#system: one String for the shell,
+  # or a program and its arguments. The keywords are what RubyLLM adds to
+  # the sandbox's own policy for one run: +readable+ and +writable+ paths
+  # holding the run's files, +denied+ paths it must not see, even inside
+  # readable ones, the +directory+ to start in when the sandbox has none of
+  # its own, and +env+, the environment the run's languages and packages
+  # need. +timeout+ is the sandbox's own, or 120 seconds when it answers
+  # +timeout+ with +nil+ or not at all. +network+ is +nil+ for the
+  # sandbox's own access; RubyLLM passes <tt>{ allow: [...] }</tt> only to
+  # install declared packages from their registries. With a block, +run+
+  # may yield each line of output as it arrives, from standard output and
+  # standard error, like IO#each_line, and code execution reports the
+  # lines as progress; a sandbox may ignore the block. The result may also
+  # answer +blocked+, the hosts the network policy refused. A sandbox may
+  # answer +reason+, which RubyLLM adds to the error it raises when
+  # #supported? is false, and +with_libraries_of+, taking paths and
+  # returning a sandbox whose runs may load the libraries those files
+  # link, which RubyLLM calls with Ruby and its extensions. It may also
+  # answer +readable+, +writable+, +network+, +directory+, and +timeout+,
+  # which describe it to the model and to the person approving an
+  # escalation.
+  module Sandbox
+    # Seconds a run may take when the sandbox sets no timeout.
+    DEFAULT_TIMEOUT = 120
+
+    # The values Configuration#sandbox_backend accepts.
+    BACKENDS = %i[bubblewrap landlock].freeze
+
+    class << self
+      # Returns a runner for the sandbox +value+ describes, or +nil+ for
+      # none. A String names the sandbox class, looked up on each call.
+      # An MXC::Sandbox runs on +backend+ on Linux unless it names its own.
+      #
+      # Raises ConfigurationError for a value that is not a sandbox, or for
+      # a backend other than those in BACKENDS.
+      def resolve(value, backend: RubyLLM.config.sandbox_backend) # :nodoc:
+        return if value.nil?
+
+        value = constant(value) if value.is_a?(String)
+        return MXC.new(value, backend: backend_name(backend)) if mxc?(value)
+
+        instance = value.is_a?(Class) ? value.new : value
+        return instance if instance.respond_to?(:run) && instance.respond_to?(:supported?)
+
+        raise ConfigurationError,
+              "A sandbox is an MXC::Sandbox class or an object answering supported? and run, got #{value.inspect}"
+      end
+
+      # Returns the name the model uses for +value+: its class name without
+      # a +Sandbox+ suffix, in snake case, so WorkspaceSandbox is
+      # +workspace+.
+      #
+      # Raises ArgumentError when the class has no name.
+      def name_for(value) # :nodoc:
+        base = class_name(value).to_s.split('::').last.to_s.delete_suffix('Sandbox')
+        if base.empty?
+          raise ArgumentError, "Name the sandbox #{value.inspect} with a Hash: escalate_to: { name => sandbox }"
+        end
+
+        base.gsub(/([A-Z\d])([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+
+      # Raises ConfigurationError unless +sandbox+ can run on this machine.
+      def verify(sandbox) # :nodoc:
+        return if sandbox.nil? || sandbox.supported?
+
+        reason = sandbox.reason if sandbox.respond_to?(:reason)
+        raise ConfigurationError, ['The configured sandbox cannot run on this machine.', reason].compact.join(' ')
+      end
+
+      # Returns the class a String names. Raises ConfigurationError when
+      # nothing by that name is defined.
+      def constant(name) # :nodoc:
+        Object.const_get(name)
+      rescue NameError
+        raise ConfigurationError, "The sandbox #{name} is not defined"
+      end
+
+      private
+
+      def backend_name(backend)
+        name = backend.respond_to?(:to_sym) ? backend.to_sym : backend
+        return name if BACKENDS.include?(name)
+
+        raise ConfigurationError,
+              "config.sandbox_backend is #{BACKENDS.map(&:inspect).join(' or ')}, got #{backend.inspect}"
+      end
+
+      def class_name(value)
+        return value if value.is_a?(String)
+
+        (value.is_a?(Class) ? value : value.class).name
+      end
+
+      def mxc?(value)
+        defined?(::MXC::Sandbox) && (value.is_a?(::MXC::Sandbox) || (value.is_a?(Class) && value <= ::MXC::Sandbox))
+      end
+    end
+  end
+end

data/lib/ruby_llm/search_results.rb

@@ -13,12 +13,16 @@ module RubyLLM
   #     )
   #   end
   #
-  # Cited passages come back on the response as Message#citations.
+  # Cited passages come back on the response as Message#citations. Give a
+  # result a +:source_id+ String, such as a Global ID, to identify it to
+  # your app; its citations return it as Citation#source_id.
+  #
+  #   RubyLLM::SearchResults.new(title: doc.name, source_id: doc.to_global_id.to_s, text: doc.body)
   class SearchResults
     KEY = 'search_results' # :nodoc:
 
     # The normalized results, as an array of hashes with +:title+, +:text+,
-    # and optional +:url+ keys.
+    # and optional +:url+ and +:source_id+ keys.
     attr_reader :results
 
     # Returns a new SearchResults built from one or more result hashes, or
@@ -27,7 +31,8 @@ module RubyLLM
     #   RubyLLM::SearchResults.new(title: 'Q4 Report', url: report_url, text: report_text)
     #   RubyLLM::SearchResults.new({ title: 'A', text: '...' }, { title: 'B', text: '...' })
     #
-    # Each result is reduced to its +:title+, +:url+, and +:text+ entries.
+    # Each result is reduced to its +:title+, +:url+, +:source_id+, and
+    # +:text+ entries.
     # Raises ArgumentError if no results are given or a result is missing
     # +:title+ or +:text+.
     def initialize(*results, **result)
@@ -62,7 +67,7 @@ module RubyLLM
       entry = Support::Utils.deep_symbolize_keys(entry.to_h)
       raise ArgumentError, 'Search results require :title and :text' unless entry[:title] && entry[:text]
 
-      entry.slice(:title, :url, :text)
+      entry.slice(:title, :url, :source_id, :text)
     end
   end
 end

data/lib/ruby_llm/server_tool_call.rb

@@ -46,7 +46,7 @@ module RubyLLM
     attr_reader :search_suggestions
 
     def self.from_h(data) # :nodoc:
-      data = Support::Utils.deep_symbolize_keys(data)
+      data = data.transform_keys(&:to_sym)
       new(type: data[:type], name: data[:name], id: data[:id], input: data[:input],
           result: data[:result], raw: data[:raw])
     end