Class: Riffer::Providers::TokenUsage

Inherits:
Object
  • Object
show all
Defined in:
lib/riffer/providers/token_usage.rb,
sig/generated/riffer/providers/token_usage.rbs

Overview

Normalized token usage for an LLM API call. Buckets carry the same meaning for every provider.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(input_tokens:, output_tokens:, cache_write_tokens: nil, cache_read_tokens: nil, cost: nil) ⇒ TokenUsage

-- : (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void

Parameters:

  • input_tokens: (Integer)
  • output_tokens: (Integer)
  • cache_write_tokens: (Integer, nil) (defaults to: nil)
  • cache_read_tokens: (Integer, nil) (defaults to: nil)
  • cost: (Float, nil) (defaults to: nil) 


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

def initialize(input_tokens:, output_tokens:, cache_write_tokens: nil, cache_read_tokens: nil, cost: nil)
  @input_tokens = input_tokens
  @output_tokens = output_tokens
  @cache_write_tokens = cache_write_tokens
  @cache_read_tokens = cache_read_tokens
  @cost = cost
end

Instance Attribute Details

#cache_read_tokens ⇒ Integer? (readonly)

Subset of input_tokens read from the provider's prompt cache, when the provider reports it.

Returns:

  • (Integer, nil) 


17
18
19
 
# File 'lib/riffer/providers/token_usage.rb', line 17

def cache_read_tokens
  @cache_read_tokens
end

#cache_write_tokens ⇒ Integer? (readonly)

Subset of input_tokens written to the provider's prompt cache, when the provider reports it.

Returns:

  • (Integer, nil) 


14
15
16
 
# File 'lib/riffer/providers/token_usage.rb', line 14

def cache_write_tokens
  @cache_write_tokens
end

#cost ⇒ Float? (readonly)

Cost of the call, set when the model is priced. For observability, not billing.

Returns:

  • (Float, nil) 


20
21
22
 
# File 'lib/riffer/providers/token_usage.rb', line 20

def cost
  @cost
end

#input_tokens ⇒ Integer (readonly)

Number of tokens entering the context window, including cache reads and writes.

Returns:

  • (Integer) 


8
9
10
 
# File 'lib/riffer/providers/token_usage.rb', line 8

def input_tokens
  @input_tokens
end

#output_tokens ⇒ Integer (readonly)

Number of tokens generated by the model, including reasoning/thinking tokens.

Returns:

  • (Integer) 


11
12
13
 
# File 'lib/riffer/providers/token_usage.rb', line 11

def output_tokens
  @output_tokens
end

Instance Method Details

#+(other) ⇒ Riffer::Providers::TokenUsage

Combines two TokenUsage objects for cumulative tracking.

-- : (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage

Parameters:

Returns:



44
45
46
47
48
49
50
51
52
 
# File 'lib/riffer/providers/token_usage.rb', line 44

def +(other)
  Riffer::Providers::TokenUsage.new(
    input_tokens: input_tokens + other.input_tokens,
    output_tokens: output_tokens + other.output_tokens,
    cache_write_tokens: add_nullable(cache_write_tokens, other.cache_write_tokens),
    cache_read_tokens: add_nullable(cache_read_tokens, other.cache_read_tokens),
    cost: add_cost(cost, other.cost)
  )
end

#add_cost(a, b) ⇒ Float?

nil is absorbing, not zero: one unpriced call makes the run total nil rather than silently under-reporting.

: (Float?, Float?) -> Float?

Parameters:

  • (Float, nil)
  • (Float, nil)

Returns:

  • (Float, nil) 


78
79
80
81
 
# File 'lib/riffer/providers/token_usage.rb', line 78

def add_cost(a, b)
  return nil if a.nil? || b.nil?
  a + b
end

#add_nullable(a, b) ⇒ Integer?

-- : (Integer?, Integer?) -> Integer?

Parameters:

  • (Integer, nil)
  • (Integer, nil)

Returns:

  • (Integer, nil) 


69
70
71
72
 
# File 'lib/riffer/providers/token_usage.rb', line 69

def add_nullable(a, b)
  return nil if a.nil? && b.nil?
  (a || 0) + (b || 0)
end

#to_h ⇒ Hash[Symbol, Integer | Float]

Converts the token usage to a hash; cache tokens and cost are omitted when nil.

: () -> Hash[Symbol, (Integer | Float)]

Returns:

  • (Hash[Symbol, Integer | Float]) 


57
58
59
60
61
62
63
 
# File 'lib/riffer/providers/token_usage.rb', line 57

def to_h
  hash = {input_tokens: input_tokens, output_tokens: output_tokens} #: Hash[Symbol, (Integer | Float)]
  hash[:cache_write_tokens] = cache_write_tokens if cache_write_tokens
  hash[:cache_read_tokens] = cache_read_tokens if cache_read_tokens
  hash[:cost] = cost if cost
  hash
end

#total_tokens ⇒ Integer

Returns the total number of tokens (input + output).

-- : () -> Integer

Returns:

  • (Integer) 


36
37
38
 
# File 'lib/riffer/providers/token_usage.rb', line 36

def total_tokens
  input_tokens + output_tokens
end