[stanleyphu]

Description

The Python SDK had no way to evaluate feature flags locally. This adds the runtime client the Node and .NET SDKs already have: it polls GET /sdk/feature-flags?payload_version=2 in the background, keeps the environment's configuration in memory, and evaluates ordered targeting rules with no request per check.

flags = workos.create_feature_flags_runtime_client()
flags.start()
flags.wait_until_ready(timeout=5)
flags.is_enabled("new-checkout", {"user": "user_123", "organization": "org_123"})

• FeatureFlagsRuntimeClient polls on a daemon thread. AsyncFeatureFlagsRuntimeClient, from AsyncWorkOSClient, polls in an asyncio task. Evaluation is synchronous in both.
• Evaluation matches Node and .NET: a disabled flag serves its off value, otherwise the first rule whose conditions all match wins, then the default value. The context is a flat {target_type: id} mapping, so custom target types work the same way as user and organization.
• A failed poll keeps the last good configuration and backs off. Transient failures are retried within request_timeout, up to the client's max_retries, and a 401 stops polling.
• Also included: bootstrap from a persisted FeatureFlagsConfiguration, on_change / on_error / on_status listeners, status, get_flag(), and a manual refresh() that works without start().
• It handles fork(). With the SDK's default HTTP client, a sync client created before the fork (gunicorn --preload) polls on new connections in each worker. Where that isn't safe, start() and refresh() raise, and the client keeps serving its last configuration. That covers macOS, and a parent that already sent requests, from the runtime client or any other SDK call, through a caller-supplied HTTP client or the AsyncWorkOSClient. The README has the details.

Where it differs from Node on purpose:

• It reads v2 payloads only. A v1 response fails the refresh and keeps the previous configuration.
• Change events follow .NET: one on_change per refresh that installs a different configuration, including the first load.
• It accepts payloads Node rejects as a whole, such as a flag without a default or off value or a rule shape it doesn't know, and skips only what it can't evaluate. get_all_flags leaves out flags without a boolean answer.

All of it is hand-maintained: the runtime package and its tests are @oagen-ignore-file, and the create_feature_flags_runtime_client methods on both clients sit inside the existing @oagen-ignore fences in _client.py. There are no new dependencies. It only adds API, so it's a minor release. Squash-merge it with this title so the intermediate fix: commits don't end up in the changelog.

How I checked it:

• I ran it side by side with the Node SDK in our feature flags runtime lab, against the same fixture responses. All 87 scenario checks pass, 47 for Python and 40 for Node. They cover rule order, contexts, disabled flags, unknown rules, non-boolean values, bootstrap, 401, 403 and 500 responses, slow responses and v1 responses.
• I ran it live against a local WorkOS API (v2 payload, 17 flags) with both the thread and asyncio clients. I reordered rules, disabled and re-enabled a flag, added and removed an organization target, and tried a bad API key. Node and Python returned the same value for every flag at every step.
• The fork tests run each case in a subprocess. They pass on macOS and on Linux (python:3.12-slim in Docker).

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[x] Yes

The feature flags SDK docs describe the runtime client as Node only. A docs PR adding Python is still to do.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The changes appear safe to merge; all three previous findings are addressed.

Summary

Adds sync and async clients that poll feature flag settings and evaluate flags locally.

• Feature flags use ordered rules and matching target IDs.
• Sync and async clients keep feature flags fresh in the background.
• Forked workers follow safe rules for resuming flag polling.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Start or manual refresh] --> B[Fetch v2 settings]
  B --> C{Fetch and parsing succeed?}
  C -->|Yes| D[Install snapshot and notify listeners]
  C -->|No| E[Keep last good snapshot]
  D --> F[Evaluate flags locally]
  E --> F
  E --> G{401 response?}
  G -->|Yes| H[Stop polling]
  G -->|No| I[Wait and retry]

Loading

_{Reviews (2) · Last reviewed commit: "fix(feature-flags): Notify change listen..." · Reviewed by Greptile}

[stanleyphu]

Closing in favor of a four-PR stack that's easier to review: #764 (configuration and evaluation) → #765 (sync runtime client) → #766 (async runtime client) → #767 (fork safety). #767's tree is identical to this PR's head, so the Greptile fixes resolved here are included in #767.