llm.rb 4.1.0 → 4.2.0

data/lib/llm/tracer/null.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # A no-op tracer that ignores all tracing callbacks.
+  class Tracer::Null < Tracer
+    ##
+    # @param (see LLM::Tracer#on_request_start)
+    # @return [nil]
+    def on_request_start(**)
+      nil
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_finish)
+    # @return [nil]
+    def on_request_finish(**)
+      nil
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_error)
+    # @return [nil]
+    def on_request_error(**)
+      nil
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_start)
+    # @return [nil]
+    def on_tool_start(**)
+      nil
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_finish)
+    # @return [nil]
+    def on_tool_finish(**)
+      nil
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_error)
+    # @return [nil]
+    def on_tool_error(**)
+      nil
+    end
+  end
+end

data/lib/llm/tracer/telemetry.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+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).
+  #
+  # @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)
+  #
+  # @example InMemory export
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #   require "pp"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   llm.tracer = LLM::Tracer::Telemetry.new(llm)
+  #
+  #   ses = LLM::Session.new(llm)
+  #   ses.talk "hello"
+  #   ses.talk "how are you?"
+  #   ses.tracer.spans.each { |span| pp span }
+  #
+  # @example OTLP export
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #   require "opentelemetry-exporter-otlp"
+  #
+  #   endpoint = "https://api.smith.langchain.com/otel/v1/traces"
+  #   exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint:)
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   llm.tracer = LLM::Tracer::Telemetry.new(llm, exporter:)
+  #
+  #   ses = LLM::Session.new(llm)
+  #   ses.talk "hello"
+  #   ses.talk "how are you?"
+  class Tracer::Telemetry < Tracer
+    ##
+    # param [LLM::Provider] provider
+    #  An LLM provider
+    # @return [LLM::Tracer::Telemetry]
+    def initialize(provider, options = {})
+      super
+      @exporter = options.delete(:exporter)
+      setup!
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_start)
+    def on_request_start(operation:, model: nil)
+      case operation
+      when "chat" then start_chat(operation:, model:)
+      when "retrieval" then start_retrieval(operation:)
+      else nil
+      end
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_finish)
+    def on_request_finish(operation:, res:, model: nil, span: nil)
+      return nil unless span
+      case operation
+      when "chat" then finish_chat(operation:, model:, res:, span:)
+      when "retrieval" then finish_retrieval(operation:, res:, span:)
+      else nil
+      end
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_error)
+    def on_request_error(ex:, span:)
+      return nil unless span
+      attributes = {"error.type" => ex.class.to_s}.compact
+      attributes.each { span.set_attribute(_1, _2) }
+      span.add_event("gen_ai.request.finish")
+      span.status = ::OpenTelemetry::Trace::Status.error(ex.message)
+      span.tap(&:finish)
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_start)
+    # @return (see LLM::Tracer#on_tool_start)
+    def on_tool_start(id:, name:, arguments:, model:)
+      attributes = {
+        "gen_ai.operation.name" => "execute_tool",
+        "gen_ai.request.model" => model,
+        "gen_ai.tool.call.id" => id,
+        "gen_ai.tool.name" => name,
+        "gen_ai.tool.call.arguments" => LLM.json.dump(arguments),
+        "gen_ai.provider.name" => provider_name,
+        "server.address" => provider_host,
+        "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.add_event("gen_ai.tool.start")
+      span
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_finish)
+    # @return (see LLM::Tracer#on_tool_finish)
+    def on_tool_finish(result:, span:)
+      return nil unless span
+      attributes = {
+        "gen_ai.tool.call.id" => result.id,
+        "gen_ai.tool.name" => result.name,
+        "gen_ai.tool.call.result" => LLM.json.dump(result.value)
+      }.compact
+      attributes.each { span.set_attribute(_1, _2) }
+      span.add_event("gen_ai.tool.finish")
+      span.tap(&:finish)
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_error)
+    # @return (see LLM::Tracer#on_tool_error)
+    def on_tool_error(ex:, span:)
+      return nil unless span
+      attributes = {"error.type" => ex.class.to_s}.compact
+      attributes.each { span.set_attribute(_1, _2) }
+      span.add_event("gen_ai.tool.finish")
+      span.status = ::OpenTelemetry::Trace::Status.error(ex.message)
+      span.tap(&:finish)
+    end
+
+    ##
+    # @note
+    # This method returns an empty array for exporters that
+    # do not implement 'finished_spans' such as the OTLP
+    # exporter
+    # @return [Array<OpenTelemetry::SDK::Trace::SpanData>]
+    def spans
+      return [] unless @exporter.respond_to?(:finished_spans)
+      flush!
+      @exporter.finished_spans
+    end
+
+    ##
+    # Flushes queued telemetry to the configured exporter.
+    # @note
+    #  Exports are batched in the background by default.
+    #  Long-lived processes usually do not need to call this method.
+    #  Short-lived scripts should call {#flush!} before exit to reduce
+    #  the risk of losing spans that are still buffered.
+    # @return (see LLM::Tracer#flush!)
+    def flush!
+      @tracer_provider.force_flush
+      nil
+    end
+
+    private
+
+    ##
+    # @api private
+    def setup!
+      require "opentelemetry/sdk" unless defined?(OpenTelemetry)
+      @exporter ||= OpenTelemetry::SDK::Trace::Export::InMemorySpanExporter.new
+      processor = OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(@exporter)
+      @tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
+      @tracer_provider.add_span_processor(processor)
+      @tracer = @tracer_provider.tracer("llm.rb", LLM::VERSION)
+    end
+
+    ##
+    # @param [String] operation
+    # @param [LLM::Response] res
+    # @api private
+    def finish_attributes(operation, res)
+      case @provider.class.to_s
+      when "LLM::OpenAI" then openai_attributes(operation, res)
+      else {}
+      end
+    end
+
+    ##
+    # @param [String] operation
+    # @param [LLM::Response] res
+    # @api private
+    def openai_attributes(operation, res)
+      case operation
+      when "chat"
+        {
+          "openai.response.service_tier" => res.service_tier,
+          "openai.response.system_fingerprint" => res.system_fingerprint
+        }
+      when "retrieval"
+        {
+          "openai.vector_store.search.result_count" => res.size,
+          "openai.vector_store.search.has_more" => res.has_more
+        }
+      else {}
+      end
+    end
+
+    ##
+    # start_*
+
+    def start_chat(operation:, model:)
+      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
+      span_name = [operation, model].compact.join(" ")
+      span = @tracer.start_span(span_name.empty? ? "gen_ai.request" : span_name, kind: :client, attributes:)
+      span.add_event("gen_ai.request.start")
+      span
+    end
+
+    def start_retrieval(operation:)
+      attributes = {
+        "gen_ai.operation.name" => operation,
+        "gen_ai.provider.name" => provider_name,
+        "server.address" => provider_host,
+        "server.port" => provider_port
+      }.compact
+      span = @tracer.start_span(operation, kind: :client, attributes:)
+      span.add_event("gen_ai.request.start")
+      span
+    end
+
+    ##
+    # finish_*
+
+    def finish_chat(operation:, model:, res:, span:)
+      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
+      }.merge!(finish_attributes(operation, res)).compact
+      attributes.each { span.set_attribute(_1, _2) }
+      span.add_event("gen_ai.request.finish")
+      span.tap(&:finish)
+    end
+
+    def finish_retrieval(operation:, res:, span:)
+      attributes = {
+        "gen_ai.operation.name" => operation
+      }.merge!(finish_attributes(operation, res)).compact
+      attributes.each { span.set_attribute(_1, _2) }
+      span.add_event("gen_ai.request.finish")
+      span.tap(&:finish)
+    end
+  end
+end

data/lib/llm/tracer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Tracer LLM::Tracer} is the superclass of all
+  # LLM tracers. It can be helpful for implementing instrumentation
+  # and hooking into the lifecycle of an LLM request. See
+  # {LLM::Tracer::Telemetry LLM::Tracer::Telemetry}, and
+  # {LLM::Tracer::Logger LLM::Tracer::Logger} for example
+  # tracer implementations.
+  class Tracer
+    require_relative "tracer/logger"
+    require_relative "tracer/telemetry"
+    require_relative "tracer/null"
+
+    ##
+    # @param [LLM::Provider] provider
+    #  A provider
+    # @param [Hash] options
+    #  A hash of options
+    def initialize(provider, options = {})
+      @provider = provider
+      @options = {}
+    end
+
+    ##
+    # Called before an LLM provider request is executed.
+    # @param [String] operation
+    # @param [String] model
+    # @return [void]
+    def on_request_start(operation:, model: 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
+    # @return [void]
+    def on_request_finish(operation:, res:, model: nil, span: nil)
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # Called when an LLM provider request fails.
+    # @param [LLM::Error] ex
+    # @param [Object, nil] span
+    # @return [void]
+    def on_request_error(ex:, span:)
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # Called before a local tool/function executes.
+    # @param [String] id
+    #  The tool call ID assigned by the model/provider
+    # @param [String] name
+    #  The tool (function) name.
+    # @param [Hash] arguments
+    #  The parsed tool arguments.
+    # @param [String] model
+    #  The model name
+    # @return [void]
+    def on_tool_start(id:, name:, arguments:, model:)
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # Called after a local tool/function succeeds.
+    # @param [LLM::Function::Return] result
+    #  The tool return object.
+    # @param [Object, nil] span
+    #  The span/context object returned by {#on_tool_start}.
+    # @return [void]
+    def on_tool_finish(result:, span:)
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # Called when a local tool/function raises.
+    # @param [Exception] ex
+    #  The raised error.
+    # @param [Object, nil] span
+    #  The span/context object returned by {#on_tool_start}.
+    # @return [void]
+    def on_tool_error(ex:, span:)
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} @provider=#{@provider.class} @tracer=#{@tracer.inspect}>"
+    end
+
+    ##
+    # @return [Array]
+    def spans
+      []
+    end
+
+    ##
+    # Flush the tracer
+    # @note
+    #  This method is only implemented by the {LLM::Tracer::Telemetry} tracer.
+    #  It is a noop for other tracers.
+    # @return [nil]
+    def flush!
+      nil
+    end
+
+    private
+
+    ##
+    # @return [String]
+    def provider_name
+      @provider.class.name.split("::").last.downcase
+    end
+
+    ##
+    # @return [String]
+    def provider_host
+      @provider.instance_variable_get(:@host)
+    end
+
+    ##
+    # @return [String]
+    def provider_port
+      @provider.instance_variable_get(:@port)
+    end
+  end
+end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -3,10 +3,11 @@
 module LLM
   require "stringio"
   require_relative "llm/json_adapter"
+  require_relative "llm/tracer"
   require_relative "llm/error"
   require_relative "llm/contract"
   require_relative "llm/usage"
-  require_relative "llm/builder"
+  require_relative "llm/prompt"
   require_relative "llm/schema"
   require_relative "llm/object"
   require_relative "llm/version"
@@ -17,7 +18,7 @@ module LLM
   require_relative "llm/multipart"
   require_relative "llm/file"
   require_relative "llm/provider"
-  require_relative "llm/bot"
+  require_relative "llm/session"
   require_relative "llm/agent"
   require_relative "llm/buffer"
   require_relative "llm/function"
@@ -35,7 +36,7 @@ module LLM
   ##
   # Returns the JSON adapter used by the library
   # @return [Class]
-  #  Returns a class that responds to +dump+ and +load+
+  #  Returns a class that responds to `dump` and `load`
   def json
     @json ||= JSONAdapter::JSON
   end

data/llm.gemspec

@@ -21,7 +21,8 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.2.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/llmrb/llm"
+  spec.metadata["source_code_uri"] = "https://github.com/llmrb/llm.rb"
+  spec.metadata["documentation_uri"] = "https://0x1eef.github.io/x/llm.rb"
 
   spec.files = Dir[
     "README.md", "LICENSE",
@@ -41,4 +42,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "vcr", "~> 6.0"
   spec.add_development_dependency "dotenv", "~> 2.8"
   spec.add_development_dependency "net-http-persistent", "~> 4.0"
+  spec.add_development_dependency "opentelemetry-sdk", "~> 1.10"
+  spec.add_development_dependency "logger", "~> 1.7"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Antar Azri
@@ -164,6 +164,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 description: llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
   includes OpenAI, Gemini, Anthropic, xAI (grok), zAI, DeepSeek, Ollama, and LlamaCpp.
   The toolkit includes full support for chat, streaming, tool calling, audio, images,
@@ -181,7 +209,6 @@ files:
 - lib/llm/agent.rb
 - lib/llm/bot.rb
 - lib/llm/buffer.rb
-- lib/llm/builder.rb
 - lib/llm/client.rb
 - lib/llm/contract.rb
 - lib/llm/contract/completion.rb
@@ -192,6 +219,7 @@ files:
 - lib/llm/eventstream/parser.rb
 - lib/llm/file.rb
 - lib/llm/function.rb
+- lib/llm/function/tracing.rb
 - lib/llm/json_adapter.rb
 - lib/llm/message.rb
 - lib/llm/mime.rb
@@ -200,6 +228,7 @@ files:
 - lib/llm/object.rb
 - lib/llm/object/builder.rb
 - lib/llm/object/kernel.rb
+- lib/llm/prompt.rb
 - lib/llm/provider.rb
 - lib/llm/providers/anthropic.rb
 - lib/llm/providers/anthropic/error_handler.rb
@@ -283,8 +312,13 @@ files:
 - lib/llm/schema/string.rb
 - lib/llm/schema/version.rb
 - lib/llm/server_tool.rb
+- lib/llm/session.rb
 - lib/llm/tool.rb
 - lib/llm/tool/param.rb
+- lib/llm/tracer.rb
+- lib/llm/tracer/logger.rb
+- lib/llm/tracer/null.rb
+- lib/llm/tracer/telemetry.rb
 - lib/llm/usage.rb
 - lib/llm/utils.rb
 - lib/llm/version.rb
@@ -294,7 +328,8 @@ licenses:
 - 0BSD
 metadata:
   homepage_uri: https://github.com/llmrb/llm
-  source_code_uri: https://github.com/llmrb/llm
+  source_code_uri: https://github.com/llmrb/llm.rb
+  documentation_uri: https://0x1eef.github.io/x/llm.rb
 rdoc_options: []
 require_paths:
 - lib

data/lib/llm/builder.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-##
-# The {LLM::Builder LLM::Builder} class can build a collection
-# of messages that can be sent in a single request.
-#
-# @note
-# This API is not meant to be used directly.
-#
-# @example
-#   llm = LLM.openai(key: ENV["KEY"])
-#   bot = LLM::Bot.new(llm)
-#   prompt = bot.build_prompt do
-#     it.system "Your task is to assist the user"
-#     it.user "Hello. Can you assist me?"
-#   end
-#   res = bot.chat(prompt)
-class LLM::Builder
-  ##
-  # @param [Proc] evaluator
-  #  The evaluator
-  def initialize(provider, &evaluator)
-    @provider = provider
-    @buffer = []
-    @evaluator = evaluator
-  end
-
-  ##
-  # @return [void]
-  def call
-    @evaluator.call(self)
-  end
-
-  ##
-  # @param [String] content
-  #  The message
-  # @param [Symbol] role
-  #  The role (eg user, system)
-  # @return [void]
-  def chat(content, role: @provider.user_role)
-    role = case role.to_sym
-    when :system then @provider.system_role
-    when :user then @provider.user_role
-    when :developer then @provider.developer_role
-    else role
-    end
-    @buffer << LLM::Message.new(role, content)
-  end
-
-  ##
-  # @param [String] content
-  #  The message content
-  # @return [void]
-  def user(content)
-    chat(content, role: @provider.user_role)
-  end
-
-  ##
-  # @param [String] content
-  #  The message content
-  # @return [void]
-  def system(content)
-    chat(content, role: @provider.system_role)
-  end
-
-  ##
-  # @param [String] content
-  #  The message content
-  # @return [void]
-  def developer(content)
-    chat(content, role: @provider.developer_role)
-  end
-
-  ##
-  # @return [Array]
-  def to_a
-    @buffer.dup
-  end
-end