feature #707 [Platform][Store] Introduce EmbeddableDocumentInterface (paulinevos)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Platform][Store] Introduce `EmbeddableDocumentInterface`

| Q             | A
| ------------- | ---
| Bug fix?      |no
| New feature?  | no <!-- please update src/**/CHANGELOG.md files -->
| Docs?         | no <!-- required for new features -->
| Issues        | Fix #18
| License       | MIT

In an effort to support user land objects for the store, this PR introduces an `Embeddable` interface instead of relying on the `TextDocument` class. Please note this interface would require php ^8.4, as it uses interface properties. I chose this approach so as to introduce minimal change to the existing `TextDocument` class and usages. Instead of `content`, an `Embeddable` document has a `data` property. Any type embeddable document class can implement a hook for the `data` property if needed.

This PR also introduces union types for the document IDs so as to not make assumptions about the ID type.

Commits
-------

3e15fd5 [Platform][Store] Introduce `EmbeddableDocumentInterface`

Author: OskarStark

examples/document/vectorizing-text-documents.php

@@ -26,6 +26,6 @@
 ];
 
 $vectorizer = new Vectorizer($platform, 'text-embedding-3-large');
-$vectorDocuments = $vectorizer->vectorizeTextDocuments($textDocuments);
+$vectorDocuments = $vectorizer->vectorizeEmbeddableDocuments($textDocuments);
 
 dump(array_map(fn (VectorDocument $document) => $document->vector->getDimensions(), $vectorDocuments));

src/store/src/Document/EmbeddableDocumentInterface.php

@@ -0,0 +1,21 @@
+<?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\Store\Document;
+
+interface EmbeddableDocumentInterface
+{
+    public function getId(): mixed;
+
+    public function getContent(): string;
+
+    public function getMetadata(): Metadata;
+}

src/store/src/Document/Filter/TextContainsFilter.php

@@ -49,7 +49,7 @@ public function filter(iterable $documents, array $options = []): iterable
         $caseSensitive = $options[self::OPTION_CASE_SENSITIVE] ?? $this->caseSensitive;
 
         foreach ($documents as $document) {
-            $content = $document->content;
+            $content = $document->getContent();
 
             if ($caseSensitive) {
                 $contains = str_contains($content, $needle);

src/store/src/Document/FilterInterface.php

@@ -20,10 +20,10 @@
 interface FilterInterface
 {
     /**
-     * @param iterable<TextDocument> $documents
-     * @param array<string, mixed>   $options
+     * @param iterable<EmbeddableDocumentInterface> $documents
+     * @param array<string, mixed>                  $options
      *
-     * @return iterable<TextDocument>
+     * @return iterable<EmbeddableDocumentInterface>
      */
     public function filter(iterable $documents, array $options = []): iterable;
 }

src/store/src/Document/Loader/InMemoryLoader.php

@@ -11,19 +11,19 @@
 
 namespace Symfony\AI\Store\Document\Loader;
 
+use Symfony\AI\Store\Document\EmbeddableDocumentInterface;
 use Symfony\AI\Store\Document\LoaderInterface;
-use Symfony\AI\Store\Document\TextDocument;
 
 /**
- * Loader that returns pre-loaded TextDocuments from memory.
+ * Loader that returns preloaded documents from memory.
  * Useful for testing or when documents are already available as objects.
  *
  * @author Oskar Stark <[email protected]>
  */
 final readonly class InMemoryLoader implements LoaderInterface
 {
     /**
-     * @param TextDocument[] $documents
+     * @param EmbeddableDocumentInterface[] $documents
      */
     public function __construct(
         private array $documents = [],

src/store/src/Document/LoaderInterface.php

@@ -20,7 +20,7 @@ interface LoaderInterface
      * @param string|null          $source  Identifier for the loader to load the documents from, e.g. file path, folder, or URL. Can be null for InMemoryLoader.
      * @param array<string, mixed> $options loader specific set of options to control the loading process
      *
-     * @return iterable<TextDocument> iterable of TextDocuments loaded from the source
+     * @return iterable<EmbeddableDocumentInterface> iterable of embeddable documents loaded from the source
      */
     public function load(?string $source, array $options = []): iterable;
 }

src/store/src/Document/TextDocument.php

@@ -17,12 +17,12 @@
 /**
  * @author Christopher Hertel <[email protected]>
  */
-final readonly class TextDocument
+final readonly class TextDocument implements EmbeddableDocumentInterface
 {
     public function __construct(
-        public Uuid $id,
-        public string $content,
-        public Metadata $metadata = new Metadata(),
+        private Uuid $id,
+        private string $content,
+        private Metadata $metadata = new Metadata(),
     ) {
         if ('' === trim($this->content)) {
             throw new InvalidArgumentException('The content shall not be an empty string.');
@@ -33,4 +33,19 @@ public function withContent(string $content): self
     {
         return new self($this->id, $content, $this->metadata);
     }
+
+    public function getId(): Uuid
+    {
+        return $this->id;
+    }
+
+    public function getContent(): string
+    {
+        return $this->content;
+    }
+
+    public function getMetadata(): Metadata
+    {
+        return $this->metadata;
+    }
 }

src/store/src/Document/Transformer/TextReplaceTransformer.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\AI\Store\Document\Transformer;
 
+use Symfony\AI\Store\Document\TextDocument;
 use Symfony\AI\Store\Document\TransformerInterface;
 use Symfony\AI\Store\Exception\InvalidArgumentException;
 
@@ -32,6 +33,7 @@ public function __construct(
     }
 
     /**
+     * @param iterable<TextDocument>                   $documents
      * @param array{search?: string, replace?: string} $options
      */
     public function transform(iterable $documents, array $options = []): iterable
@@ -42,7 +44,7 @@ public function transform(iterable $documents, array $options = []): iterable
         self::validate($search, $replace);
 
         foreach ($documents as $document) {
-            yield $document->withContent(str_replace($search, $replace, $document->content));
+            yield $document->withContent(str_replace($search, $replace, $document->getContent()));
         }
     }
 

src/store/src/Document/Transformer/TextSplitTransformer.php

@@ -51,13 +51,13 @@ public function transform(iterable $documents, array $options = []): iterable
         }
 
         foreach ($documents as $document) {
-            if (mb_strlen($document->content) <= $chunkSize) {
+            if (mb_strlen($document->getContent()) <= $chunkSize) {
                 yield $document;
 
                 continue;
             }
 
-            $text = $document->content;
+            $text = $document->getContent();
             $length = mb_strlen($text);
             $start = 0;
 
@@ -66,9 +66,9 @@ public function transform(iterable $documents, array $options = []): iterable
                 $chunkText = mb_substr($text, $start, $end - $start);
 
                 yield new TextDocument(Uuid::v4(), $chunkText, new Metadata([
-                    Metadata::KEY_PARENT_ID => $document->id,
+                    Metadata::KEY_PARENT_ID => $document->getId(),
                     Metadata::KEY_TEXT => $chunkText,
-                    ...$document->metadata,
+                    ...$document->getMetadata(),
                 ]));
 
                 $start += ($chunkSize - $overlap);

src/store/src/Document/Transformer/TextTrimTransformer.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\AI\Store\Document\Transformer;
 
+use Symfony\AI\Store\Document\TextDocument;
 use Symfony\AI\Store\Document\TransformerInterface;
 
 /**
@@ -20,10 +21,13 @@
  */
 final readonly class TextTrimTransformer implements TransformerInterface
 {
+    /**
+     * @param iterable<TextDocument> $documents
+     */
     public function transform(iterable $documents, array $options = []): iterable
     {
         foreach ($documents as $document) {
-            yield $document->withContent(trim($document->content));
+            yield $document->withContent(trim($document->getContent()));
         }
     }
 }