Add classes to parse PC Instruction set. (#2268)

Summary:
Pull Request resolved: #2268

# Context
As per PC Translator design, we need a runtime library will be called during PC run. This library will be called at the beginning of PC run to encode specified fields in publisher side input into a encoded breakdown (aggregation) Ids based on active PC instruction sets for the run. The library will filter the active PC Instruction sets for the run based on parsing the pcs_features i.e. gatekeepers for the particular run.

# Product decisions
In this stack we would focus solely on functionality required for private lift runs.
We would focus on the MVP implementation of the library and its integration with fbpcf ORAM encoder library in this stack.

# Stack
1. Create runtime pc_translator library.
2. Add logic to retrieve and parse PC instruction set, filtered based on the active gatekeepers for the run.
3. Integrate pc_translator library with fbpcf ORAM encoder.
4. Add logic to generate transformed publisher output with encoded breakdown ID and write the output.

# In this diff
Add logic to retrieve and parse PC instruction set.

Differential Revision:
D44618035

Privacy Context Container: L416713

fbshipit-source-id: b9758fb3ce2fb55640eabd43b17d8d5020d6f3ef

fbpcs/pc_translator/PCTranslator.cpp

@@ -6,34 +6,70 @@
  */
 
 #include "fbpcs/pc_translator/PCTranslator.h"
+#include "fbpcs/pc_translator/input_processing/PCInstructionSet.h"
+
+#include <fbpcf/common/FunctionalUtil.h>
+#include <fbpcf/io/api/FileIOWrappers.h>
+#include <set>
+#include "folly/String.h"
 
 namespace pc_translator {
 
-std::string PCTranslator::encode(const std::string& /* inputDataset */) {
-  throw std::runtime_error("Unimplemented");
+std::string PCTranslator::encode(const std::string& inputDataset) {
+  auto validInstructionSetNames =
+      PCTranslator::retrieveInstructionSetNamesForRun(pcsFeatures_);
+  auto pcInstructionSets =
+      PCTranslator::retrieveInstructionSets(validInstructionSetNames);
+  PCTranslator::transformDataset(inputDataset, pcInstructionSets);
+  return "";
 }
 
 std::string PCTranslator::decode(
     const std::string& /* aggregatedOutputDataset */) {
   throw std::runtime_error("Unimplemented");
 }
 
-void PCTranslator::retrieveInstructionSets(
-    std::vector<std::string>& /* instructionSetNames */) {
-  throw std::runtime_error("Unimplemented");
+std::vector<std::shared_ptr<PCInstructionSet>>
+PCTranslator::retrieveInstructionSets(
+    std::vector<std::string>& instructionSetNames) {
+  std::vector<std::shared_ptr<PCInstructionSet>> pcInstructionSets;
+  for (auto instructionSetName : instructionSetNames) {
+    auto file_path = instructionSetBasePath + instructionSetName + ".json";
+    auto contents = fbpcf::io::FileIOWrappers::readFile(file_path);
+    pcInstructionSets.push_back(PCTranslator::parseInstructionSet(contents));
+  }
+  return pcInstructionSets;
 }
 
 std::vector<std::string> PCTranslator::retrieveInstructionSetNamesForRun(
-    const std::string& /* pcsFeatures */) {
-  throw std::runtime_error("Unimplemented");
+    const std::string& pcsFeatures) {
+  std::set<std::string> enabledFeatureFlags;
+  folly::splitTo<std::string>(
+      ',',
+      pcsFeatures,
+      std::inserter(enabledFeatureFlags, enabledFeatureFlags.begin()),
+      true);
+
+  std::vector<std::string> validPCInstructionSets;
+  std::copy_if(
+      enabledFeatureFlags.begin(),
+      enabledFeatureFlags.end(),
+      std::back_inserter(validPCInstructionSets),
+      [](const std::string& feature) { return feature.find("pc_instr") == 0; });
+
+  return validPCInstructionSets;
 }
 
-void PCTranslator::transformDataset(const std::string& /* input */) {
+void PCTranslator::transformDataset(
+    const std::string& /* inputData */,
+    const std::vector<std::shared_ptr<pc_translator::PCInstructionSet>>&
+    /* pcInstructionSets */) {
   throw std::runtime_error("Unimplemented");
 }
 
-void PCTranslator::parseInstructionSet(
-    const std::string& /* instructionSet */) {
-  throw std::runtime_error("Unimplemented");
+std::shared_ptr<PCInstructionSet> PCTranslator::parseInstructionSet(
+    std::string& instructionSet) {
+  return std::make_shared<PCInstructionSet>(PCInstructionSet::fromDynamic(
+      folly::parseJson(std::move(instructionSet))));
 }
 } // namespace pc_translator

fbpcs/pc_translator/PCTranslator.h

@@ -11,6 +11,7 @@
 #include <memory>
 #include <string>
 #include <vector>
+#include "fbpcs/pc_translator/input_processing/PCInstructionSet.h"
 
 namespace pc_translator {
 
@@ -23,7 +24,7 @@ namespace pc_translator {
 class PCTranslator {
  public:
   explicit PCTranslator(const std::string& pcsFeatures)
-      : pcsfeatures_(pcsFeatures) {}
+      : pcsFeatures_(pcsFeatures) {}
 
   /*
    * Method to encode the configurable fields in input dataset as per the active
@@ -41,12 +42,19 @@ class PCTranslator {
   std::string decode(const std::string& aggregatedOutputDataset);
 
  private:
-  std::string pcsfeatures_;
-  void retrieveInstructionSets(std::vector<std::string>& instructionSetNames);
+  std::string pcsFeatures_;
+  const std::string instructionSetBasePath =
+      "https://pc-translator.s3.us-west-2.amazonaws.com/";
+  std::vector<std::shared_ptr<PCInstructionSet>> retrieveInstructionSets(
+      std::vector<std::string>& instructionSetNames);
   std::vector<std::string> retrieveInstructionSetNamesForRun(
-      const std::string& pcsfeatures);
-  void parseInstructionSet(const std::string& instructionSet);
-  void transformDataset(const std::string& input);
+      const std::string& pcsFeatures);
+  std::shared_ptr<PCInstructionSet> parseInstructionSet(
+      std::string& instructionSet);
+  void transformDataset(
+      const std::string& input_data,
+      const std::vector<std::shared_ptr<pc_translator::PCInstructionSet>>&
+          pcInstructionSets);
 };
 
 } // namespace pc_translator

fbpcs/pc_translator/input_processing/FilterConstraint.cpp

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include "fbpcs/pc_translator/input_processing/FilterConstraint.h"
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace pc_translator {
+FilterConstraint::FilterConstraint(
+    const std::string& name,
+    const std::string& type,
+    int value)
+    : name_(name), type_(type), value_(value) {}
+
+std::string FilterConstraint::getName() const {
+  return name_;
+}
+
+std::string FilterConstraint::getType() const {
+  return type_;
+}
+
+int FilterConstraint::getValue() const {
+  return value_;
+}
+} // namespace pc_translator

fbpcs/pc_translator/input_processing/FilterConstraint.h

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace pc_translator {
+
+/*
+ * Class to store each filter constraint include in the PC instruction set.
+ */
+class FilterConstraint {
+ public:
+  FilterConstraint(const std::string& name, const std::string& type, int value);
+
+  /*
+   * Name of the filter constraint i.e. the field on which this filter is to be
+   * applied.
+   */
+  std::string getName() const;
+
+  /*
+   * Constraint type i.e. LT, LTE, EQ, NEQ etc.
+   */
+  std::string getType() const;
+
+  int getValue() const;
+
+ private:
+  std::string name_;
+  std::string type_;
+  int value_;
+};
+
+} // namespace pc_translator

fbpcs/pc_translator/input_processing/PCInstructionSet.cpp

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include "fbpcs/pc_translator/input_processing/PCInstructionSet.h"
+
+#include <folly/json.h>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace pc_translator {
+
+const std::vector<std::string>& PCInstructionSet::getGroupByIds() const {
+  return groupByIds;
+}
+
+const std::vector<FilterConstraint>& PCInstructionSet::getFilterConstraints()
+    const {
+  return filterConstraints;
+}
+
+PCInstructionSet PCInstructionSet::fromDynamic(const folly::dynamic& obj) {
+  PCInstructionSet pcInstructionSet;
+  auto aggregationConfig = obj["aggregated_metrics"];
+  auto groupByFields = aggregationConfig["group_by"];
+
+  for (auto groupByField : groupByFields) {
+    pcInstructionSet.groupByIds.push_back(groupByField.asString());
+  }
+
+  auto filterConstraintsFields = aggregationConfig["filter"];
+
+  for (auto& [key, constraints] : filterConstraintsFields.items()) {
+    std::string name = key.asString();
+    for (auto constraint : constraints) {
+      auto constraintType = constraint["constraint_type"].asString();
+      auto constraintValue = constraint["value"].asInt();
+      FilterConstraint filterConstraint(name, constraintType, constraintValue);
+      pcInstructionSet.filterConstraints.push_back(filterConstraint);
+    }
+  }
+
+  return pcInstructionSet;
+}
+
+} // namespace pc_translator

fbpcs/pc_translator/input_processing/PCInstructionSet.h

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <folly/json.h>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+#include "fbpcs/pc_translator/input_processing/FilterConstraint.h"
+
+namespace pc_translator {
+
+/*
+ * Class to store PC Instruction set. This class contains a list of group Ids as
+ * well as list of filter constraints.
+ */
+class PCInstructionSet {
+ public:
+  /*
+   * Method to all group Ids from the PC instruction set.
+   */
+  const std::vector<std::string>& getGroupByIds() const;
+
+  /*
+   * Method to get all filter constraints from PC instruction set.
+   */
+  const std::vector<FilterConstraint>& getFilterConstraints() const;
+
+  /*
+   * Method to get parse and create PCInstructionSet instance.
+   */
+  static PCInstructionSet fromDynamic(const folly::dynamic& obj);
+
+ private:
+  std::vector<std::string> groupByIds;
+  std::vector<FilterConstraint> filterConstraints;
+
+  void parseJson(const std::string& json);
+};
+
+} // namespace pc_translator

fbpcs/pc_translator/tests/input_processing/TestPCInstructionSet.cpp

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include <folly/json.h>
+#include <filesystem>
+#include <string>
+
+#include <fbpcf/io/api/FileIOWrappers.h>
+#include <gtest/gtest.h>
+#include "../../../emp_games/common/TestUtil.h"
+#include "fbpcs/pc_translator/input_processing/PCInstructionSet.h"
+#include "folly/Random.h"
+
+namespace pc_translator {
+class TestPCInstructionSet : public ::testing::Test {
+ public:
+ protected:
+  std::string testInstructionSetPath_;
+
+  void SetUp() override {
+    std::string baseDir =
+        private_measurement::test_util::getBaseDirFromPath(__FILE__);
+    testInstructionSetPath_ = baseDir + "test_instruction_set.json";
+  }
+};
+
+TEST_F(TestPCInstructionSet, TestStandardWorkflowTest) {
+  auto pcInstructionSet = std::make_shared<PCInstructionSet>(
+      PCInstructionSet::fromDynamic(folly::parseJson(
+          fbpcf::io::FileIOWrappers::readFile(testInstructionSetPath_))));
+  auto groupByIds = pcInstructionSet->getGroupByIds();
+  auto filterConstraints = pcInstructionSet->getFilterConstraints();
+  EXPECT_EQ(groupByIds.size(), 2);
+  EXPECT_EQ(filterConstraints.size(), 4);
+  EXPECT_EQ(filterConstraints[0].getName(), "gender");
+  EXPECT_EQ(filterConstraints[0].getType(), "EQ");
+  EXPECT_EQ(filterConstraints[0].getValue(), 0);
+}
+
+} // namespace pc_translator

fbpcs/pc_translator/tests/input_processing/test_instruction_set.json

@@ -0,0 +1,45 @@
+{
+    "publisher_input": {
+        "num_impressions": "int",
+        "num_clicks": "int",
+        "total_spend": "int",
+        "opportunity_timstamp": "int",
+        "test_flag": "int",
+        "age": "int",
+        "gender": "Optional[int]",
+        "breakdown_id": "Optional[int]"
+    },
+    "partner_input": {
+        "value": "int",
+        "event_timestamp": "int",
+        "partner_cohort_id": "Optional[int]"
+    },
+    "aggregated_metrics": {
+        "filter": {
+            "age": [
+                {
+                    "constraint_type": "GTE",
+                    "value": "25"
+                },
+                {
+                    "constraint_type": "LTE",
+                    "value": "40"
+                }
+            ],
+            "gender": [
+                {
+                    "constraint_type": "EQ",
+                    "value": "0"
+                },
+                {
+                    "constraint_type": "EQ",
+                    "value": "1"
+                }
+            ]
+        },
+        "group_by": [
+            "age",
+            "gender"
+        ]
+    }
+}