Module: SwarmSDK::Agent::ChatHelpers::TokenTracking

Included in:
SwarmSDK::Agent::Chat
Defined in:
lib/swarm_sdk/agent/chat_helpers/token_tracking.rb

Overview

Token usage tracking and context limit management

Extracted from Chat to reduce class size and centralize token metrics.

Instance Method Summary collapse

Instance Method Details

#compact_context(**options) ⇒ ContextCompactor::Metrics

Compact the conversation history to reduce token usage

Parameters:

  • options (Hash) —

    Compression options

Returns:



120
121
122
123
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 120

def compact_context(**options)
  compactor = ContextCompactor.new(self, options)
  compactor.compact
end

#context_limit ⇒ Integer?

Get context window limit for the current model

Returns:

  • (Integer, nil) —

    Maximum context tokens



13
14
15
16
17
18
19
20
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 13

def context_limit
  return @explicit_context_window if @explicit_context_window
  return @real_model_info.context_window if @real_model_info&.context_window

  model_context_window
rescue StandardError
  nil
end

#context_usage_percentage ⇒ Float

Calculate percentage of context window used

Returns:

  • (Float) —

    Percentage (0.0 to 100.0)



70
71
72
73
74
75
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 70

def context_usage_percentage
  limit = context_limit
  return 0.0 if limit.nil? || limit.zero?

  (cumulative_total_tokens.to_f / limit * 100).round(2)
end

#cumulative_cache_creation_tokens ⇒ Integer

Calculate cumulative cache creation tokens

Returns:

  • (Integer) —

    Total tokens written to cache



49
50
51
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 49

def cumulative_cache_creation_tokens
  assistant_messages.sum { |msg| msg.cache_creation_tokens || 0 }
end

#cumulative_cached_tokens ⇒ Integer

Calculate cumulative cached tokens

Returns:

  • (Integer) —

    Total cached tokens used



42
43
44
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 42

def cumulative_cached_tokens
  assistant_messages.sum { |msg| msg.cached_tokens || 0 }
end

#cumulative_input_cost ⇒ Float

Calculate cumulative input cost based on tokens and model pricing

Returns:

  • (Float) —

    Total input cost in dollars



90
91
92
93
94
95
96
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 90

def cumulative_input_cost
  pricing = model_pricing
  return 0.0 unless pricing

  input_price = pricing["input_per_million"] || pricing[:input_per_million] || 0.0
  (cumulative_input_tokens / 1_000_000.0) * input_price
end

#cumulative_input_tokens ⇒ Integer

Calculate cumulative input tokens for the conversation

Gets input_tokens from the most recent assistant message, which represents the total context size sent to the model (not sum of all messages).

Returns:

  • (Integer) —

    Total input tokens used



28
29
30
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 28

def cumulative_input_tokens
  find_last_message { |msg| msg.role == :assistant && msg.input_tokens }&.input_tokens || 0
end

#cumulative_output_cost ⇒ Float

Calculate cumulative output cost based on tokens and model pricing

Returns:

  • (Float) —

    Total output cost in dollars



101
102
103
104
105
106
107
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 101

def cumulative_output_cost
  pricing = model_pricing
  return 0.0 unless pricing

  output_price = pricing["output_per_million"] || pricing[:output_per_million] || 0.0
  (cumulative_output_tokens / 1_000_000.0) * output_price
end

#cumulative_output_tokens ⇒ Integer

Calculate cumulative output tokens across all assistant messages

Returns:

  • (Integer) —

    Total output tokens used



35
36
37
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 35

def cumulative_output_tokens
  assistant_messages.sum { |msg| msg.output_tokens || 0 }
end

#cumulative_total_cost ⇒ Float

Calculate cumulative total cost (input + output)

Returns:

  • (Float) —

    Total cost in dollars



112
113
114
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 112

def cumulative_total_cost
  cumulative_input_cost + cumulative_output_cost
end

#cumulative_total_tokens ⇒ Integer

Calculate total tokens used (input + output)

Returns:

  • (Integer) —

    Total tokens used



63
64
65
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 63

def cumulative_total_tokens
  cumulative_input_tokens + cumulative_output_tokens
end

#effective_input_tokens ⇒ Integer

Calculate effective input tokens (excluding cache hits)

Returns:

  • (Integer) —

    Actual input tokens charged



56
57
58
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 56

def effective_input_tokens
  cumulative_input_tokens - cumulative_cached_tokens
end

#tokens_remaining ⇒ Integer?

Calculate remaining tokens in context window

Returns:

  • (Integer, nil) —

    Tokens remaining



80
81
82
83
84
85
 
# File 'lib/swarm_sdk/agent/chat_helpers/token_tracking.rb', line 80

def tokens_remaining
  limit = context_limit
  return if limit.nil?

  limit - cumulative_total_tokens
end