Merge branch 'main' into support-typed-runcontext-in-textoutput-signature

Author: dsfaccini

.pre-commit-config.yaml

@@ -44,13 +44,6 @@ repos:
         types: [python]
         language: system
         pass_filenames: false
-      - id: clai-help
-        name: clai help output
-        entry: uv
-        args: [run, pytest, "clai/update_readme.py"]
-        language: system
-        types_or: [python, markdown]
-        pass_filenames: false
       - id: typecheck
         name: Typecheck
         entry: make

clai/README.md

@@ -51,31 +51,32 @@ Either way, running `clai` will start an interactive session where you can chat
 - `/multiline`: Toggle multiline input mode (use Ctrl+D to submit)
 - `/cp`: Copy the last response to clipboard
 
-## Help
+For full CLI documentation, see the [CLI documentation](https://ai.pydantic.dev/cli/).
 
+## Web Chat UI
+
+Launch a web-based chat interface:
+
+```bash
+clai web -m openai:gpt-5
 ```
-usage: clai [-h] [-m [MODEL]] [-a AGENT] [-l] [-t [CODE_THEME]] [--no-stream] [--version] [prompt]
-
-Pydantic AI CLI v...
-
-Special prompts:
-* `/exit` - exit the interactive mode (ctrl-c and ctrl-d also work)
-* `/markdown` - show the last markdown output of the last question
-* `/multiline` - toggle multiline mode
-* `/cp` - copy the last response to clipboard
-
-positional arguments:
-  prompt                AI Prompt, if omitted fall into interactive mode
-
-options:
-  -h, --help            show this help message and exit
-  -m [MODEL], --model [MODEL]
-                        Model to use, in format "<provider>:<model>" e.g. "openai:gpt-5" or "anthropic:claude-sonnet-4-5". Defaults to "openai:gpt-5".
-  -a AGENT, --agent AGENT
-                        Custom Agent to use, in format "module:variable", e.g. "mymodule.submodule:my_agent"
-  -l, --list-models     List all available models and exit
-  -t [CODE_THEME], --code-theme [CODE_THEME]
-                        Which colors to use for code, can be "dark", "light" or any theme from pygments.org/styles/. Defaults to "dark" which works well on dark terminals.
-  --no-stream           Disable streaming from the model
-  --version             Show version and exit
+
+![Web Chat UI](https://ai.pydantic.dev/img/web-chat-ui.png)
+
+This will start a web server (default: http://127.0.0.1:7932) with a chat interface.
+
+You can also serve an existing agent. For example, if you have an agent defined in `my_agent.py`:
+
+```python
+from pydantic_ai import Agent
+
+my_agent = Agent('openai:gpt-5', instructions='You are a helpful assistant.')
+```
+
+Launch the web UI with:
+
+```bash
+clai web --agent my_agent:my_agent
 ```
+
+For full Web UI documentation, see [Web Chat UI](https://ai.pydantic.dev/web/).

clai/update_readme.py

@@ -12,6 +12,7 @@ Pydantic AI supports the following built-in tools:
 - **[`WebFetchTool`][pydantic_ai.builtin_tools.WebFetchTool]**: Enables agents to fetch web pages
 - **[`MemoryTool`][pydantic_ai.builtin_tools.MemoryTool]**: Enables agents to use memory
 - **[`MCPServerTool`][pydantic_ai.builtin_tools.MCPServerTool]**: Enables agents to use remote MCP servers with communication handled by the model provider
+- **[`FileSearchTool`][pydantic_ai.builtin_tools.FileSearchTool]**: Enables agents to search through uploaded files using vector search (RAG)
 
 These tools are passed to the agent via the `builtin_tools` parameter and are executed by the model provider's infrastructure.
 
@@ -353,6 +354,23 @@ assert isinstance(result.output, BinaryImage)
 
 _(This example is complete, it can be run "as is")_
 
+To control the image resolution with Google image generation models (starting with Gemini 3 Pro Image), use the `size` parameter:
+
+```py {title="image_generation_google_resolution.py"}
+from pydantic_ai import Agent, BinaryImage, ImageGenerationTool
+
+agent = Agent(
+    'google-gla:gemini-3-pro-image-preview',
+    builtin_tools=[ImageGenerationTool(aspect_ratio='16:9', size='4K')],
+    output_type=BinaryImage,
+)
+
+result = agent.run_sync('Generate a high-resolution wide landscape illustration of an axolotl.')
+assert isinstance(result.output, BinaryImage)
+```
+
+_(This example is complete, it can be run "as is")_
+
 For more details, check the [API documentation][pydantic_ai.builtin_tools.ImageGenerationTool].
 
 #### Provider Support
@@ -366,8 +384,10 @@ For more details, check the [API documentation][pydantic_ai.builtin_tools.ImageG
 | `output_format` | ✅ | ❌ |
 | `partial_images` | ✅ | ❌ |
 | `quality` | ✅ | ❌ |
-| `size` | ✅ | ❌ |
-| `aspect_ratio` | ✅ (1:1, 2:3, 3:2) | ✅ |
+| `size` | ✅ (auto (default), 1024x1024, 1024x1536, 1536x1024) | ✅ (1K (default), 2K, 4K) |
+| `aspect_ratio` | ✅ (1:1, 2:3, 3:2) | ✅ (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9) |
+
+**Note:** For OpenAI, `auto` lets the model select the value.
 
 ## Web Fetch Tool
 
@@ -672,6 +692,100 @@ _(This example is complete, it can be run "as is")_
 | `description`         | ✅ | ❌ |
 | `headers`             | ✅ | ❌ |
 
+## File Search Tool
+
+The [`FileSearchTool`][pydantic_ai.builtin_tools.FileSearchTool] enables your agent to search through uploaded files using vector search, providing a fully managed Retrieval-Augmented Generation (RAG) system. This tool handles file storage, chunking, embedding generation, and context injection into prompts.
+
+### Provider Support
+
+| Provider | Supported | Notes |
+|----------|-----------|-------|
+| OpenAI Responses | ✅ | Full feature support. Requires files to be uploaded to vector stores via the [OpenAI Files API](https://platform.openai.com/docs/api-reference/files). To include search results on the [`BuiltinToolReturnPart`][pydantic_ai.messages.BuiltinToolReturnPart] available via [`ModelResponse.builtin_tool_calls`][pydantic_ai.messages.ModelResponse.builtin_tool_calls], enable the [`OpenAIResponsesModelSettings.openai_include_file_search_results`][pydantic_ai.models.openai.OpenAIResponsesModelSettings.openai_include_file_search_results] [model setting](agents.md#model-run-settings). |
+| Google (Gemini) | ✅ | Requires files to be uploaded via the [Gemini Files API](https://ai.google.dev/gemini-api/docs/files). Files are automatically deleted after 48 hours. Supports up to 2 GB per file and 20 GB per project. Using built-in tools and function tools (including [output tools](output.md#tool-output)) at the same time is not supported; to use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
+|| Google (Vertex AI) | ❌ | Not supported |
+| Anthropic | ❌ | Not supported |
+| Groq | ❌ | Not supported |
+| OpenAI Chat Completions | ❌ | Not supported |
+| Bedrock | ❌ | Not supported |
+| Mistral | ❌ | Not supported |
+| Cohere | ❌ | Not supported |
+| HuggingFace | ❌ | Not supported |
+| Outlines | ❌ | Not supported |
+
+### Usage
+
+#### OpenAI Responses
+
+With OpenAI, you need to first [upload files to a vector store](https://platform.openai.com/docs/assistants/tools/file-search), then reference the vector store IDs when using the `FileSearchTool`.
+
+```py {title="file_search_openai_upload.py" test="skip"}
+import asyncio
+
+from pydantic_ai import Agent, FileSearchTool
+from pydantic_ai.models.openai import OpenAIResponsesModel
+
+
+async def main():
+    model = OpenAIResponsesModel('gpt-5')
+
+    with open('my_document.txt', 'rb') as f:
+        file = await model.client.files.create(file=f, purpose='assistants')
+
+    vector_store = await model.client.vector_stores.create(name='my-docs')
+    await model.client.vector_stores.files.create(
+        vector_store_id=vector_store.id,
+        file_id=file.id
+    )
+
+    agent = Agent(
+        model,
+        builtin_tools=[FileSearchTool(file_store_ids=[vector_store.id])]
+    )
+
+    result = await agent.run('What information is in my documents about pydantic?')
+    print(result.output)
+    #> Based on your documents, Pydantic is a data validation library for Python...
+
+asyncio.run(main())
+```
+
+#### Google (Gemini)
+
+With Gemini, you need to first [create a file search store via the Files API](https://ai.google.dev/gemini-api/docs/files), then reference the file search store names.
+
+```py {title="file_search_google_upload.py" test="skip"}
+import asyncio
+
+from pydantic_ai import Agent, FileSearchTool
+from pydantic_ai.models.google import GoogleModel
+
+
+async def main():
+    model = GoogleModel('gemini-2.5-flash')
+
+    store = await model.client.aio.file_search_stores.create(
+        config={'display_name': 'my-docs'}
+    )
+
+    with open('my_document.txt', 'rb') as f:
+        await model.client.aio.file_search_stores.upload_to_file_search_store(
+            file_search_store_name=store.name,
+            file=f,
+            config={'mime_type': 'text/plain'}
+        )
+
+    agent = Agent(
+        model,
+        builtin_tools=[FileSearchTool(file_store_ids=[store.name])]
+    )
+
+    result = await agent.run('Summarize the key points from my uploaded documents.')
+    print(result.output)
+    #> The documents discuss the following key points: ...
+
+asyncio.run(main())
+```
+
 ## API Reference
 
 For complete API documentation, see the [API Reference](api/builtin_tools.md).