ruby_llm 2.1.1 → 2.2.0

data/lib/ruby_llm/file_store.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'monitor'
+require 'stringio'
+
+module RubyLLM
+  # A FileStore keeps a chat's files: what people attach, what tools
+  # return, long tool results, and what code writes. Chat#with_file_store gives
+  # a chat one, and the model works with it through tools that list, read,
+  # search, write, and edit its files, so a file reaches the model only
+  # when the model asks for it.
+  #
+  #   chat = RubyLLM.chat.with_file_store
+  #   chat.ask "Which clauses changed?", with: ["contract-v1.pdf", "contract-v2.pdf"]
+  #   chat.file_store.list.map(&:path) # => ["contract-v1.pdf", "contract-v2.pdf"]
+  #
+  # RubyLLM ships FileStore::Memory, the default, and FileStore::Directory,
+  # which keeps the files in a folder. The Rails integration keeps a
+  # persisted chat's files in Active Storage.
+  #
+  #   chat.with_file_store("tmp/work")
+  #
+  # Write your own store by subclassing FileStore and implementing #list,
+  # #[], #read, #write, and #delete. RubyLLM only ever passes them paths
+  # FileStore.path accepts: relative, with forward slashes, and without
+  # empty, <tt>.</tt>, or <tt>..</tt> parts.
+  #
+  #   class BucketStore < RubyLLM::FileStore
+  #     def initialize(bucket, prefix)
+  #       super()
+  #       @bucket = bucket
+  #       @prefix = prefix
+  #     end
+  #
+  #     def list(prefix = nil) = ...
+  #     def [](path) = ...
+  #     def read(path) = ...
+  #     def write(path, content, content_type: nil) = ...
+  #     def delete(path) = ...
+  #   end
+  #
+  # The model must read a file before its tools change it, and a file that
+  # changed since it read it must be read again. The store remembers what
+  # the model read, and #with_lock keeps two changes to the files from
+  # interleaving. Override #with_lock in a store that several processes
+  # share.
+  class FileStore
+    include Enumerable
+
+    # Raised by #delete for a path that is a folder.
+    class FolderError < ArgumentError; end # :nodoc:
+
+    # Converted texts each store keeps in memory, by default.
+    CACHED_TEXTS = 100
+
+    UNSAFE_CHARACTERS = /[\x00-\x1f\x7f\\:*?"<>|]/
+    DIGEST_CHUNK = 1024 * 1024
+    private_constant :UNSAFE_CHARACTERS, :DIGEST_CHUNK
+
+    class << self
+      # Returns +name+ as a path inside a store: relative, with forward
+      # slashes, and with a leading <tt>./</tt> or <tt>/</tt> and repeated
+      # slashes removed.
+      #
+      #   RubyLLM::FileStore.path("./reports//q3.pdf") # => "reports/q3.pdf"
+      #
+      # Raises ArgumentError for an empty path or one with <tt>.</tt> or
+      # <tt>..</tt> parts.
+      def path(name)
+        parts = name.to_s.tr('\\', '/').split('/').reject(&:empty?)
+        parts.shift while parts.first == '.'
+        if parts.empty? || parts.intersect?(%w[. ..]) || parts.any? { |part| part.match?(/[\x00-\x1f]/) }
+          raise ArgumentError, "#{name.inspect} is not a path inside the chat's files"
+        end
+
+        parts.join('/')
+      end
+
+      # Returns whether +path+ is inside the folder +prefix+, or is it.
+      # Every path is inside a +nil+ or empty prefix.
+      def inside?(path, prefix) # :nodoc:
+        return true if prefix.to_s.empty?
+
+        folder = path(prefix)
+        path == folder || path.start_with?("#{folder}/")
+      end
+
+      # Returns whether +path+ matches the glob +pattern+. A pattern
+      # without a slash matches the file name in any folder; one with a
+      # slash matches the whole path, or the path inside the folder
+      # +inside+. <tt>**</tt> matches any number of folders, a trailing
+      # <tt>/**</tt> everything under a folder, and <tt>{a,b}</tt> either.
+      def match?(path, pattern, inside: nil) # :nodoc:
+        pattern = pattern.to_s.delete_prefix('./').delete_prefix('/')
+        flags = File::FNM_PATHNAME | File::FNM_EXTGLOB
+        return File.fnmatch?(pattern, File.basename(path), flags) unless pattern.include?('/')
+
+        pattern = "#{pattern}/*" if pattern.end_with?('/**')
+        candidates = [path]
+        candidates << path.delete_prefix("#{inside}/") unless inside.to_s.empty?
+        candidates.any? { |candidate| File.fnmatch?(pattern, candidate, flags) }
+      end
+
+      # Returns a safe file name for an attachment called +name+.
+      def filename(name) # :nodoc:
+        base = File.basename(name.to_s.tr('\\', '/')).gsub(UNSAFE_CHARACTERS, '_').strip.sub(/\A\.+/, '')
+        base.empty? ? 'file' : base
+      end
+
+      # Returns the SHA-256 of +content+, a String or an IO read to its
+      # end in chunks, in hex.
+      def digest(content) # :nodoc:
+        return Digest::SHA256.hexdigest(content) unless content.respond_to?(:read)
+
+        digest = Digest::SHA256.new
+        buffer = String.new(capacity: DIGEST_CHUNK)
+        digest << buffer while content.read(DIGEST_CHUNK, buffer)
+        digest.hexdigest
+      end
+
+      # Returns the MIME type of +content+, a String or an IO that can
+      # rewind, written to +path+. An IO is sniffed from its start and
+      # left there.
+      def content_type_for(path, content) # :nodoc:
+        type = Files::MimeType.for(name: File.basename(path))
+        return type unless type == 'application/octet-stream'
+
+        Files::MimeType.for(content.respond_to?(:read) ? content : StringIO.new(content))
+      end
+
+      # Returns the bytes of +content+, a String or an IO.
+      def bytes(content) # :nodoc:
+        content = content.read if content.respond_to?(:read)
+        content.to_s.b
+      end
+    end
+
+    def initialize # :nodoc:
+      @texts = {}
+      @texts_lock = Mutex.new
+      @reads = {}
+      @reads_lock = Mutex.new
+      @store_lock = Monitor.new
+    end
+
+    # Returns the files inside the folder +prefix+, or every file, as
+    # StoredFile objects sorted by path.
+    #
+    #   chat.file_store.list("reports")
+    def list(prefix = nil)
+      raise NotImplementedError, "#{self.class} must implement list"
+    end
+
+    # Returns the StoredFile at +path+, or +nil+ when there is none.
+    #
+    #   chat.file_store["notes/plan.md"] # => #<RubyLLM::StoredFile path: "notes/plan.md", ...>
+    def [](path)
+      raise NotImplementedError, "#{self.class} must implement []"
+    end
+
+    # Returns the StoredFile at +path+. Raises FileNotFoundError when there
+    # is none.
+    #
+    #   chat.file_store.find("notes/plan.md")
+    def find(path)
+      self[path] || raise(FileNotFoundError, "No file at #{FileStore.path(path)}")
+    end
+
+    # Returns the content of the file at +path+ as a binary String.
+    # Raises FileNotFoundError when there is none.
+    def read(path)
+      raise NotImplementedError, "#{self.class} must implement read"
+    end
+
+    # Writes +content+, a String or an IO, to +path+, replacing any file
+    # there, and returns its StoredFile. The content type is detected from
+    # the path and the content unless given.
+    #
+    #   chat.file_store.write("notes/plan.md", "# Plan")
+    def write(path, content, content_type: nil)
+      raise NotImplementedError, "#{self.class} must implement write"
+    end
+
+    # Deletes the file at +path+ and returns its StoredFile, or +nil+ when
+    # there was none. Raises ArgumentError when +path+ is a folder.
+    #
+    #   chat.file_store.delete("notes/plan.md")
+    def delete(path)
+      raise NotImplementedError, "#{self.class} must implement delete"
+    end
+
+    # Deletes everything inside the folder +path+ and returns the deleted
+    # StoredFile objects, sorted by path. Raises ArgumentError when +path+
+    # is a file.
+    #
+    #   chat.file_store.delete_folder("reports") # => [#<RubyLLM::StoredFile path: "reports/q3.pdf", ...>]
+    def delete_folder(path)
+      path = FileStore.path(path)
+      refuse_file(path) if self[path]
+
+      list(path).filter_map { |file| delete(file.path) }
+    end
+
+    # Returns the folder on disk that holds the files, or +nil+. A store
+    # with one has code execution run in that folder, reading and writing
+    # the files in place; a store without one has each run read the
+    # attachments in +attachments/+ and copy in the files it names.
+    # FileStore::Directory returns its root.
+    def local_root # :nodoc:
+      nil
+    end
+
+    # Yields each StoredFile, as #list returns them.
+    def each(&)
+      list.each(&)
+    end
+
+    # Returns whether there is a file at +path+.
+    def exist?(path)
+      !self[path].nil?
+    end
+
+    # Returns the digest of the content the model last read at +path+, or
+    # +nil+ when it has not read it. The file tools compare it with the
+    # file's digest before they change the file.
+    def read_digest(path) # :nodoc:
+      @reads_lock.synchronize { @reads[FileStore.path(path)] }
+    end
+
+    # Remembers that the model read +digest+, a digest of the content, at
+    # +path+, in memory.
+    def record_read(path, digest) # :nodoc:
+      @reads_lock.synchronize { @reads[FileStore.path(path)] = digest }
+    end
+
+    # Runs the block with the store locked and returns its value, so a tool
+    # that reads a file and writes it back sees no other change in
+    # between. It is reentrant. Stores lock within this process unless
+    # they override it.
+    def with_lock(&)
+      @store_lock.synchronize(&)
+    end
+
+    # Returns the text of the file at +path+: its content when it is text,
+    # or what a converter makes of it, such as the text OCR reads from a
+    # PDF. Returns +nil+ when no converter can read the file.
+    # Conversions are kept, so each version of a file is converted once.
+    # Raises FileNotFoundError when there is no file at +path+.
+    #
+    #   chat.file_store.text("contract.pdf") # => "## Page 1\n\nThis agreement..."
+    #
+    # See Configuration#file_converters for adding converters.
+    def text(path, config: nil)
+      file = find(path)
+      cached = cached_text(file)
+      return cached if cached
+
+      Converters.convert(attachment(file.path, file:), config: config || RubyLLM.config).tap do |text|
+        cache_text(file, text) if text
+      end
+    end
+
+    # Returns the file at +path+ as an Attachment, to send it to a model.
+    # Raises FileNotFoundError when there is none.
+    def attachment(path, file: nil)
+      file ||= find(path)
+      Attachment.new(StringIO.new(read(file.path)), filename: file.filename)
+    end
+
+    # Returns the converted text kept for +file+, or +nil+, from memory.
+    def cached_text(file) # :nodoc:
+      @texts_lock.synchronize { @texts[text_key(file)] }
+    end
+
+    # Keeps +text+ as the conversion of +file+, in memory.
+    def cache_text(file, text) # :nodoc:
+      @texts_lock.synchronize do
+        @texts.delete(@texts.keys.first) if @texts.size >= CACHED_TEXTS
+        @texts[text_key(file)] = text
+      end
+    end
+
+    # Writes +attachment+ under its file name and returns its StoredFile,
+    # yielding it when it is new. A file already there with the same
+    # content is reused; one with other content keeps its place, and the
+    # attachment gets a numbered name beside it, such as
+    # <tt>report-2.pdf</tt>.
+    def store_attachment(attachment) # :nodoc:
+      content = attachment.content.to_s.b
+      digest = self.class.digest(content)
+      candidates(self.class.filename(attachment.filename)).each do |path|
+        existing = self[path]
+        return existing if existing && same_content?(existing, content, digest)
+        next if existing || folder?(path)
+
+        file = write_attachment(path, attachment, content)
+        yield file if block_given?
+        return file
+      end
+    end
+
+    private
+
+    def folder?(_path)
+      false
+    end
+
+    def refuse_folder(path)
+      raise FolderError, "#{path} is a folder: delete it with delete_folder"
+    end
+
+    def refuse_file(path)
+      raise ArgumentError, "#{path} is a file: delete it with delete"
+    end
+
+    def write_attachment(path, attachment, content)
+      write(path, content, content_type: attachment.mime_type)
+    end
+
+    def candidates(name)
+      extension = File.extname(name)
+      base = name.delete_suffix(extension)
+      Enumerator.new do |paths|
+        paths << name
+        (2..).each { |number| paths << "#{base}-#{number}#{extension}" }
+      end
+    end
+
+    def same_content?(file, content, digest)
+      file.digest ? file.digest == digest : read(file.path).b == content
+    end
+
+    def text_key(file)
+      file.digest || [file.path, file.byte_size, file.updated_at]
+    end
+  end
+end

data/lib/ruby_llm/files/saving.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Files
+    # The #save every complete downloadable result shares. Includers supply
+    # #to_blob and document #save in their own terms.
+    module Saving # :nodoc:
+      def save(path)
+        File.binwrite(File.expand_path(path), to_blob)
+        path
+      end
+    end
+  end
+end

data/lib/ruby_llm/image.rb

@@ -11,7 +11,9 @@ module RubyLLM
   #
   class Image
     include Support::Inspectable
+    include Files::Saving
     include Accounting::Usage::Result
+    include Accounting::Usage::ModelInfo
 
     # The URL of the hosted image, for providers that return one, or +nil+.
     attr_reader :url
@@ -44,7 +46,7 @@ module RubyLLM
     # +context:+ supplies a Context whose configuration replaces the
     # global one. +metadata:+ is included in the instrumentation payload.
     # +owner:+ attributes the usage to a record, such as a user, and wins
-    # over RubyLLM.with_usage_owner.
+    # over RubyLLM.with_owner.
     #
     #   image = RubyLLM.paint("A small watercolor robot", model: "gpt-image-2")
     #
@@ -57,8 +59,19 @@ module RubyLLM
     #     with: "logo.png"
     #   )
     #
-    # Providers that cannot generate several images in one request ignore
-    # +count:+ and return a single Image.
+    # Providers that cannot generate several images in one request raise
+    # ArgumentError when +count:+ is above 1.
+    #
+    # +fallbacks:+ lists models to try, in order, when the request fails
+    # with one of the errors Chat#with_fallbacks moves on from by default,
+    # such as a rate limit or an overloaded provider. Each is a model id or
+    # a Model, and gets the same request. A fallback whose model can't be
+    # found is skipped. Each attempt has its own +image.ruby_llm+ event
+    # and usage entry.
+    #
+    #   RubyLLM.paint("A small watercolor robot", model: "gpt-image-2",
+    #                 fallbacks: ["gemini-3.1-flash-image"])
+    #
     def self.paint(prompt,
                    model: nil,
                    provider: nil,
@@ -70,39 +83,54 @@ module RubyLLM
                    mask: nil,
                    provider_options: {},
                    metadata: nil,
-                   owner: nil)
-      config = context&.config || RubyLLM.config
-      model ||= config.default_image_model
-      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,
-        prompt: prompt,
-        size: size,
-        count: count,
-        provider_options: provider_options,
-        metadata: metadata,
-        tokens: empty_tokens,
-        cost: Cost.new(tokens: empty_tokens, model:, category: :images)
-      }
+                   owner: nil,
+                   fallbacks: [])
+      queue = Array(fallbacks).flatten.compact.map { |fallback| Fallback.build(fallback) }
+      operation = painting(model, provider:, assume_model_exists:, context:, owner:)
+      begin
+        with_fallback_ready(queue) do
+          operation.run(prompt:, size:, count:, provider_options:, metadata:) do |provider_instance, image_model|
+            provider_instance.paint(prompt, model: image_model, size:, count:, with:, mask:, provider_options:)
+          end
+        end
+      rescue StandardError => e
+        raise unless Fallback.error?(e, Fallback::DEFAULT_ERRORS)
 
-      RubyLLM.instrument('image.ruby_llm', payload, config: config) do |event|
-        result = Accounting::Usage.owned_by(owner) do
-          provider_instance.paint(prompt, model:, size:, count:, with:, mask:, provider_options:)
+        _, operation = Fallback.next_usable(queue) do |fallback|
+          painting(fallback.id, provider: fallback.provider, context:, owner:, resolved: fallback.model)
         end
-        images = Support::Utils.to_safe_array(result)
-        event[:result] = result
-        event[:response_model] = images.first&.model
-        event[:tokens] = Tokens.aggregate(images.map(&:tokens))
-        event[:cost] = Cost.aggregate(images.map(&:cost))
-        result
+        raise e unless operation
+
+        retry
       end
     end
 
+    # While a fallback is left, a timeout, a failed connection, or a long
+    # retry wait moves on to it instead of retrying the same model, as
+    # Chat#with_fallbacks does. Every error the transport retries is one
+    # paint falls back on, so the fallback takes each of them.
+    def self.with_fallback_ready(queue, &)
+      return yield if queue.empty?
+
+      Transport::Connection.with_fallback_ready(->(_error) { true }, &)
+    end
+    private_class_method :with_fallback_ready
+
+    def self.painting(model, provider:, context:, owner:, assume_model_exists: false, resolved: nil) # :nodoc:
+      Accounting::Operation.new(
+        'image', model, default: :default_image_model, category: :images, provider:, assume_model_exists:, context:,
+                        owner:, resolved:,
+                        report: lambda { |event, result|
+                          images = Support::Utils.to_safe_array(result)
+                          event[:result] = result
+                          event[:response_model] = images.first&.model
+                          event[:tokens] = Tokens.aggregate(images.map(&:tokens))
+                          event[:cost] = Cost.aggregate(images.map(&:cost))
+                        }
+      )
+    end
+    private_class_method :painting
+
     # :stopdoc:
 
     # Set by the protocol that generated the image, so a Context's
@@ -137,20 +165,19 @@ module RubyLLM
       if base64?
         Base64.decode64 @data
       else
-        response = Transport::Connection.basic(config).get @url
-        response.body
+        Transport::Connection.download(@url, config)
       end
     end
 
+    ##
+    # :method: save
+    # :call-seq:
+    #   save(path)
+    #
     # Writes the binary image to +path+, expanding it first. Returns
     # +path+ as given.
     #
     #   image.save("steampunk_owl.png")
-    #
-    def save(path)
-      File.binwrite(File.expand_path(path), to_blob)
-      path
-    end
 
     # Returns a Tokens with usage across every provider attempt.
     # Its fields are +nil+ when none were reported.
@@ -164,6 +191,7 @@ module RubyLLM
       @tokens ||= Tokens.new(
         input: raw_usage['input_tokens'],
         output: raw_usage['output_tokens'],
+        cache_read: raw_usage['cache_read_tokens'],
         reported_cost: raw_usage['cost']
       )
     end
@@ -179,17 +207,11 @@ module RubyLLM
       Cost.new(tokens:, model: model_info, category: :images, input_details: input_tokens_details)
     end
 
-    attr_writer :model_info # :nodoc:
-
     # Returns the image's Model from its provider's registry, falling back
     # to the requested model when the response ID is unknown. Images built
     # without a request look up #model, or return +nil+ if unknown.
     def model_info
-      return unless model
-
-      @model_info ||= RubyLLM.models.find(model)
-    rescue ModelNotFoundError
-      nil
+      super if model
     end
 
     private

data/lib/ruby_llm/input_required_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Raised when a tool asks a person something and nothing can pause the
+  # call for the answer: Tool#ask outside a chat, or an MCP server's
+  # question that no MCP.before_input_request callback answered when you
+  # call the tool yourself (MCP::InputRequiredError). Its message includes
+  # what was asked, and #requests has the Question objects. In a chat, the
+  # tool call pauses instead, and Chat#pending_questions returns them.
+  class InputRequiredError < Error
+    def initialize(source, input) # :nodoc:
+      @input = input
+      asks = requests.map { |question| [question.message, question.url].compact.join(' ') }
+      super("#{source} needs input from the user: #{asks.join('; ')}")
+    end
+
+    # The unanswered Question objects.
+    def requests
+      @input['requests'].reject(&:answered?)
+    end
+
+    # Returns everything needed to answer the questions later and resume
+    # the call, as a Hash that serializes to JSON.
+    def to_h # :nodoc:
+      @input.merge('requests' => @input['requests'].map(&:to_h)).compact
+    end
+  end
+end

data/lib/ruby_llm/judge/builder.rb

@@ -2,7 +2,7 @@
 
 module RubyLLM
   class Judge
-    class Builder # :nodoc:
+    class Builder < BasicObject # :nodoc:
       def self.resolve(value, scope:)
         return value unless value.is_a?(::Proc)
 
@@ -43,6 +43,11 @@ module RubyLLM
 
       private
 
+      def proc(&block)
+        block
+      end
+      alias lambda proc
+
       def runtime_input?(name, values, block)
         values.empty? && !block && @scope.respond_to?(name)
       end

data/lib/ruby_llm/judge.rb

@@ -136,7 +136,7 @@ module RubyLLM
     # Judges the supplied input and returns a Judgment. Accepts model and
     # provider overrides, images as +with:+, an isolated +context:+,
     # +provider_options:+, instrumentation +metadata:+, and a usage +owner:+,
-    # as RubyLLM.with_usage_owner describes. Additional
+    # as RubyLLM.with_owner describes. Additional
     # +questions:+ are a Hash keyed by question name, with +type:+,
     # +instructions:+, and +criteria:+ (probability), +options:+ (choice), or
     # +levels:+ (score). The block supplies input only. Input may be omitted

data/lib/ruby_llm/judgment.rb

@@ -76,30 +76,12 @@ module RubyLLM
       validate_input!(input, attachments)
       raise ArgumentError, 'A judgment requires a model' unless model || config.default_judgment_model
 
-      model, provider_instance = Models.resolve(model, provider:, assume_model_exists:, config:, operation: :judge,
-                                                       default_model: config.default_judgment_model)
-      empty_tokens = Tokens.new
-      payload = {
-        provider: provider_instance.slug,
-        provider_class: provider_instance.name,
-        model: model.id,
-        model_info: model,
-        question_count: questions.size,
-        attachment_count: attachments.size,
-        provider_options:,
-        metadata:,
-        tokens: empty_tokens,
-        cost: Cost.new(tokens: empty_tokens, model:)
-      }
-
-      RubyLLM.instrument('judgment.ruby_llm', payload, config:) do |event|
-        result = Accounting::Usage.owned_by(owner) do
-          provider_instance.judge(input, questions:, model:, with: attachments, provider_options:)
-        end
-        event[:result] = result
-        event[:tokens] = result.tokens
-        event[:cost] = result.cost
-        result
+      Accounting::Operation.new(
+        'judgment', model, operation: :judge, default: :default_judgment_model, provider:, assume_model_exists:,
+                           context:, owner:
+      ).run(question_count: questions.size, attachment_count: attachments.size, provider_options:,
+            metadata:) do |provider_instance, model|
+        provider_instance.judge(input, questions:, model:, with: attachments, provider_options:)
       end
     end