From bce4073a3ca5d6af0be79e624f46aa3d3831e4fd Mon Sep 17 00:00:00 2001 From: bohdanyevtukhov Date: Wed, 25 Sep 2024 15:40:56 +0300 Subject: [PATCH] Implemented AI features integration guides. --- _config.yml | 1 + .../install-the-image-search-ai-feature.md | 429 ++++++++++++++++++ .../202407.0/install-the-open-ai-feature.md | 83 ++++ ...stall-the-product-management-ai-feature.md | 254 +++++++++++ .../install-the-image-search-ai-feature.md | 7 + .../install-the-open-ai-feature.md | 7 + ...stall-the-product-management-ai-feature.md | 7 + 7 files changed, 788 insertions(+) create mode 100644 _includes/pbc/all/install-features/202407.0/install-the-image-search-ai-feature.md create mode 100644 _includes/pbc/all/install-features/202407.0/install-the-open-ai-feature.md create mode 100644 _includes/pbc/all/install-features/202407.0/install-the-product-management-ai-feature.md create mode 100644 docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-image-search-ai-feature.md create mode 100644 docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-open-ai-feature.md create mode 100644 docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-product-management-ai-feature.md diff --git a/_config.yml b/_config.yml index b8df8477057..2936290c934 100644 --- a/_config.yml +++ b/_config.yml @@ -147,6 +147,7 @@ versioned_categories: - glue-api pbc: all: + - ai-integrations - back-office - cart-and-checkout - carrier-management diff --git a/_includes/pbc/all/install-features/202407.0/install-the-image-search-ai-feature.md b/_includes/pbc/all/install-features/202407.0/install-the-image-search-ai-feature.md new file mode 100644 index 00000000000..64a80c0c647 --- /dev/null +++ b/_includes/pbc/all/install-features/202407.0/install-the-image-search-ai-feature.md @@ -0,0 +1,429 @@ +This document describes how to install the [ImageSearchAi](https://github.com/spryker-eco/image-search-ai) feature. + +## Install feature core + +Follow the steps below to install the ImageSearchAi feature core. + +### Prerequisites + +### 1) Install the required modules + + + + +```bash +composer require spryker-eco/image-search-ai:"^0.1.1" --update-with-dependencies +``` + +**Verification** + +Make sure the following modules have been installed: + +| MODULE | EXPECTED DIRECTORY | +|---------------|-------------------------------------------------| +| OpenAi | vendor/spryker-eco/open-ai | +| ImageSearchAi | vendor/spryker-eco/image-search-ai | + +--- + +### Add translations + + +Add translations as follows: + +1. Append glossary for the feature: + +**src/data/import/glossary.csv** + +``` +search.with.your-images.title,Search with your images,en_US +search.with.your-images.title,Bildern suchen,de_DE +search.with.your-images.title,Recherchez avec vos images,fr_FR +search.with.your-images.title,Buscar con sus imágenes,es_ES +search.with.your-images.content,Upload an image to find similar products,en_US +search.with.your-images.content,"Laden Sie ein Bild hoch, um ähnliche Produkte zu finden",de_DE +search.with.your-images.content,Téléchargez une image pour trouver des produits similaires,fr_FR +search.with.your-images.content,Cargue una imagen para encontrar productos similares,es_ES +search.with.your-images.error,Something went wrong. Please try another image,en_US +search.with.your-images.error,Etwas ist schiefgelaufen. Bitte versuchen Sie es mit einem anderen Bild,de_DE +search.with.your-images.error,Une erreur s'est produite. Veuillez essayer avec une autre image,fr_FR +search.with.your-images.error,"Algo salió mal. Por favor, intente con otra imagen",es_ES +search.with.your-images.button,Upload an image,en_US +search.with.your-images.button,Bild hochladen,de_DE +search.with.your-images.button,Télécharger une image,fr_FR +search.with.your-images.button,Cargar una imagen,es_ES +search.with.your.images.photo.button,Take a photo,en_US +search.with.your.images.photo.button,Foto aufnehmen,de_DE +search.with.your.images.photo.button,Prendre une photo,fr_FR +search.with.your.images.photo.button,Hacer una foto,es_ES +search.with.your-images.no-results,"No results found. Please try another image.",en_US +search.with.your-images.no-results,"Keine Ergebnisse gefunden. Bitte versuchen Sie es mit einem anderen Bild.",de_DE +search.with.your-images.no-results,"Aucun résultat trouvé. Veuillez essayer une autre image.",fr_FR +search.with.your-images.no-results,"No se encontraron resultados. Por favor, intente con otra imagen.",es_ES +``` + +2. Import data: + +```bash +console data:import glossary +``` + +**Verification** + +Make sure that the configured data has been added to the `spy_glossary_key` and `spy_glossary_translation` tables. + +### Enable controllers +Enable the following behaviors by registering the plugins: + +| PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | +| -------- |-------------------------------------------------------| --------------- | --------- | +| ImageSearchAiRouteProviderPlugin | Adds the image search routes to the Yves application. | | SprykerEco\Yves\ImageSearchAi\Plugin\Router | + +**src/Pyz/Yves/Router/RouterDependencyProvider.php** +```php + /** + * @return array<\Spryker\Yves\RouterExtension\Dependency\Plugin\RouteProviderPluginInterface> + */ + protected function getRouteProvider(): array + { + return [ + ... + new ImageSearchAiRouteProviderPlugin(), + ]; + } +``` + +To apply the changes, run the following command: + +```bash +yves router:cache:warm +``` + +**Verification** + +Url `http://mysprykershop.com/search-ai/image` will not return `404 Not Found`. + +### Set up widget +Set up the widget as follows: + +**src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** + +``` + /** + * @return array + */ + protected function getGlobalWidgets(): array + { + return [ + ... + ImageSearchAiWidget::class, + ]; + } +``` + +**src/Pyz/Yves/ShopUi/Theme/default/components/organisms/header/header.twig** + +```twig +{% raw %} + {% embed molecule('search-form') with { + ... + data: { + byImage: true, + }, + ... + } only %} + ... + {% endembed %} +{% endraw %} +``` + +**src/Pyz/Yves/ShopUi/Theme/default/components/molecules/search-form/search-form.twig** + +``` +{% raw %} +
+
+ +
+ + {% if data.byImage and widgetGlobalExists('ImageSearchAiWidget') %} +
+ {% widget 'ImageSearchAiWidget' only %}{% endwidget %} +
+ {% endif %} +
+{% endraw %} +``` + +To apply the changes, run the following command: + +```bash +console frontend:build:yves +console cache:empty-all +``` +**Verification** + +Make sure the image search button is displayed on the search form. + +### B2B Shop styling guide (optional) + +
+ Adjustments for B2B shop + +**src/Pyz/Yves/ImageSearchAi/Theme/default/components/molecules/image-uploader-popup/image-uploader-popup.twig** + +```twig +{% raw %} +{% extends molecule('image-uploader-popup', '@SprykerEco:ImageSearchAi') %} + +{% block trigger %} + +{% endblock %} +{% endraw %} +``` + +**src/Pyz/Yves/ImageSearchAi/Theme/default/components/molecules/image-uploader/image-uploader.twig** + +```twig +{% raw %} +{% extends molecule('image-uploader', '@SprykerEco:ImageSearchAi') %} + +{% block actions %} +
+
+ +
+
+ +
+
+{% endblock %} +{% endraw %} +``` + + + +**src/Pyz/Yves/ShopUi/Theme/default/components/atoms/button/button.scss** + +```scss + ... + &--sm-lg-large { + @include helper-breakpoint-media-max($lg - 1) { + font-size: rem(20); + line-height: rem(22); + padding: rem(18) rem(32); + } + } + ... +``` + +**src/Pyz/Yves/ShopUi/Theme/default/components/atoms/icon/icon.scss** + +```scss + ... + &--spinner { + animation: spin-to 1s linear infinite; + } + ... +``` + +**src/Pyz/Yves/ShopUi/Theme/default/components/molecules/search-form/search-form.scss** + +```scss + &--close { + ... + color: $setting-color-white; + background: $setting-color-black; + ... +``` + +**src/Pyz/Yves/ShopUi/Theme/default/components/molecules/search-form/search-form.twig** + +```twig +{% raw %} +
+ -
+ +
+ ... + {% if data.byImage and widgetGlobalExists('ImageSearchAiWidget') %} + -
+ +
+{% endraw %} +``` + +**src/Pyz/Yves/ShopUi/Theme/default/styles/basics/_grid.scss** +```scss + ... + &--no-shrink { + flex-shrink: 0; + } + ... + - &--gap { + + &--with-gutter, + &--gap { +``` + +**src/Pyz/Yves/ShopUi/Theme/default/styles/settings/_spacing.scss** + +```scss + $setting-spacing: ( + large: 2.8rem, + ... +``` + +**src/Pyz/Yves/ShopUi/Theme/default/styles/settings/_z-index.scss** + +```scss + ... + $setting-zi-popup: 1230; + ... +``` +
+ +
+ Adjustments for B2C shop + +**src/Pyz/Yves/ImageSearchAi/Theme/default/components/molecules/image-uploader-popup/image-uploader-popup.twig** +```twig +{% raw %} +{% extends molecule('image-uploader-popup', '@SprykerEco:ImageSearchAi') %} + +{% block trigger %} + +{% endblock %} +{% endraw %} +``` + +**src/Pyz/Yves/ShopUi/Theme/default/components/molecules/search-form/search-form.twig** + +```twig +{% raw %} + -
+ +
+ + ... + + - {% if data.byImage and widgetGlobalExists('ImageSearchAiWidget') %} + -
+ - {% widget 'ImageSearchAiWidget' only %}{% endwidget %} + -
+ - {% endif %} +{% endraw %} +``` + +**src/Pyz/Yves/ShopUi/Theme/default/components/organisms/header/header.scss** + +```scss + &__search { + @include helper-effect-transition(all); + @include helper-visibility-invisible; + padding: rem(34) rem(50) rem(34) rem(20); + background: $setting-color-white; + min-width: 100vw; + transform-origin: top center; + transform: scaleY(0); + + @include helper-breakpoint-media-min($md-min) { + min-width: rem(540); + padding-right: rem(76); + } + } + + ... + + &__search-close { + ... + right: rem(15); + ... + } + + &__image-search { + position: relative; + z-index: $setting-zi-search-suggestions + 10; + } +``` + +**src/Pyz/Yves/ShopUi/Theme/default/components/organisms/header/header.twig** + +```twig +{% raw %} +
+ {% if data.showSearchForm %} +
+ {% include molecule('search-form') with { + class: config.name ~ '__search-form', + attributes: { + 'data-search-id': 'desktop', + 'wrapper-class-name': 'js-' ~ config.name ~ '__search-wrapper', + 'close-class-name': 'js-' ~ config.name ~ '__search-close', + 'open-class-name': 'js-' ~ config.name ~ '__search-open', + 'wrapper-toggle-class-name': config.name ~ '__search-wrapper-active', + }, + } only %} +
+ + {% if widgetGlobalExists('ImageSearchAiWidget') %} +
+
+ {% widget 'ImageSearchAiWidget' only %}{% endwidget %} +
+
+ {% endif %} + {% endif %} +
+{% endraw %} +``` + +**src/Pyz/Yves/ShopUi/Theme/default/styles/basics/_grid.scss** + +```scss + .col { + ... + &--with-gutter { + padding: 0 $setting-grid-gutter; + } + + .grid { + ... + &--with-gutter { + margin: 0 (-$setting-grid-gutter); + max-width: none; + } + } +} +``` + +**src/Pyz/Yves/ShopUi/Theme/default/styles/settings/_grid.scss** +```scss + $setting-grid-gutter: rem(15); +``` + +**src/Pyz/Yves/ShopUi/Theme/default/styles/settings/_z-index.scss** +```scss + $setting-zi-popup: 800; +``` +
diff --git a/_includes/pbc/all/install-features/202407.0/install-the-open-ai-feature.md b/_includes/pbc/all/install-features/202407.0/install-the-open-ai-feature.md new file mode 100644 index 00000000000..bf0074ad0ea --- /dev/null +++ b/_includes/pbc/all/install-features/202407.0/install-the-open-ai-feature.md @@ -0,0 +1,83 @@ +This document describes how to install the [OpenAi]() feature. + +## Install feature core + +Follow the steps below to install the {Feature Name} feature core. + +### Prerequisites + +### 1) Install the required modules + +```bash +composer require spryker-eco/open-ai:"^0.1.1" --update-with-dependencies +``` + +**Verification** + + + + +Make sure the following modules have been installed: + +| MODULE | EXPECTED DIRECTORY | +|--------|-------------------------------------------------| +| OpenAi | vendor/spryker-eco/open-ai | + +### Set up the configuration + + + + + + +Add the following configuration: + +| CONFIGURATION | SPECIFICATION | NAMESPACE | +| --------------- |------------------|--------------------------| +| OpenAiConstants::API_TOKEN | OpenAi API token | SprykerEco/Shared/OpenAi | + +**config/Shared/config_default.php** + +```php + + +Set up transfer objects as follows: + +```bash +console transfer:generate +``` + +**Verification** + +Make sure the following changes have been triggered in transfer objects: + +| TRANSFER | TYPE | EVENT | PATH | +| ---------- |-------|---------|-------------------------| +| OpenAiChatRequest | class | created | src/Generated/Transfer/OpenAiChatRequest | +| OpenAiChatResponse | class | created | src/Generated/Transfer/OpenAiChatResponse | diff --git a/_includes/pbc/all/install-features/202407.0/install-the-product-management-ai-feature.md b/_includes/pbc/all/install-features/202407.0/install-the-product-management-ai-feature.md new file mode 100644 index 00000000000..33991638424 --- /dev/null +++ b/_includes/pbc/all/install-features/202407.0/install-the-product-management-ai-feature.md @@ -0,0 +1,254 @@ +This document describes how to install the [ProductManagementAi](https://github.com/spryker-eco/product-management-ai) feature. + +## Install feature core + +Follow the steps below to install the ImageSearchAi feature core. + +### Prerequisites + +### 1) Install the required modules + + + + +```bash +composer require spryker-eco/product-management-ai:"^0.1.1" --update-with-dependencies +``` + +**Verification** + +Make sure the following modules have been installed: + +| MODULE | EXPECTED DIRECTORY | +|---------------------|-------------------------------------------------| +| OpenAi | vendor/spryker-eco/open-ai | +| ProductManagementAi | vendor/spryker-eco/product-management-ai | + +--- + +### Set up database schema + + +Set up database schema as follows: + +1. Adjust the schema definition so entity changes trigger events: + +| AFFECTED ENTITY | TRIGGERED EVENTS | +|-----------------|------------------| +| SpyProductImage | * | + +```xml + + + + + +
+ + +``` + +2. Apply database changes and generate entity and transfer changes: + +```bash +console transfer:generate +console propel:install +console transfer:generate +``` + +**Verification** + + + + +Make sure that following changes have been applied by checking your database: + +| DATABASE ENTITY | TYPE | EVENT | +|-------------------|----------|-------| +| spy_product_image | alt_text | * | + +--- + +### Set up transfer objects + + +Set up transfer objects as follows: + +```bash +console transfer:generate +``` + +**Verification** + +Make sure the following changes have been triggered in transfer objects: + +| TRANSFER | TYPE | EVENT | PATH | +| ---------- |-------|---------|-------------------------| +| AiTranslatorRequest | class | created | src/Generated/Transfer/AiTranslatorRequest | +| AiTranslatorResponse | class | created | src/Generated/Transfer/AiTranslatorResponse | +| ProductImage | class | updated | src/Generated/Transfer/ProductImage | +| ProductImageStorage | class | updated | src/Generated/Transfer/ProductImageStorage | +| Category | class | updated | src/Generated/Transfer/Category | +| CategoryCollection | class | updated | src/Generated/Transfer/CategoryCollection | +| ProductAbstract | class | updated | src/Generated/Transfer/ProductAbstract | +| Locale | class | updated | src/Generated/Transfer/Locale | + +--- + +### Set up behavior +Enable the following behaviors by registering the plugins: + +| PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | +| -------- |----------------------------------------------------------| --------------- | --------- | +| ProductCategoryProductAbstractPostCreatePlugin | Adds action on product abstract post create event. | | SprykerEco\Yves\ImageSearchAi\Plugin\Router | +| ProductCategoryProductAbstractAfterUpdatePlugin | Adds action on product abstract after update event. | | SprykerEco\Yves\ImageSearchAi\Plugin\Router | +| ProductCategoryAbstractFormExpanderPlugin | Expands `ProductAbstractForm`. | | SprykerEco\Yves\ImageSearchAi\Plugin\Router | +| ImageAltTextProductConcreteEditFormExpanderPlugin | Expands `ProductConcreteEditForm` with `alt_text` field. | | SprykerEco\Yves\ImageSearchAi\Plugin\Router | +| ImageAltTextProductAbstractFormExpanderPlugin | Expands `ProductAbstractForm` with `alt_text` field. | | SprykerEco\Yves\ImageSearchAi\Plugin\Router | +| ImageAltTextProductConcreteFormExpanderPlugin | Expands `ProductConcreteForm` with `alt_text` field. | | SprykerEco\Yves\ImageSearchAi\Plugin\Router | + +**src/Pyz/Zed/Product/ProductDependencyProvider.php** +```php + /** + * The order of execution is important to support Inherited scope and sub-entity functionality + * + * @return array<\Spryker\Zed\ProductExtension\Dependency\Plugin\ProductAbstractPostCreatePluginInterface> + */ + protected function getProductAbstractPostCreatePlugins(): array + { + return [ + ... + new ProductCategoryProductAbstractPostCreatePlugin(), + ]; + } + + /** + * @param \Spryker\Zed\Kernel\Container $container + * + * @return array<\Spryker\Zed\Product\Dependency\Plugin\ProductAbstractPluginUpdateInterface> + */ + protected function getProductAbstractAfterUpdatePlugins(Container $container): array + { + return [ + ... + new ProductCategoryProductAbstractAfterUpdatePlugin(), + ]; + } +``` + +**src/Pyz/Zed/ProductManagement/ProductManagementDependencyProvider.php** + +```php + /** + * @return array<\Spryker\Zed\ProductManagementExtension\Dependency\Plugin\ProductConcreteEditFormExpanderPluginInterface> + */ + protected function getProductConcreteEditFormExpanderPlugins(): array + { + return [ + ... + new ImageAltTextProductConcreteEditFormExpanderPlugin(), + ]; + } + + /** + * @return array<\Spryker\Zed\ProductManagementExtension\Dependency\Plugin\ProductAbstractFormExpanderPluginInterface> + */ + protected function getProductAbstractFormExpanderPlugins(): array + { + return [ + ... + new ProductCategoryAbstractFormExpanderPlugin(), + new ImageAltTextProductAbstractFormExpanderPlugin(), + ]; + } + + /** + * @return array<\Spryker\Zed\ProductManagementExtension\Dependency\Plugin\ProductConcreteFormExpanderPluginInterface> + */ + protected function getProductConcreteFormExpanderPlugins(): array + { + return [ + ... + new ImageAltTextProductConcreteFormExpanderPlugin(), + ]; + } +``` + +**src/Pyz/Zed/ProductManagement/Presentation/Add/index.twig** + +```twig +{% raw %} +{% extends '@Spryker:ProductManagement/Add/index.twig' %} + +{% block content %} + {{ parent() }} + + {% include '@SprykerEco:ProductManagementAi/_partials/product-management-ai-modals.twig' %} +{% endblock %} +{% endraw %} +``` + +**src/Pyz/Zed/ProductManagement/Presentation/Edit/index.twig** + +```twig +{% raw %} +{% extends '@Spryker:ProductManagement/Edit/index.twig' %} + +{% block content %} + {{ parent() }} + + {% include '@SprykerEco:ProductManagementAi/_partials/product-management-ai-modals.twig' %} +{% endblock %} +{% endraw %} +``` + +**src/Pyz/Zed/ProductManagement/Presentation/Product/_partials/general-tab.twig** + +```twig +{% raw %} +{% extends '@Spryker:ProductManagement/Product/_partials/general-tab.twig' %} + +{% block descriptionField %} + {% embed '@Gui/Partials/localized-ibox.twig' with {'collapsed': (not loop.first), 'localeName': locale.localeName} %} + {% block content %} + {% for input in form[formKey] %} + {% embed '@SprykerEco:ProductManagementAi/_partials/ai-translation-trigger.twig' %} + {% block input %} +
+ {{ form_label(input) }} + {{ form_widget(input, {'attr': {'class': 'name-translation js-infomational-field'}}) }} + {{ form_errors(input) }} +
+ {% endblock %} + {% endembed %} + {% endfor %} + {% endblock %} + {% endembed %} +{% endblock %} + +{% block description %} +{{ parent() }} + + {% include '@SprykerEco:ProductManagementAi/_partials/category-modal-trigger.twig' %} +{% endblock %} +{% endraw %} +``` + +To apply the changes, run the following command: + +```bash +console frontend:build:backoffice +``` + +**Verification** + +Login to backoffice, go to product abstract create/update page and make sure that fields `name`, `description` and `categories` have new icon to open an AI Assistant popup. Also, make sure that on tab Images a new field `Alt Text` is displayed. diff --git a/docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-image-search-ai-feature.md b/docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-image-search-ai-feature.md new file mode 100644 index 00000000000..ce45891a508 --- /dev/null +++ b/docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-image-search-ai-feature.md @@ -0,0 +1,7 @@ +--- +title: Install the ImageSearchAi feature +description: Learn how to install the ImageSearchAi feature +template: feature-installation-guide-template +--- + +{% include pbc/all/install-features/{{page.version}}/install-the-image-search-ai-feature.md %} diff --git a/docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-open-ai-feature.md b/docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-open-ai-feature.md new file mode 100644 index 00000000000..a70e8cd3bdd --- /dev/null +++ b/docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-open-ai-feature.md @@ -0,0 +1,7 @@ +--- +title: Install the OpenAi feature +description: Learn how to install the OpenAi feature +template: feature-installation-guide-template +--- + +{% include pbc/all/install-features/{{page.version}}/install-the-open-ai-feature.md %} diff --git a/docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-product-management-ai-feature.md b/docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-product-management-ai-feature.md new file mode 100644 index 00000000000..a7b3d9f1679 --- /dev/null +++ b/docs/pbc/all/ai-integrations/202407.0/base-shop/install-and-upgrade/install-the-product-management-ai-feature.md @@ -0,0 +1,7 @@ +--- +title: Install the ProductManagementAi feature +description: Learn how to install the ProductManagementAi feature +template: feature-installation-guide-template +--- + +{% include pbc/all/install-features/{{page.version}}/install-the-product-management-ai-feature.md %}