feature #55 feat!: add UUID to all messages (OskarStark)

This PR was merged into the main branch.

Discussion
----------

feat!: add UUID to all messages

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Docs?         | yes
| Issues        |
| License       | MIT

Cherry picking php-llm/llm-chain#364

Commits
-------

4fa1279 feat!: add UUID to all messages (#364)

Author: OskarStark

src/platform/composer.json

@@ -32,6 +32,7 @@
         "symfony/property-info": "^6.4 || ^7.1",
         "symfony/serializer": "^6.4 || ^7.1",
         "symfony/type-info": "^7.2.3",
+        "symfony/uid": "^6.4 || ^7.1",
         "webmozart/assert": "^1.11"
     },
     "require-dev": {

src/platform/doc/index.rst

@@ -124,6 +124,31 @@ have different content types, like ``Text``, ``Image`` or ``Audio``, and can be
         Message::ofUser('Please describe this picture?', Image::fromFile('/path/to/image.jpg')),
     );
 
+**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
+
+.. code-block:: 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"
+
 Response Streaming
 ------------------
 

src/platform/src/Message/AssistantMessage.php

@@ -12,26 +12,35 @@
 namespace Symfony\AI\Platform\Message;
 
 use Symfony\AI\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/src/Message/MessageInterface.php

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

src/platform/src/Message/SystemMessage.php

@@ -11,17 +11,27 @@
 
 namespace Symfony\AI\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/src/Message/ToolCallMessage.php

@@ -12,20 +12,29 @@
 namespace Symfony\AI\Platform\Message;
 
 use Symfony\AI\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/src/Message/UserMessage.php

@@ -15,6 +15,7 @@
 use Symfony\AI\Platform\Message\Content\ContentInterface;
 use Symfony\AI\Platform\Message\Content\Image;
 use Symfony\AI\Platform\Message\Content\ImageUrl;
+use Symfony\Component\Uid\Uuid;
 
 /**
  * @author Denis Zunke <[email protected]>
@@ -26,17 +27,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) {

src/platform/tests/Helper/UuidAssertionTrait.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Platform\Tests\Helper;
+
+trait UuidAssertionTrait
+{
+    /**
+     * Asserts that a value is a valid UUID v7 string.
+     */
+    public static function assertIsUuidV7(mixed $actual, string $message = ''): void
+    {
+        self::assertIsString($actual, $message ?: 'Failed asserting that value is a string.');
+        self::assertMatchesRegularExpression(
+            '/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i',
+            $actual,
+            $message ?: 'Failed asserting that value is a valid UUID v7.'
+        );
+    }
+}

src/platform/tests/Message/AssistantMessageTest.php

@@ -19,12 +19,16 @@
 use Symfony\AI\Platform\Message\AssistantMessage;
 use Symfony\AI\Platform\Message\Role;
 use Symfony\AI\Platform\Response\ToolCall;
+use Symfony\AI\Platform\Tests\Helper\UuidAssertionTrait;
+use Symfony\Component\Uid\UuidV7;
 
 #[CoversClass(AssistantMessage::class)]
 #[UsesClass(ToolCall::class)]
 #[Small]
 final class AssistantMessageTest extends TestCase
 {
+    use UuidAssertionTrait;
+
     #[Test]
     public function theRoleOfTheMessageIsAsExpected(): void
     {
@@ -50,4 +54,36 @@ public function constructionWithoutContentIsPossible(): void
         self::assertSame([$toolCall], $message->toolCalls);
         self::assertTrue($message->hasToolCalls());
     }
+
+    #[Test]
+    public function messageHasUid(): void
+    {
+        $message = new AssistantMessage('foo');
+
+        self::assertInstanceOf(UuidV7::class, $message->id);
+        self::assertInstanceOf(UuidV7::class, $message->getId());
+        self::assertSame($message->id, $message->getId());
+    }
+
+    #[Test]
+    public function differentMessagesHaveDifferentUids(): void
+    {
+        $message1 = new AssistantMessage('foo');
+        $message2 = new AssistantMessage('bar');
+
+        self::assertNotSame($message1->getId()->toRfc4122(), $message2->getId()->toRfc4122());
+        self::assertIsUuidV7($message1->getId()->toRfc4122());
+        self::assertIsUuidV7($message2->getId()->toRfc4122());
+    }
+
+    #[Test]
+    public function sameMessagesHaveDifferentUids(): void
+    {
+        $message1 = new AssistantMessage('foo');
+        $message2 = new AssistantMessage('foo');
+
+        self::assertNotSame($message1->getId()->toRfc4122(), $message2->getId()->toRfc4122());
+        self::assertIsUuidV7($message1->getId()->toRfc4122());
+        self::assertIsUuidV7($message2->getId()->toRfc4122());
+    }
 }

src/platform/tests/Message/SystemMessageTest.php

@@ -17,11 +17,15 @@
 use PHPUnit\Framework\TestCase;
 use Symfony\AI\Platform\Message\Role;
 use Symfony\AI\Platform\Message\SystemMessage;
+use Symfony\AI\Platform\Tests\Helper\UuidAssertionTrait;
+use Symfony\Component\Uid\UuidV7;
 
 #[CoversClass(SystemMessage::class)]
 #[Small]
 final class SystemMessageTest extends TestCase
 {
+    use UuidAssertionTrait;
+
     #[Test]
     public function constructionIsPossible(): void
     {
@@ -30,4 +34,36 @@ public function constructionIsPossible(): void
         self::assertSame(Role::System, $message->getRole());
         self::assertSame('foo', $message->content);
     }
+
+    #[Test]
+    public function messageHasUid(): void
+    {
+        $message = new SystemMessage('foo');
+
+        self::assertInstanceOf(UuidV7::class, $message->id);
+        self::assertInstanceOf(UuidV7::class, $message->getId());
+        self::assertSame($message->id, $message->getId());
+    }
+
+    #[Test]
+    public function differentMessagesHaveDifferentUids(): void
+    {
+        $message1 = new SystemMessage('foo');
+        $message2 = new SystemMessage('bar');
+
+        self::assertNotSame($message1->getId()->toRfc4122(), $message2->getId()->toRfc4122());
+        self::assertIsUuidV7($message1->getId()->toRfc4122());
+        self::assertIsUuidV7($message2->getId()->toRfc4122());
+    }
+
+    #[Test]
+    public function sameMessagesHaveDifferentUids(): void
+    {
+        $message1 = new SystemMessage('foo');
+        $message2 = new SystemMessage('foo');
+
+        self::assertNotSame($message1->getId()->toRfc4122(), $message2->getId()->toRfc4122());
+        self::assertIsUuidV7($message1->getId()->toRfc4122());
+        self::assertIsUuidV7($message2->getId()->toRfc4122());
+    }
 }