langfuse-ruby 0.1.5 → 0.1.7

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Richard Sun
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -45,39 +44,39 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: faraday-net_http
+  name: faraday-multipart
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
 - !ruby/object:Gem::Dependency
-  name: faraday-multipart
+  name: faraday-net_http
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -201,23 +200,25 @@ files:
 - ".github/workflows/ci.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"
+- ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
+- Makefile
 - README.md
 - Rakefile
 - docs/FINAL_SUMMARY.md
 - docs/PUBLISH_GUIDE.md
 - docs/README.md
 - docs/RELEASE_CHECKLIST.md
-- docs/TYPE_VALIDATION_TROUBLESHOOTING.md
-- docs/URL_ENCODING_FIX.md
 - examples/auto_flush_control.rb
 - examples/basic_tracing.rb
 - examples/connection_config_demo.rb
 - examples/event_usage.rb
 - examples/prompt_management.rb
+- examples/simplified_usage.rb
 - examples/url_encoding_demo.rb
 - langfuse-ruby.gemspec
 - lib/langfuse.rb
@@ -226,15 +227,17 @@ files:
 - lib/langfuse/evaluation.rb
 - lib/langfuse/event.rb
 - lib/langfuse/generation.rb
+- lib/langfuse/null_objects.rb
 - lib/langfuse/observation_types.rb
+- lib/langfuse/otel_exporter.rb
 - lib/langfuse/prompt.rb
 - lib/langfuse/span.rb
 - lib/langfuse/trace.rb
 - lib/langfuse/utils.rb
 - lib/langfuse/version.rb
 - scripts/release.sh
+- scripts/test_offline.rb
 - scripts/verify_release.rb
-- test_offline.rb
 homepage: https://langfuse.com
 licenses:
 - MIT
@@ -245,7 +248,7 @@ metadata:
   changelog_uri: https://github.com/ai-firstly/langfuse-ruby/blob/main/CHANGELOG.md
   documentation_uri: https://rubydoc.info/gems/langfuse-ruby
   bug_tracker_uri: https://github.com/ai-firstly/langfuse-ruby/issues
-post_install_message:
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -260,8 +263,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby SDK for Langfuse - Open source LLM engineering platform
 test_files: []

data/docs/TYPE_VALIDATION_TROUBLESHOOTING.md

@@ -1,202 +0,0 @@
-# 类型验证错误故障排除指南
-
-## 问题描述
-
-当您遇到以下错误时：
-
-```json
-{
-  "id": "xxx",
-  "status": 400,
-  "message": "Invalid request data",
-  "error": [
-    {
-      "code": "invalid_union",
-      "errors": [],
-      "note": "No matching discriminator", 
-      "path": ["type"],
-      "message": "Invalid input"
-    }
-  ]
-}
-```
-
-这表示 Langfuse 服务器端的 API 验证发现事件的 `type` 字段不符合预期的格式。
-
-## 根本原因
-
-1. **事件类型无效**: 发送的事件类型不在服务器端支持的列表中
-2. **事件数据结构错误**: 事件的数据结构不符合对应类型的要求
-3. **数据序列化问题**: 事件数据在序列化过程中出现问题
-
-## 常见修复案例
-
-### 1. 事件类型无效
-
-```ruby
-client.trace(name: "my-trace", user_id: "user-123", input: { query: "Hello" })
-```
-
-## 解决方案
-
-### 1. 启用调试模式
-
-```ruby
-client = Langfuse.new(
-  public_key: "your-key",
-  secret_key: "your-secret",
-  debug: true  # 启用调试模式
-)
-```
-
-调试模式会显示：
-- 发送的事件类型
-- 事件数据结构
-- 详细的错误信息
-
-### 2. 检查支持的事件类型
-
-当前支持的事件类型：
-- `trace-create`
-- `generation-create`
-- `generation-update`
-- `span-create`
-- `span-update`
-- `event-create`
-- `score-create`
-
-### 3. 验证事件数据
-
-确保事件数据包含必要的字段：
-
-#### Trace 事件
-```ruby
-{
-  id: "uuid",
-  name: "trace-name",
-  user_id: "user-id",
-  input: { ... },
-  metadata: { ... },
-  tags: [...],
-  timestamp: "2025-01-01T00:00:00.000Z"
-}
-```
-
-#### Generation 事件
-```ruby
-{
-  id: "uuid",
-  trace_id: "trace-uuid",
-  name: "generation-name",
-  model: "gpt-3.5-turbo",
-  input: [...],
-  output: { ... },
-  usage: { ... },
-  metadata: { ... }
-}
-```
-
-#### Span 事件
-```ruby
-{
-  id: "uuid",
-  trace_id: "trace-uuid",
-  name: "span-name",
-  start_time: "2025-01-01T00:00:00.000Z",
-  end_time: "2025-01-01T00:00:01.000Z",
-  input: { ... },
-  output: { ... },
-  metadata: { ... }
-}
-```
-
-#### Event 事件
-```ruby
-
-```ruby
-
-```
-
-#### Score 事件
-```ruby
-
-```
-
-### 4. 检查网络和认证
-
-确保：
-- API 密钥正确
-- 网络连接正常
-- 服务器端点可访问
-
-### 5. 使用错误处理
-
-```ruby
-begin
-  client.flush
-rescue Langfuse::ValidationError => e
-  if e.message.include?('Event type validation failed')
-    puts "类型验证错误: #{e.message}"
-    # 检查事件数据格式
-  else
-    puts "其他验证错误: #{e.message}"
-  end
-rescue Langfuse::APIError => e
-  puts "API 错误: #{e.message}"
-end
-```
-
-## 预防措施
-
-1. **使用官方 SDK 方法**: 避免直接构造事件数据
-2. **数据验证**: 在发送前验证数据完整性
-3. **错误监控**: 实施适当的错误处理和监控
-4. **测试环境**: 在测试环境中验证集成
-5. **保持更新**: 定期更新 SDK 到最新版本
-
-## 示例代码
-
-```ruby
-# 正确的使用方式
-client = Langfuse.new(
-  public_key: "pk-lf-xxx",
-  secret_key: "sk-lf-xxx",
-  debug: true
-)
-
-# 创建 trace
-trace = client.trace(
-  name: "my-trace",
-  user_id: "user-123",
-  input: { query: "Hello" }
-)
-
-# 创建 generation
-generation = trace.generation(
-  name: "my-generation",
-  model: "gpt-3.5-turbo",
-  input: [{ role: "user", content: "Hello" }],
-  output: { content: "Hi there!" }
-)
-
-# 安全地刷新事件
-begin
-  client.flush
-  puts "事件发送成功"
-rescue => e
-  puts "发送失败: #{e.message}"
-end
-```
-
-## 联系支持
-
-如果问题持续存在，请提供：
-1. 完整的错误消息
-2. 调试模式的输出
-3. 相关的代码片段
-4. SDK 版本信息
-
-## 更新日志
-
-- v0.1.1: 改进了错误消息的可读性
-- v0.1.0: 初始版本 

data/docs/URL_ENCODING_FIX.md

@@ -1,164 +0,0 @@
-# URL Encoding Fix for Prompt Names
-
-## Issue Summary
-
-**Issue ID**: AIF-2  
-**Title**: Prompt names with `/` are not URL-encoded  
-**Status**: Fixed
-
-## Problem Description
-
-Prompt names containing special characters (particularly `/`) were not being URL-encoded before being interpolated into the API path when using `get_prompt`. This caused the server to misinterpret the prompt name as a nested path structure, resulting in 404 errors.
-
-### Example
-
-```ruby
-# Before fix
-client.get_prompt("EXEMPLE/my-prompt")
-
-# Generated URL (broken):
-# /api/public/v2/prompts/EXEMPLE/my-prompt
-# Server interprets this as: /api/public/v2/prompts/EXEMPLE/<nested-path>/my-prompt
-# Result: 404 Not Found
-```
-
-### Expected Behavior
-
-```ruby
-# After fix
-client.get_prompt("EXEMPLE/my-prompt")
-
-# Generated URL (correct):
-# /api/public/v2/prompts/EXEMPLE%2Fmy-prompt
-# Server correctly interprets this as a single prompt name
-# Result: Prompt found successfully
-```
-
-## Solution
-
-### Changes Made
-
-1. **Added URL encoding utility** (`lib/langfuse/utils.rb`):
-   - Added `Utils.url_encode` method using Ruby's `ERB::Util.url_encode`
-   - Provides consistent URL encoding across the SDK
-
-2. **Updated `get_prompt` method** (`lib/langfuse/client.rb`):
-   - Automatically URL-encodes prompt names before constructing API paths
-   - No breaking changes - existing code continues to work
-
-3. **Added comprehensive tests** (`spec/langfuse/client_spec.rb`):
-   - Tests for forward slashes in prompt names
-   - Tests for spaces in prompt names
-   - Tests for multiple special characters
-   - Tests for simple names (no encoding needed)
-
-4. **Updated documentation**:
-   - Added note in README about automatic URL encoding
-   - Added example demonstrating the feature
-   - Updated CHANGELOG with fix details
-
-### Code Changes
-
-#### lib/langfuse/utils.rb
-```ruby
-def url_encode(string)
-  ERB::Util.url_encode(string.to_s)
-end
-```
-
-#### lib/langfuse/client.rb
-```ruby
-def get_prompt(name, version: nil, label: nil, cache_ttl_seconds: 60)
-  # ... existing code ...
-  
-  encoded_name = Utils.url_encode(name)
-  path = "/api/public/v2/prompts/#{encoded_name}"
-  
-  # ... rest of method ...
-end
-```
-
-## Testing
-
-### Test Coverage
-
-All test cases pass successfully:
-
-```bash
-$ bundle exec rspec spec/langfuse/client_spec.rb -e "get_prompt"
-
-Langfuse::Client
-  #get_prompt
-    URL-encodes prompt names with special characters ✓
-    URL-encodes prompt names with spaces ✓
-    URL-encodes prompt names with multiple special characters ✓
-    handles simple prompt names without special characters ✓
-
-4 examples, 0 failures
-```
-
-### Test Cases
-
-1. **Forward slash**: `EXEMPLE/my-prompt` → `EXEMPLE%2Fmy-prompt`
-2. **Spaces**: `my prompt` → `my%20prompt`
-3. **Multiple special chars**: `test/prompt name?query` → `test%2Fprompt%20name%3Fquery`
-4. **Simple names**: `simple-prompt` → `simple-prompt` (no encoding needed)
-
-## Usage
-
-### Before Fix (Workaround)
-
-Users had to manually encode prompt names:
-
-```ruby
-encoded_name = ERB::Util.url_encode("EXEMPLE/my-prompt")
-client.get_prompt(encoded_name)
-```
-
-### After Fix (Automatic)
-
-Users can now use prompt names directly:
-
-```ruby
-# Works automatically!
-client.get_prompt("EXEMPLE/my-prompt")
-client.get_prompt("my prompt name")
-client.get_prompt("test/prompt?query")
-```
-
-## Backward Compatibility
-
-This fix is **100% backward compatible**:
-
-- Existing code continues to work without changes
-- Simple prompt names (without special characters) work exactly as before
-- If users were manually encoding names, double-encoding is prevented by the URL encoding algorithm
-
-## Special Characters Supported
-
-The following special characters are now properly encoded:
-
-- `/` (forward slash) → `%2F`
-- ` ` (space) → `%20`
-- `?` (question mark) → `%3F`
-- `#` (hash) → `%23`
-- `@` (at sign) → `%40`
-- `&` (ampersand) → `%26`
-- `=` (equals) → `%3D`
-- `+` (plus) → `%2B`
-- And all other URL-unsafe characters
-
-## Related Files
-
-- `lib/langfuse/utils.rb` - URL encoding utility
-- `lib/langfuse/client.rb` - Updated `get_prompt` method
-- `spec/langfuse/client_spec.rb` - Test coverage
-- `examples/url_encoding_demo.rb` - Usage examples
-- `CHANGELOG.md` - Change documentation
-- `README.md` - Updated documentation
-
-## References
-
-- Linear Issue: AIF-2
-- Ruby ERB::Util documentation: https://ruby-doc.org/stdlib-3.0.0/libdoc/erb/rdoc/ERB/Util.html
-- URL encoding standard: RFC 3986