mynameisvinn · April 11, 2024 14:37 · Apr 11, 2024
diff --git a/updates.md b/updates.md
@@ -0,0 +1,97 @@
+# Updates Ranker
+## Overview
+The Updates Ranker ranks notification types (eg thank you coupons). 
+
+## Surface
+The Updates Ranker will be used in the Deal tab.
+
+## Runbook
+### Generate User and Global Notification Features
+Notification features (eg user click rate for various notification types, triggers, and sources) are generated via a [Sparkly job](https://github.com/etsy/sparkly/blob/main/spark-jobs/recsys/src/main/scala/com/etsy/spark/jobs/recs/ranking/updates/UserAndGlobalFeatures.scala). These features are moved to FBv2 via the [recs_ranking_updates_features_fbv2 DAG](https://web.airflow.etsy-syseng-gke-prod.etsycloud.com/dags/recs_ranking_updates_features_fbv2/grid?search=recs_ranking_updates_features_fbv2&dag_run_id=scheduled__2024-04-03T00%3A00%3A00%2B00%3A00&task_id=notification_user_features_sensor)
+
+A notification consists of three features:
+
+- **notification_source:** 
+  - Possible values include: 'cart_listing', 'collection', 'favorite_listing', 'favorite_shop', 'purchased_shop', 'saved_for_later_listing'
+
+- **notification_trigger:** 
+  - Possible triggers are: 'coupon', 'in_stock', 'new_listings', 'on_sale', 'only_1_left', 'recommendations'
+
+- **notification_type:** 
+  - Types include: 'aco', 'asfl', 'cr', 'fbis', 'nfyfs', 'ofl', 'psfcl', 'psffl', 'psffs', 'pssfl', 'rfc', 'tyc'
+
+
+### Implicit Feedback
+Notification events (denoted by `notification_feed_id`) are scanned and collected in the [reranking feedback DAG](https://web.airflow.etsy-syseng-gke-prod.etsycloud.com/dags/recs_ranking_updates_implicit_feedback/grid?search=recs_ranking_updates_implicit_feedback). It can be found [here](gs://etldata-prod-recsys-data-hkwv8r/data/shared/recsys/notifications/aggregate_boe_implicit_feedback/).
+
+### Attributed Data
+Implicit feedback is joined with user and candidate features via a [Time Machine DAG](https://web.airflow.etsy-syseng-gke-prod.etsycloud.com/dags/recs_ranking_updates_flattened_attributed_instance/grid?search=recs_ranking_updates_flattened_attributed_instance) to produce training data (which can be found in `gs://etldata-prod-recsys-data-hkwv8r/data/shared/recsys/updates_ranker/updates_ranker_features/`)
+
+### Preprocessing
+Inputs to be preprocessed is specified in [this spec](https://github.com/etsy/recs/blob/main/models/purchase_ranker/src/python/etsy/recs/ranking/purchase_ranker/features/updates/updates_ranker_v1.py) and processed via a [Beam job](https://github.com/etsy/recs/blob/main/models/purchase_ranker/src/python/etsy/recs/ranking/purchase_ranker/preprocessing/transformations/updates/functions.py).
+
+### Training
+### Evaluation
+
+### Barista
+### Komodo
+Expected input:
+```json
+{
+    "name": "updates-ranker-v1",
+    "version": "v1",
+    "inputNames": [
+      "candidate",		// listing id
+      "notification_source",
+      "notification_trigger",
+      "notification_type",
+      "target",		// listing id
+      "user"			// user id
+    ],
+```
+### Client Request
+```
+// MMX REQUEST PATH
+/apiv2/notification/rec_set/ranking-v1/recs
+
+// MMX REQUEST BODY
+[03-Apr-2024 16:31:47 UTC] Array
+(
+    [coreParams] => Array
+        (
+            [limit] => 45
+            [modulePlacement] => boe_notifications_feed
+            [featureLoggingEnabled] =>
+        )
+
+    [recSetParams] => Array
+        (
+            [userId] => 31887901
+            [feedLastSeenOn] => 1709653875
+            [candidates] => Array
+                (
+                    [0] => Array
+                        (
+                            [notificationId] => 0
+                            [notificationType] => nfyfs
+                            [source] => favorite_shop
+                            [trigger] => new_listings
+                            [createdOn] => 1712159763
+                            [isSeen] =>
+                            [hasCta] =>
+                            [listingIds] => Array
+                                (
+                                    [0] => 1707908963
+                                )
+
+                            [shopIds] => Array
+                                (
+                                    [0] => 5613760
+                                )
+
+                        )
+                )
+        )
+)
+
+```