ruby_llm 1.15.0 → 2.0.0.rc1

data/lib/ruby_llm/active_record/message_methods.rb

@@ -1,63 +1,127 @@
 # frozen_string_literal: true
 
 require 'active_support/concern'
+require 'ruby_llm/active_record/attachment_helpers'
 require 'ruby_llm/active_record/payload_helpers'
 
 module RubyLLM
   module ActiveRecord
-    # Methods mixed into message models.
+    # Maps an application-owned message record onto RubyLLM's public Message
+    # API while keeping accounting and tool-call rows private to the gem.
     module MessageMethods
       extend ActiveSupport::Concern
       include PayloadHelpers
+      include AttachmentHelpers
 
-      class_methods do
-        attr_reader :chat_class, :tool_call_class, :chat_foreign_key, :tool_call_foreign_key
+      def chat_association # :nodoc:
+        send(chat_association_name)
       end
 
+      # Converts this record to a RubyLLM::Message.
       def to_llm
+        entries = ruby_llm_usage_entries
         RubyLLM::Message.new(
           role: role.to_sym,
           content: extract_content,
+          attachments: extract_attachments,
           thinking: thinking,
-          tokens: tokens,
-          tool_calls: extract_tool_calls,
-          tool_call_id: extract_tool_call_id,
-          model_id: model_association&.model_id
+          citations: citations,
+          server_tool_calls: server_tool_calls,
+          raw_content: optional_column(:raw_content),
+          raw_reasoning: optional_column(:raw_reasoning),
+          usage_entries: entries,
+          tool_calls: tool_calls,
+          tool_call_id: parent_tool_call&.id,
+          finish_reason: optional_column(:finish_reason),
+          model: entries.reverse.find(&:succeeded?)&.model,
+          cache_until_here: cache_until_here?
         )
       end
 
+      def ruby_llm_usage_entries # :nodoc:
+        ruby_llm_usages.map(&:to_entry)
+      end
+
+      # Returns the model ID from the last successful attempt, or +nil+.
+      def model
+        to_llm.model
+      end
+
+      # Returns the model from the registry, or +nil+ if it is unknown.
+      def model_info
+        to_llm.model_info
+      end
+
+      # Marks the message as a prompt cache boundary and returns it.
+      def cache_until_here
+        update!(cache_until_here: true)
+        self
+      end
+
+      # Returns +true+ if the message is a prompt cache boundary.
+      def cache_until_here?
+        optional_column(:cache_until_here) || false
+      end
+
+      # Returns the reasoning the model returned as a RubyLLM::Thinking, or +nil+.
       def thinking
         RubyLLM::Thinking.build(
-          text: thinking_text_value,
-          signature: thinking_signature_value
+          text: optional_column(:thinking_text),
+          signature: optional_column(:thinking_signature)
         )
       end
 
+      # Returns the citations as an array of RubyLLM::Citation.
+      def citations
+        Array(optional_column(:citations)).map { |citation| RubyLLM::Citation.from_h(citation) }
+      end
+
+      # Returns the provider-executed tool steps as an array of RubyLLM::ServerToolCall.
+      def server_tool_calls
+        Array(optional_column(:server_tool_calls)).map { |call| RubyLLM::ServerToolCall.from_h(call) }
+      end
+
+      # Returns the token usage across every attempt that produced the message.
       def tokens
-        RubyLLM::Tokens.build(
-          input: input_tokens,
-          output: output_tokens,
-          cached: cached_value,
-          cache_creation: cache_creation_value,
-          thinking: thinking_tokens_value
-        )
+        RubyLLM::Tokens.aggregate(ruby_llm_usages.map(&:tokens))
       end
 
+      # Returns the cost across every attempt that produced the message, as a RubyLLM::Cost.
       def cost
-        RubyLLM::Cost.new(tokens:, model: model_association)
+        records = ruby_llm_usages.to_a
+        RubyLLM::Cost.aggregate(records.map(&:cost), complete: records.all?(&:cost_available?))
       end
 
-      def cache_read_tokens
-        cached_value
+      # Returns the tool calls as RubyLLM::ToolCall values keyed by call id.
+      def tool_calls
+        ruby_llm_tool_calls.to_h { |record| [record.tool_call_id, record.to_llm] }
       end
 
-      def cache_write_tokens
-        cache_creation_value
+      # Returns the tool call this message answers, or +nil+.
+      def parent_tool_call
+        ruby_llm_parent_tool_call&.to_llm
       end
 
+      # Returns the message records that answer this message's tool calls.
+      def tool_results
+        ruby_llm_tool_calls.filter_map(&:result)
+      end
+
+      # Returns +true+ if the message carries tool calls.
+      def tool_call?
+        ruby_llm_tool_calls.any?
+      end
+
+      # Returns +true+ if the message answers a tool call.
+      def tool_result?
+        ruby_llm_parent_tool_call.present?
+      end
+
+      # Returns the partial path for the message by role, such as +messages/assistant+
+      # or +messages/tool_calls+.
       def to_partial_path
         partial_prefix = self.class.name.underscore.pluralize
-        role_partial = if to_llm.tool_call?
+        role_partial = if tool_call?
                          'tool_calls'
                        elsif role.to_s == 'tool'
                          'tool'
@@ -67,80 +131,60 @@ module RubyLLM
         "#{partial_prefix}/#{role_partial}"
       end
 
+      # Returns the error text of a failed tool result, or +nil+.
       def tool_error_message
-        payload_error_message(content)
+        payload_error_message(extract_content)
       end
 
-      private
-
-      def thinking_text_value
-        has_attribute?(:thinking_text) ? self[:thinking_text] : nil
+      # Returns why the model stopped, as the Symbol RubyLLM::Message#finish_reason reports.
+      def finish_reason
+        optional_column(:finish_reason)&.to_sym
       end
 
-      def thinking_signature_value
-        has_attribute?(:thinking_signature) ? self[:thinking_signature] : nil
+      # Returns +true+ if the model finished normally without requesting tools.
+      def stopped?
+        to_llm.stopped?
       end
 
-      def cached_value
-        has_attribute?(:cached_tokens) ? self[:cached_tokens] : nil
+      # Returns +true+ if a token limit stopped the response.
+      def max_tokens?
+        to_llm.max_tokens?
       end
 
-      def cache_creation_value
-        has_attribute?(:cache_creation_tokens) ? self[:cache_creation_tokens] : nil
+      # Returns +true+ if the model stopped to request tool calls.
+      def tool_call_stop?
+        to_llm.tool_call_stop?
       end
 
-      def thinking_tokens_value
-        has_attribute?(:thinking_tokens) ? self[:thinking_tokens] : nil
+      # Returns +true+ if a provider safety filter stopped the response.
+      def content_filtered?
+        to_llm.content_filtered?
       end
 
-      def extract_tool_calls
-        tool_calls_association.to_h do |tool_call|
-          [
-            tool_call.tool_call_id,
-            RubyLLM::ToolCall.new(
-              id: tool_call.tool_call_id,
-              name: tool_call.name,
-              arguments: tool_call.arguments,
-              thought_signature: tool_call.try(:thought_signature)
-            )
-          ]
-        end
-      end
+      # Returns the content parsed as JSON, or +nil+ when the message has no text.
+      def parsed
+        text = extract_content
+        return if text.nil? || text.empty?
 
-      def extract_tool_call_id
-        parent_tool_call&.tool_call_id
+        JSON.parse(text)
       end
 
-      def extract_content
-        return RubyLLM::Content::Raw.new(content_raw) if has_attribute?(:content_raw) && content_raw.present?
-
-        content_value = content
-        content_value = content_value.to_plain_text if content_value.respond_to?(:to_plain_text)
-
-        return content_value unless respond_to?(:attachments) && attachments.attached?
-
-        RubyLLM::Content.new(content_value).tap do |content_obj|
-          @_tempfiles = []
+      private
 
-          attachments.each do |attachment|
-            tempfile = download_attachment(attachment)
-            content_obj.add_attachment(tempfile, filename: attachment.filename.to_s)
-          end
-        end
+      def optional_column(name)
+        self[name] if has_attribute?(name)
       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
+      def extract_content
+        plain_text_content(content)
+      end
 
-        attachment.download { |chunk| tempfile.write(chunk) }
+      def extract_attachments
+        action_text_attachments = action_text_attachment_sources(content)
+        return [] unless content_attachments?(action_text_attachments)
 
-        tempfile.flush
-        tempfile.rewind
-        @_tempfiles << tempfile
-        tempfile
+        @_tempfiles = []
+        collect_attachments(action_text_attachments)
       end
     end
   end

data/lib/ruby_llm/active_record/model.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+
+module RubyLLM
+  module ActiveRecord
+    # A row of the +ruby_llm_models+ table, one per registry entry. Chats
+    # point at it through +belongs_to :model+. The +listed+ scope returns the
+    # models the provider still serves; +unlisted+ returns the ones kept only
+    # because a chat references them.
+    class Model < ::ActiveRecord::Base
+      self.table_name = 'ruby_llm_models'
+
+      validates :model_id, presence: true, uniqueness: { scope: :provider }
+      validates :provider, :name, presence: true
+
+      scope :listed, -> { where(unlisted_at: nil) }
+      scope :unlisted, -> { where.not(unlisted_at: nil) }
+
+      UNLISTED_WARNING_LIMIT = 5 # :nodoc:
+
+      class << self
+        def read # :nodoc:
+          return [] unless table_exists?
+
+          all.map(&:to_llm)
+        rescue StandardError => e
+          RubyLLM.logger.debug { "Failed to load models from database: #{e.message}, falling back to JSON" }
+          []
+        end
+
+        def write(registry) # :nodoc:
+          save_to_database(registry)
+        end
+
+        def description # :nodoc:
+          "database:#{table_name}"
+        end
+
+        def refresh # :nodoc:
+          RubyLLM.models.refresh
+        end
+
+        def save_to_database(registry = RubyLLM.models) # :nodoc:
+          transaction do
+            kept = registry.all.map do |model_info|
+              model = find_or_initialize_by(model_id: model_info.id, provider: model_info.provider)
+              model.update!(attributes_from_llm(model_info))
+              model.id
+            end
+            unlist(kept)
+          end
+        end
+
+        def from_llm(model_info) # :nodoc:
+          new(attributes_from_llm(model_info))
+        end
+
+        private
+
+        # A refresh replaces the registry, so models it no longer carries go
+        # away. A row an application record points at cannot: deleting it would
+        # dangle the reference. That row is stamped unlisted instead, keeping
+        # the chats that use it resolvable while the application migrates them.
+        def unlist(kept_ids)
+          stayed = []
+          where.not(id: kept_ids).find_each do |model|
+            transaction(requires_new: true) { model.destroy! }
+          rescue ::ActiveRecord::InvalidForeignKey
+            model.update!(unlisted_at: Time.current) unless model.unlisted_at
+            stayed << "#{model.provider}/#{model.model_id}"
+          end
+          warn_unlisted(stayed)
+        end
+
+        def warn_unlisted(names)
+          return if names.empty?
+
+          subject = names.size == 1 ? '1 model is' : "#{names.size} models are"
+          RubyLLM.logger.warn do
+            "#{subject} no longer listed by the provider and may no longer work: #{unlisted_listing(names)}. " \
+              'The rows stay because application records still reference them. The provider may have dropped ' \
+              'them, or your configured region may not offer them.'
+          end
+        end
+
+        def unlisted_listing(names)
+          extra = names.size - UNLISTED_WARNING_LIMIT
+          listing = names.first(UNLISTED_WARNING_LIMIT).join(', ')
+          extra.positive? ? "#{listing}, and #{extra} more" : listing
+        end
+
+        def attributes_from_llm(model_info)
+          {
+            model_id: model_info.id,
+            name: model_info.name,
+            provider: model_info.provider,
+            family: model_info.family,
+            model_created_at: model_info.created_at,
+            context_window: model_info.context_window,
+            max_output_tokens: model_info.max_output_tokens,
+            knowledge_cutoff: model_info.knowledge_cutoff,
+            modalities: model_info.modalities.to_h,
+            capabilities: model_info.capabilities,
+            pricing: model_info.pricing.to_h,
+            metadata: model_info.metadata,
+            unlisted_at: nil
+          }
+        end
+      end
+
+      # Returns this registry record as a RubyLLM::Model.
+      def to_llm
+        RubyLLM::Model.new(
+          id: model_id,
+          name: name,
+          provider: provider,
+          family: family,
+          created_at: model_created_at,
+          context_window: context_window,
+          max_output_tokens: max_output_tokens,
+          knowledge_cutoff: knowledge_cutoff,
+          modalities: modalities&.deep_symbolize_keys || {},
+          capabilities: capabilities,
+          pricing: pricing&.deep_symbolize_keys || {},
+          metadata: metadata&.deep_symbolize_keys || {},
+          unlisted_at: unlisted_at
+        )
+      end
+
+      # Registry readers answered from the RubyLLM::Model value of the row.
+      delegate :supports?, :price, :type, :provider_class, :label, :cost_for, :unlisted?, to: :to_llm
+    end
+  end
+end

data/lib/ruby_llm/active_record/payload_helpers.rb

@@ -5,8 +5,7 @@ require 'json'
 
 module RubyLLM
   module ActiveRecord
-    # Shared helpers for parsing serialized payloads on ActiveRecord-backed models.
-    module PayloadHelpers
+    module PayloadHelpers # :nodoc:
       private
 
       def payload_error_message(value)

data/lib/ruby_llm/active_record/tool_call.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'ruby_llm/active_record/payload_helpers'
+
+module RubyLLM
+  module ActiveRecord
+    # RubyLLM's private persistence for provider tool calls.
+    class ToolCall < ::ActiveRecord::Base # :nodoc:
+      self.table_name = 'ruby_llm_tool_calls'
+
+      include PayloadHelpers
+
+      belongs_to :message, polymorphic: true
+      belongs_to :result, polymorphic: true, optional: true
+
+      validates :tool_call_id, :name, presence: true
+
+      def to_llm
+        RubyLLM::ToolCall.new(
+          id: tool_call_id,
+          name: name,
+          arguments: arguments || {},
+          thought_signature: thought_signature,
+          remote: self[:remote]
+        )
+      end
+
+      def tool_error_message
+        payload_error_message(arguments)
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/usage.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # RubyLLM's private normalized persistence for one provider attempt.
+    class Usage < ::ActiveRecord::Base # :nodoc:
+      self.table_name = 'ruby_llm_usages'
+
+      belongs_to :chat, polymorphic: true
+      belongs_to :message, polymorphic: true, optional: true
+
+      validates :operation, inclusion: { in: ::RubyLLM::Accounting::Usage::Entry::OPERATIONS.map(&:to_s) }
+      validates :status, inclusion: { in: ::RubyLLM::Accounting::Usage::Entry::STATUSES.map(&:to_s) }
+      validates :provider, :model, presence: true
+
+      scope :chronological, -> { order(created_at: :asc, id: :asc) }
+
+      def tokens
+        RubyLLM::Tokens.new(
+          input: input_tokens,
+          output: output_tokens,
+          cache_read: cache_read_tokens,
+          cache_write: cache_write_tokens,
+          thinking: thinking_tokens
+        )
+      end
+
+      def cost
+        recorded = {
+          input: input_cost,
+          output: output_cost,
+          cache_read: cache_read_cost,
+          cache_write: cache_write_cost,
+          thinking: thinking_cost,
+          total: total_cost
+        }.compact
+        RubyLLM::Cost.from_h(recorded, tokens: tokens)
+      end
+
+      def usage_available?
+        tokens.to_h.any?
+      end
+
+      def cost_available?
+        !total_cost.nil?
+      end
+
+      def to_entry
+        ::RubyLLM::Accounting::Usage::Entry.new(
+          operation: operation,
+          provider: provider,
+          model: model,
+          status: status,
+          tokens: tokens,
+          cost: cost,
+          message: message
+        )
+      end
+    end
+  end
+end