Merge remote-tracking branch 'origin/main' into add-builtin-tools

Author: Kludex

.github/workflows/ci.yml

@@ -89,6 +89,9 @@ jobs:
           name: site
           path: site
 
+      # check all docs images are tinified, You'll need an API key from https://tinify.com/ to fix this if it fails
+      - run: uvx tinicly docs --check
+
   test-live:
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -109,6 +112,7 @@ jobs:
           --package pydantic-ai-slim
           --extra openai
           --extra vertexai
+          --extra google
           --extra groq
           --extra anthropic
           --extra mistral
@@ -221,7 +225,7 @@ jobs:
           name: diff-coverage-html
           path: index.html
 
-      - run: uv run coverage report --fail-under 95
+      - run: uv run coverage report --fail-under 100
       - run: uv run diff-cover coverage.xml --fail-under 100
       - run: uv run strict-no-cover
 

.gitignore

@@ -17,3 +17,5 @@ examples/pydantic_ai_examples/.chat_app_messages.sqlite
 /docs-site/.wrangler/
 /CLAUDE.md
 node_modules/
+**.idea/
+.coverage*

Makefile

@@ -63,6 +63,10 @@ test: ## Run tests and collect coverage data
 	uv run coverage run -m pytest
 	@uv run coverage report
 
+.PHONY: test-fast
+test-fast: ## Same as test except no coverage. ~1/4th the time depending on hardware.
+	uv run pytest -n auto --dist=loadgroup
+
 .PHONY: test-all-python
 test-all-python: ## Run tests on Python 3.9 to 3.13
 	UV_PROJECT_ENVIRONMENT=.venv39 uv run --python 3.9 --all-extras --all-packages coverage run -p -m pytest

clai/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Pydantic Services Inc. 2024 to present
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/.cursor/rules.mdc

@@ -0,0 +1,6 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+Always reference the python code in the docs e.g. `ModelSettings` should link to [`ModelSettings`][pydantic_ai.settings.ModelSettings].

docs/a2a.md

@@ -73,7 +73,7 @@ The only dependencies are:
 You can install PydanticAI with the `a2a` extra to include **FastA2A**:
 
 ```bash
-pip/uv-add 'pydantic-ai[a2a]'
+pip/uv-add 'pydantic-ai-slim[a2a]'
 ```
 
 ### PydanticAI Agent to A2A Server

docs/agents.md

@@ -135,29 +135,21 @@ async def main():
                     UserPromptPart(
                         content='What is the capital of France?',
                         timestamp=datetime.datetime(...),
-                        part_kind='user-prompt',
                     )
-                ],
-                instructions=None,
-                kind='request',
+                ]
             )
         ),
         CallToolsNode(
             model_response=ModelResponse(
-                parts=[TextPart(content='Paris', part_kind='text')],
+                parts=[TextPart(content='Paris')],
                 usage=Usage(
-                    requests=1,
-                    request_tokens=56,
-                    response_tokens=1,
-                    total_tokens=57,
-                    details=None,
+                    requests=1, request_tokens=56, response_tokens=1, total_tokens=57
                 ),
                 model_name='gpt-4o',
                 timestamp=datetime.datetime(...),
-                kind='response',
             )
         ),
-        End(data=FinalResult(output='Paris', tool_name=None, tool_call_id=None)),
+        End(data=FinalResult(output='Paris')),
     ]
     """
     print(agent_run.result.output)
@@ -206,29 +198,24 @@ async def main():
                         UserPromptPart(
                             content='What is the capital of France?',
                             timestamp=datetime.datetime(...),
-                            part_kind='user-prompt',
                         )
-                    ],
-                    instructions=None,
-                    kind='request',
+                    ]
                 )
             ),
             CallToolsNode(
                 model_response=ModelResponse(
-                    parts=[TextPart(content='Paris', part_kind='text')],
+                    parts=[TextPart(content='Paris')],
                     usage=Usage(
                         requests=1,
                         request_tokens=56,
                         response_tokens=1,
                         total_tokens=57,
-                        details=None,
                     ),
                     model_name='gpt-4o',
                     timestamp=datetime.datetime(...),
-                    kind='response',
                 )
             ),
-            End(data=FinalResult(output='Paris', tool_name=None, tool_call_id=None)),
+            End(data=FinalResult(output='Paris')),
         ]
         """
 ```
@@ -368,15 +355,16 @@ if __name__ == '__main__':
     [
         '=== UserPromptNode: What will the weather be like in Paris on Tuesday? ===',
         '=== ModelRequestNode: streaming partial request tokens ===',
-        '[Request] Starting part 0: ToolCallPart(tool_name=\'weather_forecast\', args=\'{"location":"Pa\', tool_call_id=\'0001\', part_kind=\'tool-call\')',
+        "[Request] Starting part 0: ToolCallPart(tool_name='weather_forecast', tool_call_id='0001')",
+        '[Request] Part 0 args_delta={"location":"Pa',
         '[Request] Part 0 args_delta=ris","forecast_',
         '[Request] Part 0 args_delta=date":"2030-01-',
         '[Request] Part 0 args_delta=01"}',
         '=== CallToolsNode: streaming partial response & tool usage ===',
         '[Tools] The LLM calls tool=\'weather_forecast\' with args={"location":"Paris","forecast_date":"2030-01-01"} (tool_call_id=\'0001\')',
         "[Tools] Tool call '0001' returned => The forecast in Paris on 2030-01-01 is 24°C and sunny.",
         '=== ModelRequestNode: streaming partial request tokens ===',
-        "[Request] Starting part 0: TextPart(content='It will be ', part_kind='text')",
+        "[Request] Starting part 0: TextPart(content='It will be ')",
         '[Result] The model produced a final output (tool_name=None)',
         "[Request] Part 0 text delta: 'warm and sunny '",
         "[Request] Part 0 text delta: 'in Paris on '",
@@ -414,9 +402,7 @@ result_sync = agent.run_sync(
 print(result_sync.output)
 #> Rome
 print(result_sync.usage())
-"""
-Usage(requests=1, request_tokens=62, response_tokens=1, total_tokens=63, details=None)
-"""
+#> Usage(requests=1, request_tokens=62, response_tokens=1, total_tokens=63)
 
 try:
     result_sync = agent.run_sync(
@@ -713,6 +699,30 @@ print(result.output)
 
 _(This example is complete, it can be run "as is")_
 
+You can also dynamically change the instructions for an agent by using the `@agent.instructions` decorator.
+
+```python {title="dynamic_instructions.py"}
+from datetime import date
+
+from pydantic_ai import Agent, RunContext
+
+agent = Agent('openai:gpt-4o', deps_type=str)
+
+
+@agent.instructions
+def add_the_users_name(ctx: RunContext[str]) -> str:
+    return f"The user's name is {ctx.deps}."
+
+
+@agent.instructions
+def add_the_date() -> str:
+    return f'The date is {date.today()}.'
+
+result = agent.run_sync('What is the date?', deps='Frank')
+print(result.output)
+#> Hello Frank, the date today is 2032-01-02.
+```
+
 ## Reflection and self-correction
 
 Validation errors from both function tool parameter validation and [structured output validation](output.md#structured-output) can be passed back to the model with a request to retry.
@@ -804,31 +814,22 @@ with capture_run_messages() as messages:  # (2)!
                     UserPromptPart(
                         content='Please get me the volume of a box with size 6.',
                         timestamp=datetime.datetime(...),
-                        part_kind='user-prompt',
                     )
-                ],
-                instructions=None,
-                kind='request',
+                ]
             ),
             ModelResponse(
                 parts=[
                     ToolCallPart(
                         tool_name='calc_volume',
                         args={'size': 6},
                         tool_call_id='pyd_ai_tool_call_id',
-                        part_kind='tool-call',
                     )
                 ],
                 usage=Usage(
-                    requests=1,
-                    request_tokens=62,
-                    response_tokens=4,
-                    total_tokens=66,
-                    details=None,
+                    requests=1, request_tokens=62, response_tokens=4, total_tokens=66
                 ),
                 model_name='gpt-4o',
                 timestamp=datetime.datetime(...),
-                kind='response',
             ),
             ModelRequest(
                 parts=[
@@ -837,31 +838,22 @@ with capture_run_messages() as messages:  # (2)!
                         tool_name='calc_volume',
                         tool_call_id='pyd_ai_tool_call_id',
                         timestamp=datetime.datetime(...),
-                        part_kind='retry-prompt',
                     )
-                ],
-                instructions=None,
-                kind='request',
+                ]
             ),
             ModelResponse(
                 parts=[
                     ToolCallPart(
                         tool_name='calc_volume',
                         args={'size': 6},
                         tool_call_id='pyd_ai_tool_call_id',
-                        part_kind='tool-call',
                     )
                 ],
                 usage=Usage(
-                    requests=1,
-                    request_tokens=72,
-                    response_tokens=8,
-                    total_tokens=80,
-                    details=None,
+                    requests=1, request_tokens=72, response_tokens=8, total_tokens=80
                 ),
                 model_name='gpt-4o',
                 timestamp=datetime.datetime(...),
-                kind='response',
             ),
         ]
         """

docs/api/models/function.md

@@ -28,11 +28,8 @@ async def model_function(
                 UserPromptPart(
                     content='Testing my agent...',
                     timestamp=datetime.datetime(...),
-                    part_kind='user-prompt',
                 )
-            ],
-            instructions=None,
-            kind='request',
+            ]
         )
     ]
     """

docs/api/models/google.md

@@ -0,0 +1,7 @@
+# `pydantic_ai.models.google`
+
+## Setup
+
+For details on how to set up authentication with this model, see [model configuration for Google](../../models/google.md).
+
+::: pydantic_ai.models.google

docs/api/providers.md

@@ -2,6 +2,8 @@
 
 ::: pydantic_ai.providers.Provider
 
+::: pydantic_ai.providers.google
+
 ::: pydantic_ai.providers.google_vertex
 
 ::: pydantic_ai.providers.openai