langfuse-ruby 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af3d00eedfb953a5bdc8f1a99d272debe050ed43cf160329c907cd209b28e042
-  data.tar.gz: 3a4c6ac469fa7874c0e310b059029bcaa879e6f048abfd902097dfde1d7ed3fe
+  metadata.gz: 35c5fecfa9511702e3119b58f09de37402f8fdefa118a8f848b4e64a439a383c
+  data.tar.gz: 0057c42d68a7f170f5118efc9378b751d627ef51a11fc87ec965d60be049645b
 SHA512:
-  metadata.gz: 2b74bc9c6d80fe4f09c20f38345bb0244b801acc07b770674b85778c21ad0b66b0fabe07206071c52f8780531dce49799b6db8d67b1cee662432ab8f5ae81258
-  data.tar.gz: 9901d034719eab0f2c082962cf36396591db46b33f54665c3dcb9cfdd9f22c8f96ba1b71b7296d4131e20a43355e57375e70020d734a43f810d05a802e207e3f
+  metadata.gz: ee91c309e962d21351e33a3683602b873d167038d90488e0460677959d7c32ad3f715bd77672d3fd6f7f0e21601370fc75fbd6aa2562add32e54b7ae14e79912
+  data.tar.gz: f336046b47e535cf36c0f562bb012e419801300aff98acc49e9ee13aebb037d65785c21491a41f6f0cc3cda92ba839bebfa9cbf248e83fa4451939573ca139ec

data/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        ruby-version: ['3.1', '3.2', '3.3']
+
+    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: bundle exec ruby test_offline.rb
+
+    - name: Run RuboCop
+      run: bundle exec rubocop
+      continue-on-error: true
+  
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.2'
+        bundler-cache: true
+    
+    - name: Build gem
+      run: gem build langfuse-ruby.gemspec
+    
+    - name: Verify gem can be installed
+      run: gem install langfuse-ruby-*.gem 

data/CHANGELOG.md

@@ -7,20 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 `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
 - Enhanced event validation to include all supported Langfuse event types
 - New example file `examples/event_usage.rb` demonstrating event functionality
 
-## [0.1.2] - 2025-01-13
+### Fixed
+- Improved offline test error handling and authentication validation
+- Enhanced error handling tests with proper configuration management
+- Fixed prompt template validation tests in offline mode
+- Better error message handling for authentication failures
 
-### Added
+### Improved
+- More comprehensive error handling test coverage
+- Better test isolation and cleanup procedures
+- Enhanced debugging capabilities for offline testing
+
+## [0.1.3] - 2025-07-13
+
+### Fixed
+- Enhanced event data validation and debugging capabilities
+- More detailed error messages for event structure validation failures
+
+## [0.1.2] - 2025-07-12
+
+### Fixed
 - Enhanced event data validation and debugging capabilities
 - More detailed error messages for event structure validation failures
 
-## [0.1.1] - 2025-01-12
+## [0.1.1] - 2025-07-12
 
 ### Fixed
 - Improved error handling for `get_prompt` method when prompt doesn't exist
@@ -36,7 +77,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated gemspec metadata to avoid RubyGems warnings
 - Improved documentation with clearer error handling examples
 
-## [0.1.0] - 2025-01-12
+## [0.1.0] - 2025-07-12
 
 ### Added
 - Initial release of Langfuse Ruby SDK

data/Gemfile.lock

@@ -1,10 +1,11 @@
 PATH
   remote: .
   specs:
-    langfuse-ruby (0.1.3)
+    langfuse-ruby (0.1.5)
       concurrent-ruby (~> 1.0)
-      faraday (~> 2.0)
-      faraday-net_http (~> 3.0)
+      faraday (>= 1.8, < 3.0)
+      faraday-multipart (~> 1.0)
+      faraday-net_http (>= 1.0, < 4.0)
       json (~> 2.0)
 
 GEM
@@ -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)

data/README.md

@@ -1,7 +1,9 @@
 # Langfuse Ruby SDK
 
 [![Gem Version](https://badge.fury.io/rb/langfuse-ruby.svg)](https://badge.fury.io/rb/langfuse-ruby)
-[![Build Status](https://github.com/ai-firstly/langfuse-ruby/workflows/CI/badge.svg)](https://github.com/ai-firstly/langfuse-ruby/actions)
+[![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)
 
 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.
 
@@ -67,7 +69,7 @@ trace = client.trace(
   name: "chat-completion",
   user_id: "user123",
   session_id: "session456",
-  metadata: { environment: "production" }
+  environment: "production"
 )
 
 # Add a generation (LLM call)
@@ -80,6 +82,8 @@ generation = trace.generation(
 
 generation.end(output: 'Hello! How can I help you today?', usage: { prompt_tokens: 10, completion_tokens: 15, total_tokens: 25 })
 
+trace.update(output: 'Hello! How can I help you today?')
+
 # Flush events (optional - happens automatically)
 client.flush
 ```
@@ -169,6 +173,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",
@@ -179,6 +186,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

data/docs/URL_ENCODING_FIX.md

@@ -0,0 +1,164 @@
+# 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

data/examples/basic_tracing.rb

@@ -19,8 +19,8 @@ trace = client.trace(
   user_id: 'user-123',
   session_id: 'session-456',
   input: { message: 'Hello, how are you?' },
+  environment: 'development',
   metadata: {
-    environment: 'development',
     version: '1.0.0'
   }
 )

data/examples/url_encoding_demo.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# This example demonstrates URL encoding for prompt names with special characters
+# such as forward slashes, spaces, and other URL-unsafe characters.
+
+require_relative '../lib/langfuse'
+
+# Initialize the Langfuse client
+client = Langfuse::Client.new(
+  public_key: ENV['LANGFUSE_PUBLIC_KEY'] || 'your-public-key',
+  secret_key: ENV['LANGFUSE_SECRET_KEY'] || 'your-secret-key',
+  host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+)
+
+# Example 1: Prompt name with forward slash
+# Before fix: Would result in 404 error
+# After fix: Automatically URL-encoded to EXEMPLE%2Fmy-prompt
+puts 'Example 1: Fetching prompt with forward slash in name'
+begin
+  prompt = client.get_prompt('EXEMPLE/my-prompt')
+  puts "✓ Successfully fetched prompt: #{prompt.name}"
+rescue Langfuse::ValidationError => e
+  puts "✗ Error: #{e.message}"
+end
+
+# Example 2: Prompt name with spaces
+puts "\nExample 2: Fetching prompt with spaces in name"
+begin
+  prompt = client.get_prompt('my prompt name')
+  puts "✓ Successfully fetched prompt: #{prompt.name}"
+rescue Langfuse::ValidationError => e
+  puts "✗ Error: #{e.message}"
+end
+
+# Example 3: Prompt name with multiple special characters
+puts "\nExample 3: Fetching prompt with multiple special characters"
+begin
+  prompt = client.get_prompt('test/prompt name?query')
+  puts "✓ Successfully fetched prompt: #{prompt.name}"
+rescue Langfuse::ValidationError => e
+  puts "✗ Error: #{e.message}"
+end
+
+# Example 4: Simple prompt name (no special characters)
+puts "\nExample 4: Fetching prompt with simple name"
+begin
+  prompt = client.get_prompt('simple-prompt')
+  puts "✓ Successfully fetched prompt: #{prompt.name}"
+rescue Langfuse::ValidationError => e
+  puts "✗ Error: #{e.message}"
+end
+
+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

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
                        'and evaluation capabilities for LLM applications'
   spec.homepage      = 'https://langfuse.com'
   spec.license       = 'MIT'
-  spec.required_ruby_version = '>= 2.7.0'
+  spec.required_ruby_version = '>= 3.1.0'
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   spec.metadata['homepage_uri'] = 'https://langfuse.com/docs/sdk/ruby'
@@ -24,7 +24,9 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     if File.exist?('.git')
-      `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+      `git ls-files -z`.split("\x0").reject do |f|
+        (f == 'ISSUE_AIF-2_RESOLUTION.md') || f.match(%r{\A(?:test|spec|features)/})
+      end
     else
       Dir.glob('**/*').reject do |f|
         File.directory?(f) ||
@@ -41,8 +43,9 @@ Gem::Specification.new do |spec|
 
   # Dependencies
   spec.add_dependency 'concurrent-ruby', '~> 1.0'
-  spec.add_dependency 'faraday', '~> 2.0'
-  spec.add_dependency 'faraday-net_http', '~> 3.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 'json', '~> 2.0'
 
   # Development dependencies