langfuse-ruby 0.1.3 → 0.1.5

data/lib/langfuse/span.rb

@@ -1,11 +1,12 @@
 module Langfuse
   class Span
     attr_reader :id, :trace_id, :name, :start_time, :end_time, :input, :output,
-                :metadata, :level, :status_message, :parent_observation_id, :version, :client
+                :metadata, :level, :status_message, :parent_observation_id, :version,
+                :as_type, :client
 
     def initialize(client:, trace_id:, id: nil, name: nil, start_time: nil, end_time: nil,
                    input: nil, output: nil, metadata: nil, level: nil, status_message: nil,
-                   parent_observation_id: nil, version: nil, **kwargs)
+                   parent_observation_id: nil, version: nil, as_type: nil, **kwargs)
       @client = client
       @id = id || Utils.generate_id
       @trace_id = trace_id
@@ -19,6 +20,7 @@ module Langfuse
       @status_message = status_message
       @parent_observation_id = parent_observation_id
       @version = version
+      @as_type = validate_as_type(as_type)
       @kwargs = kwargs
 
       # Create the span
@@ -50,8 +52,9 @@ module Langfuse
       self
     end
 
+    # Create a child span
     def span(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
-             metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
+             metadata: nil, level: nil, status_message: nil, version: nil, as_type: nil, **kwargs)
       @client.span(
         trace_id: @trace_id,
         name: name,
@@ -64,10 +67,12 @@ module Langfuse
         status_message: status_message,
         parent_observation_id: @id,
         version: version,
+        as_type: as_type,
         **kwargs
       )
     end
 
+    # Create a child generation
     def generation(name: nil, start_time: nil, end_time: nil, completion_start_time: nil,
                    model: nil, model_parameters: nil, input: nil, output: nil, usage: nil,
                    metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
@@ -91,6 +96,7 @@ module Langfuse
       )
     end
 
+    # Create a child event
     def event(name:, start_time: nil, input: nil, output: nil, metadata: nil,
               level: nil, status_message: nil, version: nil, **kwargs)
       @client.event(
@@ -108,6 +114,138 @@ module Langfuse
       )
     end
 
+    # Convenience methods for enhanced observation types
+
+    # Create a child agent observation
+    def agent(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+              metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        version: version,
+        as_type: ObservationType::AGENT,
+        **kwargs
+      )
+    end
+
+    # Create a child tool observation
+    def tool(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+             metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        version: version,
+        as_type: ObservationType::TOOL,
+        **kwargs
+      )
+    end
+
+    # Create a child chain observation
+    def chain(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+              metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        version: version,
+        as_type: ObservationType::CHAIN,
+        **kwargs
+      )
+    end
+
+    # Create a child retriever observation
+    def retriever(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+                  metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        version: version,
+        as_type: ObservationType::RETRIEVER,
+        **kwargs
+      )
+    end
+
+    # Create a child embedding observation
+    def embedding(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+                  model: nil, usage: nil, metadata: nil, level: nil, status_message: nil,
+                  version: nil, **kwargs)
+      merged_metadata = (metadata || {}).merge(
+        { model: model, usage: usage }.compact
+      )
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: merged_metadata.empty? ? nil : merged_metadata,
+        level: level,
+        status_message: status_message,
+        version: version,
+        as_type: ObservationType::EMBEDDING,
+        **kwargs
+      )
+    end
+
+    # Create a child evaluator observation
+    def evaluator(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+                  metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        version: version,
+        as_type: ObservationType::EVALUATOR,
+        **kwargs
+      )
+    end
+
+    # Create a child guardrail observation
+    def guardrail(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+                  metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        version: version,
+        as_type: ObservationType::GUARDRAIL,
+        **kwargs
+      )
+    end
+
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
         observation_id: @id,
@@ -124,7 +262,7 @@ module Langfuse
     end
 
     def to_dict
-      {
+      data = {
         id: @id,
         trace_id: @trace_id,
         name: @name,
@@ -137,11 +275,24 @@ module Langfuse
         status_message: @status_message,
         parent_observation_id: @parent_observation_id,
         version: @version
-      }.merge(@kwargs).compact
+      }
+      data[:type] = @as_type if @as_type
+      data.merge(@kwargs).compact
     end
 
     private
 
+    def validate_as_type(type)
+      return nil if type.nil?
+
+      type_str = type.to_s
+      unless ObservationType.valid?(type_str)
+        raise ValidationError, "Invalid observation type: #{type}. Valid types are: #{ObservationType::ALL.join(', ')}"
+      end
+
+      type_str
+    end
+
     def create_span
       data = {
         id: @id,
@@ -156,7 +307,9 @@ module Langfuse
         status_message: @status_message,
         parent_observation_id: @parent_observation_id,
         version: @version
-      }.merge(@kwargs).compact
+      }
+      data[:type] = @as_type if @as_type
+      data = data.merge(@kwargs).compact
 
       @client.enqueue_event('span-create', data)
     end
@@ -175,7 +328,9 @@ module Langfuse
         status_message: @status_message,
         parent_observation_id: @parent_observation_id,
         version: @version
-      }.merge(@kwargs).compact
+      }
+      data[:type] = @as_type if @as_type
+      data = data.merge(@kwargs).compact
 
       @client.enqueue_event('span-update', data)
     end

data/lib/langfuse/trace.rb

@@ -24,9 +24,10 @@ module Langfuse
       create_trace
     end
 
+    # Create a child span with optional type
     def span(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
              metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
-             version: nil, **kwargs)
+             version: nil, as_type: nil, **kwargs)
       @client.span(
         trace_id: @id,
         name: name,
@@ -39,10 +40,12 @@ module Langfuse
         status_message: status_message,
         parent_observation_id: parent_observation_id,
         version: version,
+        as_type: as_type,
         **kwargs
       )
     end
 
+    # Create a child generation
     def generation(name: nil, start_time: nil, end_time: nil, completion_start_time: nil,
                    model: nil, model_parameters: nil, input: nil, output: nil, usage: nil,
                    metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
@@ -67,6 +70,7 @@ module Langfuse
       )
     end
 
+    # Create a child event
     def event(name:, start_time: nil, input: nil, output: nil, metadata: nil,
               level: nil, status_message: nil, parent_observation_id: nil, version: nil, **kwargs)
       @client.event(
@@ -84,6 +88,151 @@ module Langfuse
       )
     end
 
+    # Convenience methods for enhanced observation types
+
+    # Create a child agent observation
+    def agent(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+              metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
+              version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: parent_observation_id,
+        version: version,
+        as_type: ObservationType::AGENT,
+        **kwargs
+      )
+    end
+
+    # Create a child tool observation
+    def tool(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+             metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
+             version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: parent_observation_id,
+        version: version,
+        as_type: ObservationType::TOOL,
+        **kwargs
+      )
+    end
+
+    # Create a child chain observation
+    def chain(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+              metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
+              version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: parent_observation_id,
+        version: version,
+        as_type: ObservationType::CHAIN,
+        **kwargs
+      )
+    end
+
+    # Create a child retriever observation
+    def retriever(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+                  metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
+                  version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: parent_observation_id,
+        version: version,
+        as_type: ObservationType::RETRIEVER,
+        **kwargs
+      )
+    end
+
+    # Create a child embedding observation
+    def embedding(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+                  model: nil, usage: nil, metadata: nil, level: nil, status_message: nil,
+                  parent_observation_id: nil, version: nil, **kwargs)
+      merged_metadata = (metadata || {}).merge(
+        { model: model, usage: usage }.compact
+      )
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: merged_metadata.empty? ? nil : merged_metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: parent_observation_id,
+        version: version,
+        as_type: ObservationType::EMBEDDING,
+        **kwargs
+      )
+    end
+
+    # Create a child evaluator observation
+    def evaluator(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+                  metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
+                  version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: parent_observation_id,
+        version: version,
+        as_type: ObservationType::EVALUATOR,
+        **kwargs
+      )
+    end
+
+    # Create a child guardrail observation
+    def guardrail(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
+                  metadata: nil, level: nil, status_message: nil, parent_observation_id: nil,
+                  version: nil, **kwargs)
+      span(
+        name: name,
+        start_time: start_time,
+        end_time: end_time,
+        input: input,
+        output: output,
+        metadata: metadata,
+        level: level,
+        status_message: status_message,
+        parent_observation_id: parent_observation_id,
+        version: version,
+        as_type: ObservationType::GUARDRAIL,
+        **kwargs
+      )
+    end
+
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
         trace_id: @id,
@@ -95,6 +244,23 @@ module Langfuse
       )
     end
 
+    def update(name: nil, user_id: nil, session_id: nil, version: nil,
+               release: nil, input: nil, output: nil, metadata: nil, tags: nil, **kwargs)
+      # 更新实例变量
+      @name = name if name
+      @user_id = user_id if user_id
+      @session_id = session_id if session_id
+      @version = version if version
+      @release = release if release
+      @input = input if input
+      @output = output if output
+      @metadata = metadata if metadata
+      @tags = tags if tags
+      @kwargs.merge!(kwargs) if kwargs.any?
+      # 触发 trace-update 事件
+      update_trace
+    end
+
     def get_url
       "#{@client.host}/trace/#{@id}"
     end
@@ -134,5 +300,23 @@ module Langfuse
 
       @client.enqueue_event('trace-create', data)
     end
+
+    def update_trace
+      data = {
+        id: @id,
+        name: @name,
+        user_id: @user_id,
+        session_id: @session_id,
+        version: @version,
+        release: @release,
+        input: @input,
+        output: @output,
+        metadata: @metadata,
+        tags: @tags,
+        timestamp: @timestamp
+      }.merge(@kwargs).compact
+
+      @client.enqueue_event('trace-update', data)
+    end
   end
 end

data/lib/langfuse/utils.rb

@@ -1,5 +1,6 @@
 require 'securerandom'
 require 'time'
+require 'erb'
 
 module Langfuse
   module Utils
@@ -12,6 +13,10 @@ module Langfuse
         Time.now.utc.iso8601(3)
       end
 
+      def url_encode(string)
+        ERB::Util.url_encode(string.to_s)
+      end
+
       def deep_symbolize_keys(hash)
         return hash unless hash.is_a?(Hash)
 

data/lib/langfuse/version.rb

@@ -1,3 +1,3 @@
 module Langfuse
-  VERSION = '0.1.3'
+  VERSION = "0.1.5"
 end

data/lib/langfuse.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'langfuse/version'
+require_relative 'langfuse/observation_types'
 require_relative 'langfuse/client'
 require_relative 'langfuse/trace'
 require_relative 'langfuse/span'

data/test_offline.rb

@@ -209,8 +209,8 @@ begin
     user_id: 'user-456',
     session_id: 'session-789',
     input: { query: 'Explain quantum computing' },
+    environment: 'test',
     metadata: {
-      environment: 'test',
       version: '1.0.0',
       tags: %w[physics computing]
     }
@@ -288,19 +288,45 @@ end
 # Test 11: Error handling
 puts "\n11. Testing error handling..."
 begin
-  # Test validation error
+  # Save current configuration
+  original_public_key = Langfuse.configuration.public_key
+  original_secret_key = Langfuse.configuration.secret_key
+
+  # Test authentication error - missing public key
   begin
-    Langfuse::Utils.validate_required_fields({ name: 'test' }, %i[name required_field])
-  rescue Langfuse::ValidationError => e
-    puts "✅ Validation error caught: #{e.message}"
+    Langfuse.configuration.public_key = nil
+    ENV.delete('LANGFUSE_PUBLIC_KEY')
+    Langfuse.new(public_key: nil, secret_key: 'secret')
+    puts '❌ Expected AuthenticationError but none was raised'
+  rescue Langfuse::AuthenticationError => e
+    puts "✅ Authentication error caught: #{e.message}"
+  ensure
+    Langfuse.configuration.public_key = original_public_key
   end
 
-  # Test authentication error
+  # Test authentication error - missing secret key
   begin
-    Langfuse.new(public_key: nil, secret_key: 'secret')
+    Langfuse.configuration.secret_key = nil
+    ENV.delete('LANGFUSE_SECRET_KEY')
+    Langfuse.new(public_key: 'public', secret_key: nil)
+    puts '❌ Expected AuthenticationError but none was raised'
   rescue Langfuse::AuthenticationError => e
     puts "✅ Authentication error caught: #{e.message}"
+  ensure
+    Langfuse.configuration.secret_key = original_secret_key
   end
+
+  # Test validation error through prompt template
+  begin
+    template = Langfuse::PromptTemplate.from_template('Hello {{name}}!')
+    # This should work fine
+    result = template.format(name: 'World')
+    puts "✅ Prompt template validation passed: #{result}"
+  rescue Langfuse::ValidationError => e
+    puts "✅ Validation error caught: #{e.message}"
+  end
+
+  puts '✅ Error handling tests completed'
 rescue StandardError => e
   puts "❌ Error handling failed: #{e.message}"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Richard Sun
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-13 00:00:00.000000000 Z
+date: 2025-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -28,30 +28,56 @@ dependencies:
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   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: faraday-multipart
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -172,6 +198,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"
 - CHANGELOG.md
@@ -185,11 +212,13 @@ files:
 - 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/url_encoding_demo.rb
 - langfuse-ruby.gemspec
 - lib/langfuse.rb
 - lib/langfuse/client.rb
@@ -197,6 +226,7 @@ files:
 - lib/langfuse/evaluation.rb
 - lib/langfuse/event.rb
 - lib/langfuse/generation.rb
+- lib/langfuse/observation_types.rb
 - lib/langfuse/prompt.rb
 - lib/langfuse/span.rb
 - lib/langfuse/trace.rb
@@ -223,7 +253,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="