feat: add message id, timestamp and other metadata

src/Model/Message/AssistantMessage.php

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

src/Model/Message/Message.php

@@ -7,12 +7,21 @@
 use PhpLlm\LlmChain\Model\Message\Content\Content;
 use PhpLlm\LlmChain\Model\Message\Content\Text;
 use PhpLlm\LlmChain\Model\Response\ToolCall;
+use Symfony\Component\Uid\Uuid;
 
-final readonly class Message
+/**
+ * Besides a base implementation this class is a factory for the specific message types.
+ * We sacrifice basic OOP principles in favor of developer experience.
+ */
+abstract readonly class Message implements MessageInterface
 {
-    // Disabled by default, just a bridge to the specific messages
-    private function __construct()
-    {
+    /**
+     * Only available for subclasses.
+     */
+    protected function __construct(
+        private Role $role,
+        private Metadata $metadata = new Metadata(),
+    ) {
     }
 
     public static function forSystem(string $content): SystemMessage
@@ -23,7 +32,7 @@ public static function forSystem(string $content): SystemMessage
     /**
      * @param ?ToolCall[] $toolCalls
      */
-    public static function ofAssistant(?string $content = null, ?array $toolCalls = null): AssistantMessage
+    public static function ofAssistant(?string $content = null, ?array $toolCalls = null, Metadata $metadata = new Metadata()): AssistantMessage
     {
         return new AssistantMessage($content, $toolCalls);
     }
@@ -42,4 +51,19 @@ public static function ofToolCall(ToolCall $toolCall, string $content): ToolCall
     {
         return new ToolCallMessage($toolCall, $content);
     }
+
+    public function getRole(): Role
+    {
+        return $this->role;
+    }
+
+    public function getId(): Uuid
+    {
+        return $this->id;
+    }
+
+    public function getMetadata(): Metadata
+    {
+        return $this->metadata;
+    }
 }

src/Model/Message/Metadata.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Model\Message;
+
+use Symfony\Component\Uid\Uuid;
+use Symfony\Component\Uid\UuidV4;
+
+/**
+ * @template-extends \ArrayObject<string, mixed>
+ */
+class Metadata extends \ArrayObject
+{
+    public function __construct(
+        array $array = [],
+        Uuid $id = new UuidV4(),
+        \DateTimeImmutable $createdAt = new \DateTimeImmutable(),
+    ) {
+        if (!isset($array['created_at'])) {
+            $array['created_at'] = $createdAt;
+        }
+
+        if (!isset($array['id'])) {
+            $array['id'] = $id;
+        }
+
+        parent::__construct($array);
+    }
+}

src/Model/Message/SystemMessage.php

@@ -4,15 +4,11 @@
 
 namespace PhpLlm\LlmChain\Model\Message;
 
-final readonly class SystemMessage implements MessageInterface
+final readonly class SystemMessage extends Message
 {
     public function __construct(public string $content)
     {
-    }
-
-    public function getRole(): Role
-    {
-        return Role::System;
+        parent::__construct(Role::System);
     }
 
     /**

src/Model/Message/ToolCallMessage.php

@@ -6,17 +6,13 @@
 
 use PhpLlm\LlmChain\Model\Response\ToolCall;
 
-final readonly class ToolCallMessage implements MessageInterface
+final readonly class ToolCallMessage extends Message
 {
     public function __construct(
         public ToolCall $toolCall,
         public string $content,
     ) {
-    }
-
-    public function getRole(): Role
-    {
-        return Role::ToolCall;
+        parent::__construct(Role::ToolCall);
     }
 
     /**

src/Model/Message/UserMessage.php

@@ -8,7 +8,7 @@
 use PhpLlm\LlmChain\Model\Message\Content\Image;
 use PhpLlm\LlmChain\Model\Message\Content\Text;
 
-final readonly class UserMessage implements MessageInterface
+final readonly class UserMessage extends Message
 {
     /**
      * @var list<Content>
@@ -19,11 +19,8 @@ public function __construct(
         Content ...$content,
     ) {
         $this->content = $content;
-    }
 
-    public function getRole(): Role
-    {
-        return Role::User;
+        parent::__construct(Role::User);
     }
 
     public function hasImageContent(): bool