langfuse-ruby 0.1.5 → 0.1.7

data/docs/RELEASE_CHECKLIST.md

@@ -4,7 +4,7 @@
 
 ### 1. 代码质量检查
 - [ ] 所有测试通过 (`bundle exec rspec`)
-- [ ] 离线测试通过 (`ruby test_offline.rb`)
+- [ ] 离线测试通过 (`ruby scripts/test_offline.rb`)
 - [ ] 代码风格检查 (`bundle exec rubocop`)
 - [ ] 文档更新完成
 
@@ -26,34 +26,65 @@
 
 ## 🚀 发布步骤
 
-### 方法 1: 使用发布脚本 (推荐)
+### 方法 1: 使用 GitHub Actions (推荐)
+
+> ⚠️ **重要**: 必须先运行 `bundle install` 更新 `Gemfile.lock`，否则 CI 会失败！
+
+#### 前提条件
+在 GitHub 仓库的 **Settings → Secrets and variables → Actions** 中配置：
+- `RUBYGEMS_API_KEY` - RubyGems API 密钥（在 [rubygems.org](https://rubygems.org) → Settings → API keys 中获取）
+
+> 注意：`GITHUB_TOKEN` 无需手动配置，GitHub Actions 会自动提供。
+
+#### 发布流程
+```bash
+# 1. 更新版本号
+# 编辑 lib/langfuse/version.rb
+
+# 2. 更新 Gemfile.lock（重要！）
+bundle install
+
+# 3. 提交更改
+git add .
+git commit -m "Bump version to x.x.x"
+
+# 4. 推送代码
+git push origin <branch>
+
+# 5. 创建并推送标签（触发自动发布）
+git tag vx.x.x
+git push origin vx.x.x
+```
+
+GitHub Actions 会自动：
+- 运行测试 (rspec + offline tests)
+- 构建 gem
+- 发布到 RubyGems
+- 创建 GitHub Release
+
+### 方法 2: 使用发布脚本
 ```bash
 ./scripts/release.sh
 ```
 
-### 方法 2: 手动发布
+### 方法 3: 手动发布
 ```bash
 # 1. 运行测试
 bundle exec rspec
-ruby test_offline.rb
+ruby scripts/test_offline.rb
 
 # 2. 构建 gem
-gem build langfuse.gemspec
+gem build langfuse-ruby.gemspec
 
 # 3. 发布到 RubyGems
-gem push langfuse-0.1.0.gem
+gem push langfuse-ruby-x.x.x.gem
 
 # 4. 创建 Git 标签
-git tag v0.1.0
+git tag vx.x.x
 git push origin main
-git push origin v0.1.0
+git push origin vx.x.x
 ```
 
-### 方法 3: 使用 GitHub Actions
-1. 推送代码到 GitHub
-2. 创建版本标签 (`git tag v0.1.0 && git push origin v0.1.0`)
-3. GitHub Actions 自动发布
-
 ## 📊 发布后验证
 
 ### 1. 检查 RubyGems

data/examples/auto_flush_control.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require_relative '../lib/langfuse'
 
@@ -26,7 +27,7 @@ puts "   自动刷新: #{client_auto.auto_flush}"
 puts "   刷新间隔: #{client_auto.flush_interval}秒"
 
 # 创建一些事件
-trace_auto = client_auto.trace(
+client_auto.trace(
   name: 'auto-flush-demo',
   input: { message: '这是自动刷新演示' },
   metadata: { demo: true }
@@ -60,7 +61,7 @@ trace_manual = client_manual.trace(
   metadata: { demo: true }
 )
 
-generation_manual = trace_manual.generation(
+trace_manual.generation(
   name: 'manual-generation',
   model: 'gpt-3.5-turbo',
   input: [{ role: 'user', content: 'Hello!' }],

data/examples/basic_tracing.rb

@@ -1,11 +1,12 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'langfuse'
 
 # Initialize the Langfuse client
 client = Langfuse.new(
-  public_key: ENV['LANGFUSE_PUBLIC_KEY'],
-  secret_key: ENV['LANGFUSE_SECRET_KEY'],
+  public_key: ENV.fetch('LANGFUSE_PUBLIC_KEY', nil),
+  secret_key: ENV.fetch('LANGFUSE_SECRET_KEY', nil),
   host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
 )
 
@@ -65,7 +66,7 @@ retrieval_span = workflow_trace.span(
 )
 
 # Embedding generation within retrieval
-embedding_gen = retrieval_span.generation(
+retrieval_span.generation(
   name: 'embedding-generation',
   model: 'text-embedding-ada-002',
   input: 'What is machine learning?',
@@ -158,7 +159,7 @@ puts "\n🚨 Example 4: Error handling"
 begin
   error_trace = client.trace(name: 'error-example')
 
-  error_gen = error_trace.generation(
+  error_trace.generation(
     name: 'failed-generation',
     model: 'gpt-3.5-turbo',
     input: [{ role: 'user', content: 'This will fail' }],

data/examples/connection_config_demo.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require_relative '../lib/langfuse'
 

data/examples/event_usage.rb

@@ -1,11 +1,12 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'langfuse'
 
 # Initialize the Langfuse client
 client = Langfuse.new(
-  public_key: ENV['LANGFUSE_PUBLIC_KEY'],
-  secret_key: ENV['LANGFUSE_SECRET_KEY'],
+  public_key: ENV.fetch('LANGFUSE_PUBLIC_KEY', nil),
+  secret_key: ENV.fetch('LANGFUSE_SECRET_KEY', nil),
   host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
 )
 

data/examples/prompt_management.rb

@@ -1,11 +1,12 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'langfuse'
 
 # Initialize the Langfuse client
 client = Langfuse.new(
-  public_key: ENV['LANGFUSE_PUBLIC_KEY'],
-  secret_key: ENV['LANGFUSE_SECRET_KEY'],
+  public_key: ENV.fetch('LANGFUSE_PUBLIC_KEY', nil),
+  secret_key: ENV.fetch('LANGFUSE_SECRET_KEY', nil),
   host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
 )
 

data/examples/simplified_usage.rb

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'langfuse'
+
+# Configure Langfuse globally
+Langfuse.configure do |config|
+  config.public_key = ENV.fetch('LANGFUSE_PUBLIC_KEY', nil)
+  config.secret_key = ENV.fetch('LANGFUSE_SECRET_KEY', nil)
+  config.host = ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+end
+
+puts '🚀 Simplified usage example...'
+
+# Example 1: Block-based tracing with automatic flush
+puts "\n📝 Example 1: Block-based tracing (recommended)"
+
+result = Langfuse.trace('simplified-chat', user_id: 'user-123', input: { message: 'Hello!' }) do |trace|
+  # Create a generation for the LLM call
+  generation = trace.generation(
+    name: 'openai-chat',
+    model: 'gpt-4',
+    input: [{ role: 'user', content: 'Hello!' }],
+    model_parameters: { temperature: 0.7 }
+  )
+
+  # Simulate LLM response
+  response_content = "Hi there! How can I help you today?"
+  usage = { prompt_tokens: 10, completion_tokens: 15, total_tokens: 25 }
+
+  # End the generation with output and usage
+  generation.end(output: response_content, usage: usage)
+
+  # Update trace with final output
+  trace.update(output: response_content)
+
+  # Return value from block
+  response_content
+end
+# Flush happens automatically here!
+
+puts "Response: #{result}"
+
+# Example 2: Nested spans with block-based tracing
+puts "\n🔗 Example 2: Complex workflow with spans"
+
+Langfuse.trace('document-qa', user_id: 'user-456') do |trace|
+  # Retrieval span
+  retrieval = trace.span(name: 'document-retrieval', input: { query: 'What is Ruby?' })
+  
+  # Simulate embedding generation
+  retrieval.generation(
+    name: 'embedding',
+    model: 'text-embedding-ada-002',
+    input: 'What is Ruby?',
+    output: [0.1, 0.2, 0.3],
+    usage: { prompt_tokens: 5, total_tokens: 5 }
+  )
+  
+  retrieval.end(output: { documents: ['Ruby is a programming language...'] })
+
+  # Answer generation span
+  answer_span = trace.span(name: 'answer-generation')
+  
+  gen = answer_span.generation(
+    name: 'openai-completion',
+    model: 'gpt-4',
+    input: [{ role: 'user', content: 'What is Ruby?' }]
+  )
+  
+  gen.end(
+    output: 'Ruby is a dynamic, object-oriented programming language.',
+    usage: { prompt_tokens: 50, completion_tokens: 20, total_tokens: 70 }
+  )
+  
+  answer_span.end(output: { answer: 'Ruby is a dynamic programming language.' })
+  
+  # Score the trace
+  trace.score(name: 'relevance', value: 0.95, comment: 'Highly relevant answer')
+end
+
+# Example 3: Direct trace without block (manual flush required)
+puts "\n📌 Example 3: Direct trace usage"
+
+trace = Langfuse.trace('manual-trace', user_id: 'user-789')
+puts "Created trace: #{trace.id}"
+
+generation = trace.generation(
+  name: 'quick-generation',
+  model: 'gpt-3.5-turbo',
+  input: 'Quick test'
+)
+generation.end(output: 'Done!')
+
+# Manual flush required when not using block
+Langfuse.flush
+
+# Example 4: Get and compile prompts
+puts "\n📋 Example 4: Prompt management"
+
+# Get a prompt (would fail gracefully with nil if not configured)
+# prompt = Langfuse.get_prompt('my-prompt', variables: { name: 'World' })
+# puts "Compiled prompt: #{prompt}"
+
+# Graceful degradation example
+puts "Testing graceful degradation with invalid config..."
+Langfuse.reset!
+Langfuse.configure do |config|
+  config.public_key = nil
+  config.secret_key = nil
+end
+
+# This will use NullTrace when client creation fails
+# The block still executes, just without actual tracing
+begin
+  Langfuse.trace('will-fail') do |trace|
+    puts "Trace type: #{trace.class}"
+    gen = trace.generation(name: 'test', model: 'gpt-4', input: 'hello')
+    puts "Generation type: #{gen.class}"
+    gen.end(output: 'world')
+  end
+rescue => e
+  puts "Handled error: #{e.message}"
+end
+
+puts "\n✅ Simplified usage example completed!"

data/examples/url_encoding_demo.rb

@@ -51,7 +51,7 @@ rescue Langfuse::ValidationError => e
   puts "✗ Error: #{e.message}"
 end
 
-puts "\n" + '=' * 60
+puts "\n#{'=' * 60}"
 puts 'Note: The client now automatically URL-encodes prompt names.'
 puts 'You no longer need to manually encode them!'
 puts '=' * 60

data/langfuse-ruby.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |spec|
   spec.metadata['changelog_uri'] = 'https://github.com/ai-firstly/langfuse-ruby/blob/main/CHANGELOG.md'
   spec.metadata['documentation_uri'] = 'https://rubydoc.info/gems/langfuse-ruby'
   spec.metadata['bug_tracker_uri'] = 'https://github.com/ai-firstly/langfuse-ruby/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   # Specify which files should be added to the gem when it is released.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
@@ -44,8 +45,8 @@ Gem::Specification.new do |spec|
   # Dependencies
   spec.add_dependency 'concurrent-ruby', '~> 1.0'
   spec.add_dependency 'faraday', '>= 1.8', '< 3.0'
-  spec.add_dependency 'faraday-net_http', '>= 1.0', '< 4.0'
   spec.add_dependency 'faraday-multipart', '~> 1.0'
+  spec.add_dependency 'faraday-net_http', '>= 1.0', '< 4.0'
   spec.add_dependency 'json', '~> 2.0'
 
   # Development dependencies

data/lib/langfuse/client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'faraday'
 require 'faraday/net_http'
 require 'faraday/multipart'
@@ -7,10 +9,11 @@ require 'concurrent'
 
 module Langfuse
   class Client
-    attr_reader :public_key, :secret_key, :host, :debug, :timeout, :retries, :flush_interval, :auto_flush
+    attr_reader :public_key, :secret_key, :host, :debug, :timeout, :retries, :flush_interval, :auto_flush,
+                :ingestion_mode
 
     def initialize(public_key: nil, secret_key: nil, host: nil, debug: false, timeout: 30, retries: 3,
-                   flush_interval: nil, auto_flush: nil)
+                   flush_interval: nil, auto_flush: nil, ingestion_mode: 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
@@ -23,11 +26,14 @@ module Langfuse
                     else
                       auto_flush
                     end
+      @ingestion_mode = resolve_ingestion_mode(ingestion_mode)
 
       raise AuthenticationError, 'Public key is required' unless @public_key
       raise AuthenticationError, 'Secret key is required' unless @secret_key
 
       @connection = build_connection
+      @otel_connection = build_otel_connection if @ingestion_mode == :otel
+      @otel_exporter = OtelExporter.new(connection: @otel_connection, debug: @debug) if @ingestion_mode == :otel
       @event_queue = Concurrent::Array.new
       @flush_thread = start_flush_thread if @auto_flush
     end
@@ -450,16 +456,38 @@ module Langfuse
         return
       end
 
+      if @ingestion_mode == :otel
+        send_batch_otel(valid_events)
+      else
+        send_batch_legacy(valid_events)
+      end
+    end
+
+    def send_batch_legacy(valid_events)
       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 #{valid_events.length} events" if @debug
+        puts "Flushed #{valid_events.length} events (legacy)" if @debug
         response
       rescue StandardError => e
         puts "Failed to flush events: #{e.message}" if @debug
-        # Re-queue events on failure
+        valid_events.each { |event| @event_queue << event }
+        raise
+      end
+    end
+
+    def send_batch_otel(valid_events)
+      puts "Sending #{valid_events.length} events via OTEL" if @debug
+
+      begin
+        response = @otel_exporter.export(valid_events)
+        handle_response(response)
+        puts "Flushed #{valid_events.length} events (otel)" if @debug
+        response
+      rescue StandardError => e
+        puts "Failed to flush OTEL events: #{e.message}" if @debug
         valid_events.each { |event| @event_queue << event }
         raise
       end
@@ -491,6 +519,15 @@ module Langfuse
       end
     end
 
+    def resolve_ingestion_mode(explicit_mode)
+      return explicit_mode.to_sym if explicit_mode
+
+      env_mode = ENV['LANGFUSE_INGESTION_MODE']
+      return env_mode.to_sym if env_mode && !env_mode.empty?
+
+      Langfuse.configuration.ingestion_mode || :legacy
+    end
+
     def build_connection
       Faraday.new(url: @host) do |conn|
         # 配置请求和响应处理
@@ -514,6 +551,22 @@ module Langfuse
       end
     end
 
+    # Build a separate Faraday connection for OTEL with the v4 ingestion header.
+    def build_otel_connection
+      Faraday.new(url: @host) do |conn|
+        conn.response :json, content_type: /\bjson$/
+
+        conn.headers['User-Agent'] = "langfuse-ruby/#{Langfuse::VERSION}"
+        conn.headers['Authorization'] = "Basic #{Base64.strict_encode64("#{@public_key}:#{@secret_key}")}"
+        conn.headers['x-langfuse-ingestion-version'] = '4'
+        conn.headers['Content-Type'] = 'application/json'
+
+        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)
@@ -549,7 +602,7 @@ module Langfuse
       rescue Faraday::TimeoutError => e
         raise TimeoutError, "Request timed out: #{e.message}"
       rescue Faraday::ConnectionFailed => e
-        if retries_left > 0
+        if retries_left.positive?
           retries_left -= 1
           sleep(2**(@retries - retries_left))
           retry

data/lib/langfuse/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
   class Error < StandardError; end
   class AuthenticationError < Error; end

data/lib/langfuse/evaluation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
   class Evaluation
     attr_reader :id, :name, :value, :data_type, :comment, :trace_id, :observation_id, :created_at
@@ -84,10 +86,10 @@ module Langfuse
 
     class ExactMatchEvaluator < BaseEvaluator
       def initialize(name: 'exact_match', description: 'Exact match evaluator')
-        super(name: name, description: description)
+        super
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         return create_score(value: 0, comment: 'No expected value provided') unless expected
 
         score = output.to_s.strip == expected.to_s.strip ? 1 : 0
@@ -104,7 +106,7 @@ module Langfuse
         @case_sensitive = case_sensitive
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         return create_score(value: 0, comment: 'No expected value provided') unless expected
 
         output_str = @case_sensitive ? output.to_s : output.to_s.downcase
@@ -125,11 +127,11 @@ module Langfuse
         @max_length = max_length
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         length = output.to_s.length
 
         if @min_length && @max_length
-          score = length >= @min_length && length <= @max_length ? 1 : 0
+          score = length.between?(@min_length, @max_length) ? 1 : 0
           comment = score == 1 ? "Length #{length} within range" : "Length #{length} outside range #{@min_length}-#{@max_length}"
         elsif @min_length
           score = length >= @min_length ? 1 : 0
@@ -156,7 +158,7 @@ module Langfuse
         @pattern = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern)
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         match = @pattern.match(output.to_s)
         score = match ? 1 : 0
 
@@ -169,10 +171,10 @@ module Langfuse
 
     class SimilarityEvaluator < BaseEvaluator
       def initialize(name: 'similarity', description: 'Similarity evaluator')
-        super(name: name, description: description)
+        super
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         return create_score(value: 0, comment: 'No expected value provided') unless expected
 
         # Simple character-based similarity (Levenshtein distance)
@@ -230,10 +232,10 @@ module Langfuse
       def evaluate(input, output, expected: nil, context: nil)
         # This is a placeholder for LLM-based evaluation
         # In a real implementation, you would call an LLM API here
-        prompt = @prompt_template.gsub('{input}', input.to_s)
-                                 .gsub('{output}', output.to_s)
-                                 .gsub('{expected}', expected.to_s)
-                                 .gsub('{context}', context.to_s)
+        @prompt_template.gsub('{input}', input.to_s)
+                        .gsub('{output}', output.to_s)
+                        .gsub('{expected}', expected.to_s)
+                        .gsub('{context}', context.to_s)
 
         # Simulate LLM response (in real implementation, call actual LLM)
         score = rand(0.0..1.0).round(2)

data/lib/langfuse/event.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
   class Event
     attr_reader :id, :trace_id, :name, :start_time, :input, :output, :metadata,
@@ -49,9 +51,7 @@ module Langfuse
       return nil if type.nil?
 
       type_str = type.to_s
-      unless ObservationType.valid?(type_str)
-        raise ValidationError, "Invalid observation type: #{type}. Valid types are: #{ObservationType::ALL.join(', ')}"
-      end
+      raise ValidationError, "Invalid observation type: #{type}. Valid types are: #{ObservationType::ALL.join(', ')}" unless ObservationType.valid?(type_str)
 
       type_str
     end

data/lib/langfuse/generation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
   class Generation
     attr_reader :id, :trace_id, :name, :start_time, :end_time, :completion_start_time,
@@ -301,9 +303,7 @@ module Langfuse
       return nil if type.nil?
 
       type_str = type.to_s
-      unless ObservationType.valid?(type_str)
-        raise ValidationError, "Invalid observation type: #{type}. Valid types are: #{ObservationType::ALL.join(', ')}"
-      end
+      raise ValidationError, "Invalid observation type: #{type}. Valid types are: #{ObservationType::ALL.join(', ')}" unless ObservationType.valid?(type_str)
 
       type_str
     end

data/lib/langfuse/null_objects.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # NullGeneration provides a no-op generation object for graceful degradation.
+  # Used when Langfuse is unavailable or trace creation fails.
+  class NullGeneration
+    def update(**) = self
+    def end(**) = self
+    def span(**) = NullSpan.new
+    def generation(**) = NullGeneration.new
+    def event(**) = NullEvent.new
+    def agent(**) = NullSpan.new
+    def tool(**) = NullSpan.new
+    def chain(**) = NullSpan.new
+    def retriever(**) = NullSpan.new
+    def embedding(**) = NullSpan.new
+    def evaluator(**) = NullSpan.new
+    def guardrail(**) = NullSpan.new
+    def score(**) = nil
+    def get_url = nil
+    def to_dict = {}
+    def id = nil
+    def trace_id = nil
+  end
+
+  # NullSpan provides a no-op span object for graceful degradation.
+  class NullSpan
+    def update(**) = self
+    def end(**) = self
+    def span(**) = NullSpan.new
+    def generation(**) = NullGeneration.new
+    def event(**) = NullEvent.new
+    def agent(**) = NullSpan.new
+    def tool(**) = NullSpan.new
+    def chain(**) = NullSpan.new
+    def retriever(**) = NullSpan.new
+    def embedding(**) = NullSpan.new
+    def evaluator(**) = NullSpan.new
+    def guardrail(**) = NullSpan.new
+    def score(**) = nil
+    def get_url = nil
+    def to_dict = {}
+    def id = nil
+    def trace_id = nil
+  end
+
+  # NullEvent provides a no-op event object for graceful degradation.
+  class NullEvent
+    def to_dict = {}
+    def id = nil
+    def trace_id = nil
+  end
+
+  # NullTrace provides a no-op trace object for graceful degradation.
+  # Used when Langfuse is unavailable or trace creation fails.
+  # Ensures calling code doesn't break when Langfuse has issues.
+  class NullTrace
+    def update(**) = self
+    def span(**) = NullSpan.new
+    def generation(**) = NullGeneration.new
+    def event(**) = NullEvent.new
+    def agent(**) = NullSpan.new
+    def tool(**) = NullSpan.new
+    def chain(**) = NullSpan.new
+    def retriever(**) = NullSpan.new
+    def embedding(**) = NullSpan.new
+    def evaluator(**) = NullSpan.new
+    def guardrail(**) = NullSpan.new
+    def score(**) = nil
+    def get_url = nil
+    def to_dict = {}
+    def id = nil
+  end
+end