Catalog Customization#

Source#

Note

This section presumes that the default Tokkio Retail App is already deployed.

The Catalog RAG source can be checked by using the exec command to log in to the Kubernetes pod post deployment. Replace the catalog-rag-deployment-pod-name in the example command shown below with the actual pod name for the Catalog RAG in your deployment. For example: catalog-rag-deployment-7b9786484d-v44d2

kubectl exec -ti <catalog-rag-deployment-pod-name> -- /bin/bash

Various files discussed in the sections below can be found inside the pod. You may also copy these files over locally for editing.

Catalog Schema#

The JSON schema used for Catalog RAG is currently targeted towards a restaurant based retail application. The RAG pipeline can be modified/updated to work for the existing schema easily. The schema can be observed to be used in the file menu.json in the Catalog RAG source. Here is a breakdown of various fields within the JSON schema -

  • _id [Dict] - Stores unique id

  • $oid [Str] - hexadecimal unique id for each entry in menu

  • menu_item [Bool] ⇒ set to False if you don’t want to show the item over UI as a separate item (for ex, toppings, ingredients), otherwise True

  • recommendation_type [List[Str]] ⇒ Reserved for future use

  • synonyms [List[Str]] ⇒ Alias name, if any, for this item

  • tags [List[Str]] ⇒ tags based on restrictions, specification etc., (For ex, vegan)

  • variations [List[Dict]] ⇒ Defining all possible variations

    • name [Str] ⇒ Reserved for future use

    • size [Str] ⇒ corresponding size of variation (For ex, small)

    • calories [Int] ⇒ total calories

    • price [Float] ⇒ total price

    • description [Str] ⇒ description of the food item (optional if is_default not set)

    • image [Str] ⇒ image location in NGC registry (optional if is_default not set)

    • is_default [Bool] ⇒ if available and set to True, this variation would be added to the cart if the user doesn’t mention a specific variation size

  • ingredients [List[Str]] ⇒ all ingredients present, ensure that ingredients are also added as separate food items in menu with menu_item=False)

  • toppings [List[Str]] ⇒ all available toppings, ensure that toppings are also added as separate food items in menu with menu_item=False)

  • name [Str] ⇒ name of the food item

  • item_id [Str] ⇒ unique alphanumeric item id

  • category [Str] ⇒ category of food item to which current item belongs to

All of the key-value pairs for a particular item are mandatory . So while updating OR adding a new menu item , make sure that all the default key-value pairs are present. Here is the snippet of the default schema used for Catalog RAG -

[
     {
     "_id": {
          "$oid": "string"
     },
     "menu_item": true,
     "recommendation_type": [
          "string"
     ],
     "synonyms": [
          "string"
     ],
     "tags": [
          "string"
     ],
     "variations": [
          {
          "name": "string",
          "size": "string",
          "calories": 0,
          "price": 0,
          "description": "string",
          "image": "string",
          "is_default": true
          }
     ],
     "ingredients": [
          "string"
     ],
     "toppings": [
          "string"
     ],
     "name": "string",
     "item_id": "string",
     "category": "string"
     }
]

Modifying the default Catalog#

The Catalog RAG provides an API POST /api/menu to set the catalog (with the same schema) on the fly. Note that the plugin server, cart manager, the UI Server and the UI need a restart following this update. Users can access this endpoint within the Kubernetes cluster by using the Catalog RAG service port. Requests can be sent via curl or via the fastapi client page (Example: http://localhost:8080/docs).

For major changes that include using the Catalog RAG for a very different application than a retail restaurant, it is recommended to update the prompt vectorstore_prompt.txt (found in the Catalog RAG source) and upload the updated JSON in the Catalog source such that it is utilized for creating a vectorstore at startup. The later approach would need the user to rebuild the Catalog RAG container and use the updated container for a custom/new microservice that can be used with Tokkio.

Updating Catalog Images#

Images corresponding to the items in the Catalog schema (menu.json is the default file) need to be uploaded to the front end source in order for them to be displayed correctly to the user. Check the Deploy UI for downloading the UI source. The default version already contains the images pertaining to the items in the default menu.json.

  1. Run below commands to generate the UI production build. A “build” directory will be generated:

    cd vst-streaming-lib
npm install
npm run build

2. Make a new /images directory and put it inside the /build directory of the UI. The subfolders in this directory should be equal to image_loc field in API response from UI server. For example, the API response from GET: category/item/23 will have an image_loc field. Suppose image_loc field is equal to images/image-category/item23.png. Then UI should have an image for item 23 at directory /public/images/image-category/item23.png This should be followed for all items in the catalog. 1. The new /images directory should replace existing image directory in /build/images. 2. Upload updated build directory to S3 bucket:

aws s3 sync ./build s3://tokkio-ui

  1. Save the newly generated static files in /build directory.

Functionality Customization - Catalog Schema, CM, Plugin Server and UI#

The Tokkio retail reference application expects the user to stick to the catalog schema and API flow as defined in the Tokkio retail microservices (MS). However, if needed these can be modified to incorporate any new requirements. In most of the cases changes would be needed across Plugin Server, CM, Catalog RAG and UI and their APIs.

Using a Custom Catalog RAG#

  1. Download the Catalog RAG resource locally as demonstrated in Downloading Catalog RAG source

  2. Implement the necessary modifications to customize the resource.

  3. Navigate to the source directory with Dockerfile and build the container for the updated:

    docker build -t catalog-rag-container:test

  4. Tag the created image to be uploaded to the specific NGC path used for your organization:

    sudo docker tag <image_name> <NGC_PATH/ucs-tokkio-catalog-rag-container:version_num>

  5. Push the updated container to NGC:

    docker push <NGC_PATH/ucs-tokkio-catalog-rag-container:version_num>

  6. Refer to Adding a new microservice for details regarding creating and using a custom microservice (in this case - a customized version of the Catalog RAG) that can be used for Tokkio application.

On this page