optimizely-sdk 5.1.0__tar.gz → 5.3.0__tar.gz

{optimizely_sdk-5.1.0 → optimizely_sdk-5.3.0}/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Optimizely Python SDK Changelog
 
+## 5.3.0
+November 13th, 2025
+
+This release introduces **Contextual Multi-Armed Bandit (CMAB)** support in the Optimizely Python SDK along with several enhancements, bug fixes, and infrastructure improvements.
+
+---
+
+### New Features
+
+#### **CMAB Support**
+
+A major addition in this release is support for **Contextual Multi-Armed Bandit (CMAB)**, enabling adaptive experimentation based on contextual user data.
+
+The CMAB feature includes:
+
+- CMAB Client and Service implementations to communicate with CMAB APIs ([#453](https://github.com/optimizely/python-sdk/pull/453), [#455](https://github.com/optimizely/python-sdk/pull/455))
+- Decision Service updates to handle CMAB-based decisioning ([#457](https://github.com/optimizely/python-sdk/pull/457))
+- Impression event updates to include CMAB UUID ([#458](https://github.com/optimizely/python-sdk/pull/458))
+- Cache system enhancements including a new `remove()` method for CMAB cache ([#454](https://github.com/optimizely/python-sdk/pull/454))
+- Configuration options to customize CMAB cache parameters ([#463](https://github.com/optimizely/python-sdk/pull/463))
+- Exposure of CMAB prediction endpoint for programmatic access ([#466](https://github.com/optimizely/python-sdk/pull/466))
+
+These updates collectively enable Python SDK users to leverage machine learning–driven bandit optimization strategies within Optimizely Feature Experimentation.
+
+---
+
+#### **Multi-Region Data Hosting**
+
+- Added SDK support for multi-region data hosting, allowing projects to specify their data residency region ([#459](https://github.com/optimizely/python-sdk/pull/459)).
+
+---
+
+### Security Fixes
+
+- Addressed a CSRF security warning by properly importing and registering `CSRFProtect`  
+  ([#448](https://github.com/optimizely/python-sdk/pull/448), [#450](https://github.com/optimizely/python-sdk/pull/450), [#452](https://github.com/optimizely/python-sdk/pull/452)).
+
+---
+
+### Enhancements
+
+- Updated project configuration to track CMAB properties ([#451](https://github.com/optimizely/python-sdk/pull/451)).
+- Removed unused `testapp` folder from tests as part of maintenance cleanup ([#461](https://github.com/optimizely/python-sdk/pull/461)).
+
+---
+
+### Bug Fixes
+
+- Fixed concurrency issues in CMAB service to ensure thread-safe cache and decision logic ([#462](https://github.com/optimizely/python-sdk/pull/462)).
+
+---
+
+### New Contributors
+
+- [@esrakartalOpt](https://github.com/esrakartalOpt) made their first contribution in [#459](https://github.com/optimizely/python-sdk/pull/459).
+
+---
+
+
+## 5.2.0
+February 26, 2025
+
+Python threads have been named.
+
+`PollingConfigManager` now has another optional parameter `retries` that will control how many times the SDK will attempt to get the datafile if the connection fails. Previously, the SDK would only try once. Now it defaults to maximum of three attempts. When sending event data, the SDK will attempt to send event data up to three times, where as before it would only attempt once.
+
 ## 5.1.0
 November 27th, 2024
 

{optimizely_sdk-5.1.0/optimizely_sdk.egg-info → optimizely_sdk-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: optimizely-sdk
-Version: 5.1.0
+Version: 5.3.0
 Summary: Python SDK for Optimizely Feature Experimentation, Optimizely Full Stack (legacy), and Optimizely Rollouts.
 Home-page: https://github.com/optimizely/python-sdk
 Author: Optimizely
@@ -22,17 +22,29 @@ Requires-Dist: jsonschema>=3.2.0
 Requires-Dist: pyrsistent>=0.16.0
 Requires-Dist: requests>=2.21
 Requires-Dist: idna>=2.10
+Requires-Dist: rpds-py<0.20.0; python_version < "3.11"
 Provides-Extra: test
-Requires-Dist: pytest-cov; extra == "test"
-Requires-Dist: idna>=2.10; extra == "test"
+Requires-Dist: flake8>=4.0.1; extra == "test"
+Requires-Dist: python-coveralls; extra == "test"
 Requires-Dist: jsonschema>=3.2.0; extra == "test"
+Requires-Dist: rpds-py<0.20.0; python_version < "3.11" and extra == "test"
 Requires-Dist: requests>=2.21; extra == "test"
-Requires-Dist: funcsigs>=0.4; extra == "test"
+Requires-Dist: pyrsistent>=0.16.0; extra == "test"
+Requires-Dist: idna>=2.10; extra == "test"
 Requires-Dist: pytest>=6.2.0; extra == "test"
-Requires-Dist: python-coveralls; extra == "test"
 Requires-Dist: coverage; extra == "test"
-Requires-Dist: flake8>=4.0.1; extra == "test"
-Requires-Dist: pyrsistent>=0.16.0; extra == "test"
+Requires-Dist: funcsigs>=0.4; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
 
 Optimizely Feature Experimentation is A/B testing and feature management for product development teams. Experiment in any application. Make every feature on your roadmap an opportunity to learn. Learn more at https://www.optimizely.com/products/experiment/feature-experimentation/ or see our documentation at https://docs.developers.optimizely.com/experimentation/v4.0.0-full-stack/docs/welcome. # Optimizely Python SDK
 
@@ -292,6 +304,72 @@ idna (BSD 3-Clause License https://github.com/kjd/idna/blob/master/LICENSE.md)
 - Swift - https://github.com/optimizely/swift-sdk
 # Optimizely Python SDK Changelog
 
+## 5.3.0
+November 13th, 2025
+
+This release introduces **Contextual Multi-Armed Bandit (CMAB)** support in the Optimizely Python SDK along with several enhancements, bug fixes, and infrastructure improvements.
+
+---
+
+### New Features
+
+#### **CMAB Support**
+
+A major addition in this release is support for **Contextual Multi-Armed Bandit (CMAB)**, enabling adaptive experimentation based on contextual user data.
+
+The CMAB feature includes:
+
+- CMAB Client and Service implementations to communicate with CMAB APIs ([#453](https://github.com/optimizely/python-sdk/pull/453), [#455](https://github.com/optimizely/python-sdk/pull/455))
+- Decision Service updates to handle CMAB-based decisioning ([#457](https://github.com/optimizely/python-sdk/pull/457))
+- Impression event updates to include CMAB UUID ([#458](https://github.com/optimizely/python-sdk/pull/458))
+- Cache system enhancements including a new `remove()` method for CMAB cache ([#454](https://github.com/optimizely/python-sdk/pull/454))
+- Configuration options to customize CMAB cache parameters ([#463](https://github.com/optimizely/python-sdk/pull/463))
+- Exposure of CMAB prediction endpoint for programmatic access ([#466](https://github.com/optimizely/python-sdk/pull/466))
+
+These updates collectively enable Python SDK users to leverage machine learning–driven bandit optimization strategies within Optimizely Feature Experimentation.
+
+---
+
+#### **Multi-Region Data Hosting**
+
+- Added SDK support for multi-region data hosting, allowing projects to specify their data residency region ([#459](https://github.com/optimizely/python-sdk/pull/459)).
+
+---
+
+### Security Fixes
+
+- Addressed a CSRF security warning by properly importing and registering `CSRFProtect`  
+  ([#448](https://github.com/optimizely/python-sdk/pull/448), [#450](https://github.com/optimizely/python-sdk/pull/450), [#452](https://github.com/optimizely/python-sdk/pull/452)).
+
+---
+
+### Enhancements
+
+- Updated project configuration to track CMAB properties ([#451](https://github.com/optimizely/python-sdk/pull/451)).
+- Removed unused `testapp` folder from tests as part of maintenance cleanup ([#461](https://github.com/optimizely/python-sdk/pull/461)).
+
+---
+
+### Bug Fixes
+
+- Fixed concurrency issues in CMAB service to ensure thread-safe cache and decision logic ([#462](https://github.com/optimizely/python-sdk/pull/462)).
+
+---
+
+### New Contributors
+
+- [@esrakartalOpt](https://github.com/esrakartalOpt) made their first contribution in [#459](https://github.com/optimizely/python-sdk/pull/459).
+
+---
+
+
+## 5.2.0
+February 26, 2025
+
+Python threads have been named.
+
+`PollingConfigManager` now has another optional parameter `retries` that will control how many times the SDK will attempt to get the datafile if the connection fails. Previously, the SDK would only try once. Now it defaults to maximum of three attempts. When sending event data, the SDK will attempt to send event data up to three times, where as before it would only attempt once.
+
 ## 5.1.0
 November 27th, 2024
 

{optimizely_sdk-5.1.0 → optimizely_sdk-5.3.0}/optimizely/bucketer.py

@@ -22,7 +22,7 @@ from .lib import pymmh3 as mmh3
 if version_info < (3, 8):
     from typing_extensions import Final
 else:
-    from typing import Final  # type: ignore
+    from typing import Final
 
 
 if TYPE_CHECKING:
@@ -119,13 +119,82 @@ class Bucketer:
             and array of log messages representing decision making.
      */.
         """
+        # Check if experiment is None first
+        if not experiment:
+            message = 'Invalid entity key provided for bucketing. Returning nil.'
+            project_config.logger.debug(message)
+            return None, []
+
+        if isinstance(experiment, dict):
+            # This is a holdout dictionary
+            experiment_key = experiment.get('key', '')
+            experiment_id = experiment.get('id', '')
+        else:
+            # This is an Experiment object
+            experiment_key = experiment.key
+            experiment_id = experiment.id
+
+        if not experiment_key or not experiment_key.strip():
+            message = 'Invalid entity key provided for bucketing. Returning nil.'
+            project_config.logger.debug(message)
+            return None, []
+
+        variation_id, decide_reasons = self.bucket_to_entity_id(project_config, experiment, user_id, bucketing_id)
+        if variation_id:
+            if isinstance(experiment, dict):
+                # For holdouts, find the variation in the holdout's variations array
+                variations = experiment.get('variations', [])
+                variation = next((v for v in variations if v.get('id') == variation_id), None)
+            else:
+                # For experiments, use the existing method
+                variation = project_config.get_variation_from_id_by_experiment_id(experiment_id, variation_id)
+            return variation, decide_reasons
+
+        # No variation found - log message for empty traffic range
+        message = 'Bucketed into an empty traffic range. Returning nil.'
+        project_config.logger.info(message)
+        decide_reasons.append(message)
+        return None, decide_reasons
+
+    def bucket_to_entity_id(
+        self, project_config: ProjectConfig,
+        experiment: Experiment, user_id: str, bucketing_id: str
+    ) -> tuple[Optional[str], list[str]]:
+        """
+        For a given experiment and bucketing ID determines variation ID to be shown to user.
+
+        Args:
+            project_config: Instance of ProjectConfig.
+            experiment: The experiment object (used for group/groupPolicy logic if needed).
+            user_id: The user ID string.
+            bucketing_id: The bucketing ID string for the user.
+
+        Returns:
+            Tuple of (entity_id or None, list of decide reasons).
+        """
         decide_reasons: list[str] = []
         if not experiment:
             return None, decide_reasons
 
+        # Handle both Experiment objects and holdout dictionaries
+        if isinstance(experiment, dict):
+            # This is a holdout dictionary - holdouts don't have groups
+            experiment_key = experiment.get('key', '')
+            experiment_id = experiment.get('id', '')
+            traffic_allocations = experiment.get('trafficAllocation', [])
+            has_cmab = False
+            group_policy = None
+        else:
+            # This is an Experiment object
+            experiment_key = experiment.key
+            experiment_id = experiment.id
+            traffic_allocations = experiment.trafficAllocation
+            has_cmab = bool(experiment.cmab)
+            group_policy = getattr(experiment, 'groupPolicy', None)
+
         # Determine if experiment is in a mutually exclusive group.
-        # This will not affect evaluation of rollout rules.
-        if experiment.groupPolicy in GROUP_POLICIES:
+        # This will not affect evaluation of rollout rules or holdouts.
+        if group_policy and group_policy in GROUP_POLICIES:
             group = project_config.get_group(experiment.groupId)
 
             if not group:
@@ -141,26 +210,27 @@ class Bucketer:
                 decide_reasons.append(message)
                 return None, decide_reasons
 
-            if user_experiment_id != experiment.id:
-                message = f'User "{user_id}" is not in experiment "{experiment.key}" of group {experiment.groupId}.'
+            if user_experiment_id != experiment_id:
+                message = f'User "{user_id}" is not in experiment "{experiment_key}" of group {experiment.groupId}.'
                 project_config.logger.info(message)
                 decide_reasons.append(message)
                 return None, decide_reasons
 
-            message = f'User "{user_id}" is in experiment {experiment.key} of group {experiment.groupId}.'
+            message = f'User "{user_id}" is in experiment {experiment_key} of group {experiment.groupId}.'
             project_config.logger.info(message)
             decide_reasons.append(message)
 
+        if has_cmab:
+            if experiment.cmab:
+                traffic_allocations = [
+                    {
+                        "entityId": "$",
+                        "endOfRange": experiment.cmab['trafficAllocation']
+                    }
+                ]
+
         # Bucket user if not in white-list and in group (if any)
         variation_id = self.find_bucket(project_config, bucketing_id,
-                                        experiment.id, experiment.trafficAllocation)
-        if variation_id:
-            variation = project_config.get_variation_from_id_by_experiment_id(experiment.id, variation_id)
-            return variation, decide_reasons
+                                        experiment_id, traffic_allocations)
 
-        else:
-            message = 'Bucketed into an empty traffic range. Returning nil.'
-            project_config.logger.info(message)
-            decide_reasons.append(message)
-
-        return None, decide_reasons
+        return variation_id, decide_reasons

optimizely_sdk-5.3.0/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_sdk-5.3.0/optimizely/cmab/cmab_client.py

@@ -0,0 +1,198 @@
+# 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.
+import json
+import time
+import requests
+import math
+from typing import Dict, Any, Optional
+from optimizely import logger as _logging
+from optimizely.helpers.enums import Errors
+from optimizely.exceptions import CmabFetchError, CmabInvalidResponseError
+
+# Default constants for CMAB requests
+DEFAULT_MAX_RETRIES = 1
+DEFAULT_INITIAL_BACKOFF = 0.1  # in seconds (100 ms)
+DEFAULT_MAX_BACKOFF = 10  # in seconds
+DEFAULT_BACKOFF_MULTIPLIER = 2.0
+MAX_WAIT_TIME = 10.0
+DEFAULT_PREDICTION_ENDPOINT = "https://prediction.cmab.optimizely.com/predict/{}"
+
+
+class CmabRetryConfig:
+    """Configuration for retrying CMAB requests.
+
+    Contains parameters for maximum retries, backoff intervals, and multipliers.
+    """
+    def __init__(
+        self,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        initial_backoff: float = DEFAULT_INITIAL_BACKOFF,
+        max_backoff: float = DEFAULT_MAX_BACKOFF,
+        backoff_multiplier: float = DEFAULT_BACKOFF_MULTIPLIER,
+    ):
+        self.max_retries = max_retries
+        self.initial_backoff = initial_backoff
+        self.max_backoff = max_backoff
+        self.backoff_multiplier = backoff_multiplier
+
+
+class DefaultCmabClient:
+    """Client for interacting with the CMAB service.
+
+    Provides methods to fetch decisions with optional retry logic.
+    """
+    def __init__(self, http_client: Optional[requests.Session] = None,
+                 retry_config: Optional[CmabRetryConfig] = None,
+                 logger: Optional[_logging.Logger] = None,
+                 prediction_endpoint: Optional[str] = None):
+        """Initialize the CMAB client.
+
+        Args:
+            http_client (Optional[requests.Session]): HTTP client for making requests.
+            retry_config (Optional[CmabRetryConfig]): Configuration for retry logic.
+            logger (Optional[_logging.Logger]): Logger for logging messages.
+            prediction_endpoint (Optional[str]): Custom prediction endpoint URL template.
+                                                  Use {} as placeholder for rule_id.
+        """
+        self.http_client = http_client or requests.Session()
+        self.retry_config = retry_config
+        self.logger = _logging.adapt_logger(logger or _logging.NoOpLogger())
+        self.prediction_endpoint = prediction_endpoint or DEFAULT_PREDICTION_ENDPOINT
+
+    def fetch_decision(
+        self,
+        rule_id: str,
+        user_id: str,
+        attributes: Dict[str, Any],
+        cmab_uuid: str,
+        timeout: float = MAX_WAIT_TIME
+    ) -> str:
+        """Fetch a decision from the CMAB prediction service.
+
+        Args:
+            rule_id (str): The rule ID for the experiment.
+            user_id (str): The user ID for the request.
+            attributes (Dict[str, Any]): User attributes for the request.
+            cmab_uuid (str): Unique identifier for the CMAB request.
+            timeout (float): Maximum wait time for request to respond in seconds. Defaults to 10 seconds.
+
+        Returns:
+            str: The variation ID.
+        """
+        url = self.prediction_endpoint.format(rule_id)
+        cmab_attributes = [
+            {"id": key, "value": value, "type": "custom_attribute"}
+            for key, value in attributes.items()
+        ]
+
+        request_body = {
+            "instances": [{
+                "visitorId": user_id,
+                "experimentId": rule_id,
+                "attributes": cmab_attributes,
+                "cmabUUID": cmab_uuid,
+            }]
+        }
+        if self.retry_config:
+            variation_id = self._do_fetch_with_retry(url, request_body, self.retry_config, timeout)
+        else:
+            variation_id = self._do_fetch(url, request_body, timeout)
+        return variation_id
+
+    def _do_fetch(self, url: str, request_body: Dict[str, Any], timeout: float) -> str:
+        """Perform a single fetch request to the CMAB prediction service.
+
+        Args:
+            url (str): The endpoint URL.
+            request_body (Dict[str, Any]): The request payload.
+            timeout (float): Maximum wait time for request to respond in seconds.
+        Returns:
+            str: The variation ID
+        """
+        headers = {'Content-Type': 'application/json'}
+        try:
+            response = self.http_client.post(url, data=json.dumps(request_body), headers=headers, timeout=timeout)
+        except requests.exceptions.RequestException as e:
+            error_message = Errors.CMAB_FETCH_FAILED.format(str(e))
+            self.logger.error(error_message)
+            raise CmabFetchError(error_message)
+
+        if not 200 <= response.status_code < 300:
+            error_message = Errors.CMAB_FETCH_FAILED.format(str(response.status_code))
+            self.logger.error(error_message)
+            raise CmabFetchError(error_message)
+
+        try:
+            body = response.json()
+        except json.JSONDecodeError:
+            error_message = Errors.INVALID_CMAB_FETCH_RESPONSE
+            self.logger.error(error_message)
+            raise CmabInvalidResponseError(error_message)
+
+        if not self.validate_response(body):
+            error_message = Errors.INVALID_CMAB_FETCH_RESPONSE
+            self.logger.error(error_message)
+            raise CmabInvalidResponseError(error_message)
+
+        return str(body['predictions'][0]['variation_id'])
+
+    def validate_response(self, body: Dict[str, Any]) -> bool:
+        """Validate the response structure from the CMAB service.
+
+        Args:
+            body (Dict[str, Any]): The response body to validate.
+
+        Returns:
+            bool: True if the response is valid, False otherwise.
+        """
+        return (
+            isinstance(body, dict) and
+            'predictions' in body and
+            isinstance(body['predictions'], list) and
+            len(body['predictions']) > 0 and
+            isinstance(body['predictions'][0], dict) and
+            "variation_id" in body["predictions"][0]
+        )
+
+    def _do_fetch_with_retry(
+        self,
+        url: str,
+        request_body: Dict[str, Any],
+        retry_config: CmabRetryConfig,
+        timeout: float
+    ) -> str:
+        """Perform a fetch request with retry logic.
+
+        Args:
+            url (str): The endpoint URL.
+            request_body (Dict[str, Any]): The request payload.
+            retry_config (CmabRetryConfig): Configuration for retry logic.
+            timeout (float): Maximum wait time for request to respond in seconds.
+        Returns:
+            str: The variation ID
+        """
+        backoff = retry_config.initial_backoff
+        for attempt in range(retry_config.max_retries + 1):
+            try:
+                variation_id = self._do_fetch(url, request_body, timeout)
+                return variation_id
+            except:
+                if attempt < retry_config.max_retries:
+                    self.logger.info(f"Retrying CMAB request (attempt: {attempt + 1}) after {backoff} seconds...")
+                    time.sleep(backoff)
+                    backoff = min(backoff * math.pow(retry_config.backoff_multiplier, attempt + 1),
+                                  retry_config.max_backoff)
+
+        error_message = Errors.CMAB_FETCH_FAILED.format('Exhausted all retries for CMAB request.')
+        self.logger.error(error_message)
+        raise CmabFetchError(error_message)