Merge branch 'main' into toolsets

Author: DouweM

.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/api/providers.md

@@ -28,4 +28,6 @@
 
 ::: pydantic_ai.providers.heroku.HerokuProvider
 
+::: pydantic_ai.providers.github.GitHubProvider
+
 ::: pydantic_ai.providers.openrouter.OpenRouterProvider

docs/direct.md

@@ -9,6 +9,7 @@ The following functions are available:
 - [`model_request`][pydantic_ai.direct.model_request]: Make a non-streamed async request to a model
 - [`model_request_sync`][pydantic_ai.direct.model_request_sync]: Make a non-streamed synchronous request to a model
 - [`model_request_stream`][pydantic_ai.direct.model_request_stream]: Make a streamed async request to a model
+- [`model_request_stream_sync`][pydantic_ai.direct.model_request_stream_sync]: Make a streamed sync request to a model
 
 ## Basic Example
 

docs/models/index.md

@@ -23,6 +23,7 @@ In addition, many providers are compatible with the OpenAI API, and can be used
 * [Together AI](openai.md#together-ai)
 * [Azure AI Foundry](openai.md#azure-ai-foundry)
 * [Heroku](openai.md#heroku-ai)
+* [GitHub Models](openai.md#github-models)
 
 PydanticAI also comes with [`TestModel`](../api/models/test.md) and [`FunctionModel`](../api/models/function.md)
 for testing and development.

docs/models/openai.md

@@ -366,6 +366,33 @@ agent = Agent(model)
 ...
 ```
 
+### GitHub Models
+
+To use [GitHub Models](https://docs.github.com/en/github-models), you'll need a GitHub personal access token with the `models: read` permission.
+
+Once you have the token, you can use it with the [`GitHubProvider`][pydantic_ai.providers.github.GitHubProvider]:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIModel
+from pydantic_ai.providers.github import GitHubProvider
+
+model = OpenAIModel(
+    'xai/grok-3-mini',  # GitHub Models uses prefixed model names
+    provider=GitHubProvider(api_key='your-github-token'),
+)
+agent = Agent(model)
+...
+```
+
+You can also set the `GITHUB_API_KEY` environment variable:
+
+```bash
+export GITHUB_API_KEY='your-github-token'
+```
+
+GitHub Models supports various model families with different prefixes. You can see the full list on the [GitHub Marketplace](https://github.com/marketplace?type=models) or the public [catalog endpoint](https://models.github.ai/catalog/models).
+
 ### Perplexity
 
 Follow the Perplexity [getting started](https://docs.perplexity.ai/guides/getting-started)

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/agent.py

@@ -340,7 +340,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
@@ -354,19 +354,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
 
         if mcp_servers := _deprecated_kwargs.pop('mcp_servers', None):
@@ -540,7 +544,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)
@@ -714,7 +718,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)
@@ -977,7 +981,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)
@@ -1101,7 +1105,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)
@@ -1440,7 +1444,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]: ...