fix(llma): cache cost calculation in the LangChain callback (#346)

* fix(llma): cache cost calculation in the LangChain callback

* fix: format

* Update posthog/ai/langchain/callbacks.py

Co-authored-by: Radu Raicea <radu@raicea.com>

* Bump version to 6.7.13

Master has already released 6.7.12 with other fixes, so this PR will be 6.7.13

---------

Co-authored-by: Radu Raicea <radu@raicea.com>
Co-authored-by: Andrew Maguire <andrewm4894@gmail.com>

.env.example

@@ -0,0 +1,11 @@
+# PostHog API Configuration
+# Copy this file to .env and update with your actual values
+
+# Your project API key (found on the /setup page in PostHog)
+POSTHOG_PROJECT_API_KEY=phc_your_project_api_key_here
+
+# Your personal API key (for local evaluation and other advanced features)
+POSTHOG_PERSONAL_API_KEY=phx_your_personal_api_key_here
+
+# PostHog host URL (remove this line if using posthog.com)
+POSTHOG_HOST=http://localhost:8000

.github/dependabot.yml

@@ -0,0 +1,36 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+      time: "10:00"
+      timezone: "UTC"
+    groups:
+      ai-providers:
+        patterns:
+          - "openai"
+          - "anthropic"
+          - "google-genai"
+          - "langchain-core"
+          - "langchain-community"
+          - "langchain-openai"
+          - "langchain-anthropic"
+          - "langgraph"
+    allow:
+      - dependency-name: "openai"
+      - dependency-name: "anthropic"
+      - dependency-name: "google-genai"
+      - dependency-name: "langchain-core"
+      - dependency-name: "langchain-community"
+      - dependency-name: "langchain-openai"
+      - dependency-name: "langchain-anthropic"
+      - dependency-name: "langgraph"
+    open-pull-requests-limit: 1
+    reviewers:
+      - "PostHog/team-llm-analytics"
+    # Uncomment below to enable auto-merge for minor updates when CI passes
+    # pull-request-branch-name:
+    #   separator: "/"
+    # assignees:
+    #   - "PostHog/ai-team"

.github/workflows/generate-references.yml

@@ -0,0 +1,48 @@
+name: "Generate References"
+
+on:
+  workflow_dispatch:
+
+jobs:
+  docs-generation:
+    name: Generate references
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@85e6279cec87321a52edac9c87bce653a07cf6c2
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.POSTHOG_BOT_PAT }}
+
+      - 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: Generate references
+        run: |
+          uv run bin/docs generate-references
+
+      - name: Check for changes in references
+        id: changes
+        run: |
+          if [ -n "$(git status --porcelain references/)" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+            echo "New references generated in references directory:"
+            git status --porcelain references/
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+            echo "No new references generated in references directory"
+          fi
+
+      - uses: stefanzweifel/git-auto-commit-action@778341af668090896ca464160c2def5d1d1a3eb0
+        if: steps.changes.outputs.changed == 'true'
+        with:
+          commit_message: "Update generated references"
+          file_pattern: references/

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/checkout@85e6279cec87321a52edac9c87bce653a07cf6c2
         with:
           fetch-depth: 0
-          token: ${{ secrets.POSTHOG_BOT_GITHUB_TOKEN }}
+          token: ${{ secrets.POSTHOG_BOT_PAT }}
 
       - name: Set up Python
         uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55
@@ -45,7 +45,13 @@ jobs:
       - name: Create GitHub release
         uses: actions/create-release@0cb9c9b65d5d1901c1f53e5e66eaf4afd303e70e # v1
         env:
-          GITHUB_TOKEN: ${{ secrets.POSTHOG_BOT_GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.POSTHOG_BOT_PAT }}
         with:
           tag_name: v${{ env.REPO_VERSION }}
           release_name: ${{ env.REPO_VERSION }}
+      
+      - name: Dispatch generate-references for posthog-python
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh workflow run generate-references.yml --ref master

.gitignore

@@ -18,3 +18,4 @@ posthog-analytics
 pyrightconfig.json
 .env
 .DS_Store
+posthog-python-references.json

CHANGELOG.md

@@ -1,3 +1,122 @@
+# 6.7.13 - 2025-11-02
+
+- fix(llma): cache cost calculation in the LangChain callback
+
+# 6.7.12 - 2025-11-02
+
+- fix(django): Restore process_exception method to capture view and downstream middleware exceptions (fixes #329)
+- fix(ai/langchain): Add LangChain 1.0+ compatibility for CallbackHandler imports (fixes #362)
+
+# 6.7.11 - 2025-10-28
+
+- feat(ai): Add `$ai_framework` property for framework integrations (e.g. LangChain)
+
+# 6.7.10 - 2025-10-24
+
+- fix(django): Make middleware truly hybrid - compatible with both sync (WSGI) and async (ASGI) Django stacks without breaking sync-only deployments
+
+# 6.7.9 - 2025-10-22
+
+- fix(flags): multi-condition flags with static cohorts returning wrong variants
+
+# 6.7.8 - 2025-10-16
+
+- fix(llma): missing async for OpenAI's streaming implementation
+
+# 6.7.7 - 2025-10-14
+
+- fix: remove deprecated attribute $exception_personURL from exception events
+
+# 6.7.6 - 2025-09-16
+
+- fix: don't sort condition sets with variant overrides to the top
+- fix: Prevent core Client methods from raising exceptions
+
+# 6.7.5 - 2025-09-16
+
+- feat: Django middleware now supports async request handling.
+
+# 6.7.4 - 2025-09-05
+
+- fix: Missing system prompts for some providers
+
+# 6.7.3 - 2025-09-04
+
+- fix: missing usage tokens in Gemini
+
+# 6.7.2 - 2025-09-03
+
+- fix: tool call results in streaming providers
+
+# 6.7.1 - 2025-09-01
+
+- fix: Add base64 inline image sanitization
+
+# 6.7.0 - 2025-08-26
+
+- feat: Add support for feature flag dependencies
+
+# 6.6.1 - 2025-08-21
+
+- fix: Prevent `NoneType` error when `group_properties` is `None`
+
+# 6.6.0 - 2025-08-15
+
+- feat: Add `flag_keys_to_evaluate` parameter to optimize feature flag evaluation performance by only evaluating specified flags
+- feat: Add `flag_keys_filter` option to `send_feature_flags` for selective flag evaluation in capture events
+
+# 6.5.0 - 2025-08-08
+
+- feat: Add `$context_tags` to an event to know which properties were included as tags
+
+# 6.4.1 - 2025-08-06
+
+- fix: Always pass project API key in `remote_config` requests for deterministic project routing
+
+# 6.4.0 - 2025-08-05
+
+- feat: support Vertex AI for Gemini
+
+# 6.3.4 - 2025-08-04
+
+- fix: set `$ai_tools` for all providers and `$ai_output_choices` for all non-streaming provider flows properly
+
+# 6.3.3 - 2025-08-01
+
+- fix: `get_feature_flag_result` now correctly returns FeatureFlagResult when payload is empty string instead of None
+
+# 6.3.2 - 2025-07-31
+
+- fix: Anthropic's tool calls are now handled properly
+
+# 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
@@ -5,12 +124,14 @@
 # 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"})

README.md

@@ -32,7 +32,7 @@ We recommend using [uv](https://docs.astral.sh/uv/). It's super fast.
 ```bash
 uv python install 3.9.19
 uv python pin 3.9.19
-uv venv env
+uv venv
 source env/bin/activate
 uv sync --extra dev --extra test
 pre-commit install

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,43 @@
+"""
+Constants for PostHog Python SDK documentation generation.
+"""
+
+from typing import Dict, Union
+from posthog.version import VERSION
+
+# Documentation generation metadata
+DOCUMENTATION_METADATA = {
+    "hogRef": "0.3",
+    "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": "./references",
+    "filename": f"posthog-python-references-{VERSION}.json",
+    "filename_latest": "posthog-python-references-latest.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,498 @@
+#!/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 (
+    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 = ""
+    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}")
+
+    # Clean types of empty types
+
+    # Remove types that have no properties and no examples
+    # Remove types that have no properties and no examples
+    types_list = [
+        t for t in types_list if len(t["properties"]) > 0 or t["example"] != ""
+    ]
+
+    # 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,
+            }
+        )
+
+    # Collect categories from functions
+    categories = ["Initialization", "Identification", "Capture"]
+    seen_categories = set(categories)
+    for class_info in classes_list:
+        if "functions" in class_info:
+            for func in class_info["functions"]:
+                if (
+                    "category" in func
+                    and func["category"] not in seen_categories
+                    and func["category"]
+                ):
+                    categories.append(func["category"])
+                    seen_categories.add(func["category"])
+
+    # Create the final structure
+    result = {
+        "id": "posthog-python",
+        "hogRef": DOCUMENTATION_METADATA["hogRef"],
+        "info": sdk_info,
+        "types": types_list,
+        "classes": classes_list,
+        "categories": categories,
+    }
+
+    return result
+
+
+if __name__ == "__main__":
+    print("Generating PostHog Python SDK documentation...")
+
+    try:
+        documentation = generate_sdk_documentation()
+
+        # Ensure output directory exists
+        output_dir = str(OUTPUT_CONFIG["output_dir"])
+        os.makedirs(output_dir, exist_ok=True)
+
+        output_file = os.path.join(
+            str(OUTPUT_CONFIG["output_dir"]), str(OUTPUT_CONFIG["filename"])
+        )
+        output_file_latest = os.path.join(
+            str(OUTPUT_CONFIG["output_dir"]), str(OUTPUT_CONFIG["filename_latest"])
+        )
+
+        # Write to current version
+        with open(output_file, "w") as f:
+            json.dump(documentation, f, indent=int(OUTPUT_CONFIG["indent"]))
+        # Write to latest
+        with open(output_file_latest, "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")
+
+    except Exception as e:
+        print(f"❌ Error generating documentation: {e}")
+        import traceback
+
+        traceback.print_exc()

bin/fmt

@@ -6,9 +6,7 @@ set_source_and_root_dir
 ensure_virtual_env
 
 if [[ "$1" == "--check" ]]; then
-  black --check .
-  isort --check-only .
+  ruff format --check .
 else
-  black .
-  isort .
+  ruff format .
 fi

example.py

@@ -1,175 +1,502 @@
 # PostHog Python library example
-import argparse
+#
+# This script demonstrates various PostHog Python SDK capabilities including:
+# - Basic event capture and user identification
+# - Feature flag local evaluation
+# - Feature flag payloads
+# - Context management and tagging
+#
+# Setup:
+# 1. Copy .env.example to .env and fill in your PostHog credentials
+# 2. Run this script and choose from the interactive menu
+
+import os
 
 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)",
-)
-args = parser.parse_args()
 
-posthog.debug = True
+def load_env_file():
+    """Load environment variables from .env file if it exists."""
+    env_path = os.path.join(os.path.dirname(__file__), ".env")
+    if os.path.exists(env_path):
+        with open(env_path, "r") as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, value = line.split("=", 1)
+                    os.environ.setdefault(key.strip(), value.strip())
 
-# You can find this key on the /setup page in PostHog
-posthog.project_api_key = "phc_gtWmTq3Pgl06u4sZY3TRcoQfp42yfuXHKoe8ZVSR6Kh"
-posthog.personal_api_key = "phx_fiRCOQkTA3o2ePSdLrFDAILLHjMu2Mv52vUi8MNruIm"
 
-# Where you host PostHog, with no trailing /.
-# You can remove this line if you're using posthog.com
-posthog.host = "http://localhost:8000"
-posthog.poll_interval = 10
+# Load .env file if it exists
+load_env_file()
 
-print(
-    posthog.feature_enabled(
-        args.flag,  # Use the flag from command line arguments
-        "12345",
-        groups={"organization": str("0182ee91-8ef7-0000-4cb9-fedc5f00926a")},
-        group_properties={
-            "organization": {
-                "id": "0182ee91-8ef7-0000-4cb9-fedc5f00926a",
-                "created_at": "2022-06-30 11:44:52.984121+00:00",
-            }
-        },
+# Get configuration
+project_key = os.getenv("POSTHOG_PROJECT_API_KEY", "")
+personal_api_key = os.getenv("POSTHOG_PERSONAL_API_KEY", "")
+host = os.getenv("POSTHOG_HOST", "http://localhost:8000")
+
+# Check if credentials are provided
+if not project_key or not personal_api_key:
+    print("❌ Missing PostHog credentials!")
+    print(
+        "   Please set POSTHOG_PROJECT_API_KEY and POSTHOG_PERSONAL_API_KEY environment variables"
+    )
+    print("   or copy .env.example to .env and fill in your values")
+    exit(1)
+
+# Test authentication before proceeding
+print("🔑 Testing PostHog authentication...")
+
+try:
+    # Configure PostHog with credentials
+    posthog.debug = False  # Keep quiet during auth test
+    posthog.api_key = project_key
+    posthog.project_api_key = project_key
+    posthog.personal_api_key = personal_api_key
+    posthog.host = host
+    posthog.poll_interval = 10
+
+    # Test by attempting to get feature flags (this validates both keys)
+    # This will fail if credentials are invalid
+    test_flags = posthog.get_all_flags("test_user", only_evaluate_locally=True)
+
+    # If we get here without exception, credentials work
+    print("✅ Authentication successful!")
+    print(f"   Project API Key: {project_key[:9]}...")
+    print("   Personal API Key: [REDACTED]")
+    print(f"   Host: {host}\n\n")
+
+except Exception as e:
+    print("❌ Authentication failed!")
+    print(f"   Error: {e}")
+    print("\n   Please check your credentials:")
+    print("   - POSTHOG_PROJECT_API_KEY: Project API key from PostHog settings")
+    print(
+        "   - POSTHOG_PERSONAL_API_KEY: Personal API key (required for local evaluation)"
+    )
+    print("   - POSTHOG_HOST: Your PostHog instance URL")
+    exit(1)
+
+# Display menu and get user choice
+print("🚀 PostHog Python SDK Demo - Choose an example to run:\n")
+print("1. Identify and capture examples")
+print("2. Feature flag local evaluation examples")
+print("3. Feature flag payload examples")
+print("4. Flag dependencies examples")
+print("5. Context management and tagging examples")
+print("6. Run all examples")
+print("7. Exit")
+choice = input("\nEnter your choice (1-7): ").strip()
+
+if choice == "1":
+    print("\n" + "=" * 60)
+    print("IDENTIFY AND CAPTURE EXAMPLES")
+    print("=" * 60)
+
+    posthog.debug = True
+
+    # Capture an event
+    print("📊 Capturing events...")
+    posthog.capture(
+        "event",
+        distinct_id="distinct_id",
+        properties={"property1": "value", "property2": "value"},
+        send_feature_flags=True,
+    )
+
+    # Alias a previous distinct id with a new one
+    print("🔗 Creating alias...")
+    posthog.alias("distinct_id", "new_distinct_id")
+
+    posthog.capture(
+        "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
+    print("👤 Identifying user...")
+    posthog.set(
+        distinct_id="new_distinct_id", properties={"email": "something@something.com"}
+    )
+
+    # Add properties to a group
+    print("🏢 Identifying group...")
+    posthog.group_identify("company", "id:5", {"employees": 11})
+
+    # Properties set only once to the person
+    print("🔒 Setting properties once...")
+    posthog.set_once(
+        distinct_id="new_distinct_id", properties={"self_serve_signup": True}
+    )
+
+    # This will not change the property (because it was already set)
+    posthog.set_once(
+        distinct_id="new_distinct_id", properties={"self_serve_signup": False}
+    )
+
+    print("🔄 Updating properties...")
+    posthog.set(distinct_id="new_distinct_id", properties={"current_browser": "Chrome"})
+    posthog.set(
+        distinct_id="new_distinct_id", properties={"current_browser": "Firefox"}
+    )
+
+elif choice == "2":
+    print("\n" + "=" * 60)
+    print("FEATURE FLAG LOCAL EVALUATION EXAMPLES")
+    print("=" * 60)
+
+    posthog.debug = True
+
+    print("🏁 Testing basic feature flags...")
+    print(
+        f"beta-feature for 'distinct_id': {posthog.feature_enabled('beta-feature', 'distinct_id')}"
+    )
+    print(
+        f"beta-feature for 'new_distinct_id': {posthog.feature_enabled('beta-feature', 'new_distinct_id')}"
+    )
+    print(
+        f"beta-feature with groups: {posthog.feature_enabled('beta-feature-groups', 'distinct_id', groups={'company': 'id:5'})}"
+    )
+
+    print("\n🌍 Testing location-based flags...")
+    # Assume test-flag has `City Name = Sydney` as a person property set
+    print(
+        f"Sydney user: {posthog.feature_enabled('test-flag', 'random_id_12345', person_properties={'$geoip_city_name': 'Sydney'})}"
+    )
+
+    print(
+        f"Sydney user (local only): {posthog.feature_enabled('test-flag', 'distinct_id_random_22', person_properties={'$geoip_city_name': 'Sydney'}, only_evaluate_locally=True)}"
+    )
+
+    print("\n📋 Getting all flags...")
+    print(f"All flags: {posthog.get_all_flags('distinct_id_random_22')}")
+    print(
+        f"All flags (local): {posthog.get_all_flags('distinct_id_random_22', only_evaluate_locally=True)}"
+    )
+    print(
+        f"All flags with properties: {posthog.get_all_flags('distinct_id_random_22', person_properties={'$geoip_city_name': 'Sydney'}, only_evaluate_locally=True)}"
+    )
+
+elif choice == "3":
+    print("\n" + "=" * 60)
+    print("FEATURE FLAG PAYLOAD EXAMPLES")
+    print("=" * 60)
+
+    posthog.debug = True
+
+    print("📦 Testing feature flag payloads...")
+    print(
+        f"beta-feature payload: {posthog.get_feature_flag_payload('beta-feature', 'distinct_id')}"
+    )
+    print(
+        f"All flags and payloads: {posthog.get_all_flags_and_payloads('distinct_id')}"
+    )
+    print(
+        f"Remote config payload: {posthog.get_remote_config_payload('encrypted_payload_flag_key')}"
+    )
+
+    # Get feature flag result with all details (enabled, variant, payload, key, reason)
+    print("\n🔍 Getting detailed flag result...")
+    result = posthog.get_feature_flag_result("beta-feature", "distinct_id")
+    if result:
+        print(f"Flag key: {result.key}")
+        print(f"Flag enabled: {result.enabled}")
+        print(f"Variant: {result.variant}")
+        print(f"Payload: {result.payload}")
+        print(f"Reason: {result.reason}")
+        # get_value() returns the variant if it exists, otherwise the enabled value
+        print(f"Value (variant or enabled): {result.get_value()}")
+
+elif choice == "4":
+    print("\n" + "=" * 60)
+    print("FLAG DEPENDENCIES EXAMPLES")
+    print("=" * 60)
+    print("🔗 Testing flag dependencies with local evaluation...")
+    print(
+        "   Flag structure: 'test-flag-dependency' depends on 'beta-feature' being enabled"
+    )
+    print("")
+    print("📋 Required setup (if 'test-flag-dependency' doesn't exist):")
+    print("   1. Create feature flag 'beta-feature':")
+    print("      - Condition: email contains '@example.com'")
+    print("      - Rollout: 100%")
+    print("   2. Create feature flag 'test-flag-dependency':")
+    print("      - Condition: flag 'beta-feature' is enabled")
+    print("      - Rollout: 100%")
+    print("")
+
+    posthog.debug = True
+
+    # Test @example.com user (should satisfy dependency if flags exist)
+    result1 = posthog.feature_enabled(
+        "test-flag-dependency",
+        "example_user",
+        person_properties={"email": "user@example.com"},
         only_evaluate_locally=True,
     )
-)
+    print(f"✅ @example.com user (test-flag-dependency): {result1}")
 
-
-# Capture an event
-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", "distinct_id"))
-
-# get payload
-print(posthog.get_feature_flag_payload("beta-feature", "distinct_id"))
-print(posthog.get_all_flags_and_payloads("distinct_id"))
-exit()
-# # Alias a previous distinct id with a new one
-
-posthog.alias("distinct_id", "new_distinct_id")
-
-posthog.capture(
-    "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.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(distinct_id="new_distinct_id", properties={"self_serve_signup": True})
-
-
-posthog.set_once(
-    distinct_id="new_distinct_id", properties={"self_serve_signup": False}
-)  # this will not change the property (because it was already set)
-
-posthog.set(distinct_id="new_distinct_id", properties={"current_browser": "Chrome"})
-posthog.set(distinct_id="new_distinct_id", properties={"current_browser": "Firefox"})
-
-
-# #############################################################################
-# Make sure you have a personal API key for the examples below
-
-# 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"},
+    # Test non-example.com user (dependency should not be satisfied)
+    result2 = posthog.feature_enabled(
+        "test-flag-dependency",
+        "regular_user",
+        person_properties={"email": "user@other.com"},
         only_evaluate_locally=True,
     )
-)
+    print(f"❌ Regular user (test-flag-dependency): {result2}")
 
-
-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"},
+    # Test beta-feature directly for comparison
+    beta1 = posthog.feature_enabled(
+        "beta-feature",
+        "example_user",
+        person_properties={"email": "user@example.com"},
         only_evaluate_locally=True,
     )
-)
-print(posthog.get_remote_config_payload("encrypted_payload_flag_key"))
+    beta2 = posthog.feature_enabled(
+        "beta-feature",
+        "regular_user",
+        person_properties={"email": "user@other.com"},
+        only_evaluate_locally=True,
+    )
+    print(f"📊 Beta feature comparison - @example.com: {beta1}, regular: {beta2}")
 
+    print("\n🎯 Results Summary:")
+    print(
+        f"   - Flag dependencies evaluated locally: {'✅ YES' if result1 != result2 else '❌ NO'}"
+    )
+    print("   - Zero API calls needed: ✅ YES (all evaluated locally)")
+    print("   - Python SDK supports flag dependencies: ✅ YES")
 
-# You can add tags to a context, and these are automatically added to any events (including exceptions) captured
-# within that context.
+    print("\n" + "-" * 60)
+    print("PRODUCTION-STYLE MULTIVARIATE DEPENDENCY CHAIN")
+    print("-" * 60)
+    print("🔗 Testing complex multivariate flag dependencies...")
+    print(
+        "   Structure: multivariate-root-flag -> multivariate-intermediate-flag -> multivariate-leaf-flag"
+    )
+    print("")
+    print("📋 Required setup (if flags don't exist):")
+    print(
+        "   1. Create 'multivariate-leaf-flag' with fruit variants (pineapple, mango, papaya, kiwi)"
+    )
+    print("      - pineapple: email = 'pineapple@example.com'")
+    print("      - mango: email = 'mango@example.com'")
+    print(
+        "   2. Create 'multivariate-intermediate-flag' with color variants (blue, red)"
+    )
+    print("      - blue: depends on multivariate-leaf-flag = 'pineapple'")
+    print("      - red: depends on multivariate-leaf-flag = 'mango'")
+    print(
+        "   3. Create 'multivariate-root-flag' with show variants (breaking-bad, the-wire)"
+    )
+    print("      - breaking-bad: depends on multivariate-intermediate-flag = 'blue'")
+    print("      - the-wire: depends on multivariate-intermediate-flag = 'red'")
+    print("")
 
-# 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"})
+    # Test pineapple -> blue -> breaking-bad chain
+    dependent_result3 = posthog.get_feature_flag(
+        "multivariate-root-flag",
+        "regular_user",
+        person_properties={"email": "pineapple@example.com"},
+        only_evaluate_locally=True,
+    )
+    if str(dependent_result3) != "breaking-bad":
+        print(
+            f"     ❌ Something went wrong evaluating 'multivariate-root-flag' with pineapple@example.com. Expected 'breaking-bad', got '{dependent_result3}'"
+        )
+    else:
+        print("✅ 'multivariate-root-flag' with email pineapple@example.com succeeded")
 
-    # 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")
+    # Test mango -> red -> the-wire chain
+    dependent_result4 = posthog.get_feature_flag(
+        "multivariate-root-flag",
+        "regular_user",
+        person_properties={"email": "mango@example.com"},
+        only_evaluate_locally=True,
+    )
+    if str(dependent_result4) != "the-wire":
+        print(
+            f"     ❌ Something went wrong evaluating multivariate-root-flag with mango@example.com. Expected 'the-wire', got '{dependent_result4}'"
+        )
+    else:
+        print("✅ 'multivariate-root-flag' with email mango@example.com succeeded")
 
+    # Show the complete chain evaluation
+    print("\n🔍 Complete dependency chain evaluation:")
+    for email, expected_chain in [
+        ("pineapple@example.com", ["pineapple", "blue", "breaking-bad"]),
+        ("mango@example.com", ["mango", "red", "the-wire"]),
+    ]:
+        leaf = posthog.get_feature_flag(
+            "multivariate-leaf-flag",
+            "regular_user",
+            person_properties={"email": email},
+            only_evaluate_locally=True,
+        )
+        intermediate = posthog.get_feature_flag(
+            "multivariate-intermediate-flag",
+            "regular_user",
+            person_properties={"email": email},
+            only_evaluate_locally=True,
+        )
+        root = posthog.get_feature_flag(
+            "multivariate-root-flag",
+            "regular_user",
+            person_properties={"email": email},
+            only_evaluate_locally=True,
+        )
 
-# 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")
+        actual_chain = [str(leaf), str(intermediate), str(root)]
+        chain_success = actual_chain == expected_chain
 
+        print(f"   📧 {email}:")
+        print(f"      Expected: {' -> '.join(map(str, expected_chain))}")
+        print(f"      Actual:   {' -> '.join(map(str, actual_chain))}")
+        print(f"      Status:   {'✅ SUCCESS' if chain_success else '❌ 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")
+    print("\n🎯 Multivariate Chain Summary:")
+    print("   - Complex dependency chains: ✅ SUPPORTED")
+    print("   - Multivariate flag dependencies: ✅ SUPPORTED")
+    print("   - Local evaluation of chains: ✅ WORKING")
 
+elif choice == "5":
+    print("\n" + "=" * 60)
+    print("CONTEXT MANAGEMENT AND TAGGING EXAMPLES")
+    print("=" * 60)
 
-# 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.debug = True
 
+    print("🏷️ Testing context management...")
+    print(
+        "You can add tags to a context, and these are automatically added to any events 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.
+    try:
+        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")
+            print("✅ Event captured with inherited context tags")
+            # This exception will be captured with the tags set above
+            # raise Exception("Order processing failed")
+    except Exception as e:
+        print(f"Exception captured: {e}")
+
+    # Use fresh=True to start with a clean context (no inherited tags)
+    try:
+        with posthog.new_context(fresh=True):
+            posthog.tag("session_id", "xyz789")
+            # Only session_id tag will be present, no inherited tags
+            posthog.capture("session_event")
+            print("✅ Event captured with fresh context tags")
+            # raise Exception("Session handling failed")
+    except Exception as e:
+        print(f"Exception captured: {e}")
+
+    # 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)
+        posthog.capture("order_step_completed")
+        print(f"✅ Order {order_id} processed with scoped context")
+        # 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)
+        posthog.capture("payment_processed")
+        print(f"✅ Payment {payment_id} processed with fresh scoped context")
+        # Only payment_id tag will be present, no inherited tags
+        # raise Exception("Payment processing failed")
+
+    process_order("12345")
+    process_payment("67890")
+
+elif choice == "6":
+    print("\n🔄 Running all examples...")
+
+    # Run example 1
+    print(f"\n{'🔸' * 20} IDENTIFY AND CAPTURE {'🔸' * 20}")
+    posthog.debug = True
+    print("📊 Capturing events...")
+    posthog.capture(
+        "event",
+        distinct_id="distinct_id",
+        properties={"property1": "value", "property2": "value"},
+        send_feature_flags=True,
+    )
+    print("🔗 Creating alias...")
+    posthog.alias("distinct_id", "new_distinct_id")
+    print("👤 Identifying user...")
+    posthog.set(
+        distinct_id="new_distinct_id", properties={"email": "something@something.com"}
+    )
+
+    # Run example 2
+    print(f"\n{'🔸' * 20} FEATURE FLAGS {'🔸' * 20}")
+    print("🏁 Testing basic feature flags...")
+    print(f"beta-feature: {posthog.feature_enabled('beta-feature', 'distinct_id')}")
+    print(
+        f"Sydney user: {posthog.feature_enabled('test-flag', 'random_id_12345', person_properties={'$geoip_city_name': 'Sydney'})}"
+    )
+
+    # Run example 3
+    print(f"\n{'🔸' * 20} PAYLOADS {'🔸' * 20}")
+    print("📦 Testing payloads...")
+    print(f"Payload: {posthog.get_feature_flag_payload('beta-feature', 'distinct_id')}")
+
+    # Run example 4
+    print(f"\n{'🔸' * 20} FLAG DEPENDENCIES {'🔸' * 20}")
+    print("🔗 Testing flag dependencies...")
+    result1 = posthog.feature_enabled(
+        "test-flag-dependency",
+        "demo_user",
+        person_properties={"email": "user@example.com"},
+        only_evaluate_locally=True,
+    )
+    result2 = posthog.feature_enabled(
+        "test-flag-dependency",
+        "demo_user2",
+        person_properties={"email": "user@other.com"},
+        only_evaluate_locally=True,
+    )
+    print(f"✅ @example.com user: {result1}, regular user: {result2}")
+
+    # Run example 5
+    print(f"\n{'🔸' * 20} CONTEXT MANAGEMENT {'🔸' * 20}")
+    print("🏷️ Testing context management...")
+    with posthog.new_context():
+        posthog.tag("demo_run", "all_examples")
+        posthog.capture("demo_completed")
+        print("✅ Demo completed with context tags")
+
+elif choice == "7":
+    print("👋 Goodbye!")
+    posthog.shutdown()
+    exit()
+
+else:
+    print("❌ Invalid choice. Please run again and select 1-7.")
+    posthog.shutdown()
+    exit()
+
+print("\n" + "=" * 60)
+print("✅ Example completed!")
+print("=" * 60)
 
 posthog.shutdown()

mypy-baseline.txt

@@ -36,9 +36,5 @@ 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/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: 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/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]

posthog/__init__.py

@@ -11,7 +11,8 @@ from posthog.contexts import (
     set_context_session as inner_set_context_session,
     identify_context as inner_identify_context,
 )
-from posthog.types import FeatureFlag, FlagsAndPayloads
+from posthog.feature_flags import InconclusiveMatchError, RequiresServerEvaluation
+from posthog.types import FeatureFlag, FlagsAndPayloads, FeatureFlagResult
 from posthog.version import VERSION
 
 __version__ = VERSION
@@ -20,22 +21,105 @@ __version__ = VERSION
 
 
 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)
 
 
@@ -60,6 +144,9 @@ log_captured_exceptions = False  # type: bool
 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]
 
@@ -70,40 +157,62 @@ default_client = None  # type: Optional[Client]
 # 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
-    - `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
 
-    Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.
+    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
-    # Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)
-    with posthog.new_context():
-        # Associate this context with some user, by distinct_id
-        posthog.identify_context('some user')
+    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')
 
-        # Capture an event, associated with the context-level distinct ID ('some user')
-        posthog.capture('movie started')
+            # Capture an event, associated with the context-level distinct ID ('some user')
+            capture('movie started')
 
-        # Capture an event associated with some other user (overriding the context-level distinct ID)
-        posthog.capture('movie joined', distinct_id='some-other-user')
+            # 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
-        posthog.capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})
+            # Capture an event with some properties
+            capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})
 
-        # Capture an event with some properties
-        posthog.capture('purchase', properties={'product_id': '123', 'category': 'romcom'})
-        # Capture an event with some associated group
-        posthog.capture('purchase', groups={'company': 'id:5'})
+            # 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
-        posthog.tag_context('some-tag', 'some-value')
+            # Adding a tag to the current context will cause it to appear on all subsequent events
+            tag_context('some-tag', 'some-value')
 
-        posthog.capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict
-    ```
+            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"
+            }
+        )
+        ```
+    Category:
+        Events
     """
 
     return _proxy("capture", event, **kwargs)
@@ -112,21 +221,25 @@ def capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str]:
 def set(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
     """
     Set properties on a user record.
-    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.
+    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).
 
-    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='distinct id', properties={
-         '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
     """
 
     return _proxy("set", **kwargs)
@@ -135,10 +248,26 @@ def set(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
 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 `set`.
 
-    Otherwise, operates in an identical manner to `set`.
-     ```
+    Details:
+        This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.
+
+    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'}
+            }
+        )
+
+        ```
+    Category:
+        Identification
     """
     return _proxy("set_once", **kwargs)
 
@@ -153,18 +282,27 @@ def group_identify(
 ):
     # 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
+    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
     """
 
     return _proxy(
@@ -187,19 +325,26 @@ def alias(
 ):
     # 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?". Particularly useful for associating user behaviour before and after
-    they e.g. register, login, or perform some other identifying action.
+    Associate 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
+    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
 
-    For example:
-    ```python
-    posthog.alias('anonymous session id', 'distinct id')
-    ```
+    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.
+
+    Examples:
+        ```python
+        # Alias user
+        from posthog import alias
+        alias(previous_id='distinct_id', distinct_id='alias_id')
+        ```
+    Category:
+        Identification
     """
 
     return _proxy(
@@ -217,26 +362,25 @@ def capture_exception(
     **kwargs: Unpack[OptionalCaptureArgs],
 ):
     """
-    capture_exception allows you to capture exceptions that happen in your code.
+    Capture exceptions that happen in your code.
 
-    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)
+    Args:
+        exception: The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`
 
-    A `capture_exception` call does not require any fields, but we recommend passing an exception of some kind:
-    - `exception` to specify the exception to capture. If not provided, the current exception is captured via `sys.exc_info()`
+    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`.
 
-    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`.
+    Examples:
+        ```python
+        # Capture exception
+        from posthog import capture_exception
+        try:
+            risky_operation()
+        except Exception as e:
+            capture_exception(e)
+        ```
+    Category:
+        Events
     """
 
     return _proxy("capture_exception", exception=exception, **kwargs)
@@ -245,9 +389,9 @@ def capture_exception(
 def feature_enabled(
     key,  # type: str
     distinct_id,  # type: str
-    groups={},  # type: dict
-    person_properties={},  # type: dict
-    group_properties={},  # type: dict
+    groups=None,  # type: Optional[dict]
+    person_properties=None,  # type: Optional[dict]
+    group_properties=None,  # type: Optional[dict]
     only_evaluate_locally=False,  # type: bool
     send_feature_flag_events=True,  # type: bool
     disable_geoip=None,  # type: Optional[bool]
@@ -256,23 +400,37 @@ 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",
         key=key,
         distinct_id=distinct_id,
-        groups=groups,
-        person_properties=person_properties,
-        group_properties=group_properties,
+        groups=groups or {},
+        person_properties=person_properties or {},
+        group_properties=group_properties or {},
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
@@ -282,42 +440,47 @@ def feature_enabled(
 def get_feature_flag(
     key,  # type: str
     distinct_id,  # type: str
-    groups={},  # type: dict
-    person_properties={},  # type: dict
-    group_properties={},  # type: dict
+    groups=None,  # type: Optional[dict]
+    person_properties=None,  # type: Optional[dict]
+    group_properties=None,  # type: Optional[dict]
     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",
         key=key,
         distinct_id=distinct_id,
-        groups=groups,
-        person_properties=person_properties,
-        group_properties=group_properties,
+        groups=groups or {},
+        person_properties=person_properties or {},
+        group_properties=group_properties or {},
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
@@ -326,39 +489,96 @@ def get_feature_flag(
 
 def get_all_flags(
     distinct_id,  # type: str
-    groups={},  # type: dict
-    person_properties={},  # type: dict
-    group_properties={},  # type: dict
+    groups=None,  # type: Optional[dict]
+    person_properties=None,  # type: Optional[dict]
+    group_properties=None,  # type: Optional[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",
         distinct_id=distinct_id,
-        groups=groups,
-        person_properties=person_properties,
-        group_properties=group_properties,
+        groups=groups or {},
+        person_properties=person_properties or {},
+        group_properties=group_properties or {},
         only_evaluate_locally=only_evaluate_locally,
         disable_geoip=disable_geoip,
     )
 
 
+def get_feature_flag_result(
+    key,
+    distinct_id,
+    groups=None,  # type: Optional[dict]
+    person_properties=None,  # type: Optional[dict]
+    group_properties=None,  # type: Optional[dict]
+    only_evaluate_locally=False,
+    send_feature_flag_events=True,
+    disable_geoip=None,  # type: Optional[bool]
+):
+    # type: (...) -> Optional[FeatureFlagResult]
+    """
+    Get a FeatureFlagResult object which contains the flag result and payload.
+
+    This method evaluates a feature flag and returns a FeatureFlagResult object containing:
+    - enabled: Whether the flag is enabled
+    - variant: The variant value if the flag has variants
+    - payload: The payload associated with the flag (automatically deserialized from JSON)
+    - key: The flag key
+    - reason: Why the flag was enabled/disabled
+
+    Example:
+    ```python
+    result = posthog.get_feature_flag_result('beta-feature', 'distinct_id')
+    if result and result.enabled:
+        # Use the variant and payload
+        print(f"Variant: {result.variant}")
+        print(f"Payload: {result.payload}")
+    ```
+    """
+    return _proxy(
+        "get_feature_flag_result",
+        key=key,
+        distinct_id=distinct_id,
+        groups=groups or {},
+        person_properties=person_properties or {},
+        group_properties=group_properties or {},
+        only_evaluate_locally=only_evaluate_locally,
+        send_feature_flag_events=send_feature_flag_events,
+        disable_geoip=disable_geoip,
+    )
+
+
 def get_feature_flag_payload(
     key,
     distinct_id,
     match_value=None,
-    groups={},
-    person_properties={},
-    group_properties={},
+    groups=None,  # type: Optional[dict]
+    person_properties=None,  # type: Optional[dict]
+    group_properties=None,  # type: Optional[dict]
     only_evaluate_locally=False,
     send_feature_flag_events=True,
     disable_geoip=None,  # type: Optional[bool]
@@ -368,9 +588,9 @@ def get_feature_flag_payload(
         key=key,
         distinct_id=distinct_id,
         match_value=match_value,
-        groups=groups,
-        person_properties=person_properties,
-        group_properties=group_properties,
+        groups=groups or {},
+        person_properties=person_properties or {},
+        group_properties=group_properties or {},
         only_evaluate_locally=only_evaluate_locally,
         send_feature_flag_events=send_feature_flag_events,
         disable_geoip=disable_geoip,
@@ -399,50 +619,108 @@ def get_remote_config_payload(
 
 def get_all_flags_and_payloads(
     distinct_id,
-    groups={},
-    person_properties={},
-    group_properties={},
+    groups=None,  # type: Optional[dict]
+    person_properties=None,  # type: Optional[dict]
+    group_properties=None,  # type: Optional[dict]
     only_evaluate_locally=False,
     disable_geoip=None,  # type: Optional[bool]
 ) -> FlagsAndPayloads:
     return _proxy(
         "get_all_flags_and_payloads",
         distinct_id=distinct_id,
-        groups=groups,
-        person_properties=person_properties,
-        group_properties=group_properties,
+        groups=groups or {},
+        person_properties=person_properties or {},
+        group_properties=group_properties or {},
         only_evaluate_locally=only_evaluate_locally,
         disable_geoip=disable_geoip,
     )
 
 
 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 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 setup():
+def setup() -> Client:
     global default_client
     if not default_client:
         if not api_key:
@@ -465,12 +743,15 @@ def setup():
             # 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,
             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."""

posthog/ai/anthropic/__init__.py

@@ -6,6 +6,12 @@ from .anthropic_providers import (
     AsyncAnthropicBedrock,
     AsyncAnthropicVertex,
 )
+from .anthropic_converter import (
+    format_anthropic_response,
+    format_anthropic_input,
+    extract_anthropic_tools,
+    format_anthropic_streaming_content,
+)
 
 __all__ = [
     "Anthropic",
@@ -14,4 +20,8 @@ __all__ = [
     "AsyncAnthropicBedrock",
     "AnthropicVertex",
     "AsyncAnthropicVertex",
+    "format_anthropic_response",
+    "format_anthropic_input",
+    "extract_anthropic_tools",
+    "format_anthropic_streaming_content",
 ]

posthog/ai/anthropic/anthropic.py

@@ -8,15 +8,23 @@ except ImportError:
 
 import time
 import uuid
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
+from posthog.ai.types import StreamingContentBlock, TokenUsage, ToolInProgress
 from posthog.ai.utils import (
     call_llm_and_track_usage,
-    get_model_params,
-    merge_system_prompt,
-    with_privacy_mode,
+    merge_usage_stats,
 )
+from posthog.ai.anthropic.anthropic_converter import (
+    extract_anthropic_usage_from_event,
+    handle_anthropic_content_block_start,
+    handle_anthropic_text_delta,
+    handle_anthropic_tool_delta,
+    finalize_anthropic_tool_input,
+)
+from posthog.ai.sanitization import sanitize_anthropic
 from posthog.client import Client as PostHogClient
+from posthog import setup
 
 
 class Anthropic(anthropic.Anthropic):
@@ -26,14 +34,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)
 
 
@@ -60,6 +68,7 @@ class WrappedMessages(Messages):
             posthog_groups: Optional group analytics properties
             **kwargs: Arguments passed to Anthropic's messages.create
         """
+
         if posthog_trace_id is None:
             posthog_trace_id = str(uuid.uuid4())
 
@@ -117,35 +126,66 @@ class WrappedMessages(Messages):
         **kwargs: Any,
     ):
         start_time = time.time()
-        usage_stats: Dict[str, int] = {"input_tokens": 0, "output_tokens": 0}
-        accumulated_content = []
+        usage_stats: TokenUsage = TokenUsage(input_tokens=0, output_tokens=0)
+        accumulated_content = ""
+        content_blocks: List[StreamingContentBlock] = []
+        tools_in_progress: Dict[str, ToolInProgress] = {}
+        current_text_block: Optional[StreamingContentBlock] = None
         response = super().create(**kwargs)
 
         def generator():
             nonlocal usage_stats
-            nonlocal accumulated_content  # noqa: F824
+            nonlocal accumulated_content
+            nonlocal content_blocks
+            nonlocal tools_in_progress
+            nonlocal current_text_block
+
             try:
                 for event in response:
-                    if hasattr(event, "usage") and event.usage:
-                        usage_stats = {
-                            k: getattr(event.usage, k, 0)
-                            for k in [
-                                "input_tokens",
-                                "output_tokens",
-                                "cache_read_input_tokens",
-                                "cache_creation_input_tokens",
-                            ]
-                        }
+                    # Extract usage stats from event
+                    event_usage = extract_anthropic_usage_from_event(event)
+                    merge_usage_stats(usage_stats, event_usage)
 
-                    if hasattr(event, "content") and event.content:
-                        accumulated_content.append(event.content)
+                    # Handle content block start events
+                    if hasattr(event, "type") and event.type == "content_block_start":
+                        block, tool = handle_anthropic_content_block_start(event)
+
+                        if block:
+                            content_blocks.append(block)
+
+                            if block.get("type") == "text":
+                                current_text_block = block
+                            else:
+                                current_text_block = None
+
+                        if tool:
+                            tool_id = tool["block"].get("id")
+                            if tool_id:
+                                tools_in_progress[tool_id] = tool
+
+                    # Handle text delta events
+                    delta_text = handle_anthropic_text_delta(event, current_text_block)
+
+                    if delta_text:
+                        accumulated_content += delta_text
+
+                    # Handle tool input delta events
+                    handle_anthropic_tool_delta(
+                        event, content_blocks, tools_in_progress
+                    )
+
+                    # Handle content block stop events
+                    if hasattr(event, "type") and event.type == "content_block_stop":
+                        current_text_block = None
+                        finalize_anthropic_tool_input(
+                            event, content_blocks, tools_in_progress
+                        )
 
                     yield event
 
             finally:
                 end_time = time.time()
                 latency = end_time - start_time
-                output = "".join(accumulated_content)
 
                 self._capture_streaming_event(
                     posthog_distinct_id,
@@ -156,7 +196,8 @@ class WrappedMessages(Messages):
                     kwargs,
                     usage_stats,
                     latency,
-                    output,
+                    content_blocks,
+                    accumulated_content,
                 )
 
         return generator()
@@ -169,49 +210,39 @@ class WrappedMessages(Messages):
         posthog_privacy_mode: bool,
         posthog_groups: Optional[Dict[str, Any]],
         kwargs: Dict[str, Any],
-        usage_stats: Dict[str, int],
+        usage_stats: TokenUsage,
         latency: float,
-        output: str,
+        content_blocks: List[StreamingContentBlock],
+        accumulated_content: str,
     ):
-        if posthog_trace_id is None:
-            posthog_trace_id = str(uuid.uuid4())
+        from posthog.ai.types import StreamingEventData
+        from posthog.ai.anthropic.anthropic_converter import (
+            format_anthropic_streaming_input,
+            format_anthropic_streaming_output_complete,
+        )
+        from posthog.ai.utils import capture_streaming_event
 
-        event_properties = {
-            "$ai_provider": "anthropic",
-            "$ai_model": kwargs.get("model"),
-            "$ai_model_parameters": get_model_params(kwargs),
-            "$ai_input": with_privacy_mode(
-                self._client._ph_client,
-                posthog_privacy_mode,
-                merge_system_prompt(kwargs, "anthropic"),
-            ),
-            "$ai_output_choices": with_privacy_mode(
-                self._client._ph_client,
-                posthog_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_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_properties or {}),
-        }
+        # Prepare standardized event data
+        formatted_input = format_anthropic_streaming_input(kwargs)
+        sanitized_input = sanitize_anthropic(formatted_input)
 
-        if posthog_distinct_id is None:
-            event_properties["$process_person_profile"] = False
+        event_data = StreamingEventData(
+            provider="anthropic",
+            model=kwargs.get("model", "unknown"),
+            base_url=str(self._client.base_url),
+            kwargs=kwargs,
+            formatted_input=sanitized_input,
+            formatted_output=format_anthropic_streaming_output_complete(
+                content_blocks, accumulated_content
+            ),
+            usage_stats=usage_stats,
+            latency=latency,
+            distinct_id=posthog_distinct_id,
+            trace_id=posthog_trace_id,
+            properties=posthog_properties,
+            privacy_mode=posthog_privacy_mode,
+            groups=posthog_groups,
+        )
 
-        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,
-            )
+        # Use the common capture function
+        capture_streaming_event(self._client._ph_client, event_data)

posthog/ai/anthropic/anthropic_async.py

@@ -8,14 +8,27 @@ except ImportError:
 
 import time
 import uuid
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
+from posthog import setup
+from posthog.ai.types import StreamingContentBlock, TokenUsage, ToolInProgress
 from posthog.ai.utils import (
     call_llm_and_track_usage_async,
+    extract_available_tool_calls,
     get_model_params,
     merge_system_prompt,
+    merge_usage_stats,
     with_privacy_mode,
 )
+from posthog.ai.anthropic.anthropic_converter import (
+    format_anthropic_streaming_content,
+    extract_anthropic_usage_from_event,
+    handle_anthropic_content_block_start,
+    handle_anthropic_text_delta,
+    handle_anthropic_tool_delta,
+    finalize_anthropic_tool_input,
+)
+from posthog.ai.sanitization import sanitize_anthropic
 from posthog.client import Client as PostHogClient
 
 
@@ -26,14 +39,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)
 
 
@@ -60,6 +73,7 @@ class AsyncWrappedMessages(AsyncMessages):
             posthog_groups: Optional group analytics properties
             **kwargs: Arguments passed to Anthropic's messages.create
         """
+
         if posthog_trace_id is None:
             posthog_trace_id = str(uuid.uuid4())
 
@@ -117,35 +131,66 @@ class AsyncWrappedMessages(AsyncMessages):
         **kwargs: Any,
     ):
         start_time = time.time()
-        usage_stats: Dict[str, int] = {"input_tokens": 0, "output_tokens": 0}
-        accumulated_content = []
+        usage_stats: TokenUsage = TokenUsage(input_tokens=0, output_tokens=0)
+        accumulated_content = ""
+        content_blocks: List[StreamingContentBlock] = []
+        tools_in_progress: Dict[str, ToolInProgress] = {}
+        current_text_block: Optional[StreamingContentBlock] = None
         response = await super().create(**kwargs)
 
         async def generator():
             nonlocal usage_stats
-            nonlocal accumulated_content  # noqa: F824
+            nonlocal accumulated_content
+            nonlocal content_blocks
+            nonlocal tools_in_progress
+            nonlocal current_text_block
+
             try:
                 async for event in response:
-                    if hasattr(event, "usage") and event.usage:
-                        usage_stats = {
-                            k: getattr(event.usage, k, 0)
-                            for k in [
-                                "input_tokens",
-                                "output_tokens",
-                                "cache_read_input_tokens",
-                                "cache_creation_input_tokens",
-                            ]
-                        }
+                    # Extract usage stats from event
+                    event_usage = extract_anthropic_usage_from_event(event)
+                    merge_usage_stats(usage_stats, event_usage)
 
-                    if hasattr(event, "content") and event.content:
-                        accumulated_content.append(event.content)
+                    # Handle content block start events
+                    if hasattr(event, "type") and event.type == "content_block_start":
+                        block, tool = handle_anthropic_content_block_start(event)
+
+                        if block:
+                            content_blocks.append(block)
+
+                            if block.get("type") == "text":
+                                current_text_block = block
+                            else:
+                                current_text_block = None
+
+                        if tool:
+                            tool_id = tool["block"].get("id")
+                            if tool_id:
+                                tools_in_progress[tool_id] = tool
+
+                    # Handle text delta events
+                    delta_text = handle_anthropic_text_delta(event, current_text_block)
+
+                    if delta_text:
+                        accumulated_content += delta_text
+
+                    # Handle tool input delta events
+                    handle_anthropic_tool_delta(
+                        event, content_blocks, tools_in_progress
+                    )
+
+                    # Handle content block stop events
+                    if hasattr(event, "type") and event.type == "content_block_stop":
+                        current_text_block = None
+                        finalize_anthropic_tool_input(
+                            event, content_blocks, tools_in_progress
+                        )
 
                     yield event
 
             finally:
                 end_time = time.time()
                 latency = end_time - start_time
-                output = "".join(accumulated_content)
 
                 await self._capture_streaming_event(
                     posthog_distinct_id,
@@ -156,7 +201,8 @@ class AsyncWrappedMessages(AsyncMessages):
                     kwargs,
                     usage_stats,
                     latency,
-                    output,
+                    content_blocks,
+                    accumulated_content,
                 )
 
         return generator()
@@ -169,13 +215,29 @@ class AsyncWrappedMessages(AsyncMessages):
         posthog_privacy_mode: bool,
         posthog_groups: Optional[Dict[str, Any]],
         kwargs: Dict[str, Any],
-        usage_stats: Dict[str, int],
+        usage_stats: TokenUsage,
         latency: float,
-        output: str,
+        content_blocks: List[StreamingContentBlock],
+        accumulated_content: str,
     ):
         if posthog_trace_id is None:
             posthog_trace_id = str(uuid.uuid4())
 
+        # Format output using converter
+        formatted_content = format_anthropic_streaming_content(content_blocks)
+        formatted_output = []
+
+        if formatted_content:
+            formatted_output = [{"role": "assistant", "content": formatted_content}]
+        else:
+            # Fallback to accumulated content if no blocks
+            formatted_output = [
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": accumulated_content}],
+                }
+            ]
+
         event_properties = {
             "$ai_provider": "anthropic",
             "$ai_model": kwargs.get("model"),
@@ -183,12 +245,12 @@ class AsyncWrappedMessages(AsyncMessages):
             "$ai_input": with_privacy_mode(
                 self._client._ph_client,
                 posthog_privacy_mode,
-                merge_system_prompt(kwargs, "anthropic"),
+                sanitize_anthropic(merge_system_prompt(kwargs, "anthropic")),
             ),
             "$ai_output_choices": with_privacy_mode(
                 self._client._ph_client,
                 posthog_privacy_mode,
-                [{"content": output, "role": "assistant"}],
+                formatted_output,
             ),
             "$ai_http_status": 200,
             "$ai_input_tokens": usage_stats.get("input_tokens", 0),
@@ -205,6 +267,12 @@ class AsyncWrappedMessages(AsyncMessages):
             **(posthog_properties or {}),
         }
 
+        # Add tools if available
+        available_tools = extract_available_tool_calls("anthropic", kwargs)
+
+        if available_tools:
+            event_properties["$ai_tools"] = available_tools
+
         if posthog_distinct_id is None:
             event_properties["$process_person_profile"] = False
 

posthog/ai/anthropic/anthropic_converter.py

@@ -0,0 +1,403 @@
+"""
+Anthropic-specific conversion utilities.
+
+This module handles the conversion of Anthropic API responses and inputs
+into standardized formats for PostHog tracking.
+"""
+
+import json
+from typing import Any, Dict, List, Optional, Tuple
+
+from posthog.ai.types import (
+    FormattedContentItem,
+    FormattedFunctionCall,
+    FormattedMessage,
+    FormattedTextContent,
+    StreamingContentBlock,
+    TokenUsage,
+    ToolInProgress,
+)
+
+
+def format_anthropic_response(response: Any) -> List[FormattedMessage]:
+    """
+    Format an Anthropic response into standardized message format.
+
+    Args:
+        response: The response object from Anthropic API
+
+    Returns:
+        List of formatted messages with role and content
+    """
+
+    output: List[FormattedMessage] = []
+
+    if response is None:
+        return output
+
+    content: List[FormattedContentItem] = []
+
+    # Process content blocks from the response
+    if hasattr(response, "content"):
+        for choice in response.content:
+            if (
+                hasattr(choice, "type")
+                and choice.type == "text"
+                and hasattr(choice, "text")
+                and choice.text
+            ):
+                text_content: FormattedTextContent = {
+                    "type": "text",
+                    "text": choice.text,
+                }
+                content.append(text_content)
+
+            elif (
+                hasattr(choice, "type")
+                and choice.type == "tool_use"
+                and hasattr(choice, "name")
+                and hasattr(choice, "id")
+            ):
+                function_call: FormattedFunctionCall = {
+                    "type": "function",
+                    "id": choice.id,
+                    "function": {
+                        "name": choice.name,
+                        "arguments": getattr(choice, "input", {}),
+                    },
+                }
+                content.append(function_call)
+
+    if content:
+        message: FormattedMessage = {
+            "role": "assistant",
+            "content": content,
+        }
+        output.append(message)
+
+    return output
+
+
+def format_anthropic_input(
+    messages: List[Dict[str, Any]], system: Optional[str] = None
+) -> List[FormattedMessage]:
+    """
+    Format Anthropic input messages with optional system prompt.
+
+    Args:
+        messages: List of message dictionaries
+        system: Optional system prompt to prepend
+
+    Returns:
+        List of formatted messages
+    """
+
+    formatted_messages: List[FormattedMessage] = []
+
+    # Add system message if provided
+    if system is not None:
+        formatted_messages.append({"role": "system", "content": system})
+
+    # Add user messages
+    if messages:
+        for msg in messages:
+            # Messages are already in the correct format, just ensure type safety
+            formatted_msg: FormattedMessage = {
+                "role": msg.get("role", "user"),
+                "content": msg.get("content", ""),
+            }
+            formatted_messages.append(formatted_msg)
+
+    return formatted_messages
+
+
+def extract_anthropic_tools(kwargs: Dict[str, Any]) -> Optional[Any]:
+    """
+    Extract tool definitions from Anthropic API kwargs.
+
+    Args:
+        kwargs: Keyword arguments passed to Anthropic API
+
+    Returns:
+        Tool definitions if present, None otherwise
+    """
+
+    return kwargs.get("tools", None)
+
+
+def format_anthropic_streaming_content(
+    content_blocks: List[StreamingContentBlock],
+) -> List[FormattedContentItem]:
+    """
+    Format content blocks from Anthropic streaming response.
+
+    Used by streaming handlers to format accumulated content blocks.
+
+    Args:
+        content_blocks: List of content block dictionaries from streaming
+
+    Returns:
+        List of formatted content items
+    """
+
+    formatted: List[FormattedContentItem] = []
+
+    for block in content_blocks:
+        if block.get("type") == "text":
+            formatted.append(
+                {
+                    "type": "text",
+                    "text": block.get("text") or "",
+                }
+            )
+
+        elif block.get("type") == "function":
+            formatted.append(
+                {
+                    "type": "function",
+                    "id": block.get("id"),
+                    "function": block.get("function") or {},
+                }
+            )
+
+    return formatted
+
+
+def extract_anthropic_usage_from_response(response: Any) -> TokenUsage:
+    """
+    Extract usage from a full Anthropic response (non-streaming).
+
+    Args:
+        response: The complete response from Anthropic API
+
+    Returns:
+        TokenUsage with standardized usage
+    """
+    if not hasattr(response, "usage"):
+        return TokenUsage(input_tokens=0, output_tokens=0)
+
+    result = TokenUsage(
+        input_tokens=getattr(response.usage, "input_tokens", 0),
+        output_tokens=getattr(response.usage, "output_tokens", 0),
+    )
+
+    if hasattr(response.usage, "cache_read_input_tokens"):
+        cache_read = response.usage.cache_read_input_tokens
+        if cache_read and cache_read > 0:
+            result["cache_read_input_tokens"] = cache_read
+
+    if hasattr(response.usage, "cache_creation_input_tokens"):
+        cache_creation = response.usage.cache_creation_input_tokens
+        if cache_creation and cache_creation > 0:
+            result["cache_creation_input_tokens"] = cache_creation
+
+    return result
+
+
+def extract_anthropic_usage_from_event(event: Any) -> TokenUsage:
+    """
+    Extract usage statistics from an Anthropic streaming event.
+
+    Args:
+        event: Streaming event from Anthropic API
+
+    Returns:
+        Dictionary of usage statistics
+    """
+
+    usage: TokenUsage = TokenUsage()
+
+    # Handle usage stats from message_start event
+    if hasattr(event, "type") and event.type == "message_start":
+        if hasattr(event, "message") and hasattr(event.message, "usage"):
+            usage["input_tokens"] = getattr(event.message.usage, "input_tokens", 0)
+            usage["cache_creation_input_tokens"] = getattr(
+                event.message.usage, "cache_creation_input_tokens", 0
+            )
+            usage["cache_read_input_tokens"] = getattr(
+                event.message.usage, "cache_read_input_tokens", 0
+            )
+
+    # Handle usage stats from message_delta event
+    if hasattr(event, "usage") and event.usage:
+        usage["output_tokens"] = getattr(event.usage, "output_tokens", 0)
+
+    return usage
+
+
+def handle_anthropic_content_block_start(
+    event: Any,
+) -> Tuple[Optional[StreamingContentBlock], Optional[ToolInProgress]]:
+    """
+    Handle content block start event from Anthropic streaming.
+
+    Args:
+        event: Content block start event
+
+    Returns:
+        Tuple of (content_block, tool_in_progress)
+    """
+
+    if not (hasattr(event, "type") and event.type == "content_block_start"):
+        return None, None
+
+    if not hasattr(event, "content_block"):
+        return None, None
+
+    block = event.content_block
+
+    if not hasattr(block, "type"):
+        return None, None
+
+    if block.type == "text":
+        content_block: StreamingContentBlock = {"type": "text", "text": ""}
+        return content_block, None
+
+    elif block.type == "tool_use":
+        tool_block: StreamingContentBlock = {
+            "type": "function",
+            "id": getattr(block, "id", ""),
+            "function": {"name": getattr(block, "name", ""), "arguments": {}},
+        }
+        tool_in_progress: ToolInProgress = {"block": tool_block, "input_string": ""}
+        return tool_block, tool_in_progress
+
+    return None, None
+
+
+def handle_anthropic_text_delta(
+    event: Any, current_block: Optional[StreamingContentBlock]
+) -> Optional[str]:
+    """
+    Handle text delta event from Anthropic streaming.
+
+    Args:
+        event: Delta event
+        current_block: Current text block being accumulated
+
+    Returns:
+        Text delta if present
+    """
+
+    if hasattr(event, "delta") and hasattr(event.delta, "text"):
+        delta_text = event.delta.text or ""
+
+        if current_block is not None and current_block.get("type") == "text":
+            text_val = current_block.get("text")
+            if text_val is not None:
+                current_block["text"] = text_val + delta_text
+            else:
+                current_block["text"] = delta_text
+
+        return delta_text
+
+    return None
+
+
+def handle_anthropic_tool_delta(
+    event: Any,
+    content_blocks: List[StreamingContentBlock],
+    tools_in_progress: Dict[str, ToolInProgress],
+) -> None:
+    """
+    Handle tool input delta event from Anthropic streaming.
+
+    Args:
+        event: Tool delta event
+        content_blocks: List of content blocks
+        tools_in_progress: Dictionary tracking tools being accumulated
+    """
+
+    if not (hasattr(event, "type") and event.type == "content_block_delta"):
+        return
+
+    if not (
+        hasattr(event, "delta")
+        and hasattr(event.delta, "type")
+        and event.delta.type == "input_json_delta"
+    ):
+        return
+
+    if hasattr(event, "index") and event.index < len(content_blocks):
+        block = content_blocks[event.index]
+
+        if block.get("type") == "function" and block.get("id") in tools_in_progress:
+            tool = tools_in_progress[block["id"]]
+            partial_json = getattr(event.delta, "partial_json", "")
+            tool["input_string"] += partial_json
+
+
+def finalize_anthropic_tool_input(
+    event: Any,
+    content_blocks: List[StreamingContentBlock],
+    tools_in_progress: Dict[str, ToolInProgress],
+) -> None:
+    """
+    Finalize tool input when content block stops.
+
+    Args:
+        event: Content block stop event
+        content_blocks: List of content blocks
+        tools_in_progress: Dictionary tracking tools being accumulated
+    """
+
+    if not (hasattr(event, "type") and event.type == "content_block_stop"):
+        return
+
+    if hasattr(event, "index") and event.index < len(content_blocks):
+        block = content_blocks[event.index]
+
+        if block.get("type") == "function" and block.get("id") in tools_in_progress:
+            tool = tools_in_progress[block["id"]]
+
+            try:
+                block["function"]["arguments"] = json.loads(tool["input_string"])
+            except (json.JSONDecodeError, Exception):
+                # Keep empty dict if parsing fails
+                pass
+
+            del tools_in_progress[block["id"]]
+
+
+def format_anthropic_streaming_input(kwargs: Dict[str, Any]) -> Any:
+    """
+    Format Anthropic streaming input using system prompt merging.
+
+    Args:
+        kwargs: Keyword arguments passed to Anthropic API
+
+    Returns:
+        Formatted input ready for PostHog tracking
+    """
+    from posthog.ai.utils import merge_system_prompt
+
+    return merge_system_prompt(kwargs, "anthropic")
+
+
+def format_anthropic_streaming_output_complete(
+    content_blocks: List[StreamingContentBlock], accumulated_content: str
+) -> List[FormattedMessage]:
+    """
+    Format complete Anthropic streaming output.
+
+    Combines existing logic for formatting content blocks with fallback to accumulated content.
+
+    Args:
+        content_blocks: List of content blocks accumulated during streaming
+        accumulated_content: Raw accumulated text content as fallback
+
+    Returns:
+        Formatted messages ready for PostHog tracking
+    """
+    formatted_content = format_anthropic_streaming_content(content_blocks)
+
+    if formatted_content:
+        return [{"role": "assistant", "content": formatted_content}]
+    else:
+        # Fallback to accumulated content if no blocks
+        return [
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": accumulated_content}],
+            }
+        ]

posthog/ai/anthropic/anthropic_providers.py

@@ -5,9 +5,12 @@ except ImportError:
         "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):
@@ -17,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)
 
 
@@ -30,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)
 
 
@@ -43,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)
 
 
@@ -56,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

@@ -1,4 +1,9 @@
 from .gemini import Client
+from .gemini_converter import (
+    format_gemini_input,
+    format_gemini_response,
+    extract_gemini_tools,
+)
 
 
 # Create a genai-like module for perfect drop-in replacement
@@ -8,4 +13,10 @@ class _GenAI:
 
 genai = _GenAI()
 
-__all__ = ["Client", "genai"]
+__all__ = [
+    "Client",
+    "genai",
+    "format_gemini_input",
+    "format_gemini_response",
+    "extract_gemini_tools",
+]

posthog/ai/gemini/gemini.py

@@ -3,6 +3,9 @@ import time
 import uuid
 from typing import Any, Dict, Optional
 
+from posthog.ai.types import TokenUsage, StreamingEventData
+from posthog.ai.utils import merge_system_prompt
+
 try:
     from google import genai
 except ImportError:
@@ -10,11 +13,18 @@ except ImportError:
         "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,
+    capture_streaming_event,
+    merge_usage_stats,
 )
+from posthog.ai.gemini.gemini_converter import (
+    extract_gemini_usage_from_chunk,
+    extract_gemini_content_from_chunk,
+    format_gemini_streaming_output,
+)
+from posthog.ai.sanitization import sanitize_gemini
 from posthog.client import Client as PostHogClient
 
 
@@ -36,9 +46,17 @@ class Client:
         )
     """
 
+    _ph_client: PostHogClient
+
     def __init__(
         self,
         api_key: Optional[str] = None,
+        vertexai: Optional[bool] = None,
+        credentials: Optional[Any] = None,
+        project: Optional[str] = None,
+        location: Optional[str] = None,
+        debug_config: Optional[Any] = None,
+        http_options: Optional[Any] = None,
         posthog_client: Optional[PostHogClient] = None,
         posthog_distinct_id: Optional[str] = None,
         posthog_properties: Optional[Dict[str, Any]] = None,
@@ -48,7 +66,13 @@ class Client:
     ):
         """
         Args:
-            api_key: Google AI API key. If not provided, will use GOOGLE_API_KEY or API_KEY environment variable
+            api_key: Google AI API key. If not provided, will use GOOGLE_API_KEY or API_KEY environment variable (not required for Vertex AI)
+            vertexai: Whether to use Vertex AI authentication
+            credentials: Vertex AI credentials object
+            project: GCP project ID for Vertex AI
+            location: GCP location for Vertex AI
+            debug_config: Debug configuration for the client
+            http_options: HTTP options for the client
             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)
@@ -56,12 +80,21 @@ class Client:
             posthog_groups: Default groups for all calls (can be overridden per call)
             **kwargs: Additional arguments (for future compatibility)
         """
-        if posthog_client is None:
+
+        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=posthog_client,
+            vertexai=vertexai,
+            credentials=credentials,
+            project=project,
+            location=location,
+            debug_config=debug_config,
+            http_options=http_options,
+            posthog_client=self._ph_client,
             posthog_distinct_id=posthog_distinct_id,
             posthog_properties=posthog_properties,
             posthog_privacy_mode=posthog_privacy_mode,
@@ -80,6 +113,12 @@ class Models:
     def __init__(
         self,
         api_key: Optional[str] = None,
+        vertexai: Optional[bool] = None,
+        credentials: Optional[Any] = None,
+        project: Optional[str] = None,
+        location: Optional[str] = None,
+        debug_config: Optional[Any] = None,
+        http_options: Optional[Any] = None,
         posthog_client: Optional[PostHogClient] = None,
         posthog_distinct_id: Optional[str] = None,
         posthog_properties: Optional[Dict[str, Any]] = None,
@@ -89,7 +128,13 @@ class Models:
     ):
         """
         Args:
-            api_key: Google AI API key. If not provided, will use GOOGLE_API_KEY or API_KEY environment variable
+            api_key: Google AI API key. If not provided, will use GOOGLE_API_KEY or API_KEY environment variable (not required for Vertex AI)
+            vertexai: Whether to use Vertex AI authentication
+            credentials: Vertex AI credentials object
+            project: GCP project ID for Vertex AI
+            location: GCP location for Vertex AI
+            debug_config: Debug configuration for the client
+            http_options: HTTP options for the client
             posthog_client: PostHog client for tracking usage
             posthog_distinct_id: Default distinct ID for all calls
             posthog_properties: Default properties for all calls
@@ -97,10 +142,11 @@ class Models:
             posthog_groups: Default groups for all calls
             **kwargs: Additional arguments (for future compatibility)
         """
-        if posthog_client is None:
-            raise ValueError("posthog_client is required for PostHog tracking")
 
-        self._ph_client = posthog_client
+        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
@@ -108,16 +154,46 @@ class Models:
         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")
+        # Build genai.Client arguments
+        client_args: Dict[str, Any] = {}
 
-        if api_key is None:
-            raise ValueError(
-                "API key must be provided either as parameter or via GOOGLE_API_KEY/API_KEY environment variable"
-            )
+        # Add Vertex AI parameters if provided
+        if vertexai is not None:
+            client_args["vertexai"] = vertexai
 
-        self._client = genai.Client(api_key=api_key)
+        if credentials is not None:
+            client_args["credentials"] = credentials
+
+        if project is not None:
+            client_args["project"] = project
+
+        if location is not None:
+            client_args["location"] = location
+
+        if debug_config is not None:
+            client_args["debug_config"] = debug_config
+
+        if http_options is not None:
+            client_args["http_options"] = http_options
+
+        # Handle API key authentication
+        if vertexai:
+            # For Vertex AI, api_key is optional
+            if api_key is not None:
+                client_args["api_key"] = api_key
+        else:
+            # For non-Vertex AI mode, api_key is required (backwards compatibility)
+            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"
+                )
+
+            client_args["api_key"] = api_key
+
+        self._client = genai.Client(**client_args)
         self._base_url = "https://generativelanguage.googleapis.com"
 
     def _merge_posthog_params(
@@ -129,6 +205,7 @@ class Models:
         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
@@ -144,6 +221,7 @@ class Models:
 
         # Merge properties: default properties + call properties (call properties override)
         properties = dict(self._default_properties)
+
         if call_properties:
             properties.update(call_properties)
 
@@ -179,6 +257,7 @@ class Models:
             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(
@@ -217,7 +296,7 @@ class Models:
         **kwargs: Any,
     ):
         start_time = time.time()
-        usage_stats: Dict[str, int] = {"input_tokens": 0, "output_tokens": 0}
+        usage_stats: TokenUsage = TokenUsage(input_tokens=0, output_tokens=0)
         accumulated_content = []
 
         kwargs_without_stream = {"model": model, "contents": contents, **kwargs}
@@ -228,25 +307,24 @@ class Models:
             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
-                            ),
-                        }
+                    # Extract usage stats from chunk
+                    chunk_usage = extract_gemini_usage_from_chunk(chunk)
 
-                    if hasattr(chunk, "text") and chunk.text:
-                        accumulated_content.append(chunk.text)
+                    if chunk_usage:
+                        # Gemini reports cumulative totals, not incremental values
+                        merge_usage_stats(usage_stats, chunk_usage, mode="cumulative")
+
+                    # Extract content from chunk (now returns content blocks)
+                    content_block = extract_gemini_content_from_chunk(chunk)
+
+                    if content_block is not None:
+                        accumulated_content.append(content_block)
 
                     yield chunk
 
             finally:
                 end_time = time.time()
                 latency = end_time - start_time
-                output = "".join(accumulated_content)
 
                 self._capture_streaming_event(
                     model,
@@ -259,7 +337,7 @@ class Models:
                     kwargs,
                     usage_stats,
                     latency,
-                    output,
+                    accumulated_content,
                 )
 
         return generator()
@@ -274,63 +352,39 @@ class Models:
         privacy_mode: bool,
         groups: Optional[Dict[str, Any]],
         kwargs: Dict[str, Any],
-        usage_stats: Dict[str, int],
+        usage_stats: TokenUsage,
         latency: float,
-        output: str,
+        output: Any,
     ):
-        if trace_id is None:
-            trace_id = str(uuid.uuid4())
+        # Prepare standardized event data
+        formatted_input = self._format_input(contents, **kwargs)
+        sanitized_input = sanitize_gemini(formatted_input)
 
-        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 {}),
-        }
+        event_data = StreamingEventData(
+            provider="gemini",
+            model=model,
+            base_url=self._base_url,
+            kwargs=kwargs,
+            formatted_input=sanitized_input,
+            formatted_output=format_gemini_streaming_output(output),
+            usage_stats=usage_stats,
+            latency=latency,
+            distinct_id=distinct_id,
+            trace_id=trace_id,
+            properties=properties,
+            privacy_mode=privacy_mode,
+            groups=groups,
+        )
 
-        if distinct_id is None:
-            event_properties["$process_person_profile"] = False
+        # Use the common capture function
+        capture_streaming_event(self._ph_client, event_data)
 
-        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):
+    def _format_input(self, contents, **kwargs):
         """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)}]
+
+        # Create kwargs dict with contents for merge_system_prompt
+        input_kwargs = {"contents": contents, **kwargs}
+        return merge_system_prompt(input_kwargs, "gemini")
 
     def generate_content_stream(
         self,

posthog/ai/gemini/gemini_converter.py

@@ -0,0 +1,516 @@
+"""
+Gemini-specific conversion utilities.
+
+This module handles the conversion of Gemini API responses and inputs
+into standardized formats for PostHog tracking.
+"""
+
+from typing import Any, Dict, List, Optional, TypedDict, Union
+
+from posthog.ai.types import (
+    FormattedContentItem,
+    FormattedMessage,
+    TokenUsage,
+)
+
+
+class GeminiPart(TypedDict, total=False):
+    """Represents a part in a Gemini message."""
+
+    text: str
+
+
+class GeminiMessage(TypedDict, total=False):
+    """Represents a Gemini message with various possible fields."""
+
+    role: str
+    parts: List[Union[GeminiPart, Dict[str, Any]]]
+    content: Union[str, List[Any]]
+    text: str
+
+
+def _extract_text_from_parts(parts: List[Any]) -> str:
+    """
+    Extract and concatenate text from a parts array.
+
+    Args:
+        parts: List of parts that may contain text content
+
+    Returns:
+        Concatenated text from all parts
+    """
+
+    content_parts = []
+
+    for part in parts:
+        if isinstance(part, dict) and "text" in part:
+            content_parts.append(part["text"])
+
+        elif isinstance(part, str):
+            content_parts.append(part)
+
+        elif hasattr(part, "text"):
+            # Get the text attribute value
+            text_value = getattr(part, "text", "")
+            content_parts.append(text_value if text_value else str(part))
+
+        else:
+            content_parts.append(str(part))
+
+    return "".join(content_parts)
+
+
+def _format_dict_message(item: Dict[str, Any]) -> FormattedMessage:
+    """
+    Format a dictionary message into standardized format.
+
+    Args:
+        item: Dictionary containing message data
+
+    Returns:
+        Formatted message with role and content
+    """
+
+    # Handle dict format with parts array (Gemini-specific format)
+    if "parts" in item and isinstance(item["parts"], list):
+        content = _extract_text_from_parts(item["parts"])
+        return {"role": item.get("role", "user"), "content": content}
+
+    # Handle dict with content field
+    if "content" in item:
+        content = item["content"]
+
+        if isinstance(content, list):
+            # If content is a list, extract text from it
+            content = _extract_text_from_parts(content)
+
+        elif not isinstance(content, str):
+            content = str(content)
+
+        return {"role": item.get("role", "user"), "content": content}
+
+    # Handle dict with text field
+    if "text" in item:
+        return {"role": item.get("role", "user"), "content": item["text"]}
+
+    # Fallback to string representation
+    return {"role": "user", "content": str(item)}
+
+
+def _format_object_message(item: Any) -> FormattedMessage:
+    """
+    Format an object (with attributes) into standardized format.
+
+    Args:
+        item: Object that may have text or parts attributes
+
+    Returns:
+        Formatted message with role and content
+    """
+
+    # Handle object with parts attribute
+    if hasattr(item, "parts") and hasattr(item.parts, "__iter__"):
+        content = _extract_text_from_parts(item.parts)
+        role = getattr(item, "role", "user") if hasattr(item, "role") else "user"
+
+        # Ensure role is a string
+        if not isinstance(role, str):
+            role = "user"
+
+        return {"role": role, "content": content}
+
+    # Handle object with text attribute
+    if hasattr(item, "text"):
+        role = getattr(item, "role", "user") if hasattr(item, "role") else "user"
+
+        # Ensure role is a string
+        if not isinstance(role, str):
+            role = "user"
+
+        return {"role": role, "content": item.text}
+
+    # Handle object with content attribute
+    if hasattr(item, "content"):
+        role = getattr(item, "role", "user") if hasattr(item, "role") else "user"
+
+        # Ensure role is a string
+        if not isinstance(role, str):
+            role = "user"
+
+        content = item.content
+
+        if isinstance(content, list):
+            content = _extract_text_from_parts(content)
+
+        elif not isinstance(content, str):
+            content = str(content)
+        return {"role": role, "content": content}
+
+    # Fallback to string representation
+    return {"role": "user", "content": str(item)}
+
+
+def format_gemini_response(response: Any) -> List[FormattedMessage]:
+    """
+    Format a Gemini response into standardized message format.
+
+    Args:
+        response: The response object from Gemini API
+
+    Returns:
+        List of formatted messages with role and content
+    """
+
+    output: List[FormattedMessage] = []
+
+    if response is None:
+        return output
+
+    if hasattr(response, "candidates") and response.candidates:
+        for candidate in response.candidates:
+            if hasattr(candidate, "content") and candidate.content:
+                content: List[FormattedContentItem] = []
+
+                if hasattr(candidate.content, "parts") and candidate.content.parts:
+                    for part in candidate.content.parts:
+                        if hasattr(part, "text") and part.text:
+                            content.append(
+                                {
+                                    "type": "text",
+                                    "text": part.text,
+                                }
+                            )
+
+                        elif hasattr(part, "function_call") and part.function_call:
+                            function_call = part.function_call
+                            content.append(
+                                {
+                                    "type": "function",
+                                    "function": {
+                                        "name": function_call.name,
+                                        "arguments": function_call.args,
+                                    },
+                                }
+                            )
+
+                if content:
+                    output.append(
+                        {
+                            "role": "assistant",
+                            "content": content,
+                        }
+                    )
+
+            elif hasattr(candidate, "text") and candidate.text:
+                output.append(
+                    {
+                        "role": "assistant",
+                        "content": [{"type": "text", "text": candidate.text}],
+                    }
+                )
+
+    elif hasattr(response, "text") and response.text:
+        output.append(
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": response.text}],
+            }
+        )
+
+    return output
+
+
+def extract_gemini_system_instruction(config: Any) -> Optional[str]:
+    """
+    Extract system instruction from Gemini config parameter.
+
+    Args:
+        config: Config object or dict that may contain system instruction
+
+    Returns:
+        System instruction string if present, None otherwise
+    """
+    if config is None:
+        return None
+
+    # Handle different config formats
+    if hasattr(config, "system_instruction"):
+        return config.system_instruction
+    elif isinstance(config, dict) and "system_instruction" in config:
+        return config["system_instruction"]
+    elif isinstance(config, dict) and "systemInstruction" in config:
+        return config["systemInstruction"]
+
+    return None
+
+
+def extract_gemini_tools(kwargs: Dict[str, Any]) -> Optional[Any]:
+    """
+    Extract tool definitions from Gemini API kwargs.
+
+    Args:
+        kwargs: Keyword arguments passed to Gemini API
+
+    Returns:
+        Tool definitions if present, None otherwise
+    """
+
+    if "config" in kwargs and hasattr(kwargs["config"], "tools"):
+        return kwargs["config"].tools
+
+    return None
+
+
+def format_gemini_input_with_system(
+    contents: Any, config: Any = None
+) -> List[FormattedMessage]:
+    """
+    Format Gemini input contents into standardized message format, including system instruction handling.
+
+    Args:
+        contents: Input contents in various possible formats
+        config: Config object or dict that may contain system instruction
+
+    Returns:
+        List of formatted messages with role and content fields, with system message prepended if needed
+    """
+    formatted_messages = format_gemini_input(contents)
+
+    # Check if system instruction is provided in config parameter
+    system_instruction = extract_gemini_system_instruction(config)
+
+    if system_instruction is not None:
+        has_system = any(msg.get("role") == "system" for msg in formatted_messages)
+        if not has_system:
+            from posthog.ai.types import FormattedMessage
+
+            system_message: FormattedMessage = {
+                "role": "system",
+                "content": system_instruction,
+            }
+            formatted_messages = [system_message] + list(formatted_messages)
+
+    return formatted_messages
+
+
+def format_gemini_input(contents: Any) -> List[FormattedMessage]:
+    """
+    Format Gemini input contents into standardized message format for PostHog tracking.
+
+    This function handles various input formats:
+    - String inputs
+    - List of strings, dicts, or objects
+    - Single dict or object
+    - Gemini-specific format with parts array
+
+    Args:
+        contents: Input contents in various possible formats
+
+    Returns:
+        List of formatted messages with role and content fields
+    """
+
+    # Handle string input
+    if isinstance(contents, str):
+        return [{"role": "user", "content": contents}]
+
+    # Handle list input
+    if isinstance(contents, list):
+        formatted: List[FormattedMessage] = []
+
+        for item in contents:
+            if isinstance(item, str):
+                formatted.append({"role": "user", "content": item})
+
+            elif isinstance(item, dict):
+                formatted.append(_format_dict_message(item))
+
+            else:
+                formatted.append(_format_object_message(item))
+
+        return formatted
+
+    # Handle single dict input
+    if isinstance(contents, dict):
+        return [_format_dict_message(contents)]
+
+    # Handle single object input
+    return [_format_object_message(contents)]
+
+
+def _extract_usage_from_metadata(metadata: Any) -> TokenUsage:
+    """
+    Common logic to extract usage from Gemini metadata.
+    Used by both streaming and non-streaming paths.
+
+    Args:
+        metadata: usage_metadata from Gemini response or chunk
+
+    Returns:
+        TokenUsage with standardized usage
+    """
+    usage = TokenUsage(
+        input_tokens=getattr(metadata, "prompt_token_count", 0),
+        output_tokens=getattr(metadata, "candidates_token_count", 0),
+    )
+
+    # Add cache tokens if present (don't add if 0)
+    if hasattr(metadata, "cached_content_token_count"):
+        cache_tokens = metadata.cached_content_token_count
+        if cache_tokens and cache_tokens > 0:
+            usage["cache_read_input_tokens"] = cache_tokens
+
+    # Add reasoning tokens if present (don't add if 0)
+    if hasattr(metadata, "thoughts_token_count"):
+        reasoning_tokens = metadata.thoughts_token_count
+        if reasoning_tokens and reasoning_tokens > 0:
+            usage["reasoning_tokens"] = reasoning_tokens
+
+    return usage
+
+
+def extract_gemini_usage_from_response(response: Any) -> TokenUsage:
+    """
+    Extract usage statistics from a full Gemini response (non-streaming).
+
+    Args:
+        response: The complete response from Gemini API
+
+    Returns:
+        TokenUsage with standardized usage statistics
+    """
+    if not hasattr(response, "usage_metadata") or not response.usage_metadata:
+        return TokenUsage(input_tokens=0, output_tokens=0)
+
+    return _extract_usage_from_metadata(response.usage_metadata)
+
+
+def extract_gemini_usage_from_chunk(chunk: Any) -> TokenUsage:
+    """
+    Extract usage statistics from a Gemini streaming chunk.
+
+    Args:
+        chunk: Streaming chunk from Gemini API
+
+    Returns:
+        TokenUsage with standardized usage statistics
+    """
+
+    usage: TokenUsage = TokenUsage()
+
+    if not hasattr(chunk, "usage_metadata") or not chunk.usage_metadata:
+        return usage
+
+    # Use the shared helper to extract usage
+    usage = _extract_usage_from_metadata(chunk.usage_metadata)
+
+    return usage
+
+
+def extract_gemini_content_from_chunk(chunk: Any) -> Optional[Dict[str, Any]]:
+    """
+    Extract content (text or function call) from a Gemini streaming chunk.
+
+    Args:
+        chunk: Streaming chunk from Gemini API
+
+    Returns:
+        Content block dictionary if present, None otherwise
+    """
+
+    # Check for text content
+    if hasattr(chunk, "text") and chunk.text:
+        return {"type": "text", "text": chunk.text}
+
+    # Check for function calls in candidates
+    if hasattr(chunk, "candidates") and chunk.candidates:
+        for candidate in chunk.candidates:
+            if hasattr(candidate, "content") and candidate.content:
+                if hasattr(candidate.content, "parts") and candidate.content.parts:
+                    for part in candidate.content.parts:
+                        # Check for function_call part
+                        if hasattr(part, "function_call") and part.function_call:
+                            function_call = part.function_call
+                            return {
+                                "type": "function",
+                                "function": {
+                                    "name": function_call.name,
+                                    "arguments": function_call.args,
+                                },
+                            }
+                        # Also check for text in parts
+                        elif hasattr(part, "text") and part.text:
+                            return {"type": "text", "text": part.text}
+
+    return None
+
+
+def format_gemini_streaming_output(
+    accumulated_content: Union[str, List[Any]],
+) -> List[FormattedMessage]:
+    """
+    Format the final output from Gemini streaming.
+
+    Args:
+        accumulated_content: Accumulated content from streaming (string, list of strings, or list of content blocks)
+
+    Returns:
+        List of formatted messages
+    """
+
+    # Handle legacy string input (backward compatibility)
+    if isinstance(accumulated_content, str):
+        return [
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": accumulated_content}],
+            }
+        ]
+
+    # Handle list input
+    if isinstance(accumulated_content, list):
+        content: List[FormattedContentItem] = []
+        text_parts = []
+
+        for item in accumulated_content:
+            if isinstance(item, str):
+                # Legacy support: accumulate strings
+                text_parts.append(item)
+            elif isinstance(item, dict):
+                # New format: content blocks
+                if item.get("type") == "text":
+                    text_parts.append(item.get("text", ""))
+                elif item.get("type") == "function":
+                    # If we have accumulated text, add it first
+                    if text_parts:
+                        content.append(
+                            {
+                                "type": "text",
+                                "text": "".join(text_parts),
+                            }
+                        )
+                        text_parts = []
+
+                    # Add the function call
+                    content.append(
+                        {
+                            "type": "function",
+                            "function": item.get("function", {}),
+                        }
+                    )
+
+        # Add any remaining text
+        if text_parts:
+            content.append(
+                {
+                    "type": "text",
+                    "text": "".join(text_parts),
+                }
+            )
+
+        # If we have content, return it
+        if content:
+            return [{"role": "assistant", "content": content}]
+
+    # Fallback for empty or unexpected input
+    return [{"role": "assistant", "content": [{"type": "text", "text": ""}]}]

posthog/ai/langchain/callbacks.py

@@ -5,6 +5,7 @@ except ImportError:
         "Please install LangChain to use this feature: 'pip install langchain'"
     )
 
+import json
 import logging
 import time
 from dataclasses import dataclass
@@ -19,8 +20,14 @@ from typing import (
 )
 from uuid import UUID
 
-from langchain.callbacks.base import BaseCallbackHandler
-from langchain.schema.agent import AgentAction, AgentFinish
+try:
+    # LangChain 1.0+ and modern 0.x with langchain-core
+    from langchain_core.callbacks.base import BaseCallbackHandler
+    from langchain_core.agents import AgentAction, AgentFinish
+except (ImportError, ModuleNotFoundError):
+    # Fallback for older LangChain versions
+    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,
@@ -29,12 +36,14 @@ from langchain_core.messages import (
     HumanMessage,
     SystemMessage,
     ToolMessage,
+    ToolCall,
 )
 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.ai.sanitization import sanitize_langchain
 from posthog.client import Client
 
 log = logging.getLogger("posthog")
@@ -81,7 +90,7 @@ 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, UUID]]
@@ -127,10 +136,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 {}
@@ -481,11 +487,12 @@ class CallbackHandler(BaseCallbackHandler):
         event_properties = {
             "$ai_trace_id": trace_id,
             "$ai_input_state": with_privacy_mode(
-                self._client, self._privacy_mode, run.input
+                self._ph_client, self._privacy_mode, sanitize_langchain(run.input)
             ),
             "$ai_latency": run.latency,
             "$ai_span_name": run.name,
             "$ai_span_id": run_id,
+            "$ai_framework": "langchain",
         }
         if parent_run_id is not None:
             event_properties["$ai_parent_id"] = parent_run_id
@@ -497,13 +504,13 @@ class CallbackHandler(BaseCallbackHandler):
             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
+                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,
@@ -550,17 +557,17 @@ 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, sanitize_langchain(run.input)
+            ),
             "$ai_http_status": 200,
             "$ai_latency": run.latency,
             "$ai_base_url": run.base_url,
+            "$ai_framework": "langchain",
         }
+
         if run.tools:
-            event_properties["$ai_tools"] = with_privacy_mode(
-                self._client,
-                self._privacy_mode,
-                run.tools,
-            )
+            event_properties["$ai_tools"] = run.tools
 
         if isinstance(output, BaseException):
             event_properties["$ai_http_status"] = _get_http_status(output)
@@ -586,10 +593,11 @@ class CallbackHandler(BaseCallbackHandler):
                 ]
             else:
                 completions = [
-                    _extract_raw_esponse(generation) for generation in generation_result
+                    _extract_raw_response(generation)
+                    for generation in generation_result
                 ]
             event_properties["$ai_output_choices"] = with_privacy_mode(
-                self._client, self._privacy_mode, completions
+                self._ph_client, self._privacy_mode, completions
             )
 
         if self._properties:
@@ -598,7 +606,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,
@@ -617,7 +625,7 @@ class CallbackHandler(BaseCallbackHandler):
         )
 
 
-def _extract_raw_esponse(last_response):
+def _extract_raw_response(last_response):
     """Extract the response from the last response of the LLM call."""
     # We return the text of the response if not empty
     if last_response.text is not None and last_response.text.strip() != "":
@@ -630,12 +638,35 @@ def _extract_raw_esponse(last_response):
         return ""
 
 
-def _convert_message_to_dict(message: BaseMessage) -> Dict[str, Any]:
+def _convert_lc_tool_calls_to_oai(
+    tool_calls: list[ToolCall],
+) -> list[dict[str, Any]]:
+    try:
+        return [
+            {
+                "type": "function",
+                "id": tool_call["id"],
+                "function": {
+                    "name": tool_call["name"],
+                    "arguments": json.dumps(tool_call["args"]),
+                },
+            }
+            for tool_call in tool_calls
+        ]
+    except KeyError:
+        return tool_calls
+
+
+def _convert_message_to_dict(message: BaseMessage) -> dict[str, Any]:
     # assistant message
     if isinstance(message, HumanMessage):
         message_dict = {"role": "user", "content": message.content}
     elif isinstance(message, AIMessage):
         message_dict = {"role": "assistant", "content": message.content}
+        if message.tool_calls:
+            message_dict["tool_calls"] = _convert_lc_tool_calls_to_oai(
+                message.tool_calls
+            )
     elif isinstance(message, SystemMessage):
         message_dict = {"role": "system", "content": message.content}
     elif isinstance(message, ToolMessage):
@@ -648,6 +679,9 @@ def _convert_message_to_dict(message: BaseMessage) -> Dict[str, Any]:
     if message.additional_kwargs:
         message_dict.update(message.additional_kwargs)
 
+    if "content" in message_dict and not message_dict["content"]:
+        message_dict["content"] = ""
+
     return message_dict
 
 
@@ -724,12 +758,19 @@ def _parse_usage_model(
         "cache_read": "cache_read_tokens",
         "reasoning": "reasoning_tokens",
     }
-    return ModelUsage(
+    normalized_usage = ModelUsage(
         **{
             dataclass_key: parsed_usage.get(mapped_key) or 0
             for mapped_key, dataclass_key in field_mapping.items()
         },
     )
+    # In LangChain, input_tokens is the sum of input and cache read tokens.
+    # Our cost calculation expects them to be separate, for Anthropic.
+    if normalized_usage.input_tokens and normalized_usage.cache_read_tokens:
+        normalized_usage.input_tokens = max(
+            normalized_usage.input_tokens - normalized_usage.cache_read_tokens, 0
+        )
+    return normalized_usage
 
 
 def _parse_usage(response: LLMResult) -> ModelUsage:

posthog/ai/openai/__init__.py

@@ -1,5 +1,20 @@
 from .openai import OpenAI
 from .openai_async import AsyncOpenAI
 from .openai_providers import AsyncAzureOpenAI, AzureOpenAI
+from .openai_converter import (
+    format_openai_response,
+    format_openai_input,
+    extract_openai_tools,
+    format_openai_streaming_content,
+)
 
-__all__ = ["OpenAI", "AsyncOpenAI", "AzureOpenAI", "AsyncAzureOpenAI"]
+__all__ = [
+    "OpenAI",
+    "AsyncOpenAI",
+    "AzureOpenAI",
+    "AsyncAzureOpenAI",
+    "format_openai_response",
+    "format_openai_input",
+    "extract_openai_tools",
+    "format_openai_streaming_content",
+]

posthog/ai/openai/openai.py

@@ -2,6 +2,8 @@ import time
 import uuid
 from typing import Any, Dict, List, Optional
 
+from posthog.ai.types import TokenUsage
+
 try:
     import openai
 except ImportError:
@@ -11,10 +13,19 @@ except ImportError:
 
 from posthog.ai.utils import (
     call_llm_and_track_usage,
-    get_model_params,
+    extract_available_tool_calls,
+    merge_usage_stats,
     with_privacy_mode,
 )
+from posthog.ai.openai.openai_converter import (
+    extract_openai_usage_from_chunk,
+    extract_openai_content_from_chunk,
+    extract_openai_tool_calls_from_chunk,
+    accumulate_openai_tool_calls,
+)
+from posthog.ai.sanitization import sanitize_openai, sanitize_openai_response
 from posthog.client import Client as PostHogClient
+from posthog import setup
 
 
 class OpenAI(openai.OpenAI):
@@ -24,16 +35,16 @@ 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._ph_client = posthog_client or setup()
 
         # Store original objects after parent initialization (only if they exist)
         self._original_chat = getattr(self, "chat", None)
@@ -111,7 +122,7 @@ class WrappedResponses:
         **kwargs: Any,
     ):
         start_time = time.time()
-        usage_stats: Dict[str, int] = {}
+        usage_stats: TokenUsage = TokenUsage()
         final_content = []
         response = self._original.create(**kwargs)
 
@@ -121,35 +132,17 @@ class WrappedResponses:
 
             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])
+                    # Extract usage stats from chunk
+                    chunk_usage = extract_openai_usage_from_chunk(chunk, "responses")
 
-                    if hasattr(chunk, "usage") and chunk.usage:
-                        usage_stats = {
-                            k: getattr(chunk.usage, k, 0)
-                            for k in [
-                                "input_tokens",
-                                "output_tokens",
-                                "total_tokens",
-                            ]
-                        }
+                    if chunk_usage:
+                        merge_usage_stats(usage_stats, chunk_usage)
 
-                        # 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
-                            )
+                    # Extract content from chunk
+                    content = extract_openai_content_from_chunk(chunk, "responses")
 
-                        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
-                            )
+                    if content is not None:
+                        final_content.append(content)
 
                     yield chunk
 
@@ -167,6 +160,7 @@ class WrappedResponses:
                     usage_stats,
                     latency,
                     output,
+                    None,  # Responses API doesn't have tools
                 )
 
         return generator()
@@ -179,56 +173,40 @@ class WrappedResponses:
         posthog_privacy_mode: bool,
         posthog_groups: Optional[Dict[str, Any]],
         kwargs: Dict[str, Any],
-        usage_stats: Dict[str, int],
+        usage_stats: TokenUsage,
         latency: float,
         output: Any,
-        tool_calls: Optional[List[Dict[str, Any]]] = None,
+        available_tool_calls: Optional[List[Dict[str, Any]]] = None,
     ):
-        if posthog_trace_id is None:
-            posthog_trace_id = str(uuid.uuid4())
+        from posthog.ai.types import StreamingEventData
+        from posthog.ai.openai.openai_converter import (
+            format_openai_streaming_input,
+            format_openai_streaming_output,
+        )
+        from posthog.ai.utils import capture_streaming_event
 
-        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("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 {}),
-        }
+        # Prepare standardized event data
+        formatted_input = format_openai_streaming_input(kwargs, "responses")
+        sanitized_input = sanitize_openai_response(formatted_input)
 
-        if tool_calls:
-            event_properties["$ai_tools"] = with_privacy_mode(
-                self._client._ph_client,
-                posthog_privacy_mode,
-                tool_calls,
-            )
+        event_data = StreamingEventData(
+            provider="openai",
+            model=kwargs.get("model", "unknown"),
+            base_url=str(self._client.base_url),
+            kwargs=kwargs,
+            formatted_input=sanitized_input,
+            formatted_output=format_openai_streaming_output(output, "responses"),
+            usage_stats=usage_stats,
+            latency=latency,
+            distinct_id=posthog_distinct_id,
+            trace_id=posthog_trace_id,
+            properties=posthog_properties,
+            privacy_mode=posthog_privacy_mode,
+            groups=posthog_groups,
+        )
 
-        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,
-            )
+        # Use the common capture function
+        capture_streaming_event(self._client._ph_client, event_data)
 
     def parse(
         self,
@@ -339,9 +317,9 @@ class WrappedCompletions:
         **kwargs: Any,
     ):
         start_time = time.time()
-        usage_stats: Dict[str, int] = {}
+        usage_stats: TokenUsage = TokenUsage()
         accumulated_content = []
-        accumulated_tools = {}
+        accumulated_tool_calls: Dict[int, Dict[str, Any]] = {}
         if "stream_options" not in kwargs:
             kwargs["stream_options"] = {}
         kwargs["stream_options"]["include_usage"] = True
@@ -350,70 +328,42 @@ class WrappedCompletions:
         def generator():
             nonlocal usage_stats
             nonlocal accumulated_content  # noqa: F824
-            nonlocal accumulated_tools  # noqa: F824
+            nonlocal accumulated_tool_calls
 
             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",
-                            ]
-                        }
+                    # Extract usage stats from chunk
+                    chunk_usage = extract_openai_usage_from_chunk(chunk, "chat")
 
-                        # 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 chunk_usage:
+                        merge_usage_stats(usage_stats, chunk_usage)
 
-                        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
-                            )
+                    # Extract content from chunk
+                    content = extract_openai_content_from_chunk(chunk, "chat")
 
-                    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)
+                    if content is not None:
+                        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
-                                        )
+                    # Extract and accumulate tool calls from chunk
+                    chunk_tool_calls = extract_openai_tool_calls_from_chunk(chunk)
+                    if chunk_tool_calls:
+                        accumulate_openai_tool_calls(
+                            accumulated_tool_calls, chunk_tool_calls
+                        )
 
                     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
+
+                # Convert accumulated tool calls dict to list
+                tool_calls_list = (
+                    list(accumulated_tool_calls.values())
+                    if accumulated_tool_calls
+                    else None
+                )
+
                 self._capture_streaming_event(
                     posthog_distinct_id,
                     posthog_trace_id,
@@ -423,8 +373,9 @@ class WrappedCompletions:
                     kwargs,
                     usage_stats,
                     latency,
-                    output,
-                    tools,
+                    accumulated_content,
+                    tool_calls_list,
+                    extract_available_tool_calls("openai", kwargs),
                 )
 
         return generator()
@@ -437,56 +388,41 @@ class WrappedCompletions:
         posthog_privacy_mode: bool,
         posthog_groups: Optional[Dict[str, Any]],
         kwargs: Dict[str, Any],
-        usage_stats: Dict[str, int],
+        usage_stats: TokenUsage,
         latency: float,
         output: Any,
         tool_calls: Optional[List[Dict[str, Any]]] = None,
+        available_tool_calls: Optional[List[Dict[str, Any]]] = None,
     ):
-        if posthog_trace_id is None:
-            posthog_trace_id = str(uuid.uuid4())
+        from posthog.ai.types import StreamingEventData
+        from posthog.ai.openai.openai_converter import (
+            format_openai_streaming_input,
+            format_openai_streaming_output,
+        )
+        from posthog.ai.utils import capture_streaming_event
 
-        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,
-                [{"content": output, "role": "assistant"}],
-            ),
-            "$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 or {}),
-        }
+        # Prepare standardized event data
+        formatted_input = format_openai_streaming_input(kwargs, "chat")
+        sanitized_input = sanitize_openai(formatted_input)
 
-        if tool_calls:
-            event_properties["$ai_tools"] = with_privacy_mode(
-                self._client._ph_client,
-                posthog_privacy_mode,
-                tool_calls,
-            )
+        event_data = StreamingEventData(
+            provider="openai",
+            model=kwargs.get("model", "unknown"),
+            base_url=str(self._client.base_url),
+            kwargs=kwargs,
+            formatted_input=sanitized_input,
+            formatted_output=format_openai_streaming_output(output, "chat", tool_calls),
+            usage_stats=usage_stats,
+            latency=latency,
+            distinct_id=posthog_distinct_id,
+            trace_id=posthog_trace_id,
+            properties=posthog_properties,
+            privacy_mode=posthog_privacy_mode,
+            groups=posthog_groups,
+        )
 
-        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,
-            )
+        # Use the common capture function
+        capture_streaming_event(self._client._ph_client, event_data)
 
 
 class WrappedEmbeddings:
@@ -523,6 +459,7 @@ class WrappedEmbeddings:
         Returns:
             The response from OpenAI's embeddings.create call.
         """
+
         if posthog_trace_id is None:
             posthog_trace_id = str(uuid.uuid4())
 
@@ -545,7 +482,9 @@ class WrappedEmbeddings:
             "$ai_provider": "openai",
             "$ai_model": kwargs.get("model"),
             "$ai_input": with_privacy_mode(
-                self._client._ph_client, posthog_privacy_mode, kwargs.get("input")
+                self._client._ph_client,
+                posthog_privacy_mode,
+                sanitize_openai_response(kwargs.get("input")),
             ),
             "$ai_http_status": 200,
             "$ai_input_tokens": usage_stats.get("prompt_tokens", 0),

posthog/ai/openai/openai_async.py

@@ -2,6 +2,8 @@ import time
 import uuid
 from typing import Any, Dict, List, Optional
 
+from posthog.ai.types import TokenUsage
+
 try:
     import openai
 except ImportError:
@@ -9,11 +11,22 @@ except ImportError:
         "Please install the OpenAI SDK to use this feature: 'pip install openai'"
     )
 
+from posthog import setup
 from posthog.ai.utils import (
     call_llm_and_track_usage_async,
+    extract_available_tool_calls,
     get_model_params,
+    merge_usage_stats,
     with_privacy_mode,
 )
+from posthog.ai.openai.openai_converter import (
+    extract_openai_usage_from_chunk,
+    extract_openai_content_from_chunk,
+    extract_openai_tool_calls_from_chunk,
+    accumulate_openai_tool_calls,
+    format_openai_streaming_output,
+)
+from posthog.ai.sanitization import sanitize_openai, sanitize_openai_response
 from posthog.client import Client as PostHogClient
 
 
@@ -24,7 +37,7 @@ 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.
@@ -32,8 +45,9 @@ class AsyncOpenAI(openai.AsyncOpenAI):
                             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._ph_client = posthog_client or setup()
 
         # Store original objects after parent initialization (only if they exist)
         self._original_chat = getattr(self, "chat", None)
@@ -64,6 +78,7 @@ class WrappedResponses:
 
     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(
@@ -111,7 +126,7 @@ class WrappedResponses:
         **kwargs: Any,
     ):
         start_time = time.time()
-        usage_stats: Dict[str, int] = {}
+        usage_stats: TokenUsage = TokenUsage()
         final_content = []
         response = await self._original.create(**kwargs)
 
@@ -121,35 +136,17 @@ class WrappedResponses:
 
             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])
+                    # Extract usage stats from chunk
+                    chunk_usage = extract_openai_usage_from_chunk(chunk, "responses")
 
-                    if hasattr(chunk, "usage") and chunk.usage:
-                        usage_stats = {
-                            k: getattr(chunk.usage, k, 0)
-                            for k in [
-                                "input_tokens",
-                                "output_tokens",
-                                "total_tokens",
-                            ]
-                        }
+                    if chunk_usage:
+                        merge_usage_stats(usage_stats, chunk_usage)
 
-                        # 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
-                            )
+                    # Extract content from chunk
+                    content = extract_openai_content_from_chunk(chunk, "responses")
 
-                        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
-                            )
+                    if content is not None:
+                        final_content.append(content)
 
                     yield chunk
 
@@ -157,6 +154,7 @@ class WrappedResponses:
                 end_time = time.time()
                 latency = end_time - start_time
                 output = final_content
+
                 await self._capture_streaming_event(
                     posthog_distinct_id,
                     posthog_trace_id,
@@ -167,6 +165,7 @@ class WrappedResponses:
                     usage_stats,
                     latency,
                     output,
+                    extract_available_tool_calls("openai", kwargs),
                 )
 
         return async_generator()
@@ -179,10 +178,10 @@ class WrappedResponses:
         posthog_privacy_mode: bool,
         posthog_groups: Optional[Dict[str, Any]],
         kwargs: Dict[str, Any],
-        usage_stats: Dict[str, int],
+        usage_stats: TokenUsage,
         latency: float,
         output: Any,
-        tool_calls: Optional[List[Dict[str, Any]]] = None,
+        available_tool_calls: Optional[List[Dict[str, Any]]] = None,
     ):
         if posthog_trace_id is None:
             posthog_trace_id = str(uuid.uuid4())
@@ -192,12 +191,14 @@ class WrappedResponses:
             "$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("input")
+                self._client._ph_client,
+                posthog_privacy_mode,
+                sanitize_openai_response(kwargs.get("input")),
             ),
             "$ai_output_choices": with_privacy_mode(
                 self._client._ph_client,
                 posthog_privacy_mode,
-                output,
+                format_openai_streaming_output(output, "responses"),
             ),
             "$ai_http_status": 200,
             "$ai_input_tokens": usage_stats.get("input_tokens", 0),
@@ -212,12 +213,8 @@ class WrappedResponses:
             **(posthog_properties or {}),
         }
 
-        if tool_calls:
-            event_properties["$ai_tools"] = with_privacy_mode(
-                self._client._ph_client,
-                posthog_privacy_mode,
-                tool_calls,
-            )
+        if available_tool_calls:
+            event_properties["$ai_tools"] = available_tool_calls
 
         if posthog_distinct_id is None:
             event_properties["$process_person_profile"] = False
@@ -341,9 +338,9 @@ class WrappedCompletions:
         **kwargs: Any,
     ):
         start_time = time.time()
-        usage_stats: Dict[str, int] = {}
+        usage_stats: TokenUsage = TokenUsage()
         accumulated_content = []
-        accumulated_tools = {}
+        accumulated_tool_calls: Dict[int, Dict[str, Any]] = {}
 
         if "stream_options" not in kwargs:
             kwargs["stream_options"] = {}
@@ -353,70 +350,40 @@ class WrappedCompletions:
         async def async_generator():
             nonlocal usage_stats
             nonlocal accumulated_content  # noqa: F824
-            nonlocal accumulated_tools  # noqa: F824
+            nonlocal accumulated_tool_calls
 
             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",
-                            ]
-                        }
+                    # Extract usage stats from chunk
+                    chunk_usage = extract_openai_usage_from_chunk(chunk, "chat")
+                    if chunk_usage:
+                        merge_usage_stats(usage_stats, chunk_usage)
 
-                        # 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
-                            )
+                    # Extract content from chunk
+                    content = extract_openai_content_from_chunk(chunk, "chat")
+                    if content is not None:
+                        accumulated_content.append(content)
 
-                        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
-                                        )
+                    # Extract and accumulate tool calls from chunk
+                    chunk_tool_calls = extract_openai_tool_calls_from_chunk(chunk)
+                    if chunk_tool_calls:
+                        accumulate_openai_tool_calls(
+                            accumulated_tool_calls, chunk_tool_calls
+                        )
 
                     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
+
+                # Convert accumulated tool calls dict to list
+                tool_calls_list = (
+                    list(accumulated_tool_calls.values())
+                    if accumulated_tool_calls
+                    else None
+                )
+
                 await self._capture_streaming_event(
                     posthog_distinct_id,
                     posthog_trace_id,
@@ -426,8 +393,9 @@ class WrappedCompletions:
                     kwargs,
                     usage_stats,
                     latency,
-                    output,
-                    tools,
+                    accumulated_content,
+                    tool_calls_list,
+                    extract_available_tool_calls("openai", kwargs),
                 )
 
         return async_generator()
@@ -440,10 +408,11 @@ class WrappedCompletions:
         posthog_privacy_mode: bool,
         posthog_groups: Optional[Dict[str, Any]],
         kwargs: Dict[str, Any],
-        usage_stats: Dict[str, int],
+        usage_stats: TokenUsage,
         latency: float,
         output: Any,
         tool_calls: Optional[List[Dict[str, Any]]] = None,
+        available_tool_calls: Optional[List[Dict[str, Any]]] = None,
     ):
         if posthog_trace_id is None:
             posthog_trace_id = str(uuid.uuid4())
@@ -453,16 +422,18 @@ class WrappedCompletions:
             "$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")
+                self._client._ph_client,
+                posthog_privacy_mode,
+                sanitize_openai(kwargs.get("messages")),
             ),
             "$ai_output_choices": with_privacy_mode(
                 self._client._ph_client,
                 posthog_privacy_mode,
-                [{"content": output, "role": "assistant"}],
+                format_openai_streaming_output(output, "chat", tool_calls),
             ),
             "$ai_http_status": 200,
-            "$ai_input_tokens": usage_stats.get("prompt_tokens", 0),
-            "$ai_output_tokens": usage_stats.get("completion_tokens", 0),
+            "$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
             ),
@@ -473,12 +444,8 @@ class WrappedCompletions:
             **(posthog_properties or {}),
         }
 
-        if tool_calls:
-            event_properties["$ai_tools"] = with_privacy_mode(
-                self._client._ph_client,
-                posthog_privacy_mode,
-                tool_calls,
-            )
+        if available_tool_calls:
+            event_properties["$ai_tools"] = available_tool_calls
 
         if posthog_distinct_id is None:
             event_properties["$process_person_profile"] = False
@@ -501,6 +468,7 @@ class WrappedEmbeddings:
 
     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(
@@ -526,6 +494,7 @@ class WrappedEmbeddings:
         Returns:
             The response from OpenAI's embeddings.create call.
         """
+
         if posthog_trace_id is None:
             posthog_trace_id = str(uuid.uuid4())
 
@@ -534,12 +503,13 @@ class WrappedEmbeddings:
         end_time = time.time()
 
         # Extract usage statistics if available
-        usage_stats = {}
+        usage_stats: TokenUsage = TokenUsage()
+
         if hasattr(response, "usage") and response.usage:
-            usage_stats = {
-                "prompt_tokens": getattr(response.usage, "prompt_tokens", 0),
-                "total_tokens": getattr(response.usage, "total_tokens", 0),
-            }
+            usage_stats = TokenUsage(
+                input_tokens=getattr(response.usage, "prompt_tokens", 0),
+                output_tokens=getattr(response.usage, "completion_tokens", 0),
+            )
 
         latency = end_time - start_time
 
@@ -548,10 +518,12 @@ class WrappedEmbeddings:
             "$ai_provider": "openai",
             "$ai_model": kwargs.get("model"),
             "$ai_input": with_privacy_mode(
-                self._client._ph_client, posthog_privacy_mode, kwargs.get("input")
+                self._client._ph_client,
+                posthog_privacy_mode,
+                sanitize_openai_response(kwargs.get("input")),
             ),
             "$ai_http_status": 200,
-            "$ai_input_tokens": usage_stats.get("prompt_tokens", 0),
+            "$ai_input_tokens": usage_stats.get("input_tokens", 0),
             "$ai_latency": latency,
             "$ai_trace_id": posthog_trace_id,
             "$ai_base_url": str(self._client.base_url),
@@ -582,6 +554,7 @@ class WrappedBeta:
 
     def __getattr__(self, name):
         """Fallback to original beta object for any methods we don't explicitly handle."""
+
         return getattr(self._original, name)
 
     @property
@@ -598,6 +571,7 @@ class WrappedBetaChat:
 
     def __getattr__(self, name):
         """Fallback to original beta chat object for any methods we don't explicitly handle."""
+
         return getattr(self._original, name)
 
     @property
@@ -614,6 +588,7 @@ class WrappedBetaCompletions:
 
     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(

posthog/ai/openai/openai_converter.py

@@ -0,0 +1,611 @@
+"""
+OpenAI-specific conversion utilities.
+
+This module handles the conversion of OpenAI API responses and inputs
+into standardized formats for PostHog tracking. It supports both
+Chat Completions API and Responses API formats.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from posthog.ai.types import (
+    FormattedContentItem,
+    FormattedFunctionCall,
+    FormattedImageContent,
+    FormattedMessage,
+    FormattedTextContent,
+    TokenUsage,
+)
+
+
+def format_openai_response(response: Any) -> List[FormattedMessage]:
+    """
+    Format an OpenAI response into standardized message format.
+
+    Handles both Chat Completions API and Responses API formats.
+
+    Args:
+        response: The response object from OpenAI API
+
+    Returns:
+        List of formatted messages with role and content
+    """
+
+    output: List[FormattedMessage] = []
+
+    if response is None:
+        return output
+
+    # Handle Chat Completions response format
+    if hasattr(response, "choices"):
+        content: List[FormattedContentItem] = []
+        role = "assistant"
+
+        for choice in response.choices:
+            if hasattr(choice, "message") and choice.message:
+                if choice.message.role:
+                    role = choice.message.role
+
+                if choice.message.content:
+                    content.append(
+                        {
+                            "type": "text",
+                            "text": choice.message.content,
+                        }
+                    )
+
+                if hasattr(choice.message, "tool_calls") and choice.message.tool_calls:
+                    for tool_call in choice.message.tool_calls:
+                        content.append(
+                            {
+                                "type": "function",
+                                "id": tool_call.id,
+                                "function": {
+                                    "name": tool_call.function.name,
+                                    "arguments": tool_call.function.arguments,
+                                },
+                            }
+                        )
+
+        if content:
+            output.append(
+                {
+                    "role": role,
+                    "content": content,
+                }
+            )
+
+    # Handle Responses API format
+    if hasattr(response, "output"):
+        content = []
+        role = "assistant"
+
+        for item in response.output:
+            if item.type == "message":
+                role = item.role
+
+                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")
+                        ):
+                            content.append(
+                                {
+                                    "type": "text",
+                                    "text": content_item.text,
+                                }
+                            )
+
+                        elif hasattr(content_item, "text"):
+                            content.append({"type": "text", "text": content_item.text})
+
+                        elif (
+                            hasattr(content_item, "type")
+                            and content_item.type == "input_image"
+                            and hasattr(content_item, "image_url")
+                        ):
+                            image_content: FormattedImageContent = {
+                                "type": "image",
+                                "image": content_item.image_url,
+                            }
+                            content.append(image_content)
+
+                elif hasattr(item, "content"):
+                    text_content = {"type": "text", "text": str(item.content)}
+                    content.append(text_content)
+
+            elif hasattr(item, "type") and item.type == "function_call":
+                content.append(
+                    {
+                        "type": "function",
+                        "id": getattr(item, "call_id", getattr(item, "id", "")),
+                        "function": {
+                            "name": item.name,
+                            "arguments": getattr(item, "arguments", {}),
+                        },
+                    }
+                )
+
+        if content:
+            output.append(
+                {
+                    "role": role,
+                    "content": content,
+                }
+            )
+
+    return output
+
+
+def format_openai_input(
+    messages: Optional[List[Dict[str, Any]]] = None, input_data: Optional[Any] = None
+) -> List[FormattedMessage]:
+    """
+    Format OpenAI input messages.
+
+    Handles both messages parameter (Chat Completions) and input parameter (Responses API).
+
+    Args:
+        messages: List of message dictionaries for Chat Completions API
+        input_data: Input data for Responses API
+
+    Returns:
+        List of formatted messages
+    """
+
+    formatted_messages: List[FormattedMessage] = []
+
+    # Handle Chat Completions API format
+    if messages is not None:
+        for msg in messages:
+            formatted_messages.append(
+                {
+                    "role": msg.get("role", "user"),
+                    "content": msg.get("content", ""),
+                }
+            )
+
+    # Handle Responses API format
+    if input_data is not None:
+        if isinstance(input_data, list):
+            for item in input_data:
+                role = "user"
+                content = ""
+
+                if isinstance(item, dict):
+                    role = item.get("role", "user")
+                    content = item.get("content", "")
+
+                elif isinstance(item, str):
+                    content = item
+
+                else:
+                    content = str(item)
+
+                formatted_messages.append({"role": role, "content": content})
+
+        elif isinstance(input_data, str):
+            formatted_messages.append({"role": "user", "content": input_data})
+
+        else:
+            formatted_messages.append({"role": "user", "content": str(input_data)})
+
+    return formatted_messages
+
+
+def extract_openai_tools(kwargs: Dict[str, Any]) -> Optional[Any]:
+    """
+    Extract tool definitions from OpenAI API kwargs.
+
+    Args:
+        kwargs: Keyword arguments passed to OpenAI API
+
+    Returns:
+        Tool definitions if present, None otherwise
+    """
+
+    # Check for tools parameter (newer API)
+    if "tools" in kwargs:
+        return kwargs["tools"]
+
+    # Check for functions parameter (older API)
+    if "functions" in kwargs:
+        return kwargs["functions"]
+
+    return None
+
+
+def format_openai_streaming_content(
+    accumulated_content: str, tool_calls: Optional[List[Dict[str, Any]]] = None
+) -> List[FormattedContentItem]:
+    """
+    Format content from OpenAI streaming response.
+
+    Used by streaming handlers to format accumulated content.
+
+    Args:
+        accumulated_content: Accumulated text content from streaming
+        tool_calls: Optional list of tool calls accumulated during streaming
+
+    Returns:
+        List of formatted content items
+    """
+    formatted: List[FormattedContentItem] = []
+
+    # Add text content if present
+    if accumulated_content:
+        text_content: FormattedTextContent = {
+            "type": "text",
+            "text": accumulated_content,
+        }
+        formatted.append(text_content)
+
+    # Add tool calls if present
+    if tool_calls:
+        for tool_call in tool_calls:
+            function_call: FormattedFunctionCall = {
+                "type": "function",
+                "id": tool_call.get("id"),
+                "function": tool_call.get("function", {}),
+            }
+            formatted.append(function_call)
+
+    return formatted
+
+
+def extract_openai_usage_from_response(response: Any) -> TokenUsage:
+    """
+    Extract usage statistics from a full OpenAI response (non-streaming).
+    Handles both Chat Completions and Responses API.
+
+    Args:
+        response: The complete response from OpenAI API
+
+    Returns:
+        TokenUsage with standardized usage statistics
+    """
+    if not hasattr(response, "usage"):
+        return TokenUsage(input_tokens=0, output_tokens=0)
+
+    cached_tokens = 0
+    input_tokens = 0
+    output_tokens = 0
+    reasoning_tokens = 0
+
+    # Responses API format
+    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 format
+    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
+    if hasattr(response.usage, "completion_tokens_details") and hasattr(
+        response.usage.completion_tokens_details, "reasoning_tokens"
+    ):
+        reasoning_tokens = response.usage.completion_tokens_details.reasoning_tokens
+
+    result = TokenUsage(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+    )
+
+    if cached_tokens > 0:
+        result["cache_read_input_tokens"] = cached_tokens
+    if reasoning_tokens > 0:
+        result["reasoning_tokens"] = reasoning_tokens
+
+    return result
+
+
+def extract_openai_usage_from_chunk(
+    chunk: Any, provider_type: str = "chat"
+) -> TokenUsage:
+    """
+    Extract usage statistics from an OpenAI streaming chunk.
+
+    Handles both Chat Completions and Responses API formats.
+
+    Args:
+        chunk: Streaming chunk from OpenAI API
+        provider_type: Either "chat" or "responses" to handle different API formats
+
+    Returns:
+        Dictionary of usage statistics
+    """
+
+    usage: TokenUsage = TokenUsage()
+
+    if provider_type == "chat":
+        if not hasattr(chunk, "usage") or not chunk.usage:
+            return usage
+
+        # Chat Completions API uses prompt_tokens and completion_tokens
+        # Standardize to input_tokens and output_tokens
+        usage["input_tokens"] = getattr(chunk.usage, "prompt_tokens", 0)
+        usage["output_tokens"] = getattr(chunk.usage, "completion_tokens", 0)
+
+        # Handle cached tokens
+        if hasattr(chunk.usage, "prompt_tokens_details") and hasattr(
+            chunk.usage.prompt_tokens_details, "cached_tokens"
+        ):
+            usage["cache_read_input_tokens"] = (
+                chunk.usage.prompt_tokens_details.cached_tokens
+            )
+
+        # Handle reasoning tokens
+        if hasattr(chunk.usage, "completion_tokens_details") and hasattr(
+            chunk.usage.completion_tokens_details, "reasoning_tokens"
+        ):
+            usage["reasoning_tokens"] = (
+                chunk.usage.completion_tokens_details.reasoning_tokens
+            )
+
+    elif provider_type == "responses":
+        # For Responses API, usage is only in chunk.response.usage for completed events
+        if hasattr(chunk, "type") and chunk.type == "response.completed":
+            if (
+                hasattr(chunk, "response")
+                and hasattr(chunk.response, "usage")
+                and chunk.response.usage
+            ):
+                response_usage = chunk.response.usage
+                usage["input_tokens"] = getattr(response_usage, "input_tokens", 0)
+                usage["output_tokens"] = getattr(response_usage, "output_tokens", 0)
+
+                # Handle cached tokens
+                if hasattr(response_usage, "input_tokens_details") and hasattr(
+                    response_usage.input_tokens_details, "cached_tokens"
+                ):
+                    usage["cache_read_input_tokens"] = (
+                        response_usage.input_tokens_details.cached_tokens
+                    )
+
+                # Handle reasoning tokens
+                if hasattr(response_usage, "output_tokens_details") and hasattr(
+                    response_usage.output_tokens_details, "reasoning_tokens"
+                ):
+                    usage["reasoning_tokens"] = (
+                        response_usage.output_tokens_details.reasoning_tokens
+                    )
+
+    return usage
+
+
+def extract_openai_content_from_chunk(
+    chunk: Any, provider_type: str = "chat"
+) -> Optional[str]:
+    """
+    Extract content from an OpenAI streaming chunk.
+
+    Handles both Chat Completions and Responses API formats.
+
+    Args:
+        chunk: Streaming chunk from OpenAI API
+        provider_type: Either "chat" or "responses" to handle different API formats
+
+    Returns:
+        Text content if present, None otherwise
+    """
+
+    if provider_type == "chat":
+        # Chat Completions API format
+        if (
+            hasattr(chunk, "choices")
+            and chunk.choices
+            and len(chunk.choices) > 0
+            and chunk.choices[0].delta
+            and chunk.choices[0].delta.content
+        ):
+            return chunk.choices[0].delta.content
+
+    elif provider_type == "responses":
+        # Responses API format
+        if hasattr(chunk, "type") and chunk.type == "response.completed":
+            if hasattr(chunk, "response") and chunk.response:
+                res = chunk.response
+                if res.output and len(res.output) > 0:
+                    # Return the full output for responses
+                    return res.output[0]
+
+    return None
+
+
+def extract_openai_tool_calls_from_chunk(chunk: Any) -> Optional[List[Dict[str, Any]]]:
+    """
+    Extract tool calls from an OpenAI streaming chunk.
+
+    Args:
+        chunk: Streaming chunk from OpenAI API
+
+    Returns:
+        List of tool call deltas if present, None otherwise
+    """
+    if (
+        hasattr(chunk, "choices")
+        and chunk.choices
+        and len(chunk.choices) > 0
+        and chunk.choices[0].delta
+        and hasattr(chunk.choices[0].delta, "tool_calls")
+        and chunk.choices[0].delta.tool_calls
+    ):
+        tool_calls = []
+        for tool_call in chunk.choices[0].delta.tool_calls:
+            tc_dict = {
+                "index": getattr(tool_call, "index", None),
+            }
+
+            if hasattr(tool_call, "id") and tool_call.id:
+                tc_dict["id"] = tool_call.id
+
+            if hasattr(tool_call, "type") and tool_call.type:
+                tc_dict["type"] = tool_call.type
+
+            if hasattr(tool_call, "function") and tool_call.function:
+                function_dict = {}
+                if hasattr(tool_call.function, "name") and tool_call.function.name:
+                    function_dict["name"] = tool_call.function.name
+                if (
+                    hasattr(tool_call.function, "arguments")
+                    and tool_call.function.arguments
+                ):
+                    function_dict["arguments"] = tool_call.function.arguments
+                tc_dict["function"] = function_dict
+
+            tool_calls.append(tc_dict)
+        return tool_calls
+
+    return None
+
+
+def accumulate_openai_tool_calls(
+    accumulated_tool_calls: Dict[int, Dict[str, Any]],
+    chunk_tool_calls: List[Dict[str, Any]],
+) -> None:
+    """
+    Accumulate tool calls from streaming chunks.
+
+    OpenAI sends tool calls incrementally:
+    - First chunk has id, type, function.name and partial function.arguments
+    - Subsequent chunks have more function.arguments
+
+    Args:
+        accumulated_tool_calls: Dictionary mapping index to accumulated tool call data
+        chunk_tool_calls: List of tool call deltas from current chunk
+    """
+    for tool_call_delta in chunk_tool_calls:
+        index = tool_call_delta.get("index")
+        if index is None:
+            continue
+
+        # Initialize tool call if first time seeing this index
+        if index not in accumulated_tool_calls:
+            accumulated_tool_calls[index] = {
+                "id": "",
+                "type": "function",
+                "function": {
+                    "name": "",
+                    "arguments": "",
+                },
+            }
+
+        # Update with new data from delta
+        tc = accumulated_tool_calls[index]
+
+        if "id" in tool_call_delta and tool_call_delta["id"]:
+            tc["id"] = tool_call_delta["id"]
+
+        if "type" in tool_call_delta and tool_call_delta["type"]:
+            tc["type"] = tool_call_delta["type"]
+
+        if "function" in tool_call_delta:
+            func_delta = tool_call_delta["function"]
+            if "name" in func_delta and func_delta["name"]:
+                tc["function"]["name"] = func_delta["name"]
+            if "arguments" in func_delta and func_delta["arguments"]:
+                # Arguments are sent incrementally, concatenate them
+                tc["function"]["arguments"] += func_delta["arguments"]
+
+
+def format_openai_streaming_output(
+    accumulated_content: Any,
+    provider_type: str = "chat",
+    tool_calls: Optional[List[Dict[str, Any]]] = None,
+) -> List[FormattedMessage]:
+    """
+    Format the final output from OpenAI streaming.
+
+    Args:
+        accumulated_content: Accumulated content from streaming (string for chat, list for responses)
+        provider_type: Either "chat" or "responses" to handle different API formats
+        tool_calls: Optional list of accumulated tool calls
+
+    Returns:
+        List of formatted messages
+    """
+
+    if provider_type == "chat":
+        content_items: List[FormattedContentItem] = []
+
+        # Add text content if present
+        if isinstance(accumulated_content, str) and accumulated_content:
+            content_items.append({"type": "text", "text": accumulated_content})
+        elif isinstance(accumulated_content, list):
+            # If it's a list of strings, join them
+            text = "".join(str(item) for item in accumulated_content if item)
+            if text:
+                content_items.append({"type": "text", "text": text})
+
+        # Add tool calls if present
+        if tool_calls:
+            for tool_call in tool_calls:
+                if "function" in tool_call:
+                    function_call: FormattedFunctionCall = {
+                        "type": "function",
+                        "id": tool_call.get("id", ""),
+                        "function": tool_call["function"],
+                    }
+                    content_items.append(function_call)
+
+        # Return formatted message with content
+        if content_items:
+            return [{"role": "assistant", "content": content_items}]
+        else:
+            # Empty response
+            return [{"role": "assistant", "content": []}]
+
+    elif provider_type == "responses":
+        # Responses API: accumulated_content is a list of output items
+        if isinstance(accumulated_content, list) and accumulated_content:
+            # The output is already formatted, just return it
+            return accumulated_content
+        elif isinstance(accumulated_content, str):
+            return [
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": accumulated_content}],
+                }
+            ]
+
+    # Fallback for any other format
+    return [
+        {
+            "role": "assistant",
+            "content": [{"type": "text", "text": str(accumulated_content)}],
+        }
+    ]
+
+
+def format_openai_streaming_input(
+    kwargs: Dict[str, Any], api_type: str = "chat"
+) -> Any:
+    """
+    Format OpenAI streaming input based on API type.
+
+    Args:
+        kwargs: Keyword arguments passed to OpenAI API
+        api_type: Either "chat" or "responses"
+
+    Returns:
+        Formatted input ready for PostHog tracking
+    """
+    from posthog.ai.utils import merge_system_prompt
+
+    return merge_system_prompt(kwargs, "openai")

posthog/ai/openai/openai_providers.py

@@ -15,7 +15,10 @@ 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):
@@ -25,7 +28,7 @@ class AzureOpenAI(openai.AzureOpenAI):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             api_key: Azure OpenAI API key.
@@ -34,7 +37,7 @@ class AzureOpenAI(openai.AzureOpenAI):
             **openai_config: Any additional keyword args to set on Azure OpenAI (e.g. azure_endpoint="xxx").
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
 
         # Store original objects after parent initialization (only if they exist)
         self._original_chat = getattr(self, "chat", None)
@@ -63,7 +66,7 @@ class AsyncAzureOpenAI(openai.AsyncAzureOpenAI):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             api_key: Azure OpenAI API key.
@@ -72,7 +75,7 @@ class AsyncAzureOpenAI(openai.AsyncAzureOpenAI):
             **openai_config: Any additional keyword args to set on Azure OpenAI (e.g. azure_endpoint="xxx").
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
 
         # Store original objects after parent initialization (only if they exist)
         self._original_chat = getattr(self, "chat", None)

posthog/ai/sanitization.py

@@ -0,0 +1,226 @@
+import re
+from typing import Any
+from urllib.parse import urlparse
+
+REDACTED_IMAGE_PLACEHOLDER = "[base64 image redacted]"
+
+
+def is_base64_data_url(text: str) -> bool:
+    return re.match(r"^data:([^;]+);base64,", text) is not None
+
+
+def is_valid_url(text: str) -> bool:
+    try:
+        result = urlparse(text)
+        return bool(result.scheme and result.netloc)
+    except Exception:
+        pass
+
+    return text.startswith(("/", "./", "../"))
+
+
+def is_raw_base64(text: str) -> bool:
+    if is_valid_url(text):
+        return False
+
+    return len(text) > 20 and re.match(r"^[A-Za-z0-9+/]+=*$", text) is not None
+
+
+def redact_base64_data_url(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+
+    if is_base64_data_url(value):
+        return REDACTED_IMAGE_PLACEHOLDER
+
+    if is_raw_base64(value):
+        return REDACTED_IMAGE_PLACEHOLDER
+
+    return value
+
+
+def process_messages(messages: Any, transform_content_func) -> Any:
+    if not messages:
+        return messages
+
+    def process_content(content: Any) -> Any:
+        if isinstance(content, str):
+            return content
+
+        if not content:
+            return content
+
+        if isinstance(content, list):
+            return [transform_content_func(item) for item in content]
+
+        return transform_content_func(content)
+
+    def process_message(msg: Any) -> Any:
+        if not isinstance(msg, dict) or "content" not in msg:
+            return msg
+        return {**msg, "content": process_content(msg["content"])}
+
+    if isinstance(messages, list):
+        return [process_message(msg) for msg in messages]
+
+    return process_message(messages)
+
+
+def sanitize_openai_image(item: Any) -> Any:
+    if not isinstance(item, dict):
+        return item
+
+    if (
+        item.get("type") == "image_url"
+        and isinstance(item.get("image_url"), dict)
+        and "url" in item["image_url"]
+    ):
+        return {
+            **item,
+            "image_url": {
+                **item["image_url"],
+                "url": redact_base64_data_url(item["image_url"]["url"]),
+            },
+        }
+
+    return item
+
+
+def sanitize_openai_response_image(item: Any) -> Any:
+    if not isinstance(item, dict):
+        return item
+
+    if item.get("type") == "input_image" and "image_url" in item:
+        return {
+            **item,
+            "image_url": redact_base64_data_url(item["image_url"]),
+        }
+
+    return item
+
+
+def sanitize_anthropic_image(item: Any) -> Any:
+    if not isinstance(item, dict):
+        return item
+
+    if (
+        item.get("type") == "image"
+        and isinstance(item.get("source"), dict)
+        and item["source"].get("type") == "base64"
+        and "data" in item["source"]
+    ):
+        # For Anthropic, if the source type is "base64", we should always redact the data
+        # The provider is explicitly telling us this is base64 data
+        return {
+            **item,
+            "source": {
+                **item["source"],
+                "data": REDACTED_IMAGE_PLACEHOLDER,
+            },
+        }
+
+    return item
+
+
+def sanitize_gemini_part(part: Any) -> Any:
+    if not isinstance(part, dict):
+        return part
+
+    if (
+        "inline_data" in part
+        and isinstance(part["inline_data"], dict)
+        and "data" in part["inline_data"]
+    ):
+        # For Gemini, the inline_data structure indicates base64 data
+        # We should redact any string data in this context
+        return {
+            **part,
+            "inline_data": {
+                **part["inline_data"],
+                "data": REDACTED_IMAGE_PLACEHOLDER,
+            },
+        }
+
+    return part
+
+
+def process_gemini_item(item: Any) -> Any:
+    if not isinstance(item, dict):
+        return item
+
+    if "parts" in item and item["parts"]:
+        parts = item["parts"]
+        if isinstance(parts, list):
+            parts = [sanitize_gemini_part(part) for part in parts]
+        else:
+            parts = sanitize_gemini_part(parts)
+
+        return {**item, "parts": parts}
+
+    return item
+
+
+def sanitize_langchain_image(item: Any) -> Any:
+    if not isinstance(item, dict):
+        return item
+
+    if (
+        item.get("type") == "image_url"
+        and isinstance(item.get("image_url"), dict)
+        and "url" in item["image_url"]
+    ):
+        return {
+            **item,
+            "image_url": {
+                **item["image_url"],
+                "url": redact_base64_data_url(item["image_url"]["url"]),
+            },
+        }
+
+    if item.get("type") == "image" and "data" in item:
+        return {**item, "data": redact_base64_data_url(item["data"])}
+
+    if (
+        item.get("type") == "image"
+        and isinstance(item.get("source"), dict)
+        and "data" in item["source"]
+    ):
+        # Anthropic style - raw base64 in structured format, always redact
+        return {
+            **item,
+            "source": {
+                **item["source"],
+                "data": REDACTED_IMAGE_PLACEHOLDER,
+            },
+        }
+
+    if item.get("type") == "media" and "data" in item:
+        return {**item, "data": redact_base64_data_url(item["data"])}
+
+    return item
+
+
+def sanitize_openai(data: Any) -> Any:
+    return process_messages(data, sanitize_openai_image)
+
+
+def sanitize_openai_response(data: Any) -> Any:
+    return process_messages(data, sanitize_openai_response_image)
+
+
+def sanitize_anthropic(data: Any) -> Any:
+    return process_messages(data, sanitize_anthropic_image)
+
+
+def sanitize_gemini(data: Any) -> Any:
+    if not data:
+        return data
+
+    if isinstance(data, list):
+        return [process_gemini_item(item) for item in data]
+
+    return process_gemini_item(data)
+
+
+def sanitize_langchain(data: Any) -> Any:
+    return process_messages(data, sanitize_langchain_image)

posthog/ai/types.py

@@ -0,0 +1,124 @@
+"""
+Common type definitions for PostHog AI SDK.
+
+These types are used for formatting messages and responses across different AI providers
+(Anthropic, OpenAI, Gemini, etc.) to ensure consistency in tracking and data structure.
+"""
+
+from typing import Any, Dict, List, Optional, TypedDict, Union
+
+
+class FormattedTextContent(TypedDict):
+    """Formatted text content item."""
+
+    type: str  # Literal["text"]
+    text: str
+
+
+class FormattedFunctionCall(TypedDict, total=False):
+    """Formatted function/tool call content item."""
+
+    type: str  # Literal["function"]
+    id: Optional[str]
+    function: Dict[str, Any]  # Contains 'name' and 'arguments'
+
+
+class FormattedImageContent(TypedDict):
+    """Formatted image content item."""
+
+    type: str  # Literal["image"]
+    image: str
+
+
+# Union type for all formatted content items
+FormattedContentItem = Union[
+    FormattedTextContent,
+    FormattedFunctionCall,
+    FormattedImageContent,
+    Dict[str, Any],  # Fallback for unknown content types
+]
+
+
+class FormattedMessage(TypedDict):
+    """
+    Standardized message format for PostHog tracking.
+
+    Used across all providers to ensure consistent message structure
+    when sending events to PostHog.
+    """
+
+    role: str
+    content: Union[str, List[FormattedContentItem], Any]
+
+
+class TokenUsage(TypedDict, total=False):
+    """
+    Token usage information for AI model responses.
+
+    Different providers may populate different fields.
+    """
+
+    input_tokens: int
+    output_tokens: int
+    cache_read_input_tokens: Optional[int]
+    cache_creation_input_tokens: Optional[int]
+    reasoning_tokens: Optional[int]
+
+
+class ProviderResponse(TypedDict, total=False):
+    """
+    Standardized provider response format.
+
+    Used for consistent response formatting across all providers.
+    """
+
+    messages: List[FormattedMessage]
+    usage: TokenUsage
+    error: Optional[str]
+
+
+class StreamingContentBlock(TypedDict, total=False):
+    """
+    Content block used during streaming to accumulate content.
+
+    Used for tracking text and function calls as they stream in.
+    """
+
+    type: str  # "text" or "function"
+    text: Optional[str]
+    id: Optional[str]
+    function: Optional[Dict[str, Any]]
+
+
+class ToolInProgress(TypedDict):
+    """
+    Tracks a tool/function call being accumulated during streaming.
+
+    Used by Anthropic to accumulate JSON input for tools.
+    """
+
+    block: StreamingContentBlock
+    input_string: str
+
+
+class StreamingEventData(TypedDict):
+    """
+    Standardized data for streaming events across all providers.
+
+    This type ensures consistent data structure when capturing streaming events,
+    with all provider-specific formatting already completed.
+    """
+
+    provider: str  # "openai", "anthropic", "gemini"
+    model: str
+    base_url: str
+    kwargs: Dict[str, Any]  # Original kwargs for tool extraction and special handling
+    formatted_input: Any  # Provider-formatted input ready for tracking
+    formatted_output: Any  # Provider-formatted output ready for tracking
+    usage_stats: TokenUsage
+    latency: float
+    distinct_id: Optional[str]
+    trace_id: Optional[str]
+    properties: Optional[Dict[str, Any]]
+    privacy_mode: bool
+    groups: Optional[Dict[str, Any]]

posthog/ai/utils.py

@@ -1,10 +1,74 @@
 import time
 import uuid
-from typing import Any, Callable, Dict, List, Optional
-
-from httpx import URL
+from typing import Any, Callable, Dict, List, Optional, cast
 
 from posthog.client import Client as PostHogClient
+from posthog.ai.types import FormattedMessage, StreamingEventData, TokenUsage
+from posthog.ai.sanitization import (
+    sanitize_openai,
+    sanitize_anthropic,
+    sanitize_gemini,
+    sanitize_langchain,
+)
+
+
+def merge_usage_stats(
+    target: TokenUsage, source: TokenUsage, mode: str = "incremental"
+) -> None:
+    """
+    Merge streaming usage statistics into target dict, handling None values.
+
+    Supports two modes:
+    - "incremental": Add source values to target (for APIs that report new tokens)
+    - "cumulative": Replace target with source values (for APIs that report totals)
+
+    Args:
+        target: Dictionary to update with usage stats
+        source: TokenUsage that may contain None values
+        mode: Either "incremental" or "cumulative"
+    """
+    if mode == "incremental":
+        # Add new values to existing totals
+        source_input = source.get("input_tokens")
+        if source_input is not None:
+            current = target.get("input_tokens") or 0
+            target["input_tokens"] = current + source_input
+
+        source_output = source.get("output_tokens")
+        if source_output is not None:
+            current = target.get("output_tokens") or 0
+            target["output_tokens"] = current + source_output
+
+        source_cache_read = source.get("cache_read_input_tokens")
+        if source_cache_read is not None:
+            current = target.get("cache_read_input_tokens") or 0
+            target["cache_read_input_tokens"] = current + source_cache_read
+
+        source_cache_creation = source.get("cache_creation_input_tokens")
+        if source_cache_creation is not None:
+            current = target.get("cache_creation_input_tokens") or 0
+            target["cache_creation_input_tokens"] = current + source_cache_creation
+
+        source_reasoning = source.get("reasoning_tokens")
+        if source_reasoning is not None:
+            current = target.get("reasoning_tokens") or 0
+            target["reasoning_tokens"] = current + source_reasoning
+    elif mode == "cumulative":
+        # Replace with latest values (already cumulative)
+        if source.get("input_tokens") is not None:
+            target["input_tokens"] = source["input_tokens"]
+        if source.get("output_tokens") is not None:
+            target["output_tokens"] = source["output_tokens"]
+        if source.get("cache_read_input_tokens") is not None:
+            target["cache_read_input_tokens"] = source["cache_read_input_tokens"]
+        if source.get("cache_creation_input_tokens") is not None:
+            target["cache_creation_input_tokens"] = source[
+                "cache_creation_input_tokens"
+            ]
+        if source.get("reasoning_tokens") is not None:
+            target["reasoning_tokens"] = source["reasoning_tokens"]
+    else:
+        raise ValueError(f"Invalid mode: {mode}. Must be 'incremental' or 'cumulative'")
 
 
 def get_model_params(kwargs: Dict[str, Any]) -> Dict[str, Any]:
@@ -29,285 +93,135 @@ def get_model_params(kwargs: Dict[str, Any]) -> Dict[str, Any]:
     return model_params
 
 
-def get_usage(response, provider: str) -> Dict[str, Any]:
+def get_usage(response, provider: str) -> TokenUsage:
+    """
+    Extract usage statistics from response based on provider.
+    Delegates to provider-specific converter functions.
+    """
     if provider == "anthropic":
-        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,
-        }
+        from posthog.ai.anthropic.anthropic_converter import (
+            extract_anthropic_usage_from_response,
+        )
+
+        return extract_anthropic_usage_from_response(response)
     elif provider == "openai":
-        cached_tokens = 0
-        input_tokens = 0
-        output_tokens = 0
-        reasoning_tokens = 0
+        from posthog.ai.openai.openai_converter import (
+            extract_openai_usage_from_response,
+        )
 
-        # 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": input_tokens,
-            "output_tokens": output_tokens,
-            "cache_read_input_tokens": cached_tokens,
-            "reasoning_tokens": reasoning_tokens,
-        }
+        return extract_openai_usage_from_response(response)
     elif provider == "gemini":
-        input_tokens = 0
-        output_tokens = 0
+        from posthog.ai.gemini.gemini_converter import (
+            extract_gemini_usage_from_response,
+        )
 
-        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 extract_gemini_usage_from_response(response)
 
-        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,
-    }
+    return TokenUsage(input_tokens=0, output_tokens=0)
 
 
 def format_response(response, provider: str):
     """
     Format a regular (non-streaming) response.
     """
-    output = []
-    if response is None:
-        return output
     if provider == "anthropic":
-        return format_response_anthropic(response)
+        from posthog.ai.anthropic.anthropic_converter import format_anthropic_response
+
+        return format_anthropic_response(response)
     elif provider == "openai":
-        return format_response_openai(response)
+        from posthog.ai.openai.openai_converter import format_openai_response
+
+        return format_openai_response(response)
     elif provider == "gemini":
-        return format_response_gemini(response)
-    return output
+        from posthog.ai.gemini.gemini_converter import format_gemini_response
+
+        return format_gemini_response(response)
+    return []
 
 
-def format_response_anthropic(response):
-    output = []
-    for choice in response.content:
-        if choice.text:
-            output.append(
-                {
-                    "role": "assistant",
-                    "content": choice.text,
-                }
-            )
-    return output
-
-
-def format_response_openai(response):
-    output = []
-    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):
+def extract_available_tool_calls(provider: str, kwargs: Dict[str, Any]):
+    """
+    Extract available tool calls for the given provider.
+    """
     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
+        from posthog.ai.anthropic.anthropic_converter import extract_anthropic_tools
 
-            # 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 extract_anthropic_tools(kwargs)
+    elif provider == "gemini":
+        from posthog.ai.gemini.gemini_converter import extract_gemini_tools
+
+        return extract_gemini_tools(kwargs)
+    elif provider == "openai":
+        from posthog.ai.openai.openai_converter import extract_openai_tools
+
+        return extract_openai_tools(kwargs)
     return None
 
 
-def merge_system_prompt(kwargs: Dict[str, Any], provider: str):
-    messages: List[Dict[str, Any]] = []
+def merge_system_prompt(
+    kwargs: Dict[str, Any], provider: str
+) -> List[FormattedMessage]:
+    """
+    Merge system prompts and format messages for the given provider.
+    """
     if provider == "anthropic":
+        from posthog.ai.anthropic.anthropic_converter import format_anthropic_input
+
         messages = kwargs.get("messages") or []
-        if kwargs.get("system") is None:
-            return messages
-        return [{"role": "system", "content": kwargs.get("system")}] + messages
+        system = kwargs.get("system")
+        return format_anthropic_input(messages, system)
     elif provider == "gemini":
+        from posthog.ai.gemini.gemini_converter import format_gemini_input_with_system
+
         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)}]
+        config = kwargs.get("config")
+        return format_gemini_input_with_system(contents, config)
+    elif provider == "openai":
+        from posthog.ai.openai.openai_converter import format_openai_input
 
-    # For OpenAI, handle both Chat Completions and Responses API
-    if kwargs.get("messages") is not None:
-        messages = list(kwargs.get("messages", []))
+        # For OpenAI, handle both Chat Completions and Responses API
+        messages_param = kwargs.get("messages")
+        input_param = kwargs.get("input")
 
-    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})
+        # Get base formatted messages
+        messages = format_openai_input(messages_param, input_param)
 
-    # 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
+        # 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:
+                system_msg = cast(
+                    FormattedMessage,
+                    {"role": "system", "content": kwargs.get("system")},
+                )
+                messages = [system_msg] + 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')}"
+        # 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,
             )
-        else:
-            # Create a new system message with instructions
-            messages = [
-                {"role": "system", "content": kwargs.get("instructions")}
-            ] + messages
 
-    return messages
+            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
+                instruction_msg = cast(
+                    FormattedMessage,
+                    {"role": "system", "content": kwargs.get("instructions")},
+                )
+                messages = [instruction_msg] + messages
+
+        return messages
+
+    # Default case - return empty list
+    return []
 
 
 def call_llm_and_track_usage(
@@ -318,7 +232,7 @@ def call_llm_and_track_usage(
     posthog_properties: Optional[Dict[str, Any]],
     posthog_privacy_mode: bool,
     posthog_groups: Optional[Dict[str, Any]],
-    base_url: URL,
+    base_url: str,
     call_method: Callable[..., Any],
     **kwargs: Any,
 ) -> Any:
@@ -330,8 +244,8 @@ def call_llm_and_track_usage(
     response = None
     error = None
     http_status = 200
-    usage: Dict[str, Any] = {}
-    error_params: Dict[str, any] = {}
+    usage: TokenUsage = TokenUsage()
+    error_params: Dict[str, Any] = {}
 
     try:
         response = call_method(**kwargs)
@@ -358,12 +272,15 @@ def call_llm_and_track_usage(
             usage = get_usage(response, provider)
 
         messages = merge_system_prompt(kwargs, provider)
+        sanitized_messages = sanitize_messages(messages, provider)
 
         event_properties = {
             "$ai_provider": provider,
             "$ai_model": kwargs.get("model"),
             "$ai_model_parameters": get_model_params(kwargs),
-            "$ai_input": with_privacy_mode(ph_client, posthog_privacy_mode, messages),
+            "$ai_input": with_privacy_mode(
+                ph_client, posthog_privacy_mode, sanitized_messages
+            ),
             "$ai_output_choices": with_privacy_mode(
                 ph_client, posthog_privacy_mode, format_response(response, provider)
             ),
@@ -377,33 +294,22 @@ 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
-            )
+        available_tool_calls = extract_available_tool_calls(provider, kwargs)
 
-        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 available_tool_calls:
+            event_properties["$ai_tools"] = available_tool_calls
 
-        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
-            )
+        cache_read = usage.get("cache_read_input_tokens")
+        if cache_read is not None and cache_read > 0:
+            event_properties["$ai_cache_read_input_tokens"] = cache_read
 
-        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)
+        cache_creation = usage.get("cache_creation_input_tokens")
+        if cache_creation is not None and cache_creation > 0:
+            event_properties["$ai_cache_creation_input_tokens"] = cache_creation
+
+        reasoning = usage.get("reasoning_tokens")
+        if reasoning is not None and reasoning > 0:
+            event_properties["$ai_reasoning_tokens"] = reasoning
 
         if posthog_distinct_id is None:
             event_properties["$process_person_profile"] = False
@@ -437,7 +343,7 @@ async def call_llm_and_track_usage_async(
     posthog_properties: Optional[Dict[str, Any]],
     posthog_privacy_mode: bool,
     posthog_groups: Optional[Dict[str, Any]],
-    base_url: URL,
+    base_url: str,
     call_async_method: Callable[..., Any],
     **kwargs: Any,
 ) -> Any:
@@ -445,8 +351,8 @@ async def call_llm_and_track_usage_async(
     response = None
     error = None
     http_status = 200
-    usage: Dict[str, Any] = {}
-    error_params: Dict[str, any] = {}
+    usage: TokenUsage = TokenUsage()
+    error_params: Dict[str, Any] = {}
 
     try:
         response = await call_async_method(**kwargs)
@@ -473,12 +379,15 @@ async def call_llm_and_track_usage_async(
             usage = get_usage(response, provider)
 
         messages = merge_system_prompt(kwargs, provider)
+        sanitized_messages = sanitize_messages(messages, provider)
 
         event_properties = {
             "$ai_provider": provider,
             "$ai_model": kwargs.get("model"),
             "$ai_model_parameters": get_model_params(kwargs),
-            "$ai_input": with_privacy_mode(ph_client, posthog_privacy_mode, messages),
+            "$ai_input": with_privacy_mode(
+                ph_client, posthog_privacy_mode, sanitized_messages
+            ),
             "$ai_output_choices": with_privacy_mode(
                 ph_client, posthog_privacy_mode, format_response(response, provider)
             ),
@@ -492,27 +401,18 @@ 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
-            )
+        available_tool_calls = extract_available_tool_calls(provider, kwargs)
 
-        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 available_tool_calls:
+            event_properties["$ai_tools"] = available_tool_calls
 
-        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
-            )
+        cache_read = usage.get("cache_read_input_tokens")
+        if cache_read is not None and cache_read > 0:
+            event_properties["$ai_cache_read_input_tokens"] = cache_read
+
+        cache_creation = usage.get("cache_creation_input_tokens")
+        if cache_creation is not None and cache_creation > 0:
+            event_properties["$ai_cache_creation_input_tokens"] = cache_creation
 
         if posthog_distinct_id is None:
             event_properties["$process_person_profile"] = False
@@ -538,7 +438,122 @@ async def call_llm_and_track_usage_async(
     return response
 
 
+def sanitize_messages(data: Any, provider: str) -> Any:
+    """Sanitize messages using provider-specific sanitization functions."""
+    if provider == "anthropic":
+        return sanitize_anthropic(data)
+    elif provider == "openai":
+        return sanitize_openai(data)
+    elif provider == "gemini":
+        return sanitize_gemini(data)
+    elif provider == "langchain":
+        return sanitize_langchain(data)
+    return data
+
+
 def with_privacy_mode(ph_client: PostHogClient, privacy_mode: bool, value: Any):
     if ph_client.privacy_mode or privacy_mode:
         return None
     return value
+
+
+def capture_streaming_event(
+    ph_client: PostHogClient,
+    event_data: StreamingEventData,
+):
+    """
+    Unified streaming event capture for all LLM providers.
+
+    This function handles the common logic for capturing streaming events across all providers.
+    All provider-specific formatting should be done BEFORE calling this function.
+
+    The function handles:
+    - Building PostHog event properties
+    - Extracting and adding tools based on provider
+    - Applying privacy mode
+    - Adding special token fields (cache, reasoning)
+    - Provider-specific fields (e.g., OpenAI instructions)
+    - Sending the event to PostHog
+
+    Args:
+        ph_client: PostHog client instance
+        event_data: Standardized streaming event data containing all necessary information
+    """
+    trace_id = event_data.get("trace_id") or str(uuid.uuid4())
+
+    # Build base event properties
+    event_properties = {
+        "$ai_provider": event_data["provider"],
+        "$ai_model": event_data["model"],
+        "$ai_model_parameters": get_model_params(event_data["kwargs"]),
+        "$ai_input": with_privacy_mode(
+            ph_client,
+            event_data["privacy_mode"],
+            event_data["formatted_input"],
+        ),
+        "$ai_output_choices": with_privacy_mode(
+            ph_client,
+            event_data["privacy_mode"],
+            event_data["formatted_output"],
+        ),
+        "$ai_http_status": 200,
+        "$ai_input_tokens": event_data["usage_stats"].get("input_tokens", 0),
+        "$ai_output_tokens": event_data["usage_stats"].get("output_tokens", 0),
+        "$ai_latency": event_data["latency"],
+        "$ai_trace_id": trace_id,
+        "$ai_base_url": str(event_data["base_url"]),
+        **(event_data.get("properties") or {}),
+    }
+
+    # Extract and add tools based on provider
+    available_tools = extract_available_tool_calls(
+        event_data["provider"],
+        event_data["kwargs"],
+    )
+    if available_tools:
+        event_properties["$ai_tools"] = available_tools
+
+    # Add optional token fields
+    # For Anthropic, always include cache fields even if 0 (backward compatibility)
+    # For others, only include if present and non-zero
+    if event_data["provider"] == "anthropic":
+        # Anthropic always includes cache fields
+        cache_read = event_data["usage_stats"].get("cache_read_input_tokens", 0)
+        cache_creation = event_data["usage_stats"].get("cache_creation_input_tokens", 0)
+        event_properties["$ai_cache_read_input_tokens"] = cache_read
+        event_properties["$ai_cache_creation_input_tokens"] = cache_creation
+    else:
+        # Other providers only include if non-zero
+        optional_token_fields = [
+            "cache_read_input_tokens",
+            "cache_creation_input_tokens",
+            "reasoning_tokens",
+        ]
+
+        for field in optional_token_fields:
+            value = event_data["usage_stats"].get(field)
+            if value is not None and isinstance(value, int) and value > 0:
+                event_properties[f"$ai_{field}"] = value
+
+    # Handle provider-specific fields
+    if (
+        event_data["provider"] == "openai"
+        and event_data["kwargs"].get("instructions") is not None
+    ):
+        event_properties["$ai_instructions"] = with_privacy_mode(
+            ph_client,
+            event_data["privacy_mode"],
+            event_data["kwargs"]["instructions"],
+        )
+
+    if event_data.get("distinct_id") is None:
+        event_properties["$process_person_profile"] = False
+
+    # Send event to PostHog
+    if hasattr(ph_client, "capture"):
+        ph_client.capture(
+            distinct_id=event_data.get("distinct_id") or trace_id,
+            event="$ai_generation",
+            properties=event_properties,
+            groups=event_data.get("groups"),
+        )

posthog/args.py

@@ -5,6 +5,8 @@ from datetime import datetime
 import numbers
 from uuid import UUID
 
+from posthog.types import SendFeatureFlagsOptions
+
 ID_TYPES = Union[numbers.Number, str, UUID, int]
 
 
@@ -22,7 +24,8 @@ class OptionalCaptureArgs(TypedDict):
             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.
-            Defaults to True
+            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.
     """
 
@@ -32,8 +35,8 @@ class OptionalCaptureArgs(TypedDict):
     uuid: NotRequired[Optional[str]]
     groups: NotRequired[Optional[Dict[str, str]]]
     send_feature_flags: NotRequired[
-        Optional[bool]
-    ]  # Optional so we can tell if the user is intentionally overriding a client setting or not
+        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

posthog/contexts.py

@@ -71,7 +71,9 @@ def _get_current_context() -> Optional[ContextScope]:
 
 @contextmanager
 def new_context(
-    fresh=False, capture_exceptions=True, client: Optional["Client"] = None
+    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.
@@ -94,20 +96,25 @@ def new_context(
                 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
 
@@ -138,7 +145,12 @@ def tag(key: str, value: Any) -> None:
         value: The tag value
 
     Example:
+        ```python
         posthog.tag("user_id", "123")
+        ```
+
+    Category:
+        Contexts
     """
     current_context = _get_current_context()
     if current_context:
@@ -152,6 +164,9 @@ def get_tags() -> Dict[str, Any]:
 
     Returns:
         Dict of all tags in the current context
+
+    Category:
+        Contexts
     """
     current_context = _get_current_context()
     if current_context:
@@ -170,6 +185,9 @@ def identify_context(distinct_id: str) -> None:
 
     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:
@@ -184,6 +202,9 @@ def set_context_session(session_id: str) -> None:
 
     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:
@@ -196,6 +217,9 @@ def get_context_session_id() -> Optional[str]:
 
     Returns:
         The session ID if set, None otherwise
+
+    Category:
+        Contexts
     """
     current_context = _get_current_context()
     if current_context:
@@ -209,6 +233,9 @@ def get_context_distinct_id() -> Optional[str]:
 
     Returns:
         The distinct ID if set, None otherwise
+
+    Category:
+        Contexts
     """
     current_context = _get_current_context()
     if current_context:
@@ -219,7 +246,7 @@ def get_context_distinct_id() -> Optional[str]:
 F = TypeVar("F", bound=Callable[..., Any])
 
 
-def scoped(fresh=False, capture_exceptions=True):
+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.
@@ -239,6 +266,9 @@ def scoped(fresh=False, capture_exceptions=True):
             # 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:

posthog/feature_flags.py

@@ -22,6 +22,18 @@ class InconclusiveMatchError(Exception):
     pass
 
 
+class RequiresServerEvaluation(Exception):
+    """
+    Raised when feature flag evaluation requires server-side data that is not
+    available locally (e.g., static cohorts, experience continuity).
+
+    This error should propagate immediately to trigger API fallback, unlike
+    InconclusiveMatchError which allows trying other conditions.
+    """
+
+    pass
+
+
 # This function takes a distinct_id and a feature flag key and returns a float between 0 and 1.
 # 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
@@ -55,8 +67,161 @@ def variant_lookup_table(feature_flag):
     return lookup_table
 
 
+def evaluate_flag_dependency(
+    property, flags_by_key, evaluation_cache, distinct_id, properties, cohort_properties
+):
+    """
+    Evaluate a flag dependency property according to the dependency chain algorithm.
+
+    Args:
+        property: Flag property with type="flag" and dependency_chain
+        flags_by_key: Dictionary of all flags by their key
+        evaluation_cache: Cache for storing evaluation results
+        distinct_id: The distinct ID being evaluated
+        properties: Person properties for evaluation
+        cohort_properties: Cohort properties for evaluation
+
+    Returns:
+        bool: True if all dependencies in the chain evaluate to True, False otherwise
+    """
+    if flags_by_key is None or evaluation_cache is None:
+        # Cannot evaluate flag dependencies without required context
+        raise InconclusiveMatchError(
+            f"Cannot evaluate flag dependency on '{property.get('key', 'unknown')}' without flags_by_key and evaluation_cache"
+        )
+
+    # Check if dependency_chain is present - it should always be provided for flag dependencies
+    if "dependency_chain" not in property:
+        # Missing dependency_chain indicates malformed server data
+        raise InconclusiveMatchError(
+            f"Flag dependency property for '{property.get('key', 'unknown')}' is missing required 'dependency_chain' field"
+        )
+
+    dependency_chain = property["dependency_chain"]
+
+    # Handle circular dependency (empty chain means circular)
+    if len(dependency_chain) == 0:
+        log.debug(f"Circular dependency detected for flag: {property.get('key')}")
+        raise InconclusiveMatchError(
+            f"Circular dependency detected for flag '{property.get('key', 'unknown')}'"
+        )
+
+    # Evaluate all dependencies in the chain order
+    for dep_flag_key in dependency_chain:
+        if dep_flag_key not in evaluation_cache:
+            # Need to evaluate this dependency first
+            dep_flag = flags_by_key.get(dep_flag_key)
+            if not dep_flag:
+                # Missing flag dependency - cannot evaluate locally
+                evaluation_cache[dep_flag_key] = None
+                raise InconclusiveMatchError(
+                    f"Cannot evaluate flag dependency '{dep_flag_key}' - flag not found in local flags"
+                )
+            else:
+                # Check if the flag is active (same check as in client._compute_flag_locally)
+                if not dep_flag.get("active"):
+                    evaluation_cache[dep_flag_key] = False
+                else:
+                    # Recursively evaluate the dependency
+                    try:
+                        dep_result = match_feature_flag_properties(
+                            dep_flag,
+                            distinct_id,
+                            properties,
+                            cohort_properties,
+                            flags_by_key,
+                            evaluation_cache,
+                        )
+                        evaluation_cache[dep_flag_key] = dep_result
+                    except InconclusiveMatchError as e:
+                        # If we can't evaluate a dependency, store None and propagate the error
+                        evaluation_cache[dep_flag_key] = None
+                        raise InconclusiveMatchError(
+                            f"Cannot evaluate flag dependency '{dep_flag_key}': {e}"
+                        ) from e
+
+        # Check the cached result
+        cached_result = evaluation_cache[dep_flag_key]
+        if cached_result is None:
+            # Previously inconclusive - raise error again
+            raise InconclusiveMatchError(
+                f"Flag dependency '{dep_flag_key}' was previously inconclusive"
+            )
+        elif not cached_result:
+            # Definitive False result - dependency failed
+            return False
+
+    # All dependencies in the chain have been evaluated successfully
+    # Now check if the final flag value matches the expected value in the property
+    flag_key = property.get("key")
+    expected_value = property.get("value")
+    operator = property.get("operator", "exact")
+
+    if flag_key and expected_value is not None:
+        # Get the actual value of the flag we're checking
+        actual_value = evaluation_cache.get(flag_key)
+
+        if actual_value is None:
+            # Flag wasn't evaluated - this shouldn't happen if dependency chain is correct
+            raise InconclusiveMatchError(
+                f"Flag '{flag_key}' was not evaluated despite being in dependency chain"
+            )
+
+        # For flag dependencies, we need to compare the actual flag result with expected value
+        # using the flag_evaluates_to operator logic
+        if operator == "flag_evaluates_to":
+            return matches_dependency_value(expected_value, actual_value)
+        else:
+            # This should never happen, but just to be defensive.
+            raise InconclusiveMatchError(
+                f"Flag dependency property for '{property.get('key', 'unknown')}' has invalid operator '{operator}'"
+            )
+
+    # If no value check needed, return True (all dependencies passed)
+    return True
+
+
+def matches_dependency_value(expected_value, actual_value):
+    """
+    Check if the actual flag value matches the expected dependency value.
+
+    This follows the same logic as the C# MatchesDependencyValue function:
+    - String variant case: check for exact match or boolean true
+    - Boolean case: must match expected boolean value
+
+    Args:
+        expected_value: The expected value from the property
+        actual_value: The actual value returned by the flag evaluation
+
+    Returns:
+        bool: True if the values match according to flag dependency rules
+    """
+    # String variant case - check for exact match or boolean true
+    if isinstance(actual_value, str) and len(actual_value) > 0:
+        if isinstance(expected_value, bool):
+            # Any variant matches boolean true
+            return expected_value
+        elif isinstance(expected_value, str):
+            # variants are case-sensitive, hence our comparison is too
+            return actual_value == expected_value
+        else:
+            return False
+
+    # Boolean case - must match expected boolean value
+    elif isinstance(actual_value, bool) and isinstance(expected_value, bool):
+        return actual_value == expected_value
+
+    # Default case
+    return False
+
+
 def match_feature_flag_properties(
-    flag, distinct_id, properties, cohort_properties=None
+    flag,
+    distinct_id,
+    properties,
+    cohort_properties=None,
+    flags_by_key=None,
+    evaluation_cache=None,
 ) -> FlagValue:
     flag_conditions = (flag.get("filters") or {}).get("groups") or []
     is_inconclusive = False
@@ -67,19 +232,18 @@ def match_feature_flag_properties(
     ) 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
-    # evaluated first, and the variant override is applied to the first matching condition.
-    sorted_flag_conditions = sorted(
-        flag_conditions,
-        key=lambda condition: 0 if condition.get("variant") else 1,
-    )
-
-    for condition in sorted_flag_conditions:
+    for condition in flag_conditions:
         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
+                flag,
+                distinct_id,
+                condition,
+                properties,
+                cohort_properties,
+                flags_by_key,
+                evaluation_cache,
             ):
                 variant_override = condition.get("variant")
                 if variant_override and variant_override in valid_variant_keys:
@@ -87,7 +251,12 @@ def match_feature_flag_properties(
                 else:
                     variant = get_matching_variant(flag, distinct_id)
                 return variant or True
+        except RequiresServerEvaluation:
+            # Static cohort or other missing server-side data - must fallback to API
+            raise
         except InconclusiveMatchError:
+            # Evaluation error (bad regex, invalid date, missing property, etc.)
+            # Track that we had an inconclusive match, but try other conditions
             is_inconclusive = True
 
     if is_inconclusive:
@@ -101,14 +270,36 @@ def match_feature_flag_properties(
 
 
 def is_condition_match(
-    feature_flag, distinct_id, condition, properties, cohort_properties
+    feature_flag,
+    distinct_id,
+    condition,
+    properties,
+    cohort_properties,
+    flags_by_key=None,
+    evaluation_cache=None,
 ) -> 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)
+                matches = match_cohort(
+                    prop,
+                    properties,
+                    cohort_properties,
+                    flags_by_key,
+                    evaluation_cache,
+                    distinct_id,
+                )
+            elif property_type == "flag":
+                matches = evaluate_flag_dependency(
+                    prop,
+                    flags_by_key,
+                    evaluation_cache,
+                    distinct_id,
+                    properties,
+                    cohort_properties,
+                )
             else:
                 matches = match_property(prop, properties)
             if not matches:
@@ -256,7 +447,14 @@ def match_property(property, property_values) -> bool:
     raise InconclusiveMatchError(f"Unknown operator {operator}")
 
 
-def match_cohort(property, property_values, cohort_properties) -> bool:
+def match_cohort(
+    property,
+    property_values,
+    cohort_properties,
+    flags_by_key=None,
+    evaluation_cache=None,
+    distinct_id=None,
+) -> bool:
     # Cohort properties are in the form of property groups like this:
     # {
     #     "cohort_id": {
@@ -268,15 +466,29 @@ 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 RequiresServerEvaluation(
+            f"cohort {cohort_id} not found in local cohorts - likely a static cohort that requires server evaluation"
         )
 
     property_group = cohort_properties[cohort_id]
-    return match_property_group(property_group, property_values, cohort_properties)
+    return match_property_group(
+        property_group,
+        property_values,
+        cohort_properties,
+        flags_by_key,
+        evaluation_cache,
+        distinct_id,
+    )
 
 
-def match_property_group(property_group, property_values, cohort_properties) -> bool:
+def match_property_group(
+    property_group,
+    property_values,
+    cohort_properties,
+    flags_by_key=None,
+    evaluation_cache=None,
+    distinct_id=None,
+) -> bool:
     if not property_group:
         return True
 
@@ -293,7 +505,14 @@ def match_property_group(property_group, property_values, cohort_properties) ->
         # a nested property group
         for prop in properties:
             try:
-                matches = match_property_group(prop, property_values, cohort_properties)
+                matches = match_property_group(
+                    prop,
+                    property_values,
+                    cohort_properties,
+                    flags_by_key,
+                    evaluation_cache,
+                    distinct_id,
+                )
                 if property_group_type == "AND":
                     if not matches:
                         return False
@@ -301,6 +520,9 @@ def match_property_group(property_group, property_values, cohort_properties) ->
                     # OR group
                     if matches:
                         return True
+            except RequiresServerEvaluation:
+                # Immediately propagate - this condition requires server-side data
+                raise
             except InconclusiveMatchError as e:
                 log.debug(f"Failed to compute property {prop} locally: {e}")
                 error_matching_locally = True
@@ -316,7 +538,23 @@ def match_property_group(property_group, property_values, cohort_properties) ->
         for prop in properties:
             try:
                 if prop.get("type") == "cohort":
-                    matches = match_cohort(prop, property_values, cohort_properties)
+                    matches = match_cohort(
+                        prop,
+                        property_values,
+                        cohort_properties,
+                        flags_by_key,
+                        evaluation_cache,
+                        distinct_id,
+                    )
+                elif prop.get("type") == "flag":
+                    matches = evaluate_flag_dependency(
+                        prop,
+                        flags_by_key,
+                        evaluation_cache,
+                        distinct_id,
+                        property_values,
+                        cohort_properties,
+                    )
                 else:
                     matches = match_property(prop, property_values)
 
@@ -334,6 +572,9 @@ def match_property_group(property_group, property_values, cohort_properties) ->
                         return True
                     if not matches and negation:
                         return True
+            except RequiresServerEvaluation:
+                # Immediately propagate - this condition requires server-side data
+                raise
             except InconclusiveMatchError as e:
                 log.debug(f"Failed to compute property {prop} locally: {e}")
                 error_matching_locally = True

posthog/integrations/django.py

@@ -1,9 +1,24 @@
 from typing import TYPE_CHECKING, cast
 from posthog import contexts
+from posthog.client import Client
+
+try:
+    from asgiref.sync import iscoroutinefunction, markcoroutinefunction
+except ImportError:
+    # Fallback for older Django versions without asgiref
+    import asyncio
+
+    iscoroutinefunction = asyncio.iscoroutinefunction
+
+    # No-op fallback for markcoroutinefunction
+    # Older Django versions without asgiref typically don't support async middleware anyway
+    def markcoroutinefunction(func):
+        return func
+
 
 if TYPE_CHECKING:
     from django.http import HttpRequest, HttpResponse  # noqa: F401
-    from typing import Callable, Dict, Any, Optional  # noqa: F401
+    from typing import Callable, Dict, Any, Optional, Union, Awaitable  # noqa: F401
 
 
 class PosthogContextMiddleware:
@@ -16,7 +31,8 @@ class PosthogContextMiddleware:
     - 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.
+    `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.
@@ -29,11 +45,24 @@ class PosthogContextMiddleware:
     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.
+
+    This middleware is hybrid-capable: it supports both WSGI (sync) and ASGI (async) Django applications. The middleware
+    detects at initialization whether the next middleware in the chain is async or sync, and adapts its behavior accordingly.
+    This ensures compatibility with both pure sync and pure async middleware chains, as well as mixed chains in ASGI mode.
     """
 
+    sync_capable = True
+    async_capable = True
+
     def __init__(self, get_response):
-        # type: (Callable[[HttpRequest], HttpResponse]) -> None
+        # type: (Union[Callable[[HttpRequest], HttpResponse], Callable[[HttpRequest], Awaitable[HttpResponse]]]) -> None
         self.get_response = get_response
+        self._is_coroutine = iscoroutinefunction(get_response)
+
+        # Mark this instance as a coroutine function if get_response is async
+        # This is required for Django to correctly detect async middleware
+        if self._is_coroutine:
+            markcoroutinefunction(self)
 
         from django.conf import settings
 
@@ -74,6 +103,13 @@ class PosthogContextMiddleware:
         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 = {}
@@ -149,12 +185,67 @@ class PosthogContextMiddleware:
         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)
+        # type: (HttpRequest) -> Union[HttpResponse, Awaitable[HttpResponse]]
+        """
+        Unified entry point for both sync and async request handling.
 
-        with contexts.new_context(self.capture_exceptions):
+        When sync_capable and async_capable are both True, Django passes requests
+        without conversion. This method detects the mode and routes accordingly.
+        """
+        if self._is_coroutine:
+            return self.__acall__(request)
+        else:
+            # Synchronous path
+            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)
+
+    async def __acall__(self, request):
+        # type: (HttpRequest) -> Awaitable[HttpResponse]
+        """
+        Asynchronous entry point for async request handling.
+
+        This method is called when the middleware chain is async.
+        """
+        if self.request_filter and not self.request_filter(request):
+            return await 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)
+            return await self.get_response(request)
+
+    def process_exception(self, request, exception):
+        # type: (HttpRequest, Exception) -> None
+        """
+        Process exceptions from views and downstream middleware.
+
+        Django calls this WHILE still inside the context created by __call__,
+        so request tags have already been extracted and set. This method just
+        needs to capture the exception directly.
+
+        Django converts view exceptions into responses before they propagate through
+        the middleware stack, so the context manager in __call__/__acall__ never sees them.
+
+        Note: Django's process_exception is always synchronous, even for async views.
+        """
+        if self.request_filter and not self.request_filter(request):
+            return
+
+        if not self.capture_exceptions:
+            return
+
+        # Context and tags already set by __call__ or __acall__
+        # Just capture the exception
+        if self.client:
+            self.client.capture_exception(exception)
+        else:
+            from posthog import capture_exception
+
+            capture_exception(exception)

posthog/request.py

@@ -132,12 +132,16 @@ def flags(
 
 
 def remote_config(
-    personal_api_key: str, host: Optional[str] = None, key: str = "", timeout: int = 15
+    personal_api_key: str,
+    project_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/",
+        f"/api/projects/@current/feature_flags/{key}/remote_config?token={project_api_key}",
         host,
         timeout,
     )

posthog/test/ai/anthropic/test_anthropic.py

@@ -1,5 +1,4 @@
 import os
-import time
 from unittest.mock import patch
 
 import pytest
@@ -13,14 +12,95 @@ try:
 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"
 )
 
 
+# =======================
+# Reusable Mock Helpers
+# =======================
+
+
+class MockContent:
+    """Reusable mock content class for Anthropic responses."""
+
+    def __init__(self, text="Bar", content_type="text"):
+        self.type = content_type
+        self.text = text
+
+
+class MockUsage:
+    """Reusable mock usage class for Anthropic responses."""
+
+    def __init__(
+        self,
+        input_tokens=18,
+        output_tokens=1,
+        cache_read_input_tokens=0,
+        cache_creation_input_tokens=0,
+    ):
+        self.input_tokens = input_tokens
+        self.output_tokens = output_tokens
+        self.cache_read_input_tokens = cache_read_input_tokens
+        self.cache_creation_input_tokens = cache_creation_input_tokens
+
+
+class MockResponse:
+    """Reusable mock response class for Anthropic messages."""
+
+    def __init__(
+        self,
+        content_text="Bar",
+        model="claude-3-opus-20240229",
+        input_tokens=18,
+        output_tokens=1,
+        cache_read=0,
+        cache_creation=0,
+    ):
+        self.content = [MockContent(text=content_text)]
+        self.model = model
+        self.usage = MockUsage(
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cache_read_input_tokens=cache_read,
+            cache_creation_input_tokens=cache_creation,
+        )
+
+
+def create_mock_response(**kwargs):
+    """Factory function to create mock responses with custom parameters."""
+    return MockResponse(**kwargs)
+
+
+# Streaming mock helpers
+class MockStreamEvent:
+    """Reusable mock event class for streaming responses."""
+
+    def __init__(self, event_type=None, **kwargs):
+        self.type = event_type
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+
+class MockContentBlock:
+    """Reusable mock content block for streaming."""
+
+    def __init__(self, block_type, **kwargs):
+        self.type = block_type
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+
+class MockDelta:
+    """Reusable mock delta for streaming events."""
+
+    def __init__(self, **kwargs):
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+
 @pytest.fixture
 def mock_client():
     with patch("posthog.client.Client") as mock_client:
@@ -46,22 +126,77 @@ def mock_anthropic_response():
 
 
 @pytest.fixture
-def mock_anthropic_stream():
-    class MockStreamEvent:
-        def __init__(self, content, usage=None):
-            self.content = content
-            self.usage = usage
+def mock_anthropic_stream_with_tools():
+    """Mock stream events for tool calls."""
+
+    class MockMessage:
+        def __init__(self):
+            self.usage = MockUsage(
+                input_tokens=50,
+                cache_creation_input_tokens=0,
+                cache_read_input_tokens=5,
+            )
 
     def stream_generator():
-        yield MockStreamEvent("A")
-        yield MockStreamEvent("B")
-        yield MockStreamEvent(
-            "C",
-            usage=Usage(
-                input_tokens=20,
-                output_tokens=10,
-            ),
+        # Message start with usage
+        event = MockStreamEvent("message_start")
+        event.message = MockMessage()
+        yield event
+
+        # Text block start
+        event = MockStreamEvent("content_block_start")
+        event.content_block = MockContentBlock("text")
+        event.index = 0
+        yield event
+
+        # Text delta
+        event = MockStreamEvent("content_block_delta")
+        event.delta = MockDelta(text="I'll check the weather for you.")
+        event.index = 0
+        yield event
+
+        # Text block stop
+        event = MockStreamEvent("content_block_stop")
+        event.index = 0
+        yield event
+
+        # Tool use block start
+        event = MockStreamEvent("content_block_start")
+        event.content_block = MockContentBlock(
+            "tool_use", id="toolu_stream123", name="get_weather"
         )
+        event.index = 1
+        yield event
+
+        # Tool input delta 1
+        event = MockStreamEvent("content_block_delta")
+        event.delta = MockDelta(
+            type="input_json_delta", partial_json='{"location": "San'
+        )
+        event.index = 1
+        yield event
+
+        # Tool input delta 2
+        event = MockStreamEvent("content_block_delta")
+        event.delta = MockDelta(
+            type="input_json_delta", partial_json=' Francisco", "unit": "celsius"}'
+        )
+        event.index = 1
+        yield event
+
+        # Tool block stop
+        event = MockStreamEvent("content_block_stop")
+        event.index = 1
+        yield event
+
+        # Message delta with final usage
+        event = MockStreamEvent("message_delta")
+        event.usage = MockUsage(output_tokens=25)
+        yield event
+
+        # Message stop
+        event = MockStreamEvent("message_stop")
+        yield event
 
     return stream_generator()
 
@@ -88,6 +223,56 @@ def mock_anthropic_response_with_cached_tokens():
     )
 
 
+@pytest.fixture
+def mock_anthropic_response_with_tool_calls():
+    return Message(
+        id="msg_456",
+        type="message",
+        role="assistant",
+        content=[
+            {"type": "text", "text": "I'll help you check the weather."},
+            {"type": "text", "text": " Let me look that up."},
+            {
+                "type": "tool_use",
+                "id": "toolu_abc123",
+                "name": "get_weather",
+                "input": {"location": "San Francisco"},
+            },
+        ],
+        model="claude-3-5-sonnet-20241022",
+        usage=Usage(
+            input_tokens=25,
+            output_tokens=15,
+        ),
+        stop_reason="tool_use",
+        stop_sequence=None,
+    )
+
+
+@pytest.fixture
+def mock_anthropic_response_tool_calls_only():
+    return Message(
+        id="msg_789",
+        type="message",
+        role="assistant",
+        content=[
+            {
+                "type": "tool_use",
+                "id": "toolu_def456",
+                "name": "get_weather",
+                "input": {"location": "New York", "unit": "fahrenheit"},
+            }
+        ],
+        model="claude-3-5-sonnet-20241022",
+        usage=Usage(
+            input_tokens=30,
+            output_tokens=12,
+        ),
+        stop_reason="tool_use",
+        stop_sequence=None,
+    )
+
+
 def test_basic_completion(mock_client, mock_anthropic_response):
     with patch(
         "anthropic.resources.Messages.create", return_value=mock_anthropic_response
@@ -112,7 +297,10 @@ def test_basic_completion(mock_client, mock_anthropic_response):
         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"}
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": "Test response"}],
+            }
         ]
         assert props["$ai_input_tokens"] == 20
         assert props["$ai_output_tokens"] == 10
@@ -121,83 +309,6 @@ def test_basic_completion(mock_client, mock_anthropic_response):
         assert isinstance(props["$ai_latency"], float)
 
 
-def test_streaming(mock_client, 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",
-            messages=[{"role": "user", "content": "Hello"}],
-            stream=True,
-            posthog_distinct_id="test-id",
-            posthog_properties={"foo": "bar"},
-        )
-
-        # Consume the stream
-        chunks = list(response)
-        assert len(chunks) == 3
-        assert chunks[0].content == "A"
-        assert chunks[1].content == "B"
-        assert chunks[2].content == "C"
-
-        # Wait a bit to ensure the capture is called
-        time.sleep(0.1)
-        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": "ABC"}]
-        assert props["$ai_input_tokens"] == 20
-        assert props["$ai_output_tokens"] == 10
-        assert isinstance(props["$ai_latency"], float)
-        assert props["foo"] == "bar"
-
-
-def test_streaming_with_stream_endpoint(mock_client, 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",
-            messages=[{"role": "user", "content": "Hello"}],
-            posthog_distinct_id="test-id",
-            posthog_properties={"foo": "bar"},
-        )
-
-        # Consume the stream
-        chunks = list(response)
-        assert len(chunks) == 3
-        assert chunks[0].content == "A"
-        assert chunks[1].content == "B"
-        assert chunks[2].content == "C"
-
-        # Wait a bit to ensure the capture is called
-        time.sleep(0.1)
-        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": "ABC"}]
-        assert props["$ai_input_tokens"] == 20
-        assert props["$ai_output_tokens"] == 10
-        assert isinstance(props["$ai_latency"], float)
-        assert props["foo"] == "bar"
-
-
 def test_groups(mock_client, mock_anthropic_response):
     with patch(
         "anthropic.resources.Messages.create", return_value=mock_anthropic_response
@@ -260,18 +371,23 @@ def test_privacy_mode_global(mock_client, mock_anthropic_response):
         assert props["$ai_output_choices"] is None
 
 
-@pytest.mark.skipif(not ANTHROPIC_API_KEY, reason="ANTHROPIC_API_KEY is not set")
 def test_basic_integration(mock_client):
-    client = Anthropic(posthog_client=mock_client)
-    client.messages.create(
-        model="claude-3-opus-20240229",
-        messages=[{"role": "user", "content": "Foo"}],
-        max_tokens=1,
-        temperature=0,
-        posthog_distinct_id="test-id",
-        posthog_properties={"foo": "bar"},
-        system="You must always answer with 'Bar'.",
-    )
+    """Test basic non-streaming integration."""
+
+    with patch(
+        "anthropic.resources.Messages.create",
+        return_value=create_mock_response(),
+    ):
+        client = Anthropic(posthog_client=mock_client)
+        client.messages.create(
+            model="claude-3-opus-20240229",
+            messages=[{"role": "user", "content": "Foo"}],
+            max_tokens=1,
+            temperature=0,
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+            system="You must always answer with 'Bar'.",
+        )
 
     assert mock_client.capture.call_count == 1
 
@@ -286,7 +402,9 @@ def test_basic_integration(mock_client):
         {"role": "user", "content": "Foo"},
     ]
     assert props["$ai_output_choices"][0]["role"] == "assistant"
-    assert props["$ai_output_choices"][0]["content"] == "Bar"
+    assert props["$ai_output_choices"][0]["content"] == [
+        {"type": "text", "text": "Bar"}
+    ]
     assert props["$ai_input_tokens"] == 18
     assert props["$ai_output_tokens"] == 1
     assert props["$ai_http_status"] == 200
@@ -294,17 +412,28 @@ def test_basic_integration(mock_client):
     assert isinstance(props["$ai_latency"], float)
 
 
-@pytest.mark.skipif(not ANTHROPIC_API_KEY, reason="ANTHROPIC_API_KEY is not set")
 async def test_basic_async_integration(mock_client):
-    client = AsyncAnthropic(posthog_client=mock_client)
-    await client.messages.create(
-        model="claude-3-opus-20240229",
-        messages=[{"role": "user", "content": "You must always answer with 'Bar'."}],
-        max_tokens=1,
-        temperature=0,
-        posthog_distinct_id="test-id",
-        posthog_properties={"foo": "bar"},
-    )
+    """Test async non-streaming integration."""
+
+    # Make the mock async
+    async def mock_async_create(**kwargs):
+        return create_mock_response(input_tokens=16)
+
+    with patch(
+        "anthropic.resources.messages.AsyncMessages.create",
+        side_effect=mock_async_create,
+    ):
+        client = AsyncAnthropic(posthog_client=mock_client)
+        await client.messages.create(
+            model="claude-3-opus-20240229",
+            messages=[
+                {"role": "user", "content": "You must always answer with 'Bar'."}
+            ],
+            max_tokens=1,
+            temperature=0,
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+        )
 
     assert mock_client.capture.call_count == 1
 
@@ -326,52 +455,50 @@ async def test_basic_async_integration(mock_client):
     assert isinstance(props["$ai_latency"], float)
 
 
-def test_streaming_system_prompt(mock_client, mock_anthropic_stream):
+async def test_async_streaming_system_prompt(mock_client):
+    """Test async streaming with system prompt."""
+
+    # Create a simple mock async stream using reusable helpers
+    async def mock_async_stream():
+        # Yield some events
+        yield MockStreamEvent(type="message_start")
+        yield MockStreamEvent(type="content_block_start")
+        yield MockStreamEvent(type="content_block_delta", text="Bar")
+
+        # Final message with usage
+        final_msg = MockStreamEvent(type="message_delta")
+        final_msg.usage = MockUsage(
+            input_tokens=10,
+            output_tokens=5,
+            cache_read_input_tokens=0,
+            cache_creation_input_tokens=0,
+        )
+        yield final_msg
+
+    # Mock create to return a coroutine that yields the async generator
+    # This matches the actual behavior when stream=True with await
+    async def async_create_wrapper(**kwargs):
+        return mock_async_stream()
+
     with patch(
-        "anthropic.resources.Messages.create", return_value=mock_anthropic_stream
+        "anthropic.resources.messages.AsyncMessages.create",
+        side_effect=async_create_wrapper,
     ):
-        client = Anthropic(api_key="test-key", posthog_client=mock_client)
-        response = client.messages.create(
+        client = AsyncAnthropic(posthog_client=mock_client)
+        response = await client.messages.create(
             model="claude-3-opus-20240229",
-            system="Foo",
-            messages=[{"role": "user", "content": "Bar"}],
+            system="You must always answer with 'Bar'.",
+            messages=[{"role": "user", "content": "Foo"}],
             stream=True,
+            max_tokens=1,
         )
 
-        # Consume the stream
-        list(response)
+        # Consume the stream - async finally block completes before this returns
+        [c async for c in response]
 
-        # Wait a bit to ensure the capture is called
-        time.sleep(0.1)
+        # Capture happens in the async finally block before generator completes
         assert mock_client.capture.call_count == 1
 
-        call_args = mock_client.capture.call_args[1]
-        props = call_args["properties"]
-
-        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")
-async def test_async_streaming_system_prompt(mock_client, mock_anthropic_stream):
-    client = AsyncAnthropic(posthog_client=mock_client)
-    response = await client.messages.create(
-        model="claude-3-opus-20240229",
-        system="You must always answer with 'Bar'.",
-        messages=[{"role": "user", "content": "Foo"}],
-        stream=True,
-        max_tokens=1,
-    )
-
-    # Consume the stream
-    [c async for c in response]
-
-    # Wait a bit to ensure the capture is called
-    time.sleep(0.1)
-    assert mock_client.capture.call_count == 1
-
     call_args = mock_client.capture.call_args[1]
     props = call_args["properties"]
 
@@ -425,7 +552,10 @@ def test_cached_tokens(mock_client, mock_anthropic_response_with_cached_tokens):
         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"}
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": "Test response"}],
+            }
         ]
         assert props["$ai_input_tokens"] == 20
         assert props["$ai_output_tokens"] == 10
@@ -434,3 +564,473 @@ def test_cached_tokens(mock_client, mock_anthropic_response_with_cached_tokens):
         assert props["$ai_http_status"] == 200
         assert props["foo"] == "bar"
         assert isinstance(props["$ai_latency"], float)
+
+
+def test_tool_definition(mock_client, mock_anthropic_response):
+    with patch(
+        "anthropic.resources.Messages.create",
+        return_value=mock_anthropic_response,
+    ):
+        client = Anthropic(api_key="test-key", posthog_client=mock_client)
+
+        tools = [
+            {
+                "name": "get_weather",
+                "description": "Get the current weather for a specific location",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "location": {
+                            "type": "string",
+                            "description": "The city or location name to get weather for",
+                        }
+                    },
+                    "required": ["location"],
+                },
+            }
+        ]
+
+        response = client.messages.create(
+            model="claude-3-5-sonnet-20241022",
+            max_tokens=200,
+            temperature=0.7,
+            tools=tools,
+            messages=[{"role": "user", "content": "hey"}],
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+        )
+
+        assert response == mock_anthropic_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"] == "anthropic"
+        assert props["$ai_model"] == "claude-3-5-sonnet-20241022"
+        assert props["$ai_input"] == [{"role": "user", "content": "hey"}]
+        assert props["$ai_output_choices"] == [
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": "Test response"}],
+            }
+        ]
+        assert props["$ai_input_tokens"] == 20
+        assert props["$ai_output_tokens"] == 10
+        assert props["$ai_http_status"] == 200
+        assert props["foo"] == "bar"
+        assert isinstance(props["$ai_latency"], float)
+        # Verify that tools are captured in the $ai_tools property
+        assert props["$ai_tools"] == tools
+
+
+def test_tool_calls_in_output_choices(
+    mock_client, mock_anthropic_response_with_tool_calls
+):
+    with patch(
+        "anthropic.resources.Messages.create",
+        return_value=mock_anthropic_response_with_tool_calls,
+    ):
+        client = Anthropic(api_key="test-key", posthog_client=mock_client)
+        response = client.messages.create(
+            model="claude-3-5-sonnet-20241022",
+            max_tokens=200,
+            messages=[
+                {"role": "user", "content": "What's the weather in San Francisco?"}
+            ],
+            tools=[
+                {
+                    "name": "get_weather",
+                    "description": "Get weather",
+                    "input_schema": {
+                        "type": "object",
+                        "properties": {"location": {"type": "string"}},
+                        "required": ["location"],
+                    },
+                }
+            ],
+            posthog_distinct_id="test-id",
+        )
+
+        assert response == mock_anthropic_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"] == "anthropic"
+        assert props["$ai_model"] == "claude-3-5-sonnet-20241022"
+        assert props["$ai_output_choices"] == [
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "I'll help you check the weather."},
+                    {"type": "text", "text": " Let me look that up."},
+                    {
+                        "type": "function",
+                        "id": "toolu_abc123",
+                        "function": {
+                            "name": "get_weather",
+                            "arguments": {"location": "San Francisco"},
+                        },
+                    },
+                ],
+            }
+        ]
+
+        # Check token usage
+        assert props["$ai_input_tokens"] == 25
+        assert props["$ai_output_tokens"] == 15
+        assert props["$ai_http_status"] == 200
+
+
+def test_tool_calls_only_no_content(
+    mock_client, mock_anthropic_response_tool_calls_only
+):
+    with patch(
+        "anthropic.resources.Messages.create",
+        return_value=mock_anthropic_response_tool_calls_only,
+    ):
+        client = Anthropic(api_key="test-key", posthog_client=mock_client)
+        response = client.messages.create(
+            model="claude-3-5-sonnet-20241022",
+            max_tokens=200,
+            messages=[{"role": "user", "content": "Get weather for New York"}],
+            tools=[
+                {
+                    "name": "get_weather",
+                    "description": "Get weather",
+                    "input_schema": {
+                        "type": "object",
+                        "properties": {
+                            "location": {"type": "string"},
+                            "unit": {"type": "string"},
+                        },
+                        "required": ["location"],
+                    },
+                }
+            ],
+            posthog_distinct_id="test-id",
+        )
+
+        assert response == mock_anthropic_response_tool_calls_only
+        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-5-sonnet-20241022"
+        assert props["$ai_output_choices"] == [
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "function",
+                        "id": "toolu_def456",
+                        "function": {
+                            "name": "get_weather",
+                            "arguments": {"location": "New York", "unit": "fahrenheit"},
+                        },
+                    }
+                ],
+            }
+        ]
+
+        # Check token usage
+        assert props["$ai_input_tokens"] == 30
+        assert props["$ai_output_tokens"] == 12
+        assert props["$ai_http_status"] == 200
+
+
+def test_async_tool_calls_in_output_choices(
+    mock_client, mock_anthropic_response_with_tool_calls
+):
+    import asyncio
+
+    async def mock_async_create(**kwargs):
+        return mock_anthropic_response_with_tool_calls
+
+    with patch(
+        "anthropic.resources.AsyncMessages.create",
+        side_effect=mock_async_create,
+    ):
+        async_client = AsyncAnthropic(api_key="test-key", posthog_client=mock_client)
+
+        async def run_test():
+            return await async_client.messages.create(
+                model="claude-3-5-sonnet-20241022",
+                max_tokens=200,
+                messages=[
+                    {"role": "user", "content": "What's the weather in San Francisco?"}
+                ],
+                tools=[
+                    {
+                        "name": "get_weather",
+                        "description": "Get weather",
+                        "input_schema": {
+                            "type": "object",
+                            "properties": {"location": {"type": "string"}},
+                            "required": ["location"],
+                        },
+                    }
+                ],
+                posthog_distinct_id="test-id",
+            )
+
+        response = asyncio.run(run_test())
+
+        assert response == mock_anthropic_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"] == "anthropic"
+        assert props["$ai_model"] == "claude-3-5-sonnet-20241022"
+        assert props["$ai_output_choices"] == [
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "I'll help you check the weather."},
+                    {"type": "text", "text": " Let me look that up."},
+                    {
+                        "type": "function",
+                        "id": "toolu_abc123",
+                        "function": {
+                            "name": "get_weather",
+                            "arguments": {"location": "San Francisco"},
+                        },
+                    },
+                ],
+            }
+        ]
+
+        # Check token usage
+        assert props["$ai_input_tokens"] == 25
+        assert props["$ai_output_tokens"] == 15
+        assert props["$ai_http_status"] == 200
+
+
+def test_streaming_with_tool_calls(mock_client, mock_anthropic_stream_with_tools):
+    """Test that tool calls are properly captured in streaming mode."""
+    with patch(
+        "anthropic.resources.Messages.create",
+        return_value=mock_anthropic_stream_with_tools,
+    ):
+        client = Anthropic(api_key="test-key", posthog_client=mock_client)
+        response = client.messages.create(
+            model="claude-3-5-sonnet-20241022",
+            system="You are a helpful weather assistant.",
+            messages=[
+                {"role": "user", "content": "What's the weather in San Francisco?"}
+            ],
+            tools=[
+                {
+                    "name": "get_weather",
+                    "description": "Get weather information",
+                    "input_schema": {
+                        "type": "object",
+                        "properties": {
+                            "location": {"type": "string"},
+                            "unit": {"type": "string"},
+                        },
+                        "required": ["location"],
+                    },
+                }
+            ],
+            stream=True,
+            posthog_distinct_id="test-id",
+        )
+
+        # Consume the stream - this triggers the finally block synchronously
+        list(response)
+
+        # Capture happens synchronously when generator is exhausted
+        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-5-sonnet-20241022"
+
+        # Verify system prompt is included in input
+        assert props["$ai_input"] == [
+            {"role": "system", "content": "You are a helpful weather assistant."},
+            {"role": "user", "content": "What's the weather in San Francisco?"},
+        ]
+
+        # Verify that tools are captured in the properties
+        assert props["$ai_tools"] == [
+            {
+                "name": "get_weather",
+                "description": "Get weather information",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string"},
+                        "unit": {"type": "string"},
+                    },
+                    "required": ["location"],
+                },
+            }
+        ]
+
+        # Verify output contains both text and tool call
+        output_choices = props["$ai_output_choices"]
+        assert len(output_choices) == 1
+
+        assistant_message = output_choices[0]
+        assert assistant_message["role"] == "assistant"
+
+        content = assistant_message["content"]
+        assert isinstance(content, list)
+        assert len(content) == 2
+
+        # Verify text block
+        text_block = content[0]
+        assert text_block["type"] == "text"
+        assert text_block["text"] == "I'll check the weather for you."
+
+        # Verify tool call block
+        tool_block = content[1]
+        assert tool_block["type"] == "function"
+        assert tool_block["id"] == "toolu_stream123"
+        assert tool_block["function"]["name"] == "get_weather"
+        assert tool_block["function"]["arguments"] == {
+            "location": "San Francisco",
+            "unit": "celsius",
+        }
+
+        # Check token usage
+        assert props["$ai_input_tokens"] == 50
+        assert props["$ai_output_tokens"] == 25
+        assert props["$ai_cache_read_input_tokens"] == 5
+        assert props["$ai_cache_creation_input_tokens"] == 0
+
+
+def test_async_streaming_with_tool_calls(mock_client, mock_anthropic_stream_with_tools):
+    """Test that tool calls are properly captured in async streaming mode."""
+    import asyncio
+
+    async def mock_async_generator():
+        # Convert regular generator to async generator
+        for event in mock_anthropic_stream_with_tools:
+            yield event
+
+    async def mock_async_create(**kwargs):
+        # Return the async generator (to be awaited by the implementation)
+        return mock_async_generator()
+
+    with patch(
+        "anthropic.resources.AsyncMessages.create",
+        side_effect=mock_async_create,
+    ):
+        async_client = AsyncAnthropic(api_key="test-key", posthog_client=mock_client)
+
+        async def run_test():
+            response = await async_client.messages.create(
+                model="claude-3-5-sonnet-20241022",
+                system="You are a helpful weather assistant.",
+                messages=[
+                    {"role": "user", "content": "What's the weather in San Francisco?"}
+                ],
+                tools=[
+                    {
+                        "name": "get_weather",
+                        "description": "Get weather information",
+                        "input_schema": {
+                            "type": "object",
+                            "properties": {
+                                "location": {"type": "string"},
+                                "unit": {"type": "string"},
+                            },
+                            "required": ["location"],
+                        },
+                    }
+                ],
+                stream=True,
+                posthog_distinct_id="test-id",
+            )
+
+            # Consume the async stream
+            [event async for event in response]
+
+        # asyncio.run() waits for all async operations to complete
+        asyncio.run(run_test())
+
+        # Capture completes before asyncio.run() returns
+        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-5-sonnet-20241022"
+
+        # Verify system prompt is included in input
+        assert props["$ai_input"] == [
+            {"role": "system", "content": "You are a helpful weather assistant."},
+            {"role": "user", "content": "What's the weather in San Francisco?"},
+        ]
+
+        # Verify that tools are captured in the properties
+        assert props["$ai_tools"] == [
+            {
+                "name": "get_weather",
+                "description": "Get weather information",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string"},
+                        "unit": {"type": "string"},
+                    },
+                    "required": ["location"],
+                },
+            }
+        ]
+
+        # Verify output contains both text and tool call
+        output_choices = props["$ai_output_choices"]
+        assert len(output_choices) == 1
+
+        assistant_message = output_choices[0]
+        assert assistant_message["role"] == "assistant"
+
+        content = assistant_message["content"]
+        assert isinstance(content, list)
+        assert len(content) == 2
+
+        # Verify text block
+        text_block = content[0]
+        assert text_block["type"] == "text"
+        assert text_block["text"] == "I'll check the weather for you."
+
+        # Verify tool call block
+        tool_block = content[1]
+        assert tool_block["type"] == "function"
+        assert tool_block["id"] == "toolu_stream123"
+        assert tool_block["function"]["name"] == "get_weather"
+        assert tool_block["function"]["arguments"] == {
+            "location": "San Francisco",
+            "unit": "celsius",
+        }
+
+        # Check token usage
+        assert props["$ai_input_tokens"] == 50
+        assert props["$ai_output_tokens"] == 25
+        assert props["$ai_cache_read_input_tokens"] == 5
+        assert props["$ai_cache_creation_input_tokens"] == 0

posthog/test/ai/gemini/test_gemini.py

@@ -31,6 +31,9 @@ def mock_gemini_response():
     mock_usage = MagicMock()
     mock_usage.prompt_token_count = 20
     mock_usage.candidates_token_count = 10
+    # Ensure cache and reasoning tokens are not present (not MagicMock)
+    mock_usage.cached_content_token_count = 0
+    mock_usage.thoughts_token_count = 0
     mock_response.usage_metadata = mock_usage
 
     mock_candidate = MagicMock()
@@ -56,6 +59,91 @@ def mock_google_genai_client():
         yield mock_client_instance
 
 
+@pytest.fixture
+def mock_gemini_response_with_function_calls():
+    mock_response = MagicMock()
+
+    # Mock usage metadata
+    mock_usage = MagicMock()
+    mock_usage.prompt_token_count = 25
+    mock_usage.candidates_token_count = 15
+    mock_usage.cached_content_token_count = 0
+    mock_usage.thoughts_token_count = 0
+    mock_response.usage_metadata = mock_usage
+
+    # Mock function call
+    mock_function_call = MagicMock()
+    mock_function_call.name = "get_current_weather"
+    mock_function_call.args = {"location": "San Francisco"}
+
+    # Mock text part 1
+    mock_text_part1 = MagicMock()
+    mock_text_part1.text = "I'll check the weather for you."
+    # Make hasattr(part, "text") return True
+    type(mock_text_part1).text = mock_text_part1.text
+
+    # Mock text part 2
+    mock_text_part2 = MagicMock()
+    mock_text_part2.text = " Let me look that up."
+    type(mock_text_part2).text = mock_text_part2.text
+
+    # Mock function call part - need to ensure hasattr() works correctly
+    mock_function_part = MagicMock()
+    mock_function_part.function_call = mock_function_call
+    # Make hasattr(part, "function_call") return True
+    type(mock_function_part).function_call = mock_function_part.function_call
+    # Ensure hasattr(part, "text") returns False for the function part
+    del mock_function_part.text
+
+    # Mock content with 2 text parts and 1 function call part
+    mock_content = MagicMock()
+    mock_content.parts = [mock_text_part1, mock_text_part2, mock_function_part]
+
+    # Mock candidate
+    mock_candidate = MagicMock()
+    mock_candidate.content = mock_content
+    mock_response.candidates = [mock_candidate]
+
+    return mock_response
+
+
+@pytest.fixture
+def mock_gemini_response_function_calls_only():
+    mock_response = MagicMock()
+
+    # Mock usage metadata
+    mock_usage = MagicMock()
+    mock_usage.prompt_token_count = 30
+    mock_usage.candidates_token_count = 12
+    mock_usage.cached_content_token_count = 0
+    mock_usage.thoughts_token_count = 0
+    mock_response.usage_metadata = mock_usage
+
+    # Mock function call
+    mock_function_call = MagicMock()
+    mock_function_call.name = "get_current_weather"
+    mock_function_call.args = {"location": "New York", "unit": "fahrenheit"}
+
+    # Mock function call part (no text part) - need to ensure hasattr() works correctly
+    mock_function_part = MagicMock()
+    mock_function_part.function_call = mock_function_call
+    # Make hasattr(part, "function_call") return True
+    type(mock_function_part).function_call = mock_function_part.function_call
+    # Ensure hasattr(part, "text") returns False for the function part
+    del mock_function_part.text
+
+    # Mock content with only function call part
+    mock_content = MagicMock()
+    mock_content.parts = [mock_function_part]
+
+    # Mock candidate
+    mock_candidate = MagicMock()
+    mock_candidate.content = mock_content
+    mock_response.candidates = [mock_candidate]
+
+    return mock_response
+
+
 def test_new_client_basic_generation(
     mock_client, mock_google_genai_client, mock_gemini_response
 ):
@@ -99,6 +187,8 @@ def test_new_client_streaming_with_generate_content_stream(
         mock_usage1 = MagicMock()
         mock_usage1.prompt_token_count = 10
         mock_usage1.candidates_token_count = 5
+        mock_usage1.cached_content_token_count = 0
+        mock_usage1.thoughts_token_count = 0
         mock_chunk1.usage_metadata = mock_usage1
 
         mock_chunk2 = MagicMock()
@@ -106,6 +196,8 @@ def test_new_client_streaming_with_generate_content_stream(
         mock_usage2 = MagicMock()
         mock_usage2.prompt_token_count = 10
         mock_usage2.candidates_token_count = 10
+        mock_usage2.cached_content_token_count = 0
+        mock_usage2.thoughts_token_count = 0
         mock_chunk2.usage_metadata = mock_usage2
 
         yield mock_chunk1
@@ -145,6 +237,91 @@ def test_new_client_streaming_with_generate_content_stream(
     assert isinstance(props["$ai_latency"], float)
 
 
+def test_new_client_streaming_with_tools(mock_client, mock_google_genai_client):
+    """Test that tools are captured in streaming mode"""
+
+    def mock_streaming_response():
+        mock_chunk1 = MagicMock()
+        mock_chunk1.text = "I'll check "
+        mock_usage1 = MagicMock()
+        mock_usage1.prompt_token_count = 15
+        mock_usage1.candidates_token_count = 5
+        mock_usage1.cached_content_token_count = 0
+        mock_usage1.thoughts_token_count = 0
+        mock_chunk1.usage_metadata = mock_usage1
+
+        mock_chunk2 = MagicMock()
+        mock_chunk2.text = "the weather"
+        mock_usage2 = MagicMock()
+        mock_usage2.prompt_token_count = 15
+        mock_usage2.candidates_token_count = 10
+        mock_usage2.cached_content_token_count = 0
+        mock_usage2.thoughts_token_count = 0
+        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)
+
+    # Create mock tools configuration
+    mock_tool = MagicMock()
+    mock_tool.function_declarations = [
+        MagicMock(
+            name="get_current_weather",
+            description="Gets the current weather for a given location.",
+            parameters=MagicMock(
+                type="OBJECT",
+                properties={
+                    "location": MagicMock(
+                        type="STRING",
+                        description="The city and state, e.g. San Francisco, CA",
+                    )
+                },
+                required=["location"],
+            ),
+        )
+    ]
+
+    mock_config = MagicMock()
+    mock_config.tools = [mock_tool]
+
+    response = client.models.generate_content_stream(
+        model="gemini-2.0-flash",
+        contents=["What's the weather in SF?"],
+        config=mock_config,
+        posthog_distinct_id="test-id",
+        posthog_properties={"feature": "streaming_with_tools"},
+    )
+
+    chunks = list(response)
+    assert len(chunks) == 2
+    assert chunks[0].text == "I'll check "
+    assert chunks[1].text == "the weather"
+
+    # Check that the streaming event was captured with tools
+    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"] == 15
+    assert props["$ai_output_tokens"] == 10
+    assert props["feature"] == "streaming_with_tools"
+    assert isinstance(props["$ai_latency"], float)
+
+    # Verify that tools are captured in the $ai_tools property in streaming mode
+    assert props["$ai_tools"] == [mock_tool]
+
+
 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
@@ -221,12 +398,32 @@ def test_new_client_different_input_formats(
     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"
+    # Test Gemini-specific format with parts array (like in the screenshot)
+    mock_client.reset_mock()
     client.models.generate_content(
-        model="gemini-2.0-flash", contents=[mock_part], posthog_distinct_id="test-id"
+        model="gemini-2.0-flash",
+        contents=[{"role": "user", "parts": [{"text": "hey"}]}],
+        posthog_distinct_id="test-id",
+    )
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+    assert props["$ai_input"] == [{"role": "user", "content": "hey"}]
+
+    # Test multiple parts in the parts array
+    mock_client.reset_mock()
+    client.models.generate_content(
+        model="gemini-2.0-flash",
+        contents=[{"role": "user", "parts": [{"text": "Hello "}, {"text": "world"}]}],
+        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 world"}]
+
+    # Test list input with string
+    mock_client.capture.reset_mock()
+    client.models.generate_content(
+        model="gemini-2.0-flash", contents=["List item"], posthog_distinct_id="test-id"
     )
     call_args = mock_client.capture.call_args[1]
     props = call_args["properties"]
@@ -318,3 +515,325 @@ def test_new_client_override_defaults(
     assert props["team"] == "ai"  # from defaults
     assert props["feature"] == "chat"  # from call
     assert props["urgent"] is True  # from call
+
+
+def test_vertex_ai_parameters_passed_through(
+    mock_client, mock_google_genai_client, mock_gemini_response
+):
+    """Test that Vertex AI parameters are properly passed to genai.Client"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    # Mock credentials object
+    mock_credentials = MagicMock()
+    mock_debug_config = MagicMock()
+    mock_http_options = MagicMock()
+
+    # Create client with Vertex AI parameters
+    Client(
+        vertexai=True,
+        credentials=mock_credentials,
+        project="test-project",
+        location="us-central1",
+        debug_config=mock_debug_config,
+        http_options=mock_http_options,
+        posthog_client=mock_client,
+    )
+
+    # Verify genai.Client was called with correct parameters
+    google_genai.Client.assert_called_once_with(
+        vertexai=True,
+        credentials=mock_credentials,
+        project="test-project",
+        location="us-central1",
+        debug_config=mock_debug_config,
+        http_options=mock_http_options,
+    )
+
+
+def test_api_key_mode(mock_client, mock_google_genai_client):
+    """Test API key authentication mode"""
+
+    # Create client with just API key (traditional mode)
+    Client(
+        api_key="test-api-key",
+        posthog_client=mock_client,
+    )
+
+    # Verify genai.Client was called with only api_key
+    google_genai.Client.assert_called_once_with(api_key="test-api-key")
+
+
+def test_vertex_ai_mode_with_optional_api_key(
+    mock_client, mock_google_genai_client, mock_gemini_response
+):
+    """Test Vertex AI mode with optional API key"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    mock_credentials = MagicMock()
+
+    # Create client with Vertex AI + API key
+    Client(
+        vertexai=True,
+        api_key="test-api-key",
+        credentials=mock_credentials,
+        project="test-project",
+        posthog_client=mock_client,
+    )
+
+    # Verify genai.Client was called with both Vertex AI params and API key
+    google_genai.Client.assert_called_once_with(
+        vertexai=True,
+        api_key="test-api-key",
+        credentials=mock_credentials,
+        project="test-project",
+    )
+
+
+def test_tool_use_response(mock_client, mock_google_genai_client, mock_gemini_response):
+    """Test that tools defined in config are captured in $ai_tools property"""
+    mock_google_genai_client.models.generate_content.return_value = mock_gemini_response
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    # Create mock tools configuration
+    mock_tool = MagicMock()
+    mock_tool.function_declarations = [
+        MagicMock(
+            name="get_current_weather",
+            description="Gets the current weather for a given location.",
+            parameters=MagicMock(
+                type="OBJECT",
+                properties={
+                    "location": MagicMock(
+                        type="STRING",
+                        description="The city and state, e.g. San Francisco, CA",
+                    )
+                },
+                required=["location"],
+            ),
+        )
+    ]
+
+    mock_config = MagicMock()
+    mock_config.tools = [mock_tool]
+    # Explicitly specify this config doesn't have system_instruction
+    del mock_config.system_instruction
+
+    response = client.models.generate_content(
+        model="gemini-2.5-flash",
+        contents=["hey"],
+        config=mock_config,
+        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.5-flash"
+    assert props["$ai_input"] == [{"role": "user", "content": "hey"}]
+    assert props["$ai_output_choices"] == [
+        {
+            "role": "assistant",
+            "content": [{"type": "text", "text": "Test response from Gemini"}],
+        }
+    ]
+    assert props["$ai_input_tokens"] == 20
+    assert props["$ai_output_tokens"] == 10
+    assert props["$ai_http_status"] == 200
+    assert props["foo"] == "bar"
+    assert isinstance(props["$ai_latency"], float)
+    # Verify that tools are captured in the $ai_tools property
+    assert props["$ai_tools"] == [mock_tool]
+
+
+def test_function_calls_in_output_choices(
+    mock_client, mock_google_genai_client, mock_gemini_response_with_function_calls
+):
+    """Test that function calls are properly included in $ai_output_choices"""
+    mock_google_genai_client.models.generate_content.return_value = (
+        mock_gemini_response_with_function_calls
+    )
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    response = client.models.generate_content(
+        model="gemini-2.5-flash",
+        contents=["What's the weather in San Francisco?"],
+        posthog_distinct_id="test-id",
+    )
+
+    assert response == mock_gemini_response_with_function_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"] == "gemini"
+    assert props["$ai_model"] == "gemini-2.5-flash"
+    assert props["$ai_output_choices"] == [
+        {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": "I'll check the weather for you."},
+                {"type": "text", "text": " Let me look that up."},
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "get_current_weather",
+                        "arguments": {"location": "San Francisco"},
+                    },
+                },
+            ],
+        }
+    ]
+
+    # Check token usage
+    assert props["$ai_input_tokens"] == 25
+    assert props["$ai_output_tokens"] == 15
+    assert props["$ai_http_status"] == 200
+
+
+def test_function_calls_only_no_content(
+    mock_client, mock_google_genai_client, mock_gemini_response_function_calls_only
+):
+    """Test function calls without text content in $ai_output_choices"""
+    mock_google_genai_client.models.generate_content.return_value = (
+        mock_gemini_response_function_calls_only
+    )
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    response = client.models.generate_content(
+        model="gemini-2.5-flash",
+        contents=["Get weather for New York"],
+        posthog_distinct_id="test-id",
+    )
+
+    assert response == mock_gemini_response_function_calls_only
+    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.5-flash"
+    assert props["$ai_output_choices"] == [
+        {
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "get_current_weather",
+                        "arguments": {"location": "New York", "unit": "fahrenheit"},
+                    },
+                }
+            ],
+        }
+    ]
+
+    # Check token usage
+    assert props["$ai_input_tokens"] == 30
+    assert props["$ai_output_tokens"] == 12
+    assert props["$ai_http_status"] == 200
+
+
+def test_cache_and_reasoning_tokens(mock_client, mock_google_genai_client):
+    """Test that cache and reasoning tokens are properly extracted"""
+    # Create a mock response with cache and reasoning tokens
+    mock_response = MagicMock()
+    mock_response.text = "Test response with cache"
+
+    mock_usage = MagicMock()
+    mock_usage.prompt_token_count = 100
+    mock_usage.candidates_token_count = 50
+    mock_usage.cached_content_token_count = 30  # Cache tokens
+    mock_usage.thoughts_token_count = 10  # Reasoning tokens
+    mock_response.usage_metadata = mock_usage
+
+    # Mock candidates
+    mock_candidate = MagicMock()
+    mock_candidate.text = "Test response with cache"
+    mock_response.candidates = [mock_candidate]
+
+    mock_google_genai_client.models.generate_content.return_value = mock_response
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    response = client.models.generate_content(
+        model="gemini-2.5-pro",
+        contents="Test with cache",
+        posthog_distinct_id="test-id",
+    )
+
+    assert response == mock_response
+    assert mock_client.capture.call_count == 1
+
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+
+    # Check that all token types are present
+    assert props["$ai_input_tokens"] == 100
+    assert props["$ai_output_tokens"] == 50
+    assert props["$ai_cache_read_input_tokens"] == 30
+    assert props["$ai_reasoning_tokens"] == 10
+
+
+def test_streaming_cache_and_reasoning_tokens(mock_client, mock_google_genai_client):
+    """Test that cache and reasoning tokens are properly extracted in streaming"""
+    # Create mock chunks with cache and reasoning tokens
+    chunk1 = MagicMock()
+    chunk1.text = "Hello "
+    chunk1_usage = MagicMock()
+    chunk1_usage.prompt_token_count = 100
+    chunk1_usage.candidates_token_count = 5
+    chunk1_usage.cached_content_token_count = 30  # Cache tokens
+    chunk1_usage.thoughts_token_count = 0
+    chunk1.usage_metadata = chunk1_usage
+
+    chunk2 = MagicMock()
+    chunk2.text = "world!"
+    chunk2_usage = MagicMock()
+    chunk2_usage.prompt_token_count = 100
+    chunk2_usage.candidates_token_count = 10
+    chunk2_usage.cached_content_token_count = 30  # Same cache tokens
+    chunk2_usage.thoughts_token_count = 5  # Reasoning tokens
+    chunk2.usage_metadata = chunk2_usage
+
+    mock_stream = iter([chunk1, chunk2])
+    mock_google_genai_client.models.generate_content_stream.return_value = mock_stream
+
+    client = Client(api_key="test-key", posthog_client=mock_client)
+
+    response = client.models.generate_content_stream(
+        model="gemini-2.5-pro",
+        contents="Test streaming with cache",
+        posthog_distinct_id="test-id",
+    )
+
+    # Consume the stream
+    result = list(response)
+    assert len(result) == 2
+
+    # Check PostHog capture was called
+    assert mock_client.capture.call_count == 1
+
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+
+    # Check that all token types are present (should use final chunk's usage)
+    assert props["$ai_input_tokens"] == 100
+    assert props["$ai_output_tokens"] == 10
+    assert props["$ai_cache_read_input_tokens"] == 30
+    assert props["$ai_reasoning_tokens"] == 5

posthog/test/ai/langchain/test_callbacks.py

@@ -5,7 +5,7 @@ import os
 import time
 import uuid
 from typing import List, Literal, Optional, TypedDict, Union
-from unittest.mock import patch
+from unittest.mock import patch, MagicMock
 
 import pytest
 
@@ -204,6 +204,7 @@ def test_basic_chat_chain(mock_client, stream):
     # Generation is second
     assert generation_args["event"] == "$ai_generation"
     assert "distinct_id" in generation_args
+    assert generation_props["$ai_framework"] == "langchain"
     assert "$ai_model" in generation_props
     assert "$ai_provider" in generation_props
     assert generation_props["$ai_input"] == [
@@ -1564,9 +1565,9 @@ def test_anthropic_cache_write_and_read_tokens(mock_client):
             AIMessage(
                 content="Using cached analysis to provide quick response.",
                 usage_metadata={
-                    "input_tokens": 200,
+                    "input_tokens": 1200,
                     "output_tokens": 30,
-                    "total_tokens": 1030,
+                    "total_tokens": 1230,
                     "cache_read_input_tokens": 800,  # Anthropic cache read
                 },
             )
@@ -1583,7 +1584,7 @@ def test_anthropic_cache_write_and_read_tokens(mock_client):
     generation_props = generation_args["properties"]
 
     assert generation_args["event"] == "$ai_generation"
-    assert generation_props["$ai_input_tokens"] == 200
+    assert generation_props["$ai_input_tokens"] == 400
     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
@@ -1625,7 +1626,7 @@ def test_openai_cache_read_tokens(mock_client):
     generation_props = generation_args["properties"]
 
     assert generation_args["event"] == "$ai_generation"
-    assert generation_props["$ai_input_tokens"] == 150
+    assert generation_props["$ai_input_tokens"] == 50
     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
@@ -1707,7 +1708,7 @@ def test_combined_reasoning_and_cache_tokens(mock_client):
     generation_props = generation_args["properties"]
 
     assert generation_args["event"] == "$ai_generation"
-    assert generation_props["$ai_input_tokens"] == 500
+    assert generation_props["$ai_input_tokens"] == 200
     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
@@ -1727,3 +1728,401 @@ def test_openai_reasoning_tokens(mock_client):
     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
+
+
+def test_convert_message_to_dict_tool_calls():
+    """Test that _convert_message_to_dict properly converts tool calls in AIMessage."""
+    from posthog.ai.langchain.callbacks import _convert_message_to_dict
+    from langchain_core.messages import AIMessage
+    from langchain_core.messages.tool import ToolCall
+
+    # Create an AIMessage with tool calls
+    tool_calls = [
+        ToolCall(
+            id="call_123",
+            name="get_weather",
+            args={"city": "San Francisco", "units": "celsius"},
+        )
+    ]
+
+    ai_message = AIMessage(
+        content="I'll check the weather for you.", tool_calls=tool_calls
+    )
+
+    # Convert to dict
+    result = _convert_message_to_dict(ai_message)
+
+    # Verify the conversion
+    assert result["role"] == "assistant"
+    assert result["content"] == "I'll check the weather for you."
+    assert result["tool_calls"] == [
+        {
+            "type": "function",
+            "id": "call_123",
+            "function": {
+                "name": "get_weather",
+                "arguments": '{"city": "San Francisco", "units": "celsius"}',
+            },
+        }
+    ]
+
+
+def test_tool_definition(mock_client):
+    """Test that tools defined in invocation parameters are captured in $ai_tools property"""
+    callbacks = CallbackHandler(mock_client)
+    run_id = uuid.uuid4()
+
+    # Define tools to be passed to the invocation parameters
+    tools = [
+        {
+            "type": "function",
+            "function": {
+                "name": "get_weather",
+                "description": "Get the current weather for a specific location",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "location": {
+                            "type": "string",
+                            "description": "The city or location name to get weather for",
+                        }
+                    },
+                    "required": ["location"],
+                },
+            },
+        }
+    ]
+
+    with patch("time.time", return_value=1234567890):
+        callbacks._set_llm_metadata(
+            {"kwargs": {"openai_api_base": "https://api.openai.com/v1"}},
+            run_id,
+            messages=[{"role": "user", "content": "hey"}],
+            invocation_params={"temperature": 0.7, "tools": tools},
+            metadata={"ls_model_name": "gpt-4o-mini", "ls_provider": "openai"},
+            name="test",
+        )
+
+    expected = GenerationMetadata(
+        model="gpt-4o-mini",
+        input=[{"role": "user", "content": "hey"}],
+        start_time=1234567890,
+        model_params={"temperature": 0.7},
+        provider="openai",
+        base_url="https://api.openai.com/v1",
+        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 == {}
+
+    # Now test that the tools are properly captured in the PostHog event
+    mock_response = MagicMock()
+    mock_response.generations = [[MagicMock()]]
+
+    callbacks._capture_generation(
+        trace_id=run_id,
+        run_id=run_id,
+        run=run,
+        output=mock_response,
+        parent_run_id=None,
+    )
+
+    assert mock_client.capture.call_count == 1
+    call_args = mock_client.capture.call_args[1]
+    props = call_args["properties"]
+
+    assert call_args["distinct_id"] == run_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": "hey"}]
+    assert props["$ai_model_parameters"] == {"temperature": 0.7}
+    assert props["$ai_base_url"] == "https://api.openai.com/v1"
+    assert props["$ai_span_name"] == "test"
+    assert props["$ai_span_id"] == run_id
+    assert props["$ai_trace_id"] == run_id
+    assert props["$ai_latency"] == 1.0
+    # Verify that tools are captured in the $ai_tools property
+    assert props["$ai_tools"] == tools
+
+
+def test_cache_read_tokens_subtraction_from_input_tokens(mock_client):
+    """Test that cache_read_tokens are properly subtracted from input_tokens.
+
+    This tests the logic in callbacks.py lines 757-758:
+        if normalized_usage.input_tokens and normalized_usage.cache_read_tokens:
+            normalized_usage.input_tokens = max(normalized_usage.input_tokens - normalized_usage.cache_read_tokens, 0)
+    """
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Use the cached prompt for this request")]
+    )
+
+    # Scenario 1: input_tokens includes cache_read_tokens (typical case)
+    # input_tokens=150 includes 100 cache_read tokens, so actual input is 50
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Response using cached prompt context.",
+                usage_metadata={
+                    "input_tokens": 150,  # Total includes cache reads
+                    "output_tokens": 40,
+                    "total_tokens": 190,
+                    "cache_read_input_tokens": 100,  # 100 tokens read from cache
+                },
+            )
+        ]
+    )
+
+    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"
+    # Input tokens should be reduced: 150 - 100 = 50
+    assert generation_props["$ai_input_tokens"] == 50
+    assert generation_props["$ai_output_tokens"] == 40
+    assert generation_props["$ai_cache_read_input_tokens"] == 100
+
+
+def test_cache_read_tokens_subtraction_prevents_negative(mock_client):
+    """Test that cache_read_tokens subtraction doesn't result in negative input_tokens.
+
+    This tests the max(..., 0) part of the logic in callbacks.py lines 757-758.
+    """
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Edge case with large cache read")]
+    )
+
+    # Edge case: cache_read_tokens >= input_tokens
+    # This could happen in some API responses where accounting differs
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Response with edge case token counts.",
+                usage_metadata={
+                    "input_tokens": 80,
+                    "output_tokens": 20,
+                    "total_tokens": 100,
+                    "cache_read_input_tokens": 100,  # More than input_tokens
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Response with edge case token counts."
+    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"
+    # Input tokens should be 0, not negative: max(80 - 100, 0) = 0
+    assert generation_props["$ai_input_tokens"] == 0
+    assert generation_props["$ai_output_tokens"] == 20
+    assert generation_props["$ai_cache_read_input_tokens"] == 100
+
+
+def test_no_cache_read_tokens_no_subtraction(mock_client):
+    """Test that when there are no cache_read_tokens, input_tokens remain unchanged.
+
+    This tests the conditional check before the subtraction in callbacks.py line 757.
+    """
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Normal request without cache")]
+    )
+
+    # No cache usage - input_tokens should remain as-is
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Response without cache.",
+                usage_metadata={
+                    "input_tokens": 100,
+                    "output_tokens": 30,
+                    "total_tokens": 130,
+                    # No cache_read_input_tokens
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Response without cache."
+    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"
+    # Input tokens should remain unchanged at 100
+    assert generation_props["$ai_input_tokens"] == 100
+    assert generation_props["$ai_output_tokens"] == 30
+    assert generation_props["$ai_cache_read_input_tokens"] == 0
+
+
+def test_zero_input_tokens_with_cache_read(mock_client):
+    """Test edge case where input_tokens is 0 but cache_read_tokens exist.
+
+    This tests the falsy check in the conditional (line 757).
+    """
+    prompt = ChatPromptTemplate.from_messages([("user", "Edge case query")])
+
+    # Edge case: input_tokens is 0 (falsy), should skip subtraction
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Response.",
+                usage_metadata={
+                    "input_tokens": 0,
+                    "output_tokens": 10,
+                    "total_tokens": 10,
+                    "cache_read_input_tokens": 50,
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "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"
+    # Input tokens should remain 0 (no subtraction because input_tokens is falsy)
+    assert generation_props["$ai_input_tokens"] == 0
+    assert generation_props["$ai_output_tokens"] == 10
+    assert generation_props["$ai_cache_read_input_tokens"] == 50
+
+
+def test_cache_write_tokens_not_subtracted_from_input(mock_client):
+    """Test that cache_creation_input_tokens (cache write) do NOT affect input_tokens.
+
+    Only cache_read_tokens should be subtracted from input_tokens, not cache_write_tokens.
+    """
+    prompt = ChatPromptTemplate.from_messages([("user", "Create cache")])
+
+    # Cache creation without cache read
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Creating cache.",
+                usage_metadata={
+                    "input_tokens": 1000,
+                    "output_tokens": 20,
+                    "total_tokens": 1020,
+                    "cache_creation_input_tokens": 800,  # Cache write, not read
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Creating cache."
+    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"
+    # Input tokens should NOT be reduced by cache_creation_input_tokens
+    assert generation_props["$ai_input_tokens"] == 1000
+    assert generation_props["$ai_output_tokens"] == 20
+    assert generation_props["$ai_cache_creation_input_tokens"] == 800
+    assert generation_props["$ai_cache_read_input_tokens"] == 0
+
+
+def test_agent_action_and_finish_imports():
+    """
+    Regression test for LangChain 1.0+ compatibility (Issue #362).
+    Verifies that AgentAction and AgentFinish can be imported and used.
+    This test ensures the imports work with both LangChain 0.x and 1.0+.
+    """
+    # Import the types that caused the compatibility issue
+    try:
+        from langchain_core.agents import AgentAction, AgentFinish
+    except (ImportError, ModuleNotFoundError):
+        from langchain.schema.agent import AgentAction, AgentFinish  # type: ignore
+
+    # Verify they're available in the callbacks module
+    from posthog.ai.langchain.callbacks import CallbackHandler
+
+    # Test on_agent_action with mock data
+    mock_client = MagicMock()
+    callbacks = CallbackHandler(mock_client)
+    run_id = uuid.uuid4()
+    parent_run_id = uuid.uuid4()
+
+    # Create mock AgentAction
+    action = AgentAction(tool="test_tool", tool_input="test_input", log="test_log")
+
+    # Should not raise an exception
+    callbacks.on_agent_action(action, run_id=run_id, parent_run_id=parent_run_id)
+
+    # Verify parent was set
+    assert run_id in callbacks._parent_tree
+    assert callbacks._parent_tree[run_id] == parent_run_id
+
+    # Test on_agent_finish with mock data
+    finish = AgentFinish(return_values={"output": "test_output"}, log="finish_log")
+
+    # Should not raise an exception
+    callbacks.on_agent_finish(finish, run_id=run_id, parent_run_id=parent_run_id)
+
+    # Verify capture was called
+    assert mock_client.capture.call_count == 1
+    call_args = mock_client.capture.call_args[1]
+    assert call_args["event"] == "$ai_span"

posthog/test/ai/openai/test_openai.py

@@ -1,6 +1,5 @@
-import json
 import time
-from unittest.mock import patch
+from unittest.mock import AsyncMock, patch
 
 import pytest
 
@@ -26,6 +25,7 @@ try:
         ResponseOutputMessage,
         ResponseOutputText,
         ResponseUsage,
+        ResponseFunctionToolCall,
         ParsedResponse,
     )
     from openai.types.responses.parsed_response import (
@@ -34,6 +34,7 @@ try:
     )
 
     from posthog.ai.openai import OpenAI
+    from posthog.ai.openai.openai_async import AsyncOpenAI
 
     OPENAI_AVAILABLE = True
 except ImportError:
@@ -218,6 +219,106 @@ def mock_openai_response_with_cached_tokens():
     )
 
 
+@pytest.fixture
+def streaming_tool_call_chunks():
+    return [
+        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,
+            ),
+        ),
+    ]
+
+
 @pytest.fixture
 def mock_openai_response_with_tool_calls():
     return ChatCompletion(
@@ -227,11 +328,27 @@ def mock_openai_response_with_tool_calls():
         created=int(time.time()),
         choices=[
             Choice(
-                finish_reason="tool_calls",
+                finish_reason="stop",
                 index=0,
                 message=ChatCompletionMessage(
                     content="I'll check the weather for you.",
                     role="assistant",
+                ),
+            ),
+            Choice(
+                finish_reason="stop",
+                index=1,
+                message=ChatCompletionMessage(
+                    content=" Let me look that up.",
+                    role="assistant",
+                ),
+            ),
+            Choice(
+                finish_reason="tool_calls",
+                index=2,
+                message=ChatCompletionMessage(
+                    content=None,
+                    role="assistant",
                     tool_calls=[
                         ChatCompletionMessageToolCall(
                             id="call_abc123",
@@ -243,7 +360,7 @@ def mock_openai_response_with_tool_calls():
                         )
                     ],
                 ),
-            )
+            ),
         ],
         usage=CompletionUsage(
             completion_tokens=15,
@@ -253,6 +370,97 @@ def mock_openai_response_with_tool_calls():
     )
 
 
+@pytest.fixture
+def mock_openai_response_tool_calls_only():
+    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=None,
+                    role="assistant",
+                    tool_calls=[
+                        ChatCompletionMessageToolCall(
+                            id="call_def456",
+                            type="function",
+                            function=Function(
+                                name="get_weather",
+                                arguments='{"location": "New York"}',
+                            ),
+                        )
+                    ],
+                ),
+            )
+        ],
+        usage=CompletionUsage(
+            completion_tokens=10,
+            prompt_tokens=25,
+            total_tokens=35,
+        ),
+    )
+
+
+@pytest.fixture
+def mock_responses_api_with_tool_calls():
+    return Response(
+        id="resp_123",
+        object="response",
+        created_at=int(time.time()),
+        model="gpt-4o-mini",
+        status="completed",
+        error=None,
+        incomplete_details=None,
+        instructions=None,
+        max_output_tokens=None,
+        tools=[],
+        tool_choice="auto",
+        parallel_tool_calls=True,
+        output=[
+            ResponseOutputMessage(
+                id="msg_456",
+                type="message",
+                role="assistant",
+                status="completed",
+                content=[
+                    ResponseOutputText(
+                        type="output_text",
+                        text="I'll help you with the weather.",
+                        annotations=[],
+                    ),
+                    ResponseOutputText(
+                        type="output_text",
+                        text=" Let me check that for you.",
+                        annotations=[],
+                    ),
+                ],
+            ),
+            ResponseFunctionToolCall(
+                id="fc_789",
+                type="function_call",
+                name="get_weather",
+                call_id="call_xyz789",
+                arguments='{"location": "Chicago"}',
+                status="completed",
+            ),
+        ],
+        usage=ResponseUsage(
+            input_tokens=30,
+            output_tokens=20,
+            input_tokens_details={"prompt_tokens": 30, "cached_tokens": 0},
+            output_tokens_details={"reasoning_tokens": 0},
+            total_tokens=50,
+        ),
+        previous_response_id=None,
+        user=None,
+        metadata={},
+    )
+
+
 def test_basic_completion(mock_client, mock_openai_response):
     with patch(
         "openai.resources.chat.completions.Completions.create",
@@ -278,7 +486,10 @@ def test_basic_completion(mock_client, mock_openai_response):
         assert props["$ai_model"] == "gpt-4"
         assert props["$ai_input"] == [{"role": "user", "content": "Hello"}]
         assert props["$ai_output_choices"] == [
-            {"role": "assistant", "content": "Test response"}
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": "Test response"}],
+            }
         ]
         assert props["$ai_input_tokens"] == 20
         assert props["$ai_output_tokens"] == 10
@@ -427,7 +638,10 @@ def test_cached_tokens(mock_client, mock_openai_response_with_cached_tokens):
         assert props["$ai_model"] == "gpt-4"
         assert props["$ai_input"] == [{"role": "user", "content": "Hello"}]
         assert props["$ai_output_choices"] == [
-            {"role": "assistant", "content": "Test response"}
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": "Test response"}],
+            }
         ]
         assert props["$ai_input_tokens"] == 20
         assert props["$ai_output_tokens"] == 10
@@ -475,24 +689,34 @@ def test_tool_calls(mock_client, mock_openai_response_with_tool_calls):
             {"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."}
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "I'll check the weather for you."},
+                    {"type": "text", "text": " Let me look that up."},
+                    {
+                        "type": "function",
+                        "id": "call_abc123",
+                        "function": {
+                            "name": "get_weather",
+                            "arguments": '{"location": "San Francisco", "unit": "celsius"}',
+                        },
+                    },
+                ],
+            }
         ]
 
-        # Check that tool calls are properly captured
+        # Check that defined tools are properly captured in $ai_tools
         assert "$ai_tools" in props
-        tool_calls = props["$ai_tools"]
-        assert len(tool_calls) == 1
+        defined_tools = props["$ai_tools"]
+        assert len(defined_tools) == 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"}
+        # Verify the defined tool details
+        defined_tool = defined_tools[0]
+        assert defined_tool["type"] == "function"
+        assert defined_tool["function"]["name"] == "get_weather"
+        assert defined_tool["function"]["description"] == "Get weather"
+        assert defined_tool["function"]["parameters"] == {}
 
         # Check token usage
         assert props["$ai_input_tokens"] == 20
@@ -500,109 +724,122 @@ def test_tool_calls(mock_client, mock_openai_response_with_tool_calls):
         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",
+def test_tool_calls_only_no_content(mock_client, mock_openai_response_tool_calls_only):
+    with patch(
+        "openai.resources.chat.completions.Completions.create",
+        return_value=mock_openai_response_tool_calls_only,
+    ):
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+        response = client.chat.completions.create(
             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,
-                )
+            messages=[{"role": "user", "content": "Get weather for New York"}],
+            tools=[
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "get_weather",
+                        "description": "Get weather",
+                        "parameters": {},
+                    },
+                }
             ],
-        ),
-        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,
-            ),
-        ),
-    ]
+            posthog_distinct_id="test-id",
+        )
 
+        assert response == mock_openai_response_tool_calls_only
+        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_output_choices"] == [
+            {
+                "role": "assistant",
+                "content": [
+                    {
+                        "type": "function",
+                        "id": "call_def456",
+                        "function": {
+                            "name": "get_weather",
+                            "arguments": '{"location": "New York"}',
+                        },
+                    }
+                ],
+            }
+        ]
+
+        # Check token usage
+        assert props["$ai_input_tokens"] == 25
+        assert props["$ai_output_tokens"] == 10
+        assert props["$ai_http_status"] == 200
+
+
+def test_responses_api_tool_calls(mock_client, mock_responses_api_with_tool_calls):
+    with patch(
+        "openai.resources.responses.Responses.create",
+        return_value=mock_responses_api_with_tool_calls,
+    ):
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+        response = client.responses.create(
+            model="gpt-4o-mini",
+            input=[{"role": "user", "content": "What's the weather in Chicago?"}],
+            tools=[
+                {
+                    "name": "get_weather",
+                    "type": "function",
+                    "function": {
+                        "name": "get_weather",
+                        "description": "Get weather",
+                        "parameters": {},
+                    },
+                }
+            ],
+            posthog_distinct_id="test-id",
+        )
+
+        assert response == mock_responses_api_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-4o-mini"
+        assert props["$ai_output_choices"] == [
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "I'll help you with the weather."},
+                    {"type": "text", "text": " Let me check that for you."},
+                    {
+                        "type": "function",
+                        "id": "call_xyz789",
+                        "function": {
+                            "name": "get_weather",
+                            "arguments": '{"location": "Chicago"}',
+                        },
+                    },
+                ],
+            }
+        ]
+
+        # Check token usage
+        assert props["$ai_input_tokens"] == 30
+        assert props["$ai_output_tokens"] == 20
+        assert props["$ai_http_status"] == 200
+
+
+def test_streaming_with_tool_calls(mock_client, streaming_tool_call_chunks):
     # 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
+        mock_create.return_value = streaming_tool_call_chunks
 
         client = OpenAI(api_key="test-key", posthog_client=mock_client)
 
@@ -631,7 +868,7 @@ def test_streaming_with_tool_calls(mock_client):
 
         # Verify the chunks were returned correctly
         assert len(chunks) == 4
-        assert chunks == tool_call_chunks
+        assert chunks == streaming_tool_call_chunks
 
         # Verify the capture was called with the right arguments
         assert mock_client.capture.call_count == 1
@@ -644,26 +881,41 @@ def test_streaming_with_tool_calls(mock_client):
         assert props["$ai_provider"] == "openai"
         assert props["$ai_model"] == "gpt-4"
 
-        # Check that the tool calls were properly accumulated
+        # Check that defined tools are properly captured in $ai_tools
         assert "$ai_tools" in props
-        tool_calls = props["$ai_tools"]
-        assert len(tool_calls) == 1
+        defined_tools = props["$ai_tools"]
+        assert len(defined_tools) == 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 defined tool details
+        defined_tool = defined_tools[0]
+        assert defined_tool["type"] == "function"
+        assert defined_tool["function"]["name"] == "get_weather"
+        assert defined_tool["function"]["description"] == "Get weather"
+        assert defined_tool["function"]["parameters"] == {}
 
-        # 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 both text content and tool calls were accumulated
+        output_content = props["$ai_output_choices"][0]["content"]
 
-        # Check that the content was also accumulated
+        # Find text content and tool call in the output
+        text_content = None
+        tool_call_content = None
+        for item in output_content:
+            if item["type"] == "text":
+                text_content = item
+            elif item["type"] == "function":
+                tool_call_content = item
+
+        # Verify text content
+        assert text_content is not None
+        assert text_content["text"] == "The weather in San Francisco is 15°C."
+
+        # Verify tool call was captured
+        assert tool_call_content is not None
+        assert tool_call_content["id"] == "call_abc123"
+        assert tool_call_content["function"]["name"] == "get_weather"
         assert (
-            props["$ai_output_choices"][0]["content"]
-            == "The weather in San Francisco is 15°C."
+            tool_call_content["function"]["arguments"]
+            == '{"location": "San Francisco", "unit": "celsius"}'
         )
 
         # Check token usage
@@ -696,7 +948,10 @@ def test_responses_api(mock_client, mock_openai_response_with_responses_api):
         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"}
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": "Test response"}],
+            }
         ]
         assert props["$ai_input_tokens"] == 10
         assert props["$ai_output_tokens"] == 10
@@ -765,7 +1020,12 @@ def test_responses_parse(mock_client, mock_parsed_response):
         assert props["$ai_output_choices"] == [
             {
                 "role": "assistant",
-                "content": '{"name": "Science Fair", "date": "Friday", "participants": ["Alice", "Bob"]}',
+                "content": [
+                    {
+                        "type": "text",
+                        "text": '{"name": "Science Fair", "date": "Friday", "participants": ["Alice", "Bob"]}',
+                    }
+                ],
             }
         ]
         assert props["$ai_input_tokens"] == 15
@@ -774,3 +1034,308 @@ def test_responses_parse(mock_client, mock_parsed_response):
         assert props["$ai_http_status"] == 200
         assert props["foo"] == "bar"
         assert isinstance(props["$ai_latency"], float)
+
+
+def test_responses_api_streaming_with_tokens(mock_client):
+    """Test that Responses API streaming properly captures token usage from response.usage."""
+    from openai.types.responses import ResponseUsage
+    from unittest.mock import MagicMock
+
+    # Create mock response chunks with usage data in the correct location
+    chunks = []
+
+    # First chunk - just content, no usage
+    chunk1 = MagicMock()
+    chunk1.type = "response.text.delta"
+    chunk1.text = "Test "
+    chunks.append(chunk1)
+
+    # Second chunk - more content
+    chunk2 = MagicMock()
+    chunk2.type = "response.text.delta"
+    chunk2.text = "response"
+    chunks.append(chunk2)
+
+    # Final chunk - completed event with usage in response.usage
+    chunk3 = MagicMock()
+    chunk3.type = "response.completed"
+    chunk3.response = MagicMock()
+    chunk3.response.usage = ResponseUsage(
+        input_tokens=25,
+        output_tokens=30,
+        total_tokens=55,
+        input_tokens_details={"prompt_tokens": 25, "cached_tokens": 0},
+        output_tokens_details={"reasoning_tokens": 0},
+    )
+    chunk3.response.output = ["Test response"]
+    chunks.append(chunk3)
+
+    captured_kwargs = {}
+
+    def mock_streaming_response(**kwargs):
+        # Capture the kwargs to verify stream_options was NOT added
+        captured_kwargs.update(kwargs)
+        return iter(chunks)
+
+    with patch(
+        "openai.resources.responses.Responses.create",
+        side_effect=mock_streaming_response,
+    ):
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+
+        # Consume the streaming response
+        response = client.responses.create(
+            model="gpt-4o-mini",
+            input=[{"role": "user", "content": "Test message"}],
+            stream=True,
+            posthog_distinct_id="test-id",
+            posthog_properties={"test": "streaming"},
+        )
+
+        # Consume all chunks
+        list(response)
+
+        # Verify stream_options was NOT added (Responses API doesn't support it)
+        assert "stream_options" not in captured_kwargs
+
+        # Verify capture was called
+        assert mock_client.capture.call_count == 1
+
+        call_args = mock_client.capture.call_args[1]
+        props = call_args["properties"]
+
+        # Verify tokens are captured correctly from response.usage (not 0)
+        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_tokens"] == 25  # Should not be 0
+        assert props["$ai_output_tokens"] == 30  # Should not be 0
+        assert props["test"] == "streaming"
+        assert isinstance(props["$ai_latency"], float)
+
+
+@pytest.mark.asyncio
+async def test_async_chat_streaming_with_tool_calls(
+    mock_client, streaming_tool_call_chunks
+):
+    captured_kwargs = {}
+
+    async def mock_create(self, **kwargs):
+        captured_kwargs["kwargs"] = kwargs
+
+        async def chunk_iterable():
+            for chunk in streaming_tool_call_chunks:
+                yield chunk
+
+        return chunk_iterable()
+
+    with patch(
+        "openai.resources.chat.completions.AsyncCompletions.create", new=mock_create
+    ):
+        client = AsyncOpenAI(api_key="test-key", posthog_client=mock_client)
+
+        response_stream = await 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",
+        )
+
+        chunks = []
+        async for chunk in response_stream:
+            chunks.append(chunk)
+
+    kwargs = captured_kwargs["kwargs"]
+    assert kwargs["stream_options"]["include_usage"] is True
+
+    assert len(chunks) == len(streaming_tool_call_chunks)
+    assert chunks == streaming_tool_call_chunks
+
+    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_output_tokens"] == 15
+    assert props["$ai_input_tokens"] == 20
+    assert isinstance(props["$ai_latency"], float)
+
+
+@pytest.mark.asyncio
+async def test_async_responses_streaming_with_tokens(mock_client):
+    from openai.types.responses import ResponseUsage
+    from unittest.mock import MagicMock
+
+    chunks = []
+
+    chunk1 = MagicMock()
+    chunk1.type = "response.text.delta"
+    chunk1.text = "Test "
+    chunks.append(chunk1)
+
+    chunk2 = MagicMock()
+    chunk2.type = "response.text.delta"
+    chunk2.text = "response"
+    chunks.append(chunk2)
+
+    chunk3 = MagicMock()
+    chunk3.type = "response.completed"
+    chunk3.response = MagicMock()
+    chunk3.response.usage = ResponseUsage(
+        input_tokens=25,
+        output_tokens=30,
+        total_tokens=55,
+        input_tokens_details={"prompt_tokens": 25, "cached_tokens": 0},
+        output_tokens_details={"reasoning_tokens": 0},
+    )
+    chunk3.response.output = ["Test response"]
+    chunks.append(chunk3)
+
+    captured_kwargs = {}
+
+    async def mock_create(self, **kwargs):
+        captured_kwargs["kwargs"] = kwargs
+
+        async def chunk_iterable():
+            for chunk in chunks:
+                yield chunk
+
+        return chunk_iterable()
+
+    with patch("openai.resources.responses.AsyncResponses.create", new=mock_create):
+        client = AsyncOpenAI(api_key="test-key", posthog_client=mock_client)
+
+        response_stream = await client.responses.create(
+            model="gpt-4o-mini",
+            input=[{"role": "user", "content": "Test message"}],
+            stream=True,
+            posthog_distinct_id="test-id",
+            posthog_properties={"test": "streaming"},
+        )
+
+        async for _ in response_stream:
+            pass
+
+    kwargs = captured_kwargs["kwargs"]
+    assert "stream_options" not in kwargs
+
+    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_tokens"] == 25
+    assert props["$ai_output_tokens"] == 30
+    assert props["test"] == "streaming"
+    assert isinstance(props["$ai_latency"], float)
+
+
+@pytest.mark.asyncio
+async def test_async_embeddings_create(mock_client, mock_embedding_response):
+    mock_create = AsyncMock(return_value=mock_embedding_response)
+
+    with patch("openai.resources.embeddings.AsyncEmbeddings.create", new=mock_create):
+        client = AsyncOpenAI(api_key="test-key", posthog_client=mock_client)
+
+        response = await client.embeddings.create(
+            model="text-embedding-3-small",
+            input="Hello world",
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+        )
+
+    assert response == mock_embedding_response
+    assert mock_create.await_count == 1
+    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_embedding"
+    assert props["$ai_provider"] == "openai"
+    assert props["$ai_model"] == "text-embedding-3-small"
+    assert props["foo"] == "bar"
+    assert isinstance(props["$ai_latency"], float)
+
+
+def test_tool_definition(mock_client, mock_openai_response):
+    """Test that tools defined in the create function are captured in $ai_tools property"""
+    with patch(
+        "openai.resources.chat.completions.Completions.create",
+        return_value=mock_openai_response,
+    ):
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+
+        # Define tools to be passed to the create function
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "get_weather",
+                    "description": "Get the current weather for a specific location",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "location": {
+                                "type": "string",
+                                "description": "The city or location name to get weather for",
+                            }
+                        },
+                        "required": ["location"],
+                    },
+                },
+            }
+        ]
+
+        response = client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "hey"}],
+            tools=tools,
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+        )
+
+        assert response == mock_openai_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-mini"
+        assert props["$ai_input"] == [{"role": "user", "content": "hey"}]
+        assert props["$ai_output_choices"] == [
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": "Test response"}],
+            }
+        ]
+        assert props["$ai_input_tokens"] == 20
+        assert props["$ai_output_tokens"] == 10
+        assert props["$ai_http_status"] == 200
+        assert props["foo"] == "bar"
+        assert isinstance(props["$ai_latency"], float)
+        # Verify that tools are captured in the $ai_tools property
+        assert props["$ai_tools"] == tools

posthog/test/ai/test_sanitization.py

@@ -0,0 +1,335 @@
+import unittest
+
+from posthog.ai.sanitization import (
+    redact_base64_data_url,
+    sanitize_openai,
+    sanitize_openai_response,
+    sanitize_anthropic,
+    sanitize_gemini,
+    sanitize_langchain,
+    is_base64_data_url,
+    is_raw_base64,
+    REDACTED_IMAGE_PLACEHOLDER,
+)
+
+
+class TestSanitization(unittest.TestCase):
+    def setUp(self):
+        self.sample_base64_image = "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
+        self.sample_base64_png = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
+        self.regular_url = "https://example.com/image.jpg"
+        self.raw_base64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUl=="
+
+    def test_is_base64_data_url(self):
+        self.assertTrue(is_base64_data_url(self.sample_base64_image))
+        self.assertTrue(is_base64_data_url(self.sample_base64_png))
+        self.assertFalse(is_base64_data_url(self.regular_url))
+        self.assertFalse(is_base64_data_url("regular text"))
+
+    def test_is_raw_base64(self):
+        self.assertTrue(is_raw_base64(self.raw_base64))
+        self.assertFalse(is_raw_base64("short"))
+        self.assertFalse(is_raw_base64(self.regular_url))
+        self.assertFalse(is_raw_base64("/path/to/file"))
+
+    def test_redact_base64_data_url(self):
+        self.assertEqual(
+            redact_base64_data_url(self.sample_base64_image), REDACTED_IMAGE_PLACEHOLDER
+        )
+        self.assertEqual(
+            redact_base64_data_url(self.sample_base64_png), REDACTED_IMAGE_PLACEHOLDER
+        )
+        self.assertEqual(redact_base64_data_url(self.regular_url), self.regular_url)
+        self.assertEqual(redact_base64_data_url(None), None)
+        self.assertEqual(redact_base64_data_url(123), 123)
+
+    def test_sanitize_openai(self):
+        input_data = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "What is in this image?"},
+                    {
+                        "type": "image_url",
+                        "image_url": {
+                            "url": self.sample_base64_image,
+                            "detail": "high",
+                        },
+                    },
+                ],
+            }
+        ]
+
+        result = sanitize_openai(input_data)
+
+        self.assertEqual(result[0]["content"][0]["text"], "What is in this image?")
+        self.assertEqual(
+            result[0]["content"][1]["image_url"]["url"], REDACTED_IMAGE_PLACEHOLDER
+        )
+        self.assertEqual(result[0]["content"][1]["image_url"]["detail"], "high")
+
+    def test_sanitize_openai_preserves_regular_urls(self):
+        input_data = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": self.regular_url},
+                    }
+                ],
+            }
+        ]
+
+        result = sanitize_openai(input_data)
+        self.assertEqual(result[0]["content"][0]["image_url"]["url"], self.regular_url)
+
+    def test_sanitize_openai_response(self):
+        input_data = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "input_image",
+                        "image_url": self.sample_base64_image,
+                    }
+                ],
+            }
+        ]
+
+        result = sanitize_openai_response(input_data)
+        self.assertEqual(
+            result[0]["content"][0]["image_url"], REDACTED_IMAGE_PLACEHOLDER
+        )
+
+    def test_sanitize_anthropic(self):
+        input_data = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "What is in this image?"},
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/jpeg",
+                            "data": "base64data",
+                        },
+                    },
+                ],
+            }
+        ]
+
+        result = sanitize_anthropic(input_data)
+
+        self.assertEqual(result[0]["content"][0]["text"], "What is in this image?")
+        self.assertEqual(
+            result[0]["content"][1]["source"]["data"], REDACTED_IMAGE_PLACEHOLDER
+        )
+        self.assertEqual(result[0]["content"][1]["source"]["type"], "base64")
+        self.assertEqual(result[0]["content"][1]["source"]["media_type"], "image/jpeg")
+
+    def test_sanitize_gemini(self):
+        input_data = [
+            {
+                "parts": [
+                    {"text": "What is in this image?"},
+                    {
+                        "inline_data": {
+                            "mime_type": "image/jpeg",
+                            "data": "base64data",
+                        }
+                    },
+                ]
+            }
+        ]
+
+        result = sanitize_gemini(input_data)
+
+        self.assertEqual(result[0]["parts"][0]["text"], "What is in this image?")
+        self.assertEqual(
+            result[0]["parts"][1]["inline_data"]["data"], REDACTED_IMAGE_PLACEHOLDER
+        )
+        self.assertEqual(
+            result[0]["parts"][1]["inline_data"]["mime_type"], "image/jpeg"
+        )
+
+    def test_sanitize_langchain_openai_style(self):
+        input_data = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": self.sample_base64_image},
+                    }
+                ],
+            }
+        ]
+
+        result = sanitize_langchain(input_data)
+        self.assertEqual(
+            result[0]["content"][0]["image_url"]["url"], REDACTED_IMAGE_PLACEHOLDER
+        )
+
+    def test_sanitize_langchain_anthropic_style(self):
+        input_data = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {"data": "base64data"},
+                    }
+                ],
+            }
+        ]
+
+        result = sanitize_langchain(input_data)
+        self.assertEqual(
+            result[0]["content"][0]["source"]["data"], REDACTED_IMAGE_PLACEHOLDER
+        )
+
+    def test_sanitize_with_data_url_format(self):
+        # Test that data URLs are properly detected and redacted across providers
+        data_url = "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD"
+
+        # OpenAI format
+        openai_data = [
+            {
+                "role": "user",
+                "content": [{"type": "image_url", "image_url": {"url": data_url}}],
+            }
+        ]
+        result = sanitize_openai(openai_data)
+        self.assertEqual(
+            result[0]["content"][0]["image_url"]["url"], REDACTED_IMAGE_PLACEHOLDER
+        )
+
+        # Anthropic format
+        anthropic_data = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/jpeg",
+                            "data": data_url,
+                        },
+                    }
+                ],
+            }
+        ]
+        result = sanitize_anthropic(anthropic_data)
+        self.assertEqual(
+            result[0]["content"][0]["source"]["data"], REDACTED_IMAGE_PLACEHOLDER
+        )
+
+        # LangChain format
+        langchain_data = [
+            {"role": "user", "content": [{"type": "image", "data": data_url}]}
+        ]
+        result = sanitize_langchain(langchain_data)
+        self.assertEqual(result[0]["content"][0]["data"], REDACTED_IMAGE_PLACEHOLDER)
+
+    def test_sanitize_with_raw_base64(self):
+        # Test that raw base64 strings (without data URL prefix) are detected
+        raw_base64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUl=="
+
+        # Test with Anthropic format
+        anthropic_data = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/png",
+                            "data": raw_base64,
+                        },
+                    }
+                ],
+            }
+        ]
+        result = sanitize_anthropic(anthropic_data)
+        self.assertEqual(
+            result[0]["content"][0]["source"]["data"], REDACTED_IMAGE_PLACEHOLDER
+        )
+
+        # Test with Gemini format
+        gemini_data = [
+            {"parts": [{"inline_data": {"mime_type": "image/png", "data": raw_base64}}]}
+        ]
+        result = sanitize_gemini(gemini_data)
+        self.assertEqual(
+            result[0]["parts"][0]["inline_data"]["data"], REDACTED_IMAGE_PLACEHOLDER
+        )
+
+    def test_sanitize_preserves_regular_content(self):
+        # Ensure non-base64 content is preserved across all providers
+        regular_url = "https://example.com/image.jpg"
+        text_content = "What do you see?"
+
+        # OpenAI
+        openai_data = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": text_content},
+                    {"type": "image_url", "image_url": {"url": regular_url}},
+                ],
+            }
+        ]
+        result = sanitize_openai(openai_data)
+        self.assertEqual(result[0]["content"][0]["text"], text_content)
+        self.assertEqual(result[0]["content"][1]["image_url"]["url"], regular_url)
+
+        # Anthropic
+        anthropic_data = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": text_content},
+                    {"type": "image", "source": {"type": "url", "url": regular_url}},
+                ],
+            }
+        ]
+        result = sanitize_anthropic(anthropic_data)
+        self.assertEqual(result[0]["content"][0]["text"], text_content)
+        # URL-based images should remain unchanged
+        self.assertEqual(result[0]["content"][1]["source"]["url"], regular_url)
+
+    def test_sanitize_handles_non_dict_content(self):
+        input_data = [{"role": "user", "content": "Just text"}]
+
+        result = sanitize_openai(input_data)
+        self.assertEqual(result, input_data)
+
+    def test_sanitize_handles_none_input(self):
+        self.assertIsNone(sanitize_openai(None))
+        self.assertIsNone(sanitize_anthropic(None))
+        self.assertIsNone(sanitize_gemini(None))
+        self.assertIsNone(sanitize_langchain(None))
+
+    def test_sanitize_handles_single_message(self):
+        input_data = {
+            "role": "user",
+            "content": [
+                {
+                    "type": "image_url",
+                    "image_url": {"url": self.sample_base64_image},
+                }
+            ],
+        }
+
+        result = sanitize_openai(input_data)
+        self.assertEqual(
+            result["content"][0]["image_url"]["url"], REDACTED_IMAGE_PLACEHOLDER
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

posthog/test/ai/test_system_prompts.py

@@ -0,0 +1,354 @@
+"""
+Tests for system prompt capture across all LLM providers.
+
+This test suite ensures that system prompts are correctly captured in analytics
+regardless of how they're passed to the providers:
+- As first message in messages/contents array (standard format)
+- As separate system parameter (Anthropic, OpenAI)
+- As instructions parameter (OpenAI Responses API)
+- As system_instruction parameter (Gemini)
+"""
+
+import time
+import unittest
+from unittest.mock import patch, MagicMock
+
+
+class TestSystemPromptCapture(unittest.TestCase):
+    """Test system prompt capture for all providers."""
+
+    def setUp(self):
+        super().setUp()
+        self.test_system_prompt = "You are a helpful AI assistant."
+        self.test_user_message = "Hello, how are you?"
+        self.test_response = "I'm doing well, thank you!"
+
+        # Create mock PostHog client
+        self.client = MagicMock()
+        self.client.privacy_mode = False
+
+    def _assert_system_prompt_captured(self, captured_input):
+        """Helper to assert system prompt is correctly captured."""
+        self.assertEqual(
+            len(captured_input), 2, "Should have 2 messages (system + user)"
+        )
+        self.assertEqual(
+            captured_input[0]["role"], "system", "First message should be system"
+        )
+        self.assertEqual(
+            captured_input[0]["content"],
+            self.test_system_prompt,
+            "System content should match",
+        )
+        self.assertEqual(
+            captured_input[1]["role"], "user", "Second message should be user"
+        )
+        self.assertEqual(
+            captured_input[1]["content"],
+            self.test_user_message,
+            "User content should match",
+        )
+
+    # OpenAI Tests
+    def test_openai_messages_array_system_prompt(self):
+        """Test OpenAI with system prompt in messages array."""
+        try:
+            from posthog.ai.openai import OpenAI
+            from openai.types.chat import ChatCompletion, ChatCompletionMessage
+            from openai.types.chat.chat_completion import Choice
+            from openai.types.completion_usage import CompletionUsage
+        except ImportError:
+            self.skipTest("OpenAI package not available")
+
+        mock_response = ChatCompletion(
+            id="test",
+            model="gpt-4",
+            object="chat.completion",
+            created=int(time.time()),
+            choices=[
+                Choice(
+                    finish_reason="stop",
+                    index=0,
+                    message=ChatCompletionMessage(
+                        content=self.test_response, role="assistant"
+                    ),
+                )
+            ],
+            usage=CompletionUsage(
+                completion_tokens=10, prompt_tokens=20, total_tokens=30
+            ),
+        )
+
+        with patch(
+            "openai.resources.chat.completions.Completions.create",
+            return_value=mock_response,
+        ):
+            client = OpenAI(posthog_client=self.client, api_key="test")
+
+            messages = [
+                {"role": "system", "content": self.test_system_prompt},
+                {"role": "user", "content": self.test_user_message},
+            ]
+
+            client.chat.completions.create(
+                model="gpt-4", messages=messages, posthog_distinct_id="test-user"
+            )
+
+            self.assertEqual(len(self.client.capture.call_args_list), 1)
+            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self._assert_system_prompt_captured(properties["$ai_input"])
+
+    def test_openai_separate_system_parameter(self):
+        """Test OpenAI with system prompt as separate parameter."""
+        try:
+            from posthog.ai.openai import OpenAI
+            from openai.types.chat import ChatCompletion, ChatCompletionMessage
+            from openai.types.chat.chat_completion import Choice
+            from openai.types.completion_usage import CompletionUsage
+        except ImportError:
+            self.skipTest("OpenAI package not available")
+
+        mock_response = ChatCompletion(
+            id="test",
+            model="gpt-4",
+            object="chat.completion",
+            created=int(time.time()),
+            choices=[
+                Choice(
+                    finish_reason="stop",
+                    index=0,
+                    message=ChatCompletionMessage(
+                        content=self.test_response, role="assistant"
+                    ),
+                )
+            ],
+            usage=CompletionUsage(
+                completion_tokens=10, prompt_tokens=20, total_tokens=30
+            ),
+        )
+
+        with patch(
+            "openai.resources.chat.completions.Completions.create",
+            return_value=mock_response,
+        ):
+            client = OpenAI(posthog_client=self.client, api_key="test")
+
+            messages = [{"role": "user", "content": self.test_user_message}]
+
+            client.chat.completions.create(
+                model="gpt-4",
+                messages=messages,
+                system=self.test_system_prompt,
+                posthog_distinct_id="test-user",
+            )
+
+            self.assertEqual(len(self.client.capture.call_args_list), 1)
+            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self._assert_system_prompt_captured(properties["$ai_input"])
+
+    def test_openai_streaming_system_parameter(self):
+        """Test OpenAI streaming with system parameter."""
+        try:
+            from posthog.ai.openai import OpenAI
+            from openai.types.chat.chat_completion_chunk import ChatCompletionChunk
+            from openai.types.chat.chat_completion_chunk import Choice as ChoiceChunk
+            from openai.types.chat.chat_completion_chunk import ChoiceDelta
+            from openai.types.completion_usage import CompletionUsage
+        except ImportError:
+            self.skipTest("OpenAI package not available")
+
+        chunk1 = ChatCompletionChunk(
+            id="test",
+            model="gpt-4",
+            object="chat.completion.chunk",
+            created=int(time.time()),
+            choices=[
+                ChoiceChunk(
+                    finish_reason=None,
+                    index=0,
+                    delta=ChoiceDelta(content="Hello", role="assistant"),
+                )
+            ],
+        )
+
+        chunk2 = ChatCompletionChunk(
+            id="test",
+            model="gpt-4",
+            object="chat.completion.chunk",
+            created=int(time.time()),
+            choices=[
+                ChoiceChunk(
+                    finish_reason="stop",
+                    index=0,
+                    delta=ChoiceDelta(content=" there!", role=None),
+                )
+            ],
+            usage=CompletionUsage(
+                completion_tokens=10, prompt_tokens=20, total_tokens=30
+            ),
+        )
+
+        with patch(
+            "openai.resources.chat.completions.Completions.create",
+            return_value=[chunk1, chunk2],
+        ):
+            client = OpenAI(posthog_client=self.client, api_key="test")
+
+            messages = [{"role": "user", "content": self.test_user_message}]
+
+            response_generator = client.chat.completions.create(
+                model="gpt-4",
+                messages=messages,
+                system=self.test_system_prompt,
+                stream=True,
+                posthog_distinct_id="test-user",
+            )
+
+            list(response_generator)  # Consume generator
+
+            self.assertEqual(len(self.client.capture.call_args_list), 1)
+            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self._assert_system_prompt_captured(properties["$ai_input"])
+
+    # Anthropic Tests
+    def test_anthropic_messages_array_system_prompt(self):
+        """Test Anthropic with system prompt in messages array."""
+        try:
+            from posthog.ai.anthropic import Anthropic
+        except ImportError:
+            self.skipTest("Anthropic package not available")
+
+        with patch("anthropic.resources.messages.Messages.create") as mock_create:
+            mock_response = MagicMock()
+            mock_response.usage.input_tokens = 20
+            mock_response.usage.output_tokens = 10
+            mock_response.usage.cache_read_input_tokens = None
+            mock_response.usage.cache_creation_input_tokens = None
+            mock_create.return_value = mock_response
+
+            client = Anthropic(posthog_client=self.client, api_key="test")
+
+            messages = [
+                {"role": "system", "content": self.test_system_prompt},
+                {"role": "user", "content": self.test_user_message},
+            ]
+
+            client.messages.create(
+                model="claude-3-5-sonnet-20241022",
+                messages=messages,
+                posthog_distinct_id="test-user",
+            )
+
+            self.assertEqual(len(self.client.capture.call_args_list), 1)
+            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self._assert_system_prompt_captured(properties["$ai_input"])
+
+    def test_anthropic_separate_system_parameter(self):
+        """Test Anthropic with system prompt as separate parameter."""
+        try:
+            from posthog.ai.anthropic import Anthropic
+        except ImportError:
+            self.skipTest("Anthropic package not available")
+
+        with patch("anthropic.resources.messages.Messages.create") as mock_create:
+            mock_response = MagicMock()
+            mock_response.usage.input_tokens = 20
+            mock_response.usage.output_tokens = 10
+            mock_response.usage.cache_read_input_tokens = None
+            mock_response.usage.cache_creation_input_tokens = None
+            mock_create.return_value = mock_response
+
+            client = Anthropic(posthog_client=self.client, api_key="test")
+
+            messages = [{"role": "user", "content": self.test_user_message}]
+
+            client.messages.create(
+                model="claude-3-5-sonnet-20241022",
+                messages=messages,
+                system=self.test_system_prompt,
+                posthog_distinct_id="test-user",
+            )
+
+            self.assertEqual(len(self.client.capture.call_args_list), 1)
+            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self._assert_system_prompt_captured(properties["$ai_input"])
+
+    # Gemini Tests
+    def test_gemini_contents_array_system_prompt(self):
+        """Test Gemini with system prompt in contents array."""
+        try:
+            from posthog.ai.gemini import Client
+        except ImportError:
+            self.skipTest("Gemini package not available")
+
+        with patch("google.genai.Client") as mock_genai_class:
+            mock_response = MagicMock()
+            mock_response.candidates = [MagicMock()]
+            mock_response.candidates[0].content.parts = [MagicMock()]
+            mock_response.candidates[0].content.parts[0].text = self.test_response
+            mock_response.usage_metadata.prompt_token_count = 20
+            mock_response.usage_metadata.candidates_token_count = 10
+            mock_response.usage_metadata.cached_content_token_count = None
+            mock_response.usage_metadata.thoughts_token_count = None
+
+            mock_client_instance = MagicMock()
+            mock_models_instance = MagicMock()
+            mock_models_instance.generate_content.return_value = mock_response
+            mock_client_instance.models = mock_models_instance
+            mock_genai_class.return_value = mock_client_instance
+
+            client = Client(posthog_client=self.client, api_key="test")
+
+            contents = [
+                {"role": "system", "content": self.test_system_prompt},
+                {"role": "user", "content": self.test_user_message},
+            ]
+
+            client.models.generate_content(
+                model="gemini-2.0-flash",
+                contents=contents,
+                posthog_distinct_id="test-user",
+            )
+
+            self.assertEqual(len(self.client.capture.call_args_list), 1)
+            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self._assert_system_prompt_captured(properties["$ai_input"])
+
+    def test_gemini_system_instruction_parameter(self):
+        """Test Gemini with system_instruction in config parameter."""
+        try:
+            from posthog.ai.gemini import Client
+        except ImportError:
+            self.skipTest("Gemini package not available")
+
+        with patch("google.genai.Client") as mock_genai_class:
+            mock_response = MagicMock()
+            mock_response.candidates = [MagicMock()]
+            mock_response.candidates[0].content.parts = [MagicMock()]
+            mock_response.candidates[0].content.parts[0].text = self.test_response
+            mock_response.usage_metadata.prompt_token_count = 20
+            mock_response.usage_metadata.candidates_token_count = 10
+            mock_response.usage_metadata.cached_content_token_count = None
+            mock_response.usage_metadata.thoughts_token_count = None
+
+            mock_client_instance = MagicMock()
+            mock_models_instance = MagicMock()
+            mock_models_instance.generate_content.return_value = mock_response
+            mock_client_instance.models = mock_models_instance
+            mock_genai_class.return_value = mock_client_instance
+
+            client = Client(posthog_client=self.client, api_key="test")
+
+            contents = [{"role": "user", "content": self.test_user_message}]
+            config = {"system_instruction": self.test_system_prompt}
+
+            client.models.generate_content(
+                model="gemini-2.0-flash",
+                contents=contents,
+                config=config,
+                posthog_distinct_id="test-user",
+            )
+
+            self.assertEqual(len(self.client.capture.call_args_list), 1)
+            properties = self.client.capture.call_args_list[0][1]["properties"]
+            self._assert_system_prompt_captured(properties["$ai_input"])

posthog/test/integrations/test_middleware.py

@@ -4,7 +4,21 @@ from posthog.contexts import (
     get_context_distinct_id,
 )
 import unittest
-from unittest.mock import Mock
+from unittest.mock import Mock, patch
+import asyncio
+
+# Configure Django settings before importing middleware
+import django
+from django.conf import settings
+
+if not settings.configured:
+    settings.configure(
+        DEBUG=True,
+        SECRET_KEY="test-secret-key",
+        INSTALLED_APPS=[],
+        MIDDLEWARE=[],
+    )
+    django.setup()
 
 from posthog.integrations.django import PosthogContextMiddleware
 
@@ -38,14 +52,33 @@ class TestPosthogContextMiddleware(unittest.TestCase):
         request_filter=None,
         tag_map=None,
         capture_exceptions=True,
+        get_response=None,
     ):
-        """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
+        """Helper to create middleware instance with mock Django settings"""
+        if get_response is None:
+            get_response = Mock()
+
+        with patch("django.conf.settings") as mock_settings:
+            # Configure mock settings
+            mock_settings.POSTHOG_MW_EXTRA_TAGS = extra_tags
+            mock_settings.POSTHOG_MW_REQUEST_FILTER = request_filter
+            mock_settings.POSTHOG_MW_TAG_MAP = tag_map
+            mock_settings.POSTHOG_MW_CAPTURE_EXCEPTIONS = capture_exceptions
+            mock_settings.POSTHOG_MW_CLIENT = None
+
+            # Make hasattr work correctly
+            def mock_hasattr(obj, name):
+                return name in [
+                    "POSTHOG_MW_EXTRA_TAGS",
+                    "POSTHOG_MW_REQUEST_FILTER",
+                    "POSTHOG_MW_TAG_MAP",
+                    "POSTHOG_MW_CAPTURE_EXCEPTIONS",
+                    "POSTHOG_MW_CLIENT",
+                ]
+
+            with patch("builtins.hasattr", side_effect=mock_hasattr):
+                middleware = PosthogContextMiddleware(get_response)
+
         return middleware
 
     def test_extract_tags_basic(self):
@@ -168,6 +201,348 @@ class TestPosthogContextMiddleware(unittest.TestCase):
 
         self.assertEqual(tags["$request_method"], "PATCH")
 
+    def test_process_exception_called_during_view_exception(self):
+        """
+        Unit test verifying process_exception captures exceptions per Django's contract.
+
+        Since this is a library test (no Django runtime), we simulate how Django
+        would invoke our middleware in production:
+        1. Middleware.__call__ creates context with request tags
+        2. View raises exception inside get_response
+        3. Django's BaseHandler catches it, calls process_exception, returns error response
+        4. Exception never propagates to middleware's context manager
+
+        We manually call process_exception to simulate Django's behavior - this is
+        the only way to test the hook without a full Django integration test.
+        """
+        mock_client = Mock()
+        view_exception = ValueError("View raised this error")
+        error_response = Mock(status_code=500)
+
+        def mock_get_response(request):
+            # Simulate Django's exception handling: catches view exception,
+            # calls process_exception hook if it exists, returns error response
+            if hasattr(middleware, "process_exception"):
+                middleware.process_exception(request, view_exception)
+            return error_response
+
+        middleware = self.create_middleware(get_response=mock_get_response)
+        middleware.client = mock_client
+
+        request = MockRequest(
+            headers={"X-POSTHOG-DISTINCT-ID": "test-user"},
+            method="POST",
+            path="/api/endpoint",
+        )
+        response = middleware(request)
+
+        self.assertEqual(response.status_code, 500)
+        mock_client.capture_exception.assert_called_once_with(view_exception)
+
+    def test_process_exception_respects_capture_exceptions_false(self):
+        """Verify process_exception respects capture_exceptions=False setting"""
+        mock_client = Mock()
+        view_exception = ValueError("Should not be captured")
+
+        def mock_get_response(request):
+            if hasattr(middleware, "process_exception"):
+                middleware.process_exception(request, view_exception)
+            return Mock(status_code=500)
+
+        middleware = self.create_middleware(
+            capture_exceptions=False, get_response=mock_get_response
+        )
+        middleware.client = mock_client
+
+        request = MockRequest()
+        middleware(request)
+
+        mock_client.capture_exception.assert_not_called()
+
+    def test_process_exception_respects_request_filter(self):
+        """Verify process_exception respects request_filter setting"""
+        mock_client = Mock()
+        view_exception = ValueError("Should be filtered")
+
+        def mock_get_response(request):
+            if hasattr(middleware, "process_exception"):
+                middleware.process_exception(request, view_exception)
+            return Mock(status_code=500)
+
+        middleware = self.create_middleware(
+            request_filter=lambda req: False,
+            capture_exceptions=True,
+            get_response=mock_get_response,
+        )
+        middleware.client = mock_client
+
+        request = MockRequest()
+        middleware(request)
+
+        mock_client.capture_exception.assert_not_called()
+
+
+class TestPosthogContextMiddlewareSync(unittest.TestCase):
+    """Test synchronous middleware behavior"""
+
+    def test_sync_middleware_call(self):
+        """Test that sync middleware correctly processes requests"""
+        mock_response = Mock()
+        get_response = Mock(return_value=mock_response)
+
+        # Create middleware with sync get_response
+        middleware = PosthogContextMiddleware(get_response)
+
+        # Verify sync mode detected
+        self.assertFalse(middleware._is_coroutine)
+
+        request = MockRequest(
+            headers={"X-POSTHOG-SESSION-ID": "test-session"},
+            method="GET",
+            path="/test",
+        )
+
+        with new_context():
+            response = middleware(request)
+
+            # Verify response returned
+            self.assertEqual(response, mock_response)
+            get_response.assert_called_once_with(request)
+
+    def test_sync_middleware_with_filter(self):
+        """Test sync middleware respects request filter"""
+        mock_response = Mock()
+        get_response = Mock(return_value=mock_response)
+
+        # Create middleware with request filter that filters all requests
+        request_filter = lambda req: False
+        middleware = PosthogContextMiddleware.__new__(PosthogContextMiddleware)
+        middleware.get_response = get_response
+        middleware._is_coroutine = False
+        middleware.request_filter = request_filter
+        middleware.capture_exceptions = True
+        middleware.client = None
+
+        request = MockRequest()
+
+        # Should skip context creation and return response directly
+        response = middleware(request)
+        self.assertEqual(response, mock_response)
+        get_response.assert_called_once_with(request)
+
+    def test_view_exceptions_only_captured_via_process_exception(self):
+        """
+        Demonstrates that process_exception is required to capture view exceptions.
+
+        In production Django, view exceptions don't propagate to middleware's context
+        manager because Django's BaseHandler catches them first and converts them to
+        error responses. Django provides the exception via process_exception hook instead.
+
+        This unit test proves:
+        1. Context manager in __call__ never sees view exceptions (Django intercepts)
+        2. Only process_exception can capture them
+        3. Without process_exception, exceptions are silently lost (v6.7.5 regression)
+
+        We manually call process_exception to verify the hook works - in production,
+        Django's BaseHandler would call it when a view raises.
+        """
+        mock_client = Mock()
+        get_response = Mock(return_value=Mock(status_code=500))
+
+        middleware = PosthogContextMiddleware(get_response)
+        middleware.client = mock_client
+
+        def get_response_simulating_django(request):
+            # Simulates Django behavior: view exception converted to error response,
+            # never propagates to middleware's context manager
+            return Mock(status_code=500)
+
+        middleware._sync_get_response = get_response_simulating_django
+
+        request = MockRequest()
+
+        response = middleware(request)
+        self.assertEqual(response.status_code, 500)
+
+        # Context manager didn't capture anything - exception was intercepted by Django
+        mock_client.capture_exception.assert_not_called()
+
+        # Verify process_exception hook exists and captures exceptions when called
+        if hasattr(middleware, "process_exception"):
+            exception = ValueError("View error")
+            middleware.process_exception(request, exception)
+            mock_client.capture_exception.assert_called_once_with(exception)
+        else:
+            self.fail(
+                "process_exception missing - view exceptions will not be captured!"
+            )
+
+
+class TestPosthogContextMiddlewareAsync(unittest.TestCase):
+    """Test asynchronous middleware behavior"""
+
+    def test_async_middleware_detection(self):
+        """Test that async get_response is correctly detected"""
+
+        async def async_get_response(request):
+            return Mock()
+
+        middleware = PosthogContextMiddleware(async_get_response)
+
+        # Verify async mode detected
+        self.assertTrue(middleware._is_coroutine)
+
+    def test_async_middleware_call(self):
+        """Test that async middleware correctly processes requests"""
+
+        async def run_test():
+            mock_response = Mock()
+
+            async def async_get_response(request):
+                return mock_response
+
+            middleware = PosthogContextMiddleware(async_get_response)
+
+            request = MockRequest(
+                headers={"X-POSTHOG-SESSION-ID": "async-session"},
+                method="POST",
+                path="/async-test",
+            )
+
+            with new_context():
+                # Call should return the coroutine from __acall__
+                result = middleware(request)
+
+                # Verify it's a coroutine
+                self.assertTrue(asyncio.iscoroutine(result))
+
+                # Await the result
+                response = await result
+                self.assertEqual(response, mock_response)
+
+        asyncio.run(run_test())
+
+    def test_async_middleware_with_filter(self):
+        """Test async middleware respects request filter"""
+
+        async def run_test():
+            mock_response = Mock()
+
+            async def async_get_response(request):
+                return mock_response
+
+            # Properly initialize middleware
+            middleware = PosthogContextMiddleware(async_get_response)
+            # Override request filter after initialization
+            middleware.request_filter = lambda req: False
+
+            request = MockRequest()
+
+            # Should skip context creation and return response directly
+            result = middleware(request)
+            response = await result
+            self.assertEqual(response, mock_response)
+
+        asyncio.run(run_test())
+
+    def test_async_middleware_context_propagation(self):
+        """Test that async middleware properly propagates context"""
+
+        async def run_test():
+            mock_response = Mock()
+
+            async def async_get_response(request):
+                # Verify context is available during async processing
+                session_id = get_context_session_id()
+                self.assertEqual(session_id, "async-session-123")
+                return mock_response
+
+            middleware = PosthogContextMiddleware(async_get_response)
+
+            request = MockRequest(
+                headers={"X-POSTHOG-SESSION-ID": "async-session-123"},
+                method="GET",
+            )
+
+            with new_context():
+                result = middleware(request)
+                await result
+
+        asyncio.run(run_test())
+
+    def test_async_middleware_exception_capture(self):
+        """Test that async middleware captures exceptions during request processing"""
+
+        async def run_test():
+            mock_client = Mock()
+
+            # Make async_get_response raise an exception
+            async def raise_exception(request):
+                raise ValueError("Async test exception")
+
+            # Properly initialize middleware
+            middleware = PosthogContextMiddleware(raise_exception)
+            middleware.client = mock_client  # Override with mock client
+
+            request = MockRequest()
+
+            # Should capture exception and re-raise
+            with self.assertRaises(ValueError):
+                result = middleware(request)
+                await result
+
+            # Verify exception was captured by middleware
+            mock_client.capture_exception.assert_called_once()
+            captured_exception = mock_client.capture_exception.call_args[0][0]
+            self.assertIsInstance(captured_exception, ValueError)
+            self.assertEqual(str(captured_exception), "Async test exception")
+
+        asyncio.run(run_test())
+
+
+class TestPosthogContextMiddlewareHybrid(unittest.TestCase):
+    """Test hybrid middleware behavior with mixed sync/async chains"""
+
+    def test_hybrid_flags_set(self):
+        """Test that both capability flags are set"""
+        self.assertTrue(PosthogContextMiddleware.sync_capable)
+        self.assertTrue(PosthogContextMiddleware.async_capable)
+
+    def test_sync_to_async_routing(self):
+        """Test that __call__ routes to __acall__ when async"""
+
+        async def run_test():
+            async def async_get_response(request):
+                return Mock()
+
+            middleware = PosthogContextMiddleware(async_get_response)
+
+            # Verify routing happens
+            request = MockRequest()
+            result = middleware(request)
+
+            # Should be a coroutine from __acall__
+            self.assertTrue(asyncio.iscoroutine(result))
+            await result  # Clean up
+
+        asyncio.run(run_test())
+
+    def test_sync_path_direct_return(self):
+        """Test that sync path returns directly without coroutine"""
+        mock_response = Mock()
+
+        def sync_get_response(request):
+            return mock_response
+
+        middleware = PosthogContextMiddleware(sync_get_response)
+
+        request = MockRequest()
+        result = middleware(request)
+
+        # Should NOT be a coroutine
+        self.assertFalse(asyncio.iscoroutine(result))
+        self.assertEqual(result, mock_response)
+
 
 if __name__ == "__main__":
     unittest.main()

posthog/test/test_client.py

@@ -2,17 +2,18 @@ import time
 import unittest
 from datetime import datetime
 from uuid import uuid4
-from posthog.contexts import get_context_session_id, set_context_session, new_context
 
 import mock
 import six
 from parameterized import parameterized
 
 from posthog.client import Client
+from posthog.contexts import get_context_session_id, new_context, set_context_session
 from posthog.request import APIError
 from posthog.test.test_utils import FAKE_TEST_API_KEY
 from posthog.types import FeatureFlag, LegacyFlagMetadata
 from posthog.version import VERSION
+from posthog.contexts import tag
 
 
 class TestClient(unittest.TestCase):
@@ -647,8 +648,8 @@ class TestClient(unittest.TestCase):
                 timeout=3,
                 distinct_id="distinct_id",
                 groups={},
-                person_properties=None,
-                group_properties=None,
+                person_properties={},
+                group_properties={},
                 geoip_disable=True,
             )
 
@@ -711,8 +712,8 @@ class TestClient(unittest.TestCase):
                 timeout=12,
                 distinct_id="distinct_id",
                 groups={},
-                person_properties=None,
-                group_properties=None,
+                person_properties={},
+                group_properties={},
                 geoip_disable=False,
             )
 
@@ -751,6 +752,186 @@ class TestClient(unittest.TestCase):
 
             self.assertEqual(patch_flags.call_count, 0)
 
+    @mock.patch("posthog.client.flags")
+    def test_capture_with_send_feature_flags_options_only_evaluate_locally_true(
+        self, patch_flags
+    ):
+        """Test that SendFeatureFlagsOptions with only_evaluate_locally=True uses local evaluation"""
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                personal_api_key=FAKE_TEST_API_KEY,
+                sync_mode=True,
+            )
+
+            # Set up local flags
+            client.feature_flags = [
+                {
+                    "id": 1,
+                    "key": "local-flag",
+                    "active": True,
+                    "filters": {
+                        "groups": [
+                            {
+                                "properties": [{"key": "region", "value": "US"}],
+                                "rollout_percentage": 100,
+                            }
+                        ],
+                    },
+                }
+            ]
+
+            send_options = {
+                "only_evaluate_locally": True,
+                "person_properties": {"region": "US"},
+            }
+
+            msg_uuid = client.capture(
+                "test event", distinct_id="distinct_id", send_feature_flags=send_options
+            )
+
+            self.assertIsNotNone(msg_uuid)
+            self.assertFalse(self.failed)
+
+            # Verify flags() was not called (no remote evaluation)
+            patch_flags.assert_not_called()
+
+            # Check the message includes the local flag
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+
+            self.assertEqual(msg["properties"]["$feature/local-flag"], True)
+            self.assertEqual(msg["properties"]["$active_feature_flags"], ["local-flag"])
+
+    @mock.patch("posthog.client.flags")
+    def test_capture_with_send_feature_flags_options_only_evaluate_locally_false(
+        self, patch_flags
+    ):
+        """Test that SendFeatureFlagsOptions with only_evaluate_locally=False forces remote evaluation"""
+        patch_flags.return_value = {"featureFlags": {"remote-flag": "remote-value"}}
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                personal_api_key=FAKE_TEST_API_KEY,
+                sync_mode=True,
+            )
+
+            send_options = {
+                "only_evaluate_locally": False,
+                "person_properties": {"plan": "premium"},
+                "group_properties": {"company": {"type": "enterprise"}},
+            }
+
+            msg_uuid = client.capture(
+                "test event",
+                distinct_id="distinct_id",
+                groups={"company": "acme"},
+                send_feature_flags=send_options,
+            )
+
+            self.assertIsNotNone(msg_uuid)
+            self.assertFalse(self.failed)
+
+            # Verify flags() was called with the correct properties
+            patch_flags.assert_called_once()
+            call_args = patch_flags.call_args[1]
+            self.assertEqual(call_args["person_properties"], {"plan": "premium"})
+            self.assertEqual(
+                call_args["group_properties"], {"company": {"type": "enterprise"}}
+            )
+
+            # Check the message includes the remote flag
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+
+            self.assertEqual(msg["properties"]["$feature/remote-flag"], "remote-value")
+
+    @mock.patch("posthog.client.flags")
+    def test_capture_with_send_feature_flags_options_default_behavior(
+        self, patch_flags
+    ):
+        """Test that SendFeatureFlagsOptions without only_evaluate_locally defaults to remote evaluation"""
+        patch_flags.return_value = {"featureFlags": {"default-flag": "default-value"}}
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                personal_api_key=FAKE_TEST_API_KEY,
+                sync_mode=True,
+            )
+
+            send_options = {
+                "person_properties": {"subscription": "pro"},
+            }
+
+            msg_uuid = client.capture(
+                "test event", distinct_id="distinct_id", send_feature_flags=send_options
+            )
+
+            self.assertIsNotNone(msg_uuid)
+            self.assertFalse(self.failed)
+
+            # Verify flags() was called (default to remote evaluation)
+            patch_flags.assert_called_once()
+            call_args = patch_flags.call_args[1]
+            self.assertEqual(call_args["person_properties"], {"subscription": "pro"})
+
+            # Check the message includes the flag
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+
+            self.assertEqual(
+                msg["properties"]["$feature/default-flag"], "default-value"
+            )
+
+    @mock.patch("posthog.client.flags")
+    def test_capture_exception_with_send_feature_flags_options(self, patch_flags):
+        """Test that capture_exception also supports SendFeatureFlagsOptions"""
+        patch_flags.return_value = {"featureFlags": {"exception-flag": True}}
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                personal_api_key=FAKE_TEST_API_KEY,
+                sync_mode=True,
+            )
+
+            send_options = {
+                "only_evaluate_locally": False,
+                "person_properties": {"user_type": "admin"},
+            }
+
+            try:
+                raise ValueError("Test exception")
+            except ValueError as e:
+                msg_uuid = client.capture_exception(
+                    e, distinct_id="distinct_id", send_feature_flags=send_options
+                )
+
+            self.assertIsNotNone(msg_uuid)
+            self.assertFalse(self.failed)
+
+            # Verify flags() was called with the correct properties
+            patch_flags.assert_called_once()
+            call_args = patch_flags.call_args[1]
+            self.assertEqual(call_args["person_properties"], {"user_type": "admin"})
+
+            # Check the message includes the flag
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+
+            self.assertEqual(msg["event"], "$exception")
+            self.assertEqual(msg["properties"]["$feature/exception-flag"], True)
+
     def test_stringifies_distinct_id(self):
         # A large number that loses precision in node:
         # node -e "console.log(157963456373623802 + 1)" > 157963456373623800
@@ -1561,6 +1742,7 @@ class TestClient(unittest.TestCase):
             person_properties={"distinct_id": "some_id"},
             group_properties={},
             geoip_disable=True,
+            flag_keys_to_evaluate=["random_key"],
         )
         patch_flags.reset_mock()
         client.feature_enabled(
@@ -1575,6 +1757,7 @@ class TestClient(unittest.TestCase):
             person_properties={"distinct_id": "feature_enabled_distinct_id"},
             group_properties={},
             geoip_disable=True,
+            flag_keys_to_evaluate=["random_key"],
         )
         patch_flags.reset_mock()
         client.get_all_flags_and_payloads("all_flags_payloads_id")
@@ -1591,7 +1774,7 @@ class TestClient(unittest.TestCase):
 
     @mock.patch("posthog.client.Poller")
     @mock.patch("posthog.client.get")
-    def test_call_identify_fails(self, patch_get, patch_poll):
+    def test_call_identify_fails(self, patch_get, patch_poller):
         def raise_effect():
             raise Exception("http exception")
 
@@ -1635,6 +1818,7 @@ class TestClient(unittest.TestCase):
                 "instance": {"$group_key": "app.posthog.com"},
             },
             geoip_disable=False,
+            flag_keys_to_evaluate=["random_key"],
         )
 
         patch_flags.reset_mock()
@@ -1661,6 +1845,7 @@ class TestClient(unittest.TestCase):
                 "instance": {"$group_key": "app.posthog.com"},
             },
             geoip_disable=False,
+            flag_keys_to_evaluate=["random_key"],
         )
 
         patch_flags.reset_mock()
@@ -1877,7 +2062,7 @@ class TestClient(unittest.TestCase):
 
     def test_set_context_session_override_in_capture(self):
         """Test that explicit session ID overrides context session ID in capture"""
-        from posthog.contexts import set_context_session, new_context
+        from posthog.contexts import new_context, set_context_session
 
         with mock.patch("posthog.client.batch_post") as mock_post:
             client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True)
@@ -1903,3 +2088,381 @@ class TestClient(unittest.TestCase):
                 self.assertEqual(
                     msg["properties"]["$session_id"], "explicit-session-override"
                 )
+
+    @mock.patch("posthog.client.Poller")
+    @mock.patch("posthog.client.get")
+    def test_enable_local_evaluation_false_disables_poller(
+        self, patch_get, patch_poller
+    ):
+        """Test that when enable_local_evaluation=False, the poller is not started"""
+        patch_get.return_value = {
+            "flags": [
+                {"id": 1, "name": "Beta Feature", "key": "beta-feature", "active": True}
+            ],
+            "group_type_mapping": {},
+            "cohorts": {},
+        }
+
+        client = Client(
+            FAKE_TEST_API_KEY,
+            personal_api_key="test-personal-key",
+            enable_local_evaluation=False,
+        )
+
+        # Load feature flags should not start the poller
+        client.load_feature_flags()
+
+        # Assert that the poller was not created/started
+        patch_poller.assert_not_called()
+        # But the feature flags should still be loaded
+        patch_get.assert_called_once()
+        self.assertEqual(len(client.feature_flags), 1)
+        self.assertEqual(client.feature_flags[0]["key"], "beta-feature")
+
+    @mock.patch("posthog.client.Poller")
+    @mock.patch("posthog.client.get")
+    def test_enable_local_evaluation_true_starts_poller(self, patch_get, patch_poller):
+        """Test that when enable_local_evaluation=True (default), the poller is started"""
+        patch_get.return_value = {
+            "flags": [
+                {"id": 1, "name": "Beta Feature", "key": "beta-feature", "active": True}
+            ],
+            "group_type_mapping": {},
+            "cohorts": {},
+        }
+
+        client = Client(
+            FAKE_TEST_API_KEY,
+            personal_api_key="test-personal-key",
+            enable_local_evaluation=True,
+        )
+
+        # Load feature flags should start the poller
+        client.load_feature_flags()
+
+        # Assert that the poller was created and started
+        patch_poller.assert_called_once()
+        patch_get.assert_called_once()
+        self.assertEqual(len(client.feature_flags), 1)
+        self.assertEqual(client.feature_flags[0]["key"], "beta-feature")
+
+    @mock.patch("posthog.client.remote_config")
+    def test_get_remote_config_payload_works_without_poller(self, patch_remote_config):
+        """Test that get_remote_config_payload works without local evaluation enabled"""
+        patch_remote_config.return_value = {"test": "payload"}
+
+        client = Client(
+            FAKE_TEST_API_KEY,
+            personal_api_key="test-personal-key",
+            enable_local_evaluation=False,
+        )
+
+        # Should work without poller
+        result = client.get_remote_config_payload("test-flag")
+
+        self.assertEqual(result, {"test": "payload"})
+        patch_remote_config.assert_called_once_with(
+            "test-personal-key",
+            FAKE_TEST_API_KEY,
+            client.host,
+            "test-flag",
+            timeout=client.feature_flags_request_timeout_seconds,
+        )
+
+    def test_get_remote_config_payload_requires_personal_api_key(self):
+        """Test that get_remote_config_payload requires personal API key"""
+        client = Client(
+            FAKE_TEST_API_KEY,
+            enable_local_evaluation=False,
+        )
+
+        result = client.get_remote_config_payload("test-flag")
+
+        self.assertIsNone(result)
+
+    def test_parse_send_feature_flags_method(self):
+        """Test the _parse_send_feature_flags helper method"""
+        client = Client(FAKE_TEST_API_KEY, sync_mode=True)
+
+        # Test boolean True
+        result = client._parse_send_feature_flags(True)
+        expected = {
+            "should_send": True,
+            "only_evaluate_locally": None,
+            "person_properties": None,
+            "group_properties": None,
+            "flag_keys_filter": None,
+        }
+        self.assertEqual(result, expected)
+
+        # Test boolean False
+        result = client._parse_send_feature_flags(False)
+        expected = {
+            "should_send": False,
+            "only_evaluate_locally": None,
+            "person_properties": None,
+            "group_properties": None,
+            "flag_keys_filter": None,
+        }
+        self.assertEqual(result, expected)
+
+        # Test options dict with all fields
+        options = {
+            "only_evaluate_locally": True,
+            "person_properties": {"plan": "premium"},
+            "group_properties": {"company": {"type": "enterprise"}},
+        }
+        result = client._parse_send_feature_flags(options)
+        expected = {
+            "should_send": True,
+            "only_evaluate_locally": True,
+            "person_properties": {"plan": "premium"},
+            "group_properties": {"company": {"type": "enterprise"}},
+            "flag_keys_filter": None,
+        }
+        self.assertEqual(result, expected)
+
+        # Test options dict with partial fields
+        options = {"person_properties": {"user_id": "123"}}
+        result = client._parse_send_feature_flags(options)
+        expected = {
+            "should_send": True,
+            "only_evaluate_locally": None,
+            "person_properties": {"user_id": "123"},
+            "group_properties": None,
+            "flag_keys_filter": None,
+        }
+        self.assertEqual(result, expected)
+
+        # Test empty dict
+        result = client._parse_send_feature_flags({})
+        expected = {
+            "should_send": True,
+            "only_evaluate_locally": None,
+            "person_properties": None,
+            "group_properties": None,
+            "flag_keys_filter": None,
+        }
+        self.assertEqual(result, expected)
+
+        # Test invalid types
+        with self.assertRaises(TypeError) as cm:
+            client._parse_send_feature_flags("invalid")
+        self.assertIn("Invalid type for send_feature_flags", str(cm.exception))
+
+        with self.assertRaises(TypeError) as cm:
+            client._parse_send_feature_flags(123)
+        self.assertIn("Invalid type for send_feature_flags", str(cm.exception))
+
+        with self.assertRaises(TypeError) as cm:
+            client._parse_send_feature_flags(None)
+        self.assertIn("Invalid type for send_feature_flags", str(cm.exception))
+
+    @mock.patch("posthog.client.flags")
+    def test_capture_with_send_feature_flags_flag_keys_filter(self, patch_flags):
+        """Test that SendFeatureFlagsOptions with flag_keys_filter only evaluates specified flags"""
+        # When flag_keys_to_evaluate is provided, the API should only return the requested flags
+        patch_flags.return_value = {
+            "featureFlags": {
+                "flag1": "value1",
+                "flag3": "value3",
+            }
+        }
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                personal_api_key=FAKE_TEST_API_KEY,
+                sync_mode=True,
+            )
+
+            send_options = {
+                "flag_keys_filter": ["flag1", "flag3"],
+                "person_properties": {"subscription": "pro"},
+            }
+
+            msg_uuid = client.capture(
+                "test event", distinct_id="distinct_id", send_feature_flags=send_options
+            )
+
+            self.assertIsNotNone(msg_uuid)
+            self.assertFalse(self.failed)
+
+            # Verify flags() was called with flag_keys_to_evaluate
+            patch_flags.assert_called_once()
+            call_args = patch_flags.call_args[1]
+            self.assertEqual(call_args["flag_keys_to_evaluate"], ["flag1", "flag3"])
+            self.assertEqual(call_args["person_properties"], {"subscription": "pro"})
+
+            # Check the message includes only the filtered flags
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+
+            self.assertEqual(msg["properties"]["$feature/flag1"], "value1")
+            self.assertEqual(msg["properties"]["$feature/flag3"], "value3")
+            # flag2 should not be included since it wasn't requested
+            self.assertNotIn("$feature/flag2", msg["properties"])
+
+    @mock.patch("posthog.client.batch_post")
+    def test_get_feature_flag_result_with_empty_string_payload(self, patch_batch_post):
+        """Test that get_feature_flag_result returns a FeatureFlagResult when payload is empty string"""
+        client = Client(
+            FAKE_TEST_API_KEY,
+            personal_api_key="test_personal_api_key",
+            sync_mode=True,
+        )
+
+        # Set up local evaluation with a flag that has empty string payload
+        client.feature_flags = [
+            {
+                "id": 1,
+                "name": "Test flag",
+                "key": "test-flag",
+                "is_simple_flag": False,
+                "active": True,
+                "rollout_percentage": None,
+                "filters": {
+                    "groups": [
+                        {
+                            "properties": [],
+                            "rollout_percentage": None,
+                            "variant": "empty-variant",
+                        }
+                    ],
+                    "multivariate": {
+                        "variants": [
+                            {
+                                "key": "empty-variant",
+                                "name": "Empty Variant",
+                                "rollout_percentage": 100,
+                            }
+                        ]
+                    },
+                    "payloads": {"empty-variant": ""},  # Empty string payload
+                },
+            }
+        ]
+
+        # Test get_feature_flag_result
+        result = client.get_feature_flag_result(
+            "test-flag", "test-user", only_evaluate_locally=True
+        )
+
+        # Should return a FeatureFlagResult, not None
+        self.assertIsNotNone(result)
+        self.assertEqual(result.key, "test-flag")
+        self.assertEqual(result.get_value(), "empty-variant")
+        self.assertEqual(result.payload, "")  # Should be empty string, not None
+
+    @mock.patch("posthog.client.batch_post")
+    def test_get_all_flags_and_payloads_with_empty_string(self, patch_batch_post):
+        """Test that get_all_flags_and_payloads includes flags with empty string payloads"""
+        client = Client(
+            FAKE_TEST_API_KEY,
+            personal_api_key="test_personal_api_key",
+            sync_mode=True,
+        )
+
+        # Set up multiple flags with different payload types
+        client.feature_flags = [
+            {
+                "id": 1,
+                "name": "Flag with empty payload",
+                "key": "empty-payload-flag",
+                "is_simple_flag": False,
+                "active": True,
+                "filters": {
+                    "groups": [{"properties": [], "variant": "variant1"}],
+                    "multivariate": {
+                        "variants": [{"key": "variant1", "rollout_percentage": 100}]
+                    },
+                    "payloads": {"variant1": ""},  # Empty string
+                },
+            },
+            {
+                "id": 2,
+                "name": "Flag with normal payload",
+                "key": "normal-payload-flag",
+                "is_simple_flag": False,
+                "active": True,
+                "filters": {
+                    "groups": [{"properties": [], "variant": "variant2"}],
+                    "multivariate": {
+                        "variants": [{"key": "variant2", "rollout_percentage": 100}]
+                    },
+                    "payloads": {"variant2": "normal payload"},
+                },
+            },
+        ]
+
+        result = client.get_all_flags_and_payloads(
+            "test-user", only_evaluate_locally=True
+        )
+
+        # Check that both flags are included
+        self.assertEqual(result["featureFlags"]["empty-payload-flag"], "variant1")
+        self.assertEqual(result["featureFlags"]["normal-payload-flag"], "variant2")
+
+        # Check that empty string payload is included (not filtered out)
+        self.assertIn("empty-payload-flag", result["featureFlagPayloads"])
+        self.assertEqual(result["featureFlagPayloads"]["empty-payload-flag"], "")
+        self.assertEqual(
+            result["featureFlagPayloads"]["normal-payload-flag"], "normal payload"
+        )
+
+    def test_context_tags_added(self):
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True)
+
+            with new_context():
+                tag("random_tag", 12345)
+                client.capture("python test event", distinct_id="distinct_id")
+
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+            self.assertEqual(msg["properties"]["$context_tags"], ["random_tag"])
+
+    @mock.patch(
+        "posthog.client.Client._enqueue", side_effect=Exception("Unexpected error")
+    )
+    def test_methods_handle_exceptions(self, mock_enqueue):
+        """Test that all decorated methods handle exceptions gracefully."""
+        client = Client("test-key")
+
+        test_cases = [
+            ("capture", ["test_event"], {}),
+            ("set", [], {"distinct_id": "some-id", "properties": {"a": "b"}}),
+            ("set_once", [], {"distinct_id": "some-id", "properties": {"a": "b"}}),
+            ("group_identify", ["group-type", "group-key"], {}),
+            ("alias", ["some-id", "new-id"], {}),
+        ]
+
+        for method_name, args, kwargs in test_cases:
+            with self.subTest(method=method_name):
+                method = getattr(client, method_name)
+                result = method(*args, **kwargs)
+                self.assertEqual(result, None)
+
+    @mock.patch(
+        "posthog.client.Client._enqueue", side_effect=Exception("Expected error")
+    )
+    def test_debug_flag_re_raises_exceptions(self, mock_enqueue):
+        """Test that methods re-raise exceptions when debug=True."""
+        client = Client("test-key", debug=True)
+
+        test_cases = [
+            ("capture", ["test_event"], {}),
+            ("set", [], {"distinct_id": "some-id", "properties": {"a": "b"}}),
+            ("set_once", [], {"distinct_id": "some-id", "properties": {"a": "b"}}),
+            ("group_identify", ["group-type", "group-key"], {}),
+            ("alias", ["some-id", "new-id"], {}),
+        ]
+
+        for method_name, args, kwargs in test_cases:
+            with self.subTest(method=method_name):
+                method = getattr(client, method_name)
+                with self.assertRaises(Exception) as cm:
+                    method(*args, **kwargs)
+                self.assertEqual(str(cm.exception), "Expected error")

posthog/test/test_module.py

@@ -18,14 +18,6 @@ class TestModule(unittest.TestCase):
             "testsecret", host="http://localhost:8000", on_error=self.failed
         )
 
-    def test_no_api_key(self):
-        self.posthog.api_key = None
-        self.assertRaises(Exception, self.posthog.capture)
-
-    def test_no_host(self):
-        self.posthog.host = None
-        self.assertRaises(Exception, self.posthog.capture)
-
     def test_track(self):
         res = self.posthog.capture("python module event", distinct_id="distinct_id")
         self._assert_enqueue_result(res)

posthog/test/test_utils.py

@@ -1,3 +1,4 @@
+import time
 import unittest
 from dataclasses import dataclass
 from datetime import date, datetime, timedelta
@@ -12,6 +13,7 @@ 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"
@@ -173,3 +175,124 @@ class TestUtils(unittest.TestCase):
                 "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
+        )
+
+    def test_cache_basic_operations(self):
+        distinct_id = "user123"
+        flag_key = "test-flag"
+        flag_version = 1
+
+        # 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()
+
+    def test_cache_ttl_expiration(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
+        )
+
+        # Should be available immediately
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is not None
+
+        # 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

@@ -9,6 +9,27 @@ FlagValue = Union[bool, str]
 BeforeSendCallback = Callable[[dict[str, Any]], Optional[dict[str, Any]]]
 
 
+# Type alias for the send_feature_flags parameter
+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 } }
+    """
+
+    should_send: bool
+    only_evaluate_locally: Optional[bool]
+    person_properties: Optional[dict[str, Any]]
+    group_properties: Optional[dict[str, dict[str, Any]]]
+    flag_keys_filter: Optional[list[str]]
+
+
 @dataclass(frozen=True)
 class FlagReason:
     code: str
@@ -92,7 +113,7 @@ class FeatureFlag:
             variant=variant,
             reason=None,
             metadata=LegacyFlagMetadata(
-                payload=payload if payload else None,
+                payload=payload,
             ),
         )
 
@@ -160,7 +181,9 @@ class FeatureFlagResult:
             key=key,
             enabled=enabled,
             variant=variant,
-            payload=json.loads(payload) if isinstance(payload, str) else payload,
+            payload=json.loads(payload)
+            if isinstance(payload, str) and payload
+            else payload,
             reason=None,
         )
 
@@ -201,6 +224,7 @@ class FeatureFlagResult:
             payload=(
                 json.loads(details.metadata.payload)
                 if isinstance(details.metadata.payload, str)
+                and details.metadata.payload
                 else details.metadata.payload
             ),
             reason=details.reason.description if details.reason else None,
@@ -278,5 +302,7 @@ def to_payloads(response: FlagsResponse) -> Optional[dict[str, str]]:
     return {
         key: value.metadata.payload
         for key, value in response.get("flags", {}).items()
-        if isinstance(value, FeatureFlag) and value.enabled and value.metadata.payload
+        if isinstance(value, FeatureFlag)
+        and value.enabled
+        and value.metadata.payload is not None
     }

posthog/utils.py

@@ -1,6 +1,8 @@
+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
@@ -157,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)

posthog/version.py

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

remote_config_example.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+Simple test script for PostHog remote config endpoint.
+"""
+
+import posthog
+
+# Initialize PostHog client
+posthog.api_key = "phc_..."
+posthog.personal_api_key = "phs_..."  # or "phx_..."
+posthog.host = "http://localhost:8000"  # or "https://us.posthog.com"
+posthog.debug = True
+
+
+def test_remote_config():
+    """Test remote config payload retrieval."""
+    print("Testing remote config endpoint...")
+
+    # Test feature flag key - replace with an actual flag key from your project
+    flag_key = "unencrypted-remote-config-setting"
+
+    try:
+        # Get remote config payload
+        payload = posthog.get_remote_config_payload(flag_key)
+        print(f"✅ Success! Remote config payload for '{flag_key}': {payload}")
+
+    except Exception as e:
+        print(f"❌ Error getting remote config: {e}")
+
+
+if __name__ == "__main__":
+    test_remote_config()