llm.rb 6.1.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57b39b3b4b79d1d9f8cfd10426ad233d698dd6e3ed84bfef887c8c63f543f40f
-  data.tar.gz: 443ed7e2a04259c69d41b1da7a42e7637efaa4ab1075548706ce349bced7ed51
+  metadata.gz: 6c923952039095a2234eb1bd5c058a951b0d797d27577cdf7f679df59b49060b
+  data.tar.gz: 3667e0d79e44634f769dfced198dd07c1039f173cb43b72aab7d3204aa3638f8
 SHA512:
-  metadata.gz: f8e53dc41eacf16cea35f64a6048aa77852fcf7a135676b2b9c02e37beff174b5a500948477c4f931ff0a71d20c4503ba3e9eef19358d3aaa204040e77fe14c5
-  data.tar.gz: 358ce7f33d2dca51365f6581867006970fd66079dcaa189268e2deff2f297c89b8332fd11b714bedfd89124413b7a9e12fc09d928c2c28f2e9cb2368f2bc3e24
+  metadata.gz: 655d450b2ffeb71ed9564b7c5c23a2a86e9e385de9dc1abdac18588e460cffdecd1b2da1d5ef9fc162dc3f3286b7d2c979baec3953cd1ddbdab74d1ef5b87112
+  data.tar.gz: a044fedb675c4d92eff55c210d588b68b80c7e3967188674c2de4d8f6bc69d76e8f15c18f49fb54e09a8c93dff89074304d231609337bfa3bc79c96e1f3f576b

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## Unreleased
+
+## v7.0.0
+
+Changes since `v6.1.0`.
+
+This release turns agent tool-loop limit errors into in-band advisory
+returns so the LLM can react to rate limits and continue the loop. It
+adds `tool_attempts: nil` as a way to opt out of advisory tool-limit
+returns entirely, and fixes the default provider HTTP path to keep
+`net-http-persistent` optional when not explicitly enabled.
+
+### Breaking
+
+* **Return in-band tool-loop limit errors from agents** <br>
+  Stop raising `LLM::ToolLoopError` when an agent exhausts its tool loop
+  attempt budget, and instead send advisory `LLM::Function::Return`
+  errors back through the model so the LLM can react to the rate limit
+  in-band and continue the loop.
+
+* **Allow `tool_attempts: nil` to disable advisory tool-limit returns** <br>
+  Keep the default `tool_attempts` budget at `25`, but treat an explicit
+  `tool_attempts: nil` as an opt-out that disables advisory tool-limit
+  returns entirely.
+
+### Fix
+
+* **Keep `net-http-persistent` optional on normal HTTP requests** <br>
+  Stop the default provider HTTP path from loading `net/http/persistent`
+  unless persistent transport support is explicitly enabled.
+
 ## v6.1.0
 
 Changes since `v6.0.0`.

data/README.md

@@ -4,7 +4,7 @@
 <p align="center">
   <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1"><img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc"></a>
   <a href="https://opensource.org/license/0bsd"><img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License"></a>
-  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-6.1.0-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-7.0.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -370,6 +370,10 @@ worker.join
   or experimental `:ractor` support for class-based tools. MCP tools are not
   supported by the current `:ractor` mode, but mixed tool sets can still
   route MCP tools and local tools through different strategies at runtime.
+  By default, the tool attempt budget is `25`. When an agent exhausts that
+  budget, it sends advisory tool errors back through the model instead of
+  raising out of the runtime. Set `tool_attempts: nil` to disable that
+  advisory behavior.
 - **Tool calls have an explicit lifecycle** <br>
   A tool call can be executed, cancelled through
   [`LLM::Function#cancel`](https://0x1eef.github.io/x/llm.rb/LLM/Function.html#cancel-instance_method),
@@ -625,7 +629,7 @@ This example uses [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context
 [`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html) together so
 long-lived contexts can summarize older history and expose the lifecycle
 through stream hooks. This approach is inspired by General Intelligence
-Systems' [Brute](https://github.com/general-intelligence-systems/brute). The
+Systems. The
 compactor can also use its own `model:` if you want summarization to run on a
 different model from the main context. `token_threshold:` accepts either a
 fixed token count or a percentage string like `"90%"`, which resolves

data/lib/llm/agent.rb

@@ -19,6 +19,9 @@ module LLM
   # * The automatic tool loop enables the wrapped context's `guard` by default.
   #   The built-in {LLM::LoopGuard LLM::LoopGuard} detects repeated tool-call
   #   patterns and blocks stuck execution before more tool work is queued.
+  # * The default tool attempt budget is `25`. After that, the agent sends
+  #   advisory tool errors back through the model and keeps the loop in-band.
+  #   Set `tool_attempts: nil` to disable that advisory behavior.
   # * Tool loop execution can be configured with `concurrency :call`,
   #   `:thread`, `:task`, `:fiber`, `:ractor`, or a list of queued task
   #   types such as `[:thread, :ractor]`.
@@ -161,7 +164,10 @@ module LLM
     #
     # @param prompt (see LLM::Provider#complete)
     # @param [Hash] params The params passed to the provider, including optional :stream, :tools, :schema etc.
-    # @option params [Integer] :tool_attempts The maxinum number of tool call iterations (default 25)
+    # @option params [Integer] :tool_attempts
+    #  The maxinum number of tool call iterations before the agent sends
+    #  in-band advisory tool errors back through the model (default 25).
+    #  Set to `nil` to disable advisory tool-limit returns.
     # @return [LLM::Response] Returns the LLM's response for this turn.
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
@@ -180,7 +186,10 @@ module LLM
     # @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] :tool_attempts The maxinum number of tool call iterations (default 25)
+    # @option params [Integer] :tool_attempts
+    #  The maxinum number of tool call iterations before the agent sends
+    #  in-band advisory tool errors back through the model (default 25).
+    #  Set to `nil` to disable advisory tool-limit returns.
     # @return [LLM::Response] Returns the LLM's response for this turn.
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
@@ -393,20 +402,37 @@ module LLM
 
     def run_loop(method, prompt, params)
       loop = proc do
-        max = Integer(params.delete(:tool_attempts) || 25)
+        max = params.key?(:tool_attempts) ? params.delete(:tool_attempts) : 25
+        max = Integer(max) if max
         stream = params[:stream] || @ctx.params[:stream]
         stream.extra[:concurrency] = concurrency if LLM::Stream === stream
         res = @ctx.public_send(method, apply_instructions(prompt), params)
-        max.times do
+        loop do
           break if @ctx.functions.empty?
-          res = @ctx.public_send(method, call_functions, params)
+          if max
+            max.times do
+              break if @ctx.functions.empty?
+              res = @ctx.public_send(method, call_functions, params)
+            end
+            break if @ctx.functions.empty?
+            res = @ctx.public_send(method, @ctx.functions.map { rate_limit(_1) }, params)
+          else
+            res = @ctx.public_send(method, call_functions, params)
+          end
         end
-        raise LLM::ToolLoopError, "pending tool calls remain" unless @ctx.functions.empty?
         res
       end
       @tracer ? @llm.with_tracer(@tracer, &loop) : loop.call
     end
 
+    def rate_limit(function)
+      LLM::Function::Return.new(function.id, function.name, {
+        error: true,
+        type: LLM::ToolLoopError.name,
+        message: "tool loop rate limit reached"
+      })
+    end
+
     def resolve_option(option)
       Proc === option ? instance_exec(&option) : option
     end

data/lib/llm/compactor.rb

@@ -5,8 +5,7 @@
 # smaller replacement message when a context grows too large.
 #
 # This work is directly inspired by the compaction approach developed by
-# General Intelligence Systems in
-# [Brute](https://github.com/general-intelligence-systems/brute).
+# General Intelligence Systems.
 #
 # The compactor can also use a different model from the main context by
 # setting `model:` in the compactor config. Compaction thresholds are opt-in:

data/lib/llm/context.rb

@@ -96,8 +96,7 @@ module LLM
     ##
     # Returns a context compactor
     # This feature is inspired by the compaction approach developed by
-    # General Intelligence Systems in
-    # [Brute](https://github.com/general-intelligence-systems/brute).
+    # General Intelligence Systems.
     # @return [LLM::Compactor]
     def compactor
       @compactor = LLM::Compactor.new(self, @compactor || {}) unless LLM::Compactor === @compactor

data/lib/llm/loop_guard.rb

@@ -10,8 +10,7 @@
 #
 # {LLM::LoopGuard LLM::LoopGuard} detects when a context is repeating the same
 # tool-call pattern instead of making progress. It is directly inspired by
-# General Intelligence Systems' Brute runtime and its doom-loop detection
-# approach.
+# General Intelligence Systems and its doom-loop detection approach.
 #
 # The public interface is intentionally small:
 # - `call(ctx)` returns `nil` when no intervention is needed
@@ -22,14 +21,6 @@
 # {LLM::Agent LLM::Agent} enables this guard by default through its wrapped
 # context.
 #
-# Brute is MIT licensed. The relevant license grant is:
-#
-#   Permission is hereby granted, free of charge, to any person obtaining a copy
-#   of this software and associated documentation files (the "Software"), to deal
-#   in the Software without restriction, including without limitation the rights
-#   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-#   copies of the Software, and to permit persons to whom the Software is
-#   furnished to do so.
 class LLM::LoopGuard
   ##
   # The default number of repeated tool-call patterns required before

data/lib/llm/provider/transport/http.rb

@@ -71,7 +71,7 @@ class LLM::Provider
       ##
       # @return [Boolean]
       def persistent?
-        !persistent_client.nil?
+        !@persistent_client.nil?
       end
 
       ##

data/lib/llm/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 6.1.0
+  version: 7.0.0
 platform: ruby
 authors:
 - Antar Azri