feat(flags): make the sendFeatureFlags parameter more declarative and ergonomic (#283)

* feat(llmo): Use default PH client for langchain

* chore: Run formatter

* feat: Test the CallbackHandler without any PH client

* chore: Run formatter

.github/workflows/call-flags-project-board.yml

@@ -0,0 +1,17 @@
+# This workflow is used to call the flags-project-board workflow when a pull request is opened, ready for review, review requested, synchronized, converted to draft, or reopened.
+# It is used to update the feature flags project board with the pull request information.
+
+name: Call Feature Flags Project Workflow
+
+on:
+    pull_request:
+        types: [opened, ready_for_review, review_requested, synchronize, converted_to_draft, reopened]
+
+jobs:
+    call-flags-project:
+        uses: PostHog/.github/.github/workflows/flags-project-board.yml@main
+        with:
+            pr_number: ${{ github.event.pull_request.number }}
+            pr_node_id: ${{ github.event.pull_request.node_id }}
+            is_draft: ${{ github.event.pull_request.draft }}
+        secrets: inherit

.github/workflows/ci.yml

@@ -9,38 +9,29 @@ jobs:
         runs-on: ubuntu-latest
 
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@85e6279cec87321a52edac9c87bce653a07cf6c2
               with:
                   fetch-depth: 1
 
             - name: Set up Python 3.11
-              uses: actions/setup-python@v2
+              uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55
               with:
                   python-version: 3.11.11
 
-            - uses: actions/cache@v3
+            - name: Install uv
+              uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5.4.1
               with:
-                  path: ~/.cache/pip
-                  key: ${{ runner.os }}-pip-${{ hashFiles('setup.py') }}
-                  restore-keys: |
-                      ${{ runner.os }}-pip-
+                  enable-cache: true
+                  pyproject-file: 'pyproject.toml'
 
             - name: Install dev dependencies
+              shell: bash
               run: |
-                  python -m pip install -e .[dev]
-              if: steps.cache.outputs.cache-hit != 'true'
+                  UV_PROJECT_ENVIRONMENT=$pythonLocation uv sync --extra dev
 
-            - name: Check formatting with black
+            - name: Check formatting with ruff
               run: |
-                  black --check .
-
-            - name: Lint with flake8
-              run: |
-                  flake8 posthog --ignore E501,W503
-
-            - name: Check import order with isort
-              run: |
-                  isort --check-only .
+                  ruff format --check .
 
             - name: Check types with mypy
               run: |
@@ -54,18 +45,25 @@ jobs:
                 python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
 
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@85e6279cec87321a52edac9c87bce653a07cf6c2
               with:
                   fetch-depth: 1
 
             - name: Set up Python ${{ matrix.python-version }}
-              uses: actions/setup-python@v2
+              uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55
               with:
                   python-version: ${{ matrix.python-version }}
 
-            - name: Install requirements.txt dependencies with pip
+            - name: Install uv
+              uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5.4.1
+              with:
+                  enable-cache: true
+                  pyproject-file: 'pyproject.toml'
+
+            - name: Install test dependencies
+              shell: bash
               run: |
-                  python -m pip install -e .[test]
+                  UV_PROJECT_ENVIRONMENT=$pythonLocation uv sync --extra test
 
             - name: Run posthog tests
               run: |

.github/workflows/release.yaml

@@ -1,38 +1,51 @@
-name: 'Release'
+name: "Release"
 
 on:
-  - workflow_dispatch
+  push:
+    branches:
+      - master
+    paths:
+      - "posthog/version.py"
+  workflow_dispatch:
 
 jobs:
-    release:
-        name: Publish release
-        runs-on: ubuntu-20.04
+  release:
+    name: Publish release
+    runs-on: ubuntu-latest
+    env:
+      TWINE_USERNAME: __token__
+      TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@85e6279cec87321a52edac9c87bce653a07cf6c2
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.POSTHOG_BOT_GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55
+        with:
+          python-version: 3.11.11
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5.4.1
+        with:
+            enable-cache: true
+            pyproject-file: 'pyproject.toml'
+            
+      - name: Detect version
+        run: echo "REPO_VERSION=$(python3 posthog/version.py)" >> $GITHUB_ENV
+
+      - name: Prepare for building release
+        run: uv sync --extra dev
+
+      - name: Push releases to PyPI
+        run: uv run make release && uv run make release_analytics
+
+      - name: Create GitHub release
+        uses: actions/create-release@0cb9c9b65d5d1901c1f53e5e66eaf4afd303e70e # v1
         env:
-            TWINE_USERNAME: __token__
-            TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        steps:
-            - name: Checkout the repository
-              uses: actions/checkout@v2
-              with:
-                  fetch-depth: 0
-                  token: ${{ secrets.POSTHOG_BOT_GITHUB_TOKEN }}
-
-            - name: Set up Python
-              uses: actions/setup-python@v2
-
-            - name: Detect version
-              run: echo "REPO_VERSION=$(python3 posthog/version.py)" >> $GITHUB_ENV
-
-            - name: Prepare for building release
-              run: pip install -U pip setuptools wheel twine
-
-            - name: Push release to PyPI
-              run: make release && make release_analytics
-
-            - name: Create GitHub release
-              uses: actions/create-release@v1
-              env:
-                  GITHUB_TOKEN: ${{ secrets.POSTHOG_BOT_GITHUB_TOKEN }}
-              with:
-                  tag_name: v${{ env.REPO_VERSION }}
-                  release_name: ${{ env.REPO_VERSION }}
+          GITHUB_TOKEN: ${{ secrets.POSTHOG_BOT_GITHUB_TOKEN }}
+        with:
+          tag_name: v${{ env.REPO_VERSION }}
+          release_name: ${{ env.REPO_VERSION }}

.gitignore

@@ -17,3 +17,5 @@ posthog-analytics
 .coverage
 pyrightconfig.json
 .env
+.DS_Store
+posthog-python-references.json

.pre-commit-config.yaml

@@ -1,9 +1,10 @@
 repos:
-  - repo: https://github.com/psf/black
-    rev: stable
-    hooks:
-    - id: black
-  - repo: https://github.com/pycqa/isort
-    rev: 5.7.0
-    hooks:
-      - id: isort
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.11.12
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format

BEFORE_SEND.md

@@ -0,0 +1,237 @@
+# Before Send Hook
+
+The `before_send` parameter allows you to modify or filter events before they are sent to PostHog. This is useful for:
+
+- **Privacy**: Removing or masking sensitive data (PII)
+- **Filtering**: Dropping unwanted events (test events, internal users, etc.)
+- **Enhancement**: Adding custom properties to all events
+- **Transformation**: Modifying event names or property formats
+
+## Basic Usage
+
+```python
+import posthog
+from typing import Optional, Dict, Any
+
+def my_before_send(event: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Process event before sending to PostHog.
+    
+    Args:
+        event: The event dictionary containing 'event', 'distinct_id', 'properties', etc.
+    
+    Returns:
+        Modified event dictionary to send, or None to drop the event
+    """
+    # Your processing logic here
+    return event
+
+# Initialize client with before_send hook
+client = posthog.Client(
+    api_key="your-project-api-key",
+    before_send=my_before_send
+)
+```
+
+## Common Use Cases
+
+### 1. Filter Out Events
+
+```python
+from typing import Optional, Any
+
+def filter_events_by_property_or_event_name(event: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """Drop events from internal users or test environments."""
+    properties = event.get("properties", {})
+    
+    # Choose some property from your events
+    event_source = properties.get("event_source", "")
+    if event_source.endswith("internal"):
+        return None  # Drop the event
+    
+    # Filter out test events
+    if event.get("event") == "test_event":
+        return None
+    
+    return event
+```
+
+### 2. Remove/Mask PII Data
+
+```python
+from typing import Optional, Any
+
+def scrub_pii(event: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """Remove or mask personally identifiable information."""
+    properties = event.get("properties", {})
+    
+    # Mask email but keep domain for analytics
+    if "email" in properties:
+        email = properties["email"]
+        if "@" in email:
+            domain = email.split("@")[1]
+            properties["email"] = f"***@{domain}"
+        else:
+            properties["email"] = "***"
+    
+    # Remove sensitive fields entirely
+    sensitive_fields = ["my_business_info", "secret_things"]
+    for field in sensitive_fields:
+        properties.pop(field, None)
+    
+    return event
+```
+
+### 3. Add Custom Properties
+
+```python
+from typing import Optional, Any
+
+from datetime import datetime
+from typing import Optional, Any
+
+def add_context(event: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """Add custom properties to all events."""
+    if "properties" not in event:
+        event["properties"] = {}
+    
+    event["properties"].update({
+        "app_version": "2.1.0",
+        "environment": "production", 
+        "processed_at": datetime.now().isoformat()
+    })
+    
+    return event
+```
+
+### 4. Transform Event Names
+
+```python
+from typing import Optional, Any
+
+def normalize_event_names(event: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """Convert event names to a consistent format."""
+    original_event = event.get("event")
+    if original_event:
+        # Convert to snake_case
+        normalized = original_event.lower().replace(" ", "_").replace("-", "_")
+        event["event"] = f"app_{normalized}"
+    
+    return event
+```
+
+### 5. Log and drop in "dev" mode
+
+When running in local dev often, you want to log but drop all events
+
+
+```python
+from typing import Optional, Any
+
+def log_and_drop_all(event: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """Convert event names to a consistent format."""
+    print(event)
+    
+    return None
+```
+
+### 6. Combined Processing
+
+```python
+from typing import Optional, Any
+
+def comprehensive_processor(event: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """Apply multiple transformations in sequence."""
+    
+    # Step 1: Filter unwanted events
+    if should_drop_event(event):
+        return None
+    
+    # Step 2: Scrub PII
+    event = scrub_pii(event)
+    
+    # Step 3: Add context
+    event = add_context(event)
+    
+    # Step 4: Normalize names
+    event = normalize_event_names(event)
+    
+    return event
+
+def should_drop_event(event: dict[str, Any]) -> bool:
+    """Determine if event should be dropped."""
+    # Your filtering logic
+    return False
+```
+
+## Error Handling
+
+If your `before_send` function raises an exception, PostHog will:
+
+1. Log the error 
+2. Continue with the original, unmodified event
+3. Not crash your application
+
+```python
+from typing import Optional, Any
+
+def risky_before_send(event: dict[str, Any]) -> Optional[dict[str, Any]]:
+    # If this raises an exception, the original event will be sent
+    risky_operation()
+    return event
+```
+
+## Complete Example
+
+```python
+import posthog
+from typing import Optional, Any
+import re
+
+def production_before_send(event: dict[str, Any]) -> Optional[dict[str, Any]]:
+    try:
+        properties = event.get("properties", {})
+        
+        # 1. Filter out bot traffic
+        user_agent = properties.get("$user_agent", "")
+        if re.search(r'bot|crawler|spider', user_agent, re.I):
+            return None
+        
+        # 2. Filter out internal traffic  
+        ip = properties.get("$ip", "")
+        if ip.startswith("192.168.") or ip.startswith("10."):
+            return None
+        
+        # 3. Scrub email PII but keep domain
+        if "email" in properties:
+            email = properties["email"]
+            if "@" in email:
+                domain = email.split("@")[1]
+                properties["email"] = f"***@{domain}"
+        
+        # 4. Add custom context
+        properties.update({
+            "app_version": "1.0.0",
+            "build_number": "123"
+        })
+        
+        # 5. Normalize event name
+        if event.get("event"):
+            event["event"] = event["event"].lower().replace(" ", "_")
+        
+        return event
+        
+    except Exception as e:
+        # Log error but don't crash
+        print(f"Error in before_send: {e}")
+        return event  # Return original event on error
+
+# Usage
+client = posthog.Client(
+    api_key="your-api-key",
+    before_send=production_before_send
+)
+
+# All events will now be processed by your before_send function
+client.capture("user_123", "Page View", {"url": "/home"})
+```

CHANGELOG.md

@@ -1,3 +1,265 @@
+# 6.3.0 - 2025-07-22
+
+- feat: Enhanced `send_feature_flags` parameter to accept `SendFeatureFlagsOptions` object for declarative control over local/remote evaluation and custom properties
+
+# 6.2.1 - 2025-07-21
+
+- feat: make `posthog_client` an optional argument in PostHog AI providers wrappers (`posthog.ai.*`), intuitively using the default client as the default
+
+# 6.1.1 - 2025-07-16
+
+- fix: correctly capture exceptions processed by Django from views or middleware
+
+# 6.1.0 - 2025-07-10
+
+- feat: decouple feature flag local evaluation from personal API keys; support decrypting remote config payloads without relying on the feature flags poller
+
+# 6.0.4 - 2025-07-09
+
+- fix: add POSTHOG_MW_CLIENT setting to django middleware, to support custom clients for exception capture.
+
+# 6.0.3 - 2025-07-07
+
+- feat: add a feature flag evaluation cache (local storage or redis) to support returning flag evaluations when the service is down
+
+# 6.0.2 - 2025-07-02
+
+- fix: send_feature_flags changed to default to false in `Client::capture_exception`
+
+# 6.0.1
+
+- fix: response `$process_person_profile` property when passed to capture
+
+# 6.0.0
+
+This release contains a number of major breaking changes:
+
+- feat: make distinct_id an optional parameter in posthog.capture and related functions
+- feat: make capture and related functions return `Optional[str]`, which is the UUID of the sent event, if it was sent
+- fix: remove `identify` (prefer `posthog.set()`), and `page` and `screen` (prefer `posthog.capture()`)
+- fix: delete exception-capture specific integrations module. Prefer the general-purpose django middleware as a replacement for the django `Integration`.
+
+To migrate to this version, you'll mostly just need to switch to using named keyword arguments, rather than positional ones. For example:
+
+```python
+# Old calling convention
+posthog.capture("user123", "button_clicked", {"button_id": "123"})
+# New calling convention
+posthog.capture(distinct_id="user123", event="button_clicked", properties={"button_id": "123"})
+
+# Better pattern
+with posthog.new_context():
+    posthog.identify_context("user123")
+
+    # The event name is the first argument, and can be passed positionally, or as a keyword argument in a later position
+    posthog.capture("button_pressed")
+```
+
+Generally, arguments are now appropriately typed, and docstrings have been updated. If something is unclear, please open an issue, or submit a PR!
+
+# 5.4.0 - 2025-06-20
+
+- feat: add support to session_id context on page method
+
+# 5.3.0 - 2025-06-19
+
+- fix: safely handle exception values
+
+# 5.2.0 - 2025-06-19
+
+- feat: construct artificial stack traces if no traceback is available on a captured exception
+
+## 5.1.0 - 2025-06-18
+
+- feat: session and distinct ID's can now be associated with contexts, and are used as such
+- feat: django http request middleware
+
+## 5.0.0 - 2025-06-16
+
+- fix: removed deprecated sentry integration
+
+## 4.10.0 - 2025-06-13
+
+- fix: no longer fail in autocapture.
+
+## 4.9.0 - 2025-06-13
+
+- feat(ai): track reasoning and cache tokens in the LangChain callback
+
+## 4.8.0 - 2025-06-10
+
+- fix: export scoped, rather than tracked, decorator
+- feat: allow use of contexts without error tracking
+
+## 4.7.0 - 2025-06-10
+
+- feat: add support for parse endpoint in responses API (no longer beta)
+
+## 4.6.2 - 2025-06-09
+
+- fix: replace `import posthog` with direct method imports
+
+## 4.6.1 - 2025-06-09
+
+- fix: replace `import posthog` in `posthoganalytics` package
+
+## 4.6.0 - 2025-06-09
+
+- feat: add additional user and request context to captured exceptions via the Django integration
+- feat: Add `setup()` function to initialise default client
+
+## 4.5.0 - 2025-06-09
+
+- feat: add before_send callback (#249)
+
+## 4.4.2- 2025-06-09
+
+- empty point release to fix release automation
+
+## 4.4.1 2025-06-09
+
+- empty point release to fix release automation
+
+## 4.4.0 - 2025-06-09
+
+- Use the new `/flags` endpoint for all feature flag evaluations (don't fall back to `/decide` at all)
+
+## 4.3.2 - 2025-06-06
+
+1. Add context management:
+
+- New context manager with `posthog.new_context()`
+- Tag functions: `posthog.tag()`, `posthog.get_tags()`, `posthog.clear_tags()`
+- Function decorator:
+  - `@posthog.scoped` - Creates context and captures exceptions thrown within the function
+- Automatic deduplication of exceptions to ensure each exception is only captured once
+
+2. fix: feature flag request use geoip_disable (#235)
+3. chore: pin actions versions (#210)
+4. fix: opinionated setup and clean fn fix (#240)
+5. fix: release action failed (#241)
+
+## 4.2.0 - 2025-05-22
+
+Add support for google gemini
+
+## 4.1.0 - 2025-05-22
+
+Moved ai openai package to a composition approach over inheritance.
+
+## 4.0.1 – 2025-04-29
+
+1. Remove deprecated `monotonic` library. Use Python's core `time.monotonic` function instead
+2. Clarify Python 3.9+ is required
+
+## 4.0.0 - 2025-04-24
+
+1. Added new method `get_feature_flag_result` which returns a `FeatureFlagResult` object. This object breaks down the result of a feature flag into its enabled state, variant, and payload. The benefit of this method is it allows you to retrieve the result of a feature flag and its payload in a single API call. You can call `get_value` on the result to get the value of the feature flag, which is the same value returned by `get_feature_flag` (aka the string `variant` if the flag is a multivariate flag or the `boolean` value if the flag is a boolean flag).
+
+Example:
+
+```python
+result = posthog.get_feature_flag_result("my-flag", "distinct_id")
+print(result.enabled)     # True or False
+print(result.variant)     # 'the-variant-value' or None
+print(result.payload)     # {'foo': 'bar'}
+print(result.get_value()) # 'the-variant-value' or True or False
+print(result.reason)      # 'matched condition set 2' (Not available for local evaluation)
+```
+
+Breaking change:
+
+1. `get_feature_flag_payload` now deserializes payloads from JSON strings to `Any`. Previously, it returned the payload as a JSON encoded string.
+
+Before:
+
+```python
+payload = get_feature_flag_payload('key', 'distinct_id') # "{\"some\": \"payload\"}"
+```
+
+After:
+
+```python
+payload = get_feature_flag_payload('key', 'distinct_id') # {"some": "payload"}
+```
+
+## 3.25.0 – 2025-04-15
+
+1. Roll out new `/flags` endpoint to 100% of `/decide` traffic, excluding the top 10 customers.
+
+## 3.24.3 – 2025-04-15
+
+1. Fix hash inclusion/exclusion for flag rollout
+
+## 3.24.2 – 2025-04-15
+
+1. Roll out new /flags endpoint to 10% of /decide traffic
+
+## 3.24.1 – 2025-04-11
+
+1. Add `log_captured_exceptions` option to proxy setup
+
+## 3.24.0 – 2025-04-10
+
+1. Add config option to `log_captured_exceptions`
+
+## 3.23.0 – 2025-03-26
+
+1. Expand automatic retries to include read errors (e.g. RemoteDisconnected)
+
+## 3.22.0 – 2025-03-26
+
+1. Add more information to `$feature_flag_called` events.
+2. Support for the `/decide?v=4` endpoint which contains more information about feature flags.
+
+## 3.21.0 – 2025-03-17
+
+1. Support serializing dataclasses.
+
+## 3.20.0 – 2025-03-13
+
+1. Add support for OpenAI Responses API.
+
+## 3.19.2 – 2025-03-11
+
+1. Fix install requirements for analytics package
+
+## 3.19.1 – 2025-03-11
+
+1. Fix bug where None is sent as delta in azure
+
+## 3.19.0 – 2025-03-04
+
+1. Add support for tool calls in OpenAI and Anthropic.
+2. Add support for cached tokens.
+
+## 3.18.1 – 2025-03-03
+
+1. Improve quota-limited feature flag logs
+
+## 3.18.0 - 2025-02-28
+
+1. Add support for Azure OpenAI.
+
+## 3.17.0 - 2025-02-27
+
+1. The LangChain handler now captures tools in `$ai_generation` events, in property `$ai_tools`. This allows for displaying tools provided to the LLM call in PostHog UI. Note that support for `$ai_tools` in OpenAI and Anthropic SDKs is coming soon.
+
+## 3.16.0 - 2025-02-26
+
+1. feat: add some platform info to events (#198)
+
+## 3.15.1 - 2025-02-23
+
+1. Fix async client support for OpenAI.
+
+## 3.15.0 - 2025-02-19
+
+1. Support quota-limited feature flags
+
+## 3.14.2 - 2025-02-19
+
+1. Evaluate feature flag payloads with case sensitivity correctly. Fixes <https://github.com/PostHog/posthog-python/issues/178>
 
 ## 3.14.1 - 2025-02-18
 

LICENSE

@@ -20,3 +20,29 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+---
+
+Some files in this codebase contain code from getsentry/sentry-javascript by Software, Inc. dba Sentry.
+In such cases it is explicitly stated in the file header. This license only applies to the relevant code in such cases.
+
+MIT License
+
+Copyright (c) 2012 Functional Software, Inc. dba Sentry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -1,6 +1,5 @@
 lint:
-	pylint --rcfile=.pylintrc --reports=y --exit-zero analytics | tee pylint.out
-	flake8 --max-complexity=10 --statistics analytics > flake8.out || true
+	uvx ruff format
 
 test:
 	coverage run -m pytest
@@ -17,22 +16,42 @@ release_analytics:
 	rm -rf posthoganalytics
 	mkdir posthoganalytics
 	cp -r posthog/* posthoganalytics/
-	find ./posthoganalytics -type f -exec sed -i '' -e 's/from posthog /from posthoganalytics /g' {} \;
-	find ./posthoganalytics -type f -exec sed -i '' -e 's/from posthog\./from posthoganalytics\./g' {} \;
+	find ./posthoganalytics -type f -name "*.py" -exec sed -i.bak -e 's/from posthog /from posthoganalytics /g' {} \;
+	find ./posthoganalytics -type f -name "*.py" -exec sed -i.bak -e 's/from posthog\./from posthoganalytics\./g' {} \;
+	find ./posthoganalytics -name "*.bak" -delete
 	rm -rf posthog
 	python setup_analytics.py sdist bdist_wheel
 	twine upload dist/*
 	mkdir posthog
-	find ./posthoganalytics -type f -exec sed -i '' -e 's/from posthoganalytics /from posthog /g' {} \;
-	find ./posthoganalytics -type f -exec sed -i '' -e 's/from posthoganalytics\./from posthog\./g' {} \;
+	find ./posthoganalytics -type f -name "*.py" -exec sed -i.bak -e 's/from posthoganalytics /from posthog /g' {} \;
+	find ./posthoganalytics -type f -name "*.py" -exec sed -i.bak -e 's/from posthoganalytics\./from posthog\./g' {} \;
+	find ./posthoganalytics -name "*.bak" -delete
 	cp -r posthoganalytics/* posthog/
 	rm -rf posthoganalytics
+	rm -f pyproject.toml
+	cp pyproject.toml.backup pyproject.toml
+	rm -f pyproject.toml.backup
 
 e2e_test:
 	.buildscripts/e2e.sh
 
-django_example:
-	python -m pip install -e ".[sentry]"
-	cd sentry_django_example && python manage.py runserver 8080
+prep_local:
+	rm -rf ../posthog-python-local
+	mkdir ../posthog-python-local
+	cp -r . ../posthog-python-local/
+	cd ../posthog-python-local && rm -rf dist build posthoganalytics .git
+	cd ../posthog-python-local && mkdir posthoganalytics
+	cd ../posthog-python-local && cp -r posthog/* posthoganalytics/
+	cd ../posthog-python-local && find ./posthoganalytics -type f -name "*.py" -exec sed -i.bak -e 's/from posthog /from posthoganalytics /g' {} \;
+	cd ../posthog-python-local && find ./posthoganalytics -type f -name "*.py" -exec sed -i.bak -e 's/from posthog\./from posthoganalytics\./g' {} \;
+	cd ../posthog-python-local && find ./posthoganalytics -name "*.bak" -delete
+	cd ../posthog-python-local && rm -rf posthog
+	cd ../posthog-python-local && sed -i.bak 's/from version import VERSION/from posthoganalytics.version import VERSION/' setup_analytics.py
+	cd ../posthog-python-local && rm setup_analytics.py.bak
+	cd ../posthog-python-local && sed -i.bak 's/"posthog"/"posthoganalytics"/' setup.py
+	cd ../posthog-python-local && rm setup.py.bak
+	cd ../posthog-python-local && python -c "import setup_analytics" 2>/dev/null || true
+	@echo "Local copy created at ../posthog-python-local"
+	@echo "Install with: pip install -e ../posthog-python-local"
 
-.PHONY: test lint release e2e_test
+.PHONY: test lint release e2e_test prep_local

README.md

@@ -1,7 +1,14 @@
 # PostHog Python
 
-[![PyPI](https://img.shields.io/pypi/v/posthog)](https://pypi.org/project/posthog/)
-
+<p align="center">
+  <img alt="posthoglogo" src="https://user-images.githubusercontent.com/65415371/205059737-c8a4f836-4889-4654-902e-f302b187b6a0.png">
+</p>
+<p align="center">
+   <a href="https://pypi.org/project/posthog/"><img alt="pypi installs" src="https://img.shields.io/pypi/v/posthog"/></a>
+   <img alt="GitHub contributors" src="https://img.shields.io/github/contributors/posthog/posthog-python">
+  <img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/posthog/posthog-python"/>
+  <img alt="GitHub closed issues" src="https://img.shields.io/github/issues-closed/posthog/posthog-python"/>
+</p>
 
 Please see the [Python integration docs](https://posthog.com/docs/integrations/python-integration) for details.
 
@@ -9,38 +16,51 @@ Please see the [Python integration docs](https://posthog.com/docs/integrations/p
 
 ### Testing Locally
 
-1. Run `python3 -m venv env` (creates virtual environment called "env")
+We recommend using [uv](https://docs.astral.sh/uv/). It's super fast.
+
+1. Run `uv venv env` (creates virtual environment called "env")
+    * or `python3 -m venv env`
 2. Run `source env/bin/activate` (activates the virtual environment)
-3. Run `python3 -m pip install -e ".[test]"` (installs the package in develop mode, along with test dependencies)
-4. Run `make test`
+3. Run `uv sync --extra dev --extra test` (installs the package in develop mode, along with test dependencies)
+    * or `pip install -e ".[dev,test]"`
+4. you have to run `pre-commit install` to have auto linting pre commit
+5. Run `make test`
   1. To run a specific test do `pytest -k test_no_api_key`
 
+## PostHog recommends `uv` so...
+
+```bash
+uv python install 3.9.19
+uv python pin 3.9.19
+uv venv
+source env/bin/activate
+uv sync --extra dev --extra test
+pre-commit install
+make test
+```
+
 ### Running Locally
 
 Assuming you have a [local version of PostHog](https://posthog.com/docs/developing-locally) running, you can run `python3 example.py` to see the library in action.
 
-### Running the Django Sentry Integration Locally
-
-There's a sample Django project included, called `sentry_django_example`, which explains how to use PostHog with Sentry.
-
-There's 2 places of importance (Changes required are all marked with TODO in the sample project directory)
-
-1. Settings.py
-    1. Input your Sentry DSN
-    2. Input your Sentry Org and ProjectID details into `PosthogIntegration()`
-    3. Add `POSTHOG_DJANGO` to settings.py. This allows the `PosthogDistinctIdMiddleware` to get the distinct_ids
-
-2. urls.py
-    1. This includes the `sentry-debug/` endpoint, which generates an exception
-
-To run things: `make django_example`. This installs the posthog-python library with the sentry-sdk add-on, and then runs the django app.
-Also start the PostHog app locally.
-Then navigate to `http://127.0.0.1:8080/sentry-debug/` and you should get an event in both Sentry and PostHog, with links to each other.
-
 ### Releasing Versions
 
-Updated are released using GitHub Actions: after bumping `version.py` in `master` and adding to `CHANGELOG.md`, go to [our release workflow's page](https://github.com/PostHog/posthog-python/actions/workflows/release.yaml) and dispatch it manually, using workflow from `master`.
+Updates are released automatically using GitHub Actions when `version.py` is updated on `master`. After bumping `version.py` in `master` and adding to `CHANGELOG.md`, the [release workflow](https://github.com/PostHog/posthog-python/blob/master/.github/workflows/release.yaml) will automatically trigger and deploy the new version.
 
-## Questions?
+If you need to check the latest runs or manually trigger a release, you can go to [our release workflow's page](https://github.com/PostHog/posthog-python/actions/workflows/release.yaml) and dispatch it manually, using workflow from `master`.
 
-### [Join our Slack community.](https://join.slack.com/t/posthogusers/shared_invite/enQtOTY0MzU5NjAwMDY3LTc2MWQ0OTZlNjhkODk3ZDI3NDVjMDE1YjgxY2I4ZjI4MzJhZmVmNjJkN2NmMGJmMzc2N2U3Yjc3ZjI5NGFlZDQ)
+
+### Testing changes locally with the PostHog app
+
+You can run `make prep_local`, and it'll create a new folder alongside the SDK repo one called `posthog-python-local`, which you can then import into the posthog project by changing pyproject.toml to look like this:
+```toml
+dependencies = [
+    ...
+    "posthoganalytics" #NOTE: no version number
+    ...
+]
+...
+[tools.uv.sources]
+posthoganalytics = { path = "../posthog-python-local" }
+```
+This'll let you build and test SDK changes fully locally, incorporating them into your local posthog app stack. It mainly takes care of the `posthog -> posthoganalytics` module renaming. You'll need to re-run `make prep_local` each time you make a change, and re-run `uv sync --active` in the posthog app project.

bin/build

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+#/ Usage: bin/build
+#/ Description: Runs linter and mypy
+source bin/helpers/_utils.sh
+set_source_and_root_dir
+
+flake8 posthog --ignore E501,W503
+mypy --no-site-packages --config-file mypy.ini . | mypy-baseline filter

bin/docs

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+#/ Usage: bin/docs
+#/ Description: Generate documentation for the PostHog Python SDK
+source bin/helpers/_utils.sh
+set_source_and_root_dir
+ensure_virtual_env
+
+exec python3 "$(dirname "$0")/docs_scripts/generate_json_schemas.py" "$@" 

bin/docs_scripts/doc_constant.py

@@ -0,0 +1,81 @@
+"""
+Constants for PostHog Python SDK documentation generation.
+"""
+
+from typing import Dict, Union
+
+# Types that are built-in to Python and don't need to be documented
+NO_DOCS_TYPES = [
+    "Client",
+    "any",
+    "int",
+    "float",
+    "bool",
+    "dict",
+    "list",
+    "str",
+    "tuple",
+    "set",
+    "frozenset",
+    "bytes",
+    "bytearray",
+    "memoryview",
+    "range",
+    "slice",
+    "complex",
+    "Union",
+    "Optional",
+    "Any",
+    "Callable",
+    "Type",
+    "TypeVar",
+    "Generic",
+    "Literal",
+    "ClassVar",
+    "Final",
+    "Annotated",
+    "NotRequired",
+    "Required",
+    "None",
+    "NoneType",
+    "object",
+    "Unpack",
+    "BaseException",
+    "Exception",
+]
+
+# Documentation generation metadata
+DOCUMENTATION_METADATA = {
+    "hogRef": "0.1",
+    "slugPrefix": "posthog-python",
+    "specUrl": "https://github.com/PostHog/posthog-python",
+}
+
+# Docstring parsing patterns for new format
+DOCSTRING_PATTERNS = {
+    "examples_section": r"Examples:\s*\n(.*?)(?=\n\s*\n\s*Category:|\Z)",
+    "args_section": r"Args:\s*\n(.*?)(?=\n\s*\n\s*Examples:|\n\s*\n\s*Details:|\n\s*\n\s*Category:|\Z)",
+    "details_section": r"Details:\s*\n(.*?)(?=\n\s*\n\s*Examples:|\n\s*\n\s*Category:|\Z)",
+    "category_section": r"Category:\s*\n\s*(.+?)\s*(?:\n|$)",
+    "code_block": r"```(?:python)?\n(.*?)```",
+    "param_description": r"^\s*{param_name}:\s*(.+?)(?=\n\s*\w+:|\Z)",
+    "args_marker": r"\n\s*Args:\s*\n",
+    "examples_marker": r"\n\s*Examples:\s*\n",
+    "details_marker": r"\n\s*Details:\s*\n",
+    "category_marker": r"\n\s*Category:\s*\n",
+}
+
+# Output file configuration
+OUTPUT_CONFIG: Dict[str, Union[str, int]] = {
+    "output_dir": ".",
+    "filename": "posthog-python-references.json",
+    "indent": 2,
+}
+
+# Documentation structure defaults
+DOC_DEFAULTS = {
+    "showDocs": True,
+    "releaseTag": "public",
+    "return_type_void": "None",
+    "max_optional_params": 3,
+}

bin/docs_scripts/generate_json_schemas.py

@@ -0,0 +1,472 @@
+#!/usr/bin/env python3
+"""
+Generate comprehensive SDK documentation JSON from PostHog Python SDK.
+This script inspects the code and docstrings to create documentation in the specified format.
+"""
+
+import json
+import inspect
+import re
+from dataclasses import is_dataclass, fields
+from typing import get_origin, get_args, Union
+from textwrap import dedent
+from doc_constant import (
+    NO_DOCS_TYPES,
+    DOCUMENTATION_METADATA,
+    DOCSTRING_PATTERNS,
+    OUTPUT_CONFIG,
+    DOC_DEFAULTS,
+)
+import os
+
+
+def extract_examples_from_docstring(docstring: str) -> list:
+    """Extract code examples from docstring."""
+    if not docstring:
+        return []
+
+    examples = []
+
+    # Look for Examples section in the new format
+    examples_section_match = re.search(
+        DOCSTRING_PATTERNS["examples_section"], docstring, re.DOTALL
+    )
+    if examples_section_match:
+        examples_content = examples_section_match.group(1).strip()
+        # Extract code blocks from the Examples section
+        code_blocks = re.findall(
+            DOCSTRING_PATTERNS["code_block"], examples_content, re.DOTALL
+        )
+        for i, code_block in enumerate(code_blocks):
+            # Remove common leading whitespace while preserving relative indentation
+            code = dedent(code_block).strip()
+
+            # Extract name from first comment line if present
+            lines = code.split("\n")
+            name = f"Example {i + 1}"  # Default fallback
+
+            if lines and lines[0].strip().startswith("#"):
+                # Extract name from first comment, keep the comment in the code
+                comment_text = lines[0].strip()[1:].strip()
+                if comment_text:
+                    name = comment_text
+
+            examples.append({"id": f"example_{i + 1}", "name": name, "code": code})
+
+    return examples
+
+
+def extract_details_from_docstring(docstring: str) -> str:
+    """Extract details section from docstring."""
+    if not docstring:
+        return ""
+
+    # Look for Details section
+    details_match = re.search(
+        DOCSTRING_PATTERNS["details_section"], docstring, re.DOTALL
+    )
+    if details_match:
+        details_content = details_match.group(1).strip()
+        # Clean up formatting
+        return details_content.replace("\n", " ")
+
+    return ""
+
+
+def parse_docstring_tags(docstring: str) -> dict:
+    """Parse tags from docstring Category section."""
+    if not docstring:
+        return {}
+
+    tags = {}
+
+    # Extract Category section
+    category_match = re.search(DOCSTRING_PATTERNS["category_section"], docstring)
+    if category_match:
+        category_value = category_match.group(1).strip()
+        tags["category"] = category_value
+
+    return tags
+
+
+def extract_description_from_docstring(docstring: str) -> str:
+    """Extract main description from docstring."""
+    if not docstring:
+        return ""
+
+    # Clean up the docstring
+    cleaned = dedent(docstring).strip()
+
+    # Find the end of the description by looking for first section marker
+    # Check for Args:, Examples:, Details:, or Category: sections
+    section_patterns = [
+        DOCSTRING_PATTERNS["args_marker"],
+        DOCSTRING_PATTERNS["examples_marker"],
+        DOCSTRING_PATTERNS["details_marker"],
+        DOCSTRING_PATTERNS["category_marker"],
+    ]
+
+    end_pos = len(cleaned)
+    for pattern in section_patterns:
+        match = re.search(pattern, cleaned)
+        if match:
+            end_pos = min(end_pos, match.start())
+
+    # Extract description up to the first section marker
+    description = cleaned[:end_pos].strip()
+
+    # Remove one level of \n since it will be rendered as markdown
+    # and \n will be padded in later steps
+    description = description.replace("\n", " ")
+
+    return description
+
+
+def get_type_name(type_annotation) -> str:
+    """Convert type annotation to string name."""
+    if type_annotation is None or type_annotation is type(None):
+        return "any"
+
+    # Handle typing constructs
+    origin = get_origin(type_annotation)
+    if origin is not None:
+        # Handle Union types (including Optional)
+        if origin is Union:
+            args = get_args(type_annotation)
+            if len(args) == 2 and type(None) in args:
+                # This is Optional[Type] - get the non-None type
+                non_none_type = next(arg for arg in args if arg is not type(None))
+                return f"Optional[{get_type_name(non_none_type)}]"
+            else:
+                # Regular Union - list all types
+                type_names = [get_type_name(arg) for arg in args]
+                return f"Union[{', '.join(type_names)}]"
+
+        # Handle other generic types (List, Dict, etc.)
+        origin_name = getattr(origin, "__name__", str(origin))
+        args = get_args(type_annotation)
+        if args:
+            arg_names = [get_type_name(arg) for arg in args]
+            return f"{origin_name}[{', '.join(arg_names)}]"
+        else:
+            return origin_name
+
+    # Handle regular types
+    elif hasattr(type_annotation, "__name__"):
+        return type_annotation.__name__
+    else:
+        return str(type_annotation)
+
+
+def analyze_parameter(param: inspect.Parameter, docstring: str = "") -> dict:
+    """Analyze a function parameter and return its documentation."""
+    # Determine if parameter is optional (has default value)
+    is_optional = param.default == inspect.Parameter.empty
+
+    # Get the type annotation
+    type_annotation = param.annotation
+    param_type = "any"
+
+    if type_annotation != inspect.Parameter.empty:
+        # Handle Union/Optional types first
+        origin = get_origin(type_annotation)
+        if origin is Union:
+            args = get_args(type_annotation)
+            if len(args) == 2 and type(None) in args:
+                # This is Optional[Type]
+                non_none_type = next(arg for arg in args if arg is not type(None))
+                param_type = get_type_name(non_none_type)
+                is_optional = True
+            else:
+                # Other Union types, use first type
+                param_type = get_type_name(args[0]) if args else "any"
+        else:
+            param_type = get_type_name(type_annotation)
+    elif param.default != inspect.Parameter.empty:
+        # No type annotation, but has default value - infer type from default
+        param_type = get_type_name(type(param.default))
+
+    # Extract parameter description from Args section
+    param_description = f"Parameter: {param.name}"
+    if docstring:
+        # Look for Args section and extract description for this parameter
+        args_section_match = re.search(
+            DOCSTRING_PATTERNS["args_section"], docstring, re.DOTALL
+        )
+        if args_section_match:
+            args_content = args_section_match.group(1)
+            # Look for the parameter description
+            param_pattern = DOCSTRING_PATTERNS["param_description"].format(
+                param_name=re.escape(param.name)
+            )
+            param_match = re.search(
+                param_pattern, args_content, re.MULTILINE | re.DOTALL
+            )
+            if param_match:
+                param_description = param_match.group(1).strip().replace("\n", " ")
+
+    param_info = {
+        "name": param.name,
+        "description": param_description,
+        "isOptional": is_optional,
+        "type": param_type,
+    }
+
+    return param_info
+
+
+def analyze_function(func, name: str) -> dict:
+    """Analyze a function and return its documentation."""
+    try:
+        sig = inspect.signature(func)
+        docstring = inspect.getdoc(func) or ""
+
+        # Skip functions with empty docstrings
+        if not docstring.strip():
+            return {}
+
+        # Extract parameters (excluding 'self')
+        params = []
+        for param_name, param in sig.parameters.items():
+            if param_name != "self":
+                params.append(analyze_parameter(param, docstring))
+
+        # Special handling for constructor
+        display_name = name
+        if name == "__init__":
+            display_name = func.__qualname__.split(".")[0]
+
+        # Parse tags from docstring
+        tags = parse_docstring_tags(docstring)
+
+        category = tags.get("category", None)
+
+        # Extract description
+        description = extract_description_from_docstring(docstring)
+
+        # Skip if no meaningful description
+        if not description.strip():
+            return {}
+
+        # Extract details section (only if it exists)
+        details = extract_details_from_docstring(docstring)
+
+        # Get examples from docstring, do not generate fallback examples
+        examples = extract_examples_from_docstring(docstring)
+        # If no examples, do not include the examples key or set to empty list
+
+        result = {
+            "id": name,
+            "title": display_name,
+            "description": description,
+            "details": details,
+            "category": category,
+            "params": params,
+            "showDocs": DOC_DEFAULTS["showDocs"],
+            "releaseTag": DOC_DEFAULTS["releaseTag"],
+            "returnType": {
+                "id": "return_type",
+                "name": get_type_name(sig.return_annotation)
+                if sig.return_annotation != inspect.Signature.empty
+                else DOC_DEFAULTS["return_type_void"],
+            },
+        }
+        if examples:
+            result["examples"] = examples
+        return result
+    except Exception as e:
+        print(f"Error analyzing function {name}: {e}")
+        return {}
+
+
+def analyze_class(cls) -> dict:
+    """Analyze a class and return its documentation."""
+    class_doc = inspect.getdoc(cls) or f"Class: {cls.__name__}"
+
+    # Get all public methods and constructor
+    functions = []
+    for method_name in dir(cls):
+        if method_name.startswith("_") and method_name != "__init__":
+            continue
+
+        method = getattr(cls, method_name)
+        if callable(method):
+            func_info = analyze_function(method, method_name)
+            if func_info:  # Only add if not None (empty docstring check)
+                functions.append(func_info)
+
+    return {
+        "id": cls.__name__,
+        "title": cls.__name__,
+        "description": extract_description_from_docstring(class_doc),
+        "functions": functions,
+    }
+
+
+def analyze_type(cls) -> dict:
+    """Analyze a type/dataclass and return its documentation."""
+    type_info = {
+        "id": cls.__name__,
+        "name": cls.__name__,
+        "path": f"{cls.__module__}.{cls.__name__}",
+        "properties": [],
+        "example": "",
+    }
+
+    if is_dataclass(cls):
+        # Handle dataclass
+        for field in fields(cls):
+            prop = {
+                "name": field.name,
+                "type": get_type_name(field.type),
+                "description": f"Field: {field.name}",
+            }
+            type_info["properties"].append(prop)
+    elif hasattr(cls, "__annotations__"):
+        # Handle TypedDict or annotated class
+        for field_name, field_type in cls.__annotations__.items():
+            prop = {
+                "name": field_name,
+                "type": get_type_name(field_type),
+                "description": f"Field: {field_name}",
+            }
+            type_info["properties"].append(prop)
+
+    return type_info
+
+
+def generate_sdk_documentation():
+    """Generate complete SDK documentation in the requested format."""
+
+    # Import PostHog components
+    import posthog
+    from posthog.client import Client
+    import posthog.types as types_module
+    import posthog.args as args_module
+    from posthog.version import VERSION
+
+    # Main SDK info
+    sdk_info = {
+        "version": VERSION,
+        "id": "posthog-python",
+        "title": "PostHog Python SDK",
+        "description": "Integrate PostHog into any python application.",
+        "slugPrefix": DOCUMENTATION_METADATA["slugPrefix"],
+        "specUrl": DOCUMENTATION_METADATA["specUrl"],
+    }
+
+    # Collect types
+    types_list = []
+
+    # Types from posthog.types
+    for name in dir(types_module):
+        obj = getattr(types_module, name)
+        if inspect.isclass(obj) and not name.startswith("_"):
+            try:
+                type_info = analyze_type(obj)
+                types_list.append(type_info)
+            except Exception as e:
+                print(f"Error analyzing type {name}: {e}")
+
+    # Types from posthog.args
+    for name in dir(args_module):
+        obj = getattr(args_module, name)
+        if inspect.isclass(obj) and not name.startswith("_"):
+            try:
+                type_info = analyze_type(obj)
+                types_list.append(type_info)
+            except Exception as e:
+                print(f"Error analyzing type {name}: {e}")
+
+    # Collect classes
+    classes_list = []
+
+    # Main PostHog class (renamed from Client)
+    client_class = analyze_class(Client)
+    client_class["id"] = "PostHog"
+    client_class["title"] = "PostHog"
+    classes_list.append(client_class)
+
+    # Global module functions (functions callable as posthog.function_name)
+    global_functions = []
+    for func_name in dir(posthog):
+        # Skip private functions and non-callables
+        if func_name.startswith("_") or not callable(getattr(posthog, func_name)):
+            continue
+
+        func = getattr(posthog, func_name)
+        # Only include functions actually defined in the posthog module (not imported)
+        # and exclude class references
+        if (
+            func_name not in ["Client", "Posthog"]
+            and hasattr(func, "__module__")
+            and func.__module__ == "posthog"
+        ):
+            try:
+                func_info = analyze_function(func, func_name)
+                if func_info:  # Only add if not None (has proper docstring)
+                    global_functions.append(func_info)
+            except Exception:
+                continue
+
+    # Add global functions as a "class"
+    if global_functions:
+        classes_list.append(
+            {
+                "id": "PostHogModule",
+                "title": "PostHog Module Functions",
+                "description": "Global functions available in the PostHog module",
+                "functions": global_functions,
+            }
+        )
+
+    # Create the final structure
+    result = {
+        "id": "posthog-python",
+        "hogRef": DOCUMENTATION_METADATA["hogRef"],
+        "info": sdk_info,
+        "noDocsTypes": NO_DOCS_TYPES,
+        "types": types_list,
+        "classes": classes_list,
+    }
+
+    return result
+
+
+if __name__ == "__main__":
+    print("Generating PostHog Python SDK documentation...")
+
+    try:
+        documentation = generate_sdk_documentation()
+
+        # Write to file
+        output_file = os.path.join(
+            str(OUTPUT_CONFIG["output_dir"]), str(OUTPUT_CONFIG["filename"])
+        )
+        with open(output_file, "w") as f:
+            json.dump(documentation, f, indent=int(OUTPUT_CONFIG["indent"]))
+
+        print(f"✓ Generated {output_file}")
+
+        # Print summary
+        types_count = len(documentation["types"])
+        classes_count = len(documentation["classes"])
+
+        total_functions = sum(len(cls["functions"]) for cls in documentation["classes"])
+
+        print("📊 Documentation Summary:")
+        print(f"   • {types_count} types documented")
+        print(f"   • {classes_count} classes documented")
+        print(f"   • {total_functions} functions documented")
+
+        no_docs = documentation["noDocsTypes"]
+        if no_docs:
+            print(
+                f"   • {len(no_docs)} types without documentation: {', '.join(no_docs[:5])}{'...' if len(no_docs) > 5 else ''}"
+            )
+
+    except Exception as e:
+        print(f"❌ Error generating documentation: {e}")
+        import traceback
+
+        traceback.print_exc()

bin/fmt

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#/ Usage: bin/fmt
+#/ Description: Formats and lints the code
+source bin/helpers/_utils.sh
+set_source_and_root_dir
+ensure_virtual_env
+
+if [[ "$1" == "--check" ]]; then
+  black --check .
+  isort --check-only .
+else
+  black .
+  isort .
+fi

bin/helpers/_utils.sh

@@ -0,0 +1,26 @@
+error() {
+    echo "$@" >&2
+}
+
+fatal() {
+    error "$@"
+    exit 1
+}
+
+set_source_and_root_dir() {
+    { set +x; } 2>/dev/null
+    source_dir="$( cd -P "$( dirname "$0" )" >/dev/null 2>&1 && pwd )"
+    root_dir=$(cd "$source_dir" && cd ../ && pwd)
+    cd "$root_dir"
+}
+
+ensure_virtual_env() {
+    if [ -z "$VIRTUAL_ENV" ]; then
+        echo "Virtual environment not activated. Activating now..."
+        if [ ! -f env/bin/activate ]; then
+            echo "Virtual environment not found. Please run 'python -m venv env' first."
+            exit 1
+        fi
+        source env/bin/activate
+    fi
+}

bin/setup

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+#/ Usage: bin/setup
+#/ Description: Sets up the dependencies needed to develop this project
+source bin/helpers/_utils.sh
+set_source_and_root_dir
+
+if [ ! -d "env" ]; then
+  python3 -m venv env
+fi
+
+source env/bin/activate
+pip install -e ".[dev,test]"

bin/test

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+#/ Usage: bin/test
+#/ Description: Runs all the unit tests for this project
+source bin/helpers/_utils.sh
+set_source_and_root_dir
+
+ensure_virtual_env
+
+# Pass through all arguments to pytest
+pytest "$@"

example.py

@@ -6,7 +6,9 @@ import posthog
 # Add argument parsing
 parser = argparse.ArgumentParser(description="PostHog Python library example")
 parser.add_argument(
-    "--flag", default="person-on-events-enabled", help="Feature flag key to check (default: person-on-events-enabled)"
+    "--flag",
+    default="person-on-events-enabled",
+    help="Feature flag key to check (default: person-on-events-enabled)",
 )
 args = parser.parse_args()
 
@@ -38,10 +40,19 @@ print(
 
 
 # Capture an event
-posthog.capture("distinct_id", "event", {"property1": "value", "property2": "value"}, send_feature_flags=True)
+posthog.capture(
+    "event",
+    distinct_id="distinct_id",
+    properties={"property1": "value", "property2": "value"},
+    send_feature_flags=True,
+)
 
 print(posthog.feature_enabled("beta-feature", "distinct_id"))
-print(posthog.feature_enabled("beta-feature-groups", "distinct_id", groups={"company": "id:5"}))
+print(
+    posthog.feature_enabled(
+        "beta-feature-groups", "distinct_id", groups={"company": "id:5"}
+    )
+)
 
 print(posthog.feature_enabled("beta-feature", "distinct_id"))
 
@@ -53,27 +64,36 @@ exit()
 
 posthog.alias("distinct_id", "new_distinct_id")
 
-posthog.capture("new_distinct_id", "event2", {"property1": "value", "property2": "value"})
 posthog.capture(
-    "new_distinct_id", "event-with-groups", {"property1": "value", "property2": "value"}, groups={"company": "id:5"}
+    "event2",
+    distinct_id="new_distinct_id",
+    properties={"property1": "value", "property2": "value"},
+)
+posthog.capture(
+    "event-with-groups",
+    distinct_id="new_distinct_id",
+    properties={"property1": "value", "property2": "value"},
+    groups={"company": "id:5"},
 )
 
 # # Add properties to the person
-posthog.identify("new_distinct_id", {"email": "something@something.com"})
+posthog.set(
+    distinct_id="new_distinct_id", properties={"email": "something@something.com"}
+)
 
 # Add properties to a group
 posthog.group_identify("company", "id:5", {"employees": 11})
 
 # properties set only once to the person
-posthog.set_once("new_distinct_id", {"self_serve_signup": True})
+posthog.set_once(distinct_id="new_distinct_id", properties={"self_serve_signup": True})
 
 
 posthog.set_once(
-    "new_distinct_id", {"self_serve_signup": False}
+    distinct_id="new_distinct_id", properties={"self_serve_signup": False}
 )  # this will not change the property (because it was already set)
 
-posthog.set("new_distinct_id", {"current_browser": "Chrome"})
-posthog.set("new_distinct_id", {"current_browser": "Firefox"})
+posthog.set(distinct_id="new_distinct_id", properties={"current_browser": "Chrome"})
+posthog.set(distinct_id="new_distinct_id", properties={"current_browser": "Firefox"})
 
 
 # #############################################################################
@@ -82,7 +102,13 @@ posthog.set("new_distinct_id", {"current_browser": "Firefox"})
 # Local Evaluation
 
 # If flag has City=Sydney, this call doesn't go to `/decide`
-print(posthog.feature_enabled("test-flag", "distinct_id_random_22", person_properties={"$geoip_city_name": "Sydney"}))
+print(
+    posthog.feature_enabled(
+        "test-flag",
+        "distinct_id_random_22",
+        person_properties={"$geoip_city_name": "Sydney"},
+    )
+)
 
 print(
     posthog.feature_enabled(
@@ -98,10 +124,52 @@ print(posthog.get_all_flags("distinct_id_random_22"))
 print(posthog.get_all_flags("distinct_id_random_22", only_evaluate_locally=True))
 print(
     posthog.get_all_flags(
-        "distinct_id_random_22", person_properties={"$geoip_city_name": "Sydney"}, only_evaluate_locally=True
+        "distinct_id_random_22",
+        person_properties={"$geoip_city_name": "Sydney"},
+        only_evaluate_locally=True,
     )
 )
 print(posthog.get_remote_config_payload("encrypted_payload_flag_key"))
 
 
+# You can add tags to a context, and these are automatically added to any events (including exceptions) captured
+# within that context.
+
+# You can enter a new context using a with statement. Any exceptions thrown in the context will be captured,
+# and tagged with the context tags. Other events captured will also be tagged with the context tags. By default,
+# the new context inherits tags from the parent context.
+with posthog.new_context():
+    posthog.tag("transaction_id", "abc123")
+    posthog.tag("some_arbitrary_value", {"tags": "can be dicts"})
+
+    # This event will be captured with the tags set above
+    posthog.capture("order_processed")
+    # This exception will be captured with the tags set above
+    raise Exception("Order processing failed")
+
+
+# Use fresh=True to start with a clean context (no inherited tags)
+with posthog.new_context(fresh=True):
+    posthog.tag("session_id", "xyz789")
+    # Only session_id tag will be present, no inherited tags
+    raise Exception("Session handling failed")
+
+
+# You can also use the `@posthog.scoped()` decorator to enter a new context.
+# By default, it inherits tags from the parent context
+@posthog.scoped()
+def process_order(order_id):
+    posthog.tag("order_id", order_id)
+    # Exception will be captured and tagged automatically
+    raise Exception("Order processing failed")
+
+
+# Use fresh=True to start with a clean context (no inherited tags)
+@posthog.scoped(fresh=True)
+def process_payment(payment_id):
+    posthog.tag("payment_id", payment_id)
+    # Only payment_id tag will be present, no inherited tags
+    raise Exception("Payment processing failed")
+
+
 posthog.shutdown()

llm_observability_examples.py

@@ -1,220 +0,0 @@
-import os
-import uuid
-
-from pydantic import BaseModel
-
-import posthog
-from posthog.ai.openai import AsyncOpenAI, OpenAI
-
-# Example credentials - replace these with your own or use environment variables
-posthog.project_api_key = os.getenv("POSTHOG_PROJECT_API_KEY", "your-project-api-key")
-posthog.host = os.getenv("POSTHOG_HOST", "http://localhost:8000")  # Or https://app.posthog.com
-posthog.debug = True
-# change this to False to see usage events
-# posthog.privacy_mode = True
-
-openai_client = OpenAI(
-    api_key=os.getenv("OPENAI_API_KEY", "your-openai-api-key"),
-    posthog_client=posthog,
-)
-
-async_openai_client = AsyncOpenAI(
-    api_key=os.getenv("OPENAI_API_KEY", "your-openai-api-key"),
-    posthog_client=posthog,
-)
-
-
-def main_sync():
-    trace_id = str(uuid.uuid4())
-    print("Trace ID:", trace_id)
-    distinct_id = "test2_distinct_id"
-    properties = {"test_property": "test_value"}
-    groups = {"company": "test_company"}
-
-    try:
-        # basic_openai_call(distinct_id, trace_id, properties, groups)
-        # streaming_openai_call(distinct_id, trace_id, properties, groups)
-        # embedding_openai_call(distinct_id, trace_id, properties, groups)
-        # image_openai_call()
-        beta_openai_call(distinct_id, trace_id, properties, groups)
-    except Exception as e:
-        print("Error during OpenAI call:", str(e))
-
-
-async def main_async():
-    trace_id = str(uuid.uuid4())
-    print("Trace ID:", trace_id)
-    distinct_id = "test_distinct_id"
-    properties = {"test_property": "test_value"}
-    groups = {"company": "test_company"}
-
-    try:
-        await basic_async_openai_call(distinct_id, trace_id, properties, groups)
-        await streaming_async_openai_call(distinct_id, trace_id, properties, groups)
-        await embedding_async_openai_call(distinct_id, trace_id, properties, groups)
-        await image_async_openai_call()
-    except Exception as e:
-        print("Error during OpenAI call:", str(e))
-
-
-def basic_openai_call(distinct_id, trace_id, properties, groups):
-    response = openai_client.chat.completions.create(
-        model="gpt-4o-mini",
-        messages=[
-            {"role": "system", "content": "You are a complex problem solver."},
-            {"role": "user", "content": "Explain quantum computing in simple terms."},
-        ],
-        max_tokens=100,
-        temperature=0.7,
-        posthog_distinct_id=distinct_id,
-        posthog_trace_id=trace_id,
-        posthog_properties=properties,
-        posthog_groups=groups,
-    )
-    print(response)
-    if response and response.choices:
-        print("OpenAI response:", response.choices[0].message.content)
-    else:
-        print("No response or unexpected format returned.")
-    return response
-
-
-async def basic_async_openai_call(distinct_id, trace_id, properties, groups):
-    response = await async_openai_client.chat.completions.create(
-        model="gpt-4o-mini",
-        messages=[
-            {"role": "system", "content": "You are a complex problem solver."},
-            {"role": "user", "content": "Explain quantum computing in simple terms."},
-        ],
-        max_tokens=100,
-        temperature=0.7,
-        posthog_distinct_id=distinct_id,
-        posthog_trace_id=trace_id,
-        posthog_properties=properties,
-        posthog_groups=groups,
-    )
-    if response and hasattr(response, "choices"):
-        print("OpenAI response:", response.choices[0].message.content)
-    else:
-        print("No response or unexpected format returned.")
-    return response
-
-
-def streaming_openai_call(distinct_id, trace_id, properties, groups):
-
-    response = openai_client.chat.completions.create(
-        model="gpt-4o-mini",
-        messages=[
-            {"role": "system", "content": "You are a complex problem solver."},
-            {"role": "user", "content": "Explain quantum computing in simple terms."},
-        ],
-        max_tokens=100,
-        temperature=0.7,
-        stream=True,
-        posthog_distinct_id=distinct_id,
-        posthog_trace_id=trace_id,
-        posthog_properties=properties,
-        posthog_groups=groups,
-    )
-
-    for chunk in response:
-        if hasattr(chunk, "choices") and chunk.choices and len(chunk.choices) > 0:
-            print(chunk.choices[0].delta.content or "", end="")
-
-    return response
-
-
-async def streaming_async_openai_call(distinct_id, trace_id, properties, groups):
-    response = await async_openai_client.chat.completions.create(
-        model="gpt-4o-mini",
-        messages=[
-            {"role": "system", "content": "You are a complex problem solver."},
-            {"role": "user", "content": "Explain quantum computing in simple terms."},
-        ],
-        max_tokens=100,
-        temperature=0.7,
-        stream=True,
-        posthog_distinct_id=distinct_id,
-        posthog_trace_id=trace_id,
-        posthog_properties=properties,
-        posthog_groups=groups,
-    )
-
-    async for chunk in response:
-        if hasattr(chunk, "choices") and chunk.choices and len(chunk.choices) > 0:
-            print(chunk.choices[0].delta.content or "", end="")
-
-    return response
-
-
-# none instrumented
-def image_openai_call():
-    response = openai_client.images.generate(model="dall-e-3", prompt="A cute baby hedgehog", n=1, size="1024x1024")
-    print(response)
-    return response
-
-
-# none instrumented
-async def image_async_openai_call():
-    response = await async_openai_client.images.generate(
-        model="dall-e-3", prompt="A cute baby hedgehog", n=1, size="1024x1024"
-    )
-    print(response)
-    return response
-
-
-def embedding_openai_call(posthog_distinct_id, posthog_trace_id, posthog_properties, posthog_groups):
-    response = openai_client.embeddings.create(
-        input="The hedgehog is cute",
-        model="text-embedding-3-small",
-        posthog_distinct_id=posthog_distinct_id,
-        posthog_trace_id=posthog_trace_id,
-        posthog_properties=posthog_properties,
-        posthog_groups=posthog_groups,
-    )
-    print(response)
-    return response
-
-
-async def embedding_async_openai_call(posthog_distinct_id, posthog_trace_id, posthog_properties, posthog_groups):
-    response = await async_openai_client.embeddings.create(
-        input="The hedgehog is cute",
-        model="text-embedding-3-small",
-        posthog_distinct_id=posthog_distinct_id,
-        posthog_trace_id=posthog_trace_id,
-        posthog_properties=posthog_properties,
-        posthog_groups=posthog_groups,
-    )
-    print(response)
-    return response
-
-
-class CalendarEvent(BaseModel):
-    name: str
-    date: str
-    participants: list[str]
-
-
-def beta_openai_call(distinct_id, trace_id, properties, groups):
-    response = openai_client.beta.chat.completions.parse(
-        model="gpt-4o-mini",
-        messages=[
-            {"role": "system", "content": "Extract the event information."},
-            {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
-        ],
-        response_format=CalendarEvent,
-        posthog_distinct_id=distinct_id,
-        posthog_trace_id=trace_id,
-        posthog_properties=properties,
-        posthog_groups=groups,
-    )
-    print(response)
-    return response
-
-
-# HOW TO RUN:
-# comment out one of these to run the other
-
-if __name__ == "__main__":
-    main_sync()
-# asyncio.run(main_async())

mypy-baseline.txt

@@ -1,7 +1,6 @@
 posthog/utils.py:0: error: Library stubs not installed for "six"  [import-untyped]
 posthog/utils.py:0: error: Library stubs not installed for "dateutil.tz"  [import-untyped]
 posthog/utils.py:0: error: Statement is unreachable  [unreachable]
-posthog/utils.py:0: error: Argument 1 to "join" of "str" has incompatible type "AttributeError"; expected "Iterable[str]"  [arg-type]
 posthog/request.py:0: error: Library stubs not installed for "requests"  [import-untyped]
 posthog/request.py:0: note: Hint: "python3 -m pip install types-requests"
 posthog/request.py:0: error: Library stubs not installed for "dateutil.tz"  [import-untyped]
@@ -23,39 +22,25 @@ posthog/client.py:0: error: Library stubs not installed for "six"  [import-untyp
 posthog/client.py:0: note: Hint: "python3 -m pip install types-six"
 posthog/client.py:0: error: Name "queue" already defined (by an import)  [no-redef]
 posthog/client.py:0: error: Need type annotation for "queue"  [var-annotated]
-posthog/client.py:0: error: Item "None" of "Any | None" has no attribute "get"  [union-attr]
-simulator.py:0: error: Unexpected keyword argument "anonymous_id" for "capture"  [call-arg]
-posthog/__init__.py:0: note: "capture" defined here
-simulator.py:0: error: Unexpected keyword argument "anonymous_id" for "identify"  [call-arg]
-posthog/__init__.py:0: note: "identify" defined here
-simulator.py:0: error: Unexpected keyword argument "traits" for "identify"  [call-arg]
-posthog/__init__.py:0: note: "identify" defined here
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "Any | list[Any]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "dict[Any, Any]", variable has type "None")  [assignment]
+posthog/client.py:0: error: "None" has no attribute "__iter__" (not iterable)  [attr-defined]
+posthog/client.py:0: error: Statement is unreachable  [unreachable]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "Any | dict[Any, Any]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "Any | dict[Any, Any]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "dict[Never, Never]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "dict[Never, Never]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Right operand of "and" is never evaluated  [unreachable]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "Poller", variable has type "None")  [assignment]
+posthog/client.py:0: error: "None" has no attribute "start"  [attr-defined]
+posthog/client.py:0: error: "None" has no attribute "get"  [attr-defined]
+posthog/client.py:0: error: Statement is unreachable  [unreachable]
+posthog/client.py:0: error: Statement is unreachable  [unreachable]
 example.py:0: error: Statement is unreachable  [unreachable]
-posthog/sentry/posthog_integration.py:0: error: Statement is unreachable  [unreachable]
 posthog/ai/utils.py:0: error: Need type annotation for "output" (hint: "output: list[<type>] = ...")  [var-annotated]
 posthog/ai/utils.py:0: error: Function "builtins.any" is not valid as a type  [valid-type]
 posthog/ai/utils.py:0: note: Perhaps you meant "typing.Any" instead of "any"?
-posthog/ai/utils.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
 posthog/ai/utils.py:0: error: Function "builtins.any" is not valid as a type  [valid-type]
 posthog/ai/utils.py:0: note: Perhaps you meant "typing.Any" instead of "any"?
-posthog/ai/utils.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-sentry_django_example/sentry_django_example/settings.py:0: error: Need type annotation for "ALLOWED_HOSTS" (hint: "ALLOWED_HOSTS: list[<type>] = ...")  [var-annotated]
-sentry_django_example/sentry_django_example/settings.py:0: error: Incompatible types in assignment (expression has type "str", variable has type "None")  [assignment]
-posthog/ai/openai/openai_async.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/openai/openai_async.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/openai/openai_async.py:0: error: Unpacked dict entry 11 has incompatible type "dict[str, Any] | None"; expected "SupportsKeysAndGetItem[str, Any]"  [dict-item]
-posthog/ai/openai/openai_async.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/openai/openai_async.py:0: error: Unpacked dict entry 8 has incompatible type "dict[str, Any] | None"; expected "SupportsKeysAndGetItem[str, Any]"  [dict-item]
-posthog/ai/openai/openai.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/openai/openai.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/openai/openai.py:0: error: Unpacked dict entry 11 has incompatible type "dict[str, Any] | None"; expected "SupportsKeysAndGetItem[str, Any]"  [dict-item]
-posthog/ai/openai/openai.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/openai/openai.py:0: error: Unpacked dict entry 8 has incompatible type "dict[str, Any] | None"; expected "SupportsKeysAndGetItem[str, Any]"  [dict-item]
-posthog/ai/anthropic/anthropic_async.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/anthropic/anthropic_async.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/anthropic/anthropic_async.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/anthropic/anthropic.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/anthropic/anthropic.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-posthog/ai/anthropic/anthropic.py:0: error: Incompatible types in assignment (expression has type "UUID", variable has type "str | None")  [assignment]
-llm_observability_examples.py:0: error: Argument "posthog_client" to "OpenAI" has incompatible type Module; expected "Client"  [arg-type]
-llm_observability_examples.py:0: error: Argument "posthog_client" to "AsyncOpenAI" has incompatible type Module; expected "Client"  [arg-type]
+posthog/client.py:0: error: Name "urlparse" already defined (possibly by an import)  [no-redef]
+posthog/client.py:0: error: Name "parse_qs" already defined (possibly by an import)  [no-redef]

mypy.ini

@@ -9,6 +9,7 @@ check_untyped_defs = True
 warn_unreachable = True
 strict_equality = True
 ignore_missing_imports = True
+exclude = env/.*|venv/.*|build/.*
 
 [mypy-django.*]
 ignore_missing_imports = True

posthog/__init__.py

@@ -1,13 +1,127 @@
 import datetime  # noqa: F401
-import warnings
-from typing import Callable, Dict, List, Optional, Tuple  # noqa: F401
+from typing import Callable, Dict, Optional, Any  # noqa: F401
+from typing_extensions import Unpack
 
+from posthog.args import OptionalCaptureArgs, OptionalSetArgs, ExceptionArg
 from posthog.client import Client
-from posthog.exception_capture import Integrations  # noqa: F401
+from posthog.contexts import (
+    new_context as inner_new_context,
+    scoped as inner_scoped,
+    tag as inner_tag,
+    set_context_session as inner_set_context_session,
+    identify_context as inner_identify_context,
+)
+from posthog.types import FeatureFlag, FlagsAndPayloads
 from posthog.version import VERSION
 
 __version__ = VERSION
 
+"""Context management."""
+
+
+def new_context(fresh=False, capture_exceptions=True):
+    """
+    Create a new context scope that will be active for the duration of the with block.
+
+    Args:
+        fresh: Whether to start with a fresh context (default: False)
+        capture_exceptions: Whether to capture exceptions raised within the context (default: True)
+
+    Examples:
+        ```python
+        from posthog import new_context, tag, capture
+        with new_context():
+            tag("request_id", "123")
+            capture("event_name", properties={"property": "value"})
+        ```
+
+    Category:
+        Contexts
+    """
+    return inner_new_context(fresh=fresh, capture_exceptions=capture_exceptions)
+
+
+def scoped(fresh=False, capture_exceptions=True):
+    """
+    Decorator that creates a new context for the function.
+
+    Args:
+        fresh: Whether to start with a fresh context (default: False)
+        capture_exceptions: Whether to capture and track exceptions with posthog error tracking (default: True)
+
+    Examples:
+        ```python
+        from posthog import scoped, tag, capture
+        @scoped()
+        def process_payment(payment_id):
+            tag("payment_id", payment_id)
+            capture("payment_started")
+        ```
+
+    Category:
+        Contexts
+    """
+    return inner_scoped(fresh=fresh, capture_exceptions=capture_exceptions)
+
+
+def set_context_session(session_id: str):
+    """
+    Set the session ID for the current context.
+
+    Args:
+        session_id: The session ID to associate with the current context and its children
+
+    Examples:
+        ```python
+        from posthog import set_context_session
+        set_context_session("session_123")
+        ```
+
+    Category:
+        Contexts
+    """
+    return inner_set_context_session(session_id)
+
+
+def identify_context(distinct_id: str):
+    """
+    Identify the current context with a distinct ID.
+
+    Args:
+        distinct_id: The distinct ID to associate with the current context and its children
+
+    Examples:
+        ```python
+        from posthog import identify_context
+        identify_context("user_123")
+        ```
+
+    Category:
+        Identification
+    """
+    return inner_identify_context(distinct_id)
+
+
+def tag(name: str, value: Any):
+    """
+    Add a tag to the current context.
+
+    Args:
+        name: The tag key
+        value: The tag value
+
+    Examples:
+        ```python
+        from posthog import tag
+        tag("user_id", "123")
+        ```
+
+    Category:
+        Contexts
+    """
+    return inner_tag(name, value)
+
+
 """Settings."""
 api_key = None  # type: Optional[str]
 host = None  # type: Optional[str]
@@ -24,237 +138,177 @@ feature_flags_request_timeout_seconds = 3  # type: int
 super_properties = None  # type: Optional[Dict]
 # Currently alpha, use at your own risk
 enable_exception_autocapture = False  # type: bool
-exception_autocapture_integrations = []  # type: List[Integrations]
+log_captured_exceptions = False  # type: bool
 # Used to determine in app paths for exception autocapture. Defaults to the current working directory
 project_root = None  # type: Optional[str]
 # Used for our AI observability feature to not capture any prompt or output just usage + metadata
 privacy_mode = False  # type: bool
+# Whether to enable feature flag polling for local evaluation by default. Defaults to True.
+# We recommend setting this to False if you are only using the personalApiKey for evaluating remote config payloads via `get_remote_config_payload` and not using local evaluation.
+enable_local_evaluation = True  # type: bool
 
 default_client = None  # type: Optional[Client]
 
 
-def capture(
-    distinct_id,  # type: str
-    event,  # type: str
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    groups=None,  # type: Optional[Dict]
-    send_feature_flags=False,
-    disable_geoip=None,  # type: Optional[bool]
-):
-    # type: (...) -> Tuple[bool, dict]
+# NOTE - this and following functions take unpacked kwargs because we needed to make
+# it impossible to write `posthog.capture(distinct-id, event-name)` - basically, to enforce
+# the breaking change made between 5.3.0 and 6.0.0. This decision can be unrolled in later
+# versions, without a breaking change, to get back the type information in function signatures
+def capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str]:
     """
-    Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up.
+    Capture anything a user does within your system.
 
-    A `capture` call requires
-    - `distinct id` which uniquely identifies your user
-    - `event name` to specify the event
-    - We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on.
+    Args:
+        event: The event name to specify the event
+        **kwargs: Optional arguments including:
+            distinct_id: Unique identifier for the user
+            properties: Dict of event properties
+            timestamp: When the event occurred
+            groups: Dict of group types and IDs
+            disable_geoip: Whether to disable GeoIP lookup
 
-    Optionally you can submit
-    - `properties`, which can be a dict with any information you'd like to add
-    - `groups`, which is a dict of group type -> group key mappings
+    Details:
+        Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.
 
-    For example:
-    ```python
-    posthog.capture('distinct id', 'opened app')
-    posthog.capture('distinct id', 'movie played', {'movie_id': '123', 'category': 'romcom'})
+    Examples:
+        ```python
+        # Context and capture usage
+        from posthog import new_context, identify_context, tag_context, capture
+        # Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)
+        with new_context():
+            # Associate this context with some user, by distinct_id
+            identify_context('some user')
 
-    posthog.capture('distinct id', 'purchase', groups={'company': 'id:5'})
-    ```
-    """
+            # Capture an event, associated with the context-level distinct ID ('some user')
+            capture('movie started')
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
+            # Capture an event associated with some other user (overriding the context-level distinct ID)
+            capture('movie joined', distinct_id='some-other-user')
+
+            # Capture an event with some properties
+            capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})
+
+            # Capture an event with some properties
+            capture('purchase', properties={'product_id': '123', 'category': 'romcom'})
+            # Capture an event with some associated group
+            capture('purchase', groups={'company': 'id:5'})
+
+            # Adding a tag to the current context will cause it to appear on all subsequent events
+            tag_context('some-tag', 'some-value')
+
+            capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict
+        ```
+        ```python
+        # Set event properties
+        from posthog import capture
+        capture(
+            "user_signed_up",
+            distinct_id="distinct_id_of_the_user",
+            properties={
+                "login_type": "email",
+                "is_free_trial": "true"
+            }
         )
-
-    return _proxy(
-        "capture",
-        distinct_id=distinct_id,
-        event=event,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        groups=groups,
-        send_feature_flags=send_feature_flags,
-        disable_geoip=disable_geoip,
-    )
-
-
-def identify(
-    distinct_id,  # type: str
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    disable_geoip=None,  # type: Optional[bool]
-):
-    # type: (...) -> Tuple[bool, dict]
-    """
-    Identify lets you add metadata on your users so you can more easily identify who they are in PostHog, and even do things like segment users by these properties.
-
-    An `identify` call requires
-    - `distinct id` which uniquely identifies your user
-    - `properties` with a dict with any key: value pairs
-
-    For example:
-    ```python
-    posthog.identify('distinct id', {
-        'email': 'dwayne@gmail.com',
-        'name': 'Dwayne Johnson'
-    })
-    ```
+        ```
+    Category:
+        Events
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-    return _proxy(
-        "identify",
-        distinct_id=distinct_id,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        disable_geoip=disable_geoip,
-    )
+    return _proxy("capture", event, **kwargs)
 
 
-def set(
-    distinct_id,  # type: str
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    disable_geoip=None,  # type: Optional[bool]
-):
-    # type: (...) -> Tuple[bool, dict]
+def set(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
     """
     Set properties on a user record.
-    This will overwrite previous people property values, just like `identify`.
 
-     A `set` call requires
-     - `distinct id` which uniquely identifies your user
-     - `properties` with a dict with any key: value pairs
+    Details:
+        This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).
 
-     For example:
-     ```python
-     posthog.set('distinct id', {
-         'current_browser': 'Chrome',
-     })
-     ```
+    Examples:
+        ```python
+        # Set person properties
+        from posthog import capture
+        capture(
+            'distinct_id',
+            event='event_name',
+            properties={
+                '$set': {'name': 'Max Hedgehog'},
+                '$set_once': {'initial_url': '/blog'}
+            }
+        )
+        ```
+    Category:
+        Identification
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-    return _proxy(
-        "set",
-        distinct_id=distinct_id,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        disable_geoip=disable_geoip,
-    )
+    return _proxy("set", **kwargs)
 
 
-def set_once(
-    distinct_id,  # type: str
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    disable_geoip=None,  # type: Optional[bool]
-):
-    # type: (...) -> Tuple[bool, dict]
+def set_once(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
     """
     Set properties on a user record, only if they do not yet exist.
-    This will not overwrite previous people property values, unlike `identify`.
 
-     A `set_once` call requires
-     - `distinct id` which uniquely identifies your user
-     - `properties` with a dict with any key: value pairs
+    Details:
+        This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.
 
-     For example:
-     ```python
-     posthog.set_once('distinct id', {
-         'referred_by': 'friend',
-     })
-     ```
-    """
-
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
+    Examples:
+        ```python
+        # Set property once
+        from posthog import capture
+        capture(
+            'distinct_id',
+            event='event_name',
+            properties={
+                '$set': {'name': 'Max Hedgehog'},
+                '$set_once': {'initial_url': '/blog'}
+            }
         )
 
-    return _proxy(
-        "set_once",
-        distinct_id=distinct_id,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        disable_geoip=disable_geoip,
-    )
+        ```
+    Category:
+        Identification
+    """
+    return _proxy("set_once", **kwargs)
 
 
 def group_identify(
     group_type,  # type: str
     group_key,  # type: str
     properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
     timestamp=None,  # type: Optional[datetime.datetime]
     uuid=None,  # type: Optional[str]
     disable_geoip=None,  # type: Optional[bool]
 ):
-    # type: (...) -> Tuple[bool, dict]
+    # type: (...) -> Optional[str]
     """
-    Set properties on a group
+    Set properties on a group.
 
-     A `group_identify` call requires
-     - `group_type` type of your group
-     - `group_key` unique identifier of the group
-     - `properties` with a dict with any key: value pairs
+    Args:
+        group_type: Type of your group
+        group_key: Unique identifier of the group
+        properties: Properties to set on the group
+        timestamp: Optional timestamp for the event
+        uuid: Optional UUID for the event
+        disable_geoip: Whether to disable GeoIP lookup
 
-     For example:
-     ```python
-     posthog.group_identify('company', 5, {
-         'employees': 11,
-     })
-     ```
+    Examples:
+        ```python
+        # Group identify
+        from posthog import group_identify
+        group_identify('company', 'company_id_in_your_db', {
+            'name': 'Awesome Inc.',
+            'employees': 11
+        })
+        ```
+    Category:
+        Identification
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
     return _proxy(
         "group_identify",
         group_type=group_type,
         group_key=group_key,
         properties=properties,
-        context=context,
         timestamp=timestamp,
         uuid=uuid,
         disable_geoip=disable_geoip,
@@ -264,41 +318,38 @@ def group_identify(
 def alias(
     previous_id,  # type: str
     distinct_id,  # type: str
-    context=None,  # type: Optional[Dict]
     timestamp=None,  # type: Optional[datetime.datetime]
     uuid=None,  # type: Optional[str]
     disable_geoip=None,  # type: Optional[bool]
 ):
-    # type: (...) -> Tuple[bool, dict]
+    # type: (...) -> Optional[str]
     """
-    To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like "Which marketing channels leads to users churning after a month?" or "What do users do on our website before signing up?"
+    Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.
 
-    In a purely back-end implementation, this means whenever an anonymous user does something, you'll want to send a session ID ([Django](https://stackoverflow.com/questions/526179/in-django-how-can-i-find-out-the-request-session-sessionid-and-use-it-as-a-vari), [Flask](https://stackoverflow.com/questions/15156132/flask-login-how-to-get-session-id)) with the capture call. Then, when that users signs up, you want to do an alias call with the session ID and the newly created user ID.
+    Args:
+        previous_id: The unique ID of the user before
+        distinct_id: The current unique id
+        timestamp: Optional timestamp for the event
+        uuid: Optional UUID for the event
+        disable_geoip: Whether to disable GeoIP lookup
 
-    The same concept applies for when a user logs in.
+    Details:
+        To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like "Which marketing channels leads to users churning after a month?" or "What do users do on our website before signing up?". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.
 
-    An `alias` call requires
-    - `previous distinct id` the unique ID of the user before
-    - `distinct id` the current unique id
-
-    For example:
-    ```python
-    posthog.alias('anonymous session id', 'distinct id')
-    ```
+    Examples:
+        ```python
+        # Alias user
+        from posthog import alias
+        alias(previous_id='distinct_id', distinct_id='alias_id')
+        ```
+    Category:
+        Identification
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
     return _proxy(
         "alias",
         previous_id=previous_id,
         distinct_id=distinct_id,
-        context=context,
         timestamp=timestamp,
         uuid=uuid,
         disable_geoip=disable_geoip,
@@ -306,55 +357,32 @@ def alias(
 
 
 def capture_exception(
-    exception=None,  # type: Optional[BaseException]
-    distinct_id=None,  # type: Optional[str]
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    groups=None,  # type: Optional[Dict]
+    exception: Optional[ExceptionArg] = None,
+    **kwargs: Unpack[OptionalCaptureArgs],
 ):
-    # type: (...) -> Tuple[bool, dict]
     """
-    capture_exception allows you to capture exceptions that happen in your code. This is useful for debugging and understanding what errors your users are encountering.
-    This function never raises an exception, even if it fails to send the event.
+    Capture exceptions that happen in your code.
 
-    A `capture_exception` call does not require any fields, but we recommend sending:
-    - `distinct id` which uniquely identifies your user for which this exception happens
-    - `exception` to specify the exception to capture. If not provided, the current exception is captured via `sys.exc_info()`
+    Args:
+        exception: The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`
 
-    Optionally you can submit
-    - `properties`, which can be a dict with any information you'd like to add
-    - `groups`, which is a dict of group type -> group key mappings
+    Details:
+        Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the "traceback"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError("Some Error"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.
 
-    For example:
-    ```python
-    try:
-        1 / 0
-    except Exception as e:
-        posthog.capture_exception(e, 'my specific distinct id')
-        posthog.capture_exception(distinct_id='my specific distinct id')
-
-    ```
+    Examples:
+        ```python
+        # Capture exception
+        from posthog import capture_exception
+        try:
+            risky_operation()
+        except Exception as e:
+            capture_exception(e)
+        ```
+    Category:
+        Events
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-    return _proxy(
-        "capture_exception",
-        exception=exception,
-        distinct_id=distinct_id,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        groups=groups,
-    )
+    return _proxy("capture_exception", exception=exception, **kwargs)
 
 
 def feature_enabled(
@@ -371,15 +399,29 @@ def feature_enabled(
     """
     Use feature flags to enable or disable features for users.
 
-    For example:
-    ```python
-    if posthog.feature_enabled('beta feature', 'distinct id'):
-        # do something
-    if posthog.feature_enabled('groups feature', 'distinct id', groups={"organization": "5"}):
-        # do something
-    ```
+    Args:
+        key: The feature flag key
+        distinct_id: The user's distinct ID
+        groups: Groups mapping
+        person_properties: Person properties
+        group_properties: Group properties
+        only_evaluate_locally: Whether to evaluate only locally
+        send_feature_flag_events: Whether to send feature flag events
+        disable_geoip: Whether to disable GeoIP lookup
 
-    You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.
+    Details:
+        You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.
+
+    Examples:
+        ```python
+        # Boolean feature flag
+        from posthog import feature_enabled, get_feature_flag_payload
+        is_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')
+        if is_my_flag_enabled:
+            matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')
+        ```
+    Category:
+        Feature flags
     """
     return _proxy(
         "feature_enabled",
@@ -403,28 +445,33 @@ def get_feature_flag(
     only_evaluate_locally=False,  # type: bool
     send_feature_flag_events=True,  # type: bool
     disable_geoip=None,  # type: Optional[bool]
-):
+) -> Optional[FeatureFlag]:
     """
     Get feature flag variant for users. Used with experiments.
-    Example:
-    ```python
-    if posthog.get_feature_flag('beta-feature', 'distinct_id') == 'test-variant':
-        # do test variant code
-    if posthog.get_feature_flag('beta-feature', 'distinct_id') == 'control':
-        # do control code
-    ```
 
-    `groups` are a mapping from group type to group key. So, if you have a group type of "organization" and a group key of "5",
-    you would pass groups={"organization": "5"}.
+    Args:
+        key: The feature flag key
+        distinct_id: The user's distinct ID
+        groups: Groups mapping from group type to group key
+        person_properties: Person properties
+        group_properties: Group properties in format { group_type_name: { group_properties } }
+        only_evaluate_locally: Whether to evaluate only locally
+        send_feature_flag_events: Whether to send feature flag events
+        disable_geoip: Whether to disable GeoIP lookup
 
-    `group_properties` take the format: { group_type_name: { group_properties } }
+    Details:
+        `groups` are a mapping from group type to group key. So, if you have a group type of "organization" and a group key of "5", you would pass groups={"organization": "5"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type "organization" and the group key "5", with the properties name, and employee count, you'll send these as: group_properties={"organization": {"name": "PostHog", "employees": 11}}.
 
-    So, for example, if you have the group type "organization" and the group key "5", with the properties name, and employee count,
-    you'll send these as:
-
-    ```python
-        group_properties={"organization": {"name": "PostHog", "employees": 11}}
-    ```
+    Examples:
+        ```python
+        # Multivariate feature flag
+        from posthog import get_feature_flag, get_feature_flag_payload
+        enabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')
+        if enabled_variant == 'variant-key':
+            matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')
+        ```
+    Category:
+        Feature flags
     """
     return _proxy(
         "get_feature_flag",
@@ -446,15 +493,29 @@ def get_all_flags(
     group_properties={},  # type: dict
     only_evaluate_locally=False,  # type: bool
     disable_geoip=None,  # type: Optional[bool]
-):
+) -> Optional[dict[str, FeatureFlag]]:
     """
     Get all flags for a given user.
-    Example:
-    ```python
-    flags = posthog.get_all_flags('distinct_id')
-    ```
 
-    flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.
+    Args:
+        distinct_id: The user's distinct ID
+        groups: Groups mapping
+        person_properties: Person properties
+        group_properties: Group properties
+        only_evaluate_locally: Whether to evaluate only locally
+        disable_geoip: Whether to disable GeoIP lookup
+
+    Details:
+        Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.
+
+    Examples:
+        ```python
+        # All flags for user
+        from posthog import get_all_flags
+        get_all_flags('distinct_id_of_your_user')
+        ```
+    Category:
+        Feature flags
     """
     return _proxy(
         "get_all_flags",
@@ -477,7 +538,7 @@ def get_feature_flag_payload(
     only_evaluate_locally=False,
     send_feature_flag_events=True,
     disable_geoip=None,  # type: Optional[bool]
-):
+) -> Optional[str]:
     return _proxy(
         "get_feature_flag_payload",
         key=key,
@@ -519,7 +580,7 @@ def get_all_flags_and_payloads(
     group_properties={},
     only_evaluate_locally=False,
     disable_geoip=None,  # type: Optional[bool]
-):
+) -> FlagsAndPayloads:
     return _proxy(
         "get_all_flags_and_payloads",
         distinct_id=distinct_id,
@@ -532,45 +593,94 @@ def get_all_flags_and_payloads(
 
 
 def feature_flag_definitions():
-    """Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded."""
+    """
+    Returns loaded feature flags.
+
+    Details:
+        Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.
+
+    Examples:
+        ```python
+        from posthog import feature_flag_definitions
+        definitions = feature_flag_definitions()
+        ```
+
+    Category:
+        Feature flags
+    """
     return _proxy("feature_flag_definitions")
 
 
 def load_feature_flags():
-    """Load feature flag definitions from PostHog."""
+    """
+    Load feature flag definitions from PostHog.
+
+    Examples:
+        ```python
+        from posthog import load_feature_flags
+        load_feature_flags()
+        ```
+
+    Category:
+        Feature flags
+    """
     return _proxy("load_feature_flags")
 
 
-def page(*args, **kwargs):
-    """Send a page call."""
-    _proxy("page", *args, **kwargs)
-
-
-def screen(*args, **kwargs):
-    """Send a screen call."""
-    _proxy("screen", *args, **kwargs)
-
-
 def flush():
-    """Tell the client to flush."""
+    """
+    Tell the client to flush all queued events.
+
+    Examples:
+        ```python
+        from posthog import flush
+        flush()
+        ```
+
+    Category:
+        Client management
+    """
     _proxy("flush")
 
 
 def join():
-    """Block program until the client clears the queue"""
+    """
+    Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.
+
+    Examples:
+        ```python
+        from posthog import join
+        join()
+        ```
+
+    Category:
+        Client management
+    """
     _proxy("join")
 
 
 def shutdown():
-    """Flush all messages and cleanly shutdown the client"""
+    """
+    Flush all messages and cleanly shutdown the client.
+
+    Examples:
+        ```python
+        from posthog import shutdown
+        shutdown()
+        ```
+
+    Category:
+        Client management
+    """
     _proxy("flush")
     _proxy("join")
 
 
-def _proxy(method, *args, **kwargs):
-    """Create an analytics client if one doesn't exist and send to it."""
+def setup() -> Client:
     global default_client
     if not default_client:
+        if not api_key:
+            raise ValueError("API key is required")
         default_client = Client(
             api_key,
             host=host,
@@ -579,7 +689,6 @@ def _proxy(method, *args, **kwargs):
             send=send,
             sync_mode=sync_mode,
             personal_api_key=personal_api_key,
-            project_api_key=project_api_key,
             poll_interval=poll_interval,
             disabled=disabled,
             disable_geoip=disable_geoip,
@@ -589,13 +698,21 @@ def _proxy(method, *args, **kwargs):
             # This kind of initialisation is very annoying for exception capture. We need to figure out a way around this,
             # or deprecate this proxy option fully (it's already in the process of deprecation, no new clients should be using this method since like 5-6 months)
             enable_exception_autocapture=enable_exception_autocapture,
-            exception_autocapture_integrations=exception_autocapture_integrations,
+            log_captured_exceptions=log_captured_exceptions,
+            enable_local_evaluation=enable_local_evaluation,
         )
 
     # always set incase user changes it
     default_client.disabled = disabled
     default_client.debug = debug
 
+    return default_client
+
+
+def _proxy(method, *args, **kwargs):
+    """Create an analytics client if one doesn't exist and send to it."""
+    setup()
+
     fn = getattr(default_client, method)
     return fn(*args, **kwargs)
 

posthog/ai/anthropic/__init__.py

@@ -1,6 +1,11 @@
 from .anthropic import Anthropic
 from .anthropic_async import AsyncAnthropic
-from .anthropic_providers import AnthropicBedrock, AnthropicVertex, AsyncAnthropicBedrock, AsyncAnthropicVertex
+from .anthropic_providers import (
+    AnthropicBedrock,
+    AnthropicVertex,
+    AsyncAnthropicBedrock,
+    AsyncAnthropicVertex,
+)
 
 __all__ = [
     "Anthropic",

posthog/ai/anthropic/anthropic.py

@@ -2,14 +2,22 @@ try:
     import anthropic
     from anthropic.resources import Messages
 except ImportError:
-    raise ModuleNotFoundError("Please install the Anthropic SDK to use this feature: 'pip install anthropic'")
+    raise ModuleNotFoundError(
+        "Please install the Anthropic SDK to use this feature: 'pip install anthropic'"
+    )
 
 import time
 import uuid
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, cast
 
-from posthog.ai.utils import call_llm_and_track_usage, get_model_params, merge_system_prompt, with_privacy_mode
+from posthog.ai.utils import (
+    call_llm_and_track_usage,
+    get_model_params,
+    merge_system_prompt,
+    with_privacy_mode,
+)
 from posthog.client import Client as PostHogClient
+from posthog import setup
 
 
 class Anthropic(anthropic.Anthropic):
@@ -19,14 +27,14 @@ class Anthropic(anthropic.Anthropic):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             posthog_client: PostHog client for tracking usage
             **kwargs: Additional arguments passed to the Anthropic client
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = WrappedMessages(self)
 
 
@@ -54,7 +62,7 @@ class WrappedMessages(Messages):
             **kwargs: Arguments passed to Anthropic's messages.create
         """
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         if kwargs.get("stream", False):
             return self._create_streaming(
@@ -89,7 +97,7 @@ class WrappedMessages(Messages):
         **kwargs: Any,
     ):
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         return self._create_streaming(
             posthog_distinct_id,
@@ -116,7 +124,7 @@ class WrappedMessages(Messages):
 
         def generator():
             nonlocal usage_stats
-            nonlocal accumulated_content
+            nonlocal accumulated_content  # noqa: F824
             try:
                 for event in response:
                     if hasattr(event, "usage") and event.usage:
@@ -125,6 +133,8 @@ class WrappedMessages(Messages):
                             for k in [
                                 "input_tokens",
                                 "output_tokens",
+                                "cache_read_input_tokens",
+                                "cache_creation_input_tokens",
                             ]
                         }
 
@@ -165,7 +175,7 @@ class WrappedMessages(Messages):
         output: str,
     ):
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         event_properties = {
             "$ai_provider": "anthropic",
@@ -184,6 +194,12 @@ class WrappedMessages(Messages):
             "$ai_http_status": 200,
             "$ai_input_tokens": usage_stats.get("input_tokens", 0),
             "$ai_output_tokens": usage_stats.get("output_tokens", 0),
+            "$ai_cache_read_input_tokens": usage_stats.get(
+                "cache_read_input_tokens", 0
+            ),
+            "$ai_cache_creation_input_tokens": usage_stats.get(
+                "cache_creation_input_tokens", 0
+            ),
             "$ai_latency": latency,
             "$ai_trace_id": posthog_trace_id,
             "$ai_base_url": str(self._client.base_url),

posthog/ai/anthropic/anthropic_async.py

@@ -2,13 +2,21 @@ try:
     import anthropic
     from anthropic.resources import AsyncMessages
 except ImportError:
-    raise ModuleNotFoundError("Please install the Anthropic SDK to use this feature: 'pip install anthropic'")
+    raise ModuleNotFoundError(
+        "Please install the Anthropic SDK to use this feature: 'pip install anthropic'"
+    )
 
 import time
 import uuid
 from typing import Any, Dict, Optional
 
-from posthog.ai.utils import call_llm_and_track_usage_async, get_model_params, merge_system_prompt, with_privacy_mode
+from posthog import setup
+from posthog.ai.utils import (
+    call_llm_and_track_usage_async,
+    get_model_params,
+    merge_system_prompt,
+    with_privacy_mode,
+)
 from posthog.client import Client as PostHogClient
 
 
@@ -19,14 +27,14 @@ class AsyncAnthropic(anthropic.AsyncAnthropic):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             posthog_client: PostHog client for tracking usage
             **kwargs: Additional arguments passed to the Anthropic client
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = AsyncWrappedMessages(self)
 
 
@@ -54,7 +62,7 @@ class AsyncWrappedMessages(AsyncMessages):
             **kwargs: Arguments passed to Anthropic's messages.create
         """
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         if kwargs.get("stream", False):
             return await self._create_streaming(
@@ -89,7 +97,7 @@ class AsyncWrappedMessages(AsyncMessages):
         **kwargs: Any,
     ):
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         return await self._create_streaming(
             posthog_distinct_id,
@@ -116,7 +124,7 @@ class AsyncWrappedMessages(AsyncMessages):
 
         async def generator():
             nonlocal usage_stats
-            nonlocal accumulated_content
+            nonlocal accumulated_content  # noqa: F824
             try:
                 async for event in response:
                     if hasattr(event, "usage") and event.usage:
@@ -125,6 +133,8 @@ class AsyncWrappedMessages(AsyncMessages):
                             for k in [
                                 "input_tokens",
                                 "output_tokens",
+                                "cache_read_input_tokens",
+                                "cache_creation_input_tokens",
                             ]
                         }
 
@@ -165,7 +175,7 @@ class AsyncWrappedMessages(AsyncMessages):
         output: str,
     ):
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         event_properties = {
             "$ai_provider": "anthropic",
@@ -184,6 +194,12 @@ class AsyncWrappedMessages(AsyncMessages):
             "$ai_http_status": 200,
             "$ai_input_tokens": usage_stats.get("input_tokens", 0),
             "$ai_output_tokens": usage_stats.get("output_tokens", 0),
+            "$ai_cache_read_input_tokens": usage_stats.get(
+                "cache_read_input_tokens", 0
+            ),
+            "$ai_cache_creation_input_tokens": usage_stats.get(
+                "cache_creation_input_tokens", 0
+            ),
             "$ai_latency": latency,
             "$ai_trace_id": posthog_trace_id,
             "$ai_base_url": str(self._client.base_url),

posthog/ai/anthropic/anthropic_providers.py

@@ -1,11 +1,16 @@
 try:
     import anthropic
 except ImportError:
-    raise ModuleNotFoundError("Please install the Anthropic SDK to use this feature: 'pip install anthropic'")
+    raise ModuleNotFoundError(
+        "Please install the Anthropic SDK to use this feature: 'pip install anthropic'"
+    )
+
+from typing import Optional
 
 from posthog.ai.anthropic.anthropic import WrappedMessages
 from posthog.ai.anthropic.anthropic_async import AsyncWrappedMessages
 from posthog.client import Client as PostHogClient
+from posthog import setup
 
 
 class AnthropicBedrock(anthropic.AnthropicBedrock):
@@ -15,9 +20,9 @@ class AnthropicBedrock(anthropic.AnthropicBedrock):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = WrappedMessages(self)
 
 
@@ -28,9 +33,9 @@ class AsyncAnthropicBedrock(anthropic.AsyncAnthropicBedrock):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = AsyncWrappedMessages(self)
 
 
@@ -41,9 +46,9 @@ class AnthropicVertex(anthropic.AnthropicVertex):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = WrappedMessages(self)
 
 
@@ -54,7 +59,7 @@ class AsyncAnthropicVertex(anthropic.AsyncAnthropicVertex):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = AsyncWrappedMessages(self)

posthog/ai/gemini/__init__.py

@@ -0,0 +1,11 @@
+from .gemini import Client
+
+
+# Create a genai-like module for perfect drop-in replacement
+class _GenAI:
+    Client = Client
+
+
+genai = _GenAI()
+
+__all__ = ["Client", "genai"]

posthog/ai/gemini/gemini.py

@@ -0,0 +1,371 @@
+import os
+import time
+import uuid
+from typing import Any, Dict, Optional
+
+try:
+    from google import genai
+except ImportError:
+    raise ModuleNotFoundError(
+        "Please install the Google Gemini SDK to use this feature: 'pip install google-genai'"
+    )
+
+from posthog import setup
+from posthog.ai.utils import (
+    call_llm_and_track_usage,
+    get_model_params,
+    with_privacy_mode,
+)
+from posthog.client import Client as PostHogClient
+
+
+class Client:
+    """
+    A drop-in replacement for genai.Client that automatically sends LLM usage events to PostHog.
+
+    Usage:
+        client = Client(
+            api_key="your_api_key",
+            posthog_client=posthog_client,
+            posthog_distinct_id="default_user",  # Optional defaults
+            posthog_properties={"team": "ai"}    # Optional defaults
+        )
+        response = client.models.generate_content(
+            model="gemini-2.0-flash",
+            contents=["Hello world"],
+            posthog_distinct_id="specific_user"  # Override default
+        )
+    """
+
+    _ph_client: PostHogClient
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        posthog_client: Optional[PostHogClient] = None,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: bool = False,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+        """
+        Args:
+            api_key: Google AI API key. If not provided, will use GOOGLE_API_KEY or API_KEY environment variable
+            posthog_client: PostHog client for tracking usage
+            posthog_distinct_id: Default distinct ID for all calls (can be overridden per call)
+            posthog_properties: Default properties for all calls (can be overridden per call)
+            posthog_privacy_mode: Default privacy mode for all calls (can be overridden per call)
+            posthog_groups: Default groups for all calls (can be overridden per call)
+            **kwargs: Additional arguments (for future compatibility)
+        """
+        self._ph_client = posthog_client or setup()
+
+        if self._ph_client is None:
+            raise ValueError("posthog_client is required for PostHog tracking")
+
+        self.models = Models(
+            api_key=api_key,
+            posthog_client=self._ph_client,
+            posthog_distinct_id=posthog_distinct_id,
+            posthog_properties=posthog_properties,
+            posthog_privacy_mode=posthog_privacy_mode,
+            posthog_groups=posthog_groups,
+            **kwargs,
+        )
+
+
+class Models:
+    """
+    Models interface that mimics genai.Client().models with PostHog tracking.
+    """
+
+    _ph_client: PostHogClient  # Not None after __init__ validation
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        posthog_client: Optional[PostHogClient] = None,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: bool = False,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+        """
+        Args:
+            api_key: Google AI API key. If not provided, will use GOOGLE_API_KEY or API_KEY environment variable
+            posthog_client: PostHog client for tracking usage
+            posthog_distinct_id: Default distinct ID for all calls
+            posthog_properties: Default properties for all calls
+            posthog_privacy_mode: Default privacy mode for all calls
+            posthog_groups: Default groups for all calls
+            **kwargs: Additional arguments (for future compatibility)
+        """
+        self._ph_client = posthog_client or setup()
+
+        if self._ph_client is None:
+            raise ValueError("posthog_client is required for PostHog tracking")
+
+        # Store default PostHog settings
+        self._default_distinct_id = posthog_distinct_id
+        self._default_properties = posthog_properties or {}
+        self._default_privacy_mode = posthog_privacy_mode
+        self._default_groups = posthog_groups
+
+        # Handle API key - try parameter first, then environment variables
+        if api_key is None:
+            api_key = os.environ.get("GOOGLE_API_KEY") or os.environ.get("API_KEY")
+
+        if api_key is None:
+            raise ValueError(
+                "API key must be provided either as parameter or via GOOGLE_API_KEY/API_KEY environment variable"
+            )
+
+        self._client = genai.Client(api_key=api_key)
+        self._base_url = "https://generativelanguage.googleapis.com"
+
+    def _merge_posthog_params(
+        self,
+        call_distinct_id: Optional[str],
+        call_trace_id: Optional[str],
+        call_properties: Optional[Dict[str, Any]],
+        call_privacy_mode: Optional[bool],
+        call_groups: Optional[Dict[str, Any]],
+    ):
+        """Merge call-level PostHog parameters with client defaults."""
+        # Use call-level values if provided, otherwise fall back to defaults
+        distinct_id = (
+            call_distinct_id
+            if call_distinct_id is not None
+            else self._default_distinct_id
+        )
+        privacy_mode = (
+            call_privacy_mode
+            if call_privacy_mode is not None
+            else self._default_privacy_mode
+        )
+        groups = call_groups if call_groups is not None else self._default_groups
+
+        # Merge properties: default properties + call properties (call properties override)
+        properties = dict(self._default_properties)
+        if call_properties:
+            properties.update(call_properties)
+
+        if call_trace_id is None:
+            call_trace_id = str(uuid.uuid4())
+
+        return distinct_id, call_trace_id, properties, privacy_mode, groups
+
+    def generate_content(
+        self,
+        model: str,
+        contents,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_trace_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: Optional[bool] = None,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ):
+        """
+        Generate content using Gemini's API while tracking usage in PostHog.
+
+        This method signature exactly matches genai.Client().models.generate_content()
+        with additional PostHog tracking parameters.
+
+        Args:
+            model: The model to use (e.g., 'gemini-2.0-flash')
+            contents: The input content for generation
+            posthog_distinct_id: ID to associate with the usage event (overrides client default)
+            posthog_trace_id: Trace UUID for linking events (auto-generated if not provided)
+            posthog_properties: Extra properties to include in the event (merged with client defaults)
+            posthog_privacy_mode: Whether to redact sensitive information (overrides client default)
+            posthog_groups: Group analytics properties (overrides client default)
+            **kwargs: Arguments passed to Gemini's generate_content
+        """
+        # Merge PostHog parameters
+        distinct_id, trace_id, properties, privacy_mode, groups = (
+            self._merge_posthog_params(
+                posthog_distinct_id,
+                posthog_trace_id,
+                posthog_properties,
+                posthog_privacy_mode,
+                posthog_groups,
+            )
+        )
+
+        kwargs_with_contents = {"model": model, "contents": contents, **kwargs}
+
+        return call_llm_and_track_usage(
+            distinct_id,
+            self._ph_client,
+            "gemini",
+            trace_id,
+            properties,
+            privacy_mode,
+            groups,
+            self._base_url,
+            self._client.models.generate_content,
+            **kwargs_with_contents,
+        )
+
+    def _generate_content_streaming(
+        self,
+        model: str,
+        contents,
+        distinct_id: Optional[str],
+        trace_id: Optional[str],
+        properties: Optional[Dict[str, Any]],
+        privacy_mode: bool,
+        groups: Optional[Dict[str, Any]],
+        **kwargs: Any,
+    ):
+        start_time = time.time()
+        usage_stats: Dict[str, int] = {"input_tokens": 0, "output_tokens": 0}
+        accumulated_content = []
+
+        kwargs_without_stream = {"model": model, "contents": contents, **kwargs}
+        response = self._client.models.generate_content_stream(**kwargs_without_stream)
+
+        def generator():
+            nonlocal usage_stats
+            nonlocal accumulated_content  # noqa: F824
+            try:
+                for chunk in response:
+                    if hasattr(chunk, "usage_metadata") and chunk.usage_metadata:
+                        usage_stats = {
+                            "input_tokens": getattr(
+                                chunk.usage_metadata, "prompt_token_count", 0
+                            ),
+                            "output_tokens": getattr(
+                                chunk.usage_metadata, "candidates_token_count", 0
+                            ),
+                        }
+
+                    if hasattr(chunk, "text") and chunk.text:
+                        accumulated_content.append(chunk.text)
+
+                    yield chunk
+
+            finally:
+                end_time = time.time()
+                latency = end_time - start_time
+                output = "".join(accumulated_content)
+
+                self._capture_streaming_event(
+                    model,
+                    contents,
+                    distinct_id,
+                    trace_id,
+                    properties,
+                    privacy_mode,
+                    groups,
+                    kwargs,
+                    usage_stats,
+                    latency,
+                    output,
+                )
+
+        return generator()
+
+    def _capture_streaming_event(
+        self,
+        model: str,
+        contents,
+        distinct_id: Optional[str],
+        trace_id: Optional[str],
+        properties: Optional[Dict[str, Any]],
+        privacy_mode: bool,
+        groups: Optional[Dict[str, Any]],
+        kwargs: Dict[str, Any],
+        usage_stats: Dict[str, int],
+        latency: float,
+        output: str,
+    ):
+        if trace_id is None:
+            trace_id = str(uuid.uuid4())
+
+        event_properties = {
+            "$ai_provider": "gemini",
+            "$ai_model": model,
+            "$ai_model_parameters": get_model_params(kwargs),
+            "$ai_input": with_privacy_mode(
+                self._ph_client,
+                privacy_mode,
+                self._format_input(contents),
+            ),
+            "$ai_output_choices": with_privacy_mode(
+                self._ph_client,
+                privacy_mode,
+                [{"content": output, "role": "assistant"}],
+            ),
+            "$ai_http_status": 200,
+            "$ai_input_tokens": usage_stats.get("input_tokens", 0),
+            "$ai_output_tokens": usage_stats.get("output_tokens", 0),
+            "$ai_latency": latency,
+            "$ai_trace_id": trace_id,
+            "$ai_base_url": self._base_url,
+            **(properties or {}),
+        }
+
+        if distinct_id is None:
+            event_properties["$process_person_profile"] = False
+
+        if hasattr(self._ph_client, "capture"):
+            self._ph_client.capture(
+                distinct_id=distinct_id,
+                event="$ai_generation",
+                properties=event_properties,
+                groups=groups,
+            )
+
+    def _format_input(self, contents):
+        """Format input contents for PostHog tracking"""
+        if isinstance(contents, str):
+            return [{"role": "user", "content": contents}]
+        elif isinstance(contents, list):
+            formatted = []
+            for item in contents:
+                if isinstance(item, str):
+                    formatted.append({"role": "user", "content": item})
+                elif hasattr(item, "text"):
+                    formatted.append({"role": "user", "content": item.text})
+                else:
+                    formatted.append({"role": "user", "content": str(item)})
+            return formatted
+        else:
+            return [{"role": "user", "content": str(contents)}]
+
+    def generate_content_stream(
+        self,
+        model: str,
+        contents,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_trace_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: Optional[bool] = None,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ):
+        # Merge PostHog parameters
+        distinct_id, trace_id, properties, privacy_mode, groups = (
+            self._merge_posthog_params(
+                posthog_distinct_id,
+                posthog_trace_id,
+                posthog_properties,
+                posthog_privacy_mode,
+                posthog_groups,
+            )
+        )
+
+        return self._generate_content_streaming(
+            model,
+            contents,
+            distinct_id,
+            trace_id,
+            properties,
+            privacy_mode,
+            groups,
+            **kwargs,
+        )

posthog/ai/langchain/callbacks.py

@@ -1,7 +1,9 @@
 try:
     import langchain  # noqa: F401
 except ImportError:
-    raise ModuleNotFoundError("Please install LangChain to use this feature: 'pip install langchain'")
+    raise ModuleNotFoundError(
+        "Please install LangChain to use this feature: 'pip install langchain'"
+    )
 
 import logging
 import time
@@ -12,7 +14,6 @@ from typing import (
     List,
     Optional,
     Sequence,
-    Tuple,
     Union,
     cast,
 )
@@ -21,11 +22,18 @@ from uuid import UUID
 from langchain.callbacks.base import BaseCallbackHandler
 from langchain.schema.agent import AgentAction, AgentFinish
 from langchain_core.documents import Document
-from langchain_core.messages import AIMessage, BaseMessage, FunctionMessage, HumanMessage, SystemMessage, ToolMessage
+from langchain_core.messages import (
+    AIMessage,
+    BaseMessage,
+    FunctionMessage,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+)
 from langchain_core.outputs import ChatGeneration, LLMResult
 from pydantic import BaseModel
 
-from posthog import default_client
+from posthog import setup
 from posthog.ai.utils import get_model_params, with_privacy_mode
 from posthog.client import Client
 
@@ -60,6 +68,8 @@ class GenerationMetadata(SpanMetadata):
     """Model parameters of the run: temperature, max_tokens, etc."""
     base_url: Optional[str] = None
     """Base URL of the provider's API used in the run."""
+    tools: Optional[List[Dict[str, Any]]] = None
+    """Tools provided to the model."""
 
 
 RunMetadata = Union[SpanMetadata, GenerationMetadata]
@@ -71,10 +81,10 @@ class CallbackHandler(BaseCallbackHandler):
     The PostHog LLM observability callback handler for LangChain.
     """
 
-    _client: Client
+    _ph_client: Client
     """PostHog client instance."""
 
-    _distinct_id: Optional[Union[str, int, float, UUID]]
+    _distinct_id: Optional[Union[str, int, UUID]]
     """Distinct ID of the user to associate the trace with."""
 
     _trace_id: Optional[Union[str, int, float, UUID]]
@@ -102,7 +112,7 @@ class CallbackHandler(BaseCallbackHandler):
         self,
         client: Optional[Client] = None,
         *,
-        distinct_id: Optional[Union[str, int, float, UUID]] = None,
+        distinct_id: Optional[Union[str, int, UUID]] = None,
         trace_id: Optional[Union[str, int, float, UUID]] = None,
         properties: Optional[Dict[str, Any]] = None,
         privacy_mode: bool = False,
@@ -117,10 +127,7 @@ class CallbackHandler(BaseCallbackHandler):
             privacy_mode: Whether to redact the input and output of the trace.
             groups: Optional additional PostHog groups to use for the trace.
         """
-        posthog_client = client or default_client
-        if posthog_client is None:
-            raise ValueError("PostHog client is required")
-        self._client = posthog_client
+        self._ph_client = client or setup()
         self._distinct_id = distinct_id
         self._trace_id = trace_id
         self._properties = properties or {}
@@ -141,7 +148,9 @@ class CallbackHandler(BaseCallbackHandler):
     ):
         self._log_debug_event("on_chain_start", run_id, parent_run_id, inputs=inputs)
         self._set_parent_of_run(run_id, parent_run_id)
-        self._set_trace_or_span_metadata(serialized, inputs, run_id, parent_run_id, **kwargs)
+        self._set_trace_or_span_metadata(
+            serialized, inputs, run_id, parent_run_id, **kwargs
+        )
 
     def on_chain_end(
         self,
@@ -174,9 +183,13 @@ class CallbackHandler(BaseCallbackHandler):
         parent_run_id: Optional[UUID] = None,
         **kwargs,
     ):
-        self._log_debug_event("on_chat_model_start", run_id, parent_run_id, messages=messages)
+        self._log_debug_event(
+            "on_chat_model_start", run_id, parent_run_id, messages=messages
+        )
         self._set_parent_of_run(run_id, parent_run_id)
-        input = [_convert_message_to_dict(message) for row in messages for message in row]
+        input = [
+            _convert_message_to_dict(message) for row in messages for message in row
+        ]
         self._set_llm_metadata(serialized, run_id, input, **kwargs)
 
     def on_llm_start(
@@ -214,7 +227,9 @@ class CallbackHandler(BaseCallbackHandler):
         """
         The callback works for both streaming and non-streaming runs. For streaming runs, the chain must set `stream_usage=True` in the LLM.
         """
-        self._log_debug_event("on_llm_end", run_id, parent_run_id, response=response, kwargs=kwargs)
+        self._log_debug_event(
+            "on_llm_end", run_id, parent_run_id, response=response, kwargs=kwargs
+        )
         self._pop_run_and_capture_generation(run_id, parent_run_id, response)
 
     def on_llm_error(
@@ -238,9 +253,13 @@ class CallbackHandler(BaseCallbackHandler):
         metadata: Optional[Dict[str, Any]] = None,
         **kwargs: Any,
     ) -> Any:
-        self._log_debug_event("on_tool_start", run_id, parent_run_id, input_str=input_str)
+        self._log_debug_event(
+            "on_tool_start", run_id, parent_run_id, input_str=input_str
+        )
         self._set_parent_of_run(run_id, parent_run_id)
-        self._set_trace_or_span_metadata(serialized, input_str, run_id, parent_run_id, **kwargs)
+        self._set_trace_or_span_metadata(
+            serialized, input_str, run_id, parent_run_id, **kwargs
+        )
 
     def on_tool_end(
         self,
@@ -277,7 +296,9 @@ class CallbackHandler(BaseCallbackHandler):
     ) -> Any:
         self._log_debug_event("on_retriever_start", run_id, parent_run_id, query=query)
         self._set_parent_of_run(run_id, parent_run_id)
-        self._set_trace_or_span_metadata(serialized, query, run_id, parent_run_id, **kwargs)
+        self._set_trace_or_span_metadata(
+            serialized, query, run_id, parent_run_id, **kwargs
+        )
 
     def on_retriever_end(
         self,
@@ -287,7 +308,9 @@ class CallbackHandler(BaseCallbackHandler):
         parent_run_id: Optional[UUID] = None,
         **kwargs: Any,
     ):
-        self._log_debug_event("on_retriever_end", run_id, parent_run_id, documents=documents)
+        self._log_debug_event(
+            "on_retriever_end", run_id, parent_run_id, documents=documents
+        )
         self._pop_run_and_capture_trace_or_span(run_id, parent_run_id, documents)
 
     def on_retriever_error(
@@ -362,7 +385,9 @@ class CallbackHandler(BaseCallbackHandler):
     ):
         default_name = "trace" if parent_run_id is None else "span"
         run_name = _get_langchain_run_name(serialized, **kwargs) or default_name
-        self._runs[run_id] = SpanMetadata(name=run_name, input=input, start_time=time.time(), end_time=None)
+        self._runs[run_id] = SpanMetadata(
+            name=run_name, input=input, start_time=time.time(), end_time=None
+        )
 
     def _set_llm_metadata(
         self,
@@ -374,9 +399,13 @@ class CallbackHandler(BaseCallbackHandler):
         **kwargs,
     ):
         run_name = _get_langchain_run_name(serialized, **kwargs) or "generation"
-        generation = GenerationMetadata(name=run_name, input=messages, start_time=time.time(), end_time=None)
+        generation = GenerationMetadata(
+            name=run_name, input=messages, start_time=time.time(), end_time=None
+        )
         if isinstance(invocation_params, dict):
             generation.model_params = get_model_params(invocation_params)
+            if tools := invocation_params.get("tools"):
+                generation.tools = tools
         if isinstance(metadata, dict):
             if model := metadata.get("ls_model_name"):
                 generation.model = model
@@ -406,7 +435,9 @@ class CallbackHandler(BaseCallbackHandler):
             return run_id
         return trace_id
 
-    def _get_parent_run_id(self, trace_id: Any, run_id: UUID, parent_run_id: Optional[UUID]):
+    def _get_parent_run_id(
+        self, trace_id: Any, run_id: UUID, parent_run_id: Optional[UUID]
+    ):
         """
         Replace the parent run ID with the trace ID for second level runs when a custom trace ID is set.
         """
@@ -414,17 +445,25 @@ class CallbackHandler(BaseCallbackHandler):
             return trace_id
         return parent_run_id
 
-    def _pop_run_and_capture_trace_or_span(self, run_id: UUID, parent_run_id: Optional[UUID], outputs: Any):
+    def _pop_run_and_capture_trace_or_span(
+        self, run_id: UUID, parent_run_id: Optional[UUID], outputs: Any
+    ):
         trace_id = self._get_trace_id(run_id)
         self._pop_parent_of_run(run_id)
         run = self._pop_run_metadata(run_id)
         if not run:
             return
         if isinstance(run, GenerationMetadata):
-            log.warning(f"Run {run_id} is a generation, but attempted to be captured as a trace or span.")
+            log.warning(
+                f"Run {run_id} is a generation, but attempted to be captured as a trace or span."
+            )
             return
         self._capture_trace_or_span(
-            trace_id, run_id, run, outputs, self._get_parent_run_id(trace_id, run_id, parent_run_id)
+            trace_id,
+            run_id,
+            run,
+            outputs,
+            self._get_parent_run_id(trace_id, run_id, parent_run_id),
         )
 
     def _capture_trace_or_span(
@@ -438,7 +477,9 @@ class CallbackHandler(BaseCallbackHandler):
         event_name = "$ai_trace" if parent_run_id is None else "$ai_span"
         event_properties = {
             "$ai_trace_id": trace_id,
-            "$ai_input_state": with_privacy_mode(self._client, self._privacy_mode, run.input),
+            "$ai_input_state": with_privacy_mode(
+                self._ph_client, self._privacy_mode, run.input
+            ),
             "$ai_latency": run.latency,
             "$ai_span_name": run.name,
             "$ai_span_id": run_id,
@@ -452,12 +493,14 @@ class CallbackHandler(BaseCallbackHandler):
             event_properties["$ai_error"] = _stringify_exception(outputs)
             event_properties["$ai_is_error"] = True
         elif outputs is not None:
-            event_properties["$ai_output_state"] = with_privacy_mode(self._client, self._privacy_mode, outputs)
+            event_properties["$ai_output_state"] = with_privacy_mode(
+                self._ph_client, self._privacy_mode, outputs
+            )
 
         if self._distinct_id is None:
             event_properties["$process_person_profile"] = False
 
-        self._client.capture(
+        self._ph_client.capture(
             distinct_id=self._distinct_id or run_id,
             event=event_name,
             properties=event_properties,
@@ -465,7 +508,10 @@ class CallbackHandler(BaseCallbackHandler):
         )
 
     def _pop_run_and_capture_generation(
-        self, run_id: UUID, parent_run_id: Optional[UUID], response: Union[LLMResult, BaseException]
+        self,
+        run_id: UUID,
+        parent_run_id: Optional[UUID],
+        response: Union[LLMResult, BaseException],
     ):
         trace_id = self._get_trace_id(run_id)
         self._pop_parent_of_run(run_id)
@@ -473,10 +519,16 @@ class CallbackHandler(BaseCallbackHandler):
         if not run:
             return
         if not isinstance(run, GenerationMetadata):
-            log.warning(f"Run {run_id} is not a generation, but attempted to be captured as a generation.")
+            log.warning(
+                f"Run {run_id} is not a generation, but attempted to be captured as a generation."
+            )
             return
         self._capture_generation(
-            trace_id, run_id, run, response, self._get_parent_run_id(trace_id, run_id, parent_run_id)
+            trace_id,
+            run_id,
+            run,
+            response,
+            self._get_parent_run_id(trace_id, run_id, parent_run_id),
         )
 
     def _capture_generation(
@@ -495,11 +547,19 @@ class CallbackHandler(BaseCallbackHandler):
             "$ai_provider": run.provider,
             "$ai_model": run.model,
             "$ai_model_parameters": run.model_params,
-            "$ai_input": with_privacy_mode(self._client, self._privacy_mode, run.input),
+            "$ai_input": with_privacy_mode(
+                self._ph_client, self._privacy_mode, run.input
+            ),
             "$ai_http_status": 200,
             "$ai_latency": run.latency,
             "$ai_base_url": run.base_url,
         }
+        if run.tools:
+            event_properties["$ai_tools"] = with_privacy_mode(
+                self._ph_client,
+                self._privacy_mode,
+                run.tools,
+            )
 
         if isinstance(output, BaseException):
             event_properties["$ai_http_status"] = _get_http_status(output)
@@ -507,9 +567,14 @@ class CallbackHandler(BaseCallbackHandler):
             event_properties["$ai_is_error"] = True
         else:
             # Add usage
-            input_tokens, output_tokens = _parse_usage(output)
-            event_properties["$ai_input_tokens"] = input_tokens
-            event_properties["$ai_output_tokens"] = output_tokens
+            usage = _parse_usage(output)
+            event_properties["$ai_input_tokens"] = usage.input_tokens
+            event_properties["$ai_output_tokens"] = usage.output_tokens
+            event_properties["$ai_cache_creation_input_tokens"] = (
+                usage.cache_write_tokens
+            )
+            event_properties["$ai_cache_read_input_tokens"] = usage.cache_read_tokens
+            event_properties["$ai_reasoning_tokens"] = usage.reasoning_tokens
 
             # Generation results
             generation_result = output.generations[-1]
@@ -519,8 +584,12 @@ class CallbackHandler(BaseCallbackHandler):
                     for generation in generation_result
                 ]
             else:
-                completions = [_extract_raw_esponse(generation) for generation in generation_result]
-            event_properties["$ai_output_choices"] = with_privacy_mode(self._client, self._privacy_mode, completions)
+                completions = [
+                    _extract_raw_esponse(generation) for generation in generation_result
+                ]
+            event_properties["$ai_output_choices"] = with_privacy_mode(
+                self._ph_client, self._privacy_mode, completions
+            )
 
         if self._properties:
             event_properties.update(self._properties)
@@ -528,7 +597,7 @@ class CallbackHandler(BaseCallbackHandler):
         if self._distinct_id is None:
             event_properties["$process_person_profile"] = False
 
-        self._client.capture(
+        self._ph_client.capture(
             distinct_id=self._distinct_id or trace_id,
             event="$ai_generation",
             properties=event_properties,
@@ -581,9 +650,18 @@ def _convert_message_to_dict(message: BaseMessage) -> Dict[str, Any]:
     return message_dict
 
 
+@dataclass
+class ModelUsage:
+    input_tokens: Optional[int]
+    output_tokens: Optional[int]
+    cache_write_tokens: Optional[int]
+    cache_read_tokens: Optional[int]
+    reasoning_tokens: Optional[int]
+
+
 def _parse_usage_model(
-    usage: Union[BaseModel, Dict],
-) -> Tuple[Union[int, None], Union[int, None]]:
+    usage: Union[BaseModel, dict],
+) -> ModelUsage:
     if isinstance(usage, BaseModel):
         usage = usage.__dict__
 
@@ -591,15 +669,23 @@ def _parse_usage_model(
         # https://pypi.org/project/langchain-anthropic/ (works also for Bedrock-Anthropic)
         ("input_tokens", "input"),
         ("output_tokens", "output"),
+        ("cache_creation_input_tokens", "cache_write"),
+        ("cache_read_input_tokens", "cache_read"),
         # https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/get-token-count
         ("prompt_token_count", "input"),
         ("candidates_token_count", "output"),
+        ("cached_content_token_count", "cache_read"),
+        ("thoughts_token_count", "reasoning"),
         # Bedrock: https://docs.aws.amazon.com/bedrock/latest/userguide/monitoring-cw.html#runtime-cloudwatch-metrics
         ("inputTokenCount", "input"),
         ("outputTokenCount", "output"),
+        ("cacheCreationInputTokenCount", "cache_write"),
+        ("cacheReadInputTokenCount", "cache_read"),
         # Bedrock Anthropic
         ("prompt_tokens", "input"),
         ("completion_tokens", "output"),
+        ("cache_creation_input_tokens", "cache_write"),
+        ("cache_read_input_tokens", "cache_read"),
         # langchain-ibm https://pypi.org/project/langchain-ibm/
         ("input_token_count", "input"),
         ("generated_token_count", "output"),
@@ -610,18 +696,52 @@ def _parse_usage_model(
         if model_key in usage:
             captured_count = usage[model_key]
             final_count = (
-                sum(captured_count) if isinstance(captured_count, list) else captured_count
+                sum(captured_count)
+                if isinstance(captured_count, list)
+                else captured_count
             )  # For Bedrock, the token count is a list when streamed
 
             parsed_usage[type_key] = final_count
 
-    return parsed_usage.get("input"), parsed_usage.get("output")
+    # Caching (OpenAI & langchain 0.3.9+)
+    if "input_token_details" in usage and isinstance(
+        usage["input_token_details"], dict
+    ):
+        parsed_usage["cache_write"] = usage["input_token_details"].get("cache_creation")
+        parsed_usage["cache_read"] = usage["input_token_details"].get("cache_read")
+
+    # Reasoning (OpenAI & langchain 0.3.9+)
+    if "output_token_details" in usage and isinstance(
+        usage["output_token_details"], dict
+    ):
+        parsed_usage["reasoning"] = usage["output_token_details"].get("reasoning")
+
+    field_mapping = {
+        "input": "input_tokens",
+        "output": "output_tokens",
+        "cache_write": "cache_write_tokens",
+        "cache_read": "cache_read_tokens",
+        "reasoning": "reasoning_tokens",
+    }
+    return ModelUsage(
+        **{
+            dataclass_key: parsed_usage.get(mapped_key) or 0
+            for mapped_key, dataclass_key in field_mapping.items()
+        },
+    )
 
 
-def _parse_usage(response: LLMResult):
+def _parse_usage(response: LLMResult) -> ModelUsage:
     # langchain-anthropic uses the usage field
     llm_usage_keys = ["token_usage", "usage"]
-    llm_usage: Tuple[Union[int, None], Union[int, None]] = (None, None)
+    llm_usage: ModelUsage = ModelUsage(
+        input_tokens=None,
+        output_tokens=None,
+        cache_write_tokens=None,
+        cache_read_tokens=None,
+        reasoning_tokens=None,
+    )
+
     if response.llm_output is not None:
         for key in llm_usage_keys:
             if response.llm_output.get(key):
@@ -635,8 +755,12 @@ def _parse_usage(response: LLMResult):
                 break
 
             for generation_chunk in generation:
-                if generation_chunk.generation_info and ("usage_metadata" in generation_chunk.generation_info):
-                    llm_usage = _parse_usage_model(generation_chunk.generation_info["usage_metadata"])
+                if generation_chunk.generation_info and (
+                    "usage_metadata" in generation_chunk.generation_info
+                ):
+                    llm_usage = _parse_usage_model(
+                        generation_chunk.generation_info["usage_metadata"]
+                    )
                     break
 
                 message_chunk = getattr(generation_chunk, "message", {})
@@ -648,13 +772,19 @@ def _parse_usage(response: LLMResult):
                     else None
                 )
                 bedrock_titan_usage = (
-                    response_metadata.get("amazon-bedrock-invocationMetrics", None)  # for Bedrock-Titan
+                    response_metadata.get(
+                        "amazon-bedrock-invocationMetrics", None
+                    )  # for Bedrock-Titan
                     if isinstance(response_metadata, dict)
                     else None
                 )
-                ollama_usage = getattr(message_chunk, "usage_metadata", None)  # for Ollama
+                ollama_usage = getattr(
+                    message_chunk, "usage_metadata", None
+                )  # for Ollama
 
-                chunk_usage = bedrock_anthropic_usage or bedrock_titan_usage or ollama_usage
+                chunk_usage = (
+                    bedrock_anthropic_usage or bedrock_titan_usage or ollama_usage
+                )
                 if chunk_usage:
                     llm_usage = _parse_usage_model(chunk_usage)
                     break
@@ -670,7 +800,9 @@ def _get_http_status(error: BaseException) -> int:
     return status_code
 
 
-def _get_langchain_run_name(serialized: Optional[Dict[str, Any]], **kwargs: Any) -> Optional[str]:
+def _get_langchain_run_name(
+    serialized: Optional[Dict[str, Any]], **kwargs: Any
+) -> Optional[str]:
     """Retrieve the name of a serialized LangChain runnable.
 
     The prioritization for the determination of the run name is as follows:

posthog/ai/openai/__init__.py

@@ -1,4 +1,5 @@
 from .openai import OpenAI
 from .openai_async import AsyncOpenAI
+from .openai_providers import AsyncAzureOpenAI, AzureOpenAI
 
-__all__ = ["OpenAI", "AsyncOpenAI"]
+__all__ = ["OpenAI", "AsyncOpenAI", "AzureOpenAI", "AsyncAzureOpenAI"]

posthog/ai/openai/openai.py

@@ -1,15 +1,21 @@
 import time
 import uuid
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 try:
     import openai
-    import openai.resources
 except ImportError:
-    raise ModuleNotFoundError("Please install the OpenAI SDK to use this feature: 'pip install openai'")
+    raise ModuleNotFoundError(
+        "Please install the OpenAI SDK to use this feature: 'pip install openai'"
+    )
 
-from posthog.ai.utils import call_llm_and_track_usage, get_model_params, with_privacy_mode
+from posthog.ai.utils import (
+    call_llm_and_track_usage,
+    get_model_params,
+    with_privacy_mode,
+)
 from posthog.client import Client as PostHogClient
+from posthog import setup
 
 
 class OpenAI(openai.OpenAI):
@@ -19,31 +25,46 @@ class OpenAI(openai.OpenAI):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             api_key: OpenAI API key.
-            posthog_client: If provided, events will be captured via this client instead
-                            of the global posthog.
+            posthog_client: If provided, events will be captured via this client instead of the global `posthog`.
             **openai_config: Any additional keyword args to set on openai (e.g. organization="xxx").
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
-        self.chat = WrappedChat(self)
-        self.embeddings = WrappedEmbeddings(self)
-        self.beta = WrappedBeta(self)
+        self._ph_client = posthog_client or setup()
+
+        # Store original objects after parent initialization (only if they exist)
+        self._original_chat = getattr(self, "chat", None)
+        self._original_embeddings = getattr(self, "embeddings", None)
+        self._original_beta = getattr(self, "beta", None)
+        self._original_responses = getattr(self, "responses", None)
+
+        # Replace with wrapped versions (only if originals exist)
+        if self._original_chat is not None:
+            self.chat = WrappedChat(self, self._original_chat)
+
+        if self._original_embeddings is not None:
+            self.embeddings = WrappedEmbeddings(self, self._original_embeddings)
+
+        if self._original_beta is not None:
+            self.beta = WrappedBeta(self, self._original_beta)
+
+        if self._original_responses is not None:
+            self.responses = WrappedResponses(self, self._original_responses)
 
 
-class WrappedChat(openai.resources.chat.Chat):
-    _client: OpenAI
+class WrappedResponses:
+    """Wrapper for OpenAI responses that tracks usage in PostHog."""
 
-    @property
-    def completions(self):
-        return WrappedCompletions(self._client)
+    def __init__(self, client: OpenAI, original_responses):
+        self._client = client
+        self._original = original_responses
 
-
-class WrappedCompletions(openai.resources.chat.completions.Completions):
-    _client: OpenAI
+    def __getattr__(self, name):
+        """Fallback to original responses object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     def create(
         self,
@@ -55,7 +76,7 @@ class WrappedCompletions(openai.resources.chat.completions.Completions):
         **kwargs: Any,
     ):
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         if kwargs.get("stream", False):
             return self._create_streaming(
@@ -76,7 +97,7 @@ class WrappedCompletions(openai.resources.chat.completions.Completions):
             posthog_privacy_mode,
             posthog_groups,
             self._client.base_url,
-            super().create,
+            self._original.create,
             **kwargs,
         )
 
@@ -91,38 +112,51 @@ class WrappedCompletions(openai.resources.chat.completions.Completions):
     ):
         start_time = time.time()
         usage_stats: Dict[str, int] = {}
-        accumulated_content = []
-        if "stream_options" not in kwargs:
-            kwargs["stream_options"] = {}
-        kwargs["stream_options"]["include_usage"] = True
-        response = super().create(**kwargs)
+        final_content = []
+        response = self._original.create(**kwargs)
 
         def generator():
             nonlocal usage_stats
-            nonlocal accumulated_content
+            nonlocal final_content  # noqa: F824
+
             try:
                 for chunk in response:
+                    if hasattr(chunk, "type") and chunk.type == "response.completed":
+                        res = chunk.response
+                        if res.output and len(res.output) > 0:
+                            final_content.append(res.output[0])
+
                     if hasattr(chunk, "usage") and chunk.usage:
                         usage_stats = {
                             k: getattr(chunk.usage, k, 0)
                             for k in [
-                                "prompt_tokens",
-                                "completion_tokens",
+                                "input_tokens",
+                                "output_tokens",
                                 "total_tokens",
                             ]
                         }
 
-                    if hasattr(chunk, "choices") and chunk.choices and len(chunk.choices) > 0:
-                        content = chunk.choices[0].delta.content
-                        if content:
-                            accumulated_content.append(content)
+                        # Add support for cached tokens
+                        if hasattr(chunk.usage, "output_tokens_details") and hasattr(
+                            chunk.usage.output_tokens_details, "reasoning_tokens"
+                        ):
+                            usage_stats["reasoning_tokens"] = (
+                                chunk.usage.output_tokens_details.reasoning_tokens
+                            )
+
+                        if hasattr(chunk.usage, "input_tokens_details") and hasattr(
+                            chunk.usage.input_tokens_details, "cached_tokens"
+                        ):
+                            usage_stats["cache_read_input_tokens"] = (
+                                chunk.usage.input_tokens_details.cached_tokens
+                            )
 
                     yield chunk
 
             finally:
                 end_time = time.time()
                 latency = end_time - start_time
-                output = "".join(accumulated_content)
+                output = final_content
                 self._capture_streaming_event(
                     posthog_distinct_id,
                     posthog_trace_id,
@@ -147,16 +181,277 @@ class WrappedCompletions(openai.resources.chat.completions.Completions):
         kwargs: Dict[str, Any],
         usage_stats: Dict[str, int],
         latency: float,
-        output: str,
+        output: Any,
+        tool_calls: Optional[List[Dict[str, Any]]] = None,
     ):
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         event_properties = {
             "$ai_provider": "openai",
             "$ai_model": kwargs.get("model"),
             "$ai_model_parameters": get_model_params(kwargs),
-            "$ai_input": with_privacy_mode(self._client._ph_client, posthog_privacy_mode, kwargs.get("messages")),
+            "$ai_input": with_privacy_mode(
+                self._client._ph_client, posthog_privacy_mode, kwargs.get("input")
+            ),
+            "$ai_output_choices": with_privacy_mode(
+                self._client._ph_client,
+                posthog_privacy_mode,
+                output,
+            ),
+            "$ai_http_status": 200,
+            "$ai_input_tokens": usage_stats.get("input_tokens", 0),
+            "$ai_output_tokens": usage_stats.get("output_tokens", 0),
+            "$ai_cache_read_input_tokens": usage_stats.get(
+                "cache_read_input_tokens", 0
+            ),
+            "$ai_reasoning_tokens": usage_stats.get("reasoning_tokens", 0),
+            "$ai_latency": latency,
+            "$ai_trace_id": posthog_trace_id,
+            "$ai_base_url": str(self._client.base_url),
+            **(posthog_properties or {}),
+        }
+
+        if tool_calls:
+            event_properties["$ai_tools"] = with_privacy_mode(
+                self._client._ph_client,
+                posthog_privacy_mode,
+                tool_calls,
+            )
+
+        if posthog_distinct_id is None:
+            event_properties["$process_person_profile"] = False
+
+        if hasattr(self._client._ph_client, "capture"):
+            self._client._ph_client.capture(
+                distinct_id=posthog_distinct_id or posthog_trace_id,
+                event="$ai_generation",
+                properties=event_properties,
+                groups=posthog_groups,
+            )
+
+    def parse(
+        self,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_trace_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: bool = False,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ):
+        """
+        Parse structured output using OpenAI's 'responses.parse' method, but also track usage in PostHog.
+
+        Args:
+            posthog_distinct_id: Optional ID to associate with the usage event.
+            posthog_trace_id: Optional trace UUID for linking events.
+            posthog_properties: Optional dictionary of extra properties to include in the event.
+            posthog_privacy_mode: Whether to anonymize the input and output.
+            posthog_groups: Optional dictionary of groups to associate with the event.
+            **kwargs: Any additional parameters for the OpenAI Responses Parse API.
+
+        Returns:
+            The response from OpenAI's responses.parse call.
+        """
+        return call_llm_and_track_usage(
+            posthog_distinct_id,
+            self._client._ph_client,
+            "openai",
+            posthog_trace_id,
+            posthog_properties,
+            posthog_privacy_mode,
+            posthog_groups,
+            self._client.base_url,
+            self._original.parse,
+            **kwargs,
+        )
+
+
+class WrappedChat:
+    """Wrapper for OpenAI chat that tracks usage in PostHog."""
+
+    def __init__(self, client: OpenAI, original_chat):
+        self._client = client
+        self._original = original_chat
+
+    def __getattr__(self, name):
+        """Fallback to original chat object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
+
+    @property
+    def completions(self):
+        return WrappedCompletions(self._client, self._original.completions)
+
+
+class WrappedCompletions:
+    """Wrapper for OpenAI chat completions that tracks usage in PostHog."""
+
+    def __init__(self, client: OpenAI, original_completions):
+        self._client = client
+        self._original = original_completions
+
+    def __getattr__(self, name):
+        """Fallback to original completions object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
+
+    def create(
+        self,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_trace_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: bool = False,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ):
+        if posthog_trace_id is None:
+            posthog_trace_id = str(uuid.uuid4())
+
+        if kwargs.get("stream", False):
+            return self._create_streaming(
+                posthog_distinct_id,
+                posthog_trace_id,
+                posthog_properties,
+                posthog_privacy_mode,
+                posthog_groups,
+                **kwargs,
+            )
+
+        return call_llm_and_track_usage(
+            posthog_distinct_id,
+            self._client._ph_client,
+            "openai",
+            posthog_trace_id,
+            posthog_properties,
+            posthog_privacy_mode,
+            posthog_groups,
+            self._client.base_url,
+            self._original.create,
+            **kwargs,
+        )
+
+    def _create_streaming(
+        self,
+        posthog_distinct_id: Optional[str],
+        posthog_trace_id: Optional[str],
+        posthog_properties: Optional[Dict[str, Any]],
+        posthog_privacy_mode: bool,
+        posthog_groups: Optional[Dict[str, Any]],
+        **kwargs: Any,
+    ):
+        start_time = time.time()
+        usage_stats: Dict[str, int] = {}
+        accumulated_content = []
+        accumulated_tools = {}
+        if "stream_options" not in kwargs:
+            kwargs["stream_options"] = {}
+        kwargs["stream_options"]["include_usage"] = True
+        response = self._original.create(**kwargs)
+
+        def generator():
+            nonlocal usage_stats
+            nonlocal accumulated_content  # noqa: F824
+            nonlocal accumulated_tools  # noqa: F824
+
+            try:
+                for chunk in response:
+                    if hasattr(chunk, "usage") and chunk.usage:
+                        usage_stats = {
+                            k: getattr(chunk.usage, k, 0)
+                            for k in [
+                                "prompt_tokens",
+                                "completion_tokens",
+                                "total_tokens",
+                            ]
+                        }
+
+                        # Add support for cached tokens
+                        if hasattr(chunk.usage, "prompt_tokens_details") and hasattr(
+                            chunk.usage.prompt_tokens_details, "cached_tokens"
+                        ):
+                            usage_stats["cache_read_input_tokens"] = (
+                                chunk.usage.prompt_tokens_details.cached_tokens
+                            )
+
+                        if hasattr(chunk.usage, "output_tokens_details") and hasattr(
+                            chunk.usage.output_tokens_details, "reasoning_tokens"
+                        ):
+                            usage_stats["reasoning_tokens"] = (
+                                chunk.usage.output_tokens_details.reasoning_tokens
+                            )
+
+                    if (
+                        hasattr(chunk, "choices")
+                        and chunk.choices
+                        and len(chunk.choices) > 0
+                    ):
+                        if chunk.choices[0].delta and chunk.choices[0].delta.content:
+                            content = chunk.choices[0].delta.content
+                            if content:
+                                accumulated_content.append(content)
+
+                        # Process tool calls
+                        tool_calls = getattr(chunk.choices[0].delta, "tool_calls", None)
+                        if tool_calls:
+                            for tool_call in tool_calls:
+                                index = tool_call.index
+                                if index not in accumulated_tools:
+                                    accumulated_tools[index] = tool_call
+                                else:
+                                    # Append arguments for existing tool calls
+                                    if hasattr(tool_call, "function") and hasattr(
+                                        tool_call.function, "arguments"
+                                    ):
+                                        accumulated_tools[
+                                            index
+                                        ].function.arguments += (
+                                            tool_call.function.arguments
+                                        )
+
+                    yield chunk
+
+            finally:
+                end_time = time.time()
+                latency = end_time - start_time
+                output = "".join(accumulated_content)
+                tools = list(accumulated_tools.values()) if accumulated_tools else None
+                self._capture_streaming_event(
+                    posthog_distinct_id,
+                    posthog_trace_id,
+                    posthog_properties,
+                    posthog_privacy_mode,
+                    posthog_groups,
+                    kwargs,
+                    usage_stats,
+                    latency,
+                    output,
+                    tools,
+                )
+
+        return generator()
+
+    def _capture_streaming_event(
+        self,
+        posthog_distinct_id: Optional[str],
+        posthog_trace_id: Optional[str],
+        posthog_properties: Optional[Dict[str, Any]],
+        posthog_privacy_mode: bool,
+        posthog_groups: Optional[Dict[str, Any]],
+        kwargs: Dict[str, Any],
+        usage_stats: Dict[str, int],
+        latency: float,
+        output: Any,
+        tool_calls: Optional[List[Dict[str, Any]]] = None,
+    ):
+        if posthog_trace_id is None:
+            posthog_trace_id = str(uuid.uuid4())
+
+        event_properties = {
+            "$ai_provider": "openai",
+            "$ai_model": kwargs.get("model"),
+            "$ai_model_parameters": get_model_params(kwargs),
+            "$ai_input": with_privacy_mode(
+                self._client._ph_client, posthog_privacy_mode, kwargs.get("messages")
+            ),
             "$ai_output_choices": with_privacy_mode(
                 self._client._ph_client,
                 posthog_privacy_mode,
@@ -165,12 +460,23 @@ class WrappedCompletions(openai.resources.chat.completions.Completions):
             "$ai_http_status": 200,
             "$ai_input_tokens": usage_stats.get("prompt_tokens", 0),
             "$ai_output_tokens": usage_stats.get("completion_tokens", 0),
+            "$ai_cache_read_input_tokens": usage_stats.get(
+                "cache_read_input_tokens", 0
+            ),
+            "$ai_reasoning_tokens": usage_stats.get("reasoning_tokens", 0),
             "$ai_latency": latency,
             "$ai_trace_id": posthog_trace_id,
             "$ai_base_url": str(self._client.base_url),
-            **posthog_properties,
+            **(posthog_properties or {}),
         }
 
+        if tool_calls:
+            event_properties["$ai_tools"] = with_privacy_mode(
+                self._client._ph_client,
+                posthog_privacy_mode,
+                tool_calls,
+            )
+
         if posthog_distinct_id is None:
             event_properties["$process_person_profile"] = False
 
@@ -183,8 +489,16 @@ class WrappedCompletions(openai.resources.chat.completions.Completions):
             )
 
 
-class WrappedEmbeddings(openai.resources.embeddings.Embeddings):
-    _client: OpenAI
+class WrappedEmbeddings:
+    """Wrapper for OpenAI embeddings that tracks usage in PostHog."""
+
+    def __init__(self, client: OpenAI, original_embeddings):
+        self._client = client
+        self._original = original_embeddings
+
+    def __getattr__(self, name):
+        """Fallback to original embeddings object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     def create(
         self,
@@ -202,16 +516,18 @@ class WrappedEmbeddings(openai.resources.embeddings.Embeddings):
             posthog_distinct_id: Optional ID to associate with the usage event.
             posthog_trace_id: Optional trace UUID for linking events.
             posthog_properties: Optional dictionary of extra properties to include in the event.
+            posthog_privacy_mode: Whether to anonymize the input and output.
+            posthog_groups: Optional dictionary of groups to associate with the event.
             **kwargs: Any additional parameters for the OpenAI Embeddings API.
 
         Returns:
             The response from OpenAI's embeddings.create call.
         """
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         start_time = time.time()
-        response = super().create(**kwargs)
+        response = self._original.create(**kwargs)
         end_time = time.time()
 
         # Extract usage statistics if available
@@ -228,13 +544,15 @@ class WrappedEmbeddings(openai.resources.embeddings.Embeddings):
         event_properties = {
             "$ai_provider": "openai",
             "$ai_model": kwargs.get("model"),
-            "$ai_input": with_privacy_mode(self._client._ph_client, posthog_privacy_mode, kwargs.get("input")),
+            "$ai_input": with_privacy_mode(
+                self._client._ph_client, posthog_privacy_mode, kwargs.get("input")
+            ),
             "$ai_http_status": 200,
             "$ai_input_tokens": usage_stats.get("prompt_tokens", 0),
             "$ai_latency": latency,
             "$ai_trace_id": posthog_trace_id,
             "$ai_base_url": str(self._client.base_url),
-            **posthog_properties,
+            **(posthog_properties or {}),
         }
 
         if posthog_distinct_id is None:
@@ -252,24 +570,48 @@ class WrappedEmbeddings(openai.resources.embeddings.Embeddings):
         return response
 
 
-class WrappedBeta(openai.resources.beta.Beta):
-    _client: OpenAI
+class WrappedBeta:
+    """Wrapper for OpenAI beta features that tracks usage in PostHog."""
+
+    def __init__(self, client: OpenAI, original_beta):
+        self._client = client
+        self._original = original_beta
+
+    def __getattr__(self, name):
+        """Fallback to original beta object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     @property
     def chat(self):
-        return WrappedBetaChat(self._client)
+        return WrappedBetaChat(self._client, self._original.chat)
 
 
-class WrappedBetaChat(openai.resources.beta.chat.Chat):
-    _client: OpenAI
+class WrappedBetaChat:
+    """Wrapper for OpenAI beta chat that tracks usage in PostHog."""
+
+    def __init__(self, client: OpenAI, original_beta_chat):
+        self._client = client
+        self._original = original_beta_chat
+
+    def __getattr__(self, name):
+        """Fallback to original beta chat object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     @property
     def completions(self):
-        return WrappedBetaCompletions(self._client)
+        return WrappedBetaCompletions(self._client, self._original.completions)
 
 
-class WrappedBetaCompletions(openai.resources.beta.chat.completions.Completions):
-    _client: OpenAI
+class WrappedBetaCompletions:
+    """Wrapper for OpenAI beta chat completions that tracks usage in PostHog."""
+
+    def __init__(self, client: OpenAI, original_beta_completions):
+        self._client = client
+        self._original = original_beta_completions
+
+    def __getattr__(self, name):
+        """Fallback to original beta completions object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     def parse(
         self,
@@ -289,6 +631,6 @@ class WrappedBetaCompletions(openai.resources.beta.chat.completions.Completions)
             posthog_privacy_mode,
             posthog_groups,
             self._client.base_url,
-            super().parse,
+            self._original.parse,
             **kwargs,
         )

posthog/ai/openai/openai_async.py

@@ -1,14 +1,20 @@
 import time
 import uuid
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional, cast
 
 try:
     import openai
-    import openai.resources
 except ImportError:
-    raise ModuleNotFoundError("Please install the OpenAI SDK to use this feature: 'pip install openai'")
+    raise ModuleNotFoundError(
+        "Please install the OpenAI SDK to use this feature: 'pip install openai'"
+    )
 
-from posthog.ai.utils import call_llm_and_track_usage_async, get_model_params, with_privacy_mode
+from posthog import setup
+from posthog.ai.utils import (
+    call_llm_and_track_usage_async,
+    get_model_params,
+    with_privacy_mode,
+)
 from posthog.client import Client as PostHogClient
 
 
@@ -19,30 +25,47 @@ class AsyncOpenAI(openai.AsyncOpenAI):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             api_key: OpenAI API key.
-            posthog_client: If provided, events will be captured via this client instance.
-            **openai_config: Additional keyword args (e.g. organization="xxx").
+            posthog_client: If provided, events will be captured via this client instead
+                            of the global posthog.
+            **openai_config: Any additional keyword args to set on openai (e.g. organization="xxx").
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
-        self.chat = WrappedChat(self)
-        self.embeddings = WrappedEmbeddings(self)
-        self.beta = WrappedBeta(self)
+        self._ph_client = posthog_client or setup()
+
+        # Store original objects after parent initialization (only if they exist)
+        self._original_chat = getattr(self, "chat", None)
+        self._original_embeddings = getattr(self, "embeddings", None)
+        self._original_beta = getattr(self, "beta", None)
+        self._original_responses = getattr(self, "responses", None)
+
+        # Replace with wrapped versions (only if originals exist)
+        if self._original_chat is not None:
+            self.chat = WrappedChat(self, self._original_chat)
+
+        if self._original_embeddings is not None:
+            self.embeddings = WrappedEmbeddings(self, self._original_embeddings)
+
+        if self._original_beta is not None:
+            self.beta = WrappedBeta(self, self._original_beta)
+
+        if self._original_responses is not None:
+            self.responses = WrappedResponses(self, self._original_responses)
 
 
-class WrappedChat(openai.resources.chat.AsyncChat):
-    _client: AsyncOpenAI
+class WrappedResponses:
+    """Async wrapper for OpenAI responses that tracks usage in PostHog."""
 
-    @property
-    def completions(self):
-        return WrappedCompletions(self._client)
+    def __init__(self, client: AsyncOpenAI, original_responses):
+        self._client = client
+        self._original = original_responses
 
-
-class WrappedCompletions(openai.resources.chat.completions.AsyncCompletions):
-    _client: AsyncOpenAI
+    def __getattr__(self, name):
+        """Fallback to original responses object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     async def create(
         self,
@@ -54,9 +77,8 @@ class WrappedCompletions(openai.resources.chat.completions.AsyncCompletions):
         **kwargs: Any,
     ):
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
-        # If streaming, handle streaming specifically
         if kwargs.get("stream", False):
             return await self._create_streaming(
                 posthog_distinct_id,
@@ -67,59 +89,75 @@ class WrappedCompletions(openai.resources.chat.completions.AsyncCompletions):
                 **kwargs,
             )
 
-        response = await call_llm_and_track_usage_async(
+        return await call_llm_and_track_usage_async(
             posthog_distinct_id,
             self._client._ph_client,
             "openai",
             posthog_trace_id,
             posthog_properties,
+            posthog_privacy_mode,
+            posthog_groups,
             self._client.base_url,
-            super().create,
+            self._original.create,
             **kwargs,
         )
-        return response
 
     async def _create_streaming(
         self,
         posthog_distinct_id: Optional[str],
         posthog_trace_id: Optional[str],
         posthog_properties: Optional[Dict[str, Any]],
-        posthog_privacy_mode: bool = False,
-        posthog_groups: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: bool,
+        posthog_groups: Optional[Dict[str, Any]],
         **kwargs: Any,
     ):
         start_time = time.time()
         usage_stats: Dict[str, int] = {}
-        accumulated_content = []
-        if "stream_options" not in kwargs:
-            kwargs["stream_options"] = {}
-        kwargs["stream_options"]["include_usage"] = True
-        response = await super().create(**kwargs)
+        final_content = []
+        response = await self._original.create(**kwargs)
 
         async def async_generator():
-            nonlocal usage_stats, accumulated_content
+            nonlocal usage_stats
+            nonlocal final_content  # noqa: F824
+
             try:
                 async for chunk in response:
+                    if hasattr(chunk, "type") and chunk.type == "response.completed":
+                        res = chunk.response
+                        if res.output and len(res.output) > 0:
+                            final_content.append(res.output[0])
+
                     if hasattr(chunk, "usage") and chunk.usage:
                         usage_stats = {
                             k: getattr(chunk.usage, k, 0)
                             for k in [
-                                "prompt_tokens",
-                                "completion_tokens",
+                                "input_tokens",
+                                "output_tokens",
                                 "total_tokens",
                             ]
                         }
-                    if hasattr(chunk, "choices") and chunk.choices and len(chunk.choices) > 0:
-                        content = chunk.choices[0].delta.content
-                        if content:
-                            accumulated_content.append(content)
+
+                        # Add support for cached tokens
+                        if hasattr(chunk.usage, "output_tokens_details") and hasattr(
+                            chunk.usage.output_tokens_details, "reasoning_tokens"
+                        ):
+                            usage_stats["reasoning_tokens"] = (
+                                chunk.usage.output_tokens_details.reasoning_tokens
+                            )
+
+                        if hasattr(chunk.usage, "input_tokens_details") and hasattr(
+                            chunk.usage.input_tokens_details, "cached_tokens"
+                        ):
+                            usage_stats["cache_read_input_tokens"] = (
+                                chunk.usage.input_tokens_details.cached_tokens
+                            )
 
                     yield chunk
 
             finally:
                 end_time = time.time()
                 latency = end_time - start_time
-                output = "".join(accumulated_content)
+                output = final_content
                 await self._capture_streaming_event(
                     posthog_distinct_id,
                     posthog_trace_id,
@@ -144,16 +182,280 @@ class WrappedCompletions(openai.resources.chat.completions.AsyncCompletions):
         kwargs: Dict[str, Any],
         usage_stats: Dict[str, int],
         latency: float,
-        output: str,
+        output: Any,
+        tool_calls: Optional[List[Dict[str, Any]]] = None,
     ):
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         event_properties = {
             "$ai_provider": "openai",
             "$ai_model": kwargs.get("model"),
             "$ai_model_parameters": get_model_params(kwargs),
-            "$ai_input": with_privacy_mode(self._client._ph_client, posthog_privacy_mode, kwargs.get("messages")),
+            "$ai_input": with_privacy_mode(
+                self._client._ph_client, posthog_privacy_mode, kwargs.get("input")
+            ),
+            "$ai_output_choices": with_privacy_mode(
+                self._client._ph_client,
+                posthog_privacy_mode,
+                output,
+            ),
+            "$ai_http_status": 200,
+            "$ai_input_tokens": usage_stats.get("input_tokens", 0),
+            "$ai_output_tokens": usage_stats.get("output_tokens", 0),
+            "$ai_cache_read_input_tokens": usage_stats.get(
+                "cache_read_input_tokens", 0
+            ),
+            "$ai_reasoning_tokens": usage_stats.get("reasoning_tokens", 0),
+            "$ai_latency": latency,
+            "$ai_trace_id": posthog_trace_id,
+            "$ai_base_url": str(self._client.base_url),
+            **(posthog_properties or {}),
+        }
+
+        if tool_calls:
+            event_properties["$ai_tools"] = with_privacy_mode(
+                self._client._ph_client,
+                posthog_privacy_mode,
+                tool_calls,
+            )
+
+        if posthog_distinct_id is None:
+            event_properties["$process_person_profile"] = False
+
+        if hasattr(self._client._ph_client, "capture"):
+            self._client._ph_client.capture(
+                distinct_id=posthog_distinct_id or posthog_trace_id,
+                event="$ai_generation",
+                properties=event_properties,
+                groups=posthog_groups,
+            )
+
+    async def parse(
+        self,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_trace_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: bool = False,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ):
+        """
+        Parse structured output using OpenAI's 'responses.parse' method, but also track usage in PostHog.
+
+        Args:
+            posthog_distinct_id: Optional ID to associate with the usage event.
+            posthog_trace_id: Optional trace UUID for linking events.
+            posthog_properties: Optional dictionary of extra properties to include in the event.
+            posthog_privacy_mode: Whether to anonymize the input and output.
+            posthog_groups: Optional dictionary of groups to associate with the event.
+            **kwargs: Any additional parameters for the OpenAI Responses Parse API.
+
+        Returns:
+            The response from OpenAI's responses.parse call.
+        """
+        return await call_llm_and_track_usage_async(
+            posthog_distinct_id,
+            self._client._ph_client,
+            "openai",
+            posthog_trace_id,
+            posthog_properties,
+            posthog_privacy_mode,
+            posthog_groups,
+            self._client.base_url,
+            self._original.parse,
+            **kwargs,
+        )
+
+
+class WrappedChat:
+    """Async wrapper for OpenAI chat that tracks usage in PostHog."""
+
+    def __init__(self, client: AsyncOpenAI, original_chat):
+        self._client = client
+        self._original = original_chat
+
+    def __getattr__(self, name):
+        """Fallback to original chat object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
+
+    @property
+    def completions(self):
+        return WrappedCompletions(self._client, self._original.completions)
+
+
+class WrappedCompletions:
+    """Async wrapper for OpenAI chat completions that tracks usage in PostHog."""
+
+    def __init__(self, client: AsyncOpenAI, original_completions):
+        self._client = client
+        self._original = original_completions
+
+    def __getattr__(self, name):
+        """Fallback to original completions object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
+
+    async def create(
+        self,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_trace_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: bool = False,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ):
+        if posthog_trace_id is None:
+            posthog_trace_id = str(uuid.uuid4())
+
+        # If streaming, handle streaming specifically
+        if kwargs.get("stream", False):
+            return await self._create_streaming(
+                posthog_distinct_id,
+                posthog_trace_id,
+                posthog_properties,
+                posthog_privacy_mode,
+                posthog_groups,
+                **kwargs,
+            )
+
+        response = await call_llm_and_track_usage_async(
+            posthog_distinct_id,
+            self._client._ph_client,
+            "openai",
+            posthog_trace_id,
+            posthog_properties,
+            posthog_privacy_mode,
+            posthog_groups,
+            self._client.base_url,
+            self._original.create,
+            **kwargs,
+        )
+        return response
+
+    async def _create_streaming(
+        self,
+        posthog_distinct_id: Optional[str],
+        posthog_trace_id: Optional[str],
+        posthog_properties: Optional[Dict[str, Any]],
+        posthog_privacy_mode: bool,
+        posthog_groups: Optional[Dict[str, Any]],
+        **kwargs: Any,
+    ):
+        start_time = time.time()
+        usage_stats: Dict[str, int] = {}
+        accumulated_content = []
+        accumulated_tools = {}
+
+        if "stream_options" not in kwargs:
+            kwargs["stream_options"] = {}
+        kwargs["stream_options"]["include_usage"] = True
+        response = await self._original.create(**kwargs)
+
+        async def async_generator():
+            nonlocal usage_stats
+            nonlocal accumulated_content  # noqa: F824
+            nonlocal accumulated_tools  # noqa: F824
+
+            try:
+                async for chunk in response:
+                    if hasattr(chunk, "usage") and chunk.usage:
+                        usage_stats = {
+                            k: getattr(chunk.usage, k, 0)
+                            for k in [
+                                "prompt_tokens",
+                                "completion_tokens",
+                                "total_tokens",
+                            ]
+                        }
+
+                        # Add support for cached tokens
+                        if hasattr(chunk.usage, "prompt_tokens_details") and hasattr(
+                            chunk.usage.prompt_tokens_details, "cached_tokens"
+                        ):
+                            usage_stats["cache_read_input_tokens"] = (
+                                chunk.usage.prompt_tokens_details.cached_tokens
+                            )
+
+                        if hasattr(chunk.usage, "output_tokens_details") and hasattr(
+                            chunk.usage.output_tokens_details, "reasoning_tokens"
+                        ):
+                            usage_stats["reasoning_tokens"] = (
+                                chunk.usage.output_tokens_details.reasoning_tokens
+                            )
+
+                    if (
+                        hasattr(chunk, "choices")
+                        and chunk.choices
+                        and len(chunk.choices) > 0
+                    ):
+                        if chunk.choices[0].delta and chunk.choices[0].delta.content:
+                            content = chunk.choices[0].delta.content
+                            if content:
+                                accumulated_content.append(content)
+
+                        # Process tool calls
+                        tool_calls = getattr(chunk.choices[0].delta, "tool_calls", None)
+                        if tool_calls:
+                            for tool_call in tool_calls:
+                                index = tool_call.index
+                                if index not in accumulated_tools:
+                                    accumulated_tools[index] = tool_call
+                                else:
+                                    # Append arguments for existing tool calls
+                                    if hasattr(tool_call, "function") and hasattr(
+                                        tool_call.function, "arguments"
+                                    ):
+                                        accumulated_tools[
+                                            index
+                                        ].function.arguments += (
+                                            tool_call.function.arguments
+                                        )
+
+                    yield chunk
+
+            finally:
+                end_time = time.time()
+                latency = end_time - start_time
+                output = "".join(accumulated_content)
+                tools = list(accumulated_tools.values()) if accumulated_tools else None
+                await self._capture_streaming_event(
+                    posthog_distinct_id,
+                    posthog_trace_id,
+                    posthog_properties,
+                    posthog_privacy_mode,
+                    posthog_groups,
+                    kwargs,
+                    usage_stats,
+                    latency,
+                    output,
+                    tools,
+                )
+
+        return async_generator()
+
+    async def _capture_streaming_event(
+        self,
+        posthog_distinct_id: Optional[str],
+        posthog_trace_id: Optional[str],
+        posthog_properties: Optional[Dict[str, Any]],
+        posthog_privacy_mode: bool,
+        posthog_groups: Optional[Dict[str, Any]],
+        kwargs: Dict[str, Any],
+        usage_stats: Dict[str, int],
+        latency: float,
+        output: Any,
+        tool_calls: Optional[List[Dict[str, Any]]] = None,
+    ):
+        if posthog_trace_id is None:
+            posthog_trace_id = str(uuid.uuid4())
+
+        event_properties = {
+            "$ai_provider": "openai",
+            "$ai_model": kwargs.get("model"),
+            "$ai_model_parameters": get_model_params(kwargs),
+            "$ai_input": with_privacy_mode(
+                self._client._ph_client, posthog_privacy_mode, kwargs.get("messages")
+            ),
             "$ai_output_choices": with_privacy_mode(
                 self._client._ph_client,
                 posthog_privacy_mode,
@@ -162,12 +464,23 @@ class WrappedCompletions(openai.resources.chat.completions.AsyncCompletions):
             "$ai_http_status": 200,
             "$ai_input_tokens": usage_stats.get("prompt_tokens", 0),
             "$ai_output_tokens": usage_stats.get("completion_tokens", 0),
+            "$ai_cache_read_input_tokens": usage_stats.get(
+                "cache_read_input_tokens", 0
+            ),
+            "$ai_reasoning_tokens": usage_stats.get("reasoning_tokens", 0),
             "$ai_latency": latency,
             "$ai_trace_id": posthog_trace_id,
             "$ai_base_url": str(self._client.base_url),
-            **posthog_properties,
+            **(posthog_properties or {}),
         }
 
+        if tool_calls:
+            event_properties["$ai_tools"] = with_privacy_mode(
+                self._client._ph_client,
+                posthog_privacy_mode,
+                tool_calls,
+            )
+
         if posthog_distinct_id is None:
             event_properties["$process_person_profile"] = False
 
@@ -180,8 +493,16 @@ class WrappedCompletions(openai.resources.chat.completions.AsyncCompletions):
             )
 
 
-class WrappedEmbeddings(openai.resources.embeddings.AsyncEmbeddings):
-    _client: AsyncOpenAI
+class WrappedEmbeddings:
+    """Async wrapper for OpenAI embeddings that tracks usage in PostHog."""
+
+    def __init__(self, client: AsyncOpenAI, original_embeddings):
+        self._client = client
+        self._original = original_embeddings
+
+    def __getattr__(self, name):
+        """Fallback to original embeddings object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     async def create(
         self,
@@ -199,18 +520,18 @@ class WrappedEmbeddings(openai.resources.embeddings.AsyncEmbeddings):
             posthog_distinct_id: Optional ID to associate with the usage event.
             posthog_trace_id: Optional trace UUID for linking events.
             posthog_properties: Optional dictionary of extra properties to include in the event.
-            posthog_privacy_mode: Whether to store input and output in PostHog.
-            posthog_groups: Optional dictionary of groups to include in the event.
+            posthog_privacy_mode: Whether to anonymize the input and output.
+            posthog_groups: Optional dictionary of groups to associate with the event.
             **kwargs: Any additional parameters for the OpenAI Embeddings API.
 
         Returns:
             The response from OpenAI's embeddings.create call.
         """
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
         start_time = time.time()
-        response = await super().create(**kwargs)
+        response = await self._original.create(**kwargs)
         end_time = time.time()
 
         # Extract usage statistics if available
@@ -227,13 +548,15 @@ class WrappedEmbeddings(openai.resources.embeddings.AsyncEmbeddings):
         event_properties = {
             "$ai_provider": "openai",
             "$ai_model": kwargs.get("model"),
-            "$ai_input": with_privacy_mode(self._client._ph_client, posthog_privacy_mode, kwargs.get("input")),
+            "$ai_input": with_privacy_mode(
+                self._client._ph_client, posthog_privacy_mode, kwargs.get("input")
+            ),
             "$ai_http_status": 200,
             "$ai_input_tokens": usage_stats.get("prompt_tokens", 0),
             "$ai_latency": latency,
             "$ai_trace_id": posthog_trace_id,
             "$ai_base_url": str(self._client.base_url),
-            **posthog_properties,
+            **(posthog_properties or {}),
         }
 
         if posthog_distinct_id is None:
@@ -251,24 +574,48 @@ class WrappedEmbeddings(openai.resources.embeddings.AsyncEmbeddings):
         return response
 
 
-class WrappedBeta(openai.resources.beta.AsyncBeta):
-    _client: AsyncOpenAI
+class WrappedBeta:
+    """Async wrapper for OpenAI beta features that tracks usage in PostHog."""
+
+    def __init__(self, client: AsyncOpenAI, original_beta):
+        self._client = client
+        self._original = original_beta
+
+    def __getattr__(self, name):
+        """Fallback to original beta object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     @property
     def chat(self):
-        return WrappedBetaChat(self._client)
+        return WrappedBetaChat(self._client, self._original.chat)
 
 
-class WrappedBetaChat(openai.resources.beta.chat.AsyncChat):
-    _client: AsyncOpenAI
+class WrappedBetaChat:
+    """Async wrapper for OpenAI beta chat that tracks usage in PostHog."""
+
+    def __init__(self, client: AsyncOpenAI, original_beta_chat):
+        self._client = client
+        self._original = original_beta_chat
+
+    def __getattr__(self, name):
+        """Fallback to original beta chat object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     @property
     def completions(self):
-        return WrappedBetaCompletions(self._client)
+        return WrappedBetaCompletions(self._client, self._original.completions)
 
 
-class WrappedBetaCompletions(openai.resources.beta.chat.completions.AsyncCompletions):
-    _client: AsyncOpenAI
+class WrappedBetaCompletions:
+    """Async wrapper for OpenAI beta chat completions that tracks usage in PostHog."""
+
+    def __init__(self, client: AsyncOpenAI, original_beta_completions):
+        self._client = client
+        self._original = original_beta_completions
+
+    def __getattr__(self, name):
+        """Fallback to original beta completions object for any methods we don't explicitly handle."""
+        return getattr(self._original, name)
 
     async def parse(
         self,
@@ -288,6 +635,6 @@ class WrappedBetaCompletions(openai.resources.beta.chat.completions.AsyncComplet
             posthog_privacy_mode,
             posthog_groups,
             self._client.base_url,
-            super().parse,
+            self._original.parse,
             **kwargs,
         )

posthog/ai/openai/openai_providers.py

@@ -0,0 +1,98 @@
+try:
+    import openai
+except ImportError:
+    raise ModuleNotFoundError(
+        "Please install the Open AI SDK to use this feature: 'pip install openai'"
+    )
+
+from posthog.ai.openai.openai import (
+    WrappedBeta,
+    WrappedChat,
+    WrappedEmbeddings,
+    WrappedResponses,
+)
+from posthog.ai.openai.openai_async import WrappedBeta as AsyncWrappedBeta
+from posthog.ai.openai.openai_async import WrappedChat as AsyncWrappedChat
+from posthog.ai.openai.openai_async import WrappedEmbeddings as AsyncWrappedEmbeddings
+from posthog.ai.openai.openai_async import WrappedResponses as AsyncWrappedResponses
+from typing import Optional
+
+from posthog.client import Client as PostHogClient
+from posthog import setup
+
+
+class AzureOpenAI(openai.AzureOpenAI):
+    """
+    A wrapper around the Azure OpenAI SDK that automatically sends LLM usage events to PostHog.
+    """
+
+    _ph_client: PostHogClient
+
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
+        """
+        Args:
+            api_key: Azure OpenAI API key.
+            posthog_client: If provided, events will be captured via this client instead
+                            of the global posthog.
+            **openai_config: Any additional keyword args to set on Azure OpenAI (e.g. azure_endpoint="xxx").
+        """
+        super().__init__(**kwargs)
+        self._ph_client = posthog_client or setup()
+
+        # Store original objects after parent initialization (only if they exist)
+        self._original_chat = getattr(self, "chat", None)
+        self._original_embeddings = getattr(self, "embeddings", None)
+        self._original_beta = getattr(self, "beta", None)
+        self._original_responses = getattr(self, "responses", None)
+
+        # Replace with wrapped versions (only if originals exist)
+        if self._original_chat is not None:
+            self.chat = WrappedChat(self, self._original_chat)
+
+        if self._original_embeddings is not None:
+            self.embeddings = WrappedEmbeddings(self, self._original_embeddings)
+
+        if self._original_beta is not None:
+            self.beta = WrappedBeta(self, self._original_beta)
+
+        if self._original_responses is not None:
+            self.responses = WrappedResponses(self, self._original_responses)
+
+
+class AsyncAzureOpenAI(openai.AsyncAzureOpenAI):
+    """
+    An async wrapper around the Azure OpenAI SDK that automatically sends LLM usage events to PostHog.
+    """
+
+    _ph_client: PostHogClient
+
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
+        """
+        Args:
+            api_key: Azure OpenAI API key.
+            posthog_client: If provided, events will be captured via this client instead
+                            of the global posthog.
+            **openai_config: Any additional keyword args to set on Azure OpenAI (e.g. azure_endpoint="xxx").
+        """
+        super().__init__(**kwargs)
+        self._ph_client = posthog_client or setup()
+
+        # Store original objects after parent initialization (only if they exist)
+        self._original_chat = getattr(self, "chat", None)
+        self._original_embeddings = getattr(self, "embeddings", None)
+        self._original_beta = getattr(self, "beta", None)
+        self._original_responses = getattr(self, "responses", None)
+
+        # Replace with wrapped versions (only if originals exist)
+        if self._original_chat is not None:
+            self.chat = AsyncWrappedChat(self, self._original_chat)
+
+        if self._original_embeddings is not None:
+            self.embeddings = AsyncWrappedEmbeddings(self, self._original_embeddings)
+
+        if self._original_beta is not None:
+            self.beta = AsyncWrappedBeta(self, self._original_beta)
+
+        # Only add responses if available (newer OpenAI versions)
+        if self._original_responses is not None:
+            self.responses = AsyncWrappedResponses(self, self._original_responses)

posthog/ai/utils.py

@@ -1,6 +1,6 @@
 import time
 import uuid
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 from httpx import URL
 
@@ -34,15 +34,68 @@ def get_usage(response, provider: str) -> Dict[str, Any]:
         return {
             "input_tokens": response.usage.input_tokens,
             "output_tokens": response.usage.output_tokens,
+            "cache_read_input_tokens": response.usage.cache_read_input_tokens,
+            "cache_creation_input_tokens": response.usage.cache_creation_input_tokens,
         }
     elif provider == "openai":
+        cached_tokens = 0
+        input_tokens = 0
+        output_tokens = 0
+        reasoning_tokens = 0
+
+        # responses api
+        if hasattr(response.usage, "input_tokens"):
+            input_tokens = response.usage.input_tokens
+        if hasattr(response.usage, "output_tokens"):
+            output_tokens = response.usage.output_tokens
+        if hasattr(response.usage, "input_tokens_details") and hasattr(
+            response.usage.input_tokens_details, "cached_tokens"
+        ):
+            cached_tokens = response.usage.input_tokens_details.cached_tokens
+        if hasattr(response.usage, "output_tokens_details") and hasattr(
+            response.usage.output_tokens_details, "reasoning_tokens"
+        ):
+            reasoning_tokens = response.usage.output_tokens_details.reasoning_tokens
+
+        # chat completions
+        if hasattr(response.usage, "prompt_tokens"):
+            input_tokens = response.usage.prompt_tokens
+        if hasattr(response.usage, "completion_tokens"):
+            output_tokens = response.usage.completion_tokens
+        if hasattr(response.usage, "prompt_tokens_details") and hasattr(
+            response.usage.prompt_tokens_details, "cached_tokens"
+        ):
+            cached_tokens = response.usage.prompt_tokens_details.cached_tokens
+
         return {
-            "input_tokens": response.usage.prompt_tokens,
-            "output_tokens": response.usage.completion_tokens,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "cache_read_input_tokens": cached_tokens,
+            "reasoning_tokens": reasoning_tokens,
+        }
+    elif provider == "gemini":
+        input_tokens = 0
+        output_tokens = 0
+
+        if hasattr(response, "usage_metadata") and response.usage_metadata:
+            input_tokens = getattr(response.usage_metadata, "prompt_token_count", 0)
+            output_tokens = getattr(
+                response.usage_metadata, "candidates_token_count", 0
+            )
+
+        return {
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "cache_read_input_tokens": 0,
+            "cache_creation_input_tokens": 0,
+            "reasoning_tokens": 0,
         }
     return {
         "input_tokens": 0,
         "output_tokens": 0,
+        "cache_read_input_tokens": 0,
+        "cache_creation_input_tokens": 0,
+        "reasoning_tokens": 0,
     }
 
 
@@ -57,6 +110,8 @@ def format_response(response, provider: str):
         return format_response_anthropic(response)
     elif provider == "openai":
         return format_response_openai(response)
+    elif provider == "gemini":
+        return format_response_gemini(response)
     return output
 
 
@@ -75,24 +130,184 @@ def format_response_anthropic(response):
 
 def format_response_openai(response):
     output = []
-    for choice in response.choices:
-        if choice.message.content:
-            output.append(
-                {
-                    "content": choice.message.content,
-                    "role": choice.message.role,
-                }
-            )
+    if hasattr(response, "choices"):
+        for choice in response.choices:
+            # Handle Chat Completions response format
+            if hasattr(choice, "message") and choice.message and choice.message.content:
+                output.append(
+                    {
+                        "content": choice.message.content,
+                        "role": choice.message.role,
+                    }
+                )
+    # Handle Responses API format
+    if hasattr(response, "output"):
+        for item in response.output:
+            if item.type == "message":
+                # Extract text content from the content list
+                if hasattr(item, "content") and isinstance(item.content, list):
+                    for content_item in item.content:
+                        if (
+                            hasattr(content_item, "type")
+                            and content_item.type == "output_text"
+                            and hasattr(content_item, "text")
+                        ):
+                            output.append(
+                                {
+                                    "content": content_item.text,
+                                    "role": item.role,
+                                }
+                            )
+                        elif hasattr(content_item, "text"):
+                            output.append(
+                                {
+                                    "content": content_item.text,
+                                    "role": item.role,
+                                }
+                            )
+                        elif (
+                            hasattr(content_item, "type")
+                            and content_item.type == "input_image"
+                            and hasattr(content_item, "image_url")
+                        ):
+                            output.append(
+                                {
+                                    "content": {
+                                        "type": "image",
+                                        "image": content_item.image_url,
+                                    },
+                                    "role": item.role,
+                                }
+                            )
+                else:
+                    output.append(
+                        {
+                            "content": item.content,
+                            "role": item.role,
+                        }
+                    )
     return output
 
 
+def format_response_gemini(response):
+    output = []
+    if hasattr(response, "candidates") and response.candidates:
+        for candidate in response.candidates:
+            if hasattr(candidate, "content") and candidate.content:
+                content_text = ""
+                if hasattr(candidate.content, "parts") and candidate.content.parts:
+                    for part in candidate.content.parts:
+                        if hasattr(part, "text") and part.text:
+                            content_text += part.text
+                if content_text:
+                    output.append(
+                        {
+                            "role": "assistant",
+                            "content": content_text,
+                        }
+                    )
+            elif hasattr(candidate, "text") and candidate.text:
+                output.append(
+                    {
+                        "role": "assistant",
+                        "content": candidate.text,
+                    }
+                )
+    elif hasattr(response, "text") and response.text:
+        output.append(
+            {
+                "role": "assistant",
+                "content": response.text,
+            }
+        )
+    return output
+
+
+def format_tool_calls(response, provider: str):
+    if provider == "anthropic":
+        if hasattr(response, "tools") and response.tools and len(response.tools) > 0:
+            return response.tools
+    elif provider == "openai":
+        # Handle both Chat Completions and Responses API
+        if hasattr(response, "choices") and response.choices:
+            # Check for tool_calls in message (Chat Completions format)
+            if (
+                hasattr(response.choices[0], "message")
+                and hasattr(response.choices[0].message, "tool_calls")
+                and response.choices[0].message.tool_calls
+            ):
+                return response.choices[0].message.tool_calls
+
+            # Check for tool_calls directly in response (Responses API format)
+            if (
+                hasattr(response.choices[0], "tool_calls")
+                and response.choices[0].tool_calls
+            ):
+                return response.choices[0].tool_calls
+    return None
+
+
 def merge_system_prompt(kwargs: Dict[str, Any], provider: str):
-    if provider != "anthropic":
-        return kwargs.get("messages")
-    messages = kwargs.get("messages") or []
-    if kwargs.get("system") is None:
-        return messages
-    return [{"role": "system", "content": kwargs.get("system")}] + messages
+    messages: List[Dict[str, Any]] = []
+    if provider == "anthropic":
+        messages = kwargs.get("messages") or []
+        if kwargs.get("system") is None:
+            return messages
+        return [{"role": "system", "content": kwargs.get("system")}] + messages
+    elif provider == "gemini":
+        contents = kwargs.get("contents", [])
+        if isinstance(contents, str):
+            return [{"role": "user", "content": contents}]
+        elif isinstance(contents, list):
+            formatted = []
+            for item in contents:
+                if isinstance(item, str):
+                    formatted.append({"role": "user", "content": item})
+                elif hasattr(item, "text"):
+                    formatted.append({"role": "user", "content": item.text})
+                else:
+                    formatted.append({"role": "user", "content": str(item)})
+            return formatted
+        else:
+            return [{"role": "user", "content": str(contents)}]
+
+    # For OpenAI, handle both Chat Completions and Responses API
+    if kwargs.get("messages") is not None:
+        messages = list(kwargs.get("messages", []))
+
+    if kwargs.get("input") is not None:
+        input_data = kwargs.get("input")
+        if isinstance(input_data, list):
+            messages.extend(input_data)
+        else:
+            messages.append({"role": "user", "content": input_data})
+
+    # Check if system prompt is provided as a separate parameter
+    if kwargs.get("system") is not None:
+        has_system = any(msg.get("role") == "system" for msg in messages)
+        if not has_system:
+            messages = [{"role": "system", "content": kwargs.get("system")}] + messages
+
+    # For Responses API, add instructions to the system prompt if provided
+    if kwargs.get("instructions") is not None:
+        # Find the system message if it exists
+        system_idx = next(
+            (i for i, msg in enumerate(messages) if msg.get("role") == "system"), None
+        )
+
+        if system_idx is not None:
+            # Append instructions to existing system message
+            system_content = messages[system_idx].get("content", "")
+            messages[system_idx]["content"] = (
+                f"{system_content}\n\n{kwargs.get('instructions')}"
+            )
+        else:
+            # Create a new system message with instructions
+            messages = [
+                {"role": "system", "content": kwargs.get("instructions")}
+            ] + messages
+
+    return messages
 
 
 def call_llm_and_track_usage(
@@ -122,7 +337,9 @@ def call_llm_and_track_usage(
         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
+        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__(),
@@ -132,9 +349,12 @@ def call_llm_and_track_usage(
         latency = end_time - start_time
 
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
-        if response and hasattr(response, "usage"):
+        if response and (
+            hasattr(response, "usage")
+            or (provider == "gemini" and hasattr(response, "usage_metadata"))
+        ):
             usage = get_usage(response, provider)
 
         messages = merge_system_prompt(kwargs, provider)
@@ -157,9 +377,43 @@ def call_llm_and_track_usage(
             **(error_params or {}),
         }
 
+        tool_calls = format_tool_calls(response, provider)
+        if tool_calls:
+            event_properties["$ai_tools"] = with_privacy_mode(
+                ph_client, posthog_privacy_mode, tool_calls
+            )
+
+        if (
+            usage.get("cache_read_input_tokens") is not None
+            and usage.get("cache_read_input_tokens", 0) > 0
+        ):
+            event_properties["$ai_cache_read_input_tokens"] = usage.get(
+                "cache_read_input_tokens", 0
+            )
+
+        if (
+            usage.get("cache_creation_input_tokens") is not None
+            and usage.get("cache_creation_input_tokens", 0) > 0
+        ):
+            event_properties["$ai_cache_creation_input_tokens"] = usage.get(
+                "cache_creation_input_tokens", 0
+            )
+
+        if (
+            usage.get("reasoning_tokens") is not None
+            and usage.get("reasoning_tokens", 0) > 0
+        ):
+            event_properties["$ai_reasoning_tokens"] = usage.get("reasoning_tokens", 0)
+
         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")
+            )
+
         # send the event to posthog
         if hasattr(ph_client, "capture") and callable(ph_client.capture):
             ph_client.capture(
@@ -198,7 +452,9 @@ async def call_llm_and_track_usage_async(
         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
+        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__(),
@@ -208,9 +464,12 @@ async def call_llm_and_track_usage_async(
         latency = end_time - start_time
 
         if posthog_trace_id is None:
-            posthog_trace_id = uuid.uuid4()
+            posthog_trace_id = str(uuid.uuid4())
 
-        if response and hasattr(response, "usage"):
+        if response and (
+            hasattr(response, "usage")
+            or (provider == "gemini" and hasattr(response, "usage_metadata"))
+        ):
             usage = get_usage(response, provider)
 
         messages = merge_system_prompt(kwargs, provider)
@@ -233,9 +492,37 @@ async def call_llm_and_track_usage_async(
             **(error_params or {}),
         }
 
+        tool_calls = format_tool_calls(response, provider)
+        if tool_calls:
+            event_properties["$ai_tools"] = with_privacy_mode(
+                ph_client, posthog_privacy_mode, tool_calls
+            )
+
+        if (
+            usage.get("cache_read_input_tokens") is not None
+            and usage.get("cache_read_input_tokens", 0) > 0
+        ):
+            event_properties["$ai_cache_read_input_tokens"] = usage.get(
+                "cache_read_input_tokens", 0
+            )
+
+        if (
+            usage.get("cache_creation_input_tokens") is not None
+            and usage.get("cache_creation_input_tokens", 0) > 0
+        ):
+            event_properties["$ai_cache_creation_input_tokens"] = usage.get(
+                "cache_creation_input_tokens", 0
+            )
+
         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")
+            )
+
         # send the event to posthog
         if hasattr(ph_client, "capture") and callable(ph_client.capture):
             ph_client.capture(

posthog/args.py

@@ -0,0 +1,71 @@
+from typing import TypedDict, Optional, Any, Dict, Union, Tuple, Type
+from types import TracebackType
+from typing_extensions import NotRequired  # For Python < 3.11 compatibility
+from datetime import datetime
+import numbers
+from uuid import UUID
+
+from posthog.types import SendFeatureFlagsOptions
+
+ID_TYPES = Union[numbers.Number, str, UUID, int]
+
+
+class OptionalCaptureArgs(TypedDict):
+    """Optional arguments for the capture method.
+
+    Args:
+        distinct_id: Unique identifier for the person associated with this event. If not set, the context
+            distinct_id is used, if available, otherwise a UUID is generated, and the event is marked
+            as personless. Setting context-level distinct_id's is recommended.
+        properties: Dictionary of properties to track with the event
+        timestamp: When the event occurred (defaults to current time)
+        uuid: Unique identifier for this specific event. If not provided, one is generated. The event
+            UUID is returned, so you can correlate it with actions in your app (like showing users an
+            error ID if you capture an exception).
+        groups: Group identifiers to associate with this event (format: {group_type: group_key})
+        send_feature_flags: Whether to include currently active feature flags in the event properties.
+            Can be a boolean (True/False) or a SendFeatureFlagsOptions object for advanced configuration.
+            Defaults to False.
+        disable_geoip: Whether to disable GeoIP lookup for this event. Defaults to False.
+    """
+
+    distinct_id: NotRequired[Optional[ID_TYPES]]
+    properties: NotRequired[Optional[Dict[str, Any]]]
+    timestamp: NotRequired[Optional[Union[datetime, str]]]
+    uuid: NotRequired[Optional[str]]
+    groups: NotRequired[Optional[Dict[str, str]]]
+    send_feature_flags: NotRequired[
+        Optional[Union[bool, SendFeatureFlagsOptions]]
+    ]  # Updated to support both boolean and options object
+    disable_geoip: NotRequired[
+        Optional[bool]
+    ]  # As above, optional so we can tell if the user is intentionally overriding a client setting or not
+
+
+class OptionalSetArgs(TypedDict):
+    """Optional arguments for the set method.
+
+    Args:
+        distinct_id: Unique identifier for the user to set properties on. If not set, the context
+            distinct_id is used, if available, otherwise this function does nothing. Setting
+            context-level distinct_id's is recommended.
+        properties: Dictionary of properties to set on the person
+        timestamp: When the properties were set (defaults to current time)
+        uuid: Unique identifier for this operation. If not provided, one is generated. This
+            UUID is returned, so you can correlate it with actions in your app.
+        disable_geoip: Whether to disable GeoIP lookup for this operation. Defaults to False.
+    """
+
+    distinct_id: NotRequired[Optional[ID_TYPES]]
+    properties: NotRequired[Optional[Dict[str, Any]]]
+    timestamp: NotRequired[Optional[Union[datetime, str]]]
+    uuid: NotRequired[Optional[str]]
+    disable_geoip: NotRequired[Optional[bool]]
+
+
+ExcInfo = Union[
+    Tuple[Type[BaseException], BaseException, Optional[TracebackType]],
+    Tuple[None, None, None],
+]
+
+ExceptionArg = Union[BaseException, ExcInfo]

posthog/consumer.py

@@ -1,9 +1,9 @@
 import json
 import logging
+import time
 from threading import Thread
 
 import backoff
-import monotonic
 
 from posthog.request import APIError, DatetimeSerializer, batch_post
 
@@ -96,18 +96,20 @@ class Consumer(Thread):
         queue = self.queue
         items = []
 
-        start_time = monotonic.monotonic()
+        start_time = time.monotonic()
         total_size = 0
 
         while len(items) < self.flush_at:
-            elapsed = monotonic.monotonic() - start_time
+            elapsed = time.monotonic() - start_time
             if elapsed >= self.flush_interval:
                 break
             try:
                 item = queue.get(block=True, timeout=self.flush_interval - elapsed)
                 item_size = len(json.dumps(item, cls=DatetimeSerializer).encode())
                 if item_size > MAX_MSG_SIZE:
-                    self.log.error("Item exceeds 900kib limit, dropping. (%s)", str(item))
+                    self.log.error(
+                        "Item exceeds 900kib limit, dropping. (%s)", str(item)
+                    )
                     continue
                 items.append(item)
                 total_size += item_size
@@ -134,7 +136,9 @@ class Consumer(Thread):
                 # retry on all other errors (eg. network)
                 return False
 
-        @backoff.on_exception(backoff.expo, Exception, max_tries=self.retries + 1, giveup=fatal_exception)
+        @backoff.on_exception(
+            backoff.expo, Exception, max_tries=self.retries + 1, giveup=fatal_exception
+        )
         def send_request():
             batch_post(
                 self.api_key,

posthog/contexts.py

@@ -0,0 +1,284 @@
+import contextvars
+from contextlib import contextmanager
+from typing import Optional, Any, Callable, Dict, TypeVar, cast, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # To avoid circular imports
+    from posthog.client import Client
+
+
+class ContextScope:
+    def __init__(
+        self,
+        parent=None,
+        fresh: bool = False,
+        capture_exceptions: bool = True,
+        client: Optional["Client"] = None,
+    ):
+        self.client: Optional[Client] = client
+        self.parent = parent
+        self.fresh = fresh
+        self.capture_exceptions = capture_exceptions
+        self.session_id: Optional[str] = None
+        self.distinct_id: Optional[str] = None
+        self.tags: Dict[str, Any] = {}
+
+    def set_session_id(self, session_id: str):
+        self.session_id = session_id
+
+    def set_distinct_id(self, distinct_id: str):
+        self.distinct_id = distinct_id
+
+    def add_tag(self, key: str, value: Any):
+        self.tags[key] = value
+
+    def get_parent(self):
+        return self.parent
+
+    def get_session_id(self) -> Optional[str]:
+        if self.session_id is not None:
+            return self.session_id
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_session_id()
+        return None
+
+    def get_distinct_id(self) -> Optional[str]:
+        if self.distinct_id is not None:
+            return self.distinct_id
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_distinct_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
+
+
+_context_stack: contextvars.ContextVar[Optional[ContextScope]] = contextvars.ContextVar(
+    "posthog_context_stack", default=None
+)
+
+
+def _get_current_context() -> Optional[ContextScope]:
+    return _context_stack.get()
+
+
+@contextmanager
+def new_context(
+    fresh: bool = False,
+    capture_exceptions: bool = True,
+    client: Optional["Client"] = None,
+):
+    """
+    Create a new context scope that will be active for the duration of the with block.
+    Any tags set within this scope will be isolated to this context. Any exceptions raised
+    or events captured within the context will be tagged with the context tags.
+
+    Args:
+        fresh: Whether to start with a fresh context (default: False).
+               If False, inherits tags, identity and session id's from parent context.
+               If True, starts with no state
+        capture_exceptions: Whether to capture exceptions raised within the context (default: True).
+               If True, captures exceptions and tags them with the context tags before propagating them.
+               If False, exceptions will propagate without being tagged or captured.
+        client: Optional client instance to use for capturing exceptions (default: None).
+                If provided, the client will be used to capture exceptions within the context.
+                If not provided, the default (global) client will be used. Note that the passed
+                client is only used to capture exceptions within the context - other events captured
+                within the context via `Client.capture` or `posthog.capture` will still carry the context
+                state (tags, identity, session id), but will be captured by the client directly used (or
+                the global one, in the case of `posthog.capture`)
+
+    Examples:
+        ```python
+        # Inherit parent context tags
+        with posthog.new_context():
+            posthog.tag("request_id", "123")
+            # Both this event and the exception will be tagged with the context tags
+            posthog.capture("event_name", {"property": "value"})
+            raise ValueError("Something went wrong")
+        ```
+        ```python
+        # Start with fresh context (no inherited tags)
+        with posthog.new_context(fresh=True):
+            posthog.tag("request_id", "123")
+            # Both this event and the exception will be tagged with the context tags
+            posthog.capture("event_name", {"property": "value"})
+            raise ValueError("Something went wrong")
+        ```
+
+    Category:
+        Contexts
+    """
+    from posthog import capture_exception
+
+    current_context = _get_current_context()
+    new_context = ContextScope(current_context, fresh, capture_exceptions, client)
+    _context_stack.set(new_context)
+
+    try:
+        yield
+    except Exception as e:
+        if new_context.capture_exceptions:
+            if new_context.client:
+                new_context.client.capture_exception(e)
+            else:
+                capture_exception(e)
+        raise
+    finally:
+        _context_stack.set(new_context.get_parent())
+
+
+def tag(key: str, value: Any) -> None:
+    """
+    Add a tag to the current context. All tags are added as properties to any event, including exceptions, captured
+    within the context.
+
+    Args:
+        key: The tag key
+        value: The tag value
+
+    Example:
+        ```python
+        posthog.tag("user_id", "123")
+        ```
+
+    Category:
+        Contexts
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.add_tag(key, value)
+
+
+def get_tags() -> Dict[str, Any]:
+    """
+    Get all tags from the current context. Note, modifying
+    the returned dictionary will not affect the current context.
+
+    Returns:
+        Dict of all tags in the current context
+
+    Category:
+        Contexts
+    """
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.collect_tags()
+    return {}
+
+
+def identify_context(distinct_id: str) -> None:
+    """
+    Identify the current context with a distinct ID, associating all events captured in this or
+    child contexts with the given distinct ID (unless identify_context is called again). This is overridden by
+    distinct id's passed directly to posthog.capture and related methods (identify, set etc). Entering a
+    fresh context will clear the context-level distinct ID. The distinct-id passed should be uniquely associated
+    with one of your users. Events captured outside of a context, or in a context with no associated distinct
+    ID, will be assigned a random UUID, and captured as "personless".
+
+    Args:
+        distinct_id: The distinct ID to associate with the current context and its children.
+
+    Category:
+        Contexts
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_distinct_id(distinct_id)
+
+
+def set_context_session(session_id: str) -> None:
+    """
+    Set the session ID for the current context, associating all events captured in this or
+    child contexts with the given session ID (unless set_context_session is called again).
+    Entering a fresh context will clear the context-level session ID.
+
+    Args:
+        session_id: The session ID to associate with the current context and its children. See https://posthog.com/docs/data/sessions
+
+    Category:
+        Contexts
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_session_id(session_id)
+
+
+def get_context_session_id() -> Optional[str]:
+    """
+    Get the session ID for the current context.
+
+    Returns:
+        The session ID if set, None otherwise
+
+    Category:
+        Contexts
+    """
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_session_id()
+    return None
+
+
+def get_context_distinct_id() -> Optional[str]:
+    """
+    Get the distinct ID for the current context.
+
+    Returns:
+        The distinct ID if set, None otherwise
+
+    Category:
+        Contexts
+    """
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_distinct_id()
+    return None
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def scoped(fresh: bool = False, capture_exceptions: bool = True):
+    """
+    Decorator that creates a new context for the function. Simply wraps
+    the function in a with posthog.new_context(): block.
+
+    Args:
+        fresh: Whether to start with a fresh context (default: False)
+        capture_exceptions: Whether to capture and track exceptions with posthog error tracking (default: True)
+
+    Example:
+        @posthog.scoped()
+        def process_payment(payment_id):
+            posthog.tag("payment_id", payment_id)
+            posthog.tag("payment_method", "credit_card")
+
+            # This event will be captured with tags
+            posthog.capture("payment_started")
+            # If this raises an exception, it will be captured with tags
+            # and then re-raised
+            some_risky_function()
+
+    Category:
+        Contexts
+    """
+
+    def decorator(func: F) -> F:
+        from functools import wraps
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            with new_context(fresh=fresh, capture_exceptions=capture_exceptions):
+                return func(*args, **kwargs)
+
+        return cast(F, wrapper)
+
+    return decorator

posthog/exception_capture.py

@@ -1,45 +1,30 @@
+# Portions of this file are derived from getsentry/sentry-javascript by Software, Inc. dba Sentry
+# Licensed under the MIT License
+
+# 💖open source (under MIT License)
+
 import logging
 import sys
 import threading
-from enum import Enum
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from posthog.client import Client
 
 
-class Integrations(str, Enum):
-    Django = "django"
-
-
 class ExceptionCapture:
     # TODO: Add client side rate limiting to prevent spamming the server with exceptions
 
     log = logging.getLogger("posthog")
 
-    def __init__(self, client: "Client", integrations: Optional[List[Integrations]] = None):
+    def __init__(self, client: "Client"):
         self.client = client
         self.original_excepthook = sys.excepthook
         sys.excepthook = self.exception_handler
         threading.excepthook = self.thread_exception_handler
-        self.enabled_integrations = []
-
-        for integration in integrations or []:
-            # TODO: Maybe find a better way of enabling integrations
-            # This is very annoying currently if we had to add any configuration per integration
-            if integration == Integrations.Django:
-                try:
-                    from posthog.exception_integrations.django import DjangoIntegration
-
-                    enabled_integration = DjangoIntegration(self.exception_receiver)
-                    self.enabled_integrations.append(enabled_integration)
-                except Exception as e:
-                    self.log.exception(f"Failed to enable Django integration: {e}")
 
     def close(self):
         sys.excepthook = self.original_excepthook
-        for integration in self.enabled_integrations:
-            integration.uninstall()
 
     def exception_handler(self, exc_type, exc_value, exc_traceback):
         # don't affect default behaviour.
@@ -59,6 +44,6 @@ class ExceptionCapture:
     def capture_exception(self, exception, metadata=None):
         try:
             distinct_id = metadata.get("distinct_id") if metadata else None
-            self.client.capture_exception(exception, distinct_id)
+            self.client.capture_exception(exception, distinct_id=distinct_id)
         except Exception as e:
             self.log.exception(f"Failed to capture exception: {e}")

posthog/exception_integrations/__init__.py

@@ -1,5 +0,0 @@
-class IntegrationEnablingError(Exception):
-    """
-    The integration could not be enabled due to a user error like
-    `django` not being installed for the `DjangoIntegration`.
-    """

posthog/exception_integrations/django.py

@@ -1,88 +0,0 @@
-import re
-import sys
-from typing import TYPE_CHECKING
-
-from posthog.exception_integrations import IntegrationEnablingError
-
-try:
-    from django import VERSION as DJANGO_VERSION
-    from django.core import signals
-
-except ImportError:
-    raise IntegrationEnablingError("Django not installed")
-
-
-if TYPE_CHECKING:
-    from typing import Any, Dict  # noqa: F401
-
-    from django.core.handlers.wsgi import WSGIRequest  # noqa: F401
-
-
-class DjangoIntegration:
-    # TODO: Abstract integrations one we have more and can see patterns
-    """
-    Autocapture errors from a Django application.
-    """
-
-    identifier = "django"
-
-    def __init__(self, capture_exception_fn=None):
-
-        if DJANGO_VERSION < (4, 2):
-            raise IntegrationEnablingError("Django 4.2 or newer is required.")
-
-        # TODO: Right now this seems too complicated / overkill for us, but seems like we can automatically plug in middlewares
-        # which is great for users (they don't need to do this) and everything should just work.
-        # We should consider this in the future, but for now we can just use the middleware and signals handlers.
-        # See: https://github.com/getsentry/sentry-python/blob/269d96d6e9821122fbff280e6a26956e5ed03c0b/sentry_sdk/integrations/django/__init__.py
-
-        self.capture_exception_fn = capture_exception_fn
-
-        def _got_request_exception(request=None, **kwargs):
-            # type: (WSGIRequest, **Any) -> None
-
-            extra_props = {}
-            if request is not None:
-                # get headers metadata
-                extra_props = DjangoRequestExtractor(request).extract_person_data()
-
-            self.capture_exception_fn(sys.exc_info(), extra_props)
-
-        signals.got_request_exception.connect(_got_request_exception)
-
-    def uninstall(self):
-        pass
-
-
-class DjangoRequestExtractor:
-
-    def __init__(self, request):
-        # type: (Any) -> None
-        self.request = request
-
-    def extract_person_data(self):
-        headers = self.headers()
-
-        # Extract traceparent and tracestate headers
-        traceparent = headers.get("traceparent")
-        tracestate = headers.get("tracestate")
-
-        # Extract the distinct_id from tracestate
-        distinct_id = None
-        if tracestate:
-            # TODO: Align on the format of the distinct_id in tracestate
-            # We can't have comma or equals in header values here, so maybe we should base64 encode it?
-            match = re.search(r"posthog-distinct-id=([^,]+)", tracestate)
-            if match:
-                distinct_id = match.group(1)
-
-        return {
-            "distinct_id": distinct_id,
-            "ip": headers.get("X-Forwarded-For"),
-            "user_agent": headers.get("User-Agent"),
-            "traceparent": traceparent,
-        }
-
-    def headers(self):
-        # type: () -> Dict[str, str]
-        return dict(self.request.headers)

posthog/exception_utils.py

@@ -1,3 +1,6 @@
+# Portions of this file are derived from getsentry/sentry-javascript by Software, Inc. dba Sentry
+# Licensed under the MIT License
+
 # copied and adapted from https://github.com/getsentry/sentry-python/blob/269d96d6e9821122fbff280e6a26956e5ed03c0b/sentry_sdk/utils.py#L689
 # 💖open source (under MIT License)
 # We want to keep payloads as similar to Sentry as possible for easy interoperability
@@ -6,8 +9,26 @@ import linecache
 import os
 import re
 import sys
+import types
 from datetime import datetime
-from typing import TYPE_CHECKING
+from types import FrameType, TracebackType  # noqa: F401
+from typing import (  # noqa: F401
+    Any,
+    Dict,
+    Iterator,
+    List,
+    Literal,
+    Optional,
+    Set,
+    Tuple,
+    TypedDict,
+    TypeVar,
+    Union,
+    cast,
+    TYPE_CHECKING,
+)
+
+from posthog.args import ExcInfo, ExceptionArg  # noqa: F401
 
 try:
     # Python 3.11
@@ -19,78 +40,61 @@ except ImportError:
 
 DEFAULT_MAX_VALUE_LENGTH = 1024
 
+LogLevelStr = Literal["fatal", "critical", "error", "warning", "info", "debug"]
 
-if TYPE_CHECKING:
-
-    from types import FrameType, TracebackType
-    from typing import (  # noqa: F401
-        Any,
-        Callable,
-        Dict,
-        Iterator,
-        List,
-        Literal,
-        Optional,
-        Set,
-        Tuple,
-        Type,
-        TypedDict,
-        TypeVar,
-        Union,
-        cast,
-    )
-
-    ExcInfo = Union[
-        Tuple[Type[BaseException], BaseException, Optional[TracebackType]],
-        Tuple[None, None, None],
-    ]
-    LogLevelStr = Literal["fatal", "critical", "error", "warning", "info", "debug"]
-
-    Event = TypedDict(
-        "Event",
-        {
-            "breadcrumbs": Dict[Literal["values"], List[Dict[str, Any]]],  # TODO: We can expand on this type
-            "check_in_id": str,
-            "contexts": Dict[str, Dict[str, object]],
-            "dist": str,
-            "duration": Optional[float],
-            "environment": str,
-            "errors": List[Dict[str, Any]],  # TODO: We can expand on this type
-            "event_id": str,
-            "exception": Dict[Literal["values"], List[Dict[str, Any]]],  # TODO: We can expand on this type
-            # "extra": MutableMapping[str, object],
-            # "fingerprint": List[str],
-            "level": LogLevelStr,
-            # "logentry": Mapping[str, object],
-            "logger": str,
-            # "measurements": Dict[str, MeasurementValue],
-            "message": str,
-            "modules": Dict[str, str],
-            # "monitor_config": Mapping[str, object],
-            "monitor_slug": Optional[str],
-            "platform": Literal["python"],
-            "profile": object,  # Should be sentry_sdk.profiler.Profile, but we can't import that here due to circular imports
-            "release": str,
-            "request": Dict[str, object],
-            # "sdk": Mapping[str, object],
-            "server_name": str,
-            "spans": List[Dict[str, object]],
-            "stacktrace": Dict[str, object],  # We access this key in the code, but I am unsure whether we ever set it
-            "start_timestamp": datetime,
-            "status": Optional[str],
-            # "tags": MutableMapping[
-            #     str, str
-            # ],  # Tags must be less than 200 characters each
-            "threads": Dict[Literal["values"], List[Dict[str, Any]]],  # TODO: We can expand on this type
-            "timestamp": Optional[datetime],  # Must be set before sending the event
-            "transaction": str,
-            # "transaction_info": Mapping[str, Any],  # TODO: We can expand on this type
-            "type": Literal["check_in", "transaction"],
-            "user": Dict[str, object],
-            "_metrics_summary": Dict[str, object],
-        },
-        total=False,
-    )
+Event = TypedDict(
+    "Event",
+    {
+        "breadcrumbs": Dict[
+            Literal["values"], List[Dict[str, Any]]
+        ],  # TODO: We can expand on this type
+        "check_in_id": str,
+        "contexts": Dict[str, Dict[str, object]],
+        "dist": str,
+        "duration": Optional[float],
+        "environment": str,
+        "errors": List[Dict[str, Any]],  # TODO: We can expand on this type
+        "event_id": str,
+        "exception": Dict[
+            Literal["values"], List[Dict[str, Any]]
+        ],  # TODO: We can expand on this type
+        # "extra": MutableMapping[str, object],
+        # "fingerprint": List[str],
+        "level": LogLevelStr,
+        # "logentry": Mapping[str, object],
+        "logger": str,
+        # "measurements": Dict[str, MeasurementValue],
+        "message": str,
+        "modules": Dict[str, str],
+        # "monitor_config": Mapping[str, object],
+        "monitor_slug": Optional[str],
+        "platform": Literal["python"],
+        "profile": object,
+        "release": str,
+        "request": Dict[str, object],
+        # "sdk": Mapping[str, object],
+        "server_name": str,
+        "spans": List[Dict[str, object]],
+        "stacktrace": Dict[
+            str, object
+        ],  # We access this key in the code, but I am unsure whether we ever set it
+        "start_timestamp": datetime,
+        "status": Optional[str],
+        # "tags": MutableMapping[
+        #     str, str
+        # ],  # Tags must be less than 200 characters each
+        "threads": Dict[
+            Literal["values"], List[Dict[str, Any]]
+        ],  # TODO: We can expand on this type
+        "timestamp": Optional[datetime],  # Must be set before sending the event
+        "transaction": str,
+        # "transaction_info": Mapping[str, Any],  # TODO: We can expand on this type
+        "type": Literal["check_in", "transaction"],
+        "user": Dict[str, object],
+        "_metrics_summary": Dict[str, object],
+    },
+    total=False,
+)
 
 
 epoch = datetime(1970, 1, 1)
@@ -126,9 +130,6 @@ def event_hint_with_exc_info(exc_info=None):
 class AnnotatedValue:
     """
     Meta information for a data field in the event payload.
-    This is to tell Relay that we have tampered with the fields value.
-    See:
-    https://github.com/getsentry/relay/blob/be12cd49a0f06ea932ed9b9f93a655de5d6ad6d1/relay-general/src/types/meta.rs#L407-L423
     """
 
     __slots__ = ("value", "metadata")
@@ -270,7 +271,10 @@ def get_lines_from_file(
     upper_bound = min(lineno + 1 + context_lines, len(source))
 
     try:
-        pre_context = [strip_string(line.strip("\r\n"), max_length=max_length) for line in source[lower_bound:lineno]]
+        pre_context = [
+            strip_string(line.strip("\r\n"), max_length=max_length)
+            for line in source[lower_bound:lineno]
+        ]
         context_line = strip_string(source[lineno].strip("\r\n"), max_length=max_length)
         post_context = [
             strip_string(line.strip("\r\n"), max_length=max_length)
@@ -302,7 +306,9 @@ def get_source_context(
         loader = None
     lineno = tb_lineno - 1
     if lineno is not None and abs_path:
-        return get_lines_from_file(abs_path, lineno, max_value_length, loader=loader, module=module)
+        return get_lines_from_file(
+            abs_path, lineno, max_value_length, loader=loader, module=module
+        )
     return [], None, []
 
 
@@ -339,7 +345,9 @@ def filename_for_module(module, abs_path):
         if not base_module_path:
             return abs_path
 
-        return abs_path.split(base_module_path.rsplit(os.sep, 2)[0], 1)[-1].lstrip(os.sep)
+        return abs_path.split(base_module_path.rsplit(os.sep, 2)[0], 1)[-1].lstrip(
+            os.sep
+        )
     except Exception:
         return abs_path
 
@@ -347,12 +355,9 @@ def filename_for_module(module, abs_path):
 def serialize_frame(
     frame,
     tb_lineno=None,
-    include_local_variables=True,
-    include_source_context=True,
     max_value_length=None,
-    custom_repr=None,
 ):
-    # type: (FrameType, Optional[int], bool, bool, Optional[int], Optional[Callable[..., Optional[str]]]) -> Dict[str, Any]
+    # type: (FrameType, Optional[int], Optional[int]) -> Dict[str, Any]
     f_code = getattr(frame, "f_code", None)
     if not f_code:
         abs_path = None
@@ -377,50 +382,13 @@ def serialize_frame(
         "lineno": tb_lineno,
     }  # type: Dict[str, Any]
 
-    if include_source_context:
-        rv["pre_context"], rv["context_line"], rv["post_context"] = get_source_context(
-            frame, tb_lineno, max_value_length
-        )
-
-    if include_local_variables:
-        # TODO(nk): Sort out this current invalid import
-        # from sentry_sdk.serializer import serialize
-
-        # rv["vars"] = serialize(
-        #     dict(frame.f_locals), is_vars=True, custom_repr=custom_repr
-        # )
-        pass
+    rv["pre_context"], rv["context_line"], rv["post_context"] = get_source_context(
+        frame, tb_lineno, max_value_length
+    )
 
     return rv
 
 
-def current_stacktrace(
-    include_local_variables=True,  # type: bool
-    include_source_context=True,  # type: bool
-    max_value_length=None,  # type: Optional[int]
-):
-    # type: (...) -> Dict[str, Any]
-    __tracebackhide__ = True
-    frames = []
-
-    f = sys._getframe()  # type: Optional[FrameType]
-    while f is not None:
-        if not should_hide_frame(f):
-            frames.append(
-                serialize_frame(
-                    f,
-                    include_local_variables=include_local_variables,
-                    include_source_context=include_source_context,
-                    max_value_length=max_value_length,
-                )
-            )
-        f = f.f_back
-
-    frames.reverse()
-
-    return {"frames": frames, "type": "raw"}
-
-
 def get_errno(exc_value):
     # type: (BaseException) -> Optional[Any]
     return getattr(exc_value, "errno", None)
@@ -428,14 +396,19 @@ def get_errno(exc_value):
 
 def get_error_message(exc_value):
     # type: (Optional[BaseException]) -> str
-    return getattr(exc_value, "message", "") or getattr(exc_value, "detail", "") or safe_str(exc_value)
+    message = (
+        getattr(exc_value, "message", "")
+        or getattr(exc_value, "detail", "")
+        or exc_value
+    )
+
+    return safe_str(message)
 
 
 def single_exception_from_error_tuple(
     exc_type,  # type: Optional[type]
     exc_value,  # type: Optional[BaseException]
     tb,  # type: Optional[TracebackType]
-    client_options=None,  # type: Optional[Dict[str, Any]]
     mechanism=None,  # type: Optional[Dict[str, Any]]
     exception_id=None,  # type: Optional[int]
     parent_id=None,  # type: Optional[int]
@@ -443,13 +416,12 @@ def single_exception_from_error_tuple(
 ):
     # type: (...) -> Dict[str, Any]
     """
-    Creates a dict that goes into the events `exception.values` list and is ingestible by Sentry.
-
-    See the Exception Interface documentation for more details:
-    https://develop.sentry.dev/sdk/event-payloads/exception/
+    Creates a dict that goes into the events `exception.values` list
     """
     exception_value = {}  # type: Dict[str, Any]
-    exception_value["mechanism"] = mechanism.copy() if mechanism else {"type": "generic", "handled": True}
+    exception_value["mechanism"] = (
+        mechanism.copy() if mechanism else {"type": "generic", "handled": True}
+    )
     if exception_id is not None:
         exception_value["mechanism"]["exception_id"] = exception_id
 
@@ -459,7 +431,9 @@ def single_exception_from_error_tuple(
         errno = None
 
     if errno is not None:
-        exception_value["mechanism"].setdefault("meta", {}).setdefault("errno", {}).setdefault("number", errno)
+        exception_value["mechanism"].setdefault("meta", {}).setdefault(
+            "errno", {}
+        ).setdefault("number", errno)
 
     if source is not None:
         exception_value["mechanism"]["source"] = source
@@ -472,7 +446,9 @@ def single_exception_from_error_tuple(
     if is_root_exception and "type" not in exception_value["mechanism"]:
         exception_value["mechanism"]["type"] = "generic"
 
-    is_exception_group = BaseExceptionGroup is not None and isinstance(exc_value, BaseExceptionGroup)
+    is_exception_group = BaseExceptionGroup is not None and isinstance(
+        exc_value, BaseExceptionGroup
+    )
     if is_exception_group:
         exception_value["mechanism"]["is_exception_group"] = True
 
@@ -480,25 +456,13 @@ def single_exception_from_error_tuple(
     exception_value["type"] = get_type_name(exc_type)
     exception_value["value"] = get_error_message(exc_value)
 
-    if client_options is None:
-        include_local_variables = True
-        include_source_context = True
-        max_value_length = DEFAULT_MAX_VALUE_LENGTH  # fallback
-        custom_repr = None
-    else:
-        include_local_variables = client_options["include_local_variables"]
-        include_source_context = client_options["include_source_context"]
-        max_value_length = client_options["max_value_length"]
-        custom_repr = client_options.get("custom_repr")
+    max_value_length = DEFAULT_MAX_VALUE_LENGTH  # fallback
 
     frames = [
         serialize_frame(
             tb.tb_frame,
             tb_lineno=tb.tb_lineno,
-            include_local_variables=include_local_variables,
-            include_source_context=include_source_context,
             max_value_length=max_value_length,
-            custom_repr=custom_repr,
         )
         for tb in iter_stacks(tb)
     ]
@@ -520,7 +484,11 @@ if HAS_CHAINED_EXCEPTIONS:
         seen_exceptions = []
         seen_exception_ids = set()  # type: Set[int]
 
-        while exc_type is not None and exc_value is not None and id(exc_value) not in seen_exception_ids:
+        while (
+            exc_type is not None
+            and exc_value is not None
+            and id(exc_value) not in seen_exception_ids
+        ):
             yield exc_type, exc_value, tb
 
             # Avoid hashing random types we don't know anything
@@ -550,7 +518,6 @@ def exceptions_from_error(
     exc_type,  # type: Optional[type]
     exc_value,  # type: Optional[BaseException]
     tb,  # type: Optional[TracebackType]
-    client_options=None,  # type: Optional[Dict[str, Any]]
     mechanism=None,  # type: Optional[Dict[str, Any]]
     exception_id=0,  # type: int
     parent_id=0,  # type: int
@@ -560,16 +527,12 @@ def exceptions_from_error(
     """
     Creates the list of exceptions.
     This can include chained exceptions and exceptions from an ExceptionGroup.
-
-    See the Exception Interface documentation for more details:
-    https://develop.sentry.dev/sdk/event-payloads/exception/
     """
 
     parent = single_exception_from_error_tuple(
         exc_type=exc_type,
         exc_value=exc_value,
         tb=tb,
-        client_options=client_options,
         mechanism=mechanism,
         exception_id=exception_id,
         parent_id=parent_id,
@@ -580,18 +543,23 @@ def exceptions_from_error(
     parent_id = exception_id
     exception_id += 1
 
-    should_supress_context = hasattr(exc_value, "__suppress_context__") and exc_value.__suppress_context__  # type: ignore
+    should_supress_context = (
+        hasattr(exc_value, "__suppress_context__") and exc_value.__suppress_context__  # type: ignore
+    )
     if should_supress_context:
         # Add direct cause.
         # The field `__cause__` is set when raised with the exception (using the `from` keyword).
-        exception_has_cause = exc_value and hasattr(exc_value, "__cause__") and exc_value.__cause__ is not None
+        exception_has_cause = (
+            exc_value
+            and hasattr(exc_value, "__cause__")
+            and exc_value.__cause__ is not None
+        )
         if exception_has_cause:
             cause = exc_value.__cause__  # type: ignore
             (exception_id, child_exceptions) = exceptions_from_error(
                 exc_type=type(cause),
                 exc_value=cause,
                 tb=getattr(cause, "__traceback__", None),
-                client_options=client_options,
                 mechanism=mechanism,
                 exception_id=exception_id,
                 source="__cause__",
@@ -601,14 +569,17 @@ def exceptions_from_error(
     else:
         # Add indirect cause.
         # The field `__context__` is assigned if another exception occurs while handling the exception.
-        exception_has_content = exc_value and hasattr(exc_value, "__context__") and exc_value.__context__ is not None
+        exception_has_content = (
+            exc_value
+            and hasattr(exc_value, "__context__")
+            and exc_value.__context__ is not None
+        )
         if exception_has_content:
             context = exc_value.__context__  # type: ignore
             (exception_id, child_exceptions) = exceptions_from_error(
                 exc_type=type(context),
                 exc_value=context,
                 tb=getattr(context, "__traceback__", None),
-                client_options=client_options,
                 mechanism=mechanism,
                 exception_id=exception_id,
                 source="__context__",
@@ -623,7 +594,6 @@ def exceptions_from_error(
                 exc_type=type(e),
                 exc_value=e,
                 tb=getattr(e, "__traceback__", None),
-                client_options=client_options,
                 mechanism=mechanism,
                 exception_id=exception_id,
                 parent_id=parent_id,
@@ -636,20 +606,20 @@ def exceptions_from_error(
 
 def exceptions_from_error_tuple(
     exc_info,  # type: ExcInfo
-    client_options=None,  # type: Optional[Dict[str, Any]]
     mechanism=None,  # type: Optional[Dict[str, Any]]
 ):
     # type: (...) -> List[Dict[str, Any]]
     exc_type, exc_value, tb = exc_info
 
-    is_exception_group = BaseExceptionGroup is not None and isinstance(exc_value, BaseExceptionGroup)
+    is_exception_group = BaseExceptionGroup is not None and isinstance(
+        exc_value, BaseExceptionGroup
+    )
 
     if is_exception_group:
         (_, exceptions) = exceptions_from_error(
             exc_type=exc_type,
             exc_value=exc_value,
             tb=tb,
-            client_options=client_options,
             mechanism=mechanism,
             exception_id=0,
             parent_id=0,
@@ -658,7 +628,9 @@ def exceptions_from_error_tuple(
     else:
         exceptions = []
         for exc_type, exc_value, tb in walk_exception_chain(exc_info):
-            exceptions.append(single_exception_from_error_tuple(exc_type, exc_value, tb, client_options, mechanism))
+            exceptions.append(
+                single_exception_from_error_tuple(exc_type, exc_value, tb, mechanism)
+            )
 
     exceptions.reverse()
 
@@ -746,11 +718,42 @@ def set_in_app_in_frames(frames, in_app_exclude, in_app_include, project_root=No
     return frames
 
 
+def exception_is_already_captured(error):
+    # type: (ExceptionArg) -> bool
+    if isinstance(error, BaseException):
+        return hasattr(error, "__posthog_exception_captured")
+    # Autocaptured exceptions are passed as a tuple from our system hooks,
+    # the second item is the exception value (the first is the exception type)
+    elif isinstance(error, tuple) and len(error) > 1:
+        return error[1] is not None and hasattr(
+            error[1], "__posthog_exception_captured"
+        )
+    else:
+        return False  # type: ignore[unreachable]
+
+
+def mark_exception_as_captured(error, uuid):
+    # type: (ExceptionArg, str) -> None
+    if isinstance(error, BaseException):
+        setattr(error, "__posthog_exception_captured", True)
+        setattr(error, "__posthog_exception_uuid", uuid)
+    # Autocaptured exceptions are passed as a tuple from our system hooks,
+    # the second item is the exception value (the first is the exception type)
+    elif isinstance(error, tuple) and len(error) > 1:
+        if error[1] is not None:
+            setattr(error[1], "__posthog_exception_captured", True)
+            setattr(error[1], "__posthog_exception_uuid", uuid)
+
+
 def exc_info_from_error(error):
-    # type: (Union[BaseException, ExcInfo]) -> ExcInfo
+    # type: (ExceptionArg) -> ExcInfo
     if isinstance(error, tuple) and len(error) == 3:
         exc_type, exc_value, tb = error
     elif isinstance(error, BaseException):
+        try:
+            construct_artificial_traceback(error)
+        except Exception:
+            pass
         tb = getattr(error, "__traceback__", None)
         if tb is not None:
             exc_type = type(error)
@@ -775,21 +778,29 @@ def exc_info_from_error(error):
     return exc_info
 
 
-def event_from_exception(
-    exc_info,  # type: Union[BaseException, ExcInfo]
-    client_options=None,  # type: Optional[Dict[str, Any]]
-    mechanism=None,  # type: Optional[Dict[str, Any]]
-):
-    # type: (...) -> Tuple[Event, Dict[str, Any]]
-    exc_info = exc_info_from_error(exc_info)
-    hint = event_hint_with_exc_info(exc_info)
-    return (
-        {
-            "level": "error",
-            "exception": {"values": exceptions_from_error_tuple(exc_info, client_options, mechanism)},
-        },
-        hint,
-    )
+def construct_artificial_traceback(e):
+    # type: (BaseException) -> None
+    if getattr(e, "__traceback__", None) is not None:
+        return
+
+    depth = 0
+    frames = []
+    while True:
+        try:
+            frame = sys._getframe(depth)
+            depth += 1
+        except ValueError:
+            break
+
+        frames.append(frame)
+
+    frames.reverse()
+
+    tb = None
+    for frame in frames:
+        tb = types.TracebackType(tb, frame, frame.f_lasti, frame.f_lineno)
+
+    setattr(e, "__traceback__", tb)
 
 
 def _module_in_list(name, items):
@@ -810,7 +821,9 @@ def _module_in_list(name, items):
 def _is_external_source(abs_path):
     # type: (str) -> bool
     # check if frame is in 'site-packages' or 'dist-packages'
-    external_source = re.search(r"[\\/](?:dist|site)-packages[\\/]", abs_path) is not None
+    external_source = (
+        re.search(r"[\\/](?:dist|site)-packages[\\/]", abs_path) is not None
+    )
     return external_source
 
 

posthog/feature_flags.py

@@ -8,6 +8,7 @@ from dateutil import parser
 from dateutil.relativedelta import relativedelta
 
 from posthog import utils
+from posthog.types import FlagValue
 from posthog.utils import convert_to_datetime_aware, is_valid_regex
 
 __LONG_SCALE__ = float(0xFFFFFFFFFFFFFFF)
@@ -25,7 +26,7 @@ class InconclusiveMatchError(Exception):
 # Given the same distinct_id and key, it'll always return the same float. These floats are
 # uniformly distributed between 0 and 1, so if we want to show this feature to 20% of traffic
 # we can do _hash(key, distinct_id) < 0.2
-def _hash(key, distinct_id, salt=""):
+def _hash(key: str, distinct_id: str, salt: str = "") -> float:
     hash_key = f"{key}.{distinct_id}{salt}"
     hash_val = int(hashlib.sha1(hash_key.encode("utf-8")).hexdigest()[:15], 16)
     return hash_val / __LONG_SCALE__
@@ -42,20 +43,28 @@ def get_matching_variant(flag, distinct_id):
 def variant_lookup_table(feature_flag):
     lookup_table = []
     value_min = 0
-    multivariates = ((feature_flag.get("filters") or {}).get("multivariate") or {}).get("variants") or []
+    multivariates = ((feature_flag.get("filters") or {}).get("multivariate") or {}).get(
+        "variants"
+    ) or []
     for variant in multivariates:
         value_max = value_min + variant["rollout_percentage"] / 100
-        lookup_table.append({"value_min": value_min, "value_max": value_max, "key": variant["key"]})
+        lookup_table.append(
+            {"value_min": value_min, "value_max": value_max, "key": variant["key"]}
+        )
         value_min = value_max
     return lookup_table
 
 
-def match_feature_flag_properties(flag, distinct_id, properties, cohort_properties=None):
+def match_feature_flag_properties(
+    flag, distinct_id, properties, cohort_properties=None
+) -> FlagValue:
     flag_conditions = (flag.get("filters") or {}).get("groups") or []
     is_inconclusive = False
     cohort_properties = cohort_properties or {}
     # Some filters can be explicitly set to null, which require accessing variants like so
-    flag_variants = ((flag.get("filters") or {}).get("multivariate") or {}).get("variants") or []
+    flag_variants = ((flag.get("filters") or {}).get("multivariate") or {}).get(
+        "variants"
+    ) or []
     valid_variant_keys = [variant["key"] for variant in flag_variants]
 
     # Stable sort conditions with variant overrides to the top. This ensures that if overrides are present, they are
@@ -69,7 +78,9 @@ def match_feature_flag_properties(flag, distinct_id, properties, cohort_properti
         try:
             # if any one condition resolves to True, we can shortcircuit and return
             # the matching variant
-            if is_condition_match(flag, distinct_id, condition, properties, cohort_properties):
+            if is_condition_match(
+                flag, distinct_id, condition, properties, cohort_properties
+            ):
                 variant_override = condition.get("variant")
                 if variant_override and variant_override in valid_variant_keys:
                     variant = variant_override
@@ -80,20 +91,32 @@ def match_feature_flag_properties(flag, distinct_id, properties, cohort_properti
             is_inconclusive = True
 
     if is_inconclusive:
-        raise InconclusiveMatchError("Can't determine if feature flag is enabled or not with given properties")
+        raise InconclusiveMatchError(
+            "Can't determine if feature flag is enabled or not with given properties"
+        )
 
     # We can only return False when either all conditions are False, or
     # no condition was inconclusive.
     return False
 
 
-def is_condition_match(feature_flag, distinct_id, condition, properties, cohort_properties):
+def is_condition_match(
+    feature_flag, distinct_id, condition, properties, cohort_properties
+) -> bool:
     rollout_percentage = condition.get("rollout_percentage")
     if len(condition.get("properties") or []) > 0:
         for prop in condition.get("properties"):
             property_type = prop.get("type")
             if property_type == "cohort":
                 matches = match_cohort(prop, properties, cohort_properties)
+            elif property_type == "flag":
+                log.warning(
+                    "Flag dependency filters are not supported in local evaluation. "
+                    "Skipping condition for flag '%s' with dependency on flag '%s'",
+                    feature_flag.get("key", "unknown"),
+                    prop.get("key", "unknown"),
+                )
+                continue
             else:
                 matches = match_property(prop, properties)
             if not matches:
@@ -102,7 +125,9 @@ def is_condition_match(feature_flag, distinct_id, condition, properties, cohort_
         if rollout_percentage is None:
             return True
 
-    if rollout_percentage is not None and _hash(feature_flag["key"], distinct_id) > (rollout_percentage / 100):
+    if rollout_percentage is not None and _hash(feature_flag["key"], distinct_id) > (
+        rollout_percentage / 100
+    ):
         return False
 
     return True
@@ -116,7 +141,9 @@ def match_property(property, property_values) -> bool:
     value = property.get("value")
 
     if key not in property_values:
-        raise InconclusiveMatchError("can't match properties without a given property value")
+        raise InconclusiveMatchError(
+            "can't match properties without a given property value"
+        )
 
     if operator == "is_not_set":
         raise InconclusiveMatchError("can't match properties with operator is_not_set")
@@ -130,7 +157,9 @@ def match_property(property, property_values) -> bool:
 
         def compute_exact_match(value, override_value):
             if isinstance(value, list):
-                return str(override_value).casefold() in [str(val).casefold() for val in value]
+                return str(override_value).casefold() in [
+                    str(val).casefold() for val in value
+                ]
             return utils.str_iequals(value, override_value)
 
         if operator == "exact":
@@ -148,10 +177,16 @@ def match_property(property, property_values) -> bool:
         return not utils.str_icontains(override_value, value)
 
     if operator == "regex":
-        return is_valid_regex(str(value)) and re.compile(str(value)).search(str(override_value)) is not None
+        return (
+            is_valid_regex(str(value))
+            and re.compile(str(value)).search(str(override_value)) is not None
+        )
 
     if operator == "not_regex":
-        return is_valid_regex(str(value)) and re.compile(str(value)).search(str(override_value)) is None
+        return (
+            is_valid_regex(str(value))
+            and re.compile(str(value)).search(str(override_value)) is None
+        )
 
     if operator in ("gt", "gte", "lt", "lte"):
         # :TRICKY: We adjust comparison based on the override value passed in,
@@ -190,10 +225,14 @@ def match_property(property, property_values) -> bool:
                 parsed_date = parser.parse(str(value))
                 parsed_date = convert_to_datetime_aware(parsed_date)
         except Exception as e:
-            raise InconclusiveMatchError("The date set on the flag is not a valid format") from e
+            raise InconclusiveMatchError(
+                "The date set on the flag is not a valid format"
+            ) from e
 
         if not parsed_date:
-            raise InconclusiveMatchError("The date set on the flag is not a valid format")
+            raise InconclusiveMatchError(
+                "The date set on the flag is not a valid format"
+            )
 
         if isinstance(override_value, datetime.datetime):
             override_date = convert_to_datetime_aware(override_value)
@@ -217,7 +256,9 @@ def match_property(property, property_values) -> bool:
             except Exception:
                 raise InconclusiveMatchError("The date provided is not a valid format")
         else:
-            raise InconclusiveMatchError("The date provided must be a string or date object")
+            raise InconclusiveMatchError(
+                "The date provided must be a string or date object"
+            )
 
     # if we get here, we don't know how to handle the operator
     raise InconclusiveMatchError(f"Unknown operator {operator}")
@@ -235,7 +276,9 @@ def match_cohort(property, property_values, cohort_properties) -> bool:
     # }
     cohort_id = str(property.get("value"))
     if cohort_id not in cohort_properties:
-        raise InconclusiveMatchError("can't match cohort without a given cohort property value")
+        raise InconclusiveMatchError(
+            "can't match cohort without a given cohort property value"
+        )
 
     property_group = cohort_properties[cohort_id]
     return match_property_group(property_group, property_values, cohort_properties)
@@ -271,7 +314,9 @@ def match_property_group(property_group, property_values, cohort_properties) ->
                 error_matching_locally = True
 
         if error_matching_locally:
-            raise InconclusiveMatchError("Can't match cohort without a given cohort property value")
+            raise InconclusiveMatchError(
+                "Can't match cohort without a given cohort property value"
+            )
         # if we get here, all matched in AND case, or none matched in OR case
         return property_group_type == "AND"
 
@@ -280,6 +325,13 @@ def match_property_group(property_group, property_values, cohort_properties) ->
             try:
                 if prop.get("type") == "cohort":
                     matches = match_cohort(prop, property_values, cohort_properties)
+                elif prop.get("type") == "flag":
+                    log.warning(
+                        "Flag dependency filters are not supported in local evaluation. "
+                        "Skipping condition with dependency on flag '%s'",
+                        prop.get("key", "unknown"),
+                    )
+                    continue
                 else:
                     matches = match_property(prop, property_values)
 
@@ -302,13 +354,17 @@ def match_property_group(property_group, property_values, cohort_properties) ->
                 error_matching_locally = True
 
         if error_matching_locally:
-            raise InconclusiveMatchError("can't match cohort without a given cohort property value")
+            raise InconclusiveMatchError(
+                "can't match cohort without a given cohort property value"
+            )
 
         # if we get here, all matched in AND case, or none matched in OR case
         return property_group_type == "AND"
 
 
-def relative_date_parse_for_feature_flag_matching(value: str) -> Optional[datetime.datetime]:
+def relative_date_parse_for_feature_flag_matching(
+    value: str,
+) -> Optional[datetime.datetime]:
     regex = r"^-?(?P<number>[0-9]+)(?P<interval>[a-z])$"
     match = re.search(regex, value)
     parsed_dt = datetime.datetime.now(datetime.timezone.utc)

posthog/integrations/django.py

@@ -0,0 +1,181 @@
+from typing import TYPE_CHECKING, cast
+from posthog import contexts, capture_exception
+from posthog.client import Client
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest, HttpResponse  # noqa: F401
+    from typing import Callable, Dict, Any, Optional  # noqa: F401
+
+
+class PosthogContextMiddleware:
+    """Middleware to automatically track Django requests.
+
+    This middleware wraps all calls with a posthog context. It attempts to extract the following from the request headers:
+    - Session ID, (extracted from `X-POSTHOG-SESSION-ID`)
+    - Distinct ID, (extracted from `X-POSTHOG-DISTINCT-ID`)
+    - Request URL as $current_url
+    - Request Method as $request_method
+
+    The context will also auto-capture exceptions and send them to PostHog, unless you disable it by setting
+    `POSTHOG_MW_CAPTURE_EXCEPTIONS` to `False` in your Django settings. The exceptions are captured using the
+    global client, unless the setting `POSTHOG_MW_CLIENT` is set to a custom client instance
+
+    The middleware behaviour is customisable through 3 additional functions:
+    - `POSTHOG_MW_EXTRA_TAGS`, which is a Callable[[HttpRequest], Dict[str, Any]] expected to return a dictionary of additional tags to be added to the context.
+    - `POSTHOG_MW_REQUEST_FILTER`, which is a Callable[[HttpRequest], bool] expected to return `False` if the request should not be tracked.
+    - `POSTHOG_MW_TAG_MAP`, which is a Callable[[Dict[str, Any]], Dict[str, Any]], which you can use to modify the tags before they're added to the context.
+
+    You can use the `POSTHOG_MW_TAG_MAP` function to remove any default tags you don't want to capture, or override them with your own values.
+
+    Context tags are automatically included as properties on all events captured within a context, including exceptions.
+    See the context documentation for more information. The extracted distinct ID and session ID, if found, are used to
+    associate all events captured in the middleware context with the same distinct ID and session as currently active on the
+    frontend. See the documentation for `set_context_session` and `identify_context` for more details.
+    """
+
+    def __init__(self, get_response):
+        # type: (Callable[[HttpRequest], HttpResponse]) -> None
+        self.get_response = get_response
+
+        from django.conf import settings
+
+        if hasattr(settings, "POSTHOG_MW_EXTRA_TAGS") and callable(
+            settings.POSTHOG_MW_EXTRA_TAGS
+        ):
+            self.extra_tags = cast(
+                "Optional[Callable[[HttpRequest], Dict[str, Any]]]",
+                settings.POSTHOG_MW_EXTRA_TAGS,
+            )
+        else:
+            self.extra_tags = None
+
+        if hasattr(settings, "POSTHOG_MW_REQUEST_FILTER") and callable(
+            settings.POSTHOG_MW_REQUEST_FILTER
+        ):
+            self.request_filter = cast(
+                "Optional[Callable[[HttpRequest], bool]]",
+                settings.POSTHOG_MW_REQUEST_FILTER,
+            )
+        else:
+            self.request_filter = None
+
+        if hasattr(settings, "POSTHOG_MW_TAG_MAP") and callable(
+            settings.POSTHOG_MW_TAG_MAP
+        ):
+            self.tag_map = cast(
+                "Optional[Callable[[Dict[str, Any]], Dict[str, Any]]]",
+                settings.POSTHOG_MW_TAG_MAP,
+            )
+        else:
+            self.tag_map = None
+
+        if hasattr(settings, "POSTHOG_MW_CAPTURE_EXCEPTIONS") and isinstance(
+            settings.POSTHOG_MW_CAPTURE_EXCEPTIONS, bool
+        ):
+            self.capture_exceptions = settings.POSTHOG_MW_CAPTURE_EXCEPTIONS
+        else:
+            self.capture_exceptions = True
+
+        if hasattr(settings, "POSTHOG_MW_CLIENT") and isinstance(
+            settings.POSTHOG_MW_CLIENT, Client
+        ):
+            self.client = cast("Optional[Client]", settings.POSTHOG_MW_CLIENT)
+        else:
+            self.client = None
+
+    def extract_tags(self, request):
+        # type: (HttpRequest) -> Dict[str, Any]
+        tags = {}
+
+        (user_id, user_email) = self.extract_request_user(request)
+
+        # Extract session ID from X-POSTHOG-SESSION-ID header
+        session_id = request.headers.get("X-POSTHOG-SESSION-ID")
+        if session_id:
+            contexts.set_context_session(session_id)
+
+        # Extract distinct ID from X-POSTHOG-DISTINCT-ID header or request user id
+        distinct_id = request.headers.get("X-POSTHOG-DISTINCT-ID") or user_id
+        if distinct_id:
+            contexts.identify_context(distinct_id)
+
+        # Extract user email
+        if user_email:
+            tags["email"] = user_email
+
+        # Extract current URL
+        absolute_url = request.build_absolute_uri()
+        if absolute_url:
+            tags["$current_url"] = absolute_url
+
+        # Extract request method
+        if request.method:
+            tags["$request_method"] = request.method
+
+        # Extract request path
+        if request.path:
+            tags["$request_path"] = request.path
+
+        # Extract IP address
+        ip_address = request.headers.get("X-Forwarded-For")
+        if ip_address:
+            tags["$ip_address"] = ip_address
+
+        # Extract user agent
+        user_agent = request.headers.get("User-Agent")
+        if user_agent:
+            tags["$user_agent"] = user_agent
+
+        # Apply extra tags if configured
+        if self.extra_tags:
+            extra = self.extra_tags(request)
+            if extra:
+                tags.update(extra)
+
+        # Apply tag mapping if configured
+        if self.tag_map:
+            tags = self.tag_map(tags)
+
+        return tags
+
+    def extract_request_user(self, request):
+        user_id = None
+        email = None
+
+        user = getattr(request, "user", None)
+
+        if user and getattr(user, "is_authenticated", False):
+            try:
+                user_id = str(user.pk)
+            except Exception:
+                pass
+
+            try:
+                email = str(user.email)
+            except Exception:
+                pass
+
+        return user_id, email
+
+    def __call__(self, request):
+        # type: (HttpRequest) -> HttpResponse
+        if self.request_filter and not self.request_filter(request):
+            return self.get_response(request)
+
+        with contexts.new_context(self.capture_exceptions, client=self.client):
+            for k, v in self.extract_tags(request).items():
+                contexts.tag(k, v)
+
+            return self.get_response(request)
+
+    def process_exception(self, request, exception):
+        if self.request_filter and not self.request_filter(request):
+            return
+
+        if not self.capture_exceptions:
+            return
+
+        if self.client:
+            self.client.capture_exception(exception)
+        else:
+            capture_exception(exception)

posthog/request.py

@@ -7,11 +7,20 @@ from typing import Any, Optional, Union
 
 import requests
 from dateutil.tz import tzutc
+from urllib3.util.retry import Retry
 
 from posthog.utils import remove_trailing_slash
 from posthog.version import VERSION
 
-adapter = requests.adapters.HTTPAdapter(max_retries=2)
+# Retry on both connect and read errors
+# by default read errors will only retry idempotent HTTP methods (so not POST)
+adapter = requests.adapters.HTTPAdapter(
+    max_retries=Retry(
+        total=2,
+        connect=2,
+        read=2,
+    )
+)
 _session = requests.sessions.Session()
 _session.mount("https://", adapter)
 
@@ -34,7 +43,12 @@ def determine_server_host(host: Optional[str]) -> str:
 
 
 def post(
-    api_key: str, host: Optional[str] = None, path=None, gzip: bool = False, timeout: int = 15, **kwargs
+    api_key: str,
+    host: Optional[str] = None,
+    path=None,
+    gzip: bool = False,
+    timeout: int = 15,
+    **kwargs,
 ) -> requests.Response:
     """Post the `kwargs` to the API"""
     log = logging.getLogger("posthog")
@@ -43,7 +57,7 @@ def post(
     url = remove_trailing_slash(host or DEFAULT_HOST) + path
     body["api_key"] = api_key
     data = json.dumps(body, cls=DatetimeSerializer)
-    log.debug("making request: %s", data)
+    log.debug("making request: %s to url: %s", data, url)
     headers = {"Content-Type": "application/json", "User-Agent": USER_AGENT}
     if gzip:
         headers["Content-Encoding"] = "gzip"
@@ -68,7 +82,21 @@ def _process_response(
     log = logging.getLogger("posthog")
     if res.status_code == 200:
         log.debug(success_message)
-        return res.json() if return_json else res
+        response = res.json() if return_json else res
+        # Handle quota limited decide responses by raising a specific error
+        # NB: other services also put entries into the quotaLimited key, but right now we only care about feature flags
+        # since most of the other services handle quota limiting in other places in the application.
+        if (
+            isinstance(response, dict)
+            and "quotaLimited" in response
+            and isinstance(response["quotaLimited"], list)
+            and "feature_flags" in response["quotaLimited"]
+        ):
+            log.warning(
+                "[FEATURE FLAGS] PostHog feature flags quota limited, resetting feature flag data.  Learn more about billing limits at https://posthog.com/docs/billing/limits-alerts"
+            )
+            raise QuotaLimitError(res.status_code, "Feature flags quota limited")
+        return response
     try:
         payload = res.json()
         log.debug("received response: %s", payload)
@@ -77,28 +105,67 @@ def _process_response(
         raise APIError(res.status_code, res.text)
 
 
-def decide(api_key: str, host: Optional[str] = None, gzip: bool = False, timeout: int = 15, **kwargs) -> Any:
+def decide(
+    api_key: str,
+    host: Optional[str] = None,
+    gzip: bool = False,
+    timeout: int = 15,
+    **kwargs,
+) -> Any:
     """Post the `kwargs to the decide API endpoint"""
-    res = post(api_key, host, "/decide/?v=3", gzip, timeout, **kwargs)
+    res = post(api_key, host, "/decide/?v=4", gzip, timeout, **kwargs)
     return _process_response(res, success_message="Feature flags decided successfully")
 
 
-def remote_config(personal_api_key: str, host: Optional[str] = None, key: str = "", timeout: int = 15) -> Any:
+def flags(
+    api_key: str,
+    host: Optional[str] = None,
+    gzip: bool = False,
+    timeout: int = 15,
+    **kwargs,
+) -> Any:
+    """Post the `kwargs to the flags API endpoint"""
+    res = post(api_key, host, "/flags/?v=2", gzip, timeout, **kwargs)
+    return _process_response(
+        res, success_message="Feature flags evaluated successfully"
+    )
+
+
+def remote_config(
+    personal_api_key: str, host: Optional[str] = None, key: str = "", timeout: int = 15
+) -> Any:
     """Get remote config flag value from remote_config API endpoint"""
-    return get(personal_api_key, f"/api/projects/@current/feature_flags/{key}/remote_config/", host, timeout)
+    return get(
+        personal_api_key,
+        f"/api/projects/@current/feature_flags/{key}/remote_config/",
+        host,
+        timeout,
+    )
 
 
 def batch_post(
-    api_key: str, host: Optional[str] = None, gzip: bool = False, timeout: int = 15, **kwargs
+    api_key: str,
+    host: Optional[str] = None,
+    gzip: bool = False,
+    timeout: int = 15,
+    **kwargs,
 ) -> requests.Response:
     """Post the `kwargs` to the batch API endpoint for events"""
     res = post(api_key, host, "/batch/", gzip, timeout, **kwargs)
-    return _process_response(res, success_message="data uploaded successfully", return_json=False)
+    return _process_response(
+        res, success_message="data uploaded successfully", return_json=False
+    )
 
 
-def get(api_key: str, url: str, host: Optional[str] = None, timeout: Optional[int] = None) -> requests.Response:
+def get(
+    api_key: str, url: str, host: Optional[str] = None, timeout: Optional[int] = None
+) -> requests.Response:
     url = remove_trailing_slash(host or DEFAULT_HOST) + url
-    res = requests.get(url, headers={"Authorization": "Bearer %s" % api_key, "User-Agent": USER_AGENT}, timeout=timeout)
+    res = requests.get(
+        url,
+        headers={"Authorization": "Bearer %s" % api_key, "User-Agent": USER_AGENT},
+        timeout=timeout,
+    )
     return _process_response(res, success_message=f"GET {url} completed successfully")
 
 
@@ -112,6 +179,10 @@ class APIError(Exception):
         return msg.format(self.message, self.status)
 
 
+class QuotaLimitError(APIError):
+    pass
+
+
 class DatetimeSerializer(json.JSONEncoder):
     def default(self, obj: Any):
         if isinstance(obj, (date, datetime)):

posthog/sentry/__init__.py

@@ -1 +0,0 @@
-POSTHOG_ID_TAG = "posthog_distinct_id"

posthog/sentry/django.py

@@ -1,28 +0,0 @@
-from django.conf import settings
-from sentry_sdk import configure_scope
-
-from posthog.sentry import POSTHOG_ID_TAG
-
-GET_DISTINCT_ID = getattr(settings, "POSTHOG_DJANGO", {}).get("distinct_id")
-
-
-def get_distinct_id(request):
-    if not GET_DISTINCT_ID:
-        return None
-    try:
-        return GET_DISTINCT_ID(request)
-    except:  # noqa: E722
-        return None
-
-
-class PosthogDistinctIdMiddleware:
-    def __init__(self, get_response):
-        self.get_response = get_response
-
-    def __call__(self, request):
-        with configure_scope() as scope:
-            distinct_id = get_distinct_id(request)
-            if distinct_id:
-                scope.set_tag(POSTHOG_ID_TAG, distinct_id)
-            response = self.get_response(request)
-        return response

posthog/sentry/posthog_integration.py

@@ -1,52 +0,0 @@
-from sentry_sdk._types import MYPY
-from sentry_sdk.hub import Hub
-from sentry_sdk.integrations import Integration
-from sentry_sdk.scope import add_global_event_processor
-from sentry_sdk.utils import Dsn
-
-import posthog
-from posthog.request import DEFAULT_HOST
-from posthog.sentry import POSTHOG_ID_TAG
-
-if MYPY:
-    from typing import Optional  # noqa: F401
-
-    from sentry_sdk._types import Event, Hint  # noqa: F401
-
-
-class PostHogIntegration(Integration):
-    identifier = "posthog-python"
-    organization = None  # The Sentry organization, used to send a direct link from PostHog to Sentry
-    project_id = None  # The Sentry project id, used to send a direct link from PostHog to Sentry
-    prefix = "https://sentry.io/organizations/"  # URL of a hosted sentry instance (default: https://sentry.io/organizations/)
-
-    @staticmethod
-    def setup_once():
-        @add_global_event_processor
-        def processor(event, hint):
-            # type: (Event, Optional[Hint]) -> Optional[Event]
-            if Hub.current.get_integration(PostHogIntegration) is not None:
-                if event.get("level") != "error":
-                    return event
-
-                if event.get("tags", {}).get(POSTHOG_ID_TAG):
-                    posthog_distinct_id = event["tags"][POSTHOG_ID_TAG]
-                    event["tags"]["PostHog URL"] = f"{posthog.host or DEFAULT_HOST}/person/{posthog_distinct_id}"
-
-                    properties = {
-                        "$sentry_event_id": event["event_id"],
-                        "$sentry_exception": event["exception"],
-                    }
-
-                    if PostHogIntegration.organization:
-                        project_id = PostHogIntegration.project_id or (
-                            not not Hub.current.client.dsn and Dsn(Hub.current.client.dsn).project_id
-                        )
-                        if project_id:
-                            properties["$sentry_url"] = (
-                                f"{PostHogIntegration.prefix}{PostHogIntegration.organization}/issues/?project={project_id}&query={event['event_id']}"
-                            )
-
-                    posthog.capture(posthog_distinct_id, "$exception", properties)
-
-            return event

posthog/test/ai/anthropic/test_anthropic.py

@@ -3,12 +3,23 @@ import time
 from unittest.mock import patch
 
 import pytest
-from anthropic.types import Message, Usage
 
-from posthog.ai.anthropic import Anthropic, AsyncAnthropic
+try:
+    from anthropic.types import Message, Usage
+
+    from posthog.ai.anthropic import Anthropic, AsyncAnthropic
+
+    ANTHROPIC_AVAILABLE = True
+except ImportError:
+    ANTHROPIC_AVAILABLE = False
 
 ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
 
+# Skip all tests if Anthropic is not available
+pytestmark = pytest.mark.skipif(
+    not ANTHROPIC_AVAILABLE, reason="Anthropic package is not available"
+)
+
 
 @pytest.fixture
 def mock_client():
@@ -55,8 +66,32 @@ def mock_anthropic_stream():
     return stream_generator()
 
 
+@pytest.fixture
+def mock_anthropic_response_with_cached_tokens():
+    # Create a mock Usage object with cached_tokens in input_tokens_details
+    usage = Usage(
+        input_tokens=20,
+        output_tokens=10,
+        cache_read_input_tokens=15,
+        cache_creation_input_tokens=2,
+    )
+
+    return Message(
+        id="msg_123",
+        type="message",
+        role="assistant",
+        content=[{"type": "text", "text": "Test response"}],
+        model="claude-3-opus-20240229",
+        usage=usage,
+        stop_reason="end_turn",
+        stop_sequence=None,
+    )
+
+
 def test_basic_completion(mock_client, mock_anthropic_response):
-    with patch("anthropic.resources.Messages.create", return_value=mock_anthropic_response):
+    with patch(
+        "anthropic.resources.Messages.create", return_value=mock_anthropic_response
+    ):
         client = Anthropic(api_key="test-key", posthog_client=mock_client)
         response = client.messages.create(
             model="claude-3-opus-20240229",
@@ -76,7 +111,9 @@ def test_basic_completion(mock_client, mock_anthropic_response):
         assert props["$ai_provider"] == "anthropic"
         assert props["$ai_model"] == "claude-3-opus-20240229"
         assert props["$ai_input"] == [{"role": "user", "content": "Hello"}]
-        assert props["$ai_output_choices"] == [{"role": "assistant", "content": "Test response"}]
+        assert props["$ai_output_choices"] == [
+            {"role": "assistant", "content": "Test response"}
+        ]
         assert props["$ai_input_tokens"] == 20
         assert props["$ai_output_tokens"] == 10
         assert props["$ai_http_status"] == 200
@@ -85,7 +122,9 @@ def test_basic_completion(mock_client, mock_anthropic_response):
 
 
 def test_streaming(mock_client, mock_anthropic_stream):
-    with patch("anthropic.resources.Messages.create", return_value=mock_anthropic_stream):
+    with patch(
+        "anthropic.resources.Messages.create", return_value=mock_anthropic_stream
+    ):
         client = Anthropic(api_key="test-key", posthog_client=mock_client)
         response = client.messages.create(
             model="claude-3-opus-20240229",
@@ -122,7 +161,9 @@ def test_streaming(mock_client, mock_anthropic_stream):
 
 
 def test_streaming_with_stream_endpoint(mock_client, mock_anthropic_stream):
-    with patch("anthropic.resources.Messages.create", return_value=mock_anthropic_stream):
+    with patch(
+        "anthropic.resources.Messages.create", return_value=mock_anthropic_stream
+    ):
         client = Anthropic(api_key="test-key", posthog_client=mock_client)
         response = client.messages.stream(
             model="claude-3-opus-20240229",
@@ -158,7 +199,9 @@ def test_streaming_with_stream_endpoint(mock_client, mock_anthropic_stream):
 
 
 def test_groups(mock_client, mock_anthropic_response):
-    with patch("anthropic.resources.Messages.create", return_value=mock_anthropic_response):
+    with patch(
+        "anthropic.resources.Messages.create", return_value=mock_anthropic_response
+    ):
         client = Anthropic(api_key="test-key", posthog_client=mock_client)
         response = client.messages.create(
             model="claude-3-opus-20240229",
@@ -175,7 +218,9 @@ def test_groups(mock_client, mock_anthropic_response):
 
 
 def test_privacy_mode_local(mock_client, mock_anthropic_response):
-    with patch("anthropic.resources.Messages.create", return_value=mock_anthropic_response):
+    with patch(
+        "anthropic.resources.Messages.create", return_value=mock_anthropic_response
+    ):
         client = Anthropic(api_key="test-key", posthog_client=mock_client)
         response = client.messages.create(
             model="claude-3-opus-20240229",
@@ -194,7 +239,9 @@ def test_privacy_mode_local(mock_client, mock_anthropic_response):
 
 
 def test_privacy_mode_global(mock_client, mock_anthropic_response):
-    with patch("anthropic.resources.Messages.create", return_value=mock_anthropic_response):
+    with patch(
+        "anthropic.resources.Messages.create", return_value=mock_anthropic_response
+    ):
         mock_client.privacy_mode = True
         client = Anthropic(api_key="test-key", posthog_client=mock_client)
         response = client.messages.create(
@@ -268,7 +315,9 @@ async def test_basic_async_integration(mock_client):
     assert call_args["event"] == "$ai_generation"
     assert props["$ai_provider"] == "anthropic"
     assert props["$ai_model"] == "claude-3-opus-20240229"
-    assert props["$ai_input"] == [{"role": "user", "content": "You must always answer with 'Bar'."}]
+    assert props["$ai_input"] == [
+        {"role": "user", "content": "You must always answer with 'Bar'."}
+    ]
     assert props["$ai_output_choices"][0]["role"] == "assistant"
     assert props["$ai_input_tokens"] == 16
     assert props["$ai_output_tokens"] == 1
@@ -278,7 +327,9 @@ async def test_basic_async_integration(mock_client):
 
 
 def test_streaming_system_prompt(mock_client, mock_anthropic_stream):
-    with patch("anthropic.resources.Messages.create", return_value=mock_anthropic_stream):
+    with patch(
+        "anthropic.resources.Messages.create", return_value=mock_anthropic_stream
+    ):
         client = Anthropic(api_key="test-key", posthog_client=mock_client)
         response = client.messages.create(
             model="claude-3-opus-20240229",
@@ -297,7 +348,10 @@ def test_streaming_system_prompt(mock_client, mock_anthropic_stream):
         call_args = mock_client.capture.call_args[1]
         props = call_args["properties"]
 
-        assert props["$ai_input"] == [{"role": "system", "content": "Foo"}, {"role": "user", "content": "Bar"}]
+        assert props["$ai_input"] == [
+            {"role": "system", "content": "Foo"},
+            {"role": "user", "content": "Bar"},
+        ]
 
 
 @pytest.mark.skipif(not ANTHROPIC_API_KEY, reason="ANTHROPIC_API_KEY is not set")
@@ -328,10 +382,15 @@ async def test_async_streaming_system_prompt(mock_client, mock_anthropic_stream)
 
 
 def test_error(mock_client, mock_anthropic_response):
-    with patch("anthropic.resources.Messages.create", side_effect=Exception("Test error")):
+    with patch(
+        "anthropic.resources.Messages.create", side_effect=Exception("Test error")
+    ):
         client = Anthropic(api_key="test-key", posthog_client=mock_client)
         with pytest.raises(Exception):
-            client.messages.create(model="claude-3-opus-20240229", messages=[{"role": "user", "content": "Hello"}])
+            client.messages.create(
+                model="claude-3-opus-20240229",
+                messages=[{"role": "user", "content": "Hello"}],
+            )
 
         assert mock_client.capture.call_count == 1
 
@@ -339,3 +398,39 @@ def test_error(mock_client, mock_anthropic_response):
         props = call_args["properties"]
         assert props["$ai_is_error"] is True
         assert props["$ai_error"] == "Test error"
+
+
+def test_cached_tokens(mock_client, mock_anthropic_response_with_cached_tokens):
+    with patch(
+        "anthropic.resources.Messages.create",
+        return_value=mock_anthropic_response_with_cached_tokens,
+    ):
+        client = Anthropic(api_key="test-key", posthog_client=mock_client)
+        response = client.messages.create(
+            model="claude-3-opus-20240229",
+            messages=[{"role": "user", "content": "Hello"}],
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+        )
+
+        assert response == mock_anthropic_response_with_cached_tokens
+        assert mock_client.capture.call_count == 1
+
+        call_args = mock_client.capture.call_args[1]
+        props = call_args["properties"]
+
+        assert call_args["distinct_id"] == "test-id"
+        assert call_args["event"] == "$ai_generation"
+        assert props["$ai_provider"] == "anthropic"
+        assert props["$ai_model"] == "claude-3-opus-20240229"
+        assert props["$ai_input"] == [{"role": "user", "content": "Hello"}]
+        assert props["$ai_output_choices"] == [
+            {"role": "assistant", "content": "Test response"}
+        ]
+        assert props["$ai_input_tokens"] == 20
+        assert props["$ai_output_tokens"] == 10
+        assert props["$ai_cache_read_input_tokens"] == 15
+        assert props["$ai_cache_creation_input_tokens"] == 2
+        assert props["$ai_http_status"] == 200
+        assert props["foo"] == "bar"
+        assert isinstance(props["$ai_latency"], float)

posthog/test/ai/gemini/test_gemini.py

@@ -0,0 +1,320 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+try:
+    from google import genai as google_genai
+
+    from posthog.ai.gemini import Client
+
+    GEMINI_AVAILABLE = True
+except ImportError:
+    GEMINI_AVAILABLE = False
+
+pytestmark = pytest.mark.skipif(
+    not GEMINI_AVAILABLE, reason="Google Gemini package is not available"
+)
+
+
+@pytest.fixture
+def mock_client():
+    with patch("posthog.client.Client") as mock_client:
+        mock_client.privacy_mode = False
+        yield mock_client
+
+
+@pytest.fixture
+def mock_gemini_response():
+    mock_response = MagicMock()
+    mock_response.text = "Test response from Gemini"
+
+    mock_usage = MagicMock()
+    mock_usage.prompt_token_count = 20
+    mock_usage.candidates_token_count = 10
+    mock_response.usage_metadata = mock_usage
+
+    mock_candidate = MagicMock()
+    mock_candidate.text = "Test response from Gemini"
+    mock_content = MagicMock()
+    mock_part = MagicMock()
+    mock_part.text = "Test response from Gemini"
+    mock_content.parts = [mock_part]
+    mock_candidate.content = mock_content
+    mock_response.candidates = [mock_candidate]
+
+    return mock_response
+
+
+@pytest.fixture
+def mock_google_genai_client():
+    """Mock for the new google-genai Client"""
+    with patch.object(google_genai, "Client") as mock_client_class:
+        mock_client_instance = MagicMock()
+        mock_models = MagicMock()
+        mock_client_instance.models = mock_models
+        mock_client_class.return_value = mock_client_instance
+        yield mock_client_instance
+
+
+def test_new_client_basic_generation(
+    mock_client, mock_google_genai_client, mock_gemini_response
+):
+    """Test the new Client/Models API structure"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    response = client.models.generate_content(
+        model="gemini-2.0-flash",
+        contents=["Tell me a fun fact about hedgehogs"],
+        posthog_distinct_id="test-id",
+        posthog_properties={"foo": "bar"},
+    )
+
+    assert response == mock_gemini_response
+    assert mock_client.capture.call_count == 1
+
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+
+    assert call_args["distinct_id"] == "test-id"
+    assert call_args["event"] == "$ai_generation"
+    assert props["$ai_provider"] == "gemini"
+    assert props["$ai_model"] == "gemini-2.0-flash"
+    assert props["$ai_input_tokens"] == 20
+    assert props["$ai_output_tokens"] == 10
+    assert props["foo"] == "bar"
+    assert "$ai_trace_id" in props
+    assert props["$ai_latency"] > 0
+
+
+def test_new_client_streaming_with_generate_content_stream(
+    mock_client, mock_google_genai_client
+):
+    """Test the new generate_content_stream method"""
+
+    def mock_streaming_response():
+        mock_chunk1 = MagicMock()
+        mock_chunk1.text = "Hello "
+        mock_usage1 = MagicMock()
+        mock_usage1.prompt_token_count = 10
+        mock_usage1.candidates_token_count = 5
+        mock_chunk1.usage_metadata = mock_usage1
+
+        mock_chunk2 = MagicMock()
+        mock_chunk2.text = "world!"
+        mock_usage2 = MagicMock()
+        mock_usage2.prompt_token_count = 10
+        mock_usage2.candidates_token_count = 10
+        mock_chunk2.usage_metadata = mock_usage2
+
+        yield mock_chunk1
+        yield mock_chunk2
+
+    # Mock the generate_content_stream method
+    mock_google_genai_client.models.generate_content_stream.return_value = (
+        mock_streaming_response()
+    )
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    response = client.models.generate_content_stream(
+        model="gemini-2.0-flash",
+        contents=["Write a short story"],
+        posthog_distinct_id="test-id",
+        posthog_properties={"feature": "streaming"},
+    )
+
+    chunks = list(response)
+    assert len(chunks) == 2
+    assert chunks[0].text == "Hello "
+    assert chunks[1].text == "world!"
+
+    # Check that the streaming event was captured
+    assert mock_client.capture.call_count == 1
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+
+    assert call_args["distinct_id"] == "test-id"
+    assert call_args["event"] == "$ai_generation"
+    assert props["$ai_provider"] == "gemini"
+    assert props["$ai_model"] == "gemini-2.0-flash"
+    assert props["$ai_input_tokens"] == 10
+    assert props["$ai_output_tokens"] == 10
+    assert props["feature"] == "streaming"
+    assert isinstance(props["$ai_latency"], float)
+
+
+def test_new_client_groups(mock_client, mock_google_genai_client, mock_gemini_response):
+    """Test groups functionality with new Client API"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    client.models.generate_content(
+        model="gemini-2.0-flash",
+        contents=["Hello"],
+        posthog_distinct_id="test-id",
+        posthog_groups={"company": "company_123"},
+    )
+
+    call_args = mock_client.capture.call_args[1]
+    assert call_args["groups"] == {"company": "company_123"}
+
+
+def test_new_client_privacy_mode_local(
+    mock_client, mock_google_genai_client, mock_gemini_response
+):
+    """Test local privacy mode with new Client API"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    client.models.generate_content(
+        model="gemini-2.0-flash",
+        contents=["Hello"],
+        posthog_distinct_id="test-id",
+        posthog_privacy_mode=True,
+    )
+
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+    assert props["$ai_input"] is None
+    assert props["$ai_output_choices"] is None
+
+
+def test_new_client_privacy_mode_global(
+    mock_client, mock_google_genai_client, mock_gemini_response
+):
+    """Test global privacy mode with new Client API"""
+    mock_client.privacy_mode = True
+
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    client.models.generate_content(
+        model="gemini-2.0-flash",
+        contents=["Hello"],
+        posthog_distinct_id="test-id",
+    )
+
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+    assert props["$ai_input"] is None
+    assert props["$ai_output_choices"] is None
+
+
+def test_new_client_different_input_formats(
+    mock_client, mock_google_genai_client, mock_gemini_response
+):
+    """Test different input formats with new Client API"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    # Test string input
+    client.models.generate_content(
+        model="gemini-2.0-flash", contents="Hello", posthog_distinct_id="test-id"
+    )
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+    assert props["$ai_input"] == [{"role": "user", "content": "Hello"}]
+
+    # Test list input
+    mock_client.capture.reset_mock()
+    mock_part = MagicMock()
+    mock_part.text = "List item"
+    client.models.generate_content(
+        model="gemini-2.0-flash", contents=[mock_part], posthog_distinct_id="test-id"
+    )
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+    assert props["$ai_input"] == [{"role": "user", "content": "List item"}]
+
+
+def test_new_client_model_parameters(
+    mock_client, mock_google_genai_client, mock_gemini_response
+):
+    """Test model parameters with new Client API"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    client.models.generate_content(
+        model="gemini-2.0-flash",
+        contents=["Hello"],
+        posthog_distinct_id="test-id",
+        temperature=0.7,
+        max_tokens=100,
+    )
+
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+    assert props["$ai_model_parameters"]["temperature"] == 0.7
+    assert props["$ai_model_parameters"]["max_tokens"] == 100
+
+
+def test_new_client_default_settings(
+    mock_client, mock_google_genai_client, mock_gemini_response
+):
+    """Test client with default PostHog settings"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    client = Client(
+        api_key="test-key",
+        posthog_client=mock_client,
+        posthog_distinct_id="default_user",
+        posthog_properties={"team": "ai"},
+        posthog_privacy_mode=False,
+        posthog_groups={"company": "acme_corp"},
+    )
+
+    # Call without overriding defaults
+    client.models.generate_content(model="gemini-2.0-flash", contents=["Hello"])
+
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+
+    assert call_args["distinct_id"] == "default_user"
+    assert call_args["groups"] == {"company": "acme_corp"}
+    assert props["team"] == "ai"
+
+
+def test_new_client_override_defaults(
+    mock_client, mock_google_genai_client, mock_gemini_response
+):
+    """Test overriding client defaults per call"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    client = Client(
+        api_key="test-key",
+        posthog_client=mock_client,
+        posthog_distinct_id="default_user",
+        posthog_properties={"team": "ai"},
+        posthog_privacy_mode=False,
+        posthog_groups={"company": "acme_corp"},
+    )
+
+    # Override defaults in call
+    client.models.generate_content(
+        model="gemini-2.0-flash",
+        contents=["Hello"],
+        posthog_distinct_id="specific_user",
+        posthog_properties={"feature": "chat", "urgent": True},
+        posthog_privacy_mode=True,
+        posthog_groups={"organization": "special_org"},
+    )
+
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+
+    # Check overrides
+    assert call_args["distinct_id"] == "specific_user"
+    assert call_args["groups"] == {"organization": "special_org"}
+    assert props["$ai_input"] is None  # privacy mode was overridden
+
+    # Check merged properties (defaults + call-specific)
+    assert props["team"] == "ai"  # from defaults
+    assert props["feature"] == "chat"  # from call
+    assert props["urgent"] is True  # from call

posthog/test/ai/langchain/test_callbacks.py

@@ -8,19 +8,44 @@ from typing import List, Literal, Optional, TypedDict, Union
 from unittest.mock import patch
 
 import pytest
-from langchain_anthropic.chat_models import ChatAnthropic
-from langchain_community.chat_models.fake import FakeMessagesListChatModel
-from langchain_community.llms.fake import FakeListLLM, FakeStreamingListLLM
-from langchain_core.messages import AIMessage, HumanMessage
-from langchain_core.prompts import ChatPromptTemplate
-from langchain_core.runnables import RunnableLambda
-from langchain_core.tools import tool
-from langchain_openai.chat_models import ChatOpenAI
-from langgraph.graph.state import END, START, StateGraph
-from langgraph.prebuilt import create_react_agent
 
-from posthog.ai.langchain import CallbackHandler
-from posthog.ai.langchain.callbacks import GenerationMetadata, SpanMetadata
+try:
+    from langchain_anthropic.chat_models import ChatAnthropic
+    from langchain_community.chat_models.fake import FakeMessagesListChatModel
+    from langchain_community.llms.fake import FakeListLLM, FakeStreamingListLLM
+    from langchain_core.messages import AIMessage, HumanMessage
+    from langchain_core.prompts import ChatPromptTemplate
+    from langchain_core.runnables import RunnableLambda
+    from langchain_core.tools import tool
+    from langchain_openai.chat_models import ChatOpenAI
+    from langgraph.graph.state import END, START, StateGraph
+    from langgraph.prebuilt import create_react_agent
+
+    from posthog.ai.langchain import CallbackHandler
+    from posthog.ai.langchain.callbacks import GenerationMetadata, SpanMetadata
+
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+
+    class FakeListLLM:
+        pass
+
+    class FakeStreamingListLLM:
+        pass
+
+    class HumanMessage:
+        pass
+
+    class AIMessage:
+        pass
+
+    LANGCHAIN_AVAILABLE = False
+
+
+# Skip all tests if LangChain is not available
+pytestmark = pytest.mark.skipif(
+    not LANGCHAIN_AVAILABLE, reason="LangChain package is not available"
+)
 
 OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
 ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
@@ -229,7 +254,9 @@ async def test_async_basic_chat_chain(mock_client, stream):
     callbacks = [CallbackHandler(mock_client)]
     chain = prompt | model
     if stream:
-        result = [m async for m in chain.astream({}, config={"callbacks": callbacks})][0]
+        result = [m async for m in chain.astream({}, config={"callbacks": callbacks})][
+            0
+        ]
     else:
         result = await chain.ainvoke({}, config={"callbacks": callbacks})
     assert result.content == "The Los Angeles Dodgers won the World Series in 2020."
@@ -293,10 +320,17 @@ def test_basic_llm_chain(mock_client, Model, stream):
 
     if stream:
         result = "".join(
-            [m for m in model.stream("Who won the world series in 2020?", config={"callbacks": callbacks})]
+            [
+                m
+                for m in model.stream(
+                    "Who won the world series in 2020?", config={"callbacks": callbacks}
+                )
+            ]
         )
     else:
-        result = model.invoke("Who won the world series in 2020?", config={"callbacks": callbacks})
+        result = model.invoke(
+            "Who won the world series in 2020?", config={"callbacks": callbacks}
+        )
     assert result == "The Los Angeles Dodgers won the World Series in 2020."
 
     assert mock_client.capture.call_count == 1
@@ -308,7 +342,9 @@ def test_basic_llm_chain(mock_client, Model, stream):
     assert "$ai_model" in props
     assert "$ai_provider" in props
     assert props["$ai_input"] == ["Who won the world series in 2020?"]
-    assert props["$ai_output_choices"] == ["The Los Angeles Dodgers won the World Series in 2020."]
+    assert props["$ai_output_choices"] == [
+        "The Los Angeles Dodgers won the World Series in 2020."
+    ]
     assert props["$ai_http_status"] == 200
     assert props["$ai_trace_id"] is not None
     assert isinstance(props["$ai_latency"], float)
@@ -329,10 +365,17 @@ async def test_async_basic_llm_chain(mock_client, Model, stream):
 
     if stream:
         result = "".join(
-            [m async for m in model.astream("Who won the world series in 2020?", config={"callbacks": callbacks})]
+            [
+                m
+                async for m in model.astream(
+                    "Who won the world series in 2020?", config={"callbacks": callbacks}
+                )
+            ]
         )
     else:
-        result = await model.ainvoke("Who won the world series in 2020?", config={"callbacks": callbacks})
+        result = await model.ainvoke(
+            "Who won the world series in 2020?", config={"callbacks": callbacks}
+        )
     assert result == "The Los Angeles Dodgers won the World Series in 2020."
 
     assert mock_client.capture.call_count == 1
@@ -344,7 +387,9 @@ async def test_async_basic_llm_chain(mock_client, Model, stream):
     assert "$ai_model" in props
     assert "$ai_provider" in props
     assert props["$ai_input"] == ["Who won the world series in 2020?"]
-    assert props["$ai_output_choices"] == ["The Los Angeles Dodgers won the World Series in 2020."]
+    assert props["$ai_output_choices"] == [
+        "The Los Angeles Dodgers won the World Series in 2020."
+    ]
     assert props["$ai_http_status"] == 200
     assert props["$ai_trace_id"] is not None
     assert isinstance(props["$ai_latency"], float)
@@ -395,8 +440,12 @@ def test_trace_id_and_inputs_for_multiple_chains(mock_client):
     assert "distinct_id" in first_generation_args
     assert "$ai_model" in first_generation_props
     assert "$ai_provider" in first_generation_props
-    assert first_generation_props["$ai_input"] == [{"role": "user", "content": "Foo bar"}]
-    assert first_generation_props["$ai_output_choices"] == [{"role": "assistant", "content": "Bar"}]
+    assert first_generation_props["$ai_input"] == [
+        {"role": "user", "content": "Foo bar"}
+    ]
+    assert first_generation_props["$ai_output_choices"] == [
+        {"role": "assistant", "content": "Bar"}
+    ]
     assert first_generation_props["$ai_http_status"] == 200
     assert isinstance(first_generation_props["$ai_latency"], float)
     assert "$ai_span_id" in first_generation_props
@@ -416,8 +465,12 @@ def test_trace_id_and_inputs_for_multiple_chains(mock_client):
     assert "distinct_id" in second_generation_args
     assert "$ai_model" in second_generation_props
     assert "$ai_provider" in second_generation_props
-    assert second_generation_props["$ai_input"] == [{"role": "assistant", "content": "Bar"}]
-    assert second_generation_props["$ai_output_choices"] == [{"role": "assistant", "content": "Bar"}]
+    assert second_generation_props["$ai_input"] == [
+        {"role": "assistant", "content": "Bar"}
+    ]
+    assert second_generation_props["$ai_output_choices"] == [
+        {"role": "assistant", "content": "Bar"}
+    ]
     assert second_generation_props["$ai_http_status"] == 200
     assert second_generation_props["$ai_trace_id"] is not None
     assert isinstance(second_generation_props["$ai_latency"], float)
@@ -452,7 +505,9 @@ def test_personless_mode(mock_client):
     assert trace_args["properties"]["$process_person_profile"] is False
 
     id = uuid.uuid4()
-    chain.invoke({}, config={"callbacks": [CallbackHandler(mock_client, distinct_id=id)]})
+    chain.invoke(
+        {}, config={"callbacks": [CallbackHandler(mock_client, distinct_id=id)]}
+    )
     assert mock_client.capture.call_count == 6
     span_args = mock_client.capture.call_args_list[3][1]
     generation_args = mock_client.capture.call_args_list[4][1]
@@ -492,7 +547,9 @@ def test_personless_mode_exception(mock_client):
 
     id = uuid.uuid4()
     with pytest.raises(Exception):
-        chain.invoke({}, config={"callbacks": [CallbackHandler(mock_client, distinct_id=id)]})
+        chain.invoke(
+            {}, config={"callbacks": [CallbackHandler(mock_client, distinct_id=id)]}
+        )
     assert mock_client.capture.call_count == 6
     span_args = mock_client.capture.call_args_list[3][1]
     generation_args = mock_client.capture.call_args_list[4][1]
@@ -551,7 +608,9 @@ def test_metadata(mock_client):
     assert generation_call_props["$ai_trace_id"] == "test-trace-id"
     assert generation_call_props["foo"] == "bar"
     assert generation_call_props["$ai_input"] == [{"role": "user", "content": "Foo"}]
-    assert generation_call_props["$ai_output_choices"] == [{"role": "assistant", "content": "Bar"}]
+    assert generation_call_props["$ai_output_choices"] == [
+        {"role": "assistant", "content": "Bar"}
+    ]
     assert generation_call_props["$ai_http_status"] == 200
     assert isinstance(generation_call_props["$ai_latency"], float)
 
@@ -618,88 +677,66 @@ def test_graph_state(mock_client):
     assert isinstance(result["messages"][2], AIMessage)
     assert result["messages"][2].content == "It's a type of greeble."
 
-    assert mock_client.capture.call_count == 11
+    assert mock_client.capture.call_count == 6
     calls = [call[1] for call in mock_client.capture.call_args_list]
 
-    trace_args = calls[10]
-    trace_props = calls[10]["properties"]
+    # The trace event is captured at the end
+    trace_args = calls[-1]
+    trace_props = calls[-1]["properties"]
 
     # Events are captured in the reverse order.
     # Check all trace_ids
     for call in calls:
         assert call["properties"]["$ai_trace_id"] == trace_props["$ai_trace_id"]
 
-    # First span, write the state
-    assert calls[0]["event"] == "$ai_span"
-    assert calls[0]["properties"]["$ai_parent_id"] == calls[2]["properties"]["$ai_span_id"]
-    assert "$ai_span_id" in calls[0]["properties"]
-    assert calls[0]["properties"]["$ai_input_state"] == initial_state
-    assert calls[0]["properties"]["$ai_output_state"] == initial_state
-
-    # Second span, set the START node
-    assert calls[1]["event"] == "$ai_span"
-    assert calls[1]["properties"]["$ai_parent_id"] == calls[2]["properties"]["$ai_span_id"]
-    assert "$ai_span_id" in calls[1]["properties"]
-    assert calls[1]["properties"]["$ai_input_state"] == initial_state
-    assert calls[1]["properties"]["$ai_output_state"] == initial_state
-
-    # Third span, finish initialization
-    assert calls[2]["event"] == "$ai_span"
-    assert "$ai_span_id" in calls[2]["properties"]
-    assert calls[2]["properties"]["$ai_span_name"] == START
-    assert calls[2]["properties"]["$ai_parent_id"] == trace_props["$ai_trace_id"]
-    assert calls[2]["properties"]["$ai_input_state"] == initial_state
-    assert calls[2]["properties"]["$ai_output_state"] == initial_state
-
-    # Fourth span, save the value of fake_plain during its execution
+    # 1. Span, finish initialization
     second_state = {
-        "messages": [HumanMessage(content="What's a bar?"), AIMessage(content="Let's explore bar.")],
+        "messages": [
+            HumanMessage(content="What's a bar?"),
+            AIMessage(content="Let's explore bar."),
+        ],
         "xyz": "abc",
     }
+
+    # 1. Span - the fake_plain node, which doesn't do anything
+    assert calls[0]["event"] == "$ai_span"
+    assert calls[0]["properties"]["$ai_parent_id"] == trace_props["$ai_trace_id"]
+    assert "$ai_span_id" in calls[0]["properties"]
+    assert calls[0]["properties"]["$ai_span_name"] == "fake_plain"
+    assert calls[0]["properties"]["$ai_input_state"] == initial_state
+    assert calls[0]["properties"]["$ai_output_state"] == second_state
+
+    # 2. Span - the ChatPromptTemplate within fake_llm's FakeMessagesListChatModel
+    assert calls[1]["event"] == "$ai_span"
+    assert (
+        calls[1]["properties"]["$ai_parent_id"] == calls[3]["properties"]["$ai_span_id"]
+    )
+    assert "$ai_span_id" in calls[1]["properties"]
+    assert calls[1]["properties"]["$ai_span_name"] == "ChatPromptTemplate"
+
+    # 3. Generation - the FakeMessagesListChatModel within fake_llm's RunnableSequence
+    assert calls[2]["event"] == "$ai_generation"
+    assert (
+        calls[2]["properties"]["$ai_parent_id"] == calls[3]["properties"]["$ai_span_id"]
+    )
+    assert "$ai_span_id" in calls[2]["properties"]
+    assert calls[2]["properties"]["$ai_span_name"] == "FakeMessagesListChatModel"
+
+    # 4. Span - RunnableSequence within fake_llm
     assert calls[3]["event"] == "$ai_span"
-    assert calls[3]["properties"]["$ai_parent_id"] == calls[4]["properties"]["$ai_span_id"]
+    assert (
+        calls[3]["properties"]["$ai_parent_id"] == calls[4]["properties"]["$ai_span_id"]
+    )
     assert "$ai_span_id" in calls[3]["properties"]
-    assert calls[3]["properties"]["$ai_input_state"] == second_state
-    assert calls[3]["properties"]["$ai_output_state"] == second_state
+    assert calls[3]["properties"]["$ai_span_name"] == "RunnableSequence"
 
-    # Fifth span, run the fake_plain node
+    # 5. Span - the fake_llm node
     assert calls[4]["event"] == "$ai_span"
-    assert "$ai_span_id" in calls[4]["properties"]
-    assert calls[4]["properties"]["$ai_span_name"] == "fake_plain"
     assert calls[4]["properties"]["$ai_parent_id"] == trace_props["$ai_trace_id"]
-    assert calls[4]["properties"]["$ai_input_state"] == initial_state
-    assert calls[4]["properties"]["$ai_output_state"] == second_state
+    assert "$ai_span_id" in calls[4]["properties"]
+    assert calls[4]["properties"]["$ai_span_name"] == "fake_llm"
 
-    # Sixth span, chat prompt template
-    assert calls[5]["event"] == "$ai_span"
-    assert calls[5]["properties"]["$ai_parent_id"] == calls[7]["properties"]["$ai_span_id"]
-    assert "$ai_span_id" in calls[5]["properties"]
-    assert calls[5]["properties"]["$ai_span_name"] == "ChatPromptTemplate"
-
-    # 7. Generation, fake_llm
-    assert calls[6]["event"] == "$ai_generation"
-    assert calls[6]["properties"]["$ai_parent_id"] == calls[7]["properties"]["$ai_span_id"]
-    assert "$ai_span_id" in calls[6]["properties"]
-    assert calls[6]["properties"]["$ai_span_name"] == "FakeMessagesListChatModel"
-
-    # 8. Span, RunnableSequence
-    assert calls[7]["event"] == "$ai_span"
-    assert calls[7]["properties"]["$ai_parent_id"] == calls[9]["properties"]["$ai_span_id"]
-    assert "$ai_span_id" in calls[7]["properties"]
-    assert calls[7]["properties"]["$ai_span_name"] == "RunnableSequence"
-
-    # 9. Span, fake_llm write
-    assert calls[8]["event"] == "$ai_span"
-    assert calls[8]["properties"]["$ai_parent_id"] == calls[9]["properties"]["$ai_span_id"]
-    assert "$ai_span_id" in calls[8]["properties"]
-
-    # 10. Span, fake_llm node
-    assert calls[9]["event"] == "$ai_span"
-    assert calls[9]["properties"]["$ai_parent_id"] == trace_props["$ai_trace_id"]
-    assert "$ai_span_id" in calls[9]["properties"]
-    assert calls[9]["properties"]["$ai_span_name"] == "fake_llm"
-
-    # 11. Trace
+    # 6. Trace
     assert trace_args["event"] == "$ai_trace"
     assert trace_props["$ai_span_name"] == "LangGraph"
 
@@ -713,9 +750,14 @@ def test_graph_state(mock_client):
     assert isinstance(trace_props["$ai_output_state"]["messages"][0], HumanMessage)
     assert trace_props["$ai_output_state"]["messages"][0].content == "What's a bar?"
     assert isinstance(trace_props["$ai_output_state"]["messages"][1], AIMessage)
-    assert trace_props["$ai_output_state"]["messages"][1].content == "Let's explore bar."
+    assert (
+        trace_props["$ai_output_state"]["messages"][1].content == "Let's explore bar."
+    )
     assert isinstance(trace_props["$ai_output_state"]["messages"][2], AIMessage)
-    assert trace_props["$ai_output_state"]["messages"][2].content == "It's a type of greeble."
+    assert (
+        trace_props["$ai_output_state"]["messages"][2].content
+        == "It's a type of greeble."
+    )
     assert trace_args["properties"]["$ai_output_state"]["xyz"] == "abc"
 
 
@@ -743,7 +785,9 @@ def test_callbacks_logic(mock_client):
         assert len(callbacks._parent_tree.items()) == 1
         return [m]
 
-    (chain | RunnableLambda(assert_intermediary_run) | model).invoke({}, config={"callbacks": [callbacks]})
+    (chain | RunnableLambda(assert_intermediary_run) | model).invoke(
+        {}, config={"callbacks": [callbacks]}
+    )
     assert callbacks._runs == {}
     assert callbacks._parent_tree == {}
 
@@ -836,10 +880,16 @@ def test_openai_chain(mock_client):
         {"role": "system", "content": 'You must always answer with "Bar".'},
         {"role": "user", "content": "Foo"},
     ]
-    assert gen_props["$ai_output_choices"] == [{"role": "assistant", "content": "Bar", "refusal": None}]
+    assert gen_props["$ai_output_choices"] == [
+        {"role": "assistant", "content": "Bar", "refusal": None}
+    ]
     assert gen_props["$ai_http_status"] == 200
     assert isinstance(gen_props["$ai_latency"], float)
-    assert min(approximate_latency - 1, 0) <= math.floor(gen_props["$ai_latency"]) <= approximate_latency
+    assert (
+        min(approximate_latency - 1, 0)
+        <= math.floor(gen_props["$ai_latency"])
+        <= approximate_latency
+    )
     assert gen_props["$ai_input_tokens"] == 20
     assert gen_props["$ai_output_tokens"] == 1
 
@@ -1113,7 +1163,11 @@ def test_anthropic_chain(mock_client):
     assert gen_props["$ai_output_choices"] == [{"role": "assistant", "content": "Bar"}]
     assert gen_props["$ai_http_status"] == 200
     assert isinstance(gen_props["$ai_latency"], float)
-    assert min(approximate_latency - 1, 0) <= math.floor(gen_props["$ai_latency"]) <= approximate_latency
+    assert (
+        min(approximate_latency - 1, 0)
+        <= math.floor(gen_props["$ai_latency"])
+        <= approximate_latency
+    )
     assert gen_props["$ai_input_tokens"] == 17
     assert gen_props["$ai_output_tokens"] == 1
 
@@ -1168,6 +1222,61 @@ async def test_async_anthropic_streaming(mock_client):
     assert isinstance(trace_props["$ai_output_state"], AIMessage)
 
 
+def test_metadata_tools(mock_client):
+    callbacks = CallbackHandler(mock_client)
+    run_id = uuid.uuid4()
+    tools = [
+        [
+            {
+                "type": "function",
+                "function": {
+                    "name": "foo",
+                    "description": "The foo.",
+                    "parameters": {
+                        "properties": {
+                            "bar": {
+                                "description": "The bar of foo.",
+                                "type": "string",
+                            },
+                        },
+                        "required": ["query_description", "query_kind"],
+                        "type": "object",
+                        "additionalProperties": False,
+                    },
+                    "strict": True,
+                },
+            }
+        ]
+    ]
+
+    with patch("time.time", return_value=1234567890):
+        callbacks._set_llm_metadata(
+            {"kwargs": {"openai_api_base": "https://us.posthog.com"}},
+            run_id,
+            messages=[{"role": "user", "content": "What's the weather like in SF?"}],
+            invocation_params={"temperature": 0.5, "tools": tools},
+            metadata={"ls_model_name": "hog-mini", "ls_provider": "posthog"},
+            name="test",
+        )
+    expected = GenerationMetadata(
+        model="hog-mini",
+        input=[{"role": "user", "content": "What's the weather like in SF?"}],
+        start_time=1234567890,
+        model_params={"temperature": 0.5},
+        provider="posthog",
+        base_url="https://us.posthog.com",
+        name="test",
+        tools=tools,
+        end_time=None,
+    )
+    assert callbacks._runs[run_id] == expected
+    with patch("time.time", return_value=1234567891):
+        run = callbacks._pop_run_metadata(run_id)
+    expected.end_time = 1234567891
+    assert run == expected
+    assert callbacks._runs == {}
+
+
 def test_tool_calls(mock_client):
     prompt = ChatPromptTemplate.from_messages([("user", "Foo")])
     model = FakeMessagesListChatModel(
@@ -1205,7 +1314,10 @@ def test_tool_calls(mock_client):
             },
         }
     ]
-    assert "additional_kwargs" not in generation_call["properties"]["$ai_output_choices"][0]
+    assert (
+        "additional_kwargs"
+        not in generation_call["properties"]["$ai_output_choices"][0]
+    )
 
 
 async def test_async_traces(mock_client):
@@ -1227,7 +1339,9 @@ async def test_async_traces(mock_client):
     approximate_latency = math.floor(time.time() - start_time)
     assert mock_client.capture.call_count == 4
 
-    first_call, second_call, third_call, fourth_call = mock_client.capture.call_args_list
+    first_call, second_call, third_call, fourth_call = (
+        mock_client.capture.call_args_list
+    )
     assert first_call[1]["event"] == "$ai_span"
     assert second_call[1]["event"] == "$ai_generation"
     assert third_call[1]["event"] == "$ai_trace"
@@ -1235,7 +1349,9 @@ async def test_async_traces(mock_client):
     assert fourth_call[1]["event"] == "$ai_trace"
     assert fourth_call[1]["properties"]["$ai_span_name"] == "sleep"
     assert (
-        min(approximate_latency - 1, 0) <= math.floor(third_call[1]["properties"]["$ai_latency"]) <= approximate_latency
+        min(approximate_latency - 1, 0)
+        <= math.floor(third_call[1]["properties"]["$ai_latency"])
+        <= approximate_latency
     )
 
 
@@ -1257,14 +1373,16 @@ def test_langgraph_agent(mock_client):
     model = ChatOpenAI(api_key=OPENAI_API_KEY, model="gpt-4o-mini", temperature=0)
     graph = create_react_agent(model, tools=tools)
     inputs = {"messages": [("user", "what is the weather in sf")]}
-    cb = CallbackHandler(mock_client, trace_id="test-trace-id", distinct_id="test-distinct-id")
+    cb = CallbackHandler(
+        mock_client, trace_id="test-trace-id", distinct_id="test-distinct-id"
+    )
     graph.invoke(inputs, config={"callbacks": [cb]})
     calls = [call[1] for call in mock_client.capture.call_args_list]
-    assert len(calls) == 21
+    assert len(calls) == 15
     for call in calls:
         assert call["properties"]["$ai_trace_id"] == "test-trace-id"
     assert len([call for call in calls if call["event"] == "$ai_generation"]) == 2
-    assert len([call for call in calls if call["event"] == "$ai_span"]) == 18
+    assert len([call for call in calls if call["event"] == "$ai_span"]) == 12
     assert len([call for call in calls if call["event"] == "$ai_trace"]) == 1
 
 
@@ -1277,7 +1395,9 @@ def test_span_set_parent_ids(mock_client, trace_id):
         ]
     )
     model = FakeMessagesListChatModel(
-        responses=[AIMessage(content="The Los Angeles Dodgers won the World Series in 2020.")]
+        responses=[
+            AIMessage(content="The Los Angeles Dodgers won the World Series in 2020.")
+        ]
     )
     callbacks = [CallbackHandler(mock_client, trace_id=trace_id)]
     chain = prompt | model
@@ -1286,10 +1406,16 @@ def test_span_set_parent_ids(mock_client, trace_id):
     assert mock_client.capture.call_count == 3
 
     span_props = mock_client.capture.call_args_list[0][1]
-    assert span_props["properties"]["$ai_trace_id"] == span_props["properties"]["$ai_parent_id"]
+    assert (
+        span_props["properties"]["$ai_trace_id"]
+        == span_props["properties"]["$ai_parent_id"]
+    )
 
     generation_props = mock_client.capture.call_args_list[1][1]
-    assert generation_props["properties"]["$ai_trace_id"] == generation_props["properties"]["$ai_parent_id"]
+    assert (
+        generation_props["properties"]["$ai_trace_id"]
+        == generation_props["properties"]["$ai_parent_id"]
+    )
 
 
 @pytest.mark.parametrize("trace_id", ["test-trace-id", None])
@@ -1309,9 +1435,13 @@ def test_span_set_parent_ids_for_third_level_run(mock_client, trace_id):
 
     assert mock_client.capture.call_count == 3
 
-    span2, span1, trace = [call[1]["properties"] for call in mock_client.capture.call_args_list]
-    assert span2["$ai_parent_id"] == span1["$ai_span_id"]
-    assert span1["$ai_parent_id"] == trace["$ai_trace_id"]
+    calls = mock_client.capture.call_args_list
+    span_props_2 = calls[0][1]["properties"]
+    span_props_1 = calls[1][1]["properties"]
+    trace_props = calls[2][1]["properties"]
+
+    assert span_props_2["$ai_parent_id"] == span_props_1["$ai_span_id"]
+    assert span_props_1["$ai_parent_id"] == trace_props["$ai_trace_id"]
 
 
 def test_captures_error_with_details_in_span(mock_client):
@@ -1326,7 +1456,10 @@ def test_captures_error_with_details_in_span(mock_client):
         pass
 
     assert mock_client.capture.call_count == 2
-    assert mock_client.capture.call_args_list[1][1]["properties"]["$ai_error"] == "ValueError: test"
+    assert (
+        mock_client.capture.call_args_list[1][1]["properties"]["$ai_error"]
+        == "ValueError: test"
+    )
     assert mock_client.capture.call_args_list[1][1]["properties"]["$ai_is_error"]
 
 
@@ -1342,5 +1475,281 @@ def test_captures_error_without_details_in_span(mock_client):
         pass
 
     assert mock_client.capture.call_count == 2
-    assert mock_client.capture.call_args_list[1][1]["properties"]["$ai_error"] == "ValueError"
+    assert (
+        mock_client.capture.call_args_list[1][1]["properties"]["$ai_error"]
+        == "ValueError"
+    )
     assert mock_client.capture.call_args_list[1][1]["properties"]["$ai_is_error"]
+
+
+def test_openai_reasoning_tokens(mock_client):
+    """Test that OpenAI reasoning tokens are captured correctly."""
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Think step by step about this problem")]
+    )
+
+    # Mock response with reasoning tokens in output_token_details
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Let me think through this step by step...",
+                usage_metadata={
+                    "input_tokens": 10,
+                    "output_tokens": 25,
+                    "total_tokens": 35,
+                    "output_token_details": {"reasoning": 15},  # 15 reasoning tokens
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Let me think through this step by step..."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 10
+    assert generation_props["$ai_output_tokens"] == 25
+    assert generation_props["$ai_reasoning_tokens"] == 15
+
+
+def test_anthropic_cache_write_and_read_tokens(mock_client):
+    """Test that Anthropic cache creation and read tokens are captured correctly."""
+    prompt = ChatPromptTemplate.from_messages([("user", "Analyze this large document")])
+
+    # First call with cache creation
+    model_write = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="I've analyzed the document and cached the context.",
+                usage_metadata={
+                    "total_tokens": 1050,
+                    "input_tokens": 1000,
+                    "output_tokens": 50,
+                    "cache_creation_input_tokens": 800,  # Anthropic cache write
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model_write
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "I've analyzed the document and cached the context."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 1000
+    assert generation_props["$ai_output_tokens"] == 50
+    assert generation_props["$ai_cache_creation_input_tokens"] == 800
+    assert generation_props["$ai_cache_read_input_tokens"] == 0
+    assert generation_props["$ai_reasoning_tokens"] == 0
+
+    # Reset mock for second call
+    mock_client.reset_mock()
+
+    # Second call with cache read
+    model_read = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Using cached analysis to provide quick response.",
+                usage_metadata={
+                    "input_tokens": 200,
+                    "output_tokens": 30,
+                    "total_tokens": 1030,
+                    "cache_read_input_tokens": 800,  # Anthropic cache read
+                },
+            )
+        ]
+    )
+
+    chain = prompt | model_read
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Using cached analysis to provide quick response."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 200
+    assert generation_props["$ai_output_tokens"] == 30
+    assert generation_props["$ai_cache_creation_input_tokens"] == 0
+    assert generation_props["$ai_cache_read_input_tokens"] == 800
+    assert generation_props["$ai_reasoning_tokens"] == 0
+
+
+def test_openai_cache_read_tokens(mock_client):
+    """Test that OpenAI cache read tokens are captured correctly."""
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Use the cached prompt for this request")]
+    )
+
+    # Mock response with cache read tokens in input_token_details
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Response using cached prompt context.",
+                usage_metadata={
+                    "input_tokens": 150,
+                    "output_tokens": 40,
+                    "total_tokens": 190,
+                    "input_token_details": {
+                        "cache_read": 100,  # 100 tokens read from cache
+                        "cache_creation": 0,
+                    },
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Response using cached prompt context."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 150
+    assert generation_props["$ai_output_tokens"] == 40
+    assert generation_props["$ai_cache_read_input_tokens"] == 100
+    assert generation_props["$ai_cache_creation_input_tokens"] == 0
+    assert generation_props["$ai_reasoning_tokens"] == 0
+
+
+def test_openai_cache_creation_tokens(mock_client):
+    """Test that OpenAI cache creation tokens are captured correctly."""
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Create a cache for this large prompt context")]
+    )
+
+    # Mock response with cache creation tokens in input_token_details
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Created cache for the prompt context.",
+                usage_metadata={
+                    "input_tokens": 2000,
+                    "output_tokens": 25,
+                    "total_tokens": 2025,
+                    "input_token_details": {
+                        "cache_creation": 1500,  # 1500 tokens written to cache
+                        "cache_read": 0,
+                    },
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Created cache for the prompt context."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 2000
+    assert generation_props["$ai_output_tokens"] == 25
+    assert generation_props["$ai_cache_creation_input_tokens"] == 1500
+    assert generation_props["$ai_cache_read_input_tokens"] == 0
+    assert generation_props["$ai_reasoning_tokens"] == 0
+
+
+def test_combined_reasoning_and_cache_tokens(mock_client):
+    """Test that both reasoning tokens and cache tokens can be captured together."""
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Think through this cached problem")]
+    )
+
+    # Mock response with both reasoning and cache tokens
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Let me reason through this using cached context...",
+                usage_metadata={
+                    "input_tokens": 500,
+                    "output_tokens": 100,
+                    "total_tokens": 600,
+                    "input_token_details": {"cache_read": 300, "cache_creation": 0},
+                    "output_token_details": {"reasoning": 60},  # 60 reasoning tokens
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Let me reason through this using cached context..."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 500
+    assert generation_props["$ai_output_tokens"] == 100
+    assert generation_props["$ai_cache_read_input_tokens"] == 300
+    assert generation_props["$ai_cache_creation_input_tokens"] == 0
+    assert generation_props["$ai_reasoning_tokens"] == 60
+
+
+@pytest.mark.skipif(not OPENAI_API_KEY, reason="OPENAI_API_KEY is not set")
+def test_openai_reasoning_tokens(mock_client):
+    model = ChatOpenAI(
+        api_key=OPENAI_API_KEY, model="o4-mini", max_completion_tokens=10
+    )
+    cb = CallbackHandler(
+        mock_client, trace_id="test-trace-id", distinct_id="test-distinct-id"
+    )
+    model.invoke("what is the weather in sf", config={"callbacks": [cb]})
+    call = mock_client.capture.call_args_list[0][1]
+    assert call["properties"]["$ai_reasoning_tokens"] is not None
+    assert call["properties"]["$ai_input_tokens"] is not None
+    assert call["properties"]["$ai_output_tokens"] is not None
+
+
+def test_callback_handler_without_client():
+    """Test that CallbackHandler works properly when no PostHog client is passed."""
+    with patch("posthog.ai.langchain.callbacks.setup") as mock_setup:
+        mock_client = mock_setup.return_value
+
+        callbacks = CallbackHandler()
+
+        # Verify that setup() was called
+        mock_setup.assert_called_once()
+
+        # Verify that the client was set to the result of setup()
+        assert callbacks._ph_client == mock_client
+
+        # Test that the callback handler works with a simple chain
+        prompt = ChatPromptTemplate.from_messages([("user", "Foo")])
+        model = FakeMessagesListChatModel(responses=[AIMessage(content="Bar")])
+        chain = prompt | model
+
+        # This should work and call the mock client
+        result = chain.invoke({}, config={"callbacks": [callbacks]})
+        assert result.content == "Bar"
+
+        # Verify that the mock client was used for capturing events
+        assert mock_client.capture.call_count == 3

posthog/test/ai/openai/test_openai.py

@@ -1,14 +1,48 @@
+import json
 import time
 from unittest.mock import patch
 
 import pytest
-from openai.types.chat import ChatCompletion, ChatCompletionMessage
-from openai.types.chat.chat_completion import Choice
-from openai.types.completion_usage import CompletionUsage
-from openai.types.create_embedding_response import CreateEmbeddingResponse, Usage
-from openai.types.embedding import Embedding
 
-from posthog.ai.openai import OpenAI
+try:
+    from openai.types.chat import ChatCompletion, ChatCompletionMessage
+    from openai.types.chat.chat_completion import Choice
+    from openai.types.chat.chat_completion_chunk import ChatCompletionChunk
+    from openai.types.chat.chat_completion_chunk import Choice as ChoiceChunk
+    from openai.types.chat.chat_completion_chunk import (
+        ChoiceDelta,
+        ChoiceDeltaToolCall,
+        ChoiceDeltaToolCallFunction,
+    )
+    from openai.types.chat.chat_completion_message_tool_call import (
+        ChatCompletionMessageToolCall,
+        Function,
+    )
+    from openai.types.completion_usage import CompletionUsage
+    from openai.types.create_embedding_response import CreateEmbeddingResponse, Usage
+    from openai.types.embedding import Embedding
+    from openai.types.responses import (
+        Response,
+        ResponseOutputMessage,
+        ResponseOutputText,
+        ResponseUsage,
+        ParsedResponse,
+    )
+    from openai.types.responses.parsed_response import (
+        ParsedResponseOutputMessage,
+        ParsedResponseOutputText,
+    )
+
+    from posthog.ai.openai import OpenAI
+
+    OPENAI_AVAILABLE = True
+except ImportError:
+    OPENAI_AVAILABLE = False
+
+# Skip all tests if OpenAI is not available
+pytestmark = pytest.mark.skipif(
+    not OPENAI_AVAILABLE, reason="OpenAI package is not available"
+)
 
 
 @pytest.fixture
@@ -43,6 +77,102 @@ def mock_openai_response():
     )
 
 
+@pytest.fixture
+def mock_openai_response_with_responses_api():
+    return Response(
+        id="test",
+        model="gpt-4o-mini",
+        object="response",
+        created_at=1741476542,
+        status="completed",
+        error=None,
+        incomplete_details=None,
+        instructions=None,
+        max_output_tokens=None,
+        tools=[],
+        tool_choice="auto",
+        output=[
+            ResponseOutputMessage(
+                id="msg_123",
+                type="message",
+                role="assistant",
+                status="completed",
+                content=[
+                    ResponseOutputText(
+                        type="output_text",
+                        text="Test response",
+                        annotations=[],
+                    )
+                ],
+            )
+        ],
+        parallel_tool_calls=True,
+        previous_response_id=None,
+        usage=ResponseUsage(
+            input_tokens=10,
+            output_tokens=10,
+            input_tokens_details={"prompt_tokens": 10, "cached_tokens": 0},
+            output_tokens_details={"reasoning_tokens": 15},
+            total_tokens=20,
+        ),
+        user=None,
+        metadata={},
+    )
+
+
+@pytest.fixture
+def mock_parsed_response():
+    return ParsedResponse(
+        id="test",
+        model="gpt-4o-2024-08-06",
+        object="response",
+        created_at=1741476542,
+        status="completed",
+        error=None,
+        incomplete_details=None,
+        instructions=None,
+        max_output_tokens=None,
+        tools=[],
+        tool_choice="auto",
+        output=[
+            ParsedResponseOutputMessage(
+                id="msg_123",
+                type="message",
+                role="assistant",
+                status="completed",
+                content=[
+                    ParsedResponseOutputText(
+                        type="output_text",
+                        text='{"name": "Science Fair", "date": "Friday", "participants": ["Alice", "Bob"]}',
+                        annotations=[],
+                        parsed={
+                            "name": "Science Fair",
+                            "date": "Friday",
+                            "participants": ["Alice", "Bob"],
+                        },
+                    )
+                ],
+            )
+        ],
+        output_parsed={
+            "name": "Science Fair",
+            "date": "Friday",
+            "participants": ["Alice", "Bob"],
+        },
+        parallel_tool_calls=True,
+        previous_response_id=None,
+        usage=ResponseUsage(
+            input_tokens=15,
+            output_tokens=20,
+            input_tokens_details={"prompt_tokens": 15, "cached_tokens": 0},
+            output_tokens_details={"reasoning_tokens": 5},
+            total_tokens=35,
+        ),
+        user=None,
+        metadata={},
+    )
+
+
 @pytest.fixture
 def mock_embedding_response():
     return CreateEmbeddingResponse(
@@ -62,8 +192,72 @@ def mock_embedding_response():
     )
 
 
+@pytest.fixture
+def mock_openai_response_with_cached_tokens():
+    return ChatCompletion(
+        id="test",
+        model="gpt-4",
+        object="chat.completion",
+        created=int(time.time()),
+        choices=[
+            Choice(
+                finish_reason="stop",
+                index=0,
+                message=ChatCompletionMessage(
+                    content="Test response",
+                    role="assistant",
+                ),
+            )
+        ],
+        usage=CompletionUsage(
+            completion_tokens=10,
+            prompt_tokens=20,
+            total_tokens=30,
+            prompt_tokens_details={"cached_tokens": 15},
+        ),
+    )
+
+
+@pytest.fixture
+def mock_openai_response_with_tool_calls():
+    return ChatCompletion(
+        id="test",
+        model="gpt-4",
+        object="chat.completion",
+        created=int(time.time()),
+        choices=[
+            Choice(
+                finish_reason="tool_calls",
+                index=0,
+                message=ChatCompletionMessage(
+                    content="I'll check the weather for you.",
+                    role="assistant",
+                    tool_calls=[
+                        ChatCompletionMessageToolCall(
+                            id="call_abc123",
+                            type="function",
+                            function=Function(
+                                name="get_weather",
+                                arguments='{"location": "San Francisco", "unit": "celsius"}',
+                            ),
+                        )
+                    ],
+                ),
+            )
+        ],
+        usage=CompletionUsage(
+            completion_tokens=15,
+            prompt_tokens=20,
+            total_tokens=35,
+        ),
+    )
+
+
 def test_basic_completion(mock_client, mock_openai_response):
-    with patch("openai.resources.chat.completions.Completions.create", return_value=mock_openai_response):
+    with patch(
+        "openai.resources.chat.completions.Completions.create",
+        return_value=mock_openai_response,
+    ):
         client = OpenAI(api_key="test-key", posthog_client=mock_client)
         response = client.chat.completions.create(
             model="gpt-4",
@@ -83,7 +277,9 @@ def test_basic_completion(mock_client, mock_openai_response):
         assert props["$ai_provider"] == "openai"
         assert props["$ai_model"] == "gpt-4"
         assert props["$ai_input"] == [{"role": "user", "content": "Hello"}]
-        assert props["$ai_output_choices"] == [{"role": "assistant", "content": "Test response"}]
+        assert props["$ai_output_choices"] == [
+            {"role": "assistant", "content": "Test response"}
+        ]
         assert props["$ai_input_tokens"] == 20
         assert props["$ai_output_tokens"] == 10
         assert props["$ai_http_status"] == 200
@@ -92,7 +288,10 @@ def test_basic_completion(mock_client, mock_openai_response):
 
 
 def test_embeddings(mock_client, mock_embedding_response):
-    with patch("openai.resources.embeddings.Embeddings.create", return_value=mock_embedding_response):
+    with patch(
+        "openai.resources.embeddings.Embeddings.create",
+        return_value=mock_embedding_response,
+    ):
         client = OpenAI(api_key="test-key", posthog_client=mock_client)
         response = client.embeddings.create(
             model="text-embedding-3-small",
@@ -119,7 +318,10 @@ def test_embeddings(mock_client, mock_embedding_response):
 
 
 def test_groups(mock_client, mock_openai_response):
-    with patch("openai.resources.chat.completions.Completions.create", return_value=mock_openai_response):
+    with patch(
+        "openai.resources.chat.completions.Completions.create",
+        return_value=mock_openai_response,
+    ):
         client = OpenAI(api_key="test-key", posthog_client=mock_client)
         response = client.chat.completions.create(
             model="gpt-4",
@@ -137,7 +339,10 @@ def test_groups(mock_client, mock_openai_response):
 
 
 def test_privacy_mode_local(mock_client, mock_openai_response):
-    with patch("openai.resources.chat.completions.Completions.create", return_value=mock_openai_response):
+    with patch(
+        "openai.resources.chat.completions.Completions.create",
+        return_value=mock_openai_response,
+    ):
         client = OpenAI(api_key="test-key", posthog_client=mock_client)
         response = client.chat.completions.create(
             model="gpt-4",
@@ -156,7 +361,10 @@ def test_privacy_mode_local(mock_client, mock_openai_response):
 
 
 def test_privacy_mode_global(mock_client, mock_openai_response):
-    with patch("openai.resources.chat.completions.Completions.create", return_value=mock_openai_response):
+    with patch(
+        "openai.resources.chat.completions.Completions.create",
+        return_value=mock_openai_response,
+    ):
         mock_client.privacy_mode = True
         client = OpenAI(api_key="test-key", posthog_client=mock_client)
         response = client.chat.completions.create(
@@ -176,10 +384,15 @@ def test_privacy_mode_global(mock_client, mock_openai_response):
 
 
 def test_error(mock_client, mock_openai_response):
-    with patch("openai.resources.chat.completions.Completions.create", side_effect=Exception("Test error")):
+    with patch(
+        "openai.resources.chat.completions.Completions.create",
+        side_effect=Exception("Test error"),
+    ):
         client = OpenAI(api_key="test-key", posthog_client=mock_client)
         with pytest.raises(Exception):
-            client.chat.completions.create(model="gpt-4", messages=[{"role": "user", "content": "Hello"}])
+            client.chat.completions.create(
+                model="gpt-4", messages=[{"role": "user", "content": "Hello"}]
+            )
 
         assert mock_client.capture.call_count == 1
 
@@ -187,3 +400,377 @@ def test_error(mock_client, mock_openai_response):
         props = call_args["properties"]
         assert props["$ai_is_error"] is True
         assert props["$ai_error"] == "Test error"
+
+
+def test_cached_tokens(mock_client, mock_openai_response_with_cached_tokens):
+    with patch(
+        "openai.resources.chat.completions.Completions.create",
+        return_value=mock_openai_response_with_cached_tokens,
+    ):
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+        response = client.chat.completions.create(
+            model="gpt-4",
+            messages=[{"role": "user", "content": "Hello"}],
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+        )
+
+        assert response == mock_openai_response_with_cached_tokens
+        assert mock_client.capture.call_count == 1
+
+        call_args = mock_client.capture.call_args[1]
+        props = call_args["properties"]
+
+        assert call_args["distinct_id"] == "test-id"
+        assert call_args["event"] == "$ai_generation"
+        assert props["$ai_provider"] == "openai"
+        assert props["$ai_model"] == "gpt-4"
+        assert props["$ai_input"] == [{"role": "user", "content": "Hello"}]
+        assert props["$ai_output_choices"] == [
+            {"role": "assistant", "content": "Test response"}
+        ]
+        assert props["$ai_input_tokens"] == 20
+        assert props["$ai_output_tokens"] == 10
+        assert props["$ai_cache_read_input_tokens"] == 15
+        assert props["$ai_http_status"] == 200
+        assert props["foo"] == "bar"
+        assert isinstance(props["$ai_latency"], float)
+
+
+def test_tool_calls(mock_client, mock_openai_response_with_tool_calls):
+    with patch(
+        "openai.resources.chat.completions.Completions.create",
+        return_value=mock_openai_response_with_tool_calls,
+    ):
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+        response = client.chat.completions.create(
+            model="gpt-4",
+            messages=[
+                {"role": "user", "content": "What's the weather in San Francisco?"}
+            ],
+            tools=[
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "get_weather",
+                        "description": "Get weather",
+                        "parameters": {},
+                    },
+                }
+            ],
+            posthog_distinct_id="test-id",
+        )
+
+        assert response == mock_openai_response_with_tool_calls
+        assert mock_client.capture.call_count == 1
+
+        call_args = mock_client.capture.call_args[1]
+        props = call_args["properties"]
+
+        assert call_args["distinct_id"] == "test-id"
+        assert call_args["event"] == "$ai_generation"
+        assert props["$ai_provider"] == "openai"
+        assert props["$ai_model"] == "gpt-4"
+        assert props["$ai_input"] == [
+            {"role": "user", "content": "What's the weather in San Francisco?"}
+        ]
+        assert props["$ai_output_choices"] == [
+            {"role": "assistant", "content": "I'll check the weather for you."}
+        ]
+
+        # Check that tool calls are properly captured
+        assert "$ai_tools" in props
+        tool_calls = props["$ai_tools"]
+        assert len(tool_calls) == 1
+
+        # Verify the tool call details
+        tool_call = tool_calls[0]
+        assert tool_call.id == "call_abc123"
+        assert tool_call.type == "function"
+        assert tool_call.function.name == "get_weather"
+
+        # Verify the arguments
+        arguments = tool_call.function.arguments
+        parsed_args = json.loads(arguments)
+        assert parsed_args == {"location": "San Francisco", "unit": "celsius"}
+
+        # Check token usage
+        assert props["$ai_input_tokens"] == 20
+        assert props["$ai_output_tokens"] == 15
+        assert props["$ai_http_status"] == 200
+
+
+def test_streaming_with_tool_calls(mock_client):
+    # Create mock tool call chunks that will be returned in sequence
+    tool_call_chunks = [
+        ChatCompletionChunk(
+            id="chunk1",
+            model="gpt-4",
+            object="chat.completion.chunk",
+            created=1234567890,
+            choices=[
+                ChoiceChunk(
+                    index=0,
+                    delta=ChoiceDelta(
+                        role="assistant",
+                        tool_calls=[
+                            ChoiceDeltaToolCall(
+                                index=0,
+                                id="call_abc123",
+                                type="function",
+                                function=ChoiceDeltaToolCallFunction(
+                                    name="get_weather",
+                                    arguments='{"location": "',
+                                ),
+                            )
+                        ],
+                    ),
+                    finish_reason=None,
+                )
+            ],
+        ),
+        ChatCompletionChunk(
+            id="chunk2",
+            model="gpt-4",
+            object="chat.completion.chunk",
+            created=1234567891,
+            choices=[
+                ChoiceChunk(
+                    index=0,
+                    delta=ChoiceDelta(
+                        tool_calls=[
+                            ChoiceDeltaToolCall(
+                                index=0,
+                                id="call_abc123",
+                                type="function",
+                                function=ChoiceDeltaToolCallFunction(
+                                    arguments='San Francisco"',
+                                ),
+                            )
+                        ],
+                    ),
+                    finish_reason=None,
+                )
+            ],
+        ),
+        ChatCompletionChunk(
+            id="chunk3",
+            model="gpt-4",
+            object="chat.completion.chunk",
+            created=1234567892,
+            choices=[
+                ChoiceChunk(
+                    index=0,
+                    delta=ChoiceDelta(
+                        tool_calls=[
+                            ChoiceDeltaToolCall(
+                                index=0,
+                                id="call_abc123",
+                                type="function",
+                                function=ChoiceDeltaToolCallFunction(
+                                    arguments=', "unit": "celsius"}',
+                                ),
+                            )
+                        ],
+                    ),
+                    finish_reason=None,
+                )
+            ],
+        ),
+        ChatCompletionChunk(
+            id="chunk4",
+            model="gpt-4",
+            object="chat.completion.chunk",
+            created=1234567893,
+            choices=[
+                ChoiceChunk(
+                    index=0,
+                    delta=ChoiceDelta(
+                        content="The weather in San Francisco is 15°C.",
+                    ),
+                    finish_reason=None,
+                )
+            ],
+            usage=CompletionUsage(
+                prompt_tokens=20,
+                completion_tokens=15,
+                total_tokens=35,
+            ),
+        ),
+    ]
+
+    # Mock the create method to return our chunks
+    with patch("openai.resources.chat.completions.Completions.create") as mock_create:
+        # Set up the mock to return our chunks when iterated
+        mock_create.return_value = tool_call_chunks
+
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+
+        # Call the streaming method
+        response_generator = client.chat.completions.create(
+            model="gpt-4",
+            messages=[
+                {"role": "user", "content": "What's the weather in San Francisco?"}
+            ],
+            tools=[
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "get_weather",
+                        "description": "Get weather",
+                        "parameters": {},
+                    },
+                }
+            ],
+            stream=True,
+            posthog_distinct_id="test-id",
+        )
+
+        # Consume the generator to trigger the event capture
+        chunks = list(response_generator)
+
+        # Verify the chunks were returned correctly
+        assert len(chunks) == 4
+        assert chunks == tool_call_chunks
+
+        # Verify the capture was called with the right arguments
+        assert mock_client.capture.call_count == 1
+
+        call_args = mock_client.capture.call_args[1]
+        props = call_args["properties"]
+
+        assert call_args["distinct_id"] == "test-id"
+        assert call_args["event"] == "$ai_generation"
+        assert props["$ai_provider"] == "openai"
+        assert props["$ai_model"] == "gpt-4"
+
+        # Check that the tool calls were properly accumulated
+        assert "$ai_tools" in props
+        tool_calls = props["$ai_tools"]
+        assert len(tool_calls) == 1
+
+        # Verify the complete tool call was properly assembled
+        tool_call = tool_calls[0]
+        assert tool_call.id == "call_abc123"
+        assert tool_call.type == "function"
+        assert tool_call.function.name == "get_weather"
+
+        # Verify the arguments were concatenated correctly
+        arguments = tool_call.function.arguments
+        parsed_args = json.loads(arguments)
+        assert parsed_args == {"location": "San Francisco", "unit": "celsius"}
+
+        # Check that the content was also accumulated
+        assert (
+            props["$ai_output_choices"][0]["content"]
+            == "The weather in San Francisco is 15°C."
+        )
+
+        # Check token usage
+        assert props["$ai_input_tokens"] == 20
+        assert props["$ai_output_tokens"] == 15
+
+
+# test responses api
+def test_responses_api(mock_client, mock_openai_response_with_responses_api):
+    with patch(
+        "openai.resources.responses.Responses.create",
+        return_value=mock_openai_response_with_responses_api,
+    ):
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+        response = client.responses.create(
+            model="gpt-4o-mini",
+            input="Hello",
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+        )
+        assert response == mock_openai_response_with_responses_api
+        assert mock_client.capture.call_count == 1
+
+        call_args = mock_client.capture.call_args[1]
+        props = call_args["properties"]
+
+        assert call_args["distinct_id"] == "test-id"
+        assert call_args["event"] == "$ai_generation"
+        assert props["$ai_provider"] == "openai"
+        assert props["$ai_model"] == "gpt-4o-mini"
+        assert props["$ai_input"] == [{"role": "user", "content": "Hello"}]
+        assert props["$ai_output_choices"] == [
+            {"role": "assistant", "content": "Test response"}
+        ]
+        assert props["$ai_input_tokens"] == 10
+        assert props["$ai_output_tokens"] == 10
+        assert props["$ai_reasoning_tokens"] == 15
+        assert props["$ai_http_status"] == 200
+        assert props["foo"] == "bar"
+        assert isinstance(props["$ai_latency"], float)
+
+
+def test_responses_parse(mock_client, mock_parsed_response):
+    with patch(
+        "openai.resources.responses.Responses.parse",
+        return_value=mock_parsed_response,
+    ):
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+        response = client.responses.parse(
+            model="gpt-4o-2024-08-06",
+            input=[
+                {"role": "system", "content": "Extract the event information."},
+                {
+                    "role": "user",
+                    "content": "Alice and Bob are going to a science fair on Friday.",
+                },
+            ],
+            text={
+                "format": {
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": "event",
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "name": {"type": "string"},
+                                "date": {"type": "string"},
+                                "participants": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                },
+                            },
+                            "required": ["name", "date", "participants"],
+                        },
+                    },
+                }
+            },
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+        )
+
+        assert response == mock_parsed_response
+        assert mock_client.capture.call_count == 1
+
+        call_args = mock_client.capture.call_args[1]
+        props = call_args["properties"]
+
+        assert call_args["distinct_id"] == "test-id"
+        assert call_args["event"] == "$ai_generation"
+        assert props["$ai_provider"] == "openai"
+        assert props["$ai_model"] == "gpt-4o-2024-08-06"
+        assert props["$ai_input"] == [
+            {"role": "system", "content": "Extract the event information."},
+            {
+                "role": "user",
+                "content": "Alice and Bob are going to a science fair on Friday.",
+            },
+        ]
+        assert props["$ai_output_choices"] == [
+            {
+                "role": "assistant",
+                "content": '{"name": "Science Fair", "date": "Friday", "participants": ["Alice", "Bob"]}',
+            }
+        ]
+        assert props["$ai_input_tokens"] == 15
+        assert props["$ai_output_tokens"] == 20
+        assert props["$ai_reasoning_tokens"] == 5
+        assert props["$ai_http_status"] == 200
+        assert props["foo"] == "bar"
+        assert isinstance(props["$ai_latency"], float)

posthog/test/exception_integrations/__init__.py

@@ -1,3 +0,0 @@
-import pytest
-
-pytest.importorskip("django")

posthog/test/exception_integrations/test_django.py

@@ -1,68 +0,0 @@
-from posthog.exception_integrations.django import DjangoRequestExtractor
-
-DEFAULT_USER_AGENT = (
-    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
-)
-
-
-def mock_request_factory(override_headers):
-    class Request:
-        META = {}
-        # TRICKY: Actual django request dict object has case insensitive matching, and strips http from the names
-        headers = {
-            "User-Agent": DEFAULT_USER_AGENT,
-            "Referrer": "http://example.com",
-            "X-Forwarded-For": "193.4.5.12",
-            **(override_headers or {}),
-        }
-
-    return Request()
-
-
-def test_request_extractor_with_no_trace():
-    request = mock_request_factory(None)
-    extractor = DjangoRequestExtractor(request)
-    assert extractor.extract_person_data() == {
-        "ip": "193.4.5.12",
-        "user_agent": DEFAULT_USER_AGENT,
-        "traceparent": None,
-        "distinct_id": None,
-    }
-
-
-def test_request_extractor_with_trace():
-    request = mock_request_factory({"traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"})
-    extractor = DjangoRequestExtractor(request)
-    assert extractor.extract_person_data() == {
-        "ip": "193.4.5.12",
-        "user_agent": DEFAULT_USER_AGENT,
-        "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
-        "distinct_id": None,
-    }
-
-
-def test_request_extractor_with_tracestate():
-    request = mock_request_factory(
-        {
-            "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
-            "tracestate": "posthog-distinct-id=1234",
-        }
-    )
-    extractor = DjangoRequestExtractor(request)
-    assert extractor.extract_person_data() == {
-        "ip": "193.4.5.12",
-        "user_agent": DEFAULT_USER_AGENT,
-        "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
-        "distinct_id": "1234",
-    }
-
-
-def test_request_extractor_with_complicated_tracestate():
-    request = mock_request_factory({"tracestate": "posthog-distinct-id=alohaMountainsXUYZ,rojo=00f067aa0ba902b7"})
-    extractor = DjangoRequestExtractor(request)
-    assert extractor.extract_person_data() == {
-        "ip": "193.4.5.12",
-        "user_agent": DEFAULT_USER_AGENT,
-        "traceparent": None,
-        "distinct_id": "alohaMountainsXUYZ",
-    }

posthog/test/integrations/test_middleware.py

@@ -0,0 +1,173 @@
+from posthog.contexts import (
+    new_context,
+    get_context_session_id,
+    get_context_distinct_id,
+)
+import unittest
+from unittest.mock import Mock
+
+from posthog.integrations.django import PosthogContextMiddleware
+
+
+class MockRequest:
+    """Mock Django HttpRequest object"""
+
+    def __init__(
+        self,
+        headers=None,
+        method="GET",
+        path="/test",
+        host="example.com",
+        is_secure=False,
+    ):
+        self.headers = headers or {}
+        self.method = method
+        self.path = path
+        self._host = host
+        self._is_secure = is_secure
+
+    def build_absolute_uri(self):
+        scheme = "https" if self._is_secure else "http"
+        return f"{scheme}://{self._host}{self.path}"
+
+
+class TestPosthogContextMiddleware(unittest.TestCase):
+    def create_middleware(
+        self,
+        extra_tags=None,
+        request_filter=None,
+        tag_map=None,
+        capture_exceptions=True,
+    ):
+        """Helper to create middleware instance without calling __init__"""
+        middleware = PosthogContextMiddleware.__new__(PosthogContextMiddleware)
+        middleware.get_response = Mock()
+        middleware.extra_tags = extra_tags
+        middleware.request_filter = request_filter
+        middleware.tag_map = tag_map
+        middleware.capture_exceptions = capture_exceptions
+        return middleware
+
+    def test_extract_tags_basic(self):
+        with new_context():
+            """Test basic tag extraction from request"""
+            middleware = self.create_middleware()
+            request = MockRequest(
+                headers={
+                    "X-POSTHOG-SESSION-ID": "session-123",
+                    "X-POSTHOG-DISTINCT-ID": "user-456",
+                },
+                method="POST",
+                path="/api/test",
+                host="example.com",
+                is_secure=True,
+            )
+
+            tags = middleware.extract_tags(request)
+
+            self.assertEqual(get_context_session_id(), "session-123")
+            self.assertEqual(get_context_distinct_id(), "user-456")
+            self.assertEqual(tags["$current_url"], "https://example.com/api/test")
+            self.assertEqual(tags["$request_method"], "POST")
+
+    def test_extract_tags_missing_headers(self):
+        """Test tag extraction when PostHog headers are missing"""
+
+        with new_context():
+            middleware = self.create_middleware()
+            request = MockRequest(headers={}, method="GET", path="/home")
+
+            tags = middleware.extract_tags(request)
+
+            self.assertIsNone(get_context_session_id())
+            self.assertIsNone(get_context_distinct_id())
+            self.assertEqual(tags["$current_url"], "http://example.com/home")
+            self.assertEqual(tags["$request_method"], "GET")
+
+    def test_extract_tags_partial_headers(self):
+        """Test tag extraction with only some PostHog headers present"""
+
+        with new_context():
+            middleware = self.create_middleware()
+            request = MockRequest(
+                headers={"X-POSTHOG-SESSION-ID": "session-only"}, method="PUT"
+            )
+
+            tags = middleware.extract_tags(request)
+
+            self.assertEqual(get_context_session_id(), "session-only")
+            self.assertIsNone(get_context_distinct_id())
+            self.assertEqual(tags["$request_method"], "PUT")
+
+    def test_extract_tags_with_extra_tags(self):
+        """Test tag extraction with extra_tags function"""
+
+        def extra_tags_func(request):
+            return {"custom_tag": "custom_value", "user_id": "789"}
+
+        with new_context():
+            middleware = self.create_middleware(extra_tags=extra_tags_func)
+            request = MockRequest(
+                headers={"X-POSTHOG-SESSION-ID": "session-123"}, method="GET"
+            )
+
+            tags = middleware.extract_tags(request)
+
+            self.assertEqual(get_context_session_id(), "session-123")
+            self.assertEqual(tags["custom_tag"], "custom_value")
+            self.assertEqual(tags["user_id"], "789")
+
+    def test_extract_tags_with_tag_map(self):
+        """Test tag extraction with tag_map function"""
+
+        def extra_tags_func(request):
+            return {"custom_tag": "custom_value", "user_id": "789"}
+
+        def tag_map_func(tags):
+            if "custom_tag" in tags:
+                tags["mapped_custom_tag"] = f"mapped_{tags['custom_tag']}"
+                del tags["custom_tag"]
+            return tags
+
+        with new_context():
+            middleware = self.create_middleware(
+                tag_map=tag_map_func, extra_tags=extra_tags_func
+            )
+            request = MockRequest(
+                headers={"X-POSTHOG-SESSION-ID": "session-123"}, method="GET"
+            )
+
+            tags = middleware.extract_tags(request)
+
+            self.assertEqual(tags["mapped_custom_tag"], "mapped_custom_value")
+
+    def test_extract_tags_extra_tags_returns_none(self):
+        """Test tag extraction when extra_tags returns None"""
+
+        def extra_tags_func(request):
+            return None
+
+        middleware = self.create_middleware(extra_tags=extra_tags_func)
+        request = MockRequest(method="GET")
+
+        tags = middleware.extract_tags(request)
+
+        self.assertEqual(tags["$request_method"], "GET")
+        # Should not crash when extra_tags returns None
+
+    def test_extract_tags_extra_tags_returns_empty_dict(self):
+        """Test tag extraction when extra_tags returns empty dict"""
+
+        def extra_tags_func(request):
+            return {}
+
+        middleware = self.create_middleware(extra_tags=extra_tags_func)
+        request = MockRequest(method="PATCH")
+
+        tags = middleware.extract_tags(request)
+
+        self.assertEqual(tags["$request_method"], "PATCH")
+
+
+if __name__ == "__main__":
+    unittest.main()

posthog/test/test_before_send.py

@@ -0,0 +1,218 @@
+import unittest
+
+import mock
+
+from posthog.client import Client
+from posthog.test.test_utils import FAKE_TEST_API_KEY
+
+
+class TestClient(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        # This ensures no real HTTP POST requests are made
+        cls.client_post_patcher = mock.patch("posthog.client.batch_post")
+        cls.consumer_post_patcher = mock.patch("posthog.consumer.batch_post")
+        cls.client_post_patcher.start()
+        cls.consumer_post_patcher.start()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.client_post_patcher.stop()
+        cls.consumer_post_patcher.stop()
+
+    def set_fail(self, e, batch):
+        """Mark the failure handler"""
+        print("FAIL", e, batch)  # noqa: T201
+        self.failed = True
+
+    def setUp(self):
+        self.failed = False
+        self.client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail)
+
+    def test_before_send_callback_modifies_event(self):
+        """Test that before_send callback can modify events."""
+        processed_events = []
+
+        def my_before_send(event):
+            processed_events.append(event.copy())
+            if "properties" not in event:
+                event["properties"] = {}
+            event["properties"]["processed_by_before_send"] = True
+            return event
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=my_before_send,
+                sync_mode=True,
+            )
+            msg_uuid = client.capture(
+                "test_event", distinct_id="user1", properties={"original": "value"}
+            )
+
+            self.assertIsNotNone(msg_uuid)
+
+            # Get the enqueued message from the mock
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+
+            self.assertEqual(
+                enqueued_msg["properties"]["processed_by_before_send"], True
+            )
+            self.assertEqual(enqueued_msg["properties"]["original"], "value")
+            self.assertEqual(len(processed_events), 1)
+            self.assertEqual(processed_events[0]["event"], "test_event")
+
+    def test_before_send_callback_drops_event(self):
+        """Test that before_send callback can drop events by returning None."""
+
+        def drop_test_events(event):
+            if event.get("event") == "test_drop_me":
+                return None
+            return event
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=drop_test_events,
+                sync_mode=True,
+            )
+
+            # Event should be dropped
+            msg_uuid = client.capture("test_drop_me", distinct_id="user1")
+            self.assertIsNone(msg_uuid)
+
+            # Event should go through
+            msg_uuid = client.capture("keep_me", distinct_id="user1")
+            self.assertIsNotNone(msg_uuid)
+
+            # Check the enqueued message
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+            self.assertEqual(enqueued_msg["event"], "keep_me")
+
+    def test_before_send_callback_handles_exceptions(self):
+        """Test that exceptions in before_send don't crash the client."""
+
+        def buggy_before_send(event):
+            raise ValueError("Oops!")
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=buggy_before_send,
+                sync_mode=True,
+            )
+            msg_uuid = client.capture("robust_event", distinct_id="user1")
+
+            # Event should still be sent despite the exception
+            self.assertIsNotNone(msg_uuid)
+
+            # Check the enqueued message
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+            self.assertEqual(enqueued_msg["event"], "robust_event")
+
+    def test_before_send_callback_works_with_all_event_types(self):
+        """Test that before_send works with capture, set, etc."""
+
+        def add_marker(event):
+            if "properties" not in event:
+                event["properties"] = {}
+            event["properties"]["marked"] = True
+            return event
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=add_marker,
+                sync_mode=True,
+            )
+
+            # Test capture
+            msg_uuid = client.capture("event", distinct_id="user1")
+            self.assertIsNotNone(msg_uuid)
+
+            # Test set
+            msg_uuid = client.set(distinct_id="user1", properties={"prop": "value"})
+            self.assertIsNotNone(msg_uuid)
+
+            # Check all events were marked
+            self.assertEqual(mock_post.call_count, 2)
+            for call in mock_post.call_args_list:
+                batch_data = call[1]["batch"]
+                enqueued_msg = batch_data[0]
+                self.assertTrue(enqueued_msg["properties"]["marked"])
+
+    def test_before_send_callback_disabled_when_none(self):
+        """Test that client works normally when before_send is None."""
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=None,
+                sync_mode=True,
+            )
+            msg_uuid = client.capture("normal_event", distinct_id="user1")
+            self.assertIsNotNone(msg_uuid)
+
+            # Check the event was sent normally
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+            self.assertEqual(enqueued_msg["event"], "normal_event")
+
+    def test_before_send_callback_pii_scrubbing_example(self):
+        """Test a realistic PII scrubbing use case."""
+
+        def scrub_pii(event):
+            properties = event.get("properties", {})
+
+            # Mask email but keep domain
+            if "email" in properties:
+                email = properties["email"]
+                if "@" in email:
+                    domain = email.split("@")[1]
+                    properties["email"] = f"***@{domain}"
+                else:
+                    properties["email"] = "***"
+
+            # Remove credit card
+            properties.pop("credit_card", None)
+
+            return event
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=scrub_pii,
+                sync_mode=True,
+            )
+            msg_uuid = client.capture(
+                "form_submit",
+                distinct_id="user1",
+                properties={
+                    "email": "user@example.com",
+                    "credit_card": "1234-5678-9012-3456",
+                    "form_name": "contact",
+                },
+            )
+
+            self.assertIsNotNone(msg_uuid)
+
+            # Check the enqueued message was scrubbed
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+
+            self.assertEqual(enqueued_msg["properties"]["email"], "***@example.com")
+            self.assertNotIn("credit_card", enqueued_msg["properties"])
+            self.assertEqual(enqueued_msg["properties"]["form_name"], "contact")

posthog/test/test_consumer.py

@@ -58,7 +58,11 @@ class TestConsumer(unittest.TestCase):
         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"}
+                track = {
+                    "type": "track",
+                    "event": "python event %d" % i,
+                    "distinct_id": "distinct_id",
+                }
                 q.put(track)
                 time.sleep(flush_interval * 1.1)
             self.assertEqual(mock_post.call_count, 3)
@@ -69,11 +73,17 @@ class TestConsumer(unittest.TestCase):
         q = Queue()
         flush_interval = 0.5
         flush_at = 10
-        consumer = Consumer(q, TEST_API_KEY, flush_at=flush_at, flush_interval=flush_interval)
+        consumer = Consumer(
+            q, TEST_API_KEY, flush_at=flush_at, flush_interval=flush_interval
+        )
         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"}
+                track = {
+                    "type": "track",
+                    "event": "python event %d" % i,
+                    "distinct_id": "distinct_id",
+                }
                 q.put(track)
             time.sleep(flush_interval * 1.1)
             self.assertEqual(mock_post.call_count, 2)
@@ -91,8 +101,14 @@ class TestConsumer(unittest.TestCase):
 
         mock_post.call_count = 0
 
-        with mock.patch("posthog.consumer.batch_post", mock.Mock(side_effect=mock_post)):
-            track = {"type": "track", "event": "python event", "distinct_id": "distinct_id"}
+        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:
@@ -107,7 +123,8 @@ class TestConsumer(unittest.TestCase):
                     self.assertEqual(exc, expected_exception)
                 else:
                     self.fail(
-                        "request() should raise an exception if still failing after %d retries" % consumer.retries
+                        "request() should raise an exception if still failing after %d retries"
+                        % consumer.retries
                     )
 
     def test_request_retry(self):
@@ -148,7 +165,12 @@ class TestConsumer(unittest.TestCase):
         properties = {}
         for n in range(0, 500):
             properties[str(n)] = "one_long_property_value_to_build_a_big_event"
-        track = {"type": "track", "event": "python event", "distinct_id": "distinct_id", "properties": properties}
+        track = {
+            "type": "track",
+            "event": "python event",
+            "distinct_id": "distinct_id",
+            "properties": properties,
+        }
         msg_size = len(json.dumps(track).encode())
         # Let's capture 8MB of data to trigger two batches
         n_msgs = int(8_000_000 / msg_size)
@@ -158,10 +180,15 @@ class TestConsumer(unittest.TestCase):
             res.status_code = 200
             request_size = len(data.encode())
             # Batches close after the first message bringing it bigger than BATCH_SIZE_LIMIT, let's add 10% of margin
-            self.assertTrue(request_size < (5 * 1024 * 1024) * 1.1, "batch size (%d) higher than limit" % request_size)
+            self.assertTrue(
+                request_size < (5 * 1024 * 1024) * 1.1,
+                "batch size (%d) higher than limit" % request_size,
+            )
             return res
 
-        with mock.patch("posthog.request._session.post", side_effect=mock_post_fn) as mock_post:
+        with mock.patch(
+            "posthog.request._session.post", side_effect=mock_post_fn
+        ) as mock_post:
             consumer.start()
             for _ in range(0, n_msgs + 2):
                 q.put(track)

posthog/test/test_contexts.py

@@ -0,0 +1,207 @@
+import unittest
+from unittest.mock import patch
+
+from posthog.contexts import (
+    get_tags,
+    new_context,
+    scoped,
+    tag,
+    identify_context,
+    set_context_session,
+    get_context_session_id,
+    get_context_distinct_id,
+)
+
+
+class TestContexts(unittest.TestCase):
+    def test_tag_and_get_tags(self):
+        with new_context(fresh=True):
+            tag("key1", "value1")
+            tag("key2", 2)
+
+            tags = get_tags()
+            assert tags["key1"] == "value1"
+            assert tags["key2"] == 2
+
+    def test_new_context_isolation(self):
+        with new_context(fresh=True):
+            # Set tag in outer context
+            tag("outer", "value")
+
+            with new_context(fresh=True):
+                # Inner context should start empty
+                assert get_tags() == {}
+
+                # Set tag in inner context
+                tag("inner", "value")
+                assert get_tags()["inner"] == "value"
+
+                # Outer tag should not be visible
+                self.assertNotIn("outer", get_tags())
+
+            with new_context(fresh=False):
+                # Inner context should inherit outer tag
+                assert get_tags() == {"outer": "value"}
+
+            # After exiting context, inner tag should be gone
+            self.assertNotIn("inner", get_tags())
+
+            # Outer tag should still be there
+            assert get_tags()["outer"] == "value"
+
+    def test_nested_contexts(self):
+        with new_context(fresh=True):
+            tag("level1", "value1")
+
+            with new_context(fresh=True):
+                tag("level2", "value2")
+
+                with new_context(fresh=True):
+                    tag("level3", "value3")
+                    assert get_tags() == {"level3": "value3"}
+
+                # Back to level 2
+                assert get_tags() == {"level2": "value2"}
+
+            # Back to level 1
+            assert get_tags() == {"level1": "value1"}
+
+    @patch("posthog.capture_exception")
+    def test_scoped_decorator_success(self, mock_capture):
+        @scoped()
+        def successful_function(x, y):
+            tag("x", x)
+            tag("y", y)
+            return x + y
+
+        result = successful_function(1, 2)
+
+        # Function should execute normally
+        assert result == 3
+
+        # No exception should be captured
+        mock_capture.assert_not_called()
+
+        # Context should be cleared after function execution
+        assert get_tags() == {}
+
+    @patch("posthog.capture_exception")
+    def test_scoped_decorator_exception(self, mock_capture):
+        test_exception = ValueError("Test exception")
+
+        def check_context_on_capture(exception, **kwargs):
+            # Assert tags are available when capture_exception is called
+            current_tags = get_tags()
+            assert current_tags.get("important_context") == "value"
+
+        mock_capture.side_effect = check_context_on_capture
+
+        @scoped()
+        def failing_function():
+            tag("important_context", "value")
+            raise test_exception
+
+        # Function should raise the exception
+        with self.assertRaises(ValueError):
+            failing_function()
+
+        # Verify capture_exception was called
+        mock_capture.assert_called_once_with(test_exception)
+
+        # Context should be cleared after function execution
+        assert get_tags() == {}
+
+    @patch("posthog.capture_exception")
+    def test_new_context_exception_handling(self, mock_capture):
+        test_exception = RuntimeError("Context exception")
+
+        def check_context_on_capture(exception, **kwargs):
+            # Assert inner context tags are available when capture_exception is called
+            current_tags = get_tags()
+            assert current_tags.get("inner_context") == "inner_value"
+
+        mock_capture.side_effect = check_context_on_capture
+
+        # Set up outer context
+        with new_context():
+            tag("outer_context", "outer_value")
+
+            try:
+                with new_context():
+                    tag("inner_context", "inner_value")
+                    raise test_exception
+            except RuntimeError:
+                pass  # Expected exception
+
+            # Outer context should still be intact
+            assert get_tags()["outer_context"] == "outer_value"
+
+        # Verify capture_exception was called
+        mock_capture.assert_called_once_with(test_exception)
+
+    def test_identify_context(self):
+        with new_context(fresh=True):
+            # Initially no distinct ID
+            assert get_context_distinct_id() is None
+
+            # Set distinct ID
+            identify_context("user123")
+            assert get_context_distinct_id() == "user123"
+
+    def test_set_context_session(self):
+        with new_context(fresh=True):
+            # Initially no session ID
+            assert get_context_session_id() is None
+
+            # Set session ID
+            set_context_session("session456")
+            assert get_context_session_id() == "session456"
+
+    def test_context_inheritance_fresh_context(self):
+        with new_context(fresh=True):
+            identify_context("user123")
+            set_context_session("session456")
+
+            with new_context(fresh=True):
+                # Fresh context should not inherit
+                assert get_context_distinct_id() is None
+                assert get_context_session_id() is None
+
+            # Original context should still have values
+            assert get_context_distinct_id() == "user123"
+            assert get_context_session_id() == "session456"
+
+    def test_context_inheritance_non_fresh_context(self):
+        with new_context(fresh=True):
+            identify_context("user123")
+            set_context_session("session456")
+
+            with new_context(fresh=False):
+                # Non-fresh context should inherit
+                assert get_context_distinct_id() == "user123"
+                assert get_context_session_id() == "session456"
+
+                # Override in child context
+                identify_context("user789")
+                set_context_session("session999")
+                assert get_context_distinct_id() == "user789"
+                assert get_context_session_id() == "session999"
+
+            # Original context should still have original values
+            assert get_context_distinct_id() == "user123"
+            assert get_context_session_id() == "session456"
+
+    def test_scoped_decorator_with_context_ids(self):
+        @scoped()
+        def function_with_context():
+            identify_context("user456")
+            set_context_session("session789")
+            return get_context_distinct_id(), get_context_session_id()
+
+        distinct_id, session_id = function_with_context()
+        assert distinct_id == "user456"
+        assert session_id == "session789"
+
+        # Context should be cleared after function execution
+        assert get_context_distinct_id() is None
+        assert get_context_session_id() is None

posthog/test/test_exception_capture.py

@@ -32,32 +32,3 @@ def test_excepthook(tmpdir):
         b'"$exception_list": [{"mechanism": {"type": "generic", "handled": true}, "module": null, "type": "ZeroDivisionError", "value": "division by zero", "stacktrace": {"frames": [{"platform": "python", "filename": "app.py", "abs_path"'
         in output
     )
-
-
-def test_trying_to_use_django_integration(tmpdir):
-    app = tmpdir.join("app.py")
-    app.write(
-        dedent(
-            """
-    from posthog import Posthog, Integrations
-    posthog = Posthog('phc_x', host='https://eu.i.posthog.com', enable_exception_autocapture=True, exception_autocapture_integrations=[Integrations.Django], debug=True, on_error=lambda e, batch: print('error handling batch: ', e, batch))
-
-    # frame_value = "LOL"
-
-    1/0
-    """
-        )
-    )
-
-    with pytest.raises(subprocess.CalledProcessError) as excinfo:
-        subprocess.check_output([sys.executable, str(app)], stderr=subprocess.STDOUT)
-
-    output = excinfo.value.output
-
-    assert b"ZeroDivisionError" in output
-    assert b"LOL" in output
-    assert b"DEBUG:posthog:data uploaded successfully" in output
-    assert (
-        b'"$exception_list": [{"mechanism": {"type": "generic", "handled": true}, "module": null, "type": "ZeroDivisionError", "value": "division by zero", "stacktrace": {"frames": [{"platform": "python", "filename": "app.py", "abs_path"'
-        in output
-    )

posthog/test/test_feature_flag.py

@@ -0,0 +1,189 @@
+import unittest
+
+from posthog.types import FeatureFlag, FlagMetadata, FlagReason, LegacyFlagMetadata
+
+
+class TestFeatureFlag(unittest.TestCase):
+    def test_feature_flag_from_json(self):
+        # Test with full metadata
+        resp = {
+            "key": "test-flag",
+            "enabled": True,
+            "variant": "test-variant",
+            "reason": {
+                "code": "matched_condition",
+                "condition_index": 0,
+                "description": "Matched condition set 1",
+            },
+            "metadata": {
+                "id": 1,
+                "payload": '{"some": "json"}',
+                "version": 2,
+                "description": "test-description",
+            },
+        }
+
+        flag = FeatureFlag.from_json(resp)
+        self.assertEqual(flag.key, "test-flag")
+        self.assertTrue(flag.enabled)
+        self.assertEqual(flag.variant, "test-variant")
+        self.assertEqual(flag.get_value(), "test-variant")
+        self.assertEqual(
+            flag.reason,
+            FlagReason(
+                code="matched_condition",
+                condition_index=0,
+                description="Matched condition set 1",
+            ),
+        )
+        self.assertEqual(
+            flag.metadata,
+            FlagMetadata(
+                id=1,
+                payload='{"some": "json"}',
+                version=2,
+                description="test-description",
+            ),
+        )
+
+    def test_feature_flag_from_json_minimal(self):
+        # Test with minimal required fields
+        resp = {"key": "test-flag", "enabled": True}
+
+        flag = FeatureFlag.from_json(resp)
+        self.assertEqual(flag.key, "test-flag")
+        self.assertTrue(flag.enabled)
+        self.assertIsNone(flag.variant)
+        self.assertEqual(flag.get_value(), True)
+        self.assertIsNone(flag.reason)
+        self.assertEqual(flag.metadata, LegacyFlagMetadata(payload=None))
+
+    def test_feature_flag_from_json_without_metadata(self):
+        # Test with reason but no metadata
+        resp = {
+            "key": "test-flag",
+            "enabled": True,
+            "variant": "test-variant",
+            "reason": {
+                "code": "matched_condition",
+                "condition_index": 0,
+                "description": "Matched condition set 1",
+            },
+        }
+
+        flag = FeatureFlag.from_json(resp)
+        self.assertEqual(flag.key, "test-flag")
+        self.assertTrue(flag.enabled)
+        self.assertEqual(flag.variant, "test-variant")
+        self.assertEqual(flag.get_value(), "test-variant")
+        self.assertEqual(
+            flag.reason,
+            FlagReason(
+                code="matched_condition",
+                condition_index=0,
+                description="Matched condition set 1",
+            ),
+        )
+        self.assertEqual(flag.metadata, LegacyFlagMetadata(payload=None))
+
+    def test_flag_reason_from_json(self):
+        # Test with complete data
+        resp = {
+            "code": "user_in_segment",
+            "condition_index": 1,
+            "description": "User is in segment 'beta_users'",
+        }
+        reason = FlagReason.from_json(resp)
+        self.assertEqual(reason.code, "user_in_segment")
+        self.assertEqual(reason.condition_index, 1)
+        self.assertEqual(reason.description, "User is in segment 'beta_users'")
+
+        # Test with partial data
+        resp = {"code": "user_in_segment"}
+        reason = FlagReason.from_json(resp)
+        self.assertEqual(reason.code, "user_in_segment")
+        self.assertIsNone(reason.condition_index)  # default value
+        self.assertEqual(reason.description, "")
+
+        # Test with None
+        self.assertIsNone(FlagReason.from_json(None))
+
+    def test_flag_metadata_from_json(self):
+        # Test with complete data
+        resp = {
+            "id": 123,
+            "payload": {"key": "value"},
+            "version": 1,
+            "description": "Test flag",
+        }
+        metadata = FlagMetadata.from_json(resp)
+        self.assertEqual(metadata.id, 123)
+        self.assertEqual(metadata.payload, {"key": "value"})
+        self.assertEqual(metadata.version, 1)
+        self.assertEqual(metadata.description, "Test flag")
+
+        # Test with partial data
+        resp = {"id": 123}
+        metadata = FlagMetadata.from_json(resp)
+        self.assertEqual(metadata.id, 123)
+        self.assertIsNone(metadata.payload)
+        self.assertEqual(metadata.version, 0)  # default value
+        self.assertEqual(metadata.description, "")  # default value
+
+        # Test with None
+        self.assertIsInstance(FlagMetadata.from_json(None), LegacyFlagMetadata)
+
+    def test_feature_flag_from_json_complete(self):
+        # Test with complete data
+        resp = {
+            "key": "test-flag",
+            "enabled": True,
+            "variant": "control",
+            "reason": {
+                "code": "user_in_segment",
+                "condition_index": 1,
+                "description": "User is in segment 'beta_users'",
+            },
+            "metadata": {
+                "id": 123,
+                "payload": {"key": "value"},
+                "version": 1,
+                "description": "Test flag",
+            },
+        }
+        flag = FeatureFlag.from_json(resp)
+        self.assertEqual(flag.key, "test-flag")
+        self.assertTrue(flag.enabled)
+        self.assertEqual(flag.variant, "control")
+        self.assertIsInstance(flag.reason, FlagReason)
+        self.assertEqual(flag.reason.code, "user_in_segment")
+        self.assertIsInstance(flag.metadata, FlagMetadata)
+        self.assertEqual(flag.metadata.id, 123)
+        self.assertEqual(flag.metadata.payload, {"key": "value"})
+
+    def test_feature_flag_from_json_minimal_data(self):
+        # Test with minimal data
+        resp = {"key": "test-flag", "enabled": False}
+        flag = FeatureFlag.from_json(resp)
+        self.assertEqual(flag.key, "test-flag")
+        self.assertFalse(flag.enabled)
+        self.assertIsNone(flag.variant)
+        self.assertIsNone(flag.reason)
+        self.assertIsInstance(flag.metadata, LegacyFlagMetadata)
+        self.assertIsNone(flag.metadata.payload)
+
+    def test_feature_flag_from_json_with_reason(self):
+        # Test with reason but no metadata
+        resp = {
+            "key": "test-flag",
+            "enabled": True,
+            "reason": {"code": "user_in_segment"},
+        }
+        flag = FeatureFlag.from_json(resp)
+        self.assertEqual(flag.key, "test-flag")
+        self.assertTrue(flag.enabled)
+        self.assertIsNone(flag.variant)
+        self.assertIsInstance(flag.reason, FlagReason)
+        self.assertEqual(flag.reason.code, "user_in_segment")
+        self.assertIsInstance(flag.metadata, LegacyFlagMetadata)
+        self.assertIsNone(flag.metadata.payload)

posthog/test/test_feature_flag_result.py

@@ -0,0 +1,444 @@
+import unittest
+
+import mock
+
+from posthog.client import Client
+from posthog.test.test_utils import FAKE_TEST_API_KEY
+from posthog.types import FeatureFlag, FeatureFlagResult, FlagMetadata, FlagReason
+
+
+class TestFeatureFlagResult(unittest.TestCase):
+    def test_from_bool_value_and_payload(self):
+        result = FeatureFlagResult.from_value_and_payload(
+            "test-flag", True, "[1, 2, 3]"
+        )
+
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.enabled, True)
+        self.assertEqual(result.variant, None)
+        self.assertEqual(result.payload, [1, 2, 3])
+
+    def test_from_false_value_and_payload(self):
+        result = FeatureFlagResult.from_value_and_payload(
+            "test-flag", False, '{"some": "value"}'
+        )
+
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.enabled, False)
+        self.assertEqual(result.variant, None)
+        self.assertEqual(result.payload, {"some": "value"})
+
+    def test_from_variant_value_and_payload(self):
+        result = FeatureFlagResult.from_value_and_payload(
+            "test-flag", "control", "true"
+        )
+
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.enabled, True)
+        self.assertEqual(result.variant, "control")
+        self.assertEqual(result.payload, True)
+
+    def test_from_none_value_and_payload(self):
+        result = FeatureFlagResult.from_value_and_payload(
+            "test-flag", None, '{"some": "value"}'
+        )
+        self.assertIsNone(result)
+
+    def test_from_boolean_flag_details(self):
+        flag_details = FeatureFlag(
+            key="test-flag",
+            enabled=True,
+            variant=None,
+            metadata=FlagMetadata(
+                id=1, version=1, description="test-flag", payload='"Some string"'
+            ),
+            reason=FlagReason(
+                code="test-reason", description="test-reason", condition_index=0
+            ),
+        )
+
+        result = FeatureFlagResult.from_flag_details(flag_details)
+
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.enabled, True)
+        self.assertEqual(result.variant, None)
+        self.assertEqual(result.payload, "Some string")
+
+    def test_from_boolean_flag_details_with_override_variant_match_value(self):
+        flag_details = FeatureFlag(
+            key="test-flag",
+            enabled=True,
+            variant=None,
+            metadata=FlagMetadata(
+                id=1, version=1, description="test-flag", payload='"Some string"'
+            ),
+            reason=FlagReason(
+                code="test-reason", description="test-reason", condition_index=0
+            ),
+        )
+
+        result = FeatureFlagResult.from_flag_details(
+            flag_details, override_match_value="control"
+        )
+
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.enabled, True)
+        self.assertEqual(result.variant, "control")
+        self.assertEqual(result.payload, "Some string")
+
+    def test_from_boolean_flag_details_with_override_boolean_match_value(self):
+        flag_details = FeatureFlag(
+            key="test-flag",
+            enabled=True,
+            variant="control",
+            metadata=FlagMetadata(
+                id=1, version=1, description="test-flag", payload='{"some": "value"}'
+            ),
+            reason=FlagReason(
+                code="test-reason", description="test-reason", condition_index=0
+            ),
+        )
+
+        result = FeatureFlagResult.from_flag_details(
+            flag_details, override_match_value=True
+        )
+
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.enabled, True)
+        self.assertEqual(result.variant, None)
+        self.assertEqual(result.payload, {"some": "value"})
+
+    def test_from_boolean_flag_details_with_override_false_match_value(self):
+        flag_details = FeatureFlag(
+            key="test-flag",
+            enabled=True,
+            variant="control",
+            metadata=FlagMetadata(
+                id=1, version=1, description="test-flag", payload='{"some": "value"}'
+            ),
+            reason=FlagReason(
+                code="test-reason", description="test-reason", condition_index=0
+            ),
+        )
+
+        result = FeatureFlagResult.from_flag_details(
+            flag_details, override_match_value=False
+        )
+
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.enabled, False)
+        self.assertEqual(result.variant, None)
+        self.assertEqual(result.payload, {"some": "value"})
+
+    def test_from_variant_flag_details(self):
+        flag_details = FeatureFlag(
+            key="test-flag",
+            enabled=True,
+            variant="control",
+            metadata=FlagMetadata(
+                id=1, version=1, description="test-flag", payload='{"some": "value"}'
+            ),
+            reason=FlagReason(
+                code="test-reason", description="test-reason", condition_index=0
+            ),
+        )
+
+        result = FeatureFlagResult.from_flag_details(flag_details)
+
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.enabled, True)
+        self.assertEqual(result.variant, "control")
+        self.assertEqual(result.payload, {"some": "value"})
+
+    def test_from_none_flag_details(self):
+        result = FeatureFlagResult.from_flag_details(None)
+
+        self.assertIsNone(result)
+
+    def test_from_flag_details_with_none_payload(self):
+        flag_details = FeatureFlag(
+            key="test-flag",
+            enabled=True,
+            variant=None,
+            metadata=FlagMetadata(
+                id=1, version=1, description="test-flag", payload=None
+            ),
+            reason=FlagReason(
+                code="test-reason", description="test-reason", condition_index=0
+            ),
+        )
+
+        result = FeatureFlagResult.from_flag_details(flag_details)
+
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.enabled, True)
+        self.assertEqual(result.variant, None)
+        self.assertIsNone(result.payload)
+
+
+class TestGetFeatureFlagResult(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        # This ensures no real HTTP POST requests are made
+        cls.capture_patch = mock.patch.object(Client, "capture")
+        cls.capture_patch.start()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.capture_patch.stop()
+
+    def set_fail(self, e, batch):
+        """Mark the failure handler"""
+        print("FAIL", e, batch)  # noqa: T201
+        self.failed = True
+
+    def setUp(self):
+        self.failed = False
+        self.client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail)
+
+    @mock.patch.object(Client, "capture")
+    def test_get_feature_flag_result_boolean_local_evaluation(self, patch_capture):
+        basic_flag = {
+            "id": 1,
+            "name": "Beta Feature",
+            "key": "person-flag",
+            "active": True,
+            "filters": {
+                "groups": [
+                    {
+                        "properties": [
+                            {
+                                "key": "region",
+                                "operator": "exact",
+                                "value": ["USA"],
+                                "type": "person",
+                            }
+                        ],
+                        "rollout_percentage": 100,
+                    }
+                ],
+                "payloads": {"true": "300"},
+            },
+        }
+        self.client.feature_flags = [basic_flag]
+
+        flag_result = self.client.get_feature_flag_result(
+            "person-flag", "some-distinct-id", person_properties={"region": "USA"}
+        )
+        self.assertEqual(flag_result.enabled, True)
+        self.assertEqual(flag_result.variant, None)
+        self.assertEqual(flag_result.payload, 300)
+        patch_capture.assert_called_with(
+            "$feature_flag_called",
+            distinct_id="some-distinct-id",
+            properties={
+                "$feature_flag": "person-flag",
+                "$feature_flag_response": True,
+                "locally_evaluated": True,
+                "$feature/person-flag": True,
+                "$feature_flag_payload": 300,
+            },
+            groups={},
+            disable_geoip=None,
+        )
+
+    @mock.patch.object(Client, "capture")
+    def test_get_feature_flag_result_variant_local_evaluation(self, patch_capture):
+        basic_flag = {
+            "id": 1,
+            "name": "Beta Feature",
+            "key": "person-flag",
+            "active": True,
+            "filters": {
+                "groups": [
+                    {
+                        "properties": [
+                            {
+                                "key": "region",
+                                "operator": "exact",
+                                "value": ["USA"],
+                                "type": "person",
+                            }
+                        ],
+                        "rollout_percentage": 100,
+                    }
+                ],
+                "multivariate": {
+                    "variants": [
+                        {"key": "variant-1", "rollout_percentage": 50},
+                        {"key": "variant-2", "rollout_percentage": 50},
+                    ]
+                },
+                "payloads": {"variant-1": '{"some": "value"}'},
+            },
+        }
+        self.client.feature_flags = [basic_flag]
+
+        flag_result = self.client.get_feature_flag_result(
+            "person-flag", "distinct_id", person_properties={"region": "USA"}
+        )
+        self.assertEqual(flag_result.enabled, True)
+        self.assertEqual(flag_result.variant, "variant-1")
+        self.assertEqual(flag_result.get_value(), "variant-1")
+        self.assertEqual(flag_result.payload, {"some": "value"})
+
+        patch_capture.assert_called_with(
+            "$feature_flag_called",
+            distinct_id="distinct_id",
+            properties={
+                "$feature_flag": "person-flag",
+                "$feature_flag_response": "variant-1",
+                "locally_evaluated": True,
+                "$feature/person-flag": "variant-1",
+                "$feature_flag_payload": {"some": "value"},
+            },
+            groups={},
+            disable_geoip=None,
+        )
+
+        another_flag_result = self.client.get_feature_flag_result(
+            "person-flag", "another-distinct-id", person_properties={"region": "USA"}
+        )
+        self.assertEqual(another_flag_result.enabled, True)
+        self.assertEqual(another_flag_result.variant, "variant-2")
+        self.assertEqual(another_flag_result.get_value(), "variant-2")
+        self.assertIsNone(another_flag_result.payload)
+
+        patch_capture.assert_called_with(
+            "$feature_flag_called",
+            distinct_id="another-distinct-id",
+            properties={
+                "$feature_flag": "person-flag",
+                "$feature_flag_response": "variant-2",
+                "locally_evaluated": True,
+                "$feature/person-flag": "variant-2",
+            },
+            groups={},
+            disable_geoip=None,
+        )
+
+    @mock.patch("posthog.client.flags")
+    @mock.patch.object(Client, "capture")
+    def test_get_feature_flag_result_boolean_decide(self, patch_capture, patch_flags):
+        patch_flags.return_value = {
+            "flags": {
+                "person-flag": {
+                    "key": "person-flag",
+                    "enabled": True,
+                    "variant": None,
+                    "reason": {
+                        "description": "Matched condition set 1",
+                    },
+                    "metadata": {
+                        "id": 23,
+                        "version": 42,
+                        "payload": "300",
+                    },
+                },
+            },
+        }
+
+        flag_result = self.client.get_feature_flag_result(
+            "person-flag", "some-distinct-id"
+        )
+        self.assertEqual(flag_result.enabled, True)
+        self.assertEqual(flag_result.variant, None)
+        self.assertEqual(flag_result.payload, 300)
+        patch_capture.assert_called_with(
+            "$feature_flag_called",
+            distinct_id="some-distinct-id",
+            properties={
+                "$feature_flag": "person-flag",
+                "$feature_flag_response": True,
+                "locally_evaluated": False,
+                "$feature/person-flag": True,
+                "$feature_flag_reason": "Matched condition set 1",
+                "$feature_flag_id": 23,
+                "$feature_flag_version": 42,
+                "$feature_flag_payload": 300,
+            },
+            groups={},
+            disable_geoip=None,
+        )
+
+    @mock.patch("posthog.client.flags")
+    @mock.patch.object(Client, "capture")
+    def test_get_feature_flag_result_variant_decide(self, patch_capture, patch_flags):
+        patch_flags.return_value = {
+            "flags": {
+                "person-flag": {
+                    "key": "person-flag",
+                    "enabled": True,
+                    "variant": "variant-1",
+                    "reason": {
+                        "description": "Matched condition set 1",
+                    },
+                    "metadata": {
+                        "id": 1,
+                        "version": 2,
+                        "payload": "[1, 2, 3]",
+                    },
+                },
+            },
+        }
+
+        flag_result = self.client.get_feature_flag_result("person-flag", "distinct_id")
+        self.assertEqual(flag_result.enabled, True)
+        self.assertEqual(flag_result.variant, "variant-1")
+        self.assertEqual(flag_result.get_value(), "variant-1")
+        self.assertEqual(flag_result.payload, [1, 2, 3])
+        patch_capture.assert_called_with(
+            "$feature_flag_called",
+            distinct_id="distinct_id",
+            properties={
+                "$feature_flag": "person-flag",
+                "$feature_flag_response": "variant-1",
+                "locally_evaluated": False,
+                "$feature/person-flag": "variant-1",
+                "$feature_flag_reason": "Matched condition set 1",
+                "$feature_flag_id": 1,
+                "$feature_flag_version": 2,
+                "$feature_flag_payload": [1, 2, 3],
+            },
+            groups={},
+            disable_geoip=None,
+        )
+
+    @mock.patch("posthog.client.flags")
+    @mock.patch.object(Client, "capture")
+    def test_get_feature_flag_result_unknown_flag(self, patch_capture, patch_flags):
+        patch_flags.return_value = {
+            "flags": {
+                "person-flag": {
+                    "key": "person-flag",
+                    "enabled": True,
+                    "variant": None,
+                    "reason": {
+                        "description": "Matched condition set 1",
+                    },
+                    "metadata": {
+                        "id": 23,
+                        "version": 42,
+                        "payload": "300",
+                    },
+                },
+            },
+        }
+
+        flag_result = self.client.get_feature_flag_result(
+            "no-person-flag", "some-distinct-id"
+        )
+
+        self.assertIsNone(flag_result)
+        patch_capture.assert_called_with(
+            "$feature_flag_called",
+            distinct_id="some-distinct-id",
+            properties={
+                "$feature_flag": "no-person-flag",
+                "$feature_flag_response": None,
+                "locally_evaluated": False,
+                "$feature/no-person-flag": None,
+            },
+            groups={},
+            disable_geoip=None,
+        )

posthog/test/test_module.py

@@ -7,15 +7,16 @@ class TestModule(unittest.TestCase):
     posthog = None
 
     def _assert_enqueue_result(self, result):
-        self.assertEqual(type(result[0]), bool)
-        self.assertEqual(type(result[1]), dict)
+        self.assertEqual(type(result[0]), str)
 
     def failed(self):
         self.failed = True
 
     def setUp(self):
         self.failed = False
-        self.posthog = Posthog("testsecret", host="http://localhost:8000", on_error=self.failed)
+        self.posthog = Posthog(
+            "testsecret", host="http://localhost:8000", on_error=self.failed
+        )
 
     def test_no_api_key(self):
         self.posthog.api_key = None
@@ -26,12 +27,7 @@ class TestModule(unittest.TestCase):
         self.assertRaises(Exception, self.posthog.capture)
 
     def test_track(self):
-        res = self.posthog.capture("distinct_id", "python module event")
-        self._assert_enqueue_result(res)
-        self.posthog.flush()
-
-    def test_identify(self):
-        res = self.posthog.identify("distinct_id", {"email": "user@email.com"})
+        res = self.posthog.capture("python module event", distinct_id="distinct_id")
         self._assert_enqueue_result(res)
         self.posthog.flush()
 
@@ -40,9 +36,5 @@ class TestModule(unittest.TestCase):
         self._assert_enqueue_result(res)
         self.posthog.flush()
 
-    def test_page(self):
-        self.posthog.page("distinct_id", "https://posthog.com/contact")
-        self.posthog.flush()
-
     def test_flush(self):
         self.posthog.flush()

posthog/test/test_request.py

@@ -2,23 +2,39 @@ import json
 import unittest
 from datetime import date, datetime
 
+import mock
 import pytest
 import requests
 
-from posthog.request import DatetimeSerializer, batch_post, determine_server_host
+from posthog.request import (
+    DatetimeSerializer,
+    QuotaLimitError,
+    batch_post,
+    decide,
+    determine_server_host,
+)
 from posthog.test.test_utils import TEST_API_KEY
 
 
 class TestRequests(unittest.TestCase):
     def test_valid_request(self):
-        res = batch_post(TEST_API_KEY, batch=[{"distinct_id": "distinct_id", "event": "python event", "type": "track"}])
+        res = batch_post(
+            TEST_API_KEY,
+            batch=[
+                {"distinct_id": "distinct_id", "event": "python event", "type": "track"}
+            ],
+        )
         self.assertEqual(res.status_code, 200)
 
     def test_invalid_request_error(self):
-        self.assertRaises(Exception, batch_post, "testsecret", "https://t.posthog.com", False, "[{]")
+        self.assertRaises(
+            Exception, batch_post, "testsecret", "https://t.posthog.com", False, "[{]"
+        )
 
     def test_invalid_host(self):
-        self.assertRaises(Exception, batch_post, "testsecret", "t.posthog.com/", batch=[])
+        self.assertRaises(
+            Exception, batch_post, "testsecret", "t.posthog.com/", batch=[]
+        )
 
     def test_datetime_serialization(self):
         data = {"created": datetime(2012, 3, 4, 5, 6, 7, 891011)}
@@ -34,16 +50,62 @@ class TestRequests(unittest.TestCase):
 
     def test_should_not_timeout(self):
         res = batch_post(
-            TEST_API_KEY, batch=[{"distinct_id": "distinct_id", "event": "python event", "type": "track"}], timeout=15
+            TEST_API_KEY,
+            batch=[
+                {"distinct_id": "distinct_id", "event": "python event", "type": "track"}
+            ],
+            timeout=15,
         )
         self.assertEqual(res.status_code, 200)
 
     def test_should_timeout(self):
         with self.assertRaises(requests.ReadTimeout):
             batch_post(
-                "key", batch=[{"distinct_id": "distinct_id", "event": "python event", "type": "track"}], timeout=0.0001
+                "key",
+                batch=[
+                    {
+                        "distinct_id": "distinct_id",
+                        "event": "python event",
+                        "type": "track",
+                    }
+                ],
+                timeout=0.0001,
             )
 
+    def test_quota_limited_response(self):
+        mock_response = requests.Response()
+        mock_response.status_code = 200
+        mock_response._content = json.dumps(
+            {
+                "quotaLimited": ["feature_flags"],
+                "featureFlags": {},
+                "featureFlagPayloads": {},
+                "errorsWhileComputingFlags": False,
+            }
+        ).encode("utf-8")
+
+        with mock.patch("posthog.request._session.post", return_value=mock_response):
+            with self.assertRaises(QuotaLimitError) as cm:
+                decide("fake_key", "fake_host")
+
+            self.assertEqual(cm.exception.status, 200)
+            self.assertEqual(cm.exception.message, "Feature flags quota limited")
+
+    def test_normal_decide_response(self):
+        mock_response = requests.Response()
+        mock_response.status_code = 200
+        mock_response._content = json.dumps(
+            {
+                "featureFlags": {"flag1": True},
+                "featureFlagPayloads": {},
+                "errorsWhileComputingFlags": False,
+            }
+        ).encode("utf-8")
+
+        with mock.patch("posthog.request._session.post", return_value=mock_response):
+            response = decide("fake_key", "fake_host")
+            self.assertEqual(response["featureFlags"], {"flag1": True})
+
 
 @pytest.mark.parametrize(
     "host, expected",

posthog/test/test_size_limited_dict.py

@@ -0,0 +1,24 @@
+import unittest
+
+from parameterized import parameterized
+
+from posthog import utils
+
+
+class TestSizeLimitedDict(unittest.TestCase):
+    @parameterized.expand([(10, 100), (5, 20), (20, 200)])
+    def test_size_limited_dict(self, size: int, iterations: int) -> None:
+        values = utils.SizeLimitedDict(size, lambda _: -1)
+
+        for i in range(iterations):
+            values[i] = i
+
+            assert values[i] == i
+            assert len(values) == i % size + 1
+
+            if i % size == 0:
+                # old numbers should've been removed
+                self.assertIsNone(values.get(i - 1))
+                self.assertIsNone(values.get(i - 3))
+                self.assertIsNone(values.get(i - 5))
+                self.assertIsNone(values.get(i - 9))

posthog/test/test_types.py

@@ -0,0 +1,208 @@
+import unittest
+
+from parameterized import parameterized
+
+from posthog.types import (
+    FeatureFlag,
+    FlagMetadata,
+    FlagReason,
+    LegacyFlagMetadata,
+    normalize_flags_response,
+    to_flags_and_payloads,
+)
+
+
+class TestTypes(unittest.TestCase):
+    @parameterized.expand([(True,), (False,)])
+    def test_normalize_decide_response_v4(self, has_errors: bool):
+        resp = {
+            "flags": {
+                "my-flag": FeatureFlag(
+                    key="my-flag",
+                    enabled=True,
+                    variant="test-variant",
+                    reason=FlagReason(
+                        code="matched_condition",
+                        condition_index=0,
+                        description="Matched condition set 1",
+                    ),
+                    metadata=FlagMetadata(
+                        id=1,
+                        payload='{"some": "json"}',
+                        version=2,
+                        description="test-description",
+                    ),
+                )
+            },
+            "errorsWhileComputingFlags": has_errors,
+            "requestId": "test-id",
+        }
+
+        result = normalize_flags_response(resp)
+
+        flag = result["flags"]["my-flag"]
+        self.assertEqual(flag.key, "my-flag")
+        self.assertTrue(flag.enabled)
+        self.assertEqual(flag.variant, "test-variant")
+        self.assertEqual(flag.get_value(), "test-variant")
+        self.assertEqual(
+            flag.reason,
+            FlagReason(
+                code="matched_condition",
+                condition_index=0,
+                description="Matched condition set 1",
+            ),
+        )
+        self.assertEqual(
+            flag.metadata,
+            FlagMetadata(
+                id=1,
+                payload='{"some": "json"}',
+                version=2,
+                description="test-description",
+            ),
+        )
+        self.assertEqual(result["errorsWhileComputingFlags"], has_errors)
+        self.assertEqual(result["requestId"], "test-id")
+
+    def test_normalize_decide_response_legacy(self):
+        # Test legacy response format with "featureFlags" and "featureFlagPayloads"
+        resp = {
+            "featureFlags": {"my-flag": "test-variant"},
+            "featureFlagPayloads": {"my-flag": '{"some": "json-payload"}'},
+            "errorsWhileComputingFlags": False,
+            "requestId": "test-id",
+        }
+
+        result = normalize_flags_response(resp)
+
+        flag = result["flags"]["my-flag"]
+        self.assertEqual(flag.key, "my-flag")
+        self.assertTrue(flag.enabled)
+        self.assertEqual(flag.variant, "test-variant")
+        self.assertEqual(flag.get_value(), "test-variant")
+        self.assertIsNone(flag.reason)
+        self.assertEqual(
+            flag.metadata, LegacyFlagMetadata(payload='{"some": "json-payload"}')
+        )
+        self.assertFalse(result["errorsWhileComputingFlags"])
+        self.assertEqual(result["requestId"], "test-id")
+        # Verify legacy fields are removed
+        self.assertNotIn("featureFlags", result)
+        self.assertNotIn("featureFlagPayloads", result)
+
+    def test_normalize_decide_response_boolean_flag(self):
+        # Test legacy response with boolean flag
+        resp = {"featureFlags": {"my-flag": True}, "errorsWhileComputingFlags": False}
+
+        result = normalize_flags_response(resp)
+
+        self.assertIn("requestId", result)
+        self.assertIsNone(result["requestId"])
+
+        flag = result["flags"]["my-flag"]
+        self.assertEqual(flag.key, "my-flag")
+        self.assertTrue(flag.enabled)
+        self.assertIsNone(flag.variant)
+        self.assertIsNone(flag.reason)
+        self.assertEqual(flag.metadata, LegacyFlagMetadata(payload=None))
+        self.assertFalse(result["errorsWhileComputingFlags"])
+        self.assertNotIn("featureFlags", result)
+        self.assertNotIn("featureFlagPayloads", result)
+
+    def test_to_flags_and_payloads_v4(self):
+        # Test v4 response format
+        resp = {
+            "flags": {
+                "my-variant-flag": FeatureFlag(
+                    key="my-variant-flag",
+                    enabled=True,
+                    variant="test-variant",
+                    reason=FlagReason(
+                        code="matched_condition",
+                        condition_index=0,
+                        description="Matched condition set 1",
+                    ),
+                    metadata=FlagMetadata(
+                        id=1,
+                        payload='{"some": "json"}',
+                        version=2,
+                        description="test-description",
+                    ),
+                ),
+                "my-boolean-flag": FeatureFlag(
+                    key="my-boolean-flag",
+                    enabled=True,
+                    variant=None,
+                    reason=FlagReason(
+                        code="matched_condition",
+                        condition_index=0,
+                        description="Matched condition set 1",
+                    ),
+                    metadata=FlagMetadata(
+                        id=1, payload=None, version=2, description="test-description"
+                    ),
+                ),
+                "disabled-flag": FeatureFlag(
+                    key="disabled-flag",
+                    enabled=False,
+                    variant=None,
+                    reason=None,
+                    metadata=LegacyFlagMetadata(payload=None),
+                ),
+            },
+            "errorsWhileComputingFlags": False,
+            "requestId": "test-id",
+        }
+
+        result = to_flags_and_payloads(resp)
+
+        self.assertEqual(result["featureFlags"]["my-variant-flag"], "test-variant")
+        self.assertEqual(result["featureFlags"]["my-boolean-flag"], True)
+        self.assertEqual(result["featureFlags"]["disabled-flag"], False)
+        self.assertEqual(
+            result["featureFlagPayloads"]["my-variant-flag"], '{"some": "json"}'
+        )
+        self.assertNotIn("my-boolean-flag", result["featureFlagPayloads"])
+        self.assertNotIn("disabled-flag", result["featureFlagPayloads"])
+
+    def test_to_flags_and_payloads_empty(self):
+        # Test empty response
+        resp = {
+            "flags": {},
+            "errorsWhileComputingFlags": False,
+            "requestId": "test-id",
+        }
+
+        result = to_flags_and_payloads(resp)
+
+        self.assertEqual(result["featureFlags"], {})
+        self.assertEqual(result["featureFlagPayloads"], {})
+
+    def test_to_flags_and_payloads_with_payload(self):
+        resp = {
+            "flags": {
+                "decide-flag": {
+                    "key": "decide-flag",
+                    "enabled": True,
+                    "variant": "decide-variant",
+                    "reason": {
+                        "code": "matched_condition",
+                        "condition_index": 0,
+                        "description": "Matched condition set 1",
+                    },
+                    "metadata": {
+                        "id": 23,
+                        "version": 42,
+                        "payload": '{"foo": "bar"}',
+                    },
+                }
+            },
+            "requestId": "18043bf7-9cf6-44cd-b959-9662ee20d371",
+        }
+
+        normalized = normalize_flags_response(resp)
+        result = to_flags_and_payloads(normalized)
+
+        self.assertEqual(result["featureFlags"]["decide-flag"], "decide-variant")
+        self.assertEqual(result["featureFlagPayloads"]["decide-flag"], '{"foo": "bar"}')

posthog/test/test_utils.py

@@ -1,4 +1,6 @@
+import time
 import unittest
+from dataclasses import dataclass
 from datetime import date, datetime, timedelta
 from decimal import Decimal
 from typing import Optional
@@ -6,27 +8,41 @@ from uuid import UUID
 
 import six
 from dateutil.tz import tzutc
+from parameterized import parameterized
 from pydantic import BaseModel
 from pydantic.v1 import BaseModel as BaseModelV1
 
 from posthog import utils
+from posthog.types import FeatureFlagResult
 
 TEST_API_KEY = "kOOlRy2QlMY9jHZQv0bKz0FZyazBUoY8Arj0lFVNjs4"
 FAKE_TEST_API_KEY = "random_key"
 
 
 class TestUtils(unittest.TestCase):
+    @parameterized.expand(
+        [
+            ("naive datetime should be naive", True),
+            ("timezone-aware datetime should not be naive", False),
+        ]
+    )
+    def test_is_naive(self, _name: str, expected_naive: bool):
+        if expected_naive:
+            dt = datetime.now()  # naive datetime
+        else:
+            dt = datetime.now(tz=tzutc())  # timezone-aware datetime
+
+        assert utils.is_naive(dt) is expected_naive
+
     def test_timezone_utils(self):
         now = datetime.now()
         utcnow = datetime.now(tz=tzutc())
-        self.assertTrue(utils.is_naive(now))
-        self.assertFalse(utils.is_naive(utcnow))
 
         fixed = utils.guess_timezone(now)
-        self.assertFalse(utils.is_naive(fixed))
+        assert utils.is_naive(fixed) is False
 
         shouldnt_be_edited = utils.guess_timezone(utcnow)
-        self.assertEqual(utcnow, shouldnt_be_edited)
+        assert utcnow == shouldnt_be_edited
 
     def test_clean(self):
         simple = {
@@ -53,36 +69,40 @@ class TestUtils(unittest.TestCase):
         pre_clean_keys = combined.keys()
 
         utils.clean(combined)
-        self.assertEqual(combined.keys(), pre_clean_keys)
+        assert combined.keys() == pre_clean_keys
 
         # test UUID separately, as the UUID object doesn't equal its string representation according to Python
-        self.assertEqual(utils.clean(UUID("12345678123456781234567812345678")), "12345678-1234-5678-1234-567812345678")
+        assert (
+            utils.clean(UUID("12345678123456781234567812345678"))
+            == "12345678-1234-5678-1234-567812345678"
+        )
 
     def test_clean_with_dates(self):
         dict_with_dates = {
             "birthdate": date(1980, 1, 1),
-            "registration": datetime.utcnow(),
+            "registration": datetime.now(tz=tzutc()),
         }
-        self.assertEqual(dict_with_dates, utils.clean(dict_with_dates))
+        assert dict_with_dates == utils.clean(dict_with_dates)
 
     def test_bytes(self):
-        if six.PY3:
-            item = bytes(10)
-        else:
-            item = bytearray(10)
-
+        item = bytes(10)
         utils.clean(item)
+        assert utils.clean(item) == "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
 
     def test_clean_fn(self):
         cleaned = utils.clean({"fn": lambda x: x, "number": 4})
-        self.assertEqual(cleaned["number"], 4)
-        # TODO: fixme, different behavior on python 2 and 3
-        if "fn" in cleaned:
-            self.assertEqual(cleaned["fn"], None)
+        assert cleaned == {"fn": None, "number": 4}
 
-    def test_remove_slash(self):
-        self.assertEqual("http://posthog.io", utils.remove_trailing_slash("http://posthog.io/"))
-        self.assertEqual("http://posthog.io", utils.remove_trailing_slash("http://posthog.io"))
+    @parameterized.expand(
+        [
+            ("http://posthog.io/", "http://posthog.io"),
+            ("http://posthog.io", "http://posthog.io"),
+            ("https://example.com/path/", "https://example.com/path"),
+            ("https://example.com/path", "https://example.com/path"),
+        ]
+    )
+    def test_remove_slash(self, input_url, expected_url):
+        assert expected_url == utils.remove_trailing_slash(input_url)
 
     def test_clean_pydantic(self):
         class ModelV2(BaseModel):
@@ -97,34 +117,182 @@ class TestUtils(unittest.TestCase):
         class NestedModel(BaseModel):
             foo: ModelV2
 
-        self.assertEqual(utils.clean(ModelV2(foo="1", bar=2)), {"foo": "1", "bar": 2, "baz": None})
-        self.assertEqual(utils.clean(ModelV1(foo=1, bar="2")), {"foo": 1, "bar": "2"})
-        self.assertEqual(
-            utils.clean(NestedModel(foo=ModelV2(foo="1", bar=2, baz="3"))), {"foo": {"foo": "1", "bar": 2, "baz": "3"}}
+        assert utils.clean(ModelV2(foo="1", bar=2)) == {
+            "foo": "1",
+            "bar": 2,
+            "baz": None,
+        }
+        assert utils.clean(ModelV1(foo=1, bar="2")) == {"foo": 1, "bar": "2"}
+        assert utils.clean(NestedModel(foo=ModelV2(foo="1", bar=2, baz="3"))) == {
+            "foo": {"foo": "1", "bar": 2, "baz": "3"}
+        }
+
+    def test_clean_pydantic_like_class(self) -> None:
+        class Dummy:
+            def model_dump(self, required_param: str) -> dict:
+                return {}
+
+        # previously python 2 code would cause an error while cleaning,
+        # and this entire object would be None, and we would log an error
+        # let's allow ourselves to clean `Dummy` as None,
+        # without blatting the `test` key
+        assert utils.clean({"test": Dummy()}) == {"test": None}
+
+    def test_clean_dataclass(self):
+        @dataclass
+        class InnerDataClass:
+            inner_foo: str
+            inner_bar: int
+            inner_uuid: UUID
+            inner_date: datetime
+            inner_optional: Optional[str] = None
+
+        @dataclass
+        class TestDataClass:
+            foo: str
+            bar: int
+            nested: InnerDataClass
+
+        assert utils.clean(
+            TestDataClass(
+                foo="1",
+                bar=2,
+                nested=InnerDataClass(
+                    inner_foo="3",
+                    inner_bar=4,
+                    inner_uuid=UUID("12345678123456781234567812345678"),
+                    inner_date=datetime(2025, 1, 1),
+                ),
+            )
+        ) == {
+            "foo": "1",
+            "bar": 2,
+            "nested": {
+                "inner_foo": "3",
+                "inner_bar": 4,
+                "inner_uuid": "12345678-1234-5678-1234-567812345678",
+                "inner_date": datetime(2025, 1, 1),
+                "inner_optional": None,
+            },
+        }
+
+
+class TestFlagCache(unittest.TestCase):
+    def setUp(self):
+        self.cache = utils.FlagCache(max_size=3, default_ttl=1)
+        self.flag_result = FeatureFlagResult.from_value_and_payload(
+            "test-flag", True, None
         )
 
-        class Dummy:
-            def model_dump(self, required_param):
-                pass
+    def test_cache_basic_operations(self):
+        distinct_id = "user123"
+        flag_key = "test-flag"
+        flag_version = 1
 
-        # Skips a class with a defined non-Pydantic `model_dump` method.
-        self.assertEqual(utils.clean({"test": Dummy()}), {})
+        # Test cache miss
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is None
 
+        # Test cache set and hit
+        self.cache.set_cached_flag(
+            distinct_id, flag_key, self.flag_result, flag_version
+        )
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is not None
+        assert result.get_value()
 
-class TestSizeLimitedDict(unittest.TestCase):
-    def test_size_limited_dict(self):
-        size = 10
-        values = utils.SizeLimitedDict(size, lambda _: -1)
+    def test_cache_ttl_expiration(self):
+        distinct_id = "user123"
+        flag_key = "test-flag"
+        flag_version = 1
 
-        for i in range(100):
-            values[i] = i
+        # Set flag in cache
+        self.cache.set_cached_flag(
+            distinct_id, flag_key, self.flag_result, flag_version
+        )
 
-            self.assertEqual(values[i], i)
-            self.assertEqual(len(values), i % size + 1)
+        # Should be available immediately
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is not None
 
-            if i % size == 0:
-                # old numbers should've been removed
-                self.assertIsNone(values.get(i - 1))
-                self.assertIsNone(values.get(i - 3))
-                self.assertIsNone(values.get(i - 5))
-                self.assertIsNone(values.get(i - 9))
+        # Wait for TTL to expire (1 second + buffer)
+        time.sleep(1.1)
+
+        # Should be expired
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is None
+
+    def test_cache_version_invalidation(self):
+        distinct_id = "user123"
+        flag_key = "test-flag"
+        old_version = 1
+        new_version = 2
+
+        # Set flag with old version
+        self.cache.set_cached_flag(distinct_id, flag_key, self.flag_result, old_version)
+
+        # Should hit with old version
+        result = self.cache.get_cached_flag(distinct_id, flag_key, old_version)
+        assert result is not None
+
+        # Should miss with new version
+        result = self.cache.get_cached_flag(distinct_id, flag_key, new_version)
+        assert result is None
+
+        # Invalidate old version
+        self.cache.invalidate_version(old_version)
+
+        # Should miss even with old version after invalidation
+        result = self.cache.get_cached_flag(distinct_id, flag_key, old_version)
+        assert result is None
+
+    def test_stale_cache_functionality(self):
+        distinct_id = "user123"
+        flag_key = "test-flag"
+        flag_version = 1
+
+        # Set flag in cache
+        self.cache.set_cached_flag(
+            distinct_id, flag_key, self.flag_result, flag_version
+        )
+
+        # Wait for TTL to expire
+        time.sleep(1.1)
+
+        # Should not get fresh cache
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is None
+
+        # Should get stale cache (within 1 hour default)
+        stale_result = self.cache.get_stale_cached_flag(distinct_id, flag_key)
+        assert stale_result is not None
+        assert stale_result.get_value()
+
+    def test_lru_eviction(self):
+        # Cache has max_size=3, so adding 4 users should evict the LRU one
+        flag_version = 1
+
+        # Add 3 users
+        for i in range(3):
+            user_id = f"user{i}"
+            self.cache.set_cached_flag(
+                user_id, "test-flag", self.flag_result, flag_version
+            )
+
+        # Access user0 to make it recently used
+        self.cache.get_cached_flag("user0", "test-flag", flag_version)
+
+        # Add 4th user, should evict user1 (least recently used)
+        self.cache.set_cached_flag("user3", "test-flag", self.flag_result, flag_version)
+
+        # user0 should still be there (was recently accessed)
+        result = self.cache.get_cached_flag("user0", "test-flag", flag_version)
+        assert result is not None
+
+        # user2 should still be there (was recently added)
+        result = self.cache.get_cached_flag("user2", "test-flag", flag_version)
+        assert result is not None
+
+        # user3 should be there (just added)
+        result = self.cache.get_cached_flag("user3", "test-flag", flag_version)
+        assert result is not None

posthog/types.py

@@ -0,0 +1,300 @@
+import json
+from dataclasses import dataclass
+from typing import Any, Callable, List, Optional, TypedDict, Union, cast
+
+FlagValue = Union[bool, str]
+
+# Type alias for the before_send callback function
+# Takes an event dictionary and returns the modified event or None to drop it
+BeforeSendCallback = Callable[[dict[str, Any]], Optional[dict[str, Any]]]
+
+
+class SendFeatureFlagsOptions(TypedDict, total=False):
+    """Options for sending feature flags with capture events.
+
+    Args:
+        only_evaluate_locally: Whether to only use local evaluation for feature flags.
+            If True, only flags that can be evaluated locally will be included.
+            If False, remote evaluation via /flags API will be used when needed.
+        person_properties: Properties to use for feature flag evaluation specific to this event.
+            These properties will be merged with any existing person properties.
+        group_properties: Group properties to use for feature flag evaluation specific to this event.
+            Format: { group_type_name: { group_properties } }
+    """
+
+    only_evaluate_locally: Optional[bool]
+    person_properties: Optional[dict[str, Any]]
+    group_properties: Optional[dict[str, dict[str, Any]]]
+
+
+@dataclass(frozen=True)
+class FlagReason:
+    code: str
+    condition_index: Optional[int]
+    description: str
+
+    @classmethod
+    def from_json(cls, resp: Any) -> Optional["FlagReason"]:
+        if not resp:
+            return None
+        return cls(
+            code=resp.get("code", ""),
+            condition_index=resp.get("condition_index"),
+            description=resp.get("description", ""),
+        )
+
+
+@dataclass(frozen=True)
+class LegacyFlagMetadata:
+    payload: Any
+
+
+@dataclass(frozen=True)
+class FlagMetadata:
+    id: int
+    payload: Optional[str]
+    version: int
+    description: str
+
+    @classmethod
+    def from_json(cls, resp: Any) -> Union["FlagMetadata", LegacyFlagMetadata]:
+        if not resp:
+            return LegacyFlagMetadata(payload=None)
+        return cls(
+            id=resp.get("id", 0),
+            payload=resp.get("payload"),
+            version=resp.get("version", 0),
+            description=resp.get("description", ""),
+        )
+
+
+@dataclass(frozen=True)
+class FeatureFlag:
+    key: str
+    enabled: bool
+    variant: Optional[str]
+    reason: Optional[FlagReason]
+    metadata: Union[FlagMetadata, LegacyFlagMetadata]
+
+    def get_value(self) -> FlagValue:
+        return self.variant or self.enabled
+
+    @classmethod
+    def from_json(cls, resp: Any) -> "FeatureFlag":
+        reason = None
+        if resp.get("reason"):
+            reason = FlagReason.from_json(resp.get("reason"))
+
+        metadata = None
+        if resp.get("metadata"):
+            metadata = FlagMetadata.from_json(resp.get("metadata"))
+        else:
+            metadata = LegacyFlagMetadata(payload=None)
+
+        return cls(
+            key=resp.get("key"),
+            enabled=resp.get("enabled"),
+            variant=resp.get("variant"),
+            reason=reason,
+            metadata=metadata,
+        )
+
+    @classmethod
+    def from_value_and_payload(
+        cls, key: str, value: FlagValue, payload: Any
+    ) -> "FeatureFlag":
+        enabled, variant = (True, value) if isinstance(value, str) else (value, None)
+        return cls(
+            key=key,
+            enabled=enabled,
+            variant=variant,
+            reason=None,
+            metadata=LegacyFlagMetadata(
+                payload=payload if payload else None,
+            ),
+        )
+
+
+class FlagsResponse(TypedDict, total=False):
+    flags: dict[str, FeatureFlag]
+    errorsWhileComputingFlags: bool
+    requestId: str
+    quotaLimit: Optional[List[str]]
+
+
+class FlagsAndPayloads(TypedDict, total=True):
+    featureFlags: Optional[dict[str, FlagValue]]
+    featureFlagPayloads: Optional[dict[str, Any]]
+
+
+@dataclass(frozen=True)
+class FeatureFlagResult:
+    """
+    The result of calling a feature flag which includes the flag result, variant, and payload.
+
+    Attributes:
+        key (str): The unique identifier of the feature flag.
+        enabled (bool): Whether the feature flag is enabled for the current context.
+        variant (Optional[str]): The variant value if the flag is enabled and has variants, None otherwise.
+        payload (Optional[Any]): Additional data associated with the feature flag, if any.
+        reason (Optional[str]): A description of why the flag was enabled or disabled, if available.
+    """
+
+    key: str
+    enabled: bool
+    variant: Optional[str]
+    payload: Optional[Any]
+    reason: Optional[str]
+
+    def get_value(self) -> FlagValue:
+        """
+        Returns the value of the flag. This is the variant if it exists, otherwise the enabled value.
+        This is the value we report as `$feature_flag_response` in the `$feature_flag_called` event.
+
+        Returns:
+            FlagValue: Either a string variant or boolean value representing the flag's state.
+        """
+        return self.variant or self.enabled
+
+    @classmethod
+    def from_value_and_payload(
+        cls, key: str, value: Union[FlagValue, None], payload: Any
+    ) -> Union["FeatureFlagResult", None]:
+        """
+        Creates a FeatureFlagResult from a flag value and payload.
+
+        Args:
+            key (str): The unique identifier of the feature flag.
+            value (Union[FlagValue, None]): The value of the flag (string variant or boolean).
+            payload (Any): Additional data associated with the feature flag.
+
+        Returns:
+            Union[FeatureFlagResult, None]: A new FeatureFlagResult instance, or None if value is None.
+        """
+        if value is None:
+            return None
+        enabled, variant = (True, value) if isinstance(value, str) else (value, None)
+        return cls(
+            key=key,
+            enabled=enabled,
+            variant=variant,
+            payload=json.loads(payload) if isinstance(payload, str) else payload,
+            reason=None,
+        )
+
+    @classmethod
+    def from_flag_details(
+        cls,
+        details: Union[FeatureFlag, None],
+        override_match_value: Optional[FlagValue] = None,
+    ) -> "FeatureFlagResult | None":
+        """
+        Create a FeatureFlagResult from a FeatureFlag object.
+
+        Args:
+            details (Union[FeatureFlag, None]): The FeatureFlag object to convert.
+            override_match_value (Optional[FlagValue]): If provided, this value will be used to populate
+                the enabled and variant fields instead of the values from the FeatureFlag.
+
+        Returns:
+            FeatureFlagResult | None: A new FeatureFlagResult instance, or None if details is None.
+        """
+
+        if details is None:
+            return None
+
+        if override_match_value is not None:
+            enabled, variant = (
+                (True, override_match_value)
+                if isinstance(override_match_value, str)
+                else (override_match_value, None)
+            )
+        else:
+            enabled, variant = (details.enabled, details.variant)
+
+        return cls(
+            key=details.key,
+            enabled=enabled,
+            variant=variant,
+            payload=(
+                json.loads(details.metadata.payload)
+                if isinstance(details.metadata.payload, str)
+                else details.metadata.payload
+            ),
+            reason=details.reason.description if details.reason else None,
+        )
+
+
+def normalize_flags_response(resp: Any) -> FlagsResponse:
+    """
+    Normalize the response from the decide or flags API endpoint into a FlagsResponse.
+
+    Args:
+        resp: A v3 or v4 response from the decide (or a v1 or v2 response from the flags) API endpoint.
+
+    Returns:
+        A FlagsResponse containing feature flags and their details.
+    """
+    if "requestId" not in resp:
+        resp["requestId"] = None
+    if "flags" in resp:
+        flags = resp["flags"]
+        # For each flag, create a FeatureFlag object
+        for key, value in flags.items():
+            if isinstance(value, FeatureFlag):
+                continue
+            value["key"] = key
+            flags[key] = FeatureFlag.from_json(value)
+    else:
+        # Handle legacy format
+        featureFlags = resp.get("featureFlags", {})
+        featureFlagPayloads = resp.get("featureFlagPayloads", {})
+        resp.pop("featureFlags", None)
+        resp.pop("featureFlagPayloads", None)
+        # look at each key in featureFlags and create a FeatureFlag object
+        flags = {}
+        for key, value in featureFlags.items():
+            flags[key] = FeatureFlag.from_value_and_payload(
+                key, value, featureFlagPayloads.get(key, None)
+            )
+        resp["flags"] = flags
+    return cast(FlagsResponse, resp)
+
+
+def to_flags_and_payloads(resp: FlagsResponse) -> FlagsAndPayloads:
+    """
+    Convert a FlagsResponse into a FlagsAndPayloads object which is a
+    dict of feature flags and their payloads. This is needed by certain
+    functions in the client.
+    Args:
+        resp: A FlagsResponse containing feature flags and their payloads.
+
+    Returns:
+        A tuple containing:
+            - A dictionary mapping flag keys to their values (bool or str)
+            - A dictionary mapping flag keys to their payloads
+    """
+    return {"featureFlags": to_values(resp), "featureFlagPayloads": to_payloads(resp)}
+
+
+def to_values(response: FlagsResponse) -> Optional[dict[str, FlagValue]]:
+    if "flags" not in response:
+        return None
+
+    flags = response.get("flags", {})
+    return {
+        key: value.get_value()
+        for key, value in flags.items()
+        if isinstance(value, FeatureFlag)
+    }
+
+
+def to_payloads(response: FlagsResponse) -> Optional[dict[str, str]]:
+    if "flags" not in response:
+        return None
+
+    return {
+        key: value.metadata.payload
+        for key, value in response.get("flags", {}).items()
+        if isinstance(value, FeatureFlag) and value.enabled and value.metadata.payload
+    }

posthog/utils.py

@@ -1,10 +1,17 @@
+import json
 import logging
 import numbers
 import re
+import time
 from collections import defaultdict
+from dataclasses import asdict, is_dataclass
 from datetime import date, datetime, timezone
 from decimal import Decimal
+from typing import Any, Optional
 from uuid import UUID
+import sys
+import platform
+import distro  # For Linux OS detection
 
 import six
 from dateutil.tz import tzlocal, tzutc
@@ -51,7 +58,9 @@ def clean(item):
         return float(item)
     if isinstance(item, UUID):
         return str(item)
-    if isinstance(item, (six.string_types, bool, numbers.Number, datetime, date, type(None))):
+    if isinstance(
+        item, (six.string_types, bool, numbers.Number, datetime, date, type(None))
+    ):
         return item
     if isinstance(item, (set, list, tuple)):
         return _clean_list(item)
@@ -68,6 +77,8 @@ def clean(item):
         pass
     if isinstance(item, dict):
         return _clean_dict(item)
+    if is_dataclass(item) and not isinstance(item, type):
+        return _clean_dataclass(item)
     return _coerce_unicode(item)
 
 
@@ -90,14 +101,41 @@ def _clean_dict(dict_):
     return data
 
 
-def _coerce_unicode(cmplx):
+def _clean_dataclass(dataclass_):
+    data = asdict(dataclass_)
+    data = _clean_dict(data)
+    return data
+
+
+def _coerce_unicode(cmplx: Any) -> Optional[str]:
+    """
+    In theory, this method is only called
+    after many isinstance checks are carried out in `utils.clean`.
+    When we supported Python 2 it was safe to call `decode` on a `str`
+    but in Python 3 that will throw.
+    So, we check if the input is bytes and only call `decode` in that case.
+
+    Previously we would always call `decode` on the input
+    That would throw an error.
+    Then we would call `decode` on the stringified error
+    That would throw an error.
+    And then we would return `None`
+
+    To avoid a breaking change, we can maintain the behavior
+    that anything which did not have `decode` in Python 2
+    returns None.
+    """
+    item = None
     try:
-        item = cmplx.decode("utf-8", "strict")
-    except AttributeError as exception:
-        item = ":".join(exception)
-        item.decode("utf-8", "strict")
+        if isinstance(cmplx, bytes):
+            item = cmplx.decode("utf-8", "strict")
+        elif isinstance(cmplx, str):
+            item = cmplx
+    except Exception as exception:
+        item = ":".join(map(str, exception.args))
         log.warning("Error decoding: %s", item)
         return None
+
     return item
 
 
@@ -121,6 +159,266 @@ class SizeLimitedDict(defaultdict):
         super().__setitem__(key, value)
 
 
+class FlagCacheEntry:
+    def __init__(self, flag_result, flag_definition_version, timestamp=None):
+        self.flag_result = flag_result
+        self.flag_definition_version = flag_definition_version
+        self.timestamp = timestamp or time.time()
+
+    def is_valid(self, current_time, ttl, current_flag_version):
+        time_valid = (current_time - self.timestamp) < ttl
+        version_valid = self.flag_definition_version == current_flag_version
+        return time_valid and version_valid
+
+    def is_stale_but_usable(self, current_time, max_stale_age=3600):
+        return (current_time - self.timestamp) < max_stale_age
+
+
+class FlagCache:
+    def __init__(self, max_size=10000, default_ttl=300):
+        self.cache = {}  # distinct_id -> {flag_key: FlagCacheEntry}
+        self.access_times = {}  # distinct_id -> last_access_time
+        self.max_size = max_size
+        self.default_ttl = default_ttl
+
+    def get_cached_flag(self, distinct_id, flag_key, current_flag_version):
+        current_time = time.time()
+
+        if distinct_id not in self.cache:
+            return None
+
+        user_flags = self.cache[distinct_id]
+        if flag_key not in user_flags:
+            return None
+
+        entry = user_flags[flag_key]
+        if entry.is_valid(current_time, self.default_ttl, current_flag_version):
+            self.access_times[distinct_id] = current_time
+            return entry.flag_result
+
+        return None
+
+    def get_stale_cached_flag(self, distinct_id, flag_key, max_stale_age=3600):
+        current_time = time.time()
+
+        if distinct_id not in self.cache:
+            return None
+
+        user_flags = self.cache[distinct_id]
+        if flag_key not in user_flags:
+            return None
+
+        entry = user_flags[flag_key]
+        if entry.is_stale_but_usable(current_time, max_stale_age):
+            return entry.flag_result
+
+        return None
+
+    def set_cached_flag(
+        self, distinct_id, flag_key, flag_result, flag_definition_version
+    ):
+        current_time = time.time()
+
+        # Evict LRU users if we're at capacity
+        if distinct_id not in self.cache and len(self.cache) >= self.max_size:
+            self._evict_lru()
+
+        # Initialize user cache if needed
+        if distinct_id not in self.cache:
+            self.cache[distinct_id] = {}
+
+        # Store the flag result
+        self.cache[distinct_id][flag_key] = FlagCacheEntry(
+            flag_result, flag_definition_version, current_time
+        )
+        self.access_times[distinct_id] = current_time
+
+    def invalidate_version(self, old_version):
+        users_to_remove = []
+
+        for distinct_id, user_flags in self.cache.items():
+            flags_to_remove = []
+            for flag_key, entry in user_flags.items():
+                if entry.flag_definition_version == old_version:
+                    flags_to_remove.append(flag_key)
+
+            # Remove invalidated flags
+            for flag_key in flags_to_remove:
+                del user_flags[flag_key]
+
+            # Remove user entirely if no flags remain
+            if not user_flags:
+                users_to_remove.append(distinct_id)
+
+        # Clean up empty users
+        for distinct_id in users_to_remove:
+            del self.cache[distinct_id]
+            if distinct_id in self.access_times:
+                del self.access_times[distinct_id]
+
+    def _evict_lru(self):
+        if not self.access_times:
+            return
+
+        # Remove 20% of least recently used entries
+        sorted_users = sorted(self.access_times.items(), key=lambda x: x[1])
+        to_remove = max(1, len(sorted_users) // 5)
+
+        for distinct_id, _ in sorted_users[:to_remove]:
+            if distinct_id in self.cache:
+                del self.cache[distinct_id]
+            if distinct_id in self.access_times:
+                del self.access_times[distinct_id]
+
+    def clear(self):
+        self.cache.clear()
+        self.access_times.clear()
+
+
+class RedisFlagCache:
+    def __init__(
+        self, redis_client, default_ttl=300, stale_ttl=3600, key_prefix="posthog:flags:"
+    ):
+        self.redis = redis_client
+        self.default_ttl = default_ttl
+        self.stale_ttl = stale_ttl
+        self.key_prefix = key_prefix
+        self.version_key = f"{key_prefix}version"
+
+    def _get_cache_key(self, distinct_id, flag_key):
+        return f"{self.key_prefix}{distinct_id}:{flag_key}"
+
+    def _serialize_entry(self, flag_result, flag_definition_version, timestamp=None):
+        if timestamp is None:
+            timestamp = time.time()
+
+        # Use clean to make flag_result JSON-serializable for cross-platform compatibility
+        serialized_result = clean(flag_result)
+
+        entry = {
+            "flag_result": serialized_result,
+            "flag_version": flag_definition_version,
+            "timestamp": timestamp,
+        }
+        return json.dumps(entry)
+
+    def _deserialize_entry(self, data):
+        try:
+            entry = json.loads(data)
+            flag_result = entry["flag_result"]
+            return FlagCacheEntry(
+                flag_result=flag_result,
+                flag_definition_version=entry["flag_version"],
+                timestamp=entry["timestamp"],
+            )
+        except (json.JSONDecodeError, KeyError, ValueError):
+            # If deserialization fails, treat as cache miss
+            return None
+
+    def get_cached_flag(self, distinct_id, flag_key, current_flag_version):
+        try:
+            cache_key = self._get_cache_key(distinct_id, flag_key)
+            data = self.redis.get(cache_key)
+
+            if data:
+                entry = self._deserialize_entry(data)
+                if entry and entry.is_valid(
+                    time.time(), self.default_ttl, current_flag_version
+                ):
+                    return entry.flag_result
+
+            return None
+        except Exception:
+            # Redis error - return None to fall back to normal evaluation
+            return None
+
+    def get_stale_cached_flag(self, distinct_id, flag_key, max_stale_age=None):
+        try:
+            if max_stale_age is None:
+                max_stale_age = self.stale_ttl
+
+            cache_key = self._get_cache_key(distinct_id, flag_key)
+            data = self.redis.get(cache_key)
+
+            if data:
+                entry = self._deserialize_entry(data)
+                if entry and entry.is_stale_but_usable(time.time(), max_stale_age):
+                    return entry.flag_result
+
+            return None
+        except Exception:
+            # Redis error - return None
+            return None
+
+    def set_cached_flag(
+        self, distinct_id, flag_key, flag_result, flag_definition_version
+    ):
+        try:
+            cache_key = self._get_cache_key(distinct_id, flag_key)
+            serialized_entry = self._serialize_entry(
+                flag_result, flag_definition_version
+            )
+
+            # Set with TTL for automatic cleanup (use stale_ttl for total lifetime)
+            self.redis.setex(cache_key, self.stale_ttl, serialized_entry)
+
+            # Update the current version
+            self.redis.set(self.version_key, flag_definition_version)
+
+        except Exception:
+            # Redis error - silently fail, don't break flag evaluation
+            pass
+
+    def invalidate_version(self, old_version):
+        try:
+            # For Redis, we use a simple approach: scan for keys with old version
+            # and delete them. This could be expensive with many keys, but it's
+            # necessary for correctness.
+
+            cursor = 0
+            pattern = f"{self.key_prefix}*"
+
+            while True:
+                cursor, keys = self.redis.scan(cursor, match=pattern, count=100)
+
+                for key in keys:
+                    if key.decode() == self.version_key:
+                        continue
+
+                    try:
+                        data = self.redis.get(key)
+                        if data:
+                            entry_dict = json.loads(data)
+                            if entry_dict.get("flag_version") == old_version:
+                                self.redis.delete(key)
+                    except (json.JSONDecodeError, KeyError):
+                        # If we can't parse the entry, delete it to be safe
+                        self.redis.delete(key)
+
+                if cursor == 0:
+                    break
+
+        except Exception:
+            # Redis error - silently fail
+            pass
+
+    def clear(self):
+        try:
+            # Delete all keys matching our pattern
+            cursor = 0
+            pattern = f"{self.key_prefix}*"
+
+            while True:
+                cursor, keys = self.redis.scan(cursor, match=pattern, count=100)
+                if keys:
+                    self.redis.delete(*keys)
+                if cursor == 0:
+                    break
+        except Exception:
+            # Redis error - silently fail
+            pass
+
+
 def convert_to_datetime_aware(date_obj):
     if date_obj.tzinfo is None:
         date_obj = date_obj.replace(tzinfo=timezone.utc)
@@ -165,3 +463,57 @@ def str_iequals(value, comparand):
         False
     """
     return str(value).casefold() == str(comparand).casefold()
+
+
+def get_os_info():
+    """
+    Returns standardized OS name and version information.
+    Similar to how user agent parsing works in JS.
+    """
+    os_name = ""
+    os_version = ""
+
+    platform_name = sys.platform
+
+    if platform_name.startswith("win"):
+        os_name = "Windows"
+        if hasattr(platform, "win32_ver"):
+            win_version = platform.win32_ver()[0]
+            if win_version:
+                os_version = win_version
+
+    elif platform_name == "darwin":
+        os_name = "Mac OS X"
+        if hasattr(platform, "mac_ver"):
+            mac_version = platform.mac_ver()[0]
+            if mac_version:
+                os_version = mac_version
+
+    elif platform_name.startswith("linux"):
+        os_name = "Linux"
+        linux_info = distro.info()
+        if linux_info["version"]:
+            os_version = linux_info["version"]
+
+    elif platform_name.startswith("freebsd"):
+        os_name = "FreeBSD"
+        if hasattr(platform, "release"):
+            os_version = platform.release()
+
+    else:
+        os_name = platform_name
+        if hasattr(platform, "release"):
+            os_version = platform.release()
+
+    return os_name, os_version
+
+
+def system_context() -> dict[str, Any]:
+    os_name, os_version = get_os_info()
+
+    return {
+        "$python_runtime": platform.python_implementation(),
+        "$python_version": "%s.%s.%s" % (sys.version_info[:3]),
+        "$os": os_name,
+        "$os_version": os_version,
+    }

posthog/version.py

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

pyproject.toml

@@ -1,10 +1,98 @@
-[tool.black]
-line-length = 120
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
 
-[tool.isort]
-multi_line_output = 3
-include_trailing_comma = true
-force_grid_wrap = 8
-ensure_newline_before_comments = true
-line_length = 120
-virtual_env = "env"
+[project]
+name = "posthog"
+dynamic = ["version"]
+description = "Integrate PostHog into any python application."
+authors = [{ name = "PostHog", email = "hey@posthog.com" }]
+maintainers = [{ name = "PostHog", email = "hey@posthog.com" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "requests>=2.7,<3.0",
+    "six>=1.5",
+    "python-dateutil>=2.2",
+    "backoff>=1.10.0",
+    "distro>=1.5.0",
+    "typing-extensions>=4.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/posthog/posthog-python"
+Repository = "https://github.com/posthog/posthog-python"
+
+[project.optional-dependencies]
+langchain = ["langchain>=0.2.0"]
+dev = [
+    "django-stubs",
+    "lxml",
+    "mypy",
+    "mypy-baseline",
+    "types-mock",
+    "types-python-dateutil",
+    "types-requests",
+    "types-setuptools",
+    "types-six",
+    "pre-commit",
+    "pydantic",
+    "ruff",
+    "setuptools",
+    "packaging",
+    "wheel",
+    "twine",
+    "tomli",
+    "tomli_w",
+]
+test = [
+    "mock>=2.0.0",
+    "freezegun==1.5.1",
+    "coverage",
+    "pytest",
+    "pytest-timeout",
+    "pytest-asyncio",
+    "django",
+    "openai",
+    "anthropic",
+    "langgraph>=0.4.8",
+    "langchain-core>=0.3.65",
+    "langchain-community>=0.3.25",
+    "langchain-openai>=0.3.22",
+    "langchain-anthropic>=0.3.15",
+    "google-genai",
+    "pydantic",
+    "parameterized>=0.8.1",
+]
+
+[tool.setuptools]
+packages = [
+    "posthog",
+    "posthog.ai",
+    "posthog.ai.langchain",
+    "posthog.ai.openai",
+    "posthog.ai.anthropic",
+    "posthog.ai.gemini",
+    "posthog.test",
+    "posthog.integrations",
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "posthog.version.VERSION" }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

sentry_django_example/manage.py

@@ -1,22 +0,0 @@
-#!/usr/bin/env python
-"""Django's command-line utility for administrative tasks."""
-import os
-import sys
-
-
-def main():
-    """Run administrative tasks."""
-    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "sentry_django_example.settings")
-    try:
-        from django.core.management import execute_from_command_line
-    except ImportError as exc:
-        raise ImportError(
-            "Couldn't import Django. Are you sure it's installed and "
-            "available on your PYTHONPATH environment variable? Did you "
-            "forget to activate a virtual environment?"
-        ) from exc
-    execute_from_command_line(sys.argv)
-
-
-if __name__ == "__main__":
-    main()

sentry_django_example/sentry_django_example/asgi.py

@@ -1,16 +0,0 @@
-"""
-ASGI config for sentry_django_example project.
-
-It exposes the ASGI callable as a module-level variable named ``application``.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/3.2/howto/deployment/asgi/
-"""
-
-import os
-
-from django.core.asgi import get_asgi_application
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "sentry_django_example.settings")
-
-application = get_asgi_application()

sentry_django_example/sentry_django_example/settings.py

@@ -1,167 +0,0 @@
-"""
-Django settings for sentry_django_example project.
-
-Generated by 'django-admin startproject' using Django 3.2.2.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/3.2/topics/settings/
-
-For the full list of settings and their values, see
-https://docs.djangoproject.com/en/3.2/ref/settings/
-"""
-
-from pathlib import Path
-from uuid import uuid4
-
-# Build paths inside the project like this: BASE_DIR / 'subdir'.
-BASE_DIR = Path(__file__).resolve().parent.parent
-
-
-# Quick-start development settings - unsuitable for production
-# See https://docs.djangoproject.com/en/3.2/howto/deployment/checklist/
-
-# SECURITY WARNING: keep the secret key used in production secret!
-SECRET_KEY = "django-insecure-4kzfiq7vb(t0+jbl#vq)u=%06ouf)n*=l%730c8=tk(wkm9i9o"
-
-# SECURITY WARNING: don't run with debug turned on in production!
-DEBUG = True
-
-ALLOWED_HOSTS = []
-
-
-# PostHog Setup (can be a separate app)
-import posthog
-
-# You can find this key on the /setup page in PostHog
-posthog.api_key = "LXP6nQXvo-2TCqGVrWvPah8uJIyVykoMmhnEkEBi5PA"  # TODO: replace with your api key
-
-posthog.personal_api_key = ""
-
-# Where you host PostHog, with no trailing /.
-# You can remove this line if you're using posthog.com
-posthog.host = "http://127.0.0.1:8000"
-
-from posthog.sentry.posthog_integration import PostHogIntegration
-
-PostHogIntegration.organization = "posthog"  # TODO: your sentry organization
-# PostHogIntegration.prefix = # TODO: your self hosted Sentry url. (default: https://sentry.io/organizations/)
-
-# Since Sentry doesn't allow Integrations configuration (see https://github.com/getsentry/sentry-python/blob/master/sentry_sdk/integrations/__init__.py#L171-L183)
-# we work around this by setting static class variables beforehand
-
-# Sentry Setup
-import sentry_sdk
-from sentry_sdk.integrations.django import DjangoIntegration
-
-sentry_sdk.init(
-    dsn="https://27ac54f7f4cf484abf1335436b0c52e5@o344752.ingest.sentry.io/5624115",  # TODO: your Sentry DSN here
-    integrations=[DjangoIntegration(), PostHogIntegration()],
-    # Set traces_sample_rate to 1.0 to capture 100%
-    # of transactions for performance monitoring.
-    # We recommend adjusting this value in production.
-    traces_sample_rate=1.0,
-    # If you wish to associate users to errors (assuming you are using
-    # django.contrib.auth) you may enable sending PII data.
-    send_default_pii=True,
-)
-
-POSTHOG_DJANGO = {
-    "distinct_id": lambda request: str(uuid4())  # TODO: your logic for generating unique ID, given the request object
-}
-
-# Application definition
-
-INSTALLED_APPS = [
-    "django.contrib.admin",
-    "django.contrib.auth",
-    "django.contrib.contenttypes",
-    "django.contrib.sessions",
-    "django.contrib.messages",
-    "django.contrib.staticfiles",
-]
-
-MIDDLEWARE = [
-    "django.middleware.security.SecurityMiddleware",
-    "django.contrib.sessions.middleware.SessionMiddleware",
-    "django.middleware.common.CommonMiddleware",
-    "django.middleware.csrf.CsrfViewMiddleware",
-    "django.contrib.auth.middleware.AuthenticationMiddleware",
-    "django.contrib.messages.middleware.MessageMiddleware",
-    "django.middleware.clickjacking.XFrameOptionsMiddleware",
-    "posthog.sentry.django.PosthogDistinctIdMiddleware",
-]
-
-ROOT_URLCONF = "sentry_django_example.urls"
-
-TEMPLATES = [
-    {
-        "BACKEND": "django.template.backends.django.DjangoTemplates",
-        "DIRS": [],
-        "APP_DIRS": True,
-        "OPTIONS": {
-            "context_processors": [
-                "django.template.context_processors.debug",
-                "django.template.context_processors.request",
-                "django.contrib.auth.context_processors.auth",
-                "django.contrib.messages.context_processors.messages",
-            ],
-        },
-    },
-]
-
-WSGI_APPLICATION = "sentry_django_example.wsgi.application"
-
-
-# Database
-# https://docs.djangoproject.com/en/3.2/ref/settings/#databases
-
-DATABASES = {
-    "default": {
-        "ENGINE": "django.db.backends.sqlite3",
-        "NAME": BASE_DIR / "db.sqlite3",
-    }
-}
-
-
-# Password validation
-# https://docs.djangoproject.com/en/3.2/ref/settings/#auth-password-validators
-
-AUTH_PASSWORD_VALIDATORS = [
-    {
-        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
-    },
-    {
-        "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
-    },
-    {
-        "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
-    },
-    {
-        "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
-    },
-]
-
-
-# Internationalization
-# https://docs.djangoproject.com/en/3.2/topics/i18n/
-
-LANGUAGE_CODE = "en-us"
-
-TIME_ZONE = "UTC"
-
-USE_I18N = True
-
-USE_L10N = True
-
-USE_TZ = True
-
-
-# Static files (CSS, JavaScript, Images)
-# https://docs.djangoproject.com/en/3.2/howto/static-files/
-
-STATIC_URL = "/static/"
-
-# Default primary key field type
-# https://docs.djangoproject.com/en/3.2/ref/settings/#default-auto-field
-
-DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

sentry_django_example/sentry_django_example/urls.py

@@ -1,28 +0,0 @@
-"""sentry_django_example URL Configuration
-
-The `urlpatterns` list routes URLs to views. For more information please see:
-    https://docs.djangoproject.com/en/3.2/topics/http/urls/
-Examples:
-Function views
-    1. Add an import:  from my_app import views
-    2. Add a URL to urlpatterns:  path('', views.home, name='home')
-Class-based views
-    1. Add an import:  from other_app.views import Home
-    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
-Including another URLconf
-    1. Import the include() function: from django.urls import include, path
-    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
-"""
-
-from django.contrib import admin
-from django.urls import path
-
-
-def trigger_error(request):
-    division_by_zero = 1 / 0
-
-
-urlpatterns = [
-    path("admin/", admin.site.urls),
-    path("sentry-debug/", trigger_error),
-]

sentry_django_example/sentry_django_example/wsgi.py

@@ -1,16 +0,0 @@
-"""
-WSGI config for sentry_django_example project.
-
-It exposes the WSGI callable as a module-level variable named ``application``.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/3.2/howto/deployment/wsgi/
-"""
-
-import os
-
-from django.core.wsgi import get_wsgi_application
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "sentry_django_example.settings")
-
-application = get_wsgi_application()

setup.cfg

@@ -1,5 +0,0 @@
-[bdist_wheel]
-universal = 1
-
-[tool:pytest]
-asyncio_mode = auto

setup.py

@@ -8,94 +8,28 @@ except ImportError:
 
 # Don't import analytics-python module here, since deps may not be installed
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "posthog"))
-from version import VERSION
+from version import VERSION  # noqa: E402
 
 long_description = """
-PostHog is developer-friendly, self-hosted product analytics. posthog-python is the python package.
+PostHog is developer-friendly, self-hosted product analytics.
+posthog-python is the python package.
+
+This package requires Python 3.9 or higher.
 """
 
-install_requires = [
-    "requests>=2.7,<3.0",
-    "six>=1.5",
-    "monotonic>=1.5",
-    "backoff>=1.10.0",
-    "python-dateutil>2.1",
-]
-
-extras_require = {
-    "dev": [
-        "black",
-        "django-stubs",
-        "isort",
-        "flake8",
-        "flake8-print",
-        "lxml",
-        "mypy",
-        "mypy-baseline",
-        "types-mock",
-        "types-python-dateutil",
-        "types-requests",
-        "types-setuptools",
-        "types-six",
-        "pre-commit",
-        "pydantic",
-    ],
-    "test": [
-        "mock>=2.0.0",
-        "freezegun==1.5.1",
-        "pylint",
-        "flake8",
-        "coverage",
-        "pytest",
-        "pytest-timeout",
-        "pytest-asyncio",
-        "django",
-        "openai",
-        "anthropic",
-        "langgraph",
-        "langchain-community>=0.2.0",
-        "langchain-openai>=0.2.0",
-        "langchain-anthropic>=0.2.0",
-        "pydantic",
-    ],
-    "sentry": ["sentry-sdk", "django"],
-    "langchain": ["langchain>=0.2.0"],
-}
-
+# Minimal setup.py for backward compatibility
+# Most configuration is now in pyproject.toml
 setup(
     name="posthog",
     version=VERSION,
+    # Basic fields for backward compatibility
     url="https://github.com/posthog/posthog-python",
     author="Posthog",
     author_email="hey@posthog.com",
     maintainer="PostHog",
     maintainer_email="hey@posthog.com",
-    test_suite="posthog.test.all",
-    packages=[
-        "posthog",
-        "posthog.ai",
-        "posthog.ai.langchain",
-        "posthog.ai.openai",
-        "posthog.ai.anthropic",
-        "posthog.test",
-        "posthog.sentry",
-        "posthog.exception_integrations",
-    ],
     license="MIT License",
-    install_requires=install_requires,
-    extras_require=extras_require,
     description="Integrate PostHog into any python application.",
     long_description=long_description,
-    classifiers=[
-        "Development Status :: 5 - Production/Stable",
-        "Intended Audience :: Developers",
-        "License :: OSI Approved :: MIT License",
-        "Operating System :: OS Independent",
-        "Programming Language :: Python",
-        "Programming Language :: Python :: 3.9",
-        "Programming Language :: Python :: 3.10",
-        "Programming Language :: Python :: 3.11",
-        "Programming Language :: Python :: 3.12",
-        "Programming Language :: Python :: 3.13",
-    ],
+    # This will fallback to pyproject.toml for detailed configuration
 )

setup_analytics.py

@@ -1,69 +1,68 @@
 import os
 import sys
+import tomli
+import tomli_w
+import shutil
 
 try:
     from setuptools import setup
 except ImportError:
     from distutils.core import setup
 
-# Don't import module here, since deps may not be installed
+# Don't import analytics-python module here, since deps may not be installed
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "posthoganalytics"))
-from version import VERSION
+from version import VERSION  # noqa: E402
+
+
+# Copy the original pyproject.toml as backup
+shutil.copy("pyproject.toml", "pyproject.toml.backup")
+
+# Read the original pyproject.toml
+with open("pyproject.toml", "rb") as f:
+    config = tomli.load(f)
+
+# Override specific values
+config["project"]["name"] = "posthoganalytics"
+config["tool"]["setuptools"]["dynamic"]["version"] = {
+    "attr": "posthoganalytics.version.VERSION"
+}
+
+# Rename packages from posthog.* to posthoganalytics.*
+if "packages" in config["tool"]["setuptools"]:
+    new_packages = []
+    for package in config["tool"]["setuptools"]["packages"]:
+        if package == "posthog":
+            new_packages.append("posthoganalytics")
+        elif package.startswith("posthog."):
+            new_packages.append(package.replace("posthog.", "posthoganalytics.", 1))
+        else:
+            new_packages.append(package)
+    config["tool"]["setuptools"]["packages"] = new_packages
+
+# Overwrite the original pyproject.toml
+with open("pyproject.toml", "wb") as f:
+    tomli_w.dump(config, f)
 
 long_description = """
-PostHog is developer-friendly, self-hosted product analytics. posthog-python is the python package.
+PostHog is developer-friendly, self-hosted product analytics.
+posthog-python is the python package.
+
+This package requires Python 3.9 or higher.
 """
 
-install_requires = ["requests>=2.7,<3.0", "six>=1.5", "monotonic>=1.5", "backoff>=1.10.0", "python-dateutil>2.1"]
-
-tests_require = ["mock>=2.0.0"]
-
+# Minimal setup.py for backward compatibility
+# Most configuration is now in pyproject.toml
 setup(
     name="posthoganalytics",
     version=VERSION,
+    # Basic fields for backward compatibility
     url="https://github.com/posthog/posthog-python",
     author="Posthog",
     author_email="hey@posthog.com",
     maintainer="PostHog",
     maintainer_email="hey@posthog.com",
-    test_suite="posthoganalytics.test.all",
-    packages=[
-        "posthoganalytics",
-        "posthoganalytics.ai",
-        "posthoganalytics.ai.langchain",
-        "posthoganalytics.ai.openai",
-        "posthoganalytics.ai.anthropic",
-        "posthoganalytics.test",
-        "posthoganalytics.sentry",
-        "posthoganalytics.exception_integrations",
-    ],
     license="MIT License",
-    install_requires=install_requires,
-    tests_require=tests_require,
-    extras_require={
-        "sentry": ["sentry-sdk", "django"],
-    },
     description="Integrate PostHog into any python application.",
     long_description=long_description,
-    classifiers=[
-        "Development Status :: 5 - Production/Stable",
-        "Intended Audience :: Developers",
-        "License :: OSI Approved :: MIT License",
-        "Operating System :: OS Independent",
-        "Programming Language :: Python",
-        "Programming Language :: Python :: 2",
-        "Programming Language :: Python :: 2.6",
-        "Programming Language :: Python :: 2.7",
-        "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.2",
-        "Programming Language :: Python :: 3.3",
-        "Programming Language :: Python :: 3.4",
-        "Programming Language :: Python :: 3.5",
-        "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: 3.7",
-        "Programming Language :: Python :: 3.8",
-        "Programming Language :: Python :: 3.9",
-        "Programming Language :: Python :: 3.10",
-        "Programming Language :: Python :: 3.11",
-    ],
+    # This will fallback to pyproject.toml for detailed configuration
 )

simulator.py

@@ -1,104 +0,0 @@
-import argparse
-import json
-import logging
-
-import posthog
-
-__name__ = "simulator.py"
-__version__ = "0.0.1"
-__description__ = "scripting simulator"
-
-
-def json_hash(str):
-    if str:
-        return json.loads(str)
-
-
-# posthog -method=<method> -posthog-write-key=<posthogWriteKey> [options]
-
-
-parser = argparse.ArgumentParser(description="send a posthog message")
-
-parser.add_argument("--writeKey", help="the posthog writeKey")
-parser.add_argument("--type", help="The posthog message type")
-
-parser.add_argument("--distinct_id", help="the user id to send the event as")
-parser.add_argument("--anonymousId", help="the anonymous user id to send the event as")
-
-parser.add_argument("--event", help="the event name to send with the event")
-parser.add_argument("--properties", help="the event properties to send (JSON-encoded)")
-
-parser.add_argument("--name", help="name of the screen or page to send with the message")
-
-parser.add_argument("--traits", help="the identify/group traits to send (JSON-encoded)")
-
-parser.add_argument("--groupId", help="the group id")
-
-options = parser.parse_args()
-
-
-def failed(status, msg):
-    raise Exception(msg)
-
-
-def capture():
-    posthog.capture(
-        options.distinct_id,
-        options.event,
-        anonymous_id=options.anonymousId,
-        properties=json_hash(options.properties),
-    )
-
-
-def page():
-    posthog.page(
-        options.distinct_id,
-        name=options.name,
-        anonymous_id=options.anonymousId,
-        properties=json_hash(options.properties),
-    )
-
-
-def identify():
-    posthog.identify(
-        options.distinct_id,
-        anonymous_id=options.anonymousId,
-        traits=json_hash(options.traits),
-    )
-
-
-def set_once():
-    posthog.set_once(
-        options.distinct_id,
-        properties=json_hash(options.traits),
-    )
-
-
-def set():
-    posthog.set(
-        options.distinct_id,
-        properties=json_hash(options.traits),
-    )
-
-
-def unknown():
-    print()
-
-
-posthog.api_key = options.writeKey
-posthog.on_error = failed
-posthog.debug = True
-
-log = logging.getLogger("posthog")
-ch = logging.StreamHandler()
-ch.setLevel(logging.DEBUG)
-log.addHandler(ch)
-
-switcher = {"capture": capture, "page": page, "identify": identify, "set_once": set_once, "set": set}
-
-func = switcher.get(options.type)
-if func:
-    func()
-    posthog.shutdown()
-else:
-    print("Invalid Message Type " + options.type)