feat: getBestBanditAction (#161)

* move bandit event logging up
* extract action sorting
* bump version for release

Author: typotter

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eppo/js-client-sdk-common",
-  "version": "4.5.4",
+  "version": "4.6.0",
   "description": "Eppo SDK for client-side JavaScript applications (base for both web and react native)",
   "main": "dist/index.js",
   "files": [

src/bandit-evaluator.spec.ts

@@ -425,4 +425,94 @@ describe('BanditEvaluator', () => {
       expect(resultB.optimalityGap).toBeCloseTo(0.3);
     });
   });
+
+  describe('evaluateBestBandit', () => {
+    it('evaluates the bandit with action contexts', () => {
+      const subjectAttributes: ContextAttributes = {
+        numericAttributes: { age: 25 },
+        categoricalAttributes: { location: 'US' },
+      };
+      const subjectAttributesB: ContextAttributes = {
+        numericAttributes: { age: 25 },
+        categoricalAttributes: {},
+      };
+      const actions: Record<string, ContextAttributes> = {
+        action1: { numericAttributes: { price: 10 }, categoricalAttributes: { category: 'A' } },
+        action2: { numericAttributes: { price: 20 }, categoricalAttributes: { category: 'B' } },
+      };
+      const banditModel: BanditModelData = {
+        gamma: 0.1,
+        defaultActionScore: 0.0,
+        actionProbabilityFloor: 0.1,
+        coefficients: {
+          action1: {
+            actionKey: 'action1',
+            intercept: 0.5,
+            subjectNumericCoefficients: [
+              { attributeKey: 'age', coefficient: 0.1, missingValueCoefficient: 0.0 },
+            ],
+            subjectCategoricalCoefficients: [
+              {
+                attributeKey: 'location',
+                missingValueCoefficient: 0.0,
+                valueCoefficients: { US: 0.2 },
+              },
+            ],
+            actionNumericCoefficients: [
+              { attributeKey: 'price', coefficient: 0.05, missingValueCoefficient: 0.0 },
+            ],
+            actionCategoricalCoefficients: [
+              {
+                attributeKey: 'category',
+                missingValueCoefficient: 0.0,
+                valueCoefficients: { A: 0.3 },
+              },
+            ],
+          },
+          action2: {
+            actionKey: 'action2',
+            intercept: 0.3,
+            subjectNumericCoefficients: [
+              { attributeKey: 'age', coefficient: 0.1, missingValueCoefficient: 0.0 },
+            ],
+            subjectCategoricalCoefficients: [
+              {
+                attributeKey: 'location',
+                missingValueCoefficient: -3.0,
+                valueCoefficients: { US: 0.2 },
+              },
+            ],
+            actionNumericCoefficients: [
+              { attributeKey: 'price', coefficient: 0.05, missingValueCoefficient: 0.0 },
+            ],
+            actionCategoricalCoefficients: [
+              {
+                attributeKey: 'category',
+                missingValueCoefficient: 0.0,
+                valueCoefficients: { B: 0.3 },
+              },
+            ],
+          },
+        },
+      };
+
+      // Subject A gets assigned action 2
+      const resultA = banditEvaluator.evaluateBestBanditAction(
+        subjectAttributes,
+        actions,
+        banditModel,
+      );
+
+      expect(resultA).toEqual('action2');
+
+      // Subject B gets assigned action 1 because of the missing location penalty
+      const resultB = banditEvaluator.evaluateBestBanditAction(
+        subjectAttributesB,
+        actions,
+        banditModel,
+      );
+
+      expect(resultB).toEqual('action1');
+    });
+  });
 });

src/bandit-evaluator.ts

@@ -23,6 +23,21 @@ export class BanditEvaluator {
   private readonly assignmentShards = BANDIT_ASSIGNMENT_SHARDS; // We just hard code this for now
   private readonly sharder: Sharder = new MD5Sharder();
 
+  public evaluateBestBanditAction(
+    subjectAttributes: ContextAttributes,
+    actions: Record<string, ContextAttributes>,
+    banditModel: BanditModelData,
+  ): string | null {
+    const actionScores: Record<string, number> = this.scoreActions(
+      subjectAttributes,
+      actions,
+      banditModel,
+    );
+
+    const { topAction } = this.getTopScore(actionScores);
+    return topAction;
+  }
+
   public evaluateBandit(
     flagKey: string,
     subjectKey: string,
@@ -140,20 +155,7 @@ export class BanditEvaluator {
       return actionWeights;
     }
 
-    // First find the action with the highest score
-    let currTopScore: number | null = null;
-    let currTopAction: string | null = null;
-    actionScoreEntries.forEach(([actionKey, actionScore]) => {
-      if (
-        currTopScore === null ||
-        currTopAction === null ||
-        actionScore > currTopScore ||
-        (actionScore === currTopScore && actionKey < currTopAction)
-      ) {
-        currTopScore = actionScore;
-        currTopAction = actionKey;
-      }
-    });
+    const { topScore: currTopScore, topAction: currTopAction } = this.getTopScore(actionScores);
 
     if (currTopScore === null || currTopAction === null) {
       // Appease typescript with this check and extra variables
@@ -228,4 +230,27 @@ export class BanditEvaluator {
     }
     return assignedAction;
   }
+
+  private getTopScore(actionScores: Record<string, number>): {
+    topScore: number | null;
+    topAction: string | null;
+  } {
+    const actionScoreEntries = Object.entries(actionScores);
+    // Find the action with the highest score, tie-breaking by name, selecting the alpha-numerically smaller key.
+    let topScore: number | null = null;
+    let topAction: string | null = null;
+    actionScoreEntries.forEach(([actionKey, actionScore]) => {
+      if (
+        topScore === null ||
+        topAction === null ||
+        actionScore > topScore ||
+        (actionScore === topScore && actionKey < topAction)
+      ) {
+        topScore = actionScore;
+        topAction = actionKey;
+      }
+    });
+
+    return { topScore, topAction };
+  }
 }

src/client/eppo-client-with-bandits.spec.ts

@@ -452,6 +452,41 @@ describe('EppoClient Bandits E2E test', () => {
       });
     });
 
+    describe('Best bandit action', () => {
+      it('Selects the highest scoring action', async () => {
+        const actions: Record<string, ContextAttributes> = {
+          nike: {
+            numericAttributes: { brand_affinity: 1.0 },
+            categoricalAttributes: {},
+          },
+          adidas: {
+            numericAttributes: { brand_affinity: 1.0 },
+            categoricalAttributes: {},
+          },
+          reebok: {
+            numericAttributes: { brand_affinity: 2.0 },
+            categoricalAttributes: {},
+          },
+        };
+
+        const subjectAttributesWithAreaCode: Attributes = {
+          age: 25,
+          mistake: 'oops',
+          country: 'USA',
+          gender_identity: 'female',
+          area_code: '303', // categorical area code
+        };
+
+        const banditAssignment = client.getBestAction(
+          flagKey,
+          subjectAttributesWithAreaCode,
+          actions,
+          'default',
+        );
+        expect(banditAssignment).toBe('adidas');
+      });
+    });
+
     describe('Assignment logging deduplication', () => {
       let mockEvaluateFlag: jest.SpyInstance;
       let mockEvaluateBandit: jest.SpyInstance;

src/client/eppo-client.ts

@@ -501,6 +501,47 @@ export default class EppoClient {
     return { variation, action };
   }
 
+  /**
+   * Evaluates the supplied actions using the first bandit associated with `flagKey` and returns the best ranked action.
+   *
+   * This method should be considered **preview** and is subject to change as requirements mature.
+   *
+   * NOTE: This method does not do any logging or assignment computation and so calling this method will have
+   * NO IMPACT on bandit and experiment training.
+   *
+   * Only use this method under certain circumstances (i.e. where the impact of the choice of bandit cannot be measured,
+   * but you want to put the "best foot forward", for example, when being web-crawled).
+   *
+   */
+  getBestAction(
+    flagKey: string,
+    subjectAttributes: BanditSubjectAttributes,
+    actions: BanditActions,
+    defaultAction: string,
+  ): string {
+    let result: string | null = null;
+
+    const flagBanditVariations = this.banditVariationConfigurationStore?.get(flagKey);
+    const banditKey = flagBanditVariations?.at(0)?.key;
+
+    if (banditKey) {
+      const banditParameters = this.banditModelConfigurationStore?.get(banditKey);
+      if (banditParameters) {
+        const contextualSubjectAttributes =
+          this.ensureContextualSubjectAttributes(subjectAttributes);
+        const actionsWithContextualAttributes = this.ensureActionsWithContextualAttributes(actions);
+
+        result = this.banditEvaluator.evaluateBestBanditAction(
+          contextualSubjectAttributes,
+          actionsWithContextualAttributes,
+          banditParameters.modelData,
+        );
+      }
+    }
+
+    return result ?? defaultAction;
+  }
+
   getBanditActionDetails(
     flagKey: string,
     subjectKey: string,