feature #640 [AI Bundle][Platform] Add ModelCatalog (OskarStark)

This PR was squashed before being merged into the main branch.

Discussion
----------

[AI Bundle][Platform] Add `ModelCatalog`

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Docs?         | yes
| Issues        | --
| License       | MIT

Recipe-PR:
* symfony/recipes#1452

# ModelCatalog Architecture Refactoring

### BC Breaks
* ⚠️ All model constants removed
* ⚠️ Child model class constructors were changed and now have an `$capabilities` parameter
* ⚠️ `PlatformFactory` constructor changed for all bridges to be able to receive a `ModelCatalogInterface`
* ⚠️ `PlatformInterface` now has an additional `getModelCatalog` method
* ⚠️ `PlatformInterface::__invoke` no receives an model as string (before `Model`)
* ⚠️ `Vectorizer::__construct` no receives an model as string (before `Model`)
* ⚠️ `Agent::__construct` no receives an model as string (before `Model`)

## Overview
This PR refactors how models are defined and managed in the Symfony AI Platform, moving from constants in Model classes to centralized ModelCatalogs.

## Before (Old Configuration)

### Defining Models
Models were defined as constants in Model classes:

```php
// src/platform/src/Bridge/OpenAi/Gpt.php
class Gpt extends Model
{
    public const GPT_4O = 'gpt-4o';
    public const GPT_4O_MINI = 'gpt-4o-mini';
    // ... more constants

    public function __construct(string $name = self::GPT_4O, array $options = [])
    {
        $capabilities = [
            Capability::INPUT_MESSAGES,
            Capability::OUTPUT_TEXT,
            // ... capabilities determined in constructor
        ];

        if (self::GPT_4O_AUDIO === $name) {
            $capabilities[] = Capability::INPUT_AUDIO;
        }
        // ... more logic

        parent::__construct($name, $capabilities, $options);
    }
}
```

### Using Models
```php
use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
use Symfony\AI\Platform\Bridge\Voyage\Voyage;

// Had to create Model objects
$model = new Gpt('gpt-4o-mini');
$result = $platform->invoke($model, $input);

// Or with constants
$embeddings = new Voyage(Voyage::V3);
$result = $platform->invoke($embeddings, $text);
```

### Adding Custom Models
There was no standardized way to add custom models. You had to:
- Either extend a Model class and override the constructor
- Or create a Model instance with hardcoded capabilities

## After (New Configuration)

### Defining Models
Models are now defined in centralized ModelCatalog classes:

```php
// src/platform/src/Bridge/OpenAi/ModelCatalog.php
final class ModelCatalog extends AbstractModelCatalog
{
    public function __construct(array $additionalModels = [])
    {
        $defaultModels = [
            'gpt-4o' => [
                'class' => Gpt::class,
                'capabilities' => [
                    Capability::INPUT_MESSAGES,
                    Capability::OUTPUT_TEXT,
                    Capability::OUTPUT_STREAMING,
                    Capability::TOOL_CALLING,
                    Capability::INPUT_IMAGE,
                    Capability::OUTPUT_STRUCTURED,
                ],
            ],
            'gpt-4o-mini' => [
                'class' => Gpt::class,
                'capabilities' => [
                    Capability::INPUT_MESSAGES,
                    Capability::OUTPUT_TEXT,
                    Capability::OUTPUT_STREAMING,
                    Capability::TOOL_CALLING,
                    Capability::INPUT_IMAGE,
                    Capability::OUTPUT_STRUCTURED,
                ],
            ],
            // ... more models
        ];

        $this->models = array_merge($defaultModels, $additionalModels);
    }
}
```

### Using Models
```php
// Just pass model name as string - much simpler!
$result = $platform->invoke('gpt-4o-mini', $input);

// Works with any platform
$result = $platform->invoke('voyage-3', $text);
```

### Adding Custom Models

#### Option 1: Via ModelCatalog Constructor
```php
use Symfony\AI\Platform\Bridge\OpenAi\ModelCatalog;
use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;

$customModels = [
    'custom-gpt-4' => [
        'class' => Gpt::class,
        'capabilities' => [
            Capability::INPUT_MESSAGES,
            Capability::OUTPUT_TEXT,
            Capability::OUTPUT_STREAMING,
            Capability::TOOL_CALLING,
            Capability::OUTPUT_STRUCTURED,
        ],
    ],
];

$modelCatalog = new ModelCatalog($customModels);
$platform = new Platform($modelClients, $resultConverters, $modelCatalog, $contract);

// Use the custom model
$result = $platform->invoke('custom-gpt-4', $input);
```

#### Option 2: Via Symfony Configuration (if using AI Bundle)
```yaml
# config/packages/ai.yaml
ai:
    platform:
        openai:
            models:
                custom-gpt-4:
                    class: OpenAi\Gpt
                    capabilities:
                        - input_messages
                        - output_text
                        - output_streaming
                        - tool_calling
                        - output_structured
```

## Benefits

1. **Cleaner API**: Use simple strings instead of Model objects
2. **Centralized Model Management**: All models defined in one place per platform
3. **Easier Custom Models**: Add custom models via constructor or configuration
4. **Better Testing**: Standardized ModelCatalogTestCase for all implementations
5. **No More Constants**: Model classes are simpler, no need for constants
6. **Flexible Capabilities**: Capabilities defined per model, not in constructor logic

## Migration Guide

### For Application Code
```diff
- $result = $platform->invoke(new Gpt(Gpt::GPT_4O), $input);
+ $result = $platform->invoke('gpt-4o', $input);
```

### For Custom Platforms
```php
// Before: Had to extend Model class or handle in constructor
class MyModel extends Model {
    public function __construct() {
        // Complex capability logic
    }
}

// After: Just add to ModelCatalog
$catalog = new ModelCatalog([
    'my-model' => [
        'class' => MyModel::class,
        'capabilities' => [...],
    ],
]);
```

## Special Cases

### HuggingFace
HuggingFace ModelCatalog accepts any model name since they support thousands of models:

```php
final class ModelCatalog extends DynamicModelCatalog
{
    // HuggingFace supports a wide range of models dynamically
    // Models are identified by repository/model format (e.g., "microsoft/DialoGPT-medium")
}
```

## Testing

All ModelCatalogs can now be tested using the base `ModelCatalogTestCase`:

```php
final class MyModelCatalogTest extends ModelCatalogTestCase
{
    protected function createCatalog(): ModelCatalogInterface
    {
        return new MyModelCatalog();
    }

    public static function modelsProvider(): iterable
    {
        yield 'model-name' => [
            'model-name',
            ModelClass::class,
            [Capability::INPUT_MESSAGES, Capability::OUTPUT_TEXT],
        ];
    }
}
```

Commits
-------

4f06377 [AI Bundle][Platform] Add `ModelCatalog`

Author: chr-hertel

demo/config/packages/ai.yaml

@@ -4,34 +4,27 @@ ai:
             api_key: '%env(OPENAI_API_KEY)%'
     agent:
         blog:
-            model:
-                class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
-                name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Gpt::GPT_4O_MINI
+            model: 'gpt-4o-mini'
             tools:
                 - 'Symfony\AI\Agent\Toolbox\Tool\SimilaritySearch'
                 - service: 'clock'
                   name: 'clock'
                   description: 'Provides the current date and time.'
                   method: 'now'
         stream:
-            model:
-                class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
-                name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Gpt::GPT_4O_MINI
+            model: 'gpt-4o-mini'
             prompt: |
                 You are an example chat application where messages from the LLM are streamed to the user using
                 Server-Sent Events via `symfony/ux-turbo` / Turbo Streams. This example does not use any custom
                 javascript and solely relies on the built-in `live` & `turbo_stream` Stimulus controllers.
                 Whatever the user asks, tell them about the application & used technologies.
             tools: false
         youtube:
-            model:
-                class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
-                name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Gpt::GPT_4O_MINI
+            model: 'gpt-4o-mini'
             tools: false
         wikipedia:
             model:
-                class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
-                name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Gpt::GPT_4O_MINI
+                name: 'gpt-4o-mini'
                 options:
                     temperature: 0.5
             prompt:
@@ -40,9 +33,7 @@ ai:
             tools:
                 - 'Symfony\AI\Agent\Toolbox\Tool\Wikipedia'
         audio:
-            model:
-                class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
-                name: 'gpt-4o-mini?temperature=1.0'
+            model: 'gpt-4o-mini?temperature=1.0'
             prompt: 'You are a friendly chatbot that likes to have a conversation with users and asks them some questions.'
             tools:
                 # Agent in agent 🤯
@@ -55,9 +46,7 @@ ai:
                 collection: 'symfony_blog'
     vectorizer:
         openai:
-            model:
-                class: 'Symfony\AI\Platform\Bridge\OpenAi\Embeddings'
-                name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Embeddings::TEXT_ADA_002
+            model: 'text-embedding-ada-002'
     indexer:
         blog:
             loader: 'Symfony\AI\Store\Document\Loader\RssFeedLoader'

examples/aimlapi/chat.php

@@ -9,21 +9,19 @@
  * file that was distributed with this source code.
  */
 
-use Symfony\AI\Platform\Bridge\AiMlApi\Completions;
 use Symfony\AI\Platform\Bridge\AiMlApi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('AIMLAPI_API_KEY'), http_client());
-$model = new Completions(Completions::GEMINI_2_0_FLASH);
 
 $messages = new MessageBag(
     Message::forSystem('You are a pirate and you write funny.'),
     Message::ofUser('What is the Symfony framework?'),
 );
-$result = $platform->invoke($model, $messages, [
+$result = $platform->invoke('gemini-2.0-flash', $messages, [
     'max_tokens' => 500, // specific options just for this call
 ]);
 

examples/aimlapi/image-input-binary.php

@@ -9,20 +9,14 @@
  * file that was distributed with this source code.
  */
 
-use Symfony\AI\Platform\Bridge\AiMlApi\Completions;
 use Symfony\AI\Platform\Bridge\AiMlApi\PlatformFactory;
-use Symfony\AI\Platform\Capability;
 use Symfony\AI\Platform\Message\Content\Image;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('AIMLAPI_API_KEY'), http_client());
-$model = new Completions(
-    name: Completions::GOOGLE_GEMMA_3_27B_IT,
-    capabilities: [...Completions::DEFAULT_CAPABILITIES, Capability::INPUT_IMAGE]
-);
 
 $messages = new MessageBag(
     Message::forSystem('You are an image analyzer bot that helps identify the content of images.'),
@@ -31,6 +25,6 @@
         Image::fromFile(dirname(__DIR__, 2).'/fixtures/image.jpg'),
     ),
 );
-$result = $platform->invoke($model, $messages);
+$result = $platform->invoke('google/gemma-3-27b-it', $messages);
 
 echo $result->getResult()->getContent().\PHP_EOL;

examples/aimlapi/toolcall.php

@@ -13,24 +13,18 @@
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
 use Symfony\AI\Agent\Toolbox\Tool\Wikipedia;
 use Symfony\AI\Agent\Toolbox\Toolbox;
-use Symfony\AI\Platform\Bridge\AiMlApi\Completions;
 use Symfony\AI\Platform\Bridge\AiMlApi\PlatformFactory;
-use Symfony\AI\Platform\Capability;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('AIMLAPI_API_KEY'), http_client());
-$model = new Completions(
-    name: Completions::GOOGLE_GEMINI_2_5_FLASH,
-    capabilities: [...Completions::DEFAULT_CAPABILITIES, Capability::TOOL_CALLING]
-);
 
 $wikipedia = new Wikipedia(http_client());
 $toolbox = new Toolbox([$wikipedia], logger: logger());
 $processor = new AgentProcessor($toolbox);
-$agent = new Agent($platform, $model, [$processor], [$processor], logger: logger());
+$agent = new Agent($platform, 'google/gemini-2.5-flash', [$processor], [$processor], logger: logger());
 
 $messages = new MessageBag(Message::ofUser('Who is the current chancellor of Germany?'));
 $result = $agent->call($messages);

examples/aimlapi/vectorizing.php

@@ -9,18 +9,14 @@
  * file that was distributed with this source code.
  */
 
-use Symfony\AI\Platform\Bridge\AiMlApi\Embeddings;
 use Symfony\AI\Platform\Bridge\AiMlApi\PlatformFactory;
 use Symfony\AI\Store\Document\Vectorizer;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('AIMLAPI_API_KEY'), http_client());
-$embeddings = new Embeddings(
-    name: Embeddings::TEXT_EMBEDDING_3_SMALL
-);
 
-$vectorizer = new Vectorizer($platform, $embeddings);
+$vectorizer = new Vectorizer($platform, 'text-embedding-3-small');
 
 $string = 'Hello World';
 $vector = $vectorizer->vectorize($string);

examples/albert/chat.php

@@ -10,16 +10,13 @@
  */
 
 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__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('ALBERT_API_KEY'), env('ALBERT_API_URL'), http_client());
 
-$model = new Gpt('gpt-4o');
-
 $documentContext = <<<'CONTEXT'
     Document: AI Strategy of France
 
@@ -42,6 +39,6 @@
     Message::ofUser('What are the main objectives of France\'s AI strategy?'),
 );
 
-$result = $platform->invoke($model, $messages);
+$result = $platform->invoke('llama-3.3-70b-instruct', $messages);
 
 echo $result->getResult()->getContent().\PHP_EOL;

examples/anthropic/chat.php

@@ -9,20 +9,18 @@
  * file that was distributed with this source code.
  */
 
-use Symfony\AI\Platform\Bridge\Anthropic\Claude;
 use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('ANTHROPIC_API_KEY'), httpClient: http_client());
-$model = new Claude(Claude::SONNET_37);
 
 $messages = new MessageBag(
     Message::forSystem('You are a pirate and you write funny.'),
     Message::ofUser('What is the Symfony framework?'),
 );
-$result = $platform->invoke($model, $messages);
+$result = $platform->invoke('claude-3-5-sonnet-20241022', $messages);
 
 echo $result->getResult()->getContent().\PHP_EOL;

examples/anthropic/image-input-binary.php

@@ -9,7 +9,6 @@
  * file that was distributed with this source code.
  */
 
-use Symfony\AI\Platform\Bridge\Anthropic\Claude;
 use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory;
 use Symfony\AI\Platform\Message\Content\Image;
 use Symfony\AI\Platform\Message\Message;
@@ -18,7 +17,6 @@
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('ANTHROPIC_API_KEY'), httpClient: http_client());
-$model = new Claude(Claude::SONNET_37);
 
 $messages = new MessageBag(
     Message::forSystem('You are an image analyzer bot that helps identify the content of images.'),
@@ -27,6 +25,6 @@
         'Describe this image.',
     ),
 );
-$result = $platform->invoke($model, $messages);
+$result = $platform->invoke('claude-3-5-sonnet-20241022', $messages);
 
 echo $result->getResult()->getContent().\PHP_EOL;

examples/anthropic/image-input-url.php

@@ -9,7 +9,6 @@
  * file that was distributed with this source code.
  */
 
-use Symfony\AI\Platform\Bridge\Anthropic\Claude;
 use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory;
 use Symfony\AI\Platform\Message\Content\ImageUrl;
 use Symfony\AI\Platform\Message\Message;
@@ -18,7 +17,6 @@
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('ANTHROPIC_API_KEY'), httpClient: http_client());
-$model = new Claude(Claude::SONNET_37);
 
 $messages = new MessageBag(
     Message::forSystem('You are an image analyzer bot that helps identify the content of images.'),
@@ -27,6 +25,6 @@
         'Describe this image.',
     ),
 );
-$result = $platform->invoke($model, $messages);
+$result = $platform->invoke('claude-3-5-sonnet-20241022', $messages);
 
 echo $result->getResult()->getContent().\PHP_EOL;

examples/anthropic/pdf-input-binary.php

@@ -9,7 +9,6 @@
  * file that was distributed with this source code.
  */
 
-use Symfony\AI\Platform\Bridge\Anthropic\Claude;
 use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory;
 use Symfony\AI\Platform\Message\Content\Document;
 use Symfony\AI\Platform\Message\Message;
@@ -18,14 +17,13 @@
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('ANTHROPIC_API_KEY'), httpClient: http_client());
-$model = new Claude(Claude::SONNET_37);
 
 $messages = new MessageBag(
     Message::ofUser(
         Document::fromFile(dirname(__DIR__, 2).'/fixtures/document.pdf'),
         'What is this document about?',
     ),
 );
-$result = $platform->invoke($model, $messages);
+$result = $platform->invoke('claude-3-5-sonnet-20241022', $messages);
 
 echo $result->getResult()->getContent().\PHP_EOL;