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/tools.md

@@ -721,11 +721,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
 
-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.
+### MCP Tools {#mcp-tools}
 
-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.
+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.
+
+You will need to install the `langchain-community` package and any others required by the tool in question.
+
+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 +745,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/_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,
+    )

pydantic_ai_slim/pydantic_ai/ext/langchain.py

@@ -27,13 +27,13 @@ def run(self, *args: Any, **kwargs: Any) -> str: ...
 
 
 def tool_from_langchain(langchain_tool: LangChainTool) -> Tool:
-    """Creates a Pydantic tool proxy from a LangChain tool.
+    """Creates a Pydantic AI tool proxy from a LangChain tool.
 
     Args:
         langchain_tool: The LangChain tool to wrap.
 
     Returns:
-        A Pydantic tool that corresponds to the LangChain tool.
+        A Pydantic AI tool that corresponds to the LangChain tool.
     """
     function_name = langchain_tool.name
     function_description = langchain_tool.description

pydantic_ai_slim/pydantic_ai/messages.py

@@ -25,7 +25,7 @@
     from .models.instrumented import InstrumentationSettings
 
 
-AudioMediaType: TypeAlias = Literal['audio/wav', 'audio/mpeg']
+AudioMediaType: TypeAlias = Literal['audio/wav', 'audio/mpeg', 'audio/ogg', 'audio/flac', 'audio/aiff', 'audio/aac']
 ImageMediaType: TypeAlias = Literal['image/jpeg', 'image/png', 'image/gif', 'image/webp']
 DocumentMediaType: TypeAlias = Literal[
     'application/pdf',
@@ -48,7 +48,7 @@
     'video/3gpp',
 ]
 
-AudioFormat: TypeAlias = Literal['wav', 'mp3']
+AudioFormat: TypeAlias = Literal['wav', 'mp3', 'oga', 'flac', 'aiff', 'aac']
 ImageFormat: TypeAlias = Literal['jpeg', 'png', 'gif', 'webp']
 DocumentFormat: TypeAlias = Literal['csv', 'doc', 'docx', 'html', 'md', 'pdf', 'txt', 'xls', 'xlsx']
 VideoFormat: TypeAlias = Literal['mkv', 'mov', 'mp4', 'webm', 'flv', 'mpeg', 'mpg', 'wmv', 'three_gp']
@@ -99,6 +99,13 @@ class FileUrl(ABC):
     * If False, the URL is sent directly to the model and no download is performed.
     """
 
+    vendor_metadata: dict[str, Any] | None = None
+    """Vendor-specific metadata for the file.
+
+    Supported by:
+    - `GoogleModel`: `VideoUrl.vendor_metadata` is used as `video_metadata`: https://ai.google.dev/gemini-api/docs/video-understanding#customize-video-processing
+    """
+
     @property
     @abstractmethod
     def media_type(self) -> str:
@@ -175,13 +182,25 @@ class AudioUrl(FileUrl):
 
     @property
     def media_type(self) -> AudioMediaType:
-        """Return the media type of the audio file, based on the url."""
+        """Return the media type of the audio file, based on the url.
+
+        References:
+        - Gemini: https://ai.google.dev/gemini-api/docs/audio#supported-formats
+        """
         if self.url.endswith('.mp3'):
             return 'audio/mpeg'
-        elif self.url.endswith('.wav'):
+        if self.url.endswith('.wav'):
             return 'audio/wav'
-        else:
-            raise ValueError(f'Unknown audio file extension: {self.url}')
+        if self.url.endswith('.flac'):
+            return 'audio/flac'
+        if self.url.endswith('.oga'):
+            return 'audio/ogg'
+        if self.url.endswith('.aiff'):
+            return 'audio/aiff'
+        if self.url.endswith('.aac'):
+            return 'audio/aac'
+
+        raise ValueError(f'Unknown audio file extension: {self.url}')
 
     @property
     def format(self) -> AudioFormat:
@@ -263,6 +282,13 @@ class BinaryContent:
     media_type: AudioMediaType | ImageMediaType | DocumentMediaType | str
     """The media type of the binary data."""
 
+    vendor_metadata: dict[str, Any] | None = None
+    """Vendor-specific metadata for the file.
+
+    Supported by:
+    - `GoogleModel`: `BinaryContent.vendor_metadata` is used as `video_metadata`: https://ai.google.dev/gemini-api/docs/video-understanding#customize-video-processing
+    """
+
     kind: Literal['binary'] = 'binary'
     """Type identifier, this is available on all parts as a discriminator."""
 
@@ -344,6 +370,10 @@ class ToolReturn:
 _audio_format_lookup: dict[str, AudioFormat] = {
     'audio/mpeg': 'mp3',
     'audio/wav': 'wav',
+    'audio/flac': 'flac',
+    'audio/ogg': 'oga',
+    'audio/aiff': 'aiff',
+    'audio/aac': 'aac',
 }
 _image_format_lookup: dict[str, ImageFormat] = {
     'image/jpeg': 'jpeg',

pydantic_ai_slim/pydantic_ai/models/anthropic.py

@@ -90,10 +90,9 @@
 
 
 class AnthropicModelSettings(ModelSettings, total=False):
-    """Settings used for an Anthropic model request.
+    """Settings used for an Anthropic model request."""
 
-    ALL FIELDS MUST BE `anthropic_` PREFIXED SO YOU CAN MERGE THEM WITH OTHER MODELS.
-    """
+    # ALL FIELDS MUST BE `anthropic_` PREFIXED SO YOU CAN MERGE THEM WITH OTHER MODELS.
 
     anthropic_metadata: BetaMetadataParam
     """An object describing metadata about the request.