llm.rb 4.1.0 → 4.3.0

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.3.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

@@ -16,12 +16,13 @@ Gem::Specification.new do |spec|
   SUMMARY
 
   spec.description = spec.summary
-  spec.homepage = "https://github.com/llmrb/llm"
   spec.license = "0BSD"
   spec.required_ruby_version = ">= 3.2.0"
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/llmrb/llm"
+  spec.homepage = "https://github.com/llmrb/llm.rb"
+  spec.metadata["homepage_uri"] = "https://github.com/llmrb/llm.rb"
+  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.3.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,18 +312,25 @@ files:
 - lib/llm/schema/string.rb
 - lib/llm/schema/version.rb
 - lib/llm/server_tool.rb
+- lib/llm/session.rb
+- lib/llm/session/deserializer.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
 - llm.gemspec
-homepage: https://github.com/llmrb/llm
+homepage: https://github.com/llmrb/llm.rb
 licenses:
 - 0BSD
 metadata:
-  homepage_uri: https://github.com/llmrb/llm
-  source_code_uri: https://github.com/llmrb/llm
+  homepage_uri: https://github.com/llmrb/llm.rb
+  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