Module: Legion::LLM::Metering::Tokens

Extended by:
Legion::Logging::Helper
Defined in:
lib/legion/llm/metering/tokens.rb

Constant Summary collapse

MUTEX = 
Mutex.new
MAX_ENTRIES = 
10_000

Class Method Summary collapse

Class Method Details

.record(input_tokens:, output_tokens:) ⇒ Hash

Records token usage from a completed LLM call.

Parameters:

  • input_tokens (Integer) —

    number of input tokens consumed

  • output_tokens (Integer) —

    number of output tokens produced

Returns:

  • (Hash) —

    the recorded entry



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/legion/llm/metering/tokens.rb', line 19

def record(input_tokens:, output_tokens:)
  entry = {
    input_tokens:  input_tokens.to_i,
    output_tokens: output_tokens.to_i,
    recorded_at:   Time.now
  }

  MUTEX.synchronize do
    store << entry
    # Evict oldest entries to prevent unbounded memory growth in long-running processes
    if store.size > MAX_ENTRIES
      evicted = store.shift(store.size - MAX_ENTRIES)
      log.debug "[LLM::TokenTracker] evicted #{evicted.size} entries (max #{MAX_ENTRIES})"
    end
  end
  log.debug "[LLM::TokenTracker] recorded #{input_tokens}+#{output_tokens} tokens (total: #{total_tokens})"
  entry
end

.reset! ⇒ Object

Clears all recorded entries (for test isolation).



80
81
82
 
# File 'lib/legion/llm/metering/tokens.rb', line 80

def reset!
  MUTEX.synchronize { @store = [] }
end

.session_exceeded? ⇒ Boolean

Returns true when total_tokens >= session_max_tokens (and limit is configured).

Returns:

  • (Boolean) 


62
63
64
65
66
67
 
# File 'lib/legion/llm/metering/tokens.rb', line 62

def session_exceeded?
  limit = session_max_tokens
  return false unless limit&.positive?

  total_tokens >= limit
end

.session_warning? ⇒ Boolean

Returns true when total_tokens >= session_warn_tokens (and threshold is configured).

Returns:

  • (Boolean) 


72
73
74
75
76
77
 
# File 'lib/legion/llm/metering/tokens.rb', line 72

def session_warning?
  threshold = session_warn_tokens
  return false unless threshold&.positive?

  total_tokens >= threshold
end

.summary ⇒ Hash

Returns a summary hash with totals and configured limits.

Returns:

  • (Hash) 


87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/legion/llm/metering/tokens.rb', line 87

def summary
  max   = session_max_tokens
  warn  = session_warn_tokens
  total = total_tokens
  {
    total_tokens:        total,
    total_input_tokens:  total_input_tokens,
    total_output_tokens: total_output_tokens,
    session_max_tokens:  max,
    session_warn_tokens: warn,
    exceeded:            session_exceeded?,
    warning:             session_warning?,
    remaining:           max ? [max - total, 0].max : nil
  }
end

.total_input_tokens ⇒ Integer

Returns total input tokens accumulated.

Returns:

  • (Integer) 


48
49
50
 
# File 'lib/legion/llm/metering/tokens.rb', line 48

def total_input_tokens
  MUTEX.synchronize { store.sum { |e| e[:input_tokens] } }
end

.total_output_tokens ⇒ Integer

Returns total output tokens accumulated.

Returns:

  • (Integer) 


55
56
57
 
# File 'lib/legion/llm/metering/tokens.rb', line 55

def total_output_tokens
  MUTEX.synchronize { store.sum { |e| e[:output_tokens] } }
end

.total_tokens ⇒ Integer

Returns total tokens accumulated across all recorded calls.

Returns:

  • (Integer) 


41
42
43
 
# File 'lib/legion/llm/metering/tokens.rb', line 41

def total_tokens
  MUTEX.synchronize { store.sum { |e| e[:input_tokens] + e[:output_tokens] } }
end