llm.rb 4.1.0 → 4.2.0

data/lib/llm/agent.rb

@@ -6,15 +6,10 @@ module LLM
   # reusable, preconfigured assistants with defaults for model,
   # tools, schema, and instructions.
   #
-  # @note
-  # Unlike {LLM::Bot LLM::Bot}, this class will automatically run
-  # tool calls for you.
-  #
-  # @note
-  #  Instructions are injected only on the first request.
-  #
-  # @note
-  #  This idea originally came from RubyLLM and was adapted to llm.rb.
+  # **Notes:**
+  # * Instructions are injected only on the first request.
+  # * An agent will automatically execute tool calls (unlike {LLM::Session LLM::Session}).
+  # * The idea originally came from RubyLLM and was adapted to llm.rb.
   #
   # @example
   #   class SystemAdmin < LLM::Agent
@@ -26,7 +21,7 @@ module LLM
   #
   #   llm = LLM.openai(key: ENV["KEY"])
   #   agent = SystemAdmin.new(llm)
-  #   agent.chat("Run 'date'")
+  #   agent.talk("Run 'date'")
   class Agent
     ##
     # Set or get the default model
@@ -85,7 +80,7 @@ module LLM
     def initialize(provider, params = {})
       defaults = {model: self.class.model, tools: self.class.tools, schema: self.class.schema}.compact
       @provider = provider
-      @bot = LLM::Bot.new(provider, defaults.merge(params))
+      @ses = LLM::Session.new(provider, defaults.merge(params))
       @instructions_applied = false
     end
 
@@ -100,19 +95,20 @@ module LLM
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
     #   agent = LLM::Agent.new(llm)
-    #   response = agent.chat("Hello, what is your name?")
+    #   response = agent.talk("Hello, what is your name?")
     #   puts response.choices[0].content
-    def chat(prompt, params = {})
+    def talk(prompt, params = {})
       i, max = 0, Integer(params.delete(:max_tool_rounds) || 10)
-      res = @bot.chat(apply_instructions(prompt), params)
-      until @bot.functions.empty?
+      res = @ses.talk(apply_instructions(prompt), params)
+      until @ses.functions.empty?
         raise LLM::ToolLoopError, "pending tool calls remain" if i >= max
-        res = @bot.chat @bot.functions.map(&:call), params
+        res = @ses.talk @ses.functions.map(&:call), params
         i += 1
       end
       @instructions_applied = true
       res
     end
+    alias_method :chat, :talk
 
     ##
     # Maintain a conversation via the responses API.
@@ -130,10 +126,10 @@ module LLM
     #   puts res.output_text
     def respond(prompt, params = {})
       i, max = 0, Integer(params.delete(:max_tool_rounds) || 10)
-      res = @bot.respond(apply_instructions(prompt), params)
-      until @bot.functions.empty?
+      res = @ses.respond(apply_instructions(prompt), params)
+      until @ses.functions.empty?
         raise LLM::ToolLoopError, "pending tool calls remain" if i >= max
-        res = @bot.respond @bot.functions.map(&:call), params
+        res = @ses.respond @ses.functions.map(&:call), params
         i += 1
       end
       @instructions_applied = true
@@ -143,26 +139,29 @@ module LLM
     ##
     # @return [LLM::Buffer<LLM::Message>]
     def messages
-      @bot.messages
+      @ses.messages
     end
 
     ##
     # @return [Array<LLM::Function>]
     def functions
-      @bot.functions
+      @ses.functions
     end
 
     ##
     # @return [LLM::Object]
     def usage
-      @bot.usage
+      @ses.usage
     end
 
     ##
-    # @return [LLM::Builder]
-    def build_prompt(&)
-      @bot.build_prompt(&)
+    # @param (see LLM::Session#prompt)
+    # @return (see LLM::Session#prompt)
+    # @see LLM::Session#prompt
+    def prompt(&b)
+      @ses.prompt(&b)
     end
+    alias_method :build_prompt, :prompt
 
     ##
     # @param [String] url
@@ -170,7 +169,7 @@ module LLM
     # @return [LLM::Object]
     #  Returns a tagged object
     def image_url(url)
-      @bot.image_url(url)
+      @ses.image_url(url)
     end
 
     ##
@@ -179,7 +178,7 @@ module LLM
     # @return [LLM::Object]
     #  Returns a tagged object
     def local_file(path)
-      @bot.local_file(path)
+      @ses.local_file(path)
     end
 
     ##
@@ -188,7 +187,21 @@ module LLM
     # @return [LLM::Object]
     #  Returns a tagged object
     def remote_file(res)
-      @bot.remote_file(res)
+      @ses.remote_file(res)
+    end
+
+    ##
+    # @return [LLM::Tracer]
+    #  Returns an LLM tracer
+    def tracer
+      @ses.tracer
+    end
+
+    ##
+    # Returns the model an Agent is actively using
+    # @return [String]
+    def model
+      @ses.model
     end
 
     private
@@ -196,17 +209,16 @@ module LLM
     def apply_instructions(prompt)
       instr = self.class.instructions
       return prompt unless instr
-      if LLM::Builder === prompt
+      if LLM::Prompt === prompt
         messages = prompt.to_a
-        builder = LLM::Builder.new(@provider) do |builder|
-          builder.system instr unless @instructions_applied
-          messages.each { |msg| builder.chat(msg.content, role: msg.role) }
-        end
-        builder.tap(&:call)
+        prompt = LLM::Prompt.new(@provider)
+        prompt.system instr unless @instructions_applied
+        messages.each { |msg| prompt.talk(msg.content, role: msg.role) }
+        prompt
       else
-        build_prompt do
-          _1.system instr unless @instructions_applied
-          _1.user prompt
+        prompt do
+          system instr unless @instructions_applied
+          user prompt
         end
       end
     end

data/lib/llm/bot.rb

@@ -2,7 +2,7 @@
 
 module LLM
   ##
-  # {LLM::Bot LLM::Bot} provides an object that can maintain a
+  # {LLM::Session LLM::Session} provides an object that can maintain a
   # conversation. A conversation can use the chat completions API
   # that all LLM providers support or the responses API that currently
   # only OpenAI supports.
@@ -11,20 +11,18 @@ module LLM
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm  = LLM.openai(key: ENV["KEY"])
-  #   bot  = LLM::Bot.new(llm)
-  #   url  = "https://upload.wikimedia.org/wikipedia/commons/c/c7/Lisc_lipy.jpg"
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   ses = LLM::Session.new(llm)
   #
-  #   prompt = bot.build_prompt do
-  #     it.system "Your task is to answer all user queries"
-  #     it.user ["Tell me about this URL", bot.image_url(url)]
-  #     it.user ["Tell me about this PDF", bot.local_file("handbook.pdf")]
+  #   prompt = LLM::Prompt.new(llm) do
+  #     system "Be concise and show your reasoning briefly."
+  #     user "If a train goes 60 mph for 1.5 hours, how far does it travel?"
+  #     user "Now double the speed for the same time."
   #   end
-  #   bot.chat(prompt)
   #
-  #   # The full conversation history is in bot.messages
-  #   bot.messages.each { print "[#{_1.role}] ", _1.content, "\n" }
-  class Bot
+  #   ses.talk(prompt)
+  #   ses.messages.each { |m| puts "[#{m.role}] #{m.content}" }
+  class Session
     ##
     # Returns an Enumerable for the messages in a conversation
     # @return [LLM::Buffer<LLM::Message>]
@@ -54,10 +52,10 @@ module LLM
     # @return [LLM::Response] Returns the LLM's response for this turn.
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
-    #   bot = LLM::Bot.new(llm)
-    #   response = bot.chat("Hello, what is your name?")
-    #   puts response.choices[0].content
-    def chat(prompt, params = {})
+    #   ses = LLM::Session.new(llm)
+    #   res = ses.talk("Hello, what is your name?")
+    #   puts res.messages[0].content
+    def talk(prompt, params = {})
       prompt, params, messages = fetch(prompt, params)
       params = params.merge(messages: [*@messages.to_a, *messages])
       params = @params.merge(params)
@@ -67,6 +65,7 @@ module LLM
       @messages.concat [res.choices[-1]]
       res
     end
+    alias_method :chat, :talk
 
     ##
     # Maintain a conversation via the responses API.
@@ -78,8 +77,8 @@ module LLM
     # @return [LLM::Response] Returns the LLM's response for this turn.
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
-    #   bot = LLM::Bot.new(llm)
-    #   res = bot.respond("What is the capital of France?")
+    #   ses = LLM::Session.new(llm)
+    #   res = ses.respond("What is the capital of France?")
     #   puts res.output_text
     def respond(prompt, params = {})
       prompt, params, messages = fetch(prompt, params)
@@ -107,8 +106,13 @@ module LLM
     def functions
       @messages
         .select(&:assistant?)
-        .flat_map(&:functions)
-        .select(&:pending?)
+        .flat_map do |msg|
+          fns = msg.functions.select(&:pending?)
+          fns.each do |fn|
+            fn.tracer = tracer
+            fn.model  = msg.model
+          end
+        end
     end
 
     ##
@@ -123,16 +127,24 @@ module LLM
     end
 
     ##
-    # Build a prompt
+    # Build a role-aware prompt for a single request.
+    #
+    # Prefer this method over {#build_prompt}. The older
+    # method name is kept for backward compatibility.
     # @example
-    #   prompt = bot.build_prompt do
-    #     it.system "Your task is to assist the user"
-    #     it.user "Hello, can you assist me?"
+    #   prompt = ses.prompt do
+    #     system "Your task is to assist the user"
+    #     user "Hello, can you assist me?"
     #   end
-    #   bot.chat(prompt)
-    def build_prompt(&)
-      LLM::Builder.new(@provider, &).tap(&:call)
+    #   ses.talk(prompt)
+    # @param [Proc] b
+    #  A block that composes messages. If it takes one argument,
+    #  it receives the prompt object. Otherwise it runs in prompt context.
+    # @return [LLM::Prompt]
+    def prompt(&b)
+      LLM::Prompt.new(@provider, &b)
     end
+    alias_method :build_prompt, :prompt
 
     ##
     # Recongize an object as a URL to an image
@@ -164,14 +176,31 @@ module LLM
       LLM::Object.from(value: res, kind: :remote_file)
     end
 
+    ##
+    # @return [LLM::Tracer]
+    #  Returns an LLM tracer
+    def tracer
+      @provider.tracer
+    end
+
+    ##
+    # Returns the model a Session is actively using
+    # @return [String]
+    def model
+      messages.find(&:assistant?)&.model || @params[:model]
+    end
+
     private
 
     def fetch(prompt, params)
-      return [prompt, params, []] unless LLM::Builder === prompt
+      return [prompt, params, []] unless LLM::Prompt === prompt
       messages = prompt.to_a
       prompt = messages.shift
       params.merge!(role: prompt.role)
       [prompt.content, params, messages]
     end
   end
+
+  # Backward-compatible alias
+  Bot = Session
 end

data/lib/llm/function/tracing.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Tracing LLM::Function::Tracing} module patches
+  # an LLM function (or tool) in order to add tracing support.
+  module Tracing
+    def call(...)
+      return super unless @tracer
+      span = @tracer.on_tool_start(id:, name:, arguments:, model:)
+      result = super
+      @tracer.on_tool_finish(result:, span:)
+      result
+    rescue => ex
+      @tracer.on_tool_error(ex:, span:)
+      raise(ex)
+    end
+  end
+end

data/lib/llm/function.rb

@@ -29,6 +29,9 @@
 #     end
 #   end
 class LLM::Function
+  require_relative "function/tracing"
+  prepend LLM::Function::Tracing
+
   class Return < Struct.new(:id, :name, :value)
   end
 
@@ -42,6 +45,16 @@ class LLM::Function
   # @return [Array, nil]
   attr_accessor :arguments
 
+  ##
+  # Returns a tracer, or nil
+  # @return [LLM::Tracer, nil]
+  attr_accessor :tracer
+
+  ##
+  # Returns a model name, or nil
+  # @return [String, nil]
+  attr_accessor :model
+
   ##
   # @param [String] name The function name
   # @yieldparam [LLM::Function] self The function object
@@ -116,9 +129,9 @@ class LLM::Function
   # Returns a value that communicates that the function call was cancelled
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   bot = LLM::Bot.new(llm, tools: [fn1, fn2])
-  #   bot.chat "I want to run the functions"
-  #   bot.chat bot.functions.map(&:cancel)
+  #   ses = LLM::Session.new(llm, tools: [fn1, fn2])
+  #   ses.talk "I want to run the functions"
+  #   ses.talk ses.functions.map(&:cancel)
   # @return [LLM::Function::Return]
   def cancel(reason: "function call cancelled")
     Return.new(id, name, {cancelled: true, reason:})

data/lib/llm/json_adapter.rb

@@ -63,7 +63,7 @@ module LLM
     # @return (see JSONAdapter#dump)
     def self.dump(obj)
       require "oj" unless defined?(::Oj)
-      ::Oj.dump(obj)
+      ::Oj.dump(obj, mode: :compat)
     end
 
     ##

data/lib/llm/message.rb

@@ -136,6 +136,13 @@ module LLM
     end
     alias_method :token_usage, :usage
 
+    ##
+    # @return [String, nil]
+    #  Returns the model associated with a message
+    def model
+      response&.model
+    end
+
     ##
     # Returns a string representation of the message
     # @return [String]

data/lib/llm/prompt.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+##
+# {LLM::Prompt LLM::Prompt} is a small object for composing
+# a single request from multiple role-aware messages.
+# A prompt is not just a string. It is an ordered chain of
+# messages with explicit roles (for example `system` and `user`).
+# Use {LLM::Session#prompt} when building a prompt inside a session.
+# Use `LLM::Prompt.new(provider)` directly when you want to construct
+# or pass prompt objects around explicitly.
+#
+# @example
+#   llm = LLM.openai(key: ENV["KEY"])
+#   ses = LLM::Session.new(llm)
+#
+#   prompt = ses.prompt do
+#     system "Your task is to assist the user"
+#     user "Hello. Can you assist me?"
+#   end
+#
+#   res = ses.talk(prompt)
+class LLM::Prompt
+  ##
+  # @param [LLM::Provider] provider
+  #  A provider used to resolve provider-specific role names.
+  # @param [Proc] b
+  #  A block that composes messages. If the block takes one argument,
+  #  it receives the prompt object. Otherwise the block runs in the
+  #  prompt context via `instance_eval`.
+  def initialize(provider, &b)
+    @provider = provider
+    @buffer = []
+    unless b.nil?
+      (b.arity == 1) ? b.call(self) : instance_eval(&b)
+    end
+  end
+
+  ##
+  # @param [String] content
+  #  The message
+  # @param [Symbol] role
+  #  The role (eg user, system)
+  # @return [void]
+  def talk(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
+  alias_method :chat, :talk
+
+  ##
+  # @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<LLM::Message>]
+  #  Returns the prompt messages in order.
+  def to_a
+    @buffer.dup
+  end
+end

data/lib/llm/provider.rb

@@ -37,6 +37,7 @@ class LLM::Provider
     @timeout = timeout
     @ssl = ssl
     @client = persistent ? persistent_client : transient_client
+    @tracer = LLM::Tracer::Null.new(self)
     @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
   end
 
@@ -45,7 +46,7 @@ class LLM::Provider
   # @return [String]
   # @note The secret key is redacted in inspect for security reasons
   def inspect
-    "#<#{self.class.name}:0x#{object_id.to_s(16)} @key=[REDACTED] @client=#{@client.inspect}>"
+    "#<#{self.class.name}:0x#{object_id.to_s(16)} @key=[REDACTED] @client=#{@client.inspect} @tracer=#{@tracer.inspect}>"
   end
 
   ##
@@ -69,7 +70,7 @@ class LLM::Provider
   #   llm = LLM.openai(key: ENV["KEY"])
   #   messages = [{role: "system", content: "Your task is to answer all of my questions"}]
   #   res = llm.complete("5 + 2 ?", messages:)
-  #   print "[#{res.choices[0].role}]", res.choices[0].content, "\n"
+  #   print "[#{res.messages[0].role}]", res.messages[0].content, "\n"
   # @param [String] prompt
   #  The input prompt to be completed
   # @param [Hash] params
@@ -91,10 +92,10 @@ class LLM::Provider
   # Starts a new chat powered by the chat completions API
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
-  # @return [LLM::Bot]
+  # @return [LLM::Session]
   def chat(prompt, params = {})
     role = params.delete(:role)
-    LLM::Bot.new(self, params).chat(prompt, role:)
+    LLM::Session.new(self, params).talk(prompt, role:)
   end
 
   ##
@@ -102,10 +103,10 @@ class LLM::Provider
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
-  # @return [LLM::Bot]
+  # @return [LLM::Session]
   def respond(prompt, params = {})
     role = params.delete(:role)
-    LLM::Bot.new(self, params).respond(prompt, role:)
+    LLM::Session.new(self, params).respond(prompt, role:)
   end
 
   ##
@@ -252,6 +253,30 @@ class LLM::Provider
     :developer
   end
 
+  ##
+  # @return [LLM::Tracer]
+  #  Returns an LLM tracer
+  def tracer
+    @tracer
+  end
+
+  ##
+  # Set the tracer
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   llm.tracer = LLM::Tracer::Logger.new(llm, path: "/path/to/log.txt")
+  #   # ...
+  # @param [LLM::Tracer] tracer
+  #  A tracer
+  # @return [void]
+  def tracer=(tracer)
+    @tracer = if tracer.nil?
+      LLM::Tracer::Null.new(self)
+    else
+      tracer
+    end
+  end
+
   private
 
   attr_reader :client, :base_uri, :host, :port, :timeout, :ssl
@@ -303,7 +328,8 @@ class LLM::Provider
   # @raise [SystemCallError]
   #  When there is a network error at the operating system level
   # @return [Net::HTTPResponse]
-  def execute(request:, stream: nil, stream_parser: self.stream_parser, &b)
+  def execute(request:, operation:, stream: nil, stream_parser: self.stream_parser, model: nil, &b)
+    span = @tracer.on_request_start(operation:, model:)
     args = (Net::HTTP === client) ? [request] : [URI.join(base_uri, request.path), request]
     res = if stream
       client.request(*args) do |res|
@@ -323,18 +349,20 @@ class LLM::Provider
       b ? client.request(*args) { (Net::HTTPSuccess === _1) ? b.call(_1) : _1 } :
           client.request(*args)
     end
-    handle_response(res)
+    [handle_response(res, span), span]
   end
 
   ##
   # Handles the response from a request
   # @param [Net::HTTPResponse] res
   #  The response to handle
+  # @param [Object, nil] span
+  #  The span
   # @return [Net::HTTPResponse]
-  def handle_response(res)
+  def handle_response(res, span)
     case res
     when Net::HTTPOK then res.body = parse_response(res)
-    else error_handler.new(res).raise_error!
+    else error_handler.new(@tracer, span, res).raise_error!
     end
     res
   end
@@ -375,4 +403,22 @@ class LLM::Provider
       end
     end
   end
+
+  ##
+  # @return [Hash<Symbol, LLM::Tracer>]
+  def tracers
+    self.class.tracers
+  end
+
+  ##
+  # Finalizes tracing after a response has been adapted/wrapped.
+  # @param [String] operation
+  # @param [String, nil] model
+  # @param [LLM::Response] res
+  # @param [Object, nil] span
+  # @return [LLM::Response]
+  def finish_trace(operation:, res:, model: nil, span: nil)
+    @tracer.on_request_finish(operation:, model:, res:, span:)
+    res
+  end
 end

data/lib/llm/providers/anthropic/error_handler.rb

@@ -10,10 +10,21 @@ class LLM::Anthropic
     attr_reader :res
 
     ##
+    # @return [Object, nil]
+    #  The span
+    attr_reader :span
+
+    ##
+    # @param [LLM::Tracer] tracer
+    #  The tracer
+    # @param [Object, nil] span
+    #  The span
     # @param [Net::HTTPResponse] res
     #  The response from the server
     # @return [LLM::Anthropic::ErrorHandler]
-    def initialize(res)
+    def initialize(tracer, span, res)
+      @tracer = tracer
+      @span = span
       @res = res
     end
 
@@ -21,15 +32,26 @@ class LLM::Anthropic
     # @raise [LLM::Error]
     #  Raises a subclass of {LLM::Error LLM::Error}
     def raise_error!
+      ex = error
+      @tracer.on_request_error(ex:, span:)
+    ensure
+      raise(ex)
+    end
+
+    private
+
+    ##
+    # @return [LLM::Error]
+    def error
       case res
       when Net::HTTPServerError
-        raise LLM::ServerError.new { _1.response = res }, "Server error"
+        LLM::ServerError.new("Server error").tap { _1.response = res }
       when Net::HTTPUnauthorized
-        raise LLM::UnauthorizedError.new { _1.response = res }, "Authentication error"
+        LLM::UnauthorizedError.new("Authentication error").tap { _1.response = res }
       when Net::HTTPTooManyRequests
-        raise LLM::RateLimitError.new { _1.response = res }, "Too many requests"
+        LLM::RateLimitError.new("Too many requests").tap { _1.response = res }
       else
-        raise LLM::Error.new { _1.response = res }, "Unexpected response"
+        LLM::Error.new("Unexpected response").tap { _1.response = res }
       end
     end
   end