Merge branch 'main' into update-versins

Author: medaminezghal

.github/workflows/stale.yml

@@ -1,19 +1,25 @@
-name: 'Close stale issues'
+name: 'Close stale issues and PRs'
 on:
   schedule:
     - cron: '0 14 * * *'
 
 permissions:
   issues: write
+  pull-requests: write
 
 jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/stale@v9
         with:
-          stale-issue-message: 'This issue is stale, and will be closed in 3 days if no reply is received.'
-          close-issue-message: 'Closing this issue as it has been inactive for 10 days.'
-          any-of-labels: 'question,more info'
           days-before-stale: 7
           days-before-close: 3
+
+          any-of-issue-labels: 'question,more info'
+          stale-issue-message: 'This issue is stale, and will be closed in 3 days if no reply is received.'
+          close-issue-message: 'Closing this issue as it has been inactive for 10 days.'
+
+          any-of-pr-labels: 'awaiting author revision'
+          stale-pr-message: 'This PR is stale, and will be closed in 3 days if no reply is received.'
+          close-pr-message: 'Closing this PR as it has been inactive for 10 days.'

docs/agents.md

@@ -467,6 +467,7 @@ This structure allows you to configure common parameters that influence the mode
 `timeout`, and more.
 
 There are two ways to apply these settings:
+
 1. Passing to `run{_sync,_stream}` functions via the `model_settings` argument. This allows for fine-tuning on a per-request basis.
 2. Setting during [`Agent`][pydantic_ai.agent.Agent] initialization via the `model_settings` argument. These settings will be applied by default to all subsequent run calls using said agent. However, `model_settings` provided during a specific run call will override the agent's default settings.
 

docs/changelog.md

@@ -12,6 +12,12 @@ PydanticAI is still pre-version 1, so breaking changes will occur, however:
 !!! note
     Here's a filtered list of the breaking changes for each version to help you upgrade PydanticAI.
 
+### v0.4.0 (2025-07-08)
+
+See [#1799](https://github.com/pydantic/pydantic-ai/pull/1799) - Pydantic Evals `EvaluationReport` and `ReportCase` are now generic dataclasses instead of Pydantic models. If you were serializing them using `model_dump()`, you will now need to use the `EvaluationReportAdapter` and `ReportCaseAdapter` type adapters instead.
+
+See [#1507](https://github.com/pydantic/pydantic-ai/pull/1507) - The `ToolDefinition` `description` argument is now optional and the order of positional arguments has changed from `name, description, parameters_json_schema, ...` to `name, parameters_json_schema, description, ...` to account for this.
+
 ### v0.3.0 (2025-06-18)
 
 See [#1142](https://github.com/pydantic/pydantic-ai/pull/1142) — Adds support for thinking parts.

docs/direct.md

@@ -66,7 +66,7 @@ async def main():
             function_tools=[
                 ToolDefinition(
                     name=Divide.__name__.lower(),
-                    description=Divide.__doc__ or '',
+                    description=Divide.__doc__,
                     parameters_json_schema=Divide.model_json_schema(),
                 )
             ],

docs/tools.md

@@ -451,7 +451,6 @@ print(test_model.last_model_request_parameters.function_tools)
 [
     ToolDefinition(
         name='foobar',
-        description='This is a Foobar',
         parameters_json_schema={
             'properties': {
                 'x': {'type': 'integer'},
@@ -462,6 +461,7 @@ print(test_model.last_model_request_parameters.function_tools)
             'title': 'Foobar',
             'type': 'object',
         },
+        description='This is a Foobar',
     )
 ]
 """
@@ -591,7 +591,6 @@ print(test_model.last_model_request_parameters.function_tools)
 [
     ToolDefinition(
         name='greet',
-        description='',
         parameters_json_schema={
             'additionalProperties': False,
             'properties': {
@@ -721,11 +720,19 @@ def my_flaky_tool(query: str) -> str:
 ```
 Raising `ModelRetry` also generates a `RetryPromptPart` containing the exception message, which is sent back to the LLM to guide its next attempt. Both `ValidationError` and `ModelRetry` respect the `retries` setting configured on the `Tool` or `Agent`.
 
-## Use LangChain Tools {#langchain-tools}
+## Third-Party Tools
+
+### MCP Tools {#mcp-tools}
+
+See the [MCP Client](./mcp/client.md) documentation for how to use MCP servers with Pydantic AI.
+
+### LangChain Tools {#langchain-tools}
+
+If you'd like to use a tool from LangChain's [community tool library](https://python.langchain.com/docs/integrations/tools/) with Pydantic AI, you can use the `pydancic_ai.ext.langchain.tool_from_langchain` convenience method. Note that Pydantic AI will not validate the arguments in this case -- it's up to the model to provide arguments matching the schema specified by the LangChain tool, and up to the LangChain tool to raise an error if the arguments are invalid.
 
-If you'd like to use a tool from LangChain's [community tool library](https://python.langchain.com/docs/integrations/tools/) with PydanticAI, you can use the `pydancic_ai.ext.langchain.tool_from_langchain` convenience method. Note that PydanticAI will not validate the arguments in this case -- it's up to the model to provide arguments matching the schema specified by the LangChain tool, and up to the LangChain tool to raise an error if the arguments are invalid.
+You will need to install the `langchain-community` package and any others required by the tool in question.
 
-Here is how you can use it to augment model responses using a LangChain web search tool. This tool will need you to install the `langchain-community` and `duckduckgo-search` dependencies to work properly.
+Here is how you can use the LangChain `DuckDuckGoSearchRun` tool, which requires the `duckduckgo-search` package:
 
 ```python {test="skip"}
 from langchain_community.tools import DuckDuckGoSearchRun
@@ -737,15 +744,44 @@ search = DuckDuckGoSearchRun()
 search_tool = tool_from_langchain(search)
 
 agent = Agent(
-    'google-gla:gemini-2.0-flash',  # (1)!
+    'google-gla:gemini-2.0-flash',
     tools=[search_tool],
 )
 
-result = agent.run_sync('What is the release date of Elden Ring Nightreign?')  # (2)!
+result = agent.run_sync('What is the release date of Elden Ring Nightreign?')  # (1)!
 print(result.output)
 #> Elden Ring Nightreign is planned to be released on May 30, 2025.
 ```
 
+1. The release date of this game is the 30th of May 2025, which is after the knowledge cutoff for Gemini 2.0 (August 2024).
+
+### ACI.dev Tools {#aci-tools}
+
+If you'd like to use a tool from the [ACI.dev tool library](https://www.aci.dev/tools) with Pydantic AI, you can use the `pydancic_ai.ext.aci.tool_from_aci` convenience method. Note that Pydantic AI will not validate the arguments in this case -- it's up to the model to provide arguments matching the schema specified by the ACI tool, and up to the ACI tool to raise an error if the arguments are invalid.
+
+You will need to install the `aci-sdk` package, set your ACI API key in the `ACI_API_KEY` environment variable, and pass your ACI "linked account owner ID" to the function.
+
+Here is how you can use the ACI.dev `TAVILY__SEARCH` tool:
+
+```python {test="skip"}
+import os
+
+from pydantic_ai import Agent
+from pydantic_ai.ext.aci import tool_from_aci
+
+tavily_search = tool_from_aci(
+    'TAVILY__SEARCH',
+    linked_account_owner_id=os.getenv('LINKED_ACCOUNT_OWNER_ID')
+)
+
+agent = Agent(
+    'google-gla:gemini-2.0-flash',
+    tools=[tavily_search]
+)
+
+result = agent.run_sync('What is the release date of Elden Ring Nightreign?')  # (1)!
+print(result.output)
+#> Elden Ring Nightreign is planned to be released on May 30, 2025.
+```
 
-1. While this task is simple Gemini 1.5 didn't want to use the provided tool. Gemini 2.0 is still fast and cheap.
-2. The release date of this game is the 30th of May 2025, which was confirmed after the knowledge cutoff for Gemini 2.0 (August 2024).
+1. The release date of this game is the 30th of May 2025, which is after the knowledge cutoff for Gemini 2.0 (August 2024).

pydantic_ai_slim/pydantic_ai/_function_schema.py

@@ -35,7 +35,7 @@ class FunctionSchema:
     """Internal information about a function schema."""
 
     function: Callable[..., Any]
-    description: str
+    description: str | None
     validator: SchemaValidator
     json_schema: ObjectJsonSchema
     # if not None, the function takes a single by that name (besides potentially `info`)

pydantic_ai_slim/pydantic_ai/_griffe.py

@@ -19,7 +19,7 @@ def doc_descriptions(
     sig: Signature,
     *,
     docstring_format: DocstringFormat,
-) -> tuple[str, dict[str, str]]:
+) -> tuple[str | None, dict[str, str]]:
     """Extract the function description and parameter descriptions from a function's docstring.
 
     The function parses the docstring using the specified format (or infers it if 'auto')
@@ -35,7 +35,7 @@ def doc_descriptions(
     """
     doc = func.__doc__
     if doc is None:
-        return '', {}
+        return None, {}
 
     # see https://github.com/mkdocstrings/griffe/issues/293
     parent = cast(GriffeObject, sig)

pydantic_ai_slim/pydantic_ai/_utils.py

@@ -315,8 +315,11 @@ def dataclasses_no_defaults_repr(self: Any) -> str:
     return f'{self.__class__.__qualname__}({", ".join(kv_pairs)})'
 
 
+_datetime_ta = TypeAdapter(datetime)
+
+
 def number_to_datetime(x: int | float) -> datetime:
-    return TypeAdapter(datetime).validate_python(x)
+    return _datetime_ta.validate_python(x)
 
 
 AwaitableCallable = Callable[..., Awaitable[T]]

pydantic_ai_slim/pydantic_ai/agent.py

@@ -296,7 +296,7 @@ def __init__(
         if 'result_type' in _deprecated_kwargs:
             if output_type is not str:  # pragma: no cover
                 raise TypeError('`result_type` and `output_type` cannot be set at the same time.')
-            warnings.warn('`result_type` is deprecated, use `output_type` instead', DeprecationWarning)
+            warnings.warn('`result_type` is deprecated, use `output_type` instead', DeprecationWarning, stacklevel=2)
             output_type = _deprecated_kwargs.pop('result_type')
 
         self.output_type = output_type
@@ -310,19 +310,23 @@ def __init__(
             warnings.warn(
                 '`result_tool_name` is deprecated, use `output_type` with `ToolOutput` instead',
                 DeprecationWarning,
+                stacklevel=2,
             )
 
         self._deprecated_result_tool_description = _deprecated_kwargs.pop('result_tool_description', None)
         if self._deprecated_result_tool_description is not None:
             warnings.warn(
                 '`result_tool_description` is deprecated, use `output_type` with `ToolOutput` instead',
                 DeprecationWarning,
+                stacklevel=2,
             )
         result_retries = _deprecated_kwargs.pop('result_retries', None)
         if result_retries is not None:
             if output_retries is not None:  # pragma: no cover
                 raise TypeError('`output_retries` and `result_retries` cannot be set at the same time.')
-            warnings.warn('`result_retries` is deprecated, use `max_result_retries` instead', DeprecationWarning)
+            warnings.warn(
+                '`result_retries` is deprecated, use `max_result_retries` instead', DeprecationWarning, stacklevel=2
+            )
             output_retries = result_retries
 
         default_output_mode = (
@@ -472,7 +476,7 @@ async def main():
         if 'result_type' in _deprecated_kwargs:  # pragma: no cover
             if output_type is not str:
                 raise TypeError('`result_type` and `output_type` cannot be set at the same time.')
-            warnings.warn('`result_type` is deprecated, use `output_type` instead.', DeprecationWarning)
+            warnings.warn('`result_type` is deprecated, use `output_type` instead.', DeprecationWarning, stacklevel=2)
             output_type = _deprecated_kwargs.pop('result_type')
 
         _utils.validate_empty_kwargs(_deprecated_kwargs)
@@ -640,7 +644,7 @@ async def main():
         if 'result_type' in _deprecated_kwargs:  # pragma: no cover
             if output_type is not str:
                 raise TypeError('`result_type` and `output_type` cannot be set at the same time.')
-            warnings.warn('`result_type` is deprecated, use `output_type` instead.', DeprecationWarning)
+            warnings.warn('`result_type` is deprecated, use `output_type` instead.', DeprecationWarning, stacklevel=2)
             output_type = _deprecated_kwargs.pop('result_type')
 
         _utils.validate_empty_kwargs(_deprecated_kwargs)
@@ -879,7 +883,7 @@ def run_sync(
         if 'result_type' in _deprecated_kwargs:  # pragma: no cover
             if output_type is not str:
                 raise TypeError('`result_type` and `output_type` cannot be set at the same time.')
-            warnings.warn('`result_type` is deprecated, use `output_type` instead.', DeprecationWarning)
+            warnings.warn('`result_type` is deprecated, use `output_type` instead.', DeprecationWarning, stacklevel=2)
             output_type = _deprecated_kwargs.pop('result_type')
 
         _utils.validate_empty_kwargs(_deprecated_kwargs)
@@ -997,7 +1001,7 @@ async def main():
         if 'result_type' in _deprecated_kwargs:  # pragma: no cover
             if output_type is not str:
                 raise TypeError('`result_type` and `output_type` cannot be set at the same time.')
-            warnings.warn('`result_type` is deprecated, use `output_type` instead.', DeprecationWarning)
+            warnings.warn('`result_type` is deprecated, use `output_type` instead.', DeprecationWarning, stacklevel=2)
             output_type = _deprecated_kwargs.pop('result_type')
 
         _utils.validate_empty_kwargs(_deprecated_kwargs)
@@ -1336,7 +1340,11 @@ async def output_validator_deps(ctx: RunContext[str], data: str) -> str:
         return func
 
     @deprecated('`result_validator` is deprecated, use `output_validator` instead.')
-    def result_validator(self, func: Any, /) -> Any: ...
+    def result_validator(self, func: Any, /) -> Any:
+        warnings.warn(
+            '`result_validator` is deprecated, use `output_validator` instead.', DeprecationWarning, stacklevel=2
+        )
+        return self.output_validator(func)  # type: ignore
 
     @overload
     def tool(self, func: ToolFuncContext[AgentDepsT, ToolParams], /) -> ToolFuncContext[AgentDepsT, ToolParams]: ...

pydantic_ai_slim/pydantic_ai/ext/aci.py

@@ -0,0 +1,66 @@
+# Checking whether aci-sdk is installed
+try:
+    from aci import ACI
+except ImportError as _import_error:
+    raise ImportError('Please install `aci-sdk` to use ACI.dev tools') from _import_error
+
+from typing import Any
+
+from aci import ACI
+
+from pydantic_ai import Tool
+
+
+def _clean_schema(schema):
+    if isinstance(schema, dict):
+        # Remove non-standard keys (e.g., 'visible')
+        return {k: _clean_schema(v) for k, v in schema.items() if k not in {'visible'}}
+    elif isinstance(schema, list):
+        return [_clean_schema(item) for item in schema]
+    else:
+        return schema
+
+
+def tool_from_aci(aci_function: str, linked_account_owner_id: str) -> Tool:
+    """Creates a Pydantic AI tool proxy from an ACI function.
+
+    Args:
+        aci_function: The ACI function to wrao.
+        linked_account_owner_id: The ACI user ID to execute the function on behalf of.
+
+    Returns:
+        A Pydantic AI tool that corresponds to the ACI.dev tool.
+    """
+    aci = ACI()
+    function_definition = aci.functions.get_definition(aci_function)
+    function_name = function_definition['function']['name']
+    function_description = function_definition['function']['description']
+    inputs = function_definition['function']['parameters']
+
+    json_schema = {
+        'additionalProperties': inputs.get('additionalProperties', False),
+        'properties': inputs.get('properties', {}),
+        'required': inputs.get('required', []),
+        # Default to 'object' if not specified
+        'type': inputs.get('type', 'object'),
+    }
+
+    # Clean the schema
+    json_schema = _clean_schema(json_schema)
+
+    def implementation(*args: Any, **kwargs: Any) -> str:
+        if args:
+            raise TypeError('Positional arguments are not allowed')
+        return aci.handle_function_call(
+            function_name,
+            kwargs,
+            linked_account_owner_id=linked_account_owner_id,
+            allowed_apps_only=True,
+        )
+
+    return Tool.from_schema(
+        function=implementation,
+        name=function_name,
+        description=function_description,
+        json_schema=json_schema,
+    )