langfuse-ruby 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bb59924d3a9dcb1cb99841c6d07dd1277838ffee389d13ada1c8b03cafeb524
-  data.tar.gz: c5ba1846cd51fc3dc82fb43dd335d88394549652531a5243101ccd43ef71b3fa
+  metadata.gz: 0e15fd7f7f4e2e8b1a8018f27de35f42a3124973c8a455b50781a0d08924aa3d
+  data.tar.gz: 91253f7addf89cef33fcf047376f8667fae8e2e9d75f096b4096d4c876d06b20
 SHA512:
-  metadata.gz: 9e448848c65cb8cd6f7ab7e4e566787bcab4aa8c43f20da7cc7a7a39e24e888c734c23644682f080635a0288b40fc4e3e169d8576445fdd07dde8d676faaccca
-  data.tar.gz: 9d9d1e88bf2e1161bd1d7f316e17600904169344b679839992a227eb35ac48e7edbe188ce782e3757f9f03a8a39104eac8c171a23f7bdc0c54b707754dfd87e8
+  metadata.gz: 62d8773683844ecc44a1d258765f0522f77e83b02cbb7b7441d892e3e6a9252348f8ccfd331e185186b46aa9fb30203146e7beffd29a1330b5ab14ff75862a47
+  data.tar.gz: 23e33a0b7d7b8b25c07e9663cf320771a6db8160fb18302179acc8aeaaf99c1740add31c84448106df46efe22e89b2c36ce7bae6b66e600e525226854a2003d7

data/.github/workflows/ci.yml

@@ -2,33 +2,33 @@ name: CI
 
 on:
   push:
-    branches: [ main, master ]
+    branches: [ master ]
   pull_request:
-    branches: [ main, master ]
+    branches: [ master ]
 
 jobs:
   test:
     runs-on: ubuntu-latest
-    
+
     strategy:
       matrix:
-        ruby-version: ['2.7', '3.0', '3.1', '3.2', '3.3']
-    
+        ruby-version: ['3.1', '3.2', '3.3', '3.4']
+
     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
-    
+      run: bundle exec ruby scripts/test_offline.rb
+
     - name: Run RuboCop
       run: bundle exec rubocop
       continue-on-error: true
@@ -43,7 +43,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.2'
+        ruby-version: '3.4'
         bundler-cache: true
     
     - name: Build gem

data/.github/workflows/release.yml

@@ -16,17 +16,17 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.2'
+        ruby-version: '3.4'
         bundler-cache: true
     
     - name: Run tests
       run: bundle exec rspec
     
     - name: Run offline tests
-      run: ruby test_offline.rb
+      run: bundle exec ruby scripts/test_offline.rb
     
     - name: Build gem
-      run: gem build langfuse.gemspec
+      run: gem build langfuse-ruby.gemspec
     
     - name: Publish to RubyGems
       run: |
@@ -38,14 +38,13 @@ jobs:
         RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
     
     - name: Create GitHub Release
-      uses: actions/create-release@v1
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      uses: softprops/action-gh-release@v2
       with:
-        tag_name: ${{ github.ref }}
-        release_name: Release ${{ github.ref }}
+        files: "*.gem"
         body: |
           Changes in this Release
           - Check CHANGELOG.md for details
         draft: false
-        prerelease: false 
+        prerelease: false
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.rubocop.yml

@@ -0,0 +1,66 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  Exclude:
+    - 'bin/*'
+    - 'vendor/**/*'
+    - 'spec/fixtures/**/*'
+    - 'scripts/**/*'
+    - 'examples/**/*'
+    - 'langfuse-ruby.gemspec'
+    - 'Gemfile'
+    - 'Rakefile'
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'langfuse-ruby.gemspec'
+
+Metrics/MethodLength:
+  Max: 50
+  Exclude:
+    - 'scripts/**/*'
+
+Metrics/AbcSize:
+  Max: 50
+  Exclude:
+    - 'scripts/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Style/AsciiComments:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  Exclude:
+    - 'lib/langfuse/evaluation.rb'
+
+Metrics/ClassLength:
+  Max: 600

data/CHANGELOG.md

@@ -7,10 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Simplified API**: New class-level convenience methods for easier usage
+  - `Langfuse.trace(name, **options, &block)` - Block-based tracing with automatic flush
+  - `Langfuse.get_prompt(name, variables:, retries:)` - Get and compile prompts with retry support
+  - `Langfuse.client` - Thread-safe singleton client access
+  - `Langfuse.flush` / `Langfuse.shutdown` / `Langfuse.reset!` - Client lifecycle management
+- **Graceful Degradation**: Null object pattern for fault tolerance
+  - `NullTrace`, `NullGeneration`, `NullSpan`, `NullEvent` - No-op objects when Langfuse is unavailable
+- **Retry Support**: `get_prompt` now supports configurable retries with exponential backoff (default: 2 retries)
+- New example file `examples/simplified_usage.rb` demonstrating the simplified API
+- Comprehensive test coverage for convenience methods (28 new tests)
+
+## [0.1.5] - 2025-12-26
+
+### Added
+- Support for all enhanced observation types: `agent`, `tool`, `chain`, `retriever`, `embedding`, `evaluator`, `guardrail`
+- New `ObservationType` module with constants for all observation types
+- Convenience methods on `Client` and `Trace` for creating enhanced observations
+- New `as_type` parameter on `span()` method for specifying observation type
+- Comprehensive test coverage for enhanced observation types
+
+### Fixed
+- Fixed URL encoding for prompt names containing special characters (/, spaces, etc.) in `get_prompt` method
+- Prompt names are now automatically URL-encoded before being interpolated into API paths
+
+### Changed
+- Updated Ruby version requirement to >= 3.1.0
+- Environment variables moved from metadata to top-level trace attributes
+
+### Internal
+- Added `Utils.url_encode` helper method for consistent URL encoding across the SDK
+- CI improvements for offline test execution
+
 ## [0.1.4] - 2025-07-29
 
 ### Added
-- Added support for `trace-update` event type in Langfuse ingestion API
+- Added support for `trace` event type in Langfuse ingestion API
 - Added support for `event-create` event type in Langfuse ingestion API
 - New `Event` class for creating generic events within traces, spans, and generations
 - Added `event()` method to `Client`, `Trace`, `Span`, and `Generation` classes

data/CLAUDE.md

@@ -0,0 +1,100 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the official Ruby SDK for [Langfuse](https://langfuse.com) - an open-source LLM engineering platform. The SDK provides tracing, prompt management, and evaluation capabilities for LLM applications.
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all RSpec tests
+bundle exec rake spec
+
+# Run a single test file
+bundle exec rspec spec/langfuse/client_spec.rb
+
+# Run offline tests (no network required)
+bundle exec rake test_offline
+
+# Run all tests (spec + offline)
+bundle exec rake test_all
+
+# Lint code
+bundle exec rubocop
+
+# Build the gem
+bundle exec rake build
+
+# Release to RubyGems
+bundle exec rake release_gem
+```
+
+## Architecture
+
+### Core Classes
+
+- **`Langfuse`** ([lib/langfuse.rb](lib/langfuse.rb)) - Module with class-level convenience methods (`trace`, `get_prompt`, `client`, `flush`, `shutdown`, `reset!`)
+- **`Langfuse::Client`** ([lib/langfuse/client.rb](lib/langfuse/client.rb)) - Main entry point. Handles API authentication, HTTP connections (via Faraday), event queuing, and background flush thread for auto-batching events.
+- **`Langfuse::Trace`** ([lib/langfuse/trace.rb](lib/langfuse/trace.rb)) - Top-level container for a request/session.
+- **`Langfuse::Span`** ([lib/langfuse/span.rb](lib/langfuse/span.rb)) - Timed operation with enhanced type support.
+- **`Langfuse::Generation`** ([lib/langfuse/generation.rb](lib/langfuse/generation.rb)) - LLM call tracking.
+- **`Langfuse::Event`** ([lib/langfuse/event.rb](lib/langfuse/event.rb)) - Point-in-time events.
+- **`Langfuse::Prompt`** ([lib/langfuse/prompt.rb](lib/langfuse/prompt.rb)) - Prompt templates with caching.
+- **`Langfuse::NullTrace/NullGeneration/NullSpan`** ([lib/langfuse/null_objects.rb](lib/langfuse/null_objects.rb)) - Null objects for graceful degradation.
+
+### Simplified API (Recommended)
+
+```ruby
+# Block-based tracing with automatic flush
+Langfuse.trace("my-trace", user_id: "user-1") do |trace|
+  gen = trace.generation(name: "openai", model: "gpt-4", input: messages)
+  response = call_llm(...)
+  gen.end(output: response, usage: usage)
+end  # Auto flush!
+
+# Get prompt with variables and retry
+Langfuse.get_prompt("my-prompt", variables: { name: "Alice" }, retries: 3)
+```
+
+### Event Flow
+
+1. Observations (traces, spans, generations, events) are created via Client methods
+2. Events are queued in `@event_queue` (thread-safe `Concurrent::Array`)
+3. Background flush thread sends batched events to `/api/public/ingestion` endpoint
+4. Manual flush available via `client.flush`; graceful shutdown via `client.shutdown`
+
+### Observation Types
+
+The SDK supports enhanced observation types defined in `ObservationType` module:
+- Core: `span`, `generation`, `event`
+- Enhanced: `agent`, `tool`, `chain`, `retriever`, `embedding`, `evaluator`, `guardrail`
+
+Enhanced types are implemented as spans with `as_type` metadata sent to the API.
+
+### Configuration
+
+Client accepts config via:
+1. Constructor parameters
+2. `Langfuse.configure` block
+3. Environment variables: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_HOST`, `LANGFUSE_FLUSH_INTERVAL`, `LANGFUSE_AUTO_FLUSH`
+
+### Error Handling
+
+Custom exceptions in [lib/langfuse/errors.rb](lib/langfuse/errors.rb):
+- `AuthenticationError`, `APIError`, `NetworkError`, `ValidationError`, `RateLimitError`, `TimeoutError`
+
+Graceful degradation: When Langfuse is unavailable, `Langfuse.trace` yields a `NullTrace` that silently no-ops all operations.
+
+## Key Implementation Details
+
+- Uses Faraday for HTTP with Basic Auth (public_key:secret_key)
+- Prompt names with special characters are auto-URL-encoded via `Utils.url_encode`
+- `trace-update` events merge into existing `trace-create` in queue (deduplication)
+- All keys are converted to camelCase before API submission via `Utils.deep_camelize_keys`
+- Thread-safe singleton client via `Thread.current[:langfuse_client]`
+- `get_prompt` supports configurable retries with exponential backoff

data/Gemfile

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

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    langfuse-ruby (0.1.4)
+    langfuse-ruby (0.1.6)
       concurrent-ruby (~> 1.0)
       faraday (>= 1.8, < 3.0)
+      faraday-multipart (~> 1.0)
       faraday-net_http (>= 1.0, < 4.0)
       json (~> 2.0)
 
@@ -24,6 +25,8 @@ GEM
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
+    faraday-multipart (1.1.1)
+      multipart-post (~> 2.0)
     faraday-net_http (3.4.1)
       net-http (>= 0.5.0)
     hashdiff (1.2.0)
@@ -31,6 +34,7 @@ GEM
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
+    multipart-post (2.4.1)
     net-http (0.6.0)
       uri
     parallel (1.27.0)
@@ -85,7 +89,7 @@ GEM
     yard (0.9.37)
 
 PLATFORMS
-  arm64-darwin-23
+  arm64-darwin
   ruby
 
 DEPENDENCIES
@@ -93,7 +97,7 @@ DEPENDENCIES
   langfuse-ruby!
   rake (~> 13.0)
   rspec (~> 3.0)
-  rubocop (~> 1.21)
+  rubocop (~> 1.0)
   vcr (~> 6.0)
   webmock (~> 3.0)
   yard (~> 0.9)

data/Makefile

@@ -0,0 +1,73 @@
+.PHONY: install test spec test-offline test-all lint lint-fix build release clean console help tag
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install dependencies
+	bundle install
+
+spec: ## Run RSpec tests
+	bundle exec rake spec
+
+test-offline: ## Run offline tests (no network required)
+	bundle exec rake test_offline
+
+test-all: ## Run all tests (spec + offline)
+	bundle exec rake test_all
+
+test: spec ## Alias for spec
+
+lint: ## Run RuboCop linter
+	bundle exec rubocop
+
+lint-fix: ## Run RuboCop with auto-correct
+	bundle exec rubocop -A
+
+build: ## Build the gem
+	bundle exec rake build
+
+release: tag build ## Release: tag + build + push to RubyGems
+	bundle exec rake release_gem
+
+clean: ## Remove built gem files
+	rm -f langfuse-ruby-*.gem
+	rm -rf pkg/
+
+console: ## Start an IRB console with the gem loaded
+	bundle exec irb -r langfuse
+
+tag: ## Create and push a version tag. Usage: make tag [VERSION=x.y.z]
+	@git fetch --tags; \
+	if [ -z "$(VERSION)" ]; then \
+		LATEST=$$(git tag -l 'v*' --sort=-v:refname | head -n1); \
+		if [ -z "$$LATEST" ]; then \
+			NEW_TAG="v0.0.1"; \
+		else \
+			MAJOR=$$(echo $$LATEST | sed 's/^v//' | cut -d. -f1); \
+			MINOR=$$(echo $$LATEST | sed 's/^v//' | cut -d. -f2); \
+			PATCH=$$(echo $$LATEST | sed 's/^v//' | cut -d. -f3); \
+			PATCH=$$((PATCH + 1)); \
+			NEW_TAG="v$$MAJOR.$$MINOR.$$PATCH"; \
+		fi; \
+	else \
+		NEW_TAG="v$(VERSION)"; \
+		LATEST=$$(git tag -l 'v*' --sort=-v:refname | head -n1); \
+		if [ "$$LATEST" = "$$NEW_TAG" ]; then \
+			echo "Tag $$NEW_TAG already exists on remote, deleting and re-pushing..."; \
+			git tag -d "$$NEW_TAG" 2>/dev/null || true; \
+			git push origin --delete "$$NEW_TAG" 2>/dev/null || true; \
+		elif git tag -l "$$NEW_TAG" | grep -q "$$NEW_TAG"; then \
+			echo "Error: Tag $$NEW_TAG exists but is not the latest tag (latest: $$LATEST). Aborting."; \
+			exit 1; \
+		fi; \
+	fi; \
+	NEW_VERSION=$$(echo $$NEW_TAG | sed 's/^v//'); \
+	echo "Updating version to $$NEW_VERSION ..."; \
+	sed -i '' "s/VERSION = '.*'/VERSION = '$$NEW_VERSION'/" lib/langfuse/version.rb; \
+	git add lib/langfuse/version.rb; \
+	git commit -m "Release $$NEW_TAG" --allow-empty; \
+	git tag "$$NEW_TAG"; \
+	echo "Pushing tag $$NEW_TAG ..."; \
+	git push origin HEAD; \
+	git push origin "$$NEW_TAG"; \
+	echo "Done! Tagged and pushed $$NEW_TAG"

data/README.md

@@ -1,9 +1,6 @@
 # Langfuse Ruby SDK
 
-[![Gem Version](https://badge.fury.io/rb/langfuse-ruby.svg)](https://badge.fury.io/rb/langfuse-ruby)
-[![CI](https://github.com/ai-firstly/langfuse-ruby/workflows/CI/badge.svg)](https://github.com/ai-firstly/langfuse-ruby/actions/workflows/ci.yml)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7.0-red.svg)](https://www.ruby-lang.org/)
-[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Gem Version](https://badge.fury.io/rb/langfuse-ruby.svg)](https://badge.fury.io/rb/langfuse-ruby) [![CI](https://github.com/ai-firstly/langfuse-ruby/workflows/CI/badge.svg)](https://github.com/ai-firstly/langfuse-ruby/actions/workflows/ci.yml) [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1.0-red.svg)](https://www.ruby-lang.org/) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 Ruby SDK for [Langfuse](https://langfuse.com) - the open-source LLM engineering platform. This SDK provides comprehensive tracing, prompt management, and evaluation capabilities for LLM applications.
 
@@ -69,7 +66,7 @@ trace = client.trace(
   name: "chat-completion",
   user_id: "user123",
   session_id: "session456",
-  metadata: { environment: "production" }
+  environment: "production"
 )
 
 # Add a generation (LLM call)
@@ -88,6 +85,80 @@ trace.update(output: 'Hello! How can I help you today?')
 client.flush
 ```
 
+## Simplified Usage (Recommended)
+
+For most use cases, you can use the simplified class-level API with automatic flush:
+
+### Block-based Tracing
+
+```ruby
+require 'langfuse'
+
+# Configure once
+Langfuse.configure do |config|
+  config.public_key = ENV['LANGFUSE_PUBLIC_KEY']
+  config.secret_key = ENV['LANGFUSE_SECRET_KEY']
+end
+
+# Use block-based tracing - flush happens automatically!
+Langfuse.trace("my-trace", user_id: "user-1", input: { message: "Hello" }) do |trace|
+  generation = trace.generation(
+    name: "openai-chat",
+    model: "gpt-4",
+    input: [{ role: "user", content: "Hello" }],
+    model_parameters: { temperature: 0.7 }
+  )
+
+  # Call your LLM
+  response = call_openai(...)
+
+  # Record the response
+  generation.end(output: response.content, usage: response.usage)
+  trace.update(output: response.content)
+end  # Automatic flush here!
+```
+
+### Get Prompts with Variables
+
+```ruby
+# Get and compile a prompt in one call
+prompt = Langfuse.get_prompt("greeting-prompt", variables: { name: "Alice" })
+# => "Hello Alice! How can I help you today?"
+
+# Get prompt without compilation
+prompt_obj = Langfuse.get_prompt("greeting-prompt")
+compiled = prompt_obj.compile(name: "Bob")
+```
+
+### Graceful Degradation
+
+The simplified API includes null objects that ensure your code continues working even if Langfuse is unavailable:
+
+```ruby
+# If Langfuse fails, a NullTrace is used - your code still runs
+Langfuse.trace("my-trace") do |trace|
+  # This works even if Langfuse is down
+  gen = trace.generation(name: "test", model: "gpt-4", input: "hello")
+  gen.end(output: "world")
+end
+```
+
+### Other Class Methods
+
+```ruby
+# Get the thread-safe singleton client
+client = Langfuse.client
+
+# Manual flush (when not using block-based tracing)
+Langfuse.flush
+
+# Shutdown the client
+Langfuse.shutdown
+
+# Reset the singleton (useful for testing)
+Langfuse.reset!
+```
+
 ### 3. Nested Spans
 
 ```ruby
@@ -173,6 +244,9 @@ event = client.event(
 # Get a prompt
 prompt = client.get_prompt("chat-prompt", version: 1)
 
+# Prompt names with special characters are automatically URL-encoded
+prompt = client.get_prompt("EXEMPLE/my-prompt")  # Works correctly!
+
 # Compile prompt with variables
 compiled = prompt.compile(
   user_name: "Alice",
@@ -183,6 +257,8 @@ puts compiled
 # Output: "Hello Alice! Let's discuss machine learning today."
 ```
 
+> **Note**: Prompt names containing special characters (like `/`, spaces, `?`, etc.) are automatically URL-encoded. You don't need to manually encode them.
+
 ### Create Prompts
 
 ```ruby
@@ -493,6 +569,14 @@ Check out the `examples/` directory for more comprehensive examples:
 - [Evaluation Pipeline](examples/evaluation_pipeline.rb)
 - [Rails Integration](examples/rails_integration.rb)
 
+## Documentation
+
+For more detailed information, please refer to the [documentation](docs/README.md).
+
+- [Publishing Guide](docs/PUBLISH_GUIDE.md)
+- [Release Checklist](docs/RELEASE_CHECKLIST.md)
+- [Examples](examples/)
+
 ## Development
 
 After checking out the repo, run:
@@ -525,7 +609,6 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Links
 
-- [Langfuse Documentation](https://langfuse.com/docs)
-- [Langfuse GitHub](https://github.com/langfuse/langfuse)
-- [API Reference](https://api.reference.langfuse.com)
-- [Ruby SDK Documentation](https://rubydoc.info/gems/langfuse-ruby) 
+- [Langfuse Ruby SDK Documentation](https://rubydoc.info/gems/langfuse-ruby)
+- [RubyGems](https://rubygems.org/gems/langfuse-ruby)
+- [Langfuse Documentation](https://langfuse.com/docs) 

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require_relative 'lib/langfuse/version'
@@ -9,13 +11,13 @@ task default: :spec
 # Custom release task
 desc 'Release gem to RubyGems'
 task release_gem: [:build] do
-  sh "gem push pkg/langfuse-ruby-#{Langfuse::VERSION}.gem"
+  sh "gem push langfuse-ruby-#{Langfuse::VERSION}.gem"
 end
 
 # Offline test task
 desc 'Run offline tests'
 task :test_offline do
-  sh 'ruby test_offline.rb'
+  sh 'ruby scripts/test_offline.rb'
 end
 
 # Complete test suite

data/docs/FINAL_SUMMARY.md

@@ -8,15 +8,16 @@
 
 ### 核心功能
 - ✅ **完整的追踪系统** - traces, spans, generations
-- ✅ **提示管理** - 版本控制、缓存、变量编译
+- ✅ **简化 API** - 类级别方法，block-based tracing，自动 flush
+- ✅ **提示管理** - 版本控制、缓存、变量编译、重试支持
 - ✅ **评估系统** - 6种内置评估器 + 自定义评分
+- ✅ **优雅降级** - NullTrace/NullGeneration 空对象模式
 - ✅ **客户端管理** - HTTP客户端、认证、重试机制
 - ✅ **异步处理** - 事件队列、后台线程
 - ✅ **错误处理** - 完整的错误分类和处理
-- ✅ **工具类** - ID生成、时间戳、数据转换
 
 ### 技术规格
-- **Ruby版本**: >= 2.7.0
+- **Ruby版本**: >= 3.1.0
 - **依赖项**: Faraday, concurrent-ruby, json
 - **测试**: RSpec + 离线测试 (23个测试全部通过)
 - **文档**: 完整的README、API文档、示例代码
@@ -83,7 +84,7 @@ vim langfuse.gemspec
 # 初始化 Git 仓库
 git init
 git add .
-git commit -m "Initial commit: Langfuse Ruby SDK v0.1.0"
+git commit -m "Initial commit: Langfuse Ruby SDK v#{Langfuse::VERSION}"
 
 # 创建 GitHub 仓库并推送
 git remote add origin https://github.com/您的用户名/langfuse-ruby.git
@@ -97,16 +98,16 @@ git push -u origin main
 
 # 方法 2: 手动发布
 gem build langfuse.gemspec
-gem push langfuse-0.1.0.gem
+gem push langfuse-ruby-#{Langfuse::VERSION}.gem
 ```
 
 ### 3. 验证发布
 ```bash
 # 运行验证脚本
-ruby scripts/verify_release.rb
+ruby scripts/test_offline.rb
 
 # 手动验证
-gem install langfuse  # 或您的 gem 名称
+gem install langfuse-ruby
 ruby -e "require 'langfuse'; puts Langfuse::VERSION"
 ```
 
@@ -120,9 +121,9 @@ ruby -e "require 'langfuse'; puts Langfuse::VERSION"
 - **文档文件**: 5个
 
 ### 测试覆盖率
-- **RSpec 测试**: 12个 (100% 通过)
-- **离线测试**: 11个 (100% 通过)
-- **总测试数**: 23个 (100% 通过)
+- **RSpec 测试**: 84个 (100% 通过)
+- **新增测试**: 28个 (简化 API + 空对象)
+- **总测试数**: 84个 (100% 通过)
 
 ### 功能完整性
 - **与 Python SDK 对比**: 100% 功能对等