[FSSDK-11175] Update: Implement Decision Service methods to handle CMAB

optimizely/bucketer.py

@@ -28,7 +28,7 @@
 if TYPE_CHECKING:
     # prevent circular dependenacy by skipping import at runtime
     from .project_config import ProjectConfig
-    from .entities import Experiment, Variation
+    from .entities import Experiment, Variation, Group
     from .helpers.types import TrafficAllocation
 
 
@@ -164,3 +164,67 @@ def bucket(
             decide_reasons.append(message)
 
         return None, decide_reasons
+
+    def bucket_to_entity_id(
+        self,
+        bucketing_id: str,
+        experiment: Experiment,
+        traffic_allocations: list[TrafficAllocation],
+        group: Optional[Group] = None
+    ) -> tuple[Optional[str], list[str]]:
+        """
+        Buckets the user and returns the entity ID (for CMAB experiments).
+        Args:
+            bucketing_id: The bucketing ID string for the user.
+            experiment: The experiment object (for group/groupPolicy logic if needed).
+            traffic_allocations: List of traffic allocation dicts (should have 'entity_id' and 'end_of_range' keys).
+            group: (optional) Group object for mutex group support.
+
+        Returns:
+            Tuple of (entity_id or None, list of decide reasons).
+        """
+        decide_reasons = []
+
+        group_id = getattr(experiment, 'groupId', None)
+        if group_id and group and getattr(group, 'policy', None) == 'random':
+            bucket_key = bucketing_id + group_id
+            bucket_val = self._generate_bucket_value(bucket_key)
+            decide_reasons.append(f'Generated group bucket value {bucket_val} for key "{bucket_key}".')
+
+            matched = False
+            for allocation in group.trafficAllocation:
+                end_of_range = allocation['endOfRange']
+                entity_id = allocation['entityId']
+                if bucket_val < end_of_range:
+                    matched = True
+                    if entity_id != experiment.id:
+                        decide_reasons.append(
+                            f'User not bucketed into experiment "{experiment.id}" (got "{entity_id}").'
+                        )
+                        return None, decide_reasons
+                    decide_reasons.append(
+                        f'User is bucketed into experiment "{experiment.id}" within group "{group_id}".'
+                    )
+                    break
+            if not matched:
+                decide_reasons.append(
+                    f'User not bucketed into any experiment in group "{group_id}".'
+                )
+                return None, decide_reasons
+
+        # Main experiment bucketing
+        bucket_key = bucketing_id + experiment.id
+        bucket_val = self._generate_bucket_value(bucket_key)
+        decide_reasons.append(f'Generated experiment bucket value {bucket_val} for key "{bucket_key}".')
+
+        for allocation in traffic_allocations:
+            end_of_range = allocation['endOfRange']
+            entity_id = allocation['entityId']
+            if bucket_val < end_of_range:
+                decide_reasons.append(
+                    f'User bucketed into entity id "{entity_id}".'
+                )
+                return entity_id, decide_reasons
+
+        decide_reasons.append('User not bucketed into any entity id.')
+        return None, decide_reasons

optimizely/cmab/__init__.py

@@ -0,0 +1,12 @@
+# Copyright 2025, Optimizely
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

optimizely/cmab/cmab_service.py

@@ -35,6 +35,18 @@ class CmabCacheValue(TypedDict):
 
 
 class DefaultCmabService:
+    """
+    DefaultCmabService handles decisioning for Contextual Multi-Armed Bandit (CMAB) experiments,
+    including caching and filtering user attributes for efficient decision retrieval.
+
+    Attributes:
+        cmab_cache: LRUCache for user CMAB decisions.
+        cmab_client: Client to fetch decisions from the CMAB backend.
+        logger: Optional logger.
+
+    Methods:
+        get_decision: Retrieves a CMAB decision with caching and attribute filtering.
+    """
     def __init__(self, cmab_cache: LRUCache[str, CmabCacheValue],
                  cmab_client: DefaultCmabClient, logger: Optional[_logging.Logger] = None):
         self.cmab_cache = cmab_cache