[AI-FSSDK] [FSSDK-12368] Local Holdouts - Cleanup flag base setup and add includedRules and rule-level lookup

[Mat001]

Summary

Implements Local Holdouts support for the Python SDK, replacing legacy flag-level holdout targeting (includedFlags/excludedFlags) with rule-level targeting (includedRules).

Related Ticket: FSSDK-12368

Changes

Data Model

• Added included_rules field to Holdout model (optional array of rule IDs)
• Added is_global property (True when included_rules is None)
• Removed legacy fields: included_flags, excluded_flags

Holdout Configuration

• Updated HoldoutConfig from flag-level to rule-level mapping
• Implemented get_global_holdouts() - returns holdouts with included_rules == None
• Implemented get_holdouts_for_rule(rule_id) - returns holdouts targeting specific rule
• Added validation for rule holdouts map integrity

Decision Flow

• Global holdouts evaluated at flag level (before forced decisions)
• Local holdouts evaluated per-rule (after forced decisions, before audience/traffic)
• If user hits local holdout, rule evaluation is skipped
• Returns correct decision metadata: source="holdout", experiment_id, ruleKey

Edge Cases

• Missing included_rules field defaults to None (global holdout)
• Empty array [] vs None handled correctly (empty = local with no rules, None = global)
• Invalid rule IDs skipped gracefully (no errors)
• Cross-flag targeting supported (one holdout can target rules from multiple flags)

Testing

New Tests (11 comprehensive tests in tests/test_local_holdouts.py)

• Global holdout evaluation
• Local single-rule targeting
• Local multi-rule targeting (same flag and cross-flag)
• Precedence (global before local)
• Edge cases (missing field, empty array, invalid rule IDs)

Updated Tests (60 existing tests)

• Migrated from included_flags/excluded_flags to included_rules
• Updated to use is_global property
• Verified backward compatibility

Quality Metrics

• ✅ Tests: 71/71 passing (100%)
• ✅ Critical Issues: 0
• ✅ Warnings: 0
• ✅ Comprehensive edge case coverage

Files Modified

• optimizely/entities.py - Holdout model updates
• optimizely/project_config.py - Mapping and retrieval logic
• optimizely/decision_service.py - Decision flow integration
• optimizely/helpers/types.py - Type definitions
• tests/test_local_holdouts.py - New comprehensive test suite
• tests/test_decision_service_holdout.py - API updates
• tests/test_config.py - Model updates

Test Plan

• Unit tests pass (71/71)
• Global holdouts work correctly
• Local holdouts work correctly (single rule, multiple rules)
• Edge cases handled (missing field, empty array, invalid IDs)
• Backward compatibility verified (old datafiles work)
• Cross-flag targeting works
• Precedence correct (global → forced → local → rule)

🤖 Generated with Claude Code

[FarhanAnjum-opti]

Changes look good to me. A few things that needs addressing are commented.

[FarhanAnjum-opti]

Tests look good. But this file breaks existing convention of module level testing. The Python SDK organizes tests by source module (e.g., test_config.py for config/entities,
test_decision_service_holdout.py for decision service holdout logic), not by feature. The tests in LocalHoldoutsTest (entity properties, project config methods) should be added to
test_config.py, and LocalHoldoutsDecisionFlowTest should be added to test_decision_service_holdout.py. This file should then be removed.

[FarhanAnjum-opti]

NotRequired with the conditional import adds unnecessary complexity here. These TypedDicts are just intermediate types for type signatures (as noted in the file itself), and backward
compatibility is already handled in Holdout.__init__ where includedRules: Optional[list[str]] = None with **kwargs: Any — if an older datafile omits the
field, **kwargs absorbs any unknown keys and includedRules defaults to None (global holdout). The type system doesn't need to model the "key absent" case when the runtime already
handles it. Just using Optional[list[str]] would be simpler and avoids the new typing_extensions dependency for Python < 3.11.

Suggested change

	if version_info < (3, 11):
	from typing_extensions import NotRequired
	else:
	from typing import NotRequired # type: ignore

[FarhanAnjum-opti]

Suggested change

	includedRules: NotRequired[Optional[list[str]]]
	includedRules: Optional[list[str]]