feat: Add Albert API platform support with comprehensive tests

- Add Albert-specific model clients for OpenAI-compatible API
- Add PlatformFactory for easy Albert platform creation
- Add comprehensive unit tests for all components
- Require explicit API version in URL (e.g., /v1, /v2)
- Add strict URL validation (HTTPS required, no trailing slashes)
- Use plain PHP exception handling instead of external assertions
- Apply consistent code style and rector fixes

Author: OskarStark

.env

@@ -65,5 +65,9 @@ RUN_EXPENSIVE_EXAMPLES=false
 # For using Gemini
 GEMINI_API_KEY=
 
+# For using Albert API (French Sovereign AI)
+ALBERT_API_KEY=
+ALBERT_API_URL=
+
 # For MariaDB store. Server defined in compose.yaml
 MARIADB_URI=pdo-mysql://[email protected]:3309/my_database

README.md

@@ -69,6 +69,7 @@ $embeddings = new Embeddings();
   * [DeepSeek's R1](https://www.deepseek.com/) with [OpenRouter](https://www.openrouter.com/) as Platform
   * [Amazon's Nova](https://nova.amazon.com) with [AWS](https://aws.amazon.com/bedrock/) as Platform
   * [Mistral's Mistral](https://www.mistral.ai/) with [Mistral](https://www.mistral.ai/) as Platform
+  * [Albert API](https://github.com/etalab-ia/albert-api) models with [Albert](https://github.com/etalab-ia/albert-api) as Platform (French government's sovereign AI gateway)
 * Embeddings Models
   * [OpenAI's Text Embeddings](https://platform.openai.com/docs/guides/embeddings/embedding-models) with [OpenAI](https://platform.openai.com/docs/overview) and [Azure](https://learn.microsoft.com/azure/ai-services/openai/concepts/models) as Platform
   * [Voyage's Embeddings](https://docs.voyageai.com/docs/embeddings) with [Voyage](https://www.voyageai.com/) as Platform
@@ -166,6 +167,7 @@ $response = $chain->call($messages, [
 1. [Google's Gemini with Google](examples/google/chat.php)
 1. [Google's Gemini with OpenRouter](examples/openrouter/chat-gemini.php)
 1. [Mistral's Mistral with Mistral](examples/mistral/chat-mistral.php)
+1. [Albert API (French Sovereign AI)](examples/albert/chat.php)
 
 ### Tools
 

examples/albert/chat.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpLlm\LlmChain\Chain\Chain;
+use PhpLlm\LlmChain\Platform\Bridge\Albert\PlatformFactory;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\GPT;
+use PhpLlm\LlmChain\Platform\Message\Message;
+use PhpLlm\LlmChain\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/../vendor/autoload.php';
+
+if (empty($_ENV['ALBERT_API_KEY'])) {
+    echo 'Please set the ALBERT_API_KEY environment variable.'.\PHP_EOL;
+    exit(1);
+}
+
+if (empty($_ENV['ALBERT_API_URL'])) {
+    echo 'Please set the ALBERT_API_URL environment variable (e.g., https://your-albert-instance.com/v1).'.\PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create(
+    apiKey: $_ENV['ALBERT_API_KEY'],
+    baseUrl: $_ENV['ALBERT_API_URL'],
+);
+
+$model = new GPT('gpt-4o');
+$chain = new Chain($platform, $model);
+
+$documentContext = <<<'CONTEXT'
+    Document: AI Strategy of France
+
+    France has launched a comprehensive national AI strategy with the following key objectives:
+    1. Strengthening the AI ecosystem and attracting talent
+    2. Developing sovereign AI capabilities
+    3. Ensuring ethical and responsible AI development
+    4. Supporting AI adoption in public services
+    5. Investing €1.5 billion in AI research and development
+
+    The Albert project is part of this strategy, providing a sovereign AI solution for French public administration.
+    CONTEXT;
+
+$messages = new MessageBag(
+    Message::forSystem(
+        'You are an AI assistant with access to documents about French AI initiatives. '.
+        'Use the provided context to answer questions accurately.'
+    ),
+    Message::ofUser($documentContext),
+    Message::ofUser('What are the main objectives of France\'s AI strategy?'),
+);
+
+$response = $chain->call($messages);
+
+echo $response->getContent().\PHP_EOL;

src/Platform/Bridge/Albert/EmbeddingsModelClient.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Platform\Bridge\Albert;
+
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\Embeddings;
+use PhpLlm\LlmChain\Platform\Exception\InvalidArgumentException;
+use PhpLlm\LlmChain\Platform\Model;
+use PhpLlm\LlmChain\Platform\ModelClientInterface;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+final readonly class EmbeddingsModelClient implements ModelClientInterface
+{
+    public function __construct(
+        private HttpClientInterface $httpClient,
+        #[\SensitiveParameter] private string $apiKey,
+        private string $baseUrl,
+    ) {
+        if ('' === $apiKey) {
+            throw new InvalidArgumentException('The API key must not be empty.');
+        }
+        if ('' === $baseUrl) {
+            throw new InvalidArgumentException('The base URL must not be empty.');
+        }
+    }
+
+    public function supports(Model $model): bool
+    {
+        return $model instanceof Embeddings;
+    }
+
+    public function request(Model $model, array|string $payload, array $options = []): ResponseInterface
+    {
+        return $this->httpClient->request('POST', \sprintf('%s/embeddings', $this->baseUrl), [
+            'auth_bearer' => $this->apiKey,
+            'json' => \is_array($payload) ? array_merge($payload, $options) : $payload,
+        ]);
+    }
+}

src/Platform/Bridge/Albert/GPTModelClient.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Platform\Bridge\Albert;
+
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\GPT;
+use PhpLlm\LlmChain\Platform\Exception\InvalidArgumentException;
+use PhpLlm\LlmChain\Platform\Model;
+use PhpLlm\LlmChain\Platform\ModelClientInterface;
+use Symfony\Component\HttpClient\EventSourceHttpClient;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+final readonly class GPTModelClient implements ModelClientInterface
+{
+    private EventSourceHttpClient $httpClient;
+
+    public function __construct(
+        HttpClientInterface $httpClient,
+        #[\SensitiveParameter] private string $apiKey,
+        private string $baseUrl,
+    ) {
+        $this->httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
+
+        if ('' === $apiKey) {
+            throw new InvalidArgumentException('The API key must not be empty.');
+        }
+        if ('' === $baseUrl) {
+            throw new InvalidArgumentException('The base URL must not be empty.');
+        }
+    }
+
+    public function supports(Model $model): bool
+    {
+        return $model instanceof GPT;
+    }
+
+    public function request(Model $model, array|string $payload, array $options = []): ResponseInterface
+    {
+        return $this->httpClient->request('POST', \sprintf('%s/chat/completions', $this->baseUrl), [
+            'auth_bearer' => $this->apiKey,
+            'json' => \is_array($payload) ? array_merge($payload, $options) : $payload,
+        ]);
+    }
+}

src/Platform/Bridge/Albert/PlatformFactory.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Platform\Bridge\Albert;
+
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\Embeddings\ResponseConverter as EmbeddingsResponseConverter;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\GPT\ResponseConverter as GPTResponseConverter;
+use PhpLlm\LlmChain\Platform\Contract;
+use PhpLlm\LlmChain\Platform\Exception\InvalidArgumentException;
+use PhpLlm\LlmChain\Platform\Platform;
+use Symfony\Component\HttpClient\EventSourceHttpClient;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+final class PlatformFactory
+{
+    public static function create(
+        #[\SensitiveParameter] string $apiKey,
+        string $baseUrl,
+        ?HttpClientInterface $httpClient = null,
+    ): Platform {
+        if (!str_starts_with($baseUrl, 'https://')) {
+            throw new InvalidArgumentException('The Albert URL must start with "https://".');
+        }
+
+        if (str_ends_with($baseUrl, '/')) {
+            throw new InvalidArgumentException('The Albert URL must not end with a trailing slash.');
+        }
+
+        if (!preg_match('/\/v\d+$/', $baseUrl)) {
+            throw new InvalidArgumentException('The Albert URL must include an API version (e.g., /v1, /v2).');
+        }
+
+        $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
+
+        $gptClient = new GPTModelClient($httpClient, $apiKey, $baseUrl);
+        $embeddingsClient = new EmbeddingsModelClient($httpClient, $apiKey, $baseUrl);
+
+        return new Platform(
+            [
+                $gptClient,
+                $embeddingsClient,
+            ],
+            [
+                new GPTResponseConverter(),
+                new EmbeddingsResponseConverter(),
+            ],
+            Contract::create(),
+        );
+    }
+}