class RubyLLM::CachedContent

A CachedContent is a provider-side prompt cache resource. Create one with ::create from a long, stable prompt prefix, then attach it to a chat so later requests read the cached tokens instead of resending them. This lifecycle requires a provider with managed cache resources; automatic prompt caching is configured with Chat#with_caching.

cache = RubyLLM.cache(big_document, model: 'gemini-3.7-flash', ttl: 3600)
chat = RubyLLM.chat(model: 'gemini-3.7-flash').with_caching(id: cache)
chat.ask "What does the document conclude?"
cache.delete

Cache names are provider-owned. Persist provider alongside name and pass it back when finding the cache later.

Attributes

created_at [R]

The Time the provider stored the cache.

expires_at [R]

The Time the provider will delete the cache.

metadata [R]

The raw provider response data for the cache, as a Hash.

model [R]

The model the cache was created for.

name [R]

The provider-assigned resource name, such as "cachedContents/abc123".

provider [R]

The slug of the provider that stores the cache.

tokens [R]

The number of tokens stored in the cache.

Public Class Methods

create (content, model:, ttl: nil, instructions: nil, provider: nil, context: nil, with: nil)

Source

# File lib/ruby_llm/cached_content.rb, line 88
def self.create(content, model:, ttl: nil, instructions: nil, provider: nil, context: nil, with: nil)
  config = context&.config || RubyLLM.config
  model_instance, provider_instance = Models.resolve(model, provider: provider, config: config)

  provider_instance.cache_content(content, model: model_instance, ttl:, instructions:, with:)
end

Creates a provider-side prompt cache from content and returns a CachedContent. Also available as RubyLLM.cache.

RubyLLM::CachedContent.create(big_document, model: 'gemini-3.7-flash')

content is the text to cache; pass file attachments with with: the way Chat#ask accepts them. instructions: caches a system prompt alongside the content, and ttl: sets the cache lifetime in seconds (Integer) or as a provider duration string such as "300s". When provider: is omitted, the model’s default provider is used. The content must exceed the model’s minimum cacheable token count.

find (name, provider: nil, context: nil)

Source

# File lib/ruby_llm/cached_content.rb, line 101
def self.find(name, provider: nil, context: nil)
  config = context&.config || RubyLLM.config

  provider_instance = if provider
                        Provider.resolve!(provider).new(config)
                      else
                        Models.resolve(config.default_model, config:).last
                      end
  provider_instance.find_cache(name)
end

Fetches an existing cache resource by name and returns a CachedContent. When provider: is omitted, the provider of the configured default model is used.

cache = RubyLLM::CachedContent.find("cachedContents/abc123", provider: :gemini)

Public Instance Methods

delete ()

Source

# File lib/ruby_llm/cached_content.rb, line 58
def delete
  @provider_instance.delete_cache(name)
  self
end

Deletes the cache resource from the provider. Returns self.

renew (ttl:)

Source

# File lib/ruby_llm/cached_content.rb, line 69
def renew(ttl:)
  refreshed = @provider_instance.extend_cache(name, ttl: ttl)
  @expires_at = refreshed.expires_at
  @metadata = refreshed.metadata
  self
end

Extends the cache’s lifetime to ttl: seconds from now, given as an Integer or a provider duration string such as "600s". Updates expires_at and returns self.

cache.renew(ttl: 3600)