Merge remote-tracking branch 'origin/main' into feature/meilisearch-configurable-semantic-ratio

Author: ahmed-bhs

.github/workflows/integration-tests.yaml

@@ -15,7 +15,7 @@ concurrency:
     cancel-in-progress: true
 
 env:
-    REQUIRED_PHP_EXTENSIONS: 'mongodb'
+    REQUIRED_PHP_EXTENSIONS: 'mongodb, redis'
 
 jobs:
     examples:

CLAUDE.md

@@ -30,7 +30,7 @@ Each component has its own test suite. Run tests for specific components:
 # Platform component
 cd src/platform && vendor/bin/phpunit
 
-# Agent component  
+# Agent component
 cd src/agent && vendor/bin/phpunit
 
 # AI Bundle
@@ -111,10 +111,10 @@ Each component uses:
 - Do not use void return type for testcase methods
 - Always run PHP-CS-Fixer to ensure proper code style
 - Always add a newline at the end of the file
-- Prefer self::assert* oder $this->assert* in tests
+- Prefer self::assert* over $this->assert* in tests
 - Never add Claude as co-author in the commits
 - Add @author tags to newly introduced classes by the user
 - Prefer classic if statements over short-circuit evaluation when possible
 - Define array shapes for parameters and return types
 - Use project specific exceptions instead of global exception classes like \RuntimeException, \InvalidArgumentException etc.
-- NEVER mention Claude as co-author in commits
+- NEVER mention Claude as co-author in commits

demo/config/packages/ai.yaml

@@ -70,6 +70,7 @@ ai:
             filters:
                 - 'app.filter.week_of_symfony'
             transformers:
+                - 'Symfony\AI\Store\Document\Transformer\TextSplitTransformer'
                 - 'Symfony\AI\Store\Document\Transformer\TextTrimTransformer'
             vectorizer: 'ai.vectorizer.openai'
             store: 'ai.store.chroma_db.symfonycon'
@@ -89,6 +90,7 @@ services:
         $store: '@ai.store.chroma_db.symfonycon'
 
     Symfony\AI\Store\Document\Loader\RssFeedLoader: ~
+    Symfony\AI\Store\Document\Transformer\TextSplitTransformer: ~
     Symfony\AI\Store\Document\Transformer\TextTrimTransformer: ~
 
     app.filter.week_of_symfony:

demo/src/Mcp/Tools/CurrentTimeTool.php

@@ -12,12 +12,18 @@
 namespace App\Mcp\Tools;
 
 use Mcp\Capability\Attribute\McpTool;
+use Psr\Log\LoggerInterface;
 
 /**
  * @author Tom Hart <tom.hart.221@gmail.com>
  */
 class CurrentTimeTool
 {
+    public function __construct(
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
     /**
      * Returns the current time in UTC.
      *
@@ -26,6 +32,8 @@ class CurrentTimeTool
     #[McpTool(name: 'current-time')]
     public function getCurrentTime(string $format = 'Y-m-d H:i:s'): string
     {
+        $this->logger->info('CurrentTimeTool called', ['format' => $format]);
+
         return (new \DateTime('now', new \DateTimeZone('UTC')))->format($format);
     }
 }

demo/templates/components/wikipedia.html.twig

@@ -9,14 +9,14 @@
     <div id="chat-body" class="card-body p-4 overflow-auto">
         {% for message in this.messages %}
             {% include '_message.html.twig' with { message, latest: loop.last } %}
-            {% if message.metadata.has('sources') %}
-                <div class="ms-5">
-                    <h6>Sources:</h6>
-                    <ol>
-                        {% for source in message.metadata.get('sources') %}
-                            <li><a class="text-black-50" href="{{ source.reference }}" target="_blank" rel="noopener">{{ source.name }}</a></li>
-                        {% endfor %}
-                    </ol>
+            {% if message.metadata.has('sources') and 0 != message.metadata.get('sources')|length %}
+                <div class="ms-5 ps-4" style="margin-top: -1.5em;">
+                    <span class="text-muted">Sources:</span>
+                    {% for source in message.metadata.get('sources') %}
+                        <a class="text-black-50" href="{{ source.reference }}" target="_blank" rel="noopener">
+                            <span class="badge text-bg-secondary">{{ source.name }}</span>
+                        </a>
+                    {% endfor %}
                 </div>
             {% endif %}
         {% else %}

docs/bundles/ai-bundle.rst

@@ -67,7 +67,6 @@ Advanced Example with Multiple Agents
         agent:
             rag:
                 platform: 'ai.platform.azure.gpt_deployment'
-                structured_output: false # Disables support for "output_structure" option, default is true
                 track_token_usage: true # Enable tracking of token usage for the agent, default is true
                 model: 'gpt-4o-mini'
                 memory: 'You have access to conversation history and user preferences' # Optional: static memory content
@@ -513,11 +512,6 @@ Configuration
                 # Fallback agent for unmatched requests (required)
                 fallback: 'general'
 
-.. important::
-
-    The orchestrator agent MUST have ``structured_output: true`` (the default) to work correctly.
-    The multi-agent system uses structured output to reliably parse agent selection decisions.
-
 Each multi-agent configuration automatically registers a service with the ID pattern ``ai.multi_agent.{name}``.
 
 For the example above, the service ``ai.multi_agent.support`` is registered and can be injected::
@@ -956,6 +950,48 @@ The profiler panel provides insights into the agent's execution:
 .. image:: profiler.png
    :alt: Profiler Panel
 
+Message stores
+--------------
+
+Message stores are critical to store messages sent to agents in the short / long term, they can be configured
+and reused in multiple chats, providing the capacity to agents to keep previous interactions.
+
+Configuring message stores
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Message stores are defined in the ``message_store`` section of your configuration:
+
+.. code-block:: yaml
+
+    ai:
+        # ...
+        message_store:
+            youtube:
+                cache:
+                    service: 'cache.app'
+                    key: 'youtube'
+
+Chats
+-----
+
+Chats are the entrypoint when it comes to sending messages to agents and retrieving content (mostly text)
+that contains the response from the agent.
+
+Each chat requires to define an agent and a message store.
+
+Configuring Chats
+~~~~~~~~~~~~~~~~~
+
+Chats are defined in the ``chat`` section of your configuration:
+
+.. code-block:: yaml
+
+    ai:
+        # ...
+        chat:
+            youtube:
+                agent: 'ai.agent.youtube'
+                message_store: 'ai.message_store.cache.youtube'
 
 .. _`Symfony AI Agent`: https://github.com/symfony/ai-agent
 .. _`Symfony AI Chat`: https://github.com/symfony/ai-chat

docs/bundles/mcp-bundle.rst

@@ -113,6 +113,33 @@ Dynamic resources with parameters:
 
 All capabilities are automatically discovered in the ``src/`` directory when the server starts.
 
+Attribute Placement Patterns
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The MCP SDK, and therefore the MCP Bundle, supports two patterns for placing attributes on your capabilities:
+
+**Invokable Pattern** - Attribute on a class with ``__invoke()`` method::
+
+    #[McpTool(name: 'my-tool')]
+    class MyTool
+    {
+        public function __invoke(string $param): string
+        {
+            // Implementation
+        }
+    }
+
+**Method-Based Pattern** - Multiple attributes on individual methods::
+
+    class MyTools
+    {
+        #[McpTool(name: 'tool-one')]
+        public function toolOne(): string { }
+
+        #[McpTool(name: 'tool-two')]
+        public function toolTwo(): string { }
+    }
+
 Transport Types
 ...............
 

docs/components/agent.rst

@@ -483,80 +483,6 @@ Code Examples
 * `RAG with MongoDB`_
 * `RAG with Pinecone`_
 
-Structured Output
------------------
-
-A typical use-case of LLMs is to classify and extract data from unstructured sources, which is supported by some models
-by features like Structured Output or providing a Response Format.
-
-PHP Classes as Output
-~~~~~~~~~~~~~~~~~~~~~
-
-Symfony AI supports that use-case by abstracting the hustle of defining and providing schemas to the LLM and converting
-the result back to PHP objects.
-
-To achieve this, a specific agent processor needs to be registered::
-
-    use Symfony\AI\Agent\Agent;
-    use Symfony\AI\Agent\StructuredOutput\AgentProcessor;
-    use Symfony\AI\Agent\StructuredOutput\ResponseFormatFactory;
-    use Symfony\AI\Fixtures\StructuredOutput\MathReasoning;
-    use Symfony\AI\Platform\Message\Message;
-    use Symfony\AI\Platform\Message\MessageBag;
-    use Symfony\Component\Serializer\Encoder\JsonEncoder;
-    use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
-    use Symfony\Component\Serializer\Serializer;
-
-    // Initialize Platform and LLM
-
-    $serializer = new Serializer([new ObjectNormalizer()], [new JsonEncoder()]);
-    $processor = new AgentProcessor(new ResponseFormatFactory(), $serializer);
-    $agent = new Agent($platform, $model, [$processor], [$processor]);
-
-    $messages = new MessageBag(
-        Message::forSystem('You are a helpful math tutor. Guide the user through the solution step by step.'),
-        Message::ofUser('how can I solve 8x + 7 = -23'),
-    );
-    $result = $agent->call($messages, ['output_structure' => MathReasoning::class]);
-
-    dump($result->getContent()); // returns an instance of `MathReasoning` class
-
-Array Structures as Output
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Also PHP array structures as response_format are supported, which also requires the agent processor mentioned above::
-
-    use Symfony\AI\Platform\Message\Message;
-    use Symfony\AI\Platform\Message\MessageBag;
-
-    // Initialize Platform, LLM and agent with processors and Clock tool
-
-    $messages = new MessageBag(Message::ofUser('What date and time is it?'));
-    $result = $agent->call($messages, ['response_format' => [
-        'type' => 'json_schema',
-        'json_schema' => [
-            'name' => 'clock',
-            'strict' => true,
-            'schema' => [
-                'type' => 'object',
-                'properties' => [
-                    'date' => ['type' => 'string', 'description' => 'The current date in the format YYYY-MM-DD.'],
-                    'time' => ['type' => 'string', 'description' => 'The current time in the format HH:MM:SS.'],
-                ],
-                'required' => ['date', 'time'],
-                'additionalProperties' => false,
-            ],
-        ],
-    ]]);
-
-    dump($result->getContent()); // returns an array
-
-Code Examples
-~~~~~~~~~~~~~
-
-* `Structured Output with PHP class`_
-* `Structured Output with array`_
-
 Input & Output Processing
 -------------------------
 
@@ -825,7 +751,5 @@ Code Examples
 .. _`Store Component`: https://github.com/symfony/ai-store
 .. _`RAG with MongoDB`: https://github.com/symfony/ai/blob/main/examples/rag/mongodb.php
 .. _`RAG with Pinecone`: https://github.com/symfony/ai/blob/main/examples/rag/pinecone.php
-.. _`Structured Output with PHP class`: https://github.com/symfony/ai/blob/main/examples/openai/structured-output-math.php
-.. _`Structured Output with array`: https://github.com/symfony/ai/blob/main/examples/openai/structured-output-clock.php
 .. _`Chat with static memory`: https://github.com/symfony/ai/blob/main/examples/memory/static.php
 .. _`Chat with embedding search memory`: https://github.com/symfony/ai/blob/main/examples/memory/mariadb.php

docs/components/chat.rst

@@ -31,6 +31,24 @@ with a ``Symfony\AI\Agent\AgentInterface`` and a ``Symfony\AI\Chat\MessageStoreI
 
     $chat->submit(Message::ofUser('Hello'));
 
+You can find more advanced usage in combination with an Agent using the store for long-term context:
+
+* `External services storage with Cache`_
+* `Current session context storage with HttpFoundation session`_
+* `Current process context storage with InMemory`_
+* `Long-term context with Meilisearch`_
+* `Long-term context with Pogocache`_
+* `Long-term context with Redis`_
+
+Supported Message stores
+------------------------
+
+* `Cache`_
+* `HttpFoundation session`_
+* `InMemory`_
+* `Meilisearch`_
+* `Pogocache`_
+* `Redis`_
 
 Implementing a Bridge
 ---------------------
@@ -105,3 +123,16 @@ store and ``bin/console ai:message-store:drop`` to clean up the message store:
 
     $ php bin/console ai:message-store:setup symfonycon
     $ php bin/console ai:message-store:drop symfonycon
+
+.. _`External services storage with Cache`: https://github.com/symfony/ai/blob/main/examples/chat/persistent-chat-cache.php
+.. _`Current session context storage with HttpFoundation session`: https://github.com/symfony/ai/blob/main/examples/chat/persistent-chat-session.php
+.. _`Current process context storage with InMemory`: https://github.com/symfony/ai/blob/main/examples/chat/persistent-chat.php
+.. _`Long-term context with Meilisearch`: https://github.com/symfony/ai/blob/main/examples/chat/persistent-chat-meilisearch.php
+.. _`Long-term context with Pogocache`: https://github.com/symfony/ai/blob/main/examples/chat/persistent-chat-pogocache.php
+.. _`Long-term context with Redis`: https://github.com/symfony/ai/blob/main/examples/chat/persistent-chat-redis.php
+.. _`Cache`: https://symfony.com/doc/current/components/cache.html
+.. _`InMemory`: https://www.php.net/manual/en/language.types.array.php
+.. _`HttpFoundation session`: https://developers.cloudflare.com/vectorize/
+.. _`Meilisearch`: https://www.meilisearch.com/
+.. _`Pogocache`: https://pogocache.com/
+.. _`Redis`: https://redis.io/