Update bandit action context examples to use attributes only related to subject-action interaction (#504)

* update examples

* update general page on action contexts

* feedback from PR

* changes from self-review

Author: aarsilv

docs/contextual-bandits/actions_contexts.md

@@ -11,7 +11,7 @@ At a high level, to select a particular action, the Contextual Bandit performs t
 
 There are two processes at play that make the Contextual Bandit work:
 
-1. **Real-time decision making**: based on provided actions and contexts, select an action
+1. **Real-time decision-making**: based on provided actions and contexts, select an action
 2. **Model updating**: periodically, update the parameters of the Contextual Bandit based on outcome data.
 
 ## Bandit objective
@@ -32,7 +32,7 @@ Consider optimizing across multiple product promotions that we can show the user
 We can leverage the built-in [experiment analysis](/contextual-bandits/analysis) to verify that the selected objective is well-aligned with improving long term outcomes.
 :::
 
-## Real-time decision making
+## Real-time decision-making
 
 In order to make real-time decisions, you provide Eppo with actions and contexts that are relevant to personalize the experience.
 The Eppo SDK then uses the underlying Contextual Bandit model to select an action, balancing exploration and exploitation; learning and optimizing at the same time.
@@ -61,31 +61,35 @@ Contextual Bandits automatically explore new actions as they are encountered and
 
 To create a bandit policy that personalizes, you need to provide context. 
 
-Generally, there are three types of context:
-1. Subject context: For example, the subjects's past behavior, demographic information, are they on a mobile device, etc.
-2. Action context: For example, the size of the discount, the type of product, the price, etc.
-3. Subject-action interaction context: For example, the brand affinity of the subject to the product (based on past purchases, user reviews, etc.)
+Generally, there are two types of context:
+1. Subject context: For example, the subject's past behavior, demographic information, whether they are on a mobile device, etc.
+2. Action (Subject-action interaction) context: For example, the number of previous purchases of the action's brand or product category.
 
-Note that the first of these is independent of the actions, while the other two are action dependent. 
-For convenience, you can supply the subject attributes once and they will be used across all actions, while
-separately, you can supply action specific attributes.
+Note that the first of these is independent of the actions, while the other is action dependent. 
+The subject attributes are provided directly and not tied to a specific action, while separately, you can supply action-specific attributes for each action.
 Behind the scenes, we combine the two to create a single context per action that is used by the underlying model to select which action to pick.
 
+:::info Currently, we build bandit models on a per-action basis
+Be sure action attributes are subject-specific. Any action attributes that are not specific to the subject will end up
+being the same for all subjects and be ignored as they will not be predictive.
+:::
+
+
 #### Subject attributes
 
 Subject attributes capture information about the subject that is relevant to the actions. 
 Generic attributes such as age (bucket), gender, and device information can be helpful, but the most salient attributes are product specific.
 
 #### Action attributes
 
-Action attributes capture information that is unique to a particular action. For example, the discount offered in a promotion, the price of a product, etc.
-Furthermore, you can also leverage action attributes to include information that is specific to the subject-action pair. For example, you can leverage an internal Machine Learning model that measures brand affinity.
+Action attributes capture information that is unique to a particular action for the subject. For example, the number of
+previous purchases the subject has made of the action's brand or product category.
 
 :::info What context attributes to use
 Selection of which attributes to include in the context is a bit of an art.
 
 In general, there are two types of attributes that will help the Contextual Bandit efficiently learn a strong policy:
-1. Attributes that provide a strong signal on personalization: For example, the brand affinity of the subject to the product, the price, etc.
+1. Attributes that provide a strong signal on personalization: For example, the brand affinity of the subject to the product.
 2. Attributes that predict the outcome of an action: For example, when optimizing for purchases, whether a user is a new or returning user might not affect which action is best, but it can help reduce variance (similar to CUPED), helping the contextual bandit learn more efficiently
 :::
 

docs/sdks/sdk-features/bandits.md

@@ -38,11 +38,11 @@ subject_attributes = eppo_client.bandit.ContextAttributes(
 actions = {
   "nike": eppo_client.bandit.ContextAttributes(
     numeric_attributes={"brand_affinity": 2.3},
-    categorical_attributes={"aspect_ratio": "16:9"}
+    categorical_attributes={"previously_purchased": true}
   ),
   "adidas": eppo_client.bandit.ContextAttributes(
     numeric_attributes={"brand_affinity": 0.2},
-    categorical_attributes={"aspect_ratio": "16:9"}
+    categorical_attributes={"previously_purchased": false}
   )
 }
 

docs/sdks/server-sdks/java.md

@@ -186,8 +186,8 @@ The properties of the event object passed to the bandit logger, accessible via g
 | `subjectNumericAttributes` (Attributes)     | Metadata about numeric attributes of the subject. Map of the name of attributes their provided values             | {age=60}                     |
 | `subjectCategoricalAttributes` (Attributes) | Metadata about non-numeric attributes of the subject. Map of the name of attributes their provided values         | {country=FR}                 |
 | `action` (String)                           | The action assigned by the bandit                                                                                 | "promo-20%-off"              |
-| `actionNumericAttributes` (Attributes)      | Metadata about numeric attributes of the assigned action. Map of the name of attributes their provided values     | {discount=0.2}               |
-| `actionCategoricalAttributes` (Attributes)  | Metadata about non-numeric attributes of the assigned action. Map of the name of attributes their provided values | {promoTextColor=white}       |
+| `actionNumericAttributes` (Attributes)      | Metadata about numeric attributes of the assigned action. Map of the name of attributes their provided values     | {brandAffinity=0.3}          |
+| `actionCategoricalAttributes` (Attributes)  | Metadata about non-numeric attributes of the assigned action. Map of the name of attributes their provided values | {previouslyPurchased=false}  |
 | `actionProbability` (Double)                | The weight between 0 and 1 the bandit valued the assigned action                                                  | 0.25                         |
 | `optimalityGap` (Double)                    | The difference between the score of the selected action and the highest-scored action                             | 456                          |
 | `modelVersion` (String)                     | The key for the version (iteration) of the bandit parameters used to determine the action probability             | "v123"                       |
@@ -233,14 +233,14 @@ Actions actions = new BanditActions(
     new Attributes(
       Map.of(
         "brandAffinity", EppoValue.valueOf(2.3),
-        "imageAspectRatio", EppoValue.valueOf("16:9")
+        "previouslyPurchased", EppoValue.valueOf(true)
       )
     ),
     "adidas",
     new Attributes(
       Map.of(
         "brandAffinity", EppoValue.valueOf(0.2),
-        "imageAspectRatio",  EppoValue.valueOf("16:9")
+        "previouslyPurchased", EppoValue.valueOf(false)
       )
     )
   )
@@ -318,10 +318,9 @@ Similar to subject context, action contexts can be provided as `Attributes`--whi
 is a numeric attribute, and everything else is a categorical attribute--or as `ContextAttributes`, which have explicit 
 bucketing into `numericAttributes` and `categoricalAttributes`.
 
-Note that action contexts can contain two kinds of information:
-- Action-specific context (e.g., the image aspect ratio of image corresponding to this action)
-- Subject-action interaction context (e.g., there could be a "brand-affinity" model that computes brand affinities of users  
-  to brands, and scores of that model can be added to the action context to provide additional context for the bandit)
+Note that relevant action contexts are subject-action interactions. For example, there could be a "brand-affinity" model 
+that computes brand affinities of users to brands, and scores of that model can be added to the action context to provide 
+additional context for the bandit.
 
 If there is no action context, you can use a `Set<String>` of all the action names when constructing `BanditActions` to
 pass in.

docs/sdks/server-sdks/node.md

@@ -484,21 +484,21 @@ await init({
 
 The SDK will invoke the `logBanditAction()` function with an `IBanditEvent` object that contains the following fields:
 
-| Field                                       | Description                                                                                                       | Example                        |
-|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------|--------------------------------|
-| `timestamp` (string)                        | The time when the action is taken in UTC as an ISO string                                                         | "2024-03-22T14:26:55.000Z"     |
-| `featureFlag` (string)                      | The key of the feature flag corresponding to the bandit                                                           | "bandit-test-allocation-4"     |
-| `bandit` (string)                           | The key (unique identifier) of the bandit                                                                         | "ad-bandit-1"                  |
-| `subject` (string)                          | An identifier of the subject or user assigned to the experiment variation                                         | "ed6f85019080"                 |
-| `subjectNumericAttributes` (Attributes)     | Metadata about numeric attributes of the subject. Map of the name of attributes their provided values             | `{"age": 30}`                  |
-| `subjectCategoricalAttributes` (Attributes) | Metadata about non-numeric attributes of the subject. Map of the name of attributes their provided values         | `{"loyalty_tier": "gold"}`     |
-| `action` (string)                           | The action assigned by the bandit                                                                                 | "promo-20%-off"                |
-| `actionNumericAttributes` (Attributes)      | Metadata about numeric attributes of the assigned action. Map of the name of attributes their provided values     | `{"discount": 0.2}`            |
-| `actionCategoricalAttributes` (Attributes)  | Metadata about non-numeric attributes of the assigned action. Map of the name of attributes their provided values | `{"promoTextColor": "white"}`  |
-| `actionProbability` (number)                | The weight between 0 and 1 the bandit valued the assigned action                                                  | 0.25                           |
-| `optimalityGap` (number)                    | The difference between the score of the selected action and the highest-scored action                             | 456                            | 
-| `modelVersion` (string)                     | Unique identifier for the version (iteration) of the bandit parameters used to determine the action probability   | "v123"                         |
-| `metaData` Record<string, unknown>          | Any additional freeform meta data, such as the version of the SDK                                                 | `{ "sdkLibVersion": "3.5.1" }` |
+| Field                                       | Description                                                                                                       | Example                          |
+|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------|----------------------------------|
+| `timestamp` (string)                        | The time when the action is taken in UTC as an ISO string                                                         | "2024-03-22T14:26:55.000Z"       |
+| `featureFlag` (string)                      | The key of the feature flag corresponding to the bandit                                                           | "bandit-test-allocation-4"       |
+| `bandit` (string)                           | The key (unique identifier) of the bandit                                                                         | "ad-bandit-1"                    |
+| `subject` (string)                          | An identifier of the subject or user assigned to the experiment variation                                         | "ed6f85019080"                   |
+| `subjectNumericAttributes` (Attributes)     | Metadata about numeric attributes of the subject. Map of the name of attributes their provided values             | `{"age": 30}`                    |
+| `subjectCategoricalAttributes` (Attributes) | Metadata about non-numeric attributes of the subject. Map of the name of attributes their provided values         | `{"loyalty_tier": "gold"}`       |
+| `action` (string)                           | The action assigned by the bandit                                                                                 | "promo-20%-off"                  |
+| `actionNumericAttributes` (Attributes)      | Metadata about numeric attributes of the assigned action. Map of the name of attributes their provided values     | `{"brandAffinity": 0.2}`         |
+| `actionCategoricalAttributes` (Attributes)  | Metadata about non-numeric attributes of the assigned action. Map of the name of attributes their provided values | `{"previouslyPurchased": false}` |
+| `actionProbability` (number)                | The weight between 0 and 1 the bandit valued the assigned action                                                  | 0.25                             |
+| `optimalityGap` (number)                    | The difference between the score of the selected action and the highest-scored action                             | 456                              | 
+| `modelVersion` (string)                     | Unique identifier for the version (iteration) of the bandit parameters used to determine the action probability   | "v123"                           |
+| `metaData` Record<string, unknown>          | Any additional freeform meta data, such as the version of the SDK                                                 | `{ "sdkLibVersion": "3.5.1" }`   |
 
 ### Querying the bandit for an action
 
@@ -579,10 +579,9 @@ Similar to subject context, action contexts can be provided as `Attributes`--whi
 attribute, and everything else is a categorical attribute--or as `ContextAttributes`, which have explicit bucketing into `numericAttributes`
 and `categoricalAttributes`.
 
-Note that action contexts can contain two kinds of information:
-- Action-specific context (e.g., the image aspect ratio of image corresponding to this action)
-- Subject-action interaction context (e.g., there could be a "brand-affinity" model that computes brand affinities of users to brands,   
-  and scores of that model can be added to the action context to provide additional context for the bandit)
+Note that relevant action contexts are subject-action interactions. For example, there could be a "brand-affinity" model
+that computes brand affinities of users to brands, and scores of that model can be added to the action context to provide
+additional context for the bandit.
 
 If there is no action context, an array of strings comprising only the actions names can also be passed in.