Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .sampo/changesets/ai-posthog-options.md
Original file line number Diff line number Diff line change
@@ -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.
36 changes: 28 additions & 8 deletions docs/migration-7.x-to-8.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ You need to change code if your app does any of these:
- sends events to a self-hosted PostHog that does not serve the capture v1 endpoints
- sends events through a proxy that redirects capture requests to another host
- reuses one event `uuid` for more than one event
- sets `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` or `$product_tour_id` as a property: use the matching option instead (see [Event options](#event-options)). For MCP events, pass options in `event_options` (see [MCP analytics](#mcp-analytics))
- expects `super_properties` to override properties passed to a single call, including `$set` and `$groups`
- sets `$is_server`, `$geoip_disable` or a system property such as `$os` and expects the SDK's value to win
- has a `before_send` hook that returns a new dict: copy `options`, or the event is sent without them, including the `process_person_profile=False` the SDK sets for events without a distinct ID (see [Event options](#event-options)). The same applies to MCP's `before_send` (see [MCP analytics](#mcp-analytics))
Expand Down Expand Up @@ -202,13 +201,13 @@ Capture v1 sends processing options in an `options` object, next to `properties`
posthog.capture("signed_up", distinct_id="user-1", options={"cookieless_mode": True})
```

The MCP capture methods take `event_options` instead (see [MCP analytics](#mcp-analytics)).
The MCP capture methods take `event_options` instead (see [MCP analytics](#mcp-analytics)), and the AI integrations take `posthog_options` (see [AI capture](#ai-capture)).

- `super_options`, a new `Client`, `AsyncPosthog` and module setting, sets options on every event, like `super_properties`.
- `set_context_option(key, value)` sets an option for the current context, like `tag()`. `get_context_options()` returns the options of the current context. Both exist on `Client` and as module functions. `AsyncPosthog` has no context methods, like it has no `tag()`, so call the module functions. They apply to every client in the context.
- The Celery integration propagates context options to workers, like tags.
- A propagated `process_person_profile: True` turns person processing on for worker events without a distinct ID. Each of those events creates a person.
- In eager mode (`task_always_eager`), Celery publishes nothing, so the distinct ID, tags and options do not reach the task's events. To carry them, pass the task's PostHog headers with `task.apply(headers=...)`, as described in `references/middleware_configuration.md`.
- 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.
Expand Down Expand Up @@ -263,9 +262,31 @@ These changes follow from this order:
- `enable_full_ai_capture` now controls only content: string truncation and media redaction. It no longer chooses the endpoint. `_use_ai_lane` and `_enable_multimodal_capture` still work as aliases.
- The AI integrations call your client's `capture_ai`, and never `capture`. A custom client object must implement `capture_ai` and accept its `options` keyword argument. If the client has no `capture_ai`, the wrapper, callback handler or tracing processor logs one error when you create it and captures no AI events; provider calls still work. Before, such a client got `capture` calls.
- Tests that pass a `Mock` client to an AI integration must assert on `mock.capture_ai`, not `mock.capture`.
- When an AI integration or MCP falls back to a trace, run or session ID, it turns person processing off with a per-event option. This is the only option the integrations set. It wins over `super_options` and context options. `before_send` can still change it.
- When an AI integration or MCP falls back to a trace, run or session ID, it turns person processing off with a per-event option. This is the only option the integrations set on their own. It wins over your `posthog_options`, `options`, `super_options` and context options. `before_send` can still change it.
- An empty or whitespace-only distinct ID passed to an AI integration, such as `posthog_distinct_id=""`, counts as missing, so the integration falls back the same way and turns person processing off. In 7.x, an empty ID gave non-streaming wrapper calls a random personless ID. Streaming calls, embeddings and LangChain used the trace or run ID with person processing on. OpenAI Agents already treated an empty ID as missing. Every integration sent a whitespace-only ID as given, with person processing on.
- The AI integrations have no `options` argument. To set options on their events, use `set_context_option` in a context around the call, or `super_options`. `before_send` can also change an event's `options`.
- The AI integrations take capture options:
- Every wrapper method that takes `posthog_properties` also takes `posthog_options`, for the events of that call. This covers OpenAI, Anthropic and Gemini, sync and async, and the Claude Agent SDK `query()` and `PostHogClaudeSDKClient`. The name keeps it apart from the Claude Agent SDK's own `options`.
- The Gemini clients take `posthog_options` as a default for every call. A call's `posthog_options` win key by key.
- LangChain's `CallbackHandler` and `PostHogMiddleware`, OpenAI Agents' `instrument()` and `PostHogTracingProcessor`, and the Claude Agent SDK's `instrument()` and `PostHogClaudeAgentProcessor` take `options=` for every event. LangChain also reads `posthog_options` from run metadata, like `posthog_properties`. Like properties, the handler's or processor's options win over a run's or a query's. The `$exception` event LangChain captures for a failed run gets the same options.
- These are the event's own options, so they win over context options and `super_options`, which still fill the keys they leave unset. `before_send` can still change them.
- A value that is not a dict is logged as a warning and ignored. The provider call still runs, and the provider never receives `posthog_options`.

```python
from posthog.ai.langchain import CallbackHandler
from posthog.ai.openai import OpenAI

client = OpenAI(posthog_client=posthog_client)
client.chat.completions.create(
model="gpt-5-mini",
messages=[{"role": "user", "content": "Hello"}],
posthog_distinct_id="user-1",
posthog_options={"cookieless_mode": True},
)

handler = CallbackHandler(
posthog_client, distinct_id="user-1", options={"cookieless_mode": True}
)
```
- New `Client` and `AsyncPosthog` arguments for the AI lane:
- `capture_ai_compression`: default none. `POSTHOG_CAPTURE_COMPRESSION` does not apply to it.
- `capture_ai_max_queue_size`: default 1000
Expand Down Expand Up @@ -310,9 +331,8 @@ A context you open inside the handler has ended by then, so options you set in i
Events you capture inside that context still get them.
To set options on `$mcp_tool_call`, use the `event_options` callback.

MCP's `before_send` sees each event's `options` in an `options` key of `PostHogCaptureEvent`.
The SDK sends what the hook returns, so a hook that returns a new dict must copy `options`.
Otherwise the event is sent without them, including the `process_person_profile: False` the SDK sets for an event without an identity, and PostHog creates a person for each session.
MCP's `before_send` gets each event's `options` in an `options` key of `PostHogCaptureEvent`.
A hook that returns a new dict must copy them, or the event is sent without the anonymous `process_person_profile: False`.

## Batching and size limits

Expand Down
19 changes: 19 additions & 0 deletions posthog/ai/anthropic/anthropic.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
):
"""
Expand All @@ -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
"""

Expand All @@ -84,6 +89,7 @@ def create(
posthog_properties,
posthog_privacy_mode,
posthog_groups,
posthog_options=posthog_options,
**kwargs,
)

Expand All @@ -97,6 +103,7 @@ def create(
posthog_groups,
self._client.base_url,
super().create,
posthog_options=posthog_options,
**kwargs,
)

Expand All @@ -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,
):
"""
Expand All @@ -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:
Expand Down Expand Up @@ -147,6 +159,7 @@ def tracked_request():
posthog_groups,
kwargs,
start_time,
options=posthog_options,
)

setattr(manager, request_attribute, tracked_request)
Expand All @@ -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()
Expand All @@ -172,6 +186,7 @@ def _create_streaming(
posthog_groups,
kwargs,
start_time,
options=posthog_options,
)

def _track_streaming_response(
Expand All @@ -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()

Expand Down Expand Up @@ -213,6 +229,7 @@ def generator():
accumulator.accumulated_content,
stop_reason=accumulator.stop_reason,
error=stream_error,
options=options,
)

return _StreamWrapper(generator(), stream=response)
Expand All @@ -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 (
Expand Down Expand Up @@ -259,6 +277,7 @@ def _capture_streaming_event(
groups=posthog_groups,
stop_reason=stop_reason,
error=error,
options=options,
)

# Use the common capture function
Expand Down
19 changes: 19 additions & 0 deletions posthog/ai/anthropic/anthropic_async.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
):
"""
Expand All @@ -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
"""

Expand All @@ -84,6 +89,7 @@ async def create(
posthog_properties,
posthog_privacy_mode,
posthog_groups,
posthog_options=posthog_options,
**kwargs,
)

Expand All @@ -97,6 +103,7 @@ async def create(
posthog_groups,
self._client.base_url,
super().create,
posthog_options=posthog_options,
**kwargs,
)

Expand All @@ -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,
):
"""
Expand All @@ -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:
Expand Down Expand Up @@ -147,6 +159,7 @@ async def tracked_request():
posthog_groups,
kwargs,
start_time,
options=posthog_options,
)

setattr(manager, request_attribute, tracked_request())
Expand All @@ -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()
Expand All @@ -172,6 +186,7 @@ async def _create_streaming(
posthog_groups,
kwargs,
start_time,
options=posthog_options,
)

def _track_streaming_response(
Expand All @@ -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()

Expand Down Expand Up @@ -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)
Expand All @@ -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 (
Expand Down Expand Up @@ -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
Expand Down
13 changes: 13 additions & 0 deletions posthog/ai/claude_agent_sdk/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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().
Expand All @@ -69,6 +74,7 @@ def instrument(
privacy_mode=privacy_mode,
groups=groups,
properties=properties,
options=options,
)


Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Loading
Loading