Class: Phronomy::TokenUsage

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/token_usage.rb

Overview

Immutable value object that holds token usage counts for a single LLM call or an accumulated total across multiple calls.

Fields mirror the values reported by RubyLLM::Tokens:

input - tokens consumed by the input (prompt) output - tokens produced by the model (completion) cached - input tokens served from the provider's prompt cache cache_creation - input tokens written into the prompt cache (Anthropic)

All fields are Integer or nil (nil means the provider did not report that value for this call).

Examples:

Accumulate usage across a ReAct loop

total = Phronomy::TokenUsage.zero
chat.messages.each do |msg|
  total += Phronomy::TokenUsage.from_tokens(msg.tokens)
end

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(input: nil, output: nil, cached: nil, cache_creation: nil) ⇒ TokenUsage

Returns a new instance of TokenUsage.



25
26
27
28
29
30
 
# File 'lib/phronomy/token_usage.rb', line 25

def initialize(input: nil, output: nil, cached: nil, cache_creation: nil)
  @input = input
  @output = output
  @cached = cached
  @cache_creation = cache_creation
end

Instance Attribute Details

#cache_creation ⇒ Object (readonly)

Returns the value of attribute cache_creation.



23
24
25
 
# File 'lib/phronomy/token_usage.rb', line 23

def cache_creation
  @cache_creation
end

#cached ⇒ Object (readonly)

Returns the value of attribute cached.



23
24
25
 
# File 'lib/phronomy/token_usage.rb', line 23

def cached
  @cached
end

#input ⇒ Object (readonly)

Returns the value of attribute input.



23
24
25
 
# File 'lib/phronomy/token_usage.rb', line 23

def input
  @input
end

#output ⇒ Object (readonly)

Returns the value of attribute output.



23
24
25
 
# File 'lib/phronomy/token_usage.rb', line 23

def output
  @output
end

Class Method Details

.from_tokens(tokens) ⇒ Object

Builds a TokenUsage from a RubyLLM::Tokens object. Returns zero when tokens is nil (provider did not report usage). nil fields within the tokens object are coerced to 0.



40
41
42
43
44
45
46
47
48
49
 
# File 'lib/phronomy/token_usage.rb', line 40

def self.from_tokens(tokens)
  return zero if tokens.nil?

  new(
    input: tokens.input || 0,
    output: tokens.output || 0,
    cached: tokens.cached || 0,
    cache_creation: tokens.cache_creation || 0
  )
end

.zero ⇒ Object

Returns a zero-valued TokenUsage suitable as an accumulator seed.



33
34
35
 
# File 'lib/phronomy/token_usage.rb', line 33

def self.zero
  new(input: 0, output: 0, cached: 0, cache_creation: 0)
end

Instance Method Details

#+(other) ⇒ Object

Adds two TokenUsage instances. nil fields are treated as 0 so that partially-reported usage accumulates correctly. When other is nil, returns self unchanged.



54
55
56
57
58
59
60
61
62
63
 
# File 'lib/phronomy/token_usage.rb', line 54

def +(other)
  return self if other.nil?

  self.class.new(
    input: _add(input, other.input),
    output: _add(output, other.output),
    cached: _add(cached, other.cached),
    cache_creation: _add(cache_creation, other.cache_creation)
  )
end

#==(other) ⇒ Object 



65
66
67
68
69
70
71
 
# File 'lib/phronomy/token_usage.rb', line 65

def ==(other)
  other.is_a?(TokenUsage) &&
    input == other.input &&
    output == other.output &&
    cached == other.cached &&
    cache_creation == other.cache_creation
end

#to_h ⇒ Object 



73
74
75
 
# File 'lib/phronomy/token_usage.rb', line 73

def to_h
  {input: input, output: output, cached: cached, cache_creation: cache_creation}
end