refactor: add extension point to payload contract handling

chr-hertel · chr-hertel · commit c6ba1ceddb3b · 2025-05-05T00:26:59.000+02:00
diff --git a/src/Bridge/OpenAI/DallE/ContractExtension.php b/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,
+        ];
+    }
+}
diff --git a/src/Bridge/OpenAI/DallE/ModelClient.php b/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,
             ]),
         ]);
     }
diff --git a/src/Bridge/OpenAI/Embeddings/ContractExtension.php b/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,
+        ];
+    }
+}
diff --git a/src/Bridge/OpenAI/Embeddings/ModelClient.php b/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,
             ]),
         ]);
     }
diff --git a/src/Bridge/OpenAI/Embeddings/ResponseConverter.php b/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;
     }
diff --git a/src/Bridge/OpenAI/GPT/ModelClient.php b/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,
             ]),
         ]);
     }
diff --git a/src/Bridge/OpenAI/GPT/ResponseConverter.php b/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;
     }
diff --git a/src/Bridge/OpenAI/PlatformFactory.php b/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(),
+            ),
         );
     }
 }
diff --git a/src/Bridge/OpenAI/Whisper/ContractExtension.php b/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(),
+        ];
+    }
+}
diff --git a/src/Bridge/OpenAI/Whisper/ModelClient.php b/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()]),
         ]);
     }
 }
diff --git a/src/Bridge/OpenAI/Whisper/ResponseConverter.php b/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
diff --git a/src/Model/Message/AssistantMessage.php b/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) {
diff --git a/src/Model/Message/SystemMessage.php b/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,
         ];
     }
diff --git a/src/Model/Message/ToolCallMessage.php b/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,
         ];
diff --git a/src/Model/Message/UserMessage.php b/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;
 
diff --git a/src/Platform.php b/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);
             }
         }
diff --git a/src/Platform/Contract.php b/src/Platform/Contract.php
diff --git a/src/Platform/Contract/Extension.php b/src/Platform/Contract/Extension.php
diff --git a/src/Platform/Contract/InputNormalizer.php b/src/Platform/Contract/InputNormalizer.php
diff --git a/src/Platform/ModelClient.php b/src/Platform/ModelClient.php
diff --git a/src/Platform/ResponseConverter.php b/src/Platform/ResponseConverter.php

Original file line number	Diff line number	Diff line change
`@@ -28,18 +28,17 @@ public function __construct(`
`28`	`28`	`Assert::startsWith($apiKey, 'sk-', 'The API key must start with "sk-".');`
`29`	`29`	`}`
`30`	`30`
`31`		`- public function supports(Model $model, array\|string\|object $input): bool`
	`31`	`+ public function supports(Model $model): bool`
`32`	`32`	`{`
`33`	`33`	`return $model instanceof DallE;`
`34`	`34`	`}`
`35`	`35`
`36`		`- public function request(Model $model, object\|array\|string $input, array $options = []): HttpResponse`
	`36`	`+ public function request(Model $model, array $payload, array $options = []): HttpResponse`
`37`	`37`	`{`
`38`	`38`	`return $this->httpClient->request('POST', 'https://api.openai.com/v1/images/generations', [`
`39`	`39`	`'auth_bearer' => $this->apiKey,`
`40`		`- 'json' => \array_merge($options, [`
	`40`	`+ 'json' => \array_merge($options, $payload, [`
`41`	`41`	`'model' => $model->getName(),`
`42`		`- 'prompt' => $input,`
`43`	`42`	`]),`
`44`	`43`	`]);`
`45`	`44`	`}`
Original file line number	Diff line number	Diff line change
`@@ -22,18 +22,17 @@ public function __construct(`
`22`	`22`	`Assert::startsWith($apiKey, 'sk-', 'The API key must start with "sk-".');`
`23`	`23`	`}`
`24`	`24`
`25`		`- public function supports(Model $model, array\|string\|object $input): bool`
	`25`	`+ public function supports(Model $model): bool`
`26`	`26`	`{`
`27`	`27`	`return $model instanceof Embeddings;`
`28`	`28`	`}`
`29`	`29`
`30`		`- public function request(Model $model, object\|array\|string $input, array $options = []): ResponseInterface`
	`30`	`+ public function request(Model $model, array $payload, array $options = []): ResponseInterface`
`31`	`31`	`{`
`32`	`32`	`return $this->httpClient->request('POST', 'https://api.openai.com/v1/embeddings', [`
`33`	`33`	`'auth_bearer' => $this->apiKey,`
`34`		`- 'json' => array_merge($model->getOptions(), $options, [`
	`34`	`+ 'json' => array_merge($options, $payload, [`
`35`	`35`	`'model' => $model->getName(),`
`36`		`- 'input' => $input,`
`37`	`36`	`]),`
`38`	`37`	`]);`
`39`	`38`	`}`
Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,7 @@`
`14`	`14`
`15`	`15`	`final class ResponseConverter implements PlatformResponseConverter`
`16`	`16`	`{`
`17`		`- public function supports(Model $model, array\|string\|object $input): bool`
	`17`	`+ public function supports(Model $model): bool`
`18`	`18`	`{`
`19`	`19`	`return $model instanceof Embeddings;`
`20`	`20`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,25 +18,26 @@`
`18`	`18`
`19`	`19`	`public function __construct(`
`20`	`20`	`HttpClientInterface $httpClient,`
`21`		`- #[\SensitiveParameter] private string $apiKey,`
	`21`	`+ #[\SensitiveParameter]`
	`22`	`+ private string $apiKey,`
`22`	`23`	`) {`
`23`	`24`	`$this->httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);`
`24`	`25`	`Assert::stringNotEmpty($apiKey, 'The API key must not be empty.');`
`25`	`26`	`Assert::startsWith($apiKey, 'sk-', 'The API key must start with "sk-".');`
`26`	`27`	`}`
`27`	`28`
`28`		`- public function supports(Model $model, array\|string\|object $input): bool`
	`29`	`+ public function supports(Model $model): bool`
`29`	`30`	`{`
`30`	`31`	`return $model instanceof GPT;`
`31`	`32`	`}`
`32`	`33`
`33`		`- public function request(Model $model, object\|array\|string $input, array $options = []): ResponseInterface`
	`34`	`+ public function request(Model $model, array $payload, array $options = []): ResponseInterface`
`34`	`35`	`{`
`35`	`36`	`return $this->httpClient->request('POST', 'https://api.openai.com/v1/chat/completions', [`
`36`	`37`	`'auth_bearer' => $this->apiKey,`
`37`	`38`	`'json' => array_merge($options, [`
`38`	`39`	`'model' => $model->getName(),`
`39`		`- 'messages' => $input,`
	`40`	`+ 'messages' => $payload,`
`40`	`41`	`]),`
`41`	`42`	`]);`
`42`	`43`	`}`
Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@`
`24`	`24`
`25`	`25`	`final class ResponseConverter implements PlatformResponseConverter`
`26`	`26`	`{`
`27`		`- public function supports(Model $model, array\|string\|object $input): bool`
	`27`	`+ public function supports(Model $model): bool`
`28`	`28`	`{`
`29`	`29`	`return $model instanceof GPT;`
`30`	`30`	`}`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,6 @@`
`5`	`5`	`namespace PhpLlm\LlmChain\Bridge\OpenAI\Whisper;`
`6`	`6`
`7`	`7`	`use PhpLlm\LlmChain\Bridge\OpenAI\Whisper;`
`8`		`-use PhpLlm\LlmChain\Model\Message\Content\Audio;`
`9`	`8`	`use PhpLlm\LlmChain\Model\Model;`
`10`	`9`	`use PhpLlm\LlmChain\Platform\ModelClient as BaseModelClient;`
`11`	`10`	`use Symfony\Contracts\HttpClient\HttpClientInterface;`
`@@ -22,22 +21,17 @@ public function __construct(`
`22`	`21`	`Assert::stringNotEmpty($apiKey, 'The API key must not be empty.');`
`23`	`22`	`}`
`24`	`23`
`25`		`- public function supports(Model $model, object\|array\|string $input): bool`
	`24`	`+ public function supports(Model $model): bool`
`26`	`25`	`{`
`27`		`- return $model instanceof Whisper && $input instanceof Audio;`
	`26`	`+ return $model instanceof Whisper;`
`28`	`27`	`}`
`29`	`28`
`30`		`- public function request(Model $model, object\|array\|string $input, array $options = []): ResponseInterface`
	`29`	`+ public function request(Model $model, array $payload, array $options = []): ResponseInterface`
`31`	`30`	`{`
`32`		`- assert($input instanceof Audio);`
`33`		`-`
`34`	`31`	`return $this->httpClient->request('POST', 'https://api.openai.com/v1/audio/transcriptions', [`
`35`	`32`	`'auth_bearer' => $this->apiKey,`
`36`	`33`	`'headers' => ['Content-Type' => 'multipart/form-data'],`
`37`		`- 'body' => array_merge($options, $model->getOptions(), [`
`38`		`- 'model' => $model->getName(),`
`39`		`- 'file' => $input->asResource(),`
`40`		`- ]),`
	`34`	`+ 'body' => array_merge($options, $payload, ['model' => $model->getName()]),`
`41`	`35`	`]);`
`42`	`36`	`}`
`43`	`37`	`}`