Class: Legion::Extensions::Llm::Canonical::Usage

Inherits:
Data
  • Object
show all
Defined in:
lib/legion/extensions/llm/canonical/usage.rb

Overview

rubocop:disable Lint/ConstantDefinitionInBlock – required for Data.define block scope Canonical usage/metering data for a response. Ports field vocabulary from lex-llm Tokens and legion-llm Types. Includes non-token units extension point per G20b.

Constant Summary collapse

USAGE_KNOWN_KEYS = 
%i[input_tokens output_tokens cache_read_tokens cache_write_tokens
thinking_tokens units].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#cache_read_tokens ⇒ Object (readonly)

Returns the value of attribute cache_read_tokens

Returns:

  • (Object) —

    the current value of cache_read_tokens



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 12

def cache_read_tokens
  @cache_read_tokens
end

#cache_write_tokens ⇒ Object (readonly)

Returns the value of attribute cache_write_tokens

Returns:

  • (Object) —

    the current value of cache_write_tokens



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 12

def cache_write_tokens
  @cache_write_tokens
end

#input_tokens ⇒ Object (readonly)

Returns the value of attribute input_tokens

Returns:

  • (Object) —

    the current value of input_tokens



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 12

def input_tokens
  @input_tokens
end

#output_tokens ⇒ Object (readonly)

Returns the value of attribute output_tokens

Returns:

  • (Object) —

    the current value of output_tokens



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 12

def output_tokens
  @output_tokens
end

#thinking_tokens ⇒ Object (readonly)

Returns the value of attribute thinking_tokens

Returns:

  • (Object) —

    the current value of thinking_tokens



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 12

def thinking_tokens
  @thinking_tokens
end

#units ⇒ Object (readonly)

Returns the value of attribute units

Returns:

  • (Object) —

    the current value of units



12
13
14
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 12

def units
  @units
end

Class Method Details

.from_hash(source) ⇒ Object

Build from a Hash (raw provider response or deserialized wire payload). Accepts both canonical key names and legacy provider spellings.



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 21

def self.from_hash(source)
  return nil if source.nil? || source.empty?

  h = source.transform_keys(&:to_sym)

  # Normalize legacy key names
  h[:input_tokens] ||= h.delete(:input) || h.delete(:prompt_tokens)
  h[:output_tokens] ||= h.delete(:output) || h.delete(:completion_tokens)
  h[:cache_read_tokens] ||= h.delete(:cached) || h.delete(:cache_read)
  h[:cache_write_tokens] ||= h.delete(:cache_creation) || h.delete(:cache_write)
  h[:thinking_tokens] ||= h.delete(:thinking) || h.delete(:reasoning)

  # Extract units (non-token extension point — G20b)
  units = h.delete(:units) || {}

  new(
    input_tokens: h[:input_tokens],
    output_tokens: h[:output_tokens],
    cache_read_tokens: h[:cache_read_tokens],
    cache_write_tokens: h[:cache_write_tokens],
    thinking_tokens: h[:thinking_tokens],
    units: units
  )
end

Instance Method Details

#to_h ⇒ Object

Serialize to a Hash for AMQP/fleet/wire transport.



47
48
49
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 47

def to_h
  super.compact
end

#total_tokens ⇒ Object

Total tokens across all categories.



52
53
54
55
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 52

def total_tokens
  [input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
   thinking_tokens].compact.sum
end