langfuse-rb 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba92036fbe7b63b8355a113e44ff3f62cfcb11817ae3b3c1c444756af55ebf84
-  data.tar.gz: 44097d4d441ad6d2d8780a95cb836d0368ed0b772f16036e301ece7e018df0a1
+  metadata.gz: 0751bccadaa11e94f6fb8db5d8eb5a356b7102d2b811f1bc8b9b5e2f9c924072
+  data.tar.gz: 0c52e3a2738c090fa1804ed5a8722337ca58ba045a5aad0262e9a20ce4c1dd28
 SHA512:
-  metadata.gz: 6e8880c58683dc7ff719f0c966515841e9a3e3df024f88175297090949a6befaddf23528b24a65d3825fa40e33118348087c0dbe5312543c16bfef65856eaf12
-  data.tar.gz: a82f8be469125e99355c5b6a1bd747a1f2e395dd6e0eb098f8319a0976419dfd60087c6252e26c2570db15994ed084d3156069019541c3b32acc7f1827c92792
+  metadata.gz: 8a27652b71192d9a92b520f9c95af0990aae08af3e649b6c2d6f6827dacc3b8d402d3833e96abf2e7c5d20728defc19b1b92a4bc6b5778f47809f9266a34e11f
+  data.tar.gz: 435c45905b38b3f3f0e0641799394a9834c7ccd6e24d5f56adbf5cabed9345c77f7e842d33c91637c775c30f5b13cb26e434f9eb5fce45ac417b9e89544a9044

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-05-05
+
+### Added
+- Expose prompt cache operations on the client (#89)
+
+### Changed
+- Tighten cache event dispatch and generation safety for prompt caching (#90)
+
+### Documentation
+- Align README with sibling Langfuse SDKs (#88)
+
+## [0.9.0] - 2026-04-28
+
+### Added
+- Expose `type`, `commit_message`, and `resolution_graph` metadata on text and chat prompt clients (#87)
+
+### Fixed
+- Preserve and compile chat prompt message placeholders in parity with Langfuse Python and JS SDKs (#86)
+- Preserve raw prompt compile variables instead of HTML-escaping JSON, XML, and HTML-like values (#85)
+- Suppress prompt name/version attribution on fallback prompt clients so fallback output is not reported as prompt version 0 (#84)
+
+### Documentation
+- Link to upstream Langfuse agent skills and refresh README header image (#81, #83)
+
 ## [0.8.0] - 2026-04-24
 
 ### Added
@@ -100,7 +124,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrated from legacy ingestion API to OTLP endpoint
 - Removed `tracing_enabled` configuration flag (#2)
 
-[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.5.0...v0.6.0

data/README.md

@@ -1,74 +1,20 @@
-![header](https://camo.githubusercontent.com/26d19b945bc752101b4aca468e07b118a44af07340db79af29f7df95505f2cea/68747470733a2f2f6c616e67667573652e636f6d2f6c616e67667573655f6c6f676f5f77686974652e706e67)
+<img width="2255" height="527" alt="langfuse-wordart" src="https://github.com/user-attachments/assets/59422d0a-6ecb-4e5f-a21c-cae955b5ce75" />
 
 # Langfuse Ruby SDK
 
-[![Gem Version](https://badge.fury.io/rb/langfuse-rb.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/langfuse-rb)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2.0-ruby.svg)](https://www.ruby-lang.org/en/)
-[![Test Coverage](https://img.shields.io/badge/coverage-99.6%25-brightgreen.svg)](coverage)
-
-> Ruby SDK for [Langfuse](https://langfuse.com) - Open-source LLM observability and prompt management.
+[![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![CI test status](https://img.shields.io/github/actions/workflow/status/simplepractice/langfuse-rb/ci.yml?style=flat-square&label=All%20tests)](https://github.com/simplepractice/langfuse-rb/actions/workflows/ci.yml?query=branch%3Amain)
+[![Gem Version](https://img.shields.io/gem/v/langfuse-rb.svg?style=flat-square&label=gem+langfuse-rb)](https://rubygems.org/gems/langfuse-rb)
 
 ## Installation
 
-```ruby
-gem "langfuse-rb"
-```
-
-## Quick Start
-
-```ruby
-Langfuse.configure do |config|
-  config.public_key = ENV["LANGFUSE_PUBLIC_KEY"]
-  config.secret_key = ENV["LANGFUSE_SECRET_KEY"]
-  config.base_url = ENV.fetch("LANGFUSE_BASE_URL", "https://cloud.langfuse.com")
-
-  # Optional: sample traces and trace-linked scores deterministically
-  config.sample_rate = 1.0
-end
-
-message = Langfuse.client.compile_prompt(
-  "greeting",
-  variables: { name: "Alice" }
-)
-```
-
-Langfuse tracing is isolated by default. `Langfuse.configure` stores configuration only; it does not replace `OpenTelemetry.tracer_provider`.
-
-`sample_rate` is applied to traces and trace-linked scores. Rebuild the client with `Langfuse.reset!` before expecting runtime sampling changes to take effect.
-
-## Trace an LLM Call
+> [!IMPORTANT]
+> The SDK requires Ruby `>= 3.2.0`.
 
 ```ruby
-Langfuse.observe("chat-completion", as_type: :generation) do |gen|
-  gen.model = "gpt-4.1-mini"
-  gen.input = [{ role: "user", content: "Hello!" }]
-
-  response = openai_client.chat(
-    parameters: {
-      model: "gpt-4.1-mini",
-      messages: [{ role: "user", content: "Hello!" }]
-    }
-  )
-
-  gen.update(
-    output: response.dig("choices", 0, "message", "content"),
-    usage_details: {
-      prompt_tokens: response.dig("usage", "prompt_tokens"),
-      completion_tokens: response.dig("usage", "completion_tokens")
-    }
-  )
-end
+gem "langfuse-rb"
 ```
 
-## Start Here
-
-- [Documentation Hub](docs/README.md)
-- [Getting Started](docs/GETTING_STARTED.md)
-- [Prompts](docs/PROMPTS.md)
-- [Tracing](docs/TRACING.md)
-- [Scoring](docs/SCORING.md)
-- [Rails Patterns](docs/RAILS.md)
-
-## License
+## Docs
 
-[MIT](LICENSE)
+Please [see our docs](docs/README.md) for detailed information on this SDK.

data/lib/langfuse/api_client.rb

@@ -5,6 +5,7 @@ require "faraday/retry"
 require "base64"
 require "json"
 require "uri"
+require_relative "prompt_fetch_result"
 
 module Langfuse
   # HTTP client for Langfuse API
@@ -22,6 +23,16 @@ module Langfuse
   #   )
   #
   class ApiClient # rubocop:disable Metrics/ClassLength
+    include PromptCacheEvents
+
+    # Bundles the resolved cache key with the per-call TTL override so private
+    # prompt-fetch helpers take one arg instead of four.
+    PromptFetchOptions = Struct.new(:key, :cache_ttl, keyword_init: true) do
+      def name = key.name
+      def version = key.version
+      def label = key.label
+    end
+
     # @return [String] Langfuse public API key
     attr_reader :public_key
 
@@ -48,15 +59,20 @@ module Langfuse
     # @param timeout [Integer] HTTP request timeout in seconds
     # @param logger [Logger] Logger instance for debugging
     # @param cache [PromptCache, RailsCacheAdapter, nil] Optional cache for prompt responses
+    # @param cache_observer [#call, nil] Optional observer for prompt cache events
     # @return [ApiClient]
-    def initialize(public_key:, secret_key:, base_url:, timeout: 5, logger: nil, cache: nil)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(public_key:, secret_key:, base_url:, timeout: 5, logger: nil, cache: nil, cache_observer: nil)
       @public_key = public_key
       @secret_key = secret_key
       @base_url = base_url
       @timeout = timeout
       @logger = logger || Logger.new($stdout, level: Logger::WARN)
       @cache = cache
+      @cache_backend_name = compute_cache_backend_name
+      setup_prompt_cache_events(cache_observer: cache_observer)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Get a Faraday connection
     #
@@ -109,17 +125,127 @@ module Langfuse
     # @param name [String] The name of the prompt
     # @param version [Integer, nil] Optional specific version number
     # @param label [String, nil] Optional label (e.g., "production", "latest")
+    # @param cache_ttl [Integer, nil] Optional TTL override for this fetch
     # @return [Hash] The prompt data
     # @raise [ArgumentError] if both version and label are provided
     # @raise [NotFoundError] if the prompt is not found
     # @raise [UnauthorizedError] if authentication fails
     # @raise [ApiError] for other API errors
-    def get_prompt(name, version: nil, label: nil)
+    def get_prompt(name, version: nil, label: nil, cache_ttl: nil)
+      get_prompt_result(name, version: version, label: label, cache_ttl: cache_ttl).prompt
+    end
+
+    # Fetch a prompt and include cache metadata.
+    #
+    # @param name [String] The name of the prompt
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label (e.g., "production", "latest")
+    # @param cache_ttl [Integer, nil] Optional TTL override for this fetch
+    # @return [PromptFetchResult] Prompt data plus cache metadata
+    # @raise [ArgumentError] if both version and label are provided
+    # @raise [ArgumentError] if cache_ttl is negative
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def get_prompt_result(name, version: nil, label: nil, cache_ttl: nil)
+      validate_prompt_fetch_options!(version, label, cache_ttl)
+
+      options = PromptFetchOptions.new(
+        key: prompt_cache_key(name, version: version, label: label),
+        cache_ttl: cache_ttl
+      )
+      return fetch_uncached_prompt_result(options, CacheStatus::DISABLED) if cache.nil?
+      return fetch_uncached_prompt_result(options, CacheStatus::BYPASS) if cache_ttl&.zero?
+
+      fetch_cached_prompt_result(options)
+    end
+
+    # Refresh a prompt from the API, optionally writing through to cache.
+    #
+    # @param name [String] The name of the prompt
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label
+    # @param cache_ttl [Integer, nil] Optional TTL override for this refresh
+    # @return [PromptFetchResult] Prompt data plus cache metadata
+    # @raise [ArgumentError] if both version and label are provided
+    # @raise [ArgumentError] if cache_ttl is negative
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def refresh_prompt(name, version: nil, label: nil, cache_ttl: nil)
+      validate_prompt_fetch_options!(version, label, cache_ttl)
+
+      refresh_prompt_result(
+        PromptFetchOptions.new(
+          key: prompt_cache_key(name, version: version, label: label),
+          cache_ttl: cache_ttl
+        )
+      )
+    end
+
+    # Inspect the logical and generated cache keys for a prompt.
+    #
+    # @param name [String] The prompt name
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label
+    # @return [PromptCacheKey] Logical and generated cache keys
+    # @raise [ArgumentError] if both version and label are provided
+    def prompt_cache_key(name, version: nil, label: nil)
       raise ArgumentError, "Cannot specify both version and label" if version && label
-      return fetch_prompt_from_api(name, version: version, label: label) if cache.nil?
 
-      cache_key = PromptCache.build_key(name, version: version, label: label)
-      fetch_with_appropriate_caching_strategy(cache_key, name, version, label)
+      logical_key = PromptCache.build_key(name, version: version, label: label)
+      storage_key = if generated_storage_key_cache?
+                      cache.storage_key(logical_key, name: name)
+                    else
+                      logical_key
+                    end
+      PromptCacheKey.new(name: name, version: version, label: label, logical_key: logical_key, storage_key: storage_key)
+    end
+
+    # Invalidate one exact logical prompt cache key.
+    #
+    # @param name [String] The prompt name
+    # @param version [Integer, nil] Optional specific version number
+    # @param label [String, nil] Optional label
+    # @return [PromptCacheKey] The invalidated key
+    # @raise [ArgumentError] if both version and label are provided
+    def invalidate_prompt_cache(name, version: nil, label: nil)
+      key = prompt_cache_key(name, version: version, label: label)
+      deleted = cache&.delete(key.storage_key) || false
+      emit_prompt_cache_event(:delete) { event_payload(key, CacheStatus::MISS, CacheSource::CACHE, deleted: deleted) }
+      emit_prompt_cache_event(:invalidate) do
+        event_payload(key, CacheStatus::MISS, CacheSource::CACHE, scope: :exact)
+      end
+      key
+    end
+
+    # Invalidate all cached variants for one prompt name.
+    #
+    # @param name [String] The prompt name
+    # @return [Integer, nil] New generation, or nil when cache is disabled
+    def invalidate_prompt_cache_by_name(name)
+      generation = cache&.invalidate_name(name)
+      payload = { name: name, backend: cache_backend_name, generation: generation, scope: :name }
+      emit_prompt_cache_event(:invalidate, payload)
+      generation
+    end
+
+    # Logically clear the whole Langfuse prompt cache namespace.
+    #
+    # @return [Integer, nil] New global generation, or nil when cache is disabled
+    def clear_prompt_cache
+      generation = cache&.clear_logically
+      emit_prompt_cache_event(:clear, backend: cache_backend_name, generation: generation)
+      generation
+    end
+
+    # Return prompt cache statistics.
+    #
+    # @return [Hash] Cache statistics
+    def prompt_cache_stats
+      return disabled_prompt_cache_stats unless cache
+
+      cache.stats
     end
 
     # Create a new prompt (or new version if prompt with same name exists)
@@ -158,7 +284,7 @@ module Langfuse
         payload[:commitMessage] = commit_message if commit_message
 
         response = connection.post(path, payload)
-        handle_response(response)
+        handle_response(response).tap { invalidate_prompt_cache_after_mutation(name) }
       end
     end
     # rubocop:enable Metrics/ParameterLists
@@ -188,7 +314,7 @@ module Langfuse
         payload = { newLabels: labels }
 
         response = connection.patch(path, payload)
-        handle_response(response)
+        handle_response(response).tap { invalidate_prompt_cache_after_mutation(name) }
       end
     end
 
@@ -595,21 +721,219 @@ module Langfuse
 
     private
 
-    # Fetch prompt using the most appropriate caching strategy available
-    #
-    # @param cache_key [String] The cache key for this prompt
-    # @param name [String] The name of the prompt
-    # @param version [Integer, nil] Optional specific version number
-    # @param label [String, nil] Optional label
-    # @return [Hash] The prompt data
-    def fetch_with_appropriate_caching_strategy(cache_key, name, version, label)
-      if swr_cache_available?
-        fetch_with_swr_cache(cache_key, name, version, label)
-      elsif distributed_cache_available?
-        fetch_with_distributed_cache(cache_key, name, version, label)
+    def validate_prompt_fetch_options!(version, label, cache_ttl)
+      raise ArgumentError, "Cannot specify both version and label" if version && label
+      return if cache_ttl.nil?
+      raise ArgumentError, "cache_ttl must be a non-negative Integer" unless cache_ttl.is_a?(Integer)
+      raise ArgumentError, "cache_ttl must be non-negative" if cache_ttl.negative?
+    end
+
+    def fetch_uncached_prompt_result(options, cache_status)
+      prompt_data = fetch_prompt_for_options(options)
+      build_prompt_result(options.key, prompt_data, cache_status, CacheSource::API)
+    end
+
+    def fetch_cached_prompt_result(options)
+      return fetch_swr_prompt_result(options) if swr_cache_available?
+
+      fetch_non_swr_prompt_result(options)
+    end
+
+    def fetch_swr_prompt_result(options)
+      unless generated_storage_key_cache?
+        prompt_data = fetch_with_swr_cache(options.key.storage_key, options.name, options.version, options.label)
+        return cache_hit_prompt_result(options.key, prompt_data)
+      end
+
+      result = fetch_swr_cached_prompt_result(options)
+      return result if result
+
+      fetch_cache_miss_prompt_result(options, swr_enabled: true, distributed_enabled: false)
+    end
+
+    def fetch_non_swr_prompt_result(options)
+      distributed_enabled = distributed_cache_available?
+
+      if !generated_storage_key_cache? && distributed_enabled
+        prompt_data = fetch_with_distributed_cache(options.key.storage_key, options.name, options.version,
+                                                   options.label)
+        return cache_hit_prompt_result(options.key, prompt_data)
+      end
+
+      cached_data = cache.get(options.key.storage_key)
+      return cache_hit_prompt_result(options.key, cached_data) if cached_data
+
+      fetch_cache_miss_prompt_result(options, swr_enabled: false, distributed_enabled: distributed_enabled)
+    end
+
+    def fetch_swr_cached_prompt_result(options)
+      key = options.key
+      entry = cache.entry(key.storage_key) if cache.respond_to?(:entry)
+      return nil unless entry.respond_to?(:fresh?)
+      return cache_hit_prompt_result(key, entry.data) if entry.fresh?
+      return nil unless entry.stale?
+
+      emit_prompt_cache_event(:stale_serve) { event_payload(key, CacheStatus::STALE, CacheSource::CACHE) }
+      schedule_prompt_cache_refresh(options)
+      build_prompt_result(key, entry.data, CacheStatus::STALE, CacheSource::CACHE)
+    end
+
+    def cache_hit_prompt_result(key, prompt_data)
+      emit_prompt_cache_event(:hit) { event_payload(key, CacheStatus::HIT, CacheSource::CACHE) }
+      build_prompt_result(key, prompt_data, CacheStatus::HIT, CacheSource::CACHE)
+    end
+
+    def fetch_cache_miss_prompt_result(options, swr_enabled: false, distributed_enabled: nil)
+      emit_prompt_cache_event(:miss) { event_payload(options.key, CacheStatus::MISS, CacheSource::API) }
+      distributed_enabled = distributed_cache_available? if distributed_enabled.nil?
+
+      if !swr_enabled && distributed_enabled
+        fetch_cache_miss_with_lock(options)
       else
-        fetch_with_simple_cache(cache_key, name, version, label)
+        fetch_cache_miss_directly(options, swr_enabled: swr_enabled)
+      end
+    end
+
+    def fetch_cache_miss_with_lock(options)
+      key = options.key
+      fetched = false
+      prompt_data = cache_fetch_with_lock(key.storage_key, options.cache_ttl) do
+        fetched = true
+        fetch_prompt_for_options(options)
+      end
+      emit_prompt_cache_event(:write) { event_payload(key, CacheStatus::MISS, CacheSource::API) } if fetched
+      status = fetched ? CacheStatus::MISS : CacheStatus::HIT
+      source = fetched ? CacheSource::API : CacheSource::CACHE
+      build_prompt_result(key, prompt_data, status, source)
+    end
+
+    def fetch_cache_miss_directly(options, swr_enabled: false)
+      prompt_data = fetch_prompt_for_options(options)
+      write_prompt_cache(options.key, prompt_data, options.cache_ttl, swr_enabled: swr_enabled)
+      build_prompt_result(options.key, prompt_data, CacheStatus::MISS, CacheSource::API)
+    end
+
+    def refresh_prompt_result(options)
+      key = options.key
+      emit_prompt_cache_event(:refresh_start) { event_payload(key, CacheStatus::REFRESH, CacheSource::API) }
+      prompt_data = fetch_prompt_for_options(options)
+      write_refresh_prompt_cache(key, prompt_data, options.cache_ttl)
+      status = refresh_cache_status(options.cache_ttl)
+      emit_prompt_cache_event(:refresh_success) { event_payload(key, status, CacheSource::API) }
+      build_prompt_result(key, prompt_data, status, CacheSource::API)
+    rescue StandardError => e
+      emit_prompt_cache_event(:refresh_failure) do
+        event_payload(key, CacheStatus::REFRESH, CacheSource::API,
+                      error_class: e.class.name, error_message: e.message)
       end
+      raise
+    end
+
+    def schedule_prompt_cache_refresh(options)
+      return unless cache.respond_to?(:refresh_async)
+
+      key = options.key
+      scheduled = cache.refresh_async(
+        key.storage_key,
+        ttl: options.cache_ttl,
+        on_success: ->(_value) { emit_refresh_success_events(key) },
+        on_failure: ->(error) { emit_refresh_failure_event(key, error) }
+      ) { fetch_prompt_for_options(options) }
+      return unless scheduled
+
+      emit_prompt_cache_event(:refresh_start) { event_payload(key, CacheStatus::STALE, CacheSource::CACHE) }
+    end
+
+    def fetch_prompt_for_options(options)
+      fetch_prompt_from_api(options.name, version: options.version, label: options.label)
+    end
+
+    def emit_refresh_success_events(key)
+      emit_prompt_cache_event(:refresh_success) { event_payload(key, CacheStatus::REFRESH, CacheSource::API) }
+      emit_prompt_cache_event(:write) { event_payload(key, CacheStatus::REFRESH, CacheSource::API) }
+    end
+
+    def emit_refresh_failure_event(key, error)
+      emit_prompt_cache_event(:refresh_failure) do
+        event_payload(key, CacheStatus::STALE, CacheSource::CACHE,
+                      error_class: error.class.name, error_message: error.message)
+      end
+    end
+
+    def write_refresh_prompt_cache(key, prompt_data, cache_ttl)
+      return unless cache
+      return if cache_ttl&.zero?
+
+      write_prompt_cache(key, prompt_data, cache_ttl,
+                         cache_status: CacheStatus::REFRESH, swr_enabled: swr_cache_available?)
+    end
+
+    def write_prompt_cache(key, prompt_data, cache_ttl, cache_status: CacheStatus::MISS, swr_enabled: false)
+      if swr_enabled && cache.respond_to?(:write_with_stale_while_revalidate)
+        cache.write_with_stale_while_revalidate(key.storage_key, prompt_data, ttl: cache_ttl)
+      elsif cache_ttl.nil?
+        cache.set(key.storage_key, prompt_data)
+      else
+        cache.set(key.storage_key, prompt_data, ttl: cache_ttl)
+      end
+      emit_prompt_cache_event(:write) { event_payload(key, cache_status, CacheSource::API) }
+    end
+
+    def cache_fetch_with_lock(storage_key, cache_ttl, &)
+      return cache.fetch_with_lock(storage_key, &) if cache_ttl.nil?
+
+      cache.fetch_with_lock(storage_key, ttl: cache_ttl, &)
+    end
+
+    def refresh_cache_status(cache_ttl)
+      return CacheStatus::DISABLED unless cache
+      return CacheStatus::BYPASS if cache_ttl&.zero?
+
+      CacheStatus::REFRESH
+    end
+
+    def build_prompt_result(key, prompt_data, cache_status, source)
+      PromptFetchResult.new(
+        prompt: prompt_data,
+        logical_key: key.logical_key,
+        storage_key: key.storage_key,
+        cache_status: cache_status,
+        source: source,
+        name: prompt_data["name"] || key.name,
+        version: prompt_data["version"] || key.version,
+        label: key.resolved_label
+      )
+    end
+
+    attr_reader :cache_backend_name
+
+    def compute_cache_backend_name
+      return CacheBackend::DISABLED unless cache
+      return CacheBackend::RAILS if cache.is_a?(RailsCacheAdapter)
+      return CacheBackend::MEMORY if cache.is_a?(PromptCache)
+
+      cache.class.name
+    end
+
+    def disabled_prompt_cache_stats
+      {
+        backend: CacheBackend::DISABLED,
+        enabled: false,
+        current_generation_entries: nil,
+        orphaned_entries: nil,
+        total_entries: nil,
+        unsupported_counts: CacheBackend::UNSUPPORTED_COUNT_KEYS
+      }
+    end
+
+    def generated_storage_key_cache?
+      cache.is_a?(PromptCache) || cache.is_a?(RailsCacheAdapter)
+    end
+
+    def invalidate_prompt_cache_after_mutation(name)
+      generation = cache&.invalidate_name(name)
+      payload = { name: name, backend: cache_backend_name, generation: generation, scope: :name, mutation: true }
+      emit_prompt_cache_event(:invalidate, payload)
     end
 
     # Check if SWR cache is available
@@ -707,16 +1031,6 @@ module Langfuse
       end
     end
 
-    # Fetch with simple cache (in-memory cache)
-    def fetch_with_simple_cache(cache_key, name, version, label)
-      cached_data = cache.get(cache_key)
-      return cached_data if cached_data
-
-      prompt_data = fetch_prompt_from_api(name, version: version, label: label)
-      cache.set(cache_key, prompt_data)
-      prompt_data
-    end
-
     # Fetch a prompt from the API (without caching)
     #
     # @param name [String] The name of the prompt

data/lib/langfuse/cache_constants.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Symbol constants for prompt cache event payloads.
+  # Producers (ApiClient, PromptFetchResult) and consumers (observers,
+  # ActiveSupport::Notifications subscribers) share these definitions so a
+  # rename in one place can't silently desync from the other.
+  module CacheStatus
+    HIT = :hit
+    MISS = :miss
+    STALE = :stale
+    REFRESH = :refresh
+    BYPASS = :bypass
+    DISABLED = :disabled
+  end
+
+  module CacheSource
+    CACHE = :cache
+    API = :api
+    FALLBACK = :fallback
+  end
+
+  module CacheBackend
+    MEMORY = "memory"
+    RAILS = "rails"
+    DISABLED = "disabled"
+
+    # Stat keys backend implementations may not be able to compute. Surfaced in
+    # `#stats[:unsupported_counts]` so callers can distinguish "0" from "unknown".
+    UNSUPPORTED_COUNT_KEYS = %i[current_generation_entries orphaned_entries total_entries].freeze
+  end
+end