feat: emit LaunchDarkly context identity on AI SDK feature_flag spans

[ccschmitz-launchdarkly]

What

Python counterpart of the js-ai-sdk change (filed alongside this). Carries the identity of the context an AI Config was evaluated for onto the run's root span, so observability can filter a config's traces down to a single context. This PR also carries the TELEMETRY-CONTRACT.md update for both SDKs, since that document is canonical for both.

Three attributes, none of them a new LaunchDarkly convention:

Where	Attribute	Value
feature_flag event	feature_flag.context.id	canonical key — an OTel semconv attribute (RC since v1.29.0), same value go-server-sdk/ldotel emits
feature_flag event	feature_flag.contextKeys	JSON object of per-kind keys — matches the observability browser SDK
root span	context.contextKeys.<kind>	one attribute per kind — matches the browser SDK and the product-analytics pipeline

Why the identity is emitted in two shapes

feature_flag.context.id is a composite for a multi-kind context (kind:key:kind:key, sorted), so it cannot answer "filter this config's traces to this one user" — which is exactly the question AI Config Monitoring's group-by asks, since that groups per kind. And feature_flag.contextKeys lands in a ClickHouse String column holding JSON, so filtering it per kind would be substring matching. The per-kind span attributes are what give an exact match on a single kind.

Why keys only

Context keys are identifiers, and LaunchDarkly's other OTel integrations already expose them. Context attribute values are where the personal data lives, so none are read or emitted, and no capture option is added — there is nothing to gate. A test asserts that a context carrying name and email leaks neither.

How it works

No plumbing. execute_and_track / execute_and_stream already merge ldContext into the variables dict next to __ld, after the caller's own variables so it can't be clobbered. set_ld_span_attributes reads it there, and all six handler packages reach it through their spans.start_root_span, so provider coverage is uniform by construction.

Deliberately not on TrackData: that dict is the data payload of every $ld:ai:* track call, where context keys would duplicate the call's own context argument and bloat every analytics event.

New ld_context.py is a port of getCanonicalKey/getContextKeys from the observability browser SDK's LaunchDarkly integration, sharing fixtures with the TypeScript port so the two cannot drift. It deliberately does not go through ldclient.Context.fully_qualified_key: ldclient is an optional import here (see to_ld_context), and an attribute that silently vanishes for anyone using a custom client is worse than no attribute.

context_identity never raises — this runs on the emit path of every run, so a malformed context degrades to emitting nothing.

Two details worth a reviewer's eye

json.dumps needs explicit separators. Python defaults to ", " / ": "; JSON.stringify emits neither. Without separators=(",", ":") the same context would produce a different string in Python than in TypeScript, in a column consumers may match as text. There is a test pinning the exact bytes.

The vocabulary lock needed widening, in the same commit. tests/test_cross_handler_parity.py statically scans attribute literals against a committed list. Its regex was lowercase-only (feature_flag\.[a-z_.]+) and limited to the gen_ai/launchdarkly/feature_flag/ld namespaces, so it could see feature_flag.context.id but not feature_flag.contextKeys (camelCase) or context.contextKeys.<kind> (f-string, context namespace). Adding the keys to EXPECTED_VOCABULARY without widening the scanner fails one lock test; widening without adding fails the other — so both halves are in one commit. Verified that widening surfaces nothing else: there are no pre-existing set_attribute("context… literals and no uppercase letters in any existing "feature_flag.…" literal.

RecordedSpan.add_event also discarded event attributes (events was a list[str]), so nothing could assert on the feature_flag event's payload. It is now a name-keyed dict; all existing usages are membership checks and survive unchanged.

Testing

• make test — 1135 passed, 11 skipped
• make lint — clean
• Both TestVocabularyLock tests pass
• New: 20 cases in test_ld_context.py (shared fixtures with the TS port), 9 in test_span_attributes.py (nothing covered set_ld_span_attributes before), plus 2 cross-handler cases asserting all six handlers write the per-kind attributes and that tool spans still do not

Pre-existing failure, unrelated: make typecheck fails with Duplicate module named "conftest". This repo has 8 identically-named conftest.py files and no per-package mypy config; the failure reproduces on unmodified origin/main and this branch touches none of them. Every new and modified file passes mypy --strict individually. Worth its own ticket.

Still outstanding, tracked on the ticket: end-to-end verification in staging that the context.contextKeys.user=… filter returns the run.

Links

• AIC-3230 — https://launchdarkly.atlassian.net/browse/AIC-3230
• O11Y-1921 (the consumer this unblocks) — https://launchdarkly.atlassian.net/browse/O11Y-1921
• js-ai-sdk counterpart: filed alongside this

---

Note

Overview
Adds evaluation context identity to the Python AI SDK’s root invoke_agent span and its feature_flag event so AI Config Monitoring can filter traces by a single context kind (e.g. user), not only by config.

ld_context.py ports canonical-key and per-kind-key derivation from the observability browser SDK / js-ai-sdk, with shared test fixtures so emitters stay aligned. set_ld_span_attributes reads variables["ldContext"] and, when identity is valid, sets feature_flag.context.id, compact JSON feature_flag.contextKeys (matching JSON.stringify), and one span attribute per kind as context.contextKeys.<kind>. Malformed or missing context emits nothing and never raises; only context keys are written—no custom attribute values.

TELEMETRY-CONTRACT.md documents the new fields and the keys-only rule. Cross-handler parity tests assert all six handlers get context on the root only (not tool spans), and the vocabulary lock scanner was extended for camelCase feature_flag.contextKeys and the context namespace.

^{Reviewed by Cursor Bugbot for commit a820aa8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a820aa8. Configure here.}

[cursor]

JSON encoding mismatches TypeScript output

Low Severity

json.dumps still uses ensure_ascii=True, so non-ASCII context keys are emitted as \uXXXX escapes. JSON.stringify writes those characters as-is, so feature_flag.contextKeys will not be byte-identical to js-ai-sdk or the browser SDK for the same context. That string is stored verbatim in ClickHouse and may be matched as text.

 

^{Reviewed by Cursor Bugbot for commit a820aa8. Configure here.}