Equivalence — POST /v1/equivalence

Equivalence

Are these the same product? Returns one of five relations with the specific attributes that differ and a confidence — because 'similar' is not an answer a machine can act on.

POST /v1/equivalence

Request

Name	Type	Notes
a	string	Any reference — identifier, URL or product_id.
b	string	The other one.
strictness	enum	exact \| practical \| loose. Default practical.

Request & response

POST /v1/equivalence
{ "a": "B09XS7JWHH", "b": "bestbuy:6505727" }

→ 200
{ "relation": "identical",
  "confidence": 1.0,
  "basis": "gtin_exact",
  "differences": [] }

// a harder one
POST /v1/equivalence
{ "a": "sony wh-1000xm4", "b": "sony wh-1000xm5" }

→ 200
{ "relation": "successor",
  "confidence": 0.97,
  "direction": "b_supersedes_a",
  "differences": [
    { "attribute": "generation", "a": "XM4", "b": "XM5" },
    { "attribute": "anc_processor", "a": "QN1", "b": "V1 + QN1" },
    { "attribute": "folding", "a": true, "b": false,
      "note": "XM5 does not fold — a real regression for some buyers" } ],
  "guidance": "Do not treat as a price comparison. XM4 is discontinued; a lower price reflects clearance, not a better deal on the same item." }

Notes

The five relations: `identical` (same item, same identity), `variant` (same product, different size, colour or capacity), `substitute` (different product, same job), `successor` (one supersedes the other), `unrelated`.

`differences` is the field agents actually need. A relation without the differing attributes cannot be explained to a user, and an agent that cannot explain its recommendation gets overridden.

Strictness matters. `exact` requires identity down to the pack. `practical` treats a 500ml and a 550ml bottle of the same product as variants. `loose` will call two 65-inch OLED televisions substitutes. Pick deliberately — the right setting differs between a repricer and a shopping assistant.