[Agent] Add Model Router system for intelligent model selection

examples/router/01-vision-simple.php

@@ -0,0 +1,63 @@
+<?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\Agent\InputProcessor\ModelRouterInputProcessor;
+use Symfony\AI\Agent\Router\Result\RoutingResult;
+use Symfony\AI\Agent\Router\SimpleRouter;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+// Create platform
+$platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
+
+// Create simple vision router: if message contains image → use gpt-4-vision
+$visionRouter = new SimpleRouter(
+    fn ($input, $ctx) =>
+        $input->getMessageBag()->containsImage()
+            ? new RoutingResult('gpt-4o', reason: 'Image detected')
+            : null
+);
+
+// Create agent with router
+$agent = new Agent(
+    platform: $platform,
+    model: 'gpt-4o-mini', // Default model
+    inputProcessors: [
+        new ModelRouterInputProcessor($visionRouter),
+    ],
+);
+
+echo "Example 1: Simple Vision Routing\n";
+echo "=================================\n\n";
+
+// Test 1: Text only - should use default model (gpt-4o-mini)
+echo "Test 1: Text only message\n";
+$result = $agent->call(new MessageBag(
+    Message::ofUser('What is PHP?')
+));
+echo 'Response: '.$result->asText()."\n\n";
+
+// Test 2: With image - should automatically route to gpt-4o
+echo "Test 2: Message with image\n";
+$imagePath = realpath(__DIR__.'/../../fixtures/assets/image-sample.png');
+if (!file_exists($imagePath)) {
+    echo "Image file not found: {$imagePath}\n";
+    exit(1);
+}
+
+$result = $agent->call(new MessageBag(
+    Message::ofUser('What is in this image?')->withImage($imagePath)
+));
+echo 'Response: '.$result->asText()."\n";

examples/router/02-vision-with-fallback.php

@@ -0,0 +1,62 @@
+<?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\Agent\InputProcessor\ModelRouterInputProcessor;
+use Symfony\AI\Agent\Router\Result\RoutingResult;
+use Symfony\AI\Agent\Router\SimpleRouter;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+// Create platform
+$platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
+
+// Router that uses vision model for images, default for text
+$router = new SimpleRouter(
+    fn ($input, $ctx) => $input->getMessageBag()->containsImage()
+        ? new RoutingResult('gpt-4o', reason: 'Vision model for images')
+        : new RoutingResult($ctx->getDefaultModel(), reason: 'Default model for text')
+);
+
+// Create agent with router
+$agent = new Agent(
+    platform: $platform,
+    model: 'gpt-4o-mini', // Default model
+    inputProcessors: [
+        new ModelRouterInputProcessor($router),
+    ],
+);
+
+echo "Example 2: Vision with Fallback\n";
+echo "================================\n\n";
+
+// Test 1: Text query
+echo "Test 1: Text query → gpt-4o-mini (default)\n";
+$result = $agent->call(new MessageBag(
+    Message::ofUser('Explain quantum computing in simple terms')
+));
+echo 'Response: '.$result->asText()."\n\n";
+
+// Test 2: Image query
+echo "Test 2: Image query → gpt-4o (vision)\n";
+$imagePath = realpath(__DIR__.'/../../fixtures/assets/image-sample.png');
+if (!file_exists($imagePath)) {
+    echo "Image file not found: {$imagePath}\n";
+    exit(1);
+}
+
+$result = $agent->call(new MessageBag(
+    Message::ofUser('Describe this image')->withImage($imagePath)
+));
+echo 'Response: '.$result->asText()."\n";

examples/router/03-multi-provider.php

@@ -0,0 +1,82 @@
+<?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\Agent\InputProcessor\ModelRouterInputProcessor;
+use Symfony\AI\Agent\Router\ChainRouter;
+use Symfony\AI\Agent\Router\Result\RoutingResult;
+use Symfony\AI\Agent\Router\SimpleRouter;
+use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory as AnthropicFactory;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory as OpenAiFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+// For this example, we'll use OpenAI platform, but show routing to different models
+// In a real scenario, you might have multiple platform instances
+$platform = OpenAiFactory::create(env('OPENAI_API_KEY'), http_client());
+
+// Create chain router that tries multiple strategies
+$router = new ChainRouter([
+    // Strategy 1: Try gpt-4o for images
+    new SimpleRouter(
+        fn ($input) =>
+            $input->getMessageBag()->containsImage()
+                ? new RoutingResult('gpt-4o', reason: 'OpenAI GPT-4o for vision')
+                : null
+    ),
+
+    // Strategy 2: Fallback to gpt-4o-mini for simple text
+    new SimpleRouter(
+        fn ($input) =>
+            !$input->getMessageBag()->containsImage()
+                ? new RoutingResult('gpt-4o-mini', reason: 'OpenAI GPT-4o-mini for text')
+                : null
+    ),
+
+    // Strategy 3: Default fallback
+    new SimpleRouter(
+        fn ($input, $ctx) => new RoutingResult($ctx->getDefaultModel(), reason: 'Default')
+    ),
+]);
+
+// Create agent with chain router
+$agent = new Agent(
+    platform: $platform,
+    model: 'gpt-4o-mini', // Default model
+    inputProcessors: [
+        new ModelRouterInputProcessor($router),
+    ],
+);
+
+echo "Example 3: Multi-Provider Routing\n";
+echo "==================================\n\n";
+
+// Test 1: Simple text
+echo "Test 1: Simple text → gpt-4o-mini\n";
+$result = $agent->call(new MessageBag(
+    Message::ofUser('What is 2 + 2?')
+));
+echo 'Response: '.$result->asText()."\n\n";
+
+// Test 2: Image
+echo "Test 2: Image → gpt-4o\n";
+$imagePath = realpath(__DIR__.'/../../fixtures/assets/image-sample.png');
+if (!file_exists($imagePath)) {
+    echo "Image file not found: {$imagePath}\n";
+    exit(1);
+}
+
+$result = $agent->call(new MessageBag(
+    Message::ofUser('What is in this image?')->withImage($imagePath)
+));
+echo 'Response: '.$result->asText()."\n";

examples/router/04-content-detection.php

@@ -0,0 +1,89 @@
+<?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\Agent\InputProcessor\ModelRouterInputProcessor;
+use Symfony\AI\Agent\Router\Result\RoutingResult;
+use Symfony\AI\Agent\Router\SimpleRouter;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+// Create platform
+$platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
+
+// Router that handles multiple content types
+$router = new SimpleRouter(
+    fn ($input, $ctx) => match (true) {
+        $input->getMessageBag()->containsImage() => new RoutingResult(
+            'gpt-4o',
+            reason: 'Image detected - using vision model'
+        ),
+        $input->getMessageBag()->containsAudio() => new RoutingResult(
+            'whisper-1',
+            reason: 'Audio detected - using speech-to-text model'
+        ),
+        $input->getMessageBag()->containsPdf() => new RoutingResult(
+            'gpt-4o',
+            reason: 'PDF detected - using advanced model'
+        ),
+        default => new RoutingResult(
+            $ctx->getDefaultModel(),
+            reason: 'Text only - using default model'
+        ),
+    }
+);
+
+// Create agent with router
+$agent = new Agent(
+    platform: $platform,
+    model: 'gpt-4o-mini', // Default model
+    inputProcessors: [
+        new ModelRouterInputProcessor($router),
+    ],
+);
+
+echo "Example 4: Content Type Detection\n";
+echo "==================================\n\n";
+
+// Test 1: Plain text
+echo "Test 1: Plain text\n";
+$result = $agent->call(new MessageBag(
+    Message::ofUser('What is machine learning?')
+));
+echo 'Response: '.$result->asText()."\n\n";
+
+// Test 2: Image
+echo "Test 2: Image content\n";
+$imagePath = realpath(__DIR__.'/../../fixtures/assets/image-sample.png');
+if (!file_exists($imagePath)) {
+    echo "Image file not found: {$imagePath}\n";
+    exit(1);
+}
+
+$result = $agent->call(new MessageBag(
+    Message::ofUser('Analyze this image')->withImage($imagePath)
+));
+echo 'Response: '.$result->asText()."\n\n";
+
+// Test 3: PDF (if available)
+$pdfPath = realpath(__DIR__.'/../../fixtures/assets/pdf-sample.pdf');
+if (file_exists($pdfPath)) {
+    echo "Test 3: PDF content\n";
+    $result = $agent->call(new MessageBag(
+        Message::ofUser('Summarize this PDF')->withPdf($pdfPath)
+    ));
+    echo 'Response: '.$result->asText()."\n";
+} else {
+    echo "Test 3: PDF content - skipped (PDF file not found)\n";
+}

examples/router/05-cost-optimized.php

@@ -0,0 +1,98 @@
+<?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\Agent\InputProcessor\ModelRouterInputProcessor;
+use Symfony\AI\Agent\Router\Result\RoutingResult;
+use Symfony\AI\Agent\Router\SimpleRouter;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+// Helper function to estimate tokens
+function estimateTokens(MessageBag $messageBag): int
+{
+    $text = '';
+    foreach ($messageBag->getMessages() as $message) {
+        $content = $message->getContent();
+        if (\is_string($content)) {
+            $text .= $content;
+        }
+    }
+
+    // Rough estimate: 1 token ≈ 4 characters
+    return (int) (\strlen($text) / 4);
+}
+
+// Create platform
+$platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
+
+// Cost-optimized router: use cheaper models for simple queries
+$router = new SimpleRouter(
+    function ($input, $ctx) {
+        $tokenCount = estimateTokens($input->getMessageBag());
+
+        if ($tokenCount < 100) {
+            return new RoutingResult(
+                'gpt-4o-mini',
+                reason: "Low cost for short query ({$tokenCount} tokens)"
+            );
+        }
+
+        if ($tokenCount < 500) {
+            return new RoutingResult(
+                'gpt-4o-mini',
+                reason: "Balanced cost for medium query ({$tokenCount} tokens)"
+            );
+        }
+
+        return new RoutingResult(
+            'gpt-4o',
+            reason: "Full model for complex query ({$tokenCount} tokens)"
+        );
+    }
+);
+
+// Create agent with router
+$agent = new Agent(
+    platform: $platform,
+    model: 'gpt-4o', // Default model
+    inputProcessors: [
+        new ModelRouterInputProcessor($router),
+    ],
+);
+
+echo "Example 5: Cost-Optimized Routing\n";
+echo "==================================\n\n";
+
+// Test 1: Short query
+echo "Test 1: Short query (< 100 tokens)\n";
+$result = $agent->call(new MessageBag(
+    Message::ofUser('What is 2 + 2?')
+));
+echo 'Response: '.$result->asText()."\n\n";
+
+// Test 2: Medium query
+echo "Test 2: Medium query (100-500 tokens)\n";
+$result = $agent->call(new MessageBag(
+    Message::ofUser('Explain the concept of object-oriented programming and give me a few examples.')
+));
+echo 'Response: '.$result->asText()."\n\n";
+
+// Test 3: Long query
+echo "Test 3: Long query (> 500 tokens)\n";
+$longText = str_repeat('This is a longer text that requires more processing. ', 50);
+$result = $agent->call(new MessageBag(
+    Message::ofUser("Analyze this text and provide insights: {$longText}")
+));
+echo 'Response: '.$result->asText()."\n";