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

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

Overview

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. Canonical keys only (O03a): provider spellings are translated at the edges.

Constant Summary collapse

BUILD_SITE = 
'Canonical::Usage.build'
FROM_HASH_SITE = 
'Canonical::Usage.from_hash'
NEW_SITE = 
'Canonical::Usage.new'

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



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

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



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

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



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

def input_tokens
  @input_tokens
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata

Returns:

  • (Object) —

    the current value of metadata



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

def metadata
  @metadata
end

#output_tokens ⇒ Object (readonly)

Returns the value of attribute output_tokens

Returns:

  • (Object) —

    the current value of output_tokens



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

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



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

def thinking_tokens
  @thinking_tokens
end

#units ⇒ Object (readonly)

Returns the value of attribute units

Returns:

  • (Object) —

    the current value of units



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

def units
  @units
end

Class Method Details

.build(input_tokens: nil, output_tokens: nil, cache_read_tokens: nil, cache_write_tokens: nil, thinking_tokens: nil, units: nil, metadata: {}) ⇒ Object

rubocop:disable Metrics/ParameterLists -- factory methods have many params Build from keyword args (primary constructor).



19
20
21
22
23
24
25
26
27
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 19

def self.build(
  input_tokens: nil, output_tokens: nil, cache_read_tokens: nil,
  cache_write_tokens: nil, thinking_tokens: nil, units: nil, metadata: {}
)
  new(
    input_tokens:, output_tokens:, cache_read_tokens:, cache_write_tokens:,
    thinking_tokens:, units: units || {}, metadata: Strict.metadata!(metadata, self::BUILD_SITE)
  )
end

.from_hash(source) ⇒ Object

Build from a Hash (raw provider response or deserialized wire payload). from_hash({}) is a valid all-nil Usage (the no-usage object), never nil.



32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 32

def self.from_hash(source)
  Strict.require_hash!(source, self::FROM_HASH_SITE)
  hash = Strict.symbolize_keys(source)
  metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
  build(
    input_tokens: hash[:input_tokens],
    output_tokens: hash[:output_tokens],
    cache_read_tokens: hash[:cache_read_tokens],
    cache_write_tokens: hash[:cache_write_tokens],
    thinking_tokens: hash[:thinking_tokens],
    units: hash[:units] || {},
    metadata:
  )
end

Instance Method Details

#as_json ⇒ Object

MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.



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

def as_json(*)
  to_h
end

#to_h ⇒ Object

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



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

def to_h
  super.compact
end

#to_json ⇒ Object 



57
58
59
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 57

def to_json(*)
  to_h.to_json(*)
end

#total_tokens ⇒ Object

Total tokens across all categories.



62
63
64
65
 
# File 'lib/legion/extensions/llm/canonical/usage.rb', line 62

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