ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/active_record/acts_as.rb

@@ -4,153 +4,136 @@ require 'active_support/concern'
 require 'active_support/inflector'
 
 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.
   module ActiveRecord
-    # Adds chat and message persistence capabilities to ActiveRecord models.
+    # Adds the RubyLLM conversation API to application-owned records.
+    #
+    #   class Chat < ApplicationRecord
+    #     acts_as_chat
+    #   end
+    #
+    #   class Message < ApplicationRecord
+    #     acts_as_message
+    #     has_many_attached :attachments
+    #   end
+    #
+    #   chat = Chat.create!(model: "gpt-5.6-luna")
+    #   response = chat.ask "Summarize this report.", with: report.document
+    #   response.content
+    #   chat.cost.total
+    #
+    # The install generator creates the required schema. The chat_ui
+    # generator adds controllers, an Active Job, and Turbo Stream views.
+    #
     module ActsAs
       extend ActiveSupport::Concern
 
-      def self.included(base)
+      def self.included(base) # :nodoc:
         super
-        RubyLLM.config.model_registry_source ||= RubyLLM::ModelRegistry::ActiveRecordSource.new
+        RubyLLM.config.model_registry_store ||= RubyLLM::ActiveRecord::Model
+        RubyLLM.config.batch_store ||= RubyLLM::ActiveRecord::Batch
       end
 
+      ##
+      # :singleton-method: acts_as_chat
+      # :call-seq:
+      #   acts_as_chat(messages: :messages, message_class: nil, messages_foreign_key: nil)
+      #
+      # Turns an application record into a persisted RubyLLM chat.
+      #
+      #   class Chat < ApplicationRecord
+      #     acts_as_chat
+      #   end
+      #
+      # 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.
+      #
+      # 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.
+
+      ##
+      # :singleton-method: acts_as_message
+      # :call-seq:
+      #   acts_as_message(chat: :chat, chat_class: nil, chat_foreign_key: nil, touch_chat: false)
+      #
+      # Turns an application record into a persisted RubyLLM message.
+      #
+      #   class Message < ApplicationRecord
+      #     acts_as_message
+      #   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+.
+      #
+      # Options:
+      #
+      # [+chat:+] Name of the chat association. Defaults to +:chat+.
+      # [+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+.
+
       class_methods do # rubocop:disable Metrics/BlockLength
-        def acts_as_chat(messages: :messages, message_class: nil, messages_foreign_key: nil, # rubocop:disable Metrics/ParameterLists
-                         model: :model, model_class: nil, model_foreign_key: nil)
+        def acts_as_chat(messages: :messages, message_class: nil, messages_foreign_key: nil)
           include RubyLLM::ActiveRecord::ChatMethods
 
-          class_attribute :messages_association_name, :model_association_name, :message_class, :model_class
-
+          class_attribute :messages_association_name, :message_class
           self.messages_association_name = messages
-          self.model_association_name = model
           self.message_class = (message_class || messages.to_s.classify).to_s
-          self.model_class = (model_class || model.to_s.classify).to_s
 
           has_many messages,
-                   -> { order(created_at: :asc) },
+                   -> { order(:created_at, :id) },
                    class_name: self.message_class,
                    foreign_key: messages_foreign_key,
                    dependent: :destroy
 
-          belongs_to model,
-                     class_name: self.model_class,
-                     foreign_key: model_foreign_key,
+          belongs_to :model,
+                     class_name: 'RubyLLM::ActiveRecord::Model',
+                     foreign_key: :ruby_llm_model_id,
                      optional: true
 
-          define_method :messages_association do
-            send(messages_association_name)
-          end
-
-          define_method :model_association do
-            send(model_association_name)
-          end
-
-          define_method :'model_association=' do |value|
-            send("#{model_association_name}=", value)
-          end
-        end
-
-        def acts_as_model(chats: :chats, chat_class: nil, chats_foreign_key: nil)
-          include RubyLLM::ActiveRecord::ModelMethods
-
-          class_attribute :chats_association_name, :chat_class
-
-          self.chats_association_name = chats
-          self.chat_class = (chat_class || chats.to_s.classify).to_s
-
-          validates :model_id, presence: true, uniqueness: { scope: :provider }
-          validates :provider, presence: true
-          validates :name, presence: true
-
-          has_many chats, class_name: self.chat_class, foreign_key: chats_foreign_key
-
-          define_method :chats_association do
-            send(chats_association_name)
-          end
+          has_many :ruby_llm_usages,
+                   -> { chronological },
+                   as: :chat,
+                   class_name: 'RubyLLM::ActiveRecord::Usage',
+                   dependent: :destroy
         end
 
-        def acts_as_message(chat: :chat, chat_class: nil, chat_foreign_key: nil, touch_chat: false, # rubocop:disable Metrics/ParameterLists
-                            tool_calls: :tool_calls, tool_call_class: nil, tool_calls_foreign_key: nil,
-                            model: :model, model_class: nil, model_foreign_key: nil)
+        def acts_as_message(chat: :chat, chat_class: nil, chat_foreign_key: nil, touch_chat: false)
           include RubyLLM::ActiveRecord::MessageMethods
 
-          class_attribute :chat_association_name, :tool_calls_association_name, :model_association_name,
-                          :chat_class, :tool_call_class, :model_class
-
+          class_attribute :chat_association_name, :chat_class
           self.chat_association_name = chat
-          self.tool_calls_association_name = tool_calls
-          self.model_association_name = model
           self.chat_class = (chat_class || chat.to_s.classify).to_s
-          self.tool_call_class = (tool_call_class || tool_calls.to_s.classify).to_s
-          self.model_class = (model_class || model.to_s.classify).to_s
 
           belongs_to chat,
                      class_name: self.chat_class,
                      foreign_key: chat_foreign_key,
                      touch: touch_chat
 
-          has_many tool_calls,
-                   class_name: self.tool_call_class,
-                   foreign_key: tool_calls_foreign_key,
+          has_many :ruby_llm_tool_calls,
+                   as: :message,
+                   class_name: 'RubyLLM::ActiveRecord::ToolCall',
                    dependent: :destroy
 
-          belongs_to :parent_tool_call,
-                     class_name: self.tool_call_class,
-                     foreign_key: ActiveSupport::Inflector.foreign_key(tool_calls.to_s.singularize),
-                     optional: true
-
-          has_many :tool_results,
-                   through: tool_calls,
-                   source: :result,
-                   class_name: name
-
-          belongs_to model,
-                     class_name: self.model_class,
-                     foreign_key: model_foreign_key,
-                     optional: true
-
-          delegate :tool_call?, :tool_result?, to: :to_llm
-
-          define_method :chat_association do
-            send(chat_association_name)
-          end
-
-          define_method :tool_calls_association do
-            send(tool_calls_association_name)
-          end
-
-          define_method :model_association do
-            send(model_association_name)
-          end
-        end
-
-        def acts_as_tool_call(message: :message, message_class: nil, message_foreign_key: nil, # rubocop:disable Metrics/ParameterLists
-                              result: :result, result_class: nil, result_foreign_key: nil)
-          include RubyLLM::ActiveRecord::ToolCallMethods
-
-          class_attribute :message_association_name, :result_association_name, :message_class, :result_class
-
-          self.message_association_name = message
-          self.result_association_name = result
-          self.message_class = (message_class || message.to_s.classify).to_s
-          self.result_class = (result_class || self.message_class).to_s
-
-          belongs_to message,
-                     class_name: self.message_class,
-                     foreign_key: message_foreign_key
-
-          has_one result,
-                  class_name: self.result_class,
-                  foreign_key: result_foreign_key,
+          has_one :ruby_llm_parent_tool_call,
+                  as: :result,
+                  class_name: 'RubyLLM::ActiveRecord::ToolCall',
                   dependent: :nullify
 
-          define_method :message_association do
-            send(message_association_name)
-          end
-
-          define_method :result_association do
-            send(result_association_name)
-          end
+          has_many :ruby_llm_usages,
+                   -> { chronological },
+                   as: :message,
+                   class_name: 'RubyLLM::ActiveRecord::Usage',
+                   dependent: :nullify
         end
       end
     end

data/lib/ruby_llm/active_record/attachment_helpers.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object/blank'
+require 'tempfile'
+
+module RubyLLM
+  module ActiveRecord
+    module AttachmentHelpers # :nodoc:
+      private
+
+      def persist_content(message_record, attachments)
+        return unless message_record.respond_to?(:attachments)
+
+        attachables = prepare_for_active_storage(attachments)
+        message_record.attachments.attach(attachables) if attachables.any?
+      end
+
+      def prepare_for_active_storage(attachments)
+        Support::Utils.to_safe_array(attachments).filter_map do |attachment|
+          case attachment
+          when ActionDispatch::Http::UploadedFile, ActiveStorage::Blob
+            attachment
+          when ActiveStorage::Attachment, ActiveStorage::Attached::One, ActiveStorage::Attached::Many
+            active_storage_blobs(attachment)
+          when Hash
+            attachment.values.map { |v| prepare_for_active_storage(v) }
+          else
+            convert_to_active_storage_format(attachment)
+          end
+        end.flatten.compact
+      end
+
+      def convert_to_active_storage_format(source)
+        return if source.blank?
+
+        attachment = source.is_a?(RubyLLM::Attachment) ? source : RubyLLM::Attachment.new(source)
+
+        if attachment.active_storage?
+          active_storage_blobs(attachment.source)
+        else
+          {
+            io: StringIO.new(attachment.content),
+            filename: attachment.filename,
+            content_type: attachment.mime_type
+          }
+        end
+      rescue StandardError => e
+        RubyLLM.logger.warn "Failed to process attachment #{source}: #{e.message}"
+        nil
+      end
+
+      def active_storage_blobs(attachment)
+        case attachment
+        when ActiveStorage::Blob then attachment
+        when ActiveStorage::Attachment, ActiveStorage::Attached::One then attachment.blob
+        when ActiveStorage::Attached::Many then attachment.blobs
+        end
+      end
+
+      def plain_text_content(content_value)
+        return content_value.to_plain_text if content_value.respond_to?(:to_plain_text)
+
+        content_value
+      end
+
+      def action_text_attachment_sources(content_value)
+        return [] unless content_value.respond_to?(:body)
+
+        body = content_value.body
+        return [] unless body.respond_to?(:attachables)
+
+        body.attachables.flat_map { |attachable| action_text_attachable_sources(attachable) }.compact
+      end
+
+      def action_text_attachable_sources(attachable)
+        source = active_storage_blobs(attachable)
+        source ||= attachable.blob if attachable.respond_to?(:blob)
+
+        Support::Utils.to_safe_array(source)
+      end
+
+      def content_attachments?(action_text_attachments)
+        action_text_attachments.any? || active_storage_attachments?
+      end
+
+      def active_storage_attachments?
+        respond_to?(:attachments) && attachments.attached?
+      end
+
+      def collect_attachments(action_text_attachments)
+        list = action_text_attachments.map { |source| RubyLLM::Attachment.new(source) }
+        return list unless active_storage_attachments?
+
+        list + attachment_sources.map { |attachment, attachable| stored_attachment(attachment, attachable) }
+      end
+
+      def attachment_sources
+        change = pending_attachment_change
+        return attachments_with_blobs.map { |attachment| [attachment, nil] } unless pending_attachment_change?(change)
+
+        change.attachments.zip(change.attachables)
+      end
+
+      def attachments_with_blobs
+        records = attachments.to_a
+        ::ActiveRecord::Associations::Preloader.new(records: records, associations: :blob).call
+        records
+      end
+
+      def pending_attachment_change
+        attachment_changes['attachments'] if respond_to?(:attachment_changes)
+      end
+
+      def pending_attachment_change?(change)
+        change.respond_to?(:attachments) && change.respond_to?(:attachables)
+      end
+
+      def stored_attachment(attachment, attachable)
+        if pending_upload_attachable?(attachable)
+          pending_upload_attachment(attachable)
+        else
+          tempfile = download_attachment(attachment)
+          RubyLLM::Attachment.new(tempfile, filename: attachment.filename.to_s)
+        end
+      end
+
+      def pending_upload_attachable?(attachable)
+        return false if attachable.nil? || attachable.is_a?(String)
+        return false if instance_of_class?(attachable, 'ActiveStorage::Blob')
+
+        uploaded_file?(attachable) || active_storage_upload_hash?(attachable) ||
+          attachable.is_a?(File) || pathname?(attachable)
+      end
+
+      def uploaded_file?(attachable)
+        instance_of_class?(attachable, 'ActionDispatch::Http::UploadedFile') ||
+          instance_of_class?(attachable, 'Rack::Test::UploadedFile')
+      end
+
+      def active_storage_upload_hash?(attachable)
+        attachable.is_a?(Hash) && attachment_hash_io(attachable).present?
+      end
+
+      def pathname?(attachable)
+        defined?(Pathname) && attachable.is_a?(Pathname)
+      end
+
+      def pending_upload_attachment(attachable)
+        if attachable.is_a?(Hash)
+          RubyLLM::Attachment.new(attachment_hash_io(attachable), filename: attachment_hash_filename(attachable))
+        else
+          RubyLLM::Attachment.new(attachable)
+        end
+      end
+
+      def attachment_hash_io(attachable)
+        attachable[:io] || attachable['io']
+      end
+
+      def attachment_hash_filename(attachable)
+        filename = attachable[:filename] || attachable['filename']
+        filename&.to_s
+      end
+
+      def instance_of_class?(object, class_name)
+        Object.const_get(class_name).then { |klass| object.is_a?(klass) }
+      rescue NameError
+        false
+      end
+
+      def download_attachment(attachment)
+        ext = File.extname(attachment.filename.to_s)
+        basename = File.basename(attachment.filename.to_s, ext)
+        tempfile = Tempfile.new([basename, ext])
+        tempfile.binmode
+
+        attachment.download { |chunk| tempfile.write(chunk) }
+
+        tempfile.flush
+        tempfile.rewind
+        @_tempfiles << tempfile
+        tempfile
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/batch.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # RubyLLM's private persistence for provider-side batches.
+    class Batch < ::ActiveRecord::Base # :nodoc:
+      self.table_name = 'ruby_llm_batches'
+
+      STATUSES = %w[pending succeeded failed cancelled].freeze
+
+      validates :provider_batch_id, :provider, :status, presence: true
+      validates :status, inclusion: { in: STATUSES }
+
+      class << self
+        def persist(batch, chats)
+          records = Array(chats)
+          return unless table_exists?
+          return unless persistable_chats?(records)
+
+          create!(
+            provider_batch_id: batch.id,
+            provider: batch.provider,
+            status: batch.status,
+            raw_status: batch.raw_status,
+            completed: batch.complete?,
+            request_counts: batch.request_counts,
+            reported_cost: batch.reported_cost&.to_h,
+            batch_protocol: batch.batch_protocol,
+            chat_type: records.first.class.polymorphic_name,
+            chat_ids: records.map(&:id)
+          )
+        end
+
+        def fetch(id, provider: nil, context: nil)
+          find_record(id, provider:)&.to_llm(context:, store: self)
+        end
+
+        def sync(batch)
+          find_record(batch.id, provider: batch.provider)&.sync_from(batch)
+        end
+
+        private
+
+        def find_record(id, provider: nil)
+          return unless table_exists?
+
+          scope = where(provider_batch_id: id)
+          scope = scope.where(provider: provider.to_s) if provider
+          scope.order(id: :desc).first
+        end
+
+        def persistable_chats?(records)
+          records.all? { |chat| persisted_chat?(chat) } && records.map(&:class).uniq.one?
+        end
+
+        def persisted_chat?(chat)
+          chat.respond_to?(:to_llm) && chat.respond_to?(:id) && chat.persisted?
+        end
+      end
+
+      def chats
+        klass = chat_type.constantize
+        by_id = klass.where(klass.primary_key => Array(chat_ids))
+                     .index_by { |chat| chat.public_send(klass.primary_key) }
+        Array(chat_ids).map { |id| by_id[id] }
+      end
+
+      def to_llm(context: nil, store: nil)
+        config = context&.config || RubyLLM.config
+        provider_instance = RubyLLM::Provider.resolve!(provider).new(config)
+        RubyLLM::Batch.new(
+          provider: provider_instance,
+          chats: chats.map { |chat| chat&.to_llm },
+          id: provider_batch_id,
+          raw_status: raw_status,
+          completed: completed,
+          request_counts: request_counts,
+          reported_cost: reported_cost && RubyLLM::Cost.from_h(reported_cost),
+          batch_protocol: batch_protocol,
+          store: store
+        )
+      end
+
+      def sync_from(batch)
+        attributes = {
+          status: batch.status,
+          raw_status: batch.raw_status,
+          completed: batch.complete?,
+          request_counts: batch.request_counts,
+          batch_protocol: batch.batch_protocol
+        }
+        attributes[:reported_cost] = batch.reported_cost.to_h if batch.reported_cost
+        update!(attributes)
+      end
+    end
+  end
+end