86: Add default limit for tools completions

docs/guides/tools.md

@@ -243,6 +243,46 @@ class DataAnalysis < RubyLLM::Tool
 end
 ```
 
+## Maximum Tools Call Limiting
+
+When calling tools it is important to consider if you're response could trigger a loop. RubyLLM provides built-in protection against infinite tool call loops:
+
+```ruby
+# Set a maximum number of tool calls per conversation
+chat = RubyLLM.chat(max_tool_calls: 5)
+
+# The chat will stop after 5 tool calls and return an error
+response = chat.ask "What's the weather in every major city?"
+# => "I apologize, but I've reached the maximum number of tool calls (5) for this conversation. 
+#     Please try breaking down your request into smaller, more focused questions."
+```
+
+### Global Configuration
+
+You can set a default maximum tool calls limit for all chats through the global configuration:
+
+```ruby
+RubyLLM.configure do |config|
+  # Default is 25 calls per conversation
+  config.max_tool_calls = 10  # Set a more conservative limit
+end
+```
+
+If you wish to remove this safe-guard you can set the max_tool_calls to `nil`.
+```ruby
+RubyLLM.configure do |config|
+  # Unlimited tools calls allowed
+  config.max_tool_calls = nil
+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_calls: 15)
+```
+
 ## Security Considerations
 
 When implementing tools that process user input (via the AI):

lib/ruby_llm.rb

@@ -29,8 +29,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_calls: config.max_tool_calls)
+      Chat.new(model: model, provider: provider, max_tool_calls: max_tool_calls)
     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_calls
 
-    def initialize(model: nil, provider: nil)
+    def initialize(model: nil, provider: nil, max_tool_calls: nil) # rubocop:disable Metrics/MethodLength
       model_id = model || RubyLLM.config.default_model
       with_model(model_id, provider: provider)
       @temperature = 0.7
@@ -23,6 +23,8 @@ def initialize(model: nil, provider: nil)
         new_message: nil,
         end_message: nil
       }
+      @max_tool_calls = max_tool_calls
+      @number_of_tool_calls = 0
     end
 
     def ask(message = nil, with: {}, &block)
@@ -105,6 +107,10 @@ def handle_tool_calls(response, &)
     end
 
     def execute_tool(tool_call)
+      raise ToolCallsLimitReachedError, "Tool calls limit reached: #{@max_tool_calls}" if max_tool_calls_reached?
+
+      @number_of_tool_calls += 1
+
       tool = tools[tool_call.name.to_sym]
       args = tool_call.arguments
       tool.call(args)
@@ -117,5 +123,11 @@ def add_tool_result(tool_use_id, result)
         tool_call_id: tool_use_id
       )
     end
+
+    def max_tool_calls_reached?
+      return false unless @max_tool_calls
+
+      @number_of_tool_calls >= @max_tool_calls
+    end
   end
 end

lib/ruby_llm/configuration.rb

@@ -18,14 +18,16 @@ class Configuration
                   :default_embedding_model,
                   :default_image_model,
                   :request_timeout,
-                  :max_retries
+                  :max_retries,
+                  :max_tool_calls
 
     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_calls = 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 ToolCallsLimitReachedError < StandardError; end
 
   # Error classes for different HTTP status codes
   class BadRequestError < Error; end