Class: Langfuse::PromptCacheCoordinator Private

Inherits:
Object
  • Object
show all
Defined in:
lib/langfuse/prompt_cache_coordinator.rb

Overview

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

Coordinates prompt fetch/cache behavior between the API transport and the configured cache backend. Both supported backends (PromptCache and RailsCacheAdapter) provide the full cache + SWR surface; only RailsCacheAdapter adds distributed-lock fetch, which is the one branch the dispatch needs to make.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(cache:, event_emitter:, fetch_prompt:) ⇒ PromptCacheCoordinator

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.

Parameters:

  • cache (PromptCache, RailsCacheAdapter, nil) —

    Configured cache backend

  • event_emitter (#emit_prompt_cache_event) —

    Emitter for cache events

  • fetch_prompt (#call) —

    Callable that fetches prompt data from the API



19
20
21
22
23
24
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 19

def initialize(cache:, event_emitter:, fetch_prompt:)
  @cache = cache
  @event_emitter = event_emitter
  @fetch_prompt = fetch_prompt
  @backend_name = compute_backend_name
end

Instance Attribute Details

#backend_name ⇒ String (readonly)

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 Backend identifier reported in events and stats.

Returns:

  • (String) —

    Backend identifier reported in events and stats



27
28
29
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 27

def backend_name
  @backend_name
end

Instance Method Details

#clear_prompt_cache ⇒ Integer?

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.

Logically clear the entire prompt cache namespace.

Returns:

  • (Integer, nil) —

    New global generation, or nil when caching is disabled



119
120
121
122
123
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 119

def clear_prompt_cache
  generation = @cache&.clear_logically
  emit(:clear, backend: @backend_name, generation: generation)
  generation
end

#get_prompt_result(name, version: nil, label: nil, cache_ttl: nil) ⇒ PromptFetchResult

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.

Fetch a prompt and include cache metadata.

Parameters:

  • name (String) —

    Prompt name

  • version (Integer, nil) (defaults to: nil) —

    Optional prompt version

  • label (String, nil) (defaults to: nil) —

    Optional prompt label

  • cache_ttl (Integer, nil) (defaults to: nil) —

    Optional TTL override (0 forces a bypass)

Returns:



36
37
38
39
40
41
42
43
44
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 36

def get_prompt_result(name, version: nil, label: nil, cache_ttl: nil)
  validate_fetch_options!(version, label, cache_ttl)
  key = prompt_cache_key(name, version: version, label: label)

  return fetch_uncached(key, CacheStatus::DISABLED) if @cache.nil?
  return fetch_uncached(key, CacheStatus::BYPASS) if cache_ttl&.zero?

  fetch_cached(key, cache_ttl)
end

#invalidate_after_mutation(name) ⇒ Integer?

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.

Invalidate after prompt mutation (create/update). Distinct from manual invalidation so observers can tell the two apart.

Parameters:

  • name (String) —

    Prompt name

Returns:

  • (Integer, nil) —

    New generation



112
113
114
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 112

def invalidate_after_mutation(name)
  emit_name_invalidation(name, mutation: true)
end

#invalidate_prompt_cache(name, version: nil, label: nil) ⇒ PromptCacheKey

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.

Invalidate one exact logical prompt cache key.

Parameters:

  • name (String) —

    Prompt name

  • version (Integer, nil) (defaults to: nil) —

    Optional prompt version

  • label (String, nil) (defaults to: nil) —

    Optional prompt label

Returns:



91
92
93
94
95
96
97
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 91

def invalidate_prompt_cache(name, version: nil, label: nil)
  key = prompt_cache_key(name, version: version, label: label)
  deleted = @cache ? @cache.delete(key.storage_key) : false
  emit(:delete) { event_payload(key, CacheStatus::MISS, CacheSource::CACHE, deleted: deleted) }
  emit(:invalidate) { event_payload(key, CacheStatus::MISS, CacheSource::CACHE, scope: :exact) }
  key
end

#invalidate_prompt_cache_by_name(name) ⇒ Integer?

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.

Invalidate all cached variants for one prompt name.

Parameters:

  • name (String) —

    Prompt name

Returns:

  • (Integer, nil) —

    New generation, or nil when caching is disabled



103
104
105
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 103

def invalidate_prompt_cache_by_name(name)
  emit_name_invalidation(name, mutation: false)
end

#prompt_cache_key(name, version: nil, label: nil) ⇒ PromptCacheKey

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.

Inspect the logical and generated cache keys for a prompt.

Parameters:

  • name (String) —

    Prompt name

  • version (Integer, nil) (defaults to: nil) —

    Optional prompt version

  • label (String, nil) (defaults to: nil) —

    Optional prompt label

Returns:

Raises:

  • (ArgumentError) 


77
78
79
80
81
82
83
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 77

def prompt_cache_key(name, version: nil, label: nil)
  raise ArgumentError, "Cannot specify both version and label" if version && label

  logical_key = PromptCache.build_key(name, version: version, label: label)
  storage_key = @cache ? @cache.storage_key(logical_key, name: name) : logical_key
  PromptCacheKey.new(name: name, version: version, label: label, logical_key: logical_key, storage_key: storage_key)
end

#prompt_cache_stats ⇒ Hash

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 Prompt cache statistics.

Returns:

  • (Hash) —

    Prompt cache statistics



126
127
128
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 126

def prompt_cache_stats
  @cache ? @cache.stats : disabled_stats
end

#refresh_prompt(name, version: nil, label: nil, cache_ttl: nil) ⇒ PromptFetchResult

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.

Refresh a prompt from the API, optionally writing through to cache.

Parameters:

  • name (String) —

    Prompt name

  • version (Integer, nil) (defaults to: nil) —

    Optional prompt version

  • label (String, nil) (defaults to: nil) —

    Optional prompt label

  • cache_ttl (Integer, nil) (defaults to: nil) —

    Optional TTL override

Returns:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/langfuse/prompt_cache_coordinator.rb', line 53

def refresh_prompt(name, version: nil, label: nil, cache_ttl: nil)
  validate_fetch_options!(version, label, cache_ttl)
  key = prompt_cache_key(name, version: version, label: label)

  emit(:refresh_start) { event_payload(key, CacheStatus::REFRESH, CacheSource::API) }
  prompt_data = @fetch_prompt.call(name, version: version, label: label)
  write_through(key, prompt_data, cache_ttl, status: CacheStatus::REFRESH) if @cache && !cache_ttl&.zero?
  status = refresh_status(cache_ttl)
  emit(:refresh_success) { event_payload(key, status, CacheSource::API) }
  build_result(key, prompt_data, status, CacheSource::API)
rescue StandardError => e
  emit(:refresh_failure) do
    event_payload(key, CacheStatus::REFRESH, CacheSource::API,
                  error_class: e.class.name, error_message: e.message)
  end
  raise
end