Enhance CMAB decision handling by returning reasons for decisions and updating type hints

Author: FarhanAnjum-opti

optimizely/cmab/cmab_service.py

@@ -15,7 +15,7 @@
 import hashlib
 import threading
 
-from typing import Optional, List, TypedDict
+from typing import Optional, List, TypedDict, Tuple
 from optimizely.cmab.cmab_client import DefaultCmabClient
 from optimizely.odp.lru_cache import LRUCache
 from optimizely.optimizely_user_context import OptimizelyUserContext, UserAttributes
@@ -65,26 +65,40 @@ def _get_lock_index(self, user_id: str, rule_id: str) -> int:
         return hash_value % NUM_LOCK_STRIPES
 
     def get_decision(self, project_config: ProjectConfig, user_context: OptimizelyUserContext,
-                     rule_id: str, options: List[str]) -> CmabDecision:
+                     rule_id: str, options: List[str]) -> Tuple[CmabDecision, List[str]]:
 
         lock_index = self._get_lock_index(user_context.user_id, rule_id)
         with self.locks[lock_index]:
             return self._get_decision(project_config, user_context, rule_id, options)
 
     def _get_decision(self, project_config: ProjectConfig, user_context: OptimizelyUserContext,
-                      rule_id: str, options: List[str]) -> CmabDecision:
+                      rule_id: str, options: List[str]) -> Tuple[CmabDecision, List[str]]:
 
         filtered_attributes = self._filter_attributes(project_config, user_context, rule_id)
+        reasons = []
 
         if OptimizelyDecideOption.IGNORE_CMAB_CACHE in options:
-            return self._fetch_decision(rule_id, user_context.user_id, filtered_attributes)
+            reason = f"Ignoring CMAB cache for user '{user_context.user_id}' and rule '{rule_id}'"
+            if self.logger:
+                self.logger.debug(reason)
+            reasons.append(reason)
+            cmab_decision = self._fetch_decision(rule_id, user_context.user_id, filtered_attributes)
+            return cmab_decision, reasons
 
         if OptimizelyDecideOption.RESET_CMAB_CACHE in options:
+            reason = f"Resetting CMAB cache for user '{user_context.user_id}' and rule '{rule_id}'"
+            if self.logger:
+                self.logger.debug(reason)
+            reasons.append(reason)
             self.cmab_cache.reset()
 
         cache_key = self._get_cache_key(user_context.user_id, rule_id)
 
         if OptimizelyDecideOption.INVALIDATE_USER_CMAB_CACHE in options:
+            reason = f"Invalidating CMAB cache for user '{user_context.user_id}' and rule '{rule_id}'"
+            if self.logger:
+                self.logger.debug(reason)
+            reasons.append(reason)
             self.cmab_cache.remove(cache_key)
 
         cached_value = self.cmab_cache.lookup(cache_key)
@@ -93,17 +107,35 @@ def _get_decision(self, project_config: ProjectConfig, user_context: OptimizelyU
 
         if cached_value:
             if cached_value['attributes_hash'] == attributes_hash:
-                return CmabDecision(variation_id=cached_value['variation_id'], cmab_uuid=cached_value['cmab_uuid'])
+                reason = f"CMAB cache hit for user '{user_context.user_id}' and rule '{rule_id}'"
+                if self.logger:
+                    self.logger.debug(reason)
+                reasons.append(reason)
+                return CmabDecision(variation_id=cached_value['variation_id'], cmab_uuid=cached_value['cmab_uuid']), reasons
             else:
+                reason = f"CMAB cache attributes mismatch for user '{user_context.user_id}' and rule '{rule_id}', fetching new decision."
+                if self.logger:
+                    self.logger.debug(reason)
+                reasons.append(reason)
                 self.cmab_cache.remove(cache_key)
+        else:
+            reason = f"CMAB cache miss for user '{user_context.user_id}' and rule '{rule_id}'"
+            if self.logger:
+                self.logger.debug(reason)
+            reasons.append(reason)
 
         cmab_decision = self._fetch_decision(rule_id, user_context.user_id, filtered_attributes)
+        reason = f"CMAB decision is {cmab_decision}"
+        if self.logger:
+            self.logger.debug(reason)
+        reasons.append(reason)
+
         self.cmab_cache.save(cache_key, {
             'attributes_hash': attributes_hash,
             'variation_id': cmab_decision['variation_id'],
             'cmab_uuid': cmab_decision['cmab_uuid'],
         })
-        return cmab_decision
+        return cmab_decision, reasons
 
     def _fetch_decision(self, rule_id: str, user_id: str, attributes: UserAttributes) -> CmabDecision:
         cmab_uuid = str(uuid.uuid4())

optimizely/decision_service.py

@@ -175,9 +175,10 @@ def _get_decision_for_cmab_experiment(
         # User is in CMAB allocation, proceed to CMAB decision
         try:
             options_list = list(options) if options is not None else []
-            cmab_decision = self.cmab_service.get_decision(
+            cmab_decision, cmab_reasons = self.cmab_service.get_decision(
                 project_config, user_context, experiment.id, options_list
             )
+            decide_reasons.extend(cmab_reasons)
             return {
                 "error": False,
                 "result": cmab_decision,

optimizely/event/event_processor.py

@@ -72,7 +72,7 @@ class Signal:
 
     def __init__(
         self,
-        event_dispatcher: Optional[type[EventDispatcher] | CustomEventDispatcher] = None,
+        event_dispatcher: Optional[EventDispatcher | CustomEventDispatcher] = None,
         logger: Optional[_logging.Logger] = None,
         start_on_init: bool = False,
         event_queue: Optional[queue.Queue[UserEvent | Signal]] = None,

tests/test_cmab_service.py

@@ -60,7 +60,7 @@ def test_returns_decision_from_cache_when_valid(self):
             "cmab_uuid": "uuid-123"
         }
 
-        decision = self.cmab_service.get_decision(
+        decision, _ = self.cmab_service.get_decision(
             self.mock_project_config, self.mock_user_context, "exp1", []
         )
 
@@ -72,7 +72,7 @@ def test_ignores_cache_when_option_given(self):
         self.mock_cmab_client.fetch_decision.return_value = "varB"
         expected_attributes = {"age": 25, "location": "USA"}
 
-        decision = self.cmab_service.get_decision(
+        decision, _ = self.cmab_service.get_decision(
             self.mock_project_config,
             self.mock_user_context,
             "exp1",
@@ -105,7 +105,7 @@ def test_invalidates_user_cache_when_option_given(self):
     def test_resets_cache_when_option_given(self):
         self.mock_cmab_client.fetch_decision.return_value = "varD"
 
-        decision = self.cmab_service.get_decision(
+        decision, _ = self.cmab_service.get_decision(
             self.mock_project_config,
             self.mock_user_context,
             "exp1",
@@ -128,7 +128,7 @@ def test_new_decision_when_hash_changes(self):
         expected_hash = self.cmab_service._hash_attributes(expected_attribute)
         expected_key = self.cmab_service._get_cache_key("user123", "exp1")
 
-        decision = self.cmab_service.get_decision(self.mock_project_config, self.mock_user_context, "exp1", [])
+        decision, _ = self.cmab_service.get_decision(self.mock_project_config, self.mock_user_context, "exp1", [])
         self.mock_cmab_cache.remove.assert_called_once_with(expected_key)
         self.mock_cmab_cache.save.assert_called_once_with(
             expected_key,
@@ -171,7 +171,7 @@ def test_only_cmab_attributes_passed_to_client(self):
         }
         self.mock_cmab_client.fetch_decision.return_value = "varF"
 
-        decision = self.cmab_service.get_decision(
+        decision, _ = self.cmab_service.get_decision(
             self.mock_project_config,
             self.mock_user_context,
             "exp1",

tests/test_decision_service.py

@@ -792,10 +792,13 @@ def test_get_variation_cmab_experiment_user_in_traffic_allocation(self):
                               'logger') as mock_logger:
 
             # Configure CMAB service to return a decision
-            mock_cmab_service.get_decision.return_value = {
-                'variation_id': '111151',
-                'cmab_uuid': 'test-cmab-uuid-123'
-            }
+            mock_cmab_service.get_decision.return_value = (
+                {
+                    'variation_id': '111151',
+                    'cmab_uuid': 'test-cmab-uuid-123'
+                },
+                []  # reasons list
+            )
 
             # Call get_variation with the CMAB experiment
             variation_result = self.decision_service.get_variation(