langfuse-ruby 0.1.4 → 0.1.6

data/lib/langfuse/evaluation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
   class Evaluation
     attr_reader :id, :name, :value, :data_type, :comment, :trace_id, :observation_id, :created_at
@@ -84,10 +86,10 @@ module Langfuse
 
     class ExactMatchEvaluator < BaseEvaluator
       def initialize(name: 'exact_match', description: 'Exact match evaluator')
-        super(name: name, description: description)
+        super
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         return create_score(value: 0, comment: 'No expected value provided') unless expected
 
         score = output.to_s.strip == expected.to_s.strip ? 1 : 0
@@ -104,7 +106,7 @@ module Langfuse
         @case_sensitive = case_sensitive
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         return create_score(value: 0, comment: 'No expected value provided') unless expected
 
         output_str = @case_sensitive ? output.to_s : output.to_s.downcase
@@ -125,11 +127,11 @@ module Langfuse
         @max_length = max_length
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         length = output.to_s.length
 
         if @min_length && @max_length
-          score = length >= @min_length && length <= @max_length ? 1 : 0
+          score = length.between?(@min_length, @max_length) ? 1 : 0
           comment = score == 1 ? "Length #{length} within range" : "Length #{length} outside range #{@min_length}-#{@max_length}"
         elsif @min_length
           score = length >= @min_length ? 1 : 0
@@ -156,7 +158,7 @@ module Langfuse
         @pattern = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern)
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         match = @pattern.match(output.to_s)
         score = match ? 1 : 0
 
@@ -169,10 +171,10 @@ module Langfuse
 
     class SimilarityEvaluator < BaseEvaluator
       def initialize(name: 'similarity', description: 'Similarity evaluator')
-        super(name: name, description: description)
+        super
       end
 
-      def evaluate(input, output, expected: nil, context: nil)
+      def evaluate(_input, output, expected: nil, context: nil)
         return create_score(value: 0, comment: 'No expected value provided') unless expected
 
         # Simple character-based similarity (Levenshtein distance)
@@ -230,10 +232,10 @@ module Langfuse
       def evaluate(input, output, expected: nil, context: nil)
         # This is a placeholder for LLM-based evaluation
         # In a real implementation, you would call an LLM API here
-        prompt = @prompt_template.gsub('{input}', input.to_s)
-                                 .gsub('{output}', output.to_s)
-                                 .gsub('{expected}', expected.to_s)
-                                 .gsub('{context}', context.to_s)
+        @prompt_template.gsub('{input}', input.to_s)
+                        .gsub('{output}', output.to_s)
+                        .gsub('{expected}', expected.to_s)
+                        .gsub('{context}', context.to_s)
 
         # Simulate LLM response (in real implementation, call actual LLM)
         score = rand(0.0..1.0).round(2)

data/lib/langfuse/event.rb

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
+
 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 +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 event
@@ -25,7 +28,7 @@ module Langfuse
     end
 
     def to_dict
-      {
+      data = {
         id: @id,
         trace_id: @trace_id,
         name: @name,
@@ -37,11 +40,22 @@ 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
+      raise ValidationError, "Invalid observation type: #{type}. Valid types are: #{ObservationType::ALL.join(', ')}" unless ObservationType.valid?(type_str)
+
+      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

@@ -1,13 +1,15 @@
+# frozen_string_literal: true
+
 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 +27,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 +65,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 +80,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 +109,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 +127,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 +275,7 @@ module Langfuse
     end
 
     def to_dict
-      {
+      data = {
         id: @id,
         trace_id: @trace_id,
         name: @name,
@@ -153,11 +292,22 @@ 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
+      raise ValidationError, "Invalid observation type: #{type}. Valid types are: #{ObservationType::ALL.join(', ')}" unless ObservationType.valid?(type_str)
+
+      type_str
+    end
+
     def create_generation
       @client.enqueue_event('generation-create', to_dict)
     end

data/lib/langfuse/null_objects.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # NullGeneration provides a no-op generation object for graceful degradation.
+  # Used when Langfuse is unavailable or trace creation fails.
+  class NullGeneration
+    def update(**) = self
+    def end(**) = self
+    def span(**) = NullSpan.new
+    def generation(**) = NullGeneration.new
+    def event(**) = NullEvent.new
+    def agent(**) = NullSpan.new
+    def tool(**) = NullSpan.new
+    def chain(**) = NullSpan.new
+    def retriever(**) = NullSpan.new
+    def embedding(**) = NullSpan.new
+    def evaluator(**) = NullSpan.new
+    def guardrail(**) = NullSpan.new
+    def score(**) = nil
+    def get_url = nil
+    def to_dict = {}
+    def id = nil
+    def trace_id = nil
+  end
+
+  # NullSpan provides a no-op span object for graceful degradation.
+  class NullSpan
+    def update(**) = self
+    def end(**) = self
+    def span(**) = NullSpan.new
+    def generation(**) = NullGeneration.new
+    def event(**) = NullEvent.new
+    def agent(**) = NullSpan.new
+    def tool(**) = NullSpan.new
+    def chain(**) = NullSpan.new
+    def retriever(**) = NullSpan.new
+    def embedding(**) = NullSpan.new
+    def evaluator(**) = NullSpan.new
+    def guardrail(**) = NullSpan.new
+    def score(**) = nil
+    def get_url = nil
+    def to_dict = {}
+    def id = nil
+    def trace_id = nil
+  end
+
+  # NullEvent provides a no-op event object for graceful degradation.
+  class NullEvent
+    def to_dict = {}
+    def id = nil
+    def trace_id = nil
+  end
+
+  # NullTrace provides a no-op trace object for graceful degradation.
+  # Used when Langfuse is unavailable or trace creation fails.
+  # Ensures calling code doesn't break when Langfuse has issues.
+  class NullTrace
+    def update(**) = self
+    def span(**) = NullSpan.new
+    def generation(**) = NullGeneration.new
+    def event(**) = NullEvent.new
+    def agent(**) = NullSpan.new
+    def tool(**) = NullSpan.new
+    def chain(**) = NullSpan.new
+    def retriever(**) = NullSpan.new
+    def embedding(**) = NullSpan.new
+    def evaluator(**) = NullSpan.new
+    def guardrail(**) = NullSpan.new
+    def score(**) = nil
+    def get_url = nil
+    def to_dict = {}
+    def id = nil
+  end
+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/prompt.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Langfuse
   class Prompt
     attr_reader :id, :name, :version, :prompt, :config, :labels, :tags, :type, :created_at, :updated_at
@@ -148,8 +150,6 @@ module Langfuse
       new(template: template, input_variables: variables)
     end
 
-    private
-
     def self.extract_variables(text)
       variables = []