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/.sampo/changesets/lib-is-an-sdk-value.md b/.sampo/changesets/lib-is-an-sdk-value.md new file mode 100644 index 000000000..160010a2a --- /dev/null +++ b/.sampo/changesets/lib-is-an-sdk-value.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +Events send `$lib` and `$lib_version` as they are at send time, whoever set them. If no `$lib` is set in the call's `properties`, a context tag or `super_properties`, the SDK sets both to `posthog-python` and the installed version. If `$lib` is `posthog-python` and `$lib_version` is missing, the SDK fills in the version. A `$lib` that names another library is sent with whatever `$lib_version` it has, so set both when you override them. Only a non-empty string counts as set. In 7.x the SDK overwrote a `$lib` or `$lib_version` set in a call or a context tag. `before_send` can still change or remove both, and `AsyncPosthog` follows the same rules. 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/.sampo/changesets/mcp-keeps-sdk-identity.md b/.sampo/changesets/mcp-keeps-sdk-identity.md index 731c7faab..a1987b481 100644 --- a/.sampo/changesets/mcp-keeps-sdk-identity.md +++ b/.sampo/changesets/mcp-keeps-sdk-identity.md @@ -2,4 +2,4 @@ pypi/posthog: major --- -MCP instrumentation no longer relabels the client as `posthog-python-mcp`. `posthog.mcp.instrument()` and `PostHogMCP` used to change `$lib`, the `PostHog-Sdk-Info` header and the feature flag request `User-Agent` for every event the client sent, including the app's own events. All events now report `posthog-python`. Filter MCP traffic on the `$mcp_*` events and properties. +MCP instrumentation no longer relabels the whole client. In 7.x, `posthog.mcp.instrument()` and `PostHogMCP` changed `$lib` on every event the client sent, including the app's own, and the SDK name in its request headers, feature flag requests included. `instrument()` without a client relabeled the global client. Now only MCP analytics events report `posthog-python-mcp`, and everything else reports `posthog-python`. The label is set in each MCP event's own properties, so a `$lib` in `super_properties` no longer replaces it; `before_send` can. diff --git a/docs/migration-7.x-to-8.0.md b/docs/migration-7.x-to-8.0.md index 6bbfd06bb..071fdf0f7 100644 --- a/docs/migration-7.x-to-8.0.md +++ b/docs/migration-7.x-to-8.0.md @@ -18,13 +18,14 @@ 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` to turn person processing on for events without a distinct ID -- passes strings such as `"true"` for `$cookieless_mode`, `$ignore_sent_at` or `$process_person_profile` - 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)) +- 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 -- sets `$lib` or `$lib_version`, or filters on `$lib = "posthog-python-mcp"` +- sets `$lib` or `$lib_version` in a call's `properties`, a context tag or `super_properties` +- filters insights or dashboards on `$lib = posthog-python-mcp` - passes a personal API key (`phx_...`) as the project API key - reads event content from the SDK's debug log - calls `alias()` without a `distinct_id` and relies on the context distinct ID @@ -34,11 +35,12 @@ You need to change code if your app does any of these: | Method | Endpoint | | --- | --- | -| `capture`, `set`, `set_once`, `alias`, `group_identify`, `capture_exception` | `/i/v1/analytics/events` | +| `capture`, `set`, `set_once`, `alias`, `group_identify`, `capture_exception`, `AsyncPosthog.capture_immediate` | `/i/v1/analytics/events` | | `capture_ai`, `capture_ai_immediate`, and the AI wrapper integrations | `/i/v1/ai/events` | | OpenTelemetry (`posthog.ai.otel`) | `/i/v0/ai/otel`, unchanged | -If you send events to a self-hosted PostHog, check that it serves both endpoints before you upgrade. +If you send events to a self-hosted PostHog, check that it serves both `/i/v1/analytics/events` and `/i/v1/ai/events` before you upgrade. +Self-hosted PostHog serves the AI endpoint from a separate capture service, so check each route. An endpoint that is not served drops every event sent to it. If you send events through your own reverse proxy, update it before you upgrade: @@ -56,15 +58,32 @@ If a proxy redirects capture requests to another host, point `host` at the final ## SDK identity -PostHog sets `$lib` and `$lib_version` on every event from the `PostHog-Sdk-Info` request header, which is always `posthog-python/`. -The SDK removes `$lib` and `$lib_version` from the properties it sends. -A value you set in a call, in `super_properties` or in `before_send` does not reach PostHog. +By default every event carries `$lib: "posthog-python"` and the installed package version in `$lib_version`. +PostHog stores the values the event is sent with. -MCP instrumentation no longer relabels the client. -In 7.x, `posthog.mcp.instrument()` and `PostHogMCP` set the client's identity to `posthog-python-mcp`. -With the default client, or any client the app also used, every event and feature flag request from the app then reported `posthog-python-mcp`, not only the MCP events. -In 8.0, MCP events report `posthog-python` like all other events. -To find MCP traffic, filter on the `$mcp_*` events and properties instead of `$lib`. +You can set them in a call's `properties`, a context tag or `super_properties`. Like any other property, each one comes from the most specific place that sets it, so set both in the same place. +`$lib` and `$lib_version` count as set only when they are non-empty strings. +If you set `$lib` without `$lib_version`, the SDK adds its own version only when `$lib` is `posthog-python`. +A `$lib_version` without a `$lib` is replaced with the SDK's. +`before_send` sees both and can change or remove them. +In 7.x the SDK overwrote a `$lib` or `$lib_version` set in a call or a context tag. + +This changes `super_properties` too: + +- `super_properties={"$lib": "my-lib"}` sends no `$lib_version`. In 7.x it sent the SDK version. +- `super_properties={"$lib_version": "1.0"}` without a `$lib` sends the SDK's `$lib` and version. In 7.x it sent `1.0`. + +If an event reaches PostHog without `$lib`, PostHog fills both from the SDK name and version your request sends. +If `$lib` is that SDK name and `$lib_version` is missing, empty or not a string, PostHog fills `$lib_version` the same way. + +MCP analytics events from `posthog.mcp.instrument()` or `PostHogMCP` report `posthog-python-mcp` and the installed package version. +The integration sets both in each event's own properties, so neither a context tag nor `super_properties` replaces them. `before_send` can. +In 7.x the MCP integration relabeled the whole client, or the default client when `instrument()` got none: the app's own events, the request headers and feature flag requests. +In 8.0 those report `posthog-python`, so one client can serve both. + +Custom events from `PostHogMCP.capture()` now report `posthog-python`. In 7.x they reported `posthog-python-mcp`. +Custom events from `McpAnalytics.capture()`, the handle `instrument()` returns, still report `posthog-python-mcp`. +If an insight or dashboard filters on `$lib = posthog-python-mcp`, check that it still finds the events you expect. ## Removed options and APIs @@ -154,7 +173,7 @@ The SDK moves them out of `properties` for you. - `group_identify` no longer adds the context session ID. A session takes the person of its latest event, and this event's distinct ID is not the session's user. - `alias()` needs an explicit `distinct_id`. It no longer falls back to the context distinct ID, which can come from a request header the client controls. Without one, the call is dropped with a warning. - Context tags and context options now apply to `alias` and `group_identify`, below the call's own values, as they do for `capture`. -- Person processing turned off in the context, with `set_context_option("process_person_profile", False)` or a `$process_person_profile` tag, or in `super_options`, now applies to `$create_alias` and `$groupidentify` events too. A `$process_person_profile: False` in `super_properties` already did this in 7.x. PostHog drops these events when person processing is off, with an ingestion warning. Capture accepts them, so `on_error` does not report the drop. To keep them, turn person processing off per call instead. +- Person processing turned off in the context with `set_context_option("process_person_profile", False)`, or in `super_options`, now applies to `$create_alias` and `$groupidentify` events too. PostHog drops these events when person processing is off, with an ingestion warning. Capture accepts them, so `on_error` does not report the drop. To keep them, turn person processing off per call instead. ## Tracing headers @@ -182,21 +201,29 @@ 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)), 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. -- The legacy option properties, the `$`-prefixed properties legacy capture reads as settings, still work. They fill the matching option only when it is unset, and the SDK always removes them from `properties`. Their values are no longer converted, so pass `True` or `False`, not `"true"`. +- Each option replaces a legacy option property: - | Legacy option property | Option | + | Option | Replaces | | --- | --- | - | `$cookieless_mode` | `cookieless_mode` | - | `$ignore_sent_at` | `disable_skew_correction` | - | `$product_tour_id` | `product_tour_id` | - | `$process_person_profile` | `process_person_profile` | + | `cookieless_mode` | `$cookieless_mode` | + | `disable_skew_correction` | `$ignore_sent_at` | + | `product_tour_id` | `$product_tour_id` | + | `process_person_profile` | `$process_person_profile` | + + Legacy option properties still work, but an option overrides its legacy property. Use options. +- Pass `True` or `False` for `cookieless_mode`, `disable_skew_correction` and `process_person_profile`. PostHog also reads common forms such as `"false"`, `"off"` or `0`. -- An option set at any layer wins over its legacy property set at any layer. For example, `super_options={"cookieless_mode": True}` wins over an event's `$cookieless_mode: False`. When you move a default to options, move the per-event overrides of that key to options too. +- These four options are the full set. PostHog ignores any other key in `options`. Session and window IDs stay `$session_id` and `$window_id` properties (see [Session and window IDs](#session-and-window-ids)). - A `None` option counts as unset, so a later step can fill it. Values apply in this order. Steps 2 to 4 fill only the options and properties that the steps before them left unset: @@ -204,41 +231,62 @@ Values apply in this order. Steps 2 to 4 fill only the options and properties th 1. the `options` and `properties` of the call, then the call's `disable_geoip` argument, which fills `$geoip_disable` 2. context options and tags 3. `super_options` and `super_properties` -4. values the SDK sets: `$is_server` from `is_server`, `$geoip_disable` from the client's `disable_geoip` setting, system properties such as `$os` and `$python_version`, the `$feature/` and `$active_feature_flags` properties from `flags` or `send_feature_flags`, `$trace_id` and `$span_id` from the active OpenTelemetry span (in `capture` and `capture_ai` only with `capture_trace_context=True`, and always in `capture_exception`), `options.process_person_profile = false` for events without a distinct ID, and `$release_id` from `POSTHOG_RELEASE_ID` +4. values the SDK sets: `$lib` and `$lib_version` as a pair (see [SDK identity](#sdk-identity)), `$is_server` from `is_server`, `$geoip_disable` from the client's `disable_geoip` setting, system properties such as `$os` and `$python_version`, the `$feature/` and `$active_feature_flags` properties from `flags` or `send_feature_flags`, `$trace_id` and `$span_id` from the active OpenTelemetry span (in `capture` and `capture_ai` only with `capture_trace_context=True`, and always in `capture_exception`), `options.process_person_profile = false` for events without a distinct ID, and `$release_id` from `POSTHOG_RELEASE_ID` 5. `before_send`, which sees the result of steps 1 to 4 and can change or remove any of it -6. legacy properties, which fill unset options and are then removed A property set to `None` counts as set, so no later step fills it. +`$lib` and `$lib_version` are the exception: they count as set only when they are non-empty strings (see [SDK identity](#sdk-identity)). `$set`, `$set_once`, `$groups` and `$group_set` fill one level deep. When the call and a later step both set one of them to a dict, the later step adds only the keys the call left out. For example, `super_properties={"$set": {"plan": "free", "source": "web"}}` and a call with `properties={"$set": {"plan": "pro"}}` send `{"plan": "pro", "source": "web"}`. These changes follow from this order: -- Properties passed to a call now override `super_properties`. `super_properties` can no longer change `$lib` or `$lib_version`. -- A `$is_server`, `$geoip_disable` or system property such as `$os` that you set in a call or a context tag now wins over the SDK's value. In 7.x the SDK overwrote it. `super_properties` win over the SDK's value too, so `super_properties={"$geoip_disable": False}` turns GeoIP lookup on for events, even with `disable_geoip=True`. +- Properties passed to a call now override `super_properties`. +- A `$is_server`, `$geoip_disable`, `$lib`, `$lib_version` or system property such as `$os` that you set in a call or a context tag now wins over the SDK's value. In 7.x the SDK overwrote it. `super_properties` win over the SDK's value too, so `super_properties={"$geoip_disable": False}` turns GeoIP lookup on for events, even with `disable_geoip=True`. - Feature flag properties from `flags` or `send_feature_flags` still lose to the same key in the call's `properties`, a context tag or `super_properties`, as in 7.x. - A `$trace_id` or `$span_id` in a context tag or `super_properties` now replaces the active OpenTelemetry span's IDs. In 7.x the span's IDs beat context tags. Setting either key in the call's `properties`, a context tag or `super_properties` stops the SDK adding both. In 7.x the SDK still added the other key. - A `disable_geoip` argument to a call belongs to that event, so it wins over context tags and `super_properties`. A `$geoip_disable` in the call's own `properties` still wins over it. `disable_geoip=False` now sends `$geoip_disable: false`. In 7.x it sent no `$geoip_disable` property. - The `groups` argument merges into a `$groups` property of the call, and wins key by key. In 7.x it replaced the property. MCP events merge their identity's groups into a custom `$groups` property the same way. - A `$set`, `$set_once`, `$groups` or `$group_set` in `super_properties` no longer replaces the whole value of the call. The two merge, and the call wins key by key. -- An event without a distinct ID gets `options.process_person_profile = false`. A `$process_person_profile: true` property no longer turns person processing back on. Set the option instead. -- Review your `before_send` hooks for the new event shape. To change an option, edit `options`: a legacy property that `before_send` adds does not replace an option that is already set. A hook that returns a new dict must copy `options`, or the event is sent without them. That includes the `process_person_profile = false` the SDK sets for an event without a distinct ID, so PostHog would create a person for its generated ID. -- When the server enables minimal `$feature_flag_called` events, those events now keep `$window_id` and the legacy option properties, so their options still apply. +- An event without a distinct ID gets `options.process_person_profile = false`. To turn person processing on for it, set the `process_person_profile` option. +- Review your `before_send` hooks for the new event shape. To change an option, edit `options`. A hook that returns a new dict must copy `options`, or the event is sent without them. That includes the `process_person_profile = false` the SDK sets for an event without a distinct ID, so PostHog would create a person for its generated ID. +- When the server enables minimal `$feature_flag_called` events, those events now keep `$window_id`. Their options still apply, because the trim removes only properties. ## AI capture - `capture_ai` and the AI wrapper integrations send to `/i/v1/ai/events`. The AI endpoint accepts events up to 8 MiB. -- Send `$ai_` events with `capture_ai`. `capture()` sends every event to `/i/v1/analytics/events`, including `$ai_` events, which PostHog accepts there for now. +- Send `$ai_` events with `capture_ai`. `capture()` sends every event to `/i/v1/analytics/events`, including `$ai_` events. PostHog accepts them there for now, but this is temporary. - `capture_ai` sends any event name to the AI endpoint. PostHog drops an event whose name does not start with `$ai_` as `misrouted_event`, and `on_error` reports it. The SDK writes only a debug log. - The OpenTelemetry integration (`PostHogSpanProcessor`, `PostHogTraceExporter`) is unchanged: it still exports spans over OTLP to `/i/v0/ai/otel`. - `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`, context options and a `$process_person_profile: true` property. `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`, `super_options`, or a legacy property such as `$cookieless_mode` in `posthog_properties`. -- MCP's `PostHogCaptureEvent` has an `options` key. +- 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 @@ -250,6 +298,42 @@ 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` 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 - 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/__init__.py b/posthog/__init__.py index 0fb354749..22667f3f2 100644 --- a/posthog/__init__.py +++ b/posthog/__init__.py @@ -394,10 +394,7 @@ def get_context_options() -> Dict[str, Any]: super_options: Capture options for every captured event, such as ``{"cookieless_mode": True}``. They fill only options the event leaves unset, before ``before_send`` runs. An event's own ``options`` and - context options override them, and ``before_send`` can change them. They also - win over an event's legacy property for the same key, such as - ``$cookieless_mode``, so pass per-event overrides of that key as - ``options``. + context options override them, and ``before_send`` can change them. metrics: Config dict for the ``client.metrics`` API (``service_name``, ``service_version``, ``environment``, ``flush_interval``, ...). Applied when ``setup()`` builds the global client, or on a later ``setup()`` 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/async_client.py b/posthog/async_client.py index d3fb2a86f..2840e2b84 100644 --- a/posthog/async_client.py +++ b/posthog/async_client.py @@ -550,9 +550,7 @@ def _prepare_event( msg["timestamp"] = _rfc3339_timestamp(datetime.now(tz=timezone.utc)) sent_uuid = self._normalize_uuid(msg) - properties = msg.setdefault("properties", {}) - properties["$lib"] = "posthog-python" - properties["$lib_version"] = VERSION + msg.setdefault("properties", {}) msg["options"] = msg.get("options") or {} if property_allowlist is not None: @@ -625,6 +623,8 @@ def _event_defaults( system_properties=system_properties, flag_properties=flag_properties, trace_properties=trace_properties, + library_id="posthog-python", + library_version=VERSION, ) def _build_capture_event( diff --git a/posthog/capture_event.py b/posthog/capture_event.py index 5504496c3..42da0e554 100644 --- a/posthog/capture_event.py +++ b/posthog/capture_event.py @@ -14,8 +14,10 @@ - ``$set``/``$set_once`` have no top-level form in v1; the server reads them from ``properties``. The legacy ``set()``/``set_once()`` builders emit them at the top level, so they are relocated into ``properties`` here. -- ``$lib``/``$lib_version`` are injected server-side from the required - ``PostHog-Sdk-Info`` header and are stripped from v1 properties. +- ``$lib``/``$lib_version`` are sent as they are at send time. The SDK fills + them as a pair below every other layer, and ``before_send`` can change or + remove them. The ``PostHog-Sdk-Info`` header is only a server-side fallback + for events that don't name their library. """ import logging @@ -43,8 +45,8 @@ # Properties that defaults fill one level deep when both values are dicts. _NESTED_FILL_PROPERTIES = frozenset({"$set", "$set_once", "$groups", "$group_set"}) -# Properties dropped from v1 events (server injects them from PostHog-Sdk-Info). -_STRIP_FROM_PROPERTIES = ("$lib", "$lib_version") +# The library identity pair. Only a non-empty string counts as set. +_LIBRARY_PROPERTIES = ("$lib", "$lib_version") # Legacy properties and the option each one fills. The order matches posthog-rs # and posthog-go. @@ -134,6 +136,12 @@ class _EventDefaults: option_layers: tuple[Mapping[str, Any], ...] = () property_allowlist: Optional[Collection[str]] = None trace_properties: Optional[Mapping[str, Any]] = None + library: Optional[tuple[str, str]] = None + + +def _is_library_value(value: Any) -> bool: + """Whether ``value`` sets ``$lib`` or ``$lib_version``: a non-empty string.""" + return isinstance(value, str) and value != "" def _build_event_defaults( @@ -151,6 +159,8 @@ def _build_event_defaults( system_properties: Optional[Mapping[str, Any]] = None, flag_properties: Optional[Mapping[str, Any]] = None, trace_properties: Optional[Mapping[str, Any]] = None, + library_id: str, + library_version: str, ) -> _EventDefaults: """Order the layers: per-call arguments, context, global, then SDK values. @@ -161,6 +171,8 @@ def _build_event_defaults( ``send_feature_flags``) are SDK values, so context and super properties beat them. ``trace_properties`` (``$trace_id`` and ``$span_id`` from the active OpenTelemetry span) are SDK values that fill as a pair. + ``library_id`` and ``library_version`` are the SDK's own ``$lib`` and + ``$lib_version``. They fill as a pair below every other layer. """ call_properties = ( {} if call_disable_geoip is None else {"$geoip_disable": call_disable_geoip} @@ -188,6 +200,7 @@ def _build_event_defaults( ), property_allowlist=property_allowlist, trace_properties=trace_properties, + library=(library_id, library_version), ) @@ -196,11 +209,13 @@ def _fill_event_defaults( ) -> None: """Fill the keys an event left unset from ``defaults``, layer by layer. - A property is unset only when its key is missing. An option is unset when - it is missing or ``None``, the same rule hoisting uses. ``$set``, - ``$set_once``, ``$groups`` and ``$group_set`` fill one level deep when the - event's value and the default are both dicts. ``trace_properties`` fill - last, and only when the event and every layer leave all their keys unset. + A property is unset only when its key is missing, except ``$lib`` and + ``$lib_version``, which are unset unless they hold a non-empty string. An + option is unset when it is missing or ``None``, the same rule hoisting + uses. ``$set``, ``$set_once``, ``$groups`` and ``$group_set`` fill one + level deep when the event's value and the default are both dicts. + ``trace_properties`` fill last, and only when the event and every layer + leave all their keys unset. The SDK's ``library`` fills after every layer. """ if defaults is None: return @@ -213,7 +228,11 @@ def _fill_event_defaults( for key, value in property_layer.items(): if allowlist is not None and key not in allowlist: continue - if key not in properties: + if key not in properties or ( + key in _LIBRARY_PROPERTIES + and _is_library_value(value) + and not _is_library_value(properties[key]) + ): properties[key] = _clean(value) continue existing = properties[key] @@ -230,6 +249,8 @@ def _fill_event_defaults( for key, value in trace_properties.items(): if allowlist is None or key in allowlist: properties[key] = _clean(value) + if defaults.library is not None: + _fill_library(properties, defaults.library, allowlist) options = _event_options(msg.get("options")) for option_layer in defaults.option_layers: for key, value in option_layer.items(): @@ -238,6 +259,32 @@ def _fill_event_defaults( msg["options"] = options +def _fill_library( + properties: dict[str, Any], + library: tuple[str, str], + allowlist: Optional[Collection[str]], +) -> None: + """Fill the SDK's ``$lib`` and ``$lib_version`` as a pair. + + With no ``$lib`` set, both are filled, replacing a lone ``$lib_version``. + A ``$lib`` naming this SDK with no ``$lib_version`` gets the SDK version. + A ``$lib`` naming another library keeps whatever ``$lib_version`` it has, + because the SDK version would misdescribe it. + """ + library_id, library_version = library + if not _is_library_value(properties.get("$lib")): + fill = {"$lib": library_id, "$lib_version": library_version} + elif properties["$lib"] == library_id and not _is_library_value( + properties.get("$lib_version") + ): + fill = {"$lib_version": library_version} + else: + return + for key, value in fill.items(): + if allowlist is None or key in allowlist: + properties[key] = value + + def _merge_groups(properties: dict[str, Any], groups: Mapping[str, Any]) -> None: """Merge typed ``groups`` into the ``$groups`` property; ``groups`` wins key by key.""" existing = properties.get("$groups") @@ -282,9 +329,6 @@ def _to_v1_event(msg: dict) -> dict: else: properties[key] = top_val - for key in _STRIP_FROM_PROPERTIES: - properties.pop(key, None) - options = _event_options(msg.get("options")) for prop_key, option_key in _LEGACY_OPTION_PROPERTIES: if prop_key not in properties: diff --git a/posthog/client.py b/posthog/client.py index 7033e6bfd..b775b0d79 100644 --- a/posthog/client.py +++ b/posthog/client.py @@ -876,9 +876,7 @@ def __init__( ``{"cookieless_mode": True}``. They fill only options the event leaves unset, before ``before_send`` runs. An event's own ``options`` and context options override them, and - ``before_send`` can change them. They also win over an event's legacy property - for the same key, such as ``$cookieless_mode``, so pass - per-event overrides of that key as ``options``. + ``before_send`` can change them. enable_exception_autocapture: Automatically capture uncaught exceptions. log_captured_exceptions: Also log exceptions captured by error @@ -1889,9 +1887,8 @@ def capture( ``{"process_person_profile": False}``. Sent as given, for PostHog to validate. They override context options and ``super_options``, which fill in before ``before_send`` runs. - An option set at any layer wins over its - legacy ``$`` property, such as ``$process_person_profile``, - set at any layer. A ``None`` option counts as unset. + An option overrides its legacy ``$`` property, such as + ``$process_person_profile``. A ``None`` option counts as unset. Examples: ```python @@ -1947,7 +1944,7 @@ def capture_ai( Category: Capture """ - if not event.startswith("$ai_"): + if isinstance(event, str) and not event.startswith("$ai_"): self.log.debug( "capture_ai called with non-AI event name %r; routing it to the AI endpoint anyway.", event, @@ -2744,8 +2741,6 @@ def _enqueue( if not msg.get("properties"): msg["properties"] = {} - msg["properties"]["$lib"] = self._library_id - msg["properties"]["$lib_version"] = self._library_version msg["options"] = msg.get("options") or {} @@ -2765,6 +2760,8 @@ def _enqueue( system_properties=system_properties, flag_properties=flag_properties, trace_properties=trace_properties, + library_id=self._library_id, + library_version=self._library_version, ), ) 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/mcp/README.md b/posthog/mcp/README.md index 7dd4e70f5..474c29c23 100644 --- a/posthog/mcp/README.md +++ b/posthog/mcp/README.md @@ -31,9 +31,8 @@ analytics = instrument(server, posthog) Install is just `pip install posthog`. `instrument()` needs the MCP SDK at runtime, but anyone wrapping a server already has it. -MCP analytics events report `$lib: "posthog-python"` and the installed `posthog` package version in `$lib_version`, like every other event the client sends. -PostHog sets both from the client's `PostHog-Sdk-Info` request header, so `instrument()` and `PostHogMCP` do not relabel the client. -Filter MCP traffic by its `$mcp_*` events and properties instead. +MCP analytics events report `$lib: "posthog-python-mcp"` and the installed `posthog` package version in `$lib_version`, so SDK Health can compare MCP traffic with Python SDK releases. +The client's other events, request headers and feature flag requests keep reporting `posthog-python`, so one client can serve both. ## Defaults and opt-outs @@ -104,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 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 b5c3add23..cdfa25874 100644 --- a/posthog/mcp/_posthog_events.py +++ b/posthog/mcp/_posthog_events.py @@ -10,14 +10,17 @@ from datetime import datetime, timezone from typing import Any, Dict, List -from posthog.capture_event import _merge_groups +from posthog.capture_event import _fill_library, _merge_groups +from posthog.version import VERSION from .constants import ( POSTHOG_MCP_ANALYTICS_SOURCE, + POSTHOG_MCP_LIB_NAME, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, ) from ._event_types import MCPAnalyticsEventType +from .logger import warn from .types import Event, PostHogCaptureEvent _BUILT_IN_EVENT_NAME_BY_TYPE = { @@ -49,17 +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, @@ -78,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), } @@ -102,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: @@ -266,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) @@ -304,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/constants.py b/posthog/mcp/constants.py index 2d26e1631..de359e693 100644 --- a/posthog/mcp/constants.py +++ b/posthog/mcp/constants.py @@ -43,6 +43,7 @@ ) POSTHOG_MCP_ANALYTICS_SOURCE = "posthog_mcp_analytics" +POSTHOG_MCP_LIB_NAME = "posthog-python-mcp" class PostHogMCPAnalyticsEvent: 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/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/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_lib_label.py b/posthog/test/mcp/test_lib_label.py new file mode 100644 index 000000000..ea3155ea3 --- /dev/null +++ b/posthog/test/mcp/test_lib_label.py @@ -0,0 +1,226 @@ +"""``posthog-python-mcp`` labels the MCP pipeline's events, and only those.""" + +from datetime import datetime, timezone +from unittest import mock + +import pytest + +from posthog.async_client import AsyncClient +from posthog.capture_event import _to_v1_event +from posthog.client import Client +from posthog.contexts import new_context, tag +from posthog.mcp import instrument +from posthog.mcp._event_types import MCPAnalyticsEventType +from posthog.mcp._sink import McpCaptureOptions, McpEventSink +from posthog.mcp.posthog_mcp import PostHogMCP +from posthog.test.mcp._helpers import MCP_MAJOR, flush_background +from posthog.test.capture_helpers import ( + patch_async_capture_send, + patch_capture_send, + sent_batch, + sent_events, +) +from posthog.version import VERSION + +MCP_LIB = ("posthog-python-mcp", VERSION) +SDK_LIB = ("posthog-python", VERSION) + + +def _tool_call(**overrides): + event = { + "event_type": MCPAnalyticsEventType.MCP_TOOLS_CALL, + "session_id": "ses_abc", + "resource_name": "search", + "timestamp": datetime.now(timezone.utc), + } + event.update(overrides) + return event + + +def _failed_tool_call(): + return _tool_call(is_error=True, error={"message": "boom", "type": "ValueError"}) + + +def _lib(properties): + return (properties.get("$lib"), properties.get("$lib_version")) + + +def _sync_wire(send): + return {e["event"]: e["properties"] for e in map(_to_v1_event, sent_events(send))} + + +async def test_sync_client_labels_mcp_events_and_not_app_events(): + with patch_capture_send("client") as send: + client = Client("phc_test", sync_mode=True) + await McpEventSink(client).capture(_failed_tool_call(), McpCaptureOptions()) + client.capture("app event", distinct_id="user-1") + + wire = _sync_wire(send) + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["$exception"]) == MCP_LIB + assert _lib(wire["app event"]) == SDK_LIB + assert {c.kwargs["sdk_info"] for c in send.call_args_list} == { + f"posthog-python/{VERSION}" + } + + +async def test_async_client_labels_mcp_events_and_not_app_events(): + with patch_async_capture_send(new=mock.AsyncMock()) as send: + client = AsyncClient("phc_test") + await McpEventSink(client).capture(_failed_tool_call(), McpCaptureOptions()) + client.capture("app event", distinct_id="user-1") + await client.shutdown() + + wire = { + e["event"]: e["properties"] + for index in range(len(send.await_args_list)) + for e in sent_batch(send, index) + } + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["$exception"]) == MCP_LIB + assert _lib(wire["app event"]) == SDK_LIB + + +@pytest.mark.parametrize("client_kind", ["sync", "async"]) +async def test_instrumented_server_labels_its_tool_calls(client_kind): + if MCP_MAJOR >= 2: + from mcp.server.mcpserver import MCPServer as Server + else: + from mcp.server.fastmcp import FastMCP as Server + + server = Server(f"lib-label-{client_kind}") + + @server.tool() + def echo(msg: str) -> str: + return msg + + if client_kind == "sync": + with patch_capture_send("client") as send: + client = Client("phc_test", sync_mode=True) + instrument(server, client) + await server._tool_manager.call_tool("echo", {"msg": "hi"}) + await flush_background() + client.capture("app event", distinct_id="user-1") + wire = _sync_wire(send) + else: + with patch_async_capture_send(new=mock.AsyncMock()) as send: + client = AsyncClient("phc_test") + instrument(server, client) + await server._tool_manager.call_tool("echo", {"msg": "hi"}) + await flush_background() + client.capture("app event", distinct_id="user-1") + await client.shutdown() + wire = { + e["event"]: e["properties"] + for index in range(len(send.await_args_list)) + for e in sent_batch(send, index) + } + + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["app event"]) == SDK_LIB + + +def test_posthog_mcp_labels_tool_calls_and_not_custom_events(): + with patch_capture_send("client") as send: + client = PostHogMCP("phc_test", sync_mode=True) + client.capture_tool_call("search", distinct_id="user-1", session_id="ses_abc") + client.flush() + client.capture("app event", distinct_id="user-1") + + wire = _sync_wire(send) + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["app event"]) == SDK_LIB + + +def test_instrument_without_a_client_leaves_the_default_client_unlabeled(): + from mcp.server.lowlevel import Server + + with patch_capture_send("client") as send: + default_client = Client("phc_test", sync_mode=True) + with mock.patch("posthog.setup", return_value=default_client): + instrument(Server("probe-default-client")) + default_client.capture("app event", distinct_id="user-1") + + assert _lib(_sync_wire(send)["app event"]) == SDK_LIB + assert send.call_args.kwargs["sdk_info"] == f"posthog-python/{VERSION}" + + +@pytest.mark.parametrize( + "properties, expected", + [ + ({"$lib": "my-wrapper", "$lib_version": "2.0.0"}, ("my-wrapper", "2.0.0")), + ({"$lib": "my-wrapper"}, ("my-wrapper", None)), + ({"$lib_version": "9.9.9"}, MCP_LIB), + ({"$lib": ""}, MCP_LIB), + ({"$lib": None, "$lib_version": "9.9.9"}, MCP_LIB), + ({"$lib": 5}, MCP_LIB), + ({"$lib": "posthog-python-mcp"}, MCP_LIB), + ({"$lib": "posthog-python"}, SDK_LIB), + ], + ids=[ + "app_pair_wins", + "app_lib_keeps_no_version", + "lone_version_replaced", + "empty_lib_unset", + "null_lib_unset", + "number_lib_unset", + "label_gets_version", + "sdk_lib_gets_version", + ], +) +async def test_event_properties_follow_the_pair_rule(properties, expected): + with patch_capture_send("client") as send: + client = Client("phc_test", sync_mode=True) + await McpEventSink(client).capture( + _tool_call(properties=properties), McpCaptureOptions() + ) + + assert _lib(_sync_wire(send)["$mcp_tool_call"]) == expected + + +@pytest.mark.parametrize("layer", ["super_properties", "context_tag"]) +async def test_mcp_label_beats_lower_layers_but_not_on_app_events(layer): + wrapper = {"$lib": "my-wrapper", "$lib_version": "2.0.0"} + with patch_capture_send("client") as send: + client = Client( + "phc_test", + sync_mode=True, + super_properties=wrapper if layer == "super_properties" else None, + ) + with new_context(fresh=True): + if layer == "context_tag": + for key, value in wrapper.items(): + tag(key, value) + await McpEventSink(client).capture(_tool_call(), McpCaptureOptions()) + client.capture("app event", distinct_id="user-1") + + wire = _sync_wire(send) + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["app event"]) == ("my-wrapper", "2.0.0") + + +def _relabel(event): + event["properties"]["$lib"] = "my-wrapper" + event["properties"]["$lib_version"] = "2.0.0" + return event + + +def _unlabel(event): + event["properties"].pop("$lib") + event["properties"].pop("$lib_version") + return event + + +@pytest.mark.parametrize( + "before_send, expected", + [(_relabel, ("my-wrapper", "2.0.0")), (_unlabel, SDK_LIB)], + ids=["mcp_before_send_relabels", "removal_falls_back_to_the_sdk_pair"], +) +async def test_mcp_before_send_sees_the_label(before_send, expected): + with patch_capture_send("client") as send: + client = Client("phc_test", sync_mode=True) + await McpEventSink(client).capture( + _tool_call(), McpCaptureOptions(before_send=before_send) + ) + + assert _lib(_sync_wire(send)["$mcp_tool_call"]) == expected 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/posthog/test/snapshots/event_family.json b/posthog/test/snapshots/event_family.json index 9747da5c7..34baa95a5 100644 --- a/posthog/test/snapshots/event_family.json +++ b/posthog/test/snapshots/event_family.json @@ -11,6 +11,8 @@ "company": "company-456" }, "$is_server": true, + "$lib": "posthog-python", + "$lib_version": "", "$os": "", "$os_distro": "", "$os_version": "", @@ -38,6 +40,8 @@ "properties": { "$geoip_disable": true, "$is_server": true, + "$lib": "posthog-python", + "$lib_version": "", "$set": { "email": "person@example.com", "plan": "pro" @@ -53,6 +57,8 @@ "properties": { "$geoip_disable": true, "$is_server": true, + "$lib": "posthog-python", + "$lib_version": "", "alias": "user-123", "distinct_id": "anonymous-789" }, @@ -71,7 +77,9 @@ "name": "Example Corp" }, "$group_type": "company", - "$is_server": true + "$is_server": true, + "$lib": "posthog-python", + "$lib_version": "" }, "timestamp": "2026-01-02T03:04:05.000000+00:00", "uuid": "00000000-0000-4000-8000-000000000004" diff --git a/posthog/test/snapshots/exception_event.json b/posthog/test/snapshots/exception_event.json index f1336bd95..34edbee40 100644 --- a/posthog/test/snapshots/exception_event.json +++ b/posthog/test/snapshots/exception_event.json @@ -119,6 +119,8 @@ "company": "company-456" }, "$is_server": true, + "$lib": "posthog-python", + "$lib_version": "", "$os": "", "$os_distro": "", "$os_version": "", diff --git a/posthog/test/test_async_feature_flags.py b/posthog/test/test_async_feature_flags.py index da35bf17d..b09387f60 100644 --- a/posthog/test/test_async_feature_flags.py +++ b/posthog/test/test_async_feature_flags.py @@ -8,10 +8,12 @@ import pytest from posthog import AsyncPosthog +from posthog.capture_event import _to_v1_event from posthog.client import _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES from posthog.contexts import new_context, set_context_device_id from posthog.request import APIError from posthog.test.capture_helpers import patch_async_capture_send +from posthog.version import VERSION def flags_response(*, minimal=False): @@ -201,6 +203,11 @@ async def send_batch(api_key, host, batch, **kwargs): "$feature_flag_request_id", "$feature_flag_has_experiment", } <= set(event["properties"]) + wire_properties = _to_v1_event(event)["properties"] + assert (wire_properties["$lib"], wire_properties["$lib_version"]) == ( + "posthog-python", + VERSION, + ) @pytest.mark.asyncio diff --git a/posthog/test/test_capture_event.py b/posthog/test/test_capture_event.py index 2b0a9c7b7..9c50e57e2 100644 --- a/posthog/test/test_capture_event.py +++ b/posthog/test/test_capture_event.py @@ -79,10 +79,16 @@ def test_required_fields_preserved(self) -> None: self.assertEqual(event["distinct_id"], "user-1") self.assertEqual(event["timestamp"], "2026-06-27T12:00:00.000000+00:00") - def test_strips_lib_and_lib_version(self) -> None: - event = _to_v1_event(_legacy_msg()) - self.assertNotIn("$lib", event["properties"]) - self.assertNotIn("$lib_version", event["properties"]) + @parameterized.expand( + [ + ("sdk", {"$lib": "posthog-python", "$lib_version": "9.9.9"}), + ("caller_lib_alone", {"$lib": "caller-lib"}), + ("null", {"$lib": None, "$lib_version": None}), + ] + ) + def test_sends_lib_and_lib_version_as_given(self, _name, library) -> None: + event = _to_v1_event(_legacy_msg(properties=dict(library))) + self.assertEqual(event["properties"], library) def test_options_empty_dict_when_no_sentinels(self) -> None: event = _to_v1_event(_legacy_msg(properties={"plain": "value"})) diff --git a/posthog/test/test_client.py b/posthog/test/test_client.py index 2f5f7b3b4..3af7dd6d1 100644 --- a/posthog/test/test_client.py +++ b/posthog/test/test_client.py @@ -1889,14 +1889,18 @@ def test_capture_replaces_invalid_timestamp_with_current_utc_time(self, timestam @parameterized.expand( [ - ("missing", None, None), - ("non_string", 123, None), - ("empty", "", None), - ("set_by_before_send", "valid", 123), + (f"{name}_{method}", event, hook_event, method) + for name, event, hook_event in [ + ("missing", None, None), + ("non_string", 123, None), + ("empty", "", None), + ("set_by_before_send", "valid", 123), + ] + for method in ["capture", "capture_ai"] ] ) def test_capture_drops_an_invalid_event_name_and_logs_once( - self, _, event, hook_event + self, _, event, hook_event, method ): def before_send(msg): if hook_event is not None: @@ -1907,13 +1911,16 @@ def before_send(msg): patch_capture_send("client") as mock_post, mock.patch("posthog.utils._warned_reasons", set()), mock.patch.object(Client.log, "warning") as mock_warning, + mock.patch.object(Client.log, "exception") as mock_exception, ): client = Client(FAKE_TEST_API_KEY, sync_mode=True, before_send=before_send) - results = [client.capture(event, distinct_id="user") for _ in range(2)] + capture = getattr(client, method) + results = [capture(event, distinct_id="user") for _ in range(2)] self.assertEqual(results, [None, None]) mock_post.assert_not_called() mock_warning.assert_called_once() + mock_exception.assert_not_called() @parameterized.expand( [ diff --git a/posthog/test/test_event_options.py b/posthog/test/test_event_options.py index abc0fa291..1990ee995 100644 --- a/posthog/test/test_event_options.py +++ b/posthog/test/test_event_options.py @@ -14,6 +14,7 @@ sent_events, ) from posthog.test.test_utils import FAKE_TEST_API_KEY +from posthog.version import VERSION OPTIONS = {"cookieless_mode": True, "future_option": "kept"} @@ -35,6 +36,7 @@ ), } ASYNC_CAPTURE_CALLS = {k: v for k, v in CAPTURE_CALLS.items() if k != "capture_ai"} +ASYNC_LIBRARY_CALLS = {**ASYNC_CAPTURE_CALLS, "capture_ai": CAPTURE_CALLS["capture_ai"]} def _sync_wire_events(call, before_send=None, **config) -> list[dict]: @@ -386,8 +388,16 @@ async def test_async_nested_properties_fill_one_level_deep(): _assert_nested_properties(events) -CALLER_SDK_VALUES = {"$is_server": False, "$geoip_disable": False, "$os": "caller-os"} +CALLER_SDK_VALUES = { + "$is_server": False, + "$geoip_disable": False, + "$os": "caller-os", + "$lib": "caller-lib", + "$lib_version": "caller-version", +} SDK_FLAGS = {"$is_server": False, "$geoip_disable": False} +SDK_LIBRARY = {"$lib": "posthog-python", "$lib_version": VERSION} +CALLER_LIBRARY = {"$lib": "caller-lib", "$lib_version": "caller-version"} def _capture_with_caller_sdk_values(source): @@ -645,21 +655,213 @@ async def test_async_call_disable_geoip_is_an_event_value( assert events[0]["properties"]["$geoip_disable"] is expected +EVERY_PATH_CASES = [ + pytest.param(None, SDK_LIBRARY, id="sdk_library"), + pytest.param(SDK_FLAGS, SDK_FLAGS, id="super_flags"), + pytest.param(CALLER_LIBRARY, CALLER_LIBRARY, id="super_library"), +] + + @pytest.mark.parametrize("method", list(CAPTURE_CALLS)) -def test_sync_super_properties_beat_sdk_values_on_every_path(method): +@pytest.mark.parametrize("super_properties, expected", EVERY_PATH_CASES) +def test_sync_super_properties_beat_sdk_values_on_every_path( + method, super_properties, expected +): events = _sync_wire_events( - lambda c: CAPTURE_CALLS[method](c, None), super_properties=SDK_FLAGS + lambda c: CAPTURE_CALLS[method](c, None), super_properties=super_properties ) - _assert_caller_values(events, SDK_FLAGS) + _assert_caller_values(events, expected) @pytest.mark.asyncio -@pytest.mark.parametrize("method", list(ASYNC_CAPTURE_CALLS)) -async def test_async_super_properties_beat_sdk_values_on_every_path(method): +@pytest.mark.parametrize("method", list(ASYNC_LIBRARY_CALLS)) +@pytest.mark.parametrize("super_properties, expected", EVERY_PATH_CASES) +async def test_async_super_properties_beat_sdk_values_on_every_path( + method, super_properties, expected +): events = await _async_wire_events( - lambda c: ASYNC_CAPTURE_CALLS[method](c, None), super_properties=SDK_FLAGS + lambda c: ASYNC_LIBRARY_CALLS[method](c, None), + super_properties=super_properties, + ) + _assert_caller_values(events, expected) + + +def _library(properties): + return {k: properties[k] for k in SDK_LIBRARY if k in properties} + + +# Layers, lowest first: super, context, event. Only a non-empty string sets +# $lib or $lib_version, so a null, empty or non-string value counts as unset. +LIBRARY_CASES = [ + pytest.param({}, {}, {}, SDK_LIBRARY, id="no_layer"), + pytest.param( + {}, {}, {"$lib": "caller-lib"}, {"$lib": "caller-lib"}, id="caller_lib_alone" + ), + pytest.param( + {}, + {}, + {"$lib": "caller-lib", "$lib_version": None}, + {"$lib": "caller-lib", "$lib_version": None}, + id="caller_lib_keeps_null_version", + ), + pytest.param({}, {}, {"$lib": "posthog-python"}, SDK_LIBRARY, id="sdk_lib_alone"), + pytest.param( + {}, + {}, + {"$lib": "posthog-python", "$lib_version": ""}, + SDK_LIBRARY, + id="sdk_lib_empty_version", + ), + pytest.param( + {}, + {}, + {"$lib": "posthog-python", "$lib_version": 5}, + SDK_LIBRARY, + id="sdk_lib_number_version", + ), + pytest.param({}, {}, {"$lib": " "}, {"$lib": " "}, id="whitespace_lib_is_set"), + pytest.param( + {"$lib": 5, "$lib_version": "super-version"}, + {}, + {}, + SDK_LIBRARY, + id="super_number_lib", + ), + pytest.param( + {}, + {}, + {"$lib": "posthog-python", "$lib_version": "1.0.0"}, + {"$lib": "posthog-python", "$lib_version": "1.0.0"}, + id="sdk_lib_caller_version", + ), + *( + pytest.param({}, {}, {"$lib": value}, SDK_LIBRARY, id=f"{name}_lib") + for name, value in [ + ("null", None), + ("empty", ""), + ("number", 5), + ("bool", True), + ("dict", {}), + ] + ), + pytest.param( + {}, {}, {"$lib_version": "caller-version"}, SDK_LIBRARY, id="lone_version" + ), + pytest.param( + {}, + {}, + {"$lib": None, "$lib_version": "caller-version"}, + SDK_LIBRARY, + id="null_lib_with_version", + ), + pytest.param( + {"$lib_version": "super-version"}, + {}, + {}, + SDK_LIBRARY, + id="super_lone_version", + ), + pytest.param( + CALLER_LIBRARY, {}, {"$lib": None}, CALLER_LIBRARY, id="super_fills_null_lib" + ), + pytest.param( + {}, + {"$lib": "context-lib"}, + {"$lib": ""}, + {"$lib": "context-lib"}, + id="context_fills_empty_lib", + ), + pytest.param( + CALLER_LIBRARY, + {"$lib": "context-lib"}, + {}, + {"$lib": "context-lib", "$lib_version": "caller-version"}, + id="context_beats_super_by_key", + ), + pytest.param( + {"$lib": "super-lib"}, + {}, + {"$lib": "posthog-python"}, + SDK_LIBRARY, + id="event_sdk_lib_beats_super", + ), +] + + +def _library_capture(context, event): + def call(client): + with new_context(fresh=True): + for key, value in context.items(): + tag(key, value) + return client.capture("e", distinct_id="u", properties=dict(event)) + + return call + + +@pytest.mark.parametrize("super_properties, context, event, expected", LIBRARY_CASES) +def test_sync_sdk_library_fills_as_a_pair(super_properties, context, event, expected): + events = _sync_wire_events( + _library_capture(context, event), super_properties=super_properties + ) + assert _library(events[0]["properties"]) == expected + + +@pytest.mark.asyncio +@pytest.mark.parametrize("super_properties, context, event, expected", LIBRARY_CASES) +async def test_async_sdk_library_fills_as_a_pair( + super_properties, context, event, expected +): + events = await _async_wire_events( + _library_capture(context, event), super_properties=super_properties + ) + assert _library(events[0]["properties"]) == expected + + +def _without_library(properties): + return {k: v for k, v in properties.items() if k not in SDK_LIBRARY} + + +LIBRARY_HOOKS = { + "change": ( + lambda p: {**_without_library(p), "$lib": "hook-lib"}, + {"$lib": "hook-lib"}, + ), + "remove": (_without_library, {}), + "null": (lambda p: {**p, "$lib": None}, {**SDK_LIBRARY, "$lib": None}), +} + + +def _library_hook(seen, change): + def hook(msg): + seen.append(_library(msg["properties"])) + return {**msg, "properties": change(msg["properties"])} + + return hook + + +@pytest.mark.parametrize("hook", list(LIBRARY_HOOKS)) +def test_sync_before_send_sees_and_changes_the_sdk_library(hook): + change, expected = LIBRARY_HOOKS[hook] + seen: list = [] + events = _sync_wire_events( + lambda c: c.capture("e", distinct_id="u"), + before_send=_library_hook(seen, change), + ) + assert seen == [SDK_LIBRARY] + assert _library(events[0]["properties"]) == expected + + +@pytest.mark.asyncio +@pytest.mark.parametrize("hook", list(LIBRARY_HOOKS)) +async def test_async_before_send_sees_and_changes_the_sdk_library(hook): + change, expected = LIBRARY_HOOKS[hook] + seen: list = [] + events = await _async_wire_events( + lambda c: c.capture("e", distinct_id="u"), + before_send=_library_hook(seen, change), ) - _assert_caller_values(events, SDK_FLAGS) + assert seen == [SDK_LIBRARY] + assert _library(events[0]["properties"]) == expected @pytest.mark.parametrize("method", ["set", "set_once"]) diff --git a/posthog/test/test_feature_flag_called_minimization.py b/posthog/test/test_feature_flag_called_minimization.py index c73116b98..2106ae778 100644 --- a/posthog/test/test_feature_flag_called_minimization.py +++ b/posthog/test/test_feature_flag_called_minimization.py @@ -19,6 +19,7 @@ from posthog.test.capture_helpers import record_sync_capture_sends from posthog.test.test_utils import FAKE_TEST_API_KEY from posthog.utils import system_context +from posthog.version import VERSION def _flags_response(has_experiment, gate): @@ -85,6 +86,12 @@ def _flag_called_properties(self, captured, index=0): assert events, "no $feature_flag_called event captured" return events[index]["properties"] + def _assert_wire_sdk_library(self, captured): + events = [m for m in captured if m["event"] == "$feature_flag_called"] + properties = _to_v1_event(events[0])["properties"] + self.assertEqual(properties["$lib"], "posthog-python") + self.assertEqual(properties["$lib_version"], VERSION) + class TestMinimizationViaFlagsResponse(_CapturedEventsMixin, unittest.TestCase): """Gate sourced from the top-level ``minimalFlagCalledEvents`` field of the v2 @@ -121,6 +128,7 @@ def test_gated_non_experiment_flag_sends_exactly_the_allowlist(self, patch_flags | set(system_context()), ) self.assertLessEqual(set(properties), _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES) + self._assert_wire_sdk_library(captured) self.assertIs(properties["$is_server"], True) self.assertEqual(properties["$feature_flag"], "person-flag") self.assertEqual(properties["$feature_flag_response"], True) @@ -332,6 +340,7 @@ def test_gated_non_experiment_flag_sends_exactly_the_allowlist( | set(system_context()), ) self.assertLessEqual(set(properties), _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES) + self._assert_wire_sdk_library(captured) self.assertEqual(properties["$feature_flag_response"], True) self.assertIs(properties["locally_evaluated"], True) @@ -533,6 +542,7 @@ def test_gated_non_experiment_flag_sends_exactly_the_allowlist(self, patch_flags | set(system_context()), ) self.assertLessEqual(set(properties), _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES) + self._assert_wire_sdk_library(captured) self.assertEqual(properties["$feature_flag_response"], "variant-value") self.assertIs(properties["$feature_flag_has_experiment"], False) diff --git a/references/public_api_snapshot.txt b/references/public_api_snapshot.txt index c6d71aef6..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 @@ -1078,6 +1080,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 @@ -1227,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) @@ -1266,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 @@ -1295,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) @@ -1354,7 +1357,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) @@ -1397,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 @@ -1436,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 @@ -1446,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] @@ -1614,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 @@ -1625,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) @@ -1695,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) @@ -1725,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 @@ -1874,14 +1877,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]