ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/active_record/acts_as.rb

@@ -7,7 +7,8 @@ module RubyLLM
   # Rails integration brings the RubyLLM API to Active Record models, with
   # Active Storage attachments and a persisted message lifecycle for Hotwire
   # streaming and background jobs. Applications own chats and messages;
-  # RubyLLM owns the supporting usage, tool-call, registry, and batch records.
+  # RubyLLM owns the supporting records (see Record), which applications
+  # read and query.
   module ActiveRecord
     # Adds the RubyLLM conversation API to application-owned records.
     #
@@ -17,10 +18,9 @@ module RubyLLM
     #
     #   class Message < ApplicationRecord
     #     acts_as_message
-    #     has_many_attached :attachments
     #   end
     #
-    #   chat = Chat.create!(model: "gpt-5.6-luna")
+    #   chat = Chat.create!(model: "gpt-6-luna")
     #   response = chat.ask "Summarize this report.", with: report.document
     #   response.content
     #   chat.cost.total
@@ -40,7 +40,7 @@ module RubyLLM
       ##
       # :singleton-method: acts_as_chat
       # :call-seq:
-      #   acts_as_chat(messages: :messages, message_class: nil, messages_foreign_key: nil)
+      #   acts_as_chat(messages: :messages, message_class: nil, messages_foreign_key: nil, owner: nil)
       #
       # Turns an application record into a persisted RubyLLM chat.
       #
@@ -50,19 +50,34 @@ module RubyLLM
       #
       # Adds the RubyLLM::Chat API (see ChatMethods), a +has_many+
       # association to the messages, a +belongs_to :model+ association to
-      # the registry row, and a +has_many :ruby_llm_usages+ association over
-      # the attempts the chat paid for.
+      # the registry row, a +has_many :ruby_llm_usages+ association over
+      # the attempts the chat paid for, a
+      # +has_many :ruby_llm_queued_messages+ association over the messages
+      # waiting in its queue (see ChatMethods#queue), and a
+      # +has_many :ruby_llm_chat_files+ association over its files (see
+      # ChatFiles#with_file_store).
       #
       # Options:
       #
       # [+messages:+] Name of the messages association. Defaults to +:messages+.
       # [+message_class:+] Class of the messages. Inferred from the association name.
       # [+messages_foreign_key:+] Foreign key on the messages table. Inferred by Rails.
+      # [+owner:+] Name of the association whose record the chat works for,
+      #            such as +:user+. Every attempt the chat makes is
+      #            attributed to it in the usage ledger, and the Active
+      #            Storage file store keeps the chat's files for it (see
+      #            ChatFiles#with_file_store). Defaults to +nil+, which
+      #            leaves usage to RubyLLM.with_owner.
+      #
+      #   class Chat < ApplicationRecord
+      #     belongs_to :user
+      #     acts_as_chat owner: :user
+      #   end
 
       ##
       # :singleton-method: acts_as_message
       # :call-seq:
-      #   acts_as_message(chat: :chat, chat_class: nil, chat_foreign_key: nil, touch_chat: false)
+      #   acts_as_message(chat: :chat, chat_class: nil, chat_foreign_key: nil, touch_chat: false, broadcasts: nil)
       #
       # Turns an application record into a persisted RubyLLM message.
       #
@@ -71,8 +86,15 @@ module RubyLLM
       #   end
       #
       # Adds the RubyLLM::Message readers (see MessageMethods), a
-      # +belongs_to+ association to the chat, and the tool-call and usage
-      # associations behind +tool_calls+, +tokens+, and +cost+.
+      # +belongs_to+ association to the chat, the associations behind
+      # +tool_calls+, +tokens+, and +cost+ (+has_many :ruby_llm_tool_calls+
+      # over the ToolCall rows it requested, +has_one :ruby_llm_parent_tool_call+
+      # for the call a tool message answers, and +has_many :ruby_llm_usages+
+      # over its Usage rows), and
+      # <tt>has_many_attached :attachments</tt>, so Active Storage is
+      # required. When turbo-rails and Action Cable are loaded, it also
+      # broadcasts the chat's messages with Turbo when
+      # Configuration#broadcast_messages is on (see MessageBroadcasting).
       #
       # Options:
       #
@@ -80,14 +102,21 @@ module RubyLLM
       # [+chat_class:+] Class of the chat. Inferred from the association name.
       # [+chat_foreign_key:+] Foreign key on this table. Inferred by Rails.
       # [+touch_chat:+] Touch the chat when a message is saved. Defaults to +false+.
+      # [+broadcasts:+] Broadcast messages with Turbo. Defaults to +nil+,
+      #                 which follows Configuration#broadcast_messages.
+      #                 Overrides it with +true+ or +false+.
 
       class_methods do # rubocop:disable Metrics/BlockLength
-        def acts_as_chat(messages: :messages, message_class: nil, messages_foreign_key: nil)
+        def acts_as_chat(messages: :messages, message_class: nil, messages_foreign_key: nil, owner: nil)
           include RubyLLM::ActiveRecord::ChatMethods
+          include RubyLLM::ActiveRecord::ChatFiles
+          singleton_class.prepend RubyLLM::ActiveRecord::ChatColumnGuard
 
           class_attribute :messages_association_name, :message_class
+          class_attribute :owner_association_name, instance_accessor: false
           self.messages_association_name = messages
           self.message_class = (message_class || messages.to_s.classify).to_s
+          self.owner_association_name = owner&.to_sym
 
           has_many messages,
                    -> { order(:created_at, :id) },
@@ -105,10 +134,27 @@ module RubyLLM
                    as: :chat,
                    class_name: 'RubyLLM::ActiveRecord::Usage',
                    inverse_of: :chat,
+                   dependent: :nullify
+
+          has_many :ruby_llm_queued_messages,
+                   -> { order(:created_at, :id) },
+                   as: :chat,
+                   class_name: 'RubyLLM::ActiveRecord::QueuedMessage',
+                   inverse_of: :chat,
                    dependent: :destroy
+
+          has_many :ruby_llm_chat_files,
+                   -> { order(:path, :id) },
+                   as: :chat,
+                   class_name: 'RubyLLM::ActiveRecord::ChatFile',
+                   inverse_of: :chat,
+                   dependent: :destroy
+
+          RubyLLM::ActiveRecord::QueuedMessage.declare_attachments
+          RubyLLM::ActiveRecord::ChatFile.declare_attachments
         end
 
-        def acts_as_message(chat: :chat, chat_class: nil, chat_foreign_key: nil, touch_chat: false)
+        def acts_as_message(chat: :chat, chat_class: nil, chat_foreign_key: nil, touch_chat: false, broadcasts: nil)
           include RubyLLM::ActiveRecord::MessageMethods
 
           class_attribute :chat_association_name, :chat_class
@@ -137,6 +183,27 @@ module RubyLLM
                    class_name: 'RubyLLM::ActiveRecord::Usage',
                    inverse_of: :message,
                    dependent: :nullify
+
+          ruby_llm_attachments
+          ruby_llm_broadcasting(broadcasts)
+        end
+
+        private
+
+        def ruby_llm_attachments
+          if respond_to?(:has_many_attached)
+            has_many_attached :attachments unless reflect_on_attachment(:attachments)
+          else
+            RubyLLM.logger.warn "#{name} has no attachments because Active Storage is not loaded. " \
+                                'Load it with require "active_storage/engine" in config/application.rb, ' \
+                                'then run bin/rails active_storage:install and bin/rails db:migrate.'
+          end
+        end
+
+        def ruby_llm_broadcasting(broadcasts)
+          class_attribute :ruby_llm_broadcasts, instance_writer: false
+          self.ruby_llm_broadcasts = broadcasts
+          include RubyLLM::ActiveRecord::MessageBroadcasting if broadcasts || MessageBroadcasting.available?
         end
       end
     end

data/lib/ruby_llm/active_record/attachment_helpers.rb

@@ -8,7 +8,11 @@ module RubyLLM
       private
 
       def persist_content(message_record, attachments)
-        return unless message_record.respond_to?(:attachments)
+        unless message_record.respond_to?(:attachments)
+          raise RubyLLM::ConfigurationError,
+                "#{message_record.class.name} cannot store attachments without Active Storage. " \
+                'Load it with require "active_storage/engine", then run bin/rails active_storage:install.'
+        end
 
         attachables = prepare_for_active_storage(attachments)
         return if attachables.empty?
@@ -61,7 +65,7 @@ module RubyLLM
             io: StringIO.new(attachment.content),
             filename: attachment.filename,
             content_type: attachment.mime_type,
-            metadata: { resolution: attachment.resolution&.to_s }.compact
+            metadata: { resolution: attachment.resolution&.to_s, processing: attachment.processing&.to_s }.compact
           }
         end
       rescue StandardError => e
@@ -233,7 +237,8 @@ module RubyLLM
         stored = if pending_upload_attachable?(attachable)
                    pending_upload_attachment(attachable)
                  else
-                   RubyLLM::Attachment.new(attachment, resolution: attachment.metadata['resolution']&.to_sym)
+                   RubyLLM::Attachment.new(attachment, resolution: attachment.metadata['resolution']&.to_sym,
+                                                       processing: attachment.metadata['processing']&.to_sym)
                  end
         stored.provider_file_store = ProviderFile.store { attachment.blob&.key }
         stored
@@ -264,7 +269,8 @@ module RubyLLM
         if attachable.is_a?(Hash)
           RubyLLM::Attachment.new(attachment_hash_io(attachable),
                                   filename: attachment_hash_filename(attachable),
-                                  resolution: attachable.dig(:metadata, :resolution)&.to_sym)
+                                  resolution: attachable.dig(:metadata, :resolution)&.to_sym,
+                                  processing: attachable.dig(:metadata, :processing)&.to_sym)
         else
           RubyLLM::Attachment.new(attachable)
         end

data/lib/ruby_llm/active_record/batch.rb

@@ -2,17 +2,37 @@
 
 module RubyLLM
   module ActiveRecord
-    # RubyLLM's private persistence for provider-side batches.
-    class Batch < Record # :nodoc:
+    # A provider-side batch of persisted chats, in RubyLLM's
+    # +ruby_llm_batches+ table. RubyLLM.batch writes a row when it submits
+    # persisted chats of one class, and RubyLLM::Batch.find reads it back
+    # in any process.
+    #
+    #   RubyLLM::ActiveRecord::Batch.where(completed: false).pluck(:provider_batch_id)
+    #
+    # Its columns:
+    #
+    # [+provider_batch_id+] The provider's id for the batch.
+    # [+provider+] The provider's slug.
+    # [+status+] <tt>"pending"</tt>, <tt>"succeeded"</tt>, <tt>"failed"</tt>, or <tt>"cancelled"</tt>.
+    # [+raw_status+] The status as the provider last reported it.
+    # [+completed+] Whether the provider has finished the batch.
+    # [+request_counts+] The provider's request counts, as a Hash.
+    # [+reported_cost+] The cost the provider reported, as a Hash.
+    # [+chat_type+, +chat_ids+] The class and ids of the submitted chats.
+    #
+    # RubyLLM writes these rows. Read and query them, and add scopes and
+    # columns of your own, but do not create or update them.
+    # Use RubyLLM::Batch to refresh a batch and deliver its results.
+    class Batch < Record
       self.table_name = 'ruby_llm_batches'
 
-      STATUSES = %w[pending succeeded failed cancelled].freeze
+      STATUSES = %w[pending succeeded failed cancelled].freeze # :nodoc:
 
       validates :provider_batch_id, :provider, :status, presence: true
       validates :status, inclusion: { in: STATUSES }
 
       class << self
-        def persist(batch, chats)
+        def persist(batch, chats) # :nodoc:
           records = Array(chats)
           return unless table_exists?
           return unless persistable_chats?(records)
@@ -31,11 +51,11 @@ module RubyLLM
           )
         end
 
-        def fetch(id, provider: nil, context: nil)
+        def fetch(id, provider: nil, context: nil) # :nodoc:
           find_record(id, provider:)&.to_llm(context:, store: self)
         end
 
-        def sync(batch)
+        def sync(batch) # :nodoc:
           find_record(batch.id, provider: batch.provider)&.sync_from(batch)
         end
 
@@ -58,6 +78,8 @@ module RubyLLM
         end
       end
 
+      # Returns the submitted chat records in submission order, with +nil+
+      # for a chat that no longer exists.
       def chats
         klass = chat_type.constantize
         by_id = klass.where(klass.primary_key => Array(chat_ids))
@@ -65,12 +87,15 @@ module RubyLLM
         Array(chat_ids).map { |id| by_id[id] }
       end
 
-      def to_llm(context: nil, store: nil)
+      def to_llm(context: nil, store: nil) # :nodoc:
         config = context&.config || RubyLLM.config
         provider_instance = RubyLLM::Provider.resolve!(provider).new(config)
+        records = chats
         RubyLLM::Batch.new(
           provider: provider_instance,
-          chats: chats.map { |chat| chat&.to_llm },
+          chats: records.map { |chat| chat&.to_llm },
+          delivered: records.each_index.select { |index| answered?(records[index]) },
+          delivery: ->(index, failed: false, &deliver) { deliver_once(records[index], failed:, &deliver) },
           id: provider_batch_id,
           raw_status: raw_status,
           completed: completed,
@@ -81,7 +106,7 @@ module RubyLLM
         )
       end
 
-      def sync_from(batch)
+      def sync_from(batch) # :nodoc:
         attributes = {
           status: batch.status,
           raw_status: batch.raw_status,
@@ -92,6 +117,39 @@ module RubyLLM
         attributes[:reported_cost] = batch.reported_cost.to_h if batch.reported_cost
         update!(attributes)
       end
+
+      private
+
+      # Two pollers can load a batch before either delivers, so the check
+      # is repeated once this one holds the chat.
+      def deliver_once(chat, failed: false)
+        return yield.then { true } unless chat
+
+        chat.claiming_delivery do
+          yield unless failed ? billed_failure?(chat) : answered?(chat)
+          true
+        end
+      end
+
+      # A failed slot adds no message, so its usage row is what marks it.
+      def billed_failure?(chat)
+        usages = chat.ruby_llm_usages
+        usages.klass.uncached do
+          usages.where(status: 'failed').where(usages.klass.arel_table[:created_at].gt(created_at)).exists?
+        end
+      end
+
+      # The chat was awaiting the model when the batch was submitted, so an
+      # assistant message newer than the batch answers that turn, whatever
+      # the chat went on to stage after it.
+      def answered?(chat)
+        return false unless chat
+
+        messages = chat.messages_association
+        messages.klass.uncached do
+          messages.where(role: :assistant).where(messages.klass.arel_table[:created_at].gt(created_at)).exists?
+        end
+      end
     end
   end
 end

data/lib/ruby_llm/active_record/chat_agent_hooks.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # What the Agent that configured a persisted chat adds to its
+    # operations: its rescue_from handlers, and one +agent.ruby_llm+ event
+    # around each run, shared with the chat the record wraps.
+    module ChatAgentHooks # :nodoc:
+      include RubyLLM::Chat::AgentRun
+      include RubyLLM::Chat::Rescuable
+
+      private
+
+      def agent_run_chat = @chat
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_approvals.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Keeps approval decisions on tool call records, read outside the query
+    # cache, so every process decides tool calls the same way. A call
+    # approved with <tt>remember: true</tt> is recorded as +remembered+,
+    # and later calls to the same tool in the chat run without asking.
+    # A call saved while it requires approval is recorded as +pending+, so
+    # pending approvals are read from the rows without building the chat's
+    # tools.
+    module ChatApprovals # :nodoc:
+      def persisted_tool_call_approval(tool_call) # :nodoc:
+        record = RubyLLM::ActiveRecord::ToolCall.uncached { find_tool_call(tool_call.id) }
+        return unless record&.has_attribute?(:approval)
+
+        case record.approval
+        when 'approved', 'remembered' then true
+        when 'denied' then false
+        end
+      end
+
+      def persisted_remembered_tool?(call) # :nodoc:
+        return false unless persisted? && row_supports_approval?
+
+        RubyLLM::ActiveRecord::ToolCall.uncached do
+          identity = tool_identity.to_h { |column| [column, call.public_send(column)] }
+          chat_tool_calls.where(**identity, approval: 'remembered').exists?
+        end
+      end
+
+      private
+
+      def persisted_pending_approvals
+        pending = chat_tool_calls.where(approval: 'pending', result_id: nil)
+        remembered = RubyLLM::ActiveRecord::ToolCall.uncached do
+          chat_tool_calls.where(approval: 'remembered').distinct.pluck(*tool_identity)
+        end
+        remembered.reduce(pending) do |calls, identity|
+          calls.where.not(id: pending.where(tool_identity.zip(Array(identity)).to_h).select(:id))
+        end.order(:created_at, :id).skip_query_cache!
+      end
+
+      def tool_identity
+        RubyLLM::ActiveRecord::ToolCall.column_names.include?('namespace') ? %i[namespace name] : %i[name]
+      end
+
+      def chat_tool_calls
+        RubyLLM::ActiveRecord::ToolCall.where(
+          message_type: messages_association.klass.polymorphic_name,
+          message_id: messages_association.select(:id)
+        )
+      end
+
+      def record_tool_call_decision(tool_call, decision)
+        record = tool_call_record(tool_call)
+        decide_persisted_tool_call(record, decision)
+        record
+      end
+
+      def tool_call_record(tool_call)
+        id = tool_call.respond_to?(:tool_call_id) ? tool_call.tool_call_id : tool_call
+        id = id.id if id.respond_to?(:id) && !id.is_a?(String)
+        record = RubyLLM::ActiveRecord::ToolCall.uncached { find_tool_call(id) }
+        raise ArgumentError, "Unknown tool call: #{id.inspect}" unless record
+
+        record
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_cancellation.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Reads a cancellation request another process persisted on the chat
+    # record, at most once per poll interval, and clears it once observed.
+    # A request is for the run holding the chat, or for the run about to
+    # answer what waits. New work recorded while no run holds the chat, and
+    # a run that finds nothing waiting, clear a request that is left over.
+    module ChatCancellation # :nodoc:
+      def poll_run_cancellation # :nodoc:
+        renew_run_claim
+        consume_persisted_cancellation_request
+      end
+
+      def forget_stale_cancellation # :nodoc:
+        return if @run_claim_token || !run_claims? || !has_attribute?(:cancelled)
+
+        requested = unclaimed(chat_row.where(cancelled: true), Time.current)
+        remember_cancellation(false) if requested.update_all(cancelled: false) == 1
+      end
+
+      private
+
+      def request_cancellation
+        return request_run_cancellation if run_claims?
+
+        persisted? ? update_column(:cancelled, true) : self[:cancelled] = true
+        @chat&.cancel
+      end
+
+      # The conditional update can't land after the run's release, which
+      # clears the request, so it can't outlive the run it was meant for.
+      def request_run_cancellation
+        claimed_until = chat_row.arel_table[:claimed_until]
+        if chat_row.where(claimed_until.gt(Time.current)).update_all(cancelled: true) == 1
+          remember_cancellation(true)
+          @chat&.cancel if @run_claim_token
+        elsif !nothing_to_stop?
+          update_column(:cancelled, true)
+        end
+      end
+
+      def nothing_to_stop?
+        return false unless ChatQueue.new(self).none?
+
+        messages_association.klass.uncached do
+          latest = messages_association.where.not(role: :system).reorder(created_at: :desc, id: :desc).first
+          latest.nil? || finished_reply?(latest)
+        end
+      end
+
+      def finished_reply?(message)
+        message.role.to_s == 'assistant' && message.content.present? &&
+          !unfinished_record?(message) && !message.tool_call?
+      end
+
+      def settle_cancellation_request
+        return unless @run_claim_token && has_attribute?(:cancelled)
+
+        remember_cancellation(self.class.uncached { chat_row.pick(:cancelled) })
+        clear_cancellation_request if self[:cancelled] && to_llm.complete? && ChatQueue.new(self).none?
+      end
+
+      def remember_cancellation(requested)
+        self[:cancelled] = requested
+        clear_attribute_changes([:cancelled])
+      end
+
+      def consume_persisted_cancellation_request
+        if self[:cancelled]
+          clear_cancellation_request
+          return :cancelled
+        end
+        return unless persisted?
+        return unless cancellation_poll_due?
+        return unless persisted_cancellation_request?
+
+        clear_cancellation_request
+        :cancelled
+      end
+
+      # Jobs and requests run with the query cache on, which would replay the
+      # first poll's answer for the rest of the run.
+      def persisted_cancellation_request?
+        self.class.uncached do
+          self.class.unscoped.where(self.class.primary_key => id).pick(:cancelled)
+        end
+      end
+
+      def clear_cancellation_request
+        self[:cancelled] = false
+        self.class.unscoped.where(self.class.primary_key => id).update_all(cancelled: false) if persisted?
+      end
+
+      def cancellation_poll_due?
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        interval = ChatMethods::CANCELLATION_POLL_INTERVAL
+        return false if @last_cancellation_poll_at && now - @last_cancellation_poll_at < interval
+
+        @last_cancellation_poll_at = now
+        true
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_column_guard.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Refuses a chat table with a column, or a chat model with an
+    # association, that a RubyLLM reader on the record would hide, such as
+    # a +temperature+ column or a +tools+ association: reading it would
+    # return RubyLLM's setting instead of the stored value. The check runs
+    # when the class loads its columns, so it needs no database at boot. A
+    # reader hides a column or an association when it comes from
+    # ChatMethods or ChatFiles, or a module they bring along, such as
+    # Enumerable.
+    module ChatColumnGuard # :nodoc:
+      OWNERS = (ChatMethods.ancestors | ChatFiles.ancestors).freeze
+
+      private
+
+      def load_schema!
+        super
+        hidden = columns_hash.keys.select { |column| hidden_by_ruby_llm?(column) }
+        raise ArgumentError, hidden_columns_message(hidden) if hidden.any?
+
+        associations = reflect_on_all_associations.select do |association|
+          association.name.to_s != messages_association_name.to_s && hidden_by_ruby_llm?(association.name)
+        end
+        raise ArgumentError, hidden_associations_message(associations) if associations.any?
+      end
+
+      def hidden_by_ruby_llm?(name)
+        method_defined?(name) && OWNERS.include?(instance_method(name).owner)
+      end
+
+      def hidden_columns_message(hidden)
+        columns = hidden.map { |column| "#{table_name}.#{column}" }.join(', ')
+        readers = hidden.map { |column| "#{name}##{column}" }.join(', ')
+        them = hidden.one? ? 'it' : 'them'
+        "#{columns} cannot be read on #{name}: acts_as_chat defines #{readers}, which would hide #{them}. " \
+          "Rename the column in a migration, such as rename_column :#{table_name}, :#{hidden.first}, " \
+          ":#{hidden.first}_setting."
+      end
+
+      def hidden_associations_message(associations)
+        names = associations.map { |association| "#{association.macro} :#{association.name}" }.join(', ')
+        readers = associations.map { |association| "#{name}##{association.name}" }.join(', ')
+        them = associations.one? ? 'it' : 'them'
+        "#{names} cannot be read on #{name}: acts_as_chat defines #{readers}, which would hide #{them}. " \
+          "Rename #{them}, with class_name: and foreign_key: options that keep the same table and columns."
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_file.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # A file in a persisted chat's FileStore, in RubyLLM's
+    # +ruby_llm_chat_files+ table, with its content in Active Storage. It
+    # keeps the text a converter made of the file, so each version is
+    # converted once.
+    #
+    #   chat.ruby_llm_chat_files.pluck(:path) # => ["contract.pdf", "results/search-call_1.json"]
+    #
+    # Rows with an +owner+ are seen only through a store for that owner
+    # (see ChatFiles#with_file_store); rows without one are seen by every
+    # store of the chat.
+    class ChatFile < Record
+      self.table_name = 'ruby_llm_chat_files'
+
+      belongs_to :chat, polymorphic: true
+      belongs_to :owner, polymorphic: true, optional: true
+
+      # Declares the content attachment when Active Storage is loaded.
+      # Called by +acts_as_chat+, since Active Storage loads after
+      # RubyLLM's records.
+      def self.declare_attachments # :nodoc:
+        return unless respond_to?(:has_one_attached) && !reflect_on_attachment(:file)
+
+        has_one_attached :file
+      end
+
+      # Returns the file as a RubyLLM::StoredFile.
+      def to_stored_file
+        RubyLLM::StoredFile.new(path:, byte_size:, content_type:, digest:, updated_at:,
+                                owner: (owner if owner_id))
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_files.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # The file store of a persisted chat, added by +acts_as_chat+ with
+    # ChatMethods: the chat's files live in +ruby_llm_chat_files+, with
+    # their content in Active Storage.
+    module ChatFiles
+      # Applies Chat#with_file_store and returns this record. Without a
+      # +store+, the chat keeps its files in Active Storage, in
+      # +ruby_llm_chat_files+ (see ActiveRecord::FileStore), for the
+      # chat's owner, the record <tt>acts_as_chat owner:</tt> names: that
+      # store writes files for the owner and sees only their files and the
+      # files without an owner. Pass +nil+ to remove the store.
+      #
+      #   chat.with_file_store
+      #   chat.with_file_store("tmp/chats/42")
+      #   chat.with_file_store(:memory)
+      #   chat.with_file_store(nil)
+      #
+      # :call-seq:
+      #   with_file_store(store = active_storage_store, inline_limit: 10_000, tools: %i[read write edit])
+      def with_file_store(store = RubyLLM::Chat::FileReferences::DEFAULT_STORE, **)
+        store = FileStore.new(self) if store.equal?(RubyLLM::Chat::FileReferences::DEFAULT_STORE)
+        to_llm.with_file_store(store, **)
+        self
+      end
+    end
+  end
+end