langfuse-ruby 0.1.4 → 0.1.5

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

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