feat: open contract class to be extendable

DZunke · DZunke · commit b55d08bafe9b · 2025-07-05T10:19:22.000+02:00
diff --git a/src/Platform/Bridge/Anthropic/Contract/AnthropicContract.php b/src/Platform/Bridge/Anthropic/Contract/AnthropicContract.php
@@ -4,17 +4,17 @@
 
 namespace PhpLlm\LlmChain\Platform\Bridge\Anthropic\Contract;
 
+use PhpLlm\LlmChain\Platform\Contract;
 use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
 
 /**
  * @author Denis Zunke <denis.zunke@gmail.com>
  */
-final readonly class AnthropicSet
+final readonly class AnthropicContract extends Contract
 {
-    /** @return array<NormalizerInterface> */
-    public static function get(): array
+    public static function create(NormalizerInterface ...$normalizer): Contract
     {
-        return [
+        return parent::create(
             new AssistantMessageNormalizer(),
             new DocumentNormalizer(),
             new DocumentUrlNormalizer(),
@@ -23,6 +23,7 @@ public static function get(): array
             new MessageBagNormalizer(),
             new ToolCallMessageNormalizer(),
             new ToolNormalizer(),
-        ];
+            ...$normalizer,
+        );
     }
 }
diff --git a/src/Platform/Bridge/Anthropic/PlatformFactory.php b/src/Platform/Bridge/Anthropic/PlatformFactory.php
@@ -4,9 +4,8 @@
 
 namespace PhpLlm\LlmChain\Platform\Bridge\Anthropic;
 
-use PhpLlm\LlmChain\Platform\Bridge\Anthropic\Contract\AnthropicSet;
+use PhpLlm\LlmChain\Platform\Bridge\Anthropic\Contract\AnthropicContract;
 use PhpLlm\LlmChain\Platform\Contract;
-use PhpLlm\LlmChain\Platform\ContractInterface;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -21,14 +20,14 @@ public static function create(
         string $apiKey,
         string $version = '2023-06-01',
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
 
         return new Platform(
             [new ModelClient($httpClient, $apiKey, $version)],
             [new ResponseConverter()],
-            $contract ?? Contract::create(...AnthropicSet::get()),
+            $contract ?? AnthropicContract::create(),
         );
     }
 }
diff --git a/src/Platform/Bridge/Azure/Meta/PlatformFactory.php b/src/Platform/Bridge/Azure/Meta/PlatformFactory.php
@@ -4,7 +4,7 @@
 
 namespace PhpLlm\LlmChain\Platform\Bridge\Azure\Meta;
 
-use PhpLlm\LlmChain\Platform\ContractInterface;
+use PhpLlm\LlmChain\Platform\Contract;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\HttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -19,7 +19,7 @@ public static function create(
         #[\SensitiveParameter]
         string $apiKey,
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $modelClient = new LlamaHandler($httpClient ?? HttpClient::create(), $baseUrl, $apiKey);
 
diff --git a/src/Platform/Bridge/Azure/OpenAI/PlatformFactory.php b/src/Platform/Bridge/Azure/OpenAI/PlatformFactory.php
@@ -8,7 +8,6 @@
 use PhpLlm\LlmChain\Platform\Bridge\OpenAI\GPT\ResponseConverter;
 use PhpLlm\LlmChain\Platform\Bridge\OpenAI\Whisper\AudioNormalizer;
 use PhpLlm\LlmChain\Platform\Contract;
-use PhpLlm\LlmChain\Platform\ContractInterface;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -25,7 +24,7 @@ public static function create(
         #[\SensitiveParameter]
         string $apiKey,
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
         $embeddingsResponseFactory = new EmbeddingsModelClient($httpClient, $baseUrl, $deployment, $apiVersion, $apiKey);
diff --git a/src/Platform/Bridge/Bedrock/Platform.php b/src/Platform/Bridge/Bedrock/Platform.php
@@ -6,7 +6,6 @@
 use PhpLlm\LlmChain\Platform\Bridge\Bedrock\Nova\Contract as NovaContract;
 use PhpLlm\LlmChain\Platform\Bridge\Meta\Contract as LlamaContract;
 use PhpLlm\LlmChain\Platform\Contract;
-use PhpLlm\LlmChain\Platform\ContractInterface;
 use PhpLlm\LlmChain\Platform\Exception\RuntimeException;
 use PhpLlm\LlmChain\Platform\Model;
 use PhpLlm\LlmChain\Platform\PlatformInterface;
@@ -27,7 +26,7 @@ class Platform implements PlatformInterface
      */
     public function __construct(
         iterable $modelClients,
-        private ?ContractInterface $contract = null,
+        private ?Contract $contract = null,
     ) {
         $this->contract = $contract ?? Contract::create(
             new AnthropicContract\AssistantMessageNormalizer(),
diff --git a/src/Platform/Bridge/Bedrock/PlatformFactory.php b/src/Platform/Bridge/Bedrock/PlatformFactory.php
@@ -8,7 +8,7 @@
 use PhpLlm\LlmChain\Platform\Bridge\Bedrock\Anthropic\ClaudeHandler;
 use PhpLlm\LlmChain\Platform\Bridge\Bedrock\Meta\LlamaModelClient;
 use PhpLlm\LlmChain\Platform\Bridge\Bedrock\Nova\NovaHandler;
-use PhpLlm\LlmChain\Platform\ContractInterface;
+use PhpLlm\LlmChain\Platform\Contract;
 
 /**
  * @author Björn Altmann
@@ -17,7 +17,7 @@
 {
     public static function create(
         BedrockRuntimeClient $bedrockRuntimeClient = new BedrockRuntimeClient(),
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $modelClient[] = new ClaudeHandler($bedrockRuntimeClient);
         $modelClient[] = new NovaHandler($bedrockRuntimeClient);
diff --git a/src/Platform/Bridge/Google/Contract/GoogleContract.php b/src/Platform/Bridge/Google/Contract/GoogleContract.php
@@ -4,22 +4,23 @@
 
 namespace PhpLlm\LlmChain\Platform\Bridge\Google\Contract;
 
+use PhpLlm\LlmChain\Platform\Contract;
 use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
 
 /**
  * @author Denis Zunke <denis.zunke@gmail.com>
  */
-final readonly class GoogleSet
+final readonly class GoogleContract extends Contract
 {
-    /** @return array<NormalizerInterface> */
-    public static function get(): array
+    public static function create(NormalizerInterface ...$normalizer): Contract
     {
-        return [
+        return parent::create(
             new AssistantMessageNormalizer(),
             new MessageBagNormalizer(),
             new ToolNormalizer(),
             new ToolCallMessageNormalizer(),
             new UserMessageNormalizer(),
-        ];
+            ...$normalizer,
+        );
     }
 }
diff --git a/src/Platform/Bridge/Google/PlatformFactory.php b/src/Platform/Bridge/Google/PlatformFactory.php
@@ -4,10 +4,9 @@
 
 namespace PhpLlm\LlmChain\Platform\Bridge\Google;
 
-use PhpLlm\LlmChain\Platform\Bridge\Google\Contract\GoogleSet;
+use PhpLlm\LlmChain\Platform\Bridge\Google\Contract\GoogleContract;
 use PhpLlm\LlmChain\Platform\Bridge\Google\Embeddings\ModelClient;
 use PhpLlm\LlmChain\Platform\Contract;
-use PhpLlm\LlmChain\Platform\ContractInterface;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -21,7 +20,7 @@ public static function create(
         #[\SensitiveParameter]
         string $apiKey,
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
         $responseHandler = new ModelHandler($httpClient, $apiKey);
@@ -30,7 +29,7 @@ public static function create(
         return new Platform(
             [$responseHandler, $embeddings],
             [$responseHandler, $embeddings],
-            $contract ?? Contract::create(...GoogleSet::get()),
+            $contract ?? GoogleContract::create(),
         );
     }
 }
diff --git a/src/Platform/Bridge/HuggingFace/PlatformFactory.php b/src/Platform/Bridge/HuggingFace/PlatformFactory.php
@@ -7,7 +7,6 @@
 use PhpLlm\LlmChain\Platform\Bridge\HuggingFace\Contract\FileNormalizer;
 use PhpLlm\LlmChain\Platform\Bridge\HuggingFace\Contract\MessageBagNormalizer;
 use PhpLlm\LlmChain\Platform\Contract;
-use PhpLlm\LlmChain\Platform\ContractInterface;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -22,7 +21,7 @@ public static function create(
         string $apiKey,
         string $provider = Provider::HF_INFERENCE,
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
 
diff --git a/src/Platform/Bridge/Mistral/PlatformFactory.php b/src/Platform/Bridge/Mistral/PlatformFactory.php
@@ -10,7 +10,6 @@
 use PhpLlm\LlmChain\Platform\Bridge\Mistral\Llm\ModelClient as MistralModelClient;
 use PhpLlm\LlmChain\Platform\Bridge\Mistral\Llm\ResponseConverter as MistralResponseConverter;
 use PhpLlm\LlmChain\Platform\Contract;
-use PhpLlm\LlmChain\Platform\ContractInterface;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -24,7 +23,7 @@ public static function create(
         #[\SensitiveParameter]
         string $apiKey,
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
 
diff --git a/src/Platform/Bridge/Ollama/PlatformFactory.php b/src/Platform/Bridge/Ollama/PlatformFactory.php
@@ -4,7 +4,7 @@
 
 namespace PhpLlm\LlmChain\Platform\Bridge\Ollama;
 
-use PhpLlm\LlmChain\Platform\ContractInterface;
+use PhpLlm\LlmChain\Platform\Contract;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -17,7 +17,7 @@ final class PlatformFactory
     public static function create(
         string $hostUrl = 'http://localhost:11434',
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
         $handler = new LlamaModelHandler($httpClient, $hostUrl);
diff --git a/src/Platform/Bridge/OpenAI/PlatformFactory.php b/src/Platform/Bridge/OpenAI/PlatformFactory.php
@@ -13,7 +13,6 @@
 use PhpLlm\LlmChain\Platform\Bridge\OpenAI\Whisper\ModelClient as WhisperModelClient;
 use PhpLlm\LlmChain\Platform\Bridge\OpenAI\Whisper\ResponseConverter as WhisperResponseConverter;
 use PhpLlm\LlmChain\Platform\Contract;
-use PhpLlm\LlmChain\Platform\ContractInterface;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -27,7 +26,7 @@ public static function create(
         #[\SensitiveParameter]
         string $apiKey,
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
 
diff --git a/src/Platform/Bridge/OpenRouter/PlatformFactory.php b/src/Platform/Bridge/OpenRouter/PlatformFactory.php
@@ -8,7 +8,6 @@
 use PhpLlm\LlmChain\Platform\Bridge\Google\Contract\MessageBagNormalizer;
 use PhpLlm\LlmChain\Platform\Bridge\Google\Contract\UserMessageNormalizer;
 use PhpLlm\LlmChain\Platform\Contract;
-use PhpLlm\LlmChain\Platform\ContractInterface;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -22,7 +21,7 @@ public static function create(
         #[\SensitiveParameter]
         string $apiKey,
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
         $handler = new Client($httpClient, $apiKey);
diff --git a/src/Platform/Bridge/Replicate/PlatformFactory.php b/src/Platform/Bridge/Replicate/PlatformFactory.php
@@ -6,7 +6,6 @@
 
 use PhpLlm\LlmChain\Platform\Bridge\Replicate\Contract\LlamaMessageBagNormalizer;
 use PhpLlm\LlmChain\Platform\Contract;
-use PhpLlm\LlmChain\Platform\ContractInterface;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\Clock\Clock;
 use Symfony\Component\HttpClient\HttpClient;
@@ -21,7 +20,7 @@ public static function create(
         #[\SensitiveParameter]
         string $apiKey,
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         return new Platform(
             [new LlamaModelClient(new Client($httpClient ?? HttpClient::create(), new Clock(), $apiKey))],
diff --git a/src/Platform/Bridge/Voyage/PlatformFactory.php b/src/Platform/Bridge/Voyage/PlatformFactory.php
@@ -4,7 +4,7 @@
 
 namespace PhpLlm\LlmChain\Platform\Bridge\Voyage;
 
-use PhpLlm\LlmChain\Platform\ContractInterface;
+use PhpLlm\LlmChain\Platform\Contract;
 use PhpLlm\LlmChain\Platform\Platform;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -18,7 +18,7 @@ public static function create(
         #[\SensitiveParameter]
         string $apiKey,
         ?HttpClientInterface $httpClient = null,
-        ?ContractInterface $contract = null,
+        ?Contract $contract = null,
     ): Platform {
         $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
         $handler = new ModelHandler($httpClient, $apiKey);
diff --git a/src/Platform/Contract.php b/src/Platform/Contract.php
@@ -4,7 +4,17 @@
 
 namespace PhpLlm\LlmChain\Platform;
 
-use PhpLlm\LlmChain\Platform\Contract\PlatformSet;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Message\AssistantMessageNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Message\Content\AudioNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Message\Content\ImageNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Message\Content\ImageUrlNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Message\Content\TextNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Message\MessageBagNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Message\SystemMessageNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Message\ToolCallMessageNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Message\UserMessageNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\Response\ToolCallNormalizer;
+use PhpLlm\LlmChain\Platform\Contract\Normalizer\ToolNormalizer;
 use PhpLlm\LlmChain\Platform\Tool\Tool;
 use Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer;
 use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
@@ -13,19 +23,38 @@
 /**
  * @author Christopher Hertel <mail@christopher-hertel.de>
  */
-final readonly class Contract implements ContractInterface
+readonly class Contract
 {
     public const CONTEXT_MODEL = 'model';
 
     public function __construct(
-        private NormalizerInterface $normalizer,
+        protected NormalizerInterface $normalizer,
     ) {
     }
 
     public static function create(NormalizerInterface ...$normalizer): self
     {
+        // Messages
+        $normalizer[] = new MessageBagNormalizer();
+        $normalizer[] = new AssistantMessageNormalizer();
+        $normalizer[] = new SystemMessageNormalizer();
+        $normalizer[] = new ToolCallMessageNormalizer();
+        $normalizer[] = new UserMessageNormalizer();
+
+        // Message Content
+        $normalizer[] = new AudioNormalizer();
+        $normalizer[] = new ImageNormalizer();
+        $normalizer[] = new ImageUrlNormalizer();
+        $normalizer[] = new TextNormalizer();
+
+        // Options
+        $normalizer[] = new ToolNormalizer();
+
+        // Response
+        $normalizer[] = new ToolCallNormalizer();
+
         return new self(
-            new Serializer(array_merge($normalizer, PlatformSet::get())),
+            new Serializer($normalizer),
         );
     }
 
@@ -34,7 +63,7 @@ public static function create(NormalizerInterface ...$normalizer): self
      *
      * @return array<string, mixed>|string
      */
-    public function createRequestPayload(Model $model, object|array|string $input): string|array
+    final public function createRequestPayload(Model $model, object|array|string $input): string|array
     {
         return $this->normalizer->normalize($input, context: [self::CONTEXT_MODEL => $model]);
     }
@@ -44,7 +73,7 @@ public function createRequestPayload(Model $model, object|array|string $input):
      *
      * @return array<string, mixed>
      */
-    public function createToolOption(array $tools, Model $model): array
+    final public function createToolOption(array $tools, Model $model): array
     {
         return $this->normalizer->normalize($tools, context: [self::CONTEXT_MODEL => $model, AbstractObjectNormalizer::PRESERVE_EMPTY_OBJECTS => true]);
     }
diff --git a/src/Platform/Contract/PlatformSet.php b/src/Platform/Contract/PlatformSet.php
diff --git a/src/Platform/ContractInterface.php b/src/Platform/ContractInterface.php
diff --git a/src/Platform/Platform.php b/src/Platform/Platform.php
