Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

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

GET /products/api/v1/products/{gtin}
GET /certifications/api/v1/products/{gtin}   # certifications held
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. 
POST /search/api/v1/search/session
{
  "query": "<user's intent, e.g. 'organic oat milk'>",
  "latitude": ..., "longitude": ...,
  "constraints": {
    "exclude_allergens":       ["peanuts"],
    "require_certifications":  ["vegan", "organic"],
    "avoid_substances":        ["sucralose"]
  }
}
Or, for stateless calls, use the catalog endpoint with the same slugs as repeated query params: 
GET /search/api/v1/search?q=organic+oat+milk
  &exclude_allergens=peanuts
  &require_certifications=vegan

​
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