Product Search settings
Navigation: WordPress Admin → WooCommerce → AI Assistant → Product Search
WooCommerce always retrieves products. AI is optional.
Search mode
What it does Chooses the retrieval strategy label. Live catalog rows always come from WooCommerce (or, for Hybrid, from WooCommerce plus optional developer-supplied IDs).
Default value automatic — Automatic (recommended).
Available options
| Value | Label | What actually runs |
|---|---|---|
automatic | Automatic (recommended) | Native WooCommerce search. AI intent may run for complex queries if a key exists and Enable AI query understanding is on. |
native | Native WooCommerce | Rule-based WooCommerce search only. AI intent is disabled. |
ai | AI-assisted | Same catalog pipeline as Automatic. AI intent is allowed (subject to the toggles below). There is no separate “AI replaces WooCommerce” engine. |
hybrid | Semantic / Hybrid | Native catalog plus semantic candidate IDs only if a developer hooks aiwsa_semantic_search_available to true and returns IDs via aiwsa_semantic_search_ids. This plugin does not ship a vector index. Without that hook, Hybrid behaves like native catalog retrieval. |
Recommended configuration Automatic.
When to use it Use Native to avoid extra AI spend. Do not expect Hybrid to “turn on embeddings” by itself.
Effect on the frontend Shoppers see product cards from wc_get_products (with ranking). Semantic IDs, if any, are re-fetched as live WooCommerce products; stale IDs are dropped.
Dependencies Search tool Enable product search (on by default).
Important notes Semantic search is an integration point, not a finished merchant feature.
Example Automatic + AI key: “red running shoes under $80” may get an intent parse, then WooCommerce filters. “nike shoes” stays on keywords if AI for complex queries only is on.
Enable AI query understanding
What it does Allows one extra AI call that turns a natural-language search into structured filters (price, category, attributes). Simple keywords stay on WooCommerce.
Default value On.
Available options On / Off. Hidden if a licence filter disables search_ai_intent.
Recommended configuration On when you have an API key; Off to save tokens.
When to use it Queries like “something waterproof under 50 for hiking”.
Effect on the frontend Better filter interpretation when the call succeeds. Failures fall back to WooCommerce search.
Dependencies API key, Search mode not Native, feature gate search_ai_intent.
Important notes A licence plugin can disable this. Catalog search still runs.
Example On for a fashion store with lots of attribute filters.
AI for complex queries only
What it does Skips the AI intent call for short keyword searches such as “nike shoes”.
Default value On.
Available options On / Off.
Recommended configuration On.
When to use it Keep On to control cost. Off if almost every query is a long sentence.
Effect on the frontend Short queries are faster (no extra round trip).
Dependencies Enable AI query understanding.
Important notes “Simple” means: shorter than the minimum length, or up to 3 tokens without constraint words (under, waterproof, $99, etc.). Structured tool args (price already set) also skip AI.
Example “OEG Parts New 12V Starter Motor” as an exact title is handled by native catalog search, not by inventing a category.
Minimum query length
What it does AI intent is not used below this character length.
Default value 4
Available options 2–40
Recommended configuration 4
When to use it Raise it if you see wasted AI calls on tiny strings.
Effect on the frontend Short strings go straight to WooCommerce.
Dependencies AI query understanding.
Important notes Applies to the leftover query after rule-based parsing.
Example Leave at 4.
Maximum results
What it does Number of product cards returned after ranking.
Default value 8
Available options 1–24
Recommended configuration 6–8 on mobile-friendly chats.
When to use it Lower for a boutique; higher for a large catalog (still capped).
Effect on the frontend Fewer or more cards in the chat.
Dependencies None.
Important notes The engine may retrieve a larger candidate window internally, then slice to this number.
Example 8 for a general store.
Include out-of-stock products
What it does When off, in-stock products are preferred and out-of-stock rows are excluded unless the shopper asks for them. When on, out-of-stock products may appear (with Notify me).
Default value Off.
Available options On / Off.
Recommended configuration Off for conversion; On if you sell preorders and want visibility.
When to use it Catalogs with many missing _stock_status meta values are still treated as in-stock (the query layer allows missing/empty stock meta).
Effect on the frontend Off: mostly purchasable cards. On: more cards, some with stock alerts.
Dependencies WooCommerce stock settings.
Important notes Default stock filter is instock unless this is on.
Example Keep Off for a parts shop that should not push unavailable motors.
Show match explanations
What it does Adds a short reason on product cards using only WooCommerce fields. No extra AI call.
Default value On.
Available options On / Off. Licence-gated as search_match_explanation.
Recommended configuration On.
When to use it Helps shoppers see why a card matched (category, keyword, price).
Effect on the frontend Small explanation text on cards.
Dependencies Feature gate.
Important notes Filter aiwsa_search_explanation can change the text.
Example On for a store with overlapping categories.
Intent cache duration (hours)
What it does Repeated queries reuse the last AI interpretation.
Default value 6
Available options 1–168 hours (clamped in code; TTL between 5 minutes and 7 days).
Recommended configuration 6
When to use it Busy stores with repeated phrases.
Effect on the frontend Faster repeat searches; cached filters may lag if you rename attributes.
Dependencies AI query understanding.
Important notes Cache is keyed without shopper PII.
Example 6 hours on a mid-size shop.
Fallback to WooCommerce search
What it does When exact filters match nothing, show similar catalog products instead of an empty list.
Default value On.
Available options On / Off.
Recommended configuration On.
When to use it Avoid “no products” when a guessed category was too strict. The search tool already drops over-aggressive category guesses on long titles.
Effect on the frontend More “similar products” and fewer empty states.
Dependencies None.
Important notes This is catalog fallback, not AI fallback copy.
Example On for a catalog with messy categories.
AI request timeout (seconds)
What it does Timeout for the intent-parse call. 0 uses the provider timeout. Failed or slow AI calls fall back to WooCommerce search.
Default value 0
Available options 0–60 (effective timeout is clamped 5–60 when an override is set).
Recommended configuration 0
When to use it Set 8–15 if intent calls stall the chat.
Effect on the frontend Shoppers still get native results after a timeout.
Dependencies AI provider.
Important notes Does not replace the main chat timeout.
Example 0 on a reliable OpenAI connection.
Search tools
Same page, second card. Tools default to enabled when unset.
Enable product search (search_products)
Lets the assistant look up products by query, SKU, category, attributes, and price.
Default: On.
If Off, catalog search from chat is blocked.
Enable category listing (list_categories)
Lets the assistant list store categories when a shopper asks what you sell.
Default: On.