Class: RubyLLM::Agents::TrackReport

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby_llm/agents/track_report.rb

Overview

Aggregated read-only report returned by RubyLLM::Agents.track.

Provides totals and breakdowns across all agent calls made inside the tracked block.

Examples:

report = RubyLLM::Agents.track do
  TranscribeAgent.call(with: audio_path)
  ChatAgent.call(message: "hello")
end
report.total_cost   # => 0.0078
report.call_count   # => 2

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(value:, error:, results:, request_id:, started_at:, completed_at:) ⇒ TrackReport

Returns a new instance of TrackReport.



23
24
25
26
27
28
29
30
 
# File 'lib/ruby_llm/agents/track_report.rb', line 23

def initialize(value:, error:, results:, request_id:, started_at:, completed_at:)
  @value = value
  @error = error
  @results = results.freeze
  @request_id = request_id
  @started_at = started_at
  @completed_at = completed_at
end

Instance Attribute Details

#completed_at ⇒ Object (readonly) 



21
22
23
 
# File 'lib/ruby_llm/agents/track_report.rb', line 21

def completed_at
  @completed_at
end

#error ⇒ Object (readonly) 



20
21
22
 
# File 'lib/ruby_llm/agents/track_report.rb', line 20

def error
  @error
end

#request_id ⇒ Object (readonly) 



20
21
22
 
# File 'lib/ruby_llm/agents/track_report.rb', line 20

def request_id
  @request_id
end

#results ⇒ Object (readonly) 



20
21
22
 
# File 'lib/ruby_llm/agents/track_report.rb', line 20

def results
  @results
end

#started_at ⇒ Object (readonly) 



21
22
23
 
# File 'lib/ruby_llm/agents/track_report.rb', line 21

def started_at
  @started_at
end

#value ⇒ Object (readonly) 



20
21
22
 
# File 'lib/ruby_llm/agents/track_report.rb', line 20

def value
  @value
end

Instance Method Details

#all_successful? ⇒ Boolean

Returns:

  • (Boolean) 


104
105
106
 
# File 'lib/ruby_llm/agents/track_report.rb', line 104

def all_successful?
  @results.all?(&:success?)
end

#any_errors? ⇒ Boolean

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/ruby_llm/agents/track_report.rb', line 108

def any_errors?
  @results.any?(&:error?)
end

#billable_count ⇒ Object

Calls that actually hit a provider.



51
52
53
 
# File 'lib/ruby_llm/agents/track_report.rb', line 51

def billable_count
  billable_results.size
end

#billable_results ⇒ Object

Results that hit a provider (everything except cache replays).



90
91
92
 
# File 'lib/ruby_llm/agents/track_report.rb', line 90

def billable_results
  @billable_results ||= @results.reject { |r| cached_result?(r) }
end

#cache_savings ⇒ Object

What the cached calls would have cost at the original calls' prices.



85
86
87
 
# File 'lib/ruby_llm/agents/track_report.rb', line 85

def cache_savings
  cached_results.sum { |r| r.total_cost || 0 }
end

#cached_count ⇒ Object

Calls served from the response cache — no API call, no spend.



46
47
48
 
# File 'lib/ruby_llm/agents/track_report.rb', line 46

def cached_count
  cached_results.size
end

#cached_results ⇒ Object

Results replayed from the response cache.



95
96
97
 
# File 'lib/ruby_llm/agents/track_report.rb', line 95

def cached_results
  @cached_results ||= @results.select { |r| cached_result?(r) }
end

#call_count ⇒ Object

Every agent call made in the block, including ones served from cache.



41
42
43
 
# File 'lib/ruby_llm/agents/track_report.rb', line 41

def call_count
  @results.size
end

#cost_breakdown ⇒ Object 



124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/ruby_llm/agents/track_report.rb', line 124

def cost_breakdown
  @results.map do |r|
    {
      agent: r.respond_to?(:agent_class_name) ? r.agent_class_name : nil,
      model: r.chosen_model_id,
      cost: cached_result?(r) ? 0 : (r.total_cost || 0),
      tokens: cached_result?(r) ? 0 : (r.total_tokens || 0),
      cached: cached_result?(r),
      duration_ms: r.duration_ms
    }
  end
end

#duration_ms ⇒ Object 



99
100
101
102
 
# File 'lib/ruby_llm/agents/track_report.rb', line 99

def duration_ms
  return nil unless @started_at && @completed_at
  ((@completed_at - @started_at) * 1000).to_i
end

#errors ⇒ Object 



112
113
114
 
# File 'lib/ruby_llm/agents/track_report.rb', line 112

def errors
  @results.select(&:error?)
end

#failed? ⇒ Boolean

Returns:

  • (Boolean) 


36
37
38
 
# File 'lib/ruby_llm/agents/track_report.rb', line 36

def failed?
  !successful?
end

#input_cost ⇒ Object 



64
65
66
 
# File 'lib/ruby_llm/agents/track_report.rb', line 64

def input_cost
  billable_results.sum { |r| r.input_cost || 0 }
end

#input_tokens ⇒ Object 



76
77
78
 
# File 'lib/ruby_llm/agents/track_report.rb', line 76

def input_tokens
  billable_results.sum { |r| r.input_tokens || 0 }
end

#models_used ⇒ Object 



120
121
122
 
# File 'lib/ruby_llm/agents/track_report.rb', line 120

def models_used
  @results.filter_map(&:chosen_model_id).uniq
end

#output_cost ⇒ Object 



68
69
70
 
# File 'lib/ruby_llm/agents/track_report.rb', line 68

def output_cost
  billable_results.sum { |r| r.output_cost || 0 }
end

#output_tokens ⇒ Object 



80
81
82
 
# File 'lib/ruby_llm/agents/track_report.rb', line 80

def output_tokens
  billable_results.sum { |r| r.output_tokens || 0 }
end

#successful ⇒ Object 



116
117
118
 
# File 'lib/ruby_llm/agents/track_report.rb', line 116

def successful
  @results.select(&:success?)
end

#successful? ⇒ Boolean

Returns:

  • (Boolean) 


32
33
34
 
# File 'lib/ruby_llm/agents/track_report.rb', line 32

def successful?
  @error.nil?
end

#to_h ⇒ Object 



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/ruby_llm/agents/track_report.rb', line 137

def to_h
  {
    successful: successful?,
    value: value,
    error: error&.message,
    request_id: request_id,
    call_count: call_count,
    cached_count: cached_count,
    billable_count: billable_count,
    total_cost: total_cost,
    cache_savings: cache_savings,
    input_cost: input_cost,
    output_cost: output_cost,
    total_tokens: total_tokens,
    input_tokens: input_tokens,
    output_tokens: output_tokens,
    duration_ms: duration_ms,
    started_at: started_at,
    completed_at: completed_at,
    models_used: models_used,
    cost_breakdown: cost_breakdown
  }
end

#total_cost ⇒ Object

Costs and token counts cover only the calls that actually hit a provider. A cached result replays the ORIGINAL call's figures, so including them would report spend that was never incurred — the execution records for cache hits are written with zero cost, and these totals reconcile with them.



60
61
62
 
# File 'lib/ruby_llm/agents/track_report.rb', line 60

def total_cost
  billable_results.sum { |r| r.total_cost || 0 }
end

#total_tokens ⇒ Object 



72
73
74
 
# File 'lib/ruby_llm/agents/track_report.rb', line 72

def total_tokens
  billable_results.sum { |r| r.total_tokens || 0 }
end