llm.rb 4.6.0 → 4.8.0

data/lib/llm/tracer/telemetry.rb

@@ -7,8 +7,7 @@ module LLM
   # The {LLM::Tracer::Telemetry LLM::Tracer::Telemetry} tracer provides
   # telemetry support through the [opentelemetry-ruby](https://github.com/open-telemetry/opentelemetry-ruby)
   # RubyGem. The gem should be installed separately since this feature is opt-in
-  # and disabled by default. This feature exists to support integration with tools
-  # like [LangSmith](https://www.langsmith.com).
+  # and disabled by default.
   #
   # @see https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai Telemetry specs (index)
   # @see https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/openai.md Telemetry specs (OpenAI)
@@ -58,7 +57,7 @@ module LLM
     #
     # @param (see LLM::Tracer#start_trace)
     # @return [self]
-    def start_trace(trace_group_id: nil, name: "llm", attributes: {})
+    def start_trace(trace_group_id: nil, name: "llm", attributes: {}, metadata: nil)
       return self if trace_group_id.to_s.empty?
 
       span_context = span_context_from_trace_group_id(trace_group_id.to_s)
@@ -73,25 +72,25 @@ module LLM
         attributes: attrs,
         with_parent: parent_ctx
       )
-      thread[thread_root_span_key] = root_span
-      thread[thread_root_context_key] = ::OpenTelemetry::Trace.context_with_span(root_span)
+      @root_span = root_span
+      @root_context = ::OpenTelemetry::Trace.context_with_span(root_span)
       self
     end
 
     ##
     # @return [self]
     def stop_trace
-      thread[thread_root_span_key]&.finish
-      thread[thread_root_span_key] = nil
-      thread[thread_root_context_key] = nil
+      @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)
+    def on_request_start(operation:, model: nil, inputs: nil)
       case operation
-      when "chat" then start_chat(operation:, model:)
+      when "chat" then start_chat(operation:, model:, inputs:)
       when "retrieval" then start_retrieval(operation:)
       else nil
       end
@@ -99,10 +98,10 @@ module LLM
 
     ##
     # @param (see LLM::Tracer#on_request_finish)
-    def on_request_finish(operation:, res:, model: nil, span: nil)
+    def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil)
       return nil unless span
       case operation
-      when "chat" then finish_chat(operation:, model:, res:, span:)
+      when "chat" then finish_chat(operation:, model:, res:, span:, outputs:, metadata:)
       when "retrieval" then finish_retrieval(operation:, res:, span:)
       else nil
       end
@@ -132,7 +131,7 @@ module LLM
         "gen_ai.provider.name" => provider_name,
         "server.address" => provider_host,
         "server.port" => provider_port
-      }.compact
+      }.merge!(trace_attributes(span_kind: "tool")).compact
       span_name = ["execute_tool", name].compact.join(" ")
       span = create_span(span_name.empty? ? "gen_ai.tool" : span_name, attributes:)
       span.add_event("gen_ai.tool.start")
@@ -196,30 +195,12 @@ module LLM
     ##
     # @api private
     def create_span(name, kind: :client, attributes: {})
-      root_context = thread[thread_root_context_key]
+      root_context = @root_context
       opts = {kind:, attributes:}
       opts[:with_parent] = root_context if root_context
       @tracer.start_span(name, **opts)
     end
 
-    ##
-    # @api private
-    def thread_root_span_key
-      @thread_root_span_key ||= :"llm.telemetry.root_span.#{object_id}"
-    end
-
-    ##
-    # @api private
-    def thread_root_context_key
-      @thread_root_context_key ||= :"llm.telemetry.root_context.#{object_id}"
-    end
-
-    ##
-    # @api private
-    def thread
-      Thread.current
-    end
-
     ##
     # Converts a string trace_group_id to an OpenTelemetry SpanContext so all
     # spans created with this context share the same trace_id.
@@ -281,16 +262,20 @@ module LLM
     ##
     # start_*
 
-    def start_chat(operation:, model:)
+    def start_chat(operation:, model:, inputs: nil)
+      request_metadata = consume_request_metadata
+      input_value = request_metadata[:user_input]
       attributes = {
         "gen_ai.operation.name" => operation,
         "gen_ai.request.model" => model,
         "gen_ai.provider.name" => provider_name,
         "server.address" => provider_host,
-        "server.port" => provider_port
-      }.compact
+        "server.port" => provider_port,
+        "input.value" => serialize_request_value(input_value)
+      }.merge!(trace_attributes(span_kind: "llm")).compact
       span_name = [operation, model].compact.join(" ")
       span = create_span(span_name.empty? ? "gen_ai.request" : span_name, attributes:)
+      set_span_attributes(span, consume_extra_inputs.merge(inputs || {}))
       span.add_event("gen_ai.request.start")
       span
     end
@@ -301,7 +286,7 @@ module LLM
         "gen_ai.provider.name" => provider_name,
         "server.address" => provider_host,
         "server.port" => provider_port
-      }.compact
+      }.merge!(trace_attributes(span_kind: "retriever")).compact
       span = create_span(operation, attributes:)
       span.add_event("gen_ai.request.start")
       span
@@ -310,16 +295,26 @@ module LLM
     ##
     # finish_*
 
-    def finish_chat(operation:, model:, res:, span:)
+    def finish_chat(operation:, model:, res:, span:, outputs: nil, metadata: nil)
+      output_value = if res.respond_to?(:output_text)
+        res.output_text
+      else
+        (res.respond_to?(:content) ? res.content : nil)
+      end
       attributes = {
         "gen_ai.operation.name" => operation,
         "gen_ai.request.model" => model,
         "gen_ai.response.id" => res.id,
         "gen_ai.response.model" => model,
         "gen_ai.usage.input_tokens" => res.usage.input_tokens,
-        "gen_ai.usage.output_tokens" => res.usage.output_tokens
+        "gen_ai.usage.output_tokens" => res.usage.output_tokens,
+        "output.value" => serialize_request_value(output_value)
       }.merge!(finish_attributes(operation, res)).compact
       attributes.each { span.set_attribute(_1, _2) }
+      set_span_attributes(span, consume_extra_outputs.merge(outputs || {}))
+      finish_metadata = consume_finish_metadata_proc(res)
+      metadata = (metadata || {}).merge(finish_metadata || {})
+      set_span_attributes(span, metadata.transform_keys { "langsmith.metadata.#{_1}" })
       span.add_event("gen_ai.request.finish")
       span.tap(&:finish)
     end
@@ -328,9 +323,83 @@ module LLM
       attributes = {
         "gen_ai.operation.name" => operation
       }.merge!(finish_attributes(operation, res)).compact
+      chunks_json = retrieval_chunks_json(res)
+      attributes["langsmith.metadata.chunks"] = chunks_json if chunks_json
       attributes.each { span.set_attribute(_1, _2) }
       span.add_event("gen_ai.request.finish")
       span.tap(&:finish)
     end
+
+    ##
+    # @api private
+    # Serialize retrieval response chunks for span attributes (e.g. langsmith.metadata.chunks).
+    # Returns a JSON string or nil when res has no data.
+    def consume_finish_metadata_proc(res)
+      key = LLM::Tracer::FINISH_METADATA_PROC_KEY
+      proc = Thread.current[key]
+      Thread.current[key] = nil
+      return {} unless proc.respond_to?(:call)
+
+      proc.call(res) || {}
+    rescue
+      {}
+    end
+
+    def retrieval_chunks_json(res)
+      return nil unless res.respond_to?(:data)
+
+      data = res.data
+      return nil unless data.is_a?(Array)
+
+      payload = data.map { |c| c.respond_to?(:to_h) ? c.to_h : c }
+      LLM.json.dump(payload)
+    rescue
+      nil
+    end
+
+    ##
+    # @api private
+    # Hook for tracer-specific span attributes.
+    # Subclasses can override this to inject provider-agnostic tags.
+    def trace_attributes(span_kind:)
+      {}
+    end
+
+    ##
+    # @api private
+    # Sets attribute key-value pairs on the span, serializing non-primitive values to JSON.
+    def set_span_attributes(span, attrs)
+      return if attrs.nil? || attrs.empty?
+
+      attrs.each do |key, value|
+        span.set_attribute(key.to_s, serialize_span_value(value))
+      end
+    end
+
+    ##
+    # @api private
+    # OpenTelemetry attributes accept String, Numeric, Boolean, or Array of those.
+    # Complex values (hashes, arrays of objects) are serialized to JSON strings.
+    def serialize_span_value(value)
+      case value
+      when String, Numeric, TrueClass, FalseClass
+        value
+      when Array
+        value.all? { |v| v.is_a?(String) || v.is_a?(Numeric) || v == true || v == false } ? value : LLM.json.dump(value)
+      else
+        LLM.json.dump(value)
+      end
+    end
+
+    def serialize_request_value(value)
+      case value
+      when nil
+        nil
+      when String
+        value
+      else
+        LLM.json.dump(value)
+      end
+    end
   end
 end

data/lib/llm/tracer.rb

@@ -11,6 +11,7 @@ module LLM
   class Tracer
     require_relative "tracer/logger"
     require_relative "tracer/telemetry"
+    require_relative "tracer/langsmith"
     require_relative "tracer/null"
 
     ##
@@ -27,19 +28,22 @@ module LLM
     # Called before an LLM provider request is executed.
     # @param [String] operation
     # @param [String] model
+    # @param [Hash, nil] inputs Optional span attributes (e.g. gen_ai.input.messages) from llm.rb or caller.
     # @return [void]
-    def on_request_start(operation:, model: nil)
+    def on_request_start(operation:, model: nil, inputs: nil)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 
     ##
     # Called after an LLM provider request succeeds.
     # @param [String] operation
-    # @param [String] model
     # @param [LLM::Response] res
     # @param [Object, nil] span
+    # @param [String] model
+    # @param [Hash, nil] outputs Optional span attributes (e.g. gen_ai.output.messages) from llm.rb or caller.
+    # @param [Hash, nil] metadata Optional metadata (emitted as langsmith.metadata.*) from llm.rb or caller.
     # @return [void]
-    def on_request_finish(operation:, res:, model: nil, span: nil)
+    def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
     end
 
@@ -101,8 +105,11 @@ module LLM
     #  Name for the root span (e.g. "chatbot.turn").
     # @param [Hash] attributes
     #  OpenTelemetry attributes to set on the root span.
+    # @param [Hash, nil] metadata
+    #  Optional. Trace-level metadata merged into the trace (e.g. langsmith.metadata.*).
+    #  Only used by tracers that support it (e.g. {LLM::Tracer::Langsmith}).
     # @return [self]
-    def start_trace(trace_group_id: nil, name: "llm", attributes: {})
+    def start_trace(trace_group_id: nil, name: "llm", attributes: {}, metadata: nil)
       self
     end
 
@@ -136,8 +143,105 @@ module LLM
       nil
     end
 
+    ##
+    # Merges extra attributes for the current trace/span. Used by applications
+    # (e.g. chatbot) to add metadata, span inputs, or span outputs to the next
+    # span or to the trace. No-op by default; {LLM::Tracer::Langsmith} merges
+    # into thread-local storage and emits them as langsmith/GenAI attributes.
+    #
+    # @param [Hash, nil] metadata
+    #  Key-value pairs merged into trace/span metadata (e.g. langsmith.metadata.*).
+    # @param [Hash, nil] inputs
+    #  Key-value pairs set on the next span at start (e.g. gen_ai.input.messages).
+    #  Consumed when the span is created.
+    # @param [Hash, nil] outputs
+    #  Key-value pairs set on the current span at finish (e.g. gen_ai.output.messages).
+    #  Must be set before the request finishes (e.g. in a block passed to the provider).
+    # @return [self]
+    def merge_extra(metadata: nil, inputs: nil, outputs: nil)
+      self
+    end
+
+    ##
+    # Optional: set a proc to supply metadata when the next chat span finishes.
+    # The proc is called with the response (res) and should return a Hash of
+    # metadata (e.g. { intent: "...", confidence: 1.0 }) to merge onto the span
+    # as langsmith.metadata.*. Cleared after use. Used by apps to attach
+    # routing/intent that is only known after the response.
+    #
+    # @param [Proc, nil] proc (res) -> Hash or nil
+    # @return [self]
+    def set_finish_metadata_proc(proc)
+      thread[FINISH_METADATA_PROC_KEY] = proc
+      self
+    end
+
+    FINISH_METADATA_PROC_KEY = :"llm.tracer.finish_metadata_proc"
+
+    ##
+    # Returns the current extra bag (metadata, inputs, outputs) for the current
+    # thread/trace. Used by subclasses; default returns empty hashes.
+    #
+    # @return [Hash] { metadata: {}, inputs: {}, outputs: {} }
+    def current_extra
+      {}
+    end
+
+    ##
+    # Returns and clears extra inputs for the next span. Called by the telemetry
+    # tracer when starting a span. Subclasses (e.g. Langsmith) override to
+    # return thread-local inputs; default returns {}.
+    #
+    # @return [Hash] Attribute key => value to set on the span at start
+    def consume_extra_inputs
+      {}
+    end
+
+    ##
+    # Returns and clears extra outputs for the current span. Called by the
+    # telemetry tracer when finishing a span. Subclasses override to return
+    # thread-local outputs; default returns {}.
+    #
+    # @return [Hash] Attribute key => value to set on the span at finish
+    def consume_extra_outputs
+      {}
+    end
+
+    ##
+    # Store per-request metadata (e.g. user_input) to be consumed by tracers
+    # when starting the next span. Used for plain-text input.value / output.value.
+    #
+    # @param [Hash] metadata e.g. { user_input: "the user question" }
+    # @return [nil]
+    def set_request_metadata(metadata)
+      return nil unless metadata && !metadata.empty?
+      key = thread_request_metadata_key
+      current = thread[key] || {}
+      thread[key] = current.merge(metadata.compact)
+      nil
+    end
+
+    ##
+    # Consume and clear per-request metadata. Called by the telemetry tracer at span start.
+    #
+    # @return [Hash]
+    def consume_request_metadata
+      key = thread_request_metadata_key
+      data = thread[key] || {}
+      thread[key] = nil
+      data
+    end
+
     private
 
+    def thread_request_metadata_key
+      @thread_request_metadata_key ||= :"llm.tracer.request_metadata.#{object_id}"
+    end
+
+    def thread
+      Thread.current
+    end
+
     ##
     # @return [String]
     def provider_name

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -10,6 +10,7 @@ module LLM
   require_relative "llm/prompt"
   require_relative "llm/schema"
   require_relative "llm/object"
+  require_relative "llm/model"
   require_relative "llm/version"
   require_relative "llm/utils"
   require_relative "llm/message"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.6.0
+  version: 4.8.0
 platform: ruby
 authors:
 - Antar Azri
@@ -223,6 +223,7 @@ files:
 - lib/llm/json_adapter.rb
 - lib/llm/message.rb
 - lib/llm/mime.rb
+- lib/llm/model.rb
 - lib/llm/multipart.rb
 - lib/llm/multipart/enumerator_io.rb
 - lib/llm/object.rb
@@ -240,6 +241,7 @@ files:
 - lib/llm/providers/anthropic/response_adapter/completion.rb
 - lib/llm/providers/anthropic/response_adapter/enumerable.rb
 - lib/llm/providers/anthropic/response_adapter/file.rb
+- lib/llm/providers/anthropic/response_adapter/models.rb
 - lib/llm/providers/anthropic/response_adapter/web_search.rb
 - lib/llm/providers/anthropic/stream_parser.rb
 - lib/llm/providers/deepseek.rb
@@ -271,6 +273,7 @@ files:
 - lib/llm/providers/ollama/response_adapter.rb
 - lib/llm/providers/ollama/response_adapter/completion.rb
 - lib/llm/providers/ollama/response_adapter/embedding.rb
+- lib/llm/providers/ollama/response_adapter/models.rb
 - lib/llm/providers/ollama/stream_parser.rb
 - lib/llm/providers/openai.rb
 - lib/llm/providers/openai/audio.rb
@@ -290,6 +293,7 @@ files:
 - lib/llm/providers/openai/response_adapter/enumerable.rb
 - lib/llm/providers/openai/response_adapter/file.rb
 - lib/llm/providers/openai/response_adapter/image.rb
+- lib/llm/providers/openai/response_adapter/models.rb
 - lib/llm/providers/openai/response_adapter/moderations.rb
 - lib/llm/providers/openai/response_adapter/responds.rb
 - lib/llm/providers/openai/response_adapter/web_search.rb
@@ -304,6 +308,7 @@ files:
 - lib/llm/schema.rb
 - lib/llm/schema/array.rb
 - lib/llm/schema/boolean.rb
+- lib/llm/schema/enum.rb
 - lib/llm/schema/integer.rb
 - lib/llm/schema/leaf.rb
 - lib/llm/schema/null.rb
@@ -317,6 +322,7 @@ files:
 - lib/llm/tool.rb
 - lib/llm/tool/param.rb
 - lib/llm/tracer.rb
+- lib/llm/tracer/langsmith.rb
 - lib/llm/tracer/logger.rb
 - lib/llm/tracer/null.rb
 - lib/llm/tracer/telemetry.rb