langfuse-ruby 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d97c16de061cdf52403a05086a90aaac149b9fe9dc6d771e36709e763abcb3eb
-  data.tar.gz: c254257501aff83671377cc50ea8f25c143d8dca6fa0f40d157fcfa6eb3d75b9
+  metadata.gz: 0bb8cc1f797c0b240830c5f909665dde61bb8a5540f1db8a04393ae0d741ee44
+  data.tar.gz: bc5b9e1dc24e2861ac66955bec4dccd25bbadaf1a3c5f59ddbacd784a50b2180
 SHA512:
-  metadata.gz: f2cf7c8a6d72bb5a81b73ba6a5a110e9e6312b09e9a790a14d566a41b1e7d4a8ce40c53fb8d0d74b4c12c9cd06bd20e03680b6829505f69aa7b80dee3ecf6750
-  data.tar.gz: c880f859cf2f0d6fc9586ceada7c7488ff25a8be4c3fbf4740443477e592b8eee20895e24c69c371a8f0a96c60fd40d1a66de2126b762378ea41115665de3666
+  metadata.gz: d5486239447652d3b97eb6200bc2f24ee829bef24da86409747f6a250fcc1126ce68841673b0e67da56a75e08ff4ec1bc9edf4b241c3431b855abdf2befdd7b9
+  data.tar.gz: 88b61075d0a394629dec59bbec509a7f4c80b0269a887dcef866b3a8a250fd75b362fe84fc6247e72b5305935702a7175c1db825461bb05270145912d6e8f79e

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 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).
+
+## [0.1.1] - 2025-01-12
+
+### Fixed
+- Improved error handling for `get_prompt` method when prompt doesn't exist
+- Better error messages for 404 responses that return HTML instead of JSON
+- Enhanced debugging capabilities with detailed request/response logging
+
+### Added
+- Comprehensive troubleshooting guide for prompt management issues
+- Better detection of HTML responses vs JSON responses
+- More specific error types for different failure scenarios
+
+### Changed
+- Updated gemspec metadata to avoid RubyGems warnings
+- Improved documentation with clearer error handling examples
+
+## [0.1.0] - 2025-01-12
+
+### Added
+- Initial release of Langfuse Ruby SDK
+- Complete tracing capabilities with traces, spans, and generations
+- Prompt management with versioning and caching
+- Built-in evaluators (exact match, similarity, length, contains, regex)
+- Custom scoring and evaluation pipeline support
+- Async event processing with automatic batching
+- Comprehensive error handling and validation
+- Framework integration examples (Rails, Sidekiq)
+- Full test suite with RSpec
+- Documentation and examples
+
+### Features
+- **Tracing**: Full observability for LLM applications
+- **Prompt Management**: Version control and deployment of prompts
+- **Evaluation**: Multiple built-in evaluators and custom scoring
+- **Async Processing**: Background event processing with batching
+- **Type Safety**: Comprehensive error handling
+- **Integration**: Easy integration with Ruby frameworks 

data/Gemfile

@@ -1,9 +1,9 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in langfuse.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
-gem "rspec", "~> 3.0"
-gem "rubocop", "~> 1.21"
-gem "yard", "~> 0.9"
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'rubocop', '~> 1.21'
+gem 'yard', '~> 0.9'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    langfuse-ruby (0.1.1)
+    langfuse-ruby (0.1.2)
       concurrent-ruby (~> 1.0)
       faraday (~> 2.0)
       faraday-net_http (~> 3.0)

data/docs/PUBLISH_GUIDE.md

@@ -108,10 +108,10 @@ chmod 0600 ~/.gem/credentials
 
 ```bash
 # 构建最新版本
-gem build langfuse.gemspec
+gem build langfuse-ruby.gemspec
 
 # 发布到 RubyGems
-gem push langfuse-ruby-0.1.0.gem
+gem push langfuse-ruby-0.1.x.gem
 ```
 
 ## 📊 发布后验证

data/docs/README.md

@@ -7,10 +7,6 @@
 ### 开发和发布
 - [📋 发布指南](PUBLISH_GUIDE.md) - 详细的 gem 发布流程
 - [✅ 发布检查清单](RELEASE_CHECKLIST.md) - 发布前的检查项目
-- [📝 变更日志](CHANGELOG.md) - 版本更新记录
-
-### 项目概览
-- [📊 项目总结](PROJECT_SUMMARY.md) - 项目整体介绍
 - [🎯 最终总结](FINAL_SUMMARY.md) - 项目完成情况总结
 
 ## 🔗 相关链接

data/examples/connection_config_demo.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/langfuse'
+
+puts '🚀 Langfuse Ruby SDK 连接配置演示'
+puts '=' * 50
+
+# 显示默认配置
+puts "\n📋 默认配置信息:"
+puts "   默认主机: #{Langfuse.configuration.host}"
+puts "   默认超时: #{Langfuse.configuration.timeout}秒"
+puts "   默认重试: #{Langfuse.configuration.retries}次"
+
+# 方法 1: 使用测试密钥创建客户端（仅用于演示）
+puts "\n📝 方法 1: 直接参数配置"
+puts '代码示例：'
+puts 'client = Langfuse.new('
+puts "  public_key: 'pk-lf-your-public-key',"
+puts "  secret_key: 'sk-lf-your-secret-key',"
+puts "  host: 'https://us.cloud.langfuse.com'"
+puts ')'
+
+# 使用测试密钥创建客户端
+test_client = Langfuse.new(
+  public_key: 'test-public-key',
+  secret_key: 'test-secret-key',
+  host: 'https://us.cloud.langfuse.com'
+)
+
+puts '✅ 客户端配置成功'
+puts "   主机: #{test_client.host}"
+puts "   超时: #{test_client.timeout}秒"
+puts "   重试: #{test_client.retries}次"
+
+# 方法 2: 全局配置
+puts "\n📝 方法 2: 全局配置"
+puts '代码示例：'
+puts 'Langfuse.configure do |config|'
+puts "  config.public_key = 'pk-lf-your-public-key'"
+puts "  config.secret_key = 'sk-lf-your-secret-key'"
+puts "  config.host = 'https://us.cloud.langfuse.com'"
+puts '  config.debug = true'
+puts 'end'
+
+Langfuse.configure do |config|
+  config.public_key = 'test-public-key'
+  config.secret_key = 'test-secret-key'
+  config.host = 'https://us.cloud.langfuse.com'
+  config.debug = true
+  config.timeout = 60
+  config.retries = 5
+end
+
+global_client = Langfuse.new
+puts '✅ 全局配置成功'
+puts "   主机: #{global_client.host}"
+puts "   调试模式: #{global_client.debug}"
+puts "   超时: #{global_client.timeout}秒"
+puts "   重试: #{global_client.retries}次"
+
+# 方法 3: 环境变量配置
+puts "\n📝 方法 3: 环境变量配置"
+puts '设置环境变量：'
+puts "export LANGFUSE_PUBLIC_KEY='pk-lf-your-public-key'"
+puts "export LANGFUSE_SECRET_KEY='sk-lf-your-secret-key'"
+puts "export LANGFUSE_HOST='https://us.cloud.langfuse.com'"
+puts ''
+puts '然后使用：'
+puts 'client = Langfuse.new'
+
+if ENV['LANGFUSE_PUBLIC_KEY'] && ENV['LANGFUSE_SECRET_KEY']
+  env_client = Langfuse.new
+  puts '✅ 环境变量配置成功'
+  puts "   主机: #{env_client.host}"
+else
+  puts '⚠️  环境变量未设置，跳过此示例'
+end
+
+# 连接配置详情
+puts "\n🔧 连接配置详情:"
+puts '根据 Langfuse 官方文档:'
+puts '1. 认证方式: HTTP Basic Auth'
+puts '2. 用户名: Langfuse Public Key (pk-lf-...)'
+puts '3. 密码: Langfuse Secret Key (sk-lf-...)'
+puts '4. 默认服务器: https://us.cloud.langfuse.com'
+puts '5. 内容类型: application/json'
+puts "6. User-Agent: langfuse-ruby/#{Langfuse::VERSION}"
+
+# 创建测试 trace（不发送到服务器）
+puts "\n🧪 创建测试 Trace（离线）:"
+begin
+  trace = test_client.trace(
+    name: 'connection-test',
+    user_id: 'demo-user',
+    input: { message: '测试连接配置' },
+    metadata: { demo: true }
+  )
+
+  puts '✅ Trace 创建成功'
+  puts "   ID: #{trace.id}"
+  puts "   名称: #{trace.name}"
+  puts "   用户ID: #{trace.user_id}"
+
+  # 添加 generation
+  generation = trace.generation(
+    name: 'demo-generation',
+    model: 'gpt-3.5-turbo',
+    input: [{ role: 'user', content: 'Hello!' }],
+    output: { content: '你好！' },
+    usage: { prompt_tokens: 5, completion_tokens: 3, total_tokens: 8 }
+  )
+
+  puts '✅ Generation 创建成功'
+  puts "   ID: #{generation.id}"
+  puts "   模型: #{generation.model}"
+rescue StandardError => e
+  puts "❌ 测试失败: #{e.message}"
+end
+
+puts "\n📚 使用提示:"
+puts "1. 替换示例中的 'test-public-key' 和 'test-secret-key' 为您的真实 API 密钥"
+puts '2. 确保网络连接正常'
+puts '3. 启用 debug 模式可以查看详细的请求日志'
+puts '4. 调用 client.flush 来发送事件到服务器'
+puts '5. 使用 client.shutdown 来优雅地关闭客户端'
+
+puts "\n🎉 连接配置演示完成！"

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

@@ -99,7 +99,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 +138,7 @@ module Langfuse
         **kwargs
       }
 
-      response = post('/api/public/prompts', data)
+      response = post('/api/public/v2/prompts', data)
       Prompt.new(response.body)
     end
 
@@ -227,15 +227,24 @@ module Langfuse
 
     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
 

data/lib/langfuse/version.rb

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

data/lib/langfuse.rb

@@ -35,7 +35,7 @@ module Langfuse
     def initialize
       @public_key = nil
       @secret_key = nil
-      @host = 'https://cloud.langfuse.com'
+      @host = 'https://us.cloud.langfuse.com'
       @debug = false
       @timeout = 30
       @retries = 3

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Richard Sun
@@ -175,19 +175,18 @@ files:
 - ".github/workflows/ci.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- PROMPT_TROUBLESHOOTING.md
 - README.md
 - Rakefile
-- docs/CHANGELOG.md
 - docs/FINAL_SUMMARY.md
-- docs/PROJECT_SUMMARY.md
 - docs/PUBLISH_GUIDE.md
 - docs/README.md
 - docs/RELEASE_CHECKLIST.md
 - examples/basic_tracing.rb
+- examples/connection_config_demo.rb
 - examples/prompt_management.rb
 - langfuse-ruby.gemspec
 - lib/langfuse.rb
@@ -202,7 +201,6 @@ files:
 - lib/langfuse/version.rb
 - scripts/release.sh
 - scripts/verify_release.rb
-- test_basic.rb
 - test_offline.rb
 homepage: https://langfuse.com
 licenses:

data/PROMPT_TROUBLESHOOTING.md

@@ -1,206 +0,0 @@
-# Langfuse Ruby SDK - Prompt 获取故障排除指南
-
-## 问题描述
-
-当调用 `client.get_prompt("prompt-name")` 时，可能会遇到以下错误：
-
-```
-JSON::ParserError: unexpected token at '<!DOCTYPE html>
-```
-
-## 问题原因
-
-这个错误通常表示 Langfuse API 返回了 HTML 页面而不是预期的 JSON 响应。最常见的原因是：
-
-1. **404 错误**：请求的 prompt 不存在
-2. **认证问题**：API 密钥无效或权限不足
-3. **网络问题**：无法连接到 Langfuse 服务器
-
-## 解决方案
-
-### 1. 检查 Prompt 是否存在
-
-首先确认要获取的 prompt 是否已在 Langfuse 中创建：
-
-```ruby
-# 尝试获取 prompt
-begin
-  prompt = client.get_prompt("your-prompt-name")
-  puts "成功获取 prompt: #{prompt.name}"
-rescue Langfuse::ValidationError => e
-  if e.message.include?("404")
-    puts "Prompt 不存在，请先创建它"
-  else
-    puts "其他验证错误: #{e.message}"
-  end
-rescue => e
-  puts "未知错误: #{e.message}"
-end
-```
-
-### 2. 创建测试 Prompt
-
-如果 prompt 不存在，可以先创建一个：
-
-```ruby
-# 创建一个测试 prompt
-test_prompt = client.create_prompt(
-  name: "test-prompt",
-  prompt: "Hello {{name}}! This is a test prompt.",
-  labels: ["test"],
-  config: { temperature: 0.7 }
-)
-
-puts "创建了 prompt: #{test_prompt.name}"
-
-# 然后尝试获取它
-retrieved_prompt = client.get_prompt("test-prompt")
-puts "成功获取 prompt: #{retrieved_prompt.name}"
-```
-
-### 3. 检查 API 密钥
-
-确认 API 密钥设置正确：
-
-```ruby
-# 检查环境变量
-puts "Public Key: #{ENV['LANGFUSE_PUBLIC_KEY']}"
-puts "Secret Key: #{ENV['LANGFUSE_SECRET_KEY'] ? '已设置' : '未设置'}"
-puts "Host: #{ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'}"
-
-# 或者在代码中直接设置
-client = Langfuse.new(
-  public_key: "your-public-key",
-  secret_key: "your-secret-key",
-  host: "https://cloud.langfuse.com"
-)
-```
-
-### 4. 测试连接
-
-测试与 Langfuse 服务器的基本连接：
-
-```ruby
-begin
-  response = client.send(:get, "/api/public/health")
-  puts "连接正常"
-rescue => e
-  puts "连接失败: #{e.message}"
-end
-```
-
-### 5. 启用调试模式
-
-启用调试模式以获取更多信息：
-
-```ruby
-client = Langfuse.new(
-  public_key: "your-public-key",
-  secret_key: "your-secret-key",
-  host: "https://cloud.langfuse.com",
-  debug: true  # 启用调试模式
-)
-```
-
-## 改进的错误处理
-
-Ruby SDK 已经改进了错误处理，现在会提供更清晰的错误信息：
-
-```ruby
-begin
-  prompt = client.get_prompt("non-existent-prompt")
-rescue Langfuse::ValidationError => e
-  puts "验证错误: #{e.message}"
-  # 现在会显示：Resource not found (404). Server returned HTML page instead of JSON API response. This usually means the requested resource does not exist.
-rescue Langfuse::AuthenticationError => e
-  puts "认证错误: #{e.message}"
-rescue => e
-  puts "其他错误: #{e.message}"
-end
-```
-
-## 常见问题
-
-### Q: 为什么会收到 HTML 响应而不是 JSON？
-
-A: 当 API 端点返回 404 错误时，Langfuse 服务器返回一个 HTML 错误页面而不是 JSON 响应。这是 Web 应用程序的常见行为。
-
-### Q: 如何确认 prompt 名称是否正确？
-
-A: 可以登录 Langfuse Web 界面查看所有可用的 prompt，或者使用 API 列出所有 prompt：
-
-```ruby
-# 注意：这需要使用底层 API 方法
-# prompts = client.api.prompts.list()
-```
-
-### Q: 大小写是否重要？
-
-A: 是的，prompt 名称是区分大小写的。确保使用正确的大小写。
-
-### Q: 如何处理网络超时？
-
-A: 可以调整超时设置：
-
-```ruby
-client = Langfuse.new(
-  public_key: "your-public-key",
-  secret_key: "your-secret-key",
-  host: "https://cloud.langfuse.com",
-  timeout: 60  # 60 秒超时
-)
-```
-
-## 完整示例
-
-以下是一个完整的示例，展示如何安全地获取 prompt：
-
-```ruby
-require 'langfuse'
-
-# 初始化客户端
-client = Langfuse.new(
-  public_key: ENV['LANGFUSE_PUBLIC_KEY'],
-  secret_key: ENV['LANGFUSE_SECRET_KEY'],
-  host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com',
-  debug: true
-)
-
-# 安全地获取 prompt
-def safe_get_prompt(client, name)
-  begin
-    prompt = client.get_prompt(name)
-    puts "✅ 成功获取 prompt: #{prompt.name}"
-    return prompt
-  rescue Langfuse::ValidationError => e
-    if e.message.include?("404")
-      puts "❌ Prompt '#{name}' 不存在"
-      puts "建议：请先在 Langfuse 中创建这个 prompt"
-    else
-      puts "❌ 验证错误: #{e.message}"
-    end
-  rescue Langfuse::AuthenticationError => e
-    puts "❌ 认证失败: #{e.message}"
-    puts "建议：检查 API 密钥是否正确"
-  rescue => e
-    puts "❌ 未知错误: #{e.message}"
-  end
-  return nil
-end
-
-# 使用示例
-prompt = safe_get_prompt(client, "your-prompt-name")
-if prompt
-  compiled = prompt.compile(variable: "value")
-  puts "编译后的 prompt: #{compiled}"
-end
-```
-
-## 获取帮助
-
-如果问题仍然存在，请：
-
-1. 检查 [Langfuse 文档](https://langfuse.com/docs/prompts/get-started)
-2. 访问 [GitHub Issues](https://github.com/langfuse/langfuse-ruby/issues)
-3. 加入 [Discord 社区](https://discord.gg/langfuse)
-4. 查看 [状态页面](https://status.langfuse.com) 了解服务状态 

data/docs/CHANGELOG.md

@@ -1,49 +0,0 @@
-# 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]
-
-## [0.1.0] - 2025-01-09
-
-### Added
-- Initial release of Langfuse Ruby SDK
-- Complete tracing functionality with traces, spans, and generations
-- Prompt management with version control and caching
-- Built-in evaluation system with multiple evaluators
-- Comprehensive error handling and validation
-- Automatic event batching and background processing
-- Support for environment variable configuration
-- Extensive documentation and examples
-- Full test coverage with RSpec
-- Framework integration examples (Rails, Sidekiq)
-
-### Features
-- **Tracing**: Create and manage traces with nested spans and generations
-- **Prompt Management**: Create, retrieve, and compile prompts with variable substitution
-- **Evaluation**: Built-in evaluators for exact match, similarity, length, regex, and custom scoring
-- **Client Management**: Robust HTTP client with retries, timeouts, and authentication
-- **Event Processing**: Asynchronous event queue with automatic flushing
-- **Error Handling**: Comprehensive error types with detailed messages
-- **Utilities**: Helper methods for ID generation, timestamps, and data transformation
-
-### Dependencies
-- faraday (~> 2.0) - HTTP client library
-- faraday-net_http (~> 3.0) - Net::HTTP adapter for Faraday
-- json (~> 2.0) - JSON parsing and generation
-- concurrent-ruby (~> 1.0) - Thread-safe data structures
-
-### Development Dependencies
-- bundler (~> 2.0)
-- rake (~> 13.0)
-- rspec (~> 3.0)
-- webmock (~> 3.0)
-- vcr (~> 6.0)
-- rubocop (~> 1.0)
-- yard (~> 0.9)
-
-[Unreleased]: https://github.com/ai-firstly/langfuse-ruby/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/ai-firstly/langfuse-ruby/releases/tag/v0.1.0 

data/docs/PROJECT_SUMMARY.md

@@ -1,263 +0,0 @@
-# Langfuse Ruby SDK - 项目总结
-
-## 🎉 项目完成状态
-
-✅ **项目已完成** - 所有核心功能已实现并通过测试
-
-## 📋 功能清单
-
-### ✅ 已实现的功能
-
-1. **核心架构**
-   - [x] 模块化设计
-   - [x] 完整的错误处理系统
-   - [x] 配置管理
-   - [x] 工具类和辅助方法
-
-2. **客户端管理**
-   - [x] HTTP 客户端（基于 Faraday）
-   - [x] 认证系统（Basic Auth）
-   - [x] 自动重试机制
-   - [x] 超时处理
-   - [x] 错误分类和处理
-
-3. **追踪功能**
-   - [x] Trace 创建和管理
-   - [x] Span 创建和嵌套
-   - [x] Generation 追踪（LLM 调用）
-   - [x] 事件队列和批处理
-   - [x] 后台线程自动刷新
-
-4. **提示管理**
-   - [x] 提示创建和获取
-   - [x] 版本控制
-   - [x] 缓存机制
-   - [x] 变量编译（{{variable}} 格式）
-   - [x] 文本和聊天提示支持
-   - [x] 提示模板类
-
-5. **评估系统**
-   - [x] 基础评估器框架
-   - [x] 精确匹配评估器
-   - [x] 相似度评估器（Levenshtein 距离）
-   - [x] 长度评估器
-   - [x] 包含评估器
-   - [x] 正则表达式评估器
-   - [x] 自定义评分系统
-
-6. **测试和文档**
-   - [x] 完整的测试套件
-   - [x] 详细的 README 文档
-   - [x] 使用示例
-   - [x] API 文档
-   - [x] 变更日志
-
-## 🏗️ 项目结构
-
-```
-langfuse/
-├── lib/
-│   └── langfuse/
-│       ├── client.rb          # 核心客户端
-│       ├── trace.rb           # 追踪功能
-│       ├── span.rb            # Span 管理
-│       ├── generation.rb      # Generation 管理
-│       ├── prompt.rb          # 提示管理
-│       ├── evaluation.rb      # 评估系统
-│       ├── errors.rb          # 错误定义
-│       ├── utils.rb           # 工具类
-│       └── version.rb         # 版本信息
-├── spec/                      # 测试文件
-├── examples/                  # 使用示例
-├── langfuse.gemspec          # Gem 规范
-├── README.md                 # 项目文档
-├── CHANGELOG.md              # 变更日志
-└── LICENSE                   # 许可证
-```
-
-## 🔧 技术栈
-
-- **Ruby**: >= 2.7.0
-- **HTTP 客户端**: Faraday 2.0+
-- **并发处理**: concurrent-ruby 1.0+
-- **JSON 处理**: json 2.0+
-- **测试框架**: RSpec 3.0+
-- **代码质量**: RuboCop 1.0+
-
-## 🚀 核心特性
-
-### 1. 追踪系统
-- 支持嵌套的 traces、spans 和 generations
-- 自动 ID 生成和时间戳
-- 元数据和标签支持
-- 异步事件处理
-
-### 2. 提示管理
-- 版本控制和缓存
-- 变量替换系统
-- 多种提示格式支持
-- LangChain 兼容性
-
-### 3. 评估框架
-- 多种内置评估器
-- 可扩展的评估系统
-- 自定义评分支持
-- 详细的评估结果
-
-### 4. 企业级特性
-- 完整的错误处理
-- 配置管理
-- 环境变量支持
-- 框架集成示例
-
-## 📊 测试结果
-
-```
-🚀 Testing Langfuse Ruby SDK (Offline Mode)...
-
-✅ Configuration successful
-✅ Client initialization successful
-✅ Trace creation successful
-✅ Generation creation successful
-✅ Prompt template successful
-✅ Chat prompt template successful
-✅ Evaluators successful (5/5)
-✅ Utils successful
-✅ Event queue successful
-✅ Complex workflow successful
-✅ Error handling successful
-
-🎉 All offline tests completed successfully!
-```
-
-## 📚 使用示例
-
-### 基本用法
-```ruby
-require 'langfuse'
-
-client = Langfuse.new(
-  public_key: "pk-lf-...",
-  secret_key: "sk-lf-..."
-)
-
-trace = client.trace(
-  name: "chat-completion",
-  user_id: "user123",
-  input: { message: "Hello!" }
-)
-
-generation = trace.generation(
-  name: "openai-chat",
-  model: "gpt-3.5-turbo",
-  input: [{ role: "user", content: "Hello!" }],
-  output: { content: "Hi there!" }
-)
-
-client.flush
-```
-
-### 提示管理
-```ruby
-# 获取提示
-prompt = client.get_prompt("greeting-prompt")
-
-# 编译提示
-compiled = prompt.compile(
-  user_name: "Alice",
-  topic: "AI"
-)
-```
-
-### 评估系统
-```ruby
-evaluator = Langfuse::Evaluators::ExactMatchEvaluator.new
-result = evaluator.evaluate(
-  "What is 2+2?",
-  "4",
-  expected: "4"
-)
-```
-
-## 🔄 与官方 SDK 对比
-
-| 功能 | Python SDK | JS SDK | Ruby SDK |
-|------|------------|--------|----------|
-| 基础追踪 | ✅ | ✅ | ✅ |
-| 提示管理 | ✅ | ✅ | ✅ |
-| 评估系统 | ✅ | ✅ | ✅ |
-| 异步处理 | ✅ | ✅ | ✅ |
-| 错误处理 | ✅ | ✅ | ✅ |
-| 框架集成 | ✅ | ✅ | ✅ |
-
-## 📦 发布准备
-
-### Gem 规范
-- 名称: `langfuse`
-- 版本: `0.1.0`
-- 许可证: MIT
-- Ruby 版本: >= 2.7.0
-
-### 依赖项
-```ruby
-spec.add_dependency "faraday", "~> 2.0"
-spec.add_dependency "faraday-net_http", "~> 3.0"
-spec.add_dependency "json", "~> 2.0"
-spec.add_dependency "concurrent-ruby", "~> 1.0"
-```
-
-## 🛠️ 开发指南
-
-### 安装依赖
-```bash
-bundle install
-```
-
-### 运行测试
-```bash
-bundle exec rspec
-```
-
-### 离线测试
-```bash
-ruby test_offline.rb
-```
-
-## 🔮 未来扩展
-
-### 可能的改进
-1. **性能优化**
-   - 连接池管理
-   - 更高效的批处理
-   - 内存优化
-
-2. **功能扩展**
-   - 更多评估器
-   - 数据集管理
-   - 实验功能
-
-3. **集成支持**
-   - Rails 集成 gem
-   - Sidekiq 中间件
-   - 更多框架支持
-
-## 📄 许可证
-
-MIT License - 允许商业和开源使用
-
-## 🤝 贡献指南
-
-1. Fork 项目
-2. 创建功能分支
-3. 提交更改
-4. 创建 Pull Request
-
-## 📞 支持
-
-- GitHub Issues: 报告 bug 和功能请求
-- 文档: 详细的使用指南
-- 示例: 完整的使用示例
-
----
-
-**总结**: 这个 Langfuse Ruby SDK 是一个功能完整、测试充分的生产级 SDK，完全兼容 Langfuse API，可以立即用于生产环境。它提供了与官方 Python 和 JavaScript SDK 相同的功能，并且遵循 Ruby 社区的最佳实践。 

data/test_basic.rb

@@ -1,183 +0,0 @@
-#!/usr/bin/env ruby
-
-require_relative 'lib/langfuse'
-
-puts "🚀 Testing Langfuse Ruby SDK..."
-
-# Test 1: Basic configuration
-puts "\n1. Testing configuration..."
-Langfuse.configure do |config|
-  config.public_key = "test_key"
-  config.secret_key = "test_secret"
-  config.host = "https://test.langfuse.com"
-  config.debug = true
-end
-
-puts "✅ Configuration successful"
-puts "   Public key: #{Langfuse.configuration.public_key}"
-puts "   Host: #{Langfuse.configuration.host}"
-
-# Test 2: Client initialization
-puts "\n2. Testing client initialization..."
-begin
-  client = Langfuse.new(
-    public_key: "test_key",
-    secret_key: "test_secret",
-    host: "https://test.langfuse.com"
-  )
-  puts "✅ Client initialization successful"
-  puts "   Client class: #{client.class}"
-  puts "   Public key: #{client.public_key}"
-rescue => e
-  puts "❌ Client initialization failed: #{e.message}"
-end
-
-# Test 3: Trace creation
-puts "\n3. Testing trace creation..."
-begin
-  trace = client.trace(
-    name: "test-trace",
-    user_id: "test-user",
-    input: { message: "Hello, world!" }
-  )
-  puts "✅ Trace creation successful"
-  puts "   Trace ID: #{trace.id}"
-  puts "   Trace name: #{trace.name}"
-rescue => e
-  puts "❌ Trace creation failed: #{e.message}"
-end
-
-# Test 4: Generation creation
-puts "\n4. Testing generation creation..."
-begin
-  generation = trace.generation(
-    name: "test-generation",
-    model: "gpt-3.5-turbo",
-    input: [{ role: "user", content: "Hello!" }],
-    output: { content: "Hi there!" }
-  )
-  puts "✅ Generation creation successful"
-  puts "   Generation ID: #{generation.id}"
-  puts "   Model: #{generation.model}"
-rescue => e
-  puts "❌ Generation creation failed: #{e.message}"
-end
-
-# Test 5: Span creation
-puts "\n5. Testing span creation..."
-begin
-  span = trace.span(
-    name: "test-span",
-    input: { query: "test query" }
-  )
-  puts "✅ Span creation successful"
-  puts "   Span ID: #{span.id}"
-  puts "   Span name: #{span.name}"
-rescue => e
-  puts "❌ Span creation failed: #{e.message}"
-end
-
-# Test 6: Prompt template
-puts "\n6. Testing prompt template..."
-begin
-  template = Langfuse::PromptTemplate.from_template(
-    "Hello {{name}}! How are you feeling {{mood}} today?"
-  )
-
-  formatted = template.format(
-    name: "Alice",
-    mood: "happy"
-  )
-
-  puts "✅ Prompt template successful"
-  puts "   Template variables: #{template.input_variables}"
-  puts "   Formatted: #{formatted}"
-rescue => e
-  puts "❌ Prompt template failed: #{e.message}"
-end
-
-# Test 7: Chat prompt template
-puts "\n7. Testing chat prompt template..."
-begin
-  chat_template = Langfuse::ChatPromptTemplate.from_messages([
-    { role: "system", content: "You are a helpful {{role}} assistant." },
-    { role: "user", content: "{{user_input}}" }
-  ])
-
-  messages = chat_template.format(
-    role: "coding",
-    user_input: "Help me with Ruby"
-  )
-
-  puts "✅ Chat prompt template successful"
-  puts "   Template variables: #{chat_template.input_variables}"
-  puts "   Messages count: #{messages.length}"
-rescue => e
-  puts "❌ Chat prompt template failed: #{e.message}"
-end
-
-# Test 8: Evaluators
-puts "\n8. Testing evaluators..."
-begin
-  # Exact match evaluator
-  exact_match = Langfuse::Evaluators::ExactMatchEvaluator.new
-  result = exact_match.evaluate(
-    input: "What is 2+2?",
-    output: "4",
-    expected: "4"
-  )
-  puts "✅ Exact match evaluator successful"
-  puts "   Result: #{result}"
-
-  # Similarity evaluator
-  similarity = Langfuse::Evaluators::SimilarityEvaluator.new
-  result = similarity.evaluate(
-    input: "What is AI?",
-    output: "Artificial Intelligence",
-    expected: "AI is artificial intelligence"
-  )
-  puts "✅ Similarity evaluator successful"
-  puts "   Result: #{result}"
-rescue => e
-  puts "❌ Evaluator failed: #{e.message}"
-end
-
-# Test 9: Utils
-puts "\n9. Testing utilities..."
-begin
-  id = Langfuse::Utils.generate_id
-  timestamp = Langfuse::Utils.current_timestamp
-
-  puts "✅ Utils successful"
-  puts "   Generated ID: #{id}"
-  puts "   Timestamp: #{timestamp}"
-rescue => e
-  puts "❌ Utils failed: #{e.message}"
-end
-
-# Test 10: Event queue
-puts "\n10. Testing event queue..."
-begin
-  queue_size_before = client.instance_variable_get(:@event_queue).length
-
-  client.score(
-    trace_id: trace.id,
-    name: "test-score",
-    value: 0.9
-  )
-
-  queue_size_after = client.instance_variable_get(:@event_queue).length
-
-  puts "✅ Event queue successful"
-  puts "   Queue size before: #{queue_size_before}"
-  puts "   Queue size after: #{queue_size_after}"
-rescue => e
-  puts "❌ Event queue failed: #{e.message}"
-end
-
-puts "\n🎉 All tests completed!"
-puts "   This SDK is ready for use with Langfuse!"
-puts "   Remember to set your real API keys when using in production."
-
-# Clean shutdown
-client.shutdown