yu-dev/module-ai-catalog-search

Magento 2 AI catalog search: an LLM turns natural-language storefront queries into keywords and filters, applied either to the native search page (Native mode) or a dedicated AI results page with real-facet suggestions (AI mode).

Maintainers

Package info

github.com/yuriyakishin/magento2-ai-catalog-search

Type:magento2-module

pkg:composer/yu-dev/module-ai-catalog-search

Transparency log

Statistics

Installs: 8

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.2 2026-07-28 18:32 UTC

Requires

MIT 28915e6641be24f76ccf16da9dd51a5242c78fce

ecommercesearchelasticsearchmagentoopensearchnlpaimagento2Geminigrokopenaillmclaudeproduct-searchcatalog-searchnatural-language-search

Published on Packagist.org on 2026-07-28 18:32 UTC

This package is auto-updated.

Last update: 2026-07-28 18:35:13 UTC

README

Live demo

🔗 Demo: yu.net.ua

Magento's native search matches literally on words: a customer who types "red jacket for men under $50" gets results for that exact phrase — Magento doesn't understand that "red" is a color, "for men" is a catalog section, and "$50" is a price ceiling, unless the customer opens the filters manually and sets them himself. Yu_AiCatalogSearch plugs AI straight into the storefront search box: a plain-language query turns itself into the right filters.

What the customer sees

The customer just types a query as usual:

"red jacket for men under $50" → the AI figures out on its own: color — red, category — men's, price — under $50, and applies it as ordinary search filters.

Two modes — the merchant's choice

The module offers two ways to show the result — switched by a single field in the admin panel:

  • Native (default) — the customer lands on Magento's regular search results page, with the usual filter navigation on the left, just with the right filters already applied. Fully native storefront look, zero visual difference from the theme — the safest option to roll out.

    Native mode — the regular search results page with filters already applied

  • AI — the customer lands on a dedicated page with AI-picked suggestion chips above the results ("Only red", "Under $40"), built from the actual product stock in the current result set rather than a static filter tree — so a suggestion never leads to an empty page. The product grid itself stays fully native: colors, swatches, wishlist, compare, sorting — all as usual.

    AI mode — a dedicated page with AI suggestions above the results

If the AI is unavailable for any reason, or fails to parse the query, search simply works as usual, unchanged — the customer won't even notice.

Features

  • Understands attributes, category and price in a single query, in whatever language the customer uses.
  • Never breaks plain text search — if the query carries no filters, nothing changes compared to regular search.
  • Query-parse caching — identical queries don't spend a repeat AI call.
  • Query log — every parse is recorded (what the customer typed, what the AI recognized, the cost of the call).
  • Never touches catalog settings — the module only reads which attributes the merchant has configured as filterable, and never changes those settings itself.

Requirements

  • PHP >= 8.1
  • Magento 2.4.x with Elasticsearch/OpenSearch configured
  • The Yu_AiLlm and Yu_AiSearchEngine modules (installed automatically as dependencies)
  • An API key for at least one supported LLM provider

Installation

composer require yu-dev/module-ai-catalog-search
bin/magento module:enable Yu_AiLlm Yu_AiSearchEngine Yu_AiCatalogSearch
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The module is installed disabled — search behavior won't change until you enable it in the admin panel and configure at least one LLM provider.

Configuration

Stores → Configuration → Search Product AI → General

  • Enable AI Search — the main switch.
  • Results Mode — Native or AI, see above.
  • Minimum Query Length — queries shorter than this aren't sent to the AI (e.g. single letters or product codes).
  • Parse Timeout — how long to wait for the AI's answer before falling back to unmodified regular search.
  • Parse Cache Lifetime — how long to remember the parse of identical queries.
  • Log Search Queries — keep a query log.

For Native mode to work fully, the merchant's catalog needs Magento's own "Use in Search Results Layered Navigation" setting enabled for the relevant attributes and for price (Stores → Attributes → Product → the attribute in question) — without it the AI still understands the query just fine, but can't apply the filter as a separate parameter, and instead just folds it into the keyword search. AI mode needs no such setting.

A category the AI is expected to recognize in a query (e.g. "for men", "women's") must be marked as Anchor (Catalog → Categories → the category → Display Settings → Is Anchor). Without this flag the category doesn't participate in search — the AI simply can't apply it as a filter, even when it correctly reads the customer's intent.

The LLM provider (OpenAI, Anthropic Claude, Google Gemini, xAI Grok and others) is configured once, in Stores → Configuration → AI → LLM AI — this section is shared across all AI modules on the store, including Yu_AiChat.

Author

Yuriy Akishin:

License

MIT