From 1cbed54d6df2559388bef89534050f42c3903011 Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Sat, 7 Nov 2026 17:39:43 -0800 Subject: [PATCH 1/3] feat(mcp): add event_options to MCP capture calls and instrument The PostHogMCP capture_* methods and McpAnalytics.capture take a keyword-only event_options argument, and MCPAnalyticsOptions gains an event_options callback, called for the same events as event_properties. Per-call options win over the callback's key by key, and an event without an identity still always sends process_person_profile: False. A non-dict value is logged and ignored. Co-Authored-By: Claude Opus 5.5 --- .sampo/changesets/mcp-event-options.md | 5 + posthog/mcp/__init__.py | 25 +- posthog/mcp/_capture.py | 2 + posthog/mcp/_instrumentation.py | 32 ++- posthog/mcp/_internal.py | 16 ++ posthog/mcp/_posthog_events.py | 43 ++- posthog/mcp/posthog_mcp.py | 47 +++- posthog/mcp/types.py | 11 +- posthog/test/mcp/test_features_m4.py | 11 +- posthog/test/mcp/test_pipeline.py | 356 +++++++++++++++++++++++++ posthog/test/mcp/test_posthog_mcp.py | 70 +++++ references/public_api_snapshot.txt | 15 +- 12 files changed, 599 insertions(+), 34 deletions(-) create mode 100644 .sampo/changesets/mcp-event-options.md diff --git a/.sampo/changesets/mcp-event-options.md b/.sampo/changesets/mcp-event-options.md new file mode 100644 index 000000000..d04282679 --- /dev/null +++ b/.sampo/changesets/mcp-event-options.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: minor +--- + +MCP events take capture options. The `PostHogMCP` capture methods and `McpAnalytics.capture` take an `event_options` argument, and `MCPAnalyticsOptions(event_options=...)` sets options on every event `instrument()` captures automatically, from a function of `(request, extra)` like `event_properties`. An event without an identity still always sends `process_person_profile: False`. `PostHogMCP.capture()` keeps the core client's `options` argument. diff --git a/posthog/mcp/__init__.py b/posthog/mcp/__init__.py index 9c2ca3151..4e12348de 100644 --- a/posthog/mcp/__init__.py +++ b/posthog/mcp/__init__.py @@ -33,7 +33,7 @@ import weakref from datetime import datetime, timezone -from typing import Any, Optional +from typing import Any, Dict, Optional from posthog.client import Client @@ -151,9 +151,19 @@ class McpAnalytics: def __init__(self, key: Any) -> None: self._key = key - async def capture(self, event: str, properties: Optional[dict] = None) -> None: + async def capture( + self, + event: str, + properties: Optional[dict] = None, + *, + event_options: Optional[Dict[str, Any]] = None, + ) -> None: """Capture a custom event for this server. ``event`` is sent verbatim (a - customer-defined event, so it is not ``$``-prefixed).""" + customer-defined event, so it is not ``$``-prefixed). + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. An event from a session + without an identity always sends ``process_person_profile: False``.""" if not isinstance(event, str) or not event: raise ValueError( 'capture() requires an event name, e.g. await analytics.capture("feedback_submitted")' @@ -169,6 +179,7 @@ async def capture(self, event: str, properties: Optional[dict] = None) -> None: "event_name": event, "timestamp": datetime.now(timezone.utc), "properties": properties, + "event_options": event_options, }, ) if coro is not None: @@ -187,7 +198,13 @@ class _NoopAnalytics(McpAnalytics): def __init__(self) -> None: # noqa: D401 - graceful degradation handle super().__init__(None) - async def capture(self, event: str, properties: Optional[dict] = None) -> None: + async def capture( + self, + event: str, + properties: Optional[dict] = None, + *, + event_options: Optional[Dict[str, Any]] = None, + ) -> None: return None async def flush(self) -> None: diff --git a/posthog/mcp/_capture.py b/posthog/mcp/_capture.py index ef48ef4a4..f74942de1 100644 --- a/posthog/mcp/_capture.py +++ b/posthog/mcp/_capture.py @@ -71,6 +71,8 @@ def capture_event( "error_type": event_input.get("error_type"), "conversation_id": event_input.get("conversation_id"), "properties": event_input.get("properties"), + "callback_event_options": event_input.get("callback_event_options"), + "event_options": event_input.get("event_options"), } options = McpCaptureOptions( diff --git a/posthog/mcp/_instrumentation.py b/posthog/mcp/_instrumentation.py index cd87dd4a2..bd2d1e8b0 100644 --- a/posthog/mcp/_instrumentation.py +++ b/posthog/mcp/_instrumentation.py @@ -41,7 +41,12 @@ resolve_send_feedback_tool_name, ) from ._intent import resolve_tool_call_intent, set_event_intent -from ._internal import MCPAnalyticsData, handle_identify, resolve_event_properties +from ._internal import ( + MCPAnalyticsData, + handle_identify, + resolve_event_options, + resolve_event_properties, +) from ._tool_input import get_tool_input_properties from ._model_parameters import ( add_model_parameter_to_schema, @@ -285,6 +290,7 @@ def text(value: Any) -> Optional[str]: "timestamp": timestamp, } await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) @@ -341,9 +347,9 @@ async def _maybe_emit_initialize( "protocol_version": protocol_version, "timestamp": datetime.now(timezone.utc), } - await _apply_event_properties( - data, event, {"method": "initialize", "params": {}}, extra - ) + request = {"method": "initialize", "params": {}} + await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) @@ -361,6 +367,19 @@ async def _apply_event_properties( event["properties"] = props +async def _apply_event_options( + data: MCPAnalyticsData, + event: Dict[str, Any], + request: Dict[str, Any], + extra: Optional[Dict[str, Any]], +) -> None: + """Resolve the customer's ``event_options`` callback onto the event, for the + same events as ``event_properties``.""" + options = await resolve_event_options(data, request, extra) + if options is not None: + event["callback_event_options"] = options + + def resolve_session_and_client( raw_session_id: Optional[str], client_name: Optional[str], @@ -797,6 +816,7 @@ async def record_tool_call( event["error"] = capture_exception(result) props = await resolve_event_properties(data, request, extra) + await _apply_event_options(data, event, request, extra) input_aliases = None if data.options.resolve_input_aliases is not None: try: @@ -1373,6 +1393,7 @@ async def record_missing_capability( event["llm_model"] = model event["llm_model_source"] = source await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) except Exception as err: # noqa: BLE001 - isolate analytics from the tool path @@ -1428,6 +1449,7 @@ async def record_feedback( **(props or {}), **build_feedback_event_properties(report), } + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) except Exception as err: # noqa: BLE001 - isolate analytics from the tool path @@ -1468,6 +1490,7 @@ async def record_tools_list( if error is not None: event["error"] = capture_exception(error) await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) except Exception as err: # noqa: BLE001 - isolate analytics from the tool path @@ -1520,6 +1543,7 @@ async def record_resource_request( if error is not None: event["error"] = capture_exception(error) await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) except Exception as err: # noqa: BLE001 - isolate analytics from the request path diff --git a/posthog/mcp/_internal.py b/posthog/mcp/_internal.py index 44a1eeb48..fdbcf3688 100644 --- a/posthog/mcp/_internal.py +++ b/posthog/mcp/_internal.py @@ -221,3 +221,19 @@ async def resolve_event_properties( except Exception as e: # noqa: BLE001 log(f"event_properties callback error: {e}") return None + + +async def resolve_event_options( + data: MCPAnalyticsData, + request: Dict[str, Any], + extra: Optional[Dict[str, Any]] = None, +) -> Any: + """Return the ``event_options`` callback's result as given. The event + builder checks that it is a dict, as it does for per-call options.""" + if not data.options.event_options: + return None + try: + return await _maybe_await(data.options.event_options(request, extra)) + except Exception as e: # noqa: BLE001 + log(f"event_options callback error: {e}") + return None diff --git a/posthog/mcp/_posthog_events.py b/posthog/mcp/_posthog_events.py index 6f14942a4..cdfa25874 100644 --- a/posthog/mcp/_posthog_events.py +++ b/posthog/mcp/_posthog_events.py @@ -20,6 +20,7 @@ PostHogMCPAnalyticsProperty, ) from ._event_types import MCPAnalyticsEventType +from .logger import warn from .types import Event, PostHogCaptureEvent _BUILT_IN_EVENT_NAME_BY_TYPE = { @@ -51,19 +52,20 @@ def _get_timestamp(event: Event) -> datetime: def build_posthog_capture_events( event: Event, enable_exception_autocapture: bool = True ) -> List[PostHogCaptureEvent]: - batch = [_build_capture_event(event)] + options = _get_options(event) + batch = [_build_capture_event(event, dict(options))] if ( event.get("is_error") and event.get("error") and enable_exception_autocapture is not False ): - batch.append(_build_exception_event(event)) + batch.append(_build_exception_event(event, dict(options))) for capture in batch: _fill_library(capture["properties"], (POSTHOG_MCP_LIB_NAME, VERSION), None) return batch -def _build_capture_event(event: Event) -> PostHogCaptureEvent: +def _build_capture_event(event: Event, options: Dict[str, Any]) -> PostHogCaptureEvent: properties: Dict[str, Any] = { _P.INTERFACE: "mcp", _P.SOURCE: POSTHOG_MCP_ANALYTICS_SOURCE, @@ -82,7 +84,7 @@ def _build_capture_event(event: Event) -> PostHogCaptureEvent: "event": event_name, "distinct_id": _get_distinct_id(event), "properties": properties, - "options": _get_options(event), + "options": options, "timestamp": _get_timestamp(event), } @@ -106,13 +108,34 @@ def _add_groups(event: Event, properties: Dict[str, Any]) -> None: _merge_groups(properties, groups) +def _event_options(value: Any, source: str) -> Dict[str, Any]: + """Return a copy of caller options, or ``{}`` when they are not a dict.""" + if value is None: + return {} + if not isinstance(value, dict): + warn( + f"{source} must be a dict, got {type(value).__name__}. " + "Sending the event without them." + ) + return {} + return dict(value) + + def _get_options(event: Event) -> Dict[str, Any]: + # Per-call options win over the callback's, key by key. + options = { + **_event_options( + event.get("callback_event_options"), "The event_options callback result" + ), + **_event_options(event.get("event_options"), "event_options"), + } # Without a resolved identity the distinct id is just the session id, so # processing a person profile would mint one anonymous person per session. - # As an option it beats any custom $process_person_profile property. + # Applied last, so it beats caller options and any custom + # $process_person_profile property. if not event.get("identify_actor_given_id"): - return {"process_person_profile": False} - return {} + options["process_person_profile"] = False + return options def _is_tool_call(event: Event) -> bool: @@ -270,7 +293,9 @@ def _add_server_build(event: Event, properties: Dict[str, Any]) -> None: properties[_P.SERVER_BUILD] = event["server_build"] -def _build_exception_event(event: Event) -> PostHogCaptureEvent: +def _build_exception_event( + event: Event, options: Dict[str, Any] +) -> PostHogCaptureEvent: properties: Dict[str, Any] = {_P.INTERFACE: "mcp"} _add_session_id(event, properties) _add_conversation_id(event, properties) @@ -308,6 +333,6 @@ def _build_exception_event(event: Event) -> PostHogCaptureEvent: "event": PostHogMCPAnalyticsEvent.EXCEPTION, "distinct_id": _get_distinct_id(event), "properties": properties, - "options": _get_options(event), + "options": options, "timestamp": _get_timestamp(event), } diff --git a/posthog/mcp/posthog_mcp.py b/posthog/mcp/posthog_mcp.py index ee76a7443..f7ebd90fe 100644 --- a/posthog/mcp/posthog_mcp.py +++ b/posthog/mcp/posthog_mcp.py @@ -175,7 +175,10 @@ def shutdown(self) -> None: def capture( self, event: str, **kwargs: Unpack[OptionalCaptureArgs] ) -> Optional[str]: - """Capture a custom event with the configured server build as a default.""" + """Capture a custom event with the configured server build as a default. + + This is the core ``Client.capture``, so it takes ``options=``. The MCP + ``capture_*`` methods take ``event_options=`` instead.""" if self._server_build is not None: properties = dict(kwargs.get("properties") or {}) if properties.get(PostHogMCPAnalyticsProperty.SERVER_BUILD) is None: @@ -210,9 +213,14 @@ def capture_tool_call( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: - """Capture a tool invocation. Emits ``$mcp_tool_call`` (+ ``$exception`` on error).""" + """Capture a tool invocation. Emits ``$mcp_tool_call`` (+ ``$exception`` on error). + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_TOOLS_CALL, distinct_id, @@ -221,6 +229,7 @@ def capture_tool_call( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -258,9 +267,14 @@ def capture_initialize( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: - """Capture the connection handshake. Emits ``$mcp_initialize``.""" + """Capture the connection handshake. Emits ``$mcp_initialize``. + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_INITIALIZE, distinct_id, @@ -269,6 +283,7 @@ def capture_initialize( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -299,10 +314,15 @@ def capture_tools_list( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: """Capture a ``tools/list`` response. Emits ``$mcp_tools_list`` with the - advertised tool names (``$mcp_listed_tool_names``).""" + advertised tool names (``$mcp_listed_tool_names``). + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_TOOLS_LIST, distinct_id, @@ -311,6 +331,7 @@ def capture_tools_list( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -344,12 +365,17 @@ def capture_missing_capability( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: """Capture a ``get_more_tools`` call as a missing-capability report. Emits ``$mcp_missing_capability`` with the agent's description as ``$mcp_intent``. Reply to the agent with ``get_more_tools_result()`` after passing it - through :meth:`prepare_tool_result`.""" + through :meth:`prepare_tool_result`. + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_MISSING_CAPABILITY, distinct_id, @@ -358,6 +384,7 @@ def capture_missing_capability( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -384,6 +411,7 @@ def capture_feedback( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: """Capture a ``send_feedback`` call as an agent-feedback report. Emits @@ -391,7 +419,11 @@ def capture_feedback( summary/details as ``$mcp_intent``. Reply to the agent with ``send_feedback_result()`` (or a custom text) after routing the report to your own feedback backend and passing the reply through - :meth:`prepare_tool_result`.""" + :meth:`prepare_tool_result`. + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_FEEDBACK, distinct_id, @@ -400,6 +432,7 @@ def capture_feedback( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -704,6 +737,7 @@ def _base_event( set_properties: Optional[JsonRecord], groups: Optional[Dict[str, str]], properties: Optional[JsonRecord], + event_options: Optional[Dict[str, Any]], timestamp: Optional[datetime], client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, @@ -714,6 +748,7 @@ def _base_event( "conversation_id": conversation_id, "timestamp": timestamp or datetime.now(timezone.utc), "properties": properties, + "event_options": event_options, "groups": groups, # Raw transport headers. A custom dispatcher holds its own request # object, so it passes these itself; instrumented servers read them diff --git a/posthog/mcp/types.py b/posthog/mcp/types.py index 17bb0b837..c5c30bba2 100644 --- a/posthog/mcp/types.py +++ b/posthog/mcp/types.py @@ -62,8 +62,9 @@ # Internal MCP event as it flows through the SDK before capture. Modeled as a # plain dict (constructed and read with ``.get()`` throughout) to mirror the TS # plain-object pipeline. Snake_case keys map to the ``$mcp_*`` wire keys in -# ``posthog_events``. Known keys: client_name, client_version, conversation_id, -# duration, error, error_type, event_name, event_type, groups, id, identify_actor_data, +# ``posthog_events``. Known keys: callback_event_options, client_name, +# client_version, conversation_id, duration, error, error_type, event_name, +# event_options, event_type, groups, id, identify_actor_data, # identify_actor_given_id, is_error, listed_tool_names, parameters, properties, # resource_name, response, server_name, server_version, session_id, timestamp, # tool_category, tool_description, user_intent, user_intent_source, llm_model, @@ -180,6 +181,7 @@ class FeedbackReport: ] # (request, extra) -> Optional[UserIdentity] | awaitable IntentFallbackFn = Callable[..., Any] # (request, extra) -> Optional[str] | awaitable EventPropertiesFn = Callable[..., Any] # (request, extra) -> Optional[dict] | awaitable +EventOptionsFn = Callable[..., Any] # (request, extra) -> Optional[dict] | awaitable InputAliasMap = Dict[str, List[str]] @@ -254,6 +256,11 @@ class MCPAnalyticsOptions: # no `$mcp_tools_list`. Nothing else changes: tools keep their injected # arguments, and the virtual tools stay listed. send_tools_list_event: bool = True + # Capture options, such as `process_person_profile`, for every + # auto-captured event: a callable (request, extra) -> dict | None, sync or + # async, called for the same events as `event_properties`. An event without + # an identity always sends `process_person_profile: False`. + event_options: Optional[EventOptionsFn] = None @dataclass diff --git a/posthog/test/mcp/test_features_m4.py b/posthog/test/mcp/test_features_m4.py index 561162cad..ff41a375f 100644 --- a/posthog/test/mcp/test_features_m4.py +++ b/posthog/test/mcp/test_features_m4.py @@ -296,13 +296,16 @@ async def _ct(name, arguments): ) -async def test_event_properties_applied_to_all_event_types(): +async def test_event_properties_and_options_applied_to_all_event_types(): server = make_lowlevel() client = FakeClient() instrument( server, client, - MCPAnalyticsOptions(event_properties=lambda request, extra: {"tenant": "acme"}), + MCPAnalyticsOptions( + event_properties=lambda request, extra: {"tenant": "acme"}, + event_options=lambda request, extra: {"cookieless_mode": True}, + ), ) await server.request_handlers[mcp_types.ListToolsRequest]( @@ -320,6 +323,10 @@ async def test_event_properties_applied_to_all_event_types(): assert evs[0]["properties"].get("tenant") == "acme", ( f"{name} missing event_properties" ) + assert evs[0]["options"] == { + "cookieless_mode": True, + "process_person_profile": False, + }, f"{name} missing event_options" # --- PostHogMCP -------------------------------------------------------------- diff --git a/posthog/test/mcp/test_pipeline.py b/posthog/test/mcp/test_pipeline.py index 9a6cb6c69..cc00b9201 100644 --- a/posthog/test/mcp/test_pipeline.py +++ b/posthog/test/mcp/test_pipeline.py @@ -1,5 +1,6 @@ """Unit tests for the MCP analytics core pipeline (Milestone 1, no server).""" +import copy from datetime import datetime, timezone import pytest @@ -24,6 +25,20 @@ from posthog.mcp._sink import McpCaptureOptions, McpEventSink, process_mcp_event from posthog.test.capture_helpers import patch_capture_send, sent_events from posthog.mcp._truncation import MAX_EVENT_BYTES, normalize, truncate_event +from posthog.mcp import McpAnalytics, _NoopAnalytics +from posthog.mcp._instrumentation import ( + _maybe_emit_initialize, + record_feedback, + record_initialize, + record_missing_capability, + record_resource_request, + record_tool_call, + record_tools_list, +) +from posthog.mcp._internal import MCPAnalyticsData, set_server_tracking_data +from posthog.mcp.logger import set_logger +from posthog.mcp.types import FeedbackReport, MCPAnalyticsOptions, UserIdentity +from posthog.test.mcp._helpers import FakeClient, flush_background # --- ids --------------------------------------------------------------------- @@ -1161,3 +1176,344 @@ async def test_anonymous_event_sends_personless_option(before_send, expected): ) [wire] = [_to_v1_event(msg) for msg in sent_events(send)] assert wire["options"] == {"process_person_profile": expected} + + +# --- event options ----------------------------------------------------------- + + +def _options_event(identified, **fields): + event = { + "event_type": MCPAnalyticsEventType.MCP_TOOLS_CALL, + "session_id": "ses_abc", + "resource_name": "broken_tool", + "is_error": True, + "error": capture_exception(ValueError("boom")), + "timestamp": datetime.now(timezone.utc), + **fields, + } + if identified: + event["identify_actor_given_id"] = "user_1" + return event + + +@pytest.mark.parametrize( + "identified, callback, per_call, expected", + [ + (True, None, None, {}), + (True, None, {"cookieless_mode": True}, {"cookieless_mode": True}), + (True, {"cookieless_mode": True}, None, {"cookieless_mode": True}), + ( + True, + {"product_tour_id": "callback", "cookieless_mode": True}, + {"product_tour_id": "call"}, + {"product_tour_id": "call", "cookieless_mode": True}, + ), + ( + True, + {"process_person_profile": False}, + {"process_person_profile": True}, + {"process_person_profile": True}, + ), + (False, None, None, {"process_person_profile": False}), + ( + False, + None, + {"process_person_profile": True, "cookieless_mode": True}, + {"process_person_profile": False, "cookieless_mode": True}, + ), + ( + False, + {"process_person_profile": True}, + None, + {"process_person_profile": False}, + ), + ], + ids=[ + "identified_without_options", + "identified_per_call", + "identified_callback", + "per_call_beats_callback_key_by_key", + "identified_keeps_user_values", + "anonymous_without_options", + "anonymous_personless_beats_per_call", + "anonymous_personless_beats_callback", + ], +) +def test_event_options_layering(identified, callback, per_call, expected): + callers = copy.deepcopy((callback, per_call)) + event = _options_event( + identified, callback_event_options=callback, event_options=per_call + ) + captures = build_posthog_capture_events(event) + + assert [c["event"] for c in captures] == [ + PostHogMCPAnalyticsEvent.TOOL_CALL, + PostHogMCPAnalyticsEvent.EXCEPTION, + ] + assert [c["options"] for c in captures] == [expected, expected] + # Each event gets its own copy, so before_send can change one alone. + assert captures[0]["options"] is not captures[1]["options"] + assert not any(k.startswith("$") for k in captures[0]["options"]) + # The caller's dicts are copied, never changed. + assert (callback, per_call) == callers + + +@pytest.mark.parametrize( + "field, message", + [ + ( + "event_options", + "event_options must be a dict, got str. Sending the event without them.", + ), + ( + "callback_event_options", + "The event_options callback result must be a dict, got list. " + "Sending the event without them.", + ), + ], +) +def test_non_dict_event_options_are_logged_and_ignored(field, message, caplog): + value = "process_person_profile" if field == "event_options" else ["x"] + event = _options_event(True, **{field: value}) + + with caplog.at_level("WARNING", logger="posthog.mcp"): + captures = build_posthog_capture_events(event) + + assert [c["options"] for c in captures] == [{}, {}] + # Checked once per event, not once per payload. + assert [r.getMessage() for r in caplog.records] == [message] + + +async def test_before_send_sees_merged_event_options(): + seen = [] + + def before_send(capture): + seen.append(dict(capture["options"])) + return capture + + event = _options_event( + False, + callback_event_options={"cookieless_mode": True}, + event_options={"process_person_profile": True, "product_tour_id": "t"}, + ) + await process_mcp_event(event, McpCaptureOptions(before_send=before_send)) + + expected = { + "cookieless_mode": True, + "product_tour_id": "t", + "process_person_profile": False, + } + assert seen == [expected, expected] + + +@pytest.mark.parametrize( + "identified, expected", + [ + (True, {"cookieless_mode": True, "process_person_profile": True}), + (False, {"cookieless_mode": True, "process_person_profile": False}), + ], + ids=["identified", "anonymous"], +) +async def test_event_options_reach_the_v1_payload(identified, expected): + event = _options_event( + identified, + is_error=False, + error=None, + event_options={"cookieless_mode": True, "process_person_profile": True}, + ) + with patch_capture_send("client") as send: + client = Client("test-key", sync_mode=True) + await McpEventSink(client).capture(event, McpCaptureOptions()) + [wire] = [_to_v1_event(msg) for msg in sent_events(send)] + assert wire["options"] == expected + assert not any(k.startswith("$") for k in wire["options"]) + assert "$process_person_profile" not in wire["properties"] + assert "$cookieless_mode" not in wire["properties"] + + +async def _record_every_event_type(data, session_id): + """Drive every auto-capture call site that runs ``event_properties``.""" + now = datetime.now(timezone.utc) + await record_initialize( + data, + session_id=session_id, + params={"clientInfo": {"name": "c"}}, + result=None, + extra=None, + timestamp=now, + ) + # The first-request stand-in for an initialize nothing observed. + await _maybe_emit_initialize(data, "ses_first", "generated", None, None, None) + await record_tool_call( + data, session_id, name="broken", arguments={}, error=RuntimeError("boom") + ) + await record_missing_capability( + data, session_id, tool_name="get_more_tools", context="csv", arguments={} + ) + await record_feedback( + data, + session_id, + report=FeedbackReport(summary="good"), + tool_name="send_feedback", + arguments={}, + ) + await record_tools_list( + data, session_id, names=["a"], request={"method": "tools/list"} + ) + for event_type, method in ( + (MCPAnalyticsEventType.MCP_RESOURCES_LIST, "resources/list"), + (MCPAnalyticsEventType.MCP_RESOURCES_READ, "resources/read"), + ): + await record_resource_request( + data, + session_id, + event_type=event_type, + request={"method": method, "params": {"uri": "file:///a"}}, + ) + await flush_background() + + +_EVERY_AUTO_CAPTURED_EVENT = [ + PostHogMCPAnalyticsEvent.INITIALIZE, + PostHogMCPAnalyticsEvent.INITIALIZE, + PostHogMCPAnalyticsEvent.TOOL_CALL, + PostHogMCPAnalyticsEvent.EXCEPTION, + PostHogMCPAnalyticsEvent.MISSING_CAPABILITY, + PostHogMCPAnalyticsEvent.FEEDBACK, + PostHogMCPAnalyticsEvent.TOOLS_LIST, + PostHogMCPAnalyticsEvent.RESOURCES_LIST, + PostHogMCPAnalyticsEvent.RESOURCE_READ, +] + + +def _sync_options(request, extra): + return {"process_person_profile": True, "cookieless_mode": True} + + +async def _async_options(request, extra): + return _sync_options(request, extra) + + +@pytest.mark.parametrize("callback", [_sync_options, _async_options]) +@pytest.mark.parametrize( + "identified, expected", + [ + (True, {"process_person_profile": True, "cookieless_mode": True}), + (False, {"process_person_profile": False, "cookieless_mode": True}), + ], + ids=["identified", "anonymous"], +) +async def test_event_options_callback_applies_to_every_auto_captured_event( + callback, identified, expected +): + requests = [] + + def recording(request, extra): + requests.append(request.get("method")) + return callback(request, extra) + + client = FakeClient() + data = MCPAnalyticsData( + options=MCPAnalyticsOptions(event_options=recording), + sink=McpEventSink(client), + ) + if identified: + for session_id in ("ses_abc", "ses_first"): + data.identified_sessions.set(session_id, UserIdentity("user_1")) + + await _record_every_event_type(data, "ses_abc") + + assert [e["event"] for e in client.events] == _EVERY_AUTO_CAPTURED_EVENT + assert [e["options"] for e in client.events] == [expected] * len(client.events) + # One call per MCP request, with that request. + assert requests == [ + "initialize", + "initialize", + "tools/call", + "tools/call", + "tools/call", + "tools/list", + "resources/list", + "resources/read", + ] + + +def _raise(request, extra): + raise RuntimeError("callback failed") + + +@pytest.mark.parametrize( + "callback, log_line", + [ + ( + lambda request, extra: "nope", + "The event_options callback result must be a dict, got str. " + "Sending the event without them.", + ), + ( + lambda request, extra: 0, + "The event_options callback result must be a dict, got int. " + "Sending the event without them.", + ), + (_raise, "event_options callback error: callback failed"), + ], + ids=["non_dict", "falsy_non_dict", "raises"], +) +async def test_failed_event_options_callback_still_sends_events(callback, log_line): + logged = [] + set_logger(logged.append) + try: + client = FakeClient() + data = MCPAnalyticsData( + options=MCPAnalyticsOptions(event_options=callback), + sink=McpEventSink(client), + ) + await _record_every_event_type(data, "ses_abc") + finally: + set_logger(None) + + assert [e["event"] for e in client.events] == _EVERY_AUTO_CAPTURED_EVENT + assert [e["options"] for e in client.events] == [ + {"process_person_profile": False} + ] * len(client.events) + assert log_line in logged + + +class _ServerKey: + """A weakly referenceable stand-in for an instrumented server.""" + + +@pytest.mark.parametrize( + "identified, expected", + [ + (True, {"cookieless_mode": True, "process_person_profile": True}), + (False, {"cookieless_mode": True, "process_person_profile": False}), + ], + ids=["identified", "anonymous"], +) +async def test_analytics_capture_sends_event_options(identified, expected): + client = FakeClient() + key = _ServerKey() + data = MCPAnalyticsData( + options=MCPAnalyticsOptions(), sink=McpEventSink(client), session_id="ses" + ) + if identified: + data.identified_sessions.set("ses", UserIdentity("user_1")) + set_server_tracking_data(key, data) + + await McpAnalytics(key).capture( + "feedback_submitted", + {"rating": 5}, + event_options={"cookieless_mode": True, "process_person_profile": True}, + ) + + [event] = client.events + assert event["event"] == "feedback_submitted" + assert event["options"] == expected + + +async def test_noop_analytics_capture_accepts_event_options(): + assert ( + await _NoopAnalytics().capture("e", event_options={"cookieless_mode": True}) + is None + ) diff --git a/posthog/test/mcp/test_posthog_mcp.py b/posthog/test/mcp/test_posthog_mcp.py index 7d8cd66c5..720a5a56f 100644 --- a/posthog/test/mcp/test_posthog_mcp.py +++ b/posthog/test/mcp/test_posthog_mcp.py @@ -10,6 +10,7 @@ from mcp.types import CallToolResult, ServerResult, TextContent, Tool from posthog.mcp import ( + FeedbackReport, PostHogMCP, PreparedToolCall, derive_session_id_from_conversation, @@ -118,6 +119,75 @@ def test_mcp_client_keeps_the_sdk_identity(): assert send.call_args.kwargs["sdk_info"] == f"posthog-python/{VERSION}" +_CAPTURE_METHODS = [ + ("capture_tool_call", ("search",), {}, "$mcp_tool_call"), + ("capture_initialize", (), {}, "$mcp_initialize"), + ("capture_tools_list", (), {"tool_names": ["a"]}, "$mcp_tools_list"), + ("capture_missing_capability", (), {}, "$mcp_missing_capability"), + ( + "capture_feedback", + (), + {"report": FeedbackReport(summary="good")}, + "$mcp_feedback", + ), +] + + +@pytest.mark.parametrize( + "method, args, kwargs, event_name", + _CAPTURE_METHODS, + ids=[m[0] for m in _CAPTURE_METHODS], +) +@pytest.mark.parametrize( + "distinct_id, expected", + [ + ("user_1", {"cookieless_mode": True, "process_person_profile": True}), + (None, {"cookieless_mode": True, "process_person_profile": False}), + ], + ids=["identified", "anonymous"], +) +async def test_capture_methods_send_event_options( + method, args, kwargs, event_name, distinct_id, expected +): + client, captured = make_client() + event_options = {"cookieless_mode": True, "process_person_profile": True} + getattr(client, method)( + *args, distinct_id=distinct_id, event_options=event_options, **kwargs + ) + await _flush() + + [event] = captured + assert event["event"] == event_name + assert event["options"] == expected + assert event_options == {"cookieless_mode": True, "process_person_profile": True} + + +async def test_capture_tool_call_event_options_reach_the_exception_sibling(): + client, captured = make_client() + client.capture_tool_call( + "broken", + is_error=True, + error=RuntimeError("kaboom"), + distinct_id="u", + event_options={"product_tour_id": "tour"}, + ) + await _flush() + + assert [(e["event"], e["options"]) for e in captured] == [ + ("$mcp_tool_call", {"product_tour_id": "tour"}), + ("$exception", {"product_tour_id": "tour"}), + ] + + +async def test_capture_methods_pass_empty_options_without_event_options(): + client, captured = make_client() + client.capture_tool_call("search", distinct_id="u") + await _flush() + + [event] = captured + assert event["options"] == {} + + async def test_capture_initialize_and_tools_list(): client, captured = make_client() client.capture_initialize( diff --git a/references/public_api_snapshot.txt b/references/public_api_snapshot.txt index c6d71aef6..315c83721 100644 --- a/references/public_api_snapshot.txt +++ b/references/public_api_snapshot.txt @@ -1078,6 +1078,7 @@ attribute posthog.mcp.types.MCPAnalyticsOptions.collect_feedback: Union[bool, Co attribute posthog.mcp.types.MCPAnalyticsOptions.context: Union[bool, MCPAnalyticsContextOptions] = True attribute posthog.mcp.types.MCPAnalyticsOptions.enable_conversation_id: bool = True attribute posthog.mcp.types.MCPAnalyticsOptions.enable_exception_autocapture: bool = True +attribute posthog.mcp.types.MCPAnalyticsOptions.event_options: Optional[EventOptionsFn] = None attribute posthog.mcp.types.MCPAnalyticsOptions.event_properties: Optional[EventPropertiesFn] = None attribute posthog.mcp.types.MCPAnalyticsOptions.identify: Optional[Union[IdentifyFn, UserIdentity]] = None attribute posthog.mcp.types.MCPAnalyticsOptions.intent_fallback: Optional[IntentFallbackFn] = None @@ -1354,7 +1355,7 @@ class posthog.mcp.types.CollectFeedbackOptions(tool_name: Optional[str] = None, class posthog.mcp.types.FeedbackReport(feedback_type: str = 'other', summary: str = '', sentiment: Optional[str] = None, friction_points: Optional[str] = None, suggested_improvement: Optional[str] = None, details: Optional[str] = None, tool_name: Optional[str] = None, task_completed: Optional[bool] = None, extras: JsonRecord = dict(), raw: JsonRecord = dict()) class posthog.mcp.types.MCPAnalyticsContextOptions(description: Optional[str] = None) class posthog.mcp.types.MCPAnalyticsModelOptions(description: Optional[str] = None) -class posthog.mcp.types.MCPAnalyticsOptions(logger: Optional[LoggerFn] = None, report_missing: bool = False, missing_capability_tool_name: Optional[str] = None, enable_conversation_id: bool = True, enable_exception_autocapture: bool = True, context: Union[bool, MCPAnalyticsContextOptions] = True, identify: Optional[Union[IdentifyFn, UserIdentity]] = None, intent_fallback: Optional[IntentFallbackFn] = None, before_send: Optional[BeforeSendFn] = None, event_properties: Optional[EventPropertiesFn] = None, capture_model: Union[bool, MCPAnalyticsModelOptions] = True, collect_feedback: Union[bool, CollectFeedbackOptions] = False, server_build: Optional[str] = None, should_record_input_key: Optional[ShouldRecordInputKeyFn] = None, resolve_input_aliases: Optional[ResolveInputAliasesFn] = None, resolve_original_tool: Optional[Callable[[str], Any]] = None, send_initialize_event: bool = True, send_tools_list_event: bool = True) +class posthog.mcp.types.MCPAnalyticsOptions(logger: Optional[LoggerFn] = None, report_missing: bool = False, missing_capability_tool_name: Optional[str] = None, enable_conversation_id: bool = True, enable_exception_autocapture: bool = True, context: Union[bool, MCPAnalyticsContextOptions] = True, identify: Optional[Union[IdentifyFn, UserIdentity]] = None, intent_fallback: Optional[IntentFallbackFn] = None, before_send: Optional[BeforeSendFn] = None, event_properties: Optional[EventPropertiesFn] = None, capture_model: Union[bool, MCPAnalyticsModelOptions] = True, collect_feedback: Union[bool, CollectFeedbackOptions] = False, server_build: Optional[str] = None, should_record_input_key: Optional[ShouldRecordInputKeyFn] = None, resolve_input_aliases: Optional[ResolveInputAliasesFn] = None, resolve_original_tool: Optional[Callable[[str], Any]] = None, send_initialize_event: bool = True, send_tools_list_event: bool = True, event_options: Optional[EventOptionsFn] = None) class posthog.mcp.types.PreparedToolCall(args: Optional[JsonRecord] = None, intent: Optional[str] = None, intent_source: Optional[str] = None, is_missing_capability: bool = False, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, is_feedback: bool = False, feedback_report: Optional[FeedbackReport] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, _conversation_state: Optional[PreparedConversationState] = None) class posthog.mcp.types.ToolInputOptions(should_record_input_key: Optional[ShouldRecordInputKeyFn] = None, input_aliases: Optional[InputAliasMap] = None) class posthog.mcp.types.UserIdentity(distinct_id: str, properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None) @@ -1874,14 +1875,14 @@ method posthog.integrations.django.PosthogContextMiddleware.extract_tags(request method posthog.integrations.django.PosthogContextMiddleware.process_exception(request, exception) method posthog.integrations.flask.PosthogFlaskIntegration.init_app(app: Flask) -> None method posthog.integrations.otel.PostHogContextSpanProcessor.on_start(span: Span, parent_context: Optional[Context] = None) -> None -method posthog.mcp.McpAnalytics.capture(event: str, properties: Optional[dict] = None) -> None +method posthog.mcp.McpAnalytics.capture(event: str, properties: Optional[dict] = None, *, event_options: Optional[Dict[str, Any]] = None) -> None method posthog.mcp.McpAnalytics.flush() -> None method posthog.mcp.posthog_mcp.PostHogMCP.capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] -method posthog.mcp.posthog_mcp.PostHogMCP.capture_feedback(*, report: FeedbackReport, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None -method posthog.mcp.posthog_mcp.PostHogMCP.capture_initialize(*, client_name: Optional[str] = None, client_version: Optional[str] = None, protocol_version: Optional[str] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None -method posthog.mcp.posthog_mcp.PostHogMCP.capture_missing_capability(*, context: Optional[str] = None, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, parameters: Any = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None -method posthog.mcp.posthog_mcp.PostHogMCP.capture_tool_call(tool_name: str, *, intent: Optional[str] = None, intent_source: Optional[str] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, is_error: bool = False, error: Any = None, error_type: Optional[str] = None, category: Optional[str] = None, tool_description: Optional[str] = None, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None -method posthog.mcp.posthog_mcp.PostHogMCP.capture_tools_list(*, tool_names: Optional[List[str]] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, is_error: bool = False, error: Any = None, error_type: Optional[str] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_feedback(*, report: FeedbackReport, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_initialize(*, client_name: Optional[str] = None, client_version: Optional[str] = None, protocol_version: Optional[str] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_missing_capability(*, context: Optional[str] = None, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, parameters: Any = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_tool_call(tool_name: str, *, intent: Optional[str] = None, intent_source: Optional[str] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, is_error: bool = False, error: Any = None, error_type: Optional[str] = None, category: Optional[str] = None, tool_description: Optional[str] = None, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_tools_list(*, tool_names: Optional[List[str]] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, is_error: bool = False, error: Any = None, error_type: Optional[str] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None method posthog.mcp.posthog_mcp.PostHogMCP.flush(timeout_seconds: Optional[float] = 10) -> None method posthog.mcp.posthog_mcp.PostHogMCP.prepare_tool_call(name: str, args: Optional[JsonRecord] = None, *, request_meta: Optional[JsonRecord] = None, original_tool: Any = None, session_id: Optional[str] = None) -> PreparedToolCall method posthog.mcp.posthog_mcp.PostHogMCP.prepare_tool_list(tools: List[Any], context: Union[bool, MCPAnalyticsContextOptions] = True, report_missing: bool = False, collect_feedback: bool = False) -> List[Any] From fc264cd23ba5fc2325ce647c1d7a92db79279828 Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Sat, 7 Nov 2026 17:39:43 -0800 Subject: [PATCH 2/3] docs(mcp): document MCP event_options Covers the per-call argument and the callback, why context options set inside a tool handler miss $mcp_tool_call, copying options in MCP before_send, and the options vs event_options split on PostHogMCP. Co-Authored-By: Claude Opus 5.5 --- docs/migration-7.x-to-8.0.md | 46 ++++++++++++++++++++++++++++++++--- posthog/mcp/README.md | 47 ++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 4 deletions(-) diff --git a/docs/migration-7.x-to-8.0.md b/docs/migration-7.x-to-8.0.md index 8b63cea08..40dd58dfc 100644 --- a/docs/migration-7.x-to-8.0.md +++ b/docs/migration-7.x-to-8.0.md @@ -18,10 +18,10 @@ 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)) +- 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)) +- 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)) - captures `$ai_` events with `capture()`: send them with `capture_ai()` - tests the AI integrations with a mock client and asserts on `capture` - passes its own client object to the AI integrations @@ -202,6 +202,8 @@ 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)). + - `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. - 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. @@ -258,10 +260,9 @@ 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 pass. 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. It wins over `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`. -- MCP's `PostHogCaptureEvent` has an `options` key. - 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 @@ -273,6 +274,43 @@ These changes follow from this order: - `AsyncPosthog` sends events with `requests` in a worker thread. It uses `httpx` only for feature flags and remote config. - `AsyncPosthog` accepts `privacy_mode` and `enable_full_ai_capture`, with the same meaning as on `Client`. An AI integration given an `AsyncPosthog` client used to always truncate and redact media. +## MCP analytics + +MCP events take options like other events, through an `event_options` argument and an `event_options` callback. + +- The `PostHogMCP` capture methods (`capture_tool_call`, `capture_initialize`, `capture_tools_list`, `capture_missing_capability` and `capture_feedback`) and `McpAnalytics.capture`, on the handle `instrument()` returns, take an `event_options` argument. It sets options on that event. For a failed tool call, it also sets them on the `$exception` event. +- `MCPAnalyticsOptions(event_options=...)` sets options on every event `instrument()` captures automatically, including `$exception` events. It does not apply to `McpAnalytics.capture`. Like `event_properties`, it is a function of `(request, extra)` that returns a dict or `None`, and it can be sync or async. +- `PostHogMCP.capture()` is the core client's `capture`, so it takes `options`. The MCP capture methods take `event_options`. +- The SDK passes these options as the event's own options, so they win over context options and `super_options`. +- An event without an identity always sends `process_person_profile: False`, even when `event_options` sets it to `True`. Its distinct ID is the session ID, so person processing would create a person for each session. To process a person, identify the user with `identify` or pass `distinct_id`. +- An `event_options` value that is not a dict is logged and ignored. The event is still sent. + +```python +from posthog.mcp import MCPAnalyticsOptions, PostHogMCP, instrument + +instrument( + server, + posthog, + MCPAnalyticsOptions(event_options=lambda request, extra: {"cookieless_mode": True}), +) + +mcp_client = PostHogMCP("phc_...") +mcp_client.capture_tool_call( + "search_docs", + distinct_id="user-1", + event_options={"process_person_profile": False}, +) +``` + +`instrument()` captures `$mcp_tool_call` after the tool handler returns. +A context you open inside the handler has ended by then, so options you set in it with `set_context_option` do not reach `$mcp_tool_call`. +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. + ## Batching and size limits - An analytics event over 10 MiB is dropped and logged, because no capture request can carry it. 7.x dropped events over 900 KiB. Capture drops an event over its own per-event limit and reports it in `CaptureError.drops` as `event_too_big`. diff --git a/posthog/mcp/README.md b/posthog/mcp/README.md index 316ab2637..474c29c23 100644 --- a/posthog/mcp/README.md +++ b/posthog/mcp/README.md @@ -103,6 +103,53 @@ keep their injected arguments, and the virtual tools stay listed. SDK has no request context for it, so `extra["ctx"]` carries only `.request`. `get_request_headers(extra)` works the same as for any other request. +## Event options + +Set capture options, such as `cookieless_mode` or `process_person_profile`, on +MCP events with `event_options`. + +`MCPAnalyticsOptions(event_options=...)` sets options on every event +`instrument()` captures automatically, including `$exception` events. Like +`event_properties`, it is a function of `(request, extra)` that returns a dict or +`None`, and it can be sync or async: + +```python +instrument( + server, + posthog, + MCPAnalyticsOptions(event_options=lambda request, extra: {"cookieless_mode": True}), +) +``` + +The `PostHogMCP` capture methods and `McpAnalytics.capture` take an +`event_options` argument for one event: + +```python +await analytics.capture("report_exported", event_options={"cookieless_mode": True}) + +mcp_client = PostHogMCP("phc_...") +mcp_client.capture_tool_call( + "search_docs", + distinct_id="user-1", + event_options={"process_person_profile": False}, +) +``` + +`PostHogMCP.capture()` is the core client's `capture`, so it takes `options` +instead. + +An event without an identity always sends `process_person_profile: False`, even +when `event_options` sets it to `True`. An `event_options` value that is not a +dict is logged and ignored. + +`$mcp_tool_call` is captured after the tool handler returns, so options set with +`set_context_option` in a context opened inside the handler do not reach it. Use +the `event_options` callback instead. + +`before_send` sees each event's `options`. A hook that returns a new dict must +copy `options`, or the event is sent without them, including the +`process_person_profile: False` set for an event without an identity. + ## Capture safe input field names Tool-call events include `$mcp_input_keys`. The SDK records names from the From 2e020ede8bc7672352fe5e165581a44f17f728c8 Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Mon, 9 Nov 2026 15:40:34 -0800 Subject: [PATCH 3/3] feat(celery): propagate context options to workers (#1207) * feat(celery): propagate context options to workers Publish context options in an X-POSTHOG-CONTEXT-OPTIONS task header, next to the tags header, and set them as context options on the worker before the task started event. propagate_context=False sends none. Co-Authored-By: Claude Opus 5.5 * docs(celery): point eager tasks to explicit PostHog headers Co-Authored-By: Claude Opus 5.5 * feat(ai): take capture options in the AI integrations (#1208) * feat(ai): take capture options in the AI integrations Every AI wrapper method that takes posthog_properties also takes posthog_options, and the Gemini clients take it as a per-client default. LangChain's CallbackHandler and PostHogMiddleware, and the OpenAI Agents and Claude Agent SDK instrument() and processors, take options=. LangChain also reads posthog_options from run metadata. The wrappers never pass posthog_options to the provider. The options are sent as the event's own options, below the personless process_person_profile: False. A value that is not a dict is logged and ignored, and no options argument is passed when none are set. Co-Authored-By: Claude Opus 5.5 * fix(ai): send LangChain exception events with the run's options Co-Authored-By: Claude Opus 5.5 * docs(migration): simplify the 8.0 checklist and MCP hook note Co-Authored-By: Claude Opus 5.5 * fix(ai): pass exception options as a typed keyword Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .sampo/changesets/ai-posthog-options.md | 5 + .sampo/changesets/celery-context-options.md | 5 + docs/migration-7.x-to-8.0.md | 37 ++- 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 | 34 ++- 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/integrations/celery.py | 29 +- 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 | 117 ++++++++ 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 ++++ .../integrations/test_celery_integration.py | 227 ++++++++++++++- references/public_api_snapshot.txt | 84 +++--- 32 files changed, 1554 insertions(+), 76 deletions(-) create mode 100644 .sampo/changesets/ai-posthog-options.md create mode 100644 .sampo/changesets/celery-context-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/.sampo/changesets/celery-context-options.md b/.sampo/changesets/celery-context-options.md new file mode 100644 index 000000000..8f4dda567 --- /dev/null +++ b/.sampo/changesets/celery-context-options.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: minor +--- + +The Celery integration propagates context options from the publisher to the worker, like tags. Options set with `set_context_option` before a task is published apply to every event captured while the task runs. `propagate_context=False` sends none of them. diff --git a/docs/migration-7.x-to-8.0.md b/docs/migration-7.x-to-8.0.md index 40dd58dfc..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)) @@ -202,10 +201,13 @@ 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. +- 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](../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. @@ -260,9 +262,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. 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`. + + ```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 @@ -307,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 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..57d2daeb4 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: @@ -569,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: @@ -586,10 +600,14 @@ 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( - 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( @@ -597,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 or None, ) if exception_id: event_properties["$exception_event_id"] = exception_id @@ -689,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 @@ -754,6 +780,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/integrations/celery.py b/posthog/integrations/celery.py index c11117922..c71d816c3 100644 --- a/posthog/integrations/celery.py +++ b/posthog/integrations/celery.py @@ -10,8 +10,8 @@ queue, retry count, duration, Celery version etc. - Any custom events captured inside a task (via ``client.capture``) are automatically enriched with the same Celery-specific properties via context tags. -- Propagates PostHog context (distinct ID, session ID, tags) from the producer - process to the worker process. +- Propagates PostHog context (distinct ID, session ID, tags, context options) + from the producer process to the worker process. Supports Celery 4.0+ (Message Protocol Version 2). @@ -82,6 +82,7 @@ CONTEXT_DISTINCT_ID_HEADER = "X-POSTHOG-DISTINCT-ID" CONTEXT_SESSION_ID_HEADER = "X-POSTHOG-SESSION-ID" CONTEXT_TAGS_HEADER = "X-POSTHOG-CONTEXT-TAGS" +CONTEXT_OPTIONS_HEADER = "X-POSTHOG-CONTEXT-OPTIONS" logger = logging.getLogger("posthog") @@ -101,8 +102,8 @@ class PosthogCeleryIntegration: capture_task_lifecycle_events: Whether to emit lifecycle events of the task such as "started", "success", "failure" etc. (default ``True``). propagate_context: Whether to propagate PostHog context (distinct - ID, session ID, tags) from the producer to the worker via task - headers (default ``True``). + ID, session ID, tags, context options) from the producer to the + worker via task headers (default ``True``). task_filter: Optional callback ``(task_name, task_properties) -> bool`` expected to return ``False`` if a given task should not be tracked. """ @@ -228,6 +229,7 @@ def _on_before_task_publish(self, *args, **kwargs): distinct_id = contexts.get_context_distinct_id() session_id = contexts.get_context_session_id() tags = contexts.get_tags() + options = contexts.get_context_options() posthog_headers: dict[str, str] = {} if distinct_id: @@ -236,6 +238,10 @@ def _on_before_task_publish(self, *args, **kwargs): posthog_headers[CONTEXT_SESSION_ID_HEADER] = session_id if tags: posthog_headers[CONTEXT_TAGS_HEADER] = json.dumps(tags, default=str) + if options: + posthog_headers[CONTEXT_OPTIONS_HEADER] = json.dumps( + options, default=str + ) if posthog_headers: headers.update(posthog_headers) @@ -293,6 +299,7 @@ def _on_task_prerun(self, *args, **kwargs): sender = kwargs.get("sender") request = getattr(sender, "request", None) context_tags = self._extract_propagated_tags(request) + context_options = self._extract_propagated_options(request) task_properties = self._build_task_properties( sender=sender, task_id=task_id, @@ -316,6 +323,8 @@ def _on_task_prerun(self, *args, **kwargs): merged_tags = {**task_properties, **context_tags} for key, value in merged_tags.items(): contexts.tag(key, value) + for key, value in context_options.items(): + contexts.set_context_option(key, value) if self.capture_task_lifecycle_events and self._should_track( task_name, task_properties @@ -420,14 +429,20 @@ def _apply_propagated_identity(self, request: Any) -> None: contexts.set_context_session(str(session_id)) def _extract_propagated_tags(self, request: Any) -> dict[str, Any]: + return self._extract_propagated_json(request, CONTEXT_TAGS_HEADER) + + def _extract_propagated_options(self, request: Any) -> dict[str, Any]: + return self._extract_propagated_json(request, CONTEXT_OPTIONS_HEADER) + + def _extract_propagated_json(self, request: Any, header: str) -> dict[str, Any]: headers = self._extract_headers(request) - raw_tags = headers.get(CONTEXT_TAGS_HEADER) - if not isinstance(raw_tags, (str, bytes, bytearray)): + raw = headers.get(header) + if not isinstance(raw, (str, bytes, bytearray)): return {} try: - parsed = json.loads(raw_tags) + parsed = json.loads(raw) except Exception: return {} 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..55e5dde6d 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 @@ -2812,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() @@ -3076,3 +3125,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/posthog/test/integrations/test_celery_integration.py b/posthog/test/integrations/test_celery_integration.py index 0e06314eb..ae558e586 100644 --- a/posthog/test/integrations/test_celery_integration.py +++ b/posthog/test/integrations/test_celery_integration.py @@ -1,11 +1,17 @@ +import json import unittest from types import ModuleType from types import SimpleNamespace from unittest.mock import Mock, patch +from parameterized import parameterized + from posthog import contexts +from posthog.capture_event import _to_v1_event +from posthog.client import Client from posthog.integrations.celery import ( CONTEXT_DISTINCT_ID_HEADER, + CONTEXT_OPTIONS_HEADER, CONTEXT_SESSION_ID_HEADER, CONTEXT_TAGS_HEADER, PosthogCeleryIntegration, @@ -206,19 +212,39 @@ def test_before_task_publish_propagates_context_headers(self): contexts.identify_context("distinct-123") contexts.set_context_session("session-456") contexts.tag("request_id", "abc") + contexts.set_context_option("cookieless_mode", True) integration._on_before_task_publish(sender="test.task", headers=headers) self.assertEqual(headers[CONTEXT_DISTINCT_ID_HEADER], "distinct-123") self.assertEqual(headers[CONTEXT_SESSION_ID_HEADER], "session-456") - self.assertIn(CONTEXT_TAGS_HEADER, headers) + self.assertEqual( + json.loads(headers[CONTEXT_TAGS_HEADER]), {"request_id": "abc"} + ) + self.assertEqual( + json.loads(headers[CONTEXT_OPTIONS_HEADER]), {"cookieless_mode": True} + ) # celery#4875: headers must also be nested inside headers["headers"] # so they survive to task.request.headers on the worker inner = headers["headers"] self.assertEqual(inner[CONTEXT_DISTINCT_ID_HEADER], "distinct-123") self.assertEqual(inner[CONTEXT_SESSION_ID_HEADER], "session-456") - self.assertIn(CONTEXT_TAGS_HEADER, inner) + self.assertEqual(json.loads(inner[CONTEXT_TAGS_HEADER]), {"request_id": "abc"}) + self.assertEqual( + json.loads(inner[CONTEXT_OPTIONS_HEADER]), {"cookieless_mode": True} + ) + + def test_before_task_publish_skips_options_header_without_context_options(self): + integration = PosthogCeleryIntegration() + headers = {} + + with contexts.new_context(fresh=True): + contexts.tag("request_id", "abc") + integration._on_before_task_publish(sender="test.task", headers=headers) + + self.assertNotIn(CONTEXT_OPTIONS_HEADER, headers) + self.assertNotIn(CONTEXT_OPTIONS_HEADER, headers["headers"]) def test_before_task_publish_preserves_existing_nested_headers(self): integration = PosthogCeleryIntegration() @@ -240,6 +266,7 @@ def test_before_task_publish_nested_headers_round_trips_to_worker(self): contexts.identify_context("user-rt") contexts.set_context_session("sess-rt") contexts.tag("env", "test") + contexts.set_context_option("process_person_profile", False) integration._on_before_task_publish(sender="test.task", headers=headers) # Simulate Celery worker: task.request.headers is the nested dict @@ -256,6 +283,9 @@ def test_before_task_publish_nested_headers_round_trips_to_worker(self): self.assertEqual(contexts.get_context_distinct_id(), "user-rt") self.assertEqual(contexts.get_context_session_id(), "sess-rt") self.assertEqual(contexts.get_tags().get("env"), "test") + self.assertEqual( + contexts.get_context_options(), {"process_person_profile": False} + ) # close out the task lifecycle so the test doesn't leave context hanging around integration._on_task_success(sender=task) @@ -268,6 +298,7 @@ def test_before_task_publish_respects_propagate_context_flag(self): contexts.identify_context("distinct-123") contexts.set_context_session("session-456") contexts.tag("request_id", "abc") + contexts.set_context_option("process_person_profile", False) integration._on_before_task_publish(sender="test.task", headers=headers) @@ -709,10 +740,194 @@ def test_prerun_exits_context_on_failure_after_entry(self): ctx_after = contexts._get_current_context() self.assertIs(ctx_after, ctx_before) - def test_extract_propagated_tags_invalid_json_returns_empty_dict(self): + @parameterized.expand( + [ + ("tags", CONTEXT_TAGS_HEADER, "_extract_propagated_tags"), + ("options", CONTEXT_OPTIONS_HEADER, "_extract_propagated_options"), + ] + ) + def test_extract_propagated_header_invalid_json_returns_empty_dict( + self, _name, header, extractor + ): integration = PosthogCeleryIntegration() - request = SimpleNamespace(headers={CONTEXT_TAGS_HEADER: "{bad json"}) + request = SimpleNamespace(headers={header: "{bad json"}) + + self.assertEqual(getattr(integration, extractor)(request), {}) + + +def _set_producer_context(distinct_id=None, tags=None, options=None): + if distinct_id: + contexts.identify_context(distinct_id) + for key, value in (tags or {}).items(): + contexts.tag(key, value) + for key, value in (options or {}).items(): + contexts.set_context_option(key, value) + + +class TestCeleryContextOptionsOnTheWire(unittest.TestCase): + """Checks the options worker events send, through a real client.""" + + def _client(self, **kwargs): + sent = [] + client = Client( + "phc_test", + send=False, + before_send=lambda msg: sent.append(msg) or msg, + **kwargs, + ) + return client, sent + + def _worker_task(self, headers): + request = SimpleNamespace( + headers=headers, delivery_info={}, hostname="worker-1", retries=0 + ) + return SimpleNamespace(name="app.tasks.example", request=request) + + def _run_worker(self, integration, client, headers, in_task=None): + task = self._worker_task(headers) + integration._on_task_prerun(sender=task, task_id="task-1") + if in_task: + in_task() + client.capture("in task") + integration._on_task_success(sender=task) + + def _publish_and_run( + self, producer, super_options=None, in_task=None, propagate_context=True + ): + kwargs = {"super_options": super_options} if super_options else {} + client, sent = self._client(**kwargs) + integration = PosthogCeleryIntegration( + client=client, propagate_context=propagate_context + ) + headers = {} + with contexts.new_context(fresh=True, client=client): + _set_producer_context(**producer) + integration._on_before_task_publish(sender="t", headers=headers) + self._run_worker(integration, client, headers.get("headers", {}), in_task) + return { + event["event"]: event["options"] + for event in (_to_v1_event(msg) for msg in sent) + } + + @parameterized.expand( + [ + ( + "all_four_options", + { + "distinct_id": "user-1", + "options": { + "process_person_profile": False, + "cookieless_mode": True, + "disable_skew_correction": True, + "product_tour_id": "tour-1", + }, + }, + None, + { + "process_person_profile": False, + "cookieless_mode": True, + "disable_skew_correction": True, + "product_tour_id": "tour-1", + }, + ), + ( + "option_beats_legacy_tag_on_same_key", + { + "distinct_id": "user-1", + "tags": {"$process_person_profile": True}, + "options": {"process_person_profile": False}, + }, + None, + {"process_person_profile": False}, + ), + ( + "legacy_tag_only", + {"distinct_id": "user-1", "tags": {"$process_person_profile": False}}, + None, + {"process_person_profile": False}, + ), + ( + "context_option_beats_worker_super_options", + {"distinct_id": "user-1", "options": {"cookieless_mode": False}}, + {"cookieless_mode": True}, + {"cookieless_mode": False}, + ), + ( + "personless_process_person_profile_true", + {"options": {"process_person_profile": True}}, + None, + {"process_person_profile": True}, + ), + ] + ) + def test_worker_events_send_propagated_options( + self, _name, producer, super_options, expected + ): + options_by_event = self._publish_and_run(producer, super_options) + + self.assertEqual( + options_by_event, + { + "celery task started": expected, + "in task": expected, + "celery task success": expected, + }, + ) - tags = integration._extract_propagated_tags(request) + def test_option_set_inside_task_overrides_propagated_option(self): + options_by_event = self._publish_and_run( + {"distinct_id": "user-1", "options": {"process_person_profile": False}}, + in_task=lambda: contexts.set_context_option("process_person_profile", True), + ) - self.assertEqual(tags, {}) + self.assertEqual( + options_by_event, + { + "celery task started": {"process_person_profile": False}, + "in task": {"process_person_profile": True}, + "celery task success": {"process_person_profile": True}, + }, + ) + + @parameterized.expand( + [ + ("missing", None, {}), + ("bad_json", "{bad json", {}), + ("not_an_object", '["cookieless_mode"]', {}), + ("bytes", b'{"cookieless_mode": true}', {"cookieless_mode": True}), + ] + ) + def test_worker_handles_options_header(self, _name, raw, expected): + client, sent = self._client() + integration = PosthogCeleryIntegration(client=client) + headers = {CONTEXT_DISTINCT_ID_HEADER: "user-1"} + if raw is not None: + headers[CONTEXT_OPTIONS_HEADER] = raw + + self._run_worker(integration, client, headers) + + self.assertEqual( + [(msg["event"], _to_v1_event(msg)["options"]) for msg in sent], + [ + ("celery task started", expected), + ("in task", expected), + ("celery task success", expected), + ], + ) + + def test_propagate_context_false_sends_no_options(self): + options_by_event = self._publish_and_run( + {"distinct_id": "user-1", "options": {"cookieless_mode": True}}, + propagate_context=False, + ) + + # The distinct ID is not propagated either, so worker events are personless. + personless = {"process_person_profile": False} + self.assertEqual( + options_by_event, + { + "celery task started": personless, + "in task": personless, + "celery task success": personless, + }, + ) 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