feat: add Albert API support (symfony#366)

This PR adds support for [Albert
API](https://github.com/etalab-ia/albert-api), the French government's
sovereign AI gateway. Albert provides an OpenAI-compatible API interface
for various language models while ensuring data sovereignty and
compliance with French/EU regulations.

- 🇫🇷 **Sovereign AI**: Albert is hosted and operated by the French
government
- 🔧 **OpenAI-compatible**: Uses the same API structure as OpenAI
- 🔒 **Data Privacy**: Ensures data remains within French/EU jurisdiction
- 🎯 **Public Sector Focus**: Designed for use by French public
administration

- Created Albert-specific model clients (GPTModelClient and
EmbeddingsModelClient) with configurable base URL
- Added PlatformFactory for easy Albert API initialization
- Reuses OpenAI's response converters for compatibility
- Supports both chat completions and embeddings endpoints

```php
use PhpLlm\LlmChain\Platform\Bridge\Albert\PlatformFactory;
use PhpLlm\LlmChain\Platform\Bridge\OpenAI\GPT;

$platform = PlatformFactory::create(
    apiKey: $_ENV['ALBERT_API_KEY'],
    albertUrl: $_ENV['ALBERT_API_URL']
);

$model = new GPT('gpt-4o');
$chain = new Chain($platform, $model);
```

- Added unit tests for PlatformFactory
- Added example script demonstrating Albert API usage with RAG context
- All tests pass and code follows project standards

- Updated README to list Albert as a supported platform
- Added example file showing how to use Albert API
- Included context about French AI strategy in the example

This implementation allows French public sector organizations to
leverage LLM Chain while maintaining data sovereignty and regulatory
compliance.

Closes symfony#346

Author: OskarStark

examples/.env

@@ -68,6 +68,10 @@ 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
 

examples/albert/chat.php

@@ -0,0 +1,54 @@
+<?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.
+ */
+
+use Symfony\AI\Agent\Agent;
+use Symfony\AI\Platform\Bridge\Albert\PlatformFactory;
+use Symfony\AI\Platform\Bridge\OpenAI\GPT;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/../vendor/autoload.php';
+
+if (!isset($_SERVER['ALBERT_API_KEY'], $_SERVER['ALBERT_API_URL'])) {
+    echo 'Please set the ALBERT_API_KEY and ALBERT_API_URL environment variable (e.g., https://your-albert-instance.com/v1).'.\PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_SERVER['ALBERT_API_KEY'], $_SERVER['ALBERT_API_URL']);
+
+$model = new GPT('gpt-4o');
+$agent = new Agent($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 = $agent->call($messages);
+
+echo $response->getContent().\PHP_EOL;

src/platform/doc/index.rst

@@ -77,6 +77,7 @@ usually defined by the specific models and their documentation.
     * `DeepSeek's R1`_ with `OpenRouter`_ as Platform
     * `Amazon's Nova`_ with `AWS Bedrock`_ as Platform
     * `Mistral's Mistral`_ with `Mistral`_ as Platform
+    * `Albert API`_ models with `Albert`_ as Platform (French government's sovereign AI gateway)
 * **Embeddings Models**
     * `Google's Text Embeddings`_ with `Google`_
     * `OpenAI's Text Embeddings`_ with `OpenAI`_ and `Azure`_ as Platform
@@ -307,6 +308,8 @@ which can be useful to speed up the processing::
 .. _`DeepSeek's R1`: https://www.deepseek.com/
 .. _`Amazon's Nova`: https://nova.amazon.com
 .. _`Mistral's Mistral`: https://www.mistral.ai/
+.. _`Albert API`: https://github.com/etalab-ia/albert-api
+.. _`Albert`: https://alliance.numerique.gouv.fr/produit/albert/
 .. _`Mistral`: https://www.mistral.ai/
 .. _`Google's Text Embeddings`: https://ai.google.dev/gemini-api/docs/embeddings
 .. _`OpenAI's Text Embeddings`: https://platform.openai.com/docs/guides/embeddings/embedding-models

src/platform/phpstan.dist.neon

@@ -17,5 +17,5 @@ parameters:
             path: src/*
             reportUnmatched: false # only needed for older Symfony versions
         -
-            message: '#no value type specified in iterable type array#'
+            identifier: missingType.iterableValue
             path: tests/*

src/platform/src/Bridge/Albert/EmbeddingsModelClient.php

@@ -0,0 +1,47 @@
+<?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\Platform\Bridge\Albert;
+
+use Symfony\AI\Platform\Bridge\OpenAI\Embeddings;
+use Symfony\AI\Platform\Exception\InvalidArgumentException;
+use Symfony\AI\Platform\Model;
+use Symfony\AI\Platform\ModelClientInterface;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+/**
+ * @author Oskar Stark <[email protected]>
+ */
+final readonly class EmbeddingsModelClient implements ModelClientInterface
+{
+    public function __construct(
+        private HttpClientInterface $httpClient,
+        #[\SensitiveParameter] private string $apiKey,
+        private string $baseUrl,
+    ) {
+        '' !== $apiKey || throw new InvalidArgumentException('The API key must not be empty.');
+        '' !== $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/src/Bridge/Albert/GPTModelClient.php

@@ -0,0 +1,52 @@
+<?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\Platform\Bridge\Albert;
+
+use Symfony\AI\Platform\Bridge\OpenAI\GPT;
+use Symfony\AI\Platform\Exception\InvalidArgumentException;
+use Symfony\AI\Platform\Model;
+use Symfony\AI\Platform\ModelClientInterface;
+use Symfony\Component\HttpClient\EventSourceHttpClient;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+/**
+ * @author Oskar Stark <[email protected]>
+ */
+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);
+
+        '' !== $apiKey || throw new InvalidArgumentException('The API key must not be empty.');
+        '' !== $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/src/Bridge/Albert/PlatformFactory.php

@@ -0,0 +1,47 @@
+<?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\Platform\Bridge\Albert;
+
+use Symfony\AI\Platform\Bridge\OpenAI\Embeddings\ResponseConverter as EmbeddingsResponseConverter;
+use Symfony\AI\Platform\Bridge\OpenAI\GPT\ResponseConverter as GPTResponseConverter;
+use Symfony\AI\Platform\Contract;
+use Symfony\AI\Platform\Exception\InvalidArgumentException;
+use Symfony\AI\Platform\Platform;
+use Symfony\Component\HttpClient\EventSourceHttpClient;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+/**
+ * @author Oskar Stark <[email protected]>
+ */
+final class PlatformFactory
+{
+    public static function create(
+        #[\SensitiveParameter] string $apiKey,
+        string $baseUrl,
+        ?HttpClientInterface $httpClient = null,
+    ): Platform {
+        str_starts_with($baseUrl, 'https://') || throw new InvalidArgumentException('The Albert URL must start with "https://".');
+        !str_ends_with($baseUrl, '/') || throw new InvalidArgumentException('The Albert URL must not end with a trailing slash.');
+        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);
+
+        return new Platform(
+            [
+                new GPTModelClient($httpClient, $apiKey, $baseUrl),
+                new EmbeddingsModelClient($httpClient, $apiKey, $baseUrl),
+            ],
+            [new GPTResponseConverter(), new EmbeddingsResponseConverter()],
+            Contract::create(),
+        );
+    }
+}