[Store] Add SurrealDB

[Guikingone]

Q	A
Bug fix?	no
New feature?	yes
Docs?	yes
Issues	None
License	MIT

Hi 👋🏻

This PR aim to introduce SurrealDB as a store for embeddings, the store use the HTTP API as the PHP SDK is ugly to use (and does not allow mocks), the tests needs to be improved / completed but the main implementation is ready.

PS: By default, we can't send more than 1275 embeddings during the insertion phase, the SDK can bypass this limitation but again, testing issues, API and more so, the road to follow is up to the team.

[OskarStark]

We just created some CHANGELOG.md files.
Please rebase your branch and add info to the appropriate CHANGELOG.md file.

Thanks

[chr-hertel]

You're really on a great streak here to level up the store bridges - thanks for that! 🙏

Somehow the example doesn't work for me again - see below

[Guikingone]

@OskarStark 👋🏻

I updated the CHANGELOG.md file for store 🙂

[OskarStark]

Needs a rebase please

[chr-hertel]

small things about the inner contract of the Store implementation here

[chr-hertel]

what about changing the array $extraHeaders argument to string $authenticationToek and moving everything to here?

Suggested change

	$response = $this->httpClient->request($method, $url, array_merge($finalPayload, [
	'headers' => array_merge($extraHeaders, [
	'Accept' => 'application/json',
	'Content-Type' => 'application/json',
	]),
	]));
	$response = $this->httpClient->request($method, $url, array_merge($finalPayload, [
	'headers' => [
	'Accept' => 'application/json',
	'Content-Type' => 'application/json',
	'Surreal-NS' => $this->namespace,
	'Surreal-DB' => $this->database,
	'Authorization' => \sprintf('Bearer %s', $authenticationToken),
	],
	]));

[Guikingone]

The authentication token is not always required, same for Surreal-NS and Surreal-DB, those headers are not required during signin

[chr-hertel]

okay, missed that, than please let's decouple those two types of requests.

meaning, instead of using the ->request(...) in authenticate - just use the plain httpClient.

this will also remove that is_string ? body : json handling in the request method.

[chr-hertel]

if we only use that one specific option here, we could replace the blurry array $options by bool $namespacedUser

in general i wonder why that is an option and not part of the contructor arguments like $user and $password - isn't it directly connected?

[Guikingone]

namespacedUser is used if you're not root, this force the user to specify a user with its namespace, I can define the options as false by default.

[chr-hertel]

what do you think about a local cache var to make sure we authenticate only once per request/command/message?

    {
        if (isset($this->authenticationToken) {
            return $this->authenticationToken;
        }
    
        $authenticationPayload = ['user' => $this->user, 'pass' => $this->password];

        if ($this->isNamespacedUser) {
            $authenticationPayload['ns'] = $this->namespace;
            $authenticationPayload['db'] = $this->database;
        }

        $authenticationResponse = $this->httpClient->request('POST', sprintf('%s/signin'), $this->endpointUrl, $authenticationPayload)->toArray();

        if (!\array_key_exists('token', $authenticationResponse)) {
            throw new RuntimeException('The SurrealDB authentication response does not contain a token.');
        }

        return $this->authenticationToken = $authenticationResponse['token'];
    }

[OskarStark]

Suggested change

	#[\SensitiveParameter]
	private readonly string $user,
	#[\SensitiveParameter] private readonly string $user,

same for the others