Refactor tool calling logic for improved clarity (#283)

* refactor: cleanup of the tool calling logic

* fix: add "hasItems" to ToolCallCollection

#283 (comment)

* fix: harden OpenAiToolCallingTrait

#283 (comment)

* fix: security breaking-point for infinite tool calling loops

Theoretically, this should not be an issue if the upstream clients handle the flags correctly,
but it is a nice fallback gate if something is implemented incorrectly.

#283 (comment)
and
#283 (comment)

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix: don't use ToolCallAiResponse as writable class

#283 (comment)

* fix: ensure LoggingClient does not leak private information

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: Neunerlei

_changelog/next.md

@@ -8,10 +8,15 @@
 
 [//]: # (- Improvements and enhancements that improve the user experience.)
 
+- AI Model errors will now be logged to the log file in addition to being printed to the screen, making it easier to debug issues in production.
+
 ### Bugfix
 
 [//]: # (- List of bugs that have been fixed in this version.)
 
+- Refactoring and code cleanup of the tool calling logic, improving readability and maintainability.
+- `bin/env dev` now no longer dies after 300 seconds, allowing for longer-running development sessions without interruption.
+
 ### Deprecation
 
 [//]: # (- List of features or functionalities that have been deprecated in this version.)

app/Services/AI/AiFactory.php

@@ -12,7 +12,10 @@
 use App\Services\AI\Interfaces\ClientInterface;
 use App\Services\AI\Interfaces\ModelProviderInterface;
 use App\Services\AI\Providers\GenericModelProvider;
+use App\Services\AI\Tools\ToolRegistry;
+use App\Services\AI\Utils\LoggingClient;
 use App\Services\AI\Utils\ModelAwareClient;
+use App\Services\AI\Utils\ToolCallingClient;
 use App\Services\AI\Value\AiModel;
 use App\Services\AI\Value\AiModelContext;
 use App\Services\AI\Value\AvailableAiModels;
@@ -21,6 +24,7 @@
 use Illuminate\Config\Repository;
 use Illuminate\Container\Attributes\Singleton;
 use Psr\Container\ContainerInterface;
+use Psr\Log\LoggerInterface;
 
 #[Singleton]
 class AiFactory
@@ -29,7 +33,8 @@ class AiFactory
 
     public function __construct(
         private readonly ContainerInterface $container,
-        private readonly Repository         $config
+        private readonly Repository   $config,
+        private readonly ToolRegistry $toolRegistry
     )
     {
     }
@@ -112,9 +117,15 @@ function (AiModel $model) use ($provider) {
                 return $this->rememberInstance(
                     'client_for_' . $provider->getConfig()->getId() . '_model_' . $model->getId(),
                     function () use ($provider, $model) {
-                        return new ModelAwareClient(
-                            $this->getClientForProvider($provider),
-                            $model
+                        return new LoggingClient(
+                            new ToolCallingClient(
+                                new ModelAwareClient(
+                                    $this->getClientForProvider($provider),
+                                    $model
+                                ),
+                                $this->toolRegistry
+                            ),
+                            $this->container->get(LoggerInterface::class)
                         );
                     }
                 );

app/Services/AI/AiService.php

@@ -5,25 +5,21 @@
 namespace App\Services\AI;
 
 
-use App\Models\Ai\Tools\AiTool;
 use App\Services\AI\Exception\ModelIdNotAvailableException;
 use App\Services\AI\Exception\ModelNotInPayloadException;
 use App\Services\AI\Exception\NoModelSetInRequestException;
-use App\Services\AI\Tools\ToolExecutionService;
 use App\Services\AI\Value\AiModel;
 use App\Services\AI\Value\AiRequest;
 use App\Services\AI\Value\AiResponse;
 use App\Services\AI\Value\AvailableAiModels;
 use App\Services\AI\Value\ModelUsageType;
 use Illuminate\Container\Attributes\Singleton;
-use Illuminate\Support\Facades\Log;
 
 #[Singleton]
 readonly class AiService
 {
     public function __construct(
-        private AiFactory $factory,
-        private ToolExecutionService $toolExecutionService
+        private AiFactory $factory
     )
     {
     }
@@ -77,48 +73,12 @@ public function getModelOrFail(string $modelId, ?bool $external = null): AiModel
      * If the response contains tool calls, they will be automatically executed and a follow-up request will be sent.
      *
      * @param array|AiRequest $request Either an AiRequest object or an array representing the request payload.
-     * @param int $maxToolRounds Maximum number of tool execution rounds to prevent infinite loops
      * @return AiResponse
      */
-    public function sendRequest(array|AiRequest $request, int $maxToolRounds = 2): AiResponse
+    public function sendRequest(array|AiRequest $request): AiResponse
     {
         [$request, $model] = $this->resolveRequestAndModel($request);
-
-        $round = 0;
-        $currentRequest = $request;
-        while (true) {
-            $response = $model->getClient()->sendRequest($currentRequest);
-//            \Log::info($response->content);
-            if (!$this->toolExecutionService->requiresToolExecution($response)) {
-                return $response;
-            }
-
-            Log::info('AiTool execution required', [
-                'round' => $round + 1,
-                'tool_count' => count($response->toolCalls),
-            ]);
-
-            $round++;
-
-            // If we've reached max rounds, send final request without tools
-            if ($round >= $maxToolRounds) {
-                Log::warning('Max tool execution rounds reached', ['max_rounds' => $maxToolRounds]);
-
-                $currentRequest = $this->toolExecutionService->buildFollowUpRequest(
-                    $currentRequest,
-                    $response,
-                    disableTools: true
-                );
-
-                return $model->getClient()->sendRequest($currentRequest);
-            }
-
-            // Build follow-up request with tool results
-            $currentRequest = $this->toolExecutionService->buildFollowUpRequest(
-                $currentRequest,
-                $response
-            );
-        }
+        return $model->getClient()->sendRequest($request);
     }
 
     /**
@@ -129,108 +89,12 @@ public function sendRequest(array|AiRequest $request, int $maxToolRounds = 2): A
      * @param array|AiRequest $request Either an AiRequest object or an array representing the request payload.
      * @param callable(AiResponse $response): void $onData A callback function that will be called with each chunk of data received.
      *                         The function should accept a single parameter of type AiResponse.
-     * @param int $maxToolRounds Maximum number of tool execution rounds to prevent infinite loops
      * @return void
      */
-    public function sendStreamRequest(array|AiRequest $request, callable $onData, int $maxToolRounds = 5): void
+    public function sendStreamRequest(array|AiRequest $request, callable $onData): void
     {
         [$request, $model] = $this->resolveRequestAndModel($request);
-
-        $round = 0;
-        $currentRequest = $request;
-        $lastCompleteResponse = null;
-
-        while (true) {
-            // Wrap onData to capture the final complete response and mask tool call completion
-            $wrappedOnData = function(AiResponse $response) use ($onData, &$lastCompleteResponse, $round) {
-                // If this is a tool call completion, don't tell the frontend it's done yet
-                // We'll continue with follow-up requests
-                if ($response->isDone && $response->finishReason === 'tool_calls') {
-                    // Create a modified response with isDone=false for the frontend
-                    $frontendResponse = new AiResponse(
-                        content: $response->content,
-                        usage: $response->usage,
-                        isDone: false, // Mask the completion
-                        error: $response->error,
-                        toolCalls: $response->toolCalls,
-                        finishReason: $response->finishReason,
-                        type: $response->type,
-                        status: $response->status
-                    );
-                    $onData($frontendResponse);
-                    $lastCompleteResponse = $response; // Keep the real response internally
-                } else {
-                    // Normal response or final completion - send as is
-                    $onData($response);
-                    if ($response->isDone) {
-                        $lastCompleteResponse = $response;
-                    }
-                }
-            };
-
-            // Send the streaming request
-            $model->getClient()->sendStreamRequest($currentRequest, $wrappedOnData);
-
-            // Check if tool execution is needed
-            if (!$lastCompleteResponse || !$this->toolExecutionService->requiresToolExecution($lastCompleteResponse)) {
-                // No tools needed or response complete, we're done
-                return;
-            }
-            $round++;
-
-            // Check if we've reached max rounds
-            if ($round >= $maxToolRounds) {
-                Log::warning('Max tool execution rounds reached in stream', ['max_rounds' => $maxToolRounds]);
-
-                // Send status about max rounds
-                $onData(
-                    new AiResponse(
-                        content: ['text' => ''],
-                        isDone: false,
-                        type: 'status',
-                        status: [
-                            'key' => 'max_execution',
-                            'value' => 'Maximum tool execution rounds reached. Generating final response...'
-                        ]
-                ));
-
-                // Build final request with tools disabled
-                $currentRequest = $this->toolExecutionService->buildFollowUpRequest(
-                    $currentRequest,
-                    $lastCompleteResponse,
-                    disableTools: true
-                );
-                // Send the final request directly and return
-                $model->getClient()->sendStreamRequest($currentRequest, $onData);
-                return;
-            }
-
-            // Send status message about tool execution
-            $toolNames = array_map(fn($tc) => $tc->name, $lastCompleteResponse->toolCalls);
-            $capabilities = [];
-            foreach ($toolNames as $toolName) {
-                $tool = AiTool::where('name', $toolName)->firstOrFail();
-                $capabilities[] = $tool->capability;
-            }
-//            \Log::info($capabilities);
-            $onData(new AiResponse(
-                content: ['text' => ''],
-                isDone: false,
-                type: 'status',
-                status: [
-                    'key' => 'tool_call',
-                    'value' => $capabilities
-                ]
-            ));
-            // Build follow-up request with tool results
-            $currentRequest = $this->toolExecutionService->buildFollowUpRequest(
-                $currentRequest,
-                $lastCompleteResponse
-            );
-
-            // Note: Don't reset $lastCompleteResponse to null here
-            // It will be overwritten in the next iteration when isDone=true
-        }
+        $model->getClient()->sendStreamRequest($request, $onData);
     }
 
     /**

app/Services/AI/Interfaces/ClientInterface.php

@@ -6,13 +6,25 @@
 
 
 use App\Services\AI\AiFactory;
+use App\Services\AI\Utils\ClientStack;
 use App\Services\AI\Value\AiModel;
 use App\Services\AI\Value\AiRequest;
 use App\Services\AI\Value\AiResponse;
 use App\Services\AI\Value\ModelOnlineStatus;
 
 interface ClientInterface
 {
+    /**
+     * Builds the client stack by collecting all clients in the chain.
+     * Each client can choose to add itself and/or child clients to the stack.
+     * The final result describes the chain from the top-level client down to the concrete model client,
+     * and is used for dedicated instance lookup in a nested call context.
+     * @param ClientStack $stack
+     * @return ClientStack
+     * @internal
+     */
+    public function buildStack(ClientStack $stack): ClientStack;
+
     /**
      * Injects the model provider to be used by the client.
      * This method is intended for internal use only and will be called by {@see AiFactory::getClientForProvider()}
@@ -21,15 +33,15 @@ interface ClientInterface
      * @internal
      */
     public function setProvider(ModelProviderInterface $provider): void;
-    
+
     /**
      * Sends a non-streaming request to the AI service.
      * The execution is synchronous and will wait for the full response.
      * @param AiRequest $request
      * @return AiResponse
      */
     public function sendRequest(AiRequest $request): AiResponse;
-    
+
     /**
      * Sends a streaming request to the AI service.
      * The execution is asynchronous and will invoke the $onData callback for each chunk of data received.
@@ -39,7 +51,7 @@ public function sendRequest(AiRequest $request): AiResponse;
      * @return void
      */
     public function sendStreamRequest(AiRequest $request, callable $onData): void;
-    
+
     /**
      * Sends a status check request for the given model.
      *