Class: Roast::Cogs::Agent::Stats

Inherits:
Object
  • Object
show all
Includes:
ActiveSupport::NumberHelper
Defined in:
lib/roast/cogs/agent/stats.rb

Overview

Statistics about agent execution

Contains metrics tracking the performance and resource usage of an agent execution, including duration, conversation turns, token usage, and cost. Statistics are broken down by model when multiple models are used during execution.

Constant Summary collapse

NO_VALUE = 
"---"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Stats

Returns a new instance of Stats.



59
60
61
62
 
# File 'lib/roast/cogs/agent/stats.rb', line 59

def initialize
  @usage = Usage.new
  @model_usage = {}
end

Instance Attribute Details

#duration_ms ⇒ Object

The total execution duration in milliseconds

Measures the wall-clock time from when the agent started executing until it completed. This includes all time spent on API calls, processing, and waiting.

: Integer?



23
24
25
 
# File 'lib/roast/cogs/agent/stats.rb', line 23

def duration_ms
  @duration_ms
end

#model_usage ⇒ Object

Token usage and cost broken down by model

A hash mapping model names (as strings) to their individual usage statistics. This allows tracking how much each model contributed to the overall resource usage when multiple models were used during execution.

#### See Also

  • ‘usage` - for aggregate usage across all models

  • ‘Agent::Usage`

: Hash[String, Usage]



57
58
59
 
# File 'lib/roast/cogs/agent/stats.rb', line 57

def model_usage
  @model_usage
end

#num_turns ⇒ Object

The number of conversation turns in the agent execution

A turn represents one complete back-and-forth exchange between the user (or system) and the agent. For example, if the user sends a prompt and the agent responds, that is one turn. If the agent then uses a tool and responds again, that is another turn.

: Integer?



32
33
34
 
# File 'lib/roast/cogs/agent/stats.rb', line 32

def num_turns
  @num_turns
end

#usage ⇒ Object

Aggregate token usage and cost across all models

Provides the total input tokens, output tokens, and cost in USD for the entire agent execution, regardless of which models were used.

#### See Also

  • ‘model_usage` - for per-model usage breakdown

  • ‘Agent::Usage`

: Usage



44
45
46
 
# File 'lib/roast/cogs/agent/stats.rb', line 44

def usage
  @usage
end

Instance Method Details

#+(other) ⇒ Object

Add two Stats objects together, summing their durations, turns, usage, and model usage

Nil values are treated as zero when the other operand is non-nil. Model usage hashes are merged, summing usage for models that appear in both.

: (Stats) -> Stats



70
71
72
73
74
75
76
77
 
# File 'lib/roast/cogs/agent/stats.rb', line 70

def +(other)
  result = Stats.new
  result.duration_ms = sum_nils(duration_ms, other.duration_ms)&.to_int
  result.num_turns = sum_nils(num_turns, other.num_turns)&.to_int
  result.usage = usage + other.usage
  result.model_usage = merge_model_usage(model_usage, other.model_usage)
  result
end

#to_s ⇒ Object

Get a human-readable string representation of the statistics

Formats the statistics into a multi-line string with the following information:

  • Number of turns

  • Total duration (formatted as a human-readable duration)

  • Total cost in USD (formatted with 6 decimal places)

  • Per-model token usage (input and output tokens)

Values that are not available are shown as “—”.

: () -> String



90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/roast/cogs/agent/stats.rb', line 90

def to_s
  lines = []
  lines << "Turns: #{num_turns.nil? ? NO_VALUE : number_to_human(num_turns)}"
  lines << "Duration: #{duration_ms.nil? ? NO_VALUE : ActiveSupport::Duration.build((duration_ms || 0) / 1000).inspect}"
  lines << "Cost (USD): $#{usage.cost_usd.nil? ? NO_VALUE : number_to_human(usage.cost_usd, precision: 6, significant: false)}"
  model_usage.each do |m, u|
    input_tokens = u.input_tokens.nil? ? NO_VALUE : number_to_human(u.input_tokens)
    output_tokens = u.output_tokens.nil? ? NO_VALUE : number_to_human(u.output_tokens)
    lines << "Tokens (#{m}): #{input_tokens} in, #{output_tokens} out"
  end
  lines.join("\n")
end