86: Add default limit for tools completions

docs/guides/tools.md

@@ -200,6 +200,52 @@ Proper error handling within your `execute` method is crucial.
 
 See the [Error Handling Guide]({% link guides/error-handling.md %}#handling-errors-within-tools) for more discussion.
 
+## Maximum Tool LLM Requests
+
+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.
+
+Note this is a limit on the number of requests made to the provider, not the number of tool calls made by the application. **The limit is checked after all the requested tool executions have been performed**, this is to prevent the chat from 
+becoming invalid if you wish to continue the conversation after the error.
+
+This can be performed on a per chat basis using `RubyLLM.context` (see configuration documentation) or provided in the global configuration.
+
+```ruby
+RubyLLM.configure do |config|
+  config.max_tool_llm_calls = 5
+end
+chat.ask "Question that triggers tools loop"
+# => `execute_tool': Tool LLM calls limit reached: (RubyLLM::ToolCallLimitReachedError)
+```
+
+If you wish to remove this safe-guard you can set the max_tool_llm_calls to `nil`.
+```ruby
+RubyLLM.configure do |config|
+  config.max_tool_llm_calls = nil  # No limit
+end
+chat = RubyLLM.chat
+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_llm_calls = 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
+context = RubyLLM.context { |ctx| ctx.max_tool_llm_calls = 5 }
+chat = RubyLLM.chat.with_context(context)
+```
+
 ## Security Considerations
 
 {: .warning }
@@ -208,6 +254,7 @@ Treat any arguments passed to your `execute` method as potentially untrusted use
 *   **NEVER** use methods like `eval`, `system`, `send`, or direct SQL interpolation with raw arguments from the AI.
 *   **Validate and Sanitize:** Always validate parameter types, ranges, formats, and allowed values. Sanitize strings to prevent injection attacks if they are used in database queries or system commands (though ideally, avoid direct system commands).
 *   **Principle of Least Privilege:** Ensure the code within `execute` only has access to the resources it absolutely needs.
+*   **Cost-based Denial of Service:** Ensure protection against malicious input or usage, particularly when used in conjunction with tool calls if you remove the default limit.
 
 ## Next Steps
 

lib/ruby_llm/chat.rb

@@ -29,9 +29,13 @@ def initialize(model: nil, provider: nil, assume_model_exists: false, context: n
         new_message: nil,
         end_message: nil
       }
+      @max_tool_llm_calls = @config.max_tool_llm_calls
+      @number_of_tool_llm_calls = 0
     end
 
     def ask(message = nil, with: nil, &)
+      @number_of_tool_llm_calls = 0
+
       add_message role: :user, content: Content.new(message, with)
       complete(&)
     end
@@ -73,7 +77,10 @@ def with_temperature(temperature)
 
     def with_context(context)
       @context = context
-      @config = context.config
+      if context.config
+        @config = context.config
+        @max_tool_llm_calls = @config.max_tool_llm_calls
+      end
       with_model(@model.id, provider: @provider.slug, assume_exists: true)
       self
     end
@@ -125,13 +132,20 @@ def reset_messages!
     private
 
     def handle_tool_calls(response, &)
+      @number_of_tool_llm_calls += 1
+
       response.tool_calls.each_value do |tool_call|
         @on[:new_message]&.call
         result = execute_tool tool_call
         message = add_tool_result tool_call.id, result
         @on[:end_message]&.call(message)
       end
 
+      # Perform this afterwards to ensure messages remain valid for the next call
+      if max_tool_llm_calls_reached?
+        raise ToolCallLimitReachedError, "Tool LLM calls limit reached: #{@max_tool_llm_calls}"
+      end
+
       complete(&)
     end
 
@@ -148,5 +162,11 @@ def add_tool_result(tool_use_id, result)
         tool_call_id: tool_use_id
       )
     end
+
+    def max_tool_llm_calls_reached?
+      return false unless @max_tool_llm_calls
+
+      @number_of_tool_llm_calls >= @max_tool_llm_calls
+    end
   end
 end

lib/ruby_llm/configuration.rb

@@ -24,6 +24,8 @@ class Configuration
                   :bedrock_session_token,
                   :openrouter_api_key,
                   :ollama_api_base,
+                  # Default tool configuration
+                  :max_tool_llm_calls,
                   # Default models
                   :default_model,
                   :default_embedding_model,
@@ -54,6 +56,9 @@ def initialize
       @default_embedding_model = 'text-embedding-3-small'
       @default_image_model = 'dall-e-3'
 
+      # Default restrictions
+      @max_tool_llm_calls = 25
+
       # Logging configuration
       @log_file = $stdout
       @log_level = ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO

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 ToolCallLimitReachedError < StandardError; end
   class UnsupportedAttachmentError < StandardError; end
 
   # Error classes for different HTTP status codes