Merge pull request #19 from Guiziweb/docs/initial-documentation

docs: add README pitch + installation, usage, extending guides

Author: camilleislasse

README.md

@@ -8,122 +8,56 @@
     </a>
 </p>
 
-<h1 align="center">Plugin Skeleton</h1>
+<h1 align="center">Sylius Grid Assistant Plugin</h1>
 
-<p align="center">Skeleton for starting Sylius plugins.</p>
-
-## Documentation
-
-For a comprehensive guide on Sylius Plugins development please go to Sylius documentation,
-there you will find the <a href="https://docs.sylius.com/en/latest/plugin-development-guide/index.html">Plugin Development Guide</a>, that is full of examples.
-
-For more information about the **Test Application** included in the skeleton, please refer to the [Sylius documentation](https://docs.sylius.com/sylius-plugins/plugins-development-guide/testapplication).
-
-## Quickstart Installation
-
-Run `composer create-project sylius/plugin-skeleton ProjectName`.
-
-### Traditional
-
-1. From the plugin skeleton root directory, run the following commands:
-
-    ```bash
-    (cd vendor/sylius/test-application && yarn install)
-    (cd vendor/sylius/test-application && yarn build)
-    vendor/bin/console assets:install
-   
-    vendor/bin/console doctrine:database:create
-    vendor/bin/console doctrine:migrations:migrate -n
-    # Optionally load data fixtures
-    vendor/bin/console sylius:fixtures:load -n
-    ```
-
-To be able to set up a plugin's database, remember to configure your database credentials in `tests/TestApplication/.env` and `tests/TestApplication/.env.test`.
-
-2. Run your local server:
+<p align="center">
+    <a href="https://github.com/Guiziweb/GuiziwebSyliusGridAssistantPlugin/actions"><img src="https://img.shields.io/github/actions/workflow/status/Guiziweb/GuiziwebSyliusGridAssistantPlugin/build.yaml?branch=main" alt="Build status"></a>
+    <a href="https://packagist.org/packages/guiziweb/sylius-grid-assistant-plugin"><img src="https://img.shields.io/packagist/v/guiziweb/sylius-grid-assistant-plugin" alt="Latest version"></a>
+    <a href="https://packagist.org/packages/guiziweb/sylius-grid-assistant-plugin"><img src="https://img.shields.io/packagist/php-v/guiziweb/sylius-grid-assistant-plugin" alt="PHP version"></a>
+    <img src="https://img.shields.io/badge/phpunit-passing-success" alt="PHPUnit">
+    <img src="https://img.shields.io/badge/behat-passing-success" alt="Behat">
+    <img src="https://img.shields.io/badge/phpstan-level%20max-blue" alt="PHPStan max">
+    <img src="https://img.shields.io/badge/ecs-passing-success" alt="ECS">
+    <a href="https://packagist.org/packages/guiziweb/sylius-grid-assistant-plugin"><img src="https://img.shields.io/packagist/l/guiziweb/sylius-grid-assistant-plugin" alt="License"></a>
+</p>
 
-      ```bash
-      symfony server:ca:install
-      symfony server:start -d
-      ```
+> **Natural language → filtered grid.** AI-powered filtering for Sylius admin grids.
 
-3. Open your browser and navigate to `https://localhost:8000`.
+## How it works
 
-### Docker
+In an admin grid (orders, products, customers...), the assistant adds a search bar at the top. Type your query in plain language:
 
-1. Execute `make init` to initialize the container and install the dependencies.
+> *"orders over $100 from john.doe@gmail.com last month"*
 
-2. Execute `make database-init` to create the database and run migrations.
+The plugin sends the query to a Large Language Model (OpenAI, Gemini, Anthropic, Mistral...), gets back structured filters and sorting (JSON Schema strict), and redirects to the same grid with the filters applied - exactly as if you had clicked them manually.
 
-3. (Optional) Execute `make load-fixtures` to load the fixtures.
+![Demo](docs/demo.gif)
 
-4. Your app is available at `http://localhost`.
+## Requirements
 
-## Usage
+- PHP ^8.2
+- Sylius ^2.0
+- An AI provider account (OpenAI, Gemini, Anthropic, Mistral...) and its API key
 
-### Running plugin tests
+## Quick install
 
-  - PHPUnit
+This plugin ships a [Symfony Flex recipe](https://github.com/Guiziweb/SyliusRecipes). With the Guiziweb recipe endpoint configured in your project (see linked repo), the install boils down to:
 
-    ```bash
-    vendor/bin/phpunit
-    ```
+```bash
+composer require guiziweb/sylius-grid-assistant-plugin
+composer require symfony/ai-bundle symfony/ai-open-ai-platform  # or another bridge
+```
 
-  - Behat (non-JS scenarios)
+Then fill in your API key in `.env.local` and enable the grids you want. The Flex recipes (plugin + bridge) take care of the rest (bundle registration, config files, env var stub).
 
-    ```bash
-    vendor/bin/behat --strict --tags="~@javascript&&~@mink:chromedriver"
-    ```
+Full step-by-step guide (with and without Flex): [installation](docs/installation.md).
 
-  - Behat (JS scenarios)
- 
-    1. [Install Symfony CLI command](https://symfony.com/download).
- 
-    2. Start Headless Chrome:
-    
-      ```bash
-      google-chrome-stable --enable-automation --disable-background-networking --no-default-browser-check --no-first-run --disable-popup-blocking --disable-default-apps --allow-insecure-localhost --disable-translate --disable-extensions --no-sandbox --enable-features=Metal --headless --remote-debugging-port=9222 --window-size=2880,1800 --proxy-server='direct://' --proxy-bypass-list='*' http://127.0.0.1
-      ```
-    
-    3. Install SSL certificates (only once needed) and run test application's webserver on `127.0.0.1:8080`:
-    
-      ```bash
-      symfony server:ca:install
-      APP_ENV=test symfony server:start --port=8080 --daemon
-      ```
-    
-    4. Run Behat:
-    
-      ```bash
-      vendor/bin/behat --strict --tags="@javascript,@mink:chromedriver"
-      ```
-    
-  - Static Analysis
-      
-    - PHPStan
-    
-      ```bash
-      vendor/bin/phpstan analyse -c phpstan.neon -l max src/  
-      ```
+## Documentation
 
-  - Coding Standard
-  
-    ```bash
-    vendor/bin/ecs check
-    ```
+- [Installation](docs/installation.md) - full setup steps
+- [Usage](docs/usage.md) - admin guide with query examples
+- [Extending](docs/extending.md) - add custom filter types
 
-### Opening Sylius with your plugin
+## License
 
-- Using `test` environment:
-
-    ```bash
-    APP_ENV=test vendor/bin/console vendor/bin/console sylius:fixtures:load -n
-    APP_ENV=test symfony server:start -d
-    ```
-    
-- Using `dev` environment:
-
-    ```bash
-    vendor/bin/console vendor/bin/console sylius:fixtures:load -n
-    symfony server:start -d
-    ```
+MIT - see [LICENSE](LICENSE).

docs/configuration.md

@@ -0,0 +1,137 @@
+# Extending
+
+The plugin's 8 built-in schema builders cover 10 native Sylius filter types out of the box: `boolean`, `date`, `entity`, `enum`, `exists`, `money`, `numeric_range`, `select`, `string`, `ux_autocomplete`, `ux_translatable_autocomplete`. If your project defines **a custom filter type** outside that list, you need to teach the assistant about it.
+
+## When you need to extend
+
+Only when you have a **custom Sylius filter type**. If you're using stock Sylius filters with custom options/configurations, the existing builders already handle them.
+
+## Scope: this plugin vs Sylius
+
+This guide covers **the plugin's side** - the SchemaBuilder/ValueFormatter pair that teaches the AI about your filter. Registering the filter type with Sylius itself is **not** part of this plugin and must be done separately:
+
+1. A PHP class implementing `Sylius\Component\Grid\Filtering\FilterInterface`
+2. A service tagged `sylius.grid_filter` with both `type` and `form_type` attributes
+3. A template registered in `sylius_grid.templates.filter` (otherwise Sylius admin sidebar throws "Missing template for filter type X")
+
+See the [Sylius Grid Bundle documentation](https://docs.sylius.com/en/latest/book/grids/grids.html) for these steps. Once your filter is wired with Sylius, the rest of this guide tells you how to teach the AI about it.
+
+## Two interfaces to implement
+
+For each custom filter type, you need to provide:
+
+1. **A SchemaBuilder** - describes the filter to the LLM (JSON Schema describing the shape of the value the AI should return)
+2. **A ValueFormatter** - converts the LLM's response into the format your Sylius filter expects
+
+Both are auto-registered via Symfony service autoconfiguration - just create the classes, no service tag or YAML needed.
+
+## Example: custom `tags` filter
+
+Say your Sylius project has a custom filter named `tags` (matching a Sylius `TagsFilter::NAME`), which expects a comma-separated string and matches products by tag.
+
+### 1. SchemaBuilder
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\GridAssistant\Schema;
+
+use Guiziweb\SyliusGridAssistantPlugin\Schema\Builder\FilterSchemaBuilderInterface;
+use Sylius\Component\Grid\Definition\Filter;
+
+final class TagsFilterSchemaBuilder implements FilterSchemaBuilderInterface
+{
+    public static function getType(): string
+    {
+        return 'tags';
+    }
+
+    public function build(Filter $filter): array
+    {
+        return [
+            'type' => 'string',
+            'description' => sprintf(
+                '%s - comma-separated list of tags. Omit if not mentioned by the user.',
+                (string) $filter->getLabel(),
+            ),
+        ];
+    }
+}
+```
+
+The `build()` method returns a JSON Schema fragment that becomes part of the `criteria.<filter_name>` shape in the LLM `response_format` parameter.
+
+### 2. ValueFormatter
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\GridAssistant\Schema;
+
+use Guiziweb\SyliusGridAssistantPlugin\Schema\Formatter\FilterFormatResult;
+use Guiziweb\SyliusGridAssistantPlugin\Schema\Formatter\FilterValueFormatterInterface;
+use Sylius\Component\Grid\Definition\Filter;
+
+final class TagsFilterValueFormatter implements FilterValueFormatterInterface
+{
+    public static function getType(): string
+    {
+        return 'tags';
+    }
+
+    public function format(mixed $value, Filter $filter): FilterFormatResult
+    {
+        if (!is_string($value) || '' === trim($value)) {
+            return new FilterFormatResult(null); // ignore this criterion
+        }
+
+        return new FilterFormatResult(trim($value));
+    }
+}
+```
+
+The `format()` method receives the raw value from the LLM (whatever the schema returned by `build()` allows) and returns a `FilterFormatResult` containing the value in the shape Sylius expects.
+
+Return `new FilterFormatResult(null)` to silently drop the criterion (e.g. empty value, invalid format).
+
+## That's it
+
+No service registration. The plugin auto-discovers any class implementing `FilterSchemaBuilderInterface` or `FilterValueFormatterInterface` and registers them with the proper tags.
+
+## Testing your extension
+
+1. **Check the container**: `bin/console lint:container` should pass.
+2. **Test with a query**: in the admin, use a query that should trigger your filter (e.g. `"products tagged limited-edition"` for a `tags` filter).
+3. **Inspect the URL after redirect**: it should include `?criteria[tags]=limited-edition`.
+4. **Look at the AI log**: by default the plugin logs to the `ai` channel - search for `[GridAssistant]` entries to see what filters/sorting the LLM produced.
+
+## Multi-type builders/formatters
+
+If your class handles several filter types (rare), `getType()` can return an array:
+
+```php
+public static function getType(): array
+{
+    return ['tags', 'labels'];
+}
+```
+
+The same builder/formatter will be used for both types.
+
+## Overriding a built-in type
+
+Overriding a native builder/formatter for one of the stock types is technically possible (the registry stores them by type, so any same-type registration replaces the previous one), **but the registration order isn't guaranteed** by Symfony's autoconfiguration. If you really need to override, the safest path is to disable the plugin's built-in service in your `services.yaml` (turning off autoconfigure removes the tag that would register it as a builder) and replace it explicitly:
+
+```yaml
+services:
+    Guiziweb\SyliusGridAssistantPlugin\Schema\Builder\StringFilterSchemaBuilder:
+        autoconfigure: false  # disables the auto-tag, so it's no longer registered as a builder
+
+    App\GridAssistant\Schema\MyStringFilterSchemaBuilder: ~
+```
+
+Most users don't need this - prefer extending behavior via filter options (`ai_searchable`, custom `formOptions`) before resorting to overriding.