Add comments for the validation aliases

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 the name 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 the name 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

@@ -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 the name 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 the name was changed
+        Field(validation_alias=AliasChoices('output_tokens', 'response_tokens')),
+    ] = 0
     """Number of output/completion tokens."""
 
     input_audio_tokens: int = 0
@@ -34,7 +42,11 @@ 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: Annotated[
+        dict[str, int],
+        # `details` can not be `None` any longer, but we still want to support deserializing model responses stored in a DB before this was changed
+        BeforeValidator(lambda d: d or {}),
+    ] = dataclasses.field(default_factory=dict)
     """Any extra details returned by the model."""
 
     @property