llm.rb 4.0.0 → 4.2.0

data/lib/llm/agent.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Agent LLM::Agent} provides a class-level DSL for defining
+  # reusable, preconfigured assistants with defaults for model,
+  # tools, schema, and instructions.
+  #
+  # **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
+  #     model "gpt-4.1-nano"
+  #     instructions "You are a Linux system admin"
+  #     tools Shell
+  #     schema Result
+  #   end
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   agent = SystemAdmin.new(llm)
+  #   agent.talk("Run 'date'")
+  class Agent
+    ##
+    # Set or get the default model
+    # @param [String, nil] model
+    #  The model identifier
+    # @return [String, nil]
+    #  Returns the current model when no argument is provided
+    def self.model(model = nil)
+      return @model if model.nil?
+      @model = model
+    end
+
+    ##
+    # Set or get the default tools
+    # @param [Array<LLM::Function>, nil] tools
+    #  One or more tools
+    # @return [Array<LLM::Function>]
+    #  Returns the current tools when no argument is provided
+    def self.tools(*tools)
+      return @tools || [] if tools.empty?
+      @tools = tools.flatten
+    end
+
+    ##
+    # Set or get the default schema
+    # @param [#to_json, nil] schema
+    #  The schema
+    # @return [#to_json, nil]
+    #  Returns the current schema when no argument is provided
+    def self.schema(schema = nil)
+      return @schema if schema.nil?
+      @schema = schema
+    end
+
+    ##
+    # Set or get the default instructions
+    # @param [String, nil] instructions
+    #  The system instructions
+    # @return [String, nil]
+    #  Returns the current instructions when no argument is provided
+    def self.instructions(instructions = nil)
+      return @instructions if instructions.nil?
+      @instructions = instructions
+    end
+
+    ##
+    # @param [LLM::Provider] provider
+    #  A provider
+    # @param [Hash] params
+    #  The parameters to maintain throughout the conversation.
+    #  Any parameter the provider supports can be included and
+    #  not only those listed here.
+    # @option params [String] :model Defaults to the provider's default model
+    # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
+    # @option params [#to_json, nil] :schema Defaults to nil
+    def initialize(provider, params = {})
+      defaults = {model: self.class.model, tools: self.class.tools, schema: self.class.schema}.compact
+      @provider = provider
+      @ses = LLM::Session.new(provider, defaults.merge(params))
+      @instructions_applied = false
+    end
+
+    ##
+    # Maintain a conversation via the chat completions API.
+    # This method immediately sends a request to the LLM and returns the response.
+    #
+    # @param prompt (see LLM::Provider#complete)
+    # @param [Hash] params The params passed to the provider, including optional :stream, :tools, :schema etc.
+    # @option params [Integer] :max_tool_rounds The maxinum number of tool call iterations (default 10)
+    # @return [LLM::Response] Returns the LLM's response for this turn.
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   agent = LLM::Agent.new(llm)
+    #   response = agent.talk("Hello, what is your name?")
+    #   puts response.choices[0].content
+    def talk(prompt, params = {})
+      i, max = 0, Integer(params.delete(:max_tool_rounds) || 10)
+      res = @ses.talk(apply_instructions(prompt), params)
+      until @ses.functions.empty?
+        raise LLM::ToolLoopError, "pending tool calls remain" if i >= max
+        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.
+    # This method immediately sends a request to the LLM and returns the response.
+    #
+    # @note Not all LLM providers support this API
+    # @param prompt (see LLM::Provider#complete)
+    # @param [Hash] params The params passed to the provider, including optional :stream, :tools, :schema etc.
+    # @option params [Integer] :max_tool_rounds The maxinum number of tool call iterations (default 10)
+    # @return [LLM::Response] Returns the LLM's response for this turn.
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   agent = LLM::Agent.new(llm)
+    #   res = agent.respond("What is the capital of France?")
+    #   puts res.output_text
+    def respond(prompt, params = {})
+      i, max = 0, Integer(params.delete(:max_tool_rounds) || 10)
+      res = @ses.respond(apply_instructions(prompt), params)
+      until @ses.functions.empty?
+        raise LLM::ToolLoopError, "pending tool calls remain" if i >= max
+        res = @ses.respond @ses.functions.map(&:call), params
+        i += 1
+      end
+      @instructions_applied = true
+      res
+    end
+
+    ##
+    # @return [LLM::Buffer<LLM::Message>]
+    def messages
+      @ses.messages
+    end
+
+    ##
+    # @return [Array<LLM::Function>]
+    def functions
+      @ses.functions
+    end
+
+    ##
+    # @return [LLM::Object]
+    def usage
+      @ses.usage
+    end
+
+    ##
+    # @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
+    #  The URL
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def image_url(url)
+      @ses.image_url(url)
+    end
+
+    ##
+    # @param [String] path
+    #  The path
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def local_file(path)
+      @ses.local_file(path)
+    end
+
+    ##
+    # @param [LLM::Response] res
+    #  The response
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def 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
+
+    def apply_instructions(prompt)
+      instr = self.class.instructions
+      return prompt unless instr
+      if LLM::Prompt === prompt
+        messages = prompt.to_a
+        prompt = LLM::Prompt.new(@provider)
+        prompt.system instr unless @instructions_applied
+        messages.each { |msg| prompt.talk(msg.content, role: msg.role) }
+        prompt
+      else
+        prompt do
+          system instr unless @instructions_applied
+          user prompt
+        end
+      end
+    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(&).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/error.rb

@@ -50,4 +50,8 @@ module LLM
   ##
   # When the context window is exceeded
   ContextWindowError = Class.new(InvalidRequestError)
+
+  ##
+  # When stuck in a tool call loop
+  ToolLoopError = Class.new(Error)
 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