llm.rb 4.0.0 → 4.2.0

data/lib/llm/schema.rb

@@ -9,14 +9,26 @@
 # @see https://json-schema.org/ JSON Schema Specification
 # @see https://tour.json-schema.org/ JSON Schema Tour
 #
-# @example
+# @example JavaScript-style
 #  schema = LLM::Schema.new
 #  schema.object({
 #    name: schema.string.enum("John", "Jane").required,
 #    age: schema.integer.required,
-#    hobbies: schema.array(schema.string, schema.null).required,
+#    hobbies: schema.array(schema.string).required,
 #    address: schema.object({street: schema.string}).required,
 #  })
+#
+# @example Ruby-style
+#  class Address < LLM::Schema
+#    property :street, String, "Street address", required: true
+#  end
+#
+#  class Person < LLM::Schema
+#    property :name, String, "Person's name", required: true
+#    property :age, Integer, "Person's age", required: true
+#    property :hobbies, Array[String], "Person's hobbies", required: true
+#    property :address, Address, "Person's address", required: true
+#  end
 class LLM::Schema
   require_relative "schema/version"
   require_relative "schema/leaf"
@@ -50,6 +62,8 @@ class LLM::Schema
     lock do
       if LLM::Schema::Leaf === type
         prop = type
+      elsif Class === type && type.respond_to?(:object)
+        prop = type.object
       else
         target = type.name.split("::").last.downcase
         prop = schema.public_send(target)

data/lib/llm/server_tool.rb

@@ -9,9 +9,9 @@
 # @example
 #   #!/usr/bin/env ruby
 #   llm = LLM.gemini ENV["KEY"]
-#   bot = LLM::Bot.new(llm, tools: [LLM::ServerTool.new(:google_search)])
-#   bot.chat("Summarize today's news", role: :user)
-#   print bot.messages.find(&:assistant?).content, "\n"
+#   ses = LLM::Session.new(llm, tools: [LLM::ServerTool.new(:google_search)])
+#   ses.talk("Summarize today's news", role: :user)
+#   print ses.messages.find(&:assistant?).content, "\n"
 class LLM::ServerTool < Struct.new(:name, :options, :provider)
   ##
   # @return [String]

data/lib/llm/session.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "bot"

data/lib/llm/tracer/logger.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Tracer::Logger LLM::Tracer::Logger} class provides a
+  # tracer that provides logging facilities through Ruby's
+  # standard library.
+  #
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   # Log to a file
+  #   llm.tracer = LLM::Tracer::Logger.new(llm, path: "/tmp/log.txt")
+  #   # Log to $stdout (default)
+  #   llm.tracer = LLM::Tracer::Logger.new(llm, io: $stdout)
+  class Tracer::Logger < Tracer
+    ##
+    # @param (see LLM::Tracer#initialize)
+    def initialize(provider, options = {})
+      super
+      setup!(**options)
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_start)
+    # @return [void]
+    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)
+    # @return [void]
+    def on_request_finish(operation:, res:, model: nil, **)
+      case operation
+      when "chat" then finish_chat(operation:, res:, model:)
+      when "retrieval" then finish_retrieval(operation:, res:)
+      else nil
+      end
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_request_error)
+    # @return [void]
+    def on_request_error(ex:, **)
+      @logger.error(
+        tracer: "llm.rb (logger)",
+        event: "request.error",
+        provider: provider_name,
+        error_class: ex.class.to_s,
+        error_message: ex.message
+      )
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_start)
+    # @return [void]
+    def on_tool_start(id:, name:, arguments:, model:, **)
+      @logger.info(
+        tracer: "llm.rb (logger)",
+        event: "tool.start",
+        provider: provider_name,
+        operation: "execute_tool",
+        tool_id: id,
+        tool_name: name,
+        tool_arguments: arguments,
+        model:
+      )
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_finish)
+    # @return [void]
+    def on_tool_finish(result:, **)
+      @logger.info(
+        tracer: "llm.rb (logger)",
+        event: "tool.finish",
+        provider: provider_name,
+        operation: "execute_tool",
+        tool_id: result.id,
+        tool_name: result.name,
+        tool_result: result.value
+      )
+    end
+
+    ##
+    # @param (see LLM::Tracer#on_tool_error)
+    # @return [void]
+    def on_tool_error(ex:, **)
+      @logger.error(
+        tracer: "llm.rb (logger)",
+        event: "tool.error",
+        provider: provider_name,
+        operation: "execute_tool",
+        error_class: ex.class.to_s,
+        error_message: ex.message
+      )
+    end
+
+    private
+
+    ##
+    # @api private
+    def setup!(path: nil, io: $stdout)
+      require "logger" unless defined?(::Logger)
+      @logger = ::Logger.new(path || io)
+    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_service_tier: res.service_tier,
+          openai_system_fingerprint: res.system_fingerprint
+        }.compact
+      when "retrieval"
+        {
+          openai_vector_store_search_result_count: res.size,
+          openai_vector_store_search_has_more: res.has_more
+        }.compact
+      else {}
+      end
+    end
+
+    ##
+    # start_*
+
+    def start_chat(operation:, model:)
+      @logger.info(
+        tracer: "llm.rb (logger)",
+        event: "request.start",
+        provider: provider_name,
+        operation:,
+        model:
+      )
+    end
+
+    def start_retrieval(operation:)
+      @logger.info(
+        tracer: "llm.rb (logger)",
+        event: "request.start",
+        provider: provider_name,
+        operation:
+      )
+    end
+
+    ##
+    # finish_*
+
+    def finish_chat(operation:, model:, res:)
+      @logger.info(
+        tracer: "llm.rb (logger)",
+        event: "request.finish",
+        provider: provider_name,
+        operation:,
+        model:,
+        response_id: res.id,
+        input_tokens: res.usage.input_tokens,
+        output_tokens: res.usage.output_tokens,
+        **finish_attributes(operation, res)
+      )
+    end
+
+    def finish_retrieval(operation:, res:)
+      @logger.info(
+        tracer: "llm.rb (logger)",
+        event: "request.finish",
+        provider: provider_name,
+        operation:,
+        **finish_attributes(operation, res)
+      )
+    end
+  end
+end

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.0.0"
+  VERSION = "4.2.0"
 end