Skip to content

feat(ai): take capture options in the AI integrations - #1208

Merged
eli-r-ph merged 4 commits into
eli/v1-celery-context-optionsfrom
eli/v1-ai-posthog-options
Nov 9, 2026
Merged

eli-r-ph merged 4 commits into
eli/v1-celery-context-optionsfrom
eli/v1-ai-posthog-options

Conversation

@eli-r-ph

@eli-r-ph eli-r-ph commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

💡 Motivation and Context

The AI integrations had no way to set capture options per call or per integration. The only routes were set_context_option around the call, super_options or before_send. This adds posthog_options, named so it does not clash with the Claude Agent SDK's own options.

Stacked on #1207.

  • Every wrapper method that takes posthog_properties takes posthog_options: OpenAI and Anthropic (chat, responses, parse, embeddings, streaming, sync and async), Gemini (generate, stream, embed), and the Claude Agent SDK query() and PostHogClaudeSDKClient.
  • The Gemini clients take posthog_options as a default for every call. A call's options win key by key, like posthog_properties.
  • LangChain's CallbackHandler and PostHogMiddleware, and instrument() and the processors for OpenAI Agents and the Claude Agent SDK, take options=. LangChain also reads a posthog_options run-metadata key.
  • Precedence mirrors properties: the handler's or processor's options win over a run's or a query's.
  • _capture_ai_event sends the options as the event's own, so they beat context options and super_options. The personless process_person_profile: False is applied last and always wins.
  • A value that is not a dict logs a warning and is ignored, so the provider call never fails. No options argument is passed when none are set.
  • The wrappers never pass posthog_options to the provider.
  • Docs: the migration guide's AI section replaces "no options argument" with the new arguments and an example. Docstrings on every new parameter.
  • Public API snapshot and a minor changeset.

💚 How did you test it?

  • Parameterized tests run each case through every wrapper: OpenAI (8 calls), Anthropic (3 calls) and Gemini (3 calls on 3 surfaces), sync and async. Each checks:
    • the captured options;
    • that the provider never receives posthog_options;
    • personless False beats a user True, and an identified event keeps the user's values;
    • no options kwarg when unset;
    • a non-dict value logs a warning and is ignored.
  • The same cases run through the LangChain handler (all three events), OpenAI Agents instrument(), and the Claude Agent SDK query(), processor and instrument().
  • Extra tests cover Gemini client defaults, LangChain run metadata, the processor-over-query precedence, PostHogClaudeSDKClient and the middleware.
  • A real-Client test shows per-call options beat set_context_option and super_options.
  • 180 of the new cases fail without the source change. The 31 that pass guard the unset path.
  • ruff, mypy baseline and the public API check pass. The AI tests and test_client.py pass. The full suite has three fork tests that also fail on macOS without this change.

📝 Checklist

  • All commits are signed (see Commit signing)
  • I reviewed the submitted code.
  • I added tests to verify the changes.
  • I updated the docs if needed.
  • No breaking change or entry added to the changelog.

If releasing new changes

  • Ran sampo add to generate a changeset file (minor changeset written by hand)

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code, Claude Opus 5.5. The argument names, merge order and plumbing were set by the maintainer. The LangChain and Claude Agent SDK precedence copies their properties, where the integration-level value wins. LangChain's $exception events, sent with capture_exception, do not get the options. That keeps this change inside the AI event path.

🤖 Generated with Claude Code

@eli-r-ph eli-r-ph self-assigned this Nov 8, 2026
Every AI wrapper method that takes posthog_properties also takes
posthog_options, and the Gemini clients take it as a per-client
default. LangChain's CallbackHandler and PostHogMiddleware, and the
OpenAI Agents and Claude Agent SDK instrument() and processors, take
options=. LangChain also reads posthog_options from run metadata.

The wrappers never pass posthog_options to the provider. The options
are sent as the event's own options, below the personless
process_person_profile: False. A value that is not a dict is logged
and ignored, and no options argument is passed when none are set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eli-r-ph
eli-r-ph force-pushed the eli/v1-ai-posthog-options branch from 67e5ff7 to 0a65bf3 Compare November 8, 2026 02:38
@eli-r-ph
eli-r-ph marked this pull request as ready for review November 8, 2026 03:20
@eli-r-ph
eli-r-ph requested a review from a team as a code owner November 8, 2026 03:20
eli-r-ph and others added 3 commits November 7, 2026 19:22
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@marandaneto marandaneto left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code looks good; no qualifying findings. Verdict: correct.

@eli-r-ph
eli-r-ph merged commit d3fb4df into eli/v1-celery-context-options Nov 9, 2026
42 checks passed
@eli-r-ph
eli-r-ph deleted the eli/v1-ai-posthog-options branch November 9, 2026 23:40
eli-r-ph added a commit that referenced this pull request Nov 9, 2026
* feat(celery): propagate context options to workers

Publish context options in an X-POSTHOG-CONTEXT-OPTIONS task header,
next to the tags header, and set them as context options on the worker
before the task started event. propagate_context=False sends none.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(celery): point eager tasks to explicit PostHog headers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(ai): take capture options in the AI integrations (#1208)

* feat(ai): take capture options in the AI integrations

Every AI wrapper method that takes posthog_properties also takes
posthog_options, and the Gemini clients take it as a per-client
default. LangChain's CallbackHandler and PostHogMiddleware, and the
OpenAI Agents and Claude Agent SDK instrument() and processors, take
options=. LangChain also reads posthog_options from run metadata.

The wrappers never pass posthog_options to the provider. The options
are sent as the event's own options, below the personless
process_person_profile: False. A value that is not a dict is logged
and ignored, and no options argument is passed when none are set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(ai): send LangChain exception events with the run's options

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migration): simplify the 8.0 checklist and MCP hook note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(ai): pass exception options as a typed keyword

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
eli-r-ph added a commit that referenced this pull request Nov 9, 2026
* feat(mcp): add event_options to MCP capture calls and instrument

The PostHogMCP capture_* methods and McpAnalytics.capture take a
keyword-only event_options argument, and MCPAnalyticsOptions gains an
event_options callback, called for the same events as event_properties.
Per-call options win over the callback's key by key, and an event
without an identity still always sends process_person_profile: False.
A non-dict value is logged and ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(mcp): document MCP event_options

Covers the per-call argument and the callback, why context options set
inside a tool handler miss $mcp_tool_call, copying options in MCP
before_send, and the options vs event_options split on PostHogMCP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(celery): propagate context options to workers (#1207)

* feat(celery): propagate context options to workers

Publish context options in an X-POSTHOG-CONTEXT-OPTIONS task header,
next to the tags header, and set them as context options on the worker
before the task started event. propagate_context=False sends none.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(celery): point eager tasks to explicit PostHog headers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(ai): take capture options in the AI integrations (#1208)

* feat(ai): take capture options in the AI integrations

Every AI wrapper method that takes posthog_properties also takes
posthog_options, and the Gemini clients take it as a per-client
default. LangChain's CallbackHandler and PostHogMiddleware, and the
OpenAI Agents and Claude Agent SDK instrument() and processors, take
options=. LangChain also reads posthog_options from run metadata.

The wrappers never pass posthog_options to the provider. The options
are sent as the event's own options, below the personless
process_person_profile: False. A value that is not a dict is logged
and ignored, and no options argument is passed when none are set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(ai): send LangChain exception events with the run's options

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migration): simplify the 8.0 checklist and MCP hook note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(ai): pass exception options as a typed keyword

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
eli-r-ph added a commit that referenced this pull request Nov 9, 2026
…y context options, AI options (#1202, #1206, #1207, #1208)

Squash of the per-event $lib stack: #1202 (per-event $lib/$lib_version), #1206 (MCP event_options), #1207 (Celery context options to workers) and #1208 (capture options in the AI integrations).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants