Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use absolute link to PHP API Ref #2669

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions docs/ai_actions/extend_ai_actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@

## Execute Actions

You can execute AI Actions by using the [ActionServiceInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionServiceInterface.html) service, as in the following example:
You can execute AI Actions by using the [ActionServiceInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionServiceInterface.html) service, as in the following example:

Check failure on line 14 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L14

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 14, "column": 105}}}, "severity": "ERROR"}

``` php
[[= include_file('code_samples/ai_actions/src/Command/AddMissingAltTextCommand.php', 102, 121) =]]
```

The `GenerateAltTextAction` is a built-in action that implements the [ActionInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionInterface.html), takes an [Image](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-DataType-Image.html) as an input, and generates the alternative text in the response.
The `GenerateAltTextAction` is a built-in action that implements the [ActionInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionInterface.html), takes an [Image](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-DataType-Image.html) as an input, and generates the alternative text in the response.

Check failure on line 20 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L20

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 20, "column": 127}}}, "severity": "ERROR"}

This action is parameterized with the [RuntimeContext](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-RuntimeContext.html) and the [ActionContext](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-ActionContext.html), which allows you to pass additional options to the Action before it's executed.
This action is parameterized with the [RuntimeContext](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-RuntimeContext.html) and the [ActionContext](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-ActionContext.html), which allows you to pass additional options to the Action before it's executed.

Check failure on line 22 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L22

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 22, "column": 95}}}, "severity": "ERROR"}

| Type of context | Type of options | Usage | Example |
|---|---|---|---|
Expand All @@ -28,17 +28,17 @@
| Action Context | Action Handler options | Sets additional parameters for the Action Handler | Information about the model, temperature, prompt, and max tokens allowed |
| Action Context | System options | Sets additional information, not matching the other option collections | Information about the fallback locale |

Both `ActionContext` and `RuntimeContext` are passed to the Action Handler (an object implementing the [ActionHandlerInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-ActionHandlerInterface.html)) to execute the action. The Action Handler is responsible for combining all the options together, sending them to the AI service and returning an [ActionResponse](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionResponseInterface.html).
Both `ActionContext` and `RuntimeContext` are passed to the Action Handler (an object implementing the [ActionHandlerInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-ActionHandlerInterface.html)) to execute the action. The Action Handler is responsible for combining all the options together, sending them to the AI service and returning an [ActionResponse](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionResponseInterface.html).

Check failure on line 31 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L31

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 31, "column": 168}}}, "severity": "ERROR"}

You can pass the Action Handler directly to the `ActionServiceInterface::execute()` method, which overrides all the other ways of selecting the Action Handler.
You can also specify the Action Handler by including it in the provided [Action Configuration](#action-configurations).
In other cases, the Action Handler is selected automatically.
You can affect this choice by creating your own class implementing the [ActionHandlerResolverInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-ActionHandlerResolverInterface.html) or by listening to the [ResolveActionHandlerEvent](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Events-ResolveActionHandlerEvent.html) Event sent by the default implementation.
You can affect this choice by creating your own class implementing the [ActionHandlerResolverInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-ActionHandlerResolverInterface.html) or by listening to the [ResolveActionHandlerEvent](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Events-ResolveActionHandlerEvent.html) Event sent by the default implementation.

Check failure on line 36 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L36

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 36, "column": 144}}}, "severity": "ERROR"}

You can influence the execution of an Action with two events:

- [BeforeExecuteEvent](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-Event-BeforeExecuteEvent.html), fired before the Action is executed
- [ExecuteEvent](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-Event-ExecuteEvent.html), fired after the Action is executed
- [BeforeExecuteEvent](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-Event-BeforeExecuteEvent.html), fired before the Action is executed

Check failure on line 40 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L40

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 40, "column": 63}}}, "severity": "ERROR"}
- [ExecuteEvent](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-Event-ExecuteEvent.html), fired after the Action is executed

Check failure on line 41 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L41

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 41, "column": 57}}}, "severity": "ERROR"}

Below you can find the full example of a Symfony Command, together with a matching service definition.
The command finds the images modified in the last 24 hours, and adds the alternative text to them if it's missing.
Expand All @@ -61,13 +61,13 @@
Action Configurations allow you to store the parameters for a given Action in the database and reuse them when needed.
They can be managed [through the back office]([[= user_doc =]]/ai_actions/work_with_ai_actions/), [data migrations](importing_data.md#ai-action-configurations), or through the PHP API.

To manage Action Configurations through the PHP API, you need to use the [ActionConfigurationServiceInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfigurationServiceInterface.html) service.
To manage Action Configurations through the PHP API, you need to use the [ActionConfigurationServiceInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfigurationServiceInterface.html) service.

Check failure on line 64 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L64

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 64, "column": 151}}}, "severity": "ERROR"}

You can manage them using the following methods:

- Creating them with `ActionConfigurationServiceInterface::createActionConfiguration()` by passing the [ActionConfigurationCreateStruct](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfiguration-ActionConfigurationCreateStruct.html).
- Updating them with `ActionConfigurationServiceInterface::updateActionConfiguration()` by passing the [ActionConfigurationUpdateStruct](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfiguration-ActionConfigurationUpdateStruct.html).
- Deleting them with `ActionConfigurationServiceInterface::deleteActionConfiguration()` by passing the [ActionConfigurationInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfigurationInterface.html).
- Creating them with `ActionConfigurationServiceInterface::createActionConfiguration()` by passing the [ActionConfigurationCreateStruct](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfiguration-ActionConfigurationCreateStruct.html).

Check failure on line 68 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L68

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 68, "column": 177}}}, "severity": "ERROR"}
- Updating them with `ActionConfigurationServiceInterface::updateActionConfiguration()` by passing the [ActionConfigurationUpdateStruct](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfiguration-ActionConfigurationUpdateStruct.html).

Check failure on line 69 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L69

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 69, "column": 177}}}, "severity": "ERROR"}
- Deleting them with `ActionConfigurationServiceInterface::deleteActionConfiguration()` by passing the [ActionConfigurationInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfigurationInterface.html).

Check failure on line 70 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L70

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 70, "column": 174}}}, "severity": "ERROR"}

See the [AI Actions event reference](ai_action_events.md#action-configurations-management) for a list of events related to these operations.

Expand All @@ -91,7 +91,7 @@
[[= include_file('code_samples/ai_actions/src/Command/ActionConfigurationCreateCommand.php', 77, 85) =]]
```

The passed Action Configuration is only taken into account if the Action Context was not passed to the Action directly using the [ActionInterface::setActionContext()](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionInterface.html#method_hasActionContext) method.
The passed Action Configuration is only taken into account if the Action Context was not passed to the Action directly using the [ActionInterface::setActionContext()](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionInterface.html#method_hasActionContext) method.

Check failure on line 94 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L94

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 94, "column": 207}}}, "severity": "ERROR"}
The `ActionServiceInterface` service extracts the configuration options from the Action Configuration object and builds the Action Context object internally:

- Action Type options are mapped to Action Type options in the Action Context
Expand All @@ -106,7 +106,7 @@

### Register a custom Action Handler in the system.

Create a class implementing the [ActionHandlerInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-ActionHandlerInterface.html) and register it as a service:
Create a class implementing the [ActionHandlerInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-ActionHandlerInterface.html) and register it as a service:

Check failure on line 109 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L109

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 109, "column": 97}}}, "severity": "ERROR"}

- The `ActionHandlerInterface::supports()` method decides whether the Action Handler is able to execute given Action.
- The `ActionHandlerInterface::handle()` method is responsible for combining all the Action options together, sending them to the AI service and forming an Action Response.
Expand Down Expand Up @@ -151,7 +151,7 @@
![Custom Action Handler options rendered using the default Twig options formatter](img/action_handler_options.png "Custom Action Handler options rendered using the default Twig options formatter")


You can create your own formatting by creating a class implementing the [OptionsFormatterInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfiguration-OptionsFormatterInterface.html) interface and aliasing it to `Ibexa\Contracts\ConnectorAi\ActionConfiguration\OptionsFormatterInterface`.
You can create your own formatting by creating a class implementing the [OptionsFormatterInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionConfiguration-OptionsFormatterInterface.html) interface and aliasing it to `Ibexa\Contracts\ConnectorAi\ActionConfiguration\OptionsFormatterInterface`.

Check failure on line 154 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L154

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 154, "column": 140}}}, "severity": "ERROR"}

The following service definition switches the options rendering to the other built-in options formatter, displaying the options as JSON.

Expand All @@ -168,7 +168,7 @@

### Create custom Action Type

Start by creating your own Action Type, a class implementing the [ActionTypeInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionType-ActionTypeInterface.html).
Start by creating your own Action Type, a class implementing the [ActionTypeInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionType-ActionTypeInterface.html).

Check failure on line 171 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L171

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 171, "column": 127}}}, "severity": "ERROR"}
The class needs to define following parameters of the Action Type:

- name
Expand All @@ -188,7 +188,7 @@
The service definition introduces a custom `app.connector_ai.action.handler.audio_to_text` service tag to mark all the handlers capable of working with this Action Type.
The `ibexa.ai.action.type` service tag registers the class in the service container as a new Action Type.

If the Action Type is meant to be used mainly with prompt-based systems you can use the [LLMBaseActionTypeInterface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-LLMBaseActionTypeInterface.html) interface as the base for your Action Type.
If the Action Type is meant to be used mainly with prompt-based systems you can use the [LLMBaseActionTypeInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-Action-LLMBaseActionTypeInterface.html) interface as the base for your Action Type.

Check failure on line 191 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L191

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 191, "column": 157}}}, "severity": "ERROR"}
It allows you to define a base prompt directly in the Action Type that can be common for all Action Configurations.

Action Type names can be localized using the Translation component.
Expand All @@ -198,13 +198,13 @@

The `TranscribeAudio` Action Type requires adding two data classes that exist in its definition:

- an `Audio` class, implementing the [DataType interface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-DataType.html), to store the input data for the Action
- an `Audio` class, implementing the [DataType interface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-DataType.html), to store the input data for the Action

Check failure on line 201 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L201

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 201, "column": 98}}}, "severity": "ERROR"}

``` php
[[= include_file('code_samples/ai_actions/src/AI/DataType/Audio.php') =]]
```

- an `TranscribeAudioAction` class, implementing the [ActionInterface interface](../api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionInterface.html). Pass this object to the `ActionServiceInterface::execute()` method to execute the action.
- an `TranscribeAudioAction` class, implementing the [ActionInterface interface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ConnectorAi-ActionInterface.html). Pass this object to the `ActionServiceInterface::execute()` method to execute the action.

Check failure on line 207 in docs/ai_actions/extend_ai_actions.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/ai_actions/extend_ai_actions.md#L207

[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'
Raw output
{"message": "[Ibexa.VariablesGlobal] Use global variable '[[= product_name_base =]]' instead of 'Ibexa'", "location": {"path": "docs/ai_actions/extend_ai_actions.md", "range": {"start": {"line": 207, "column": 121}}}, "severity": "ERROR"}

``` php
[[= include_file('code_samples/ai_actions/src/AI/Action/TranscribeAudioAction.php') =]]
Expand Down
Loading