AI criteria
AI criteria narrow a dynamic category with a description in your own words. The category's conditions select the candidates, and an AI model judges each candidate against the criteria: the products that fit stay in the category, the others are removed.
The model is the one set up in Stores -> Configuration -> Mirasvit Extensions -> Developer -> AI Configuration. Without a provider set up there, a category with AI criteria is filled by its conditions alone, and the category form says so.
For the steps to set up a category, see how to narrow a dynamic category with AI criteria.
Fields
The fields are in the Products in Category section of a dynamic category, below the conditions.
- AI criteria: turns the criteria on for the category.
- Criteria: one to a few sentences that describe the products the category should hold. Exclusions work too, for example "not alcohol".
Both fields can be set per store view. A product stays in the category only when every store view with criteria keeps it, because a category holds the same products in all store views.
How a category is narrowed
Saving a category with AI criteria starts a background pass:
- The pass collects the products the conditions select.
- It sends the candidates that have not been judged yet to the AI provider, 20 products per request.
- When every candidate is judged, the category holds the products the model kept and is reindexed.
Until a pass completes, the category keeps the products it had. The first pass on a category therefore does not empty it while it runs.
Each judgement is stored for the product's text, the criteria and the store view's locale. A later pass, or another category with the same criteria, sends only products that are new or whose text changed, so a product is paid for once. A product whose judgement failed is sent again on the next pass.
The model gives each product a match from 0 to 100, and a product with a match of 50 or more is kept. A product whose text does not say what kind of product it is, for example one with no description, is not judged and stays out of the category.
Passes also run on the Pass schedule in the settings, hourly by default, to judge new and edited products.
Passes run in the mstDynamicCategoryAiPassProcessor queue consumer, which Magento's cron starts. If your store doesn't run consumers from cron, start it yourself:
php bin/magento queue:consumers:start mstDynamicCategoryAiPassProcessor --single-thread
One pass runs at a time, including on several servers that share the database. The pass takes its lock in the database, whatever lock provider app/etc/env.php sets (for example file or Zookeeper).
How long a pass takes
A request of 20 products takes about 11–18 seconds with gpt-4o-mini, so a pass judges about 5,000 candidates an hour. A first pass over a large catalog can take a few hours; later passes send only new or changed products and are much shorter.
Status of the pass
The status block in the Products in Category section shows the pass while it runs: candidates collected, then candidates judged, tokens spent, when it started and when it last advanced.
When the pass completes, the block shows the last pass's outcome: the number of candidates, products added and removed, tokens spent and how long it took. Each new pass starts these figures again.
When a pass fails, for example because the AI provider refuses the API key, the block shows the provider's message as the cause, and the category keeps its products. Fix the cause, then click Resume: candidates already judged are not sent again. The tokens the block then shows count only the run that resumed the pass, not what the failed run spent. Saving the category, or the next scheduled pass, also starts it again.
Preview Products
Preview Products judges a random sample of 25 of the candidates against the criteria in the form, saved or not, and opens the list of judgements for the sample. A first preview takes about 15–20 seconds. A preview repeated with the same criteria sends nothing for products already judged.
A preview doesn't change the category: it keeps its products until the criteria are saved and a pass completes. While a Re-judge All is under way, a preview shows the stored judgements.
Under the criteria, the form also shows how many products the conditions select and how many are still to judge. These counts follow your edits before you save, and they make no AI request.
Judgements list
See how each candidate was judged, in the status block, opens the list of every candidate the conditions select, kept and removed alike. For each product and store view it shows the verdict (Kept, Removed, Not judged or Waiting), the Confidence (the match), the reason the model gave, and whether the AI or an admin decided. The list can be filtered by verdict.
The reason is written in the language of the store view's locale.
Re-judge All
Re-judge All, next to Preview Products, judges every candidate of the category again against the saved criteria, which spends tokens. Use it after you change the AI model: stored judgements are reused whatever model gave them, so a new model judges only products that are new or changed until you re-judge. The category keeps its products until the pass completes.
Products added or removed by hand
When Allow manual product assignment is on, you can still add and remove products by hand:
- A product added by hand stays in the category whatever the model says.
- A product removed by hand from a category a pass has already narrowed stays out on later passes.
Permissions
The criteria are covered by their own ACL resource, Dynamic Category AI Criteria (Mirasvit_DynamicCategory::ai_criteria), under Catalog -> Inventory -> Categories. Custom admin roles and integrations need it to see or change the criteria:
- An admin role without it doesn't see the criteria fields, and a category it saves keeps the criteria it had.
- An integration without it gets a
401error when a category save sends the criteria, or when a category list filters or sorts by them.
Adobe Commerce scheduled updates
On Adobe Commerce, the AI criteria are not part of a scheduled update:
- Schedule New Update doesn't show the criteria. Every category save, except one by an admin role without the AI criteria permission, makes the criteria of the category's later scheduled versions match the version it saved, so an update never brings back older criteria. That includes saves by cron, the command line and imports.
- Criteria saved into an update's version through the API are replaced by the next save of an earlier version.
- A store-view save by a role without the AI criteria permission also makes later versions match. Its changes are saved by a queue consumer, outside the admin, and only the current values are copied.
- No pass runs when an update starts. The next scheduled pass judges the category.