llm.rb 4.3.1 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b04602c6e101c35e64efe688c889da97675ebd112293f3da5b762456a3c15673
-  data.tar.gz: 20d63516d9d81661842d29d4e7c34325103cc60bd698f7195b59cc5be44a2ccc
+  metadata.gz: 357446a155ea5c66f1f1de5e2172f021bfa339c1006bae3f35a18b1c1ad173a7
+  data.tar.gz: 4726be4c9133aa0da37771c6a16ba1eab27771acee6826a259f624a199cf8088
 SHA512:
-  metadata.gz: 5ff6f85d0ec1c469e9ca9e5cfe310f28293b270f974dd9974d00bbf3b1cf6eb44e52351bf4b9d37e338c33349230bbd98f35d9bdbefe891b6dc402f734721654
-  data.tar.gz: 71dd34c25c103c4dd874a9f86ce3628b0abf81538234d3243dbbdf03f685369dab7a052b041c6ef7c088518ae024a4894b09cceaed59a569ad33b0e1af1d5186
+  metadata.gz: b97ee9fc6594633d4176d21651a9625e8cd7c55d7d66d9e3a8a0bf5314df957447e7b4af431f57cd5e9c47408ceefc08babbb868af05d9ef7b887e543c6914a8
+  data.tar.gz: 5881e618855cf3c9830fcc5edad571b2cb015a514ab99fcd4134e09402fda6ff51e7d034d50e96988739747a0dc5520b40c4938b9f1a0ed9af328dde22a48c99

data/README.md

@@ -4,7 +4,7 @@
 <p align="center">
   <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1"><img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc"></a>
   <a href="https://opensource.org/license/0bsd"><img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License"></a>
-  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.3.1-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-4.4.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About

data/lib/llm/provider.rb

@@ -39,6 +39,7 @@ class LLM::Provider
     @client = persistent ? persistent_client : transient_client
     @tracer = LLM::Tracer::Null.new(self)
     @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
+    @headers = {"User-Agent" => "llm.rb v#{LLM::VERSION}"}
   end
 
   ##
@@ -195,7 +196,7 @@ class LLM::Provider
   # @return [LLM::Provider]
   #  Returns self
   def with(headers:)
-    tap { (@headers ||= {}).merge!(headers) }
+    tap { @headers.merge!(headers) }
   end
 
   ##

data/lib/llm/tracer/telemetry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module LLM
   ##
   # The {LLM::Tracer::Telemetry LLM::Tracer::Telemetry} tracer provides
@@ -46,9 +48,46 @@ module LLM
     def initialize(provider, options = {})
       super
       @exporter = options.delete(:exporter)
+      @root_span = nil
+      @root_context = nil
       setup!
     end
 
+    ##
+    # When +trace_group_id+ is provided, it is converted to an OpenTelemetry
+    # trace_id (via a deterministic 16-byte hash) so all spans until {#stop_trace}
+    # share that trace_id and appear as one trace in OTLP/Langfuse.
+    #
+    # @param (see LLM::Tracer#start_trace)
+    # @return [self]
+    def start_trace(trace_group_id: nil, name: "llm", attributes: {})
+      return self if trace_group_id.to_s.empty?
+
+      span_context = span_context_from_trace_group_id(trace_group_id.to_s)
+      parent_ctx = ::OpenTelemetry::Trace.context_with_span(
+        ::OpenTelemetry::Trace.non_recording_span(span_context)
+      )
+      attrs = attributes.compact
+      attrs["llm.trace_group_id"] = trace_group_id.to_s
+      @root_span = @tracer.start_span(
+        name,
+        kind: :server,
+        attributes: attrs,
+        with_parent: parent_ctx
+      )
+      @root_context = ::OpenTelemetry::Trace.context_with_span(@root_span)
+      self
+    end
+
+    ##
+    # @return [self]
+    def stop_trace
+      @root_span&.finish
+      @root_span = nil
+      @root_context = nil
+      self
+    end
+
     ##
     # @param (see LLM::Tracer#on_request_start)
     def on_request_start(operation:, model: nil)
@@ -96,7 +135,7 @@ module LLM
         "server.port" => provider_port
       }.compact
       span_name = ["execute_tool", name].compact.join(" ")
-      span = @tracer.start_span(span_name.empty? ? "gen_ai.tool" : span_name, kind: :client, attributes:)
+      span = create_span(span_name.empty? ? "gen_ai.tool" : span_name, attributes:)
       span.add_event("gen_ai.tool.start")
       span
     end
@@ -155,6 +194,30 @@ module LLM
 
     private
 
+    ##
+    # @api private
+    def create_span(name, kind: :client, attributes: {})
+      opts = {kind:, attributes:}
+      opts[:with_parent] = @root_context if @root_context
+      @tracer.start_span(name, **opts)
+    end
+
+    ##
+    # Converts a string trace_group_id to an OpenTelemetry SpanContext so all
+    # spans created with this context share the same trace_id.
+    # @api private
+    def span_context_from_trace_group_id(trace_group_id)
+      trace_id = Digest::MD5.digest(trace_group_id)
+      trace_id = ::OpenTelemetry::Trace.generate_trace_id if trace_id == ::OpenTelemetry::Trace::INVALID_TRACE_ID
+      span_id = Digest::SHA256.digest(trace_group_id)[0, 8]
+      span_id = ::OpenTelemetry::Trace.generate_span_id if span_id == ::OpenTelemetry::Trace::INVALID_SPAN_ID
+      ::OpenTelemetry::Trace::SpanContext.new(
+        trace_id:,
+        span_id:,
+        trace_flags: ::OpenTelemetry::Trace::TraceFlags::SAMPLED
+      )
+    end
+
     ##
     # @api private
     def setup!
@@ -209,7 +272,7 @@ module LLM
         "server.port" => provider_port
       }.compact
       span_name = [operation, model].compact.join(" ")
-      span = @tracer.start_span(span_name.empty? ? "gen_ai.request" : span_name, kind: :client, attributes:)
+      span = create_span(span_name.empty? ? "gen_ai.request" : span_name, attributes:)
       span.add_event("gen_ai.request.start")
       span
     end
@@ -221,7 +284,7 @@ module LLM
         "server.address" => provider_host,
         "server.port" => provider_port
       }.compact
-      span = @tracer.start_span(operation, kind: :client, attributes:)
+      span = create_span(operation, attributes:)
       span.add_event("gen_ai.request.start")
       span
     end

data/lib/llm/tracer.rb

@@ -89,6 +89,31 @@ module LLM
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 
+    ##
+    # Opens a trace group so subsequent LLM spans share the same OpenTelemetry
+    # trace_id (and appear as one trace in backends like Langfuse).
+    # When +trace_group_id+ is a string, it is used to derive the trace_id.
+    #
+    # @param [String, nil] trace_group_id
+    #  Optional. When present, converted to a 16-byte trace_id so all spans
+    #  created until {#stop_trace} are grouped in one trace.
+    # @param [String] name
+    #  Name for the root span (e.g. "chatbot.turn").
+    # @param [Hash] attributes
+    #  OpenTelemetry attributes to set on the root span.
+    # @return [self]
+    def start_trace(trace_group_id: nil, name: "llm", attributes: {})
+      self
+    end
+
+    ##
+    # Finishes the trace group started by {#start_trace}. Safe to call even if
+    # no trace is active.
+    # @return [self]
+    def stop_trace
+      self
+    end
+
     ##
     # @return [String]
     def inspect

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "4.3.1"
+  VERSION = "4.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.3.1
+  version: 4.4.0
 platform: ruby
 authors:
 - Antar Azri