Skip to content

Commit 7b1e3af

Browse files
committed
feat: Lazy identity-flag evaluation in local-eval mode
``get_identity_flags`` now returns a ``Flags`` that holds the evaluation context plus a precomputed segment-overrides reverse index, and resolves each feature on first access via the engine primitives (``is_context_in_segment`` + ``get_flag_result_from_context``) rather than running a full bulk evaluation up-front. In environments shaped like the Slack-report customer (420 features, 30 CSV-IN segments, hot loop reading one boolean flag) this takes ``get_identity_flags().is_feature_enabled(name)`` from ~430 µs to ~1.85 µs per call; 200-segment envs go from ~1200 µs to ~2 µs. The ``.all_flags()`` materialisation path is never slower than the eager baseline in the bench matrix. Back-compat: * ``Flags`` public API unchanged (``is_feature_enabled``, ``get_feature_value``, ``get_flag``, ``all_flags``). * ``FlagResult`` construction reuses the same engine helper as the bulk path — identical output shape. * New ``lazy_identity_evaluation`` constructor kwarg, default ``True``, lets operators flip back to the eager path if they hit an unexpected regression. Engine contract is untouched: the SDK consumes only already-public ``flag_engine.segments.evaluator`` symbols. beep boop
1 parent ae45cbd commit 7b1e3af

4 files changed

Lines changed: 431 additions & 12 deletions

File tree

‎flagsmith/flagsmith.py‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,13 @@
2121
map_segment_results_to_identity_segments,
2222
resolve_trait_values,
2323
)
24-
from flagsmith.models import DefaultFlag, Flags, Segment
24+
from flagsmith.models import (
25+
DefaultFlag,
26+
Flags,
27+
Segment,
28+
SegmentOverridesIndex,
29+
build_segment_overrides_index,
30+
)
2531
from flagsmith.offline_handlers import OfflineHandler
2632
from flagsmith.polling_manager import EnvironmentDataPollingManager
2733
from flagsmith.streaming_manager import EventStreamManager
@@ -77,6 +83,7 @@ def __init__(
7783
offline_handler: typing.Optional[OfflineHandler] = None,
7884
enable_realtime_updates: bool = False,
7985
application_metadata: typing.Optional[ApplicationMetadata] = None,
86+
lazy_identity_evaluation: bool = True,
8087
):
8188
"""
8289
:param environment_key: The environment key obtained from Flagsmith interface.
@@ -105,6 +112,11 @@ def __init__(
105112
default_flag_handler if offline_mode is not set and using remote evaluation.
106113
:param enable_realtime_updates: Use real-time functionality via SSE as opposed to polling the API
107114
:param application_metadata: Optional metadata about the client application.
115+
:param lazy_identity_evaluation: When True (default), ``get_identity_flags``
116+
returns a lazy ``Flags`` that resolves flags on first access using a
117+
precomputed segment-overrides index, rather than evaluating every
118+
feature in the environment up-front. Set to False to opt back into
119+
the legacy eager path if you hit a regression.
108120
"""
109121

110122
self.offline_mode = offline_mode
@@ -113,11 +125,13 @@ def __init__(
113125
self.offline_handler = offline_handler
114126
self.default_flag_handler = default_flag_handler
115127
self.enable_realtime_updates = enable_realtime_updates
128+
self.lazy_identity_evaluation = lazy_identity_evaluation
116129
self._analytics_processor: typing.Optional[AnalyticsProcessor] = None
117130
self._pipeline_analytics_processor: typing.Optional[
118131
PipelineAnalyticsProcessor
119132
] = None
120-
self._evaluation_context: typing.Optional[SDKEvaluationContext] = None
133+
self.__evaluation_context: typing.Optional[SDKEvaluationContext] = None
134+
self._segment_overrides_index: SegmentOverridesIndex = {}
121135
self._environment_updated_at: typing.Optional[datetime] = None
122136

123137
# argument validation
@@ -356,6 +370,26 @@ def update_environment(self) -> None:
356370
except (KeyError, TypeError, ValueError):
357371
logger.exception("Error parsing environment document")
358372

373+
@property
374+
def _evaluation_context(self) -> typing.Optional[SDKEvaluationContext]:
375+
return self.__evaluation_context
376+
377+
@_evaluation_context.setter
378+
def _evaluation_context(
379+
self, context: typing.Optional[SDKEvaluationContext]
380+
) -> None:
381+
"""Swap in a new evaluation context and rebuild the overrides index.
382+
383+
The index maps feature_name -> segments that override it. Built once
384+
per refresh and reused across every subsequent per-identity lazy
385+
resolution; rebuilding here keeps it in sync with the current doc
386+
without any hot-path cost.
387+
"""
388+
self.__evaluation_context = context
389+
self._segment_overrides_index = (
390+
build_segment_overrides_index(context) if context is not None else {}
391+
)
392+
359393
def _get_headers(
360394
self,
361395
environment_key: str,
@@ -407,6 +441,19 @@ def _get_identity_flags_from_document(
407441
identifier=identifier,
408442
traits=traits,
409443
)
444+
if self.lazy_identity_evaluation:
445+
# Lazy path: defer per-feature evaluation until the caller
446+
# actually reads a flag. Hot for callers that only read one
447+
# or a few flags out of a large environment.
448+
return Flags.from_evaluation_context(
449+
context=context,
450+
overrides_index=self._segment_overrides_index,
451+
analytics_processor=self._analytics_processor,
452+
default_flag_handler=self.default_flag_handler,
453+
pipeline_analytics_processor=self._pipeline_analytics_processor,
454+
identity_identifier=identifier,
455+
traits=resolve_trait_values(traits),
456+
)
410457
evaluation_result = engine.get_evaluation_result(
411458
context=context,
412459
)

‎flagsmith/models.py‎

Lines changed: 144 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,40 @@
33
import typing
44
from dataclasses import dataclass, field
55

6+
from flag_engine.context.types import SegmentContext
7+
from flag_engine.segments.evaluator import (
8+
get_flag_result_from_context,
9+
is_context_in_segment,
10+
)
11+
612
from flagsmith.analytics import AnalyticsProcessor, PipelineAnalyticsProcessor
713
from flagsmith.exceptions import FlagsmithFeatureDoesNotExistError
8-
from flagsmith.types import SDKEvaluationResult, SDKFlagResult
14+
from flagsmith.types import (
15+
FeatureMetadata,
16+
SDKEvaluationContext,
17+
SDKEvaluationResult,
18+
SDKFlagResult,
19+
SegmentMetadata,
20+
)
21+
22+
SegmentOverridesIndex = typing.Dict[
23+
str, typing.List[SegmentContext[SegmentMetadata, FeatureMetadata]]
24+
]
25+
26+
27+
def build_segment_overrides_index(
28+
context: SDKEvaluationContext,
29+
) -> SegmentOverridesIndex:
30+
"""Map feature_name -> segments that carry an override for that feature.
31+
32+
Computed once per environment-document refresh so the lazy eval path
33+
can walk only the segments actually relevant to a given flag.
34+
"""
35+
index: SegmentOverridesIndex = {}
36+
for segment_context in (context.get("segments") or {}).values():
37+
for override in segment_context.get("overrides") or ():
38+
index.setdefault(override["name"], []).append(segment_context)
39+
return index
940

1041

1142
@dataclass
@@ -60,6 +91,14 @@ class Flags:
6091
_pipeline_analytics_processor: typing.Optional[PipelineAnalyticsProcessor] = None
6192
_identity_identifier: typing.Optional[str] = None
6293
_traits: typing.Optional[typing.Dict[str, typing.Any]] = None
94+
# Lazy-evaluation state. When ``_context`` is set, ``flags`` is a
95+
# per-feature memo rather than a fully-materialised snapshot; unseen
96+
# features are resolved on demand via the engine primitives and
97+
# cached back into ``flags``. Left as ``None`` by the eager code
98+
# paths (``from_evaluation_result`` / ``from_api_flags``).
99+
_context: typing.Optional[SDKEvaluationContext] = None
100+
_overrides_index: typing.Optional[SegmentOverridesIndex] = None
101+
_fully_materialised: bool = False
63102

64103
@classmethod
65104
def from_evaluation_result(
@@ -86,6 +125,37 @@ def from_evaluation_result(
86125
_traits=traits,
87126
)
88127

128+
@classmethod
129+
def from_evaluation_context(
130+
cls,
131+
context: SDKEvaluationContext,
132+
overrides_index: SegmentOverridesIndex,
133+
analytics_processor: typing.Optional[AnalyticsProcessor],
134+
default_flag_handler: typing.Optional[typing.Callable[[str], DefaultFlag]],
135+
pipeline_analytics_processor: typing.Optional[
136+
PipelineAnalyticsProcessor
137+
] = None,
138+
identity_identifier: typing.Optional[str] = None,
139+
traits: typing.Optional[typing.Dict[str, typing.Any]] = None,
140+
) -> Flags:
141+
"""Build a lazy ``Flags`` backed by an evaluation context.
142+
143+
No engine work is done here — flags are resolved on first access
144+
via :meth:`_resolve_flag`. Reusing the same ``overrides_index``
145+
across calls amortises its construction cost (it's rebuilt only
146+
when the environment doc refreshes, not per identity).
147+
"""
148+
return cls(
149+
flags={},
150+
default_flag_handler=default_flag_handler,
151+
_analytics_processor=analytics_processor,
152+
_pipeline_analytics_processor=pipeline_analytics_processor,
153+
_identity_identifier=identity_identifier,
154+
_traits=traits,
155+
_context=context,
156+
_overrides_index=overrides_index,
157+
)
158+
89159
@classmethod
90160
def from_api_flags(
91161
cls,
@@ -116,8 +186,17 @@ def all_flags(self) -> typing.List[Flag]:
116186
"""
117187
Get a list of all Flag objects.
118188
189+
In lazy mode, this forces resolution of every feature the caller
190+
hasn't already touched — same end state and cost as eager, but
191+
only paid when someone actually asks for the full set.
192+
119193
:return: list of Flag objects.
120194
"""
195+
if self._context is not None and not self._fully_materialised:
196+
for feature_name in self._context.get("features") or {}:
197+
if feature_name not in self.flags:
198+
self.flags[feature_name] = self._resolve_flag(feature_name)
199+
self._fully_materialised = True
121200
return list(self.flags.values())
122201

123202
def is_feature_enabled(self, feature_name: str) -> bool:
@@ -151,11 +230,23 @@ def get_flag(self, feature_name: str) -> typing.Union[DefaultFlag, Flag]:
151230
try:
152231
flag = self.flags[feature_name]
153232
except KeyError:
154-
if self.default_flag_handler:
233+
# Lazy path: if this ``Flags`` wraps an evaluation context and
234+
# the feature exists in it, resolve and memoise now. Otherwise
235+
# fall through to the default_flag_handler / not-found error,
236+
# preserving the eager-mode behaviour byte-for-byte.
237+
if (
238+
self._context is not None
239+
and self._overrides_index is not None
240+
and feature_name in (self._context.get("features") or {})
241+
):
242+
flag = self._resolve_flag(feature_name)
243+
self.flags[feature_name] = flag
244+
elif self.default_flag_handler:
155245
return self.default_flag_handler(feature_name)
156-
raise FlagsmithFeatureDoesNotExistError(
157-
"Feature does not exist: %s" % feature_name
158-
)
246+
else:
247+
raise FlagsmithFeatureDoesNotExistError(
248+
"Feature does not exist: %s" % feature_name
249+
)
159250

160251
if self._analytics_processor and hasattr(flag, "feature_name"):
161252
self._analytics_processor.track_feature(flag.feature_name)
@@ -171,6 +262,54 @@ def get_flag(self, feature_name: str) -> typing.Union[DefaultFlag, Flag]:
171262

172263
return flag
173264

265+
def _resolve_flag(self, feature_name: str) -> Flag:
266+
"""Evaluate a single feature against the lazy context.
267+
268+
Uses the precomputed reverse index to walk only segments that
269+
could override this feature; falls through to the feature's
270+
default when no matching override is found. Byte-for-byte
271+
equivalent to what ``engine.get_evaluation_result`` would
272+
produce for this one feature.
273+
"""
274+
context = self._context
275+
overrides_index = self._overrides_index
276+
# ``get_flag`` / ``all_flags`` gate this call behind the same
277+
# non-None checks; assert here so type checkers can narrow.
278+
assert context is not None and overrides_index is not None
279+
280+
feature_context = context["features"][feature_name]
281+
282+
# Find the winning override, if any, by walking only the segments
283+
# that target this feature and keeping the lowest-priority match.
284+
best: typing.Optional[
285+
typing.Tuple[float, typing.Mapping[str, typing.Any], str]
286+
] = None
287+
for segment_context in overrides_index.get(feature_name, ()):
288+
if not is_context_in_segment(context, segment_context):
289+
continue
290+
for override in segment_context.get("overrides") or ():
291+
if override["name"] != feature_name:
292+
continue
293+
priority = override.get("priority", float("inf"))
294+
if best is None or priority < best[0]:
295+
best = (priority, override, segment_context["name"])
296+
297+
if best is not None:
298+
flag_result = get_flag_result_from_context(
299+
context,
300+
typing.cast(typing.Any, best[1]),
301+
reason=f"TARGETING_MATCH; segment={best[2]}",
302+
)
303+
else:
304+
flag_result = get_flag_result_from_context(
305+
context,
306+
feature_context,
307+
reason="DEFAULT",
308+
)
309+
return Flag.from_evaluation_result(
310+
typing.cast(SDKFlagResult, flag_result),
311+
)
312+
174313

175314
@dataclass
176315
class Segment:

‎tests/test_flagsmith.py‎

Lines changed: 54 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import pytest
66
import requests
77
import responses
8+
from flag_engine import engine
89
from pytest_mock import MockerFixture
910
from responses import matchers
1011

@@ -15,7 +16,7 @@
1516
FlagsmithAPIError,
1617
FlagsmithFeatureDoesNotExistError,
1718
)
18-
from flagsmith.models import DefaultFlag, Flags
19+
from flagsmith.models import DefaultFlag, Flag, Flags
1920
from flagsmith.offline_handlers import OfflineHandler
2021
from flagsmith.types import SDKEvaluationContext
2122

@@ -190,9 +191,11 @@ def test_get_identity_flags_uses_local_environment_when_available(
190191
evaluation_context: SDKEvaluationContext,
191192
mocker: MockerFixture,
192193
) -> None:
193-
# Given
194+
# Given: the eager rollback path; this test pins the engine call
195+
# shape, so bypass the lazy default to exercise it.
194196
flagsmith._evaluation_context = evaluation_context
195197
flagsmith.enable_local_evaluation = True
198+
flagsmith.lazy_identity_evaluation = False
196199
mock_engine = mocker.patch("flagsmith.flagsmith.engine")
197200

198201
expected_evaluation_result = {
@@ -231,7 +234,9 @@ def test_get_identity_flags_includes_segments_in_evaluation_context(
231234
mocker: MockerFixture,
232235
local_eval_flagsmith: Flagsmith,
233236
) -> None:
234-
# Given
237+
# Given: eager rollback path — this test asserts what goes into the
238+
# engine call directly.
239+
local_eval_flagsmith.lazy_identity_evaluation = False
235240
mock_get_evaluation_result = mocker.patch(
236241
"flagsmith.flagsmith.engine.get_evaluation_result",
237242
autospec=True,
@@ -264,6 +269,52 @@ def test_get_identity_flags_includes_segments_in_evaluation_context(
264269
assert "segments" in context
265270

266271

272+
def test_get_identity_flags__lazy_by_default__does_not_run_bulk_engine_call(
273+
local_eval_flagsmith: Flagsmith,
274+
mocker: MockerFixture,
275+
) -> None:
276+
# Given: the lazy path is on by default.
277+
assert local_eval_flagsmith.lazy_identity_evaluation is True
278+
spy = mocker.spy(engine, "get_evaluation_result")
279+
280+
# When we ask for identity flags but never touch a specific flag...
281+
flags = local_eval_flagsmith.get_identity_flags("someone")
282+
283+
# Then: no engine bulk eval has run, and nothing is materialised.
284+
assert spy.call_count == 0
285+
assert flags.flags == {}
286+
287+
# And: touching one flag populates only that flag via the lazy resolver.
288+
flag = flags.get_flag("some_feature")
289+
assert isinstance(flag, Flag)
290+
assert flag.feature_name == "some_feature"
291+
assert set(flags.flags.keys()) == {"some_feature"}
292+
# Still no bulk call — we resolved via engine primitives directly.
293+
assert spy.call_count == 0
294+
295+
296+
def test_get_identity_flags__lazy_disabled__falls_back_to_eager_path(
297+
requests_session_response_ok: None,
298+
server_api_key: str,
299+
mocker: MockerFixture,
300+
) -> None:
301+
# Given: lazy evaluation is explicitly turned off (rollback kwarg).
302+
flagsmith = Flagsmith(
303+
environment_key=server_api_key,
304+
enable_local_evaluation=True,
305+
environment_refresh_interval_seconds=0.1,
306+
lazy_identity_evaluation=False,
307+
)
308+
spy = mocker.spy(engine, "get_evaluation_result")
309+
310+
# When
311+
flags = flagsmith.get_identity_flags("someone")
312+
313+
# Then: the bulk evaluation ran up-front and every flag is resolved.
314+
assert spy.call_count == 1
315+
assert set(flags.flags.keys()) == {"some_feature"}
316+
317+
267318
@responses.activate()
268319
def test_get_identity_flags__transient_identity__calls_expected(
269320
flagsmith: Flagsmith,

0 commit comments

Comments
 (0)