From 0a65bf36e6195ec2cda1646445df7f7271a0cf3e Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Sat, 7 Nov 2026 18:31:15 -0800 Subject: [PATCH 1/4] 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 --- .sampo/changesets/ai-posthog-options.md | 5 + docs/migration-7.x-to-8.0.md | 28 +- posthog/ai/anthropic/anthropic.py | 19 ++ posthog/ai/anthropic/anthropic_async.py | 19 ++ posthog/ai/claude_agent_sdk/__init__.py | 13 + posthog/ai/claude_agent_sdk/client.py | 6 + posthog/ai/claude_agent_sdk/processor.py | 28 ++ posthog/ai/gemini/_shared.py | 13 + posthog/ai/gemini/gemini.py | 32 +++ posthog/ai/gemini/gemini_async.py | 31 ++ posthog/ai/langchain/callbacks.py | 17 ++ posthog/ai/langchain/middleware.py | 8 + posthog/ai/openai/_embeddings.py | 2 + posthog/ai/openai/_streaming.py | 2 + posthog/ai/openai/openai.py | 49 ++++ posthog/ai/openai/openai_async.py | 49 ++++ posthog/ai/openai_agents/__init__.py | 6 + posthog/ai/openai_agents/processor.py | 8 + posthog/ai/types.py | 1 + posthog/ai/utils.py | 52 +++- posthog/test/ai/anthropic/test_anthropic.py | 97 ++++++- .../ai/claude_agent_sdk/test_processor.py | 146 ++++++++++ posthog/test/ai/gemini/test_gemini.py | 155 +++++++++- posthog/test/ai/langchain/test_callbacks.py | 70 +++++ posthog/test/ai/langchain/test_middleware.py | 2 + posthog/test/ai/openai/test_openai.py | 271 ++++++++++++++++++ .../test/ai/openai_agents/test_processor.py | 31 ++ posthog/test/ai/utils.py | 52 ++++ references/public_api_snapshot.txt | 84 +++--- 29 files changed, 1240 insertions(+), 56 deletions(-) create mode 100644 .sampo/changesets/ai-posthog-options.md diff --git a/.sampo/changesets/ai-posthog-options.md b/.sampo/changesets/ai-posthog-options.md new file mode 100644 index 000000000..6c72874be --- /dev/null +++ b/.sampo/changesets/ai-posthog-options.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: minor +--- + +AI integrations take capture options. Every wrapper method that takes `posthog_properties` also takes `posthog_options` (OpenAI, Anthropic, Gemini, sync and async, and the Claude Agent SDK `query()` and `PostHogClaudeSDKClient`), and the Gemini clients take it as a default for every call. LangChain's `CallbackHandler` and `PostHogMiddleware`, and `instrument()` and the tracing processors for OpenAI Agents and the Claude Agent SDK, take `options=`. LangChain also reads `posthog_options` from run metadata. These options win over context options and `super_options`. An event without a distinct ID still always sends `process_person_profile: False`, and a value that is not a dict is logged and ignored. diff --git a/docs/migration-7.x-to-8.0.md b/docs/migration-7.x-to-8.0.md index b5bd22e28..6a0775daa 100644 --- a/docs/migration-7.x-to-8.0.md +++ b/docs/migration-7.x-to-8.0.md @@ -202,7 +202,7 @@ Capture v1 sends processing options in an `options` object, next to `properties` posthog.capture("signed_up", distinct_id="user-1", options={"cookieless_mode": True}) ``` - The MCP capture methods take `event_options` instead (see [MCP analytics](#mcp-analytics)). + The MCP capture methods take `event_options` instead (see [MCP analytics](#mcp-analytics)), and the AI integrations take `posthog_options` (see [AI capture](#ai-capture)). - `super_options`, a new `Client`, `AsyncPosthog` and module setting, sets options on every event, like `super_properties`. - `set_context_option(key, value)` sets an option for the current context, like `tag()`. `get_context_options()` returns the options of the current context. Both exist on `Client` and as module functions. `AsyncPosthog` has no context methods, like it has no `tag()`, so call the module functions. They apply to every client in the context. @@ -263,9 +263,31 @@ These changes follow from this order: - `enable_full_ai_capture` now controls only content: string truncation and media redaction. It no longer chooses the endpoint. `_use_ai_lane` and `_enable_multimodal_capture` still work as aliases. - The AI integrations call your client's `capture_ai`, and never `capture`. A custom client object must implement `capture_ai` and accept its `options` keyword argument. If the client has no `capture_ai`, the wrapper, callback handler or tracing processor logs one error when you create it and captures no AI events; provider calls still work. Before, such a client got `capture` calls. - Tests that pass a `Mock` client to an AI integration must assert on `mock.capture_ai`, not `mock.capture`. -- When an AI integration or MCP falls back to a trace, run or session ID, it turns person processing off with a per-event option. This is the only option the integrations set. It wins over `super_options` and context options. `before_send` can still change it. +- When an AI integration or MCP falls back to a trace, run or session ID, it turns person processing off with a per-event option. This is the only option the integrations set on their own. It wins over your `posthog_options`, `options`, `super_options` and context options. `before_send` can still change it. - An empty or whitespace-only distinct ID passed to an AI integration, such as `posthog_distinct_id=""`, counts as missing, so the integration falls back the same way and turns person processing off. In 7.x, an empty ID gave non-streaming wrapper calls a random personless ID. Streaming calls, embeddings and LangChain used the trace or run ID with person processing on. OpenAI Agents already treated an empty ID as missing. Every integration sent a whitespace-only ID as given, with person processing on. -- The AI integrations have no `options` argument. To set options on their events, use `set_context_option` in a context around the call, or `super_options`. `before_send` can also change an event's `options`. +- The AI integrations take capture options: + - Every wrapper method that takes `posthog_properties` also takes `posthog_options`, for the events of that call. This covers OpenAI, Anthropic and Gemini, sync and async, and the Claude Agent SDK `query()` and `PostHogClaudeSDKClient`. The name keeps it apart from the Claude Agent SDK's own `options`. + - The Gemini clients take `posthog_options` as a default for every call. A call's `posthog_options` win key by key. + - LangChain's `CallbackHandler` and `PostHogMiddleware`, OpenAI Agents' `instrument()` and `PostHogTracingProcessor`, and the Claude Agent SDK's `instrument()` and `PostHogClaudeAgentProcessor` take `options=` for every event. LangChain also reads `posthog_options` from run metadata, like `posthog_properties`. Like properties, the handler's or processor's options win over a run's or a query's. + - These are the event's own options, so they win over context options and `super_options`, which still fill the keys they leave unset. `before_send` can still change them. + - A value that is not a dict is logged as a warning and ignored. The provider call still runs, and the provider never receives `posthog_options`. + + ```python + from posthog.ai.langchain import CallbackHandler + from posthog.ai.openai import OpenAI + + client = OpenAI(posthog_client=posthog_client) + client.chat.completions.create( + model="gpt-5-mini", + messages=[{"role": "user", "content": "Hello"}], + posthog_distinct_id="user-1", + posthog_options={"cookieless_mode": True}, + ) + + handler = CallbackHandler( + posthog_client, distinct_id="user-1", options={"cookieless_mode": True} + ) + ``` - New `Client` and `AsyncPosthog` arguments for the AI lane: - `capture_ai_compression`: default none. `POSTHOG_CAPTURE_COMPRESSION` does not apply to it. - `capture_ai_max_queue_size`: default 1000 diff --git a/posthog/ai/anthropic/anthropic.py b/posthog/ai/anthropic/anthropic.py index e0b80ffe3..8bfc53438 100644 --- a/posthog/ai/anthropic/anthropic.py +++ b/posthog/ai/anthropic/anthropic.py @@ -60,6 +60,7 @@ def create( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -71,6 +72,10 @@ def create( posthog_properties: Optional dictionary of extra properties to include in the event posthog_privacy_mode: Whether to redact sensitive information in tracking posthog_groups: Optional group analytics properties + posthog_options: Optional capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to Anthropic's messages.create """ @@ -84,6 +89,7 @@ def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -97,6 +103,7 @@ def create( posthog_groups, self._client.base_url, super().create, + posthog_options=posthog_options, **kwargs, ) @@ -107,6 +114,7 @@ def stream( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -118,6 +126,10 @@ def stream( posthog_properties: Additional properties to include with the usage event. posthog_privacy_mode: Whether to redact captured input and output. posthog_groups: Optional PostHog groups to associate with the event. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to Anthropic's ``messages.create`` API. Returns: @@ -147,6 +159,7 @@ def tracked_request(): posthog_groups, kwargs, start_time, + options=posthog_options, ) setattr(manager, request_attribute, tracked_request) @@ -159,6 +172,7 @@ def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -172,6 +186,7 @@ def _create_streaming( posthog_groups, kwargs, start_time, + options=posthog_options, ) def _track_streaming_response( @@ -184,6 +199,7 @@ def _track_streaming_response( posthog_groups: Optional[Dict[str, Any]], kwargs: Dict[str, Any], start_time: float, + options: Optional[Dict[str, Any]] = None, ): accumulator = _AnthropicStreamAccumulator() @@ -213,6 +229,7 @@ def generator(): accumulator.accumulated_content, stop_reason=accumulator.stop_reason, error=stream_error, + options=options, ) return _StreamWrapper(generator(), stream=response) @@ -231,6 +248,7 @@ def _capture_streaming_event( accumulated_content: str, stop_reason: Optional[str] = None, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.types import StreamingEventData from posthog.ai.anthropic.anthropic_converter import ( @@ -259,6 +277,7 @@ def _capture_streaming_event( groups=posthog_groups, stop_reason=stop_reason, error=error, + options=options, ) # Use the common capture function diff --git a/posthog/ai/anthropic/anthropic_async.py b/posthog/ai/anthropic/anthropic_async.py index ac9be3741..6e63852b0 100644 --- a/posthog/ai/anthropic/anthropic_async.py +++ b/posthog/ai/anthropic/anthropic_async.py @@ -60,6 +60,7 @@ async def create( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -71,6 +72,10 @@ async def create( posthog_properties: Optional dictionary of extra properties to include in the event posthog_privacy_mode: Whether to redact sensitive information in tracking posthog_groups: Optional group analytics properties + posthog_options: Optional capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to Anthropic's messages.create """ @@ -84,6 +89,7 @@ async def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -97,6 +103,7 @@ async def create( posthog_groups, self._client.base_url, super().create, + posthog_options=posthog_options, **kwargs, ) @@ -107,6 +114,7 @@ def stream( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -118,6 +126,10 @@ def stream( posthog_properties: Additional properties to include with the usage event. posthog_privacy_mode: Whether to redact captured input and output. posthog_groups: Optional PostHog groups to associate with the event. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to Anthropic's async ``messages.create`` API. Returns: @@ -147,6 +159,7 @@ async def tracked_request(): posthog_groups, kwargs, start_time, + options=posthog_options, ) setattr(manager, request_attribute, tracked_request()) @@ -159,6 +172,7 @@ async def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -172,6 +186,7 @@ async def _create_streaming( posthog_groups, kwargs, start_time, + options=posthog_options, ) def _track_streaming_response( @@ -184,6 +199,7 @@ def _track_streaming_response( posthog_groups: Optional[Dict[str, Any]], kwargs: Dict[str, Any], start_time: float, + options: Optional[Dict[str, Any]] = None, ): accumulator = _AnthropicStreamAccumulator() @@ -213,6 +229,7 @@ async def generator(): accumulator.accumulated_content, stop_reason=accumulator.stop_reason, error=stream_error, + options=options, ) return AsyncStreamWrapper(generator(), stream=response) @@ -231,6 +248,7 @@ async def _capture_streaming_event( accumulated_content: str, stop_reason: Optional[str] = None, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.types import StreamingEventData from posthog.ai.anthropic.anthropic_converter import ( @@ -259,6 +277,7 @@ async def _capture_streaming_event( groups=posthog_groups, stop_reason=stop_reason, error=error, + options=options, ) # Use the common capture function diff --git a/posthog/ai/claude_agent_sdk/__init__.py b/posthog/ai/claude_agent_sdk/__init__.py index 170a08c01..4e492d313 100644 --- a/posthog/ai/claude_agent_sdk/__init__.py +++ b/posthog/ai/claude_agent_sdk/__init__.py @@ -34,6 +34,7 @@ def instrument( privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ) -> PostHogClaudeAgentProcessor: """ Create a PostHog-instrumented query wrapper for the Claude Agent SDK. @@ -49,6 +50,10 @@ def instrument( privacy_mode: If True, redacts sensitive information in tracking. groups: Optional PostHog groups to associate with events. properties: Optional additional properties to include with all events. + options: Optional capture options for all events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. Returns: PostHogClaudeAgentProcessor: A processor whose .query() method wraps claude_agent_sdk.query(). @@ -69,6 +74,7 @@ def instrument( privacy_mode=privacy_mode, groups=groups, properties=properties, + options=options, ) @@ -85,6 +91,7 @@ async def query( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, ): """ Drop-in replacement for claude_agent_sdk.query() with PostHog instrumentation. @@ -102,6 +109,11 @@ async def query( posthog_properties: Extra properties to include with all events. posthog_privacy_mode: If True, redacts sensitive content. posthog_groups: Optional PostHog groups. + posthog_options: Capture options for all events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. Named so it does not clash with + ``options``, the Claude Agent SDK options. Example: ```python @@ -147,5 +159,6 @@ async def query( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, ): yield message diff --git a/posthog/ai/claude_agent_sdk/client.py b/posthog/ai/claude_agent_sdk/client.py index 2766ec925..79b51df3b 100644 --- a/posthog/ai/claude_agent_sdk/client.py +++ b/posthog/ai/claude_agent_sdk/client.py @@ -62,6 +62,7 @@ def __init__( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, ): """ Initialize a stateful Claude Agent SDK client with PostHog instrumentation. @@ -78,6 +79,10 @@ def __init__( posthog_properties: Additional properties included on emitted AI events. posthog_privacy_mode: Whether to redact captured inputs, outputs, and tool data. posthog_groups: Optional PostHog groups to associate with emitted events. + posthog_options: Capture options for emitted AI events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. """ from dataclasses import replace as dc_replace @@ -94,6 +99,7 @@ def __init__( privacy_mode=posthog_privacy_mode, groups=posthog_groups, properties=posthog_properties or {}, + options=posthog_options, ) self._trace_id = posthog_trace_id or str(uuid.uuid4()) self._distinct_id = posthog_distinct_id diff --git a/posthog/ai/claude_agent_sdk/processor.py b/posthog/ai/claude_agent_sdk/processor.py index 8648e9e34..04bf4da16 100644 --- a/posthog/ai/claude_agent_sdk/processor.py +++ b/posthog/ai/claude_agent_sdk/processor.py @@ -30,6 +30,7 @@ ) from posthog.ai.media import ensure_serializable as _ensure_serializable from posthog.ai.utils import ( + _ai_event_options, _capture_processor_event, _resolve_ai_client, finalize_ai_content, @@ -172,6 +173,7 @@ def __init__( privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ): """ Initialize a Claude Agent SDK query processor. @@ -183,12 +185,18 @@ def __init__( privacy_mode: Whether to redact captured inputs, outputs, and tool data. groups: Optional PostHog groups to associate with emitted events. properties: Additional properties included on emitted AI events. + options: Capture options for emitted AI events, such as + ``{"cookieless_mode": True}``. They win over a query's + ``posthog_options``, context options and ``super_options``. An + event without a distinct ID always sends + ``process_person_profile: False``. """ self._client = _resolve_ai_client(client) self._distinct_id = distinct_id self._privacy_mode = privacy_mode self._groups = groups or {} self._properties = properties or {} + self._options = _ai_event_options(options) def _get_distinct_id( self, result: Optional["ResultMessage"] = None @@ -210,6 +218,7 @@ def _capture_event( distinct_id: Optional[str] = None, groups: Optional[Dict[str, Any]] = None, personless: bool = False, + options: Optional[Dict[str, Any]] = None, ) -> None: _capture_processor_event( self._client, @@ -219,6 +228,8 @@ def _capture_event( distinct_id=distinct_id, groups=groups if groups is not None else self._groups, personless=personless, + options=options, + default_options=self._options, ) async def query( @@ -234,6 +245,7 @@ async def query( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, ): """Drop-in replacement for claude_agent_sdk.query() with PostHog instrumentation. @@ -249,6 +261,9 @@ async def query( posthog_properties: Extra properties merged into all events for this query posthog_privacy_mode: Override privacy mode for this query posthog_groups: Override groups for this query + posthog_options: Capture options for all events of this query, such + as ``{"cookieless_mode": True}``. Named so it does not clash with + ``options``, the Claude Agent SDK options. """ from dataclasses import replace @@ -256,6 +271,7 @@ async def query( distinct_id_override = posthog_distinct_id or self._distinct_id trace_id = posthog_trace_id or str(uuid.uuid4()) extra_props = posthog_properties or {} + extra_options = _ai_event_options(posthog_options) # Per-call privacy can enable redaction, but cannot disable the # processor-level setting. This preserves the existing precedence. privacy = self._privacy_mode or posthog_privacy_mode is True @@ -319,6 +335,7 @@ async def query( extra_props, privacy, groups, + extra_options=extra_options, ) # Promote: tool results from this turn become input for next turn current_input = next_input @@ -342,6 +359,7 @@ async def query( extra_props, privacy, groups, + extra_options=extra_options, ) output_content = format_assistant_blocks(message.content) if output_content: @@ -388,6 +406,7 @@ async def query( extra_props, privacy, groups, + extra_options=extra_options, ) self._emit_trace( @@ -398,6 +417,7 @@ async def query( extra_props, privacy, groups, + extra_options=extra_options, ) except Exception as e: @@ -416,6 +436,7 @@ def _emit_generation( extra_props: Dict[str, Any], privacy: bool, groups: Dict[str, Any], + extra_options: Optional[Dict[str, Any]] = None, ) -> None: resolved_id = self._resolve_distinct_id(distinct_id) latency = ( @@ -476,6 +497,7 @@ def _emit_generation( resolved_id or trace_id, groups, personless=resolved_id is None, + options=extra_options, ) def _emit_generation_from_result( @@ -490,6 +512,7 @@ def _emit_generation_from_result( extra_props: Dict[str, Any], privacy: bool, groups: Dict[str, Any], + extra_options: Optional[Dict[str, Any]] = None, ) -> None: """Fallback: emit a single generation from ResultMessage aggregate data.""" resolved_id = self._resolve_distinct_id(distinct_id) @@ -550,6 +573,7 @@ def _emit_generation_from_result( resolved_id or trace_id, groups, personless=resolved_id is None, + options=extra_options, ) def _emit_tool_span( @@ -561,6 +585,7 @@ def _emit_tool_span( extra_props: Dict[str, Any], privacy: bool, groups: Dict[str, Any], + extra_options: Optional[Dict[str, Any]] = None, ) -> None: resolved_id = self._resolve_distinct_id(distinct_id) @@ -586,6 +611,7 @@ def _emit_tool_span( resolved_id or trace_id, groups, personless=resolved_id is None, + options=extra_options, ) def _emit_trace( @@ -597,6 +623,7 @@ def _emit_trace( extra_props: Dict[str, Any], privacy: bool, groups: Dict[str, Any], + extra_options: Optional[Dict[str, Any]] = None, ) -> None: resolved_id = self._resolve_distinct_id(distinct_id, result) latency = ( @@ -624,6 +651,7 @@ def _emit_trace( resolved_id or trace_id, groups, personless=resolved_id is None, + options=extra_options, ) # Flush to ensure events are sent before process exits diff --git a/posthog/ai/gemini/_shared.py b/posthog/ai/gemini/_shared.py index 998caf774..92fc38c6d 100644 --- a/posthog/ai/gemini/_shared.py +++ b/posthog/ai/gemini/_shared.py @@ -13,6 +13,7 @@ from ..types import StreamingEventData, TokenUsage from ..utils import ( _user_distinct_id, + _ai_event_options, _capture_ai_event, _resolve_ai_client, capture_streaming_event, @@ -130,6 +131,7 @@ def _initialize_policy( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, ) -> None: self._ph_client = _resolve_ai_client(posthog_client) @@ -137,6 +139,7 @@ def _initialize_policy( self._default_properties = posthog_properties or {} self._default_privacy_mode = posthog_privacy_mode self._default_groups = posthog_groups + self._default_options = _ai_event_options(posthog_options) # Every surface of one PostHog client (sync models, aio models, files) # shares a single provider client rather than opening its own. @@ -180,6 +183,12 @@ def _merge_posthog_params( trace_id = call_trace_id if call_trace_id is not None else str(uuid.uuid4()) return distinct_id, trace_id, properties, privacy_mode, groups + def _merge_posthog_options( + self, call_options: Optional[Dict[str, Any]] + ) -> Dict[str, Any]: + """Merge call-level capture options over the client defaults, key by key.""" + return {**self._default_options, **_ai_event_options(call_options)} + def _capture_streaming_event( self, model: str, @@ -195,6 +204,7 @@ def _capture_streaming_event( output: Any, stop_reason: Optional[str] = None, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ) -> None: formatted_input = merge_system_prompt( {"contents": contents, **kwargs}, "gemini" @@ -215,6 +225,7 @@ def _capture_streaming_event( groups=groups, stop_reason=stop_reason, error=error, + options=options, ) capture_streaming_event(self._ph_client, event_data) @@ -231,6 +242,7 @@ def _capture_embedding_outcome( response: Any, error: Optional[Exception], latency: float, + options: Optional[Dict[str, Any]] = None, ) -> None: input_tokens = ( extract_gemini_embedding_token_count(response) if response else None @@ -266,4 +278,5 @@ def _capture_embedding_outcome( properties=event_properties, groups=groups, personless=_user_distinct_id(distinct_id) is None, + options=options, ) diff --git a/posthog/ai/gemini/gemini.py b/posthog/ai/gemini/gemini.py index 18a33f171..9ae6be168 100644 --- a/posthog/ai/gemini/gemini.py +++ b/posthog/ai/gemini/gemini.py @@ -74,6 +74,7 @@ def __init__( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs, ): """ @@ -90,6 +91,8 @@ def __init__( posthog_properties: Default properties for all calls (can be overridden per call) posthog_privacy_mode: Default privacy mode for all calls (a call can enable it, not disable it) posthog_groups: Default groups for all calls (can be overridden per call) + posthog_options: Default capture options for all calls, such as + ``{"cookieless_mode": True}`` (can be overridden per call) **kwargs: Additional arguments (for future compatibility) """ @@ -114,6 +117,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, **kwargs, ) self.files = self._provider_client.files @@ -125,6 +129,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, **kwargs, ), files=self._provider_client.aio.files, @@ -153,6 +158,7 @@ def __init__( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs, ): """ @@ -171,6 +177,8 @@ def __init__( posthog_groups: Default groups for all calls provider_client: An already-built genai.Client to reuse instead of constructing one from the connection arguments above + posthog_options: Default capture options for all calls, such as + ``{"cookieless_mode": True}`` (can be overridden per call) **kwargs: Additional arguments (for future compatibility) """ @@ -187,6 +195,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, provider_client=provider_client, ) @@ -199,6 +208,7 @@ def generate_content( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -215,6 +225,10 @@ def generate_content( posthog_properties: Extra properties to include in the event (merged with client defaults) posthog_privacy_mode: Whether to redact sensitive information (cannot disable a client default of True) posthog_groups: Group analytics properties (overrides client default) + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's generate_content """ @@ -228,6 +242,7 @@ def generate_content( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) kwargs_with_contents = {"model": model, "contents": contents, **kwargs} @@ -241,6 +256,7 @@ def generate_content( groups, self._base_url, self._client.models.generate_content, + posthog_options=options, **kwargs_with_contents, ) @@ -253,6 +269,7 @@ def _generate_content_streaming( properties: Optional[Dict[str, Any]], privacy_mode: bool, groups: Optional[Dict[str, Any]], + options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -315,6 +332,7 @@ def generator(): accumulated_content, stop_reason=stop_reason, error=stream_error, + options=options, ) return generator() @@ -328,6 +346,7 @@ def generate_content_stream( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -342,6 +361,10 @@ def generate_content_stream( posthog_privacy_mode: Whether to redact captured input and output, overriding the client default. posthog_groups: Optional PostHog groups, overriding the client default. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's ``generate_content_stream`` API. Returns: @@ -357,6 +380,7 @@ def generate_content_stream( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) return self._generate_content_streaming( model, @@ -366,6 +390,7 @@ def generate_content_stream( properties, privacy_mode, groups, + options=options, **kwargs, ) @@ -378,6 +403,7 @@ def embed_content( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -391,6 +417,10 @@ def embed_content( posthog_properties: Extra properties to include in the event (merged with client defaults) posthog_privacy_mode: Whether to redact sensitive information (cannot disable a client default of True) posthog_groups: Group analytics properties (overrides client default) + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's embed_content (e.g., config) """ distinct_id, trace_id, properties, privacy_mode, groups = ( @@ -402,6 +432,7 @@ def embed_content( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) start_time = time.time() response = None @@ -422,6 +453,7 @@ def embed_content( properties=properties, privacy_mode=privacy_mode, groups=groups, + options=options, response=response, error=error, latency=time.time() - start_time, diff --git a/posthog/ai/gemini/gemini_async.py b/posthog/ai/gemini/gemini_async.py index 2b8b49e4a..0a5566d98 100644 --- a/posthog/ai/gemini/gemini_async.py +++ b/posthog/ai/gemini/gemini_async.py @@ -69,6 +69,7 @@ def __init__( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs, ): """ @@ -85,6 +86,8 @@ def __init__( posthog_properties: Default properties for all calls (can be overridden per call) posthog_privacy_mode: Default privacy mode for all calls (a call can enable it, not disable it) posthog_groups: Default groups for all calls (can be overridden per call) + posthog_options: Default capture options for all calls, such as + ``{"cookieless_mode": True}`` (can be overridden per call) **kwargs: Additional arguments (for future compatibility) """ @@ -109,6 +112,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, **kwargs, ) self.files = self._provider_client.aio.files @@ -137,6 +141,7 @@ def __init__( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs, ): """ @@ -155,6 +160,8 @@ def __init__( posthog_groups: Default groups for all calls provider_client: An already-built genai.Client to reuse instead of constructing one from the connection arguments above + posthog_options: Default capture options for all calls, such as + ``{"cookieless_mode": True}`` (can be overridden per call) **kwargs: Additional arguments (for future compatibility) """ @@ -171,6 +178,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, provider_client=provider_client, ) @@ -183,6 +191,7 @@ async def generate_content( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -199,6 +208,10 @@ async def generate_content( posthog_properties: Extra properties to include in the event (merged with client defaults) posthog_privacy_mode: Whether to redact sensitive information (cannot disable a client default of True) posthog_groups: Group analytics properties (overrides client default) + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's generate_content """ @@ -212,6 +225,7 @@ async def generate_content( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) kwargs_with_contents = {"model": model, "contents": contents, **kwargs} @@ -225,6 +239,7 @@ async def generate_content( groups, self._base_url, self._client.aio.models.generate_content, + posthog_options=options, **kwargs_with_contents, ) @@ -237,6 +252,7 @@ async def _generate_content_streaming( properties: Optional[Dict[str, Any]], privacy_mode: bool, groups: Optional[Dict[str, Any]], + options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -302,6 +318,7 @@ async def async_generator(): accumulated_content, stop_reason=stop_reason, error=stream_error, + options=options, ) return AsyncStreamWrapper(async_generator(), stream=response) @@ -315,6 +332,7 @@ async def generate_content_stream( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -329,6 +347,10 @@ async def generate_content_stream( posthog_privacy_mode: Whether to redact captured input and output, overriding the client default. posthog_groups: Optional PostHog groups, overriding the client default. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's async ``generate_content_stream`` API. Returns: @@ -344,6 +366,7 @@ async def generate_content_stream( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) return await self._generate_content_streaming( model, @@ -353,6 +376,7 @@ async def generate_content_stream( properties, privacy_mode, groups, + options=options, **kwargs, ) @@ -365,6 +389,7 @@ async def embed_content( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -378,6 +403,10 @@ async def embed_content( posthog_properties: Extra properties to include in the event (merged with client defaults) posthog_privacy_mode: Whether to redact sensitive information (cannot disable a client default of True) posthog_groups: Group analytics properties (overrides client default) + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's embed_content (e.g., config) """ distinct_id, trace_id, properties, privacy_mode, groups = ( @@ -389,6 +418,7 @@ async def embed_content( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) start_time = time.time() response = None @@ -409,6 +439,7 @@ async def embed_content( properties=properties, privacy_mode=privacy_mode, groups=groups, + options=options, response=response, error=error, latency=time.time() - start_time, diff --git a/posthog/ai/langchain/callbacks.py b/posthog/ai/langchain/callbacks.py index e6c959b9b..3f99cdbb6 100644 --- a/posthog/ai/langchain/callbacks.py +++ b/posthog/ai/langchain/callbacks.py @@ -43,6 +43,7 @@ from posthog.ai.gateway import warn_if_posthog_ai_gateway from posthog.ai.utils import ( + _ai_event_options, _capture_ai_event, _extract_cache_creation_ttl_breakdown, _resolve_ai_client, @@ -92,6 +93,8 @@ class GenerationMetadata(SpanMetadata): """Tools provided to the model.""" posthog_properties: Optional[Dict[str, Any]] = None """PostHog properties of the run.""" + posthog_options: Optional[Dict[str, Any]] = None + """PostHog capture options of the run.""" RunMetadata = Union[SpanMetadata, GenerationMetadata] @@ -121,6 +124,9 @@ class CallbackHandler(BaseCallbackHandler): _properties: Optional[Dict[str, Any]] """Global properties to be sent with every event.""" + _options: Dict[str, Any] + """Global capture options to be sent with every event.""" + _runs: RunMetadataStorage """Mapping of run IDs to run metadata as run metadata is only available on the start of generation.""" @@ -139,6 +145,7 @@ def __init__( properties: Optional[Dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ): """ Args: @@ -148,6 +155,11 @@ def __init__( properties: Optional additional metadata to use for the trace. privacy_mode: Whether to redact the input and output of the trace. groups: Optional additional PostHog groups to use for the trace. + options: Optional capture options for every event of the trace, such + as ``{"cookieless_mode": True}``. They win over a run's + ``posthog_options`` metadata, context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. """ self._ph_client = _resolve_ai_client(client) self._distinct_id = distinct_id @@ -155,6 +167,7 @@ def __init__( self._properties = properties or {} self._privacy_mode = privacy_mode self._groups = groups or {} + self._options = _ai_event_options(options) self._runs = {} self._parent_tree = {} @@ -479,6 +492,7 @@ def _set_llm_metadata( generation.provider = provider generation.posthog_properties = metadata.get("posthog_properties") + generation.posthog_options = metadata.get("posthog_options") try: base_url = serialized["kwargs"]["openai_api_base"] if base_url is not None: @@ -586,6 +600,7 @@ def _capture_trace_or_span( properties=event_properties, groups=self._groups, personless=_user_distinct_id(self._distinct_id) is None, + options=self._options, ) def _capture_exception_and_update_properties( @@ -754,6 +769,8 @@ def _capture_generation( properties=event_properties, groups=self._groups, personless=_user_distinct_id(self._distinct_id) is None, + # The handler's options win over the run's, like its properties. + options={**_ai_event_options(run.posthog_options), **self._options}, ) def _log_debug_event( diff --git a/posthog/ai/langchain/middleware.py b/posthog/ai/langchain/middleware.py index 8cf282a87..2d24e94d7 100644 --- a/posthog/ai/langchain/middleware.py +++ b/posthog/ai/langchain/middleware.py @@ -59,7 +59,14 @@ def __init__( properties: Optional[dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[dict[str, Any]] = None, + options: Optional[dict[str, Any]] = None, ) -> None: + """ + Args: + options: Optional capture options for every event, such as + ``{"cookieless_mode": True}``. The other arguments are the same + as :class:`CallbackHandler`'s. + """ self._callback = CallbackHandler( client, distinct_id=distinct_id, @@ -67,6 +74,7 @@ def __init__( properties=properties, privacy_mode=privacy_mode, groups=groups, + options=options, ) def before_agent( diff --git a/posthog/ai/openai/_embeddings.py b/posthog/ai/openai/_embeddings.py index 50edf2406..70a47037a 100644 --- a/posthog/ai/openai/_embeddings.py +++ b/posthog/ai/openai/_embeddings.py @@ -23,6 +23,7 @@ def _capture_embedding_event( privacy_mode: bool, groups: Optional[Dict[str, Any]], error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ) -> None: """Build and capture telemetry shared by sync and async embedding wrappers.""" usage = getattr(response, "usage", None) @@ -62,4 +63,5 @@ def _capture_embedding_event( properties=event_properties, groups=groups, personless=_user_distinct_id(distinct_id) is None, + options=options, ) diff --git a/posthog/ai/openai/_streaming.py b/posthog/ai/openai/_streaming.py index 3a7d059b4..c8b18baf2 100644 --- a/posthog/ai/openai/_streaming.py +++ b/posthog/ai/openai/_streaming.py @@ -147,6 +147,7 @@ def _build_streaming_event_data( stop_reason: Optional[str], service_tier: Optional[str] = None, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ) -> StreamingEventData: """Build the fields shared by both OpenAI streaming endpoint events.""" @@ -167,4 +168,5 @@ def _build_streaming_event_data( stop_reason=stop_reason, service_tier=service_tier, error=error, + options=options, ) diff --git a/posthog/ai/openai/openai.py b/posthog/ai/openai/openai.py index f1e0eafba..420a0ed55 100644 --- a/posthog/ai/openai/openai.py +++ b/posthog/ai/openai/openai.py @@ -78,6 +78,7 @@ def _parse_and_track( posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): return call_llm_and_track_usage( @@ -90,6 +91,7 @@ def _parse_and_track( posthog_groups, wrapper._client.base_url, wrapper._original.parse, + posthog_options=posthog_options, **kwargs, ) @@ -105,6 +107,7 @@ def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -121,6 +124,10 @@ def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's ``responses.create`` API. Returns: @@ -140,6 +147,7 @@ def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -153,6 +161,7 @@ def create( posthog_groups, self._client.base_url, self._original.create, + posthog_options=posthog_options, **kwargs, ) @@ -163,6 +172,7 @@ def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -189,6 +199,7 @@ def generator(): state, time.time() - start_time, error=stream_error, + options=posthog_options, ) return _StreamWrapper(generator(), stream=response) @@ -204,6 +215,7 @@ def _capture_streaming_event( state: _ResponsesStreamState, latency: float, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.utils import capture_streaming_event @@ -223,6 +235,7 @@ def _capture_streaming_event( stop_reason=state.stop_reason, service_tier=state.service_tier, error=error, + options=options, ) capture_streaming_event(self._client._ph_client, event_data) @@ -234,6 +247,7 @@ def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -250,6 +264,10 @@ def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Any additional parameters for the OpenAI Responses Parse API. Returns: @@ -263,6 +281,7 @@ def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) @@ -287,6 +306,7 @@ def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -303,6 +323,10 @@ def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's ``chat.completions.parse`` API. Returns: @@ -316,6 +340,7 @@ def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) @@ -327,6 +352,7 @@ def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -343,6 +369,10 @@ def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's ``chat.completions.create`` API. Returns: @@ -362,6 +392,7 @@ def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -375,6 +406,7 @@ def create( posthog_groups, self._client.base_url, self._original.create, + posthog_options=posthog_options, **kwargs, ) @@ -385,6 +417,7 @@ def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -417,6 +450,7 @@ def generator(): state, time.time() - start_time, error=stream_error, + options=posthog_options, ) return _StreamWrapper(generator(), stream=response) @@ -432,6 +466,7 @@ def _capture_streaming_event( state: _ChatCompletionsStreamState, latency: float, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.utils import capture_streaming_event @@ -451,6 +486,7 @@ def _capture_streaming_event( stop_reason=state.stop_reason, service_tier=state.service_tier, error=error, + options=options, ) capture_streaming_event(self._client._ph_client, event_data) @@ -466,6 +502,7 @@ def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -482,6 +519,10 @@ def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Any additional parameters for the OpenAI Embeddings API. Returns: @@ -511,6 +552,7 @@ def create( privacy_mode=posthog_privacy_mode, groups=posthog_groups, error=exc, + options=posthog_options, ) raise end_time = time.time() @@ -526,6 +568,7 @@ def create( properties=posthog_properties, privacy_mode=posthog_privacy_mode, groups=posthog_groups, + options=posthog_options, ) return response @@ -559,6 +602,7 @@ def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -575,6 +619,10 @@ def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's beta ``chat.completions.parse`` API. Returns: @@ -588,6 +636,7 @@ def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) diff --git a/posthog/ai/openai/openai_async.py b/posthog/ai/openai/openai_async.py index 389c6e043..1f3fa4ca5 100644 --- a/posthog/ai/openai/openai_async.py +++ b/posthog/ai/openai/openai_async.py @@ -79,6 +79,7 @@ async def _parse_and_track( posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): return await call_llm_and_track_usage_async( @@ -91,6 +92,7 @@ async def _parse_and_track( posthog_groups, wrapper._client.base_url, wrapper._original.parse, + posthog_options=posthog_options, **kwargs, ) @@ -106,6 +108,7 @@ async def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -122,6 +125,10 @@ async def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's async ``responses.create`` API. Returns: @@ -141,6 +148,7 @@ async def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -154,6 +162,7 @@ async def create( posthog_groups, self._client.base_url, self._original.create, + posthog_options=posthog_options, **kwargs, ) @@ -164,6 +173,7 @@ async def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -190,6 +200,7 @@ async def async_generator(): state, time.time() - start_time, error=stream_error, + options=posthog_options, ) return AsyncStreamWrapper(async_generator(), stream=response) @@ -205,6 +216,7 @@ async def _capture_streaming_event( state: _ResponsesStreamState, latency: float, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.utils import capture_streaming_event @@ -224,6 +236,7 @@ async def _capture_streaming_event( stop_reason=state.stop_reason, service_tier=state.service_tier, error=error, + options=options, ) capture_streaming_event(self._client._ph_client, event_data) @@ -235,6 +248,7 @@ async def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -251,6 +265,10 @@ async def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Any additional parameters for the OpenAI Responses Parse API. Returns: @@ -264,6 +282,7 @@ async def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) @@ -288,6 +307,7 @@ async def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -304,6 +324,10 @@ async def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's async ``chat.completions.parse`` API. Returns: @@ -317,6 +341,7 @@ async def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) @@ -328,6 +353,7 @@ async def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -344,6 +370,10 @@ async def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's async ``chat.completions.create`` API. Returns: @@ -364,6 +394,7 @@ async def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -377,6 +408,7 @@ async def create( posthog_groups, self._client.base_url, self._original.create, + posthog_options=posthog_options, **kwargs, ) return response @@ -388,6 +420,7 @@ async def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -421,6 +454,7 @@ async def async_generator(): state, time.time() - start_time, error=stream_error, + options=posthog_options, ) return AsyncStreamWrapper(async_generator(), stream=response) @@ -436,6 +470,7 @@ async def _capture_streaming_event( state: _ChatCompletionsStreamState, latency: float, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.utils import capture_streaming_event @@ -455,6 +490,7 @@ async def _capture_streaming_event( stop_reason=state.stop_reason, service_tier=state.service_tier, error=error, + options=options, ) capture_streaming_event(self._client._ph_client, event_data) @@ -470,6 +506,7 @@ async def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -486,6 +523,10 @@ async def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Any additional parameters for the OpenAI Embeddings API. Returns: @@ -515,6 +556,7 @@ async def create( privacy_mode=posthog_privacy_mode, groups=posthog_groups, error=exc, + options=posthog_options, ) raise end_time = time.time() @@ -530,6 +572,7 @@ async def create( properties=posthog_properties, privacy_mode=posthog_privacy_mode, groups=posthog_groups, + options=posthog_options, ) return response @@ -563,6 +606,7 @@ async def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -579,6 +623,10 @@ async def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's async beta ``chat.completions.parse`` API. Returns: @@ -592,6 +640,7 @@ async def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) diff --git a/posthog/ai/openai_agents/__init__.py b/posthog/ai/openai_agents/__init__.py index 2e1611cc7..d440f33e8 100644 --- a/posthog/ai/openai_agents/__init__.py +++ b/posthog/ai/openai_agents/__init__.py @@ -25,6 +25,7 @@ def instrument( privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ) -> PostHogTracingProcessor: """ One-liner to instrument OpenAI Agents SDK with PostHog tracing. @@ -39,6 +40,10 @@ def instrument( privacy_mode: If True, redacts input/output content from events. groups: Optional PostHog groups to associate with events. properties: Optional additional properties to include with all events. + options: Optional capture options for all events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. Returns: PostHogTracingProcessor: The registered processor instance. @@ -71,6 +76,7 @@ def instrument( privacy_mode=privacy_mode, groups=groups, properties=properties, + options=options, ) add_trace_processor(processor) return processor diff --git a/posthog/ai/openai_agents/processor.py b/posthog/ai/openai_agents/processor.py index bd1427070..8b62285e4 100644 --- a/posthog/ai/openai_agents/processor.py +++ b/posthog/ai/openai_agents/processor.py @@ -22,6 +22,7 @@ from posthog.ai.media import ensure_serializable as _ensure_serializable from posthog.ai.sanitization import _full_ai_capture_enabled, _placeholder from posthog.ai.utils import ( + _ai_event_options, _user_distinct_id, _capture_processor_event, _resolve_ai_client, @@ -102,6 +103,7 @@ def __init__( privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ): """ Initialize the PostHog tracing processor. @@ -113,12 +115,17 @@ def __init__( privacy_mode: If True, redacts input/output content from events. groups: Optional PostHog groups to associate with all events. properties: Optional additional properties to include with all events. + options: Optional capture options for all events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. """ self._client = _resolve_ai_client(client) self._distinct_id = distinct_id self._privacy_mode = privacy_mode self._groups = groups or {} self._properties = properties or {} + self._options = _ai_event_options(options) # Track span start times for latency calculation self._span_start_times: Dict[str, float] = {} @@ -207,6 +214,7 @@ def _capture_event( or properties.get("$ai_trace_id"), groups=self._groups, personless=_user_distinct_id(distinct_id) is None, + default_options=self._options, ) def on_trace_start(self, trace: Trace) -> None: diff --git a/posthog/ai/types.py b/posthog/ai/types.py index 1fc5555fa..630141ef3 100644 --- a/posthog/ai/types.py +++ b/posthog/ai/types.py @@ -144,3 +144,4 @@ class StreamingEventData(TypedDict): stop_reason: Optional[str] service_tier: NotRequired[Optional[str]] error: NotRequired[Optional[BaseException]] # raised mid-stream, if any + options: NotRequired[Optional[Dict[str, Any]]] # the caller's posthog_options diff --git a/posthog/ai/utils.py b/posthog/ai/utils.py index ffda79b95..a832cd679 100644 --- a/posthog/ai/utils.py +++ b/posthog/ai/utils.py @@ -72,24 +72,37 @@ def _user_distinct_id(distinct_id: Any) -> Any: return distinct_id if _explicit_distinct_id(distinct_id) is not None else None +def _ai_event_options(value: Any) -> Dict[str, Any]: + """Return a copy of a caller's ``posthog_options``, or ``{}`` when it is not a dict.""" + if value is None: + return {} + if not isinstance(value, dict): + logging.getLogger("posthog").warning( + "posthog_options must be a dict, got %s. Sending the event without them.", + type(value).__name__, + ) + return {} + return dict(value) + + def _capture_ai_event(ph_client, event: str, *, personless: bool = False, **kwargs): """Capture a wrapper-emitted AI event with the PostHog AI library identity. - ``personless`` marks an event whose distinct ID is a fallback, such as a - trace ID, not a real user. + ``options`` are the caller's per-event options. ``personless`` marks an + event whose distinct ID is a fallback, such as a trace ID, not a real user. """ kwargs["properties"] = { **_AI_LIB_PROPERTIES, **(kwargs.get("properties") or {}), } + options = _ai_event_options(kwargs.pop("options", None)) if personless: - # A per-event option beats legacy properties and global or context - # options, because a person profile for a fallback ID is always wrong. - # before_send can still change it. - kwargs["options"] = { - **(kwargs.get("options") or {}), - "process_person_profile": False, - } + # Set last, so it beats the caller's options as well as legacy + # properties and global or context options: a person profile for a + # fallback ID is always wrong. before_send can still change it. + options["process_person_profile"] = False + if options: + kwargs["options"] = options return ph_client.capture_ai(event=event, **kwargs) @@ -133,8 +146,14 @@ def _capture_processor_event( distinct_id: Optional[str] = None, groups: Optional[Dict[str, Any]] = None, personless: bool = False, + options: Optional[Dict[str, Any]] = None, + default_options: Optional[Dict[str, Any]] = None, ) -> None: - """Apply the shared capture policy used by AI SDK processors.""" + """Apply the shared capture policy used by AI SDK processors. + + ``default_options`` win over ``options`` key by key, like + ``default_properties`` over ``properties``. + """ try: if not callable(getattr(ph_client, "capture_ai", None)): return @@ -146,6 +165,10 @@ def _capture_processor_event( properties={**properties, **(default_properties or {})}, groups=groups, personless=personless, + options={ + **_ai_event_options(options), + **_ai_event_options(default_options), + }, ) except Exception as exc: logging.getLogger("posthog").debug("Failed to capture PostHog event: %s", exc) @@ -520,11 +543,15 @@ def call_llm_and_track_usage( posthog_groups: Optional[Dict[str, Any]], base_url: str, call_method: Callable[..., Any], + *, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ) -> Any: """ Common usage-tracking logic for both sync and async calls. call_method: the llm call method (e.g. openai.chat.completions.create) + posthog_options: capture options for the event. They are not passed to + ``call_method``. """ start_time = time.time() response = None @@ -669,6 +696,7 @@ def call_llm_and_track_usage( properties=merged_properties, groups=posthog_groups, personless=not has_person_distinct_id, + options=posthog_options, ) if error: @@ -687,6 +715,8 @@ async def call_llm_and_track_usage_async( posthog_groups: Optional[Dict[str, Any]], base_url: str, call_async_method: Callable[..., Any], + *, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ) -> Any: start_time = time.time() @@ -839,6 +869,7 @@ async def call_llm_and_track_usage_async( properties=merged_properties, groups=posthog_groups, personless=not has_person_distinct_id, + options=posthog_options, ) if error: @@ -1260,4 +1291,5 @@ def capture_streaming_event( properties=event_properties, groups=event_data.get("groups"), personless=_user_distinct_id(event_data.get("distinct_id")) is None, + options=event_data.get("options"), ) diff --git a/posthog/test/ai/anthropic/test_anthropic.py b/posthog/test/ai/anthropic/test_anthropic.py index c11188a14..2b846cd3d 100644 --- a/posthog/test/ai/anthropic/test_anthropic.py +++ b/posthog/test/ai/anthropic/test_anthropic.py @@ -29,7 +29,12 @@ from anthropic.types.raw_message_delta_event import Delta from posthog.ai.anthropic import Anthropic, AnthropicBedrock, AsyncAnthropic - from posthog.test.ai.utils import RecordingAsyncStream + from posthog.test.ai.utils import ( + POSTHOG_OPTIONS_CASES, + RecordingAsyncStream, + assert_captured_options, + posthog_call_kwargs, + ) ANTHROPIC_AVAILABLE = True except ImportError: @@ -2409,3 +2414,93 @@ def test_multimodal_client_skips_media_redaction(mock_client, mock_anthropic_res assert mock_client.capture_ai.call_count == 1 props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input"][0]["content"][0]["source"]["data"] == image_data + + +_OPTIONS_CALL_KWARGS = { + "model": "claude-haiku-4-5", + "messages": [{"role": "user", "content": "Foo"}], + "max_tokens": 1, +} + + +async def _call_anthropic_with_options(kind, is_async, mock_client, posthog_kwargs): + """Run one wrapper call and return the arguments the provider received.""" + client_class = AsyncAnthropic if is_async else Anthropic + client = client_class(api_key="test-key", posthog_client=mock_client) + + if kind == "stream_manager": + # messages.stream() builds the request itself, so record the HTTP call. + if is_async: + client.post = AsyncMock( + return_value=RecordingAsyncStream(_anthropic_raw_stream_events()) + ) + manager = client.messages.stream(**_OPTIONS_CALL_KWARGS, **posthog_kwargs) + async with manager as stream: + _ = [chunk async for chunk in stream.text_stream] + else: + client.post = Mock( + return_value=RecordingStream(_anthropic_raw_stream_events()) + ) + with client.messages.stream( + **_OPTIONS_CALL_KWARGS, **posthog_kwargs + ) as stream: + list(stream.text_stream) + return client.post.call_args + + stream = kind == "create_stream" + provider_calls = [] + + def respond(kwargs): + provider_calls.append(kwargs) + if not stream: + return create_mock_response() + events = _anthropic_stream_events() + return RecordingAsyncStream(events) if is_async else RecordingStream(events) + + async def async_create(self, **kwargs): + return respond(kwargs) + + def sync_create(self, **kwargs): + return respond(kwargs) + + target = "AsyncMessages" if is_async else "Messages" + with patch( + f"anthropic.resources.messages.{target}.create", + new=async_create if is_async else sync_create, + ): + call_kwargs = {**_OPTIONS_CALL_KWARGS, "stream": stream, **posthog_kwargs} + result = client.messages.create(**call_kwargs) + if is_async: + result = await result + if stream: + if is_async: + _ = [event async for event in result] + else: + list(result) + assert len(provider_calls) == 1 + return provider_calls[0] + + +@pytest.mark.parametrize( + "case", POSTHOG_OPTIONS_CASES, ids=[case[0] for case in POSTHOG_OPTIONS_CASES] +) +@pytest.mark.parametrize("kind", ["create", "create_stream", "stream_manager"]) +@pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"]) +async def test_posthog_options_reach_capture_and_not_the_provider( + mock_client, caplog, is_async, kind, case +): + _, distinct_id, posthog_options, expected, warns = case + + with caplog.at_level("WARNING", logger="posthog"): + provider_call = await _call_anthropic_with_options( + kind, + is_async, + mock_client, + posthog_call_kwargs(distinct_id, posthog_options), + ) + + assert "posthog_" not in repr(provider_call) + assert mock_client.capture_ai.call_count == 1 + assert_captured_options( + mock_client.capture_ai.call_args.kwargs, expected, warns, caplog + ) diff --git a/posthog/test/ai/claude_agent_sdk/test_processor.py b/posthog/test/ai/claude_agent_sdk/test_processor.py index cfa673dfc..6aceb6ce8 100644 --- a/posthog/test/ai/claude_agent_sdk/test_processor.py +++ b/posthog/test/ai/claude_agent_sdk/test_processor.py @@ -8,6 +8,7 @@ import pytest +from posthog.test.ai.utils import POSTHOG_OPTIONS_CASES, assert_captured_options from posthog.version import VERSION try: @@ -971,3 +972,148 @@ async def test_non_config_errors_propagate(self): prompt="Hello", options=ClaudeAgentOptions() ): pass + + +def _streamed_messages(): + return [ + _make_message_start(), + _make_message_stop(), + _make_assistant_message(tool_uses=[{"id": "tu_1", "name": "Read"}]), + _make_result_message(), + ] + + +def _result_only_messages(): + return [_make_result_message()] + + +# id, messages, the events they emit +CLAUDE_MESSAGE_FLOWS = [ + ("streamed", _streamed_messages, ["$ai_generation", "$ai_span", "$ai_trace"]), + ("result_only", _result_only_messages, ["$ai_generation", "$ai_trace"]), +] + + +def _claude_query(entry_point, client, distinct_id, options): + if entry_point == "module_query": + return posthog_query( + prompt="Hi", + options=ClaudeAgentOptions(), + posthog_client=client, + posthog_distinct_id=distinct_id, + posthog_options=options, + ) + if entry_point == "processor_query": + proc = PostHogClaudeAgentProcessor(client=client, distinct_id=distinct_id) + return proc.query( + prompt="Hi", options=ClaudeAgentOptions(), posthog_options=options + ) + proc = instrument(client=client, distinct_id=distinct_id, options=options) + return proc.query(prompt="Hi", options=ClaudeAgentOptions()) + + +class TestPostHogOptions: + @pytest.mark.asyncio + @pytest.mark.parametrize( + "case", + POSTHOG_OPTIONS_CASES, + ids=[case[0] for case in POSTHOG_OPTIONS_CASES], + ) + @pytest.mark.parametrize( + "flow", CLAUDE_MESSAGE_FLOWS, ids=[flow[0] for flow in CLAUDE_MESSAGE_FLOWS] + ) + @pytest.mark.parametrize( + "entry_point", ["module_query", "processor_query", "instrument"] + ) + async def test_options_reach_every_event_and_not_the_sdk( + self, mock_client, caplog, entry_point, flow, case + ): + _, make_messages, expected_events = flow + _, distinct_id, options, expected, warns = case + sdk_calls = [] + + def fake_sdk_query(**kwargs): + sdk_calls.append(kwargs) + return _fake_query(make_messages()) + + with caplog.at_level(logging.WARNING, logger="posthog"): + with patch( + "posthog.ai.claude_agent_sdk.processor.original_query", + side_effect=fake_sdk_query, + ): + async for _ in _claude_query( + entry_point, mock_client, distinct_id, options + ): + pass + + assert [set(call) for call in sdk_calls] == [{"prompt", "options", "transport"}] + calls = mock_client.capture_ai.call_args_list + assert [call.kwargs["event"] for call in calls] == expected_events + for call in calls: + assert_captured_options(call.kwargs, expected, warns, caplog) + + @pytest.mark.asyncio + async def test_processor_options_win_over_query_options(self, mock_client): + proc = PostHogClaudeAgentProcessor( + client=mock_client, + distinct_id="user", + options={"cookieless_mode": True}, + ) + + with patch( + "posthog.ai.claude_agent_sdk.processor.original_query", + side_effect=lambda **kw: _fake_query(_streamed_messages()), + ): + async for _ in proc.query( + prompt="Hi", + options=ClaudeAgentOptions(), + posthog_options={ + "cookieless_mode": False, + "disable_skew_correction": True, + }, + ): + pass + + # Like properties, the processor's options win key by key. + for call in mock_client.capture_ai.call_args_list: + assert call.kwargs["options"] == { + "cookieless_mode": True, + "disable_skew_correction": True, + } + + @pytest.mark.asyncio + async def test_sdk_client_options_reach_every_event(self, mock_client): + from posthog.ai.claude_agent_sdk import PostHogClaudeSDKClient + + sdk_client = MagicMock() + + async def noop(*args, **kwargs): + return None + + sdk_client.connect = noop + sdk_client.query = noop + sdk_client.disconnect = noop + sdk_client.receive_response = lambda: _fake_query(_streamed_messages()) + + with patch( + "posthog.ai.claude_agent_sdk.client.ClaudeSDKClient", + return_value=sdk_client, + ): + async with PostHogClaudeSDKClient( + ClaudeAgentOptions(), + posthog_client=mock_client, + posthog_distinct_id="user", + posthog_options={"cookieless_mode": True}, + ) as client: + await client.query("Hi") + async for _ in client.receive_response(): + pass + + calls = mock_client.capture_ai.call_args_list + assert [call.kwargs["event"] for call in calls] == [ + "$ai_generation", + "$ai_span", + "$ai_trace", + ] + for call in calls: + assert call.kwargs["options"] == {"cookieless_mode": True} diff --git a/posthog/test/ai/gemini/test_gemini.py b/posthog/test/ai/gemini/test_gemini.py index 016571611..b8aab03ed 100644 --- a/posthog/test/ai/gemini/test_gemini.py +++ b/posthog/test/ai/gemini/test_gemini.py @@ -1,9 +1,17 @@ import json +import logging import os -from unittest.mock import MagicMock, patch +from unittest.mock import AsyncMock, MagicMock, patch import pytest +from posthog.test.ai.utils import ( + POSTHOG_OPTIONS_CASES, + RecordingAsyncStream, + assert_captured_options, + posthog_call_kwargs, +) + try: from google import genai as google_genai @@ -1765,3 +1773,148 @@ def test_streaming_url_context_on_earlier_chunk_bills_tool_use_tokens( props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input_tokens"] == 320 assert props["$ai_output_tokens"] == 10 + + +def _gemini_stream_chunk(): + chunk = MagicMock() + chunk.text = "Hi" + usage = MagicMock() + usage.prompt_token_count = 2 + usage.candidates_token_count = 1 + usage.cached_content_token_count = 0 + usage.thoughts_token_count = 0 + chunk.usage_metadata = usage + return chunk + + +@pytest.fixture +def gemini_provider(mock_gemini_response, mock_embed_content_response): + """A genai.Client mock with sync ``models`` and async ``aio.models``.""" + with patch.object(google_genai, "Client") as client_class: + provider = MagicMock() + provider.models.generate_content.return_value = mock_gemini_response + provider.models.generate_content_stream.side_effect = lambda **kwargs: iter( + [_gemini_stream_chunk()] + ) + provider.models.embed_content.return_value = mock_embed_content_response + provider.aio.models.generate_content = AsyncMock( + return_value=mock_gemini_response + ) + provider.aio.models.generate_content_stream = AsyncMock( + side_effect=lambda **kwargs: RecordingAsyncStream([_gemini_stream_chunk()]) + ) + provider.aio.models.embed_content = AsyncMock( + return_value=mock_embed_content_response + ) + client_class.return_value = provider + yield provider + + +# id, client class, models accessor, whether the surface is async +GEMINI_SURFACES = [ + ("client_models", "Client", lambda client: client.models, False), + ("client_aio_models", "Client", lambda client: client.aio.models, True), + ("async_client_models", "AsyncClient", lambda client: client.models, True), +] + + +def _gemini_client(class_name, **kwargs): + from posthog.ai.gemini import AsyncClient + + client_class = AsyncClient if class_name == "AsyncClient" else Client + return client_class(api_key="test-key", **kwargs) + + +async def _call_gemini(models, method, is_async, **kwargs): + result = getattr(models, method)(model="gemini-2.5-flash", contents="Hi", **kwargs) + if is_async: + result = await result + if method == "generate_content_stream": + if is_async: + _ = [chunk async for chunk in result] + else: + list(result) + + +@pytest.mark.parametrize( + "case", POSTHOG_OPTIONS_CASES, ids=[case[0] for case in POSTHOG_OPTIONS_CASES] +) +@pytest.mark.parametrize( + "method", ["generate_content", "generate_content_stream", "embed_content"] +) +@pytest.mark.parametrize( + "surface", GEMINI_SURFACES, ids=[surface[0] for surface in GEMINI_SURFACES] +) +async def test_posthog_options_reach_capture_and_not_the_provider( + mock_client, gemini_provider, caplog, surface, method, case +): + _, class_name, accessor, is_async = surface + _, distinct_id, posthog_options, expected, warns = case + client = _gemini_client(class_name, posthog_client=mock_client) + + with caplog.at_level(logging.WARNING, logger="posthog"): + await _call_gemini( + accessor(client), + method, + is_async, + **posthog_call_kwargs(distinct_id, posthog_options), + ) + + models = gemini_provider.aio.models if is_async else gemini_provider.models + provider_method = getattr(models, method) + assert provider_method.call_count == 1 + assert not any( + key.startswith("posthog_") for key in provider_method.call_args.kwargs + ) + assert mock_client.capture_ai.call_count == 1 + assert_captured_options( + mock_client.capture_ai.call_args.kwargs, expected, warns, caplog + ) + + +@pytest.mark.parametrize( + "method", ["generate_content", "generate_content_stream", "embed_content"] +) +@pytest.mark.parametrize( + "surface", GEMINI_SURFACES, ids=[surface[0] for surface in GEMINI_SURFACES] +) +async def test_posthog_options_merge_over_client_defaults( + mock_client, gemini_provider, surface, method +): + _, class_name, accessor, is_async = surface + client = _gemini_client( + class_name, + posthog_client=mock_client, + posthog_options={"cookieless_mode": True, "disable_skew_correction": True}, + ) + + await _call_gemini(accessor(client), method, is_async, posthog_distinct_id="u") + await _call_gemini( + accessor(client), + method, + is_async, + posthog_distinct_id="u", + posthog_options={"cookieless_mode": False}, + ) + + assert [ + call.kwargs["options"] for call in mock_client.capture_ai.call_args_list + ] == [ + {"cookieless_mode": True, "disable_skew_correction": True}, + {"cookieless_mode": False, "disable_skew_correction": True}, + ] + + +def test_non_dict_client_default_posthog_options_are_ignored( + mock_client, gemini_provider, caplog +): + with caplog.at_level(logging.WARNING, logger="posthog"): + client = Client( + api_key="test-key", posthog_client=mock_client, posthog_options="bad" + ) + client.models.generate_content( + model="gemini-2.5-flash", contents="Hi", posthog_distinct_id="user-1" + ) + + assert "posthog_options must be a dict" in caplog.text + assert "options" not in mock_client.capture_ai.call_args.kwargs diff --git a/posthog/test/ai/langchain/test_callbacks.py b/posthog/test/ai/langchain/test_callbacks.py index 5789aed30..58fc1d69e 100644 --- a/posthog/test/ai/langchain/test_callbacks.py +++ b/posthog/test/ai/langchain/test_callbacks.py @@ -9,6 +9,8 @@ import pytest +from posthog.test.ai.utils import POSTHOG_OPTIONS_CASES, assert_captured_options + try: from langchain_anthropic.chat_models import ChatAnthropic from langchain_community.chat_models.fake import FakeMessagesListChatModel @@ -3076,3 +3078,71 @@ def test_an_error_event_records_an_integer_status(self): properties = client.capture_ai.call_args_list[0][1]["properties"] assert properties["$ai_http_status"] == 0 + + +def _invoke_fake_chain(handler, metadata=None): + prompt = ChatPromptTemplate.from_messages([("user", "Foo")]) + chain = prompt | FakeMessagesListChatModel(responses=[AIMessage(content="Bar")]) + config = {"callbacks": [handler]} + if metadata is not None: + config["metadata"] = metadata + chain.invoke({}, config=config) + + +@pytest.mark.parametrize( + "case", POSTHOG_OPTIONS_CASES, ids=[case[0] for case in POSTHOG_OPTIONS_CASES] +) +def test_handler_options_reach_every_event(mock_client, caplog, case): + _, distinct_id, options, expected, warns = case + + with caplog.at_level(logging.WARNING, logger="posthog"): + _invoke_fake_chain( + CallbackHandler(mock_client, distinct_id=distinct_id, options=options) + ) + + calls = mock_client.capture_ai.call_args_list + assert [call.kwargs["event"] for call in calls] == [ + "$ai_span", + "$ai_generation", + "$ai_trace", + ] + for call in calls: + assert_captured_options(call.kwargs, expected, warns, caplog) + + +def test_run_metadata_posthog_options_reach_the_generation(mock_client): + _invoke_fake_chain( + CallbackHandler( + mock_client, distinct_id="user-1", options={"cookieless_mode": True} + ), + metadata={ + "posthog_options": { + "cookieless_mode": False, + "disable_skew_correction": True, + } + }, + ) + + options_by_event = { + call.kwargs["event"]: call.kwargs["options"] + for call in mock_client.capture_ai.call_args_list + } + # The handler's options win over the run's, like its properties. + assert options_by_event == { + "$ai_span": {"cookieless_mode": True}, + "$ai_generation": {"cookieless_mode": True, "disable_skew_correction": True}, + "$ai_trace": {"cookieless_mode": True}, + } + + +def test_non_dict_run_metadata_posthog_options_are_ignored(mock_client, caplog): + with caplog.at_level(logging.WARNING, logger="posthog"): + _invoke_fake_chain( + CallbackHandler(mock_client), + metadata={"posthog_options": "cookieless_mode"}, + ) + + generation = mock_client.capture_ai.call_args_list[1].kwargs + assert generation["event"] == "$ai_generation" + assert generation["options"] == {"process_person_profile": False} + assert "posthog_options must be a dict" in caplog.text diff --git a/posthog/test/ai/langchain/test_middleware.py b/posthog/test/ai/langchain/test_middleware.py index 115821d7a..609d9e882 100644 --- a/posthog/test/ai/langchain/test_middleware.py +++ b/posthog/test/ai/langchain/test_middleware.py @@ -199,6 +199,7 @@ def test_instruments_sync_agent_model_and_tool_loop() -> None: trace_id="trace-id", properties={"environment": "test"}, groups={"company": "posthog"}, + options={"cookieless_mode": True}, ) ], ) @@ -219,6 +220,7 @@ def test_instruments_sync_agent_model_and_tool_loop() -> None: assert trace["groups"] == {"company": "posthog"} assert all(event["properties"]["$ai_trace_id"] == "trace-id" for event in events) assert all(event["properties"]["environment"] == "test" for event in events) + assert all(event["options"] == {"cookieless_mode": True} for event in events) assert all( event["properties"].get("$ai_parent_id") == trace["properties"]["$ai_span_id"] for event in events[:-1] diff --git a/posthog/test/ai/openai/test_openai.py b/posthog/test/ai/openai/test_openai.py index 542ca690f..0e6dde342 100644 --- a/posthog/test/ai/openai/test_openai.py +++ b/posthog/test/ai/openai/test_openai.py @@ -38,9 +38,12 @@ from posthog.ai.openai.openai_async import AsyncOpenAI from posthog.ai.openai.wrapper_utils import reset_fallback_warnings from posthog.test.ai.utils import ( + POSTHOG_OPTIONS_CASES, RecordingAsyncStream, RecordingStream, + assert_captured_options, make_response_usage, + posthog_call_kwargs, ) OPENAI_AVAILABLE = True @@ -3170,3 +3173,271 @@ def test_streaming_state_tracks_served_service_tier(): SimpleNamespace(response=SimpleNamespace(service_tier="flex"), type="other") ) assert responses_state.service_tier == "flex" + + +def _options_chat_completion(): + return ChatCompletion( + id="test", + model="gpt-4", + object="chat.completion", + created=1741476542, + choices=[ + Choice( + finish_reason="stop", + index=0, + message=ChatCompletionMessage(content="Hi", role="assistant"), + ) + ], + usage=CompletionUsage(completion_tokens=1, prompt_tokens=2, total_tokens=3), + ) + + +def _options_chat_chunks(): + return [ + ChatCompletionChunk( + id="chunk", + model="gpt-4", + object="chat.completion.chunk", + created=1741476542, + choices=[ + ChoiceChunk( + index=0, delta=ChoiceDelta(content="Hi"), finish_reason="stop" + ) + ], + usage=CompletionUsage(completion_tokens=1, prompt_tokens=2, total_tokens=3), + ) + ] + + +def _options_response(): + return Response( + id="test", + model="gpt-4o-mini", + object="response", + created_at=1741476542, + status="completed", + error=None, + incomplete_details=None, + instructions=None, + max_output_tokens=None, + tools=[], + tool_choice="auto", + output=[], + parallel_tool_calls=True, + previous_response_id=None, + usage=make_response_usage(input_tokens=2, output_tokens=1, total_tokens=3), + user=None, + metadata={}, + ) + + +def _options_response_chunks(): + chunk = MagicMock() + chunk.type = "response.completed" + chunk.response.usage = make_response_usage( + input_tokens=2, output_tokens=1, total_tokens=3 + ) + chunk.response.output = [] + return [chunk] + + +def _options_embedding(): + return CreateEmbeddingResponse( + data=[Embedding(embedding=[0.1], index=0, object="embedding")], + model="text-embedding-3-small", + object="list", + usage=Usage(prompt_tokens=2, total_tokens=2), + ) + + +_CHAT_KWARGS = {"model": "gpt-4", "messages": [{"role": "user", "content": "Hi"}]} +_RESPONSES_KWARGS = {"model": "gpt-4o-mini", "input": "Hi"} + +# id, provider module, provider class, method, wrapper accessor, call kwargs, +# response factory, whether the call streams +OPENAI_OPTIONS_CALLS = [ + ( + "chat_create", + "openai.resources.chat.completions", + "Completions", + "create", + lambda client: client.chat.completions.create, + _CHAT_KWARGS, + _options_chat_completion, + False, + ), + ( + "chat_create_stream", + "openai.resources.chat.completions", + "Completions", + "create", + lambda client: client.chat.completions.create, + {**_CHAT_KWARGS, "stream": True}, + _options_chat_chunks, + True, + ), + ( + "chat_parse", + "openai.resources.chat.completions", + "Completions", + "parse", + lambda client: client.chat.completions.parse, + _CHAT_KWARGS, + _options_chat_completion, + False, + ), + ( + "beta_chat_parse", + "openai.resources.chat.completions", + "Completions", + "parse", + lambda client: client.beta.chat.completions.parse, + _CHAT_KWARGS, + _options_chat_completion, + False, + ), + ( + "responses_create", + "openai.resources.responses", + "Responses", + "create", + lambda client: client.responses.create, + _RESPONSES_KWARGS, + _options_response, + False, + ), + ( + "responses_create_stream", + "openai.resources.responses", + "Responses", + "create", + lambda client: client.responses.create, + {**_RESPONSES_KWARGS, "stream": True}, + _options_response_chunks, + True, + ), + ( + "responses_parse", + "openai.resources.responses", + "Responses", + "parse", + lambda client: client.responses.parse, + _RESPONSES_KWARGS, + _options_response, + False, + ), + ( + "embeddings_create", + "openai.resources.embeddings", + "Embeddings", + "create", + lambda client: client.embeddings.create, + {"model": "text-embedding-3-small", "input": "Hi"}, + _options_embedding, + False, + ), +] + + +def _recording_provider_method(make_response, is_async, stream, provider_calls): + def respond(kwargs): + provider_calls.append(kwargs) + response = make_response() + if not stream: + return response + return RecordingAsyncStream(response) if is_async else RecordingStream(response) + + if is_async: + + async def async_method(self, **kwargs): + return respond(kwargs) + + return async_method + + def method(self, **kwargs): + return respond(kwargs) + + return method + + +@pytest.mark.parametrize( + "case", POSTHOG_OPTIONS_CASES, ids=[case[0] for case in POSTHOG_OPTIONS_CASES] +) +@pytest.mark.parametrize( + "call", OPENAI_OPTIONS_CALLS, ids=[call[0] for call in OPENAI_OPTIONS_CALLS] +) +@pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"]) +async def test_posthog_options_reach_capture_and_not_the_provider( + mock_client, caplog, is_async, call, case +): + _, module, class_name, method, accessor, call_kwargs, make_response, stream = call + _, distinct_id, posthog_options, expected, warns = case + provider_class = f"Async{class_name}" if is_async else class_name + provider_calls = [] + + with patch( + f"{module}.{provider_class}.{method}", + new=_recording_provider_method(make_response, is_async, stream, provider_calls), + ): + client_class = AsyncOpenAI if is_async else OpenAI + client = client_class(api_key="test-key", posthog_client=mock_client) + with caplog.at_level(logging.WARNING, logger="posthog"): + result = accessor(client)( + **call_kwargs, **posthog_call_kwargs(distinct_id, posthog_options) + ) + if is_async: + result = await result + if stream: + if is_async: + _ = [chunk async for chunk in result] + else: + list(result) + + assert len(provider_calls) == 1 + assert not any(key.startswith("posthog_") for key in provider_calls[0]) + assert mock_client.capture_ai.call_count == 1 + assert_captured_options( + mock_client.capture_ai.call_args.kwargs, expected, warns, caplog + ) + + +def test_posthog_options_beat_context_options_and_super_options(): + from posthog import new_context, set_context_option + from posthog.capture_event import _to_v1_event + from posthog.client import Client + + sent = [] + posthog_client = Client( + "phc_test", + send=False, + before_send=lambda msg: sent.append(msg) or msg, + super_options={"cookieless_mode": False, "disable_skew_correction": True}, + ) + + with patch( + "openai.resources.chat.completions.Completions.create", + return_value=_options_chat_completion(), + ): + client = OpenAI(api_key="test-key", posthog_client=posthog_client) + with new_context(): + set_context_option("cookieless_mode", False) + set_context_option("product_tour_id", "tour-1") + client.chat.completions.create( + **_CHAT_KWARGS, + posthog_distinct_id="user-1", + posthog_options={"cookieless_mode": True}, + ) + client.chat.completions.create(**_CHAT_KWARGS, posthog_distinct_id="user-1") + + assert [_to_v1_event(msg)["options"] for msg in sent] == [ + { + "cookieless_mode": True, + "product_tour_id": "tour-1", + "disable_skew_correction": True, + }, + { + "cookieless_mode": False, + "product_tour_id": "tour-1", + "disable_skew_correction": True, + }, + ] diff --git a/posthog/test/ai/openai_agents/test_processor.py b/posthog/test/ai/openai_agents/test_processor.py index e164c5216..7e70500c0 100644 --- a/posthog/test/ai/openai_agents/test_processor.py +++ b/posthog/test/ai/openai_agents/test_processor.py @@ -5,6 +5,8 @@ import pytest +from posthog.test.ai.utils import POSTHOG_OPTIONS_CASES, assert_captured_options + try: from agents.tracing.span_data import ( AgentSpanData, @@ -1197,6 +1199,35 @@ def test_instrument_with_groups_and_properties(self, mock_client): assert processor._groups == {"company": "acme"} assert processor._properties == {"env": "test"} + @pytest.mark.parametrize( + "case", + POSTHOG_OPTIONS_CASES, + ids=[case[0] for case in POSTHOG_OPTIONS_CASES], + ) + def test_instrument_options_reach_trace_and_span_events( + self, mock_client, mock_trace, mock_span, caplog, case + ): + _, distinct_id, options, expected, warns = case + + with caplog.at_level(logging.WARNING, logger="posthog"): + with patch("agents.tracing.add_trace_processor"): + processor = instrument( + client=mock_client, distinct_id=distinct_id, options=options + ) + processor.on_trace_start(mock_trace) + mock_span.span_data = GenerationSpanData(model="gpt-4o") + processor.on_span_start(mock_span) + processor.on_span_end(mock_span) + processor.on_trace_end(mock_trace) + + calls = mock_client.capture_ai.call_args_list + assert [call.kwargs["event"] for call in calls] == [ + "$ai_generation", + "$ai_trace", + ] + for call in calls: + assert_captured_options(call.kwargs, expected, warns, caplog) + class TestCapturePolicy: def test_processor_groups_are_forwarded(self, mock_client): diff --git a/posthog/test/ai/utils.py b/posthog/test/ai/utils.py index 9f27c1f38..7aecc547f 100644 --- a/posthog/test/ai/utils.py +++ b/posthog/test/ai/utils.py @@ -88,3 +88,55 @@ async def __anext__(self): async def close(self): self.closed = True + + +# Each case: name, distinct ID passed to the wrapper, posthog_options passed +# (None means the argument is left out), expected ``options`` kwarg of +# ``capture_ai`` (None means no ``options`` kwarg), and whether a non-dict +# warning is logged. +POSTHOG_OPTIONS_CASES = [ + ( + "identified_keeps_user_values", + "user-1", + {"cookieless_mode": True, "process_person_profile": True}, + {"cookieless_mode": True, "process_person_profile": True}, + False, + ), + ( + "personless_false_beats_user_true", + None, + {"cookieless_mode": True, "process_person_profile": True}, + {"cookieless_mode": True, "process_person_profile": False}, + False, + ), + ("unset_sends_no_options", "user-1", None, None, False), + ("non_dict_is_ignored", "user-1", "cookieless_mode", None, True), + ( + "non_dict_is_ignored_personless", + None, + ["cookieless_mode"], + {"process_person_profile": False}, + True, + ), +] + +NON_DICT_OPTIONS_WARNING = "posthog_options must be a dict" + + +def posthog_call_kwargs(distinct_id, posthog_options): + """The PostHog arguments of one wrapper call, leaving out unset ones.""" + kwargs = {} + if distinct_id is not None: + kwargs["posthog_distinct_id"] = distinct_id + if posthog_options is not None: + kwargs["posthog_options"] = posthog_options + return kwargs + + +def assert_captured_options(capture_kwargs, expected, warns, caplog): + """Check the ``options`` kwarg of one ``capture_ai`` call and the warning log.""" + if expected is None: + assert "options" not in capture_kwargs + else: + assert capture_kwargs["options"] == expected + assert (NON_DICT_OPTIONS_WARNING in caplog.text) is warns diff --git a/references/public_api_snapshot.txt b/references/public_api_snapshot.txt index 315c83721..2b929045e 100644 --- a/references/public_api_snapshot.txt +++ b/references/public_api_snapshot.txt @@ -564,12 +564,12 @@ attribute posthog.ai.evaluations.UploadReceipt.items: tuple[ItemReceipt, ...] attribute posthog.ai.evaluations.UploadReceipt.results: tuple[ResultReceipt, ...] attribute posthog.ai.gateway.POSTHOG_AI_GATEWAY_HOSTS = ['gateway.posthog.com', 'gateway.us.posthog.com', 'gateway.eu.posthog.com', 'ai-gateway.us.posthog.com', 'ai-gateway.eu.posthog.com'] attribute posthog.ai.gateway.log = logging.getLogger('posthog') -attribute posthog.ai.gemini.gemini.Client.aio = _GeminiAioNamespace(models=(AsyncModels(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, **kwargs)), files=(self._provider_client.aio.files)) +attribute posthog.ai.gemini.gemini.Client.aio = _GeminiAioNamespace(models=(AsyncModels(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, posthog_options=posthog_options, **kwargs)), files=(self._provider_client.aio.files)) attribute posthog.ai.gemini.gemini.Client.files = self._provider_client.files -attribute posthog.ai.gemini.gemini.Client.models = Models(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, **kwargs) +attribute posthog.ai.gemini.gemini.Client.models = Models(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, posthog_options=posthog_options, **kwargs) attribute posthog.ai.gemini.gemini_async.AsyncClient.aio = _GeminiAioNamespace(models=(self.models), files=(self.files)) attribute posthog.ai.gemini.gemini_async.AsyncClient.files = self._provider_client.aio.files -attribute posthog.ai.gemini.gemini_async.AsyncClient.models = AsyncModels(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, **kwargs) +attribute posthog.ai.gemini.gemini_async.AsyncClient.models = AsyncModels(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, posthog_options=posthog_options, **kwargs) attribute posthog.ai.gemini.gemini_converter.GeminiMessage.content: Union[str, List[Any]] attribute posthog.ai.gemini.gemini_converter.GeminiMessage.parts: List[Union[GeminiPart, Dict[str, Any]]] attribute posthog.ai.gemini.gemini_converter.GeminiMessage.role: str @@ -579,6 +579,7 @@ attribute posthog.ai.gemini.genai = _GenAI() attribute posthog.ai.langchain.callbacks.GenerationMetadata.base_url: Optional[str] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.model: Optional[str] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.model_params: Optional[Dict[str, Any]] = None +attribute posthog.ai.langchain.callbacks.GenerationMetadata.posthog_options: Optional[Dict[str, Any]] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.posthog_properties: Optional[Dict[str, Any]] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.provider: Optional[str] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.tools: Optional[List[Dict[str, Any]]] = None @@ -684,6 +685,7 @@ attribute posthog.ai.types.StreamingEventData.groups: Optional[Dict[str, Any]] attribute posthog.ai.types.StreamingEventData.kwargs: Dict[str, Any] attribute posthog.ai.types.StreamingEventData.latency: float attribute posthog.ai.types.StreamingEventData.model: str +attribute posthog.ai.types.StreamingEventData.options: NotRequired[Optional[Dict[str, Any]]] attribute posthog.ai.types.StreamingEventData.privacy_mode: bool attribute posthog.ai.types.StreamingEventData.properties: Optional[Dict[str, Any]] attribute posthog.ai.types.StreamingEventData.provider: str @@ -1228,8 +1230,8 @@ class posthog.ai.anthropic.anthropic_providers.AnthropicBedrock(posthog_client: class posthog.ai.anthropic.anthropic_providers.AnthropicVertex(posthog_client: Optional[PostHogClient] = None, **kwargs) class posthog.ai.anthropic.anthropic_providers.AsyncAnthropicBedrock(posthog_client: Optional[PostHogClient] = None, **kwargs) class posthog.ai.anthropic.anthropic_providers.AsyncAnthropicVertex(posthog_client: Optional[PostHogClient] = None, **kwargs) -class posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient(options: Optional[ClaudeAgentOptions] = None, transport: Any = None, *, posthog_client: Optional[Client] = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None) -class posthog.ai.claude_agent_sdk.processor.PostHogClaudeAgentProcessor(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None) +class posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient(options: Optional[ClaudeAgentOptions] = None, transport: Any = None, *, posthog_client: Optional[Client] = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None) +class posthog.ai.claude_agent_sdk.processor.PostHogClaudeAgentProcessor(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) class posthog.ai.evaluations.AsyncDatasetSnapshot(dataset: Dataset, revision: int, revision_id: str, _datasets: AsyncDatasets) class posthog.ai.evaluations.AsyncDatasets(transport: AsyncTransport, project_id: int) class posthog.ai.evaluations.AsyncExperiment(transport: AsyncTransport, project_id: int, id: str, *, receipt: ExperimentReceipt | None = None, submission: bytes | None = None) @@ -1267,17 +1269,17 @@ class posthog.ai.evaluations.ScorerVersion(id: str, definition_id: str, version: class posthog.ai.evaluations.ScorerVersionPage(count: int, results: tuple[ScorerVersion[ScorerConfig], ...], next_cursor: str | None) class posthog.ai.evaluations.Scorers(transport: SyncTransport, project_id: int) class posthog.ai.evaluations.UploadReceipt(items: tuple[ItemReceipt, ...], results: tuple[ResultReceipt, ...]) -class posthog.ai.gemini.gemini.Client(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs) -class posthog.ai.gemini.gemini.Models(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, **kwargs) -class posthog.ai.gemini.gemini_async.AsyncClient(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs) -class posthog.ai.gemini.gemini_async.AsyncModels(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, **kwargs) +class posthog.ai.gemini.gemini.Client(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs) +class posthog.ai.gemini.gemini.Models(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs) +class posthog.ai.gemini.gemini_async.AsyncClient(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs) +class posthog.ai.gemini.gemini_async.AsyncModels(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs) class posthog.ai.gemini.gemini_converter.GeminiMessage class posthog.ai.gemini.gemini_converter.GeminiPart -class posthog.ai.langchain.callbacks.CallbackHandler(client: Optional[Client] = None, *, distinct_id: Optional[Union[str, int, UUID]] = None, trace_id: Optional[Union[str, int, float, UUID]] = None, properties: Optional[Dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None) -class posthog.ai.langchain.callbacks.GenerationMetadata(name: str, start_time: float, end_time: Optional[float], input: Optional[Any], provider: Optional[str] = None, model: Optional[str] = None, model_params: Optional[Dict[str, Any]] = None, base_url: Optional[str] = None, tools: Optional[List[Dict[str, Any]]] = None, posthog_properties: Optional[Dict[str, Any]] = None) +class posthog.ai.langchain.callbacks.CallbackHandler(client: Optional[Client] = None, *, distinct_id: Optional[Union[str, int, UUID]] = None, trace_id: Optional[Union[str, int, float, UUID]] = None, properties: Optional[Dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) +class posthog.ai.langchain.callbacks.GenerationMetadata(name: str, start_time: float, end_time: Optional[float], input: Optional[Any], provider: Optional[str] = None, model: Optional[str] = None, model_params: Optional[Dict[str, Any]] = None, base_url: Optional[str] = None, tools: Optional[List[Dict[str, Any]]] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None) class posthog.ai.langchain.callbacks.ModelUsage(input_tokens: Optional[int], output_tokens: Optional[int], cache_write_tokens: Optional[int], cache_read_tokens: Optional[int], reasoning_tokens: Optional[int], cache_write_5m_tokens: Optional[int] = None, cache_write_1h_tokens: Optional[int] = None, web_search_count: Optional[int] = None) class posthog.ai.langchain.callbacks.SpanMetadata(name: str, start_time: float, end_time: Optional[float], input: Optional[Any]) -class posthog.ai.langchain.middleware.PostHogMiddleware(client: Optional[Client] = None, *, distinct_id: Optional[Union[str, int, UUID]] = None, trace_id: Optional[Union[str, int, float, UUID]] = None, properties: Optional[dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[dict[str, Any]] = None) +class posthog.ai.langchain.middleware.PostHogMiddleware(client: Optional[Client] = None, *, distinct_id: Optional[Union[str, int, UUID]] = None, trace_id: Optional[Union[str, int, float, UUID]] = None, properties: Optional[dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[dict[str, Any]] = None, options: Optional[dict[str, Any]] = None) class posthog.ai.openai.openai.OpenAI(posthog_client: Optional[PostHogClient] = None, **kwargs) class posthog.ai.openai.openai.WrappedBeta class posthog.ai.openai.openai.WrappedBetaChat @@ -1296,7 +1298,7 @@ class posthog.ai.openai.openai_async.WrappedEmbeddings class posthog.ai.openai.openai_async.WrappedResponses class posthog.ai.openai.openai_providers.AsyncAzureOpenAI(posthog_client: Optional[PostHogClient] = None, **kwargs) class posthog.ai.openai.openai_providers.AzureOpenAI(posthog_client: Optional[PostHogClient] = None, **kwargs) -class posthog.ai.openai_agents.processor.PostHogTracingProcessor(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[Trace], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None) +class posthog.ai.openai_agents.processor.PostHogTracingProcessor(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[Trace], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) class posthog.ai.otel.exporter.PostHogTraceExporter(api_key: str, host: str = DEFAULT_HOST, *, privacy_mode: bool = False, client: Optional[Client] = None) class posthog.ai.otel.processor.PostHogSpanProcessor(api_key: str, host: str = DEFAULT_HOST, *, privacy_mode: bool = False, client: Optional[Client] = None) class posthog.ai.prompts.CachedPrompt(prompt: str, fetched_at: float, name: str, version: int, label: Optional[str] = None, config: Optional[Dict[str, Any]] = None) @@ -1398,8 +1400,8 @@ function posthog.ai.anthropic.anthropic_converter.handle_anthropic_text_delta(ev function posthog.ai.anthropic.anthropic_converter.handle_anthropic_tool_delta(event: Any, content_blocks: List[StreamingContentBlock], tools_in_progress: Dict[str, ToolInProgress]) -> None function posthog.ai.claude_agent_sdk.formatting.format_assistant_blocks(blocks: Any) -> List[Dict[str, Any]] function posthog.ai.claude_agent_sdk.formatting.format_tool_result_content(block: Any, ph_client: Any = None) -> Any -function posthog.ai.claude_agent_sdk.instrument(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None) -> PostHogClaudeAgentProcessor -function posthog.ai.claude_agent_sdk.query(*, prompt: Any, options: Optional[ClaudeAgentOptions] = None, transport: Any = None, posthog_client: Optional[Client] = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None) +function posthog.ai.claude_agent_sdk.instrument(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) -> PostHogClaudeAgentProcessor +function posthog.ai.claude_agent_sdk.query(*, prompt: Any, options: Optional[ClaudeAgentOptions] = None, transport: Any = None, posthog_client: Optional[Client] = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None) function posthog.ai.gateway.is_posthog_ai_gateway_url(base_url: Any) -> bool function posthog.ai.gateway.warn_if_posthog_ai_gateway(base_url: Any) -> None function posthog.ai.gateway.warn_if_posthog_ai_gateway_otel_attributes(attributes: Optional[Mapping[str, Any]]) -> None @@ -1437,7 +1439,7 @@ function posthog.ai.openai.openai_converter.format_openai_streaming_output(accum function posthog.ai.openai.wrapper_utils.merge_provider_override(posthog_properties: Optional[Dict[str, Any]], posthog_provider_override: Optional[str]) -> Optional[Dict[str, Any]] function posthog.ai.openai.wrapper_utils.reset_fallback_warnings() -> None function posthog.ai.openai.wrapper_utils.warn_on_fallback(wrapper_name: str, name: str) -> None -function posthog.ai.openai_agents.instrument(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[Trace], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None) -> PostHogTracingProcessor +function posthog.ai.openai_agents.instrument(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[Trace], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) -> PostHogTracingProcessor function posthog.ai.otel.spans.is_ai_span(span: ReadableSpan) -> bool function posthog.ai.sanitization.redact_base64_data_url(value: Any) -> Any function posthog.ai.sanitization.redact_media(value: Any, max_string_len: Optional[int] = None, ph_client: Any = None) -> Any @@ -1447,8 +1449,8 @@ function posthog.ai.sanitization.sanitize_langchain(data: Any, ph_client: Any = function posthog.ai.sanitization.sanitize_messages(data: Any, provider: Optional[str] = None, ph_client: Any = None) -> Any function posthog.ai.sanitization.sanitize_openai(data: Any, ph_client: Any = None) -> Any function posthog.ai.sanitization.sanitize_openai_response(data: Any, ph_client: Any = None) -> Any -function posthog.ai.utils.call_llm_and_track_usage(posthog_distinct_id: Optional[str], ph_client: PostHogClient, provider: str, posthog_trace_id: Optional[str], posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], base_url: str, call_method: Callable[..., Any], **kwargs: Any) -> Any -function posthog.ai.utils.call_llm_and_track_usage_async(posthog_distinct_id: Optional[str], ph_client: PostHogClient, provider: str, posthog_trace_id: Optional[str], posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], base_url: str, call_async_method: Callable[..., Any], **kwargs: Any) -> Any +function posthog.ai.utils.call_llm_and_track_usage(posthog_distinct_id: Optional[str], ph_client: PostHogClient, provider: str, posthog_trace_id: Optional[str], posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], base_url: str, call_method: Callable[..., Any], *, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Any +function posthog.ai.utils.call_llm_and_track_usage_async(posthog_distinct_id: Optional[str], ph_client: PostHogClient, provider: str, posthog_trace_id: Optional[str], posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], base_url: str, call_async_method: Callable[..., Any], *, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Any function posthog.ai.utils.capture_streaming_event(ph_client: PostHogClient, event_data: StreamingEventData) function posthog.ai.utils.extract_available_tool_calls(provider: str, kwargs: Dict[str, Any]) function posthog.ai.utils.extract_stop_reason(response: Any, provider: str) -> Optional[str] @@ -1615,10 +1617,10 @@ function posthog.utils.str_iequals(value, comparand) function posthog.utils.str_istartswith(source, search) function posthog.utils.system_context() -> dict[str, Any] function posthog.utils.total_seconds(delta: timedelta) -> float -method posthog.ai.anthropic.anthropic.WrappedMessages.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.anthropic.anthropic.WrappedMessages.stream(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.anthropic.anthropic_async.AsyncWrappedMessages.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.anthropic.anthropic_async.AsyncWrappedMessages.stream(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.anthropic.anthropic.WrappedMessages.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.anthropic.anthropic.WrappedMessages.stream(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.anthropic.anthropic_async.AsyncWrappedMessages.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.anthropic.anthropic_async.AsyncWrappedMessages.stream(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.connect(prompt: Any = None) -> None method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.disconnect() -> None method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.interrupt() -> None @@ -1626,7 +1628,7 @@ method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.query(prompt: s method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.receive_response() method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.set_model(model: Optional[str] = None) -> None method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.set_permission_mode(mode: str) -> None -method posthog.ai.claude_agent_sdk.processor.PostHogClaudeAgentProcessor.query(*, prompt: Any, options: Optional[ClaudeAgentOptions] = None, transport: Any = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None) +method posthog.ai.claude_agent_sdk.processor.PostHogClaudeAgentProcessor.query(*, prompt: Any, options: Optional[ClaudeAgentOptions] = None, transport: Any = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None) method posthog.ai.evaluations.AsyncDatasetSnapshot.iter_items(*, page_size: int = 25) method posthog.ai.evaluations.AsyncDatasets.archive(dataset_id: str | UUID) method posthog.ai.evaluations.AsyncDatasets.archive_item(item_id: str | UUID, *, base_version: int) @@ -1696,12 +1698,12 @@ method posthog.ai.evaluations.Scorers.get_version(scorer_id: str | UUID, version method posthog.ai.evaluations.Scorers.list(*, limit: int = 100, offset: int = 0, search: str | None = None, kind: ScorerKind | None = None, archived: bool | None = None, order_by: ScorerOrder | None = None, tags: Sequence[str] | None = None, tag_match: Literal['any', 'all'] = 'any') method posthog.ai.evaluations.Scorers.list_versions(scorer_id: str | UUID, *, limit: int = 50, cursor: str | None = None) method posthog.ai.evaluations.Scorers.update(scorer_id: str | UUID, *, name: str | _Omitted = _OMITTED, description: str | None | _Omitted = _OMITTED, archived: bool | _Omitted = _OMITTED, tags: Sequence[str] | _Omitted = _OMITTED) -method posthog.ai.gemini.gemini.Models.embed_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini.Models.generate_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini.Models.generate_content_stream(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini_async.AsyncModels.embed_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini_async.AsyncModels.generate_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini_async.AsyncModels.generate_content_stream(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini.Models.embed_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini.Models.generate_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini.Models.generate_content_stream(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini_async.AsyncModels.embed_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini_async.AsyncModels.generate_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini_async.AsyncModels.generate_content_stream(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) method posthog.ai.langchain.callbacks.CallbackHandler.on_agent_action(action: AgentAction, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any) -> Any method posthog.ai.langchain.callbacks.CallbackHandler.on_agent_finish(finish: AgentFinish, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any) -> Any method posthog.ai.langchain.callbacks.CallbackHandler.on_chain_end(outputs: Dict[str, Any], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any) @@ -1726,18 +1728,18 @@ method posthog.ai.langchain.middleware.PostHogMiddleware.awrap_tool_call(request method posthog.ai.langchain.middleware.PostHogMiddleware.before_agent(state: _PostHogMiddlewareState, runtime: Any) -> dict[str, Any] method posthog.ai.langchain.middleware.PostHogMiddleware.wrap_model_call(request: ModelRequest[Any], handler: Callable[[ModelRequest[Any]], ModelResponse[Any]]) -> ModelResponse[Any] method posthog.ai.langchain.middleware.PostHogMiddleware.wrap_tool_call(request: ToolCallRequest, handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]]) -> ToolMessage | Command[Any] -method posthog.ai.openai.openai.WrappedBetaCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedCompletions.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedEmbeddings.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedResponses.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedResponses.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedBetaCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedCompletions.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedEmbeddings.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedResponses.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedResponses.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedBetaCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedCompletions.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedEmbeddings.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedResponses.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedResponses.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedBetaCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedCompletions.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedEmbeddings.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedResponses.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedResponses.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) method posthog.ai.openai_agents.processor.PostHogTracingProcessor.force_flush() -> None method posthog.ai.openai_agents.processor.PostHogTracingProcessor.on_span_end(span: Span[Any]) -> None method posthog.ai.openai_agents.processor.PostHogTracingProcessor.on_span_start(span: Span[Any]) -> None From 9648886129158246dc172bd7ad3cdbe4ba7fbd27 Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Sat, 7 Nov 2026 19:22:35 -0800 Subject: [PATCH 2/4] fix(ai): send LangChain exception events with the run's options Co-Authored-By: Claude Opus 5.5 --- docs/migration-7.x-to-8.0.md | 2 +- posthog/ai/langchain/callbacks.py | 17 ++++++-- posthog/test/ai/langchain/test_callbacks.py | 47 +++++++++++++++++++++ 3 files changed, 62 insertions(+), 4 deletions(-) diff --git a/docs/migration-7.x-to-8.0.md b/docs/migration-7.x-to-8.0.md index 6a0775daa..db6e74969 100644 --- a/docs/migration-7.x-to-8.0.md +++ b/docs/migration-7.x-to-8.0.md @@ -268,7 +268,7 @@ These changes follow from this order: - The AI integrations take capture options: - Every wrapper method that takes `posthog_properties` also takes `posthog_options`, for the events of that call. This covers OpenAI, Anthropic and Gemini, sync and async, and the Claude Agent SDK `query()` and `PostHogClaudeSDKClient`. The name keeps it apart from the Claude Agent SDK's own `options`. - The Gemini clients take `posthog_options` as a default for every call. A call's `posthog_options` win key by key. - - LangChain's `CallbackHandler` and `PostHogMiddleware`, OpenAI Agents' `instrument()` and `PostHogTracingProcessor`, and the Claude Agent SDK's `instrument()` and `PostHogClaudeAgentProcessor` take `options=` for every event. LangChain also reads `posthog_options` from run metadata, like `posthog_properties`. Like properties, the handler's or processor's options win over a run's or a query's. + - LangChain's `CallbackHandler` and `PostHogMiddleware`, OpenAI Agents' `instrument()` and `PostHogTracingProcessor`, and the Claude Agent SDK's `instrument()` and `PostHogClaudeAgentProcessor` take `options=` for every event. LangChain also reads `posthog_options` from run metadata, like `posthog_properties`. Like properties, the handler's or processor's options win over a run's or a query's. The `$exception` event LangChain captures for a failed run gets the same options. - These are the event's own options, so they win over context options and `super_options`, which still fill the keys they leave unset. `before_send` can still change them. - A value that is not a dict is logged as a warning and ignored. The provider call still runs, and the provider never receives `posthog_options`. diff --git a/posthog/ai/langchain/callbacks.py b/posthog/ai/langchain/callbacks.py index 3f99cdbb6..f61436e92 100644 --- a/posthog/ai/langchain/callbacks.py +++ b/posthog/ai/langchain/callbacks.py @@ -583,7 +583,7 @@ def _capture_trace_or_span( ) event_properties["$ai_is_error"] = True event_properties = self._capture_exception_and_update_properties( - outputs, event_properties + outputs, event_properties, self._options ) elif outputs is not None: @@ -604,7 +604,10 @@ def _capture_trace_or_span( ) def _capture_exception_and_update_properties( - self, exception: BaseException, event_properties: Dict[str, Any] + self, + exception: BaseException, + event_properties: Dict[str, Any], + options: Dict[str, Any], ) -> Dict[str, Any]: # An `$exception` event carries the message and stack, which echo prompts and output. if not self._ph_client.enable_exception_autocapture or _privacy_mode_enabled( @@ -612,11 +615,16 @@ def _capture_exception_and_update_properties( ): return event_properties + exception_options = dict(options) + if _user_distinct_id(self._distinct_id) is None: + # Matches the AI event: without a user, person processing stays off. + exception_options["process_person_profile"] = False exception_id = self._ph_client.capture_exception( exception, distinct_id=self._distinct_id, groups=self._groups, properties=event_properties, + **({"options": exception_options} if exception_options else {}), ) if exception_id: event_properties["$exception_event_id"] = exception_id @@ -704,7 +712,10 @@ def _capture_generation( event_properties["$ai_is_error"] = True event_properties = self._capture_exception_and_update_properties( - output, event_properties + output, + event_properties, + # The handler's options win over the run's, like its properties. + {**_ai_event_options(run.posthog_options), **self._options}, ) else: # Add usage diff --git a/posthog/test/ai/langchain/test_callbacks.py b/posthog/test/ai/langchain/test_callbacks.py index 58fc1d69e..55e5dde6d 100644 --- a/posthog/test/ai/langchain/test_callbacks.py +++ b/posthog/test/ai/langchain/test_callbacks.py @@ -2814,6 +2814,53 @@ def test_exception_autocapture_on_llm_generation_error(mock_client): assert gen_props["$ai_is_error"] is True +@pytest.mark.parametrize( + "distinct_id, handler_options, run_options, expected_options", + [ + # No user: person processing stays off, as on the AI event. + (None, {}, None, {"process_person_profile": False}), + ( + None, + {"process_person_profile": True, "cookieless_mode": True}, + None, + {"process_person_profile": False, "cookieless_mode": True}, + ), + # A user: the options are sent as set, the handler's winning over the run's. + ("user-123", {}, None, None), + ( + "user-123", + {"cookieless_mode": True}, + {"cookieless_mode": False, "product_tour_id": "tour-1"}, + {"cookieless_mode": True, "product_tour_id": "tour-1"}, + ), + ], +) +def test_exception_autocapture_sends_ai_event_options( + distinct_id, handler_options, run_options, expected_options +): + """The `$exception` event carries the same options as its generation.""" + mock_client = MagicMock() + mock_client.privacy_mode = False + mock_client.enable_exception_autocapture = True + mock_client.capture_exception.return_value = "exception-uuid-opt" + + callbacks = CallbackHandler( + mock_client, distinct_id=distinct_id, options=handler_options + ) + run_id = uuid.uuid4() + metadata = {"posthog_options": run_options} if run_options is not None else None + callbacks.on_llm_start( + serialized={"kwargs": {"openai_api_base": "https://api.openai.com"}}, + prompts=["Hello"], + run_id=run_id, + metadata=metadata, + ) + callbacks.on_llm_error(Exception("boom"), run_id=run_id) + + assert mock_client.capture_exception.call_count == 1 + assert mock_client.capture_exception.call_args[1].get("options") == expected_options + + def test_exception_autocapture_passes_ai_properties_to_exception(): """Test that AI properties are passed to the exception event.""" mock_client = MagicMock() From b2c1542ff56a15490230048726ff08d1c9869ba6 Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Sat, 7 Nov 2026 19:35:43 -0800 Subject: [PATCH 3/4] docs(migration): simplify the 8.0 checklist and MCP hook note Co-Authored-By: Claude Opus 5.5 --- docs/migration-7.x-to-8.0.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/migration-7.x-to-8.0.md b/docs/migration-7.x-to-8.0.md index db6e74969..071fdf0f7 100644 --- a/docs/migration-7.x-to-8.0.md +++ b/docs/migration-7.x-to-8.0.md @@ -18,7 +18,6 @@ You need to change code if your app does any of these: - sends events to a self-hosted PostHog that does not serve the capture v1 endpoints - sends events through a proxy that redirects capture requests to another host - reuses one event `uuid` for more than one event -- sets `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` or `$product_tour_id` as a property: use the matching option instead (see [Event options](#event-options)). For MCP events, pass options in `event_options` (see [MCP analytics](#mcp-analytics)) - expects `super_properties` to override properties passed to a single call, including `$set` and `$groups` - sets `$is_server`, `$geoip_disable` or a system property such as `$os` and expects the SDK's value to win - has a `before_send` hook that returns a new dict: copy `options`, or the event is sent without them, including the `process_person_profile=False` the SDK sets for events without a distinct ID (see [Event options](#event-options)). The same applies to MCP's `before_send` (see [MCP analytics](#mcp-analytics)) @@ -208,7 +207,7 @@ Capture v1 sends processing options in an `options` object, next to `properties` - `set_context_option(key, value)` sets an option for the current context, like `tag()`. `get_context_options()` returns the options of the current context. Both exist on `Client` and as module functions. `AsyncPosthog` has no context methods, like it has no `tag()`, so call the module functions. They apply to every client in the context. - The Celery integration propagates context options to workers, like tags. - A propagated `process_person_profile: True` turns person processing on for worker events without a distinct ID. Each of those events creates a person. - - In eager mode (`task_always_eager`), Celery publishes nothing, so the distinct ID, tags and options do not reach the task's events. To carry them, pass the task's PostHog headers with `task.apply(headers=...)`, as described in `references/middleware_configuration.md`. + - In eager mode (`task_always_eager`), Celery publishes nothing, so the distinct ID, tags and options do not reach the task's events. To carry them, pass the task's PostHog headers with `task.apply(headers=...)`, as described in [references/middleware_configuration.md](../references/middleware_configuration.md). - Context tags and options reach `capture`, `capture_ai`, `capture_exception`, `alias` and `group_identify`. Context options also reach `set` and `set_once`. `super_properties` and `super_options` reach every method. - Options are sent as given. PostHog validates them. It drops an event with an option value it cannot read, such as a list for `cookieless_mode`, as `invalid_options`, and `on_error` reports it. - An `options` value that is not a dict is logged as an error and ignored. The event is still sent. @@ -332,9 +331,8 @@ A context you open inside the handler has ended by then, so options you set in i Events you capture inside that context still get them. To set options on `$mcp_tool_call`, use the `event_options` callback. -MCP's `before_send` sees each event's `options` in an `options` key of `PostHogCaptureEvent`. -The SDK sends what the hook returns, so a hook that returns a new dict must copy `options`. -Otherwise the event is sent without them, including the `process_person_profile: False` the SDK sets for an event without an identity, and PostHog creates a person for each session. +MCP's `before_send` gets each event's `options` in an `options` key of `PostHogCaptureEvent`. +A hook that returns a new dict must copy them, or the event is sent without the anonymous `process_person_profile: False`. ## Batching and size limits From 6b18fd701eb11cac4b682b4f52ae78d6cb917ab8 Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Sun, 8 Nov 2026 09:46:51 -0800 Subject: [PATCH 4/4] fix(ai): pass exception options as a typed keyword Co-Authored-By: Claude Opus 5.5 --- posthog/ai/langchain/callbacks.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/posthog/ai/langchain/callbacks.py b/posthog/ai/langchain/callbacks.py index f61436e92..57d2daeb4 100644 --- a/posthog/ai/langchain/callbacks.py +++ b/posthog/ai/langchain/callbacks.py @@ -624,7 +624,7 @@ def _capture_exception_and_update_properties( distinct_id=self._distinct_id, groups=self._groups, properties=event_properties, - **({"options": exception_options} if exception_options else {}), + options=exception_options or None, ) if exception_id: event_properties["$exception_event_id"] = exception_id