ruby_llm 2.2.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e784b5ab43c18ac17675ffa3e46c802934a9f8eaa4ef733bd1e7c450c462fff5
-  data.tar.gz: 69d10ad8492781735ce7b50d56476bd39d3cf405e9218adb819e735712144761
+  metadata.gz: 55db20760e71db4c87a6f71b21ac7eba6b1651838dc6d897397d7d61e8283e14
+  data.tar.gz: d624ca6c55d349a74876d2ac12609484b7e8a7d28c08f7133e0c827550fd98cd
 SHA512:
-  metadata.gz: 38f20b77e3e1553f8b3962fe2da6a11c39ea339363447b652387a832637ccf0b8316d848a895296e157d869d22cc661ce231a891369aa1aee3f33cc06fb863f0
-  data.tar.gz: 1403357da777eacf6fce2d449de634e16fd848f93f8e36b9c06632fe60d1b638afe7856456ccfb1e948b5d443980c8a442f586e6f21af7cf5775dd485cdabe47
+  metadata.gz: 4ee13ff16e87c7ef85d5c9bea076b7c01dcaf6d8e7d422a632b403e31284c5c4400bd0c7d255fde5ad609e6e42cf57b5e15db514adba86d18bbcd07a41fbb7dc
+  data.tar.gz: 9988f48c57b5c8603dce67d9ddc098a3be387a9fd478756ac32037c0b8a4a3d7d5929aa60a7c1eba761677e93df980abc0fc6dfc279da9ee1e8a1f4018fa6bfa

data/README.md

@@ -179,7 +179,7 @@ Start your Rails server and visit `http://localhost:3000/chats` to try the chat
 
 ## Start with one line. Add files, tools, and agents
 
-These examples use **2.2.0**. Follow [Getting Started](https://rubyllm.com/getting-started/) to install it and configure the providers you want to try. For 1.x, use the [1.x docs](https://rubyllm.com/v1/).
+These examples use **2.2.1**. Follow [Getting Started](https://rubyllm.com/getting-started/) to install it and configure the providers you want to try. For 1.x, use the [1.x docs](https://rubyllm.com/v1/).
 
 ```ruby
 # Just ask
@@ -309,7 +309,7 @@ response.parsed
 Install RubyLLM 2.2:
 
 ```bash
-bundle add ruby_llm --version 2.2.0
+bundle add ruby_llm --version 2.2.1
 ```
 
 Configure a provider in your script, or in `config/initializers/ruby_llm.rb` in Rails:

data/lib/generators/ruby_llm/chat_ui/templates/tailwind/views/questions/_question.html.erb.tt

@@ -66,7 +66,8 @@
                   <%%= form.select "answer[#{field.name}]", field.choices, { selected: field.default, include_blank: !field.required? && !list },
                     id: field_id, multiple: list, required: list && field.required?, class: "block shadow-sm rounded-md border border-gray-400 px-3 py-2 mt-1 w-full" %>
                 <%% else %>
-                  <%%= form.text_field "answer[#{field.name}]", value: field.default, required: field.required?, id: field_id,
+                  <%%= form.text_field "answer[#{field.name}]#{"[]" if list}", value: (field.default unless list),
+                    required: field.required? && !(list && field.default), id: field_id,
                     type: steps.key?(field.type) ? "number" : "text", step: steps[field.type],
                     class: "block shadow-sm rounded-md border border-gray-400 px-3 py-2 mt-1 w-full" %>
                 <%% end %>

data/lib/generators/ruby_llm/chat_ui/templates/views/questions/_question.html.erb.tt

@@ -50,7 +50,8 @@
                   <%%= form.select "answer[#{field.name}]", field.choices, { selected: field.default, include_blank: !field.required? && !list },
                     id: field_id, multiple: list, required: list && field.required? %>
                 <%% else %>
-                  <%%= form.text_field "answer[#{field.name}]", value: field.default, required: field.required?, id: field_id,
+                  <%%= form.text_field "answer[#{field.name}]#{"[]" if list}", value: (field.default unless list),
+                    required: field.required? && !(list && field.default), id: field_id,
                     type: steps.key?(field.type) ? "number" : "text", step: steps[field.type] %>
                 <%% end %>
               <%% end %>

data/lib/ruby_llm/active_record/chat_approvals.rb

@@ -54,6 +54,9 @@ module RubyLLM
 
       def record_tool_call_decision(tool_call, decision)
         record = tool_call_record(tool_call)
+        if decision == 'remembered' && record.result_id.nil?
+          RubyLLM::Chat::ToolCallState.remembered_identity(record.to_llm)
+        end
         decide_persisted_tool_call(record, decision)
         record
       end

data/lib/ruby_llm/active_record/chat_methods.rb

@@ -129,7 +129,7 @@ module RubyLLM
       #
       def approve(tool_call, remember: false)
         record = tool_call_record(RubyLLM::Question.decided_call(tool_call, 'answer'))
-        to_llm.approve(record.to_llm, remember:) if record.result_id.nil?
+        @chat&.approve(record.to_llm, remember:) if record.result_id.nil?
         record_tool_call_decision(record, remember ? 'remembered' : 'approved')
         self
       end
@@ -839,15 +839,11 @@ module RubyLLM
       # Raises PendingToolCallsError while the last response has tool calls
       # waiting for their results and no run holds the chat.
       def ask_later(message = nil, with: nil)
-        return tap { queue(message, with:) } if running? && !message.is_a?(RubyLLM::MCP::Prompt)
-
-        to_llm.raise_if_pending_tool_calls!
-        to_llm.raise_if_prompt_attachments!(message, with)
-        to_llm.take_queued_messages
-        if message.is_a?(RubyLLM::MCP::Prompt)
-          message.messages.each { |prompt_message| add_message(prompt_message) }
-        else
-          add_message(role: :user, content: message, attachments: with)
+        staging = ChatQueue.new(self)
+        if !run_claims? || message.is_a?(RubyLLM::MCP::Prompt)
+          staging.stage(message, attachments: with)
+        elsif running? || !stage_while_idle { staging.stage(message, attachments: with) }
+          queue(message, with:)
         end
         self
       end
@@ -898,11 +894,13 @@ module RubyLLM
 
       # Runs the completion loop on the underlying chat, persisting each
       # message, and returns the latest RubyLLM::Message. Pauses while a call
-      # waits on a person (see #pending_questions). When the API call fails,
-      # destroys the empty assistant message and any orphaned tool results,
-      # then re-raises the error. When the block raises, destroys the empty
-      # assistant message and re-raises. Tool calls paused on a task or a
-      # question stay, so the next #complete picks them up.
+      # waits on a person (see #pending_questions). When the API call or a
+      # tool fails, destroys the empty assistant message, closes the tool
+      # calls of the round left without a result as unfinished, and
+      # re-raises the error. A tool call that finished keeps its result.
+      # When the block raises, destroys the empty assistant message and
+      # re-raises. Tool calls paused on a task or a question stay, so the
+      # next #complete picks them up.
       #
       # Only one process runs a chat at a time. While another process is
       # #running? it, returns the latest message without calling the model
@@ -1125,7 +1123,7 @@ module RubyLLM
       def cleanup_after_failure(error)
         reason = error.is_a?(RubyLLM::CancelledError) ? 'chat cancelled' : 'API call failed'
         cleanup_failed_messages(reason:) if blank_placeholder?
-        cleanup_orphaned_tool_results
+        @chat&.close_unfinished_tool_calls
         resync_messages if @chat
       end
 
@@ -1138,26 +1136,6 @@ module RubyLLM
         @message.destroy
       end
 
-      def cleanup_orphaned_tool_results # rubocop:disable Metrics/PerceivedComplexity
-        messages_association.reload
-        last = eager_load_messages.last
-
-        return unless last&.tool_call? || last&.tool_result?
-
-        if last.tool_call?
-          last.destroy unless last.ruby_llm_tool_calls.any?(&:paused?)
-        else
-          parent = last.ruby_llm_parent_tool_call
-          tool_call_message = parent.message
-          calls = tool_call_message.ruby_llm_tool_calls
-
-          if calls.any? { |call| call.result.nil? } && calls.none?(&:paused?)
-            calls.filter_map(&:result).each(&:destroy)
-            tool_call_message.destroy
-          end
-        end
-      end
-
       def eager_load_messages
         assoc = messages_association
         messages = assoc.to_a

data/lib/ruby_llm/active_record/chat_queue.rb

@@ -18,6 +18,18 @@ module RubyLLM
         @chat = chat
       end
 
+      def stage(message, attachments:)
+        chat = @chat.to_llm
+        chat.raise_if_pending_tool_calls!
+        chat.raise_if_prompt_attachments!(message, attachments)
+        chat.take_queued_messages
+        if message.is_a?(RubyLLM::MCP::Prompt)
+          message.messages.each { |prompt_message| @chat.add_message(prompt_message) }
+        else
+          @chat.add_message(role: :user, content: message, attachments:)
+        end
+      end
+
       def push(content:, attachments:, steer:, sender:)
         QueuedMessage.transaction do
           @chat.forget_stale_cancellation
@@ -54,7 +66,8 @@ module RubyLLM
 
       def take_one(queued)
         taken = nil
-        QueuedMessage.transaction do
+        QueuedMessage.transaction(requires_new: true) do
+          @chat.forget_stale_cancellation
           next unless QueuedMessage.where(id: queued.id).delete_all == 1
 
           taken = [@chat.to_llm.run_around_join(queued) { |**attributes| join(queued, attributes) }]

data/lib/ruby_llm/active_record/run_claims.rb

@@ -175,6 +175,21 @@ module RubyLLM
         self[:cancelled] = false if has_attribute?(:cancelled)
       end
 
+      # Hold the same row a run claims without replacing its token, so a
+      # failed submission leaves an interrupted run discoverable.
+      def stage_while_idle
+        transaction(requires_new: true) do
+          next false unless unclaimed(chat_row, Time.current).update_all('claim_token = claim_token') == 1
+
+          resync_messages if @chat && run_finished_elsewhere?
+          yield
+          true
+        end
+      rescue StandardError
+        resync_messages if @chat
+        raise
+      end
+
       def exclusively(busy, &)
         return yield if @run_claim_token
 
@@ -539,17 +554,30 @@ module RubyLLM
       end
 
       # Renewing inside the transaction holds the chat row until the result
-      # commits, so no other process can take the chat over in between.
+      # commits, so no other process can take the chat over in between. A
+      # message that touches its chat touches it after the commit: on
+      # Postgres, a second write to the row the claim renewed rechecks every
+      # foreign key on it and locks each row the chat references until the
+      # commit, which can deadlock with the application's own locks.
       def fenced_by_run_claim(&)
-        transaction do
+        reflection, columns = message_chat_touch if @run_claim_token
+        committed = transaction do
           renew_run_claim(force: true)
-          yield
+          reflection ? reflection.klass.no_touching(&) : yield
         end
+        @message.public_send(reflection.name)&.touch(*columns) if reflection && committed
+        committed
       rescue ClaimLost
         @message.destroy
         raise
       end
 
+      def message_chat_touch
+        reflection = @message.class.reflect_on_association(@message.class.chat_association_name)
+        touch = reflection&.options&.dig(:touch)
+        [reflection, touch == true ? [] : Array(touch)] if touch
+      end
+
       def tool_call_rows(tool_call_ids)
         RubyLLM::ActiveRecord::ToolCall.where(
           tool_call_id: tool_call_ids,

data/lib/ruby_llm/agent.rb

@@ -198,6 +198,7 @@ module RubyLLM
       # Called with no arguments, returns the configured options.
       #
       #   tool_options choice: :required, calls: :one
+      #   tool_options rounds: 25, calls: 50
       #
       def tool_options(**options, &block)
         return @tool_options || {} if options.empty? && !block_given?

data/lib/ruby_llm/aliases.json

@@ -279,6 +279,15 @@
     "openrouter": "google/gemini-4-carbon",
     "vertexai": "gemini-4-carbon"
   },
+  "gemini-4-hydrogen": {
+    "gemini": "gemini-4-hydrogen",
+    "openrouter": "google/gemini-4-hydrogen",
+    "vertexai": "gemini-4-hydrogen"
+  },
+  "gemini-decision-1": {
+    "gemini": "gemini-decision-1",
+    "openrouter": "google/gemini-decision-1"
+  },
   "gemini-embedding-001": {
     "gemini": "gemini-embedding-001",
     "openrouter": "google/gemini-embedding-001",

data/lib/ruby_llm/chat/file_references.rb

@@ -156,10 +156,7 @@ module RubyLLM
       end
 
       def extract(file)
-        return if file.text? || store.cached_text(file)
-
-        text = FileStore::Converters.convert(store.attachment(file.path, file:), config: @config.call, local: true)
-        store.cache_text(file, text) if text
+        store.text_with_digest(file, config: @config.call, local: true) unless file.text?
       rescue StandardError => e
         RubyLLM.logger.warn { "Could not extract the text of #{file.path}: #{e.class}" }
       end

data/lib/ruby_llm/chat/tool_call_state.rb

@@ -72,6 +72,17 @@ module RubyLLM
         decision(tool_call) == false
       end
 
+      # Returns the identity a remembered approval of +call+ applies to:
+      # later calls to the same tool. A run_code call outside a namespace
+      # is approved one call at a time.
+      def self.remembered_identity(call)
+        if call.name == CodeExecution.tool_name && call.namespace.nil?
+          raise ArgumentError, "#{call.name} calls are approved one at a time and cannot be remembered"
+        end
+
+        [call.namespace, call.name.to_s]
+      end
+
       def remember(identity)
         @remembered |= [identity]
       end

data/lib/ruby_llm/chat.rb

@@ -141,7 +141,8 @@ module RubyLLM
     # Returns the +choice+, +calls+, +concurrency+, and +rounds+ set with
     # #with_tool_options, with +nil+ for anything left at the default.
     def tool_options
-      { choice: tool_prefs[:choice], calls: tool_prefs[:calls], concurrency: concurrency, rounds: @tool_rounds }
+      { choice: tool_prefs[:choice], calls: tool_prefs[:calls] || @tool_call_cap, concurrency: concurrency,
+        rounds: @tool_rounds }
     end
 
     # Creates a chat with +model:+, or with the configured default model
@@ -625,7 +626,7 @@ module RubyLLM
     # Returns whether +tool_call+ requires approval and has no recorded
     # decision.
     def approval_pending?(tool_call) # :nodoc:
-      return false if tool_call.malformed_arguments? || skipped_result(tool_call)
+      return false if tool_call.malformed_arguments? || skipped_result(tool_call) || capped_tool_call?(tool_call)
       return approval_decision(nil, tool_call).nil? if tool_call.remote?
 
       tool = tool_for(tool_call)
@@ -847,7 +848,12 @@ module RubyLLM
     # Configures how the model uses the registered tools. +choice:+
     # constrains tool use to +:auto+, +:none+, +:required+, a tool name, or
     # a Tool class. +calls:+ limits how many tool calls one response may
-    # contain (+:many+ or +:one+). +concurrency:+ runs tool calls
+    # contain: +:one+ (or +1+) and +:many+ ask the provider, and a larger
+    # Integer runs at most that many of a response's calls to the chat's
+    # tools, in the response's order. Each call past it gets an error
+    # result straight away, without running or asking for approval, and
+    # emits one +tool_calls_capped.ruby_llm+ event per response. It is off
+    # by default. +concurrency:+ runs tool calls
     # concurrently: +true+ or +:threads+ for threads, +:fibers+ for fibers.
     # +rounds:+ limits how many model responses that ask for tools one
     # #complete may run, however many calls each holds. It is off by
@@ -860,14 +866,14 @@ module RubyLLM
     #
     #   chat.with_tools(Weather, Search).with_tool_options(choice: :required)
     #   chat.with_tool_options(calls: :one, concurrency: :threads)
-    #   chat.with_tool_options(rounds: 25)
+    #   chat.with_tool_options(rounds: 25, calls: 50)
     #   chat.with_tool_options(choice: nil)
     #
     def with_tool_options(**options)
       options.each do |option, value|
         case option
         when :choice then apply_tool_choice(value)
-        when :calls then @tool_prefs[:calls] = value.nil? ? nil : normalize_calls(value)
+        when :calls then apply_tool_calls(value)
         when :concurrency then apply_tool_concurrency(value)
         when :rounds then @tool_rounds = normalize_rounds(value)
         else raise ArgumentError, "Unknown tool option: #{option}. Valid options are: #{TOOL_OPTIONS.join(', ')}"
@@ -1757,6 +1763,27 @@ module RubyLLM
             'their tasks, before asking again.'
     end
 
+    # Closes the calls of the latest round that a raising tool left without
+    # a result, as unfinished, the way #cancel does, so the next request is
+    # valid and no finished call runs again. Unlike a cancel, the turn goes
+    # on: the next #complete asks the model, without forcing another tool
+    # call. A call that waits on a person or a task, or that another
+    # process runs, stays pending. A call that raised once its questions
+    # were answered is closed too, so the answers don't run it again.
+    def close_unfinished_tool_calls # :nodoc:
+      response = pending_tool_response
+      return unless response
+
+      @tool_prefs[:choice] = nil if forced_tool_choice?
+      pending_tool_calls(response).each do |tool_call|
+        next if running_elsewhere?(tool_call) || paused?(tool_call) || approval_pending?(tool_call)
+
+        record_tool_call_input(tool_call, nil)
+        run_callbacks(:before_message)
+        run_callbacks(:after_message, add_message(unfinished_result(tool_call)))
+      end
+    end
+
     private
 
     def agent_run_chat = self
@@ -2513,15 +2540,58 @@ module RubyLLM
     def execute_pending_tool_calls(response)
       raise_if_cancelled!
 
-      server_calls, local_calls = pending_tool_calls(response).to_h.partition { |_, call| call.remote? }.map(&:to_h)
+      pending = pending_tool_calls(response).except(*capped_tool_call_ids(response))
+      server_calls, local_calls = pending.to_h.partition { |_, call| call.remote? }.map(&:to_h)
       decisions = server_calls.transform_values { |tool_call| approval_decision(nil, tool_call) }.compact
       executable, denied = partition_pending_tool_calls(local_calls)
       executable = executable.reject { |_id, tool_call| exclusive_blocked?(tool_call, executable) }
       claimed = claim_tool_calls(executable, server_calls.slice(*decisions.keys).merge(denied))
       answer_claimed_tool_calls(claimed, server_calls, decisions, executable, denied)
+      answer_capped_tool_calls(response)
       @tool_prefs[:choice] = nil if forced_tool_choice?
     end
 
+    def answer_capped_tool_calls(response)
+      capped = unanswered_capped_tool_calls(response)
+      capped.each_value do |tool_call|
+        raise_if_cancelled!
+        run_callbacks(:before_message)
+        add_tool_result_message(tool_call, { error: capped_tool_call_error })
+      end
+    ensure
+      instrument_capped_tool_calls(response) if capped&.any? && unanswered_capped_tool_calls(response).empty?
+    end
+
+    def unanswered_capped_tool_calls(response)
+      pending_tool_calls(response).to_h.slice(*capped_tool_call_ids(response))
+    end
+
+    def capped_tool_call_ids(response)
+      return [] unless @tool_call_cap && response
+
+      response.tool_calls.reject(&:remote?).drop(@tool_call_cap).map(&:id)
+    end
+
+    def capped_tool_call?(tool_call)
+      return false unless @tool_call_cap
+
+      response = messages.reverse_each.find { |message| message.tool_calls.key?(tool_call.id) }
+      capped_tool_call_ids(response).include?(tool_call.id)
+    end
+
+    def capped_tool_call_error
+      "This call didn't run: too many tool calls in one answer (#{@tool_call_cap} at most). " \
+        'Continue step by step, a few calls at a time.'
+    end
+
+    def instrument_capped_tool_calls(response)
+      requested = response.tool_calls.count { |tool_call| !tool_call.remote? }
+      payload = { chat: self, provider: response.provider || @provider.slug, model: response.model_id || @model.id,
+                  requested:, allowed: @tool_call_cap, capped: requested - @tool_call_cap, chat_id: @run.chat_id,
+                  **agent_fields }
+      RubyLLM.instrument('tool_calls_capped.ruby_llm', payload.compact, config: @config)
+    end
+
     def answer_claimed_tool_calls(claimed, server_calls, decisions, executable, denied)
       respond_to_tool_approvals(server_calls.slice(*claimed), decisions)
       deny_tool_calls(denied.slice(*claimed))
@@ -2647,11 +2717,8 @@ module RubyLLM
       id = tool_call.respond_to?(:id) ? tool_call.id : tool_call
       call = tool_call.respond_to?(:name) ? tool_call : find_tool_call(id)
       raise ArgumentError, "Unknown tool call: #{id.inspect}" unless call
-      if call.name == CodeExecution.tool_name && call.namespace.nil?
-        raise ArgumentError, "#{call.name} calls are approved one at a time and cannot be remembered"
-      end
 
-      [call.namespace, call.name.to_s]
+      ToolCallState.remembered_identity(call)
     end
 
     def tool_call_answered?(tool_call)
@@ -3031,6 +3098,13 @@ module RubyLLM
             "Available modes: #{ToolConcurrency::MODES.join(', ')}"
     end
 
+    def apply_tool_calls(value)
+      cap = value if value.is_a?(Integer) && value > 1
+      calls = normalize_calls(value) unless value.nil? || cap
+      @tool_call_cap = cap
+      @tool_prefs[:calls] = calls
+    end
+
     def normalize_calls(calls)
       case calls
       when :many, 'many'
@@ -3038,7 +3112,8 @@ module RubyLLM
       when :one, 'one', 1
         :one
       else
-        raise ArgumentError, "Invalid calls value: #{calls.inspect}. Valid values are: :many, :one, or 1"
+        raise ArgumentError,
+              "Invalid calls value: #{calls.inspect}. Valid values are: :many, :one, or a positive integer"
       end
     end
 

data/lib/ruby_llm/configuration.rb

@@ -17,7 +17,7 @@ module RubyLLM
   # overrides.
   #
   # Provider credentials such as +openai_api_key+ are declared by each
-  # provider. See https://rubyllm.com/next/configuration-providers/ for
+  # provider. See https://rubyllm.com/configuration-providers/ for
   # provider credentials and endpoint settings.
   #
   # Assigning an empty or whitespace-only string to any option stores

data/lib/ruby_llm/file_store/tools/read.rb

@@ -44,13 +44,13 @@ module RubyLLM
           seen = nil
           result = guarded do
             file = file_at(path)
-            seen = [file.path, digest_of(file)]
             unit = (unit || 'lines').to_s
             raise ToolError, "unit is lines or characters, not #{unit}." unless UNITS.include?(unit)
-            next "#{file.path} is empty." if file.byte_size.zero?
 
-            text = store.text(file.path, config:)
+            text, digest = contents(file)
+            seen = [file.path, digest]
             next unreadable(file) if text.nil?
+            next "#{file.path} is empty." if text.empty?
 
             unit == 'characters' ? characters(file, text, offset, limit) : lines(file, text, offset, limit)
           end
@@ -60,6 +60,12 @@ module RubyLLM
 
         private
 
+        def contents(file)
+          return ['', file.digest || FileStore.digest('')] if file.byte_size.zero?
+
+          store.text_with_digest(file, config:)
+        end
+
         def lines(file, text, offset, limit)
           all = text.lines
           start = [offset.to_i, 1].max

data/lib/ruby_llm/file_store.rb

@@ -252,32 +252,52 @@ module RubyLLM
     #
     # See Configuration#file_converters for adding converters.
     def text(path, config: nil)
-      file = find(path)
-      cached = cached_text(file)
-      return cached if cached
+      text_with_digest(find(path), config:).first
+    end
 
-      Converters.convert(attachment(file.path, file:), config: config || RubyLLM.config).tap do |text|
+    # Returns the converted text of +file+ and the digest of the bytes it
+    # came from. With <tt>local: true</tt>, only converters that run on
+    # this machine for free are tried.
+    def text_with_digest(file, config:, local: false) # :nodoc:
+      text = cached_text(file) if file.digest
+      return [text, file.digest] if text
+
+      # Convert the bytes read here, and key the conversion by their own
+      # digest, so text never pairs with a version it didn't come from.
+      content = read(file.path)
+      file = StoredFile.new(**file.to_h, digest: FileStore.digest(content))
+      text = cached_text(file)
+      unless text
+        text = Converters.convert(attachment_of(file, content), config: config || RubyLLM.config, local:)
         cache_text(file, text) if text
       end
+      [text, file.digest]
     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)
+      attachment_of(file, read(file.path))
     end
 
     # Returns the converted text kept for +file+, or +nil+, from memory.
+    # A file that can no longer be read has none.
     def cached_text(file) # :nodoc:
-      @texts_lock.synchronize { @texts[text_key(file)] }
+      return unless file.digest || cached_path?(file)
+
+      key = text_key(file)
+      @texts_lock.synchronize { @texts[key] }
+    rescue FileNotFoundError
+      nil
     end
 
     # Keeps +text+ as the conversion of +file+, in memory.
     def cache_text(file, text) # :nodoc:
+      key = text_key(file)
       @texts_lock.synchronize do
         @texts.delete(@texts.keys.first) if @texts.size >= CACHED_TEXTS
-        @texts[text_key(file)] = text
+        @texts[key] = text
       end
     end
 
@@ -331,8 +351,22 @@ module RubyLLM
       file.digest ? file.digest == digest : read(file.path).b == content
     end
 
+    # A stored type is kept, unless it is the generic
+    # application/octet-stream, which leaves detection to the bytes.
+    def attachment_of(file, content)
+      generic = file.content_type.to_s.split(';').first.to_s.strip.casecmp?('application/octet-stream')
+      mime_type = file.content_type unless generic
+      Attachment.new(StringIO.new(content), filename: file.filename, mime_type:)
+    end
+
+    def cached_path?(file)
+      @texts_lock.synchronize do
+        @texts.each_key.any? { |path, type| path == file.path && type == file.content_type }
+      end
+    end
+
     def text_key(file)
-      file.digest || [file.path, file.byte_size, file.updated_at]
+      [file.path, file.content_type, file.digest || FileStore.digest(read(file.path))]
     end
   end
 end