> ## 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.

# Find Alternative

> Find an alternative product that matches user constraints (certifications, substances to avoid, dietary preferences) near a location.

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").

## Related skills

* `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