feat: Support device_id as bucketing identifier for local evaluation

[andehen]

Problem

Feature flags need to support using device_id instead of distinct_id for bucketing/hashing in local evaluation. This allows consistent flag experiences across anonymous and identified users on the same device.

Changes

• Add bucketing_identifier field support on flag["filters"] - can be "distinct_id", "device_id", or null/missing (defaults to "distinct_id")
• When bucketing_identifier: "device_id", use device_id for hash calculations instead of distinct_id
• device_id can be passed as a method parameter or resolved from context via get_context_device_id()
• If device_id is required but not provided, raise InconclusiveMatchError to trigger server fallback
• Group flags ignore bucketing_identifier and always use group identifier (via skip_bucketing_identifier parameter)

Question to the feature flags team: If a flag is configured to use device_id has bucketing identifier, but none is provided, should we:
a) raise an error and return "false" (current behavior)
b) fall back to use distinct_id and return whatever that resolves to

Personally I prefer a), as I would like to know when this happens and fix my code.

Testing

• Basic device_id bucketing - flag with bucketing_identifier: "device_id" uses device_id for hashing
• Same device_id with different distinct_ids produces same result
• Missing device_id fallback - raises InconclusiveMatchError, triggers server evaluation
• Default to distinct_id - null/missing bucketing_identifier uses distinct_id
• Multivariate with device_id - variant selection uses device_id hash
• device_id from context - get_context_device_id() is used when param not provided
• Group flags unaffected - aggregation_group_type_index continues to use group identifier
• only_evaluate_locally=True returns None when device_id required but missing
• get_all_flags properly handles device_id bucketing
• All existing tests pass (631 passed)

[github-actions]

posthog-python Compliance Report

Date: 2026-02-13 15:19:11 UTC
Duration: 159385ms

✅ All Tests Passed!

29/29 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	518ms
Format Validation.Event Has Uuid	✅	1508ms
Format Validation.Event Has Lib Properties	✅	1507ms
Format Validation.Distinct Id Is String	✅	1508ms
Format Validation.Token Is Present	✅	1507ms
Format Validation.Custom Properties Preserved	✅	1508ms
Format Validation.Event Has Timestamp	✅	1507ms
Retry Behavior.Retries On 503	✅	9517ms
Retry Behavior.Does Not Retry On 400	✅	3507ms
Retry Behavior.Does Not Retry On 401	✅	3509ms
Retry Behavior.Respects Retry After Header	✅	9510ms
Retry Behavior.Implements Backoff	✅	23534ms
Retry Behavior.Retries On 500	✅	7504ms
Retry Behavior.Retries On 502	✅	7511ms
Retry Behavior.Retries On 504	✅	7513ms
Retry Behavior.Max Retries Respected	✅	23531ms
Deduplication.Generates Unique Uuids	✅	1497ms
Deduplication.Preserves Uuid On Retry	✅	7515ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	14511ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7520ms
Deduplication.No Duplicate Events In Batch	✅	1503ms
Deduplication.Different Events Have Different Uuids	✅	1506ms
Compression.Sends Gzip When Enabled	✅	1508ms
Batch Format.Uses Proper Batch Structure	✅	1506ms
Batch Format.Flush With No Events Sends Nothing	✅	1004ms
Batch Format.Multiple Events Batched Together	✅	1506ms
Error Handling.Does Not Retry On 403	✅	3508ms
Error Handling.Does Not Retry On 413	✅	3508ms
Error Handling.Retries On 408	✅	7514ms

[dmarticus]

A few questions but nothing blocking.

Also, re: your open question about design, I agree with option (a). Silently falling back to distinct_id would mask configuration bugs and defeat the purpose of device_id bucketing. The current behavior of raising InconclusiveMatchError → server fallback is the right call. It's observable (you can log/monitor fallback rates) and self-correcting (server has the device_id from the request context or can handle it differently).

[dmarticus]

I don't think breaks anything, but it feels a little confusing technically – this is passed positionally to match_feature_flag_properties, but bucketing_value is a keyword-only arg (or at least should be treated as one given the * separator in is_condition_match). More importantly, you're adding bucketing_value as a kwarg to match_feature_flag_properties but passing it
positionally here; I'd double check this actually lands in the right parameter. Looking at the signature, it seems fine since it's a named kwarg, but worth verifying.

[dmarticus]

oh and also, If group_name isn't in groups, this will raise a KeyError. The existing code presumably handles this elsewhere, but worth confirming since you're now accessing it in a new location (before, group_name was only used in the properties lookup path).

[andehen]

good call out! i went a few extra rounds to refactor this a bit and made the code more defensive

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

posthog/client.py
Group properties default changed
In _compute_flag_locally the group properties passed to match_feature_flag_properties changed from group_properties[group_name] to group_properties.get(group_name, {}). Previously, if groups[group_name] was present but group_properties lacked that key, this would KeyError and trigger API fallback; now it silently evaluates with {} and can return a definitive False/variant locally.

This changes behavior for callers that provide groups but forget corresponding group_properties, and may prevent intended server fallback. If the previous fallback was relied upon, restore the KeyError behavior (or explicitly raise InconclusiveMatchError) when group_properties is missing for the group flag.

Prompt To Fix With AI

This is a comment left during a code review.
Path: posthog/client.py
Line: 1452:1468

Comment:
**Group properties default changed**
In `_compute_flag_locally` the group properties passed to `match_feature_flag_properties` changed from `group_properties[group_name]` to `group_properties.get(group_name, {})`. Previously, if `groups[group_name]` was present but `group_properties` lacked that key, this would `KeyError` and trigger API fallback; now it silently evaluates with `{}` and can return a definitive `False/variant` locally.

This changes behavior for callers that provide `groups` but forget corresponding `group_properties`, and may prevent intended server fallback. If the previous fallback was relied upon, restore the `KeyError` behavior (or explicitly raise `InconclusiveMatchError`) when `group_properties` is missing for the group flag.

How can I resolve this? If you propose a fix, please make it concise.