feat\!: add UUID to all messages and serialize in normalizers

- Add unique ID (UUIDv7) to all message types
- Serialize message IDs in all normalizers
- Create UuidAssertionTrait for testing UUID v7 validity
- Update all message tests with UUID assertions
- Add getId() method to MessageInterface
- Update symfony/uid dependency to ^6.4 || ^7.0

BREAKING CHANGE: MessageInterface now requires getId() method

Author: OskarStark

README.md

@@ -89,6 +89,32 @@ a **MessageBag** to a **Chain**, which takes care of LLM invocation and response
 Messages can be of different types, most importantly `UserMessage`, `SystemMessage`, or `AssistantMessage`, and can also
 have different content types, like `Text`, `Image` or `Audio`.
 
+#### Message Unique IDs
+
+Each message automatically receives a unique identifier (UUID v7) upon creation.
+This provides several benefits:
+
+- **Traceability**: Track individual messages through your application
+- **Time-ordered**: UUIDs are naturally sortable by creation time
+- **Timestamp extraction**: Get the exact creation time from the ID
+- **Database-friendly**: Sequential nature improves index performance
+
+```php
+use PhpLlm\LlmChain\Platform\Message\Message;
+
+$message = Message::ofUser('Hello, AI!');
+
+// Access the unique ID
+$id = $message->getId(); // Returns Symfony\Component\Uid\Uuid instance
+
+// Extract creation timestamp
+$createdAt = $id->getDateTime(); // Returns \DateTimeImmutable
+echo $createdAt->format('Y-m-d H:i:s.u'); // e.g., "2025-06-29 15:30:45.123456"
+
+// Get string representation
+echo $id->toRfc4122(); // e.g., "01928d1f-6f2e-7123-a456-123456789abc"
+```
+
 #### Example Chain call with messages
 
 ```php

src/Platform/Contract/Normalizer/Message/AssistantMessageNormalizer.php

@@ -31,12 +31,13 @@ public function getSupportedTypes(?string $format): array
     /**
      * @param AssistantMessage $data
      *
-     * @return array{role: 'assistant', content: string}
+     * @return array{role: 'assistant', id: string, content?: string, tool_calls?: array<array<string, mixed>>}
      */
     public function normalize(mixed $data, ?string $format = null, array $context = []): array
     {
         $array = [
             'role' => $data->getRole()->value,
+            'id' => $data->getId()->toRfc4122(),
         ];
 
         if (null !== $data->content) {

src/Platform/Contract/Normalizer/Message/SystemMessageNormalizer.php

@@ -27,13 +27,14 @@ public function getSupportedTypes(?string $format): array
     /**
      * @param SystemMessage $data
      *
-     * @return array{role: 'system', content: string}
+     * @return array{role: 'system', content: string, id: string}
      */
     public function normalize(mixed $data, ?string $format = null, array $context = []): array
     {
         return [
             'role' => $data->getRole()->value,
             'content' => $data->content,
+            'id' => $data->getId()->toRfc4122(),
         ];
     }
 }

src/Platform/Contract/Normalizer/Message/ToolCallMessageNormalizer.php

@@ -33,6 +33,7 @@ public function getSupportedTypes(?string $format): array
      *     role: 'tool',
      *     content: string,
      *     tool_call_id: string,
+     *     id: string,
      * }
      */
     public function normalize(mixed $data, ?string $format = null, array $context = []): array
@@ -41,6 +42,7 @@ public function normalize(mixed $data, ?string $format = null, array $context =
             'role' => $data->getRole()->value,
             'content' => $this->normalizer->normalize($data->content, $format, $context),
             'tool_call_id' => $data->toolCall->id,
+            'id' => $data->getId()->toRfc4122(),
         ];
     }
 }

src/Platform/Contract/Normalizer/Message/UserMessageNormalizer.php

@@ -32,11 +32,14 @@ public function getSupportedTypes(?string $format): array
     /**
      * @param UserMessage $data
      *
-     * @return array{role: 'assistant', content: string}
+     * @return array{role: 'assistant', content: string, id: string}
      */
     public function normalize(mixed $data, ?string $format = null, array $context = []): array
     {
-        $array = ['role' => $data->getRole()->value];
+        $array = [
+            'role' => $data->getRole()->value,
+            'id' => $data->getId()->toRfc4122(),
+        ];
 
         if (1 === \count($data->content) && $data->content[0] instanceof Text) {
             $array['content'] = $data->content[0]->text;

src/Platform/Message/AssistantMessage.php

@@ -5,26 +5,35 @@
 namespace PhpLlm\LlmChain\Platform\Message;
 
 use PhpLlm\LlmChain\Platform\Response\ToolCall;
+use Symfony\Component\Uid\Uuid;
 
 /**
  * @author Denis Zunke <[email protected]>
  */
 final readonly class AssistantMessage implements MessageInterface
 {
+    public Uuid $id;
+
     /**
      * @param ?ToolCall[] $toolCalls
      */
     public function __construct(
         public ?string $content = null,
         public ?array $toolCalls = null,
     ) {
+        $this->id = Uuid::v7();
     }
 
     public function getRole(): Role
     {
         return Role::Assistant;
     }
 
+    public function getId(): Uuid
+    {
+        return $this->id;
+    }
+
     public function hasToolCalls(): bool
     {
         return null !== $this->toolCalls && 0 !== \count($this->toolCalls);

src/Platform/Message/MessageInterface.php

@@ -4,10 +4,14 @@
 
 namespace PhpLlm\LlmChain\Platform\Message;
 
+use Symfony\Component\Uid\Uuid;
+
 /**
  * @author Denis Zunke <[email protected]>
  */
 interface MessageInterface
 {
     public function getRole(): Role;
+
+    public function getId(): Uuid;
 }

src/Platform/Message/SystemMessage.php

@@ -4,17 +4,27 @@
 
 namespace PhpLlm\LlmChain\Platform\Message;
 
+use Symfony\Component\Uid\Uuid;
+
 /**
  * @author Denis Zunke <[email protected]>
  */
 final readonly class SystemMessage implements MessageInterface
 {
+    public Uuid $id;
+
     public function __construct(public string $content)
     {
+        $this->id = Uuid::v7();
     }
 
     public function getRole(): Role
     {
         return Role::System;
     }
+
+    public function getId(): Uuid
+    {
+        return $this->id;
+    }
 }

src/Platform/Message/ToolCallMessage.php

@@ -5,20 +5,29 @@
 namespace PhpLlm\LlmChain\Platform\Message;
 
 use PhpLlm\LlmChain\Platform\Response\ToolCall;
+use Symfony\Component\Uid\Uuid;
 
 /**
  * @author Denis Zunke <[email protected]>
  */
 final readonly class ToolCallMessage implements MessageInterface
 {
+    public Uuid $id;
+
     public function __construct(
         public ToolCall $toolCall,
         public string $content,
     ) {
+        $this->id = Uuid::v7();
     }
 
     public function getRole(): Role
     {
         return Role::ToolCall;
     }
+
+    public function getId(): Uuid
+    {
+        return $this->id;
+    }
 }

src/Platform/Message/UserMessage.php

@@ -8,6 +8,7 @@
 use PhpLlm\LlmChain\Platform\Message\Content\ContentInterface;
 use PhpLlm\LlmChain\Platform\Message\Content\Image;
 use PhpLlm\LlmChain\Platform\Message\Content\ImageUrl;
+use Symfony\Component\Uid\Uuid;
 
 /**
  * @author Denis Zunke <[email protected]>
@@ -19,17 +20,25 @@
      */
     public array $content;
 
+    public Uuid $id;
+
     public function __construct(
         ContentInterface ...$content,
     ) {
         $this->content = $content;
+        $this->id = Uuid::v7();
     }
 
     public function getRole(): Role
     {
         return Role::User;
     }
 
+    public function getId(): Uuid
+    {
+        return $this->id;
+    }
+
     public function hasAudioContent(): bool
     {
         foreach ($this->content as $content) {