Product search
Product search is how the assistant finds real things to show a shopper. It reads your live catalogue, never its own memory, and turns matches into rich cards a customer can act on without leaving the chat.
What the assistant searches with
The assistant calls a single grounded tool, search_products, before it recommends anything. That tool accepts five filters, and it composes them so a shopper can be as broad or as specific as they like:
query: free text describing what the customer wants, such as a product name or a need.category: a category slug or name, to scope results to one part of the store.min_price: a lower price bound.max_price: an upper price bound, often the customer's stated budget.on_sale: when true, return only products that are genuinely discounted right now.
A typical request the model makes behind the scenes looks like this:
search_products({
"query": "running shoes",
"category": "footwear",
"max_price": 120,
"on_sale": true
})Every filter is optional, so "what do you have for under $50?" becomes a simple max_price search, and "show me what is on sale in kitchenware" combines category with on_sale.
The on-sale filter is honest
When a customer asks about deals, discounts or clearance, the assistant sets on_sale to true and shows only what it returns. The filter keeps just the products that carry a real reduced price, and each card shows that product's actual sale price next to its original.
An optional semantic layer for intent
Out of the box, search runs on WooCommerce keyword matching, so it works on a fresh install with no extra setup. There is also a pluggable semantic layer that understands intent and phrasing a literal keyword search would miss, such as "shoes for flat feet".
When a semantic retriever is registered, the assistant consults it first for free-text queries. The retriever returns ranked product IDs, and those IDs are then resolved against the live catalogue, so price, sale and stock are always read fresh and never come from a cached index. If no retriever is present, or it returns nothing, search quietly falls back to the keyword path. The shopper never sees an error either way.
How results become cards
Results do not arrive as a wall of text. Each product is rendered as a rich card built from live store data, so the customer can read and act in one place. Every card carries:
- the product photo
- the price, with the sale price shown when the item is discounted
- a stock indicator that flags out-of-stock items
- the star rating and review count when the product has reviews
- a View link to the product page
- an Add to cart button
Because the cards already display the photo, price, stock and links, the assistant does not repeat those details in its written reply. It gives a short, grounded recommendation and lets the cards carry the facts.
Variable products get a selector
For a variable product, such as a shirt with several sizes or colours, the card renders a labelled variation selector. The customer picks the specific option, and the chosen variation is what gets added to the cart. Sold-out variations stay visible but disabled, so the full option set is honest about what can actually be bought.
Why this stays trustworthy
- The assistant always searches before it recommends, so it never describes a product it has not looked up.
- Prices, sale flags and stock are read from the live product at the moment of the search, not from any cache or the model's training.
- The on-sale filter only ever surfaces real discounts.
The result is a shopping conversation grounded in your actual catalogue, where what the customer reads is what your store truly has.