RubyGems - langfuse-ruby - Versions diffs - 0.1.1 → 0.1.3 - Mend

langfuse-ruby 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +59 -0
data/Gemfile +5 -5
data/Gemfile.lock +1 -1
data/README.md +111 -20
data/docs/PUBLISH_GUIDE.md +2 -2
data/docs/README.md +0 -4
data/docs/TYPE_VALIDATION_TROUBLESHOOTING.md +202 -0
data/examples/auto_flush_control.rb +205 -0
data/examples/basic_tracing.rb +0 -12
data/examples/connection_config_demo.rb +141 -0
data/examples/event_usage.rb +145 -0
data/examples/prompt_management.rb +62 -71
data/lib/langfuse/client.rb +176 -58
data/lib/langfuse/event.rb +63 -0
data/lib/langfuse/generation.rb +19 -40
data/lib/langfuse/span.rb +17 -0
data/lib/langfuse/trace.rb +17 -34
data/lib/langfuse/utils.rb +23 -1
data/lib/langfuse/version.rb +1 -1
data/lib/langfuse.rb +5 -2
data/test_offline.rb +93 -101
metadata +8 -7
data/.github/workflows/ci.yml +0 -47
data/PROMPT_TROUBLESHOOTING.md +0 -206
data/docs/CHANGELOG.md +0 -49
data/docs/PROJECT_SUMMARY.md +0 -263
data/test_basic.rb +0 -183

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Richard Sun
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-12 00:00:00.000000000 Z
+date: 2025-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -172,28 +172,30 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 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
+- docs/TYPE_VALIDATION_TROUBLESHOOTING.md
+- examples/auto_flush_control.rb
 - examples/basic_tracing.rb
+- examples/connection_config_demo.rb
+- examples/event_usage.rb
 - examples/prompt_management.rb
 - langfuse-ruby.gemspec
 - lib/langfuse.rb
 - lib/langfuse/client.rb
 - lib/langfuse/errors.rb
 - lib/langfuse/evaluation.rb
+- lib/langfuse/event.rb
 - lib/langfuse/generation.rb
 - lib/langfuse/prompt.rb
 - lib/langfuse/span.rb
@@ -202,7 +204,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/.github/workflows/ci.yml DELETED Viewed

@@ -1,47 +0,0 @@
-name: CI
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        ruby-version: ['2.7', '3.0', '3.1', '3.2']
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby ${{ matrix.ruby-version }}
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true
-    - name: Run tests
-      run: bundle exec rspec
-    - name: Run offline tests
-      run: ruby test_offline.rb
-    - name: Check gem build
-      run: gem build langfuse.gemspec
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: '3.2'
-        bundler-cache: true
-    - name: Run RuboCop
-      run: bundle exec rubocop
-      continue-on-error: true

data/PROMPT_TROUBLESHOOTING.md DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 社区的最佳实践。