86: Add default limit for tools completions

Gemfile

@@ -13,6 +13,7 @@ group :development do
   gem 'bundler', '>= 2.0'
   gem 'codecov'
   gem 'dotenv'
+  gem 'faker'
   gem 'ferrum'
   gem 'irb'
   gem 'nokogiri'
@@ -31,4 +32,4 @@ group :development do
   gem 'vcr'
   gem 'webmock', '~> 3.18'
   gem 'yard', '>= 0.9'
-end
+end

docs/guides/tools.md

@@ -292,13 +292,52 @@ end
 
 > Note: For parameters with limited valid values, clearly specify them in the description.
 
+## Maximum Tool Completion Limiting
+
+When including tools it is important to consider if the response could trigger unintended recursive calls to the provider. RubyLLM provides built-in protection by providing a default limit of 25, which can be overridden or turned off entirely.
+
+This can be performed on a per chat basis or provided in the global configuration.
+
+```ruby
+# Set a maximum number of tool completions per instantiated chat object
+chat = RubyLLM.chat(max_tool_completions: 5)
+chat.ask "Question that triggers tools loop"
+# => `execute_tool': Tool completions limit reached: 5 (RubyLLM::ToolCallCompletionsReachedError)
+```
+
+If you wish to remove this safe-guard you can set the max_tool_completions to `nil`.
+```ruby
+chat = RubyLLM.chat(max_tool_completions: nil)
+chat.ask "Question that triggers tools loop"
+# Loops until you've used all your credit...
+```
+
+### Global Configuration
+
+You can set a default maximum tool completion limit for all chats through the global configuration:
+
+```ruby
+RubyLLM.configure do |config|
+  # Default is 25 calls per conversation
+  config.max_tool_completions = 10  # Set a more conservative limit
+end
+```
+
+This setting can still be overridden per-chat when needed:
+
+```ruby
+# Override the global setting for this specific chat
+chat = RubyLLM.chat(max_tool_completions: 15)
+```
+
 ## Security Considerations
 
 When implementing tools that process user input (via the AI):
 
 * Avoid using `eval`, `system` or similar methods with unsanitized input
 * Remember that AI models might be tricked into producing dangerous inputs
 * Validate all inputs and use appropriate sanitization
+* Ensure protection against Cost-based Denial of Service from malicious input, particularly when used in conjunction with tool completions if you remove the default limit
 
 ## When to Use Tools
 

lib/ruby_llm.rb

@@ -30,8 +30,8 @@ module RubyLLM
   class Error < StandardError; end
 
   class << self
-    def chat(model: nil, provider: nil)
-      Chat.new(model: model, provider: provider)
+    def chat(model: nil, provider: nil, max_tool_completions: config.max_tool_completions)
+      Chat.new(model: model, provider: provider, max_tool_completions: max_tool_completions)
     end
 
     def embed(...)

lib/ruby_llm/chat.rb

@@ -11,9 +11,9 @@ module RubyLLM
   class Chat
     include Enumerable
 
-    attr_reader :model, :messages, :tools
+    attr_reader :model, :messages, :tools, :number_of_tool_completions
 
-    def initialize(model: nil, provider: nil)
+    def initialize(model: nil, provider: nil, max_tool_completions: nil)
       model_id = model || RubyLLM.config.default_model
       with_model(model_id, provider: provider)
       @temperature = 0.7
@@ -23,9 +23,13 @@ def initialize(model: nil, provider: nil)
         new_message: nil,
         end_message: nil
       }
+      @max_tool_completions = max_tool_completions
+      @number_of_tool_completions = 0
     end
 
     def ask(message = nil, with: {}, &block)
+      @number_of_tool_completions = 0
+
       add_message role: :user, content: Content.new(message, with)
       complete(&block)
     end
@@ -108,6 +112,11 @@ def handle_tool_calls(response, &)
         @on[:end_message]&.call(message)
       end
 
+      if max_tool_completions_reached?
+        raise ToolCallCompletionsLimitReachedError, "Tool completions limit reached: #{@max_tool_completions}"
+      end
+
+      @number_of_tool_completions += 1
       complete(&)
     end
 
@@ -124,5 +133,11 @@ def add_tool_result(tool_use_id, result)
         tool_call_id: tool_use_id
       )
     end
+
+    def max_tool_completions_reached?
+      return false unless @max_tool_completions
+
+      @number_of_tool_completions >= @max_tool_completions
+    end
   end
 end

lib/ruby_llm/configuration.rb

@@ -22,14 +22,16 @@ class Configuration
                   :default_embedding_model,
                   :default_image_model,
                   :request_timeout,
-                  :max_retries
+                  :max_retries,
+                  :max_tool_completions
 
     def initialize
       @request_timeout = 120
       @max_retries = 3
       @default_model = 'gpt-4o-mini'
       @default_embedding_model = 'text-embedding-3-small'
       @default_image_model = 'dall-e-3'
+      @max_tool_completions = 25
     end
   end
 end

lib/ruby_llm/error.rb

@@ -24,6 +24,7 @@ class ConfigurationError < StandardError; end
   class InvalidRoleError < StandardError; end
   class ModelNotFoundError < StandardError; end
   class UnsupportedFunctionsError < StandardError; end
+  class ToolCallCompletionsLimitReachedError < StandardError; end
 
   # Error classes for different HTTP status codes
   class BadRequestError < Error; end