langfuse-ruby 0.1.3 → 0.1.5

data/lib/langfuse/client.rb

@@ -1,5 +1,6 @@
 require 'faraday'
 require 'faraday/net_http'
+require 'faraday/multipart'
 require 'json'
 require 'base64'
 require 'concurrent'
@@ -54,7 +55,7 @@ module Langfuse
     # Span operations
     def span(trace_id:, 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)
       Span.new(
         client: self,
         trace_id: trace_id,
@@ -68,6 +69,159 @@ module Langfuse
         status_message: status_message,
         parent_observation_id: parent_observation_id,
         version: version,
+        as_type: as_type,
+        **kwargs
+      )
+    end
+
+    # Convenience methods for enhanced observation types
+
+    # Create an agent observation (wrapper around span with as_type: 'agent')
+    def agent(trace_id:, 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(
+        trace_id: trace_id,
+        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 tool observation (wrapper around span with as_type: 'tool')
+    def tool(trace_id:, 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(
+        trace_id: trace_id,
+        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 chain observation (wrapper around span with as_type: 'chain')
+    def chain(trace_id:, 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(
+        trace_id: trace_id,
+        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 retriever observation (wrapper around span with as_type: 'retriever')
+    def retriever(trace_id:, 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(
+        trace_id: trace_id,
+        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 an embedding observation (wrapper around span with as_type: 'embedding')
+    def embedding(trace_id:, 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(
+        trace_id: trace_id,
+        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 an evaluator observation (wrapper around span with as_type: 'evaluator')
+    def evaluator_obs(trace_id:, 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(
+        trace_id: trace_id,
+        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 guardrail observation (wrapper around span with as_type: 'guardrail')
+    def guardrail(trace_id:, 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(
+        trace_id: trace_id,
+        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
@@ -125,7 +279,8 @@ module Langfuse
         return cached_prompt[:prompt]
       end
 
-      path = "/api/public/v2/prompts/#{name}"
+      encoded_name = Utils.url_encode(name)
+      path = "/api/public/v2/prompts/#{encoded_name}"
       params = {}
       params[:version] = version if version
       params[:label] = label if label
@@ -188,7 +343,7 @@ module Langfuse
     def enqueue_event(type, body)
       # 验证事件类型是否有效
       valid_types = %w[
-        trace-create
+        trace-create trace-update
         generation-create generation-update
         span-create span-update
         event-create
@@ -207,7 +362,32 @@ module Langfuse
         body: Utils.deep_stringify_keys(body)
       }
 
-      @event_queue << event
+      if type == 'trace-update'
+        # 查找对应的 trace-create 事件并更新
+        trace_id = body['id'] || body[:id]
+        if trace_id
+          existing_event_index = @event_queue.find_index do |existing_event|
+            existing_event[:type] == 'trace-create' &&
+              (existing_event[:body]['id'] == trace_id || existing_event[:body][:id] == trace_id)
+          end
+
+          if existing_event_index
+            # 更新现有的 trace-create 事件
+            @event_queue[existing_event_index][:body].merge!(event[:body])
+            @event_queue[existing_event_index][:timestamp] = event[:timestamp]
+            puts "Updated existing trace-create event for trace_id: #{trace_id}" if @debug
+          else
+            # 如果没找到对应的 trace-create 事件，将 trace-update 转换为 trace-create
+            event[:type] = 'trace-create'
+            @event_queue << event
+            puts "Converted trace-update to trace-create for trace_id: #{trace_id}" if @debug
+          end
+        elsif @debug
+          puts 'Warning: trace-update event missing trace_id, skipping'
+        end
+      else
+        @event_queue << event
+      end
       puts "Enqueued event: #{type}" if @debug
     end
 

data/lib/langfuse/event.rb

@@ -1,11 +1,11 @@
 module Langfuse
   class Event
     attr_reader :id, :trace_id, :name, :start_time, :input, :output, :metadata,
-                :level, :status_message, :parent_observation_id, :version, :client
+                :level, :status_message, :parent_observation_id, :version, :as_type, :client
 
     def initialize(client:, trace_id:, name:, id: nil, start_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
@@ -18,6 +18,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 event
@@ -25,7 +26,7 @@ module Langfuse
     end
 
     def to_dict
-      {
+      data = {
         id: @id,
         trace_id: @trace_id,
         name: @name,
@@ -37,11 +38,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_event
       data = {
         id: @id,
@@ -55,7 +69,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('event-create', data)
     end

data/lib/langfuse/generation.rb

@@ -2,12 +2,12 @@ module Langfuse
   class Generation
     attr_reader :id, :trace_id, :name, :start_time, :end_time, :completion_start_time,
                 :model, :model_parameters, :input, :output, :usage, :metadata, :level,
-                :status_message, :parent_observation_id, :version, :client
+                :status_message, :parent_observation_id, :version, :as_type, :client
 
     def initialize(client:, trace_id:, id: nil, 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, version: nil, **kwargs)
+                   parent_observation_id: nil, version: nil, as_type: nil, **kwargs)
       @client = client
       @id = id || Utils.generate_id
       @trace_id = trace_id
@@ -25,6 +25,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 generation
@@ -62,8 +63,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,
@@ -76,10 +78,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)
@@ -103,6 +107,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(
@@ -120,6 +125,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,
@@ -136,7 +273,7 @@ module Langfuse
     end
 
     def to_dict
-      {
+      data = {
         id: @id,
         trace_id: @trace_id,
         name: @name,
@@ -153,11 +290,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_generation
       @client.enqueue_event('generation-create', to_dict)
     end

data/lib/langfuse/observation_types.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Valid observation types for Langfuse
+  # These types provide semantic meaning to observations in traces
+  module ObservationType
+    # Core observation types (existing)
+    SPAN = 'span'
+    GENERATION = 'generation'
+    EVENT = 'event'
+
+    # Enhanced observation types (new in 2025)
+    AGENT = 'agent'           # Agent workflows and reasoning
+    TOOL = 'tool'             # Tool/function calls
+    CHAIN = 'chain'           # Chain operations (e.g., retrieval chains)
+    RETRIEVER = 'retriever'   # Data retrieval (vector stores, databases)
+    EMBEDDING = 'embedding'   # Embedding generation
+    EVALUATOR = 'evaluator'   # Evaluation/scoring functions
+    GUARDRAIL = 'guardrail'   # Safety filters and content moderation
+
+    # All valid observation types
+    ALL = [
+      SPAN,
+      GENERATION,
+      EVENT,
+      AGENT,
+      TOOL,
+      CHAIN,
+      RETRIEVER,
+      EMBEDDING,
+      EVALUATOR,
+      GUARDRAIL
+    ].freeze
+
+    # Types that are aliases for span (use span-create/span-update events)
+    SPAN_BASED = [
+      SPAN,
+      AGENT,
+      TOOL,
+      CHAIN,
+      RETRIEVER,
+      EMBEDDING,
+      EVALUATOR,
+      GUARDRAIL
+    ].freeze
+
+    # Validate if a type is valid
+    def self.valid?(type)
+      return true if type.nil? # nil is valid (defaults to base type)
+
+      ALL.include?(type.to_s)
+    end
+
+    # Check if type uses span events
+    def self.span_based?(type)
+      return true if type.nil?
+
+      SPAN_BASED.include?(type.to_s)
+    end
+  end
+end