feature #595 [AI Bundle] Simplify memory configuration structure (OskarStark)

OskarStark · OskarStark · commit 5e312e7c22c5 · 2025-09-16T10:38:37.000+02:00
This PR was squashed before being merged into the main branch. Discussion ---------- [AI Bundle] Simplify memory configuration structure | Q | A | ------------- | --- | Bug fix? | no | New feature? | yes | Docs? | yes | Issues | Fix #591 | License | MIT Remove guessing logic for memory keys and introduce explicit syntax: ```yaml memory: 'text' # always creates static memory processor ``` ```yaml memory: service: 'service_name' # uses service reference ``` This makes the configuration more predictable and eliminates the need to check if a string refers to an existing service. Commits ------- 9530c67 [AI Bundle] Simplify memory configuration structure
diff --git a/src/ai-bundle/config/options.php b/src/ai-bundle/config/options.php
@@ -138,13 +138,27 @@
                             ->end()
                         ->end()
                         ->booleanNode('structured_output')->defaultTrue()->end()
-                        ->scalarNode('memory')
-                            ->info('Plain string or service name of the memory provider implementing MemoryProviderInterface')
+                        ->variableNode('memory')
+                            ->info('Memory configuration: string for static memory, or array with "service" key for service reference')
                             ->defaultNull()
                             ->validate()
-                                ->ifTrue(function ($v) { return \is_string($v) && '' === $v; })
+                                ->ifTrue(function ($v) {
+                                    return \is_string($v) && '' === $v;
+                                })
                                 ->thenInvalid('Memory cannot be empty.')
                             ->end()
+                            ->validate()
+                                ->ifTrue(function ($v) {
+                                    return \is_array($v) && !isset($v['service']);
+                                })
+                                ->thenInvalid('Memory array configuration must contain a "service" key.')
+                            ->end()
+                            ->validate()
+                                ->ifTrue(function ($v) {
+                                    return \is_array($v) && isset($v['service']) && '' === $v['service'];
+                                })
+                                ->thenInvalid('Memory service cannot be empty.')
+                            ->end()
                         ->end()
                         ->arrayNode('prompt')
                             ->info('The system prompt configuration')
diff --git a/src/ai-bundle/doc/index.rst b/src/ai-bundle/doc/index.rst
@@ -71,7 +71,7 @@ Configuration
                 model:
                     class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
                     name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Gpt::GPT_4O_MINI
-                memory: 'You have access to conversation history and user preferences' # Optional: static memory or service reference
+                memory: 'You have access to conversation history and user preferences' # Optional: static memory content
                 prompt: # The system prompt configuration
                     text: 'You are a helpful assistant that can answer questions.' # The prompt text
                     include_tools: true # Include tool definitions at the end of the system prompt
@@ -208,7 +208,8 @@ This static memory content is consistently available to the agent across all con
 
 **Dynamic Memory (Advanced)**
 
-For more sophisticated scenarios, you can reference an existing service that implements dynamic memory:
+For more sophisticated scenarios, you can reference an existing service that implements dynamic memory.
+Use the array syntax with a ``service`` key to explicitly reference a service:
 
 .. code-block:: yaml
 
@@ -218,7 +219,8 @@ For more sophisticated scenarios, you can reference an existing service that imp
                 model:
                     class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
                     name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Gpt::GPT_4O_MINI
-                memory: 'my_memory_service'  # References an existing service
+                memory:
+                    service: 'my_memory_service'  # Explicitly references an existing service
                 prompt:
                     text: 'You are a helpful assistant.'
 
@@ -269,17 +271,17 @@ When using a service reference, the memory service must implement the ``Symfony\
 
 **How Memory Works**
 
-The system automatically detects whether to use static or dynamic memory:
+The system uses explicit configuration to determine memory behavior:
 
 **Static Memory Processing:**
-1. When you provide a string that doesn't match any service name
+1. When you provide a string value (e.g., ``memory: 'some text'``)
 2. The system creates a ``StaticMemoryProvider`` automatically
 3. Content is formatted as "## Static Memory" with the provided text
 4. This memory is consistently available across all conversations
 
 **Dynamic Memory Processing:**
-1. When the string matches an existing service in the container
-2. The ``MemoryInputProcessor`` uses that service directly
+1. When you provide an array with a service key (e.g., ``memory: {service: 'my_service'}``)
+2. The ``MemoryInputProcessor`` uses the specified service directly
 3. The service's ``loadMemory()`` method is called before processing user input
 4. Dynamic memory content is injected based on the current context
 
diff --git a/src/ai-bundle/src/AiBundle.php b/src/ai-bundle/src/AiBundle.php
@@ -620,12 +620,11 @@ private function processAgentConfig(string $name, array $config, ContainerBuilde
         if (isset($config['memory'])) {
             $memoryValue = $config['memory'];
 
-            // Check if the value refers to an existing service
-            if ($container->hasDefinition($memoryValue) || $container->hasAlias($memoryValue)) {
-                // Use existing service as memory provider
-                $memoryProviderReference = new Reference($memoryValue);
+            if (\is_array($memoryValue) && isset($memoryValue['service'])) {
+                // Array configuration with service key - use the service directly
+                $memoryProviderReference = new Reference($memoryValue['service']);
             } else {
-                // Create StaticMemoryProvider with the string as static content
+                // String configuration - always create StaticMemoryProvider
                 $staticMemoryProviderDefinition = (new Definition(StaticMemoryProvider::class))
                     ->setArguments([$memoryValue]);
 
diff --git a/src/ai-bundle/tests/DependencyInjection/AiBundleTest.php b/src/ai-bundle/tests/DependencyInjection/AiBundleTest.php
@@ -1098,6 +1098,75 @@ public function testEmptyStringMemoryConfigurationThrowsException()
         ]);
     }
 
+    #[TestDox('Memory array configuration without service key throws validation exception')]
+    public function testMemoryArrayConfigurationWithoutServiceKeyThrowsException()
+    {
+        $this->expectException(InvalidConfigurationException::class);
+        $this->expectExceptionMessage('Memory array configuration must contain a "service" key.');
+
+        $this->buildContainer([
+            'ai' => [
+                'agent' => [
+                    'test_agent' => [
+                        'model' => ['class' => Gpt::class],
+                        'memory' => ['invalid' => 'value'],
+                        'prompt' => [
+                            'text' => 'Test prompt',
+                        ],
+                    ],
+                ],
+            ],
+        ]);
+    }
+
+    #[TestDox('Memory array configuration with empty service throws validation exception')]
+    public function testMemoryArrayConfigurationWithEmptyServiceThrowsException()
+    {
+        $this->expectException(InvalidConfigurationException::class);
+        $this->expectExceptionMessage('Memory service cannot be empty.');
+
+        $this->buildContainer([
+            'ai' => [
+                'agent' => [
+                    'test_agent' => [
+                        'model' => ['class' => Gpt::class],
+                        'memory' => ['service' => ''],
+                        'prompt' => [
+                            'text' => 'Test prompt',
+                        ],
+                    ],
+                ],
+            ],
+        ]);
+    }
+
+    #[TestDox('Memory service configuration works correctly')]
+    public function testMemoryServiceConfigurationWorksCorrectly()
+    {
+        $container = $this->buildContainer([
+            'ai' => [
+                'agent' => [
+                    'test_agent' => [
+                        'model' => ['class' => Gpt::class],
+                        'memory' => ['service' => 'my_custom_memory_service'],
+                        'prompt' => [
+                            'text' => 'Test prompt',
+                        ],
+                    ],
+                ],
+            ],
+        ]);
+
+        // Should use the service directly, not create a StaticMemoryProvider
+        $this->assertTrue($container->hasDefinition('ai.agent.test_agent.memory_input_processor'));
+        $this->assertFalse($container->hasDefinition('ai.agent.test_agent.static_memory_provider'));
+
+        $memoryProcessor = $container->getDefinition('ai.agent.test_agent.memory_input_processor');
+        $arguments = $memoryProcessor->getArguments();
+        $this->assertInstanceOf(Reference::class, $arguments[0]);
+        $this->assertSame('my_custom_memory_service', (string) $arguments[0]);
+    }
+
     #[TestDox('Memory configuration preserves correct processor priority ordering')]
     public function testMemoryProcessorPriorityOrdering()
     {
@@ -1182,7 +1251,7 @@ public function testMemoryWithExistingServiceUsesServiceReference()
                 'agent' => [
                     'test_agent' => [
                         'model' => ['class' => Gpt::class],
-                        'memory' => 'existing_memory_service', // This service exists
+                        'memory' => ['service' => 'existing_memory_service'], // New array syntax for service
                         'prompt' => [
                             'text' => 'You are a helpful assistant.',
                         ],
@@ -1254,7 +1323,7 @@ public function testMemoryWithServiceAliasUsesAlias()
                 'agent' => [
                     'test_agent' => [
                         'model' => ['class' => Gpt::class],
-                        'memory' => 'memory_alias', // This alias exists
+                        'memory' => ['service' => 'memory_alias'], // Use new array syntax for service alias
                         'prompt' => [
                             'text' => 'You are a helpful assistant.',
                         ],
@@ -1290,7 +1359,7 @@ public function testDifferentAgentsCanUseDifferentMemoryTypes()
                 'agent' => [
                     'agent_with_service' => [
                         'model' => ['class' => Gpt::class],
-                        'memory' => 'dynamic_memory_service', // Existing service
+                        'memory' => ['service' => 'dynamic_memory_service'], // Use new array syntax for service
                         'prompt' => [
                             'text' => 'Agent with service.',
                         ],
@@ -1312,6 +1381,7 @@ public function testDifferentAgentsCanUseDifferentMemoryTypes()
 
         $serviceMemoryProcessor = $container->getDefinition('ai.agent.agent_with_service.memory_input_processor');
         $serviceArgs = $serviceMemoryProcessor->getArguments();
+        $this->assertInstanceOf(Reference::class, $serviceArgs[0]);
         $this->assertSame('dynamic_memory_service', (string) $serviceArgs[0]);
 
         // Second agent uses StaticMemoryProvider
