langfuse-ruby 0.1.1 → 0.1.3

data/examples/prompt_management.rb

@@ -9,7 +9,7 @@ client = Langfuse.new(
   host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
 )
 
-puts "🚀 Starting prompt management example..."
+puts '🚀 Starting prompt management example...'
 
 # Example 1: Create and use text prompts
 puts "\n📝 Example 1: Create and use text prompts"
@@ -17,9 +17,9 @@ puts "\n📝 Example 1: Create and use text prompts"
 begin
   # Create a text prompt
   text_prompt = client.create_prompt(
-    name: "greeting-prompt",
-    prompt: "Hello {{user_name}}! Welcome to {{service_name}}. How can I help you with {{topic}} today?",
-    labels: ["greeting", "customer-service"],
+    name: 'greeting-prompt',
+    prompt: 'Hello {{user_name}}! Welcome to {{service_name}}. How can I help you with {{topic}} today?',
+    labels: %w[greeting customer-service],
     config: {
       temperature: 0.7,
       max_tokens: 100
@@ -27,24 +27,22 @@ begin
   )
 
   puts "Created text prompt: #{text_prompt.name} (Version: #{text_prompt.version})"
-
 rescue Langfuse::APIError => e
   puts "Note: Prompt might already exist - #{e.message}"
 end
 
 # Get and use the prompt
 begin
-  prompt = client.get_prompt("greeting-prompt")
+  prompt = client.get_prompt('greeting-prompt')
 
   # Compile prompt with variables
   compiled_text = prompt.compile(
-    user_name: "Alice",
-    service_name: "AI Assistant",
-    topic: "machine learning"
+    user_name: 'Alice',
+    service_name: 'AI Assistant',
+    topic: 'machine learning'
   )
 
   puts "Compiled prompt: #{compiled_text}"
-
 rescue Langfuse::APIError => e
   puts "Could not retrieve prompt: #{e.message}"
 end
@@ -55,18 +53,18 @@ puts "\n💬 Example 2: Create and use chat prompts"
 begin
   # Create a chat prompt
   chat_prompt = client.create_prompt(
-    name: "ai-assistant-chat",
+    name: 'ai-assistant-chat',
     prompt: [
       {
-        role: "system",
-        content: "You are a helpful AI assistant specialized in {{domain}}. Always be {{tone}} and provide {{detail_level}} answers."
+        role: 'system',
+        content: 'You are a helpful AI assistant specialized in {{domain}}. Always be {{tone}} and provide {{detail_level}} answers.'
       },
       {
-        role: "user",
-        content: "{{user_message}}"
+        role: 'user',
+        content: '{{user_message}}'
       }
     ],
-    labels: ["chat", "assistant", "ai"],
+    labels: %w[chat assistant ai],
     config: {
       temperature: 0.8,
       max_tokens: 200
@@ -74,28 +72,26 @@ begin
   )
 
   puts "Created chat prompt: #{chat_prompt.name}"
-
 rescue Langfuse::APIError => e
   puts "Note: Chat prompt might already exist - #{e.message}"
 end
 
 # Get and use the chat prompt
 begin
-  chat_prompt = client.get_prompt("ai-assistant-chat")
+  chat_prompt = client.get_prompt('ai-assistant-chat')
 
   # Compile chat prompt with variables
   compiled_messages = chat_prompt.compile(
-    domain: "software development",
-    tone: "friendly and professional",
-    detail_level: "detailed",
-    user_message: "How do I implement a REST API in Ruby?"
+    domain: 'software development',
+    tone: 'friendly and professional',
+    detail_level: 'detailed',
+    user_message: 'How do I implement a REST API in Ruby?'
   )
 
-  puts "Compiled chat messages:"
+  puts 'Compiled chat messages:'
   compiled_messages.each_with_index do |message, index|
     puts "  #{index + 1}. #{message[:role]}: #{message[:content]}"
   end
-
 rescue Langfuse::APIError => e
   puts "Could not retrieve chat prompt: #{e.message}"
 end
@@ -112,34 +108,34 @@ puts "Template variables: #{translation_template.input_variables}"
 
 # Use the template
 translated_prompt = translation_template.format(
-  source_language: "English",
-  target_language: "Spanish",
-  text: "Hello, how are you today?"
+  source_language: 'English',
+  target_language: 'Spanish',
+  text: 'Hello, how are you today?'
 )
 
 puts "Translation prompt: #{translated_prompt}"
 
 # Create a reusable chat template
 coding_template = Langfuse::ChatPromptTemplate.from_messages([
-  {
-    role: "system",
-    content: "You are an expert {{language}} developer. Provide clean, well-commented code examples."
-  },
-  {
-    role: "user",
-    content: "{{request}}"
-  }
-])
+                                                               {
+                                                                 role: 'system',
+                                                                 content: 'You are an expert {{language}} developer. Provide clean, well-commented code examples.'
+                                                               },
+                                                               {
+                                                                 role: 'user',
+                                                                 content: '{{request}}'
+                                                               }
+                                                             ])
 
 puts "Chat template variables: #{coding_template.input_variables}"
 
 # Use the chat template
 coding_messages = coding_template.format(
-  language: "Ruby",
-  request: "Show me how to create a simple HTTP server"
+  language: 'Ruby',
+  request: 'Show me how to create a simple HTTP server'
 )
 
-puts "Coding chat messages:"
+puts 'Coding chat messages:'
 coding_messages.each_with_index do |message, index|
   puts "  #{index + 1}. #{message[:role]}: #{message[:content]}"
 end
@@ -149,17 +145,16 @@ puts "\n🔄 Example 4: Prompt versioning and caching"
 
 # Get specific version of a prompt
 begin
-  versioned_prompt = client.get_prompt("greeting-prompt", version: 1)
+  versioned_prompt = client.get_prompt('greeting-prompt', version: 1)
   puts "Retrieved prompt version: #{versioned_prompt.version}"
 
   # Get latest version (cached)
-  latest_prompt = client.get_prompt("greeting-prompt")
+  latest_prompt = client.get_prompt('greeting-prompt')
   puts "Latest prompt version: #{latest_prompt.version}"
 
   # Get with label
-  labeled_prompt = client.get_prompt("greeting-prompt", label: "production")
+  labeled_prompt = client.get_prompt('greeting-prompt', label: 'production')
   puts "Labeled prompt: #{labeled_prompt.labels}"
-
 rescue Langfuse::APIError => e
   puts "Could not retrieve versioned prompt: #{e.message}"
 end
@@ -169,27 +164,27 @@ puts "\n🔗 Example 5: Using prompts in tracing"
 
 begin
   # Get a prompt for use in generation
-  system_prompt = client.get_prompt("ai-assistant-chat")
+  system_prompt = client.get_prompt('ai-assistant-chat')
 
   # Create a trace
   trace = client.trace(
-    name: "prompt-based-chat",
-    user_id: "user-789",
-    input: { message: "Explain Ruby blocks" }
+    name: 'prompt-based-chat',
+    user_id: 'user-789',
+    input: { message: 'Explain Ruby blocks' }
   )
 
   # Compile the prompt
   messages = system_prompt.compile(
-    domain: "Ruby programming",
-    tone: "educational and clear",
-    detail_level: "beginner-friendly",
-    user_message: "Explain Ruby blocks"
+    domain: 'Ruby programming',
+    tone: 'educational and clear',
+    detail_level: 'beginner-friendly',
+    user_message: 'Explain Ruby blocks'
   )
 
   # Create generation with prompt
   generation = trace.generation(
-    name: "openai-chat-with-prompt",
-    model: "gpt-3.5-turbo",
+    name: 'openai-chat-with-prompt',
+    model: 'gpt-3.5-turbo',
     input: messages,
     output: {
       content: "Ruby blocks are pieces of code that can be passed to methods. They're defined using either do...end or curly braces {}. Blocks are commonly used with iterators like .each, .map, and .select."
@@ -207,7 +202,6 @@ begin
 
   puts "Created generation with prompt: #{generation.id}"
   puts "Trace URL: #{trace.get_url}"
-
 rescue Langfuse::APIError => e
   puts "Could not use prompt in tracing: #{e.message}"
 end
@@ -218,12 +212,12 @@ puts "\n🎯 Example 6: Advanced prompt features"
 # Create a prompt with complex templating
 begin
   complex_prompt = client.create_prompt(
-    name: "code-review-prompt",
+    name: 'code-review-prompt',
     prompt: {
-      system: "You are a senior {{language}} developer reviewing code. Focus on {{review_aspects}}.",
+      system: 'You are a senior {{language}} developer reviewing code. Focus on {{review_aspects}}.',
       user: "Please review this {{language}} code:\n\n```{{language}}\n{{code}}\n```\n\nProvide feedback on: {{specific_feedback}}"
     },
-    labels: ["code-review", "development"],
+    labels: %w[code-review development],
     config: {
       temperature: 0.3,
       max_tokens: 500
@@ -231,7 +225,6 @@ begin
   )
 
   puts "Created complex prompt: #{complex_prompt.name}"
-
 rescue Langfuse::APIError => e
   puts "Note: Complex prompt might already exist - #{e.message}"
 end
@@ -239,16 +232,14 @@ end
 # Create a prompt with conditional logic (using Ruby)
 class ConditionalPrompt
   def self.generate(user_level:, topic:, include_examples: true)
-    base_prompt = "Explain {{topic}} for a {{user_level}} audience."
+    base_prompt = 'Explain {{topic}} for a {{user_level}} audience.'
 
-    if include_examples
-      base_prompt += " Include practical examples."
-    end
+    base_prompt += ' Include practical examples.' if include_examples
 
-    if user_level == "beginner"
-      base_prompt += " Use simple language and avoid jargon."
-    elsif user_level == "advanced"
-      base_prompt += " Feel free to use technical terminology."
+    if user_level == 'beginner'
+      base_prompt += ' Use simple language and avoid jargon.'
+    elsif user_level == 'advanced'
+      base_prompt += ' Feel free to use technical terminology.'
     end
 
     base_prompt
@@ -256,8 +247,8 @@ class ConditionalPrompt
 end
 
 conditional_prompt_text = ConditionalPrompt.generate(
-  user_level: "beginner",
-  topic: "machine learning",
+  user_level: 'beginner',
+  topic: 'machine learning',
   include_examples: true
 )
 
@@ -266,8 +257,8 @@ puts "Conditional prompt: #{conditional_prompt_text}"
 # Use with template
 conditional_template = Langfuse::PromptTemplate.from_template(conditional_prompt_text)
 formatted_prompt = conditional_template.format(
-  topic: "neural networks",
-  user_level: "beginner"
+  topic: 'neural networks',
+  user_level: 'beginner'
 )
 
 puts "Formatted conditional prompt: #{formatted_prompt}"
@@ -277,7 +268,7 @@ puts "\n🔄 Flushing events..."
 client.flush
 
 puts "\n✅ Prompt management example completed!"
-puts "Check your Langfuse dashboard to see the prompts and traces."
+puts 'Check your Langfuse dashboard to see the prompts and traces.'
 
 # Shutdown client
 client.shutdown

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}"
@@ -99,7 +125,7 @@ module Langfuse
         return cached_prompt[:prompt]
       end
 
-      path = "/api/public/prompts/#{name}"
+      path = "/api/public/v2/prompts/#{name}"
       params = {}
       params[:version] = version if version
       params[:label] = label if label
@@ -138,7 +164,7 @@ module Langfuse
         **kwargs
       }
 
-      response = post('/api/public/prompts', data)
+      response = post('/api/public/v2/prompts', data)
       Prompt.new(response.body)
     end
 
@@ -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
+        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,
@@ -198,47 +217,144 @@ 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|
-        conn.request :authorization, :basic, @public_key, @secret_key
+        # 配置请求和响应处理
         conn.request :json
-        # 更宽松的 JSON 响应处理，支持更多 content-type
         conn.response :json, content_type: /\bjson$/
-        conn.adapter Faraday.default_adapter
+
+        # 设置 User-Agent 头部
+        conn.headers['User-Agent'] = "langfuse-ruby/#{Langfuse::VERSION}"
+        # 根据 Langfuse 文档配置 Basic Auth
+        # username: Langfuse Public Key, password: Langfuse Secret Key
+        conn.headers['Authorization'] = "Basic #{Base64.strict_encode64("#{@public_key}:#{@secret_key}")}"
+
+        # 设置超时
         conn.options.timeout = @timeout
 
-        # 添加响应中间件来处理错误响应
+        # 添加调试日志
         conn.response :logger if @debug
+
+        # 使用默认适配器
+        conn.adapter Faraday.default_adapter
       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
 
@@ -284,25 +400,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