Module: RubyLLM::Agents::CacheHelper Private

Included in:
BaseAgent, Budget::BudgetQuery, Budget::SpendRecorder, BudgetTracker, CircuitBreaker
Defined in:
lib/ruby_llm/agents/infrastructure/cache_helper.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 cache utilities for RubyLLM::Agents

Provides consistent cache key generation and store access across BudgetTracker, CircuitBreaker, and Base caching modules.

Examples:

Using in a class method context

extend CacheHelper
cache_store.read(cache_key("budget", "global", "2024-01"))

Using in an instance method context

include CacheHelper
cache_store.write(cache_key("agent", agent_type), data, expires_in: 1.hour)

Constant Summary collapse

NAMESPACE =

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

Cache key namespace prefix

"ruby_llm_agents"

Instance Method Summary collapse

Instance Method Details

#cache_delete(key) ⇒ 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.

Deletes a key from the cache

Parameters:

  • key (String) —

    The cache key

Returns:

  • (Boolean) —

    Whether the delete succeeded



71
72
73
 
# File 'lib/ruby_llm/agents/infrastructure/cache_helper.rb', line 71

def cache_delete(key)
  cache_store.delete(key)
end

#cache_exist?(key) ⇒ 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.

Checks if a key exists in the cache

Parameters:

  • key (String) —

    The cache key

Returns:

  • (Boolean) —

    True if the key exists



63
64
65
 
# File 'lib/ruby_llm/agents/infrastructure/cache_helper.rb', line 63

def cache_exist?(key)
  cache_store.exist?(key)
end

#cache_increment(key, amount = 1, expires_in: nil) ⇒ Numeric

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.

Increments a numeric value in the cache

Falls back to read-modify-write if the cache store doesn’t support increment.

Parameters:

  • key (String) —

    The cache key

  • amount (Numeric) (defaults to: 1) —

    The amount to increment by (default: 1)

  • expires_in (ActiveSupport::Duration, nil) (defaults to: nil) —

    Optional TTL for the key

Returns:

  • (Numeric) —

    The new value



83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/ruby_llm/agents/infrastructure/cache_helper.rb', line 83

def cache_increment(key, amount = 1, expires_in: nil)
  if cache_store.respond_to?(:increment)
    # Ensure key exists with TTL
    cache_store.write(key, 0, expires_in: expires_in, unless_exist: true) if expires_in
    cache_store.increment(key, amount)
  else
    # Fallback for cache stores without atomic increment
    current = (cache_store.read(key) || 0).to_f
    new_value = current + amount
    cache_store.write(key, new_value, expires_in: expires_in)
    new_value
  end
end

#cache_key(*parts) ⇒ String

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.

Generates a namespaced cache key from the given parts

Examples:

cache_key("budget", "global", "2024-01")
# => "ruby_llm_agents:budget:global:2024-01"

Parameters:

  • parts (Array<String, Symbol>) —

    Key components to join

Returns:

  • (String) —

    Namespaced cache key



37
38
39
 
# File 'lib/ruby_llm/agents/infrastructure/cache_helper.rb', line 37

def cache_key(*parts)
  ([NAMESPACE] + parts.map(&:to_s)).join(":")
end

#cache_read(key) ⇒ 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.

Reads a value from the cache

Parameters:

  • key (String) —

    The cache key

Returns:

  • (Object, nil) —

    The cached value or nil



45
46
47
 
# File 'lib/ruby_llm/agents/infrastructure/cache_helper.rb', line 45

def cache_read(key)
  cache_store.read(key)
end

#cache_store ⇒ ActiveSupport::Cache::Store

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 the configured cache store

Returns:

  • (ActiveSupport::Cache::Store) 


26
27
28
 
# File 'lib/ruby_llm/agents/infrastructure/cache_helper.rb', line 26

def cache_store
  RubyLLM::Agents.configuration.cache_store
end

#cache_write(key, value, **options) ⇒ 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.

Writes a value to the cache

Parameters:

  • key (String) —

    The cache key

  • value (Object) —

    The value to cache

  • options (Hash) —

    Options passed to cache store (e.g., expires_in:)

Returns:

  • (Boolean) —

    Whether the write succeeded



55
56
57
 
# File 'lib/ruby_llm/agents/infrastructure/cache_helper.rb', line 55

def cache_write(key, value, **options)
  cache_store.write(key, value, **options)
end