Skip to main content
User has a product they can’t use — wrong certification, contains an allergen, missing a required trait — and needs a substitute available nearby.

​
When to use

  • User says “I can’t have X because of Y, find me something else.”
  • Agent receives a recall on a product the user was planning to buy.
  • Conversational context makes clear the current candidate fails a constraint.

​
Inputs to gather

  1. What product are we replacing? GTIN preferred; free-text fallback.
  2. Why is it unsuitable? Allergen (peanuts), missing certification (not kosher), substance to avoid (ethanol), dietary stance (not vegan).
  3. Where is the user? Latitude + longitude.

​
Flow

​
1. Get the failing product’s attributes

Capture: GPC brick/category, brand, net_content range, certifications the user does want to preserve.

​
2. Search for candidates with the unified filter

Pass the hard constraints directly — the search surface drops failing candidates server-side and stamps each remaining row with inline certifications / contains_allergens / substance_flags / allergen_data_confidence. No per-candidate round-trips needed.
Or, for stateless calls, use the catalog endpoint with the same slugs as repeated query params:

​
3. Rank what’s left

Hard constraints have already filtered the result set. Rank remaining candidates by constraint-fit (PREFER hits boost the rank — see dietary-filter-search), then proximity, then price. Inspect each row’s allergen_data_confidence: low means the product hasn’t told us anything about allergens, so drop it conservatively when the user has an avoid constraint rather than recommending blindly.

​
4. Return top 3 with reasoning

Include why each alternative was selected (“certified vegan, same net content, available at Whole Foods 0.8 km away”).
  • dietary-filter-search — once unified filtering ships, start there instead
  • compare-products — show the user why the alternative is better
  • check-recalls — confirm the alternative isn’t itself under recall