langfuse-ruby 0.2.0 → 0.2.1

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,42 +157,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,
@@ -295,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

data/lib/langfuse/trace.rb

@@ -2,6 +2,8 @@
 
 module Langfuse
   class Trace
+    include PartialUpdates
+
     attr_reader :id, :name, :user_id, :session_id, :version, :release, :input, :output,
                 :metadata, :tags, :timestamp, :public, :client
 
@@ -95,87 +97,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, parent_observation_id: 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,
-        parent_observation_id: parent_observation_id,
-        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, parent_observation_id: 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,
-        parent_observation_id: parent_observation_id,
-        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, parent_observation_id: 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,
-        parent_observation_id: parent_observation_id,
-        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, parent_observation_id: 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,
-        parent_observation_id: parent_observation_id,
-        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,
@@ -200,46 +126,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, parent_observation_id: 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,
-        parent_observation_id: parent_observation_id,
-        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, parent_observation_id: 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,
-        parent_observation_id: parent_observation_id,
-        version: version,
-        as_type: ObservationType::GUARDRAIL,
-        **kwargs
-      )
-    end
-
     def score(name:, value:, data_type: nil, comment: nil, **kwargs)
       @client.score(
         trace_id: @id,
@@ -255,19 +141,27 @@ module Langfuse
                release: nil, input: nil, output: nil, metadata: nil, tags: nil,
                public: nil, **kwargs)
       # 更新实例变量
-      @name = name if name
-      @user_id = user_id if user_id
-      @session_id = session_id if session_id
-      @version = version if version
-      @release = release if release
-      @input = input if input
-      @output = output if output
-      @metadata = metadata if metadata
-      @tags = tags if tags
+      @name = name unless name.nil?
+      @user_id = user_id unless user_id.nil?
+      @session_id = session_id unless session_id.nil?
+      @version = version unless version.nil?
+      @release = release unless release.nil?
+      @input = input unless input.nil?
+      @output = output unless output.nil?
+      @metadata.merge!(metadata) if metadata
+      @tags = tags unless tags.nil?
       @public = public unless public.nil?
       @kwargs.merge!(kwargs) if kwargs.any?
+
+      track_changes(
+        { name: name, user_id: user_id, session_id: session_id, version: version,
+          release: release, input: input, output: output, metadata: metadata,
+          tags: tags, public: public },
+        kwargs.keys
+      )
       # 触发 trace-update 事件
       update_trace
+      self
     end
 
     def get_url
@@ -294,41 +188,11 @@ module Langfuse
     private
 
     def create_trace
-      data = {
-        id: @id,
-        name: @name,
-        user_id: @user_id,
-        session_id: @session_id,
-        version: @version,
-        release: @release,
-        input: @input,
-        output: @output,
-        metadata: @metadata,
-        tags: @tags,
-        timestamp: @timestamp,
-        public: @public
-      }.merge(@kwargs).compact
-
-      @client.enqueue_event('trace-create', data)
+      @client.enqueue_event('trace-create', to_dict)
     end
 
     def update_trace
-      data = {
-        id: @id,
-        name: @name,
-        user_id: @user_id,
-        session_id: @session_id,
-        version: @version,
-        release: @release,
-        input: @input,
-        output: @output,
-        metadata: @metadata,
-        tags: @tags,
-        timestamp: @timestamp,
-        public: @public
-      }.merge(@kwargs).compact
-
-      @client.enqueue_event('trace-update', data)
+      @client.enqueue_event('trace-update', update_body, trace_ref: self)
     end
   end
 end

data/lib/langfuse/utils.rb

@@ -33,26 +33,39 @@ module Langfuse
         ERB::Util.url_encode(string.to_s)
       end
 
-      def deep_symbolize_keys(hash)
-        return hash unless hash.is_a?(Hash)
-
-        hash.each_with_object({}) do |(key, value), result|
-          new_key = key.is_a?(String) ? key.to_sym : key
-          new_value = value.is_a?(Hash) ? deep_symbolize_keys(value) : value
-          result[new_key] = new_value
+      def deep_symbolize_keys(object)
+        case object
+        when Hash
+          object.each_with_object({}) do |(key, value), result|
+            new_key = key.is_a?(String) ? key.to_sym : key
+            result[new_key] = deep_symbolize_keys(value)
+          end
+        when Array
+          object.map { |item| deep_symbolize_keys(item) }
+        else
+          object
         end
       end
 
-      def deep_stringify_keys(hash)
-        return hash unless hash.is_a?(Hash)
-
-        hash.each_with_object({}) do |(key, value), result|
-          new_key = camelize_key(key.to_s)
-          new_value = value.is_a?(Hash) ? deep_stringify_keys(value) : value
-          result[new_key] = new_value
+      # 将哈希的键名转换为小驼峰格式
+      def deep_camelize_keys(object)
+        case object
+        when Hash
+          object.each_with_object({}) do |(key, value), result|
+            new_key = camelize_key(key.to_s)
+            result[new_key] = deep_camelize_keys(value)
+          end
+        when Array
+          object.map { |item| deep_camelize_keys(item) }
+        else
+          object
         end
       end
 
+      # Kept for backwards compatibility: it has always camelized keys rather
+      # than only stringifying them.
+      alias deep_stringify_keys deep_camelize_keys
+
       # Prepare an event body for the ingestion API:
       # - top-level keys are camelized (snake_case -> camelCase)
       # - user data values (input/output/metadata/usageDetails/costDetails/modelParameters)
@@ -64,24 +77,13 @@ module Langfuse
         body.each_with_object({}) do |(key, value), result|
           new_key = camelize_key(key.to_s)
           result[new_key] = if !VERBATIM_BODY_KEYS.include?(new_key) && value.is_a?(Hash)
-                              deep_stringify_keys(value)
+                              deep_camelize_keys(value)
                             else
                               value
                             end
         end
       end
 
-      # 将哈希的键名转换为小驼峰格式
-      def deep_camelize_keys(hash)
-        return hash unless hash.is_a?(Hash)
-
-        hash.each_with_object({}) do |(key, value), result|
-          new_key = camelize_key(key.to_s)
-          new_value = value.is_a?(Hash) ? deep_camelize_keys(value) : value
-          result[new_key] = new_value
-        end
-      end
-
       private
 
       # 将蛇形命名转换为小驼峰命名

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end