docs: split into components

chr-hertel · chr-hertel · commit 1e38dc58cb49 · 2025-06-21T13:29:18.000+02:00
diff --git a/README.md b/README.md
diff --git a/examples/README.md b/examples/README.md
@@ -20,7 +20,7 @@ composer install
 #### Configuration
 
 Depending on the examples you want to run, you may need to configure the needed API keys. Therefore, you need to create a
-`.env.local` file in the root of the examples directory. This file should contain the environment variables for the
+`.env.local` file in the root of the examples' directory. This file should contain the environment variables for the
 corresponding example you want to run.
 
 _Now you can run examples standalone or via the example runner._
diff --git a/src/agent/README.md b/src/agent/README.md
@@ -0,0 +1,20 @@
+# Symfony AI - Agent Component
+
+The Agent component provides a framework for building AI agents that, sits on top of the Platform and Store components,
+allowing you to create agents that can interact with users, perform tasks, and manage workflows.
+
+## Installation
+
+```bash
+composer require symfony/ai-agent
+```
+
+**This repository is a READ-ONLY sub-tree split**. See
+https://github.com/symfony/ai to create issues or submit pull requests.
+
+## Resources
+
+- [Documentation](doc/index.rst)
+- [Report issues](https://github.com/symfony/ai/issues) and
+  [send Pull Requests](https://github.com/symfony/ai/pulls)
+  in the [main Symfony AI repository](https://github.com/symfony/ai)
diff --git a/src/agent/doc/index.rst b/src/agent/doc/index.rst
@@ -0,0 +1,14 @@
+Symfony AI - Agent Component
+============================
+
+The Agent component provides a framework for building AI agents that, sits on top of the Platform and Store components,
+allowing you to create agents that can interact with users, perform tasks, and manage workflows.
+
+Installation
+------------
+
+Install the component using Composer:
+
+.. code-block:: terminal
+
+    $ composer require symfony/ai-agent
diff --git a/src/mcp-bundle/README.md b/src/mcp-bundle/README.md
@@ -59,5 +59,4 @@ mcp:
                 arguments: [] # Arguments to pass to the command
             sse:
                 url: 'http://localhost:8000/sse' # URL to SSE endpoint of MCP server
-
 ```
diff --git a/src/mcp-sdk/README.md b/src/mcp-sdk/README.md
@@ -17,10 +17,7 @@ https://github.com/symfony/ai to create issues or submit pull requests.
 
 ## Resources
 
--   [Documentation](doc/index.rst)
--   [Report issues](https://github.com/symfony/ai/issues) and
-    [send Pull Requests](https://github.com/symfony/ai/pulls)
-    in the [main Symfony AI repository](https://github.com/symfony/ai)
-
-[1]: https://symfony.com/backers
-[3]: https://symfony.com/sponsor
+- [Documentation](doc/index.rst)
+- [Report issues](https://github.com/symfony/ai/issues) and
+  [send Pull Requests](https://github.com/symfony/ai/pulls)
+  in the [main Symfony AI repository](https://github.com/symfony/ai)
diff --git a/src/mcp-sdk/doc/index.rst b/src/mcp-sdk/doc/index.rst
@@ -7,7 +7,7 @@ a PHP application and an LLM model.
 Installation
 ------------
 
-Install the bundle using Composer:
+Install the SDK using Composer:
 
 .. code-block:: terminal
 
diff --git a/src/platform/README.md b/src/platform/README.md
@@ -0,0 +1,19 @@
+# Symfony AI - Platform Component
+
+The Platform component provides an abstraction for interacting with different models, their providers and contracts.
+
+## Installation
+
+```bash
+composer require symfony/ai-platform
+```
+
+**This repository is a READ-ONLY sub-tree split**. See
+https://github.com/symfony/ai to create issues or submit pull requests.
+
+## Resources
+
+- [Documentation](doc/index.rst)
+- [Report issues](https://github.com/symfony/ai/issues) and
+  [send Pull Requests](https://github.com/symfony/ai/pulls)
+  in the [main Symfony AI repository](https://github.com/symfony/ai)
diff --git a/src/platform/doc/index.rst b/src/platform/doc/index.rst
@@ -0,0 +1,141 @@
+Symfony AI - Store Component
+============================
+
+The Platform component provides an abstraction for interacting with different models, their providers and contracts.
+
+Installation
+------------
+
+Install the component using Composer:
+
+.. code-block:: terminal
+
+    $ composer require symfony/ai-platform
+
+Purpose
+-------
+
+The Platform component provides a unified interface for working with various AI models, hosted and run by different
+providers. It allows developers to easily switch between different AI models and providers without changing their
+application code. This is particularly useful for applications that require flexibility in choosing AI models based on
+specific use cases or performance requirements.
+
+Usage
+-----
+
+The instantiation of the ``Symfony\AI\Platform\Platform`` class is usually delegated to a provider-specific factory,
+with a provider being OpenAI, Azure, Google, Replicate, and others.
+
+For example, to use the OpenAI provider, you would typically do something like this:
+
+.. code-block: php
+
+    use Symfony\AI\Platform\Bridge\OpenAI\Embeddings;
+    use Symfony\AI\Platform\Bridge\OpenAI\GPT;
+    use Symfony\AI\Platform\Bridge\OpenAI\PlatformFactory;
+
+    // Platform
+    $platform = PlatformFactory::create($_ENV['OPENAI_API_KEY']);
+
+    // Embeddings Model
+    $embeddings = new Embeddings();
+
+    // Language Model in version gpt-4o-mini
+    $gpt = new GPT(GPT::GPT_4O_MINI);
+
+And with a ``Symfony\AI\Platform\PlatformInterface`` instance, and a ``Symfony\AI\Platform\Model`` instance, you can now
+use the platform to interact with the AI model:
+
+.. code-block: php
+
+    // Generate a vector embedding for a text, returns a Symfony\AI\Platform\Response\VectorResponse
+    $response = $platform->request($embeddings, 'What is the capital of France?');
+
+    // Generate a text completion with GPT, returns a Symfony\AI\Platform\Response\TextResponse
+    $embeddingsResult = $platform->request($gpt, new MessageBag(Message::ofUser('What is the capital of France?'));
+
+Depending on the model and its capabilities, different types of inputs and outputs are supported, which results in a
+very flexible and powerful interface for working with AI models.
+
+Models
+------
+
+The component provides a model base class ``Symfony\AI\Platform\Model`` which is a combination of a model name, a set of
+capabilities, and additional options. Usually, bridges to specific providers extend this base class to provide a quick
+start for vendor-specific models and their capabilities, see ``Symfony\AI\Platform\Bridge\Anthropic\Claude`` or
+``Symfony\AI\Platform\Bridge\OpenAI\GPT``.
+
+**Capabilities** are a list of strings defined by ``Symfony\AI\Platform\Capability``, which can be used to check if a model
+supports a specific feature, like ``Capability::INPUT_AUDIO`` or ``Capability::OUTPUT_IMAGE``.
+
+**Options** are additional parameters that can be passed to the model, like ``temperature`` or ``max_tokens``, and are
+usually defined by the specific models and their documentation.
+
+Language Models and Messages
+----------------------------
+
+One central feature of the Platform component is the support for language models and easing the interaction with them.
+This is supported by providing an extensive set of data classes around the concept of messages and their content.
+
+Messages can be of different types, most importantly ``UserMessage``, ``SystemMessage``, or ``AssistantMessage``, can
+have different content types, like ``Text``, ``Image`` or ``Audio``, and can be grouped into a ``MessageBag``:
+
+.. code-block: php
+
+    use Symfony\AI\Platform\Message\Content\Image;
+    use Symfony\AI\Platform\Message\Message;
+    use Symfony\AI\Platform\Message\MessageBag;
+
+    // Create a message bag with a user message
+    $messageBag = new MessageBag(
+        Message::ofSystem('You are a helpful assistant.')
+        Message::ofUser('Please describe this picture?', Image::fromFile('/path/to/image.jpg')),
+    );
+
+Supported Models & Platforms
+----------------------------
+
+* **Language Models**
+    * `OpenAI's GPT`_ with `OpenAI`_ and `Azure`_ as Platform
+    * `Anthropic's Claude`_ with `Anthropic`_ and `AWS Bedrock`_ as Platform
+    * `Meta's Llama`_ with `Azure`_, `Ollama`_, `Replicate`_ and `AWS Bedrock`_ as Platform
+    * `Google's Gemini`_ with `Google`_ and `OpenRouter`_ as Platform
+    * `DeepSeek's R1`_ with `OpenRouter`_ as Platform
+    * `Amazon's Nova`_ with `AWS Bedrock`_ as Platform
+    * `Mistral's Mistral`_ with `Mistral`_ as Platform
+* **Embeddings Models**
+    * `OpenAI's Text Embeddings`_ with `OpenAI`_ and `Azure`_ as Platform
+    * `Voyage's Embeddings`_ with `Voyage`_ as Platform
+    * `Mistral Embed`_ with `Mistral`_ as Platform
+* **Other Models**
+    * `OpenAI's Dall·E`_ with `OpenAI`_ as Platform
+    * `OpenAI's Whisper`_ with `OpenAI`_ and `Azure`_ as Platform
+    * All models provided by `HuggingFace`_ can be listed with a command in the examples folder,
+      and also filtered, e.g. ``php examples/huggingface/_model-listing.php --provider=hf-inference --task=object-detection``
+
+See `GitHub`_ for planned support of other models and platforms.
+
+.. _`OpenAI's GPT`: https://platform.openai.com/docs/models/overview
+.. _`OpenAI`: https://platform.openai.com/docs/overview
+.. _`Azure`: https://learn.microsoft.com/azure/ai-services/openai/concepts/models
+.. _`Anthropic's Claude`: https://www.anthropic.com/claude
+.. _`Anthropic`: https://www.anthropic.com/
+.. _`AWS Bedrock`: https://aws.amazon.com/bedrock/
+.. _`Meta's Llama`: https://www.llama.com/
+.. _`Ollama`: https://ollama.com/
+.. _`Replicate`: https://replicate.com/
+.. _`Google's Gemini`: https://gemini.google.com/
+.. _`Google`: https://ai.google.dev/
+.. _`OpenRouter`: https://www.openrouter.com/
+.. _`DeepSeek's R1`: https://www.deepseek.com/
+.. _`Amazon's Nova`: https://nova.amazon.com
+.. _`Mistral's Mistral`: https://www.mistral.ai/
+.. _`Mistral`: https://www.mistral.ai/
+.. _`OpenAI's Text Embeddings`: https://platform.openai.com/docs/guides/embeddings/embedding-models
+.. _`Voyage's Embeddings`: https://docs.voyageai.com/docs/embeddings
+.. _`Voyage`: https://www.voyageai.com/
+.. _`Mistral Embed`: https://www.mistral.ai/
+.. _`OpenAI's Dall·E`: https://platform.openai.com/docs/guides/image-generation
+.. _`OpenAI's Whisper`: https://platform.openai.com/docs/guides/speech-to-text
+.. _`HuggingFace`: https://huggingface.co/
+.. _`GitHub`: https://github.com/symfony/ai/issues/16
diff --git a/src/store/README.md b/src/store/README.md
@@ -0,0 +1,19 @@
+# Symfony AI - Store Component
+
+The Store component provides a low-level abstraction for storing and retrieving documents in a vector store.
+
+## Installation
+
+```bash
+composer require symfony/ai-store
+```
+
+**This repository is a READ-ONLY sub-tree split**. See
+https://github.com/symfony/ai to create issues or submit pull requests.
+
+## Resources
+
+- [Documentation](doc/index.rst)
+- [Report issues](https://github.com/symfony/ai/issues) and
+  [send Pull Requests](https://github.com/symfony/ai/pulls)
+  in the [main Symfony AI repository](https://github.com/symfony/ai)
diff --git a/src/store/composer.json b/src/store/composer.json
@@ -1,7 +1,7 @@
 {
     "name": "symfony/ai-store",
     "type": "library",
-    "description": "PHP library for abstracting interaction with data stores in AI applications.",
+    "description": "Low-level abstraction for storing and retrieving documents in a vector store.",
     "keywords": [
         "ai",
         "mongodb",
diff --git a/src/store/doc/index.rst b/src/store/doc/index.rst
@@ -0,0 +1,94 @@
+Symfony AI - Store Component
+============================
+
+The Store component provides a low-level abstraction for storing and retrieving documents in a vector store.
+
+Installation
+------------
+
+Install the component using Composer:
+
+.. code-block:: terminal
+
+    composer require symfony/ai-store
+
+Purpose
+-------
+
+A typical use-case in agentic applications is a dynamic context-extension with similar and useful information, for so
+called **Retrieval Augmented Generation** (RAG). The Store component implements low-level interfaces, that can be
+implemented by different concrete and vendor-specific implementations, so called bridges.
+On top of those bridges, the Store component provides higher level features to populate and query those stores with and
+for documents.
+
+Embedder
+--------
+
+One higher level feature is the ``Symfony\AI\Store\Embedder``. The purpose of this service is to populate a store with documents.
+Therefore it accepts one or multiple ``Symfony\AI\Store\Document\TextDocument`` objects, converts them into embeddings and stores them in the
+used vector store.
+
+Simple usage example:
+
+.. code-block:: php
+
+    use Symfony\AI\Store\Embedder;
+    use Symfony\AI\Store\Document\TextDocument;
+
+    $embedder = new Embedder($storeBridge);
+    $document = new TextDocument('This is a sample document.');
+    $embedder->embed($document);
+
+You can find more advanced usage in combination with an Agent using the store for RAG in the examples folder:
+
+* `Similarity Search with MongoDB (RAG)`_
+* `Similarity Search with Pinecone (RAG)`_
+
+Supported Stores
+----------------
+
+* `Azure AI Search`_
+* `Chroma`_
+* `MongoDB Atlas`_
+* `Pinecone`_
+
+.. note::
+
+    See `GitHub`_ for planned stores.
+
+Implementing a Bridge
+---------------------
+
+The main extension points of the Store component are
+
+* ``Symfony\\AI\\Store\\StoreInterface`` - Takes care of adding documents to the store.
+* ``Symfony\\AI\\Store\\VectorStoreInterface`` - Takes care of querying the store for documents.
+
+This leads to a store implementing two methods:
+
+.. code-block:: php
+
+    use Symfony\AI\Store\StoreInterface;
+    use Symfony\AI\Store\VectorStoreInterface;
+
+    class MyStore implements StoreInterface, VectorStoreInterface
+    {
+        public function add(VectorDocument ...$documents): void
+        {
+            // Implementation to add a document to the store
+        }
+
+        public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+        {
+            // Implementation to query the store for documents
+            return [];
+        }
+    }
+
+.. _`Similarity Search with MongoDB (RAG)`: https://github.com/symfony/ai/blob/main/examples/store/mongodb-similarity-search.php
+.. _`Similarity Search with Pinecone (RAG)`: https://github.com/symfony/ai/blob/main/examples/store/pinecone-similarity-search.php
+.. _`Azure AI Search`: https://azure.microsoft.com/products/ai-services/ai-search
+.. _`Chroma`: https://www.trychroma.com/
+.. _`MongoDB Atlas`: https://www.mongodb.com/atlas
+.. _`Pinecone`: https://www.pinecone.io/
+.. _`GitHub`: https://github.com/symfony/ai/issues/16
