refactor: add extension point to payload contract handling

src/Bridge/OpenAI/DallE/ContractExtension.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\OpenAI\DallE;
+
+use PhpLlm\LlmChain\Bridge\OpenAI\DallE;
+use PhpLlm\LlmChain\Model\Model;
+use PhpLlm\LlmChain\Platform\Contract\Extension;
+
+final class ContractExtension implements Extension
+{
+    public function supports(Model $model): bool
+    {
+        return $model instanceof DallE;
+    }
+
+    public function registerTypes(): array
+    {
+        return [
+            'string' => 'handleInput',
+        ];
+    }
+
+    public function handleInput(string $input): array
+    {
+        return [
+            'prompt' => $input,
+        ];
+    }
+}

src/Bridge/OpenAI/DallE/ModelClient.php

@@ -28,18 +28,17 @@ public function __construct(
         Assert::startsWith($apiKey, 'sk-', 'The API key must start with "sk-".');
     }
 
-    public function supports(Model $model, array|string|object $input): bool
+    public function supports(Model $model): bool
     {
         return $model instanceof DallE;
     }
 
-    public function request(Model $model, object|array|string $input, array $options = []): HttpResponse
+    public function request(Model $model, array $payload, array $options = []): HttpResponse
     {
         return $this->httpClient->request('POST', 'https://api.openai.com/v1/images/generations', [
             'auth_bearer' => $this->apiKey,
-            'json' => \array_merge($options, [
+            'json' => \array_merge($options, $payload, [
                 'model' => $model->getName(),
-                'prompt' => $input,
             ]),
         ]);
     }

src/Bridge/OpenAI/Embeddings/ContractExtension.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\OpenAI\Embeddings;
+
+use PhpLlm\LlmChain\Bridge\OpenAI\Embeddings;
+use PhpLlm\LlmChain\Model\Model;
+use PhpLlm\LlmChain\Platform\Contract\Extension;
+
+final class ContractExtension implements Extension
+{
+    public function supports(Model $model): bool
+    {
+        return $model instanceof Embeddings;
+    }
+
+    public function registerTypes(): array
+    {
+        return [
+            'string' => 'handleInput',
+        ];
+    }
+
+    public function handleInput(string $input): array
+    {
+        return [
+            'input' => $input,
+        ];
+    }
+}

src/Bridge/OpenAI/Embeddings/ModelClient.php

@@ -22,18 +22,17 @@ public function __construct(
         Assert::startsWith($apiKey, 'sk-', 'The API key must start with "sk-".');
     }
 
-    public function supports(Model $model, array|string|object $input): bool
+    public function supports(Model $model): bool
     {
         return $model instanceof Embeddings;
     }
 
-    public function request(Model $model, object|array|string $input, array $options = []): ResponseInterface
+    public function request(Model $model, array $payload, array $options = []): ResponseInterface
     {
         return $this->httpClient->request('POST', 'https://api.openai.com/v1/embeddings', [
             'auth_bearer' => $this->apiKey,
-            'json' => array_merge($model->getOptions(), $options, [
+            'json' => array_merge($options, $payload, [
                 'model' => $model->getName(),
-                'input' => $input,
             ]),
         ]);
     }

src/Bridge/OpenAI/Embeddings/ResponseConverter.php

@@ -14,7 +14,7 @@
 
 final class ResponseConverter implements PlatformResponseConverter
 {
-    public function supports(Model $model, array|string|object $input): bool
+    public function supports(Model $model): bool
     {
         return $model instanceof Embeddings;
     }

src/Bridge/OpenAI/GPT/ModelClient.php

@@ -18,25 +18,26 @@
 
     public function __construct(
         HttpClientInterface $httpClient,
-        #[\SensitiveParameter] private string $apiKey,
+        #[\SensitiveParameter]
+        private string $apiKey,
     ) {
         $this->httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
         Assert::stringNotEmpty($apiKey, 'The API key must not be empty.');
         Assert::startsWith($apiKey, 'sk-', 'The API key must start with "sk-".');
     }
 
-    public function supports(Model $model, array|string|object $input): bool
+    public function supports(Model $model): bool
     {
         return $model instanceof GPT;
     }
 
-    public function request(Model $model, object|array|string $input, array $options = []): ResponseInterface
+    public function request(Model $model, array $payload, array $options = []): ResponseInterface
     {
         return $this->httpClient->request('POST', 'https://api.openai.com/v1/chat/completions', [
             'auth_bearer' => $this->apiKey,
             'json' => array_merge($options, [
                 'model' => $model->getName(),
-                'messages' => $input,
+                'messages' => $payload,
             ]),
         ]);
     }

src/Bridge/OpenAI/GPT/ResponseConverter.php

@@ -24,7 +24,7 @@
 
 final class ResponseConverter implements PlatformResponseConverter
 {
-    public function supports(Model $model, array|string|object $input): bool
+    public function supports(Model $model): bool
     {
         return $model instanceof GPT;
     }

src/Bridge/OpenAI/PlatformFactory.php

@@ -4,14 +4,18 @@
 
 namespace PhpLlm\LlmChain\Bridge\OpenAI;
 
+use PhpLlm\LlmChain\Bridge\OpenAI\DallE\ContractExtension as DallEContractExtension;
 use PhpLlm\LlmChain\Bridge\OpenAI\DallE\ModelClient as DallEModelClient;
+use PhpLlm\LlmChain\Bridge\OpenAI\Embeddings\ContractExtension as EmbeddingsContractExtension;
 use PhpLlm\LlmChain\Bridge\OpenAI\Embeddings\ModelClient as EmbeddingsModelClient;
 use PhpLlm\LlmChain\Bridge\OpenAI\Embeddings\ResponseConverter as EmbeddingsResponseConverter;
 use PhpLlm\LlmChain\Bridge\OpenAI\GPT\ModelClient as GPTModelClient;
 use PhpLlm\LlmChain\Bridge\OpenAI\GPT\ResponseConverter as GPTResponseConverter;
+use PhpLlm\LlmChain\Bridge\OpenAI\Whisper\ContractExtension as WhisperContractExtension;
 use PhpLlm\LlmChain\Bridge\OpenAI\Whisper\ModelClient as WhisperModelClient;
 use PhpLlm\LlmChain\Bridge\OpenAI\Whisper\ResponseConverter as WhisperResponseConverter;
 use PhpLlm\LlmChain\Platform;
+use PhpLlm\LlmChain\Platform\Contract;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 
@@ -39,6 +43,11 @@ public static function create(
                 $dallEModelClient,
                 new WhisperResponseConverter(),
             ],
+            Contract::create(
+                new DallEContractExtension(),
+                new EmbeddingsContractExtension(),
+                new WhisperContractExtension(),
+            ),
         );
     }
 }

src/Bridge/OpenAI/Whisper/ContractExtension.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
+
+use PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
+use PhpLlm\LlmChain\Model\Message\Content\Audio;
+use PhpLlm\LlmChain\Model\Model;
+use PhpLlm\LlmChain\Platform\Contract\Extension;
+
+final class ContractExtension implements Extension
+{
+    public function supports(Model $model): bool
+    {
+        return $model instanceof Whisper;
+    }
+
+    public function registerTypes(): array
+    {
+        return [
+            Audio::class => 'handleAudioInput',
+        ];
+    }
+
+    public function handleAudioInput(Audio $audio): array
+    {
+        return [
+            'file' => $audio->asResource(),
+        ];
+    }
+}

src/Bridge/OpenAI/Whisper/ModelClient.php

@@ -5,7 +5,6 @@
 namespace PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
 
 use PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
-use PhpLlm\LlmChain\Model\Message\Content\Audio;
 use PhpLlm\LlmChain\Model\Model;
 use PhpLlm\LlmChain\Platform\ModelClient as BaseModelClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -22,22 +21,17 @@ public function __construct(
         Assert::stringNotEmpty($apiKey, 'The API key must not be empty.');
     }
 
-    public function supports(Model $model, object|array|string $input): bool
+    public function supports(Model $model): bool
     {
-        return $model instanceof Whisper && $input instanceof Audio;
+        return $model instanceof Whisper;
     }
 
-    public function request(Model $model, object|array|string $input, array $options = []): ResponseInterface
+    public function request(Model $model, array $payload, array $options = []): ResponseInterface
     {
-        assert($input instanceof Audio);
-
         return $this->httpClient->request('POST', 'https://api.openai.com/v1/audio/transcriptions', [
             'auth_bearer' => $this->apiKey,
             'headers' => ['Content-Type' => 'multipart/form-data'],
-            'body' => array_merge($options, $model->getOptions(), [
-                'model' => $model->getName(),
-                'file' => $input->asResource(),
-            ]),
+            'body' => array_merge($options, $payload, ['model' => $model->getName()]),
         ]);
     }
 }

src/Bridge/OpenAI/Whisper/ResponseConverter.php

@@ -5,7 +5,6 @@
 namespace PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
 
 use PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
-use PhpLlm\LlmChain\Model\Message\Content\Audio;
 use PhpLlm\LlmChain\Model\Model;
 use PhpLlm\LlmChain\Model\Response\ResponseInterface as LlmResponse;
 use PhpLlm\LlmChain\Model\Response\TextResponse;
@@ -14,9 +13,9 @@
 
 final class ResponseConverter implements BaseResponseConverter
 {
-    public function supports(Model $model, object|array|string $input): bool
+    public function supports(Model $model): bool
     {
-        return $model instanceof Whisper && $input instanceof Audio;
+        return $model instanceof Whisper;
     }
 
     public function convert(HttpResponse $response, array $options = []): LlmResponse

src/Model/Message/AssistantMessage.php

@@ -37,7 +37,7 @@ public function hasToolCalls(): bool
     public function jsonSerialize(): array
     {
         $array = [
-            'role' => Role::Assistant,
+            'role' => Role::Assistant->value,
         ];
 
         if (null !== $this->content) {

src/Model/Message/SystemMessage.php

@@ -24,7 +24,7 @@ public function getRole(): Role
     public function jsonSerialize(): array
     {
         return [
-            'role' => Role::System,
+            'role' => Role::System->value,
             'content' => $this->content,
         ];
     }

src/Model/Message/ToolCallMessage.php

@@ -29,7 +29,7 @@ public function getRole(): Role
     public function jsonSerialize(): array
     {
         return [
-            'role' => Role::ToolCall,
+            'role' => Role::ToolCall->value,
             'content' => $this->content,
             'tool_call_id' => $this->toolCall->id,
         ];

src/Model/Message/UserMessage.php

@@ -58,7 +58,7 @@ public function hasImageContent(): bool
      */
     public function jsonSerialize(): array
     {
-        $array = ['role' => Role::User];
+        $array = ['role' => Role::User->value];
         if (1 === count($this->content) && $this->content[0] instanceof Text) {
             $array['content'] = $this->content[0]->text;
 

src/Platform.php

@@ -8,6 +8,7 @@
 use PhpLlm\LlmChain\Model\Model;
 use PhpLlm\LlmChain\Model\Response\AsyncResponse;
 use PhpLlm\LlmChain\Model\Response\ResponseInterface;
+use PhpLlm\LlmChain\Platform\Contract;
 use PhpLlm\LlmChain\Platform\ModelClient;
 use PhpLlm\LlmChain\Platform\ResponseConverter;
 use Symfony\Contracts\HttpClient\ResponseInterface as HttpResponse;
@@ -28,44 +29,47 @@
      * @param iterable<ModelClient>       $modelClients
      * @param iterable<ResponseConverter> $responseConverter
      */
-    public function __construct(iterable $modelClients, iterable $responseConverter)
-    {
+    public function __construct(
+        iterable $modelClients,
+        iterable $responseConverter,
+        private Contract $contract = new Contract([]),
+    ) {
         $this->modelClients = $modelClients instanceof \Traversable ? iterator_to_array($modelClients) : $modelClients;
         $this->responseConverter = $responseConverter instanceof \Traversable ? iterator_to_array($responseConverter) : $responseConverter;
     }
 
     public function request(Model $model, array|string|object $input, array $options = []): ResponseInterface
     {
+        $payload = $this->contract->convertRequestPayload($input, $model);
         $options = array_merge($model->getOptions(), $options);
 
-        $response = $this->doRequest($model, $input, $options);
+        $response = $this->doRequest($model, $payload, $options);
 
-        return $this->convertResponse($model, $input, $response, $options);
+        return $this->convertResponse($model, $response, $options);
     }
 
     /**
-     * @param array<mixed>|string|object $input
-     * @param array<string, mixed>       $options
+     * @param array<string, mixed> $payload
+     * @param array<string, mixed> $options
      */
-    private function doRequest(Model $model, array|string|object $input, array $options = []): HttpResponse
+    private function doRequest(Model $model, array $payload, array $options = []): HttpResponse
     {
         foreach ($this->modelClients as $modelClient) {
-            if ($modelClient->supports($model, $input)) {
-                return $modelClient->request($model, $input, $options);
+            if ($modelClient->supports($model)) {
+                return $modelClient->request($model, $payload, $options);
             }
         }
 
         throw new RuntimeException('No response factory registered for model "'.$model::class.'" with given input.');
     }
 
     /**
-     * @param array<mixed>|string|object $input
-     * @param array<string, mixed>       $options
+     * @param array<string, mixed> $options
      */
-    private function convertResponse(Model $model, object|array|string $input, HttpResponse $response, array $options): ResponseInterface
+    private function convertResponse(Model $model, HttpResponse $response, array $options): ResponseInterface
     {
         foreach ($this->responseConverter as $responseConverter) {
-            if ($responseConverter->supports($model, $input)) {
+            if ($responseConverter->supports($model)) {
                 return new AsyncResponse($responseConverter, $response, $options);
             }
         }