langfuse-ruby 0.1.7 → 0.2.1

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

data/lib/langfuse/span.rb

@@ -2,6 +2,8 @@
 
 module Langfuse
   class Span
+    include PartialUpdates
+
     attr_reader :id, :trace_id, :name, :start_time, :end_time, :input, :output,
                 :metadata, :level, :status_message, :parent_observation_id, :version,
                 :as_type, :client
@@ -31,25 +33,32 @@ module Langfuse
 
     def update(name: nil, end_time: nil, input: nil, output: nil, metadata: nil,
                level: nil, status_message: nil, version: nil, **kwargs)
-      @name = name if name
-      @end_time = end_time if end_time
-      @input = input if input
-      @output = output if output
+      @name = name unless name.nil?
+      @end_time = end_time unless end_time.nil?
+      @input = input unless input.nil?
+      @output = output unless output.nil?
       @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)
 
+      track_changes(
+        { name: name, end_time: end_time, input: input, output: output,
+          metadata: metadata, level: level, status_message: status_message,
+          version: version },
+        kwargs.keys
+      )
       update_span
       self
     end
 
     def end(output: nil, end_time: nil, **kwargs)
       @end_time = end_time || Utils.current_timestamp
-      @output = output if output
+      @output = output unless output.nil?
       @kwargs.merge!(kwargs)
 
+      track_changes({ end_time: @end_time, output: output }, kwargs.keys)
       update_span
       self
     end
@@ -77,6 +86,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,
@@ -89,6 +99,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,
@@ -116,79 +129,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,
@@ -212,44 +157,9 @@ 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,
         observation_id: @id,
         name: name,
         value: value,
@@ -294,45 +204,11 @@ module Langfuse
     end
 
     def create_span
-      data = {
-        id: @id,
-        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
-      }
-      data[:type] = @as_type if @as_type
-      data = data.merge(@kwargs).compact
-
-      @client.enqueue_event('span-create', data)
+      @client.enqueue_event('span-create', to_dict)
     end
 
     def update_span
-      data = {
-        id: @id,
-        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
-      }
-      data[:type] = @as_type if @as_type
-      data = data.merge(@kwargs).compact
-
-      @client.enqueue_event('span-update', data)
+      @client.enqueue_event('span-update', update_body)
     end
   end
 end

data/lib/langfuse/span_wrappers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Defines the enhanced observation helpers (agent, tool, chain, retriever,
+  # evaluator, guardrail) as thin wrappers around the extending class's #span,
+  # each pinning a fixed as_type.
+  #
+  # `embedding` is intentionally not generated here: every wrapper folds
+  # model/usage into metadata before delegating, so it stays hand-written.
+  module SpanWrappers
+    TYPES = {
+      agent: ObservationType::AGENT,
+      tool: ObservationType::TOOL,
+      chain: ObservationType::CHAIN,
+      retriever: ObservationType::RETRIEVER,
+      evaluator: ObservationType::EVALUATOR,
+      guardrail: ObservationType::GUARDRAIL
+    }.freeze
+
+    # `evaluator_name` exists because Client exposes the helper as
+    # `evaluator_obs`, keeping it distinct from the Evaluators API.
+    def define_span_wrappers(evaluator_name: :evaluator)
+      TYPES.each do |name, as_type|
+        method_name = name == :evaluator ? evaluator_name : name
+
+        define_method(method_name) do |**kwargs|
+          span(**kwargs, as_type: as_type)
+        end
+      end
+    end
+  end
+end

data/lib/langfuse/template_compiler.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Placeholder handling shared by Prompt, PromptTemplate and ChatPromptTemplate.
+  # Both `{{var}}` and `{var}` are supported.
+  module TemplateCompiler
+    VARIABLE_PATTERN = /\{\{([a-zA-Z0-9_.]+)\}\}|\{([a-zA-Z0-9_.]+)\}/
+
+    class << self
+      # Substitutes every provided variable in a single pass, so a value that
+      # itself contains a placeholder is never expanded again (a value like
+      # "{{admin_prompt}}" stays literal). Placeholders without a matching
+      # variable are left untouched.
+      def compile(template, variables = {})
+        text = template.to_s
+        return text if variables.nil? || variables.empty?
+
+        values = variables.to_h { |key, value| [key.to_s, value.to_s] }
+
+        text.gsub(placeholder_pattern(values.keys)) do
+          values[Regexp.last_match(1) || Regexp.last_match(2)]
+        end
+      end
+
+      def compile_messages(messages, variables = {})
+        messages.map do |message|
+          role = message[:role] || message['role']
+          content = compile(message[:content] || message['content'], variables)
+          message.merge(role: role, content: content)
+        end
+      end
+
+      def extract_variables(text)
+        text.to_s.scan(VARIABLE_PATTERN).map { |double, single| double || single }.uniq
+      end
+
+      def extract_message_variables(messages)
+        messages.flat_map do |message|
+          content = message[:content] || message['content']
+          extract_variables(content)
+        end.uniq
+      end
+
+      private
+
+      # Longest name first so a `user` variable cannot shadow `{{user_name}}`.
+      def placeholder_pattern(names)
+        alternatives = names.sort_by { |name| -name.length }
+                            .map { |name| Regexp.escape(name) }
+                            .join('|')
+
+        /\{\{(#{alternatives})\}\}|\{(#{alternatives})\}/
+      end
+    end
+  end
+end