Implement changes after the release

Author: dabrt

code_samples/ai_actions/config/add_ai_actions.sql

@@ -0,0 +1,45 @@
+create table ibexa_action_configuration
+(
+    id                        int auto_increment primary key,
+    identifier                varchar(64) not null,
+    type                      varchar(32) not null,
+    enabled                   tinyint(1)  not null,
+    action_type_options       json        null,
+    action_handler_options    json        null,
+    action_handler_identifier varchar(64) null,
+    created_at                datetime    null comment '(DC2Type:datetime_immutable)',
+    updated_at                datetime    null comment '(DC2Type:datetime_immutable)',
+    constraint ibexa_action_configuration_identifier_uc
+        unique (identifier)
+)
+collate = utf8mb4_unicode_520_ci;
+
+create index ibexa_action_configuration_enabled_idx
+    on ibexa_action_configuration (enabled);
+
+create index ibexa_action_configuration_identifier_idx
+    on ibexa_action_configuration (identifier);
+
+create table ibexa_action_configuration_ml
+(
+    id                      int auto_increment primary key,
+    action_configuration_id int          not null,
+    language_id             bigint       not null,
+    name                    varchar(190) not null,
+    description             longtext     null,
+    constraint ibexa_action_configuration_ml_uidx
+        unique (action_configuration_id, language_id),
+    constraint ibexa_action_configuration_ml_to_action_configuration_fk
+        foreign key (action_configuration_id) references ibexa_action_configuration (id)
+            on update cascade on delete cascade,
+    constraint ibexa_action_configuration_ml_to_language_fk
+        foreign key (language_id) references ezcontent_language (id)
+            on update cascade on delete cascade
+)
+    collate = utf8mb4_unicode_520_ci;
+
+create index ibexa_action_configuration_ml_action_configuration_idx
+    on ibexa_action_configuration_ml (action_configuration_id);
+
+create index ibexa_action_configuration_ml_language_idx
+    on ibexa_action_configuration_ml (language_id);

docs/ai_actions/ai_actions.md

@@ -5,12 +5,13 @@ page_type: landing_page
 
 # AI Actions
 
-Enhance the usability and flexibility of [[= product_name =]] by installing the AI Actions add-on that can automate various tasks, for example, generate alt text for images.
-Potentially, you can use AI for transforming text passages, generating illustrations for your articles based on a prompt, and so on.
+The AI Actions add-on enhances the usability and flexibility of [[= product_name =]] by automating various tasks.
+After you configure it, it can generate alt text for images or transform text passages.
+
+You can also extend it to perform other tasks or support additional AI engines.
 
 [[= cards([
 "ai_actions/ai_actions_guide",
-"ai_actions/configure_access_to_openai",
 "ai_actions/install_ai_actions",
 "ai_actions/extend_ai_actions"
 ], columns=4) =]]

docs/ai_actions/ai_actions_guide.md

@@ -6,91 +6,93 @@ description: AI Actions add-on helps editors by automating repetitive tasks.
 
 ## What are AI Actions
 
-In the evolving landscape of digital experience, artificial intelligence becomes more and more important by enhancing user interaction and automating complex tasks.
-[[= product_name =]] can be equipped with the AI Actions add-on, which harnesses AI's potential to automate various time-consuming tasks, for example, generating alt text for images.
+In the evolving landscape of digital experience, artificial intelligence becomes more and more important by enhancing user interaction and automating complex processes.
+[[= product_name =]] can be equipped with the AI Actions add-on, which harnesses AI's potential to automate time-consuming editorial tasks.
+AI Actions is an extensible solution for integrating features provided by AI services into your workflows, all managed through a user-friendly interface.
 
 Out-of-the-box, AI Actions includes two essential components: a framework package and an OpenAI connector package.
-By default it comes with two action types preconfigured:
+It comes pre-configured with the following action types:
 
-- Generate alternative text: Generate alt text for accessibility purposes
-- Refine text: Rewrite existing text according to parameters set in a prompt
+- [Refine text](#refining-text): Rewrite existing text according to parameters set in a prompt
+- [Generate alternative text](#generating-alternative-text): Generate alt text for accessibility purposes
 
-![AI Actions schematic](<img/guide_AI Actions.png>)
+![AI Actions schematic](img/guide_AI Actions.png)
 
 You can extend its capabilities beyond the default setup by creating custom connector modules, allowing users to integrate additional AI services or customize the way data is processed and interpreted.
-For example, it can transform text, or generate illustrations for your articles based on a prompt.
+For example, it could transform images, or generate illustrations for your articles based on their contents.
 The possibilities are endless and you're not limited to a specific AI service, avoiding vendor lock-in.
 
 ## Availability
 
-The AI Actions feature is an opt-in capability available as an LTS Update to the v4.6.x version of [[= product_name =]], regardless of its edition.
-To begin using AI Actions, you must first install the required packages and perform initial configuration.
+AI Actions are an opt-in capability available as an LTS Update to the v4.6.x version of [[= product_name =]], regardless of its edition.
+To begin using AI Actions, you must first [install the required packages and perform initial configuration](install_ai_actions.md).
 
 !!! note "API Key"
 
-    The Open AI connector requires that you first [get an API key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key).
+    The OpenAI connector requires that you first [get an API key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key) and make sure that you [set up a billing method](https://help.openai.com/en/articles/9038407-how-can-i-set-up-billing-for-my-account).
 
 ## How it works
 
-Built upon the PHP framework, AI Actions offer an extensible solution for integrating features provided by AI services into your workflows, all managed through a user-friendly interface.
-
-The framework package is responsible for gathering information from various sources, such as Action types, Action configurations, and contextual details like SiteAccess, user details, locale settings, and more.
+AI Actions add-on is built upon the PHP framework.
+The framework package is responsible for gathering information from various sources, such as AI action types, AI action configurations, and contextual details like SiteAccess, user details, locale settings, and more.
 This data can then be combined with user input.
-Then it's passed to a connector, such as the OpenAI connector, for final processing on [[= product_name =]] side.
-The connector wraps the data into a prompt or another suitable format and sends it to an external AI service.
-
-When the AI Service returns a response, the response goes through the connector and passes to the framework.
-It can now be presented to the user in any way necessary.
+It's then passed to a service connector, such as the default OpenAI connector, for final processing on [[= product_name =]] side.
+The service connector wraps all data into a prompt or another suitable format and sends it to an external AI service.
 
-AI Actions can also be extended beyond the default setup by creating custom connector modules, allowing users to integrate additional AI services or customize the way data is processed and interpreted.
+When the AI Service returns a response, the response goes back through the service connector and passes to the framework.
+It can then be presented to the user in any way necessary.
 
 ### Core concepts
 
+#### AI service
+
+AI service is a third party platform that provides access to artificial intelligence tools and capabilities.
+It executes tasks that it receives through a service connector.
+
 #### Action
 
-Actions are tasks or functions that the AI is set to perform.
-Each Action is a combination of an action type and an action configuration.
-Action types define what kind of task the AI performs, while action configurations specify how the task should be executed.
+Actions are tasks or functions that the AI service is set to perform.
+Each action is a combination of an AI action type and an AI action configuration.
+Action types define what kind of task the AI service performs, while AI action configurations specify how the task should be executed.
 This clear separation allows for a flexible system where actions can be created, managed, and customized with minimal effort.
 
-#### Action type
+#### AI action type
 
-Action types are predefined by developers.
-Each action type defines the structure and nature of the task that the AI service performs.
-Action types could be designed to generate alt text for images, summarize a passage of text, or even translate content into another language.
-By defining action types, developers can create a wide range of functionalities that can be deployed within the application.
+AI action types are templates predefined by developers.
+Each AI action type defines the structure and nature of the task that the AI service performs.
+AI action types could be designed, for example, to generate text based on an image, translate a passage of text, or generate a video clip based on a description.
+By defining AI action types, developers can create a wide range of functionalities that can be deployed within the application.
 
-#### Action configuration
+#### AI action configuration
 
-Website administrators use Action configurations to employ action types to generate actions.
-Action configurations are managed in the [Admin Panel](admin_panel.md), and allow administrators to customize and fine-tune the behavior of each action.
-Such tuning might involve setting specific parameters used the AI service, setting an expense limit, or configuring how the output should be handled.
-By making such adjustments, administrators can ensure that the actions are tailored to meet their requirements.
+AI action configurations store detailed parameters needed to generate AI actions based on AI action types.
+Website administrators manage AI action configurations in the [**Admin** panel](admin_panel.md), where they customize and fine-tune the behavior of each AI action.
+It might involve setting specific parameters used by the AI service, a response length, an expense limit, or configuring how the output should be handled.
+By making such adjustments, administrators can ensure that the actions are tailored to meet the needs of your organization.
 
-#### Handler
+#### Models
 
-Once an action is defined and configured, it must be executed, and this is where handlers come into play.
-Handlers are pieces of PHP code that are responsible for resolving an action.
-Each handler is designed to work with a specific AI service and action type pair.
-Handlers may include hardcoded prompts for conversational AI services like ChatGPT.
-They can also operate without prompts in the case of other types of AI.
-Handlers take parameters defined in the action type and action configuration, combine it with user input and any predefined settings or prompts, and pass this information to the AI service for processing.
+Once an AI action is defined and configured, it must be executed, and this is where models come into play.
+Each model is designed to work with a specific AI service and AI action type pair.
+Pieces of PHP code that are responsible for resolving a model are called handlers.
+They may include hardcoded prompts for conversational AI services like ChatGPT, or operate without prompts in the case of other types of AI.
+Handlers take parameters defined in the AI action type and configuration, combine it with user input and any predefined settings or prompts, and pass this information to the AI service for processing.
 
 ### Triggering actions from the UI
 
-Among other elements, AI Actions package includes UI components for:
+Among other elements, AI Actions add-on includes UI components for:
 
-- action management in the Admin Panel,
-- alt-text generation feature in image management
+- AI action management in the **Admin** panel
 - text modification in online editor
+- alt-text generation feature in the image management modal
 
 These areas are user-friendly and well integrated with the existing application’s UI.
-Administrators can manage action configurations with ease, while end-users can trigger actions with a click of a button.
+Administrators can manage action configurations with ease, while editors can trigger actions with a click of a button.
 Procedures are straightforward and intuitive, ensuring that users can quickly achieve their desired outcomes.
 
 ### Triggering actions programmatically
 
-AI Actions add-on exposes a REST API interface that allows for programmatic execution of actions.
+AI Actions add-on exposes a REST API interface that allows for programmatic execution of AI actions.
 With the API, developers can automate tasks and execute actions on batches of content by integrating them into workflows.
 <!---By issuing commands through the API, developers can trigger actions based on external events:
 ...--->
@@ -99,42 +101,40 @@ With the API, developers can automate tasks and execute actions on batches of co
 
 ### Management
 
-The AI Actions allows you to control the lifecycle of action configurations.
-Users with the appropriate permissions, governed by role-based [policies](policies.md#ai-actions), can create, edit, execute, and delete action configurations.
-Additionally, configurations can be enabled or disabled depending on the organization's needs.
+Users with the appropriate permissions, governed by role-based [policies](policies.md#ai-actions), can control the lifecycle of AI actions by creating, editing, executing, and deleting them.
+Additionally, AI action configurations can be enabled or disabled depending on the organization's needs.
 
-[Configurations management screen](ai_actions_list.md)
+![Configurations management screen](img/ai_actions_list.md)
 
-An intuitive AI Actions interface within the Admin Panel displays a list of all available action configurations.
-Here, you can search for specific configurations and filter them by type or status.
-By accessing the detailed view of individual action configurations, it is possible to quickly review all the parameters.
+An intuitive AI Actions interface within the **Admin** panel displays a list of all available AI actions.
+Here, you can search for specific actions and filter them by type or status.
+By accessing the detailed view of individual AI actions, you can quickly review all their parameters.
 
 ### Extensibility
 
-Built-in action types offer a good starting point, but the real power of AI Actions lies in extensibility.
+Built-in AI action types offer a good starting point, but the real power of the AI Actions add-on lies in extensibility.
 Extending AI Actions opens up new possibilities for content management and editing.
-Developers can extend the feature by adding new action types that use existing AI services or even integrating additional ones.
-This involves defining a new action type, writing a handler that communicates with the new service, and creating a form for configuring the options that extends the default action configuration form shown in the Admin Panel.
-For example, if this is your enterprise's requirement, a developer could write a handler that uses an AI service to generate complete articles based on a short description, or illustrations based on a body of an article.
+Developers can define new models and AI action types that use the existing AI service or even integrate additional services.
+The latter involves developing a new service connector, writing a handler that communicates with the new service, defining a new AI action type, and creating a form for configuring options, which extends the default action configuration form shown in the **Admin** panel.
+For example, if this is your organization's requirement, a developer could write a handler that uses an AI service to <insert_a description and link to Marek's use case> generate complete articles based on a short description, or illustrations based on a body of an article.
 
 ## Use cases
 
-Out of the box, the [[= product_name_base =]] AI Actions add-on comes with two action types that can help your oganization with the following tasks.
-However, before you can start using these features, some preliminary setup is required, which includes configuring access to an AI service.
+Out of the box, after you configure access to the OpenAI service, the [[= product_name_base =]] AI Actions add-on comes with two action types that can help your organization with the following tasks.
 
 ### Refining text
 
-Content editors can benefit from using AI capabilities to enhance or modify text.
+Content editors can benefit from using AI capabilities to [enhance or modify text]([[= user_doc =]]/content_management/create_edit_content_items/#ai-assistant).
 With a few clicks, they can improve content quality or reduce the workload.
-While working on content, editors can select a specific passage and request that AI performs specific actions such as: adjusting the length of the text, changing the tone, or correcting grammar and spelling errors.
+While working on content, editors can select a specific passage and request that AI performs specific actions such as: adjusting the length of the text, changing the tone, or correcting linguistic errors.
 
 ![AI Assistant](img/ai_assistant.png)
 
 With seamless with the content creation UI in mind, this functionality is available in content types that include a RichText field, and certain Page Builder blocks.
 
 ### Generating alternative text
 
-Media managers and content editors can benefit from employing AI to generate alt text for images, which results in improved accessibility and SEO.
+Media managers and content editors can benefit from employing AI to [generate alt text for images]([[= user_doc =]]/image_management/upload_images/#ai), which results in improved accessibility and SEO.
 Once the feature is configured, editors can generate alt text for images they upload to the system by clicking one button.
 
 ![Alt text generation](img/alt_text_use_ai.png)