class RubyLLM::Cost

A Cost prices token usage in US dollars using pricing from the model registry. Message#cost returns the cost of a single response, and Model#cost_for prices any token usage against a specific model.

response = chat.ask "Summarize Ruby's object model."
response.cost.total

cost = model.cost_for(response.tokens)
cost.input
cost.output

The components are RubyLLM’s normalized token buckets: input, output, cache_read, cache_write, and thinking. When the registry lacks pricing for tokens that were used, the affected component and total return nil instead of a false zero.

Public Class Methods

aggregate (costs)

Source

# File lib/ruby_llm/cost.rb, line 31
def self.aggregate(costs)
  Aggregate.build(costs)
end

Combines several costs into a Cost::Aggregate that sums each component across messages. Ignores nil entries.

cost = RubyLLM::Cost.aggregate(messages.map(&:cost))
cost.total

from_h (hash)

Source

# File lib/ruby_llm/cost.rb, line 42
def self.from_h(hash)
  amounts = COMPONENTS.to_h { |component| [component, hash[component] || hash[component.to_s]] }
  total_recorded = hash.key?(:total) || hash.key?('total')
  missing = total_recorded ? [] : COMPONENTS.reject { |component| amounts[component] }

  Aggregate.new(amounts:, missing:, tokens: amounts.values.any? { |amount| !amount.nil? })
end

Rebuilds a cost from a stored breakdown Hash, as produced by to_h and persisted alongside a message. Keys may be Strings or Symbols. Returns a Cost::Aggregate whose component readers return the recorded amounts and whose total equals the recorded :total.

RubyLLM::Cost.from_h(message.cost_details).total

Public Instance Methods

cache_read ()

Source

# File lib/ruby_llm/cost.rb, line 71
def cache_read
  amount_for(:cache_read)
end

Returns the cost of cache-read input tokens in US dollars, or nil when the token count or its pricing is unavailable.

cache_write ()

Source

# File lib/ruby_llm/cost.rb, line 77
def cache_write
  amount_for(:cache_write)
end

Returns the cost of cache-write input tokens in US dollars, or nil when the token count or its pricing is unavailable.

input ()

Source

# File lib/ruby_llm/cost.rb, line 59
def input
  amount_for(:input)
end

Returns the cost of input tokens in US dollars, or nil when the token count or its pricing is unavailable.

output ()

Source

# File lib/ruby_llm/cost.rb, line 65
def output
  amount_for(:output)
end

Returns the cost of billable output tokens in US dollars, or nil when the token count or its pricing is unavailable.

thinking ()

Source

# File lib/ruby_llm/cost.rb, line 85
def thinking
  amount_for(:thinking)
end

Returns the cost of thinking tokens in US dollars, or nil when the model does not price reasoning output separately from regular output or the token count is unavailable. When not priced separately, thinking tokens are part of output.

to_h ()

Source

# File lib/ruby_llm/cost.rb, line 104
def to_h
  {
    input: input,
    output: output,
    cache_read: cache_read,
    cache_write: cache_write,
    thinking: thinking,
    total: total
  }.compact
end

Returns a hash of component costs in US dollars, plus :total, omitting nil values.

total ()

Source

# File lib/ruby_llm/cost.rb, line 92
def total
  return nil unless tokens?
  return nil if COMPONENTS.any? { |component| missing?(component) }

  costs = COMPONENTS.filter_map { |component| public_send(component) }
  return nil if costs.empty?

  costs.sum
end

Returns the sum of all components in US dollars. Returns nil when there is no token usage, or when pricing is missing for tokens that were used.