From 81b965c393429a2c65b91b597e41f6e3621c26df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Fri, 28 Nov 2025 19:35:50 +0100 Subject: [PATCH] IBX-11003: Describe taxonomy suggestions in developer doc --- docs/content_management/taxonomy/taxonomy.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 23e4663465..ad26207339 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -112,3 +112,18 @@ The following example first lists the orphaned content items for taxonomy `tags` php bin/console ibexa:taxonomy:remove-orphaned-content tags --dry-run php bin/console ibexa:taxonomy:remove-orphaned-content tags --force ``` + +## Taxonomy suggestions + +Once the feature is enabled, with taxonomy suggestions, editors can pick from suggestions generated by an AI service based on selected fields like the product's or content item's name and description instead of having to manually browse through taxonomy trees and selecting [product categories]([[= user_doc =]]pim/work_with_product_categories/#assign-product-categories-by-editing-product-details) or [tags]([[= user_doc =]]/content_management/create_edit_content_items/#add-taxonomy-entries). + +Taxonomy suggestions build on existing [AI Actions](ai_actions_guide.md) functionality. +The `TaxonomyEmbeddingFieldProvider` uses an existing taxonomy tree as reference, generating an embedding for each path in the taxonomy tree, a multi-dimensional vector aka. embedding is generated and stored in the search index. + +When the editor creates or edits a content item or a product, they can request that the application suggests tags or product categories to be associated with the item. +When it happens, the `TextToTaxonomyActionHandler` requests that an embedding is generated based on selected fields such as name and description. +The text fields, whose values are used as source for the embedding generation, are defined when you create an [AI action](https://doc.ibexa.co/projects/userguide/en/latest/ai_actions/work_with_ai_actions/#create-ai-actions-that-use-ibexa-connect) that uses the `openai-text-to-taxonomy-entries handler`. + +The search engine then compares the generated embedding with the taxonomy path embeddings stored in its index. +It selects the three best-matching taxonomy paths and presents them to the editor as suggestions. +The user can accept the suggestions, reject them, or request a new set of suggestions directly from the user interface.