feat!: add UUID to all messages

[OskarStark]

Summary

• Added unique identifiers (UUIDv7) to all message types
• Each message now automatically gets a unique ID upon instantiation
• Added comprehensive tests for the new ID functionality

Breaking Change 🚨

This is a breaking change as MessageInterface now requires the getId(): Uuid method to be implemented by all message classes.

Implementation Details

• Added symfony/uid package dependency (^6.4 || ^7.1)
• Added public readonly Uuid $id property to all message classes
• IDs are generated automatically in constructors using Uuid::v7()
• Added getId() method to all message implementations

Why UUID v7?

UUID v7 offers significant advantages over other UUID versions:

• Time-ordered: Natural chronological sorting without additional timestamp fields
• Millisecond precision: Captures creation time with high accuracy
• Better database performance: Sequential nature improves B-tree index locality
• Globally unique: No coordination needed between distributed systems
• Extractable timestamp: Creation time can be retrieved from the ID itself

Practical Example

$message = new UserMessage(new Text('Hello'));
$timestamp = $message->getId()->getDateTime(); // Returns \DateTimeImmutable
echo $timestamp->format('Y-m-d H:i:s.u'); // e.g., "2025-06-29 23:45:12.123456"

Test Coverage

Added tests for each message type to ensure:

• ID is properly generated and accessible
• ID remains consistent for the same message instance
• Different message instances have different IDs
• Messages with identical content still receive unique IDs

Closes #77
Closes #344

🤖 Generated with Claude Code

[OskarStark]

@chr-hertel I have a question regarding the normalized message format:

Currently, the normalizers include the UUID as an id field in the serialized format. In our project, we also need the timestamp extracted from the UUID v7 in the normalized data.

Should we:

1. Add the timestamp directly to the normalizers in this library (e.g., 'timestamp' => $data->getId()->getDateTime()->format('c'))
2. Or keep the normalizers minimal and let projects that need the timestamp decorate the normalizers?

I'm leaning towards option 2 to keep the library focused, but wanted to get your thoughts on this, knowing that I need the timestamp in my project 😄

Example of what option 1 would look like:

public function normalize(mixed $data, ?string $format = null, array $context = []): array
{
    return [
        'role' => $data->getRole()->value,
        'content' => $data->content,
        'id' => $data->getId()->toRfc4122(),
        'timestamp' => $data->getId()->getDateTime()->format('c'), // ISO 8601 format
    ];
}

What do you think?

cc @DZunke @llupa

[DZunke]

I would say go with option 2 to keep the library as minimal as needed. Having the UUIDv7 is already allowing people to extract the timestamp when overriding the normalizer - as shown in the example. It is sortable by this data and also extractable on demand afterwards when someone needs it and do not want to have an overwritten normalizer. So flexibility is there.

As a compromize, when moving on with option one, it would be nice to have the format configurable with the normalizer context because the ISO 8601 format is not the only one utilized and so it would be more flexible.

[OskarStark]

Great discussion! I think Dennis's suggestion for configurable timestamps is excellent and would provide the flexibility needed.

However, I believe we should proceed step by step. This PR already implements the core UUID functionality and ID serialization, which is the foundation. Let's get this merged first, then we can tackle the configurable timestamp feature in a follow-up PR.

The current implementation gives us:

• Unique message IDs (UUID v7 with embedded timestamps)
• ID serialization in all normalizers
• Solid foundation for future timestamp features

Once this is merged, we can discuss and implement the configurable timestamp context approach in a separate, focused PR. What do you think?

[DZunke]

Sounds pretty good to me. Options would then only have to be transported to the normalizers context. But it could be a good next step, as you mentioned. I already saw the code you had here as an example before editing your message and it looked also good.

The only thing that i would then think about is the options transport. Currently it is this flexible array construction but maybe the options also need a bit more brain to have it maybe more structured into different features with a context class, or something in this direction but this is also a topic on it's own.

Generally, even i was against having the Message bloated in last discussions, i think the MR gives a good foundation for further progressing. At least because there is an interface now and the facade approach, from the last discussion about it, is obsolete.

[OskarStark]

You mean this code, right ❓

For reference, here's how we could implement the configurable timestamp feature in a follow-up PR:

// Example implementation for SystemMessageNormalizer
public function normalize(mixed $data, ?string $format = null, array $context = []): array
{
    $array = [
        'role' => $data->getRole()->value,
        'content' => $data->content,
        'id' => $data->getId()->toRfc4122(),
    ];

    // Add timestamp if requested in context
    if ($context['include_timestamp'] ?? false) {
        $timestampFormat = $context['timestamp_format'] ?? 'c'; // ISO 8601 as default
        $array['timestamp'] = $data->getId()->getDateTime()->format($timestampFormat);
    }

    return $array;
}

Usage examples:

// Default behavior (no timestamp)
$normalizer->normalize($message);

// Include ISO 8601 timestamp
$normalizer->normalize($message, null, ['include_timestamp' => true]);

// Include Unix timestamp
$normalizer->normalize($message, null, [
    'include_timestamp' => true,
    'timestamp_format' => 'U'
]);

// Include custom format
$normalizer->normalize($message, null, [
    'include_timestamp' => true,
    'timestamp_format' => 'Y-m-d H:i:s'
]);

This approach would need to be applied to all message normalizers (User, System, Assistant, ToolCall) for consistency.

[DZunke]

Yep! That is it what i saw with the last message - without the examples. Thanks for re-referencing it!

[OskarStark]

I like this more, than having the preg match written over and over again

[OskarStark]

CI 💚

[OskarStark]

So I could get an approval from you @DZunke ? 😄

[DZunke]

@OskarStark sure, i scrolled through the code a second time and yeah, it looks fine from my side. Thanks again!

[chr-hertel]

So, @OskarStark, how much of code and comments were hand crafted and what AI? 😆

[OskarStark]

Everything is AI, except 3 of my comments 😄

[chr-hertel]

The normalizers are intended for the contract of the API payload - so we cannot just add the ID there. OpenAI might tolerate that, but for example Mistral and Anthropic fail with invalid request errors.
The UID is intended for user land code anyways, and i guess after a revert in normalizers this is good to be merged :)

[chr-hertel]

Really nice one - finally settled :D thanks @OskarStark

[OskarStark]

Can we please get a release? 😄 So @llupa can proceed? Thanks