llm.rb 4.1.0 → 4.3.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,25 +187,54 @@ 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
 
+    ##
+    # @param (see LLM::Session#serialize)
+    # @return (see LLM::Session#serialize)
+    def serialize(**kw)
+      @ses.serialize(**kw)
+    end
+    alias_method :save, :serialize
+
+    ##
+    # @param (see LLM::Session#deserialize)
+    # @return (see LLM::Session#deserialize)
+    def deserialize(**kw)
+      @ses.deserialize(**kw)
+    end
+    alias_method :restore, :deserialize
+
     private
 
     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,21 @@ 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
+    require_relative "session/deserializer"
+    include Deserializer
+
     ##
     # Returns an Enumerable for the messages in a conversation
     # @return [LLM::Buffer<LLM::Message>]
@@ -54,19 +55,22 @@ 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)
       res = @provider.complete(prompt, params)
-      @messages.concat [LLM::Message.new(params[:role] || :user, prompt)]
+      role = params[:role] || @provider.user_role
+      role = @provider.tool_role if params[:role].nil? && [*prompt].grep(LLM::Function::Return).any?
+      @messages.concat [LLM::Message.new(role, prompt)]
       @messages.concat messages
       @messages.concat [res.choices[-1]]
       res
     end
+    alias_method :chat, :talk
 
     ##
     # Maintain a conversation via the responses API.
@@ -78,8 +82,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)
@@ -87,7 +91,8 @@ module LLM
       params = params.merge(previous_response_id: res_id, input: messages).compact
       params = @params.merge(params)
       res = @provider.responses.create(prompt, params)
-      @messages.concat [LLM::Message.new(params[:role] || :user, prompt)]
+      role = params[:role] || @provider.user_role
+      @messages.concat [LLM::Message.new(role, prompt)]
       @messages.concat messages
       @messages.concat [res.choices[-1]]
       res
@@ -107,8 +112,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 +133,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 +182,84 @@ 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
+
+    ##
+    # @return [Hash]
+    def to_h
+      {model:, messages:}
+    end
+
+    ##
+    # @return [String]
+    def to_json(...)
+      {schema_version: 1}.merge!(to_h).to_json(...)
+    end
+
+    ##
+    # Save a session
+    # @example
+    #  llm = LLM.openai(key: ENV["KEY"])
+    #  ses = LLM::Session.new(llm)
+    #  ses.talk "Hello"
+    #  ses.save(path: "session.json")
+    # @raise [SystemCallError]
+    #  Might raise a number of SystemCallError subclasses
+    # @return [void]
+    def serialize(path:)
+      ::File.binwrite path, LLM.json.dump(self)
+    end
+    alias_method :save, :serialize
+
+    ##
+    # Restore a session
+    # @param [String, nil] path
+    #  The path to a JSON file
+    # @param [String, nil] string
+    #  A raw JSON string
+    # @raise [SystemCallError]
+    #  Might raise a number of SystemCallError subclasses
+    # @return [LLM::Session]
+    def deserialize(path: nil, string: nil)
+      payload = if path.nil? and string.nil?
+        raise ArgumentError, "a path or string is required"
+      elsif path
+        ::File.binread(path)
+      else
+        string
+      end
+      ses = LLM.json.load(payload)
+      @messages.concat [*ses["messages"]].map { deserialize_message(_1) }
+      self
+    end
+    alias_method :restore, :deserialize
+
     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
+
+  # Scheduled for removal in v5.0
+  deprecate_constant :Bot
 end

data/lib/llm/buffer.rb

@@ -70,6 +70,12 @@ module LLM
       @messages[index]
     end
 
+    ##
+    # @return [String]
+    def to_json(...)
+      LLM.json.dump(@messages, ...)
+    end
+
     ##
     # @return [String]
     def inspect

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,7 +29,22 @@
 #     end
 #   end
 class LLM::Function
+  require_relative "function/tracing"
+  prepend LLM::Function::Tracing
+
   class Return < Struct.new(:id, :name, :value)
+    ##
+    # Returns a Hash representation of {LLM::Function::Return}
+    # @return [Hash]
+    def to_h
+      {id:, name:, value:}
+    end
+
+    ##
+    # @return [String]
+    def to_json(...)
+      LLM.json.dump(to_h, ...)
+    end
   end
 
   ##
@@ -42,6 +57,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 +141,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

@@ -35,16 +35,16 @@ module LLM
   class JSONAdapter::JSON < JSONAdapter
     ##
     # @return (see JSONAdapter#dump)
-    def self.dump(obj)
+    def self.dump(obj, ...)
       require "json" unless defined?(::JSON)
-      ::JSON.dump(obj)
+      ::JSON.dump(obj, ...)
     end
 
     ##
     # @return (see JSONAdapter#load)
-    def self.load(string)
+    def self.load(string, ...)
       require "json" unless defined?(::JSON)
-      ::JSON.parse(string)
+      ::JSON.parse(string, ...)
     end
 
     ##
@@ -61,16 +61,16 @@ module LLM
   class JSONAdapter::Oj < JSONAdapter
     ##
     # @return (see JSONAdapter#dump)
-    def self.dump(obj)
+    def self.dump(obj, options = {})
       require "oj" unless defined?(::Oj)
-      ::Oj.dump(obj)
+      ::Oj.dump(obj, options.merge(mode: :compat))
     end
 
     ##
     # @return (see JSONAdapter#load)
-    def self.load(string)
+    def self.load(string, options = {})
       require "oj" unless defined?(::Oj)
-      ::Oj.load(string, mode: :compat, symbol_keys: false, symbolize_names: false)
+      ::Oj.load(string, options.merge(mode: :compat, symbol_keys: false, symbolize_names: false))
     end
 
     ##
@@ -87,16 +87,16 @@ module LLM
   class JSONAdapter::Yajl < JSONAdapter
     ##
     # @return (see JSONAdapter#dump)
-    def self.dump(obj)
+    def self.dump(obj, ...)
       require "yajl" unless defined?(::Yajl)
-      ::Yajl::Encoder.encode(obj)
+      ::Yajl::Encoder.encode(obj, ...)
     end
 
     ##
     # @return (see JSONAdapter#load)
-    def self.load(string)
+    def self.load(string, ...)
       require "yajl" unless defined?(::Yajl)
-      ::Yajl::Parser.parse(string)
+      ::Yajl::Parser.parse(string, ...)
     end
 
     ##

data/lib/llm/message.rb

@@ -30,10 +30,18 @@ module LLM
     end
 
     ##
-    # Returns a hash representation of the message
+    # Returns a Hash representation of the message.
     # @return [Hash]
     def to_h
-      {role:, content:}
+      {role:, content:,
+       tools: @extra[:tool_calls],
+       original_tool_calls: extra[:original_tool_calls]}.compact
+    end
+
+    ##
+    # @return [String]
+    def to_json(...)
+      LLM.json.dump(to_h, ...)
     end
 
     ##
@@ -62,7 +70,7 @@ module LLM
     # @return [Array<LLM::Function>]
     def functions
       @functions ||= tool_calls.map do |fn|
-        function = tools.find { _1.name.to_s == fn["name"] }.dup
+        function = available_tools.find { _1.name.to_s == fn["name"] }.dup
         function.tap { _1.id = fn.id }
         function.tap { _1.arguments = fn.arguments }
       end
@@ -136,6 +144,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]
@@ -151,7 +166,7 @@ module LLM
       @tool_calls ||= LLM::Object.from(@extra[:tool_calls] || [])
     end
 
-    def tools
+    def available_tools
       response&.__tools__ || []
     end
   end