llm.rb 15.2.0 → 15.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c55a3fa1151afad5720fc33bbe60a71feed5577242e53b4e8d4e2f9962a18ed
-  data.tar.gz: 3099ef73435ed6d91b003a40e2e5c195a82a8f631418b21e7c8cbce9088a5c76
+  metadata.gz: '01569fad6afcf4d422b666778989e7bafd1c6e994b6e2be7801ccb5842a7aa3d'
+  data.tar.gz: f60ddf02e1a8405cf393e8c581cce61415f459d3207a7c8dc531cbe4e0e87f27
 SHA512:
-  metadata.gz: 8e0d5dd6c98355412a31dcb638081ea9f0553725cbf30aa6598eed5d16cd6d4693b5edfae8c063625ee2f5198b342e9b11850897370404267d291ddae4d747fe
-  data.tar.gz: 25102554a840fee5046804d17ff91673793603b96ab9ae246a30b7d3192a792e9bd7e384d76ce20abf2d504910330202cb2d4aef0057c7875c1ce3866ccfe177
+  metadata.gz: 8d9f88421f209e72e1631cbe3e4119d80af29aa72dc44a1917a6dfcbaa76b3d8014d70afe1c771177f6a755ea2d840ffaf92a850606fdd9d08db5c0d0283d0d6
+  data.tar.gz: b9d2417b3d2ce4f54ae5c657791518261332508b7dcfe726f19f81d97a27f329220a81ea2ced411fd15625b11c3964c69e1bcfef5df799f9ee0d16f2342cdd56

data/CHANGELOG.md

@@ -17,6 +17,63 @@
 
 *No unreleased changes yet. Check back after the next release.*
 
+## v15.2.2
+
+Changes since `v15.2.1`.
+
+This release fixes the `set_provider`, `set_context`, and `set_tracer`
+callbacks installed by `acts_as_llm` and `plugin :llm` so a subclass
+inherits them from its superclass instead of raising.
+
+### Fix
+
+* **activerecord, sequel: inherit `set_provider` from a superclass** <br>
+  The `set_provider`, `set_context`, and `set_tracer` callbacks installed by
+  `acts_as_llm` / `plugin :llm` (and their agent counterparts) are now resolved
+  through the normal method lookup chain. Defining a callback on a superclass,
+  the usual single-table inheritance setup, no longer raises
+  `NotImplementedError`, and a subclass can still override it.
+
+## v15.2.1
+
+Changes since `v15.2.0`.
+
+This release makes the agent count its tool budget across the whole turn
+and emit tool returns to the stream once that budget is spent, and lets
+`LLM::Function#cancel` carry extra return fields.
+
+### Agent
+
+* **agent: count the tool budget across the whole turn** <br>
+  [`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
+  now caps the tool calls a turn runs in total. A batch of calls is
+  spent as a batch, and a batch that would take the turn past its
+  budget is not run at all; once the budget is spent no tool call runs,
+  and the agent keeps sending its in-band advisory until the model
+  answers without requesting more tools. Previously the agent ran up to
+  the budget, then ran further batches after each advisory, so a turn
+  could run more tool calls than its budget allowed.
+
+* **agent: emit tool returns when the budget is spent** <br>
+  Fix a bug where, once a turn's tool budget was spent, the agent passed
+  its in-band returns to the model without emitting them to the stream.
+  The stream went silent, so a stream that tracked tool-call state left
+  the calls in the `call` state. The returns are now emitted through
+  [`LLM::Stream#on_tool_return`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_return-instance_method)
+  like any other tool return.
+
+### Function
+
+* **function: `LLM::Function#cancel` takes extra return fields** <br>
+  [`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel-instance_method)
+  now accepts keywords beyond `reason:` and merges them into the
+  [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+  it builds. `LLM::Function#budget_spent` now builds its return through
+  `cancel` instead of hand-rolling an error, so a budget-spent return is
+  marked `cancelled: true` and carries `action:` and `advice:` hints. A
+  callback that receives returns can now tell a cancellation apart from
+  an ordinary error.
+
 ## v15.2.0
 
 Changes since `v15.1.0`.

data/README.md

@@ -19,10 +19,10 @@ on CRuby. It has zero runtime dependencies by default, supports
 concurrent and parallel tool execution and has a single coherent API
 that spans 14+ providers.
 
-The easiest way to learn about llm.rb is to ask [the r.uby.dev chatbot](https://r.uby.dev)
+The most effective way to learn about llm.rb is to ask [the r.uby.dev chatbot](https://r.uby.dev)
 a question. It is connected to the llm.rb GitHub repository, backed by
-ActiveRecord and uses the builtin MCP feature to connect to GitHub. All
-answers are grounded in the llm.rb source code.
+ActiveRecord and uses the builtin MCP feature to connect to GitHub. The chatbot
+is an llm.rb agent that is deployed with [roda-llm](https://github.com/r-uby-dev/roda-llm#readme).
 
 ## Install
 
@@ -37,9 +37,22 @@ gem install llm.rb
 The
 [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
 class is the default high-level interface,
-and it is recommended for most use-cases. It manages tool execution
-automatically and guards against infinite loops,
-manages conversation state, and much more.
+and it is recommended for most use-cases. It manages the tool loop
+and provides configurable features on top of it. For example you can
+manage the tool loop with a retry budget alongside a tool call budget,
+among other features.
+
+The runtime is designed to keep the tool loop alive and it will
+avoid exceptions. When an error is encountered in a tool or during
+the lifecycle of an agent it is almost always reported back to the
+model as an in-band error that allows the model to correct course.
+
+A lot of care also goes into keeping the tool loop from entering
+an invalid state that would lead to API-level errors. For example,
+when a tool call is interrupted it could leave an unanswered tool
+call that a model will reject on the next turn. The runtime takes
+care of this by pruning orphaned tool calls and ensuring that the
+tool loop always remains valid. 
 
 ```ruby
 require "llm"
@@ -249,12 +262,12 @@ end
 <br>
 
 The [LLM::Agent#console](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#console-instance_method)
-method drops you into a highly capable interactive console
-that is built on top of curses. It can help you debug agents,
-test your tools, connect to MCP servers, and even A2A agents.
-The console stands out because it connects to the surrounding
-runtime and it can be extended by your code. Think of it as
-`binding.irb` but for agents.
+method drops you into an interactive console that is built on
+top of curses. It can help you debug agents, test your tools,
+connect to MCP servers, and other A2A agents. The console stands
+out because it connects to the surrounding runtime and it can
+be extended by your code. Think of it as `binding.irb` but
+for agents.
 
 ##### Demo
 

data/lib/llm/active_record/acts_as_agent.rb

@@ -37,7 +37,7 @@ module LLM::ActiveRecord
       #     acts_as_agent
       #     set instructions: "You are a system administrator",
       #         model: "gpt-4.1-nano",
-      #         tools: [Shell]
+      #         tools: [LLM::Tool::Exec]
       #   end
       #
       # @param [Hash] properties

data/lib/llm/active_record/acts_as_llm.rb

@@ -220,19 +220,25 @@ module LLM::ActiveRecord
 
       ##
       # @return [LLM::Provider]
+      # @raise [NotImplementedError]
+      #  when neither this model nor one of its ancestors implements the
+      #  callback
       def set_provider
+        return super if defined?(super)
         raise NotImplementedError, "implement the set_provider callback"
       end
 
       ##
       # @return [Hash]
       def set_context
+        return super if defined?(super)
         EMPTY_HASH.dup
       end
 
       ##
       # @return [LLM::Tracer]
       def set_tracer
+        return super if defined?(super)
         nil
       end
 

data/lib/llm/agent.rb

@@ -22,9 +22,12 @@ module LLM
   #   tool-call patterns and blocks stuck execution before more tool work is
   #   queued.
   # * The tool loop can be bounded with `tool_budget`. Once the budget is
-  #   spent, the agent sends an in-band advisory message back through the
-  #   model and keeps the loop in-band. By default no budget is set
-  #   (`nil`), so the feature is disabled.
+  #   spent, no further tool calls are run for that turn: the agent sends an
+  #   in-band advisory message back through the model instead, and keeps
+  #   sending it while the model keeps asking for tools. The budget counts
+  #   tool calls, so a batch of calls is spent as a batch, and a batch that
+  #   would take the turn past its budget is not run at all. By default no
+  #   budget is set (`nil`), so the feature is disabled.
   # * Tool loop execution can be configured with `concurrency :sequential`,
   #   `:thread`, `:async`, `:fiber`, `:fork`, or `:ractor`.
   #
@@ -32,7 +35,7 @@ module LLM
   #   class SystemAdmin < LLM::Agent
   #     set model: "gpt-4.1-nano",
   #         instructions: "You are a Linux system admin",
-  #         tools: [Shell],
+  #         tools: [LLM::Tool::Exec],
   #         schema: Result
   #   end
   #
@@ -99,7 +102,7 @@ module LLM
     #     set name: "admin",
     #         instructions: "You are a system administrator",
     #         model: "gpt-4.1-nano",
-    #         tools: [Shell, ReadFile]
+    #         tools: [LLM::Tool::Exec, LLM::Tool::ReadFile]
     #   end
     #
     # @param [Hash] properties
@@ -345,10 +348,15 @@ module LLM
     ##
     # Set or get the maximum number of tool calls
     # that are allowed in a single turn. Once the
-    # budget is spent, we will return an in-band
-    # message that informs the model it has spent
-    # its tool call budget - and usually a model
-    # will change course afterwards.
+    # budget is spent, no further tool calls are run:
+    # we return an in-band message that informs the
+    # model it has spent its tool call budget, and
+    # keep returning it while the model keeps asking
+    # for tools - a model will usually change course
+    # afterwards. The budget counts tool calls, so a
+    # batch of calls is spent as a batch, and a batch
+    # that would take the turn past its budget is not
+    # run at all.
     # @note
     #  By default this feature is disabled
     #  (set to `nil`).
@@ -823,14 +831,21 @@ module LLM
         stream = params[:stream] || @ctx.params[:stream]
         params[:stream] = LLM::Stream.try(stream, extra: {concurrency:})
         res = talk.call(apply_instructions(prompt), params)
+        spent = 0
         while @ctx.pending_functions?
-          if max
-            max.times do
-              break unless @ctx.pending_functions?
-              res = talk.call(call_functions, params)
-            end
-            res = talk.call(@ctx.pending_functions.map(&:budget_spent), params) if @ctx.pending_functions?
+          batch = @ctx.pending_functions.size
+          if max and spent + batch > max
+            ##
+            # The budget is spent, so the calls are not run.
+            # They still have to be answered though: each one
+            # gets an in-band return and, just as important,
+            # that return is emitted to the stream.
+            tools = @ctx.pending_functions
+            returns = tools.map(&:budget_spent)
+            @ctx.method(:emit_tool_returns).call(tools, returns)
+            res = talk.call(returns, params)
           else
+            spent += batch if max
             res = talk.call(call_functions, params)
           end
         end

data/lib/llm/console/buffer.rb

@@ -16,7 +16,7 @@ class LLM::Console
   # row by overwriting its contents repeatedly.
   class Buffer
     ##
-    # @param [LLM::Console] console
+    # @param [LLM::Console] repl
     #  An instance of {LLM::Console LLM::Console}.
     # @return [LLM::Console::Buffer]
     def initialize(repl)

data/lib/llm/console/command.rb

@@ -168,7 +168,7 @@ class LLM::Console
     attr_reader :agent
 
     ##
-    # @param [LLM::Console] console
+    # @param [LLM::Console] repl
     # @return [LLM::Console::Command]
     def initialize(repl)
       @repl = repl

data/lib/llm/console/input.rb

@@ -55,7 +55,7 @@ class LLM::Console
     attr_writer :paste
 
     ##
-    # @param [LLM::Console] console
+    # @param [LLM::Console] repl
     # @return [LLM::Console::Input]
     def initialize(repl, options = {})
       @repl = repl

data/lib/llm/console/status.rb

@@ -12,7 +12,7 @@ class LLM::Console
   # @api private
   class Status
     ##
-    # @param [LLM::Console] console
+    # @param [LLM::Console] repl
     # @return [LLM::Console::Status]
     def initialize(repl)
       @repl = repl

data/lib/llm/console/stream.rb

@@ -13,7 +13,7 @@ class LLM::Console
     attr_reader :tools
 
     ##
-    # @param [LLM::Console] console
+    # @param [LLM::Console] repl
     # @return [LLM::Console::Stream]
     def initialize(repl, queue)
       @repl = repl

data/lib/llm/console/window.rb

@@ -24,8 +24,8 @@ class LLM::Console
     attr_reader :input
 
     ##
-    # @param [LLM::Console] console
-    #  A read-eval-print loop.
+    # @param [LLM::Console] repl
+    #  A console.
     # @return [LLM::Console::Window]
     def initialize(repl)
       @repl   = repl

data/lib/llm/function.rb

@@ -294,8 +294,8 @@ class LLM::Function
   #   ctx.talk "I want to run the functions"
   #   ctx.talk ctx.pending_functions.map(&:cancel)
   # @return [LLM::Function::Return]
-  def cancel(reason: "function call cancelled")
-    Return.new(id, name, {cancelled: true, reason:})
+  def cancel(reason: "function call cancelled", **extra)
+    Return.new(id, name, extra.merge(cancelled: true, reason:))
   ensure
     @cancelled = true
   end
@@ -356,12 +356,11 @@ class LLM::Function
   # call budget has been spent.
   # @return [LLM::Function::Return]
   def budget_spent
-    LLM::Function::Return.new(id, name, {
-      error: true,
-      type: "LLM::BudgetSpentError",
-      message: "the tool call budget for this turn has been spent. " \
-               "try to solve the problem with less tool calls."
-    })
+    cancel(
+      reason: "you are making too many tool calls",
+      action: ["stop requesting tool calls"],
+      advice: ["produce a response from tool calls already made", "temporary error that resets on the next turn"]
+    )
   end
 
   ##

data/lib/llm/registry/model.rb

@@ -6,7 +6,7 @@ class LLM::Registry
   # metadata (pricing, limits, capabilities, and
   # modalities).
   #
-  # Models are {Comparable} by price: input cost first, then
+  # Models are `Comparable` by price: input cost first, then
   # output cost, so `models.sort` orders them from cheapest to
   # most expensive.
   class Model

data/lib/llm/sequel/agent.rb

@@ -52,7 +52,7 @@ module LLM::Sequel
       #     plugin :llm_agent
       #     set instructions: "You are a system administrator",
       #         model: "gpt-4.1-nano",
-      #         tools: [Shell]
+      #         tools: [LLM::Tool::Exec]
       #   end
       #
       # @param [Hash] properties

data/lib/llm/sequel/plugin.rb

@@ -320,19 +320,25 @@ module LLM::Sequel
 
     ##
     # @return [LLM::Provider]
+    # @raise [NotImplementedError]
+    #  when neither this model nor one of its ancestors implements the
+    #  callback
     def set_provider
+      return super if defined?(super)
       raise NotImplementedError, "implement the set_provider callback"
     end
 
     ##
     # @return [Hash]
     def set_context
+      return super if defined?(super)
       Plugin::EMPTY_HASH.dup
     end
 
     ##
     # @return [LLM::Tracer]
     def set_tracer
+      return super if defined?(super)
       nil
     end
 

data/lib/llm/tools/exec.rb

@@ -46,10 +46,8 @@ class LLM::Tool
     end
 
     ##
-    # @param [String] name
-    #  The name of a command
     # @param [Array<String>] arguments
-    #  One or more command-line arguments
+    #  A command and its arguments. The first element is the command name.
     # @param [Integer] timeout
     #  The maximum allowed time for the command to run (in seconds)
     # @param [Integer] max_bytes

data/lib/llm/tools/git.rb

@@ -16,8 +16,11 @@ class LLM::Tool
     defaults arguments: [], timeout: 5
 
     ##
-    # @param [String] subcommand
-    # @param [Array<String>, nil] arguments
+    # @param [Array<String>] arguments
+    #  One or more git arguments. The first is the subcommand and must be
+    #  one of `log`, `diff`, `commit`, `checkout`, `branch`, or `show`.
+    # @param [Integer] timeout
+    #  The maximum time to allow the command to run (in seconds)
     # @return [Hash]
     def call(arguments: [], timeout: 5)
       subcommand = arguments[0]

data/lib/llm/tools/read_file.rb

@@ -4,7 +4,7 @@ class LLM::Tool
   ##
   # The {LLM::Tool::ReadFile} class implements a tool that
   # can read the contents of a file. It returns the content
-  # as structured lines ({lineno:, content:}), so the model can
+  # as structured lines (`{lineno:, content:}`), so the model can
   # reference line numbers when requesting a narrower range.
   class ReadFile < self
     require_relative "utils"

data/lib/llm/version.rb

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

data/llm.gemspec

@@ -37,13 +37,7 @@ DESCRIPTION
   spec.post_install_message = "\n" \
                               "Got a question about llm.rb? " \
                               "\n" \
-                              "Ask the https://r.uby.dev chatbot." \
-                              "\n" \
-                              "It is connected to the official GitHub repository." \
-                              "\n" \
-                              "100% free to use." \
-                              "\n" \
-                              "Built with llm.rb and DeepSeek." \
+                              "The https://r.uby.dev website can help." \
                               "\n\n"
 
   spec.add_development_dependency "webmock", "~> 3.24.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 15.2.0
+  version: 15.2.2
 platform: ruby
 authors:
 - Robert Gleeson
@@ -695,9 +695,8 @@ metadata:
   source_code_uri: https://github.com/r-uby-dev/llm
   documentation_uri: https://r.uby.dev
   changelog_uri: https://github.com/r-uby-dev/llm/blob/main/CHANGELOG.md
-post_install_message: "\nGot a question about llm.rb? \nAsk the https://r.uby.dev
-  chatbot.\nIt is connected to the official GitHub repository.\n100% free to use.\nBuilt
-  with llm.rb and DeepSeek.\n\n"
+post_install_message: "\nGot a question about llm.rb? \nThe https://r.uby.dev website
+  can help.\n\n"
 rdoc_options: []
 require_paths:
 - lib