feat\!: add unique ID (UID) to all messages

BREAKING CHANGE: MessageInterface now requires getUid() method

- Added symfony/uid package dependency
- Added UuidV7 uid property to all message classes (UserMessage, AssistantMessage, SystemMessage, ToolCallMessage)
- UIDs are automatically generated upon message instantiation
- Added comprehensive tests for UID functionality

Closes #77
Closes #344

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: OskarStark

composer.json

@@ -33,7 +33,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",
+        "symfony/uid": "^7.3",
         "webmozart/assert": "^1.11"
     },
     "require-dev": {

src/Platform/Message/AssistantMessage.php

@@ -5,26 +5,35 @@
 namespace PhpLlm\LlmChain\Platform\Message;
 
 use PhpLlm\LlmChain\Platform\Response\ToolCall;
+use Symfony\Component\Uid\UuidV7;
 
 /**
  * @author Denis Zunke <[email protected]>
  */
 final readonly class AssistantMessage implements MessageInterface
 {
+    public UuidV7 $uid;
+
     /**
      * @param ?ToolCall[] $toolCalls
      */
     public function __construct(
         public ?string $content = null,
         public ?array $toolCalls = null,
     ) {
+        $this->uid = new UuidV7();
     }
 
     public function getRole(): Role
     {
         return Role::Assistant;
     }
 
+    public function getUid(): UuidV7
+    {
+        return $this->uid;
+    }
+
     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\UuidV7;
+
 /**
  * @author Denis Zunke <[email protected]>
  */
 interface MessageInterface
 {
     public function getRole(): Role;
+
+    public function getUid(): UuidV7;
 }

src/Platform/Message/SystemMessage.php

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

src/Platform/Message/ToolCallMessage.php

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

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\UuidV7;
 
 /**
  * @author Denis Zunke <[email protected]>
@@ -19,17 +20,25 @@
      */
     public array $content;
 
+    public UuidV7 $uid;
+
     public function __construct(
         ContentInterface ...$content,
     ) {
         $this->content = $content;
+        $this->uid = new UuidV7();
     }
 
     public function getRole(): Role
     {
         return Role::User;
     }
 
+    public function getUid(): UuidV7
+    {
+        return $this->uid;
+    }
+
     public function hasAudioContent(): bool
     {
         foreach ($this->content as $content) {

tests/Platform/Message/AssistantMessageTest.php

@@ -12,6 +12,7 @@
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\Uid\UuidV7;
 
 #[CoversClass(AssistantMessage::class)]
 #[UsesClass(ToolCall::class)]
@@ -43,4 +44,23 @@ 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->uid);
+        self::assertInstanceOf(UuidV7::class, $message->getUid());
+        self::assertSame($message->uid, $message->getUid());
+    }
+
+    #[Test]
+    public function differentMessagesHaveDifferentUids(): void
+    {
+        $message1 = new AssistantMessage('foo');
+        $message2 = new AssistantMessage('bar');
+
+        self::assertNotEquals($message1->getUid()->toRfc4122(), $message2->getUid()->toRfc4122());
+    }
 }

tests/Platform/Message/SystemMessageTest.php

@@ -10,6 +10,7 @@
 use PHPUnit\Framework\Attributes\Small;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\Uid\UuidV7;
 
 #[CoversClass(SystemMessage::class)]
 #[Small]
@@ -23,4 +24,23 @@ 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->uid);
+        self::assertInstanceOf(UuidV7::class, $message->getUid());
+        self::assertSame($message->uid, $message->getUid());
+    }
+
+    #[Test]
+    public function differentMessagesHaveDifferentUids(): void
+    {
+        $message1 = new SystemMessage('foo');
+        $message2 = new SystemMessage('bar');
+
+        self::assertNotEquals($message1->getUid()->toRfc4122(), $message2->getUid()->toRfc4122());
+    }
 }

tests/Platform/Message/ToolCallMessageTest.php

@@ -11,6 +11,7 @@
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\Uid\UuidV7;
 
 #[CoversClass(ToolCallMessage::class)]
 #[UsesClass(ToolCall::class)]
@@ -26,4 +27,25 @@ public function constructionIsPossible(): void
         self::assertSame($toolCall, $obj->toolCall);
         self::assertSame('bar', $obj->content);
     }
+
+    #[Test]
+    public function messageHasUid(): void
+    {
+        $toolCall = new ToolCall('foo', 'bar');
+        $message = new ToolCallMessage($toolCall, 'bar');
+
+        self::assertInstanceOf(UuidV7::class, $message->uid);
+        self::assertInstanceOf(UuidV7::class, $message->getUid());
+        self::assertSame($message->uid, $message->getUid());
+    }
+
+    #[Test]
+    public function differentMessagesHaveDifferentUids(): void
+    {
+        $toolCall = new ToolCall('foo', 'bar');
+        $message1 = new ToolCallMessage($toolCall, 'bar');
+        $message2 = new ToolCallMessage($toolCall, 'baz');
+
+        self::assertNotEquals($message1->getUid()->toRfc4122(), $message2->getUid()->toRfc4122());
+    }
 }

tests/Platform/Message/UserMessageTest.php

@@ -14,6 +14,7 @@
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\Uid\UuidV7;
 
 #[CoversClass(UserMessage::class)]
 #[UsesClass(Text::class)]
@@ -73,4 +74,23 @@ public function hasImageContentWithImage(): void
 
         self::assertTrue($message->hasImageContent());
     }
+
+    #[Test]
+    public function messageHasUid(): void
+    {
+        $message = new UserMessage(new Text('foo'));
+
+        self::assertInstanceOf(UuidV7::class, $message->uid);
+        self::assertInstanceOf(UuidV7::class, $message->getUid());
+        self::assertSame($message->uid, $message->getUid());
+    }
+
+    #[Test]
+    public function differentMessagesHaveDifferentUids(): void
+    {
+        $message1 = new UserMessage(new Text('foo'));
+        $message2 = new UserMessage(new Text('bar'));
+
+        self::assertNotEquals($message1->getUid()->toRfc4122(), $message2->getUid()->toRfc4122());
+    }
 }