refactor: make provider contract abstract (#434)

Author: ChrisB-TL

docs/advanced/custom-providers.md

@@ -4,27 +4,13 @@ Want to add support for a new AI provider in Prism? This guide will walk you thr
 
 ## Provider Interface
 
-All providers must implement the `Prism\Prism\Contracts\Provider` interface:
+All providers must extend the `Prism\Prism\Providers\Provider` class.
 
-```php
-use Prism\Prism\Embeddings\Request as EmbeddingsRequest;
-use Prism\Prism\Embeddings\Response as EmbeddingsResponse;
-use Prism\Prism\Structured\Request as StructuredRequest;
-use Prism\Prism\Structured\Response as StructuredResponse;
-use Prism\Prism\Text\Request as TextRequest;
-use Prism\Prism\Text\Response as TextResponse;
-
-interface Provider
-{
-    public function text(TextRequest $request): TextResponse;
-
-    public function structured(StructuredRequest $request): StructuredResponse;
-
-    public function embeddings(EmbeddingsRequest $request): EmbeddingsResponse;
-}
-```
+The abstract class has a default method for all current required methods, though this may change.
 
-The interface is intentionally simple, requiring just one method to handle text generation requests.
+Each provider should:
+- Overwrite the methods for the actions it supports. 
+- Overwrite the `handleRequestExceptions` method if supports advanced request exceptions.
 
 ## Registration Process
 

src/Concerns/ConfiguresProviders.php

@@ -4,9 +4,9 @@
 
 namespace Prism\Prism\Concerns;
 
-use Prism\Prism\Contracts\Provider;
 use Prism\Prism\Enums\Provider as ProviderEnum;
 use Prism\Prism\PrismManager;
+use Prism\Prism\Providers\Provider;
 
 trait ConfiguresProviders
 {

src/Contracts/Provider.php

@@ -4,12 +4,12 @@
 
 namespace Prism\Prism;
 
-use Prism\Prism\Contracts\Provider;
 use Prism\Prism\Embeddings\PendingRequest as PendingEmbeddingRequest;
 use Prism\Prism\Embeddings\Response as EmbeddingResponse;
 use Prism\Prism\Enums\Provider as ProviderEnum;
 use Prism\Prism\Images\PendingRequest as PendingImageRequest;
 use Prism\Prism\Images\Response as ImageResponse;
+use Prism\Prism\Providers\Provider;
 use Prism\Prism\Structured\PendingRequest as PendingStructuredRequest;
 use Prism\Prism\Structured\Response as StructuredResponse;
 use Prism\Prism\Testing\PrismFake;

src/Prism.php

@@ -7,7 +7,6 @@
 use Closure;
 use Illuminate\Contracts\Foundation\Application;
 use InvalidArgumentException;
-use Prism\Prism\Contracts\Provider;
 use Prism\Prism\Enums\Provider as ProviderEnum;
 use Prism\Prism\Providers\Anthropic\Anthropic;
 use Prism\Prism\Providers\DeepSeek\DeepSeek;
@@ -16,6 +15,7 @@
 use Prism\Prism\Providers\Mistral\Mistral;
 use Prism\Prism\Providers\Ollama\Ollama;
 use Prism\Prism\Providers\OpenAI\OpenAI;
+use Prism\Prism\Providers\Provider;
 use Prism\Prism\Providers\VoyageAI\VoyageAI;
 use Prism\Prism\Providers\XAI\XAI;
 use RuntimeException;

src/PrismManager.php

@@ -8,34 +8,30 @@
 use Illuminate\Http\Client\PendingRequest;
 use Illuminate\Http\Client\RequestException;
 use Prism\Prism\Concerns\InitializesClient;
-use Prism\Prism\Contracts\Provider;
-use Prism\Prism\Embeddings\Request as EmbeddingRequest;
-use Prism\Prism\Embeddings\Response as EmbeddingResponse;
 use Prism\Prism\Enums\Provider as ProviderName;
 use Prism\Prism\Exceptions\PrismException;
 use Prism\Prism\Exceptions\PrismProviderOverloadedException;
 use Prism\Prism\Exceptions\PrismRateLimitedException;
 use Prism\Prism\Exceptions\PrismRequestTooLargeException;
-use Prism\Prism\Images\Request as ImagesRequest;
-use Prism\Prism\Images\Response as ImagesResponse;
 use Prism\Prism\Providers\Anthropic\Concerns\ProcessesRateLimits;
 use Prism\Prism\Providers\Anthropic\Handlers\Stream;
 use Prism\Prism\Providers\Anthropic\Handlers\Structured;
 use Prism\Prism\Providers\Anthropic\Handlers\Text;
+use Prism\Prism\Providers\Provider;
 use Prism\Prism\Structured\Request as StructuredRequest;
 use Prism\Prism\Structured\Response as StructuredResponse;
 use Prism\Prism\Text\Request as TextRequest;
 use Prism\Prism\Text\Response as TextResponse;
 use Throwable;
 
-readonly class Anthropic implements Provider
+class Anthropic extends Provider
 {
     use InitializesClient, ProcessesRateLimits;
 
     public function __construct(
-        #[\SensitiveParameter] public string $apiKey,
-        public string $apiVersion,
-        public ?string $betaFeatures = null
+        #[\SensitiveParameter] readonly public string $apiKey,
+        readonly public string $apiVersion,
+        readonly public ?string $betaFeatures = null
     ) {}
 
     #[\Override]
@@ -77,18 +73,6 @@ public function stream(TextRequest $request): Generator
         return $handler->handle($request);
     }
 
-    #[\Override]
-    public function embeddings(EmbeddingRequest $request): EmbeddingResponse
-    {
-        throw new \Exception(sprintf('%s does not support embeddings', class_basename($this)));
-    }
-
-    #[\Override]
-    public function images(ImagesRequest $request): ImagesResponse
-    {
-        throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
-    }
-
     public function handleRequestExceptions(string $model, Throwable $e): never
     {
         if ($e instanceof PrismException) {

src/Providers/Anthropic/Anthropic.php

@@ -4,30 +4,24 @@
 
 namespace Prism\Prism\Providers\DeepSeek;
 
-use Generator;
 use Illuminate\Http\Client\PendingRequest;
 use Prism\Prism\Concerns\HandlesRequestExceptions;
 use Prism\Prism\Concerns\InitializesClient;
-use Prism\Prism\Contracts\Provider;
-use Prism\Prism\Embeddings\Request as EmbeddingsRequest;
-use Prism\Prism\Embeddings\Response as EmbeddingsResponse;
-use Prism\Prism\Exceptions\PrismException;
-use Prism\Prism\Images\Request as ImagesRequest;
-use Prism\Prism\Images\Response as ImagesResponse;
 use Prism\Prism\Providers\DeepSeek\Handlers\Structured;
 use Prism\Prism\Providers\DeepSeek\Handlers\Text;
+use Prism\Prism\Providers\Provider;
 use Prism\Prism\Structured\Request as StructuredRequest;
 use Prism\Prism\Structured\Response as StructuredResponse;
 use Prism\Prism\Text\Request as TextRequest;
 use Prism\Prism\Text\Response as TextResponse;
 
-readonly class DeepSeek implements Provider
+class DeepSeek extends Provider
 {
     use HandlesRequestExceptions, InitializesClient;
 
     public function __construct(
-        #[\SensitiveParameter] public string $apiKey,
-        public string $url,
+        #[\SensitiveParameter] readonly public string $apiKey,
+        readonly public string $url,
     ) {}
 
     #[\Override]
@@ -52,24 +46,6 @@ public function structured(StructuredRequest $request): StructuredResponse
         return $handler->handle($request);
     }
 
-    #[\Override]
-    public function embeddings(EmbeddingsRequest $request): EmbeddingsResponse
-    {
-        throw PrismException::unsupportedProviderAction(__FUNCTION__, class_basename($this));
-    }
-
-    #[\Override]
-    public function images(ImagesRequest $request): ImagesResponse
-    {
-        throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
-    }
-
-    #[\Override]
-    public function stream(TextRequest $request): Generator
-    {
-        throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
-    }
-
     /**
      * @param  array<string, mixed>  $options
      * @param  array<mixed>  $retry

src/Providers/DeepSeek/DeepSeek.php

@@ -9,31 +9,29 @@
 use Prism\Prism\Concerns\HandlesRequestExceptions;
 use Prism\Prism\Concerns\InitializesClient;
 use Prism\Prism\Contracts\Message;
-use Prism\Prism\Contracts\Provider;
 use Prism\Prism\Embeddings\Request as EmbeddingRequest;
 use Prism\Prism\Embeddings\Response as EmbeddingResponse;
 use Prism\Prism\Exceptions\PrismException;
-use Prism\Prism\Images\Request as ImagesRequest;
-use Prism\Prism\Images\Response as ImagesResponse;
 use Prism\Prism\Providers\Gemini\Handlers\Cache;
 use Prism\Prism\Providers\Gemini\Handlers\Embeddings;
 use Prism\Prism\Providers\Gemini\Handlers\Stream;
 use Prism\Prism\Providers\Gemini\Handlers\Structured;
 use Prism\Prism\Providers\Gemini\Handlers\Text;
 use Prism\Prism\Providers\Gemini\ValueObjects\GeminiCachedObject;
+use Prism\Prism\Providers\Provider;
 use Prism\Prism\Structured\Request as StructuredRequest;
 use Prism\Prism\Structured\Response as StructuredResponse;
 use Prism\Prism\Text\Request as TextRequest;
 use Prism\Prism\Text\Response as TextResponse;
 use Prism\Prism\ValueObjects\Messages\SystemMessage;
 
-readonly class Gemini implements Provider
+class Gemini extends Provider
 {
     use HandlesRequestExceptions, InitializesClient;
 
     public function __construct(
-        #[\SensitiveParameter] public string $apiKey,
-        public string $url,
+        #[\SensitiveParameter] readonly public string $apiKey,
+        readonly public string $url,
     ) {}
 
     #[\Override]
@@ -69,12 +67,6 @@ public function embeddings(EmbeddingRequest $request): EmbeddingResponse
         return $handler->handle($request);
     }
 
-    #[\Override]
-    public function images(ImagesRequest $request): ImagesResponse
-    {
-        throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
-    }
-
     #[\Override]
     public function stream(TextRequest $request): Generator
     {

src/Providers/Gemini/Gemini.php

@@ -4,36 +4,31 @@
 
 namespace Prism\Prism\Providers\Groq;
 
-use Generator;
 use Illuminate\Http\Client\PendingRequest;
 use Illuminate\Http\Client\RequestException;
 use Prism\Prism\Concerns\InitializesClient;
-use Prism\Prism\Contracts\Provider;
-use Prism\Prism\Embeddings\Request as EmbeddingRequest;
-use Prism\Prism\Embeddings\Response as EmbeddingResponse;
 use Prism\Prism\Enums\Provider as ProviderName;
 use Prism\Prism\Exceptions\PrismException;
 use Prism\Prism\Exceptions\PrismProviderOverloadedException;
 use Prism\Prism\Exceptions\PrismRateLimitedException;
 use Prism\Prism\Exceptions\PrismRequestTooLargeException;
-use Prism\Prism\Images\Request as ImagesRequest;
-use Prism\Prism\Images\Response as ImagesResponse;
 use Prism\Prism\Providers\Groq\Concerns\ProcessRateLimits;
 use Prism\Prism\Providers\Groq\Handlers\Structured;
 use Prism\Prism\Providers\Groq\Handlers\Text;
+use Prism\Prism\Providers\Provider;
 use Prism\Prism\Structured\Request as StructuredRequest;
 use Prism\Prism\Structured\Response as StructuredResponse;
 use Prism\Prism\Text\Request as TextRequest;
 use Prism\Prism\Text\Response as TextResponse;
 use Throwable;
 
-readonly class Groq implements Provider
+class Groq extends Provider
 {
     use InitializesClient, ProcessRateLimits;
 
     public function __construct(
-        #[\SensitiveParameter] public string $apiKey,
-        public string $url,
+        #[\SensitiveParameter] readonly public string $apiKey,
+        readonly public string $url,
     ) {}
 
     #[\Override]
@@ -52,24 +47,6 @@ public function structured(StructuredRequest $request): StructuredResponse
         return $handler->handle($request);
     }
 
-    #[\Override]
-    public function embeddings(EmbeddingRequest $request): EmbeddingResponse
-    {
-        throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
-    }
-
-    #[\Override]
-    public function images(ImagesRequest $request): ImagesResponse
-    {
-        throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
-    }
-
-    #[\Override]
-    public function stream(TextRequest $request): Generator
-    {
-        throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
-    }
-
     public function handleRequestExceptions(string $model, Throwable $e): never
     {
         if ($e instanceof PrismException) {

src/Providers/Groq/Groq.php

@@ -8,37 +8,35 @@
 use Illuminate\Http\Client\PendingRequest;
 use Illuminate\Http\Client\RequestException;
 use Prism\Prism\Concerns\InitializesClient;
-use Prism\Prism\Contracts\Provider;
 use Prism\Prism\Embeddings\Request as EmbeddingRequest;
 use Prism\Prism\Embeddings\Response as EmbeddingResponse;
 use Prism\Prism\Enums\Provider as ProviderName;
 use Prism\Prism\Exceptions\PrismException;
 use Prism\Prism\Exceptions\PrismProviderOverloadedException;
 use Prism\Prism\Exceptions\PrismRateLimitedException;
 use Prism\Prism\Exceptions\PrismRequestTooLargeException;
-use Prism\Prism\Images\Request as ImagesRequest;
-use Prism\Prism\Images\Response as ImagesResponse;
 use Prism\Prism\Providers\Mistral\Concerns\ProcessRateLimits;
 use Prism\Prism\Providers\Mistral\Handlers\Embeddings;
 use Prism\Prism\Providers\Mistral\Handlers\OCR;
 use Prism\Prism\Providers\Mistral\Handlers\Stream;
 use Prism\Prism\Providers\Mistral\Handlers\Structured;
 use Prism\Prism\Providers\Mistral\Handlers\Text;
 use Prism\Prism\Providers\Mistral\ValueObjects\OCRResponse;
+use Prism\Prism\Providers\Provider;
 use Prism\Prism\Structured\Request as StructuredRequest;
 use Prism\Prism\Structured\Response as StructuredResponse;
 use Prism\Prism\Text\Request as TextRequest;
 use Prism\Prism\Text\Response as TextResponse;
 use Prism\Prism\ValueObjects\Messages\Support\Document;
 use Throwable;
 
-readonly class Mistral implements Provider
+class Mistral extends Provider
 {
     use InitializesClient, ProcessRateLimits;
 
     public function __construct(
-        #[\SensitiveParameter] public string $apiKey,
-        public string $url,
+        #[\SensitiveParameter] readonly public string $apiKey,
+        readonly public string $url,
     ) {}
 
     #[\Override]
@@ -77,12 +75,6 @@ public function embeddings(EmbeddingRequest $request): EmbeddingResponse
         return $handler->handle($request);
     }
 
-    #[\Override]
-    public function images(ImagesRequest $request): ImagesResponse
-    {
-        throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
-    }
-
     /**
      * @throws PrismRateLimitedException
      * @throws PrismException