posthog 6.7.2__py3-none-any.whl → 6.9.0__py3-none-any.whl

posthog/ai/utils.py

@@ -1,10 +1,9 @@
 import time
 import uuid
-from typing import Any, Callable, Dict, Optional
-
+from typing import Any, Callable, Dict, List, Optional, cast
 
 from posthog.client import Client as PostHogClient
-from posthog.ai.types import StreamingEventData, StreamingUsageStats
+from posthog.ai.types import FormattedMessage, StreamingEventData, TokenUsage
 from posthog.ai.sanitization import (
     sanitize_openai,
     sanitize_anthropic,
@@ -14,7 +13,7 @@ from posthog.ai.sanitization import (
 
 
 def merge_usage_stats(
-    target: Dict[str, int], source: StreamingUsageStats, mode: str = "incremental"
+    target: TokenUsage, source: TokenUsage, mode: str = "incremental"
 ) -> None:
     """
     Merge streaming usage statistics into target dict, handling None values.
@@ -25,19 +24,58 @@ def merge_usage_stats(
 
     Args:
         target: Dictionary to update with usage stats
-        source: StreamingUsageStats that may contain None values
+        source: TokenUsage that may contain None values
         mode: Either "incremental" or "cumulative"
     """
     if mode == "incremental":
         # Add new values to existing totals
-        for key, value in source.items():
-            if value is not None and isinstance(value, int):
-                target[key] = target.get(key, 0) + value
+        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
+
+        source_web_search = source.get("web_search_count")
+        if source_web_search is not None:
+            current = target.get("web_search_count") or 0
+            target["web_search_count"] = max(current, source_web_search)
+
     elif mode == "cumulative":
         # Replace with latest values (already cumulative)
-        for key, value in source.items():
-            if value is not None and isinstance(value, int):
-                target[key] = value
+        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"]
+        if source.get("web_search_count") is not None:
+            target["web_search_count"] = source["web_search_count"]
+
     else:
         raise ValueError(f"Invalid mode: {mode}. Must be 'incremental' or 'cumulative'")
 
@@ -64,74 +102,31 @@ 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
-
-        # 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
+        from posthog.ai.openai.openai_converter import (
+            extract_openai_usage_from_response,
+        )
 
-        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):
@@ -169,9 +164,12 @@ def extract_available_tool_calls(provider: str, kwargs: Dict[str, Any]):
         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):
+def merge_system_prompt(
+    kwargs: Dict[str, Any], provider: str
+) -> List[FormattedMessage]:
     """
     Merge system prompts and format messages for the given provider.
     """
@@ -182,14 +180,15 @@ def merge_system_prompt(kwargs: Dict[str, Any], provider: str):
         system = kwargs.get("system")
         return format_anthropic_input(messages, system)
     elif provider == "gemini":
-        from posthog.ai.gemini.gemini_converter import format_gemini_input
+        from posthog.ai.gemini.gemini_converter import format_gemini_input_with_system
 
         contents = kwargs.get("contents", [])
-        return format_gemini_input(contents)
+        config = kwargs.get("config")
+        return format_gemini_input_with_system(contents, config)
     elif provider == "openai":
-        # For OpenAI, handle both Chat Completions and Responses API
         from posthog.ai.openai.openai_converter import format_openai_input
 
+        # For OpenAI, handle both Chat Completions and Responses API
         messages_param = kwargs.get("messages")
         input_param = kwargs.get("input")
 
@@ -200,9 +199,11 @@ def merge_system_prompt(kwargs: Dict[str, Any], provider: str):
         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
+                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:
@@ -220,9 +221,11 @@ def merge_system_prompt(kwargs: Dict[str, Any], provider: str):
                 )
             else:
                 # Create a new system message with instructions
-                messages = [
-                    {"role": "system", "content": kwargs.get("instructions")}
-                ] + messages
+                instruction_msg = cast(
+                    FormattedMessage,
+                    {"role": "system", "content": kwargs.get("instructions")},
+                )
+                messages = [instruction_msg] + messages
 
         return messages
 
@@ -250,7 +253,7 @@ def call_llm_and_track_usage(
     response = None
     error = None
     http_status = 200
-    usage: Dict[str, Any] = {}
+    usage: TokenUsage = TokenUsage()
     error_params: Dict[str, Any] = {}
 
     try:
@@ -305,27 +308,21 @@ def call_llm_and_track_usage(
         if available_tool_calls:
             event_properties["$ai_tools"] = available_tool_calls
 
-        if (
-            usage.get("cache_read_input_tokens") is not None
-            and usage.get("cache_read_input_tokens", 0) > 0
-        ):
-            event_properties["$ai_cache_read_input_tokens"] = usage.get(
-                "cache_read_input_tokens", 0
-            )
+        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("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_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 (
-            usage.get("reasoning_tokens") is not None
-            and usage.get("reasoning_tokens", 0) > 0
-        ):
-            event_properties["$ai_reasoning_tokens"] = usage.get("reasoning_tokens", 0)
+        reasoning = usage.get("reasoning_tokens")
+        if reasoning is not None and reasoning > 0:
+            event_properties["$ai_reasoning_tokens"] = reasoning
+
+        web_search_count = usage.get("web_search_count")
+        if web_search_count is not None and web_search_count > 0:
+            event_properties["$ai_web_search_count"] = web_search_count
 
         if posthog_distinct_id is None:
             event_properties["$process_person_profile"] = False
@@ -367,7 +364,7 @@ async def call_llm_and_track_usage_async(
     response = None
     error = None
     http_status = 200
-    usage: Dict[str, Any] = {}
+    usage: TokenUsage = TokenUsage()
     error_params: Dict[str, Any] = {}
 
     try:
@@ -422,21 +419,21 @@ async def call_llm_and_track_usage_async(
         if available_tool_calls:
             event_properties["$ai_tools"] = available_tool_calls
 
-        if (
-            usage.get("cache_read_input_tokens") is not None
-            and usage.get("cache_read_input_tokens", 0) > 0
-        ):
-            event_properties["$ai_cache_read_input_tokens"] = usage.get(
-                "cache_read_input_tokens", 0
-            )
+        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("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_creation = usage.get("cache_creation_input_tokens")
+        if cache_creation is not None and cache_creation > 0:
+            event_properties["$ai_cache_creation_input_tokens"] = cache_creation
+
+        reasoning = usage.get("reasoning_tokens")
+        if reasoning is not None and reasoning > 0:
+            event_properties["$ai_reasoning_tokens"] = reasoning
+
+        web_search_count = usage.get("web_search_count")
+        if web_search_count is not None and web_search_count > 0:
+            event_properties["$ai_web_search_count"] = web_search_count
 
         if posthog_distinct_id is None:
             event_properties["$process_person_profile"] = False
@@ -559,6 +556,15 @@ def capture_streaming_event(
             if value is not None and isinstance(value, int) and value > 0:
                 event_properties[f"$ai_{field}"] = value
 
+    # Add web search count if present (all providers)
+    web_search_count = event_data["usage_stats"].get("web_search_count")
+    if (
+        web_search_count is not None
+        and isinstance(web_search_count, int)
+        and web_search_count > 0
+    ):
+        event_properties["$ai_web_search_count"] = web_search_count
+
     # Handle provider-specific fields
     if (
         event_data["provider"] == "openai"

posthog/client.py

@@ -19,8 +19,15 @@ from posthog.exception_utils import (
     handle_in_app,
     exception_is_already_captured,
     mark_exception_as_captured,
+    try_attach_code_variables_to_frames,
+    DEFAULT_CODE_VARIABLES_MASK_PATTERNS,
+    DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS,
+)
+from posthog.feature_flags import (
+    InconclusiveMatchError,
+    RequiresServerEvaluation,
+    match_feature_flag_properties,
 )
-from posthog.feature_flags import InconclusiveMatchError, match_feature_flag_properties
 from posthog.poller import Poller
 from posthog.request import (
     DEFAULT_HOST,
@@ -35,6 +42,9 @@ from posthog.contexts import (
     _get_current_context,
     get_context_distinct_id,
     get_context_session_id,
+    get_capture_exception_code_variables_context,
+    get_code_variables_mask_patterns_context,
+    get_code_variables_ignore_patterns_context,
     new_context,
 )
 from posthog.types import (
@@ -56,7 +66,6 @@ from posthog.utils import (
     SizeLimitedDict,
     clean,
     guess_timezone,
-    remove_trailing_slash,
     system_context,
 )
 from posthog.version import VERSION
@@ -99,6 +108,34 @@ def add_context_tags(properties):
     return properties
 
 
+def no_throw(default_return=None):
+    """
+    Decorator to prevent raising exceptions from public API methods.
+    Note that this doesn't prevent errors from propagating via `on_error`.
+    Exceptions will still be raised if the debug flag is enabled.
+
+    Args:
+        default_return: Value to return on exception (default: None)
+    """
+
+    def decorator(func):
+        from functools import wraps
+
+        @wraps(func)
+        def wrapper(self, *args, **kwargs):
+            try:
+                return func(self, *args, **kwargs)
+            except Exception as e:
+                if self.debug:
+                    raise e
+                self.log.exception(f"Error in {func.__name__}: {e}")
+                return default_return
+
+        return wrapper
+
+    return decorator
+
+
 class Client(object):
     """
     This is the SDK reference for the PostHog Python SDK.
@@ -147,6 +184,9 @@ class Client(object):
         before_send=None,
         flag_fallback_cache_url=None,
         enable_local_evaluation=True,
+        capture_exception_code_variables=False,
+        code_variables_mask_patterns=None,
+        code_variables_ignore_patterns=None,
     ):
         """
         Initialize a new PostHog client instance.
@@ -202,6 +242,18 @@ class Client(object):
         self.privacy_mode = privacy_mode
         self.enable_local_evaluation = enable_local_evaluation
 
+        self.capture_exception_code_variables = capture_exception_code_variables
+        self.code_variables_mask_patterns = (
+            code_variables_mask_patterns
+            if code_variables_mask_patterns is not None
+            else DEFAULT_CODE_VARIABLES_MASK_PATTERNS
+        )
+        self.code_variables_ignore_patterns = (
+            code_variables_ignore_patterns
+            if code_variables_ignore_patterns is not None
+            else DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS
+        )
+
         if project_root is None:
             try:
                 project_root = os.getcwd()
@@ -481,6 +533,7 @@ class Client(object):
 
         return normalize_flags_response(resp_data)
 
+    @no_throw()
     def capture(
         self, event: str, **kwargs: Unpack[OptionalCaptureArgs]
     ) -> Optional[str]:
@@ -657,6 +710,7 @@ class Client(object):
                 f"Expected bool or dict."
             )
 
+    @no_throw()
     def set(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
         """
         Set properties on a person profile.
@@ -690,6 +744,8 @@ class Client(object):
 
         Category:
             Identification
+
+        Note: This method will not raise exceptions. Errors are logged.
         """
         distinct_id = kwargs.get("distinct_id", None)
         properties = kwargs.get("properties", None)
@@ -716,6 +772,7 @@ class Client(object):
 
         return self._enqueue(msg, disable_geoip)
 
+    @no_throw()
     def set_once(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
         """
         Set properties on a person profile only if they haven't been set before.
@@ -734,6 +791,8 @@ class Client(object):
 
         Category:
             Identification
+
+        Note: This method will not raise exceptions. Errors are logged.
         """
         distinct_id = kwargs.get("distinct_id", None)
         properties = kwargs.get("properties", None)
@@ -759,6 +818,7 @@ class Client(object):
 
         return self._enqueue(msg, disable_geoip)
 
+    @no_throw()
     def group_identify(
         self,
         group_type: str,
@@ -791,6 +851,8 @@ class Client(object):
 
         Category:
             Identification
+
+        Note: This method will not raise exceptions. Errors are logged.
         """
         properties = properties or {}
 
@@ -815,6 +877,7 @@ class Client(object):
 
         return self._enqueue(msg, disable_geoip)
 
+    @no_throw()
     def alias(
         self,
         previous_id: str,
@@ -840,6 +903,8 @@ class Client(object):
 
         Category:
             Identification
+
+        Note: This method will not raise exceptions. Errors are logged.
         """
         (distinct_id, personless) = get_identity_state(distinct_id)
 
@@ -932,10 +997,37 @@ class Client(object):
                     "value"
                 ),
                 "$exception_list": all_exceptions_with_trace_and_in_app,
-                "$exception_personURL": f"{remove_trailing_slash(self.raw_host)}/project/{self.api_key}/person/{distinct_id}",
                 **properties,
             }
 
+            context_enabled = get_capture_exception_code_variables_context()
+            context_mask = get_code_variables_mask_patterns_context()
+            context_ignore = get_code_variables_ignore_patterns_context()
+
+            enabled = (
+                context_enabled
+                if context_enabled is not None
+                else self.capture_exception_code_variables
+            )
+            mask_patterns = (
+                context_mask
+                if context_mask is not None
+                else self.code_variables_mask_patterns
+            )
+            ignore_patterns = (
+                context_ignore
+                if context_ignore is not None
+                else self.code_variables_ignore_patterns
+            )
+
+            if enabled:
+                try_attach_code_variables_to_frames(
+                    all_exceptions_with_trace_and_in_app,
+                    exc_info,
+                    mask_patterns=mask_patterns,
+                    ignore_patterns=ignore_patterns,
+                )
+
             if self.log_captured_exceptions:
                 self.log.exception(exception, extra=kwargs)
 
@@ -1543,7 +1635,7 @@ class Client(object):
                     self.log.debug(
                         f"Successfully computed flag locally: {key} -> {response}"
                     )
-                except InconclusiveMatchError as e:
+                except (RequiresServerEvaluation, InconclusiveMatchError) as e:
                     self.log.debug(f"Failed to compute flag {key} locally: {e}")
                 except Exception as e:
                     self.log.exception(

posthog/contexts.py

@@ -22,6 +22,9 @@ class ContextScope:
         self.session_id: Optional[str] = None
         self.distinct_id: Optional[str] = None
         self.tags: Dict[str, Any] = {}
+        self.capture_exception_code_variables: Optional[bool] = None
+        self.code_variables_mask_patterns: Optional[list] = None
+        self.code_variables_ignore_patterns: Optional[list] = None
 
     def set_session_id(self, session_id: str):
         self.session_id = session_id
@@ -32,6 +35,15 @@ class ContextScope:
     def add_tag(self, key: str, value: Any):
         self.tags[key] = value
 
+    def set_capture_exception_code_variables(self, enabled: bool):
+        self.capture_exception_code_variables = enabled
+
+    def set_code_variables_mask_patterns(self, mask_patterns: list):
+        self.code_variables_mask_patterns = mask_patterns
+
+    def set_code_variables_ignore_patterns(self, ignore_patterns: list):
+        self.code_variables_ignore_patterns = ignore_patterns
+
     def get_parent(self):
         return self.parent
 
@@ -59,6 +71,27 @@ class ContextScope:
             tags.update(new_tags)
         return tags
 
+    def get_capture_exception_code_variables(self) -> Optional[bool]:
+        if self.capture_exception_code_variables is not None:
+            return self.capture_exception_code_variables
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_capture_exception_code_variables()
+        return None
+
+    def get_code_variables_mask_patterns(self) -> Optional[list]:
+        if self.code_variables_mask_patterns is not None:
+            return self.code_variables_mask_patterns
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_code_variables_mask_patterns()
+        return None
+
+    def get_code_variables_ignore_patterns(self) -> Optional[list]:
+        if self.code_variables_ignore_patterns is not None:
+            return self.code_variables_ignore_patterns
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_code_variables_ignore_patterns()
+        return None
+
 
 _context_stack: contextvars.ContextVar[Optional[ContextScope]] = contextvars.ContextVar(
     "posthog_context_stack", default=None
@@ -243,6 +276,54 @@ def get_context_distinct_id() -> Optional[str]:
     return None
 
 
+def set_capture_exception_code_variables_context(enabled: bool) -> None:
+    """
+    Set whether code variables are captured for the current context.
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_capture_exception_code_variables(enabled)
+
+
+def set_code_variables_mask_patterns_context(mask_patterns: list) -> None:
+    """
+    Variable names matching these patterns will be masked with *** when capturing code variables.
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_code_variables_mask_patterns(mask_patterns)
+
+
+def set_code_variables_ignore_patterns_context(ignore_patterns: list) -> None:
+    """
+    Variable names matching these patterns will be ignored completely when capturing code variables.
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_code_variables_ignore_patterns(ignore_patterns)
+
+
+def get_capture_exception_code_variables_context() -> Optional[bool]:
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_capture_exception_code_variables()
+    return None
+
+
+def get_code_variables_mask_patterns_context() -> Optional[list]:
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_code_variables_mask_patterns()
+    return None
+
+
+def get_code_variables_ignore_patterns_context() -> Optional[list]:
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_code_variables_ignore_patterns()
+    return None
+
+
 F = TypeVar("F", bound=Callable[..., Any])