langfuse-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5905472e2a3dc7fc674f1fbdc86b76105f8513a3079c00c8f9c5c346c19c2f16
+  data.tar.gz: 683d86aca0810243d76fd4a0e5418e635ccaf50fd0cbe966290541eff91ccf4e
+SHA512:
+  metadata.gz: a5a5b0352f26ce66c2997b6a9bdebde37f1629550bca0c7ef221ad1954f763f1d5a1343915c54d6354ccaafb02b9e7183ac66ef2bf18a9142a69a13852e41762
+  data.tar.gz: a2c05dd96df86951eccefd43719805b07595139f6dc56bc4fe1c35a54fe9ee3936ac4f06b4b1ac78fa419cdf717fd988f4555e349ab3b9a67738405e4ee34220

data/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [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

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Langfuse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+![header](https://camo.githubusercontent.com/26d19b945bc752101b4aca468e07b118a44af07340db79af29f7df95505f2cea/68747470733a2f2f6c616e67667573652e636f6d2f6c616e67667573655f6c6f676f5f77686974652e706e67)
+
+# Langfuse Ruby SDK
+
+[![Gem Version](https://badge.fury.io/rb/langfuse.svg)](https://badge.fury.io/rb/langfuse)
+[![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
+
+- 🎯 **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
+- 💬 **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
+
+```ruby
+# Gemfile
+gem 'langfuse-rb'
+```
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+**Configure once at startup:**
+
+```ruby
+# config/initializers/langfuse.rb (Rails)
+# 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')
+end
+```
+
+**Fetch and use a prompt:**
+
+```ruby
+prompt = Langfuse.client.get_prompt("greeting")
+message = prompt.compile(name: "Alice")
+# => "Hello Alice!"
+```
+
+**Trace an LLM call:**
+
+```ruby
+Langfuse.observe("chat-completion", as_type: :generation) do |gen|
+  response = openai_client.chat(
+    parameters: {
+      model: "gpt-4",
+      messages: [{ role: "user", content: "Hello!" }]
+    }
+  )
+
+  gen.update(
+    model: "gpt-4",
+    output: response.dig("choices", 0, "message", "content"),
+    usage_details: {
+      prompt_tokens: response.dig("usage", "prompt_tokens"),
+      completion_tokens: response.dig("usage", "completion_tokens")
+    }
+  )
+end
+```
+
+> [!IMPORTANT]  
+> For complete reference see [docs](./docs/) section.
+
+## Requirements
+
+- Ruby >= 3.2.0
+- No Rails dependency (works with any Ruby project)
+
+## Contributing
+
+We welcome contributions! Please:
+
+1. Check existing [issues](https://github.com/simplepractice/langfuse-rb/issues) and roadmap
+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.
+
+## Support
+
+- **[GitHub Issues](https://github.com/simplepractice/langfuse-rb/issues)** - Bug reports and feature requests
+- **[Langfuse Documentation](https://langfuse.com/docs)** - Platform documentation
+- **[API Reference](https://api.reference.langfuse.com)** - REST API reference
+
+## License
+
+[MIT](LICENSE)

data/lib/langfuse/api_client.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "base64"
+require "json"
+
+module Langfuse
+  # HTTP client for Langfuse API
+  #
+  # Handles authentication, connection management, and HTTP requests
+  # to the Langfuse REST API.
+  #
+  # @example
+  #   api_client = Langfuse::ApiClient.new(
+  #     public_key: "pk_...",
+  #     secret_key: "sk_...",
+  #     base_url: "https://cloud.langfuse.com",
+  #     timeout: 5,
+  #     logger: Logger.new($stdout)
+  #   )
+  #
+  # rubocop:disable Metrics/ClassLength
+  class ApiClient
+    attr_reader :public_key, :secret_key, :base_url, :timeout, :logger, :cache
+
+    # Initialize a new API client
+    #
+    # @param public_key [String] Langfuse public API key
+    # @param secret_key [String] Langfuse secret API key
+    # @param base_url [String] Base URL for Langfuse API
+    # @param timeout [Integer] HTTP request timeout in seconds
+    # @param logger [Logger] Logger instance for debugging
+    # @param cache [PromptCache, nil] Optional cache for prompt responses
+    def initialize(public_key:, secret_key:, base_url:, timeout: 5, logger: nil, cache: 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
+    end
+
+    # Get a Faraday connection
+    #
+    # @param timeout [Integer, nil] Optional custom timeout for this connection
+    # @return [Faraday::Connection]
+    def connection(timeout: nil)
+      if timeout
+        # Create dedicated connection for custom timeout
+        # to avoid mutating shared connection
+        build_connection(timeout: timeout)
+      else
+        @connection ||= build_connection
+      end
+    end
+
+    # List all prompts in the Langfuse project
+    #
+    # Fetches a list of all prompt names available in your project.
+    # Note: This returns metadata only, not full prompt content.
+    #
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page (default: API default)
+    # @return [Array<Hash>] Array of prompt metadata hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   prompts = api_client.list_prompts
+    #   prompts.each do |prompt|
+    #     puts "#{prompt['name']} (v#{prompt['version']})"
+    #   end
+    def list_prompts(page: nil, limit: nil)
+      params = {}
+      params[:page] = page if page
+      params[:limit] = limit if limit
+
+      path = "/api/public/v2/prompts"
+      response = connection.get(path, params)
+      result = handle_response(response)
+
+      # API returns { data: [...], meta: {...} }
+      result["data"] || []
+    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
+
+    # Fetch a prompt from the Langfuse API
+    #
+    # Checks cache first if caching is enabled. On cache miss, fetches from API
+    # and stores in cache. When using Rails.cache backend, uses distributed lock
+    # to prevent cache stampedes.
+    #
+    # @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")
+    # @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)
+      raise ArgumentError, "Cannot specify both version and label" if version && label
+
+      cache_key = PromptCache.build_key(name, version: version, label: label)
+
+      # 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
+    end
+
+    # Send a batch of events to the Langfuse ingestion API
+    #
+    # Sends events (scores, traces, observations) to the ingestion endpoint.
+    # Retries transient errors (429, 503, 504, network errors) with exponential backoff.
+    # Batch operations are idempotent (events have unique IDs), so retries are safe.
+    #
+    # @param events [Array<Hash>] Array of event hashes to send
+    # @return [void]
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors after retries exhausted
+    #
+    # @example
+    #   events = [
+    #     {
+    #       id: SecureRandom.uuid,
+    #       type: "score-create",
+    #       timestamp: Time.now.iso8601,
+    #       body: { name: "quality", value: 0.85, trace_id: "abc123..." }
+    #     }
+    #   ]
+    #   api_client.send_batch(events)
+    def send_batch(events)
+      raise ArgumentError, "events must be an array" unless events.is_a?(Array)
+      raise ArgumentError, "events array cannot be empty" if events.empty?
+
+      path = "/api/public/ingestion"
+      payload = { batch: events }
+
+      response = connection.post(path, payload)
+      handle_batch_response(response)
+    rescue Faraday::RetriableResponse => e
+      # Retry middleware exhausted all retries - handle the final response
+      logger.error("Langfuse batch send failed: Retries exhausted - #{e.response.status}")
+      handle_batch_response(e.response)
+    rescue Faraday::Error => e
+      logger.error("Langfuse batch send failed: #{e.message}")
+      raise ApiError, "Batch send failed: #{e.message}"
+    end
+
+    private
+
+    # Fetch a prompt from the API (without caching)
+    #
+    # @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
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @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}"
+
+      response = connection.get(path, params)
+      handle_response(response)
+    rescue Faraday::RetriableResponse => e
+      # Retry middleware exhausted all retries - handle the final response
+      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
+
+    # Build a new Faraday connection
+    #
+    # @param timeout [Integer, nil] Optional timeout override
+    # @return [Faraday::Connection]
+    def build_connection(timeout: nil)
+      Faraday.new(
+        url: base_url,
+        headers: default_headers
+      ) do |conn|
+        conn.request :json
+        conn.request :retry, retry_options
+        conn.response :json, content_type: /\bjson$/
+        conn.adapter Faraday.default_adapter
+        conn.options.timeout = timeout || @timeout
+      end
+    end
+
+    # Configuration for retry middleware
+    #
+    # 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 on: 429 (rate limit), 503 (service unavailable), 504 (gateway timeout)
+    # - Does NOT retry on: 4xx errors (except 429), 5xx errors (except 503, 504)
+    #
+    # @return [Hash] Retry options for Faraday::Retry middleware
+    def retry_options
+      {
+        max: 2,
+        interval: 0.05,
+        backoff_factor: 2,
+        methods: %i[get post],
+        retry_statuses: [429, 503, 504],
+        exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
+      }
+    end
+
+    # Default headers for all requests
+    #
+    # @return [Hash]
+    def default_headers
+      {
+        "Authorization" => authorization_header,
+        "User-Agent" => user_agent,
+        "Content-Type" => "application/json"
+      }
+    end
+
+    # Generate Basic Auth header
+    #
+    # @return [String] Basic Auth header value
+    def authorization_header
+      credentials = "#{public_key}:#{secret_key}"
+      "Basic #{Base64.strict_encode64(credentials)}"
+    end
+
+    # User agent string
+    #
+    # @return [String]
+    def user_agent
+      "langfuse-rb/#{Langfuse::VERSION}"
+    end
+
+    # Build query parameters for prompt request
+    #
+    # @param version [Integer, nil] Optional version number
+    # @param label [String, nil] Optional label
+    # @return [Hash] Query parameters
+    def build_prompt_params(version: nil, label: nil)
+      params = {}
+      params[:version] = version if version
+      params[:label] = label if label
+      params
+    end
+
+    # Handle HTTP response and raise appropriate errors
+    #
+    # @param response [Faraday::Response] The HTTP response
+    # @return [Hash] The parsed response body
+    # @raise [NotFoundError] if status is 404
+    # @raise [UnauthorizedError] if status is 401
+    # @raise [ApiError] for other error statuses
+    def handle_response(response)
+      case response.status
+      when 200
+        response.body
+      when 401
+        raise UnauthorizedError, "Authentication failed. Check your API keys."
+      when 404
+        raise NotFoundError, "Prompt not found"
+      else
+        error_message = extract_error_message(response)
+        raise ApiError, "API request failed (#{response.status}): #{error_message}"
+      end
+    end
+
+    # Handle HTTP response for batch requests
+    #
+    # @param response [Faraday::Response] The HTTP response
+    # @return [void]
+    # @raise [UnauthorizedError] if status is 401
+    # @raise [ApiError] for other error statuses
+    def handle_batch_response(response)
+      case response.status
+      when 200, 201, 204, 207
+        nil
+      when 401
+        raise UnauthorizedError, "Authentication failed. Check your API keys."
+      else
+        error_message = extract_error_message(response)
+        raise ApiError, "Batch send failed (#{response.status}): #{error_message}"
+      end
+    end
+
+    # Extract error message from response body
+    #
+    # @param response [Faraday::Response] The HTTP response
+    # @return [String] The error message
+    def extract_error_message(response)
+      body_hash = case response.body
+                  in Hash => h then h
+                  in String => s then begin
+                    JSON.parse(s)
+                  rescue StandardError
+                    {}
+                  end
+                  else {}
+                  end
+
+      %w[message error].filter_map { |key| body_hash[key] }.first || "Unknown error"
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength