feat(client-personalize-runtime): This release adds support for a Reason attribute for predicted items generated by User-Personalization-v2.

Author: awstools

clients/client-personalize-runtime/src/commands/GetPersonalizedRankingCommand.ts

@@ -9,6 +9,7 @@ import {
   GetPersonalizedRankingRequest,
   GetPersonalizedRankingRequestFilterSensitiveLog,
   GetPersonalizedRankingResponse,
+  GetPersonalizedRankingResponseFilterSensitiveLog,
 } from "../models/models_0";
 import {
   PersonalizeRuntimeClientResolvedConfig,
@@ -77,6 +78,9 @@ export interface GetPersonalizedRankingCommandOutput extends GetPersonalizedRank
  * //       metadata: { // Metadata
  * //         "<keys>": "STRING_VALUE",
  * //       },
+ * //       reason: [ // ReasonList
+ * //         "STRING_VALUE",
+ * //       ],
  * //     },
  * //   ],
  * //   recommendationId: "STRING_VALUE",
@@ -120,7 +124,7 @@ export class GetPersonalizedRankingCommand extends $Command
   })
   .s("AmazonPersonalizeRuntime", "GetPersonalizedRanking", {})
   .n("PersonalizeRuntimeClient", "GetPersonalizedRankingCommand")
-  .f(GetPersonalizedRankingRequestFilterSensitiveLog, void 0)
+  .f(GetPersonalizedRankingRequestFilterSensitiveLog, GetPersonalizedRankingResponseFilterSensitiveLog)
   .ser(se_GetPersonalizedRankingCommand)
   .de(de_GetPersonalizedRankingCommand)
   .build() {}

clients/client-personalize-runtime/src/commands/GetRecommendationsCommand.ts

@@ -9,6 +9,7 @@ import {
   GetRecommendationsRequest,
   GetRecommendationsRequestFilterSensitiveLog,
   GetRecommendationsResponse,
+  GetRecommendationsResponseFilterSensitiveLog,
 } from "../models/models_0";
 import {
   PersonalizeRuntimeClientResolvedConfig,
@@ -99,6 +100,9 @@ export interface GetRecommendationsCommandOutput extends GetRecommendationsRespo
  * //       metadata: { // Metadata
  * //         "<keys>": "STRING_VALUE",
  * //       },
+ * //       reason: [ // ReasonList
+ * //         "STRING_VALUE",
+ * //       ],
  * //     },
  * //   ],
  * //   recommendationId: "STRING_VALUE",
@@ -142,7 +146,7 @@ export class GetRecommendationsCommand extends $Command
   })
   .s("AmazonPersonalizeRuntime", "GetRecommendations", {})
   .n("PersonalizeRuntimeClient", "GetRecommendationsCommand")
-  .f(GetRecommendationsRequestFilterSensitiveLog, void 0)
+  .f(GetRecommendationsRequestFilterSensitiveLog, GetRecommendationsResponseFilterSensitiveLog)
   .ser(se_GetRecommendationsCommand)
   .de(de_GetRecommendationsCommand)
   .build() {}

clients/client-personalize-runtime/src/models/models_0.ts

@@ -228,6 +228,32 @@ export interface PredictedItem {
    * @public
    */
   metadata?: Record<string, string>;
+
+  /**
+   * <p>If you use User-Personalization-v2, a list of reasons for why the item was included in recommendations. Possible reasons include the following:</p>
+   *          <ul>
+   *             <li>
+   *                <p>Promoted item - Indicates the item was included as part of a promotion that you applied in your recommendation request.</p>
+   *             </li>
+   *             <li>
+   *                <p>Exploration - Indicates the item was included with exploration.
+   *           With exploration, recommendations include items with less interactions data or relevance for the user.
+   *           For more information about exploration, see
+   *           <a href="https://docs.aws.amazon.com/personalize/latest/dg/use-case-recipe-features.html#about-exploration">Exploration</a>.</p>
+   *             </li>
+   *             <li>
+   *                <p>
+   *           Popular item - Indicates the item was included as a placeholder popular item.
+   *           If you use a filter, depending on how many recommendations the filter removes,
+   *            Amazon Personalize might add placeholder items to meet the <code>numResults</code> for your
+   *           recommendation request. These items are popular items, based on interactions data, that satisfy your filter criteria.
+   *           They don't have a relevance score for the user.
+   *         </p>
+   *             </li>
+   *          </ul>
+   * @public
+   */
+  reason?: string[];
 }
 
 /**
@@ -411,6 +437,24 @@ export const GetPersonalizedRankingRequestFilterSensitiveLog = (obj: GetPersonal
   ...(obj.filterValues && { filterValues: SENSITIVE_STRING }),
 });
 
+/**
+ * @internal
+ */
+export const PredictedItemFilterSensitiveLog = (obj: PredictedItem): any => ({
+  ...obj,
+  ...(obj.metadata && { metadata: SENSITIVE_STRING }),
+});
+
+/**
+ * @internal
+ */
+export const GetPersonalizedRankingResponseFilterSensitiveLog = (obj: GetPersonalizedRankingResponse): any => ({
+  ...obj,
+  ...(obj.personalizedRanking && {
+    personalizedRanking: obj.personalizedRanking.map((item) => PredictedItemFilterSensitiveLog(item)),
+  }),
+});
+
 /**
  * @internal
  */
@@ -428,3 +472,11 @@ export const GetRecommendationsRequestFilterSensitiveLog = (obj: GetRecommendati
   ...(obj.filterValues && { filterValues: SENSITIVE_STRING }),
   ...(obj.promotions && { promotions: obj.promotions.map((item) => PromotionFilterSensitiveLog(item)) }),
 });
+
+/**
+ * @internal
+ */
+export const GetRecommendationsResponseFilterSensitiveLog = (obj: GetRecommendationsResponse): any => ({
+  ...obj,
+  ...(obj.itemList && { itemList: obj.itemList.map((item) => PredictedItemFilterSensitiveLog(item)) }),
+});

clients/client-personalize-runtime/src/protocols/Aws_restJson1.ts

@@ -314,10 +314,13 @@ const de_PredictedItem = (output: any, context: __SerdeContext): PredictedItem =
     itemId: __expectString,
     metadata: _json,
     promotionName: __expectString,
+    reason: _json,
     score: __limitedParseDouble,
   }) as any;
 };
 
+// de_ReasonList omitted.
+
 const deserializeMetadata = (output: __HttpResponse): __ResponseMetadata => ({
   httpStatusCode: output.statusCode,
   requestId:

codegen/sdk-codegen/aws-models/personalize-runtime.json

@@ -1164,6 +1164,9 @@
       },
       "value": {
         "target": "com.amazonaws.personalizeruntime#ColumnValue"
+      },
+      "traits": {
+        "smithy.api#sensitive": {}
       }
     },
     "com.amazonaws.personalizeruntime#MetadataColumns": {
@@ -1255,6 +1258,12 @@
           "traits": {
             "smithy.api#documentation": "<p>Metadata about the item from your Items dataset.</p>"
           }
+        },
+        "reason": {
+          "target": "com.amazonaws.personalizeruntime#ReasonList",
+          "traits": {
+            "smithy.api#documentation": "<p>If you use User-Personalization-v2, a list of reasons for why the item was included in recommendations. Possible reasons include the following:</p>\n         <ul>\n            <li>\n               <p>Promoted item - Indicates the item was included as part of a promotion that you applied in your recommendation request.</p>\n            </li>\n            <li>\n               <p>Exploration - Indicates the item was included with exploration.\n          With exploration, recommendations include items with less interactions data or relevance for the user.\n          For more information about exploration, see \n          <a href=\"https://docs.aws.amazon.com/personalize/latest/dg/use-case-recipe-features.html#about-exploration\">Exploration</a>.</p>\n            </li>\n            <li>\n               <p> \n          Popular item - Indicates the item was included as a placeholder popular item.\n          If you use a filter, depending on how many recommendations the filter removes, \n           Amazon Personalize might add placeholder items to meet the <code>numResults</code> for your \n          recommendation request. These items are popular items, based on interactions data, that satisfy your filter criteria.\n          They don't have a relevance score for the user.\n        </p>\n            </li>\n         </ul>"
+          }
         }
       },
       "traits": {
@@ -1305,6 +1314,21 @@
         }
       }
     },
+    "com.amazonaws.personalizeruntime#Reason": {
+      "type": "string",
+      "traits": {
+        "smithy.api#length": {
+          "min": 0,
+          "max": 256
+        }
+      }
+    },
+    "com.amazonaws.personalizeruntime#ReasonList": {
+      "type": "list",
+      "member": {
+        "target": "com.amazonaws.personalizeruntime#Reason"
+      }
+    },
     "com.amazonaws.personalizeruntime#RecommendationID": {
       "type": "string"
     },