[AI-FSSDK] [FSSDK-12369] Add local holdouts support to Python SDK

optimizely/decision_service.py

@@ -610,6 +610,24 @@ def get_variation_for_rollout(
  return Decision(experiment=rule, variation=forced_decision_variation,
  source=enums.DecisionSources.ROLLOUT, cmab_uuid=None), decide_reasons
 
+ # Check local holdouts targeting this specific delivery rule (FSSDK-12369)
+ local_holdouts = project_config.get_holdouts_for_rule(rule.id)
+ for holdout in local_holdouts:
+ local_holdout_decision = self.get_variation_for_holdout(
+ holdout, user_context, project_config
+ )
+ decide_reasons.extend(local_holdout_decision['reasons'])
+
+ local_decision = local_holdout_decision['decision']
+ if local_decision.variation is not None:
+ message = (
+ f"The user '{user_id}' is bucketed into local holdout '{holdout.key}' "
+ f"for delivery rule '{rule.key}'."
+ )
+ self.logger.info(message)
+ decide_reasons.append(message)
+ return local_decision, decide_reasons
+
  bucketing_id, bucket_reasons = self._get_bucketing_id(user_id, attributes)
  decide_reasons += bucket_reasons
 
@@ -733,9 +751,9 @@ def get_decision_for_flag(
  reasons = decide_reasons.copy() if decide_reasons else []
  user_id = user_context.user_id
 
- # Check holdouts
-holdouts = project_config.get_holdouts_for_flag(feature_flag.key)
- for holdout in holdouts:
+ # Check global holdouts (flag level — before any rules are evaluated)
+global_holdouts = project_config.get_global_holdouts()
+ for holdout in global_holdouts:
  holdout_decision = self.get_variation_for_holdout(holdout, user_context, project_config)
  reasons.extend(holdout_decision['reasons'])
 
@@ -756,7 +774,7 @@ def get_decision_for_flag(
  'reasons': reasons
  }
 
- # If no holdout decision, check experiments then rollouts
+ # If no global holdout decision, check experiments then rollouts
  if feature_flag.experimentIds:
  for experiment_id in feature_flag.experimentIds:
  experiment = project_config.get_experiment_from_id(experiment_id)
@@ -778,6 +796,28 @@ def get_decision_for_flag(
  'reasons': reasons
  }
 
+ # Check local holdouts targeting this specific experiment rule (FSSDK-12369)
+ local_holdouts = project_config.get_holdouts_for_rule(experiment.id)
+ for holdout in local_holdouts:
+ local_holdout_decision = self.get_variation_for_holdout(
+ holdout, user_context, project_config
+ )
+ reasons.extend(local_holdout_decision['reasons'])
+
+ local_decision = local_holdout_decision['decision']
+ if local_decision.variation is not None:
+ message = (
+ f"The user '{user_id}' is bucketed into local holdout '{holdout.key}' "
+ f"for experiment rule '{experiment.key}'."
+ )
+ self.logger.info(message)
+ reasons.append(message)
+ return {
+ 'decision': local_holdout_decision['decision'],
+ 'error': False,
+ 'reasons': reasons
+ }
+
  # Get variation for experiment
  variation_result = self.get_variation(
  project_config, experiment, user_context, user_profile_tracker, reasons, decide_options

optimizely/entities.py

@@ -223,6 +223,7 @@ def __init__(
  trafficAllocation: list[TrafficAllocation],
  audienceIds: list[str],
  audienceConditions: Optional[Sequence[str | list[str]]] = None,
+ includedRules: Optional[list[str]] = None,
  **kwargs: Any
  ):
  self.id = id
@@ -232,6 +233,8 @@ def __init__(
  self.trafficAllocation = trafficAllocation
  self.audienceIds = audienceIds
  self.audienceConditions = audienceConditions
+ # None = global holdout (applies to all rules); list of rule IDs = local holdout
+ self.included_rules: Optional[list[str]] = includedRules
 
  def get_audience_conditions_or_ids(self) -> Sequence[str | list[str]]:
  """Returns audienceConditions if present, otherwise audienceIds.
@@ -241,6 +244,18 @@ def get_audience_conditions_or_ids(self) -> Sequence[str | list[str]]:
  """
  return self.audienceConditions if self.audienceConditions is not None else self.audienceIds
 
+ @property
+ def is_global(self) -> bool:
+ """Check if this is a global holdout (applies to all rules across all flags).
+
+ A holdout is global when includedRules is None (absent from datafile).
+ An empty list [] is a local holdout that targets no rules (different from global).
+
+ Returns:
+ True if included_rules is None (global), False otherwise (local).
+ """
+ return self.included_rules is None
+
  @property
  def is_activated(self) -> bool:
  """Check if the holdout is activated (running).

optimizely/helpers/types.py

@@ -130,3 +130,4 @@ class HoldoutDict(ExperimentDict):
  Extends ExperimentDict with holdout-specific properties.
  """
  holdoutStatus: HoldoutStatus
+ includedRules: Optional[list[str]] # None = global holdout; list of rule IDs = local holdout

optimizely/project_config.py

@@ -93,7 +93,10 @@ def __init__(self, datafile: str | bytes, logger: Logger, error_handler: Any):
  holdouts_data: list[types.HoldoutDict] = config.get('holdouts', [])
  self.holdouts: list[entities.Holdout] = []
  self.holdout_id_map: dict[str, entities.Holdout] = {}
- self.flag_holdouts_map: dict[str, list[entities.Holdout]] = {}
+ # Global holdouts (includedRules is None) — evaluated at flag level before any rule
+ self.global_holdouts: list[entities.Holdout] = []
+ # Rule-level holdouts — map from rule ID to holdouts targeting that rule
+ self.rule_holdouts_map: dict[str, list[entities.Holdout]] = {}
 
  # Convert holdout dicts to Holdout entities
  for holdout_data in holdouts_data:
@@ -108,6 +111,16 @@ def __init__(self, datafile: str | bytes, logger: Logger, error_handler: Any):
  # Map by ID for quick lookup
  self.holdout_id_map[holdout.id] = holdout
 
+ # Classify holdout as global or local based on includedRules
+ if holdout.is_global:
+ self.global_holdouts.append(holdout)
+ else:
+ # Local holdout — register for each targeted rule ID
+ for rule_id in (holdout.included_rules or []):
+ if rule_id not in self.rule_holdouts_map:
+ self.rule_holdouts_map[rule_id] = []
+ self.rule_holdouts_map[rule_id].append(holdout)
+
  # Utility maps for quick lookup
  self.group_id_map: dict[str, entities.Group] = self._generate_key_map(self.groups, 'id', entities.Group)
  self.experiment_id_map: dict[str, entities.Experiment] = self._generate_key_map(
@@ -240,11 +253,6 @@ def __init__(self, datafile: str | bytes, logger: Logger, error_handler: Any):
  everyone_else_variation.variables, 'id', entities.Variation.VariableUsage
  )
 
- # Map all running holdouts to this flag
- applicable_holdouts = list(self.holdout_id_map.values())
- if applicable_holdouts:
- self.flag_holdouts_map[feature.key] = applicable_holdouts
-
  rollout = None if len(feature.rolloutId) == 0 else self.rollout_id_map[feature.rolloutId]
  if rollout:
  for exp in rollout.experiments:
@@ -878,19 +886,30 @@ def get_flag_variation(
 
  return None
 
- def get_holdouts_for_flag(self, flag_key: str) -> list[entities.Holdout]:
- """ Helper method to get holdouts from an applied feature flag.
+ def get_global_holdouts(self) -> list[entities.Holdout]:
+ """Return all global holdouts (includedRules is None).
 
- Args:
- flag_key: Key of the feature flag.
+ Global holdouts are evaluated at flag level before any rule is checked.
 
  Returns:
-The holdouts that apply for a specific flag as Holdout entity objects.
+List of global Holdout entities that are currently running.
  """
- if not self.holdouts:
- return []
+ return self.global_holdouts
+
+ def get_holdouts_for_rule(self, rule_id: str) -> list[entities.Holdout]:
+ """Return local holdouts that target a specific rule.
 
- return self.flag_holdouts_map.get(flag_key, [])
+ Local holdouts are evaluated per-rule, before the rule's audience and
+ traffic allocation checks. A rule ID not present in any holdout's
+ includedRules simply returns an empty list — silently skipped.
+
+ Args:
+ rule_id: The experiment or delivery rule ID to look up.
+
+ Returns:
+ List of local Holdout entities targeting the given rule ID.
+ """
+ return self.rule_holdouts_map.get(rule_id, [])
 
  def get_holdout(self, holdout_id: str) -> Optional[entities.Holdout]:
  """ Helper method to get holdout from holdout ID.