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

Author: khvn26

benchmarks/__init__.py

@@ -0,0 +1,165 @@
+"""Customer-shape benchmark for SDK lazy identity-flag evaluation.
+
+Compares lazy (default) vs eager (rollback kwarg) per-call latency
+across three workloads — always the same flag, a rotating flag, and
+``all_flags()`` — on environments shaped after the Slack report:
+420 features, a handful of CSV-IN segments, optionally with several of
+those segments overriding the queried flag.
+
+Run with::
+
+    poetry run python -m benchmarks.bench
+    poetry run python -m benchmarks.bench --iters 5000 --warmup 500
+"""
+
+from __future__ import annotations
+
+import argparse
+import statistics
+import time
+import typing
+
+from benchmarks.env import build_environment
+from flagsmith import Flagsmith
+from flagsmith.api.types import EnvironmentModel
+from flagsmith.mappers import map_environment_document_to_context
+
+
+def _make_client(
+    *,
+    n_features: int = 420,
+    with_segments: int = 0,
+    overrides_per_queried_flag: int = 0,
+    lazy_identity_evaluation: bool = True,
+) -> Flagsmith:
+    env_doc = typing.cast(
+        EnvironmentModel,
+        build_environment(
+            n_features=n_features,
+            with_segments=with_segments,
+            overrides_per_queried_flag=overrides_per_queried_flag,
+        ),
+    )
+    # Bypass the real __init__ (no HTTP, no polling, no analytics). The
+    # _evaluation_context property setter rebuilds the overrides index,
+    # matching what happens on a real environment refresh.
+    client = Flagsmith.__new__(Flagsmith)
+    client.offline_mode = False
+    client.enable_local_evaluation = True
+    client.offline_handler = None
+    client.default_flag_handler = None
+    client.enable_realtime_updates = False
+    client.lazy_identity_evaluation = lazy_identity_evaluation
+    client._analytics_processor = None
+    client._pipeline_analytics_processor = None
+    client._environment_updated_at = None
+    client._evaluation_context = map_environment_document_to_context(env_doc)
+    return client
+
+
+def _bench(
+    label: str,
+    fn: typing.Callable[[], object],
+    *,
+    iters: int,
+    warmup: int,
+) -> None:
+    for _ in range(warmup):
+        fn()
+    # Break iters into 20 batches to get a cheap stdev estimate.
+    samples: typing.List[float] = []
+    batch = max(1, iters // 20)
+    remaining = iters
+    while remaining > 0:
+        n = min(batch, remaining)
+        t0 = time.perf_counter()
+        for _ in range(n):
+            fn()
+        samples.append((time.perf_counter() - t0) / n)
+        remaining -= n
+    p50 = statistics.median(samples) * 1e6
+    mean = statistics.fmean(samples) * 1e6
+    stdev = statistics.pstdev(samples) * 1e6
+    print(f"{label:<60} p50={p50:8.2f} µs  mean={mean:8.2f} µs  stdev={stdev:6.2f} µs")
+
+
+def run_matrix(iters: int, warmup: int) -> None:
+    traits = {"venue_id": "12345"}
+
+    scenarios: typing.List[typing.Tuple[str, typing.Dict[str, int]]] = [
+        ("customer-shape (0 overrides)", {"n_features": 420, "with_segments": 30}),
+        (
+            "flag targeted by 10 overrides",
+            {
+                "n_features": 420,
+                "with_segments": 30,
+                "overrides_per_queried_flag": 10,
+            },
+        ),
+        (
+            "segmenting-heavy (200 segs)",
+            {"n_features": 420, "with_segments": 200},
+        ),
+    ]
+
+    for label, kwargs in scenarios:
+        print(f"\n=== {label} ===")
+        lazy_client = _make_client(lazy_identity_evaluation=True, **kwargs)
+        eager_client = _make_client(lazy_identity_evaluation=False, **kwargs)
+
+        probe_flags = eager_client.get_identity_flags(
+            identifier="anonymous",
+            traits=traits,
+        )
+        probe_name = next(iter(probe_flags.flags))
+        rotating_names = list(probe_flags.flags.keys())
+
+        for mode, client in [("eager", eager_client), ("lazy ", lazy_client)]:
+            _bench(
+                f"  {mode} | get_identity_flags().is_feature_enabled(one)",
+                lambda c=client: c.get_identity_flags(  # type: ignore[misc]
+                    identifier="anonymous",
+                    traits=traits,
+                ).is_feature_enabled(probe_name),
+                iters=iters,
+                warmup=warmup,
+            )
+
+            rotating_state = {"i": 0}
+
+            def rotating(c: Flagsmith = client) -> None:
+                idx = rotating_state["i"]
+                rotating_state["i"] = (idx + 1) % len(rotating_names)
+                c.get_identity_flags(
+                    identifier="anonymous",
+                    traits=traits,
+                ).is_feature_enabled(rotating_names[idx])
+
+            _bench(
+                f"  {mode} | get_identity_flags().is_feature_enabled(rotating)",
+                rotating,
+                iters=iters,
+                warmup=warmup,
+            )
+
+            _bench(
+                f"  {mode} | get_identity_flags().all_flags()",
+                lambda c=client: c.get_identity_flags(  # type: ignore[misc]
+                    identifier="anonymous",
+                    traits=traits,
+                ).all_flags(),
+                iters=iters,
+                warmup=warmup,
+            )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--iters", type=int, default=2000)
+    parser.add_argument("--warmup", type=int, default=300)
+    args = parser.parse_args()
+    run_matrix(args.iters, args.warmup)
+
+
+if __name__ == "__main__":
+    main()

benchmarks/bench.py

@@ -0,0 +1,128 @@
+"""Synthetic environment builder for local-evaluation benchmarks.
+
+Produces a document shaped like the real Flagsmith environment payload
+so we can exercise the SDK's local-eval paths without any network or
+fixture-file dependencies. Parameters mirror the shape reported in the
+Slack thread driving the lazy-evaluation work: many features, a handful
+of CSV-IN segments, optionally several segments that all override the
+same queried flag.
+"""
+
+from __future__ import annotations
+
+import typing
+
+
+def build_environment(
+    n_features: int = 420,
+    *,
+    with_multivariate: int = 0,
+    with_segments: int = 0,
+    overrides_per_queried_flag: int = 0,
+    queried_feature_name: str = "feature_0000",
+) -> typing.Dict[str, typing.Any]:
+    """Return a Flagsmith environment document.
+
+    :param n_features: total feature count; dominant driver of eager-eval cost.
+    :param with_multivariate: how many of the first N features carry a
+        2-way multivariate split (exercises the variant hash path).
+    :param with_segments: how many segments to attach. Each has a single
+        IN condition on ``venue_id`` with a comma-separated CSV value list.
+    :param overrides_per_queried_flag: how many of those segments also
+        carry an override for ``queried_feature_name`` (at priorities
+        0..N-1, so the lowest-priority match wins deterministically).
+    :param queried_feature_name: the feature whose evaluation the bench
+        times; only meaningful when ``overrides_per_queried_flag > 0``.
+    """
+    feature_states: typing.List[typing.Dict[str, typing.Any]] = []
+    for i in range(n_features):
+        name = f"feature_{i:04d}"
+        fs: typing.Dict[str, typing.Any] = {
+            "django_id": i + 1,
+            "feature": {"name": name, "type": "STANDARD", "id": i + 1},
+            "feature_state_value": f"value-{i}",
+            "enabled": bool(i % 2),
+            "featurestate_uuid": f"fs-{i:04d}",
+            "feature_segment": None,
+            "multivariate_feature_state_values": [],
+        }
+        if with_multivariate and i < with_multivariate:
+            fs["multivariate_feature_state_values"] = [
+                {
+                    "multivariate_feature_option": {"value": f"mv-{i}-a"},
+                    "percentage_allocation": 50.0,
+                    "id": (i + 1) * 100 + 1,
+                },
+                {
+                    "multivariate_feature_option": {"value": f"mv-{i}-b"},
+                    "percentage_allocation": 50.0,
+                    "id": (i + 1) * 100 + 2,
+                },
+            ]
+        feature_states.append(fs)
+
+    segments: typing.List[typing.Dict[str, typing.Any]] = []
+    queried_feature_id: typing.Optional[int] = None
+    for fs in feature_states:
+        if fs["feature"]["name"] == queried_feature_name:
+            queried_feature_id = fs["feature"]["id"]
+            break
+    for i in range(with_segments):
+        csv_values = ",".join(str(v) for v in range(i * 100, i * 100 + 50))
+        segment: typing.Dict[str, typing.Any] = {
+            "id": 10_000 + i,
+            "name": f"segment_{i}",
+            "rules": [
+                {
+                    "type": "ALL",
+                    "rules": [],
+                    "conditions": [
+                        {
+                            "property_": "venue_id",
+                            "operator": "IN",
+                            "value": csv_values,
+                        }
+                    ],
+                }
+            ],
+            "feature_states": [],
+        }
+        if i < overrides_per_queried_flag and queried_feature_id is not None:
+            segment["feature_states"] = [
+                {
+                    "django_id": 90_000 + i,
+                    "feature": {
+                        "name": queried_feature_name,
+                        "type": "STANDARD",
+                        "id": queried_feature_id,
+                    },
+                    "feature_state_value": f"override-{i}",
+                    "enabled": True,
+                    "featurestate_uuid": f"override-{i:04d}",
+                    "feature_segment": {"priority": i},
+                    "multivariate_feature_state_values": [],
+                }
+            ]
+        segments.append(segment)
+
+    return {
+        "api_key": "B62qaMZNwfiqT76p38ggrQ",
+        "name": "Benchmark Environment",
+        "project": {
+            "name": "Benchmark project",
+            "organisation": {
+                "feature_analytics": False,
+                "name": "Benchmark Org",
+                "id": 1,
+                "persist_trait_data": True,
+                "stop_serving_flags": False,
+            },
+            "id": 1,
+            "hide_disabled_flags": False,
+            "segments": segments,
+        },
+        "segment_overrides": [],
+        "id": 1,
+        "feature_states": feature_states,
+        "identity_overrides": [],
+    }

benchmarks/env.py

@@ -21,7 +21,13 @@
     map_segment_results_to_identity_segments,
     resolve_trait_values,
 )
-from flagsmith.models import DefaultFlag, Flags, Segment
+from flagsmith.models import (
+    DefaultFlag,
+    Flags,
+    Segment,
+    SegmentOverridesIndex,
+    build_segment_overrides_index,
+)
 from flagsmith.offline_handlers import OfflineHandler
 from flagsmith.polling_manager import EnvironmentDataPollingManager
 from flagsmith.streaming_manager import EventStreamManager
@@ -77,6 +83,7 @@ def __init__(
         offline_handler: typing.Optional[OfflineHandler] = None,
         enable_realtime_updates: bool = False,
         application_metadata: typing.Optional[ApplicationMetadata] = None,
+        lazy_identity_evaluation: bool = True,
     ):
         """
         :param environment_key: The environment key obtained from Flagsmith interface.
@@ -105,6 +112,11 @@ def __init__(
             default_flag_handler if offline_mode is not set and using remote evaluation.
         :param enable_realtime_updates: Use real-time functionality via SSE as opposed to polling the API
         :param application_metadata: Optional metadata about the client application.
+        :param lazy_identity_evaluation: When True (default), ``get_identity_flags``
+            returns a lazy ``Flags`` that resolves flags on first access using a
+            precomputed segment-overrides index, rather than evaluating every
+            feature in the environment up-front. Set to False to opt back into
+            the legacy eager path if you hit a regression.
         """
 
         self.offline_mode = offline_mode
@@ -113,11 +125,13 @@ def __init__(
         self.offline_handler = offline_handler
         self.default_flag_handler = default_flag_handler
         self.enable_realtime_updates = enable_realtime_updates
+        self.lazy_identity_evaluation = lazy_identity_evaluation
         self._analytics_processor: typing.Optional[AnalyticsProcessor] = None
         self._pipeline_analytics_processor: typing.Optional[
             PipelineAnalyticsProcessor
         ] = None
-        self._evaluation_context: typing.Optional[SDKEvaluationContext] = None
+        self.__evaluation_context: typing.Optional[SDKEvaluationContext] = None
+        self._segment_overrides_index: SegmentOverridesIndex = {}
         self._environment_updated_at: typing.Optional[datetime] = None
 
         # argument validation
@@ -356,6 +370,26 @@ def update_environment(self) -> None:
             except (KeyError, TypeError, ValueError):
                 logger.exception("Error parsing environment document")
 
+    @property
+    def _evaluation_context(self) -> typing.Optional[SDKEvaluationContext]:
+        return self.__evaluation_context
+
+    @_evaluation_context.setter
+    def _evaluation_context(
+        self, context: typing.Optional[SDKEvaluationContext]
+    ) -> None:
+        """Swap in a new evaluation context and rebuild the overrides index.
+
+        The index maps feature_name -> segments that override it. Built once
+        per refresh and reused across every subsequent per-identity lazy
+        resolution; rebuilding here keeps it in sync with the current doc
+        without any hot-path cost.
+        """
+        self.__evaluation_context = context
+        self._segment_overrides_index = (
+            build_segment_overrides_index(context) if context is not None else {}
+        )
+
     def _get_headers(
         self,
         environment_key: str,
@@ -407,6 +441,19 @@ def _get_identity_flags_from_document(
             identifier=identifier,
             traits=traits,
         )
+        if self.lazy_identity_evaluation:
+            # Lazy path: defer per-feature evaluation until the caller
+            # actually reads a flag. Hot for callers that only read one
+            # or a few flags out of a large environment.
+            return Flags.from_evaluation_context(
+                context=context,
+                overrides_index=self._segment_overrides_index,
+                analytics_processor=self._analytics_processor,
+                default_flag_handler=self.default_flag_handler,
+                pipeline_analytics_processor=self._pipeline_analytics_processor,
+                identity_identifier=identifier,
+                traits=resolve_trait_values(traits),
+            )
         evaluation_result = engine.get_evaluation_result(
             context=context,
         )