langfuse-ruby 0.1.7 → 0.2.1

data/lib/langfuse/trace.rb

@@ -2,12 +2,14 @@
 
 module Langfuse
   class Trace
+    include PartialUpdates
+
     attr_reader :id, :name, :user_id, :session_id, :version, :release, :input, :output,
-                :metadata, :tags, :timestamp, :client
+                :metadata, :tags, :timestamp, :public, :client
 
     def initialize(client:, id:, name: nil, user_id: nil, session_id: nil, version: nil,
                    release: nil, input: nil, output: nil, metadata: nil, tags: nil,
-                   timestamp: nil, **kwargs)
+                   timestamp: nil, public: nil, **kwargs)
       @client = client
       @id = id
       @name = name
@@ -20,6 +22,7 @@ module Langfuse
       @metadata = metadata || {}
       @tags = tags || []
       @timestamp = timestamp
+      @public = public
       @kwargs = kwargs
 
       # Create the trace
@@ -50,6 +53,7 @@ module Langfuse
     # Create a child generation
     def generation(name: nil, start_time: nil, end_time: nil, completion_start_time: nil,
                    model: nil, model_parameters: nil, input: nil, output: nil, usage: nil,
+                   usage_details: nil, cost_details: nil, prompt: nil,
                    metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
                    version: nil, **kwargs)
       @client.generation(
@@ -63,6 +67,9 @@ module Langfuse
         input: input,
         output: output,
         usage: usage,
+        usage_details: usage_details,
+        cost_details: cost_details,
+        prompt: prompt,
         metadata: metadata,
         level: level,
         status_message: status_message,
@@ -90,87 +97,11 @@ module Langfuse
       )
     end
 
-    # Convenience methods for enhanced observation types
-
-    # Create a child agent observation
-    def agent(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-              metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
-              version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        parent_observation_id: parent_observation_id,
-        version: version,
-        as_type: ObservationType::AGENT,
-        **kwargs
-      )
-    end
-
-    # Create a child tool observation
-    def tool(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-             metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
-             version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        parent_observation_id: parent_observation_id,
-        version: version,
-        as_type: ObservationType::TOOL,
-        **kwargs
-      )
-    end
-
-    # Create a child chain observation
-    def chain(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-              metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
-              version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        parent_observation_id: parent_observation_id,
-        version: version,
-        as_type: ObservationType::CHAIN,
-        **kwargs
-      )
-    end
-
-    # Create a child retriever observation
-    def retriever(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-                  metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
-                  version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        parent_observation_id: parent_observation_id,
-        version: version,
-        as_type: ObservationType::RETRIEVER,
-        **kwargs
-      )
-    end
+    # Convenience methods for enhanced observation types: each is a child span
+    # with a fixed as_type. (embedding keeps its own definition because it folds
+    # model/usage into metadata first.)
+    extend SpanWrappers
+    define_span_wrappers
 
     # Create a child embedding observation
     def embedding(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
@@ -195,46 +126,6 @@ module Langfuse
       )
     end
 
-    # Create a child evaluator observation
-    def evaluator(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-                  metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
-                  version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        parent_observation_id: parent_observation_id,
-        version: version,
-        as_type: ObservationType::EVALUATOR,
-        **kwargs
-      )
-    end
-
-    # Create a child guardrail observation
-    def guardrail(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-                  metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
-                  version: nil, **kwargs)
-      span(
-        name: name,
-        start_time: start_time,
-        end_time: end_time,
-        input: input,
-        output: output,
-        metadata: metadata,
-        level: level,
-        status_message: status_message,
-        parent_observation_id: parent_observation_id,
-        version: version,
-        as_type: ObservationType::GUARDRAIL,
-        **kwargs
-      )
-    end
-
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
         trace_id: @id,
@@ -247,20 +138,30 @@ module Langfuse
     end
 
     def update(name: nil, user_id: nil, session_id: nil, version: nil,
-               release: nil, input: nil, output: nil, metadata: nil, tags: nil, **kwargs)
+               release: nil, input: nil, output: nil, metadata: nil, tags: nil,
+               public: nil, **kwargs)
       # 更新实例变量
-      @name = name if name
-      @user_id = user_id if user_id
-      @session_id = session_id if session_id
-      @version = version if version
-      @release = release if release
-      @input = input if input
-      @output = output if output
-      @metadata = metadata if metadata
-      @tags = tags if tags
+      @name = name unless name.nil?
+      @user_id = user_id unless user_id.nil?
+      @session_id = session_id unless session_id.nil?
+      @version = version unless version.nil?
+      @release = release unless release.nil?
+      @input = input unless input.nil?
+      @output = output unless output.nil?
+      @metadata.merge!(metadata) if metadata
+      @tags = tags unless tags.nil?
+      @public = public unless public.nil?
       @kwargs.merge!(kwargs) if kwargs.any?
+
+      track_changes(
+        { name: name, user_id: user_id, session_id: session_id, version: version,
+          release: release, input: input, output: output, metadata: metadata,
+          tags: tags, public: public },
+        kwargs.keys
+      )
       # 触发 trace-update 事件
       update_trace
+      self
     end
 
     def get_url
@@ -279,46 +180,19 @@ module Langfuse
         output: @output,
         metadata: @metadata,
         tags: @tags,
-        timestamp: @timestamp
+        timestamp: @timestamp,
+        public: @public
       }.merge(@kwargs).compact
     end
 
     private
 
     def create_trace
-      data = {
-        id: @id,
-        name: @name,
-        user_id: @user_id,
-        session_id: @session_id,
-        version: @version,
-        release: @release,
-        input: @input,
-        output: @output,
-        metadata: @metadata,
-        tags: @tags,
-        timestamp: @timestamp
-      }.merge(@kwargs).compact
-
-      @client.enqueue_event('trace-create', data)
+      @client.enqueue_event('trace-create', to_dict)
     end
 
     def update_trace
-      data = {
-        id: @id,
-        name: @name,
-        user_id: @user_id,
-        session_id: @session_id,
-        version: @version,
-        release: @release,
-        input: @input,
-        output: @output,
-        metadata: @metadata,
-        tags: @tags,
-        timestamp: @timestamp
-      }.merge(@kwargs).compact
-
-      @client.enqueue_event('trace-update', data)
+      @client.enqueue_event('trace-update', update_body, trace_ref: self)
     end
   end
 end

data/lib/langfuse/utils.rb

@@ -6,11 +6,25 @@ require 'erb'
 
 module Langfuse
   module Utils
+    # Body keys whose values must be passed through verbatim (user data),
+    # everything else nested under them keeps its original key format.
+    VERBATIM_BODY_KEYS = %w[input output metadata usageDetails costDetails modelParameters].freeze
+
     class << self
       def generate_id
         SecureRandom.uuid
       end
 
+      # W3C-compatible 32-char hex trace ID (16 bytes), used for OTel ingestion
+      def generate_hex_trace_id
+        SecureRandom.hex(16)
+      end
+
+      # W3C-compatible 16-char hex span/observation ID (8 bytes), used for OTel ingestion
+      def generate_hex_span_id
+        SecureRandom.hex(8)
+      end
+
       def current_timestamp
         Time.now.utc.iso8601(3)
       end
@@ -19,34 +33,54 @@ module Langfuse
         ERB::Util.url_encode(string.to_s)
       end
 
-      def deep_symbolize_keys(hash)
-        return hash unless hash.is_a?(Hash)
-
-        hash.each_with_object({}) do |(key, value), result|
-          new_key = key.is_a?(String) ? key.to_sym : key
-          new_value = value.is_a?(Hash) ? deep_symbolize_keys(value) : value
-          result[new_key] = new_value
+      def deep_symbolize_keys(object)
+        case object
+        when Hash
+          object.each_with_object({}) do |(key, value), result|
+            new_key = key.is_a?(String) ? key.to_sym : key
+            result[new_key] = deep_symbolize_keys(value)
+          end
+        when Array
+          object.map { |item| deep_symbolize_keys(item) }
+        else
+          object
         end
       end
 
-      def deep_stringify_keys(hash)
-        return hash unless hash.is_a?(Hash)
-
-        hash.each_with_object({}) do |(key, value), result|
-          new_key = camelize_key(key.to_s)
-          new_value = value.is_a?(Hash) ? deep_stringify_keys(value) : value
-          result[new_key] = new_value
+      # 将哈希的键名转换为小驼峰格式
+      def deep_camelize_keys(object)
+        case object
+        when Hash
+          object.each_with_object({}) do |(key, value), result|
+            new_key = camelize_key(key.to_s)
+            result[new_key] = deep_camelize_keys(value)
+          end
+        when Array
+          object.map { |item| deep_camelize_keys(item) }
+        else
+          object
         end
       end
 
-      # 将哈希的键名转换为小驼峰格式
-      def deep_camelize_keys(hash)
-        return hash unless hash.is_a?(Hash)
+      # Kept for backwards compatibility: it has always camelized keys rather
+      # than only stringifying them.
+      alias deep_stringify_keys deep_camelize_keys
+
+      # Prepare an event body for the ingestion API:
+      # - top-level keys are camelized (snake_case -> camelCase)
+      # - user data values (input/output/metadata/usageDetails/costDetails/modelParameters)
+      #   are passed through verbatim so user-provided keys are not mangled
+      # - the legacy `usage` object keys are camelized (prompt_tokens -> promptTokens)
+      def prepare_event_body(body)
+        return body unless body.is_a?(Hash)
 
-        hash.each_with_object({}) do |(key, value), result|
+        body.each_with_object({}) do |(key, value), result|
           new_key = camelize_key(key.to_s)
-          new_value = value.is_a?(Hash) ? deep_camelize_keys(value) : value
-          result[new_key] = new_value
+          result[new_key] = if !VERBATIM_BODY_KEYS.include?(new_key) && value.is_a?(Hash)
+                              deep_camelize_keys(value)
+                            else
+                              value
+                            end
         end
       end
 

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = '0.1.7'
+  VERSION = '0.2.1'
 end

data/lib/langfuse.rb

@@ -2,12 +2,16 @@
 
 require_relative 'langfuse/version'
 require_relative 'langfuse/observation_types'
+require_relative 'langfuse/span_wrappers'
+require_relative 'langfuse/partial_updates'
+require_relative 'langfuse/template_compiler'
 require_relative 'langfuse/client'
 require_relative 'langfuse/trace'
 require_relative 'langfuse/span'
 require_relative 'langfuse/generation'
 require_relative 'langfuse/event'
 require_relative 'langfuse/prompt'
+require_relative 'langfuse/prompt_cache'
 require_relative 'langfuse/evaluation'
 require_relative 'langfuse/errors'
 require_relative 'langfuse/utils'
@@ -16,6 +20,8 @@ require_relative 'langfuse/otel_exporter'
 
 # Ruby SDK for Langfuse - Open source LLM engineering platform
 module Langfuse
+  CLIENT_MUTEX = Mutex.new
+
   class << self
     # Configure the Langfuse client with default settings
     def configure
@@ -31,10 +37,10 @@ module Langfuse
       Client.new(**kwargs)
     end
 
-    # Get a thread-safe singleton client instance
+    # Get a process-wide, thread-safe singleton client instance
     # @return [Client] Langfuse client
     def client
-      Thread.current[:langfuse_client] ||= Client.new
+      @client || CLIENT_MUTEX.synchronize { @client ||= Client.new }
     end
 
     # Get a prompt and optionally compile it with variables
@@ -45,29 +51,23 @@ module Langfuse
     # @param cache_ttl_seconds [Integer] cache TTL in seconds (default: 60)
     # @param retries [Integer] number of retries on failure (default: 2)
     # @return [String, Prompt, nil] compiled prompt string if variables provided, Prompt object otherwise, nil on failure
+    # `retries` is applied inside the HTTP layer, which retries only transient
+    # failures (timeout, network, 429, 5xx), honors Retry-After and backs off with
+    # jitter. A missing prompt therefore fails immediately instead of being
+    # requested three times.
     def get_prompt(prompt_name, variables: nil, label: nil, version: nil, cache_ttl_seconds: 60, retries: 2)
-      attempts = 0
-
-      begin
-        attempts += 1
-        prompt = client.get_prompt(prompt_name, label: label, version: version, cache_ttl_seconds: cache_ttl_seconds)
-
-        if variables
-          prompt.compile(variables)
-        else
-          prompt
-        end
-      rescue StandardError => e
-        if attempts <= retries
-          sleep_time = 2**(attempts - 1) * 0.1 # Exponential backoff: 0.1s, 0.2s, 0.4s...
-          warn "Langfuse prompt fetch failed (#{prompt_name}), retrying in #{sleep_time}s... (attempt #{attempts}/#{retries + 1})" if configuration.debug
-          sleep(sleep_time)
-          retry
-        end
+      prompt = client.get_prompt(
+        prompt_name,
+        label: label,
+        version: version,
+        cache_ttl_seconds: cache_ttl_seconds,
+        retries: retries
+      )
 
-        warn "Langfuse prompt fetch failed (#{prompt_name}): #{e.message}" if configuration.debug
-        nil
-      end
+      variables ? prompt.compile(variables) : prompt
+    rescue StandardError => e
+      warn "Langfuse prompt fetch failed (#{prompt_name}): #{e.message}" if configuration.debug
+      nil
     end
 
     # Create a trace and optionally execute a block with it
@@ -100,39 +100,35 @@ module Langfuse
     #   Langfuse.flush
     #
     def trace(name = nil, user_id: nil, session_id: nil, input: nil, output: nil,
-              metadata: nil, tags: nil, version: nil, release: nil, **kwargs, &block)
-      trace = client.trace(
-        name: name,
-        user_id: user_id,
-        session_id: session_id,
-        input: input,
-        output: output,
-        metadata: metadata,
-        tags: tags,
-        version: version,
-        release: release,
-        **kwargs
-      )
-
-      if block_given?
+              metadata: nil, tags: nil, version: nil, release: nil, **kwargs)
+      # Only trace creation degrades to a NullTrace. An exception raised by the
+      # block must propagate: rescuing it here and yielding again would run the
+      # caller's block a second time (duplicate LLM calls and billing).
+      trace =
         begin
-          result = yield(trace)
-          result
-        ensure
-          flush
+          client.trace(
+            name: name,
+            user_id: user_id,
+            session_id: session_id,
+            input: input,
+            output: output,
+            metadata: metadata,
+            tags: tags,
+            version: version,
+            release: release,
+            **kwargs
+          )
+        rescue StandardError => e
+          warn "Langfuse trace creation failed: #{e.message}" if configuration.debug
+          NullTrace.new
         end
-      else
-        trace
-      end
-    rescue StandardError => e
-      warn "Langfuse trace creation failed: #{e.message}" if configuration.debug
-
-      # If block given, execute with NullTrace to ensure code continues
-      if block_given?
-        null_trace = NullTrace.new
-        yield(null_trace)
-      else
-        NullTrace.new
+
+      return trace unless block_given?
+
+      begin
+        yield(trace)
+      ensure
+        flush
       end
     end
 
@@ -152,14 +148,15 @@ module Langfuse
 
     # Reset the singleton client (mainly for testing)
     def reset!
-      Thread.current[:langfuse_client] = nil
+      CLIENT_MUTEX.synchronize { @client = nil }
     end
   end
 
   # Configuration class for Langfuse client settings
   class Configuration
     attr_accessor :public_key, :secret_key, :host, :debug, :timeout, :retries, :flush_interval, :auto_flush,
-                  :ingestion_mode
+                  :ingestion_mode, :environment, :sample_rate, :mask, :flush_at, :max_queue_size, :logger,
+                  :shutdown_on_exit, :http_adapter
 
     def initialize
       @public_key = nil
@@ -171,6 +168,14 @@ module Langfuse
       @flush_interval = 5
       @auto_flush = true
       @ingestion_mode = :legacy # :legacy or :otel
+      @environment = nil       # default tracing environment for all events
+      @sample_rate = nil       # 0.0..1.0, nil disables sampling
+      @mask = nil              # callable applied to input/output/metadata before sending
+      @flush_at = 15           # flush as soon as this many events are queued
+      @max_queue_size = 10_000 # queue cap; the oldest events are dropped when full
+      @logger = nil            # custom Logger instance
+      @shutdown_on_exit = true # register an at_exit hook that flushes pending events
+      @http_adapter = nil      # Faraday adapter, e.g. :net_http_persistent for keep-alive
     end
   end
 end

data/scripts/release.sh

@@ -49,31 +49,31 @@ if ! bundle exec rspec; then
 fi
 
 print_status "Running offline tests..."
-if ! ruby scripts/test_offline.rb; then
+if ! bundle exec ruby scripts/test_offline.rb; then
     print_error "Offline tests failed. Please fix them before releasing."
     exit 1
 fi
 
 # Build gem
 print_status "Building gem..."
-if ! gem build langfuse.gemspec; then
+if ! gem build langfuse-ruby.gemspec; then
     print_error "Gem build failed."
     exit 1
 fi
 
 # Check if gem was built successfully
-if [ ! -f "langfuse-${CURRENT_VERSION}.gem" ]; then
-    print_error "Gem file not found: langfuse-${CURRENT_VERSION}.gem"
+if [ ! -f "langfuse-ruby-${CURRENT_VERSION}.gem" ]; then
+    print_error "Gem file not found: langfuse-ruby-${CURRENT_VERSION}.gem"
     exit 1
 fi
 
-print_status "Gem built successfully: langfuse-${CURRENT_VERSION}.gem"
+print_status "Gem built successfully: langfuse-ruby-${CURRENT_VERSION}.gem"
 
 # Ask for confirmation
 echo
 echo "📋 Release Summary:"
 echo "  Version: $CURRENT_VERSION"
-echo "  Gem file: langfuse-${CURRENT_VERSION}.gem"
+echo "  Gem file: langfuse-ruby-${CURRENT_VERSION}.gem"
 echo "  Tests: ✅ Passed"
 echo
 
@@ -81,7 +81,7 @@ read -p "Do you want to proceed with the release? (y/N): " -n 1 -r
 echo
 if [[ ! $REPLY =~ ^[Yy]$ ]]; then
     print_warning "Release cancelled."
-    rm -f "langfuse-${CURRENT_VERSION}.gem"
+    rm -f "langfuse-ruby-${CURRENT_VERSION}.gem"
     exit 0
 fi
 
@@ -91,12 +91,12 @@ git tag "v${CURRENT_VERSION}"
 
 # Push to git
 print_status "Pushing to git..."
-git push origin main
+git push origin master
 git push origin "v${CURRENT_VERSION}"
 
 # Publish to RubyGems
 print_status "Publishing to RubyGems..."
-if gem push "langfuse-${CURRENT_VERSION}.gem"; then
+if gem push "langfuse-ruby-${CURRENT_VERSION}.gem"; then
     print_status "Successfully published to RubyGems!"
 else
     print_error "Failed to publish to RubyGems."
@@ -105,16 +105,16 @@ else
 fi
 
 # Clean up
-rm -f "langfuse-${CURRENT_VERSION}.gem"
+rm -f "langfuse-ruby-${CURRENT_VERSION}.gem"
 
 print_status "Release completed successfully! 🎉"
 echo
 echo "📝 Next steps:"
-echo "  1. Check https://rubygems.org/gems/langfuse"
+echo "  1. Check https://rubygems.org/gems/langfuse-ruby"
 echo "  2. Update documentation if needed"
 echo "  3. Announce the release"
 echo
 echo "🔗 Useful links:"
-echo "  - RubyGems: https://rubygems.org/gems/langfuse"
+echo "  - RubyGems: https://rubygems.org/gems/langfuse-ruby"
 echo "  - GitHub: https://github.com/ai-firstly/langfuse-ruby"
 echo "  - Documentation: https://github.com/ai-firstly/langfuse-ruby#readme"