Reformat messages so messages become simple list[ModelRequest | ModelResponse] (#259)

Author: samuelcolvin

docs/agents.md

@@ -348,11 +348,15 @@ except UnexpectedModelBehavior as e:
     """
     messages:
     [
-        UserPrompt(
-            content='Please get me the volume of a box with size 6.',
-            timestamp=datetime.datetime(...),
-            role='user',
-            message_kind='user-prompt',
+        ModelRequest(
+            parts=[
+                UserPromptPart(
+                    content='Please get me the volume of a box with size 6.',
+                    timestamp=datetime.datetime(...),
+                    part_kind='user-prompt',
+                )
+            ],
+            kind='request',
         ),
         ModelResponse(
             parts=[
@@ -364,16 +368,19 @@ except UnexpectedModelBehavior as e:
                 )
             ],
             timestamp=datetime.datetime(...),
-            role='model',
-            message_kind='model-response',
+            kind='response',
         ),
-        RetryPrompt(
-            content='Please try again.',
-            tool_name='calc_volume',
-            tool_call_id=None,
-            timestamp=datetime.datetime(...),
-            role='user',
-            message_kind='retry-prompt',
+        ModelRequest(
+            parts=[
+                RetryPromptPart(
+                    content='Please try again.',
+                    tool_name='calc_volume',
+                    tool_call_id=None,
+                    timestamp=datetime.datetime(...),
+                    part_kind='retry-prompt',
+                )
+            ],
+            kind='request',
         ),
         ModelResponse(
             parts=[
@@ -385,8 +392,7 @@ except UnexpectedModelBehavior as e:
                 )
             ],
             timestamp=datetime.datetime(...),
-            role='model',
-            message_kind='model-response',
+            kind='response',
         ),
     ]
     """

docs/api/messages.md

@@ -1,15 +1,19 @@
 # `pydantic_ai.messages`
 
+The structure of [`ModelMessage`][pydantic_ai.messages.ModelMessage] can be shown as a graph:
+
+```mermaid
+graph RL
+    SystemPromptPart(SystemPromptPart) --- ModelRequestPart
+    UserPromptPart(UserPromptPart) --- ModelRequestPart
+    ToolReturnPart(ToolReturnPart) --- ModelRequestPart
+    RetryPromptPart(RetryPromptPart) --- ModelRequestPart
+    TextPart(TextPart) --- ModelResponsePart
+    ToolCallPart(ToolCallPart) --- ModelResponsePart
+    ModelRequestPart("ModelRequestPart<br>(Union)") --- ModelRequest
+    ModelRequest("ModelRequest(parts=list[...])") --- ModelMessage
+    ModelResponsePart("ModelResponsePart<br>(Union)") --- ModelResponse
+    ModelResponse("ModelResponse(parts=list[...])") --- ModelMessage("ModelMessage<br>(Union)")
+```
+
 ::: pydantic_ai.messages
-    options:
-      members:
-        - Message
-        - SystemPrompt
-        - UserPrompt
-        - ToolReturn
-        - RetryPrompt
-        - ModelResponse
-        - ToolCall
-        - ArgsJson
-        - ArgsObject
-        - MessagesTypeAdapter

docs/api/models/function.md

@@ -11,21 +11,27 @@ Here's a minimal example:
 
 ```py {title="function_model_usage.py" call_name="test_my_agent" lint="not-imports"}
 from pydantic_ai import Agent
-from pydantic_ai.messages import Message, ModelResponse
+from pydantic_ai.messages import ModelMessage, ModelResponse
 from pydantic_ai.models.function import FunctionModel, AgentInfo
 
 my_agent = Agent('openai:gpt-4o')
 
 
-async def model_function(messages: list[Message], info: AgentInfo) -> ModelResponse:
+async def model_function(
+    messages: list[ModelMessage], info: AgentInfo
+) -> ModelResponse:
     print(messages)
     """
     [
-        UserPrompt(
-            content='Testing my agent...',
-            timestamp=datetime.datetime(...),
-            role='user',
-            message_kind='user-prompt',
+        ModelRequest(
+            parts=[
+                UserPromptPart(
+                    content='Testing my agent...',
+                    timestamp=datetime.datetime(...),
+                    part_kind='user-prompt',
+                )
+            ],
+            kind='request',
         )
     ]
     """