Add local timestamps to request and response models - include provider timestamp in `provider_details` #3598

dsfaccini · 2025-11-30T00:24:22Z

Closes #1996

This is an attempt at adding a timestamp field directly on ModelRequest. This PR also overrides the timestamp in ModelResponse that is set to the value returned by the provider (created or created_at in most cases).

Previously, only the response got a timestamp. The request's timestamp was set by the first part. The problem main with this approach is that some providers, like openai, return unix time (seconds passed since unix epoch), which for very fast requests can mean (as far as the user sees), that the response's timestamp is earlier that the request's.

Thus for absolute certainty that this is not the case, this PR sets both timestamps locally. The provider's timestamp is still stored in the models, in the response's provider_details['timestamp'].

Many tests needed adjusting because the timestamp field now becomes part of every snapshot. If this is undesired we could set the timestamp to be a private field in the model? I don't know exactly how that would go but there must be a way :).

Note: I see one commit from #3592 snuck into here, will be irrelevant when that merges.

Clarify that agents can be produced by a factory function if preferred.

The ModelRequest snapshots for Google/Vertex URL input tests were missing the timestamp field that was added in the parent commit. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

DouweM · 2025-12-02T16:48:05Z

pydantic_ai_slim/pydantic_ai/messages.py


    _: KW_ONLY

+    timestamp: datetime = field(default_factory=_now_utc)


I don't think this should have a default, as it would be filled in for old requests without this field when they are deserialized and give the false impression that this date is accurate.

that makes sense

DouweM · 2025-12-02T16:48:47Z

pydantic_ai_slim/pydantic_ai/models/google.py

        raw_finish_reason = candidate.finish_reason
        if raw_finish_reason:  # pragma: no branch
            vendor_details = {'finish_reason': raw_finish_reason.value}
+            if response.create_time is not None:


This should be done separately from whether this a finish reason

DouweM · 2025-12-02T16:49:17Z

pydantic_ai_slim/pydantic_ai/models/google.py

            _model_name=first_chunk.model_version or self._model_name,
            _response=peekable_response,
-            _timestamp=first_chunk.create_time or _utils.now_utc(),
+            _timestamp=_utils.now_utc(),


Could this be a default or something, so we don't need to repeat this?

DouweM · 2025-12-02T17:28:10Z

pydantic_ai_slim/pydantic_ai/models/groq.py

    def _process_response(self, response: chat.ChatCompletion) -> ModelResponse:
        """Process a non-streamed response, and prepare a message to return."""
-        timestamp = number_to_datetime(response.created)
+        timestamp = _utils.now_utc()


We can drop this right, because the field already has a default?

DouweM · 2025-12-02T17:29:13Z

pydantic_ai_slim/pydantic_ai/models/openai.py

            _provider_name=self._provider.name,
            _provider_url=self._provider.base_url,
+            # type of created_at is float but it's actually a Unix timestamp in seconds
+            _provider_timestamp=int(first_chunk.response.created_at),


Why aren't we using number_to_datetime anymore?

we set _provider_timestamp which is an int, when we pass that into the provider_details we do the conversion to datetime

this cast makes it seem like we're losing precision here but in reality those are seconds, don't know why the streaming model has it as a float

will double-check in case I oversaw something but this is intentional

DouweM · 2025-12-02T17:34:50Z

pydantic_ai_slim/pydantic_ai/models/openrouter.py

+            # After the chunk with native_finish_reason 'completed', OpenRouter sends one more
+            # chunk with usage data (see cassette test_openrouter_stream_with_native_options.yaml)
+            # which has native_finish_reason: null. Since provider_details is replaced on each
+            # chunk, we need to carry forward the finish_reason from the previous chunk.


Why was this not necessary previously?

https://github.com/pydantic/pydantic-ai/pull/3598/files#r2582463861

just from following the logic it seems that: on the last chunk _map_provider_details was returning an empty dict, so it wasn't overriding the provider_details. Now the dict is by default not empty (because of the timestamp) so it overrides the finish_reason: 'completed' with None.

Makes me wonder now if the we should have separate provider_details['timestamp'] for the first and last chunks?

DouweM · 2025-12-02T17:35:04Z

pydantic_ai_slim/pydantic_ai/toolsets/fastmcp.py

    if isinstance(part, TextContent):
        return part.text
-    elif isinstance(part, ImageContent | AudioContent):
+    elif isinstance(part, (ImageContent, AudioContent)):


Please restore this, unions ftw

dsfaccini · 2025-12-02T18:59:41Z

tests/models/test_openrouter.py

+        assert stream.provider_details == snapshot(
+            {
+                'timestamp': datetime.datetime(2025, 11, 2, 6, 14, 57, tzinfo=datetime.timezone.utc),
+                'finish_reason': 'completed',
+                'cost': 0.00333825,
+                'upstream_inference_cost': None,
+                'is_byok': False,
+                'downstream_provider': 'xAI',
+            }
+        )


idk why this wasn't a problem before but from the snapshot alone it seems like this test hasn't been reran in a while, right?

- remove default timestamp on ModelResponse and set it manually - adjust tests

dsfaccini · 2025-12-02T22:37:43Z

pydantic_ai_slim/pydantic_ai/messages.py

+    timestamp: datetime | None = None
+    """The timestamp when the request was sent to the model."""
+


ModelRequest.timestamp needs to be None by default for backwards compat

DouweM · 2025-12-04T15:29:56Z

docs/agents.md


 !!! tip "Agents are designed for reuse, like FastAPI Apps"
-    Agents are intended to be instantiated once (frequently as module globals) and reused throughout your application, similar to a small [FastAPI][fastapi.FastAPI] app or an [APIRouter][fastapi.APIRouter].
+    Agents can be instantiated once as a module global and reused throughout your application, similar to a small [FastAPI][fastapi.FastAPI] app or an [APIRouter][fastapi.APIRouter], or be created dynamically by a factory function like `get_agent('agent-type')`, whichever you prefer.


Remove this from this PR please ;)

this will go away when I update the branch

DouweM · 2025-12-04T15:31:25Z

pydantic_ai_slim/pydantic_ai/_agent_graph.py

                parts.append(_messages.UserPromptPart(self.user_prompt))

-            next_message = _messages.ModelRequest(parts=parts)
+            next_message = _messages.ModelRequest(parts=parts, timestamp=now_utc())


Let's se it just once on next_message below like we do with instructions, instead of adding it to 2 constructors

DouweM · 2025-12-04T15:31:45Z

pydantic_ai_slim/pydantic_ai/_agent_graph.py

        assert not self._did_stream, 'stream() should only be called once per node'

        model_settings, model_request_parameters, message_history, run_context = await self._prepare_request(ctx)
+        self.request.timestamp = now_utc()


Actually if we have it here we don't need to set it above right?

yeah that makes sense, I wasn't totally sure about this line bc I ran into an issue with the temporal tests, but that issue was unrelated so this can stay. I'll remove the unnecessary assignments

DouweM · 2025-12-04T15:32:37Z

pydantic_ai_slim/pydantic_ai/_agent_graph.py

                    instructions = await ctx.deps.get_instructions(run_context)
                    self._next_node = ModelRequestNode[DepsT, NodeRunEndT](
-                        _messages.ModelRequest(parts=[], instructions=instructions)
+                        _messages.ModelRequest(parts=[], instructions=instructions, timestamp=now_utc())


Same as above; if we set the timestamp already before sending model.request, we don't need it here right?

DouweM · 2025-12-04T15:33:13Z

pydantic_ai_slim/pydantic_ai/_agent_graph.py

                merged_message = _messages.ModelRequest(
-                    parts=parts,
-                    instructions=last_message.instructions or message.instructions,
+                    parts=parts, instructions=last_message.instructions or message.instructions, timestamp=now_utc()


We should definitely not create a new timestamp here, but use one of the existing ones

dsfaccini and others added 10 commits November 28, 2025 12:42

Clarify usage of agent factories

8d52d65

Clarify that agents can be produced by a factory function if preferred.

add timestamps and update test snapshots

8c69124

fix tests

97cad05

coverage

e041398

improve code

ed199ca

fix groq test

47af45e

covergae

f9efa8a

coverage

7722ee9

add note

bf1c640

DouweM requested changes Dec 2, 2025

View reviewed changes

DouweM self-assigned this Dec 2, 2025

DouweM added the awaiting author revision label Dec 2, 2025

dsfaccini commented Dec 2, 2025

View reviewed changes

dsfaccini added 2 commits December 2, 2025 16:15

- set default timestamp on StreamResponseModels

76aad15

- remove default timestamp on ModelResponse and set it manually - adjust tests

ModelRequest.timestamp=None by default for backwards compat

0e4500a

dsfaccini commented Dec 2, 2025

View reviewed changes

dsfaccini marked this pull request as ready for review December 3, 2025 16:13

DouweM requested changes Dec 4, 2025

View reviewed changes

dsfaccini added 11 commits December 4, 2025 10:42

Merge branch 'main' into request-reponse-timestamps

29e84ae

timestamp's set only in one place

5d0eff6

Merge branch 'main' into request-reponse-timestamps

b895578

make sure last request always has timestamp

54bcb92

Merge branch 'main' into request-reponse-timestamps

bad15b5

fix new tests

9f9bf06

fix timestamps

4176971

fix test openai responses test and remove empty provider dicts

8652eb1

add signatures

e811f4e

re-add reset to signature and pd

a501928

fix snapshots

8e1670e

coverage

702b216


		_: KW_ONLY

		timestamp: datetime = field(default_factory=_now_utc)

		timestamp: datetime \| None = None
		"""The timestamp when the request was sent to the model."""

Add local timestamps to request and response models - include provider timestamp in provider_details #3598

Are you sure you want to change the base?

Add local timestamps to request and response models - include provider timestamp in provider_details #3598

Uh oh!

Conversation

dsfaccini commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add local timestamps to request and response models - include provider timestamp in `provider_details` #3598

Add local timestamps to request and response models - include provider timestamp in `provider_details` #3598

dsfaccini commented Nov 30, 2025 •

edited

Loading