module RubyLLM::ActiveRecord::ChatMethods

Persists message_or_attributes as a message record, including any attachments and tool calls. Accepts a RubyLLM::Message, an attributes Hash, or a record responding to to_llm. Returns the message record.

chat.add_message(role: :user, content: long_context)

Applies Chat#after_dequeue and returns this record. The block receives the message record and the QueuedMessage record, in the process that runs the chat.

Applies Chat#after_fallback and returns this record.

Applies Chat#after_file_write and returns this record.

Applies Chat#after_message and returns this record.

Applies Chat#after_queue and returns this record. The block receives the QueuedMessage record, in the process that queued it.

Applies Chat#after_tool_progress and returns this record.

Applies Chat#after_tool_result and returns this record.

Applies Chat#after_unqueue and returns this record. The block receives the QueuedMessage record, in the process that unqueued it.

Applies Chat#answer and returns this record. The answer persists on the tool call, so any process can resume the call.

Records approval for tool_call (a ToolCall, a tool call record, or an id) on the persisted tool call, so the next complete executes it from any process. Approving a call that is running or answered changes nothing. With remember: true, later calls to the same tool run without asking for the rest of the chat, as RubyLLM::Chat#approve describes, in every process. Returns self.

chat.approve(params[:tool_call_id])
chat.approve(params[:tool_call_id], remember: true)
CompleteJob.perform_later(chat.id)

Persists message as a user message, after every queued message (see queue), then runs the conversation loop and returns the latest assistant RubyLLM::Message. The loop pauses when awaiting_approval? is true. Yields streaming chunks to a block.

chat.ask "What is the capital of France?"
chat.ask "What's in this file?", with: "diagram.png"

Persists message as a user message without calling the model, so complete can run later. Every queued message (see queue) is persisted first, in order. Returns self.

chat.ask_later "Summarize this document."
chat.complete

Returns whether the conversation is waiting on tool calls that require approval and have no recorded decision. See RubyLLM::Chat#awaiting_approval?.

Delegates to Chat#awaiting_input?. See that method for arguments and return values.

Delegates to Chat#awaiting_tasks?. See that method for arguments and return values.

Applies Chat#before_fallback and returns this record.

Applies Chat#before_message and returns this record.

Applies Chat#before_request and returns this record.

Applies Chat#before_tool_call and returns this record.

Marks the latest persisted message as a prompt cache boundary, or the latest in-memory message when none is persisted yet. Pass ttl: to give the boundary its own cache lifetime. Returns self.

chat.with_instructions('Reusable analysis prompt').cache_until_here
chat.with_instructions('Reusable analysis prompt').cache_until_here(ttl: "1h")

Raises ArgumentError if the chat has no messages.

Delegates to Chat#caching. See that method for arguments and return values.

Requests cancellation of the current in-flight chat operation. The request is persisted so a background job can observe it from another process.

Returns whether this record or its memoized in-memory chat has a pending cancellation request.

Delegates to Chat#citations. See that method for arguments and return values.

Delegates to Chat#code_execution. See that method for arguments and return values.

Compacts the model context and persists its assistant Message without deleting earlier messages. See RubyLLM::Chat#compact. Returns nil without calling the model while another process is running? the chat.

Delegates to Chat#compaction. See that method for arguments and return values.

Runs the completion loop on the underlying chat, persisting each message, and returns the latest RubyLLM::Message. Pauses when a tool requires approval. 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 an MCP input request 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 or running tools, and waiting? is true. Work recorded while this process ran, such as an approval, continues before it returns.

Each chunk passed to the block also answers message, the record it streams into, and broadcast (see ChunkMethods). When the messages broadcast with Turbo, the chat’s page refreshes once the run ends.

chat.complete(&:broadcast)

Queued messages join as RubyLLM::Chat#complete describes, including those another process queues while this one runs. A message that steers, queued as the run ends, starts another loop before complete returns.

Returns whether the conversation has no pending work, neither a response to generate nor tool calls to run. See RubyLLM::Chat#complete?.

Delegates to Chat#concurrency. See that method for arguments and return values.

Applies Chat#convert_unsupported_attachments and returns this record.

Returns a RubyLLM::Cost aggregating every persisted usage entry, including retries and attempts that did not produce a message.

chat.cost.total

Returns the number of input tokens the next request would carry, counted by the provider over the persisted conversation.

Applies Chat#decline and returns this record.

Delegates to Chat#deferred_tools. See that method for arguments and return values.

Records denial for tool_call (a ToolCall, a tool call record, or an id) on the persisted tool call. The next complete appends a structured denial result instead of executing the tool. Denying an answered call changes nothing. Returns self.

Raises RubyLLM::ToolCallRunningError when the call is already running.

Yields each message in the conversation. Returns an Enumerator without a block.

Delegates to Chat#end_user. See that method for arguments and return values.

Delegates to Chat#fallbacks. See that method for arguments and return values.

Delegates to Chat#file_store. See that method for arguments and return values.

Makes a single generation attempt, persists the response, and returns it as a RubyLLM::Message. Tool calls in the response are not executed. See RubyLLM::Chat#generate. Returns nil without calling the model while another process is running? the chat. A block receives the chunks as it does in complete.

Delegates to Chat#headers. See that method for arguments and return values.

Delegates to Chat#max_output_tokens. See that method for arguments and return values.

Delegates to Chat#mcp. See that method for arguments and return values.

Sets the chat’s model from an id, a RubyLLM::Model value, or the associated internal model record.

chat.model = 'gpt-6-luna'

Returns the model id assigned since the last save, or that of the associated model record, or nil.

chat.model_id # => "gpt-6-luna"

Stores value as the model id, resolved to a model record before save.

Returns the persisted tool call records that require approval and have no recorded decision, ready to render as approval cards. Pass a record (or its tool_call_id) to approve or deny. A record’s remote? identifies a provider-executed call. Records come in the order the model made the calls.

chat.pending_approvals.each { |record| render record }

Delegates to Chat#pending_inputs. Requests persist on their tool calls, so they survive restarts.

Delegates to Chat#pending_tasks. Tasks persist on their tool calls, so any process can check on them and resume the chat.

Sets the protocol override, switching the underlying chat to it when that is already built.

Returns the provider assigned since the last save, or that of the associated model record, or nil. A model id assigned without a provider has none until save resolves it.

Stores value as the provider used when resolving the model id before save.

Delegates to Chat#provider_options. See that method for arguments and return values.

Delegates to Chat#provider_tools. See that method for arguments and return values.

Queues message in the chat’s ruby_llm_queued_messages table, as RubyLLM::Chat#queue describes, and returns the QueuedMessage record. Attachments given with with: are stored with Active Storage and move to the message it becomes. owner is any record, such as the user who asked; it is stored and handed back, never interpreted.

Any process can queue a message. The process that runs the chat takes it at its next step; when none is running, run complete, usually in a job.

chat.queue params[:content], owner: Current.user
ChatResponseJob.perform_later(chat.id) unless chat.running?

Returns the QueuedMessage records waiting in the queue, oldest first, ready to render.

Reloads the record from the database, Rails-style, and refreshes the underlying chat’s persisted message history to match. Runtime-only configuration such as tools, temperature, and callbacks is preserved; a model or provider assigned since the last save is discarded. Returns self.

Returns the next request payload with before_request hooks applied.

Executes the pending tool calls and persists their results without calling the model. See RubyLLM::Chat#run_tools. Does nothing while another process is running? the chat. Returns self.

Returns whether a process is running this chat’s conversation loop: calling the model or running tools from complete, step, generate, run_tools, or compact. Reads the database, so it sees runs in other processes. While another process runs the chat, those methods return without doing anything and waiting? is true.

CompleteJob.set(wait: 1.minute).perform_later(chat.id) if chat.running?

Delegates to Chat#schema. See that method for arguments and return values.

Delegates to Chat#skills. See that method for arguments and return values.

Advances the conversation by one move: runs the pending tool calls if there are any, otherwise generates a response. Returns nil once the chat is complete or waiting?, including while another process is running? it. See RubyLLM::Chat#step. A block receives the chunks as it does in complete.

chat.step until chat.complete? || chat.waiting?

Delegates to Chat#temperature. See that method for arguments and return values.

Delegates to Chat#thinking. See that method for arguments and return values.

Returns the underlying RubyLLM::Chat for this record, building it on first call and memoizing it. The chat is loaded with the persisted messages and wired to persist new ones. Subsequent calls return the same chat without touching the database, switched to any model assigned since; use reload to refresh its message history from the record.

Returns token usage aggregated across every persisted usage entry, including retries and attempts that did not produce a message.

chat.tokens.input

Delegates to Chat#tool_options. See that method for arguments and return values.

Delegates to Chat#tools. See that method for arguments and return values.

Takes queued, a QueuedMessage record or its id, out of the queue and deletes its attachments. Returns true, or false once the loop has taken it into the conversation or it was unqueued already. See RubyLLM::Chat#unqueue.

Returns whether the conversation can’t continue until something outside it happens, as RubyLLM::Chat#waiting? describes, or until the process that is running? it finishes. Approvals, answers, and tasks persist on their tool calls, so any process sees what the chat waits on.

Applies Chat#with_caching and returns this record.

Applies Chat#with_citations and returns this record.

Applies Chat#with_code_execution and returns this record.

Applies Chat#with_compaction and returns this record.

Rebinds the underlying chat to value so subsequent requests use its configuration. Pass nil to return to the global RubyLLM configuration. The Context itself is runtime-only and is not persisted.

Applies Chat#with_end_user and returns this record.

Applies Chat#with_fallbacks and returns this record.

Applies Chat#with_headers and returns this record.

Sets the system instructions, persisting them as a message with the :system role. Replaces any persisted system messages unless append: is true. Pass persist: false to apply the instructions only to the in-memory chat for this record instance. With cache_until_here: true the instruction becomes an explicit prompt cache boundary, and cache_until_here: { ttl: "1h" } gives that boundary its own lifetime. Returns self.

chat.with_instructions "You are a Ruby expert."
chat.with_instructions "Use short bullet points.", append: true
chat.with_instructions current_context, persist: false

Applies Chat#with_max_output_tokens and returns this record.

Applies Chat#with_mcp and returns this record.

Switches the chat to model_name, resolving and saving the model record and updating the underlying chat. Falls back to the configured default model when model_name is nil. Pass protocol: to override the wire protocol the provider would pick for the model. Returns self.

chat.with_model 'claude-sonnet-5'

Applies Chat#with_provider_options and returns this record.

Applies Chat#with_provider_tools and returns this record.

Applies Chat#with_schema and returns this record.

Applies Chat#with_skills and returns this record.

Applies Chat#with_temperature and returns this record.

Applies Chat#with_thinking and returns this record.

Applies Chat#with_tool_options and returns this record.

Applies Chat#with_tools and returns this record.