langfuse-ruby 0.1.2 → 0.1.4

data/lib/langfuse/client.rb

@@ -6,22 +6,29 @@ require 'concurrent'
 
 module Langfuse
   class Client
-    attr_reader :public_key, :secret_key, :host, :debug, :timeout, :retries
+    attr_reader :public_key, :secret_key, :host, :debug, :timeout, :retries, :flush_interval, :auto_flush
 
-    def initialize(public_key: nil, secret_key: nil, host: nil, debug: false, timeout: 30, retries: 3)
+    def initialize(public_key: nil, secret_key: nil, host: nil, debug: false, timeout: 30, retries: 3,
+                   flush_interval: nil, auto_flush: nil)
       @public_key = public_key || ENV['LANGFUSE_PUBLIC_KEY'] || Langfuse.configuration.public_key
       @secret_key = secret_key || ENV['LANGFUSE_SECRET_KEY'] || Langfuse.configuration.secret_key
       @host = host || ENV['LANGFUSE_HOST'] || Langfuse.configuration.host
       @debug = debug || Langfuse.configuration.debug
       @timeout = timeout || Langfuse.configuration.timeout
       @retries = retries || Langfuse.configuration.retries
+      @flush_interval = flush_interval || ENV['LANGFUSE_FLUSH_INTERVAL']&.to_i || Langfuse.configuration.flush_interval
+      @auto_flush = if auto_flush.nil?
+                      ENV['LANGFUSE_AUTO_FLUSH'] == 'false' ? false : Langfuse.configuration.auto_flush
+                    else
+                      auto_flush
+                    end
 
       raise AuthenticationError, 'Public key is required' unless @public_key
       raise AuthenticationError, 'Secret key is required' unless @secret_key
 
       @connection = build_connection
       @event_queue = Concurrent::Array.new
-      @flush_thread = start_flush_thread
+      @flush_thread = start_flush_thread if @auto_flush
     end
 
     # Trace operations
@@ -91,6 +98,25 @@ module Langfuse
       )
     end
 
+    # Event operations
+    def event(trace_id:, name:, start_time: nil, input: nil, output: nil, metadata: nil,
+              level: nil, status_message: nil, parent_observation_id: nil, version: nil, **kwargs)
+      Event.new(
+        client: self,
+        trace_id: trace_id,
+        name: name,
+        start_time: start_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: parent_observation_id,
+        version: version,
+        **kwargs
+      )
+    end
+
     # Prompt operations
     def get_prompt(name, version: nil, label: nil, cache_ttl_seconds: 60)
       cache_key = "prompt:#{name}:#{version}:#{label}"
@@ -158,29 +184,22 @@ module Langfuse
       enqueue_event('score-create', data)
     end
 
-    # HTTP methods
-    def get(path, params = {})
-      request(:get, path, params: params)
-    end
-
-    def post(path, data = {})
-      request(:post, path, json: data)
-    end
-
-    def put(path, data = {})
-      request(:put, path, json: data)
-    end
-
-    def delete(path, params = {})
-      request(:delete, path, params: params)
-    end
-
-    def patch(path, data = {})
-      request(:patch, path, json: data)
-    end
-
     # Event queue management
     def enqueue_event(type, body)
+      # 验证事件类型是否有效
+      valid_types = %w[
+        trace-create trace-update
+        generation-create generation-update
+        span-create span-update
+        event-create
+        score-create
+      ]
+
+      unless valid_types.include?(type)
+        puts "Warning: Invalid event type '#{type}'. Skipping event." if @debug
+        return
+      end
+
       event = {
         id: Utils.generate_id,
         type: type,
@@ -188,7 +207,32 @@ module Langfuse
         body: Utils.deep_stringify_keys(body)
       }
 
-      @event_queue << event
+      if type == 'trace-update'
+        # 查找对应的 trace-create 事件并更新
+        trace_id = body['id'] || body[:id]
+        if trace_id
+          existing_event_index = @event_queue.find_index do |existing_event|
+            existing_event[:type] == 'trace-create' &&
+              (existing_event[:body]['id'] == trace_id || existing_event[:body][:id] == trace_id)
+          end
+
+          if existing_event_index
+            # 更新现有的 trace-create 事件
+            @event_queue[existing_event_index][:body].merge!(event[:body])
+            @event_queue[existing_event_index][:timestamp] = event[:timestamp]
+            puts "Updated existing trace-create event for trace_id: #{trace_id}" if @debug
+          else
+            # 如果没找到对应的 trace-create 事件，将 trace-update 转换为 trace-create
+            event[:type] = 'trace-create'
+            @event_queue << event
+            puts "Converted trace-update to trace-create for trace_id: #{trace_id}" if @debug
+          end
+        elsif @debug
+          puts 'Warning: trace-update event missing trace_id, skipping'
+        end
+      else
+        @event_queue << event
+      end
       puts "Enqueued event: #{type}" if @debug
     end
 
@@ -198,32 +242,99 @@ module Langfuse
       events = @event_queue.shift(@event_queue.length)
       return if events.empty?
 
-      batch_data = {
-        batch: events,
-        metadata: {
-          batch_size: events.length,
-          sdk_name: 'langfuse-ruby',
-          sdk_version: Langfuse::VERSION
-        }
-      }
+      send_batch(events)
+    end
+
+    def shutdown
+      @flush_thread&.kill if @auto_flush
+      flush unless @event_queue.empty?
+    end
+
+    private
+
+    def debug_event_data(events)
+      return unless @debug
+
+      puts "\n=== Event Data Debug Information ==="
+      events.each_with_index do |event, index|
+        puts "Event #{index + 1}:"
+        puts "  ID: #{event[:id]}"
+        puts "  Type: #{event[:type]}"
+        puts "  Timestamp: #{event[:timestamp]}"
+        puts "  Body keys: #{event[:body]&.keys || 'nil'}"
+
+        # 检查常见的问题
+        puts '  ⚠️  WARNING: Empty or nil type!' if event[:type].nil? || event[:type].to_s.empty?
+
+        puts '  ⚠️  WARNING: Empty body!' if event[:body].nil?
+
+        puts '  ---'
+      end
+      puts "=== End Debug Information ===\n"
+    end
+
+    def send_batch(events)
+      # 调试事件数据
+      debug_event_data(events)
+
+      # 验证事件数据
+      valid_events = events.select do |event|
+        if event[:type].nil? || event[:type].to_s.empty?
+          puts "Warning: Event with empty type detected, skipping: #{event[:id]}" if @debug
+          false
+        elsif event[:body].nil?
+          puts "Warning: Event with empty body detected, skipping: #{event[:id]}" if @debug
+          false
+        else
+          true
+        end
+      end
+
+      if valid_events.empty?
+        puts 'No valid events to send' if @debug
+        return
+      end
+
+      batch_data = build_batch_data(valid_events)
+      puts "Sending batch data: #{batch_data}" if @debug
 
       begin
         response = post('/api/public/ingestion', batch_data)
-        puts "Flushed #{events.length} events" if @debug
+        puts "Flushed #{valid_events.length} events" if @debug
+        response
       rescue StandardError => e
         puts "Failed to flush events: #{e.message}" if @debug
         # Re-queue events on failure
-        events.each { |event| @event_queue << event }
+        valid_events.each { |event| @event_queue << event }
         raise
       end
     end
 
-    def shutdown
-      @flush_thread&.kill
-      flush unless @event_queue.empty?
+    def build_batch_data(events)
+      {
+        batch: events,
+        metadata: Utils.deep_camelize_keys({
+                                             batch_size: events.length,
+                                             sdk_name: 'langfuse-ruby',
+                                             sdk_version: Langfuse::VERSION
+                                           })
+      }
     end
 
-    private
+    def start_flush_thread
+      return unless @auto_flush
+
+      Thread.new do
+        loop do
+          sleep(@flush_interval) # Configurable flush interval
+          begin
+            flush unless @event_queue.empty?
+          rescue StandardError => e
+            puts "Error in flush thread: #{e.message}" if @debug
+          end
+        end
+      end
+    end
 
     def build_connection
       Faraday.new(url: @host) do |conn|
@@ -248,6 +359,27 @@ module Langfuse
       end
     end
 
+    # HTTP methods
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, data = {})
+      request(:post, path, json: data)
+    end
+
+    def put(path, data = {})
+      request(:put, path, json: data)
+    end
+
+    def delete(path, params = {})
+      request(:delete, path, params: params)
+    end
+
+    def patch(path, data = {})
+      request(:patch, path, json: data)
+    end
+
     def request(method, path, params: {}, json: nil)
       retries_left = @retries
 
@@ -293,25 +425,27 @@ module Langfuse
       when 429
         raise RateLimitError, "Rate limit exceeded: #{response.body}"
       when 400..499
-        raise ValidationError, "Client error (#{response.status}): #{response.body}"
+        # 为 400 错误提供更详细的错误信息
+        error_details = ''
+        if response.body.is_a?(Hash) && response.body['error']
+          error_details = "\nError details: #{response.body['error']}"
+        elsif response.body.is_a?(String)
+          error_details = "\nError details: #{response.body}"
+        end
+
+        # 特别处理类型验证错误
+        unless response.body.to_s.include?('invalid_union') || response.body.to_s.include?('discriminator')
+          raise ValidationError, "Client error (#{response.status}): #{response.body}#{error_details}"
+        end
+
+        raise ValidationError,
+              "Event type validation failed (#{response.status}): The event type or structure is invalid. Please check the event format.#{error_details}"
+
       when 500..599
         raise APIError, "Server error (#{response.status}): #{response.body}"
       else
         raise APIError, "Unexpected response (#{response.status}): #{response.body}"
       end
     end
-
-    def start_flush_thread
-      Thread.new do
-        loop do
-          sleep(5) # Flush every 5 seconds
-          begin
-            flush unless @event_queue.empty?
-          rescue StandardError => e
-            puts "Error in flush thread: #{e.message}" if @debug
-          end
-        end
-      end
-    end
   end
 end

data/lib/langfuse/event.rb

@@ -0,0 +1,63 @@
+module Langfuse
+  class Event
+    attr_reader :id, :trace_id, :name, :start_time, :input, :output, :metadata,
+                :level, :status_message, :parent_observation_id, :version, :client
+
+    def initialize(client:, trace_id:, name:, id: nil, start_time: nil, input: nil,
+                   output: nil, metadata: nil, level: nil, status_message: nil,
+                   parent_observation_id: nil, version: nil, **kwargs)
+      @client = client
+      @id = id || Utils.generate_id
+      @trace_id = trace_id
+      @name = name
+      @start_time = start_time || Utils.current_timestamp
+      @input = input
+      @output = output
+      @metadata = metadata || {}
+      @level = level
+      @status_message = status_message
+      @parent_observation_id = parent_observation_id
+      @version = version
+      @kwargs = kwargs
+
+      # Create the event
+      create_event
+    end
+
+    def to_dict
+      {
+        id: @id,
+        trace_id: @trace_id,
+        name: @name,
+        start_time: @start_time,
+        input: @input,
+        output: @output,
+        metadata: @metadata,
+        level: @level,
+        status_message: @status_message,
+        parent_observation_id: @parent_observation_id,
+        version: @version
+      }.merge(@kwargs).compact
+    end
+
+    private
+
+    def create_event
+      data = {
+        id: @id,
+        trace_id: @trace_id,
+        name: @name,
+        start_time: @start_time,
+        input: @input,
+        output: @output,
+        metadata: @metadata,
+        level: @level,
+        status_message: @status_message,
+        parent_observation_id: @parent_observation_id,
+        version: @version
+      }.merge(@kwargs).compact
+
+      @client.enqueue_event('event-create', data)
+    end
+  end
+end

data/lib/langfuse/generation.rb

@@ -103,6 +103,23 @@ module Langfuse
       )
     end
 
+    def event(name:, start_time: nil, input: nil, output: nil, metadata: nil,
+              level: nil, status_message: nil, version: nil, **kwargs)
+      @client.event(
+        trace_id: @trace_id,
+        name: name,
+        start_time: start_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: @id,
+        version: version,
+        **kwargs
+      )
+    end
+
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
         observation_id: @id,
@@ -142,49 +159,11 @@ module Langfuse
     private
 
     def create_generation
-      data = {
-        id: @id,
-        trace_id: @trace_id,
-        name: @name,
-        start_time: @start_time,
-        end_time: @end_time,
-        completion_start_time: @completion_start_time,
-        model: @model,
-        model_parameters: @model_parameters,
-        input: @input,
-        output: @output,
-        usage: @usage,
-        metadata: @metadata,
-        level: @level,
-        status_message: @status_message,
-        parent_observation_id: @parent_observation_id,
-        version: @version
-      }.merge(@kwargs).compact
-
-      @client.enqueue_event('generation-create', data)
+      @client.enqueue_event('generation-create', to_dict)
     end
 
     def update_generation
-      data = {
-        id: @id,
-        trace_id: @trace_id,
-        name: @name,
-        start_time: @start_time,
-        end_time: @end_time,
-        completion_start_time: @completion_start_time,
-        model: @model,
-        model_parameters: @model_parameters,
-        input: @input,
-        output: @output,
-        usage: @usage,
-        metadata: @metadata,
-        level: @level,
-        status_message: @status_message,
-        parent_observation_id: @parent_observation_id,
-        version: @version
-      }.merge(@kwargs).compact
-
-      @client.enqueue_event('generation-update', data)
+      @client.enqueue_event('generation-update', to_dict)
     end
   end
 end

data/lib/langfuse/span.rb

@@ -91,6 +91,23 @@ module Langfuse
       )
     end
 
+    def event(name:, start_time: nil, input: nil, output: nil, metadata: nil,
+              level: nil, status_message: nil, version: nil, **kwargs)
+      @client.event(
+        trace_id: @trace_id,
+        name: name,
+        start_time: start_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: @id,
+        version: version,
+        **kwargs
+      )
+    end
+
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
         observation_id: @id,

data/lib/langfuse/trace.rb

@@ -24,23 +24,6 @@ module Langfuse
       create_trace
     end
 
-    def update(name: nil, user_id: nil, session_id: nil, version: nil, release: nil,
-               input: nil, output: nil, metadata: nil, tags: 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.merge!(metadata) if metadata
-      @tags.concat(tags) if tags
-      @kwargs.merge!(kwargs)
-
-      update_trace
-      self
-    end
-
     def span(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)
@@ -84,6 +67,23 @@ module Langfuse
       )
     end
 
+    def event(name:, start_time: nil, input: nil, output: nil, metadata: nil,
+              level: nil, status_message: nil, parent_observation_id: nil, version: nil, **kwargs)
+      @client.event(
+        trace_id: @id,
+        name: name,
+        start_time: start_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: parent_observation_id,
+        version: version,
+        **kwargs
+      )
+    end
+
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
         trace_id: @id,
@@ -95,6 +95,23 @@ 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)
+      # 更新实例变量
+      @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
+      @kwargs.merge!(kwargs) if kwargs.any?
+      # 触发 trace-update 事件
+      update_trace
+    end
+
     def get_url
       "#{@client.host}/trace/#{@id}"
     end
@@ -146,7 +163,8 @@ module Langfuse
         input: @input,
         output: @output,
         metadata: @metadata,
-        tags: @tags
+        tags: @tags,
+        timestamp: @timestamp
       }.merge(@kwargs).compact
 
       @client.enqueue_event('trace-update', data)

data/lib/langfuse/utils.rb

@@ -26,12 +26,34 @@ module Langfuse
         return hash unless hash.is_a?(Hash)
 
         hash.each_with_object({}) do |(key, value), result|
-          new_key = key.to_s
+          new_key = camelize_key(key.to_s)
           new_value = value.is_a?(Hash) ? deep_stringify_keys(value) : value
           result[new_key] = new_value
         end
       end
 
+      # 将哈希的键名转换为小驼峰格式
+      def deep_camelize_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_camelize_keys(value) : value
+          result[new_key] = new_value
+        end
+      end
+
+      private
+
+      # 将蛇形命名转换为小驼峰命名
+      def camelize_key(key)
+        return key if key.empty? || !key.include?('_')
+
+        key.split('_').map.with_index do |part, index|
+          index.zero? ? part.downcase : part.capitalize
+        end.join
+      end
+
       def validate_required_fields(data, required_fields)
         missing_fields = required_fields.select { |field| data[field].nil? || data[field].to_s.empty? }
         raise ValidationError, "Missing required fields: #{missing_fields.join(', ')}" unless missing_fields.empty?

data/lib/langfuse/version.rb

@@ -1,3 +1,3 @@
 module Langfuse
-  VERSION = '0.1.2'
+  VERSION = '0.1.4'
 end

data/lib/langfuse.rb

@@ -5,6 +5,7 @@ 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/evaluation'
 require_relative 'langfuse/errors'
@@ -30,7 +31,7 @@ module Langfuse
 
   # Configuration class for Langfuse client settings
   class Configuration
-    attr_accessor :public_key, :secret_key, :host, :debug, :timeout, :retries
+    attr_accessor :public_key, :secret_key, :host, :debug, :timeout, :retries, :flush_interval, :auto_flush
 
     def initialize
       @public_key = nil
@@ -39,6 +40,8 @@ module Langfuse
       @debug = false
       @timeout = 30
       @retries = 3
+      @flush_interval = 5
+      @auto_flush = true
     end
   end
 end