Shopping Assistant Search

The Shopping Assistant is a Vantage feature designed to enhance the online shopping experience by organizing search results into relevant groups based on user-defined specifications.

How It Works:

With the Shopping Assistant, users can create a detailed specification that defines how search results should be grouped. These groups are created based on the criteria set during the assistant's creation. Once the assistant is set up, users can perform searches by sending a text query and a shopping_assistant_id. The assistant will then return results organized into the predefined groups (you can define how many of them using max_groups), helping users quickly find what they're looking for in a structured and intuitive way.

Step 1: Shopping Assistant Creation

First step is to create a new shopping assistant by creating new configuration by sending POST request to /v1/account/{accountId}/shopping_assistants with request body like this:

{
   "name": "Tools Assistant",
   "groups": [
      "Wrenches",
      "Rakes",
      "Shovels",
      "Welding Tools"
   ],
	 "external_account_id": "external-account-id",
	 "llm_model_name": "openai-4o"
}

name

• Name for a shopping assistant configuration

groups

• List of shopping groups that this assistant will narrow search to

external_account_id

• ID of an LLM provider created in your Vantage account

llm_model_name

• Name of model to use for prompting

After successfully creating new configuration, system will send following response:

{
   "shopping_assistant_id": "01912220-08fe-73b7-8a59-44ecd994cce3",
   "account_id": "account",
   "name": "Summer time assistant",
   "groups": [
      "Summer Shorts",
      "T-Shirts",
      "BBQ",
      "Pools"
   ],
	 "external_account_id": "external-account-id",
	 "llm_model_name": "openai-4o"
}

Note the shopping_assistant_id field, you will need this ID every time you perform a search.

Step 2: Search using Shopping Assistant

After creating the assistant, invoke shopping assistant by sending a POST request to v1/search/{accountId}/{collectionId}/shopping_assistant endpoint with following request:

{
   "request_id": 123,
   "text":"A bbq summer party",
   "max_groups": 5,
   "shopping_assistant_id": "01912220-08fe-73b7-8a59-44ecd994cce3",
	  ... other semantic request fields
}

Request is in the same format as semantic search request, with addition of shopping_assistant_id field.

Response is the same as semantic search response, with addition of groups field:

{
  "request_id": 123,
  "status": 200,
  "message": "Success",
  "groups": [
    {
      "group_id": "shorts",
      "group_name": "Summer Shorts",
      "results": [
        {
          "id": "doc11`",
          "score": 0.630,
          "sort_score": 0.699
        },
        {
          "id": "doc42`",
          "score": 0.412,
          "sort_score": 0.117
        }
      ]
    },
    {
      "group_id": "thsirts",
      "group_name": "T-Shirts",
      "results": [
        {
          "id": "doc341`",
          "score": 0.713,
          "sort_score": 0.549
        },
        {
          "id": "doc33`",
          "score": 0.818,
          "sort_score": 0.223
        }
      ]
    },
  ]
  ... Other semantic query responses
}

groups

• List of best matching groups for the query sent. For example: for a query “summer party” for a e-commerce shop,
  “Shorts” & “Sunglasses” are probably much more relevant than “jacket” or “hiking shoes”.

  • group_id: Id of the group specified for this shopping assistant configuration
  • group_name: Name of the group the LLM has defined from the group_id and query text
  • results: List of search results, same as results from a semantic query request response

📘

Reference Guide for Shopping Assistant