langfuse-rb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5905472e2a3dc7fc674f1fbdc86b76105f8513a3079c00c8f9c5c346c19c2f16
-  data.tar.gz: 683d86aca0810243d76fd4a0e5418e635ccaf50fd0cbe966290541eff91ccf4e
+  metadata.gz: 60270020fc35460c5e29381351bbca35f1cdfe8b7dfe05eca43a0fb20dc06b7b
+  data.tar.gz: 4951c9b1546de4c9d00bb3b3be4c5325c8edf4d5bf6f5ecab7d9520ab052451b
 SHA512:
-  metadata.gz: a5a5b0352f26ce66c2997b6a9bdebde37f1629550bca0c7ef221ad1954f763f1d5a1343915c54d6354ccaafb02b9e7183ac66ef2bf18a9142a69a13852e41762
-  data.tar.gz: a2c05dd96df86951eccefd43719805b07595139f6dc56bc4fe1c35a54fe9ee3936ac4f06b4b1ac78fa419cdf717fd988f4555e349ab3b9a67738405e4ee34220
+  metadata.gz: 84fa1fc6ea91bda9ddcaa32dd43cb457439e0e4cdee06e3f3df88aae9c54c5b10abd16cb120f234da28733ba6497c466d0ece7888410d7b2711815e13f3956ef
+  data.tar.gz: 785bd5801a8c6b0ecd7c94f43083bdd6f12463bb918fa5f4a6faee32924a87a5058cf9700b20984fa9e8964cb3070975235771ddfddabca115cb33538020b065

data/CHANGELOG.md

@@ -7,54 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.0.0] - 2025-10-16 🚀
-
-### Initial Release
-
-Complete Ruby SDK for Langfuse with prompt management, distributed caching, LLM tracing, and Rails integration.
-
-#### Prompt Management
-- Fetch and compile text and chat prompts with Mustache templating
-- Support for prompt versioning and label-based fetching (production, staging, etc.)
-- Automatic variable substitution with nested objects and arrays
-- Global configuration pattern with `Langfuse.configure` block
-- Fallback prompt support for graceful error recovery
-
-#### Caching
-- Dual backend support: in-memory (default) and Rails.cache (distributed)
-- Thread-safe in-memory cache with TTL and LRU eviction
-- Distributed caching with Redis/Memcached via Rails.cache
-- Automatic stampede protection with distributed locks (Rails.cache only)
-- Cache warming utilities for deployment automation
-- Auto-discovery of all prompts with configurable labels
-
-#### LLM Tracing & Observability
-- Built on OpenTelemetry for industry-standard distributed tracing
-- Block-based Ruby API for traces, spans, and generations
-- Automatic prompt-to-trace linking
-- Token usage and cost tracking
-- W3C Trace Context support for distributed tracing across services
-- Integration with APM tools (Datadog, New Relic, Honeycomb, etc.)
-- Async processing with batch span export
-
-#### Rails Integration
-- Rails-friendly configuration with initializer support
-- Background job integration (Sidekiq, GoodJob, Delayed Job, etc.)
-- Rake tasks for cache management
-- Environment-specific configuration patterns
-- Credentials support for secure key management
-
-#### Developer Experience
-- Comprehensive error handling with specific error classes
-- HTTP client with automatic retry logic and exponential backoff
-- Circuit breaker pattern for resilience (via Stoplight)
-- 99.7% test coverage with 339 comprehensive test cases
-- Extensive documentation with guides for Rails, tracing, and migration
-
-#### Dependencies
-- Ruby >= 3.2.0
-- No Rails dependency (works with any Ruby project)
-- Minimal runtime dependencies (Faraday, Mustache, OpenTelemetry)
-
-[Unreleased]: https://github.com/langfuse/langfuse-ruby/compare/v1.0.0...HEAD
-[1.0.0]: https://github.com/langfuse/langfuse-ruby/releases/tag/v1.0.0
+## [0.3.0] - 2026-01-23
+
+### Added
+- Stale-while-revalidate (SWR) cache strategy for improved performance (#35)
+
+### Fixed
+- OpenTelemetry Baggage API method signatures for context propagation (#39)
+
+### Changed
+- Relaxed Faraday version constraint for better compatibility with older projects (#37)
+
+## [0.2.0] - 2025-12-19
+
+### Added
+- Prompt creation and update methods (`create_prompt`, `update_prompt`) (#36)
+
+## [0.1.0] - 2025-12-01
+
+### Added
+- Observe API with context propagation and scoring (#31)
+- W3C TraceContext propagator for distributed tracing (#1)
+- Ruby 3.4 support (#3)
+- OpenTelemetry-based tracing with OTLP export
+- Distributed caching with Rails.cache backend and stampede protection
+- Prompt management (text and chat) with Mustache templating
+- In-memory caching with TTL and LRU eviction
+- Fallback prompt support
+- Global configuration pattern with `Langfuse.configure`
+
+### Changed
+- Migrated from legacy ingestion API to OTLP endpoint
+- Removed `tracing_enabled` configuration flag (#2)
+
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/simplepractice/langfuse-rb/releases/tag/v0.1.0

data/README.md

@@ -2,49 +2,55 @@
 
 # Langfuse Ruby SDK
 
-[![Gem Version](https://badge.fury.io/rb/langfuse.svg)](https://badge.fury.io/rb/langfuse)
+[![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.
 
-## Features
+<br>
+
+### Features
 
 - 🎯 **Prompt Management** - Centralized prompt versioning with Mustache templating
 - 📊 **LLM Tracing** - Zero-boilerplate observability built on OpenTelemetry
-- ⚡ **Performance** - In-memory or Redis-backed caching with stampede protection
+- ⚡ **Performance** - In-memory or Redis-backed caching with stampede protection, both supporting stale-while-revalidate cache strategy
 - 💬 **Chat & Text Prompts** - First-class support for both formats
 - 🔄 **Automatic Retries** - Built-in exponential backoff for resilient API calls
 - 🛡️ **Fallback Support** - Graceful degradation when API unavailable
 - 🚀 **Rails-Friendly** - Global configuration pattern, works with any Ruby project
 
-## Installation
+<br>
+
+### Installation
 
 ```ruby
-# Gemfile
+# Add to Gemfile & bundle install
 gem 'langfuse-rb'
 ```
 
-```bash
-bundle install
-```
+<br>
 
-## Quick Start
+### Quick Start
 
-**Configure once at startup:**
+> Configure once at startup
 
 ```ruby
 # config/initializers/langfuse.rb (Rails)
-# or at the top of your script
+# Or at the top of your script
 Langfuse.configure do |config|
   config.public_key = ENV['LANGFUSE_PUBLIC_KEY']
   config.secret_key = ENV['LANGFUSE_SECRET_KEY']
   # Optional: for self-hosted instances
   config.base_url = ENV.fetch('LANGFUSE_BASE_URL', 'https://cloud.langfuse.com')
+
+  # Optional: Enable stale-while-revalidate for best performance
+  config.cache_backend = :rails  # or :memory
+  config.cache_stale_while_revalidate = true
 end
 ```
 
-**Fetch and use a prompt:**
+> Fetch and use a prompt
 
 ```ruby
 prompt = Langfuse.client.get_prompt("greeting")
@@ -52,7 +58,7 @@ message = prompt.compile(name: "Alice")
 # => "Hello Alice!"
 ```
 
-**Trace an LLM call:**
+> Trace an LLM call
 
 ```ruby
 Langfuse.observe("chat-completion", as_type: :generation) do |gen|
@@ -74,28 +80,35 @@ Langfuse.observe("chat-completion", as_type: :generation) do |gen|
 end
 ```
 
-> [!IMPORTANT]  
+> [!IMPORTANT]
 > For complete reference see [docs](./docs/) section.
 
-## Requirements
+<br>
+
+### Requirements
 
 - Ruby >= 3.2.0
 - No Rails dependency (works with any Ruby project)
 
-## Contributing
+<br>
+
+### Contributing
 
 We welcome contributions! Please:
 
-1. Check existing [issues](https://github.com/simplepractice/langfuse-rb/issues) and roadmap
+1. Check existing [issues](https://github.com/simplepractice/langfuse-rb/issues)
 2. Open an issue to discuss your idea
 3. Fork the repo and create a feature branch
 4. Write tests (maintain >95% coverage)
 5. Ensure `bundle exec rspec` and `bundle exec rubocop` pass
 6. Submit a pull request
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+> [!TIP]
+> See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+<br>
 
-## Support
+### Support
 
 - **[GitHub Issues](https://github.com/simplepractice/langfuse-rb/issues)** - Bug reports and feature requests
 - **[Langfuse Documentation](https://langfuse.com/docs)** - Platform documentation
@@ -103,4 +116,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE)

data/lib/langfuse/api_client.rb

@@ -4,6 +4,7 @@ require "faraday"
 require "faraday/retry"
 require "base64"
 require "json"
+require "uri"
 
 module Langfuse
   # HTTP client for Langfuse API
@@ -20,8 +21,7 @@ module Langfuse
   #     logger: Logger.new($stdout)
   #   )
   #
-  # rubocop:disable Metrics/ClassLength
-  class ApiClient
+  class ApiClient # rubocop:disable Metrics/ClassLength
     attr_reader :public_key, :secret_key, :base_url, :timeout, :logger, :cache
 
     # Initialize a new API client
@@ -106,26 +106,88 @@ module Langfuse
     # @raise [ApiError] for other API errors
     def get_prompt(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)
+    end
 
-      # Use distributed lock if cache supports it (Rails.cache backend)
-      if cache.respond_to?(:fetch_with_lock)
-        cache.fetch_with_lock(cache_key) do
-          fetch_prompt_from_api(name, version: version, label: label)
-        end
-      elsif cache
-        # In-memory cache - use simple get/set pattern
-        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
-      else
-        # No cache - fetch directly
-        fetch_prompt_from_api(name, version: version, label: label)
-      end
+    # Create a new prompt (or new version if prompt with same name exists)
+    #
+    # @param name [String] The prompt name
+    # @param prompt [String, Array<Hash>] The prompt content
+    # @param type [String] Prompt type ("text" or "chat")
+    # @param config [Hash] Optional configuration (model params, etc.)
+    # @param labels [Array<String>] Optional labels (e.g., ["production"])
+    # @param tags [Array<String>] Optional tags
+    # @param commit_message [String, nil] Optional commit message
+    # @return [Hash] The created prompt data
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example Create a text prompt
+    #   api_client.create_prompt(
+    #     name: "greeting",
+    #     prompt: "Hello {{name}}!",
+    #     type: "text",
+    #     labels: ["production"]
+    #   )
+    #
+    # rubocop:disable Metrics/ParameterLists
+    def create_prompt(name:, prompt:, type:, config: {}, labels: [], tags: [], commit_message: nil)
+      path = "/api/public/v2/prompts"
+      payload = {
+        name: name,
+        prompt: prompt,
+        type: type,
+        config: config,
+        labels: labels,
+        tags: tags
+      }
+      payload[:commitMessage] = commit_message if commit_message
+
+      response = connection.post(path, payload)
+      handle_response(response)
+    rescue Faraday::RetriableResponse => e
+      logger.error("Faraday error: Retries exhausted - #{e.response.status}")
+      handle_response(e.response)
+    rescue Faraday::Error => e
+      logger.error("Faraday error: #{e.message}")
+      raise ApiError, "HTTP request failed: #{e.message}"
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Update labels for an existing prompt version
+    #
+    # @param name [String] The prompt name
+    # @param version [Integer] The version number to update
+    # @param labels [Array<String>] New labels (replaces existing). Required.
+    # @return [Hash] The updated prompt data
+    # @raise [ArgumentError] if labels is not an array
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example Promote a prompt to production
+    #   api_client.update_prompt(
+    #     name: "greeting",
+    #     version: 2,
+    #     labels: ["production"]
+    #   )
+    def update_prompt(name:, version:, labels:)
+      raise ArgumentError, "labels must be an array" unless labels.is_a?(Array)
+
+      path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}/versions/#{version}"
+      payload = { newLabels: labels }
+
+      response = connection.patch(path, payload)
+      handle_response(response)
+    rescue Faraday::RetriableResponse => e
+      logger.error("Faraday error: Retries exhausted - #{e.response.status}")
+      handle_response(e.response)
+    rescue Faraday::Error => e
+      logger.error("Faraday error: #{e.message}")
+      raise ApiError, "HTTP request failed: #{e.message}"
     end
 
     # Send a batch of events to the Langfuse ingestion API
@@ -167,8 +229,63 @@ module Langfuse
       raise ApiError, "Batch send failed: #{e.message}"
     end
 
+    def shutdown
+      cache.shutdown if cache.respond_to?(:shutdown)
+    end
+
     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)
+      else
+        fetch_with_simple_cache(cache_key, name, version, label)
+      end
+    end
+
+    # Check if SWR cache is available
+    def swr_cache_available?
+      cache.respond_to?(:swr_enabled?) && cache.swr_enabled?
+    end
+
+    # Check if distributed cache is available
+    def distributed_cache_available?
+      cache.respond_to?(:fetch_with_lock)
+    end
+
+    # Fetch with SWR cache
+    def fetch_with_swr_cache(cache_key, name, version, label)
+      cache.fetch_with_stale_while_revalidate(cache_key) do
+        fetch_prompt_from_api(name, version: version, label: label)
+      end
+    end
+
+    # Fetch with distributed cache (Rails.cache with stampede protection)
+    def fetch_with_distributed_cache(cache_key, name, version, label)
+      cache.fetch_with_lock(cache_key) do
+        fetch_prompt_from_api(name, version: version, label: label)
+      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
@@ -180,7 +297,7 @@ module Langfuse
     # @raise [ApiError] for other API errors
     def fetch_prompt_from_api(name, version: nil, label: nil)
       params = build_prompt_params(version: version, label: label)
-      path = "/api/public/v2/prompts/#{name}"
+      path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}"
 
       response = connection.get(path, params)
       handle_response(response)
@@ -215,7 +332,9 @@ module Langfuse
     # Retries transient errors with exponential backoff:
     # - Max 2 retries (3 total attempts)
     # - Exponential backoff (0.05s * 2^retry_count)
-    # - Retries GET requests and POST requests to batch endpoint (idempotent operations)
+    # - Retries GET and PATCH requests (idempotent operations)
+    # - Retries POST requests to batch endpoint (idempotent due to event UUIDs)
+    # - Note: POST to create_prompt is NOT idempotent; retries may create duplicate versions
     # - Retries on: 429 (rate limit), 503 (service unavailable), 504 (gateway timeout)
     # - Does NOT retry on: 4xx errors (except 429), 5xx errors (except 503, 504)
     #
@@ -225,7 +344,7 @@ module Langfuse
         max: 2,
         interval: 0.05,
         backoff_factor: 2,
-        methods: %i[get post],
+        methods: %i[get post patch],
         retry_statuses: [429, 503, 504],
         exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
       }
@@ -278,7 +397,7 @@ module Langfuse
     # @raise [ApiError] for other error statuses
     def handle_response(response)
       case response.status
-      when 200
+      when 200, 201
         response.body
       when 401
         raise UnauthorizedError, "Authentication failed. Check your API keys."
@@ -327,4 +446,3 @@ module Langfuse
     end
   end
 end
-# rubocop:enable Metrics/ClassLength