[apucacao]

@andrewklatzke @jeffdupont Here's the PR that gives users a process-level path to control whether the SDK includes content in o11y. They may want to continue doing it per-handler, but that could be error-prone if they're not careful.

---

Adds a process-wide configure(options=SDKOptions) API for SDK behavior defaults. Handlers read capture_content when they run, and an explicit True or False on a factory or convenience wrapper overrides the configured default.

init_client stays the LaunchDarkly client initializer. SDKOptions is the extension point for later process-wide defaults.

---

Note

Overview
Adds configure(options=SDKOptions(...)) on the core client so apps can set process-wide behavior defaults separately from init_client. The first field is capture_content (still off by default); shutdown() resets options to built-ins.

Handler factories and convenience wrappers now take capture_content: bool | None = None. None resolves at invocation via effective_capture_content, so a handler built before startup can still follow configure. Explicit True / False overrides the process default (including False over a configured True). ProviderHandler.capture_content is a property that returns that effective bool (used for judge explanations too). Options are locked after the first __call__ / stream unless configure is called again with an identical SDKOptions.

All Tier 1 handler packages adopt the same pattern, bump launchdarkly-ai-server>=0.3.1, and add tests for streaming/process defaults. Docs (TELEMETRY-CONTRACT, README, AGENTS.md) describe the new flow.

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

[apucacao]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[jeffdupont]

Reviewed at 6be2bb0. All 2402 tests pass; the branch merges cleanly with current main and client tests still pass after the merge. The code itself is correct: all 12 effective_capture_content(content_override) call sites resolve in both blocking and stream paths, and the lock fires through ProviderHandler.__call__/.stream (tracking.py:201, :303, :315).

Must fix (spec and process gates, not code bugs)

1. configure and SDKOptions aren't on the approved API list (launchdarkly_ai_server/__init__.py)
api-surface/python/launchdarkly_ai_server.txt on monorepo main has neither (they'd sit next to config/ConfigInstance). TESTING.md §5.2 (around line 2226) says the monorepo + Name PR comes first and the SDK PR can't merge before its sync PR. CI passes today only because this repo has no api-surface/ copy yet; after the first sync it fails on both names for every open PR.
Fix: monorepo PR adding + configure / + SDKOptions (and the TS names), then merge this after the sync.

2. No spec and no TypeScript counterpart for a PII setting (monorepo TESTING.md §1.1 ~line 197, §3.14 ~line 1340)
TESTING.md doesn't mention configure/SDKOptions. §3.14 still says Python defaults capture_content=False; this PR changes it to None. §1.1 says an omitted option attaches false, which is only true while nothing is configured. No js-ai-sdk PR exists (searched configure, SDKOptions, captureContent, "process-wide").
Fix: spec PR covering precedence, the lock after first call and the shutdown() reset, updating §1.1/§3.14; then the JS PR.

3. ProviderHandler.capture_content is no longer assignable (types.py:177-182)
It's now a read-only property: h.capture_content = False raises AttributeError: property 'capture_content' of 'ProviderHandler' object has no setter. That's breaking for any caller that sets it, but the title is feat:, so release-please won't note it. (Nothing in this repo assigns it; external callers unverified.)
Fix: a 3-line @capture_content.setter writing _capture_content_override, or retitle as feat!:.

Should fix

4. The "configure turns content on" path is end-to-end tested for 1 of 6 handlers
Only openai-agents runs a handler under configure(True) and checks the span. The other five only check the wrapper forwards None, so e.g. passing content_override (falsy None) instead of the resolved bool in claude-messages _stream_impl would silently keep content off with no failing test. test_judge_gate_uses_the_effective_bool copies the expression from judges.py instead of calling run_judges, so it passes even if judges.py:188/:455 change.
Fix: one configure(True) + no-arg handler test per remaining package; replace the judge test with one that runs run_judges and asserts gen_ai.evaluation.explanation is set (pattern: test_conversation.py:216).

5. Provider packages crash on import with an older client (packages/*/pyproject.toml, e.g. openai-agents/pyproject.toml:6)
They depend on unpinned launchdarkly-ai-server and now import effective_capture_content. Upgrading only a provider package against client 0.3.0 gives ImportError. Pre-existing gap, but this PR hits all 6.
Fix: launchdarkly-ai-server>=<next client version> in the 6 provider pyprojects.

Nice to have

6. Root README.md:522 and line 5 of the six provider agents.md files still say content is off "unless the caller passes capture_content=True". Add one sentence linking to the client README "Process-wide defaults" section.

Verdict: fix 1, 2 and 3 first.

[apucacao]

@jeffdupont, thanks. The concrete items are in dab2c44.

3. ProviderHandler.capture_content is assignable again. The setter writes _capture_content_override, so handler.capture_content = False is an override and does not raise.

4. Each of the other five handlers has a streaming test that calls configure(capture_content=True) on a no-arg factory and asserts gen_ai.input.messages. test_run_judges_writes_the_explanation_from_the_configured_default runs run_judges and checks gen_ai.evaluation.explanation is "good", and that an explicit False omits it.

5. The six provider packages now depend on launchdarkly-ai-server>=0.3.1, the next client version for this feat.

6. The root README and the six provider agents.md files link to the client README's Process-wide defaults section.

1 and 2 are not changed here. They are monorepo gates, not behavior to invent on this branch:

• api-surface/python/launchdarkly_ai_server.txt still needs + configure and + SDKOptions (and the TypeScript names). This SDK PR should merge after that sync.
• TESTING.md still needs the configure spec (precedence, the lock after the first call, and the shutdown() reset) and the §1.1 / §3.14 updates, then a js-ai-sdk counterpart. There is no JS PR yet.

Local result: 2409 passed, 11 skipped. ruff, format, and mypy are clean.

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

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

[apucacao]

@jeffdupont, the two remaining gates are in e70f0e2 on https://github.com/launchdarkly/ai-sdks-monorepo/pull/58. They live in the monorepo, not in this branch.

1. api-surface/python/launchdarkly_ai_server.txt adds + configure and + SDKOptions. api-surface/typescript/ai-server.txt adds the same two names. The + mark is the joining state from TESTING.md §5.2, so a name may be exported or not yet. Python already exports them on this PR; TypeScript does not.

2. TESTING.md §3.9a specifies configure / SDKOptions: precedence is the per-call wrapper, then an explicit handler-factory value, then the configured default, then built-in false; an explicit false overrides a configured true; options can change until the first AI invocation and only an identical value is accepted after; shutdown() restores the built-in defaults and clears the lock. §1.1 and §3.14 now say an omitted capture_content is unset and resolved at invocation, not baked in as false.

The js-ai-sdk configure implementation stays deferred. This change only reserves the TypeScript names and writes the spec.

Bugbot on e70f0e2 found no issues, and the monorepo api-surface check passed. This PR's head is still dab2c44, where Bugbot already reported no issues.