docs: describe the span tree the SDK now emits by apucacao · Pull Request #37 · launchdarkly/python-ai-sdk

apucacao · 2026-08-11T20:13:36Z

Updates the docs to describe the span tree the SDK now emits.

README and AGENTS.md both still described one flat span per call with four attributes, which is what this SDK emitted before this stack and what neither SDK emits now. A reader following either document would have built the wrong thing.

README

The span tree, and the rule that tool spans are siblings of chat rather than children.
Why the root is the only span carrying the LaunchDarkly identity and the run total.
What prompt caching does to the input count. The Anthropic example is the one worth keeping in mind: the provider reports an input of 3 for a turn that processed 23,554 tokens.
That conversation content is off by default and how to turn it on, since that is the change most likely to surprise someone who was reading prompts off their spans.
That an abandoned stream is marked rather than failed.

Also fixes an install command that named a package which does not exist: launchdarkly-ai rather than launchdarkly-ai-python.

AGENTS.md

Now points at TELEMETRY-CONTRACT.md as the authority rather than restating a summary that can drift from it, and lists the shared helpers with what each one writes.

The instruction that matters most is not to hand-write a span.set_attribute for anything a helper covers: six hand-rolled copies is how these spans drifted apart in the first place.

It also records the three things a new handler author would otherwise get wrong:

Cache folding belongs at the call site, not in the shared writer.
Finish reasons have three mechanisms, not one.
except Exception does not catch the GeneratorExit a streaming consumer triggers by breaking out of the loop.

Per-package docs

Each handler package's agents.md gets a four-line note with its span shape and a pointer to the contract, so someone opening one package sees it without reading the root document first.

Where this sits

Top of the stack. Docs only, no code.

Note

Overview
Documentation now matches the three-level OpenTelemetry span tree handlers emit (invoke_agent → chat {model} → execute_tool), replacing the outdated “one flat span per call” description.

README adds user-facing coverage of the span hierarchy (tool spans as siblings of chat), why LaunchDarkly identity and run totals live on the root span, prompt-cache folding into gen_ai.usage.input_tokens, default-off conversation content via capture_content=True, and abandoned-stream handling. It also corrects the OTel install line to launchdarkly-ai-python[otel] instead of the non-existent launchdarkly-ai[otel] package name.

AGENTS.md defers span specifics to TELEMETRY-CONTRACT.md, lists shared launchdarkly_ai_server span helpers, and documents handler-author pitfalls: explicit parent context, per-provider cache folding at the call site, gated content capture, finish-reason differences, and streaming cleanup in finally for GeneratorExit.

Each Tier 1 handler package agents.md gets a short header pointing at the same span shape, spans.py, and the contract file.

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

apucacao · 2026-08-11T20:20:50Z

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 2137167. Configure here.}

apucacao · 2026-08-11T20:45:04Z

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 73fa904. Configure here.}

apucacao · 2026-08-11T21:02:24Z

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 1f5aa42. Configure here.}

apucacao · 2026-08-11T21:19:36Z

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 619c8ef. Configure here.}

apucacao · 2026-08-11T21:46:48Z

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 619c8ef. Configure here.}

apucacao · 2026-08-12T17:23:36Z

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 c2a178b. Configure here.}

apucacao · 2026-08-12T17:46:42Z

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 cc0eb52. Configure here.}

apucacao · 2026-08-12T18:03:41Z

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 b2b3c53. Configure here.}

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 73c9dd7. Configure here.}

apucacao · 2026-08-14T18:42:56Z

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 537233e. Configure here.}

apucacao · 2026-08-14T19:02:09Z

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 3ebb6af. Configure here.}

apucacao · 2026-08-14T19:17:01Z

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 1f36055. Configure here.}

apucacao · 2026-08-14T19:31:04Z

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 46af84b. Configure here.}

apucacao · 2026-08-14T19:40:42Z

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 eb6b7b8. Configure here.}

README and AGENTS.md both still described one flat span per call with four attributes, which is what this SDK emitted before the span work and what neither SDK emits now. A reader following either document would have built the wrong thing. README gains the tree, the rule that tool spans are siblings of chat rather than children, why the root is the only span carrying the LaunchDarkly identity and the run total, and what prompt caching does to the input count. The Anthropic example is the one worth keeping in mind: the provider reports an input of 3 for a turn that processed 23,554 tokens. It also documents that conversation content is off by default and how to turn it on, since that is the change most likely to surprise someone who was reading prompts off their spans. AGENTS.md now points at TELEMETRY-CONTRACT.md as the authority rather than restating a summary that can drift from it, and lists the shared helpers with what each one writes. The instruction that matters most is not to hand-write a span.set_attribute for anything a helper covers: six hand-rolled copies is how these spans drifted apart in the first place. It also records the three things a new handler author would otherwise get wrong: that cache folding belongs at the call site and not in the shared writer, that finish reasons have three mechanisms rather than one, and that `except Exception` does not catch the GeneratorExit a streaming consumer triggers by breaking out of the loop. Each handler package's agents.md gets a four-line note with its span shape and a pointer to the contract, so someone opening one package sees it without reading the root document first. Fixes the README's install command, which named a package that does not exist: launchdarkly-ai rather than launchdarkly-ai-python.

apucacao · 2026-08-14T19:57:32Z

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 bc7815a. Configure here.}

cursor Bot reviewed Aug 11, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from 2137167 to 73fa904 Compare August 11, 2026 20:43

cursor Bot reviewed Aug 11, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from 73fa904 to 1f5aa42 Compare August 11, 2026 21:01

cursor Bot reviewed Aug 11, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from 1f5aa42 to 619c8ef Compare August 11, 2026 21:18

cursor Bot reviewed Aug 11, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from 619c8ef to c2a178b Compare August 12, 2026 17:23

cursor Bot reviewed Aug 12, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from c2a178b to cc0eb52 Compare August 12, 2026 17:45

cursor Bot reviewed Aug 12, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from cc0eb52 to b2b3c53 Compare August 12, 2026 18:02

cursor Bot reviewed Aug 12, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from b2b3c53 to c139584 Compare August 12, 2026 18:07

cursor Bot reviewed Aug 14, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from 73c9dd7 to 537233e Compare August 14, 2026 18:41

cursor Bot reviewed Aug 14, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from 537233e to 3ebb6af Compare August 14, 2026 19:01

cursor Bot reviewed Aug 14, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from 3ebb6af to 1f36055 Compare August 14, 2026 19:16

cursor Bot reviewed Aug 14, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from 1f36055 to 46af84b Compare August 14, 2026 19:30

cursor Bot reviewed Aug 14, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from 46af84b to eb6b7b8 Compare August 14, 2026 19:39

cursor Bot reviewed Aug 14, 2026

View reviewed changes

apucacao force-pushed the ag/py-telemetry-docs branch from eb6b7b8 to bc7815a Compare August 14, 2026 19:56

cursor Bot reviewed Aug 14, 2026

View reviewed changes

andrewklatzke approved these changes Aug 14, 2026

View reviewed changes

apucacao marked this pull request as ready for review August 14, 2026 21:18

apucacao merged commit 6a82ef5 into main Aug 14, 2026
12 checks passed

apucacao deleted the ag/py-telemetry-docs branch August 14, 2026 21:20

github-actions Bot mentioned this pull request Aug 14, 2026

chore: release main #41

Open

Uh oh!

Conversation

apucacao commented Aug 11, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

README

AGENTS.md

Per-package docs

Where this sits

Uh oh!

apucacao commented Aug 11, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 11, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 11, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 11, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 11, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 12, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 12, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 12, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 14, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 14, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 14, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 14, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 14, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

apucacao commented Aug 14, 2026

Uh oh!

cursor Bot left a comment

apucacao commented Aug 11, 2026 •

edited by cursor Bot

Loading