diff --git a/docs/examples/ag-ui.md b/docs/examples/ag-ui.md index 80c9bb778d..27e64886e7 100644 --- a/docs/examples/ag-ui.md +++ b/docs/examples/ag-ui.md @@ -15,7 +15,7 @@ Demonstrates: ## Running the Example -With [dependencies installed and environment variables set](./index.md#usage) +With [dependencies installed and environment variables set](./setup.md#usage) you will need two command line windows. ### Pydantic AI AG-UI backend diff --git a/docs/examples/bank-support.md b/docs/examples/bank-support.md index 8956983bb6..7e0c2da5f4 100644 --- a/docs/examples/bank-support.md +++ b/docs/examples/bank-support.md @@ -8,7 +8,7 @@ Demonstrates: ## Running the Example -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.bank_support diff --git a/docs/examples/chat-app.md b/docs/examples/chat-app.md index b72cc32527..cea8220374 100644 --- a/docs/examples/chat-app.md +++ b/docs/examples/chat-app.md @@ -15,7 +15,7 @@ and `chat_app.ts` which renders messages in the browser. ## Running the Example -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.chat_app diff --git a/docs/examples/data-analyst.md b/docs/examples/data-analyst.md index b2ea046a9b..2205bfa45f 100644 --- a/docs/examples/data-analyst.md +++ b/docs/examples/data-analyst.md @@ -19,7 +19,7 @@ Demonstrates: ## Running the Example -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.data_analyst diff --git a/docs/examples/flight-booking.md b/docs/examples/flight-booking.md index a120705247..e4c90f4fad 100644 --- a/docs/examples/flight-booking.md +++ b/docs/examples/flight-booking.md @@ -28,7 +28,7 @@ graph TD ## Running the Example -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.flight_booking diff --git a/docs/examples/pydantic-model.md b/docs/examples/pydantic-model.md index da61595d7b..44a995822c 100644 --- a/docs/examples/pydantic-model.md +++ b/docs/examples/pydantic-model.md @@ -8,7 +8,7 @@ Demonstrates: ## Running the Example -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.pydantic_model diff --git a/docs/examples/question-graph.md b/docs/examples/question-graph.md index 96a1701fd7..c38063adc2 100644 --- a/docs/examples/question-graph.md +++ b/docs/examples/question-graph.md @@ -8,7 +8,7 @@ Demonstrates: ## Running the Example -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.question_graph diff --git a/docs/examples/rag.md b/docs/examples/rag.md index 2d4b3300dd..37ff8e8569 100644 --- a/docs/examples/rag.md +++ b/docs/examples/rag.md @@ -28,7 +28,7 @@ docker run --rm \ As with the [SQL gen](./sql-gen.md) example, we run postgres on port `54320` to avoid conflicts with any other postgres instances you may have running. We also mount the PostgreSQL `data` directory locally to persist the data if you need to stop and restart the container. -With that running and [dependencies installed and environment variables set](./index.md#usage), we can build the search database with (**WARNING**: this requires the `OPENAI_API_KEY` env variable and will calling the OpenAI embedding API around 300 times to generate embeddings for each section of the documentation): +With that running and [dependencies installed and environment variables set](./setup.md#usage), we can build the search database with (**WARNING**: this requires the `OPENAI_API_KEY` env variable and will calling the OpenAI embedding API around 300 times to generate embeddings for each section of the documentation): ```bash python/uv-run -m pydantic_ai_examples.rag build diff --git a/docs/examples/index.md b/docs/examples/setup.md similarity index 90% rename from docs/examples/index.md rename to docs/examples/setup.md index b7293cfa23..f02f134c5c 100644 --- a/docs/examples/index.md +++ b/docs/examples/setup.md @@ -1,6 +1,6 @@ # Examples -Examples of how to use Pydantic AI and what it can do. +Here we include some examples of how to use Pydantic AI and what it can do. ## Usage @@ -20,7 +20,7 @@ If you clone the repo, you should instead use `uv sync --extra examples` to inst ### Setting model environment variables -These examples will need you to set up authentication with one or more of the LLMs, see the [model configuration](../models/index.md) docs for details on how to do this. +These examples will need you to set up authentication with one or more of the LLMs, see the [model configuration](../models/overview.md) docs for details on how to do this. TL;DR: in most cases you'll need to set one of the following environment variables: diff --git a/docs/examples/slack-lead-qualifier.md b/docs/examples/slack-lead-qualifier.md index b119e6e4bd..3cfec7caad 100644 --- a/docs/examples/slack-lead-qualifier.md +++ b/docs/examples/slack-lead-qualifier.md @@ -64,7 +64,7 @@ You need to have a Slack workspace and the necessary permissions to create apps. ## Usage -1. Make sure you have the [dependencies installed](./index.md#usage). +1. Make sure you have the [dependencies installed](./setup.md#usage). 2. Authenticate with Modal: diff --git a/docs/examples/sql-gen.md b/docs/examples/sql-gen.md index e1518e883b..ff464e5f09 100644 --- a/docs/examples/sql-gen.md +++ b/docs/examples/sql-gen.md @@ -19,7 +19,7 @@ docker run --rm -e POSTGRES_PASSWORD=postgres -p 54320:5432 postgres _(we run postgres on port `54320` to avoid conflicts with any other postgres instances you may have running)_ -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.sql_gen diff --git a/docs/examples/stream-markdown.md b/docs/examples/stream-markdown.md index dea61772c8..5aed8ad0be 100644 --- a/docs/examples/stream-markdown.md +++ b/docs/examples/stream-markdown.md @@ -8,7 +8,7 @@ Demonstrates: ## Running the Example -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.stream_markdown diff --git a/docs/examples/stream-whales.md b/docs/examples/stream-whales.md index c987c0a6af..270bd67694 100644 --- a/docs/examples/stream-whales.md +++ b/docs/examples/stream-whales.md @@ -9,7 +9,7 @@ and displays it as a dynamic table using [`rich`](https://github.com/Textualize/ ## Running the Example -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.stream_whales diff --git a/docs/examples/weather-agent.md b/docs/examples/weather-agent.md index 0004639c81..3a3ea62f0d 100644 --- a/docs/examples/weather-agent.md +++ b/docs/examples/weather-agent.md @@ -18,7 +18,7 @@ To run this example properly, you might want to add two extra API keys **(Note i - A weather API key from [tomorrow.io](https://www.tomorrow.io/weather-api/) set via `WEATHER_API_KEY` - A geocoding API key from [geocode.maps.co](https://geocode.maps.co/) set via `GEO_API_KEY` -With [dependencies installed and environment variables set](./index.md#usage), run: +With [dependencies installed and environment variables set](./setup.md#usage), run: ```bash python/uv-run -m pydantic_ai_examples.weather_agent diff --git a/docs/index.md b/docs/index.md index e4c97a808b..bcde46c80d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,7 +24,7 @@ We built Pydantic AI with one simple aim: to bring that FastAPI feeling to GenAI Built by the team behind [Pydantic Validation](https://docs.pydantic.dev/latest/) (the validation layer of the OpenAI SDK, the Anthropic SDK, LangChain, LlamaIndex, AutoGPT, Transformers, CrewAI, Instructor and many more). - **Model-agnostic**: - Supports OpenAI, Anthropic, Gemini, Deepseek, Ollama, Groq, Cohere, and Mistral, and there is a simple interface to implement support for [other models](models/index.md). + Supports OpenAI, Anthropic, Gemini, Deepseek, Ollama, Groq, Cohere, and Mistral, and there is a simple interface to implement support for [other models](models/overview.md). - **Pydantic Logfire Integration**: Seamlessly [integrates](logfire.md) with [Pydantic Logfire](https://pydantic.dev/logfire) for real-time debugging, performance monitoring, and behavior tracking of your LLM-powered applications. @@ -244,7 +244,7 @@ file. ## Next Steps -To try Pydantic AI yourself, follow the instructions [in the examples](examples/index.md). +To try Pydantic AI yourself, follow the instructions [in the examples](examples/setup.md). Read the [docs](agents.md) to learn more about building applications with Pydantic AI. diff --git a/docs/install.md b/docs/install.md index 8da19c1550..1fd12a499d 100644 --- a/docs/install.md +++ b/docs/install.md @@ -27,7 +27,7 @@ To install examples, use the `examples` optional group: pip/uv-add "pydantic-ai[examples]" ``` -To run the examples, follow instructions in the [examples docs](examples/index.md). +To run the examples, follow instructions in the [examples docs](examples/setup.md). ## Slim Install @@ -58,7 +58,7 @@ pip/uv-add "pydantic-ai-slim[openai]" * `a2a` - installs `fasta2a` [PyPI ↗](https://pypi.org/project/fasta2a){:target="_blank"} * `ag-ui` - installs `ag-ui-protocol` [PyPI ↗](https://pypi.org/project/ag-ui-protocol){:target="_blank"} and `starlette` [PyPI ↗](https://pypi.org/project/starlette){:target="_blank"} -See the [models](models/index.md) documentation for information on which optional dependencies are required for each model. +See the [models](models/overview.md) documentation for information on which optional dependencies are required for each model. You can also install dependencies for multiple models and use cases, for example: diff --git a/docs/mcp/index.md b/docs/mcp/overview.md similarity index 100% rename from docs/mcp/index.md rename to docs/mcp/overview.md diff --git a/docs/models/index.md b/docs/models/overview.md similarity index 100% rename from docs/models/index.md rename to docs/models/overview.md diff --git a/docs/temporal.md b/docs/temporal.md index 297b97a19a..a396e11b6a 100644 --- a/docs/temporal.md +++ b/docs/temporal.md @@ -29,7 +29,7 @@ Activity code faces no restrictions on I/O or external interactions, but if an a See the [Temporal documentation](https://docs.temporal.io/evaluate/understanding-temporal#temporal-application-the-building-blocks) for more information -In the case of Pydantic AI agents, integration with Temporal means that [model requests](models/index.md), [tool calls](tools.md) that may require I/O, and [MCP server communication](mcp/client.md) all need to be offloaded to Temporal activities due to their I/O requirements, while the logic that coordinates them (i.e. the agent run) lives in the workflow. Code that handles a scheduled job or web request can then execute the workflow, which will in turn execute the activities as needed. +In the case of Pydantic AI agents, integration with Temporal means that [model requests](models/overview.md), [tool calls](tools.md) that may require I/O, and [MCP server communication](mcp/client.md) all need to be offloaded to Temporal activities due to their I/O requirements, while the logic that coordinates them (i.e. the agent run) lives in the workflow. Code that handles a scheduled job or web request can then execute the workflow, which will in turn execute the activities as needed. The diagram below shows the overall architecture of an agentic application in Temporal. The Temporal Server is responsible for tracking program execution and making sure the associated state is preserved reliably (i.e., stored to an internal database, and possibly replicated across cloud regions). @@ -71,7 +71,7 @@ See the [Temporal documentation](https://docs.temporal.io/evaluate/understanding Any agent can be wrapped in a [`TemporalAgent`][pydantic_ai.durable_exec.temporal.TemporalAgent] to get a durable agent that can be used inside a deterministic Temporal workflow, by automatically offloading all work that requires I/O (namely model requests, tool calls, and MCP server communication) to non-deterministic activities. -At the time of wrapping, the agent's [model](models/index.md) and [toolsets](toolsets.md) (including function tools registered on the agent and MCP servers) are frozen, activities are dynamically created for each, and the original model and toolsets are wrapped to call on the worker to execute the corresponding activities instead of directly performing the actions inside the workflow. The original agent can still be used as normal outside the Temporal workflow, but any changes to its model or toolsets after wrapping will not be reflected in the durable agent. +At the time of wrapping, the agent's [model](models/overview.md) and [toolsets](toolsets.md) (including function tools registered on the agent and MCP servers) are frozen, activities are dynamically created for each, and the original model and toolsets are wrapped to call on the worker to execute the corresponding activities instead of directly performing the actions inside the workflow. The original agent can still be used as normal outside the Temporal workflow, but any changes to its model or toolsets after wrapping will not be reflected in the durable agent. Here is a simple but complete example of wrapping an agent for durable execution, creating a Temporal workflow with durable execution logic, connecting to a Temporal server, and running the workflow from non-durable code. All it requires is a Temporal server to be [running locally](https://github.com/temporalio/temporal#download-and-start-temporal-server-locally): diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ae9e350baf..c4d459b24c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -20,7 +20,7 @@ Note: This fix also applies to Google Colab and [Marimo](https://github.com/mari ### `UserError: API key must be provided or set in the [MODEL]_API_KEY environment variable` -If you're running into issues with setting the API key for your model, visit the [Models](models/index.md) page to learn more about how to set an environment variable and/or pass in an `api_key` argument. +If you're running into issues with setting the API key for your model, visit the [Models](models/overview.md) page to learn more about how to set an environment variable and/or pass in an `api_key` argument. ## Monitoring HTTPX Requests diff --git a/mkdocs.yml b/mkdocs.yml index 5745c3e1f7..13ddbcb424 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,13 +13,19 @@ nav: - Introduction: index.md - install.md - help.md - - contributing.md - troubleshooting.md - changelog.md + - Documentation: - - agents.md - - Models: - - models/index.md + - Core Concepts: + - agents.md + - dependencies.md + - tools.md + - output.md + - message-history.md + - direct.md + - Models & Providers: + - Overview: models/overview.md - models/openai.md - models/anthropic.md - models/google.md @@ -28,94 +34,114 @@ nav: - models/groq.md - models/mistral.md - models/huggingface.md - - dependencies.md - - tools.md - - toolsets.md - - output.md - - message-history.md - - testing.md - - logfire.md - - multi-agent-applications.md - - graph.md - - evals.md - - input.md - - thinking.md - - direct.md - - builtin-tools.md - - common-tools.md - - retries.md - - temporal.md + - Tools & Toolsets: + - toolsets.md + - builtin-tools.md + - common-tools.md + - Advanced Features: + - input.md + - thinking.md + - retries.md - MCP: - - mcp/index.md + - Overview: mcp/overview.md - mcp/client.md - mcp/server.md - - mcp/run-python.md - - A2A: a2a.md - - AG-UI: ag-ui.md - - cli.md + - Multi-Agent Patterns: multi-agent-applications.md + - Testing: testing.md + + - Pydantic Evals: + - Overview: evals.md + + - Pydantic Graph: + - Overview: graph.md + + - Integrations: + - Debugging & Monitoring with Pydantic Logfire: logfire.md + - temporal.md + - Agent-User Interaction (AG-UI): ag-ui.md + - Agent2Agent (A2A): a2a.md + + - Related Packages: + - Clai: cli.md + - MCP Run Python: mcp/run-python.md + - Examples: - - examples/index.md - - examples/ag-ui.md - - examples/pydantic-model.md - - examples/weather-agent.md - - examples/bank-support.md - - examples/sql-gen.md - - examples/flight-booking.md - - examples/rag.md - - examples/stream-markdown.md - - examples/stream-whales.md - - examples/chat-app.md - - examples/question-graph.md - - examples/slack-lead-qualifier.md - - examples/data-analyst.md + - Setup: examples/setup.md + - Getting Started: + - examples/pydantic-model.md + - examples/weather-agent.md + - Conversational Agents: + - examples/chat-app.md + - examples/bank-support.md + - Data & Analytics: + - examples/sql-gen.md + - examples/data-analyst.md + - examples/rag.md + - Streaming: + - examples/stream-markdown.md + - examples/stream-whales.md + - Complex Workflows: + - examples/flight-booking.md + - examples/question-graph.md + - Business Applications: + - examples/slack-lead-qualifier.md + - UI Examples: + - examples/ag-ui.md - API Reference: - - api/ag_ui.md - - api/agent.md - - api/tools.md - - api/toolsets.md - - api/builtin_tools.md - - api/common_tools.md - - api/durable_exec.md - - api/output.md - - api/result.md - - api/messages.md - - api/exceptions.md - - api/settings.md - - api/usage.md - - api/mcp.md - - api/format_prompt.md - - api/direct.md - - api/ext.md - - api/models/base.md - - api/models/openai.md - - api/models/anthropic.md - - api/models/bedrock.md - - api/models/cohere.md - - api/models/google.md - - api/models/groq.md - - api/models/huggingface.md - - api/models/instrumented.md - - api/models/mistral.md - - api/models/test.md - - api/models/function.md - - api/models/fallback.md - - api/models/wrapper.md - - api/models/mcp-sampling.md - - api/profiles.md - - api/providers.md - - api/retries.md - - api/pydantic_graph/graph.md - - api/pydantic_graph/nodes.md - - api/pydantic_graph/persistence.md - - api/pydantic_graph/mermaid.md - - api/pydantic_graph/exceptions.md - - api/pydantic_evals/dataset.md - - api/pydantic_evals/evaluators.md - - api/pydantic_evals/reporting.md - - api/pydantic_evals/otel.md - - api/pydantic_evals/generation.md - - api/fasta2a.md + - pydantic_ai: + - api/ag_ui.md + - api/agent.md + - api/tools.md + - api/toolsets.md + - api/builtin_tools.md + - api/common_tools.md + - api/durable_exec.md + - api/output.md + - api/result.md + - api/messages.md + - api/exceptions.md + - api/settings.md + - api/usage.md + - api/mcp.md + - api/format_prompt.md + - api/direct.md + - api/ext.md + - api/models/base.md + - api/models/openai.md + - api/models/anthropic.md + - api/models/bedrock.md + - api/models/cohere.md + - api/models/google.md + - api/models/groq.md + - api/models/huggingface.md + - api/models/instrumented.md + - api/models/mistral.md + - api/models/test.md + - api/models/function.md + - api/models/fallback.md + - api/models/wrapper.md + - api/models/mcp-sampling.md + - api/profiles.md + - api/providers.md + - api/retries.md + - pydantic_evals: + - api/pydantic_evals/dataset.md + - api/pydantic_evals/evaluators.md + - api/pydantic_evals/reporting.md + - api/pydantic_evals/otel.md + - api/pydantic_evals/generation.md + - pydantic_graph: + - api/pydantic_graph/graph.md + - api/pydantic_graph/nodes.md + - api/pydantic_graph/persistence.md + - api/pydantic_graph/mermaid.md + - api/pydantic_graph/exceptions.md + - fasta2a: + - api/fasta2a.md + + - Project: + - contributing.md extra: # hide the "Made with Material for MkDocs" message @@ -211,6 +237,7 @@ markdown_extensions: watch: - pydantic_ai_slim + - pydantic_evals - pydantic_graph - examples @@ -275,6 +302,11 @@ plugins: - cli.md - logfire.md - examples/*.md + - redirects: + redirect_maps: + 'examples/index.md': 'examples/setup.md' + 'mcp/index.md': 'mcp/overview.md' + 'models/index.md': 'models/overview.md' hooks: - "docs/.hooks/main.py" diff --git a/pyproject.toml b/pyproject.toml index 735954a061..aafbbd710b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -111,6 +111,7 @@ docs = [ "mkdocs>=1.6.1", "mkdocs-glightbox>=0.4.0", "mkdocs-llmstxt>=0.2.0", + 'mkdocs-redirects>=1.2.2', "mkdocs-material[imaging]>=9.5.45", "mkdocstrings-python>=1.12.2", "griffe-warnings-deprecated>=1.1.0", diff --git a/uv.lock b/uv.lock index 9d2e7bc9c3..ed8de81594 100644 --- a/uv.lock +++ b/uv.lock @@ -2025,6 +2025,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728, upload-time = "2023-11-22T19:09:43.465Z" }, ] +[[package]] +name = "mkdocs-redirects" +version = "1.2.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mkdocs" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f1/a8/6d44a6cf07e969c7420cb36ab287b0669da636a2044de38a7d2208d5a758/mkdocs_redirects-1.2.2.tar.gz", hash = "sha256:3094981b42ffab29313c2c1b8ac3969861109f58b2dd58c45fc81cd44bfa0095", size = 7162, upload-time = "2024-11-07T14:57:21.109Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c4/ec/38443b1f2a3821bbcb24e46cd8ba979154417794d54baf949fefde1c2146/mkdocs_redirects-1.2.2-py3-none-any.whl", hash = "sha256:7dbfa5647b79a3589da4401403d69494bd1f4ad03b9c15136720367e1f340ed5", size = 6142, upload-time = "2024-11-07T14:57:19.143Z" }, +] + [[package]] name = "mkdocstrings" version = "0.28.1" @@ -3013,6 +3025,7 @@ docs = [ { name = "mkdocs-glightbox" }, { name = "mkdocs-llmstxt" }, { name = "mkdocs-material", extra = ["imaging"] }, + { name = "mkdocs-redirects" }, { name = "mkdocstrings-python" }, { name = "pydantic-ai", extra = ["a2a"] }, ] @@ -3062,6 +3075,7 @@ docs = [ { name = "mkdocs-glightbox", specifier = ">=0.4.0" }, { name = "mkdocs-llmstxt", specifier = ">=0.2.0" }, { name = "mkdocs-material", extras = ["imaging"], specifier = ">=9.5.45" }, + { name = "mkdocs-redirects", specifier = ">=1.2.2" }, { name = "mkdocstrings-python", specifier = ">=1.12.2" }, { name = "pydantic-ai", extras = ["a2a"], editable = "." }, ] @@ -3103,9 +3117,9 @@ requires-dist = [ { name = "devtools", specifier = ">=0.12.2" }, { name = "duckdb", specifier = ">=1.3.2" }, { name = "fastapi", specifier = ">=0.115.4" }, - { name = "gradio", marker = "python_full_version >= '3.10'", specifier = ">=5.9.0" }, + { name = "gradio", specifier = ">=5.9.0" }, { name = "logfire", extras = ["asyncpg", "fastapi", "httpx", "sqlite3"], specifier = ">=3.14.1" }, - { name = "mcp", extras = ["cli"], marker = "python_full_version >= '3.10'", specifier = ">=1.4.1" }, + { name = "mcp", extras = ["cli"], specifier = ">=1.4.1" }, { name = "modal", specifier = ">=1.0.4" }, { name = "pandas", specifier = ">=2.2.3" }, { name = "pydantic-ai-slim", extras = ["ag-ui", "anthropic", "groq", "openai", "vertexai"], editable = "pydantic_ai_slim" },