Adopt larastan and resolve PHPStan level 2 errors

composer.json

@@ -25,12 +25,12 @@
         "laravel/serializable-closure": "^2.0"
     },
     "require-dev": {
+        "larastan/larastan": "^3.9",
         "laravel/pint": "^1.26",
         "mockery/mockery": "^1.6.12",
         "orchestra/testbench": "^10.6|^11.0",
         "pestphp/pest": "^3.0|^4.0",
-        "pestphp/pest-plugin-laravel": "^3.0|^4.0",
-        "phpstan/phpstan": "^2.1"
+        "pestphp/pest-plugin-laravel": "^3.0|^4.0"
     },
     "minimum-stability": "dev",
     "prefer-stable": true,

phpstan.neon.dist

@@ -1,7 +1,12 @@
+includes:
+  - vendor/larastan/larastan/extension.neon
+
 parameters:
   paths:
     - config
     - src
     - database
 
-  level: 1
+  level: 2
+
+  noEnvCallsOutsideOfConfig: false

src/Contracts/Providers/AudioProvider.php

@@ -5,7 +5,7 @@
 use Laravel\Ai\Contracts\Gateway\AudioGateway;
 use Laravel\Ai\Responses\AudioResponse;
 
-interface AudioProvider
+interface AudioProvider extends Provider
 {
     /**
      * Generate audio from the given text.

src/Contracts/Providers/EmbeddingProvider.php

@@ -5,7 +5,7 @@
 use Laravel\Ai\Contracts\Gateway\EmbeddingGateway;
 use Laravel\Ai\Responses\EmbeddingsResponse;
 
-interface EmbeddingProvider
+interface EmbeddingProvider extends Provider
 {
     /**
      * Get embedding vectors representing the given inputs.

src/Contracts/Providers/FileProvider.php

@@ -7,7 +7,7 @@
 use Laravel\Ai\Responses\FileResponse;
 use Laravel\Ai\Responses\StoredFileResponse;
 
-interface FileProvider
+interface FileProvider extends Provider
 {
     /**
      * Get a file by its ID.

src/Contracts/Providers/ImageProvider.php

@@ -6,7 +6,7 @@
 use Laravel\Ai\Files\Image;
 use Laravel\Ai\Responses\ImageResponse;
 
-interface ImageProvider
+interface ImageProvider extends Provider
 {
     /**
      * Generate an image.

src/Contracts/Providers/Provider.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Laravel\Ai\Contracts\Providers;
+
+interface Provider
+{
+    /**
+     * Get the name of the underlying AI provider.
+     */
+    public function name(): string;
+
+    /**
+     * Get the name of the underlying AI driver.
+     */
+    public function driver(): string;
+
+    /**
+     * Get the credentials for the underlying AI provider.
+     *
+     * @return array<string, mixed>
+     */
+    public function providerCredentials(): array;
+
+    /**
+     * Get the provider connection configuration other than the driver, key, and name.
+     *
+     * @return array<string, mixed>
+     */
+    public function additionalConfiguration(): array;
+}

src/Contracts/Providers/RerankingProvider.php

@@ -5,7 +5,7 @@
 use Laravel\Ai\Contracts\Gateway\RerankingGateway;
 use Laravel\Ai\Responses\RerankingResponse;
 
-interface RerankingProvider
+interface RerankingProvider extends Provider
 {
     /**
      * Rerank the given documents based on their relevance to the query.

src/Contracts/Providers/StoreProvider.php

@@ -8,7 +8,7 @@
 use Laravel\Ai\Contracts\Gateway\StoreGateway;
 use Laravel\Ai\Store;
 
-interface StoreProvider
+interface StoreProvider extends Provider
 {
     /**
      * Get a vector store by its ID.
@@ -27,8 +27,10 @@ public function createStore(
 
     /**
      * Add a file to a vector store.
+     *
+     * @param  array<string, mixed>  $metadata
      */
-    public function addFileToStore(string $storeId, HasProviderId $file): string;
+    public function addFileToStore(string $storeId, HasProviderId $file, array $metadata = []): string;
 
     /**
      * Remove a file from a vector store.

src/Contracts/Providers/TextProvider.php

@@ -7,7 +7,7 @@
 use Laravel\Ai\Responses\AgentResponse;
 use Laravel\Ai\Responses\StreamableAgentResponse;
 
-interface TextProvider
+interface TextProvider extends Provider
 {
     /**
      * Invoke the given agent.

src/Contracts/Providers/TranscriptionProvider.php

@@ -6,7 +6,7 @@
 use Laravel\Ai\Contracts\Gateway\TranscriptionGateway;
 use Laravel\Ai\Responses\TranscriptionResponse;
 
-interface TranscriptionProvider
+interface TranscriptionProvider extends Provider
 {
     /**
      * Generate audio from the given text.

src/Events/AgentFailedOver.php

@@ -3,8 +3,8 @@
 namespace Laravel\Ai\Events;
 
 use Laravel\Ai\Contracts\Agent;
+use Laravel\Ai\Contracts\Providers\Provider;
 use Laravel\Ai\Exceptions\FailoverableException;
-use Laravel\Ai\Providers\Provider;
 
 class AgentFailedOver extends ProviderFailedOver
 {

src/Events/ProviderFailedOver.php

@@ -2,8 +2,8 @@
 
 namespace Laravel\Ai\Events;
 
+use Laravel\Ai\Contracts\Providers\Provider;
 use Laravel\Ai\Exceptions\FailoverableException;
-use Laravel\Ai\Providers\Provider;
 
 class ProviderFailedOver
 {

src/Gateway/Anthropic/AnthropicGateway.php

@@ -124,7 +124,7 @@ public function streamText(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             $body,
             0,
             null,

src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php

@@ -470,7 +470,7 @@ protected function handleStreamingToolCalls(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             $requestBody,
             $depth + 1,
             $maxSteps,
@@ -516,7 +516,7 @@ protected function resumeFromPauseTurn(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             $requestBody,
             $depth + 1,
             $maxSteps,

src/Gateway/AzureOpenAi/AzureOpenAiGateway.php

@@ -127,7 +127,7 @@ public function streamText(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             0,
             null,
             $timeout,

src/Gateway/Bedrock/Concerns/MapsAttachments.php

@@ -6,6 +6,7 @@
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\Storage;
 use InvalidArgumentException;
+use Laravel\Ai\Contracts\Files\StorableFile;
 use Laravel\Ai\Files\Base64Document;
 use Laravel\Ai\Files\Base64Image;
 use Laravel\Ai\Files\Document;
@@ -54,7 +55,7 @@ protected function mapAttachments(Collection $attachments): array
     /**
      * Build a Bedrock document content block.
      */
-    protected function buildDocumentBlock(Document $document): array
+    protected function buildDocumentBlock(Document&StorableFile $document): array
     {
         return [
             'document' => [
@@ -70,7 +71,7 @@ protected function buildDocumentBlock(Document $document): array
     /**
      * Build a Bedrock image content block.
      */
-    protected function buildImageBlock(Image $image, string $bytes): array
+    protected function buildImageBlock(Image&StorableFile $image, string $bytes): array
     {
         return [
             'image' => [
@@ -85,7 +86,7 @@ protected function buildImageBlock(Image $image, string $bytes): array
     /**
      * Map a Document's MIME type to a Bedrock document format.
      */
-    protected function getDocumentFormat(Document $document): string
+    protected function getDocumentFormat(Document&StorableFile $document): string
     {
         $mime = strtolower(trim(strtok($document->mimeType() ?? 'text/plain', ';')));
 
@@ -124,7 +125,7 @@ protected function getDocumentName(Document $document): string
      *
      * @throws InvalidArgumentException if the MIME type cannot be determined or is unsupported.
      */
-    protected function getImageFormat(Image $image): string
+    protected function getImageFormat(Image&StorableFile $image): string
     {
         $mime = $image->mimeType();
 

src/Gateway/DeepSeek/Concerns/HandlesTextStreaming.php

@@ -363,7 +363,7 @@ protected function handleStreamingToolCalls(
                 $tools,
                 $schema,
                 $options,
-                $response->getBody(),
+                $response->toPsrResponse()->getBody(),
                 $instructions,
                 $originalMessages,
                 $depth + 1,

src/Gateway/DeepSeek/DeepSeekGateway.php

@@ -116,7 +116,7 @@ public function streamText(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             $instructions,
             $messages,
             0,

src/Gateway/FakeTextGateway.php

@@ -57,9 +57,7 @@ public function generateText(
         ?TextGenerationOptions $options = null,
         ?int $timeout = null,
     ): TextResponse {
-        $message = (new Collection($messages))->last(function ($message) {
-            return $message instanceof UserMessage;
-        });
+        $message = $this->lastUserMessageOrFail($messages);
 
         $response = $this->nextResponse(
             $provider, $model, $message->content, $message->attachments, $schema
@@ -135,9 +133,7 @@ public function streamText(
         yield new StreamStart(ulid(), $provider->name(), $model, time());
         yield new TextStart(ulid(), $messageId, time());
 
-        $message = (new Collection($messages))->last(function ($message) {
-            return $message instanceof UserMessage;
-        });
+        $message = $this->lastUserMessageOrFail($messages);
 
         $fakeResponse = $this->nextResponse(
             $provider, $model, $message->content, $message->attachments, $schema
@@ -162,6 +158,22 @@ public function streamText(
         yield new StreamEnd(ulid(), 'stop', new Usage, time());
     }
 
+    /**
+     * Get the most recent user message in the conversation.
+     *
+     * @param  array<int, mixed>  $messages
+     */
+    protected function lastUserMessageOrFail(array $messages): UserMessage
+    {
+        $message = (new Collection($messages))->last(fn ($message) => $message instanceof UserMessage);
+
+        if (! $message instanceof UserMessage) {
+            throw new RuntimeException('A user message is required to fake a text response.');
+        }
+
+        return $message;
+    }
+
     /**
      * Get the next response instance.
      */

src/Gateway/Gemini/Concerns/HandlesTextStreaming.php

@@ -287,7 +287,7 @@ protected function handleStreamingToolCalls(
                 $tools,
                 $schema,
                 $options,
-                $response->getBody(),
+                $response->toPsrResponse()->getBody(),
                 $contents,
                 $instructions,
                 $depth + 1,

src/Gateway/Gemini/GeminiGateway.php

@@ -120,7 +120,7 @@ public function streamText(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             $contents,
             $instructions,
             0,

src/Gateway/Groq/Concerns/HandlesTextStreaming.php

@@ -309,7 +309,7 @@ protected function handleStreamingToolCalls(
                 $tools,
                 $schema,
                 $options,
-                $response->getBody(),
+                $response->toPsrResponse()->getBody(),
                 $instructions,
                 $originalMessages,
                 $depth + 1,

src/Gateway/Groq/GroqGateway.php

@@ -116,7 +116,7 @@ public function streamText(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             $instructions,
             $messages,
             0,

src/Gateway/Mistral/Concerns/HandlesTextStreaming.php

@@ -277,7 +277,7 @@ protected function handleStreamingToolCalls(
                 $tools,
                 $schema,
                 $options,
-                $response->getBody(),
+                $response->toPsrResponse()->getBody(),
                 $instructions,
                 $originalMessages,
                 $depth + 1,

src/Gateway/Mistral/MistralGateway.php

@@ -127,7 +127,7 @@ public function streamText(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             $instructions,
             $messages,
             timeout: $timeout,

src/Gateway/Ollama/Concerns/HandlesTextStreaming.php

@@ -307,7 +307,7 @@ protected function handleStreamingToolCalls(
                 $tools,
                 $schema,
                 $options,
-                $response->getBody(),
+                $response->toPsrResponse()->getBody(),
                 $instructions,
                 $originalMessages,
                 $depth + 1,

src/Gateway/Ollama/OllamaGateway.php

@@ -118,7 +118,7 @@ public function streamText(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             $instructions,
             $messages,
             0,

src/Gateway/OpenAi/Concerns/HandlesTextStreaming.php

@@ -402,7 +402,7 @@ protected function handleStreamingToolCalls(
                 $tools,
                 $schema,
                 $options,
-                $response->getBody(),
+                $response->toPsrResponse()->getBody(),
                 $depth + 1,
                 $maxSteps,
                 $timeout,

src/Gateway/OpenAi/OpenAiGateway.php

@@ -115,7 +115,7 @@ public function streamText(
             $tools,
             $schema,
             $options,
-            $response->getBody(),
+            $response->toPsrResponse()->getBody(),
             0,
             null,
             $timeout,