Skip to content

Commit 2188724

Browse files
dabrtdabrt
committed
IBX-8689: AI Actions documentation
1 parent 2a02aa6 commit 2188724

File tree

8 files changed

+235
-0
lines changed

8 files changed

+235
-0
lines changed

‎docs/ai_actions/ai_actions.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
description: AI Actions help editors by automating repetitive tasks.
3+
page_type: landing_page
4+
---
5+
6+
# AI Actions
7+
8+
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.
9+
Potentially, you can use AI for transforming text passages, generating illustrations for your articles based on a prompt, and so on.
10+
11+
[[= cards([
12+
"ai_actions/ai_actions_guide",
13+
"ai_actions/install_ai_actions",
14+
"ai_actions/extend_ai_actions"
15+
], columns=4) =]]
16+
17+
## Alt text generation
18+
19+
[[= cards([
20+
"ai_actions/alt_text/enable_alt_text_generation",
21+
"ai_actions/alt_text/configure_alt_text_generation",
22+
"ai_actions/alt_text/customize_alt_text_generation"
23+
], columns=4) =]]
24+
25+
## Explore AI Actions API
26+
27+
...

‎docs/ai_actions/ai_actions_guide.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
description: AI Actions add-on helps editors by automating repetitive tasks.
3+
---
4+
5+
# AI Actions product guide
6+
7+
## What are AI Actions
8+
9+
In the evolving landscape of digital experience, artificial intelligence becomes more and more important by enhancing user interaction and automating complex tasks.
10+
To harness AI's potential, [[= product_name =]] introduces th AI Actions add-on, which you can install and use to automate various time-consuming tasks, for example, generating alt text for images.
11+
12+
Built upon the PHP framework, AI Actions offer an extensible solution for integrating services provided by AI engines into your workflows, all managed through a user-friendly interface.
13+
14+
You can extend the add-on and make it do different things, for example, transform text passages, or generate illustrations for your articles based on a prompt.
15+
The possibilities are endless.
16+
17+
## Availability
18+
19+
AI Actios are available as an add-on to the v.4.6.x version of [[= product_name =]], regardless of its edition.
20+
To use it's capabilities you must install the package and perform initial configuration.
21+
22+
## How it works
23+
24+
### The core concepts
25+
26+
#### Actions
27+
28+
Actions are tasks or functions that the AI is set to perform.
29+
Each Action is a combination of an action type and an action configuration.
30+
Action types define what kind of task the AI will perform, while the action configuration specifies how the task should be executed.
31+
This clear separation allows for a flexible system where actions can be easily created, managed, and customized.
32+
33+
#### Action types
34+
35+
Action types are predefined by developers within YAML configuration.
36+
Each action type defines the structure and nature of the task that the AI engine performs.
37+
Action types could be designed to generate alt text for images, summarize a passage of text, or even translate content into another language.
38+
By defining action types in YAML, developers can create a wide range of functionalities that can be easily deployed within the application.
39+
40+
#### Action configurations
41+
42+
AAction configurations let administrators employ action types to generate actions.
43+
Action configurations are managed in the [Admin Panel](admin_panel.md), and allow administrators to customize and fine-tune the behavior of each action.
44+
This might involve setting parameters for the AI, defining specific inputs, or configuring how the output should be handled.
45+
By adjusting these configurations, administrators can ensure that the actions are tailored to meet their requirements.
46+
47+
#### Handlers
48+
49+
Once an action is defined and configured, it must be executed, and this is where handlers come into play.
50+
Handlers are pieces of PHP code that are responsible for resolving an action.
51+
Each handler is designed to work with a specific AI engine and action type pair.
52+
Handlers may include hardcoded prompts for conversational AI engines like ChatGPT, or they may operate without prompts for other types of AI.
53+
Handlers take configurations 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 engine for processing.
54+
55+
### Triggering actions from the UI
56+
57+
Among other components, AI Actions add-on brings action management in Admin Panel and alt-text generation feature in image management UI.
58+
Both these areas are user-friendly and well integrated with the application’s UI.
59+
Administrators can manage atcion configurations with ease, while end-users can trigger actions by simply clicking a button.
60+
Processes are straightforward and intuitive, ensuring that users can quickly and easily achieve their desired outcomes.
61+
62+
### Triggering actions programmatically
63+
64+
AI Actions add-on exposes an API that allows for programmatic execution of actions.
65+
With the API, developers can automate tasks and execute actions on batches of content by integrating them into workflows.
66+
By issuing commands through the API, developers can trigger actions based on external events:
67+
...
68+
69+
## Capabilities and use cases
70+
71+
### Management
72+
73+
...
74+
75+
### Extensibility
76+
77+
Built-in action types offer a good starting point, but the real power of AI Actions lies in extensibility.
78+
Extending AI Actions opens up new possibilities for content management and editing.
79+
Developers can extend the feature by adding new action types that use existing AI engines or even integrating additional AI services.
80+
This involves defining a new action type in YAML, writing a handler that communicates with the new service or engine, and creating a form for configuring the options that extends the action configuration form shown in the Admin Panel.
81+
For example, a developer could write a handler that uses an AI service to shorten or expand text passages, or generate illustrations based on a body of an article.
82+
83+
### Use cases
84+
85+
#### ...
86+
87+
#### Generating Alt Text
88+
89+
Out of the box, the [[= product_name_base =]] AI Actions add-on comes with the generating alt text for images capability.
90+
Organizations can benefit from it's use by improving accessibility and SEO.
91+
Once the feature is configured, editors can generate alt text for images they upload to the system by clicking one button, while administrators can use the API to run a batch process against a larger collection of illustrations.
92+
Before you can start generating alt text, some preliminary setup is required, which includes configuring access to an AI engine.

‎docs/ai_actions/alt_text/configure_alt_text_generation.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
description: Configure alt text generation to match your needs.
3+
---
4+
5+
# Configuree alternative text generation
6+
7+
Once you've enabled alt text generation, you can fine-tune the output to match technical requirements of your application or your company's voice and style.
8+
You can modify the settings of individual action configurations by selecting the preferred language, tone, and temperature, along with other customizable settings to ensure the generated alt text meets your specific needs.
9+
10+
## Configure action configurations
11+
12+
...

‎docs/ai_actions/alt_text/customize_alt_text_generation.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
description: Add custom features to alternative text generation for images.
3+
---
4+
5+
# Customize alternative text generation
6+
7+
If you need more control over the alt text generation feature, you can customize, for example, by integrating a different AI engine, and modifying the default behavior.
8+
9+
## Add custom glossaries
10+
11+
You can enhance the relevance of alt text or apply jargon specific for your company.
12+
One way to do it is by creating lists of specific keywords or phrases that should either always be included (whitelist) or avoided (blacklist) in the generated descriptions.
13+
14+
...
15+
16+
## Integrate a different AI engine
17+
18+
If the default AI engine doesn’t meet your requirements, you can connect to a different AI service.
19+
To do it, you must configure API endpoints, input formats, and authentication details for the new engine.
20+
21+
...

‎docs/ai_actions/alt_text/enable_alt_text_generation.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
description: Configure your application to enable generating alternative text for images.
3+
---
4+
5+
# Enable alternative text generation
6+
7+
With this feature you can enhance accessibility and streamline your content creation process by generating alternative text for images in `ezimage` and `ezimageasset` fields by using the image analysis AI.
8+
Before you can use the feature, you must enable automated alt text generation by setting up a connection with an external AI service.
9+
10+
## Get authentication parameters
11+
12+
First, either you or another [[= product_name_base =]] user responsible for managing the [[= product_name =]] instance must ...
13+
14+
## Ensure you account has credits
15+
16+
...
17+
18+
## Set up API key
19+
20+
When you receive the credentials, add them to your configuration.
21+
In the root folder of your project, edit the `<ADD FILE NAME>` file by adding the following lines with your customer ID and license key:
22+
23+
```
24+
...
25+
...
26+
```
27+
28+
!!! note "Configuring user credentials for different engines"
29+
30+
If your installation supports [multiple AI engines](extend_ai_actions.md) that perform the same AI action, you must provide credentials for each of these engines.
31+
Otherwise some of the AI Actions will remain inactive.
32+
33+
## ...

‎docs/ai_actions/extend_ai_actions.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Extend AI Actions by connecting to other engines and adding new capabilities.
3+
---
4+
5+
# Extend AI Actions
6+
7+
By extending AI Actions you can enhance the attractiveness of mundane content management and editing tasks and make them less burdensome.
8+
You can start from adding new action types that use the existing AI engine, and evolve to integrating additional AI services with completely new areas of application.
9+
For example, you could write a handler that connects to a translation model and use it to translate your website on-the-fly, or generate illustrations based on a body of an article.
10+
11+
## ...

‎docs/ai_actions/install_ai_actions.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: Install the AI Actions add-on.
3+
---
4+
5+
# Install AI Actions
6+
7+
AI Actions are available as an add-on to the v.4.6.x version of [[= product_name =]] or higher, regardless of its edition.
8+
To use this feature you must first install the add-on and then configure it YAML configuration.
9+
10+
## Install AI Actions
11+
12+
Ibexa Engage is available from v4.6.x of [[= product_name =]].
13+
Run the following command to install the bundle:
14+
15+
`composer require ibexa/connector-ai`
16+
17+
This command adds the code, Twig templates and configuration files required for using AI Actions, and modifies the permission system to account for the new functionality.
18+
19+
To check for the presence of AI Actions in your application, run the following command:
20+
21+
`composer show | grep "ibexa/connector-ai"`
22+
23+
## Prepare configuration files
24+
25+
When you install AI Actions add-on, it modifies the YAML configuration files by adding configuration keys similar to this example:
26+
27+
```yaml
28+
...
29+
30+
```

‎mkdocs.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -318,6 +318,15 @@ nav:
318318
- Add login form: templating/layout/add_login_form.md
319319
- Add navigation menu: templating/layout/add_navigation_menu.md
320320
- Add search form to front page: templating/layout/add_search_form.md
321+
- AI Actions:
322+
- AI Actions: ai_actions/ai_actions.md
323+
- AI Actions Guide: ai_actions/ai_actions_guide.md
324+
- Install AI Actions: ai_actions/install_ai_actions.md
325+
- Extend AI Actions: ai_actions/extend_ai_actions.md
326+
- Alt text generation:
327+
- Enable alt text generation: ai_actions/alt_text/enable_alt_text_generation.md
328+
- Configure alt text generation: ai_actions/alt_text/configure_alt_text_generation.md
329+
- Customize alt text generation: ai_actions/alt_text/customize_alt_text_generation.md
321330
- PIM (Product management):
322331
- PIM (Product management): pim/pim.md
323332
- PIM guide: pim/pim_guide.md

0 commit comments

Comments
 (0)