feat: add device_id to flags request payload (#407)

* feat: add device_id to flags request payload

Add device_id parameter to all feature flag methods, similar to how
distinct_id is handled. The device_id is included in the flags request
payload sent to the server.

- Add device_id parameter to Client methods and module-level functions
- Add context support via set_context_device_id() for automatic fallback
- Add tests for explicit device_id and context-based device_id
- Bump version to 7.6.0

.github/workflows/ci.yml

@@ -76,6 +76,29 @@ jobs:
               run: |
                   pytest --verbose --timeout=30
 
+    import-check:
+        name: Python ${{ matrix.python-version }} import check
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+
+        steps:
+            - uses: actions/checkout@85e6279cec87321a52edac9c87bce653a07cf6c2
+              with:
+                  fetch-depth: 1
+
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55
+              with:
+                  python-version: ${{ matrix.python-version }}
+
+            - name: Install posthog
+              run: pip install .
+
+            - name: Check import produces no warnings
+              run: python -W error -c "import posthog"
+
     django5-integration:
         name: Django 5 integration tests
         runs-on: ubuntu-latest

.github/workflows/codeql.yml

@@ -0,0 +1,45 @@
+name: 'CodeQL Advanced'
+
+on:
+  push:
+    branches: ['master']
+  pull_request:
+    branches: ['master']
+  schedule:
+    - cron: '32 13 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: 'ubuntu-latest'
+    permissions:
+      security-events: write
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: python
+            build-mode: none
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          # Disable TRAP caching - it creates a new cache per commit SHA which
+          # is never reused, causing wasted cache space.
+          # See: https://github.com/github/codeql-action/issues/2030
+          trap-caching: false
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
+        with:
+          category: '/language:${{matrix.language}}'

.github/workflows/release.yml

@@ -44,10 +44,12 @@ jobs:
         run: uv run make release && uv run make release_analytics
 
       - name: Create GitHub release
-        uses: actions/create-release@0cb9c9b65d5d1901c1f53e5e66eaf4afd303e70e # v1
-        with:
-          tag_name: v${{ env.REPO_VERSION }}
-          release_name: ${{ env.REPO_VERSION }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "v${{ env.REPO_VERSION }}" \
+            --title "${{ env.REPO_VERSION }}" \
+            --generate-notes
       
       - name: Dispatch generate-references for posthog-python
         env:

CHANGELOG.md

@@ -1,3 +1,22 @@
+# 7.6.0 - 2026-01-12
+
+feat: add device_id to flags request payload
+
+Add device_id parameter to all feature flag methods, allowing the server to track device identifiers for flag evaluation. The device_id can be passed explicitly or set via context using `set_context_device_id()`.
+
+# 7.5.1 - 2026-01-07
+
+fix: avoid return from finally block to fix Python 3.14 SyntaxWarning (#361) - thanks @jodal
+
+# 7.5.0 - 2026-01-06
+
+feat: Capture Langchain, OpenAI and Anthropic errors as exceptions (if exception autocapture is enabled)
+feat: Add reference to exception in LLMA trace and span events
+
+# 7.4.3 - 2026-01-02
+
+Fixes cache creation cost for Langchain with Anthropic
+
 # 7.4.2 - 2025-12-22
 
 feat: add `in_app_modules` option to control code variables capturing
@@ -13,6 +32,7 @@ When using OpenAI stored prompts, the model is defined in the OpenAI dashboard r
 feat: Add automatic retries for feature flag requests
 
 Feature flag API requests now automatically retry on transient failures:
+
 - Network errors (connection refused, DNS failures, timeouts)
 - Server errors (500, 502, 503, 504)
 - Up to 2 retries with exponential backoff (0.5s, 1s delays)

README.md

@@ -12,6 +12,14 @@
 
 Please see the [Python integration docs](https://posthog.com/docs/integrations/python-integration) for details.
 
+## Python Version Support
+
+| SDK Version | Python Versions Supported | Notes |
+|-------------|---------------------------|-------|
+| 7.3.1+      | 3.10, 3.11, 3.12, 3.13, 3.14 | Added Python 3.14 support |
+| 7.0.0 - 7.0.1 | 3.10, 3.11, 3.12, 3.13  | Dropped Python 3.9 support |
+| 4.0.1 - 6.x | 3.9, 3.10, 3.11, 3.12, 3.13 | Python 3.9+ required |
+
 ## Development
 
 ### Testing Locally

posthog/__init__.py

@@ -23,12 +23,18 @@ from posthog.contexts import (
 from posthog.contexts import (
     set_code_variables_mask_patterns_context as inner_set_code_variables_mask_patterns_context,
 )
+from posthog.contexts import (
+    set_context_device_id as inner_set_context_device_id,
+)
 from posthog.contexts import (
     set_context_session as inner_set_context_session,
 )
 from posthog.contexts import (
     tag as inner_tag,
 )
+from posthog.contexts import (
+    get_tags as inner_get_tags,
+)
 from posthog.exception_utils import (
     DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS,
     DEFAULT_CODE_VARIABLES_MASK_PATTERNS,
@@ -130,6 +136,26 @@ def set_context_session(session_id: str):
     return inner_set_context_session(session_id)
 
 
+def set_context_device_id(device_id: str):
+    """
+    Set the device ID for the current context, associating all feature flag requests
+    in this or child contexts with the given device ID.
+
+    Args:
+        device_id: The device ID to associate with the current context and its children
+
+    Examples:
+        ```python
+        from posthog import set_context_device_id
+        set_context_device_id("device_123")
+        ```
+
+    Category:
+        Contexts
+    """
+    return inner_set_context_device_id(device_id)
+
+
 def identify_context(distinct_id: str):
     """
     Identify the current context with a distinct ID.
@@ -190,6 +216,19 @@ def tag(name: str, value: Any):
     return inner_tag(name, value)
 
 
+def get_tags() -> Dict[str, Any]:
+    """
+    Get all tags from the current context.
+
+    Returns:
+        Dict of all tags in the current context
+
+    Category:
+        Contexts
+    """
+    return inner_get_tags()
+
+
 """Settings."""
 api_key = None  # type: Optional[str]
 host = None  # type: Optional[str]
@@ -467,6 +506,7 @@ def feature_enabled(
     only_evaluate_locally=False,  # type: bool
     send_feature_flag_events=True,  # type: bool
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ):
     # type: (...) -> bool
     """
@@ -506,6 +546,7 @@ def feature_enabled(
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -518,6 +559,7 @@ def get_feature_flag(
     only_evaluate_locally=False,  # type: bool
     send_feature_flag_events=True,  # type: bool
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ) -> Optional[FeatureFlag]:
     """
     Get feature flag variant for users. Used with experiments.
@@ -556,6 +598,7 @@ def get_feature_flag(
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -566,6 +609,7 @@ def get_all_flags(
     group_properties=None,  # type: Optional[dict]
     only_evaluate_locally=False,  # type: bool
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ) -> Optional[dict[str, FeatureFlag]]:
     """
     Get all flags for a given user.
@@ -598,6 +642,7 @@ def get_all_flags(
         group_properties=group_properties or {},
         only_evaluate_locally=only_evaluate_locally,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -610,6 +655,7 @@ def get_feature_flag_result(
     only_evaluate_locally=False,
     send_feature_flag_events=True,
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ):
     # type: (...) -> Optional[FeatureFlagResult]
     """
@@ -641,6 +687,7 @@ def get_feature_flag_result(
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -654,6 +701,7 @@ def get_feature_flag_payload(
     only_evaluate_locally=False,
     send_feature_flag_events=True,
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ) -> Optional[str]:
     return _proxy(
         "get_feature_flag_payload",
@@ -666,6 +714,7 @@ def get_feature_flag_payload(
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 
@@ -696,6 +745,7 @@ def get_all_flags_and_payloads(
     group_properties=None,  # type: Optional[dict]
     only_evaluate_locally=False,
     disable_geoip=None,  # type: Optional[bool]
+    device_id=None,  # type: Optional[str]
 ) -> FlagsAndPayloads:
     return _proxy(
         "get_all_flags_and_payloads",
@@ -705,6 +755,7 @@ def get_all_flags_and_payloads(
         group_properties=group_properties or {},
         only_evaluate_locally=only_evaluate_locally,
         disable_geoip=disable_geoip,
+        device_id=device_id,
     )
 
 

posthog/ai/langchain/callbacks.py

@@ -22,8 +22,8 @@ from uuid import UUID
 
 try:
     # LangChain 1.0+ and modern 0.x with langchain-core
-    from langchain_core.callbacks.base import BaseCallbackHandler
     from langchain_core.agents import AgentAction, AgentFinish
+    from langchain_core.callbacks.base import BaseCallbackHandler
 except (ImportError, ModuleNotFoundError):
     # Fallback for older LangChain versions
     from langchain.callbacks.base import BaseCallbackHandler
@@ -35,15 +35,15 @@ from langchain_core.messages import (
     FunctionMessage,
     HumanMessage,
     SystemMessage,
-    ToolMessage,
     ToolCall,
+    ToolMessage,
 )
 from langchain_core.outputs import ChatGeneration, LLMResult
 from pydantic import BaseModel
 
 from posthog import setup
-from posthog.ai.utils import get_model_params, with_privacy_mode
 from posthog.ai.sanitization import sanitize_langchain
+from posthog.ai.utils import get_model_params, with_privacy_mode
 from posthog.client import Client
 
 log = logging.getLogger("posthog")
@@ -506,6 +506,14 @@ class CallbackHandler(BaseCallbackHandler):
         if isinstance(outputs, BaseException):
             event_properties["$ai_error"] = _stringify_exception(outputs)
             event_properties["$ai_is_error"] = True
+            event_properties = _capture_exception_and_update_properties(
+                self._ph_client,
+                outputs,
+                self._distinct_id,
+                self._groups,
+                event_properties,
+            )
+
         elif outputs is not None:
             event_properties["$ai_output_state"] = with_privacy_mode(
                 self._ph_client, self._privacy_mode, outputs
@@ -576,10 +584,24 @@ class CallbackHandler(BaseCallbackHandler):
         if run.tools:
             event_properties["$ai_tools"] = run.tools
 
+        if self._properties:
+            event_properties.update(self._properties)
+
+        if self._distinct_id is None:
+            event_properties["$process_person_profile"] = False
+
         if isinstance(output, BaseException):
             event_properties["$ai_http_status"] = _get_http_status(output)
             event_properties["$ai_error"] = _stringify_exception(output)
             event_properties["$ai_is_error"] = True
+
+            event_properties = _capture_exception_and_update_properties(
+                self._ph_client,
+                output,
+                self._distinct_id,
+                self._groups,
+                event_properties,
+            )
         else:
             # Add usage
             usage = _parse_usage(output, run.provider, run.model)
@@ -607,12 +629,6 @@ class CallbackHandler(BaseCallbackHandler):
                 self._ph_client, self._privacy_mode, completions
             )
 
-        if self._properties:
-            event_properties.update(self._properties)
-
-        if self._distinct_id is None:
-            event_properties["$process_person_profile"] = False
-
         self._ph_client.capture(
             distinct_id=self._distinct_id or trace_id,
             event="$ai_generation",
@@ -773,9 +789,11 @@ def _parse_usage_model(
             for mapped_key, dataclass_key in field_mapping.items()
         },
     )
-    # For Anthropic providers, LangChain reports input_tokens as the sum of input and cache read tokens.
+    # For Anthropic providers, LangChain reports input_tokens as the sum of all input tokens.
     # Our cost calculation expects them to be separate for Anthropic, so we subtract cache tokens.
-    # For other providers (OpenAI, etc.), input_tokens already includes cache tokens as expected.
+    # Both cache_read and cache_write tokens should be subtracted since Anthropic's raw API
+    # reports input_tokens as tokens NOT read from or used to create a cache.
+    # For other providers (OpenAI, etc.), input_tokens already excludes cache tokens as expected.
     # Match logic consistent with plugin-server: exact match on provider OR substring match on model
     is_anthropic = False
     if provider and provider.lower() == "anthropic":
@@ -783,14 +801,14 @@ def _parse_usage_model(
     elif model and "anthropic" in model.lower():
         is_anthropic = True
 
-    if (
-        is_anthropic
-        and normalized_usage.input_tokens
-        and normalized_usage.cache_read_tokens
-    ):
-        normalized_usage.input_tokens = max(
-            normalized_usage.input_tokens - normalized_usage.cache_read_tokens, 0
+    if is_anthropic and normalized_usage.input_tokens:
+        cache_tokens = (normalized_usage.cache_read_tokens or 0) + (
+            normalized_usage.cache_write_tokens or 0
         )
+        if cache_tokens > 0:
+            normalized_usage.input_tokens = max(
+                normalized_usage.input_tokens - cache_tokens, 0
+            )
     return normalized_usage
 
 
@@ -861,6 +879,27 @@ def _parse_usage(
     return llm_usage
 
 
+def _capture_exception_and_update_properties(
+    client: Client,
+    exception: BaseException,
+    distinct_id: Optional[Union[str, int, UUID]],
+    groups: Optional[Dict[str, Any]],
+    event_properties: Dict[str, Any],
+):
+    if client.enable_exception_autocapture:
+        exception_id = client.capture_exception(
+            exception,
+            distinct_id=distinct_id,
+            groups=groups,
+            properties=event_properties,
+        )
+
+        if exception_id:
+            event_properties["$exception_event_id"] = exception_id
+
+    return event_properties
+
+
 def _get_http_status(error: BaseException) -> int:
     # OpenAI: https://github.com/openai/openai-python/blob/main/src/openai/_exceptions.py
     # Anthropic: https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_exceptions.py

posthog/ai/utils.py

@@ -2,14 +2,15 @@ import time
 import uuid
 from typing import Any, Callable, Dict, List, Optional, cast
 
-from posthog.client import Client as PostHogClient
-from posthog.ai.types import FormattedMessage, StreamingEventData, TokenUsage
+from posthog import get_tags, identify_context, new_context, tag
 from posthog.ai.sanitization import (
-    sanitize_openai,
     sanitize_anthropic,
     sanitize_gemini,
     sanitize_langchain,
+    sanitize_openai,
 )
+from posthog.ai.types import FormattedMessage, StreamingEventData, TokenUsage
+from posthog.client import Client as PostHogClient
 
 
 def merge_usage_stats(
@@ -256,94 +257,108 @@ def call_llm_and_track_usage(
     usage: TokenUsage = TokenUsage()
     error_params: Dict[str, Any] = {}
 
-    try:
-        response = call_method(**kwargs)
-    except Exception as exc:
-        error = exc
-        http_status = getattr(
-            exc, "status_code", 0
-        )  # default to 0 becuase its likely an SDK error
-        error_params = {
-            "$ai_is_error": True,
-            "$ai_error": exc.__str__(),
-        }
-    finally:
-        end_time = time.time()
-        latency = end_time - start_time
+    with new_context(client=ph_client, capture_exceptions=False):
+        if posthog_distinct_id:
+            identify_context(posthog_distinct_id)
 
-        if posthog_trace_id is None:
-            posthog_trace_id = str(uuid.uuid4())
+        try:
+            response = call_method(**kwargs)
+        except Exception as exc:
+            error = exc
+            http_status = getattr(
+                exc, "status_code", 0
+            )  # default to 0 becuase its likely an SDK error
+            error_params = {
+                "$ai_is_error": True,
+                "$ai_error": exc.__str__(),
+            }
+            # TODO: Add exception capture for OpenAI/Anthropic/Gemini wrappers when
+            # enable_exception_autocapture is True, similar to LangChain callbacks.
+            # See _capture_exception_and_update_properties in langchain/callbacks.py
+        finally:
+            end_time = time.time()
+            latency = end_time - start_time
 
-        if response and (
-            hasattr(response, "usage")
-            or (provider == "gemini" and hasattr(response, "usage_metadata"))
-        ):
-            usage = get_usage(response, provider)
+            if posthog_trace_id is None:
+                posthog_trace_id = str(uuid.uuid4())
 
-        messages = merge_system_prompt(kwargs, provider)
-        sanitized_messages = sanitize_messages(messages, provider)
+            if response and (
+                hasattr(response, "usage")
+                or (provider == "gemini" and hasattr(response, "usage_metadata"))
+            ):
+                usage = get_usage(response, provider)
 
-        event_properties = {
-            "$ai_provider": provider,
-            "$ai_model": kwargs.get("model") or getattr(response, "model", None),
-            "$ai_model_parameters": get_model_params(kwargs),
-            "$ai_input": with_privacy_mode(
-                ph_client, posthog_privacy_mode, sanitized_messages
-            ),
-            "$ai_output_choices": with_privacy_mode(
-                ph_client, posthog_privacy_mode, format_response(response, provider)
-            ),
-            "$ai_http_status": http_status,
-            "$ai_input_tokens": usage.get("input_tokens", 0),
-            "$ai_output_tokens": usage.get("output_tokens", 0),
-            "$ai_latency": latency,
-            "$ai_trace_id": posthog_trace_id,
-            "$ai_base_url": str(base_url),
-            **(posthog_properties or {}),
-            **(error_params or {}),
-        }
+            messages = merge_system_prompt(kwargs, provider)
+            sanitized_messages = sanitize_messages(messages, provider)
 
-        available_tool_calls = extract_available_tool_calls(provider, kwargs)
-
-        if available_tool_calls:
-            event_properties["$ai_tools"] = available_tool_calls
-
-        cache_read = usage.get("cache_read_input_tokens")
-        if cache_read is not None and cache_read > 0:
-            event_properties["$ai_cache_read_input_tokens"] = cache_read
-
-        cache_creation = usage.get("cache_creation_input_tokens")
-        if cache_creation is not None and cache_creation > 0:
-            event_properties["$ai_cache_creation_input_tokens"] = cache_creation
-
-        reasoning = usage.get("reasoning_tokens")
-        if reasoning is not None and reasoning > 0:
-            event_properties["$ai_reasoning_tokens"] = reasoning
-
-        web_search_count = usage.get("web_search_count")
-        if web_search_count is not None and web_search_count > 0:
-            event_properties["$ai_web_search_count"] = web_search_count
-
-        if posthog_distinct_id is None:
-            event_properties["$process_person_profile"] = False
-
-        # Process instructions for Responses API
-        if provider == "openai" and kwargs.get("instructions") is not None:
-            event_properties["$ai_instructions"] = with_privacy_mode(
-                ph_client, posthog_privacy_mode, kwargs.get("instructions")
+            tag("$ai_provider", provider)
+            tag("$ai_model", kwargs.get("model") or getattr(response, "model", None))
+            tag("$ai_model_parameters", get_model_params(kwargs))
+            tag(
+                "$ai_input",
+                with_privacy_mode(ph_client, posthog_privacy_mode, sanitized_messages),
             )
-
-        # send the event to posthog
-        if hasattr(ph_client, "capture") and callable(ph_client.capture):
-            ph_client.capture(
-                distinct_id=posthog_distinct_id or posthog_trace_id,
-                event="$ai_generation",
-                properties=event_properties,
-                groups=posthog_groups,
+            tag(
+                "$ai_output_choices",
+                with_privacy_mode(
+                    ph_client, posthog_privacy_mode, format_response(response, provider)
+                ),
             )
+            tag("$ai_http_status", http_status)
+            tag("$ai_input_tokens", usage.get("input_tokens", 0))
+            tag("$ai_output_tokens", usage.get("output_tokens", 0))
+            tag("$ai_latency", latency)
+            tag("$ai_trace_id", posthog_trace_id)
+            tag("$ai_base_url", str(base_url))
 
-    if error:
-        raise error
+            available_tool_calls = extract_available_tool_calls(provider, kwargs)
+
+            if available_tool_calls:
+                tag("$ai_tools", available_tool_calls)
+
+            cache_read = usage.get("cache_read_input_tokens")
+            if cache_read is not None and cache_read > 0:
+                tag("$ai_cache_read_input_tokens", cache_read)
+
+            cache_creation = usage.get("cache_creation_input_tokens")
+            if cache_creation is not None and cache_creation > 0:
+                tag("$ai_cache_creation_input_tokens", cache_creation)
+
+            reasoning = usage.get("reasoning_tokens")
+            if reasoning is not None and reasoning > 0:
+                tag("$ai_reasoning_tokens", reasoning)
+
+            web_search_count = usage.get("web_search_count")
+            if web_search_count is not None and web_search_count > 0:
+                tag("$ai_web_search_count", web_search_count)
+
+            if posthog_distinct_id is None:
+                tag("$process_person_profile", False)
+
+            # Process instructions for Responses API
+            if provider == "openai" and kwargs.get("instructions") is not None:
+                tag(
+                    "$ai_instructions",
+                    with_privacy_mode(
+                        ph_client, posthog_privacy_mode, kwargs.get("instructions")
+                    ),
+                )
+
+            # send the event to posthog
+            if hasattr(ph_client, "capture") and callable(ph_client.capture):
+                ph_client.capture(
+                    distinct_id=posthog_distinct_id or posthog_trace_id,
+                    event="$ai_generation",
+                    properties={
+                        **get_tags(),
+                        **(posthog_properties or {}),
+                        **(error_params or {}),
+                    },
+                    groups=posthog_groups,
+                )
+
+        if error:
+            raise error
 
     return response
 
@@ -367,94 +382,108 @@ async def call_llm_and_track_usage_async(
     usage: TokenUsage = TokenUsage()
     error_params: Dict[str, Any] = {}
 
-    try:
-        response = await call_async_method(**kwargs)
-    except Exception as exc:
-        error = exc
-        http_status = getattr(
-            exc, "status_code", 0
-        )  # default to 0 because its likely an SDK error
-        error_params = {
-            "$ai_is_error": True,
-            "$ai_error": exc.__str__(),
-        }
-    finally:
-        end_time = time.time()
-        latency = end_time - start_time
+    with new_context(client=ph_client, capture_exceptions=False):
+        if posthog_distinct_id:
+            identify_context(posthog_distinct_id)
 
-        if posthog_trace_id is None:
-            posthog_trace_id = str(uuid.uuid4())
+        try:
+            response = await call_async_method(**kwargs)
+        except Exception as exc:
+            error = exc
+            http_status = getattr(
+                exc, "status_code", 0
+            )  # default to 0 because its likely an SDK error
+            error_params = {
+                "$ai_is_error": True,
+                "$ai_error": exc.__str__(),
+            }
+            # TODO: Add exception capture for OpenAI/Anthropic/Gemini wrappers when
+            # enable_exception_autocapture is True, similar to LangChain callbacks.
+            # See _capture_exception_and_update_properties in langchain/callbacks.py
+        finally:
+            end_time = time.time()
+            latency = end_time - start_time
 
-        if response and (
-            hasattr(response, "usage")
-            or (provider == "gemini" and hasattr(response, "usage_metadata"))
-        ):
-            usage = get_usage(response, provider)
+            if posthog_trace_id is None:
+                posthog_trace_id = str(uuid.uuid4())
 
-        messages = merge_system_prompt(kwargs, provider)
-        sanitized_messages = sanitize_messages(messages, provider)
+            if response and (
+                hasattr(response, "usage")
+                or (provider == "gemini" and hasattr(response, "usage_metadata"))
+            ):
+                usage = get_usage(response, provider)
 
-        event_properties = {
-            "$ai_provider": provider,
-            "$ai_model": kwargs.get("model") or getattr(response, "model", None),
-            "$ai_model_parameters": get_model_params(kwargs),
-            "$ai_input": with_privacy_mode(
-                ph_client, posthog_privacy_mode, sanitized_messages
-            ),
-            "$ai_output_choices": with_privacy_mode(
-                ph_client, posthog_privacy_mode, format_response(response, provider)
-            ),
-            "$ai_http_status": http_status,
-            "$ai_input_tokens": usage.get("input_tokens", 0),
-            "$ai_output_tokens": usage.get("output_tokens", 0),
-            "$ai_latency": latency,
-            "$ai_trace_id": posthog_trace_id,
-            "$ai_base_url": str(base_url),
-            **(posthog_properties or {}),
-            **(error_params or {}),
-        }
+            messages = merge_system_prompt(kwargs, provider)
+            sanitized_messages = sanitize_messages(messages, provider)
 
-        available_tool_calls = extract_available_tool_calls(provider, kwargs)
-
-        if available_tool_calls:
-            event_properties["$ai_tools"] = available_tool_calls
-
-        cache_read = usage.get("cache_read_input_tokens")
-        if cache_read is not None and cache_read > 0:
-            event_properties["$ai_cache_read_input_tokens"] = cache_read
-
-        cache_creation = usage.get("cache_creation_input_tokens")
-        if cache_creation is not None and cache_creation > 0:
-            event_properties["$ai_cache_creation_input_tokens"] = cache_creation
-
-        reasoning = usage.get("reasoning_tokens")
-        if reasoning is not None and reasoning > 0:
-            event_properties["$ai_reasoning_tokens"] = reasoning
-
-        web_search_count = usage.get("web_search_count")
-        if web_search_count is not None and web_search_count > 0:
-            event_properties["$ai_web_search_count"] = web_search_count
-
-        if posthog_distinct_id is None:
-            event_properties["$process_person_profile"] = False
-
-        # Process instructions for Responses API
-        if provider == "openai" and kwargs.get("instructions") is not None:
-            event_properties["$ai_instructions"] = with_privacy_mode(
-                ph_client, posthog_privacy_mode, kwargs.get("instructions")
+            tag("$ai_provider", provider)
+            tag("$ai_model", kwargs.get("model") or getattr(response, "model", None))
+            tag("$ai_model_parameters", get_model_params(kwargs))
+            tag(
+                "$ai_input",
+                with_privacy_mode(ph_client, posthog_privacy_mode, sanitized_messages),
             )
-
-        # send the event to posthog
-        if hasattr(ph_client, "capture") and callable(ph_client.capture):
-            ph_client.capture(
-                distinct_id=posthog_distinct_id or posthog_trace_id,
-                event="$ai_generation",
-                properties=event_properties,
-                groups=posthog_groups,
+            tag(
+                "$ai_output_choices",
+                with_privacy_mode(
+                    ph_client, posthog_privacy_mode, format_response(response, provider)
+                ),
             )
+            tag("$ai_http_status", http_status)
+            tag("$ai_input_tokens", usage.get("input_tokens", 0))
+            tag("$ai_output_tokens", usage.get("output_tokens", 0))
+            tag("$ai_latency", latency)
+            tag("$ai_trace_id", posthog_trace_id)
+            tag("$ai_base_url", str(base_url))
 
-    if error:
-        raise error
+            available_tool_calls = extract_available_tool_calls(provider, kwargs)
+
+            if available_tool_calls:
+                tag("$ai_tools", available_tool_calls)
+
+            cache_read = usage.get("cache_read_input_tokens")
+            if cache_read is not None and cache_read > 0:
+                tag("$ai_cache_read_input_tokens", cache_read)
+
+            cache_creation = usage.get("cache_creation_input_tokens")
+            if cache_creation is not None and cache_creation > 0:
+                tag("$ai_cache_creation_input_tokens", cache_creation)
+
+            reasoning = usage.get("reasoning_tokens")
+            if reasoning is not None and reasoning > 0:
+                tag("$ai_reasoning_tokens", reasoning)
+
+            web_search_count = usage.get("web_search_count")
+            if web_search_count is not None and web_search_count > 0:
+                tag("$ai_web_search_count", web_search_count)
+
+            if posthog_distinct_id is None:
+                tag("$process_person_profile", False)
+
+            # Process instructions for Responses API
+            if provider == "openai" and kwargs.get("instructions") is not None:
+                tag(
+                    "$ai_instructions",
+                    with_privacy_mode(
+                        ph_client, posthog_privacy_mode, kwargs.get("instructions")
+                    ),
+                )
+
+            # send the event to posthog
+            if hasattr(ph_client, "capture") and callable(ph_client.capture):
+                ph_client.capture(
+                    distinct_id=posthog_distinct_id or posthog_trace_id,
+                    event="$ai_generation",
+                    properties={
+                        **get_tags(),
+                        **(posthog_properties or {}),
+                        **(error_params or {}),
+                    },
+                    groups=posthog_groups,
+                )
+
+        if error:
+            raise error
 
     return response
 

posthog/client.py

@@ -18,6 +18,7 @@ from posthog.contexts import (
     get_capture_exception_code_variables_context,
     get_code_variables_ignore_patterns_context,
     get_code_variables_mask_patterns_context,
+    get_context_device_id,
     get_context_distinct_id,
     get_context_session_id,
     new_context,
@@ -382,6 +383,7 @@ class Client(object):
         group_properties=None,
         disable_geoip=None,
         flag_keys_to_evaluate: Optional[list[str]] = None,
+        device_id: Optional[str] = None,
     ) -> dict[str, Union[bool, str]]:
         """
         Get feature flag variants for a user by calling decide.
@@ -394,6 +396,7 @@ class Client(object):
             disable_geoip: Whether to disable GeoIP for this request.
             flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
                 only these flags will be evaluated, improving performance.
+            device_id: The device ID for this request.
 
         Category:
             Feature flags
@@ -405,6 +408,7 @@ class Client(object):
             group_properties,
             disable_geoip,
             flag_keys_to_evaluate,
+            device_id=device_id,
         )
         return to_values(resp_data) or {}
 
@@ -416,6 +420,7 @@ class Client(object):
         group_properties=None,
         disable_geoip=None,
         flag_keys_to_evaluate: Optional[list[str]] = None,
+        device_id: Optional[str] = None,
     ) -> dict[str, str]:
         """
         Get feature flag payloads for a user by calling decide.
@@ -428,6 +433,7 @@ class Client(object):
             disable_geoip: Whether to disable GeoIP for this request.
             flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
                 only these flags will be evaluated, improving performance.
+            device_id: The device ID for this request.
 
         Examples:
             ```python
@@ -444,6 +450,7 @@ class Client(object):
             group_properties,
             disable_geoip,
             flag_keys_to_evaluate,
+            device_id=device_id,
         )
         return to_payloads(resp_data) or {}
 
@@ -455,6 +462,7 @@ class Client(object):
         group_properties=None,
         disable_geoip=None,
         flag_keys_to_evaluate: Optional[list[str]] = None,
+        device_id: Optional[str] = None,
     ) -> FlagsAndPayloads:
         """
         Get feature flags and payloads for a user by calling decide.
@@ -467,6 +475,7 @@ class Client(object):
             disable_geoip: Whether to disable GeoIP for this request.
             flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
                 only these flags will be evaluated, improving performance.
+            device_id: The device ID for this request.
 
         Examples:
             ```python
@@ -483,6 +492,7 @@ class Client(object):
             group_properties,
             disable_geoip,
             flag_keys_to_evaluate,
+            device_id=device_id,
         )
         return to_flags_and_payloads(resp)
 
@@ -494,6 +504,7 @@ class Client(object):
         group_properties=None,
         disable_geoip=None,
         flag_keys_to_evaluate: Optional[list[str]] = None,
+        device_id: Optional[str] = None,
     ) -> FlagsResponse:
         """
         Get feature flags decision.
@@ -506,6 +517,7 @@ class Client(object):
             disable_geoip: Whether to disable GeoIP for this request.
             flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
                 only these flags will be evaluated, improving performance.
+            device_id: The device ID for this request.
 
         Examples:
             ```python
@@ -522,6 +534,9 @@ class Client(object):
         if distinct_id is None:
             distinct_id = get_context_distinct_id()
 
+        if device_id is None:
+            device_id = get_context_device_id()
+
         if disable_geoip is None:
             disable_geoip = self.disable_geoip
 
@@ -534,6 +549,7 @@ class Client(object):
             "person_properties": person_properties,
             "group_properties": group_properties,
             "geoip_disable": disable_geoip,
+            "device_id": device_id,
         }
 
         if flag_keys_to_evaluate:
@@ -1464,6 +1480,7 @@ class Client(object):
         only_evaluate_locally=False,
         send_feature_flag_events=True,
         disable_geoip=None,
+        device_id: Optional[str] = None,
     ):
         """
         Check if a feature flag is enabled for a user.
@@ -1477,6 +1494,7 @@ class Client(object):
             only_evaluate_locally: Whether to only evaluate locally.
             send_feature_flag_events: Whether to send feature flag events.
             disable_geoip: Whether to disable GeoIP for this request.
+            device_id: The device ID for this request.
 
         Examples:
             ```python
@@ -1499,6 +1517,7 @@ class Client(object):
             only_evaluate_locally=only_evaluate_locally,
             send_feature_flag_events=send_feature_flag_events,
             disable_geoip=disable_geoip,
+            device_id=device_id,
         )
 
         if response is None:
@@ -1530,6 +1549,7 @@ class Client(object):
         only_evaluate_locally=False,
         send_feature_flag_events=True,
         disable_geoip=None,
+        device_id: Optional[str] = None,
     ) -> Optional[FeatureFlagResult]:
         if self.disabled:
             return None
@@ -1584,6 +1604,7 @@ class Client(object):
                         person_properties,
                         group_properties,
                         disable_geoip,
+                        device_id=device_id,
                     )
                 )
                 errors = []
@@ -1656,6 +1677,7 @@ class Client(object):
         only_evaluate_locally=False,
         send_feature_flag_events=True,
         disable_geoip=None,
+        device_id: Optional[str] = None,
     ) -> Optional[FeatureFlagResult]:
         """
         Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely
@@ -1680,6 +1702,7 @@ class Client(object):
             only_evaluate_locally: Whether to only evaluate locally.
             send_feature_flag_events: Whether to send feature flag events.
             disable_geoip: Whether to disable GeoIP for this request.
+            device_id: The device ID for this request.
 
         Returns:
             Optional[FeatureFlagResult]: The feature flag result or None if disabled/not found.
@@ -1693,6 +1716,7 @@ class Client(object):
             only_evaluate_locally=only_evaluate_locally,
             send_feature_flag_events=send_feature_flag_events,
             disable_geoip=disable_geoip,
+            device_id=device_id,
         )
 
     def get_feature_flag(
@@ -1706,6 +1730,7 @@ class Client(object):
         only_evaluate_locally=False,
         send_feature_flag_events=True,
         disable_geoip=None,
+        device_id: Optional[str] = None,
     ) -> Optional[FlagValue]:
         """
         Get multivariate feature flag value for a user.
@@ -1719,6 +1744,7 @@ class Client(object):
             only_evaluate_locally: Whether to only evaluate locally.
             send_feature_flag_events: Whether to send feature flag events.
             disable_geoip: Whether to disable GeoIP for this request.
+            device_id: The device ID for this request.
 
         Examples:
             ```python
@@ -1741,6 +1767,7 @@ class Client(object):
             only_evaluate_locally=only_evaluate_locally,
             send_feature_flag_events=send_feature_flag_events,
             disable_geoip=disable_geoip,
+            device_id=device_id,
         )
         return feature_flag_result.get_value() if feature_flag_result else None
 
@@ -1794,6 +1821,7 @@ class Client(object):
         only_evaluate_locally=False,
         send_feature_flag_events=False,
         disable_geoip=None,
+        device_id: Optional[str] = None,
     ):
         """
         Get the payload for a feature flag.
@@ -1808,6 +1836,7 @@ class Client(object):
             only_evaluate_locally: Whether to only evaluate locally.
             send_feature_flag_events: Deprecated. Use get_feature_flag() instead if you need events.
             disable_geoip: Whether to disable GeoIP for this request.
+            device_id: The device ID for this request.
 
         Examples:
             ```python
@@ -1840,6 +1869,7 @@ class Client(object):
             only_evaluate_locally=only_evaluate_locally,
             send_feature_flag_events=send_feature_flag_events,
             disable_geoip=disable_geoip,
+            device_id=device_id,
         )
         return feature_flag_result.payload if feature_flag_result else None
 
@@ -1851,6 +1881,7 @@ class Client(object):
         person_properties: dict[str, str],
         group_properties: dict[str, str],
         disable_geoip: Optional[bool],
+        device_id: Optional[str] = None,
     ) -> tuple[Optional[FeatureFlag], Optional[str], Optional[int], bool]:
         """
         Calls /flags and returns the flag details, request id, evaluated at timestamp,
@@ -1863,6 +1894,7 @@ class Client(object):
             group_properties,
             disable_geoip,
             flag_keys_to_evaluate=[key],
+            device_id=device_id,
         )
         request_id = resp_data.get("requestId")
         evaluated_at = resp_data.get("evaluatedAt")
@@ -1987,6 +2019,7 @@ class Client(object):
         only_evaluate_locally=False,
         disable_geoip=None,
         flag_keys_to_evaluate: Optional[list[str]] = None,
+        device_id: Optional[str] = None,
     ) -> Optional[dict[str, Union[bool, str]]]:
         """
         Get all feature flags for a user.
@@ -2000,6 +2033,7 @@ class Client(object):
             disable_geoip: Whether to disable GeoIP for this request.
             flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
                 only these flags will be evaluated, improving performance.
+            device_id: The device ID for this request.
 
         Examples:
             ```python
@@ -2017,6 +2051,7 @@ class Client(object):
             only_evaluate_locally=only_evaluate_locally,
             disable_geoip=disable_geoip,
             flag_keys_to_evaluate=flag_keys_to_evaluate,
+            device_id=device_id,
         )
 
         return response["featureFlags"]
@@ -2031,6 +2066,7 @@ class Client(object):
         only_evaluate_locally=False,
         disable_geoip=None,
         flag_keys_to_evaluate: Optional[list[str]] = None,
+        device_id: Optional[str] = None,
     ) -> FlagsAndPayloads:
         """
         Get all feature flags and their payloads for a user.
@@ -2044,6 +2080,7 @@ class Client(object):
             disable_geoip: Whether to disable GeoIP for this request.
             flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
                 only these flags will be evaluated, improving performance.
+            device_id: The device ID for this request.
 
         Examples:
             ```python
@@ -2079,6 +2116,7 @@ class Client(object):
                     group_properties=group_properties,
                     disable_geoip=disable_geoip,
                     flag_keys_to_evaluate=flag_keys_to_evaluate,
+                    device_id=device_id,
                 )
                 return to_flags_and_payloads(decide_response)
             except Exception as e:

posthog/consumer.py

@@ -84,12 +84,16 @@ class Consumer(Thread):
             self.log.error("error uploading: %s", e)
             success = False
             if self.on_error:
-                self.on_error(e, batch)
+                try:
+                    self.on_error(e, batch)
+                except Exception as e:
+                    self.log.error("on_error handler failed: %s", e)
         finally:
             # mark items as acknowledged from queue
             for item in batch:
                 self.queue.task_done()
-            return success
+
+        return success
 
     def next(self):
         """Return the next batch of items to upload."""

posthog/contexts.py

@@ -21,6 +21,7 @@ class ContextScope:
         self.capture_exceptions = capture_exceptions
         self.session_id: Optional[str] = None
         self.distinct_id: Optional[str] = None
+        self.device_id: Optional[str] = None
         self.tags: Dict[str, Any] = {}
         self.capture_exception_code_variables: Optional[bool] = None
         self.code_variables_mask_patterns: Optional[list] = None
@@ -32,6 +33,9 @@ class ContextScope:
     def set_distinct_id(self, distinct_id: str):
         self.distinct_id = distinct_id
 
+    def set_device_id(self, device_id: str):
+        self.device_id = device_id
+
     def add_tag(self, key: str, value: Any):
         self.tags[key] = value
 
@@ -61,15 +65,21 @@ class ContextScope:
             return self.parent.get_distinct_id()
         return None
 
+    def get_device_id(self) -> Optional[str]:
+        if self.device_id is not None:
+            return self.device_id
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_device_id()
+        return None
+
     def collect_tags(self) -> Dict[str, Any]:
-        tags = self.tags.copy()
         if self.parent and not self.fresh:
             # We want child tags to take precedence over parent tags,
-            # so we can't use a simple update here, instead collecting
-            # the parent tags and then updating with the child tags.
-            new_tags = self.parent.collect_tags()
-            tags.update(new_tags)
-        return tags
+            # so collect parent tags first, then update with child tags.
+            tags = self.parent.collect_tags()
+            tags.update(self.tags)
+            return tags
+        return self.tags.copy()
 
     def get_capture_exception_code_variables(self) -> Optional[bool]:
         if self.capture_exception_code_variables is not None:
@@ -276,6 +286,39 @@ def get_context_distinct_id() -> Optional[str]:
     return None
 
 
+def set_context_device_id(device_id: str) -> None:
+    """
+    Set the device ID for the current context, associating all feature flag requests in this or
+    child contexts with the given device ID (unless set_context_device_id is called again).
+    Entering a fresh context will clear the context-level device ID.
+
+    Args:
+        device_id: The device ID to associate with the current context and its children.
+
+    Category:
+        Contexts
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_device_id(device_id)
+
+
+def get_context_device_id() -> Optional[str]:
+    """
+    Get the device ID for the current context.
+
+    Returns:
+        The device ID if set, None otherwise
+
+    Category:
+        Contexts
+    """
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_device_id()
+    return None
+
+
 def set_capture_exception_code_variables_context(enabled: bool) -> None:
     """
     Set whether code variables are captured for the current context.

posthog/test/ai/langchain/test_callbacks.py

@@ -1638,6 +1638,95 @@ def test_anthropic_provider_subtracts_cache_tokens(mock_client):
     assert generation_args["properties"]["$ai_cache_read_input_tokens"] == 800
 
 
+def test_anthropic_provider_subtracts_cache_write_tokens(mock_client):
+    """Test that Anthropic provider correctly subtracts cache write tokens from input tokens."""
+    from langchain_core.outputs import LLMResult, ChatGeneration
+    from langchain_core.messages import AIMessage
+    from uuid import uuid4
+
+    cb = CallbackHandler(mock_client)
+    run_id = uuid4()
+
+    # Set up with Anthropic provider
+    cb._set_llm_metadata(
+        serialized={},
+        run_id=run_id,
+        messages=[{"role": "user", "content": "test"}],
+        metadata={"ls_provider": "anthropic", "ls_model_name": "claude-3-sonnet"},
+    )
+
+    # Response with cache creation: 1000 input (includes 800 being written to cache)
+    response = LLMResult(
+        generations=[
+            [
+                ChatGeneration(
+                    message=AIMessage(content="Response"),
+                    generation_info={
+                        "usage_metadata": {
+                            "input_tokens": 1000,
+                            "output_tokens": 50,
+                            "cache_creation_input_tokens": 800,
+                        }
+                    },
+                )
+            ]
+        ],
+        llm_output={},
+    )
+
+    cb._pop_run_and_capture_generation(run_id, None, response)
+
+    generation_args = mock_client.capture.call_args_list[0][1]
+    assert generation_args["properties"]["$ai_input_tokens"] == 200  # 1000 - 800
+    assert generation_args["properties"]["$ai_cache_creation_input_tokens"] == 800
+
+
+def test_anthropic_provider_subtracts_both_cache_read_and_write_tokens(mock_client):
+    """Test that Anthropic provider correctly subtracts both cache read and write tokens."""
+    from langchain_core.outputs import LLMResult, ChatGeneration
+    from langchain_core.messages import AIMessage
+    from uuid import uuid4
+
+    cb = CallbackHandler(mock_client)
+    run_id = uuid4()
+
+    # Set up with Anthropic provider
+    cb._set_llm_metadata(
+        serialized={},
+        run_id=run_id,
+        messages=[{"role": "user", "content": "test"}],
+        metadata={"ls_provider": "anthropic", "ls_model_name": "claude-3-sonnet"},
+    )
+
+    # Response with both cache read and creation
+    response = LLMResult(
+        generations=[
+            [
+                ChatGeneration(
+                    message=AIMessage(content="Response"),
+                    generation_info={
+                        "usage_metadata": {
+                            "input_tokens": 2000,
+                            "output_tokens": 50,
+                            "cache_read_input_tokens": 800,
+                            "cache_creation_input_tokens": 500,
+                        }
+                    },
+                )
+            ]
+        ],
+        llm_output={},
+    )
+
+    cb._pop_run_and_capture_generation(run_id, None, response)
+
+    generation_args = mock_client.capture.call_args_list[0][1]
+    # 2000 - 800 (read) - 500 (write) = 700
+    assert generation_args["properties"]["$ai_input_tokens"] == 700
+    assert generation_args["properties"]["$ai_cache_read_input_tokens"] == 800
+    assert generation_args["properties"]["$ai_cache_creation_input_tokens"] == 500
+
+
 def test_openai_cache_read_tokens(mock_client):
     """Test that OpenAI cache read tokens are captured correctly."""
     prompt = ChatPromptTemplate.from_messages(
@@ -2092,10 +2181,12 @@ def test_zero_input_tokens_with_cache_read(mock_client):
     assert generation_props["$ai_cache_read_input_tokens"] == 50
 
 
-def test_cache_write_tokens_not_subtracted_from_input(mock_client):
-    """Test that cache_creation_input_tokens (cache write) do NOT affect input_tokens.
+def test_non_anthropic_cache_write_tokens_not_subtracted_from_input(mock_client):
+    """Test that cache_creation_input_tokens do NOT affect input_tokens for non-Anthropic providers.
 
-    Only cache_read_tokens should be subtracted from input_tokens, not cache_write_tokens.
+    When no provider metadata is set (or for non-Anthropic providers), cache tokens should
+    NOT be subtracted from input_tokens. This is because different providers report tokens
+    differently - only Anthropic's LangChain integration requires subtraction.
     """
     prompt = ChatPromptTemplate.from_messages([("user", "Create cache")])
 
@@ -2350,3 +2441,206 @@ def test_billable_with_real_chain(mock_client):
     assert props["$ai_billable"] is True
     assert props["$ai_model"] == "fake-model"
     assert props["$ai_provider"] == "fake"
+
+
+# Exception Capture Integration Tests
+
+
+def test_exception_autocapture_on_span_error():
+    """Test that capture_exception is called when a span errors and autocapture is enabled."""
+    mock_client = MagicMock()
+    mock_client.privacy_mode = False
+    mock_client.enable_exception_autocapture = True
+    mock_client.capture_exception.return_value = "exception-uuid-123"
+
+    def failing_span(_):
+        raise ValueError("test error")
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = RunnableLambda(failing_span)
+
+    try:
+        chain.invoke({}, config={"callbacks": callbacks})
+    except ValueError:
+        pass
+
+    # Verify capture_exception was called
+    assert mock_client.capture_exception.call_count == 1
+    exception_call = mock_client.capture_exception.call_args
+    assert isinstance(exception_call[0][0], ValueError)
+    assert str(exception_call[0][0]) == "test error"
+
+
+def test_exception_autocapture_adds_exception_id_to_span_event():
+    """Test that $exception_event_id is added to the span event properties."""
+    mock_client = MagicMock()
+    mock_client.privacy_mode = False
+    mock_client.enable_exception_autocapture = True
+    mock_client.capture_exception.return_value = "exception-uuid-456"
+
+    def failing_span(_):
+        raise ValueError("test error")
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = RunnableLambda(failing_span)
+
+    try:
+        chain.invoke({}, config={"callbacks": callbacks})
+    except ValueError:
+        pass
+
+    # Find the span event (should have $ai_is_error=True)
+    span_calls = [
+        call
+        for call in mock_client.capture.call_args_list
+        if call[1].get("properties", {}).get("$ai_is_error") is True
+    ]
+    assert len(span_calls) >= 1
+
+    span_props = span_calls[0][1]["properties"]
+    assert span_props["$exception_event_id"] == "exception-uuid-456"
+    assert span_props["$ai_error"] == "ValueError: test error"
+
+
+def test_exception_autocapture_disabled_does_not_capture():
+    """Test that capture_exception is NOT called when autocapture is disabled."""
+    mock_client = MagicMock()
+    mock_client.privacy_mode = False
+    mock_client.enable_exception_autocapture = False
+
+    def failing_span(_):
+        raise ValueError("test error")
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = RunnableLambda(failing_span)
+
+    try:
+        chain.invoke({}, config={"callbacks": callbacks})
+    except ValueError:
+        pass
+
+    # Verify capture_exception was NOT called
+    assert mock_client.capture_exception.call_count == 0
+
+    # But the span event should still have error info
+    span_calls = [
+        call
+        for call in mock_client.capture.call_args_list
+        if call[1].get("properties", {}).get("$ai_is_error") is True
+    ]
+    assert len(span_calls) >= 1
+
+    span_props = span_calls[0][1]["properties"]
+    assert "$exception_event_id" not in span_props
+    assert span_props["$ai_error"] == "ValueError: test error"
+
+
+def test_exception_autocapture_on_llm_generation_error(mock_client):
+    """Test that capture_exception is called when an LLM generation fails."""
+    mock_client.privacy_mode = False
+    mock_client.enable_exception_autocapture = True
+    mock_client.capture_exception.return_value = "exception-uuid-789"
+
+    callbacks = CallbackHandler(mock_client)
+    run_id = uuid.uuid4()
+
+    # Simulate LLM start
+    callbacks.on_llm_start(
+        serialized={"kwargs": {"openai_api_base": "https://api.openai.com"}},
+        prompts=["Hello"],
+        run_id=run_id,
+    )
+
+    # Simulate LLM error
+    error = Exception("API rate limit exceeded")
+    callbacks.on_llm_error(error, run_id=run_id)
+
+    # Verify capture_exception was called
+    assert mock_client.capture_exception.call_count == 1
+    exception_call = mock_client.capture_exception.call_args
+    assert exception_call[0][0] is error
+
+    # Verify the generation event has $exception_event_id
+    generation_calls = [
+        call
+        for call in mock_client.capture.call_args_list
+        if call[1].get("event") == "$ai_generation"
+    ]
+    assert len(generation_calls) == 1
+
+    gen_props = generation_calls[0][1]["properties"]
+    assert gen_props["$exception_event_id"] == "exception-uuid-789"
+    assert gen_props["$ai_is_error"] is True
+
+
+def test_exception_autocapture_passes_ai_properties_to_exception():
+    """Test that AI properties are passed to the exception event."""
+    mock_client = MagicMock()
+    mock_client.privacy_mode = False
+    mock_client.enable_exception_autocapture = True
+    mock_client.capture_exception.return_value = "exception-uuid-abc"
+
+    callbacks = CallbackHandler(
+        mock_client,
+        distinct_id="user-123",
+        properties={"custom_prop": "custom_value"},
+    )
+    run_id = uuid.uuid4()
+
+    # Simulate LLM start
+    callbacks.on_llm_start(
+        serialized={"kwargs": {"openai_api_base": "https://api.openai.com"}},
+        prompts=["Hello"],
+        run_id=run_id,
+    )
+
+    # Simulate LLM error
+    error = Exception("API error")
+    callbacks.on_llm_error(error, run_id=run_id)
+
+    # Verify capture_exception received the properties
+    exception_call = mock_client.capture_exception.call_args
+    props = exception_call[1]["properties"]
+
+    # Should have AI-related properties
+    assert "$ai_trace_id" in props
+    assert "$ai_is_error" in props
+    assert props["$ai_is_error"] is True
+
+    # Should have distinct_id passed through
+    assert exception_call[1]["distinct_id"] == "user-123"
+
+
+def test_exception_autocapture_none_return_no_exception_id():
+    """Test that when capture_exception returns None, no $exception_event_id is added."""
+    mock_client = MagicMock()
+    mock_client.privacy_mode = False
+    mock_client.enable_exception_autocapture = True
+    mock_client.capture_exception.return_value = (
+        None  # e.g., exception already captured
+    )
+
+    def failing_span(_):
+        raise ValueError("test error")
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = RunnableLambda(failing_span)
+
+    try:
+        chain.invoke({}, config={"callbacks": callbacks})
+    except ValueError:
+        pass
+
+    # capture_exception was called but returned None
+    assert mock_client.capture_exception.call_count == 1
+
+    # Span event should NOT have $exception_event_id
+    span_calls = [
+        call
+        for call in mock_client.capture.call_args_list
+        if call[1].get("properties", {}).get("$ai_is_error") is True
+    ]
+    assert len(span_calls) >= 1
+
+    span_props = span_calls[0][1]["properties"]
+    assert "$exception_event_id" not in span_props

posthog/test/ai/test_system_prompts.py

@@ -11,7 +11,10 @@ regardless of how they're passed to the providers:
 
 import time
 import unittest
-from unittest.mock import patch, MagicMock
+from unittest.mock import MagicMock, patch
+
+from posthog.client import Client
+from posthog.test.test_utils import FAKE_TEST_API_KEY
 
 
 class TestSystemPromptCapture(unittest.TestCase):
@@ -24,7 +27,8 @@ class TestSystemPromptCapture(unittest.TestCase):
         self.test_response = "I'm doing well, thank you!"
 
         # Create mock PostHog client
-        self.client = MagicMock()
+        self.client = Client(FAKE_TEST_API_KEY)
+        self.client._enqueue = MagicMock()
         self.client.privacy_mode = False
 
     def _assert_system_prompt_captured(self, captured_input):
@@ -53,10 +57,11 @@ class TestSystemPromptCapture(unittest.TestCase):
     def test_openai_messages_array_system_prompt(self):
         """Test OpenAI with system prompt in messages array."""
         try:
-            from posthog.ai.openai import OpenAI
             from openai.types.chat import ChatCompletion, ChatCompletionMessage
             from openai.types.chat.chat_completion import Choice
             from openai.types.completion_usage import CompletionUsage
+
+            from posthog.ai.openai import OpenAI
         except ImportError:
             self.skipTest("OpenAI package not available")
 
@@ -94,17 +99,18 @@ class TestSystemPromptCapture(unittest.TestCase):
                 model="gpt-4", messages=messages, posthog_distinct_id="test-user"
             )
 
-            self.assertEqual(len(self.client.capture.call_args_list), 1)
-            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self.assertEqual(len(self.client._enqueue.call_args_list), 1)
+            properties = self.client._enqueue.call_args_list[0][0][0]["properties"]
             self._assert_system_prompt_captured(properties["$ai_input"])
 
     def test_openai_separate_system_parameter(self):
         """Test OpenAI with system prompt as separate parameter."""
         try:
-            from posthog.ai.openai import OpenAI
             from openai.types.chat import ChatCompletion, ChatCompletionMessage
             from openai.types.chat.chat_completion import Choice
             from openai.types.completion_usage import CompletionUsage
+
+            from posthog.ai.openai import OpenAI
         except ImportError:
             self.skipTest("OpenAI package not available")
 
@@ -142,18 +148,21 @@ class TestSystemPromptCapture(unittest.TestCase):
                 posthog_distinct_id="test-user",
             )
 
-            self.assertEqual(len(self.client.capture.call_args_list), 1)
-            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self.assertEqual(len(self.client._enqueue.call_args_list), 1)
+            properties = self.client._enqueue.call_args_list[0][0][0]["properties"]
             self._assert_system_prompt_captured(properties["$ai_input"])
 
     def test_openai_streaming_system_parameter(self):
         """Test OpenAI streaming with system parameter."""
         try:
-            from posthog.ai.openai import OpenAI
-            from openai.types.chat.chat_completion_chunk import ChatCompletionChunk
+            from openai.types.chat.chat_completion_chunk import (
+                ChatCompletionChunk,
+                ChoiceDelta,
+            )
             from openai.types.chat.chat_completion_chunk import Choice as ChoiceChunk
-            from openai.types.chat.chat_completion_chunk import ChoiceDelta
             from openai.types.completion_usage import CompletionUsage
+
+            from posthog.ai.openai import OpenAI
         except ImportError:
             self.skipTest("OpenAI package not available")
 
@@ -206,8 +215,8 @@ class TestSystemPromptCapture(unittest.TestCase):
 
             list(response_generator)  # Consume generator
 
-            self.assertEqual(len(self.client.capture.call_args_list), 1)
-            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self.assertEqual(len(self.client._enqueue.call_args_list), 1)
+            properties = self.client._enqueue.call_args_list[0][0][0]["properties"]
             self._assert_system_prompt_captured(properties["$ai_input"])
 
     # Anthropic Tests
@@ -239,8 +248,8 @@ class TestSystemPromptCapture(unittest.TestCase):
                 posthog_distinct_id="test-user",
             )
 
-            self.assertEqual(len(self.client.capture.call_args_list), 1)
-            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self.assertEqual(len(self.client._enqueue.call_args_list), 1)
+            properties = self.client._enqueue.call_args_list[0][0][0]["properties"]
             self._assert_system_prompt_captured(properties["$ai_input"])
 
     def test_anthropic_separate_system_parameter(self):
@@ -269,8 +278,8 @@ class TestSystemPromptCapture(unittest.TestCase):
                 posthog_distinct_id="test-user",
             )
 
-            self.assertEqual(len(self.client.capture.call_args_list), 1)
-            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self.assertEqual(len(self.client._enqueue.call_args_list), 1)
+            properties = self.client._enqueue.call_args_list[0][0][0]["properties"]
             self._assert_system_prompt_captured(properties["$ai_input"])
 
     # Gemini Tests
@@ -310,8 +319,8 @@ class TestSystemPromptCapture(unittest.TestCase):
                 posthog_distinct_id="test-user",
             )
 
-            self.assertEqual(len(self.client.capture.call_args_list), 1)
-            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self.assertEqual(len(self.client._enqueue.call_args_list), 1)
+            properties = self.client._enqueue.call_args_list[0][0][0]["properties"]
             self._assert_system_prompt_captured(properties["$ai_input"])
 
     def test_gemini_system_instruction_parameter(self):
@@ -349,6 +358,6 @@ class TestSystemPromptCapture(unittest.TestCase):
                 posthog_distinct_id="test-user",
             )
 
-            self.assertEqual(len(self.client.capture.call_args_list), 1)
-            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self.assertEqual(len(self.client._enqueue.call_args_list), 1)
+            properties = self.client._enqueue.call_args_list[0][0][0]["properties"]
             self._assert_system_prompt_captured(properties["$ai_input"])

posthog/test/test_client.py

@@ -648,6 +648,7 @@ class TestClient(unittest.TestCase):
                 person_properties={},
                 group_properties={},
                 geoip_disable=True,
+                device_id=None,
             )
 
     @mock.patch("posthog.client.flags")
@@ -712,6 +713,7 @@ class TestClient(unittest.TestCase):
                 person_properties={},
                 group_properties={},
                 geoip_disable=False,
+                device_id=None,
             )
 
     @mock.patch("posthog.client.flags")
@@ -1911,6 +1913,7 @@ class TestClient(unittest.TestCase):
             person_properties={"distinct_id": "some_id"},
             group_properties={},
             geoip_disable=True,
+            device_id=None,
             flag_keys_to_evaluate=["random_key"],
         )
         patch_flags.reset_mock()
@@ -1926,6 +1929,7 @@ class TestClient(unittest.TestCase):
             person_properties={"distinct_id": "feature_enabled_distinct_id"},
             group_properties={},
             geoip_disable=True,
+            device_id=None,
             flag_keys_to_evaluate=["random_key"],
         )
         patch_flags.reset_mock()
@@ -1939,6 +1943,7 @@ class TestClient(unittest.TestCase):
             person_properties={"distinct_id": "all_flags_payloads_id"},
             group_properties={},
             geoip_disable=False,
+            device_id=None,
         )
 
     @mock.patch("posthog.client.Poller")
@@ -1987,6 +1992,7 @@ class TestClient(unittest.TestCase):
                 "instance": {"$group_key": "app.posthog.com"},
             },
             geoip_disable=False,
+            device_id=None,
             flag_keys_to_evaluate=["random_key"],
         )
 
@@ -2014,6 +2020,7 @@ class TestClient(unittest.TestCase):
                 "instance": {"$group_key": "app.posthog.com"},
             },
             geoip_disable=False,
+            device_id=None,
             flag_keys_to_evaluate=["random_key"],
         )
 
@@ -2031,8 +2038,116 @@ class TestClient(unittest.TestCase):
             person_properties={"distinct_id": "some_id"},
             group_properties={},
             geoip_disable=False,
+            device_id=None,
         )
 
+    @parameterized.expand(
+        [
+            # method, method_args, expected_person_props, expected_flag_keys
+            (
+                "get_feature_flag",
+                ["random_key", "some_id"],
+                {"distinct_id": "some_id"},
+                ["random_key"],
+            ),
+            (
+                "feature_enabled",
+                ["random_key", "some_id"],
+                {"distinct_id": "some_id"},
+                ["random_key"],
+            ),
+            (
+                "get_all_flags_and_payloads",
+                ["some_id"],
+                {"distinct_id": "some_id"},
+                None,
+            ),
+            ("get_all_flags", ["some_id"], {"distinct_id": "some_id"}, None),
+            ("get_flags_decision", ["some_id"], {}, None),
+        ]
+    )
+    @mock.patch("posthog.client.flags")
+    def test_device_id_is_passed_to_flags_request(
+        self,
+        method,
+        method_args,
+        expected_person_props,
+        expected_flag_keys,
+        patch_flags,
+    ):
+        """Test that device_id is properly passed to the flags request when provided."""
+        patch_flags.return_value = {"featureFlags": {"beta-feature": "random-variant"}}
+        client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail)
+
+        getattr(client, method)(*method_args, device_id="test-device-123")
+
+        expected_call = {
+            "distinct_id": "some_id",
+            "groups": {},
+            "person_properties": expected_person_props,
+            "group_properties": {},
+            "geoip_disable": True,
+            "device_id": "test-device-123",
+        }
+        if expected_flag_keys:
+            expected_call["flag_keys_to_evaluate"] = expected_flag_keys
+
+        patch_flags.assert_called_with(
+            "random_key", "https://us.i.posthog.com", timeout=3, **expected_call
+        )
+
+    @mock.patch("posthog.client.flags")
+    def test_device_id_from_context_is_used_in_flags_request(self, patch_flags):
+        """Test that device_id from context is used in flags request when not explicitly provided."""
+        from posthog.contexts import new_context, set_context_device_id
+
+        patch_flags.return_value = {
+            "featureFlags": {
+                "beta-feature": "random-variant",
+            }
+        }
+        client = Client(
+            FAKE_TEST_API_KEY,
+            on_error=self.set_fail,
+        )
+
+        # Test that device_id from context is used
+        with new_context():
+            set_context_device_id("context-device-id")
+            client.get_feature_flag("random_key", "some_id")
+            patch_flags.assert_called_with(
+                "random_key",
+                "https://us.i.posthog.com",
+                timeout=3,
+                distinct_id="some_id",
+                groups={},
+                person_properties={"distinct_id": "some_id"},
+                group_properties={},
+                geoip_disable=True,
+                device_id="context-device-id",
+                flag_keys_to_evaluate=["random_key"],
+            )
+
+        # Test that explicit device_id overrides context
+        patch_flags.reset_mock()
+        with new_context():
+            set_context_device_id("context-device-id")
+            client.get_feature_flag(
+                "random_key", "some_id", device_id="explicit-device-id"
+            )
+            patch_flags.assert_called_with(
+                "random_key",
+                "https://us.i.posthog.com",
+                timeout=3,
+                distinct_id="some_id",
+                groups={},
+                person_properties={"distinct_id": "some_id"},
+                group_properties={},
+                geoip_disable=True,
+                device_id="explicit-device-id",
+                flag_keys_to_evaluate=["random_key"],
+            )
+
     @parameterized.expand(
         [
             # name, sys_platform, version_info, expected_runtime, expected_version, expected_os, expected_os_version, platform_method, platform_return, distro_info

posthog/test/test_consumer.py

@@ -1,8 +1,10 @@
 import json
 import time
 import unittest
+from typing import Any
 
 import mock
+from parameterized import parameterized
 
 try:
     from queue import Queue
@@ -14,15 +16,19 @@ from posthog.request import APIError
 from posthog.test.test_utils import TEST_API_KEY
 
 
+def _track_event(event_name: str = "python event") -> dict[str, str]:
+    return {"type": "track", "event": event_name, "distinct_id": "distinct_id"}
+
+
 class TestConsumer(unittest.TestCase):
-    def test_next(self):
+    def test_next(self) -> None:
         q = Queue()
         consumer = Consumer(q, "")
         q.put(1)
         next = consumer.next()
         self.assertEqual(next, [1])
 
-    def test_next_limit(self):
+    def test_next_limit(self) -> None:
         q = Queue()
         flush_at = 50
         consumer = Consumer(q, "", flush_at)
@@ -31,7 +37,7 @@ class TestConsumer(unittest.TestCase):
         next = consumer.next()
         self.assertEqual(next, list(range(flush_at)))
 
-    def test_dropping_oversize_msg(self):
+    def test_dropping_oversize_msg(self) -> None:
         q = Queue()
         consumer = Consumer(q, "")
         oversize_msg = {"m": "x" * MAX_MSG_SIZE}
@@ -40,15 +46,14 @@ class TestConsumer(unittest.TestCase):
         self.assertEqual(next, [])
         self.assertTrue(q.empty())
 
-    def test_upload(self):
+    def test_upload(self) -> None:
         q = Queue()
         consumer = Consumer(q, TEST_API_KEY)
-        track = {"type": "track", "event": "python event", "distinct_id": "distinct_id"}
-        q.put(track)
+        q.put(_track_event())
         success = consumer.upload()
         self.assertTrue(success)
 
-    def test_flush_interval(self):
+    def test_flush_interval(self) -> None:
         # Put _n_ items in the queue, pausing a little bit more than
         # _flush_interval_ after each one.
         # The consumer should upload _n_ times.
@@ -57,17 +62,12 @@ class TestConsumer(unittest.TestCase):
         consumer = Consumer(q, TEST_API_KEY, flush_at=10, flush_interval=flush_interval)
         with mock.patch("posthog.consumer.batch_post") as mock_post:
             consumer.start()
-            for i in range(0, 3):
-                track = {
-                    "type": "track",
-                    "event": "python event %d" % i,
-                    "distinct_id": "distinct_id",
-                }
-                q.put(track)
+            for i in range(3):
+                q.put(_track_event("python event %d" % i))
                 time.sleep(flush_interval * 1.1)
             self.assertEqual(mock_post.call_count, 3)
 
-    def test_multiple_uploads_per_interval(self):
+    def test_multiple_uploads_per_interval(self) -> None:
         # Put _flush_at*2_ items in the queue at once, then pause for
         # _flush_interval_. The consumer should upload 2 times.
         q = Queue()
@@ -78,88 +78,60 @@ class TestConsumer(unittest.TestCase):
         )
         with mock.patch("posthog.consumer.batch_post") as mock_post:
             consumer.start()
-            for i in range(0, flush_at * 2):
-                track = {
-                    "type": "track",
-                    "event": "python event %d" % i,
-                    "distinct_id": "distinct_id",
-                }
-                q.put(track)
+            for i in range(flush_at * 2):
+                q.put(_track_event("python event %d" % i))
             time.sleep(flush_interval * 1.1)
             self.assertEqual(mock_post.call_count, 2)
 
-    def test_request(self):
+    def test_request(self) -> None:
         consumer = Consumer(None, TEST_API_KEY)
-        track = {"type": "track", "event": "python event", "distinct_id": "distinct_id"}
-        consumer.request([track])
+        consumer.request([_track_event()])
 
-    def _test_request_retry(self, consumer, expected_exception, exception_count):
-        def mock_post(*args, **kwargs):
-            mock_post.call_count += 1
-            if mock_post.call_count <= exception_count:
-                raise expected_exception
+    def _run_retry_test(
+        self, exception: Exception, exception_count: int, retries: int = 10
+    ) -> None:
+        call_count = [0]
 
-        mock_post.call_count = 0
+        def mock_post(*args: Any, **kwargs: Any) -> None:
+            call_count[0] += 1
+            if call_count[0] <= exception_count:
+                raise exception
 
+        consumer = Consumer(None, TEST_API_KEY, retries=retries)
         with mock.patch(
             "posthog.consumer.batch_post", mock.Mock(side_effect=mock_post)
         ):
-            track = {
-                "type": "track",
-                "event": "python event",
-                "distinct_id": "distinct_id",
-            }
-            # request() should succeed if the number of exceptions raised is
-            # less than the retries paramater.
-            if exception_count <= consumer.retries:
-                consumer.request([track])
+            if exception_count <= retries:
+                consumer.request([_track_event()])
             else:
-                # if exceptions are raised more times than the retries
-                # parameter, we expect the exception to be returned to
-                # the caller.
-                try:
-                    consumer.request([track])
-                except type(expected_exception) as exc:
-                    self.assertEqual(exc, expected_exception)
-                else:
-                    self.fail(
-                        "request() should raise an exception if still failing after %d retries"
-                        % consumer.retries
-                    )
+                with self.assertRaises(type(exception)):
+                    consumer.request([_track_event()])
 
-    def test_request_retry(self):
-        # we should retry on general errors
-        consumer = Consumer(None, TEST_API_KEY)
-        self._test_request_retry(consumer, Exception("generic exception"), 2)
+    @parameterized.expand(
+        [
+            ("general_errors", Exception("generic exception"), 2),
+            ("server_errors", APIError(500, "Internal Server Error"), 2),
+            ("rate_limit_errors", APIError(429, "Too Many Requests"), 2),
+        ]
+    )
+    def test_request_retries_on_retriable_errors(
+        self, _name: str, exception: Exception, exception_count: int
+    ) -> None:
+        self._run_retry_test(exception, exception_count)
 
-        # we should retry on server errors
-        consumer = Consumer(None, TEST_API_KEY)
-        self._test_request_retry(consumer, APIError(500, "Internal Server Error"), 2)
+    def test_request_does_not_retry_client_errors(self) -> None:
+        with self.assertRaises(APIError):
+            self._run_retry_test(APIError(400, "Client Errors"), 1)
 
-        # we should retry on HTTP 429 errors
-        consumer = Consumer(None, TEST_API_KEY)
-        self._test_request_retry(consumer, APIError(429, "Too Many Requests"), 2)
+    def test_request_fails_when_exceptions_exceed_retries(self) -> None:
+        self._run_retry_test(APIError(500, "Internal Server Error"), 4, retries=3)
 
-        # we should NOT retry on other client errors
-        consumer = Consumer(None, TEST_API_KEY)
-        api_error = APIError(400, "Client Errors")
-        try:
-            self._test_request_retry(consumer, api_error, 1)
-        except APIError:
-            pass
-        else:
-            self.fail("request() should not retry on client errors")
-
-        # test for number of exceptions raise > retries value
-        consumer = Consumer(None, TEST_API_KEY, retries=3)
-        self._test_request_retry(consumer, APIError(500, "Internal Server Error"), 3)
-
-    def test_pause(self):
+    def test_pause(self) -> None:
         consumer = Consumer(None, TEST_API_KEY)
         consumer.pause()
         self.assertFalse(consumer.running)
 
-    def test_max_batch_size(self):
+    def test_max_batch_size(self) -> None:
         q = Queue()
         consumer = Consumer(q, TEST_API_KEY, flush_at=100000, flush_interval=3)
         properties = {}
@@ -175,7 +147,7 @@ class TestConsumer(unittest.TestCase):
         # Let's capture 8MB of data to trigger two batches
         n_msgs = int(8_000_000 / msg_size)
 
-        def mock_post_fn(_, data, **kwargs):
+        def mock_post_fn(_: str, data: str, **kwargs: Any) -> mock.Mock:
             res = mock.Mock()
             res.status_code = 200
             request_size = len(data.encode())
@@ -194,3 +166,34 @@ class TestConsumer(unittest.TestCase):
                 q.put(track)
             q.join()
             self.assertEqual(mock_post.call_count, 2)
+
+    @parameterized.expand(
+        [
+            ("on_error_succeeds", False),
+            ("on_error_raises", True),
+        ]
+    )
+    def test_upload_exception_calls_on_error_and_does_not_raise(
+        self, _name: str, on_error_raises: bool
+    ) -> None:
+        on_error_called: list[tuple[Exception, list[dict[str, str]]]] = []
+
+        def on_error(e: Exception, batch: list[dict[str, str]]) -> None:
+            on_error_called.append((e, batch))
+            if on_error_raises:
+                raise Exception("on_error failed")
+
+        q = Queue()
+        consumer = Consumer(q, TEST_API_KEY, on_error=on_error)
+        track = _track_event()
+        q.put(track)
+
+        with mock.patch.object(
+            consumer, "request", side_effect=Exception("request failed")
+        ):
+            result = consumer.upload()
+
+        self.assertFalse(result)
+        self.assertEqual(len(on_error_called), 1)
+        self.assertEqual(str(on_error_called[0][0]), "request failed")
+        self.assertEqual(on_error_called[0][1], [track])

posthog/test/test_contexts.py

@@ -191,6 +191,32 @@ class TestContexts(unittest.TestCase):
             assert get_context_distinct_id() == "user123"
             assert get_context_session_id() == "session456"
 
+    def test_child_tags_override_parent_tags_in_non_fresh_context(self):
+        with new_context(fresh=True):
+            tag("shared_key", "parent_value")
+            tag("parent_only", "parent")
+
+            with new_context(fresh=False):
+                # Child should inherit parent tags
+                assert get_tags()["parent_only"] == "parent"
+
+                # Child sets same key - should override parent
+                tag("shared_key", "child_value")
+                tag("child_only", "child")
+
+                tags = get_tags()
+                # Child value should win for shared key
+                assert tags["shared_key"] == "child_value"
+                # Both parent and child tags should be present
+                assert tags["parent_only"] == "parent"
+                assert tags["child_only"] == "child"
+
+            # Parent context should be unchanged
+            parent_tags = get_tags()
+            assert parent_tags["shared_key"] == "parent_value"
+            assert parent_tags["parent_only"] == "parent"
+            assert "child_only" not in parent_tags
+
     def test_scoped_decorator_with_context_ids(self):
         @scoped()
         def function_with_context():

posthog/version.py

@@ -1,4 +1,4 @@
-VERSION = "7.4.2"
+VERSION = "7.6.0"
 
 if __name__ == "__main__":
     print(VERSION, end="")  # noqa: T201