feat: add Albert API support

OskarStark · OskarStark · commit 257541e9f9d2 · 2025-06-30T09:51:26.000+02:00
- Albert API is an OpenAI-compatible sovereign AI gateway by French government - Added examples for chat, RAG, streaming, and tool calling - Updated README to include Albert in supported platforms - Added Albert configuration to .env file Closes #346
diff --git a/.env b/.env
@@ -65,5 +65,10 @@ RUN_EXPENSIVE_EXAMPLES=false
 # For using Gemini
 GOOGLE_API_KEY=
 
+# For using Albert API (French Sovereign AI)
+ALBERT_API_KEY=
+ALBERT_API_URL=
+ALBERT_MODEL=
+
 # For MariaDB store. Server defined in compose.yaml
 MARIADB_URI=pdo-mysql://root@127.0.0.1:3309/my_database
diff --git a/README.md b/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
+  * OpenAI-compatible models via [Albert API](https://github.com/etalab-ia/albert-api) (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
@@ -130,6 +131,7 @@ $response = $chain->call($messages, [
 
 #### Code Examples
 
+1. [Albert API (French Sovereign AI)](examples/albert/chat.php)
 1. [Anthropic's Claude](examples/anthropic/chat.php)
 1. [OpenAI's GPT with Azure](examples/azure/chat-gpt.php)
 1. [OpenAI's GPT](examples/openai/chat.php)
diff --git a/examples/albert/README.md b/examples/albert/README.md
@@ -0,0 +1,68 @@
+# Albert API Examples
+
+[Albert API](https://github.com/etalab-ia/albert-api) is an open-source generative AI API gateway developed by the French government. It provides a sovereign AI solution with OpenAI-compatible APIs, making it easy to integrate with LLM Chain.
+
+## Prerequisites
+
+1. Deploy Albert API following the [official deployment guide](https://github.com/etalab-ia/albert-api)
+2. Obtain an API key from your Albert instance
+3. Set the required environment variables:
+
+```bash
+export ALBERT_API_KEY="your-api-key"
+export ALBERT_API_URL="https://your-albert-instance.com"
+export ALBERT_MODEL="albert-7b-v2"  # or your configured model
+```
+
+## Examples
+
+### Basic Chat
+```bash
+php examples/albert/chat.php
+```
+Demonstrates basic conversation with Albert API.
+
+### RAG (Retrieval-Augmented Generation)
+```bash
+php examples/albert/rag.php
+```
+Shows how to use Albert's built-in RAG capabilities with document context.
+
+### Streaming
+```bash
+php examples/albert/stream.php
+```
+Demonstrates real-time streaming responses from Albert API.
+
+### Tool Calling
+```bash
+php examples/albert/toolcall.php
+```
+Shows how to use function/tool calling with Albert API.
+
+## Configuration
+
+Albert API is OpenAI-compatible, so it works seamlessly with LLM Chain's OpenAI bridge:
+
+```php
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\PlatformFactory;
+
+$platform = PlatformFactory::create(
+    apiKey: $albertApiKey,
+    baseUrl: rtrim($albertApiUrl, '/').'/v1/',
+);
+```
+
+## Features
+
+- **Sovereign AI**: Host your models on your own infrastructure
+- **OpenAI Compatible**: Works with existing OpenAI integrations
+- **Built-in RAG**: Native support for retrieval-augmented generation
+- **Multiple Backends**: Supports OpenAI, vLLM, and HuggingFace models
+- **Enterprise Ready**: Authentication, load balancing, and monitoring
+
+## Notes
+
+- The model name depends on your Albert deployment configuration
+- Albert supports various model backends (OpenAI, vLLM, HuggingFace TEI)
+- Check your Albert instance documentation for available models and features
diff --git a/examples/albert/chat.php b/examples/albert/chat.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpLlm\LlmChain\Chain\Chain;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\GPT;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\PlatformFactory;
+use PhpLlm\LlmChain\Platform\Message\Message;
+use PhpLlm\LlmChain\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/../vendor/autoload.php';
+
+// Albert API configuration
+$albertApiKey = $_ENV['ALBERT_API_KEY'] ?? null;
+$albertApiUrl = $_ENV['ALBERT_API_URL'] ?? null;
+
+if (empty($albertApiKey)) {
+    echo 'Please set the ALBERT_API_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+if (empty($albertApiUrl)) {
+    echo 'Please set the ALBERT_API_URL environment variable (e.g., https://your-albert-instance.com).'.PHP_EOL;
+    exit(1);
+}
+
+// Albert API is OpenAI-compatible, so we use the OpenAI platform factory
+// with a custom base URL pointing to your Albert instance
+$platform = PlatformFactory::create(
+    apiKey: $albertApiKey,
+    baseUrl: rtrim($albertApiUrl, '/').'/v1/', // Ensure proper URL format
+);
+
+// Use the model name provided by your Albert instance
+// This could be a custom model or one of the supported backends
+$model = new GPT($_ENV['ALBERT_MODEL'] ?? 'albert-7b-v2');
+
+$chain = new Chain($platform, $model);
+
+$messages = new MessageBag(
+    Message::forSystem('You are a helpful AI assistant powered by Albert API.'),
+    Message::ofUser('Hello! Can you tell me about the French government\'s AI initiatives?'),
+);
+
+$response = $chain->call($messages);
+
+echo 'Albert API Response:'.PHP_EOL;
+echo '==================='.PHP_EOL;
+echo $response->getContent().PHP_EOL;
diff --git a/examples/albert/rag.php b/examples/albert/rag.php
@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpLlm\LlmChain\Chain\Chain;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\GPT;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\PlatformFactory;
+use PhpLlm\LlmChain\Platform\Message\Message;
+use PhpLlm\LlmChain\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/../vendor/autoload.php';
+
+// Albert API configuration
+$albertApiKey = $_ENV['ALBERT_API_KEY'] ?? null;
+$albertApiUrl = $_ENV['ALBERT_API_URL'] ?? null;
+
+if (empty($albertApiKey)) {
+    echo 'Please set the ALBERT_API_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+if (empty($albertApiUrl)) {
+    echo 'Please set the ALBERT_API_URL environment variable (e.g., https://your-albert-instance.com).'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create(
+    apiKey: $albertApiKey,
+    baseUrl: rtrim($albertApiUrl, '/').'/v1/',
+);
+
+$model = new GPT($_ENV['ALBERT_MODEL'] ?? 'albert-7b-v2');
+$chain = new Chain($platform, $model);
+
+// Albert API supports RAG out of the box
+// You can pass document context as part of your messages
+$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 'Albert API RAG Response:'.PHP_EOL;
+echo '========================'.PHP_EOL;
+echo $response->getContent().PHP_EOL;
diff --git a/examples/albert/stream.php b/examples/albert/stream.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpLlm\LlmChain\Chain\Chain;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\GPT;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\PlatformFactory;
+use PhpLlm\LlmChain\Platform\Message\Message;
+use PhpLlm\LlmChain\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/../vendor/autoload.php';
+
+// Albert API configuration
+$albertApiKey = $_ENV['ALBERT_API_KEY'] ?? null;
+$albertApiUrl = $_ENV['ALBERT_API_URL'] ?? null;
+
+if (empty($albertApiKey)) {
+    echo 'Please set the ALBERT_API_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+if (empty($albertApiUrl)) {
+    echo 'Please set the ALBERT_API_URL environment variable (e.g., https://your-albert-instance.com).'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create(
+    apiKey: $albertApiKey,
+    baseUrl: rtrim($albertApiUrl, '/').'/v1/',
+);
+
+$model = new GPT($_ENV['ALBERT_MODEL'] ?? 'albert-7b-v2');
+$chain = new Chain($platform, $model);
+
+$messages = new MessageBag(
+    Message::forSystem('You are a helpful AI assistant powered by Albert API.'),
+    Message::ofUser('Write a short story about a robot discovering emotions.'),
+);
+
+// Enable streaming for real-time response
+$response = $chain->call($messages, ['stream' => true]);
+
+echo 'Albert API Streaming Response:'.PHP_EOL;
+echo '=============================='.PHP_EOL;
+
+// Stream the response token by token
+foreach ($response->getContent() as $token) {
+    echo $token;
+    flush(); // Ensure immediate output
+}
+
+echo PHP_EOL;
diff --git a/examples/albert/toolcall.php b/examples/albert/toolcall.php
@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpLlm\LlmChain\Chain\Chain;
+use PhpLlm\LlmChain\Chain\Toolbox\Attribute\AsTool;
+use PhpLlm\LlmChain\Chain\Toolbox\ChainProcessor;
+use PhpLlm\LlmChain\Chain\Toolbox\Toolbox;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\GPT;
+use PhpLlm\LlmChain\Platform\Bridge\OpenAI\PlatformFactory;
+use PhpLlm\LlmChain\Platform\Message\Message;
+use PhpLlm\LlmChain\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/../vendor/autoload.php';
+
+// Albert API configuration
+$albertApiKey = $_ENV['ALBERT_API_KEY'] ?? null;
+$albertApiUrl = $_ENV['ALBERT_API_URL'] ?? null;
+
+if (empty($albertApiKey)) {
+    echo 'Please set the ALBERT_API_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+if (empty($albertApiUrl)) {
+    echo 'Please set the ALBERT_API_URL environment variable (e.g., https://your-albert-instance.com).'.PHP_EOL;
+    exit(1);
+}
+
+// Custom tool for French administrative information
+#[AsTool('french_departments', 'Get information about French departments')]
+final class FrenchDepartments
+{
+    private array $departments = [
+        '75' => ['name' => 'Paris', 'region' => 'Île-de-France', 'prefecture' => 'Paris'],
+        '13' => ['name' => 'Bouches-du-Rhône', 'region' => 'Provence-Alpes-Côte d\'Azur', 'prefecture' => 'Marseille'],
+        '69' => ['name' => 'Rhône', 'region' => 'Auvergne-Rhône-Alpes', 'prefecture' => 'Lyon'],
+        '31' => ['name' => 'Haute-Garonne', 'region' => 'Occitanie', 'prefecture' => 'Toulouse'],
+        '44' => ['name' => 'Loire-Atlantique', 'region' => 'Pays de la Loire', 'prefecture' => 'Nantes'],
+    ];
+
+    /**
+     * Get information about a French department by its number.
+     *
+     * @param string $departmentNumber The department number (e.g., "75" for Paris)
+     */
+    public function __invoke(string $departmentNumber): array
+    {
+        if (!isset($this->departments[$departmentNumber])) {
+            return ['error' => "Department $departmentNumber not found in the database"];
+        }
+
+        return $this->departments[$departmentNumber];
+    }
+}
+
+// Initialize Albert API
+$platform = PlatformFactory::create(
+    apiKey: $albertApiKey,
+    baseUrl: rtrim($albertApiUrl, '/').'/v1/',
+);
+
+$model = new GPT($_ENV['ALBERT_MODEL'] ?? 'albert-7b-v2');
+
+// Set up toolbox with our custom tool
+$tool = new FrenchDepartments();
+$toolbox = Toolbox::create($tool);
+$processor = new ChainProcessor($toolbox);
+
+$chain = new Chain($platform, $model, [$processor], [$processor]);
+
+$messages = new MessageBag(
+    Message::forSystem('You are a helpful assistant for French administrative information.'),
+    Message::ofUser('What is the prefecture of department 69?'),
+);
+
+$response = $chain->call($messages);
+
+echo 'Albert API Tool Calling Response:'.PHP_EOL;
+echo '================================='.PHP_EOL;
+echo $response->getContent().PHP_EOL;
