IBX-10998: Document Gemini connector

docs/ai_actions/ai_actions_guide.md

@@ -12,7 +12,7 @@ Wherever you look, artificial intelligence becomes more and more important by en
 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 solution includes two essential components: a framework package and an OpenAI connector package.
-The Anthropic connector is also available - as an [LTS update](editions.md#lts-updates).
+The Anthropic and Gemini connectors are also available - as [LTS updates](editions.md#lts-updates).
 
 AI Actions can integrate with [[[= product_name_connect =]]]([[= connect_doc =]]/general/ibexa_connect/), to give you an opportunity to build complex data transformation workflows without having to rely on custom code.
 From the developer's perspective, the integration removes the burden of maintaining third-party AI handlers, and accelerates the deployment of AI-based solutions.

docs/ai_actions/configure_ai_actions.md

@@ -83,6 +83,114 @@
 ```
 You can now use the Anthropic connector in your project.
 
+## Install Google Gemini connector [[% include 'snippets/lts-update_badge.md' %]]
+
+Run the following command to install the package:
+
+``` bash
+composer require ibexa/connector-gemini
+```
+
+This command adds the feature code, including basic handlers that let you refine text or generate alternative text for images.
+
+### Get API key
+
+To use the connector with the Gemini services, you need to create an account, set up billing, enable Gemini API and get an API key.
+
+#### Create the Google Cloud project
+
+1. Sign in to the [Google Cloud Console](https://console.cloud.google.com/).
+1. In the top bar, click **Default Gemini Project** to open a project picker.
+1. Click **New project** and provide project details:
+    1. Add project name, for example, "My project".
+    1. Modify the automatically generated **Project ID** if necessary.
+    1. Select location: choose your organization.
+1.  Click **Create**.
+
+#### Configure billing
+
+1. Navigate to the Google Cloud Console's **Billing** page.
+1. If you do not have one, click **Add billing account** and add a payment method.
+1. In **Your projects** tab, locate your project, and in its line, from the **Actions** menu, select **Change billing**.
+1. Select your active billing account, and click **Set account**. 
+
+#### Enable the Gemini API 
+
+1. Navigate to the Google Cloud Console's **APIs & Services** page.
+1. From the left-hand menu, select **Library** and search for the Generative Language API.
+1. In the API's details page, click **Enable**.
+
+#### Generate the API key
+
+1. Go to [Google AI Studio](https://aistudio.google.com/app/api-keys)'s **API keys** page, and click **Create API key**.
+1. Provide a name for the API key, select "My project" from a list of projects and click **Create key**.
+1. Back in the **API keys** list, in your project's line, copy the API key.
+
+### Set API key in configuration
+
+Then, in the root folder of your project, modify the `.env` file: add an `GEMINI_API_KEY` variable and populate its value with the API key that you got from the AI service.
+
+```bash
+###> ibexa/connector-gemini ###
+GEMINI_API_KEY=<your_api_key>
+###< ibexa/connector-gemini ###
+```
+
+!!! note "Different API keys for different SiteAccesses"
+
+    If there are multiple SiteAccesses in your installation, you can set different API keys for each SiteAccess.
+    To do it, set the keys under the `ibexa.system.<scope>` [configuration key](configuration.md#configuration-files), like so:
+
+    ```yaml
+    ibexa:
+        system:
+            default:
+                connector_gemini:
+                    gemini:
+                        api_key: '%env(GEMINI_API_KEY)%'
+                        base_url: 'https://generativelanguage.googleapis.com/v1beta/' # Google Gemini's API endpoint
+    ```
+
+### Configure default models
+
+By default, when reaching out for responses, the Gemini connector uses the Gemini Pro [model](https://ai.google.dev/gemini-api/docs/models) for text refinement and Gemini Flash model for alternative text generation.
+Users can override this setting at runtime when they [edit or create an AI action]([[= user_doc =]]/ai_actions/work_with_ai_actions/#edit-existing-ai-actions).
+You can also change the default values globally.
+To do it, in `config/packages` folder, create a YAML file similar to this example:
+
+```yaml
+  ibexa_connector_gemini:
+    text_to_text:
+      models:
+        gemini-pro-latest:
+          label: 'Gemini Pro Latest'
+          max_tokens: 4096
+        gemini-flash-latest:
+          label: 'Gemini Flash Latest'
+          max_tokens: 4096
+      default_model: gemini-pro-latest
+      default_max_tokens: 4096   # Must be <= the model’s max_tokens
+      default_temperature: 0.8
+    image_to_text:
+      models:
+        gemini-flash-latest:
+          label: 'Gemini Flash Latest'
+          max_tokens: 4096
+      default_model: gemini-flash-latest
+      default_max_tokens: 4096
+      default_temperature: 1.0
+```
+
+When setting up models, make sure that you follow these rules:
+
+- `default_model` must reference a configured model
+- `default_max_tokens` must not exceed the model’s limit
+- If you use the same model for different action types, settings must be consistent
+
+You can now use the Gemini connector in your project.
+
+For more information, see [Extend Gemini connector](extend_ai_actions.md#extend-google-gemini-connector).
+
 ## Configure access to [[= product_name_connect =]]
 
 First, get the credentials by contacting [Ibexa Support](https://support.ibexa.co).

docs/ai_actions/extend_ai_actions.md

@@ -374,3 +374,64 @@
 Your custom Action Type is now fully integrated into the back office UI and can be used by the Editors.
 
 ![Transcribe Audio Action Type integrated into the back office](img/transcribe_audio.png "Transcribe Audio Action Type integrated into the back office")
+
+## Extend Google Gemini connector [[% include 'snippets/lts-update_badge.md' %]]
+
+The Gemini connector provides several extension points that allow you to customize available models, behavior, validation, and response handling, while remaining compatible with the AI Actions framework.
+
+The connector builds Gemini requests in an options provider and formats responses through a response formatter.
+Both components can be replaced or extended to customize how requests are constructed and how responses are normalized.
+
+### Add or customize models
+
+You can register additional Gemini models or customize existing ones by extending the connector’s model [configuration](configure_ai_actions.md#configure-default-models).
+
+Extend the models map by defining:
+
+- a human-readable label
+- a `max_tokens` limit
+
+Optionally, you can set the default model that would be used for the action type that you're modifying, the default allowed tokens limit and the default temperature.
+Default values must stay within the limits supported by the [Gemini API](https://ai.google.dev/gemini-api/docs/models).
+
+### Add a custom Action Handler
+
+To introduce a new Gemini-based AI action:
+
+1. Create a handler that extends `Ibexa\Contracts\ConnectorAi\Action\AbstractActionHandler`.
+1. Register the handler in `services/ai_action_handlers.yaml`.
+1. Provide supporting components as needed:
+    - a prompt factory
+    - a form type for configuration
+    - validators for action options
+
+This follows the same extension mechanism as other [custom AI actions](#create-custom-action-handler).
+
+### Add custom response formatting
+
+To change how Gemini responses are post-processed or normalized:
+
+1. Implement the `Ibexa\ConnectorGemini\Response\GeminiResponseFormatterInterface` interface.
+1. Alias your implementation in the service container to override the default formatter.
+
+### Add custom validation
+
+Add extra validation rules for Gemini action configuration options by tagging custom validators:
+
+- For `text-to-text` actions:
+
+    ``` yaml
+    ibexa.connector_ai.action_configuration.options.validator.gemini_text_to_text
+    ```
+
+- For `image-to-text` actions:
+
+    ``` yaml
+    ibexa.connector_ai.action_configuration.options.validator.gemini_image_to_text
+    ```
+
+### Replace the Gemini client implementation
+
+To get full control over the low-level API communication without modifying the connector itself, you can swap the Gemini client implementation entirely with your own:
+
+- Use dependency injection to bind your own implementation to `Ibexa\ConnectorGemini\Client\GeminiClientInterface`.

docs/ibexa_products/editions.md

@@ -67,4 +67,5 @@ The features brought by LTS Updates become standard parts of the next LTS releas
 | Feature | [[= product_name_headless =]] | [[= product_name_exp =]] | [[= product_name_com =]] |
 |-----------------|-----------------|-----------------|-----------------|
 | [Anthropic connector](configure_ai_actions.md#install-anthropic-connector) | ✔ | ✔ | ✔ |
+| [Google Gemini connector](configure_ai_actions.md#install-google-gemini-connector) | ✔ | ✔ | ✔ |
 | [Integrated help](integrated_help.md) | ✔ | ✔ | ✔ |

docs/release_notes/ibexa_dxp_v5.0.md

@@ -10,6 +10,16 @@ month_change: false
 
 <div class="release-notes" markdown="1">
 
+[[% set version = 'v5.0.6' %]]
+
+[[= release_note_entry_begin("Google Gemini connector " + version, '2026-02-03', ['Headless', 'Experience', 'Commerce', 'LTS Update', 'New feature']) =]]
+
+This release introduces a new AI connector that allows you to integrate [AI Actions](ai_actions.md) with [Google Gemini](https://gemini.google/overview/#what-gemini-is).
+
+For more information, see how to [install and configure the Google Gemini connector](configure_ai_actions.md#install-google-gemini-connector).
+
+[[= release_note_entry_end() =]]
+
 [[% set version = 'v5.0.5' %]]
 
 [[= release_note_entry_begin("Ibexa DXP " + version, '2026-01-15', ['Headless', 'Experience', 'Commerce']) =]]