refactor(store): surrealDB store improved && tested

Author: Guikingone

src/store/doc/index.rst

@@ -41,6 +41,7 @@ You can find more advanced usage in combination with an Agent using the store fo
 * `Similarity Search with MongoDB (RAG)`_
 * `Similarity Search with Pinecone (RAG)`_
 * `Similarity Search with Meilisearch (RAG)`_
+* `Similarity Search with SurrealDB (RAG)`_
 * `Similarity Search with memory storage (RAG)`_
 
 Supported Stores
@@ -53,6 +54,7 @@ Supported Stores
 * `Pinecone`_ (requires `probots-io/pinecone-php` as additional dependency)
 * `Postgres`_ (requires `ext-pdo`)
 * `Meilisearch`_
+* `SurrealDB`_
 * `InMemory`_
 
 .. note::
@@ -91,6 +93,7 @@ This leads to a store implementing two methods::
 .. _`Similarity Search with MongoDB (RAG)`: https://github.com/symfony/ai/blob/main/examples/store/mongodb-similarity-search.php
 .. _`Similarity Search with Pinecone (RAG)`: https://github.com/symfony/ai/blob/main/examples/store/pinecone-similarity-search.php
 .. _`Similarity Search with Meilisearch (RAG)`: https://github.com/symfony/ai/blob/main/examples/store/meilisearch-similarity-search.php
+.. _`Similarity Search with SurrealDB (RAG)`: https://github.com/symfony/ai/blob/main/examples/store/surrealdb-similarity-search.php
 .. _`Similarity Search with memory storage (RAG)`: https://github.com/symfony/ai/blob/main/examples/store/memory-similarity-search.php
 .. _`Azure AI Search`: https://azure.microsoft.com/products/ai-services/ai-search
 .. _`Chroma`: https://www.trychroma.com/
@@ -99,5 +102,6 @@ This leads to a store implementing two methods::
 .. _`Pinecone`: https://www.pinecone.io/
 .. _`Postgres`: https://www.postgresql.org/about/news/pgvector-070-released-2852/
 .. _`Meilisearch`: https://www.meilisearch.com/
+.. _`SurrealDB`: https://surrealdb.com/
 .. _`InMemory`: https://www.php.net/manual/en/language.types.array.php
 .. _`GitHub`: https://github.com/symfony/ai/issues/16

src/store/src/Bridge/SurrealDB/Store.php

@@ -11,11 +11,11 @@
 
 namespace Symfony\AI\Store\Bridge\SurrealDB;
 
-use Symfony\AI\AIBundle\Exception\InvalidArgumentException;
 use Symfony\AI\Platform\Vector\NullVector;
 use Symfony\AI\Platform\Vector\Vector;
 use Symfony\AI\Store\Document\Metadata;
 use Symfony\AI\Store\Document\VectorDocument;
+use Symfony\AI\Store\Exception\InvalidArgumentException;
 use Symfony\AI\Store\Exception\RuntimeException;
 use Symfony\AI\Store\InitializableStoreInterface;
 use Symfony\AI\Store\VectorStoreInterface;
@@ -53,7 +53,7 @@ public function add(VectorDocument ...$documents): void
 
         foreach ($documents as $document) {
             if (self::MAXIMUM_EMBEDDINGS_DIMENSIONS < $document->vector->getDimensions()) {
-                throw new RuntimeException(\sprintf('The SurrealDB HTTP API does not support embeddings with more than %d dimensions, found %d', self::MAXIMUM_EMBEDDINGS_DIMENSIONS, $document->vector->getDimensions()));
+                throw new InvalidArgumentException(\sprintf('The SurrealDB HTTP API does not support embeddings with more than %d dimensions, found %d', self::MAXIMUM_EMBEDDINGS_DIMENSIONS, $document->vector->getDimensions()));
             }
 
             $this->request('POST', \sprintf('key/%s', $this->table), $this->convertToIndexableArray($document), [
@@ -66,11 +66,17 @@ public function add(VectorDocument ...$documents): void
 
     public function query(Vector $vector, array $options = [], ?float $minScore = null): array
     {
+        if (self::MAXIMUM_EMBEDDINGS_DIMENSIONS < $vector->getDimensions()) {
+            throw new InvalidArgumentException(\sprintf('The dimensions of the vector must be less than or equal to %d, found %d', self::MAXIMUM_EMBEDDINGS_DIMENSIONS, $vector->getDimensions()));
+        }
+
         $authenticationToken = $this->authenticate($options);
 
+        $vectors = json_encode($vector->getData());
+
         $results = $this->request('POST', 'sql', \sprintf(
             'SELECT id, %s, _metadata, vector::similarity::%s(%s, %s) AS distance FROM %s WHERE %s <|2|> %s;',
-            $this->vectorFieldName, $this->strategy, $this->vectorFieldName, json_encode($vector->getData()), $this->table, $this->vectorFieldName, json_encode($vector->getData()),
+            $this->vectorFieldName, $this->strategy, $this->vectorFieldName, $vectors, $this->table, $this->vectorFieldName, $vectors,
         ), [
             'Surreal-NS' => $this->namespace,
             'Surreal-DB' => $this->database,
@@ -94,6 +100,12 @@ public function initialize(array $options = []): void
         ]);
     }
 
+    /**
+     * @param array<string, mixed>|string $payload
+     * @param array<string, mixed>        $extraHeaders
+     *
+     * @return array<string|int, mixed>
+     */
     private function request(string $method, string $endpoint, array|string $payload, array $extraHeaders = []): array
     {
         $url = \sprintf('%s/%s', $this->endpointUrl, $endpoint);
@@ -154,14 +166,19 @@ private function convertToVectorDocument(array $data): VectorDocument
         );
     }
 
+    /**
+     * @param array{
+     *     namespacedUser?: bool
+     * } $options The namespacedUser option is used to determine if the user is root or not, if not, both the namespace and database must be specified
+     */
     private function authenticate(array $options): string
     {
         $authenticationPayload = [
             'user' => $this->user,
             'pass' => $this->password,
         ];
 
-        if (\array_key_exists('namespacedUser', $options) && '' !== $options['namespacedUser']) {
+        if (\array_key_exists('namespacedUser', $options) && !$options['namespacedUser']) {
             $authenticationPayload['ns'] = $this->namespace;
             $authenticationPayload['db'] = $this->database;
         }