module RubyLLM::ActiveRecord::MessageMethods

MessageMethods is mixed into models that call acts_as_message. It converts persisted records into RubyLLM::Message objects and adds token, cost, prompt-caching, and rendering helpers.

message = chat_record.messages.last
message.tokens.input
message.cost.total
message.cache_until_here!

Public Instance Methods

cache_read_tokens ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 119
def cache_read_tokens
  optional_column(:cache_read_tokens)
end

Returns the number of tokens served from the provider’s prompt cache. Reads the cache_read_tokens column.

cache_until_here! ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 61
def cache_until_here!
  update!(cache_until_here: true)
  self
end

Marks this message as a prompt-cache boundary and persists the flag. Providers may then cache the conversation up to and including this message. Returns self.

chat.add_message(role: :user, content: long_context).cache_until_here!
chat.messages.last.cache_until_here!

cache_until_here? ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 68
def cache_until_here?
  optional_column(:cache_until_here) || false
end

Returns whether this message is marked as a prompt-cache boundary. Reads the optional cache_until_here column.

cache_write_tokens ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 125
def cache_write_tokens
  optional_column(:cache_write_tokens)
end

Returns the number of tokens written to the provider’s prompt cache. Reads the cache_write_tokens column.

citations ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 83
def citations
  Array(optional_column(:citations)).map { |citation| RubyLLM::Citation.from_h(citation) }
end

Returns the persisted citations as an array of RubyLLM::Citation objects. Empty when the message has none.

cost ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 110
def cost
  details = optional_column(:cost_details)
  return RubyLLM::Cost.from_h(details) if details.present?

  RubyLLM::Cost.new(tokens:, model: model_association)
end

Returns a RubyLLM::Cost for this message. When the cost_details column recorded a breakdown at completion, returns that frozen cost so a later Models.refresh! does not rewrite it. Otherwise prices this message’s tokens against the associated model record’s current pricing.

message.cost.total

thinking ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 74
def thinking
  RubyLLM::Thinking.build(
    text: optional_column(:thinking_text),
    signature: optional_column(:thinking_signature)
  )
end

Returns the persisted reasoning as a RubyLLM::Thinking, or nil when the thinking columns are empty.

to_llm ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 38
def to_llm
  RubyLLM::Message.new(
    role: role.to_sym,
    content: extract_content,
    attachments: extract_attachments,
    thinking: thinking,
    citations: citations,
    tokens: tokens,
    tool_calls: extract_tool_calls,
    tool_call_id: extract_tool_call_id,
    finish_reason: optional_column(:finish_reason),
    model: model_association&.model_id,
    cache_until_here: cache_until_here?
  )
end

Converts this record to a RubyLLM::Message, rebuilding the role, content, attachments, thinking, citations, tokens, tool calls, and prompt-cache flag from the persisted columns.

to_partial_path ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 150
def to_partial_path
  partial_prefix = self.class.name.underscore.pluralize
  role_partial = if tool_call?
                   'tool_calls'
                 elsif role.to_s == 'tool'
                   'tool'
                 else
                   role.to_s.presence || 'assistant'
                 end
  "#{partial_prefix}/#{role_partial}"
end

Returns the partial path Rails uses to render this message. The prefix comes from the model class name. The suffix is the role, with tool_calls for assistant messages that invoke tools and tool for tool results.

render @chat.messages
# renders messages/_user, messages/_assistant, messages/_tool_calls, ...

tokens ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 93
def tokens
  RubyLLM::Tokens.build(
    input: input_tokens,
    output: output_tokens,
    cache_read: optional_column(:cache_read_tokens),
    cache_write: optional_column(:cache_write_tokens),
    thinking: optional_column(:thinking_tokens)
  )
end

Returns the persisted token counts as a RubyLLM::Tokens, or nil when no counts were recorded.

message.tokens.input
message.tokens.cache_read

tool_call? ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 131
def tool_call?
  tool_calls_association.any?
end

Returns whether this message recorded tool calls for the model to run. Answered from the associations, without building a RubyLLM::Message.

tool_error_message ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 164
def tool_error_message
  payload_error_message(content)
end

Returns the error message when this tool result recorded an error, nil otherwise.

tool_result? ()

Source

# File lib/ruby_llm/active_record/message_methods.rb, line 138
def tool_result?
  parent_tool_call.present?
end

Returns whether this message is a tool result answering an earlier tool call. Answered from the associations, without building a RubyLLM::Message.