ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/active_record/chat_placeholders.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Keeps the assistant record a run writes its answer into. An answer
+    # the provider paused keeps its record, with the continuation that
+    # resumes it, so a later run continues it instead of starting again.
+    module ChatPlaceholders # :nodoc:
+      def persist_message_progress(message) # :nodoc:
+        return unless @message.has_attribute?(:continuation)
+
+        transaction do
+          @message.update!(message_attributes(message))
+          link_usage_entries(message)
+        end
+      end
+
+      private
+
+      def persist_new_message
+        unfinished = unfinished_message_record
+        return @message = unfinished if unfinished
+
+        @message.destroy if blank_placeholder?
+        remove_abandoned_placeholder
+
+        attrs = { role: :assistant, content: '' }
+        @message = messages_association.create!(attrs)
+        @last_message_id = @message.id
+        @message
+      end
+
+      def blank_placeholder?
+        return false unless @message&.persisted? && @message.content.blank?
+        return false unless @message.role.to_s == 'assistant'
+        return false if unfinished_record?(@message)
+        return false if @message.respond_to?(:attachments) && @message.attachments.attached?
+
+        !@message.ruby_llm_tool_calls.exists?
+      end
+
+      # A process killed before its reply arrived leaves its placeholder
+      # last, and the run that takes over the chat's claim writes a reply
+      # of its own, so it removes that one. A reply the model gave records
+      # usage, even a blank one. The claim is renewed first, so a run that
+      # lost it never removes the placeholder of the run that took over.
+      def remove_abandoned_placeholder
+        return unless @run_claim_token
+
+        transaction do
+          renew_run_claim(force: true)
+          record = messages_association.order(:id).last
+          record.destroy if to_llm.send(:placeholder?, record&.to_llm) && !record.ruby_llm_usages.exists?
+        end
+      end
+
+      def unfinished_message_record
+        record = messages_association.order(:id).last
+        record if record&.role.to_s == 'assistant' && unfinished_record?(record)
+      end
+
+      def unfinished_record?(record)
+        record.has_attribute?(:continuation) && record.continuation.present?
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_questions.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # The questions a persisted chat waits on, kept on its tool call rows:
+    # approvals, and the questions tools and MCP servers ask (see
+    # RubyLLM::Question). Any process reads them from the database, without
+    # building the chat, and records answers on those rows under a row
+    # lock, so a web request can answer what a job asked and another job
+    # can carry the call on. ChatMethods includes it.
+    #
+    #   chat.pending_questions.each { |question| render "questions/question", question: }
+    #   chat.answer(params[:question_id], params[:answer])
+    #   ChatResponseJob.perform_later(chat.id)
+    #
+    module ChatQuestions
+      # Returns the questions the chat waits on a person to answer, as
+      # RubyLLM::Question objects in the order the model made their calls:
+      # approvals, and the questions tools and MCP servers ask, as
+      # RubyLLM::Chat#pending_questions describes. It reads the database
+      # only, so it never builds the chat's tools or connects to its MCP
+      # servers, and it lists what any process recorded. Each question
+      # records its answer on this chat.
+      #
+      # Whether a call requires approval is decided when it is saved, by the
+      # process that received it, so a call whose tool decides with a
+      # Tool.requires_approval block stays listed until the chat runs again.
+      def pending_questions
+        approvals = persisted_pending_approvals.to_a
+        rows = RubyLLM::ActiveRecord::ToolCall.uncached { chat_tool_calls.where(result_id: nil).order(:created_at, :id).to_a }
+        rows.flat_map do |row|
+          tool_call = row.to_llm
+          next [RubyLLM::Question.approval(tool_call, chat: self)] if approvals.include?(row)
+
+          Array(row.mcp_state&.[]('requests')).filter_map do |data|
+            RubyLLM::Question.from_h(data, tool_call:, chat: self) unless data['response']
+          end
+        end
+      end
+
+      # Answers +question+, a RubyLLM::Question from #pending_questions or
+      # its id, on its tool call record, so the next +complete+ in any
+      # process carries the call on, as RubyLLM::Chat#answer describes.
+      # Answering an approval approves it, as +approve+ does, unless another
+      # decision came first, in this process or another. Takes the
+      # ActionController::Parameters a form sends for several fields, and
+      # keeps only those the question asks for. Returns +self+.
+      #
+      #   chat.answer(params[:question_id], params[:answer])
+      #
+      # Raises ArgumentError for a question the chat never asked, and for an
+      # answer the question can't take.
+      def answer(question, value = nil, **values)
+        pending = persisted_pending_question(question)
+        response = pending&.response_to(value, values)
+        return self unless pending && settle_persisted_question(pending, response)
+
+        question.respond(response) if question.is_a?(RubyLLM::Question)
+        self
+      end
+
+      # Declines +question+, a RubyLLM::Question from #pending_questions,
+      # its id, or the call of an approval, on its tool call record, as
+      # RubyLLM::Chat#decline describes, unless another decision came
+      # first. The +note+ persists with it, so whichever process carries
+      # the call on gives the model the same note. A call saved waiting for
+      # approval before 2.2 is declined by its id, as +approve+ approves
+      # it, though #pending_questions leaves it out. Returns +self+.
+      #
+      #   chat.decline(params[:question_id], params[:note])
+      #
+      # Raises ArgumentError for a question the chat never asked, and
+      # RubyLLM::ToolCallRunningError for an approval still pending whose
+      # call is already running.
+      def decline(question, note = nil)
+        pending = persisted_pending_question(question) || unmarked_approval(question)
+        response = RubyLLM::Question.declined(note)
+        return self unless pending && settle_persisted_question(pending, response)
+
+        question.respond(response) if question.is_a?(RubyLLM::Question)
+        self
+      end
+
+      def settle_persisted_input(tool_call) # :nodoc:
+        transaction do
+          # Writing first takes the row's lock on every database, SQLite
+          # included, so the state read next is the latest.
+          scope = chat_tool_calls.where(tool_call_id: tool_call.id, result_id: nil)
+          next unless scope.update_all(updated_at: Time.current) == 1
+
+          locked = RubyLLM::ActiveRecord::ToolCall.uncached { scope.lock.take }
+          next if locked.mcp_state.nil?
+
+          settled = yield(locked.mcp_state)
+          next if settled == locked.mcp_state
+
+          forget_stale_cancellation
+          locked.update!(mcp_state: settled)
+        end
+      end
+
+      # Returns the note +tool_call+ was declined with while it waits for
+      # its refusal. It is kept in +mcp_result+, which the call's result
+      # replaces, and never in +mcp_state+, where a note would look like
+      # a question the call waits on.
+      def persisted_decline_note(tool_call) # :nodoc:
+        RubyLLM::ActiveRecord::ToolCall.uncached { find_tool_call(tool_call.id) }&.mcp_result&.[]('note')
+      end
+
+      def record_persisted_decline_note(id, note) # :nodoc:
+        chat_tool_calls.where(tool_call_id: id, result_id: nil)
+                       .update_all(mcp_result: { 'note' => note }, updated_at: Time.current)
+      end
+
+      private
+
+      def persisted_pending_question(question)
+        id = persisted_question_id(question)
+        pending_questions.find { |pending| pending.id == id } ||
+          (persisted_question?(id) ? nil : raise(ArgumentError, "Unknown question: #{id.inspect}"))
+      end
+
+      def persisted_question_id(question)
+        id = question.respond_to?(:tool_call_id) ? question.tool_call_id : question
+        (id.respond_to?(:id) ? id.id : id).to_s
+      end
+
+      # A call saved before 2.2 waits for approval with no +pending+ mark,
+      # so #pending_questions can't list it, but it can be declined as
+      # +approve+ approves it.
+      def unmarked_approval(question)
+        record = RubyLLM::ActiveRecord::ToolCall.uncached { find_tool_call(persisted_question_id(question)) }
+        return unless record && record.approval.nil? && record.result_id.nil?
+
+        RubyLLM::Question.approval(record.to_llm, chat: self)
+      end
+
+      def persisted_question?(id)
+        RubyLLM::ActiveRecord::ToolCall.uncached do
+          [id, id.rpartition('/').first].any? { |tool_call_id| find_tool_call(tool_call_id) }
+        end
+      end
+
+      def record_persisted_answer(question, response)
+        settle_persisted_input(question.tool_call) { |input| question.answered_input(input, response) }
+      end
+
+      # Records +response+ to +question+ and returns whether it did. An
+      # approval is approved or denied only while it still waits, so of
+      # two people deciding at once, in any processes, the first one's
+      # decision stands.
+      def settle_persisted_question(question, response)
+        unless question.approval?
+          record_persisted_answer(question, response)
+          return true
+        end
+
+        waiting = RubyLLM::ActiveRecord::ToolCall.where(id: tool_call_record(question.tool_call.id).id,
+                                                        approval: ['pending', nil], result_id: nil)
+        transaction do
+          # Writing first takes the row's lock on every database, SQLite
+          # included, so a decision made at the same time waits for this
+          # one and then finds the call decided.
+          next false unless waiting.update_all(updated_at: Time.current) == 1
+
+          response == RubyLLM::Question::ACCEPTED ? approve(question) : refuse(question, response['note'])
+          true
+        end
+      end
+
+      def refuse(question, note)
+        record_tool_call_decision(question.tool_call, 'denied')
+        record_persisted_decline_note(question.tool_call.id, note) if note
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_queue.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'ruby_llm/active_record/attachment_helpers'
+
+module RubyLLM
+  module ActiveRecord
+    # Keeps a persisted chat's queued messages in +ruby_llm_queued_messages+,
+    # so any process can queue one and the process running the chat takes
+    # it. Taking or withdrawing deletes the row, and only the process whose
+    # delete removes it goes on, so each message joins once or not at all.
+    # Joining runs Chat#around_join inside the transaction that deletes the
+    # row, so a callback that raises puts the row back. The message record
+    # gets the row's sender when its model has a +sender+ association.
+    class ChatQueue # :nodoc:
+      include AttachmentHelpers
+
+      def initialize(chat)
+        @chat = chat
+      end
+
+      def push(content:, attachments:, steer:, sender:)
+        QueuedMessage.transaction do
+          @chat.forget_stale_cancellation
+          queued = rows.create!(content:, steer:, sender:)
+          persist_content(queued, attachments) unless attachments.nil?
+          queued
+        end
+      end
+
+      def delete(queued)
+        id = queued.respond_to?(:id) ? queued.id : queued
+        record = read { rows.find_by(id:) }
+        record if record&.withdraw
+      end
+
+      def to_a
+        read { rows.to_a }
+      end
+
+      def none?(steering_only: false)
+        !available? || read { !scope(steering_only).exists? }
+      end
+
+      def take(steering_only: false)
+        return unless available?
+
+        read { scope(steering_only).to_a }.each do |queued|
+          taken = take_one(queued)
+          yield taken.first, queued if taken
+        end
+      end
+
+      private
+
+      def take_one(queued)
+        taken = nil
+        QueuedMessage.transaction do
+          next unless QueuedMessage.where(id: queued.id).delete_all == 1
+
+          taken = [@chat.to_llm.run_around_join(queued) { |**attributes| join(queued, attributes) }]
+        rescue StandardError
+          @chat.messages_association.reset
+          raise
+        end
+        queued.attachments.purge_later if taken == [nil] && attachments?(queued)
+        taken
+      end
+
+      def join(queued, attributes)
+        blobs = queued.attachments.blobs.to_a if attachments?(queued)
+        message = @chat.persist_message({ role: :user, content: queued.content, attachments: blobs },
+                                        sender_attributes(queued).merge(attributes))
+        detach(queued) if blobs
+        message
+      end
+
+      def sender_attributes(queued)
+        association = @chat.messages_association.klass.reflect_on_association(:sender)
+        sender = queued_sender(queued) if association
+        return {} unless sender && (association.polymorphic? || sender.is_a?(association.klass))
+
+        { sender: }
+      end
+
+      # Nil once the sender's class, or the subclass its row names, is
+      # gone, say renamed since the message was queued, so the message
+      # joins without its sender instead of holding up the queue.
+      def queued_sender(queued)
+        queued.sender
+      rescue NameError, ::ActiveRecord::SubclassNotFound
+        nil
+      end
+
+      def detach(queued)
+        ActiveStorage::Attachment.where(record_type: QueuedMessage.polymorphic_name, record_id: queued.id,
+                                        name: 'attachments').delete_all
+      end
+
+      def scope(steering_only)
+        steering_only ? rows.where(steer: true) : rows
+      end
+
+      def rows
+        @chat.ruby_llm_queued_messages.scope
+      end
+
+      def read(&)
+        QueuedMessage.uncached(&)
+      end
+
+      def attachments?(queued)
+        queued.respond_to?(:attachments) && queued.attachments.attached?
+      end
+
+      def available?
+        @chat.persisted? && QueuedMessage.table_exists?
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_reply_error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Keeps a message for the person about the last failed reply in the
+    # chats table's +reply_error+ column, when it has one, so the chat's
+    # page shows it however its broadcasts arrive. A failed run writes it,
+    # and the next run clears it. A stop is not a failure.
+    module ChatReplyError # :nodoc:
+      MESSAGES = {
+        failed: 'The reply failed. Send your message again.',
+        too_long: 'This conversation is too long for the model. Start a new chat.'
+      }.freeze
+
+      private
+
+      def clear_reply_error
+        update_columns(reply_error: nil) if reply_error_column? && self[:reply_error]
+      end
+
+      def record_reply_error(error)
+        return if error.is_a?(CancelledError) || !reply_error_column?
+
+        key = error.is_a?(ContextLengthExceededError) ? :too_long : :failed
+        update_columns(reply_error: I18n.t(key, scope: %i[ruby_llm reply_error], default: MESSAGES[key]))
+      rescue StandardError => e
+        RubyLLM.logger.warn("RubyLLM could not save the reply error: #{e.class}: #{e.message}")
+      end
+
+      def reply_error_column?
+        persisted? && has_attribute?(:reply_error)
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_run.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Connects a persisted chat's conversation loop to its record: usage
+    # and progress land in the database, each cancellation checkpoint
+    # renews the run claim and polls for a request from another process,
+    # losing the claim ends the run, and the owner is the record that
+    # +acts_as_chat owner:+ names.
+    class ChatRun < Chat::Run # :nodoc:
+      def initialize(chat)
+        super()
+        @chat = chat
+      end
+
+      def record_usage(entry)
+        @chat.persist_usage_entry(entry)
+      end
+
+      def record_progress(partial)
+        @chat.persist_message_progress(partial)
+      end
+
+      def chat_id
+        @chat.id
+      end
+
+      # Stable across processes and opaque: the provider sees neither the
+      # table nor the id.
+      def cache_key
+        id = @chat.id
+        return unless id
+
+        "ruby_llm-#{Digest::SHA256.hexdigest("#{@chat.class.base_class.name}/#{id}")[0, 32]}"
+      end
+
+      def owner
+        name = @chat.class.owner_association_name
+        @chat.public_send(name) if name
+      end
+
+      def cancellation_requested?
+        @chat.poll_run_cancellation == :cancelled
+      end
+
+      def interrupted_by?(error)
+        @chat.run_claim_lost?(error)
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chat_tool_call_state.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Keeps a persisted chat's tool call state on its
+    # +ruby_llm_tool_calls+ rows, read outside the query cache, so every
+    # process sees the same state.
+    class ChatToolCallState < Chat::ToolCallState # :nodoc:
+      def initialize(chat)
+        super()
+        @chat = chat
+        @contested = []
+      end
+
+      def input(tool_call)
+        record = RubyLLM::ActiveRecord::ToolCall.uncached { @chat.find_tool_call(tool_call.id) }
+        record.mcp_state if record&.has_attribute?(:mcp_state)
+      end
+
+      def record_input(tool_call, input)
+        record = RubyLLM::ActiveRecord::ToolCall.uncached { @chat.find_tool_call(tool_call.id) }
+        return if !record&.has_attribute?(:mcp_state) || record.mcp_state == input
+
+        @chat.transaction do
+          @chat.forget_stale_cancellation
+          record.update!(mcp_state: input)
+        end
+      end
+
+      def decline_note(tool_call)
+        @chat.persisted_decline_note(tool_call)
+      end
+
+      def record_decline_note(tool_call, note)
+        @chat.record_persisted_decline_note(tool_call.id, note)
+      end
+
+      def settle(tool_call, &)
+        @chat.settle_persisted_input(tool_call, &)
+      end
+
+      def decision(tool_call)
+        decided = super
+        decided.nil? ? @chat.persisted_tool_call_approval(tool_call) : decided
+      end
+
+      def remembered?(call)
+        super || @chat.persisted_remembered_tool?(call)
+      end
+
+      def claim(requested, executing:)
+        @contested = []
+        return requested if requested.empty?
+
+        claimed = @chat.claim_persisted_tool_calls(yield, executing:)
+        @contested = requested - claimed
+        claimed
+      end
+
+      def release(ids, stopped_by = nil, finished: false)
+        @chat.release_persisted_tool_calls(ids, stopped_by, finished:)
+      end
+
+      def started(tool_call)
+        @chat.persisted_tool_call_started(tool_call.id)
+      end
+
+      def interrupted?(tool_call)
+        @chat.persisted_tool_call_interrupted?(tool_call.id)
+      end
+
+      def running_elsewhere?(tool_call)
+        @contested.include?(tool_call.id) && @chat.tool_call_running_elsewhere?(tool_call)
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/chunk_methods.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Gives each RubyLLM::Chunk streamed from a persisted chat the message
+    # record it streams into.
+    #
+    #   chat.ask("Tell me a story", &:broadcast)
+    #
+    module ChunkMethods
+      BROADCASTING_OFF = 'Messages do not broadcast. Set config.broadcast_messages = true in the ' \
+                         'RubyLLM initializer, or pass broadcasts: true to acts_as_message, with ' \
+                         'turbo-rails and Action Cable loaded.' # :nodoc:
+
+      # Returns a block that gives each chunk the record +message+ returns
+      # before passing it to +block+, or +nil+ without a block. Calls
+      # +on_error+ when +block+ raises, then re-raises the error.
+      def self.streaming(block, on_error: nil, &message) # :nodoc:
+        return unless block
+
+        lambda do |chunk|
+          block.call(attach(chunk, message.call))
+        rescue StandardError
+          on_error&.call
+          raise
+        end
+      end
+
+      # Gives +chunk+ the record +message+ it streams into. Returns +chunk+.
+      def self.attach(chunk, message) # :nodoc:
+        chunk.extend(ChunkMethods)
+        chunk.message = message
+        chunk
+      end
+
+      # Returns the persisted message record this chunk streams into.
+      attr_accessor :message
+
+      # Appends this chunk to its message on the chat's page. See
+      # MessageBroadcasting#broadcast_chunk. Raises
+      # RubyLLM::ConfigurationError when the message does not broadcast.
+      def broadcast
+        raise RubyLLM::ConfigurationError, BROADCASTING_OFF unless message.respond_to?(:broadcast_chunk)
+
+        message.broadcast_chunk(self)
+      end
+    end
+  end
+end