fix(ai): omit token counts the provider never reported (#906)

* fix(ai): omit token counts the provider never reported

Every integration wrote $ai_input_tokens: 0 and $ai_output_tokens: 0 when the provider never reported usage, so an interrupted stream priced as a free call downstream. Token counts are now written only when they trace back to a provider report: the shared capture paths, both embedding events, the LangChain callback and the Agents and Claude Agent SDK processors omit unreported counts, and the stream accumulators and response extractors no longer seed at zero.

A zero the provider reported is still sent as 0, so zero keeps meaning a real report of nothing. LangChain cache and reasoning counts follow the same rule instead of coalescing to 0, and the Agents processor's $ai_total_tokens is the sum of the reported sides, omitted when neither side reported.

Mirrors the posthog-js change (PostHog/posthog-js#4664). Ingestion distinguishes absent from zero since PostHog/posthog#90211 and older ingestion coalesces absent to 0 at read time, so this ships independently.

Generated-By: PostHog Desktop
Task-Id: ec0cc27f-fc40-4994-b153-2bfe74de1edf

* chore(ai): update public API snapshot for Optional embedding count

extract_gemini_embedding_token_count now returns Optional[int], returning None when no embedding carried a token count. Regenerated with make public_api_snapshot.

Generated-By: PostHog Desktop
Task-Id: ec0cc27f-fc40-4994-b153-2bfe74de1edf

Author: bernatixer

.sampo/changesets/omit-unreported-token-counts.md

@@ -0,0 +1,5 @@
+---
+pypi/posthog: patch
+---
+
+Omit `$ai_input_tokens` and `$ai_output_tokens` when the provider never reported usage, instead of sending `0`, so an interrupted stream no longer looks like a free call. A zero reported by the provider is still sent, and zero keeps meaning a real report of nothing. Covers the OpenAI, Anthropic, Gemini, LangChain, OpenAI Agents and Claude Agent SDK integrations.

posthog/ai/anthropic/_anthropic_stream.py

@@ -15,7 +15,7 @@ class _AnthropicStreamAccumulator:
     """Accumulates sync-neutral capture state from Anthropic stream events."""
 
     def __init__(self) -> None:
-        self.usage_stats: TokenUsage = TokenUsage(input_tokens=0, output_tokens=0)
+        self.usage_stats: TokenUsage = TokenUsage()
         self.accumulated_content = ""
         self.content_blocks: List[StreamingContentBlock] = []
         self.tools_in_progress: Dict[str, ToolInProgress] = {}

posthog/ai/anthropic/anthropic_converter.py

@@ -252,13 +252,16 @@ def extract_anthropic_usage_from_response(response: Any) -> TokenUsage:
     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 getattr(response, "usage", None) is None:
+        return TokenUsage()
+
+    result = TokenUsage()
+    input_tokens = getattr(response.usage, "input_tokens", None)
+    if input_tokens is not None:
+        result["input_tokens"] = input_tokens
+    output_tokens = getattr(response.usage, "output_tokens", None)
+    if output_tokens is not None:
+        result["output_tokens"] = output_tokens
 
     if hasattr(response.usage, "cache_read_input_tokens"):
         cache_read = response.usage.cache_read_input_tokens

posthog/ai/claude_agent_sdk/processor.py

@@ -45,10 +45,12 @@ class _GenerationData:
     """Data accumulated for a single LLM generation (one API call)."""
 
     model: Optional[str] = None
-    input_tokens: int = 0
-    output_tokens: int = 0
-    cache_read_input_tokens: int = 0
-    cache_creation_input_tokens: int = 0
+    # None when the provider never reported a count: absent means unknown,
+    # 0 is a report of nothing.
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    cache_read_input_tokens: Optional[int] = None
+    cache_creation_input_tokens: Optional[int] = None
     raw_usage: Optional[Dict[str, Any]] = None
     start_time: float = 0.0
     end_time: float = 0.0
@@ -79,13 +81,11 @@ def process_stream_event(self, event: "StreamEvent") -> None:
             message = raw.get("message", {})
             self._current.model = message.get("model")
             usage = message.get("usage", {})
-            self._current.input_tokens = usage.get("input_tokens", 0)
-            self._current.output_tokens = usage.get("output_tokens", 0)
-            self._current.cache_read_input_tokens = usage.get(
-                "cache_read_input_tokens", 0
-            )
+            self._current.input_tokens = usage.get("input_tokens")
+            self._current.output_tokens = usage.get("output_tokens")
+            self._current.cache_read_input_tokens = usage.get("cache_read_input_tokens")
             self._current.cache_creation_input_tokens = usage.get(
-                "cache_creation_input_tokens", 0
+                "cache_creation_input_tokens"
             )
             self._current.raw_usage = dict(usage)
 
@@ -410,8 +410,16 @@ def _emit_generation(
             "$ai_provider": "anthropic",
             "$ai_framework": "claude-agent-sdk",
             "$ai_model": gen.model,
-            "$ai_input_tokens": gen.input_tokens,
-            "$ai_output_tokens": gen.output_tokens,
+            **(
+                {"$ai_input_tokens": gen.input_tokens}
+                if gen.input_tokens is not None
+                else {}
+            ),
+            **(
+                {"$ai_output_tokens": gen.output_tokens}
+                if gen.output_tokens is not None
+                else {}
+            ),
             "$ai_latency": latency,
             **extra_props,
         }
@@ -472,8 +480,16 @@ def _emit_generation_from_result(
             "$ai_provider": "anthropic",
             "$ai_framework": "claude-agent-sdk",
             "$ai_model": model,
-            "$ai_input_tokens": usage.get("input_tokens", 0),
-            "$ai_output_tokens": usage.get("output_tokens", 0),
+            **(
+                {"$ai_input_tokens": usage["input_tokens"]}
+                if usage.get("input_tokens") is not None
+                else {}
+            ),
+            **(
+                {"$ai_output_tokens": usage["output_tokens"]}
+                if usage.get("output_tokens") is not None
+                else {}
+            ),
             "$ai_latency": result.duration_api_ms / 1000.0
             if result.duration_api_ms
             else 0,
@@ -494,8 +510,8 @@ def _emit_generation_from_result(
                 finalize_ai_content(output_choices, self._client),
             )
 
-        cache_read = usage.get("cache_read_input_tokens", 0)
-        cache_creation = usage.get("cache_creation_input_tokens", 0)
+        cache_read = usage.get("cache_read_input_tokens")
+        cache_creation = usage.get("cache_creation_input_tokens")
         if cache_read:
             properties["$ai_cache_read_input_tokens"] = cache_read
         if cache_creation:

posthog/ai/gemini/_shared.py

@@ -195,7 +195,9 @@ def _capture_embedding_outcome(
         error: Optional[Exception],
         latency: float,
     ) -> None:
-        input_tokens = extract_gemini_embedding_token_count(response) if response else 0
+        input_tokens = (
+            extract_gemini_embedding_token_count(response) if response else None
+        )
         event_properties = {
             "$ai_provider": "gemini",
             "$ai_model": model,
@@ -207,7 +209,9 @@ def _capture_embedding_outcome(
             "$ai_http_status": (
                 getattr(error, "status_code", 0) if error is not None else 200
             ),
-            "$ai_input_tokens": input_tokens,
+            # Omitted when the provider never reported a count: absent means
+            # unknown, 0 is a report of nothing.
+            **({"$ai_input_tokens": input_tokens} if input_tokens is not None else {}),
             "$ai_latency": latency,
             "$ai_trace_id": trace_id,
             "$ai_base_url": self._base_url,

posthog/ai/gemini/gemini.py

@@ -216,7 +216,7 @@ def _generate_content_streaming(
         **kwargs: Any,
     ):
         start_time = time.time()
-        usage_stats: TokenUsage = TokenUsage(input_tokens=0, output_tokens=0)
+        usage_stats: TokenUsage = TokenUsage()
         accumulated_content = []
         stop_reason: Optional[str] = None
 

posthog/ai/gemini/gemini_async.py

@@ -217,7 +217,7 @@ async def _generate_content_streaming(
         **kwargs: Any,
     ):
         start_time = time.time()
-        usage_stats: TokenUsage = TokenUsage(input_tokens=0, output_tokens=0)
+        usage_stats: TokenUsage = TokenUsage()
         accumulated_content = []
         stop_reason: Optional[str] = None
 

posthog/ai/gemini/gemini_converter.py

@@ -546,7 +546,7 @@ def extract_gemini_usage_from_response(response: Any) -> TokenUsage:
         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 TokenUsage()
 
     usage = _extract_usage_from_metadata(response.usage_metadata)
 
@@ -715,17 +715,19 @@ def format_gemini_streaming_output(
     return [{"role": "assistant", "content": [{"type": "text", "text": ""}]}]
 
 
-def extract_gemini_embedding_token_count(response) -> int:
+def extract_gemini_embedding_token_count(response) -> Optional[int]:
     """
     Extract total token count from a Gemini embed_content response.
     Token counts are only available per-embedding via Vertex AI's statistics.token_count.
-    Returns 0 if no token counts are available.
+    Returns None when no embedding carried a token count.
     """
     total = 0
+    reported = False
     if hasattr(response, "embeddings") and response.embeddings:
         for embedding in response.embeddings:
             if hasattr(embedding, "statistics") and embedding.statistics:
                 token_count = getattr(embedding.statistics, "token_count", None)
                 if token_count is not None:
                     total += int(token_count)
-    return total
+                    reported = True
+    return total if reported else None

posthog/ai/langchain/callbacks.py

@@ -664,11 +664,16 @@ def _capture_generation(
         else:
             # Add usage
             usage = _parse_usage(output, run.provider, run.model)
-            event_properties["$ai_input_tokens"] = usage.input_tokens
-            event_properties["$ai_output_tokens"] = usage.output_tokens
-            event_properties["$ai_cache_creation_input_tokens"] = (
-                usage.cache_write_tokens
-            )
+            # Omitted when the provider never reported a count: absent means
+            # unknown, 0 is a report of nothing.
+            if usage.input_tokens is not None:
+                event_properties["$ai_input_tokens"] = usage.input_tokens
+            if usage.output_tokens is not None:
+                event_properties["$ai_output_tokens"] = usage.output_tokens
+            if usage.cache_write_tokens is not None:
+                event_properties["$ai_cache_creation_input_tokens"] = (
+                    usage.cache_write_tokens
+                )
             if (
                 usage.cache_write_5m_tokens is not None
                 and usage.cache_write_1h_tokens is not None
@@ -679,8 +684,12 @@ def _capture_generation(
                 event_properties["$ai_cache_creation_1h_input_tokens"] = (
                     usage.cache_write_1h_tokens
                 )
-            event_properties["$ai_cache_read_input_tokens"] = usage.cache_read_tokens
-            event_properties["$ai_reasoning_tokens"] = usage.reasoning_tokens
+            if usage.cache_read_tokens is not None:
+                event_properties["$ai_cache_read_input_tokens"] = (
+                    usage.cache_read_tokens
+                )
+            if usage.reasoning_tokens is not None:
+                event_properties["$ai_reasoning_tokens"] = usage.reasoning_tokens
 
             # Generation results
             generation_result = output.generations[-1]
@@ -875,7 +884,7 @@ def _parse_usage_model(
     }
     normalized_usage = ModelUsage(
         **{
-            dataclass_key: parsed_usage.get(mapped_key) or 0
+            dataclass_key: parsed_usage.get(mapped_key)
             for mapped_key, dataclass_key in field_mapping.items()
         },
         cache_write_5m_tokens=parsed_usage.get("cache_write_5m"),

posthog/ai/openai/_embeddings.py

@@ -18,7 +18,7 @@ def _capture_embedding_event(
 ) -> None:
     """Build and capture telemetry shared by sync and async embedding wrappers."""
     usage = getattr(response, "usage", None)
-    input_tokens = getattr(usage, "prompt_tokens", 0) if usage else 0
+    input_tokens = getattr(usage, "prompt_tokens", None) if usage else None
 
     event_properties = {
         "$ai_provider": "openai",
@@ -29,7 +29,9 @@ def _capture_embedding_event(
             finalize_ai_content(request_kwargs.get("input"), posthog_client),
         ),
         "$ai_http_status": 200,
-        "$ai_input_tokens": input_tokens,
+        # Omitted when the provider never reported a count: absent means
+        # unknown, 0 is a report of nothing.
+        **({"$ai_input_tokens": input_tokens} if input_tokens is not None else {}),
         "$ai_latency": latency,
         "$ai_trace_id": trace_id,
         "$ai_base_url": str(base_url),