AWS.Personalize reference

CreateBatchInferenceJob

Source: src/AWS/Personalize/CreateBatchInferenceJob.ts

Runtime binding for personalize:CreateBatchInferenceJob — Starts a batch inference job that scores a list of users from S3 against a solution version and writes recommendations back to S3. Grants personalize:CreateBatchInferenceJob on * plus iam:PassRole (conditioned to personalize.amazonaws.com) for the data-access role the service assumes to read/write the buckets. Provide the implementation with Effect.provide(AWS.Personalize.CreateBatchInferenceJobHttp).

CreateBatchInferenceJob: Batch Inference

// init
const createBatchInferenceJob = yield* Personalize.CreateBatchInferenceJob();

const { batchInferenceJobArn } = yield* createBatchInferenceJob({
  jobName: "nightly-scores",
  solutionVersionArn,
  jobInput: { s3DataSource: { path: "s3://bucket/users.json" } },
  jobOutput: { s3DataDestination: { path: "s3://bucket/scores/" } },
  roleArn: batchRoleArn,
});

CreateCampaign

Source: src/AWS/Personalize/CreateCampaign.ts

Runtime binding for personalize:CreateCampaign — Deploys a trained solution version as a live campaign that serves real-time recommendations — the final step of the MLOps loop. Provide the implementation with Effect.provide(AWS.Personalize.CreateCampaignHttp).

CreateCampaign: Retraining Loop

// init
const createCampaign = yield* Personalize.CreateCampaign();

const { campaignArn } = yield* createCampaign({
  name: "recommendations",
  solutionVersionArn,
});

CreateDatasetImportJob

Source: src/AWS/Personalize/CreateDatasetImportJob.ts

Runtime binding for personalize:CreateDatasetImportJob — Starts a bulk import of training data from S3 into a dataset — the first step of the MLOps retraining loop. Grants personalize:CreateDatasetImportJob on * plus iam:PassRole (conditioned to personalize.amazonaws.com) for the data-access role the service assumes to read the S3 bucket. Provide the implementation with Effect.provide(AWS.Personalize.CreateDatasetImportJobHttp).

CreateDatasetImportJob: Retraining Loop

// init
const createDatasetImportJob = yield* Personalize.CreateDatasetImportJob();

const { datasetImportJobArn } = yield* createDatasetImportJob({
  jobName: "nightly-import",
  datasetArn,
  dataSource: { dataLocation: "s3://training-bucket/interactions.csv" },
  roleArn: importRoleArn,
});

CreateSolution

Source: src/AWS/Personalize/CreateSolution.ts

Runtime binding for personalize:CreateSolution — Creates a solution (a recipe + configuration to train models with) for a dataset group — set performAutoTraining to keep models fresh automatically. Provide the implementation with Effect.provide(AWS.Personalize.CreateSolutionHttp).

CreateSolution: Retraining Loop

// init
const createSolution = yield* Personalize.CreateSolution();

const { solutionArn } = yield* createSolution({
  name: "user-personalization",
  recipeArn: "arn:aws:personalize:::recipe/aws-user-personalization",
  datasetGroupArn,
});

CreateSolutionVersion

Source: src/AWS/Personalize/CreateSolutionVersion.ts

Runtime binding for personalize:CreateSolutionVersion — Trains a new model (solution version) for an existing solution — the retraining step of the MLOps loop, typically run on a schedule after fresh data is imported. Provide the implementation with Effect.provide(AWS.Personalize.CreateSolutionVersionHttp).

CreateSolutionVersion: Retraining Loop

// init
const createSolutionVersion = yield* Personalize.CreateSolutionVersion();

const { solutionVersionArn } = yield* createSolutionVersion({
  solutionArn,
  trainingMode: "UPDATE",
});

Dataset

Source: src/AWS/Personalize/Dataset.ts

An Amazon Personalize dataset — a typed collection (Interactions, Items, Users, …) inside a dataset group, backed by a schema. Creating the dataset is a cheap metadata operation; bulk imports and training happen through separate import jobs and solutions.

Dataset: Creating a Dataset

const dataset = yield* Personalize.Dataset("Interactions", {
  schemaArn: schema.schemaArn,
  datasetGroupArn: group.datasetGroupArn,
  datasetType: "Interactions",
});

DatasetGroup

Source: src/AWS/Personalize/DatasetGroup.ts

An Amazon Personalize dataset group — the top-level container that holds the datasets, solutions, and campaigns for a single use case. Creating a dataset group is cheap and fast; the expensive training work lives in solutions and campaigns provisioned separately.

DatasetGroup: Creating a Dataset Group

Custom Dataset Group

const group = yield* Personalize.DatasetGroup("Recommendations", {});

Domain Dataset Group with Encryption

const group = yield* Personalize.DatasetGroup("Storefront", {
  domain: "ECOMMERCE",
  roleArn: role.roleArn,
  kmsKeyArn: key.keyArn,
  tags: { team: "growth" },
});

DescribeBatchInferenceJob

Source: src/AWS/Personalize/DescribeBatchInferenceJob.ts

Runtime binding for personalize:DescribeBatchInferenceJob — Polls a batch inference job for completion — pairs with CreateBatchInferenceJob. Provide the implementation with Effect.provide(AWS.Personalize.DescribeBatchInferenceJobHttp).

DescribeBatchInferenceJob: Batch Inference

// init
const describeBatchInferenceJob = yield* Personalize.DescribeBatchInferenceJob();

const { batchInferenceJob } = yield* describeBatchInferenceJob({
  batchInferenceJobArn,
});
const done = batchInferenceJob?.status === "ACTIVE";

DescribeCampaign

Source: src/AWS/Personalize/DescribeCampaign.ts

Runtime binding for personalize:DescribeCampaign — Reads a campaign’s status and the solution version it serves — used to confirm a campaign update finished before switching traffic. Provide the implementation with Effect.provide(AWS.Personalize.DescribeCampaignHttp).

DescribeCampaign: Retraining Loop

// init
const describeCampaign = yield* Personalize.DescribeCampaign();

const { campaign } = yield* describeCampaign({ campaignArn });
const live = campaign?.status === "ACTIVE";

DescribeDatasetImportJob

Source: src/AWS/Personalize/DescribeDatasetImportJob.ts

Runtime binding for personalize:DescribeDatasetImportJob — Polls a bulk dataset import job for completion — pairs with CreateDatasetImportJob in the MLOps retraining loop. Provide the implementation with Effect.provide(AWS.Personalize.DescribeDatasetImportJobHttp).

DescribeDatasetImportJob: Retraining Loop

// init
const describeDatasetImportJob = yield* Personalize.DescribeDatasetImportJob();

const { datasetImportJob } = yield* describeDatasetImportJob({
  datasetImportJobArn,
});
const done = datasetImportJob?.status === "ACTIVE";

DescribeSolutionVersion

Source: src/AWS/Personalize/DescribeSolutionVersion.ts

Runtime binding for personalize:DescribeSolutionVersion — Polls a solution version for training completion — pairs with CreateSolutionVersion in the MLOps retraining loop. Provide the implementation with Effect.provide(AWS.Personalize.DescribeSolutionVersionHttp).

DescribeSolutionVersion: Retraining Loop

// init
const describeSolutionVersion = yield* Personalize.DescribeSolutionVersion();

const { solutionVersion } = yield* describeSolutionVersion({
  solutionVersionArn,
});
const trained = solutionVersion?.status === "ACTIVE";

EventTracker

Source: src/AWS/Personalize/EventTracker.ts

An Amazon Personalize event tracker — the ingestion endpoint for streaming interaction events into a dataset group’s Interactions dataset. Creating a tracker yields a trackingId that the PutEvents data-plane binding uses to record events in real time.

EventTracker: Creating an Event Tracker

const tracker = yield* Personalize.EventTracker("Tracker", {
  datasetGroupArn: group.datasetGroupArn,
});

EventTracker: Streaming Events

// init
const putEvents = yield* Personalize.PutEvents(tracker);

// runtime
yield* putEvents({
  sessionId: "session-1",
  userId: "user-1",
  eventList: [{ eventType: "click", itemId: "item-42", sentAt: new Date() }],
});

GetActionRecommendations

Source: src/AWS/Personalize/GetActionRecommendations.ts

Runtime binding for personalize:GetActionRecommendations — Returns a list of recommended actions (next best action) for a user from a campaign backed by the NEXT_BEST_ACTION recipe. Campaign ARNs are chosen at runtime, so the binding takes no arguments and grants personalize:GetActionRecommendations on *. Provide the implementation with Effect.provide(AWS.Personalize.GetActionRecommendationsHttp).

GetActionRecommendations: Serving Recommendations

// init
const getActionRecommendations = yield* Personalize.GetActionRecommendations();

const { actionList } = yield* getActionRecommendations({
  campaignArn,
  userId: "user-1",
});

GetPersonalizedRanking

Source: src/AWS/Personalize/GetPersonalizedRanking.ts

Runtime binding for personalize:GetPersonalizedRanking — Re-ranks a caller-supplied list of items for a user using a campaign backed by the Personalized-Ranking recipe. Campaign ARNs are chosen at runtime, so the binding takes no arguments and grants personalize:GetPersonalizedRanking on *. Provide the implementation with Effect.provide(AWS.Personalize.GetPersonalizedRankingHttp).

GetPersonalizedRanking: Serving Recommendations

// init
const getPersonalizedRanking = yield* Personalize.GetPersonalizedRanking();

const { personalizedRanking } = yield* getPersonalizedRanking({
  campaignArn,
  userId: "user-1",
  inputList: ["item-1", "item-2", "item-3"],
});

GetRecommendations

Source: src/AWS/Personalize/GetRecommendations.ts

Runtime binding for personalize:GetRecommendations — Returns a list of recommended items for a user from a campaign or domain recommender — the core Personalize serving call. Campaign and recommender ARNs are chosen at runtime, so the binding takes no arguments and grants personalize:GetRecommendations on *. Provide the implementation with Effect.provide(AWS.Personalize.GetRecommendationsHttp).

GetRecommendations: Serving Recommendations

// init
const getRecommendations = yield* Personalize.GetRecommendations();

const { itemList } = yield* getRecommendations({
  campaignArn,
  userId: "user-1",
  numResults: 10,
});

GetSolutionMetrics

Source: src/AWS/Personalize/GetSolutionMetrics.ts

Runtime binding for personalize:GetSolutionMetrics — Reads the offline evaluation metrics (precision, coverage, NDCG, …) of a trained solution version — used to gate deployment on model quality. Provide the implementation with Effect.provide(AWS.Personalize.GetSolutionMetricsHttp).

GetSolutionMetrics: Retraining Loop

// init
const getSolutionMetrics = yield* Personalize.GetSolutionMetrics();

const { metrics } = yield* getSolutionMetrics({ solutionVersionArn });
const ndcg = metrics?.["normalized_discounted_cumulative_gain_at_25"];

PutActionInteractions

Source: src/AWS/Personalize/PutActionInteractions.ts

Runtime binding for personalize:PutActionInteractions, scoped to one EventTracker — Records action-interaction events (Taken, Not Taken, Viewed) for the NEXT_BEST_ACTION recipe through the bound EventTracker. Events stream into the dataset group’s Action interactions dataset. Provide the implementation with Effect.provide(AWS.Personalize.PutActionInteractionsHttp).

PutActionInteractions: Streaming Events

// init
const putActionInteractions = yield* Personalize.PutActionInteractions(tracker);

yield* putActionInteractions({
  actionInteractions: [{
    actionId: "action-1",
    userId: "user-1",
    sessionId: "session-1",
    eventType: "Taken",
    timestamp: new Date(),
  }],
});

PutActions

Source: src/AWS/Personalize/PutActions.ts

Runtime binding for personalize:PutActions, scoped to one Dataset — Adds or updates actions incrementally in the bound Actions Dataset for the NEXT_BEST_ACTION recipe. Provide the implementation with Effect.provide(AWS.Personalize.PutActionsHttp).

PutActions: Incremental Imports

// init
const putActions = yield* Personalize.PutActions(actionsDataset);

yield* putActions({ actions: [{ actionId: "action-1" }] });

PutEvents

Source: src/AWS/Personalize/PutEvents.ts

Runtime binding for personalize:PutEvents, scoped to one EventTracker — Records item-interaction events (clicks, views, purchases, …) in real time through the bound EventTracker. Events stream into the dataset group’s Interactions dataset and are used by recommenders as they happen. Provide the implementation with Effect.provide(AWS.Personalize.PutEventsHttp).

PutEvents: Streaming Events

// init
const putEvents = yield* Personalize.PutEvents(tracker);

yield* putEvents({
  sessionId: "session-1",
  userId: "user-1",
  eventList: [{ eventType: "click", itemId: "item-42", sentAt: new Date() }],
});

PutItems

Source: src/AWS/Personalize/PutItems.ts

Runtime binding for personalize:PutItems, scoped to one Dataset — Adds or updates items incrementally in the bound Items Dataset — the streaming alternative to a bulk dataset import job for keeping the catalog fresh. Provide the implementation with Effect.provide(AWS.Personalize.PutItemsHttp).

PutItems: Incremental Imports

// init
const putItems = yield* Personalize.PutItems(itemsDataset);

yield* putItems({
  items: [{
    itemId: "item-42",
    properties: JSON.stringify({ category: "books" }),
  }],
});

PutUsers

Source: src/AWS/Personalize/PutUsers.ts

Runtime binding for personalize:PutUsers, scoped to one Dataset — Adds or updates users incrementally in the bound Users Dataset — the streaming alternative to a bulk dataset import job for keeping user metadata fresh. Provide the implementation with Effect.provide(AWS.Personalize.PutUsersHttp).

PutUsers: Incremental Imports

// init
const putUsers = yield* Personalize.PutUsers(usersDataset);

yield* putUsers({
  users: [{
    userId: "user-1",
    properties: JSON.stringify({ membership: "gold" }),
  }],
});

Schema

Source: src/AWS/Personalize/Schema.ts

An Amazon Personalize schema — an Avro definition that describes the fields of a dataset (Interactions, Items, Users, …). Schemas are immutable once created; changing any property replaces the schema.

Schema: Creating a Schema

const schema = yield* Personalize.Schema("Interactions", {
  schema: JSON.stringify({
    type: "record",
    name: "Interactions",
    namespace: "com.amazonaws.personalize.schema",
    fields: [
      { name: "USER_ID", type: "string" },
      { name: "ITEM_ID", type: "string" },
      { name: "TIMESTAMP", type: "long" },
    ],
    version: "1.0",
  }),
});

UpdateCampaign

Source: src/AWS/Personalize/UpdateCampaign.ts

Runtime binding for personalize:UpdateCampaign — Points a live campaign at a newly trained solution version (or adjusts its provisioned TPS) — the deploy step of the MLOps retraining loop. Provide the implementation with Effect.provide(AWS.Personalize.UpdateCampaignHttp).

UpdateCampaign: Retraining Loop

// init
const updateCampaign = yield* Personalize.UpdateCampaign();

yield* updateCampaign({ campaignArn, solutionVersionArn });