Refactor: Align Holdout implementation with Swift SDK

[muzahidul-opti]

Summary

This PR refactors the holdout implementation to use proper entity classes aligned with the Swift SDK architecture, improving type safety, consistency, and fixing a critical bug in the decision return value.

Problem Statement

The current Python SDK holdout implementation differs from the Swift SDK in several ways:

1. Mixed Types: Holdouts were stored as HoldoutDict (TypedDict) instead of proper entity classes
2. Inconsistent Storage: global_holdouts was a dict, while Swift uses an array/list
3. Mixed Variation Types: Holdout variations were plain dicts, not Variation entities
4. Decision Bug: get_variation_for_holdout() returned experiment=None in the Decision, while Swift returns the holdout itself
5. Type Safety: Dict-based checks throughout required runtime validation

Solution

Aligned Python SDK with Swift SDK by:

1. Created Holdout Entity Class (entities.py)

class Holdout(BaseEntity):
    class Status:
        DRAFT = 'Draft'
        RUNNING = 'Running'
        CONCLUDED = 'Concluded'
        ARCHIVED = 'Archived'
    
    @property
    def is_activated(self) -> bool:
        return self.status == self.Status.RUNNING
    
    def get_audience_conditions_or_ids(self) -> Sequence:
        # Enables same audience evaluation as experiments

Matches Swift's:

• struct Holdout: ExperimentCore
• var isActivated: Bool { return status == .running }
• Proper entity class with typed properties

2. Refactored ProjectConfig (project_config.py)

Before:

self.holdouts: list[HoldoutDict] = config.get('holdouts', [])
self.global_holdouts: dict[str, HoldoutDict] = {}  # Dict by ID

After:

self.holdouts: list[entities.Holdout] = []
self.global_holdouts: list[entities.Holdout] = []  # List like Swift

• Convert holdout dicts to Holdout entities during initialization
• Convert holdout variations to Variation entities
• Use list for global_holdouts (matching Swift SDK)

3. Fixed Decision Service (decision_service.py)

Critical Bug Fix:

Before:

Decision(
    experiment=None,  # ❌ Returns None
    variation=variation,
    source=enums.DecisionSources.HOLDOUT
)

After:

Decision(
    experiment=holdout,  # ✅ Returns Holdout entity (matches Swift)
    variation=variation,
    source=enums.DecisionSources.HOLDOUT
)

This matches Swift's: FeatureDecision(experiment: holdout, variation: variation, source: .holdout)

4. Unified Bucketer (bucketer.py)

Before: Separate code paths for dicts vs entities

if isinstance(experiment, dict):
    # Holdout dict handling
    experiment_key = experiment.get('key', '')
    variations = experiment.get('variations', [])
else:
    # Experiment entity handling
    experiment_key = experiment.key

After: Unified handling

# Works for both Experiment and Holdout entities
experiment_key = experiment.key
experiment_id = experiment.id

Benefits

✅ Type Safety: Holdouts are now proper entity classes with compile-time checking
✅ Consistency: Holdouts work exactly like Experiments throughout the codebase
✅ Swift Alignment: Python SDK matches Swift SDK's holdout architecture
✅ Bug Fix: Decision.experiment now returns Holdout entity (enables metadata access)
✅ Maintainability: Unified code paths reduce complexity
✅ No Breaking Changes: Holdouts from datafile still load correctly

Testing

All integration tests pass:

• ✅ Holdout entity instantiation
• ✅ ProjectConfig loads holdouts as entities
• ✅ Decision service accepts Holdout entities
• ✅ Bucketer handles both Experiment and Holdout entities
• ✅ Variations converted to Variation entities
• ✅ Full decision flow completes successfully

Alignment with Swift SDK

Feature	Swift SDK	Python SDK (Before)	Python SDK (After)
Entity Type	struct Holdout	HoldoutDict (TypedDict)	class Holdout ✅
Status Check	isActivated property	holdout.get('status') == 'Running'	holdout.is_activated ✅
Global Storage	[Holdout] (array)	dict[str, HoldoutDict]	list[entities.Holdout] ✅
Variations	Variation entities	Mixed (dicts/entities)	Variation entities ✅
Decision.experiment	Returns holdout	Returns None ❌	Returns holdout ✅

Files Changed

• optimizely/entities.py - Added Holdout entity class
• optimizely/project_config.py - Convert to entities, updated storage
• optimizely/decision_service.py - Use entities, fixed Decision return
• optimizely/bucketer.py - Unified entity handling

Checklist

• Code changes aligned with Swift SDK reference implementation
• All modules compile without errors
• All imports work correctly
• Integration tests pass
• Type safety improved with proper entity classes
• Critical bug fixed (Decision.experiment)
• No breaking changes to public API
• Backward compatible with existing datafiles

🤖 Generated with Claude Code