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

"type of created_at is float but it's actually a Unix timestamp in seconds"

That depends on the API right? OpenAI may return a timestamp with 0 decimals, but maybe others actually send a float using the decimals for milliseconds.

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?

Yeah please see if there's a way to clean up this logic. It may be better to always merge the new dict into the existing dict; that will have the same outcome of preserving the finish reason right?

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

That warrants a code comment!

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

DouweM · 2025-12-10T17:09:55Z

pydantic_ai_slim/pydantic_ai/messages.py

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


That warrants a code comment!

DouweM · 2025-12-10T17:11:50Z

pydantic_ai_slim/pydantic_ai/models/google.py

-                self.provider_details = {'finish_reason': raw_finish_reason.value}
+                provider_details_dict['finish_reason'] = raw_finish_reason.value
                self.finish_reason = _FINISH_REASON_MAP.get(raw_finish_reason)
+            if self._provider_timestamp is not None:


We're never setting this instance variable, so why have it at all?

DouweM · 2025-12-10T17:12:16Z

pydantic_ai_slim/pydantic_ai/models/google.py

    return ModelResponse(
        parts=items,
        model_name=model_name,
+        timestamp=_utils.now_utc(),


This is already the default value, right? So we shouldn't need to pass it. Same goes for the next file; please remove this wherever we do the same

DouweM · 2025-12-10T17:13:57Z

pydantic_ai_slim/pydantic_ai/models/groq.py

            _model_profile=self.profile,
-            _timestamp=number_to_datetime(first_chunk.created),
            _provider_name=self._provider.name,
+            _provider_timestamp=first_chunk.created,


I think it was better to have number_to_datetime here

DouweM · 2025-12-10T17:14:57Z

pydantic_ai_slim/pydantic_ai/models/groq.py

+                    provider_details_dict['finish_reason'] = raw_finish_reason
                    self.finish_reason = _FINISH_REASON_MAP.get(raw_finish_reason)
+                if self._provider_timestamp is not None:  # pragma: no branch
+                    provider_details_dict['timestamp'] = number_to_datetime(self._provider_timestamp)


Since this is in the loop and we never reset self._provider_timestamp, we'll be calling number_to_datetime on every chunk!

We only need to store it if it's not there already. And we can likely do that outside of the loop as well.

DouweM · 2025-12-10T17:21:43Z

pydantic_ai_slim/pydantic_ai/models/openrouter.py

-        provider_details.update(_map_openrouter_provider_details(response))
-        return provider_details
+        if openrouter_details := _map_openrouter_provider_details(response):
+            provider_details = {**(provider_details or {}), **openrouter_details}


I fee l like this was easier when we always had a dict; was there a specific reason to add | None to these provider_details methods?

DouweM · 2025-12-10T17:21:59Z

pydantic_ai_slim/pydantic_ai/models/openai.py

-                    self.provider_details = {'finish_reason': raw_finish_reason}
+                    provider_details['finish_reason'] = raw_finish_reason
                    self.finish_reason = _RESPONSES_FINISH_REASON_MAP.get(raw_finish_reason)
+                if self._provider_timestamp is not None:  # pragma: no branch


Same issue as elsewhere

DouweM · 2025-12-10T17:23:43Z

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.


Yeah please see if there's a way to clean up this logic. It may be better to always merge the new dict into the existing dict; that will have the same outcome of preserving the finish reason right?

DouweM · 2025-12-10T17:24:03Z

pydantic_ai_slim/pydantic_ai/models/outlines.py

            parts=cast(
                list[ModelResponsePart], split_content_into_text_and_thinking(response, self.profile.thinking_tags)
            ),
+            timestamp=_utils.now_utc(),


Isn't this the default already?

DouweM · 2025-12-10T17:26:22Z

pydantic_ai_slim/pydantic_ai/ui/_messages_builder.py

                last_message.parts = [*last_message.parts, part]
            else:
-                self.messages.append(ModelRequest(parts=[part]))
+                self.messages.append(ModelRequest(parts=[part], timestamp=_now_utc()))


I think this is exactly the type of situation where we do NOT want to set the timestamp, as we don't know what the actual timestamp was when these messages were originally sent to the model. (since the message history may have model requests from earlier agent runs)

I suggest having a close look at where we set timestamp=_now_utc(), because some other cases (like with a2a or mcp) may have the same issue. If we promise we set it when it's sent to the model, I think we should only set it then, not earlier. So that means inside the ModelRequestNode where we have it now, and in pydantic_ai.direct.model_request.

Resolved import conflict in test_openai_responses.py - combined datetime imports from our branch with Literal import from main. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

dsfaccini added 4 commits December 6, 2025 12:48

coverage

702b216

coverage

754c782

coverage

5327aea

Merge branch 'main' into request-reponse-timestamps

da7204f

DouweM requested changes Dec 10, 2025

View reviewed changes

dsfaccini and others added 3 commits December 11, 2025 07:48

address review comments

1f71667

resolve conflicts

60e9060


		_: 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

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!

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!

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