Class: LLM::Usage

Inherits:
Object
  • Object
show all
Defined in:
lib/llm/usage.rb

Overview

The LLM::Usage class represents token usage for a given conversation or completion. As a conversation grows, so does the number of tokens used. This class helps track the number of input, output, reasoning, cache, and overall token count. It can also help track usage of the context window (which may vary by model).

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(input_tokens: 0, output_tokens: 0, reasoning_tokens: 0, input_audio_tokens: 0, output_audio_tokens: 0, input_image_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, total_tokens: 0) ⇒ LLM::Usage

Parameters:

  • input_tokens (Integer) (defaults to: 0)
  • output_tokens (Integer) (defaults to: 0)
  • reasoning_tokens (Integer) (defaults to: 0)
  • input_audio_tokens (Integer) (defaults to: 0)
  • output_audio_tokens (Integer) (defaults to: 0)
  • input_image_tokens (Integer) (defaults to: 0)
  • cache_read_tokens (Integer) (defaults to: 0)
  • cache_write_tokens (Integer) (defaults to: 0)
  • total_tokens (Integer) (defaults to: 0) 


51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/llm/usage.rb', line 51

def initialize(input_tokens: 0, output_tokens: 0, reasoning_tokens: 0,
               input_audio_tokens: 0, output_audio_tokens: 0,
               input_image_tokens: 0, cache_read_tokens: 0,
               cache_write_tokens: 0, total_tokens: 0)
  @input_tokens = input_tokens
  @output_tokens = output_tokens
  @reasoning_tokens = reasoning_tokens
  @input_audio_tokens = input_audio_tokens
  @output_audio_tokens = output_audio_tokens
  @input_image_tokens = input_image_tokens
  @cache_read_tokens = cache_read_tokens
  @cache_write_tokens = cache_write_tokens
  @total_tokens = total_tokens
end

Class Method Details

.from(obj) ⇒ LLM::Usage

Builds an LLM::Usage from any object that exposes the token fields (eg an Object carried by a message's response).

Parameters:

Returns:



17
18
19
20
21
22
23
24
25
26
 
# File 'lib/llm/usage.rb', line 17

def self.from(obj)
  if LLM::Usage === obj
    obj
  elsif obj.respond_to?(:to_h)
    new(**obj.to_h.transform_keys(&:to_sym))
  else
    raise TypeError, "The given object (an instance of '#{obj.class}') " \
                     "cannot be coerced into an LLM::Usage object"
  end
end

.zero ⇒ LLM::Usage

Returns:



30
31
32
33
34
35
36
37
38
 
# File 'lib/llm/usage.rb', line 30

def self.zero
  new(
    input_tokens: 0, output_tokens: 0,
    reasoning_tokens: 0, input_audio_tokens: 0,
    output_audio_tokens: 0, input_image_tokens: 0,
    cache_read_tokens: 0, cache_write_tokens: 0,
    total_tokens: 0
  )
end

Instance Method Details

#+(other) ⇒ LLM::Usage

Returns a new LLM::Usage that is the sum of this usage and another. Missing (nil) fields are zero.

Parameters:

Returns:



125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/llm/usage.rb', line 125

def +(other)
  other = self.class.from(other)
  LLM::Usage.new(
    input_tokens: input_tokens + other.input_tokens,
    output_tokens: output_tokens + other.output_tokens,
    reasoning_tokens: reasoning_tokens + other.reasoning_tokens,
    input_audio_tokens: input_audio_tokens + other.input_audio_tokens,
    output_audio_tokens: output_audio_tokens + other.output_audio_tokens,
    input_image_tokens: input_image_tokens + other.input_image_tokens,
    cache_read_tokens: cache_read_tokens + other.cache_read_tokens,
    cache_write_tokens: cache_write_tokens + other.cache_write_tokens,
    total_tokens: total_tokens + other.total_tokens
  )
end

#==(other) ⇒ Boolean Also known as: eql?

Returns true when two usages hold the same token counts

Returns:

  • (Boolean) —

    Returns true when two usages hold the same token counts



143
144
145
 
# File 'lib/llm/usage.rb', line 143

def ==(other)
  other.is_a?(LLM::Usage) and other.to_h == to_h
end

#cache_read_tokens ⇒ Integer

Returns:

  • (Integer) 


104
105
106
 
# File 'lib/llm/usage.rb', line 104

def cache_read_tokens
  @cache_read_tokens || 0
end

#cache_write_tokens ⇒ Integer

Returns:

  • (Integer) 


110
111
112
 
# File 'lib/llm/usage.rb', line 110

def cache_write_tokens
  @cache_write_tokens || 0
end

#hash ⇒ Integer

Returns a hash consistent with #eql?

Returns:

  • (Integer) —

    Returns a hash consistent with #eql?



151
152
153
 
# File 'lib/llm/usage.rb', line 151

def hash
  to_h.hash
end

#input_audio_tokens ⇒ Integer

Returns:

  • (Integer) 


86
87
88
 
# File 'lib/llm/usage.rb', line 86

def input_audio_tokens
  @input_audio_tokens || 0
end

#input_image_tokens ⇒ Integer

Returns:

  • (Integer) 


98
99
100
 
# File 'lib/llm/usage.rb', line 98

def input_image_tokens
  @input_image_tokens || 0
end

#input_tokens ⇒ Integer

Returns:

  • (Integer) 


68
69
70
 
# File 'lib/llm/usage.rb', line 68

def input_tokens
  @input_tokens || 0
end

#output_audio_tokens ⇒ Integer

Returns:

  • (Integer) 


92
93
94
 
# File 'lib/llm/usage.rb', line 92

def output_audio_tokens
  @output_audio_tokens || 0
end

#output_tokens ⇒ Integer

Returns:

  • (Integer) 


74
75
76
 
# File 'lib/llm/usage.rb', line 74

def output_tokens
  @output_tokens || 0
end

#reasoning_tokens ⇒ Integer

Returns:

  • (Integer) 


80
81
82
 
# File 'lib/llm/usage.rb', line 80

def reasoning_tokens
  @reasoning_tokens || 0
end

#to_h ⇒ Hash

Returns:

  • (Hash) 


157
158
159
160
161
162
163
164
 
# File 'lib/llm/usage.rb', line 157

def to_h
  {
    input_tokens:, output_tokens:,
    reasoning_tokens:,
    input_audio_tokens:, output_audio_tokens:, input_image_tokens:,
    cache_read_tokens:, cache_write_tokens:, total_tokens:
  }
end

#to_json ⇒ String

Returns:

  • (String) 


168
169
170
 
# File 'lib/llm/usage.rb', line 168

def to_json(...)
  LLM.json.dump(to_h, ...)
end

#total_tokens ⇒ Integer

Returns:

  • (Integer) 


116
117
118
 
# File 'lib/llm/usage.rb', line 116

def total_tokens
  @total_tokens || 0
end