Class: LLM::Usage

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

Overview

This class helps track the number of input, output, reasoning, cache, and overall token count for a Context or Agent object.

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) 


66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/llm/usage.rb', line 66

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

.zero ⇒ LLM::Usage

Returns:



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

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

.from(obj) ⇒ LLM::Usage

Parameters:

Returns:



42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/llm/usage.rb', line 42

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

.fields ⇒ Array<String>

Returns:

  • (Array<String>) 


22
23
24
 
# File 'lib/llm/usage.rb', line 22

def self.fields
  FIELDS
end

Instance Method Details

#to_json ⇒ String

Returns:

  • (String) 


183
184
185
 
# File 'lib/llm/usage.rb', line 183

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

#input_tokens ⇒ Integer

Returns:

  • (Integer) 


83
84
85
 
# File 'lib/llm/usage.rb', line 83

def input_tokens
  @input_tokens || 0
end

#output_tokens ⇒ Integer

Returns:

  • (Integer) 


89
90
91
 
# File 'lib/llm/usage.rb', line 89

def output_tokens
  @output_tokens || 0
end

#reasoning_tokens ⇒ Integer

Returns:

  • (Integer) 


95
96
97
 
# File 'lib/llm/usage.rb', line 95

def reasoning_tokens
  @reasoning_tokens || 0
end

#input_audio_tokens ⇒ Integer

Returns:

  • (Integer) 


101
102
103
 
# File 'lib/llm/usage.rb', line 101

def input_audio_tokens
  @input_audio_tokens || 0
end

#output_audio_tokens ⇒ Integer

Returns:

  • (Integer) 


107
108
109
 
# File 'lib/llm/usage.rb', line 107

def output_audio_tokens
  @output_audio_tokens || 0
end

#input_image_tokens ⇒ Integer

Returns:

  • (Integer) 


113
114
115
 
# File 'lib/llm/usage.rb', line 113

def input_image_tokens
  @input_image_tokens || 0
end

#cache_read_tokens ⇒ Integer

Returns:

  • (Integer) 


119
120
121
 
# File 'lib/llm/usage.rb', line 119

def cache_read_tokens
  @cache_read_tokens || 0
end

#cache_write_tokens ⇒ Integer

Returns:

  • (Integer) 


125
126
127
 
# File 'lib/llm/usage.rb', line 125

def cache_write_tokens
  @cache_write_tokens || 0
end

#total_tokens ⇒ Integer

Returns:

  • (Integer) 


131
132
133
 
# File 'lib/llm/usage.rb', line 131

def total_tokens
  @total_tokens || 0
end

#+(other) ⇒ LLM::Usage

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

Parameters:

Returns:



140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/llm/usage.rb', line 140

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



158
159
160
 
# File 'lib/llm/usage.rb', line 158

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

#hash ⇒ Integer

Returns a hash consistent with #eql?

Returns:

  • (Integer) —

    Returns a hash consistent with #eql?



166
167
168
 
# File 'lib/llm/usage.rb', line 166

def hash
  to_h.hash
end

#to_h ⇒ Hash

Returns:

  • (Hash) 


172
173
174
175
176
177
178
179
 
# File 'lib/llm/usage.rb', line 172

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