Module: RubyLLM::Agents::Trackable Private

Included in:
BackgroundRemovalResult, EmbeddingResult, ImageAnalysisResult, ImageEditResult, ImageGenerationResult, ImagePipelineResult, ImageTransformResult, ImageUpscaleResult, ImageVariationResult, Result, SpeechResult, TranscriptionResult
Defined in:
lib/ruby_llm/agents/results/trackable.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Shared result lifecycle: registering with the active Tracker, and marking a result that was replayed from the response cache.

Both concerns fire at the same moment — when a result is handed back to the caller — and both must apply to every result type, since any agent with cache_for can have its result served from cache.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



14
15
16
17
 
# File 'lib/ruby_llm/agents/results/trackable.rb', line 14

def self.included(base)
  base.attr_reader :agent_class_name unless base.method_defined?(:agent_class_name)
  base.attr_reader :cached_at unless base.method_defined?(:cached_at)
end

Instance Method Details

#as_cache_hit(execution_id:, cached_at:) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a copy of this result marked as served from the response cache.

Used by the Cache middleware on a hit. Two things the raw cached object gets wrong on its own:

  • execution_id still points at the ORIGINAL call's row, so the result cannot be correlated with the execution written for this call.
  • the copy never passes through #initialize (it is deserialized, then duped), so it would never register with an active Tracker — making TrackReport#call_count silently under-report.

Parameters:

  • execution_id (Integer, nil) —

    The current call's execution record id

  • cached_at (Time) —

    When the cached response was first produced

Returns:

  • (Object) —

    A marked copy of this result



47
48
49
50
51
52
53
 
# File 'lib/ruby_llm/agents/results/trackable.rb', line 47

def as_cache_hit(execution_id:, cached_at:)
  dup.tap do |copy|
    copy.instance_variable_set(:@cached_at, cached_at)
    copy.instance_variable_set(:@execution_id, execution_id)
    copy.send(:register_with_tracker)
  end
end

#cached? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Whether this response was replayed from the response cache rather than generated by a fresh LLM call.

The token and cost fields describe the call that ORIGINALLY produced the response — no API call was made this time, and the execution record for this call is written with zero cost. Aggregate spend from the execution records, or exclude cached results, rather than summing #total_cost across every result. RubyLLM::Agents.track does this for you.

Returns:

  • (Boolean) 


29
30
31
 
# File 'lib/ruby_llm/agents/results/trackable.rb', line 29

def cached?
  !@cached_at.nil?
end