Module: RubyLLM::Agents::DSL::Caching

Included in:
BaseAgent
Defined in:
lib/ruby_llm/agents/dsl/caching.rb

Overview

Caching DSL for agent response caching.

This module provides configuration methods for caching features that can be mixed into any agent class.

Examples:

Basic usage

class MyAgent < RubyLLM::Agents::BaseAgent
  extend DSL::Caching

  cache_for 1.hour
end

With conditional caching

class MyAgent < RubyLLM::Agents::BaseAgent
  extend DSL::Caching

  cache_for 30.minutes
  cache_key_includes :user_id, :query
end

Constant Summary collapse

DEFAULT_CACHE_TTL =

Default cache TTL when none specified

1.hour

Caching DSL collapse

Instance Method Details

#cache(ttl_or_options = nil, for: nil, key: nil) ⇒ void

This method returns an undefined value.

Unified cache configuration method (simplified DSL)

Configures caching with a cleaner syntax using keyword arguments.

Examples:

Simple TTL (positional argument for backward compatibility)

cache 1.hour

With keyword arguments (preferred)

cache for: 1.hour
cache for: 30.minutes, key: [:query, :user_id]

Parameters:

  • ttl_or_options (ActiveSupport::Duration, Hash) (defaults to: nil) —

    TTL or options hash

  • for_duration (ActiveSupport::Duration) —

    TTL for cached responses

  • key (Array<Symbol>) (defaults to: nil) —

    Parameters to include in cache key



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/ruby_llm/agents/dsl/caching.rb', line 62

def cache(ttl_or_options = nil, for: nil, key: nil)
  # Handle positional argument (backward compatibility)
  if ttl_or_options && !ttl_or_options.is_a?(Hash)
    @cache_enabled = true
    @cache_ttl = ttl_or_options
    return
  end

  # Handle keyword arguments
  for_duration = binding.local_variable_get(:for)
  if for_duration
    @cache_enabled = true
    @cache_ttl = for_duration
  end

  @cache_key_includes = Array(key) if key
end

#cache_enabled? ⇒ Boolean

Returns whether caching is enabled for this agent

Caching IS inherited from parent classes following Ruby patterns.

Returns:

  • (Boolean) —

    true if caching is enabled



85
86
87
88
89
 
# File 'lib/ruby_llm/agents/dsl/caching.rb', line 85

def cache_enabled?
  return @cache_enabled if defined?(@cache_enabled)

  inherited_cache_enabled
end

#cache_for(ttl) ⇒ void

This method returns an undefined value.

Enables caching for this agent with explicit TTL

This is the preferred method for enabling caching.

Examples:

cache_for 1.hour
cache_for 30.minutes

Parameters:

  • ttl (ActiveSupport::Duration) —

    Time-to-live for cached responses



41
42
43
44
 
# File 'lib/ruby_llm/agents/dsl/caching.rb', line 41

def cache_for(ttl)
  @cache_enabled = true
  @cache_ttl = ttl
end

#cache_key_excludes(*keys) ⇒ Array<Symbol>

Specifies which parameters should be excluded from the cache key

Examples:

cache_key_excludes :timestamp, :request_id

Parameters:

  • keys (Array<Symbol>) —

    Parameter keys to exclude from cache key

Returns:

  • (Array<Symbol>) —

    The current cache key excludes



118
119
120
121
 
# File 'lib/ruby_llm/agents/dsl/caching.rb', line 118

def cache_key_excludes(*keys)
  @cache_key_excludes = keys.flatten if keys.any?
  @cache_key_excludes || inherited_cache_key_excludes || default_cache_key_excludes
end

#cache_key_includes(*keys) ⇒ Array<Symbol>?

Specifies which parameters should be included in the cache key

By default, all options except :skip_cache and :dry_run are included. Use this to explicitly define which parameters affect caching.

Examples:

cache_key_includes :user_id, :query, :context

Parameters:

  • keys (Array<Symbol>) —

    Parameter keys to include in cache key

Returns:

  • (Array<Symbol>, nil) —

    The current cache key includes



107
108
109
110
 
# File 'lib/ruby_llm/agents/dsl/caching.rb', line 107

def cache_key_includes(*keys)
  @cache_key_includes = keys.flatten if keys.any?
  @cache_key_includes || inherited_cache_key_includes
end

#cache_ttl ⇒ ActiveSupport::Duration

Returns the cache TTL for this agent

Returns:

  • (ActiveSupport::Duration) —

    The cache TTL



94
95
96
 
# File 'lib/ruby_llm/agents/dsl/caching.rb', line 94

def cache_ttl
  @cache_ttl || inherited_cache_ttl || DEFAULT_CACHE_TTL
end

#caching_config ⇒ Hash?

Returns the complete caching configuration hash

Used by the Cache middleware to get all settings.

Returns:

  • (Hash, nil) —

    The caching configuration



128
129
130
131
132
133
134
135
136
137
 
# File 'lib/ruby_llm/agents/dsl/caching.rb', line 128

def caching_config
  return nil unless cache_enabled?

  {
    enabled: true,
    ttl: cache_ttl,
    key_includes: cache_key_includes,
    key_excludes: cache_key_excludes
  }.compact
end