langfuse-ruby 0.2.0 → 0.2.1

data/lib/langfuse/event.rb

@@ -57,23 +57,7 @@ module Langfuse
     end
 
     def create_event
-      data = {
-        id: @id,
-        trace_id: @trace_id,
-        name: @name,
-        start_time: @start_time,
-        input: @input,
-        output: @output,
-        metadata: @metadata,
-        level: @level,
-        status_message: @status_message,
-        parent_observation_id: @parent_observation_id,
-        version: @version
-      }
-      data[:type] = @as_type if @as_type
-      data = data.merge(@kwargs).compact
-
-      @client.enqueue_event('event-create', data)
+      @client.enqueue_event('event-create', to_dict)
     end
   end
 end

data/lib/langfuse/generation.rb

@@ -2,6 +2,8 @@
 
 module Langfuse
   class Generation
+    include PartialUpdates
+
     attr_reader :id, :trace_id, :name, :start_time, :end_time, :completion_start_time,
                 :model, :model_parameters, :input, :output, :usage, :usage_details, :cost_details,
                 :prompt_name, :prompt_version, :metadata, :level,
@@ -43,35 +45,48 @@ module Langfuse
                model_parameters: nil, input: nil, output: nil, usage: nil,
                usage_details: nil, cost_details: nil, prompt: nil, metadata: nil,
                level: nil, status_message: nil, version: nil, **kwargs)
-      @name = name if name
-      @end_time = end_time if end_time
-      @completion_start_time = completion_start_time if completion_start_time
-      @model = model if model
+      @name = name unless name.nil?
+      @end_time = end_time unless end_time.nil?
+      @completion_start_time = completion_start_time unless completion_start_time.nil?
+      @model = model unless model.nil?
       @model_parameters.merge!(model_parameters) if model_parameters
-      @input = input if input
-      @output = output if output
+      @input = input unless input.nil?
+      @output = output unless output.nil?
       @usage.merge!(usage) if usage
       @usage_details.merge!(usage_details) if usage_details
       @cost_details.merge!(cost_details) if cost_details
       @prompt_name, @prompt_version = extract_prompt_info(prompt) if prompt
       @metadata.merge!(metadata) if metadata
-      @level = level if level
-      @status_message = status_message if status_message
-      @version = version if version
+      @level = level unless level.nil?
+      @status_message = status_message unless status_message.nil?
+      @version = version unless version.nil?
       @kwargs.merge!(kwargs)
 
+      changes = { name: name, end_time: end_time, completion_start_time: completion_start_time,
+                  model: model, model_parameters: model_parameters, input: input, output: output,
+                  usage: usage, usage_details: usage_details, cost_details: cost_details,
+                  metadata: metadata, level: level, status_message: status_message,
+                  version: version }
+      changes.merge!(prompt_name: @prompt_name, prompt_version: @prompt_version) if prompt
+
+      track_changes(changes, kwargs.keys)
       update_generation
       self
     end
 
     def end(output: nil, end_time: nil, usage: nil, usage_details: nil, cost_details: nil, **kwargs)
       @end_time = end_time || Utils.current_timestamp
-      @output = output if output
+      @output = output unless output.nil?
       @usage.merge!(usage) if usage
       @usage_details.merge!(usage_details) if usage_details
       @cost_details.merge!(cost_details) if cost_details
       @kwargs.merge!(kwargs)
 
+      track_changes(
+        { end_time: @end_time, output: output, usage: usage,
+          usage_details: usage_details, cost_details: cost_details },
+        kwargs.keys
+      )
       update_generation
       self
     end
@@ -99,6 +114,7 @@ module Langfuse
     # 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,
+                   usage_details: nil, cost_details: nil, prompt: nil,
                    metadata: nil, level: nil, status_message: nil, version: nil, **kwargs)
       @client.generation(
         trace_id: @trace_id,
@@ -111,6 +127,9 @@ module Langfuse
         input: input,
         output: output,
         usage: usage,
+        usage_details: usage_details,
+        cost_details: cost_details,
+        prompt: prompt,
         metadata: metadata,
         level: level,
         status_message: status_message,
@@ -138,79 +157,11 @@ 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
+    # Convenience methods for enhanced observation types: each is a child span
+    # with a fixed as_type. (embedding keeps its own definition because it folds
+    # model/usage into metadata first.)
+    extend SpanWrappers
+    define_span_wrappers
 
     # Create a child embedding observation
     def embedding(name: nil, start_time: nil, end_time: nil, input: nil, output: nil,
@@ -234,42 +185,6 @@ module Langfuse
       )
     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(
         trace_id: @trace_id,
@@ -345,7 +260,7 @@ module Langfuse
     end
 
     def update_generation
-      @client.enqueue_event('generation-update', to_dict)
+      @client.enqueue_event('generation-update', update_body)
     end
   end
 end

data/lib/langfuse/null_objects.rb

@@ -15,6 +15,7 @@ module Langfuse
     def retriever(**) = NullSpan.new
     def embedding(**) = NullSpan.new
     def evaluator(**) = NullSpan.new
+    alias evaluator_obs evaluator
     def guardrail(**) = NullSpan.new
     def score(**) = nil
     def get_url = nil
@@ -36,6 +37,7 @@ module Langfuse
     def retriever(**) = NullSpan.new
     def embedding(**) = NullSpan.new
     def evaluator(**) = NullSpan.new
+    alias evaluator_obs evaluator
     def guardrail(**) = NullSpan.new
     def score(**) = nil
     def get_url = nil
@@ -65,10 +67,12 @@ module Langfuse
     def retriever(**) = NullSpan.new
     def embedding(**) = NullSpan.new
     def evaluator(**) = NullSpan.new
+    alias evaluator_obs evaluator
     def guardrail(**) = NullSpan.new
     def score(**) = nil
     def get_url = nil
     def to_dict = {}
     def id = nil
+    def trace_id = nil
   end
 end

data/lib/langfuse/otel_exporter.rb

@@ -9,6 +9,15 @@ module Langfuse
   class OtelExporter
     OTEL_ENDPOINT = '/api/public/otel/v1/traces'
 
+    # Event types that carry the full state of an observation on every emit, so a
+    # later event supersedes the earlier one for the same observation id.
+    OBSERVATION_EVENT_TYPES = %w[span-create span-update generation-create generation-update].freeze
+
+    # Token keys accepted on the legacy `usage` object, in priority order.
+    USAGE_INPUT_KEYS = %w[promptTokens prompt_tokens inputTokens input_tokens input].freeze
+    USAGE_OUTPUT_KEYS = %w[completionTokens completion_tokens outputTokens output_tokens output].freeze
+    USAGE_TOTAL_KEYS = %w[totalTokens total_tokens total].freeze
+
     class << self
       # Convert an ID (UUID or hex string) to an OTEL 32-char hex trace ID.
       # OTEL trace IDs are 16 bytes (32 hex chars). Native hex IDs pass through unchanged.
@@ -70,7 +79,7 @@ module Langfuse
     # Build the top-level resourceSpans array from events.
     # Groups events by trace_id, producing one scopeSpan per trace.
     def build_resource_spans(events)
-      grouped = group_events_by_trace(events)
+      grouped = group_events_by_trace(collapse_observation_events(events))
 
       scope_spans = grouped.map do |_trace_id, trace_events|
         spans = trace_events.filter_map { |event| convert_event_to_span(event) }
@@ -93,6 +102,40 @@ module Langfuse
       }]
     end
 
+    # Collapse the create/update events of one observation into a single event.
+    # The v4 data model is append-only, so exporting both would produce two
+    # observations sharing a span id. Bodies are merged into new hashes, leaving
+    # the queued events untouched for re-queueing when the export fails.
+    def collapse_observation_events(events)
+      position_by_id = {}
+
+      events.each_with_object([]) do |event, collapsed|
+        id = observation_event_id(event)
+
+        if id.nil?
+          collapsed << event
+        elsif (position = position_by_id[id])
+          previous = collapsed[position]
+          collapsed[position] = previous.merge(
+            type: event[:type],
+            body: previous[:body].merge(event[:body])
+          )
+        else
+          position_by_id[id] = collapsed.length
+          collapsed << event
+        end
+      end
+    end
+
+    def observation_event_id(event)
+      return nil unless OBSERVATION_EVENT_TYPES.include?(event[:type])
+
+      body = event[:body]
+      return nil unless body.is_a?(Hash)
+
+      body['id'] || body[:id]
+    end
+
     # Group events by their trace ID for proper OTEL span hierarchy.
     def group_events_by_trace(events)
       groups = Hash.new { |h, k| h[k] = [] }
@@ -251,21 +294,65 @@ module Langfuse
         end
       end
 
-      usage = body['usage']
-      if usage.is_a?(Hash)
-        add_attr(attributes, 'gen_ai.usage.prompt_tokens', usage['promptTokens'] || usage['prompt_tokens'])
-        add_attr(attributes, 'gen_ai.usage.completion_tokens', usage['completionTokens'] || usage['completion_tokens'])
-        total = usage['totalTokens'] || usage['total_tokens']
-        add_attr(attributes, 'gen_ai.usage.total_tokens', total) if total
-      end
-
-      add_json_attr(attributes, 'langfuse.observation.usage_details', body['usageDetails'])
+      add_usage_attributes(attributes, body)
       add_json_attr(attributes, 'langfuse.observation.cost_details', body['costDetails'])
       add_attr(attributes, 'langfuse.observation.prompt.name', body['promptName'])
       add_attr(attributes, 'langfuse.observation.prompt.version', body['promptVersion'])
       add_attr(attributes, 'langfuse.observation.completion_start_time', body['completionStartTime'])
     end
 
+    # Emit token usage both as gen_ai.* semantic conventions and as the Langfuse
+    # v4 usage_details model. usage_details is what v4 uses for cost, so a legacy
+    # `usage` object is normalized into it when no explicit usage_details exists.
+    def add_usage_attributes(attributes, body)
+      usage = normalize_legacy_usage(body['usage'])
+
+      if usage
+        add_attr(attributes, 'gen_ai.usage.prompt_tokens', usage[:input])
+        add_attr(attributes, 'gen_ai.usage.completion_tokens', usage[:output])
+        add_attr(attributes, 'gen_ai.usage.total_tokens', usage[:total])
+      end
+
+      usage_details = body['usageDetails']
+      usage_details = usage if blank_value?(usage_details)
+      add_json_attr(attributes, 'langfuse.observation.usage_details', usage_details)
+    end
+
+    # Accept every shape the legacy ingestion API allowed
+    # (promptTokens / inputTokens / input) and return {input:, output:, total:}.
+    # Non-token units are skipped: usage_details is token-based, so mapping them
+    # would produce wrong cost numbers.
+    def normalize_legacy_usage(usage)
+      return nil unless usage.is_a?(Hash) && !usage.empty?
+
+      unit = usage['unit'] || usage[:unit]
+      if unit && unit.to_s.upcase != 'TOKENS'
+        log_debug { "Skipping usage with unit #{unit}; use usage_details for non-token usage" }
+        return nil
+      end
+
+      normalized = {
+        input: fetch_usage_value(usage, USAGE_INPUT_KEYS),
+        output: fetch_usage_value(usage, USAGE_OUTPUT_KEYS),
+        total: fetch_usage_value(usage, USAGE_TOTAL_KEYS)
+      }.compact
+
+      normalized.empty? ? nil : normalized
+    end
+
+    def fetch_usage_value(usage, keys)
+      keys.each do |key|
+        value = usage[key]
+        return value unless value.nil?
+      end
+
+      nil
+    end
+
+    def blank_value?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
     def to_otel_trace_id(id_str)
       self.class.to_otel_trace_id(id_str)
     end
@@ -279,14 +366,17 @@ module Langfuse
       return '0' unless timestamp_str
 
       time = Time.parse(timestamp_str.to_s)
-      (time.to_f * 1_000_000_000).to_i.to_s
+      ((time.to_i * 1_000_000_000) + time.nsec).to_s
     rescue ArgumentError
       '0'
     end
 
     # Add a string/numeric attribute to the attributes array.
+    # Structured values are JSON-encoded instead of falling back to Ruby's
+    # inspect format (which is not machine-readable on the Langfuse side).
     def add_attr(attributes, key, value)
       return if value.nil?
+      return add_json_attr(attributes, key, value) if value.is_a?(Hash) || value.is_a?(Array)
 
       otel_value = case value
                    when String

data/lib/langfuse/partial_updates.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Update events carry only the fields that changed. The ingestion API merges an
+  # update into the existing trace/observation, so re-sending a generation's
+  # input on every `end` call would double the payload of every LLM call.
+  module PartialUpdates
+    # Always sent so the server can resolve (and if needed upsert) the entity.
+    # `to_dict#slice` ignores the keys a given class does not have.
+    UPDATE_IDENTITY_FIELDS = %i[id trace_id type].freeze
+
+    private
+
+    # `changes` maps a body field to the value passed to update/end; nil means
+    # "not provided" and is left out of the update body. `extra_keys` carries the
+    # caller's **kwargs, which are merged into the body by to_dict.
+    def track_changes(changes, extra_keys = nil)
+      keys = changes.compact.keys
+      keys.concat(extra_keys.to_a)
+      @changed_fields = keys
+    end
+
+    def update_body
+      # Never tracked → this is a create path; use the full body.
+      return to_dict if @changed_fields.nil?
+
+      to_dict.slice(*UPDATE_IDENTITY_FIELDS, *@changed_fields)
+    end
+  end
+end

data/lib/langfuse/prompt.rb

@@ -64,7 +64,7 @@ module Langfuse
       # Convert text prompt to LangChain PromptTemplate format
       {
         _type: 'prompt',
-        input_variables: extract_variables(@prompt),
+        input_variables: TemplateCompiler.extract_variables(@prompt),
         template: @prompt
       }
     end
@@ -75,7 +75,7 @@ module Langfuse
         {
           _type: "#{message[:role]}_message",
           content: message[:content],
-          input_variables: extract_variables(message[:content])
+          input_variables: TemplateCompiler.extract_variables(message[:content])
         }
       end
 
@@ -87,44 +87,11 @@ module Langfuse
     end
 
     def compile_text_prompt(variables)
-      compiled = @prompt.dup
-      variables.each do |key, value|
-        compiled.gsub!("{{#{key}}}", value.to_s)
-        compiled.gsub!("{#{key}}", value.to_s)
-      end
-      compiled
+      TemplateCompiler.compile(@prompt, variables)
     end
 
     def compile_chat_prompt(variables)
-      @prompt.map do |message|
-        compiled_content = message[:content].dup
-        variables.each do |key, value|
-          compiled_content.gsub!("{{#{key}}}", value.to_s)
-          compiled_content.gsub!("{#{key}}", value.to_s)
-        end
-
-        {
-          role: message[:role],
-          content: compiled_content
-        }
-      end
-    end
-
-    def extract_variables(text)
-      # Extract variables from template text (supports {{var}} and {var} formats)
-      variables = []
-
-      # Match {{variable}} format
-      text.scan(/\{\{(\w+)\}\}/) do |match|
-        variables << match[0]
-      end
-
-      # Match {variable} format
-      text.scan(/\{(\w+)\}/) do |match|
-        variables << match[0] unless variables.include?(match[0])
-      end
-
-      variables
+      TemplateCompiler.compile_messages(@prompt, variables)
     end
   end
 
@@ -137,33 +104,15 @@ module Langfuse
     end
 
     def format(variables = {})
-      compiled = @template.dup
-      variables.each do |key, value|
-        compiled.gsub!("{{#{key}}}", value.to_s)
-        compiled.gsub!("{#{key}}", value.to_s)
-      end
-      compiled
+      TemplateCompiler.compile(@template, variables)
     end
 
     def self.from_template(template)
-      variables = extract_variables(template)
-      new(template: template, input_variables: variables)
+      new(template: template, input_variables: extract_variables(template))
     end
 
     def self.extract_variables(text)
-      variables = []
-
-      # Match {{variable}} format
-      text.scan(/\{\{(\w+)\}\}/) do |match|
-        variables << match[0]
-      end
-
-      # Match {variable} format
-      text.scan(/\{(\w+)\}/) do |match|
-        variables << match[0] unless variables.include?(match[0])
-      end
-
-      variables
+      TemplateCompiler.extract_variables(text)
     end
   end
 
@@ -176,34 +125,11 @@ module Langfuse
     end
 
     def format(variables = {})
-      @messages.map do |message|
-        compiled_content = message[:content].dup
-        variables.each do |key, value|
-          compiled_content.gsub!("{{#{key}}}", value.to_s)
-          compiled_content.gsub!("{#{key}}", value.to_s)
-        end
-
-        {
-          role: message[:role],
-          content: compiled_content
-        }
-      end
+      TemplateCompiler.compile_messages(@messages, variables)
     end
 
     def self.from_messages(messages)
-      input_variables = []
-
-      messages.each do |message|
-        message[:content].scan(/\{\{(\w+)\}\}/) do |match|
-          input_variables << match[0] unless input_variables.include?(match[0])
-        end
-
-        message[:content].scan(/\{(\w+)\}/) do |match|
-          input_variables << match[0] unless input_variables.include?(match[0])
-        end
-      end
-
-      new(messages: messages, input_variables: input_variables)
+      new(messages: messages, input_variables: TemplateCompiler.extract_message_variables(messages))
     end
   end
 end

data/lib/langfuse/prompt_cache.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Langfuse
+  # Bounded, thread-safe cache of Prompt objects, keyed by name/version/label.
+  #
+  # TTLs are measured on the monotonic clock so wall-clock jumps (NTP, DST) cannot
+  # extend or shorten an entry's lifetime. Entries keep insertion order and the
+  # oldest ones are evicted once the cache is full, so a long-running process with
+  # many prompt names cannot grow it without bound.
+  class PromptCache
+    DEFAULT_MAX_ENTRIES = 200
+
+    Entry = Struct.new(:prompt, :cached_at) do
+      def fresh?(ttl_seconds, now)
+        return false if ttl_seconds.nil?
+
+        now - cached_at < ttl_seconds
+      end
+    end
+
+    def initialize(max_entries: DEFAULT_MAX_ENTRIES)
+      @max_entries = [max_entries.to_i, 0].max
+      @entries = Concurrent::Hash.new
+      @mutex = Mutex.new
+    end
+
+    # The cached prompt while it is still fresh, otherwise nil.
+    def read(key, ttl_seconds)
+      entry = @entries[key]
+      return nil unless entry&.fresh?(ttl_seconds, monotonic_time)
+
+      entry.prompt
+    end
+
+    # The cached prompt regardless of age. Used to keep serving prompts while the
+    # Langfuse API is unreachable.
+    def read_stale(key)
+      @entries[key]&.prompt
+    end
+
+    # Writes are serialized so concurrent fetches cannot corrupt the hash while it
+    # is being trimmed. Returns the prompt for convenient chaining.
+    def write(key, prompt)
+      @mutex.synchronize do
+        @entries.delete(key)
+        @entries[key] = Entry.new(prompt, monotonic_time)
+        @entries.shift while @entries.length > @max_entries && !@entries.empty?
+      end
+
+      prompt
+    end
+
+    def length
+      @entries.length
+    end
+
+    private
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end