llm.rb 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70c5f60cafc446edf8d1be15367ca77eb89e467785c77fbc7f758c29e761e8db
-  data.tar.gz: db9ec411a0c441e471a19a98624e0973815867c28ab89f8bcebc108b4dc11b3b
+  metadata.gz: cc70b8eb2d7ce82b3959d2b7dc795a89511a1962ed443a5344bb00ef55863033
+  data.tar.gz: a9245348fccc085710ae28097b9ce9c0ec9ce8e8f5ea4e23f97a9bde5fc50fee
 SHA512:
-  metadata.gz: f06f9c0367ad3d3428ce7c5046aebd37e4bfea9eac483b5c08a448bac58e9c205d3566a246d3022e9bd6d1669a9f9b5244a475262b24303d845464f7ec3ce4de
-  data.tar.gz: 45e86e63614eb9f5c96111f6ba11d9ec3aae89572dd3959987ca4d0a190cd2d6f5c8ab8ad516cdf68512ec1c1285117616493b3670b4538564c097ec1aaa0ede
+  metadata.gz: b1a0e67e1d938792da4cf52ff6b05dba568b71c77d28ef18c11510c7f0c37b21d5514f659ae6997193774755aede0bd5af4a1239247fc396b8a4815258723eb6
+  data.tar.gz: 87bfee8769ba983ffccef6bfb276922501e8cc68b2b4f2be6857408739b7307403c120de7db1b83c612a6af61e30860366419abb790662feb679ddf6f1234102

data/README.md

@@ -13,13 +13,15 @@ tool calling, audio, images, files, and structured outputs.
 
 #### REPL
 
-A simple chatbot that maintains a conversation and streams responses in real-time:
+The [LLM::Bot](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Bot.html) class provides
+a session with an LLM provider that maintains conversation history and context across
+multiple requests. The following example implements a simple REPL loop:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(key: ENV.fetch("KEY"))
+llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm, stream: $stdout)
 loop do
   print "> "
@@ -28,34 +30,12 @@ loop do
 end
 ```
 
-#### Prompts
-
-> ℹ️  **Tip:** Some providers (such as OpenAI) support `system` and `developer`
-> roles, but the examples in this README stick to `user` roles since they are
-> supported across all providers.
-
-A prompt builder that produces a chain of messages that can be sent in one request:
-
-```ruby
-#!/usr/bin/env ruby
-require "llm"
-
-llm = LLM.openai(key: ENV.fetch("KEY"))
-bot = LLM::Bot.new(llm)
-
-prompt = bot.build_prompt do
-  it.user "Answer concisely."
-  it.user "Was 2024 a leap year?"
-  it.user "How many days were in that year?"
-end
-
-res = bot.chat(prompt)
-res.choices.each { |m| puts "[#{m.role}] #{m.content}" }
-```
-
 #### Schema
 
-A bot that instructs the LLM to respond in JSON, and according to the given schema:
+The [LLM::Schema](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Schema.html) class provides
+a simple DSL for describing the structure of a response that an LLM emits according
+to a JSON schema. The schema lets a client describe what JSON object an LLM should
+emit, and the LLM will abide by the schema to the best of its ability:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -67,20 +47,19 @@ class Estimation < LLM::Schema
   property :notes, String, "Short notes", optional: true
 end
 
-llm = LLM.openai(key: ENV.fetch("KEY"))
+llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm, schema: Estimation)
-img = llm.images.create(prompt: "A man in his 30s")
-res = bot.chat bot.image_url(img.urls.first)
-data = res.choices.find(&:assistant?).content!
-
-puts "age: #{data["age"]}"
-puts "confidence: #{data["confidence"]}"
-puts "notes: #{data["notes"]}" if data["notes"]
+bot.chat("Estimate age and confidence for a man in his 30s.")
 ```
 
 #### Tools
 
-A bot equipped with a tool that is capable of running system commands:
+The [LLM::Tool](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Tool.html) class lets you
+define callable tools for the model. Each tool is described to the LLM as a function
+it can invoke to fetch information or perform an action. The model decides when to
+call tools based on the conversation; when it does, llm.rb runs the tool and sends
+the result back on the next request. The following example implements a simple tool
+that runs shell commands:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -96,17 +75,57 @@ class System < LLM::Tool
   end
 end
 
-llm  = LLM.openai(key: ENV.fetch("KEY"))
-bot  = LLM::Bot.new(llm, tools: [System])
+llm = LLM.openai(key: ENV["KEY"])
+bot = LLM::Bot.new(llm, tools: [System])
+bot.chat("Run `date`.")
+bot.chat(bot.functions.map(&:call)) # report return value to the LLM
+```
 
-prompt = bot.build_prompt do
-  it.user "You can run safe shell commands."
-  it.user "Run `date`."
+#### Agents
+
+The [LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Agent.html)
+class provides a class-level DSL for defining reusable, preconfigured
+assistants with defaults for model, tools, schema, and instructions.
+Instructions are injected only on the first request, and unlike
+[LLM::Bot](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Bot.html),
+an [LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Agent.html)
+will automatically call tools when needed:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+class SystemAdmin < LLM::Agent
+  model "gpt-4.1"
+  instructions "You are a Linux system admin"
+  tools Shell
+  schema Result
 end
 
+llm = LLM.openai(key: ENV["KEY"])
+agent = SystemAdmin.new(llm)
+res = agent.chat("Run 'date'")
+```
+
+#### Prompts
+
+The [LLM::Bot#build_prompt](https://0x1eef.github.io/x/llm.rb/LLM/LLM/Bot.html#build_prompt-instance_method)
+method provides a simple DSL for building a chain of messages that
+can be sent in a single request. A conversation with an LLM consists
+of messages that have a role (eg system, user), and content:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+bot = LLM::Bot.new(llm)
+prompt = bot.build_prompt do
+  it.system "Answer concisely."
+  it.user "Was 2024 a leap year?"
+  it.user "How many days were in that year?"
+end
 bot.chat(prompt)
-bot.chat(bot.functions.map(&:call))
-bot.messages.select(&:assistant?).each { |m| puts "[#{m.role}] #{m.content}" }
 ```
 
 ## Features
@@ -120,6 +139,7 @@ bot.messages.select(&:assistant?).each { |m| puts "[#{m.role}] #{m.content}" }
 #### Chat, Agents
 - 🧠  Stateless + stateful chat (completions + responses)
 - 🤖  Tool calling / function execution
+- 🔁  Agent tool-call auto-execution (bounded)
 - 🗂️  JSON Schema structured output
 - 📡  Streaming responses
 
@@ -320,7 +340,7 @@ end
 llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm, schema: Player)
 prompt = bot.build_prompt do
-  it.user "The player's name is Sam and their position is (7, 12)."
+  it.system "The player's name is Sam and their position is (7, 12)."
   it.user "Return the player's name and position"
 end
 

data/lib/llm/agent.rb

@@ -0,0 +1,214 @@
+# 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.
+  #
+  # @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.
+  #
+  # @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.chat("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
+      @bot = LLM::Bot.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.chat("Hello, what is your name?")
+    #   puts response.choices[0].content
+    def chat(prompt, params = {})
+      i, max = 0, Integer(params.delete(:max_tool_rounds) || 10)
+      res = @bot.chat(apply_instructions(prompt), params)
+      until @bot.functions.empty?
+        raise LLM::ToolLoopError, "pending tool calls remain" if i >= max
+        res = @bot.chat @bot.functions.map(&:call), params
+        i += 1
+      end
+      @instructions_applied = true
+      res
+    end
+
+    ##
+    # 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 = @bot.respond(apply_instructions(prompt), params)
+      until @bot.functions.empty?
+        raise LLM::ToolLoopError, "pending tool calls remain" if i >= max
+        res = @bot.respond @bot.functions.map(&:call), params
+        i += 1
+      end
+      @instructions_applied = true
+      res
+    end
+
+    ##
+    # @return [LLM::Buffer<LLM::Message>]
+    def messages
+      @bot.messages
+    end
+
+    ##
+    # @return [Array<LLM::Function>]
+    def functions
+      @bot.functions
+    end
+
+    ##
+    # @return [LLM::Object]
+    def usage
+      @bot.usage
+    end
+
+    ##
+    # @return [LLM::Builder]
+    def build_prompt(&)
+      @bot.build_prompt(&)
+    end
+
+    ##
+    # @param [String] url
+    #  The URL
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def image_url(url)
+      @bot.image_url(url)
+    end
+
+    ##
+    # @param [String] path
+    #  The path
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def local_file(path)
+      @bot.local_file(path)
+    end
+
+    ##
+    # @param [LLM::Response] res
+    #  The response
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def remote_file(res)
+      @bot.remote_file(res)
+    end
+
+    private
+
+    def apply_instructions(prompt)
+      instr = self.class.instructions
+      return prompt unless instr
+      if LLM::Builder === 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)
+      else
+        build_prompt do
+          _1.system instr unless @instructions_applied
+          _1.user prompt
+        end
+      end
+    end
+  end
+end

data/lib/llm/bot.rb

@@ -131,7 +131,7 @@ module LLM
     #   end
     #   bot.chat(prompt)
     def build_prompt(&)
-      LLM::Builder.new(&).tap(&:call)
+      LLM::Builder.new(@provider, &).tap(&:call)
     end
 
     ##

data/lib/llm/builder.rb

@@ -4,6 +4,9 @@
 # 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)
@@ -16,7 +19,8 @@ class LLM::Builder
   ##
   # @param [Proc] evaluator
   #  The evaluator
-  def initialize(&evaluator)
+  def initialize(provider, &evaluator)
+    @provider = provider
     @buffer = []
     @evaluator = evaluator
   end
@@ -33,7 +37,13 @@ class LLM::Builder
   # @param [Symbol] role
   #  The role (eg user, system)
   # @return [void]
-  def chat(content, role: :user)
+  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
 
@@ -42,7 +52,7 @@ class LLM::Builder
   #  The message content
   # @return [void]
   def user(content)
-    chat(content, role: :user)
+    chat(content, role: @provider.user_role)
   end
 
   ##
@@ -50,7 +60,15 @@ class LLM::Builder
   #  The message content
   # @return [void]
   def system(content)
-    chat(content, role: :system)
+    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
 
   ##

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/provider.rb

@@ -234,6 +234,24 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # @return [Symbol]
+  def user_role
+    :user
+  end
+
+  ##
+  # @return [Symbol]
+  def system_role
+    :system
+  end
+
+  ##
+  # @return [Symbol]
+  def developer_role
+    :developer
+  end
+
   private
 
   attr_reader :client, :base_uri, :host, :port, :timeout, :ssl

data/lib/llm/providers/gemini.rb

@@ -103,12 +103,6 @@ module LLM
       LLM::Gemini::Models.new(self)
     end
 
-    ##
-    # @return (see LLM::Provider#assistant_role)
-    def assistant_role
-      "model"
-    end
-
     ##
     # Returns the default model for chat completions
     # @see https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash gemini-2.5-flash
@@ -141,6 +135,33 @@ module LLM
       ResponseAdapter.adapt(complete(query, tools: [server_tools[:google_search]]), type: :web_search)
     end
 
+    ##
+    # @return [Symbol]
+    #  Returns the providers user role
+    def user_role
+      :user
+    end
+
+    ##
+    # @return [Symbol]
+    #  Returns the providers system role
+    def system_role
+      :user
+    end
+
+    ##
+    # @return [Symbol]
+    # Returns the providers developer role
+    def developer_role
+      :user
+    end
+
+    ##
+    # @return (see LLM::Provider#assistant_role)
+    def assistant_role
+      "model"
+    end
+
     private
 
     def headers

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "4.0.0"
+  VERSION = "4.1.0"
 end

data/lib/llm.rb

@@ -18,6 +18,7 @@ module LLM
   require_relative "llm/file"
   require_relative "llm/provider"
   require_relative "llm/bot"
+  require_relative "llm/agent"
   require_relative "llm/buffer"
   require_relative "llm/function"
   require_relative "llm/eventstream"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Antar Azri
@@ -178,6 +178,7 @@ files:
 - LICENSE
 - README.md
 - lib/llm.rb
+- lib/llm/agent.rb
 - lib/llm/bot.rb
 - lib/llm/buffer.rb
 - lib/llm/builder.rb