[Store] Allow id to be int|string|Uuid for VectorDocument and TextDocument

docs/cookbook/rag-implementation.rst

@@ -205,7 +205,7 @@ Document Loading Strategies
     $articles = $articleRepository->findAll();
     $documents = array_map(
         fn($article) => new TextDocument(
-            id: Uuid::fromString($article->getId()),
+            id: $article->getId(),
             content: $article->getTitle().PHP_EOL.$article->getContent(),
             metadata: new Metadata(['author' => $article->getAuthor()])
         ),

src/store/src/Bridge/Azure/SearchStore.php

@@ -89,7 +89,7 @@ private function convertToIndexableArray(VectorDocument $document): array
     private function convertToVectorDocument(array $data): VectorDocument
     {
         return new VectorDocument(
-            id: Uuid::fromString($data['id']),
+            id: $data['id'],
             vector: !\array_key_exists($this->vectorFieldName, $data) || null === $data[$this->vectorFieldName]
                 ? new NullVector()
                 : new Vector($data[$this->vectorFieldName]),

src/store/src/Bridge/ChromaDb/Store.php

@@ -68,7 +68,7 @@ public function query(Vector $vector, array $options = []): array
         $documents = [];
         for ($i = 0; $i < \count($queryResponse->metadatas[0]); ++$i) {
             $documents[] = new VectorDocument(
-                id: Uuid::fromString($queryResponse->ids[0][$i]),
+                id: $queryResponse->ids[0][$i],
                 vector: new Vector($queryResponse->embeddings[0][$i]),
                 metadata: new Metadata($queryResponse->metadatas[0][$i]),
             );

src/store/src/Bridge/ClickHouse/Store.php

@@ -96,7 +96,7 @@ public function query(Vector $vector, array $options = [], ?float $minScore = nu
         $documents = [];
         foreach ($results as $result) {
             $documents[] = new VectorDocument(
-                id: Uuid::fromString($result['id']),
+                id: $result['id'],
                 vector: new Vector($result['embedding']),
                 metadata: new Metadata(json_decode($result['metadata'] ?? '{}', true, 512, \JSON_THROW_ON_ERROR)),
                 score: $result['score'],

src/store/src/Bridge/Cloudflare/Store.php

@@ -136,7 +136,7 @@ private function convertToVectorDocument(array $data): VectorDocument
             : new Vector($data['values']);
 
         return new VectorDocument(
-            id: Uuid::fromString($id),
+            id: $id,
             vector: $vector,
             metadata: new Metadata($data['metadata']),
             score: $data['score'] ?? null

src/store/src/Bridge/Local/CacheStore.php

@@ -80,7 +80,7 @@ public function query(Vector $vector, array $options = []): array
         $documents = $this->cache->get($this->cacheKey, static fn (): array => []);
 
         $vectorDocuments = array_map(static fn (array $document): VectorDocument => new VectorDocument(
-            id: Uuid::fromString($document['id']),
+            id: $document['id'],
             vector: new Vector($document['vector']),
             metadata: new Metadata($document['metadata']),
         ), $documents);

src/store/src/Bridge/Manticore/Store.php

@@ -148,7 +148,7 @@ private function convertToVectorDocument(array $data): VectorDocument
             : new Vector($payload[$this->field]);
 
         return new VectorDocument(
-            id: Uuid::fromString($payload['uuid']),
+            id: $payload['uuid'],
             vector: $vector,
             metadata: new Metadata($payload['metadata'] ?? []),
             score: $data['_knn_dist'] ?? null

src/store/src/Bridge/Neo4j/Store.php

@@ -115,7 +115,7 @@ private function convertToVectorDocument(array $data): VectorDocument
             : new Vector($payload['properties'][$this->embeddingsField]);
 
         return new VectorDocument(
-            id: Uuid::fromString($id),
+            id: $id,
             vector: $vector,
             metadata: new Metadata(json_decode($payload['properties']['metadata'], true)),
             score: $data[1] ?? null

src/store/src/Bridge/Pinecone/Store.php

@@ -70,7 +70,7 @@ public function query(Vector $vector, array $options = []): array
         $documents = [];
         foreach ($result->json()['matches'] as $match) {
             $documents[] = new VectorDocument(
-                id: Uuid::fromString($match['id']),
+                id: $match['id']),
                 vector: new Vector($match['values']),
                 metadata: new Metadata($match['metadata']),
                 score: $match['score'],

src/store/src/Bridge/Postgres/Store.php

@@ -173,7 +173,7 @@ public function query(Vector $vector, array $options = []): array
         $documents = [];
         foreach ($statement->fetchAll(\PDO::FETCH_ASSOC) as $result) {
             $documents[] = new VectorDocument(
-                id: Uuid::fromString($result['id']),
+                id: $result['id'],
                 vector: new Vector($this->fromPgvector($result['embedding'])),
                 metadata: new Metadata(json_decode($result['metadata'] ?? '{}', true, 512, \JSON_THROW_ON_ERROR)),
                 score: $result['score'],

src/store/src/Bridge/Qdrant/Store.php

@@ -151,7 +151,7 @@ private function convertToVectorDocument(array $data): VectorDocument
             : new Vector($data['vector']);
 
         return new VectorDocument(
-            id: Uuid::fromString($id),
+            id: $id,
             vector: $vector,
             metadata: new Metadata($data['payload']),
             score: $data['score'] ?? null

src/store/src/Bridge/Redis/Store.php

@@ -168,7 +168,7 @@ public function query(Vector $vector, array $options = []): array
             }
 
             $documents[] = new VectorDocument(
-                id: Uuid::fromString($data['$.id']),
+                id: $data['$.id'],
                 vector: new Vector($data['$.embedding'] ?? []),
                 metadata: new Metadata($data['$.metadata'] ?? []),
                 score: $score,

src/store/src/Bridge/Supabase/Store.php

@@ -138,7 +138,7 @@ public function query(Vector $vector, array $options = []): array
             $metadata = \is_array($record['metadata']) ? $record['metadata'] : json_decode($record['metadata'], true, 512, \JSON_THROW_ON_ERROR);
 
             $documents[] = new VectorDocument(
-                id: Uuid::fromString($record['id']),
+                id: $record['id'],
                 vector: new Vector($embedding),
                 metadata: new Metadata($metadata),
                 score: (float) $record['score'],

src/store/src/Bridge/SurrealDb/Store.php

@@ -147,7 +147,7 @@ private function convertToVectorDocument(array $data): VectorDocument
         unset($data['_metadata']['_id']);
 
         return new VectorDocument(
-            id: Uuid::fromString($id),
+            id: $id,
             vector: $vector,
             metadata: new Metadata($data['_metadata']),
         );

src/store/src/Document/TextDocument.php

@@ -19,22 +19,30 @@
  */
 final class TextDocument implements EmbeddableDocumentInterface
 {
+    private readonly int|string|Uuid $id;
+
     public function __construct(
-        private readonly Uuid $id,
+        int|string|Uuid $id,
         private readonly string $content,
         private readonly Metadata $metadata = new Metadata(),
     ) {
         if ('' === trim($this->content)) {
             throw new InvalidArgumentException('The content shall not be an empty string.');
         }
+
+        if (\is_string($id) && Uuid::isValid($id)) {
+            $this->id = Uuid::fromString($id);
+        } else {
+            $this->id = $id;
+        }
     }
 
     public function withContent(string $content): self
     {
         return new self($this->id, $content, $this->metadata);
     }
 
-    public function getId(): Uuid
+    public function getId(): int|string|Uuid
     {
         return $this->id;
     }

src/store/src/Document/VectorDocument.php

@@ -19,12 +19,19 @@
  */
 final class VectorDocument
 {
+    public readonly int|string|Uuid $id;
+
     public function __construct(
-        public readonly Uuid $id,
+        int|string|Uuid $id,
         public readonly VectorInterface $vector,
         public readonly Metadata $metadata = new Metadata(),
         public readonly ?float $score = null,
     ) {
+        if (\is_string($id) && Uuid::isValid($id)) {
+            $this->id = Uuid::fromString($id);
+        } else {
+            $this->id = $id;
+        }
     }
 
     /**

src/store/tests/Document/TextDocumentTest.php

@@ -22,6 +22,29 @@
 
 final class TextDocumentTest extends TestCase
 {
+    #[TestWith([1])]
+    #[TestWith(['id'])]
+    #[TestWith(['uuid'])]
+    public function testConstructorIdSupportsManyTypes(int|string $id)
+    {
+        if ('uuid' === $id) {
+            $id = Uuid::v4();
+        }
+
+        $document = new TextDocument($id, 'content');
+
+        $this->assertSame($id, $document->getId());
+    }
+
+    #[TestDox('Automatically convert strings in UUID format to Uuid instances')]
+    public function testConstructorConvertIdToUuid()
+    {
+        $id = Uuid::v4()->toString();
+        $document = new TextDocument($id, 'content');
+
+        $this->assertInstanceOf(Uuid::class, $document->getId());
+    }
+
     #[TestDox('Creates document with valid content and metadata')]
     public function testConstructorWithValidContent()
     {

src/store/tests/Document/VectorDocumentTest.php

@@ -15,6 +15,7 @@
 use PHPUnit\Framework\Attributes\TestDox;
 use PHPUnit\Framework\Attributes\TestWith;
 use PHPUnit\Framework\TestCase;
+use Symfony\AI\Platform\Vector\NullVector;
 use Symfony\AI\Platform\Vector\Vector;
 use Symfony\AI\Store\Document\Metadata;
 use Symfony\AI\Store\Document\VectorDocument;
@@ -25,6 +26,29 @@
  */
 final class VectorDocumentTest extends TestCase
 {
+    #[TestWith([1])]
+    #[TestWith(['id'])]
+    #[TestWith(['uuid'])]
+    public function testConstructorIdSupportsManyTypes(int|string $id)
+    {
+        if ('uuid' === $id) {
+            $id = Uuid::v4();
+        }
+
+        $document = new VectorDocument($id, new NullVector());
+
+        $this->assertSame($id, $document->id);
+    }
+
+    #[TestDox('Automatically convert strings in UUID format to Uuid instances')]
+    public function testConstructorConvertIdToUuid()
+    {
+        $id = Uuid::v4()->toString();
+        $document = new VectorDocument($id, new NullVector());
+
+        $this->assertInstanceOf(Uuid::class, $document->id);
+    }
+
     #[TestDox('Creates document with required parameters only')]
     public function testConstructorWithRequiredParameters()
     {