[Platform] Add FailoverPlatform

docs/components/platform.rst

@@ -461,6 +461,70 @@ Thanks to Symfony's Cache component, platform calls can be cached to reduce call
 
     echo $secondResult->getContent().\PHP_EOL;
 
+High Availability
+-----------------
+
+As most platform exposes a REST API, errors can occurs during generation phase due to network issues, timeout and more.
+
+To prevent exceptions at the application level and allows to keep a smooth experience for end users,
+the :class:`Symfony\\AI\\Platform\\Bridge\\Failover\\FailoverPlatform` can be used to automatically call a backup platform::
+
+    use Symfony\AI\Platform\Bridge\Failover\FailoverPlatform;
+    use Symfony\AI\Platform\Bridge\Ollama\PlatformFactory as OllamaPlatformFactory;
+    use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory as OpenAiPlatformFactory;
+    use Symfony\AI\Platform\Message\Message;
+    use Symfony\AI\Platform\Message\MessageBag;
+    use Symfony\Component\RateLimiter\RateLimiterFactory;
+    use Symfony\Component\RateLimiter\Storage\InMemoryStorage;
+
+    $rateLimiter = new RateLimiterFactory([
+        'policy' => 'sliding_window',
+        'id' => 'failover',
+        'interval' => '3 seconds',
+        'limit' => 1,
+    ], new InMemoryStorage());
+
+    // # Ollama will fail as 'gpt-4o' is not available in the catalog
+    $platform = new FailoverPlatform([
+        OllamaPlatformFactory::create(env('OLLAMA_HOST_URL'), http_client()),
+        OpenAiPlatformFactory::create(env('OPENAI_API_KEY'), http_client()),
+    ], $rateLimiter);
+
+    $result = $platform->invoke('gpt-4o', new MessageBag(
+        Message::forSystem('You are a helpful assistant.'),
+        Message::ofUser('Tina has one brother and one sister. How many sisters do Tina\'s siblings have?'),
+    ));
+
+    echo $result->asText().\PHP_EOL;
+
+This platform can also be configured when using the bundle::
+
+    # config/packages/ai.yaml
+    ai:
+        platform:
+            openai:
+                # ...
+            ollama:
+                # ...
+            failover:
+                ollama_to_openai:
+                    platforms:
+                        - 'ai.platform.ollama'
+                        - 'ai.platform.openai'
+                    rate_limiter: 'limiter.failover_platform'
+
+    # config/packages/rate_limiter.yaml
+    framework:
+        rate_limiter:
+            failover_platform:
+                policy: 'sliding_window'
+                limit: 100
+                interval: '60 minutes'
+
+.. note::
+
+    Platforms are executed in the order they're injected into :class:`Symfony\\AI\\Platform\\Bridge\\Failover\\FailoverPlatform`.
+
 Testing Tools
 -------------
 

examples/composer.json

@@ -48,6 +48,7 @@
         "symfony/ai-docker-model-runner-platform": "@dev",
         "symfony/ai-elasticsearch-store": "@dev",
         "symfony/ai-eleven-labs-platform": "@dev",
+        "symfony/ai-failover-platform": "@dev",
         "symfony/ai-gemini-platform": "@dev",
         "symfony/ai-generic-platform": "@dev",
         "symfony/ai-session-message-store": "@dev",

examples/misc/failover-platform.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\AI\Platform\Bridge\Failover\FailoverPlatform;
+use Symfony\AI\Platform\Bridge\Ollama\PlatformFactory as OllamaPlatformFactory;
+use Symfony\AI\Platform\Bridge\OpenAi\Gpt\ResultConverter;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory as OpenAiPlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\Component\RateLimiter\RateLimiterFactory;
+use Symfony\Component\RateLimiter\Storage\InMemoryStorage;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+$rateLimiter = new RateLimiterFactory([
+    'policy' => 'sliding_window',
+    'id' => 'failover',
+    'interval' => '3 seconds',
+    'limit' => 1,
+], new InMemoryStorage());
+
+// # Ollama will fail as 'gpt-4o' is not available in the catalog
+$platform = new FailoverPlatform([
+    OllamaPlatformFactory::create(env('OLLAMA_HOST_URL'), http_client()),
+    OpenAiPlatformFactory::create(env('OPENAI_API_KEY'), http_client()),
+], $rateLimiter);
+
+$result = $platform->invoke('gpt-4o', new MessageBag(
+    Message::forSystem('You are a helpful assistant.'),
+    Message::ofUser('Tina has one brother and one sister. How many sisters do Tina\'s siblings have?'),
+));
+
+assert($result->getResultConverter() instanceof ResultConverter);
+
+echo $result->asText().\PHP_EOL;

splitsh.json

@@ -43,6 +43,7 @@
         "ai-deep-seek-platform": "src/platform/src/Bridge/DeepSeek",
         "ai-docker-model-runner-platform": "src/platform/src/Bridge/DockerModelRunner",
         "ai-eleven-labs-platform": "src/platform/src/Bridge/ElevenLabs",
+        "ai-failover-platform": "src/platform/src/Bridge/Failover",
         "ai-gemini-platform": "src/platform/src/Bridge/Gemini",
         "ai-generic-platform": "src/platform/src/Bridge/Generic",
         "ai-hugging-face-platform": "src/platform/src/Bridge/HuggingFace",

src/ai-bundle/composer.json

@@ -55,6 +55,7 @@
         "symfony/ai-doctrine-message-store": "@dev",
         "symfony/ai-eleven-labs-platform": "@dev",
         "symfony/ai-elasticsearch-store": "@dev",
+        "symfony/ai-failover-platform": "@dev",
         "symfony/ai-gemini-platform": "@dev",
         "symfony/ai-generic-platform": "@dev",
         "symfony/ai-session-message-store": "@dev",

src/ai-bundle/config/options.php

@@ -114,6 +114,17 @@
                             ->end()
                         ->end()
                     ->end()
+                    ->arrayNode('failover')
+                        ->useAttributeAsKey('name')
+                        ->arrayPrototype()
+                            ->children()
+                                ->arrayNode('platforms')
+                                    ->scalarPrototype()->end()
+                                ->end()
+                                ->stringNode('rate_limiter')->cannotBeEmpty()->end()
+                            ->end()
+                        ->end()
+                    ->end()
                     ->arrayNode('gemini')
                         ->children()
                             ->stringNode('api_key')->isRequired()->end()

src/ai-bundle/src/AiBundle.php

@@ -13,6 +13,7 @@
 
 use Google\Auth\ApplicationDefaultCredentials;
 use Google\Auth\FetchAuthTokenInterface;
+use Psr\Log\LoggerInterface;
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\AgentInterface;
 use Symfony\AI\Agent\Attribute\AsInputProcessor;
@@ -60,6 +61,8 @@
 use Symfony\AI\Platform\Bridge\DockerModelRunner\PlatformFactory as DockerModelRunnerPlatformFactory;
 use Symfony\AI\Platform\Bridge\ElevenLabs\ElevenLabsApiCatalog;
 use Symfony\AI\Platform\Bridge\ElevenLabs\PlatformFactory as ElevenLabsPlatformFactory;
+use Symfony\AI\Platform\Bridge\Failover\FailoverPlatform;
+use Symfony\AI\Platform\Bridge\Failover\FailoverPlatformFactory;
 use Symfony\AI\Platform\Bridge\Gemini\PlatformFactory as GeminiPlatformFactory;
 use Symfony\AI\Platform\Bridge\Generic\PlatformFactory as GenericPlatformFactory;
 use Symfony\AI\Platform\Bridge\HuggingFace\PlatformFactory as HuggingFacePlatformFactory;
@@ -511,6 +514,34 @@ private function processPlatformConfig(string $type, array $platform, ContainerB
             return;
         }
 
+        if ('failover' === $type) {
+            if (!ContainerBuilder::willBeAvailable('symfony/ai-failover-platform', FailoverPlatformFactory::class, ['symfony/ai-bundle'])) {
+                throw new RuntimeException('Failover platform configuration requires "symfony/ai-failover-platform" package. Try running "composer require symfony/ai-failover-platform".');
+            }
+
+            foreach ($platform as $name => $config) {
+                $definition = (new Definition(FailoverPlatform::class))
+                    ->setFactory(FailoverPlatformFactory::class.'::create')
+                    ->setLazy(true)
+                    ->setArguments([
+                        array_map(
+                            static fn (string $wrappedPlatform): Reference => new Reference($wrappedPlatform),
+                            $config['platforms'],
+                        ),
+                        new Reference($config['rate_limiter']),
+                        new Reference(ClockInterface::class),
+                        new Reference(LoggerInterface::class),
+                    ])
+                    ->addTag('proxy', ['interface' => PlatformInterface::class])
+                    ->addTag('ai.platform', ['name' => $type]);
+
+                $container->setDefinition('ai.platform.'.$type.'.'.$name, $definition);
+                $container->registerAliasForArgument('ai.platform.'.$type.'.'.$name, PlatformInterface::class, $name);
+            }
+
+            return;
+        }
+
         if ('gemini' === $type) {
             if (!ContainerBuilder::willBeAvailable('symfony/ai-gemini-platform', GeminiPlatformFactory::class, ['symfony/ai-bundle'])) {
                 throw new RuntimeException('Gemini platform configuration requires "symfony/ai-gemini-platform" package. Try running "composer require symfony/ai-gemini-platform".');

src/ai-bundle/tests/DependencyInjection/AiBundleTest.php

@@ -18,6 +18,8 @@
 use PHPUnit\Framework\Attributes\TestWith;
 use PHPUnit\Framework\TestCase;
 use Probots\Pinecone\Client as PineconeClient;
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
 use Symfony\AI\Agent\AgentInterface;
 use Symfony\AI\Agent\Memory\MemoryInputProcessor;
 use Symfony\AI\Agent\Memory\StaticMemoryProvider;
@@ -31,6 +33,8 @@
 use Symfony\AI\Platform\Bridge\ElevenLabs\ElevenLabsApiCatalog;
 use Symfony\AI\Platform\Bridge\ElevenLabs\ModelCatalog as ElevenLabsModelCatalog;
 use Symfony\AI\Platform\Bridge\ElevenLabs\PlatformFactory as ElevenLabsPlatformFactory;
+use Symfony\AI\Platform\Bridge\Failover\FailoverPlatform;
+use Symfony\AI\Platform\Bridge\Failover\FailoverPlatformFactory;
 use Symfony\AI\Platform\Bridge\Ollama\OllamaApiCatalog;
 use Symfony\AI\Platform\CachedPlatform;
 use Symfony\AI\Platform\Capability;
@@ -84,6 +88,8 @@
 use Symfony\Component\DependencyInjection\Reference;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 use Symfony\Component\HttpClient\HttpClient;
+use Symfony\Component\RateLimiter\RateLimiterFactory;
+use Symfony\Component\RateLimiter\Storage\InMemoryStorage;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 
 class AiBundleTest extends TestCase
@@ -4019,6 +4025,62 @@ public function testElevenLabsPlatformWithApiCatalogCanBeRegistered()
         $this->assertSame([['interface' => ModelCatalogInterface::class]], $modelCatalogDefinition->getTag('proxy'));
     }
 
+    public function testFailoverPlatformCanBeCreated()
+    {
+        $container = $this->buildContainer([
+            'ai' => [
+                'platform' => [
+                    'ollama' => [
+                        'host_url' => 'http://127.0.0.1:11434',
+                    ],
+                    'openai' => [
+                        'api_key' => 'sk-openai_key_full',
+                    ],
+                    'failover' => [
+                        'main' => [
+                            'platforms' => [
+                                'ai.platform.ollama',
+                                'ai.platform.openai',
+                            ],
+                            'rate_limiter' => 'limiter.failover_platform',
+                        ],
+                    ],
+                ],
+            ],
+        ]);
+
+        $this->assertTrue($container->hasDefinition('ai.platform.failover.main'));
+
+        $definition = $container->getDefinition('ai.platform.failover.main');
+
+        $this->assertSame([
+            FailoverPlatformFactory::class,
+            'create',
+        ], $definition->getFactory());
+        $this->assertTrue($definition->isLazy());
+        $this->assertSame(FailoverPlatform::class, $definition->getClass());
+
+        $this->assertCount(4, $definition->getArguments());
+        $this->assertCount(2, $definition->getArgument(0));
+        $this->assertEquals([
+            new Reference('ai.platform.ollama'),
+            new Reference('ai.platform.openai'),
+        ], $definition->getArgument(0));
+        $this->assertInstanceOf(Reference::class, $definition->getArgument(1));
+        $this->assertSame('limiter.failover_platform', (string) $definition->getArgument(1));
+        $this->assertInstanceOf(Reference::class, $definition->getArgument(2));
+        $this->assertSame(ClockInterface::class, (string) $definition->getArgument(2));
+        $this->assertInstanceOf(Reference::class, $definition->getArgument(3));
+        $this->assertSame(LoggerInterface::class, (string) $definition->getArgument(3));
+
+        $this->assertTrue($definition->hasTag('proxy'));
+        $this->assertSame([['interface' => PlatformInterface::class]], $definition->getTag('proxy'));
+        $this->assertTrue($definition->hasTag('ai.platform'));
+        $this->assertSame([['name' => 'failover']], $definition->getTag('ai.platform'));
+
+        $this->assertTrue($container->hasAlias('Symfony\AI\Platform\PlatformInterface $main'));
+    }
+
     public function testOpenAiPlatformWithDefaultRegion()
     {
         $container = $this->buildContainer([
@@ -7013,6 +7075,16 @@ private function buildContainer(array $configuration): ContainerBuilder
         $container->setParameter('kernel.environment', 'dev');
         $container->setParameter('kernel.build_dir', 'public');
         $container->setDefinition(ClockInterface::class, new Definition(MonotonicClock::class));
+        $container->setDefinition(LoggerInterface::class, new Definition(NullLogger::class));
+        $container->setDefinition('limiter.failover_platform', new Definition(RateLimiterFactory::class, [
+            [
+                'policy' => 'sliding_window',
+                'id' => 'test',
+                'interval' => '60 seconds',
+                'limit' => 1,
+            ],
+            new Definition(InMemoryStorage::class),
+        ]));
 
         $extension = (new AiBundle())->getContainerExtension();
         $extension->load($configuration, $container);
@@ -7068,6 +7140,15 @@ private function getFullConfig(): array
                         'host' => 'https://api.elevenlabs.io/v1',
                         'api_key' => 'elevenlabs_key_full',
                     ],
+                    'failover' => [
+                        'main' => [
+                            'platforms' => [
+                                'ai.platform.ollama',
+                                'ai.platform.openai',
+                            ],
+                            'rate_limiter' => 'limiter.failover_platform',
+                        ],
+                    ],
                     'gemini' => [
                         'api_key' => 'gemini_key_full',
                     ],

src/platform/composer.json

@@ -64,6 +64,7 @@
         "phpstan/phpstan": "^2.1.17",
         "phpstan/phpstan-strict-rules": "^2.0",
         "phpunit/phpunit": "^11.5.46",
+        "symfony/ai-agent": "@dev",
         "symfony/cache": "^7.3|^8.0",
         "symfony/console": "^7.3|^8.0",
         "symfony/dotenv": "^7.3|^8.0",

src/platform/src/Bridge/Failover/.gitattributes

@@ -0,0 +1,3 @@
+/Tests export-ignore
+/phpunit.xml.dist export-ignore
+/.git* export-ignore

src/platform/src/Bridge/Failover/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,8 @@
+Please do not submit any Pull Requests here. They will be closed.
+---
+
+Please submit your PR here instead:
+https://github.com/symfony/ai
+
+This repository is what we call a "subtree split": a read-only subset of that main repository.
+We're looking forward to your PR there!

src/platform/src/Bridge/Failover/.github/workflows/close-pull-request.yml

@@ -0,0 +1,20 @@
+name: Close Pull Request
+
+on:
+  pull_request_target:
+    types: [opened]
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: superbrothers/close-pull-request@v3
+      with:
+        comment: |
+          Thanks for your Pull Request! We love contributions.
+
+          However, you should instead open your PR on the main repository:
+          https://github.com/symfony/ai
+
+          This repository is what we call a "subtree split": a read-only subset of that main repository.
+          We're looking forward to your PR there!

src/platform/src/Bridge/Failover/.gitignore

@@ -0,0 +1,4 @@
+vendor/
+composer.lock
+phpunit.xml
+.phpunit.result.cache

src/platform/src/Bridge/Failover/CHANGELOG.md

@@ -0,0 +1,7 @@
+CHANGELOG
+=========
+
+0.1
+---
+
+ * Add the bridge