feat: introduce message metadata and traits

examples/chat-claude-anthropic.php

@@ -3,8 +3,9 @@
 use PhpLlm\LlmChain\Anthropic\Model\Claude;
 use PhpLlm\LlmChain\Anthropic\Platform\Anthropic;
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\SystemMessage;
+use PhpLlm\LlmChain\Message\UserMessage;
 use Symfony\Component\Dotenv\Dotenv;
 use Symfony\Component\HttpClient\HttpClient;
 
@@ -21,8 +22,8 @@
 
 $chain = new Chain($llm);
 $messages = new MessageBag(
-    Message::forSystem('You are a pirate and you write funny.'),
-    Message::ofUser('What is the Symfony framework?'),
+    new SystemMessage('You are a pirate and you write funny.'),
+    new UserMessage('What is the Symfony framework?'),
 );
 $response = $chain->call($messages);
 

examples/chat-gpt-azure.php

@@ -1,8 +1,9 @@
 <?php
 
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\SystemMessage;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\Azure;
@@ -28,8 +29,8 @@
 
 $chain = new Chain($llm);
 $messages = new MessageBag(
-    Message::forSystem('You are a pirate and you write funny.'),
-    Message::ofUser('What is the Symfony framework?'),
+    new SystemMessage('You are a pirate and you write funny.'),
+    new UserMessage('What is the Symfony framework?'),
 );
 $response = $chain->call($messages);
 

examples/chat-gpt-openai.php

@@ -1,8 +1,9 @@
 <?php
 
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\SystemMessage;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\OpenAI;
@@ -24,8 +25,8 @@
 
 $chain = new Chain($llm);
 $messages = new MessageBag(
-    Message::forSystem('You are a pirate and you write funny.'),
-    Message::ofUser('What is the Symfony framework?'),
+    new SystemMessage('You are a pirate and you write funny.'),
+    new UserMessage('What is the Symfony framework?'),
 );
 $response = $chain->call($messages, [
     'max_tokens' => 500, // specific options just for this call

examples/image-describer.php

@@ -2,8 +2,9 @@
 
 use PhpLlm\LlmChain\Chain;
 use PhpLlm\LlmChain\Message\Content\Image;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\SystemMessage;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\OpenAI;
@@ -23,8 +24,8 @@
 
 $chain = new Chain($llm);
 $messages = new MessageBag(
-    Message::forSystem('You are an image analyzer bot that helps identify the content of images.'),
-    Message::ofUser(
+    new SystemMessage('You are an image analyzer bot that helps identify the content of images.'),
+    new UserMessage(
         'Describe the images as a comedian would do it.',
         new Image('https://upload.wikimedia.org/wikipedia/commons/thumb/3/31/Webysther_20160423_-_Elephpant.svg/350px-Webysther_20160423_-_Elephpant.svg.png'),
         new Image('https://upload.wikimedia.org/wikipedia/commons/thumb/3/37/African_Bush_Elephant.jpg/320px-African_Bush_Elephant.jpg'),

examples/reasoning-openai.php

@@ -1,8 +1,8 @@
 <?php
 
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\OpenAI;
@@ -29,6 +29,6 @@
     at the beginning and end, not throughout the code.
     PROMPT;
 
-$response = (new Chain($llm))->call(new MessageBag(Message::ofUser($prompt)));
+$response = (new Chain($llm))->call(new MessageBag(new UserMessage($prompt)));
 
 echo $response.PHP_EOL;

examples/store-mongodb-similarity-search.php

@@ -5,8 +5,9 @@
 use PhpLlm\LlmChain\Document\Document;
 use PhpLlm\LlmChain\Document\Metadata;
 use PhpLlm\LlmChain\DocumentEmbedder;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\SystemMessage;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Embeddings;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
@@ -69,8 +70,8 @@
 $chain = new Chain($llm, [$processor], [$processor]);
 
 $messages = new MessageBag(
-    Message::forSystem('Please answer all user questions only using SimilaritySearch function.'),
-    Message::ofUser('Which movie fits the theme of the mafia?')
+    new SystemMessage('Please answer all user questions only using SimilaritySearch function.'),
+    new UserMessage('Which movie fits the theme of the mafia?')
 );
 $response = $chain->call($messages);
 

examples/structured-output-math.php

@@ -1,8 +1,9 @@
 <?php
 
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\SystemMessage;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\OpenAI;
@@ -32,8 +33,8 @@
 $processor = new ChainProcessor($responseFormatFactory, $serializer);
 $chain = new Chain($llm, [$processor], [$processor]);
 $messages = new MessageBag(
-    Message::forSystem('You are a helpful math tutor. Guide the user through the solution step by step.'),
-    Message::ofUser('how can I solve 8x + 7 = -23'),
+    new SystemMessage('You are a helpful math tutor. Guide the user through the solution step by step.'),
+    new UserMessage('how can I solve 8x + 7 = -23'),
 );
 $response = $chain->call($messages, ['output_structure' => MathReasoning::class]);
 

examples/toolbox-clock.php

@@ -1,8 +1,8 @@
 <?php
 
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\OpenAI;
@@ -30,7 +30,7 @@
 $processor = new ChainProcessor($toolBox);
 $chain = new Chain($llm, [$processor], [$processor]);
 
-$messages = new MessageBag(Message::ofUser('What date and time is it?'));
+$messages = new MessageBag(new UserMessage('What date and time is it?'));
 $response = $chain->call($messages);
 
 echo $response.PHP_EOL;

examples/toolbox-serpapi.php

@@ -1,8 +1,8 @@
 <?php
 
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\OpenAI;
@@ -29,7 +29,7 @@
 $processor = new ChainProcessor($toolBox);
 $chain = new Chain($llm, [$processor], [$processor]);
 
-$messages = new MessageBag(Message::ofUser('Who is the current chancellor of Germany?'));
+$messages = new MessageBag(new UserMessage('Who is the current chancellor of Germany?'));
 $response = $chain->call($messages);
 
 echo $response.PHP_EOL;

examples/toolbox-weather.php

@@ -1,8 +1,8 @@
 <?php
 
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\OpenAI;
@@ -30,7 +30,7 @@
 $processor = new ChainProcessor($toolBox);
 $chain = new Chain($llm, [$processor], [$processor]);
 
-$messages = new MessageBag(Message::ofUser('How is the weather currently in Berlin?'));
+$messages = new MessageBag(new UserMessage('How is the weather currently in Berlin?'));
 $response = $chain->call($messages);
 
 echo $response.PHP_EOL;

examples/toolbox-wikipedia.php

@@ -1,8 +1,8 @@
 <?php
 
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\OpenAI;
@@ -30,7 +30,7 @@
 $processor = new ChainProcessor($toolBox);
 $chain = new Chain($llm, [$processor], [$processor]);
 
-$messages = new MessageBag(Message::ofUser('Who is the current chancellor of Germany?'));
+$messages = new MessageBag(new UserMessage('Who is the current chancellor of Germany?'));
 $response = $chain->call($messages);
 
 echo $response.PHP_EOL;

examples/toolbox-youtube.php

@@ -1,8 +1,8 @@
 <?php
 
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Message\Message;
 use PhpLlm\LlmChain\Message\MessageBag;
+use PhpLlm\LlmChain\Message\UserMessage;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt;
 use PhpLlm\LlmChain\OpenAI\Model\Gpt\Version;
 use PhpLlm\LlmChain\OpenAI\Platform\OpenAI;
@@ -30,7 +30,7 @@
 $processor = new ChainProcessor($toolBox);
 $chain = new Chain($llm, [$processor], [$processor]);
 
-$messages = new MessageBag(Message::ofUser('Please summarize this video for me: https://www.youtube.com/watch?v=6uXW-ulpj0s'));
+$messages = new MessageBag(new UserMessage('Please summarize this video for me: https://www.youtube.com/watch?v=6uXW-ulpj0s'));
 $response = $chain->call($messages);
 
 echo $response.PHP_EOL;

src/Message/AssistantMessage.php

@@ -6,20 +6,20 @@
 
 use PhpLlm\LlmChain\Response\ToolCall;
 
-final readonly class AssistantMessage implements MessageInterface
+final readonly class AssistantMessage implements Message
 {
+    use HasMetadata;
+    use HasRole;
+
     /**
      * @param ?ToolCall[] $toolCalls
      */
     public function __construct(
         public ?string $content = null,
         public ?array $toolCalls = null,
     ) {
-    }
-
-    public function getRole(): Role
-    {
-        return Role::Assistant;
+        $this->metadata = new Metadata();
+        $this->role = Role::Assistant;
     }
 
     public function hasToolCalls(): bool

src/Message/Content/ContentInterface.php → src/Message/Content/Content.php

@@ -4,6 +4,6 @@
 
 namespace PhpLlm\LlmChain\Message\Content;
 
-interface ContentInterface extends \JsonSerializable
+interface Content extends \JsonSerializable
 {
 }

src/Message/Content/Image.php

@@ -4,7 +4,7 @@
 
 namespace PhpLlm\LlmChain\Message\Content;
 
-final readonly class Image implements ContentInterface
+final readonly class Image implements Content
 {
     /**
      * @param string $url An URL like "http://localhost:3000/my-image.png" or a data url like "data:image/png;base64,iVBOR[...]"

src/Message/Content/Text.php

@@ -4,7 +4,7 @@
 
 namespace PhpLlm\LlmChain\Message\Content;
 
-final readonly class Text implements ContentInterface
+final readonly class Text implements Content
 {
     public function __construct(
         public string $text,

src/Message/HasMetadata.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Message;
+
+trait HasMetadata
+{
+    private readonly Metadata $metadata;
+
+    public function getMetadata(): Metadata
+    {
+        return $this->metadata;
+    }
+}

src/Message/HasRole.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Message;
+
+trait HasRole
+{
+    private readonly Role $role;
+
+    public function getRole(): Role
+    {
+        return $this->role;
+    }
+
+    public function isSystemMessage(): bool
+    {
+        return Role::System === $this->role;
+    }
+
+    public function isAssistantMessage(): bool
+    {
+        return Role::Assistant === $this->role;
+    }
+
+    public function isUserMessage(): bool
+    {
+        return Role::User === $this->role;
+    }
+
+    public function isToolCallMessage(): bool
+    {
+        return Role::ToolCall === $this->role;
+    }
+}