Let UsageBase.details be None again

Author: DouweM

pydantic_ai_slim/pydantic_ai/messages.py

@@ -1016,6 +1016,7 @@ class ModelResponse:
 
     provider_details: Annotated[
         dict[str, Any] | None,
+        # `vendor_details` is deprecated, but we still want to support deserializing model responses stored in a DB before it was changed
         pydantic.Field(validation_alias=pydantic.AliasChoices('provider_details', 'vendor_details')),
     ] = None
     """Additional provider-specific details in a serializable format.
@@ -1025,7 +1026,9 @@ class ModelResponse:
     """
 
     provider_response_id: Annotated[
-        str | None, pydantic.Field(validation_alias=pydantic.AliasChoices('provider_response_id', 'vendor_id'))
+        str | None,
+        # `vendor_id` is deprecated, but we still want to support deserializing model responses stored in a DB before it was changed
+        pydantic.Field(validation_alias=pydantic.AliasChoices('provider_response_id', 'vendor_id')),
     ] = None
     """request ID as specified by the model provider. This can be used to track the specific request to the model."""
 

pydantic_ai_slim/pydantic_ai/usage.py

@@ -5,7 +5,7 @@
 from dataclasses import dataclass, fields
 from typing import Annotated
 
-from pydantic import AliasChoices, BeforeValidator, Field
+from pydantic import AliasChoices, Field
 from typing_extensions import deprecated, overload
 
 from . import _utils
@@ -16,15 +16,23 @@
 
 @dataclass(repr=False, kw_only=True)
 class UsageBase:
-    input_tokens: Annotated[int, Field(validation_alias=AliasChoices('input_tokens', 'request_tokens'))] = 0
+    input_tokens: Annotated[
+        int,
+        # `request_tokens` is deprecated, but we still want to support deserializing model responses stored in a DB before it was changed
+        Field(validation_alias=AliasChoices('input_tokens', 'request_tokens')),
+    ] = 0
     """Number of input/prompt tokens."""
 
     cache_write_tokens: int = 0
     """Number of tokens written to the cache."""
     cache_read_tokens: int = 0
     """Number of tokens read from the cache."""
 
-    output_tokens: Annotated[int, Field(validation_alias=AliasChoices('output_tokens', 'response_tokens'))] = 0
+    output_tokens: Annotated[
+        int,
+        # `response_tokens` is deprecated, but we still want to support deserializing model responses stored in a DB before it was changed
+        Field(validation_alias=AliasChoices('output_tokens', 'response_tokens')),
+    ] = 0
     """Number of output/completion tokens."""
 
     input_audio_tokens: int = 0
@@ -34,7 +42,7 @@ class UsageBase:
     output_audio_tokens: int = 0
     """Number of audio output tokens."""
 
-    details: Annotated[dict[str, int], BeforeValidator(lambda d: d or {})] = dataclasses.field(default_factory=dict)
+    details: dict[str, int] | None = None
     """Any extra details returned by the model."""
 
     @property
@@ -140,7 +148,7 @@ class RunUsage(UsageBase):
     output_tokens: int = 0
     """Total number of text output/completion tokens."""
 
-    details: dict[str, int] = dataclasses.field(default_factory=dict)
+    details: dict[str, int] | None = None
     """Any extra details returned by the model."""
 
     def incr(self, incr_usage: RunUsage | RequestUsage) -> None:
@@ -164,22 +172,25 @@ def __add__(self, other: RunUsage | RequestUsage) -> RunUsage:
         return new_usage
 
 
-def _incr_usage_tokens(slf: RunUsage | RequestUsage, incr_usage: RunUsage | RequestUsage) -> None:
+def _incr_usage_tokens(self: RunUsage | RequestUsage, incr_usage: RunUsage | RequestUsage) -> None:
     """Increment the usage in place.
 
     Args:
-        slf: The usage to increment.
+        self: The usage to increment.
         incr_usage: The usage to increment by.
     """
-    slf.input_tokens += incr_usage.input_tokens
-    slf.cache_write_tokens += incr_usage.cache_write_tokens
-    slf.cache_read_tokens += incr_usage.cache_read_tokens
-    slf.input_audio_tokens += incr_usage.input_audio_tokens
-    slf.cache_audio_read_tokens += incr_usage.cache_audio_read_tokens
-    slf.output_tokens += incr_usage.output_tokens
-
-    for key, value in incr_usage.details.items():
-        slf.details[key] = slf.details.get(key, 0) + value
+    self.input_tokens += incr_usage.input_tokens
+    self.cache_write_tokens += incr_usage.cache_write_tokens
+    self.cache_read_tokens += incr_usage.cache_read_tokens
+    self.input_audio_tokens += incr_usage.input_audio_tokens
+    self.cache_audio_read_tokens += incr_usage.cache_audio_read_tokens
+    self.output_tokens += incr_usage.output_tokens
+
+    if incr_usage.details is not None:
+        if self.details is None:
+            self.details = {}
+        for key, value in incr_usage.details.items():
+            self.details[key] = self.details.get(key, 0) + value
 
 
 @dataclass(repr=False, kw_only=True)

tests/test_messages.py

@@ -393,7 +393,6 @@ def test_pre_usage_refactor_messages_deserializable():
                 usage=RequestUsage(
                     input_tokens=13,
                     output_tokens=76,
-                    details={},
                 ),
                 model_name='gpt-5-2025-08-07',
                 timestamp=IsNow(tz=timezone.utc),