Merge branch 'main' into mcp-json-env-vars

Author: wgillett

.github/workflows/ci.yml

@@ -202,7 +202,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        # TODO(Marcelo): Enable 3.11 again.
+        python-version: ["3.10", "3.12", "3.13"]
     env:
       CI: true
       COVERAGE_PROCESS_START: ./pyproject.toml

docs/.hooks/main.py

@@ -16,10 +16,12 @@
 
 def on_page_markdown(markdown: str, page: Page, config: Config, files: Files) -> str:
     """Called on each file after it is read and before it is converted to HTML."""
-    markdown = inject_snippets(markdown, (DOCS_ROOT / page.file.src_uri).parent)
+    relative_path_root = (DOCS_ROOT / page.file.src_uri).parent
+    markdown = inject_snippets(markdown, relative_path_root)
     markdown = replace_uv_python_run(markdown)
     markdown = render_examples(markdown)
     markdown = render_video(markdown)
+    markdown = create_gateway_toggle(markdown, relative_path_root)
     return markdown
 
 
@@ -39,6 +41,7 @@ def on_env(env: Environment, config: Config, files: Files) -> Environment:
 
 def on_post_build(config: Config) -> None:
     """Inject extra CSS into mermaid styles to avoid titles being the same color as the background in dark mode."""
+    assert bundle_path is not None
     if bundle_path.exists():
         content = bundle_path.read_text()
         content, _ = re.subn(r'}(\.statediagram)', '}.statediagramTitleText{fill:#888}\1', content, count=1)
@@ -115,3 +118,109 @@ def sub_cf_video(m: re.Match[str]) -> str:
   ></iframe>
 </div>
 """
+
+
+def create_gateway_toggle(markdown: str, relative_path_root: Path) -> str:
+    """Transform Python code blocks with Agent() calls to show both Pydantic AI and Gateway versions."""
+    # Pattern matches Python code blocks with or without attributes, and optional annotation definitions after
+    # Annotation definitions are numbered list items like "1. Some text" that follow the code block
+    return re.sub(
+        r'```py(?:thon)?(?: *\{?([^}\n]*)\}?)?\n(.*?)\n```(\n\n(?:\d+\..+?\n)+?\n)?',
+        lambda m: transform_gateway_code_block(m, relative_path_root),
+        markdown,
+        flags=re.MULTILINE | re.DOTALL,
+    )
+
+
+# Models that should get gateway transformation
+GATEWAY_MODELS = ('anthropic', 'openai', 'openai-responses', 'openai-chat', 'bedrock', 'google-vertex', 'groq')
+
+
+def transform_gateway_code_block(m: re.Match[str], relative_path_root: Path) -> str:
+    """Transform a single code block to show both versions if it contains Agent() calls."""
+    attrs = m.group(1) or ''
+    code = m.group(2)
+    annotations = m.group(3) or ''  # Capture annotation definitions if present
+
+    # Simple check: does the code contain both "Agent(" and a quoted string?
+    if 'Agent(' not in code:
+        attrs_str = f' {{{attrs}}}' if attrs else ''
+        return f'```python{attrs_str}\n{code}\n```{annotations}'
+
+    # Check if code contains Agent() with a model that should be transformed
+    # Look for Agent(...'model:...' or Agent(..."model:..."
+    agent_pattern = r'Agent\((?:(?!["\']).)*([\"\'])([^"\']+)\1'
+    agent_match = re.search(agent_pattern, code, flags=re.DOTALL)
+
+    if not agent_match:
+        # No Agent() with string literal found
+        attrs_str = f' {{{attrs}}}' if attrs else ''
+        return f'```python{attrs_str}\n{code}\n```{annotations}'
+
+    model_string = agent_match.group(2)
+    # Check if model starts with one of the gateway-supported models
+    should_transform = any(model_string.startswith(f'{model}:') for model in GATEWAY_MODELS)
+
+    if not should_transform:
+        # Model doesn't match gateway models, return original
+        attrs_str = f' {{{attrs}}}' if attrs else ''
+        return f'```python{attrs_str}\n{code}\n```{annotations}'
+
+    # Transform the code for gateway version
+    def replace_agent_model(match: re.Match[str]) -> str:
+        """Replace model string with gateway/ prefix."""
+        full_match = match.group(0)
+        quote = match.group(1)
+        model = match.group(2)
+
+        # Replace the model string while preserving the rest
+        return full_match.replace(f'{quote}{model}{quote}', f'{quote}gateway/{model}{quote}', 1)
+
+    # This pattern finds: "Agent(" followed by anything (lazy), then the first quoted string
+    gateway_code = re.sub(
+        agent_pattern,
+        replace_agent_model,
+        code,
+        flags=re.DOTALL,
+    )
+
+    # Build attributes string
+    docs_path = DOCS_ROOT / 'gateway'
+    relative_path = docs_path.relative_to(relative_path_root, walk_up=True)
+    link = f"<a href='{relative_path}' style='float: right;'>Learn about Gateway</a>"
+
+    attrs_str = f' {{{attrs}}}' if attrs else ''
+
+    if 'title="' in attrs:
+        gateway_attrs = attrs.replace('title="', f'title="{link} ', 1)
+    else:
+        gateway_attrs = attrs + f' title="{link}"'
+    gateway_attrs_str = f' {{{gateway_attrs}}}'
+
+    # Indent code lines for proper markdown formatting within tabs
+    # Always add 4 spaces to every line (even empty ones) to preserve annotations
+    code_lines = code.split('\n')
+    indented_code = '\n'.join('    ' + line for line in code_lines)
+
+    gateway_code_lines = gateway_code.split('\n')
+    indented_gateway_code = '\n'.join('    ' + line for line in gateway_code_lines)
+
+    # Indent annotation definitions if present (need to be inside tabs for Material to work)
+    indented_annotations = ''
+    if annotations:
+        # Remove surrounding newlines and indent each line with 4 spaces
+        annotation_lines = annotations.strip().split('\n')
+        indented_annotations = '\n\n' + '\n'.join('    ' + line for line in annotation_lines) + '\n\n'
+
+    return f"""\
+=== "With Pydantic AI Gateway"
+
+    ```python{gateway_attrs_str}
+{indented_gateway_code}
+    ```{indented_annotations}
+
+=== "Directly to Provider API"
+
+    ```python{attrs_str}
+{indented_code}
+    ```{indented_annotations}"""

docs/.overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block announce %}
+    <strong>
+        <a href="/gateway">Pydantic AI Gateway</a> is now available! 🚀
+        Enterprise-ready AI model routing: One key for all your models with real-time monitoring and budget control that works.
+    </strong>
+{% endblock %}

docs/gateway.md

@@ -0,0 +1,176 @@
+---
+title: Pydantic AI Gateway
+status: new
+---
+
+# Pydantic AI Gateway
+
+**[Pydantic AI Gateway](https://pydantic.dev/ai-gateway)** (PAIG) is a unified interface for accessing multiple AI providers with a single key. Features include built-in OpenTelemetry observability, real-time cost monitoring, failover management, and native integration with the other tools in the [Pydantic stack](https://pydantic.dev/).
+
+!!! note "Free while in Beta"
+    The Pydantic AI Gateway is currently in Beta. You can bring your own key (BYOK) or buy inference through the Gateway (we will eat the card fee for now).
+
+Sign up at [gateway.pydantic.dev](https://gateway.pydantic.dev/).
+
+!!! question "Questions?"
+    For questions and feedback, contact us on [Slack](https://logfire.pydantic.dev/docs/join-slack/).
+
+## Documentation Integration
+
+To help you get started with [Pydantic AI Gateway](https://gateway.pydantic.dev), some code examples on the Pydantic AI documentation include a "Via Pydantic AI Gateway" tab, alongside a "Direct to Provider API" tab with the standard Pydantic AI model string. The main difference between them is that when using Gateway, model strings use the `gateway/` prefix.
+
+## Key features
+
+- **API key management**: access multiple LLM providers with a single Gateway key.
+- **Cost Limits**: set spending limits at project, user, and API key levels with daily, weekly, and monthly caps.
+- **BYOK and managed providers:** Bring your own API keys (BYOK) from LLM providers, or pay for inference directly through the platform.
+- **Multi-provider support:** Access models from OpenAI, Anthropic, Google Vertex, Groq, and AWS Bedrock. _More providers coming soon_.
+- **Backend observability:** Log every request through [Pydantic Logfire](https://pydantic.dev/logfire) or any OpenTelemetry backend (_coming soon_).
+- **Zero translation**: Unlike traditional AI gateways that translate everything to one common schema, PAIG allows requests to flow through directly in each provider's native format. This gives you immediate access to the new model features as soon as they are released.
+- **Open source with self-hosting**: PAIG's core is [open source](https://github.com/pydantic/pydantic-ai-gateway/) (under [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html)), allowing self-hosting with file-based configuration, instead of using the managed service.
+- **Enterprise ready**: Includes SSO (with OIDC support), granular permissions, and flexible deployment options. Deploy to your Cloudflare account, or run on-premises with our [consulting support](https://pydantic.dev/contact).
+
+```python {title="hello_world.py"}
+from pydantic_ai import Agent
+
+agent = Agent('gateway/openai:gpt-5')
+
+result = agent.run_sync('Where does "hello world" come from?')
+print(result.output)
+"""
+The first known use of "hello, world" was in a 1974 textbook about the C programming language.
+"""
+```
+
+## Quick Start
+
+This section contains instructions on how to set up your account and run your app with Pydantic AI Gateway credentials.
+
+### Create an account
+
+Using your  GitHub or Google account, sign in at [gateway.pydantic.dev](https://gateway.pydantic.dev).
+Choose a name for your organization (or accept the default). You will automatically be assigned the Admin role.
+
+A default project will be created for you. You can choose to use it, or create a new one on the [Projects](https://gateway.pydantic.dev/admin/projects) page.
+
+### Add **Providers**
+There are two ways to use Providers in the Pydantic AI Gateway: you can bring your own key (BYOK) or buy inference through the platform.
+
+#### Bringing your own API key (BYOK)
+
+On the [Providers](https://gateway.pydantic.dev/admin/providers) page, fill in the form to add a provider. Paste your API key into the form under Credentials, and make sure to **select the Project that will be associated to this provider**. It is possible to add multiple keys from the same provider.
+
+#### Use Built-in Providers
+Go to the Billing page, add a payment method, and purchase $15 in credits to activate built-in providers. This gives you single-key access to all available models from OpenAI, Anthropic, Google Vertex, AWS Bedrock, and Groq.
+
+### Grant access to your team
+On the [Users](https://gateway.pydantic.dev/admin/users) page, create an invitation and share the URL with your team to allow them to access the project.
+
+### Create Gateway project keys
+On the Keys page, Admins can create project keys which are not affected by spending limits. Users can only create personal keys, that will inherit spending caps from both User and Project levels, whichever is more restrictive.
+
+## Usage
+After setting up your account with the instructions above, you will be able to make an AI model request with the Pydantic AI Gateway.
+The code snippets below show how you can use PAIG with different frameworks and SDKs.
+You can add `gateway/` as prefix on every known provider that
+
+To use different models, change the model string `gateway/<api_format>:<model_name>` to other models offered by the supported providers.
+
+Examples of providers and models that can be used are:
+
+| **Provider** | **API Format**  | **Example Model**                        |
+| --- |-----------------|------------------------------------------|
+| OpenAI | `openai`        | `gateway/openai:gpt-5`                   |
+| Anthropic | `anthropic`     | `gateway/anthropic:claude-sonnet-4-5`    |
+| Google Vertex | `google-vertex` | `gateway/google-vertex:gemini-2.5-flash` |
+| Groq | `groq`          | `gateway/groq:openai/gpt-oss-120b`       |
+| AWS Bedrock | `bedrock`       | `gateway/bedrock:amazon.nova-micro-v1:0` |
+
+### Pydantic AI
+Before you start, make sure you are on version 1.16 or later of `pydantic-ai`. To update to the latest version run:
+
+=== "uv"
+
+    ```bash
+    uv sync -P pydantic-ai
+    ```
+
+=== "pip"
+
+    ```bash
+    pip install -U pydantic-ai
+    ```
+
+Set the `PYDANTIC_AI_GATEWAY_API_KEY`  environment variable to your Gateway API key:
+
+```bash
+export PYDANTIC_AI_GATEWAY_API_KEY="YOUR_PAIG_TOKEN"
+```
+
+You can access multiple models with the same API key, as shown in the code snippet below.
+
+```python {title="hello_world.py"}
+from pydantic_ai import Agent
+
+agent = Agent('gateway/openai:gpt-5')
+
+result = agent.run_sync('Where does "hello world" come from?')
+print(result.output)
+"""
+The first known use of "hello, world" was in a 1974 textbook about the C programming language.
+"""
+```
+
+
+### Claude Code
+Before you start, log out of Claude Code using `/logout`.
+
+Set your gateway credentials as environment variables:
+
+```bash
+export ANTHROPIC_BASE_URL="https://gateway.pydantic.dev/proxy/anthropic"
+export ANTHROPIC_AUTH_TOKEN="YOUR_PAIG_TOKEN"
+```
+
+Replace `YOUR_PAIG_TOKEN` with the API key from the Keys page.
+
+Launch Claude Code by typing `claude`. All requests will now route through the Pydantic AI Gateway.
+
+### SDKs
+
+#### OpenAI SDK
+
+```python {title="openai_sdk.py" test="skip"}
+import openai
+
+client = openai.Client(
+    base_url='https://gateway.pydantic.dev/proxy/chat/',
+    api_key='paig_...',
+)
+
+response = client.chat.completions.create(
+    model='gpt-5',
+    messages=[{'role': 'user', 'content': 'Hello world'}],
+)
+print(response.choices[0].message.content)
+#> Hello user
+```
+
+#### Anthropic SDK
+
+```python {title="anthropic_sdk.py" test="skip"}
+import anthropic
+
+client = anthropic.Anthropic(
+    base_url='https://gateway.pydantic.dev/proxy/anthropic/',
+    auth_token='paig_...',
+)
+
+response = client.messages.create(
+    max_tokens=1000,
+    model='claude-sonnet-4-5',
+    messages=[{'role': 'user', 'content': 'Hello world'}],
+)
+print(response.content[0].text)
+#> Hello user
+```

mkdocs.yml

@@ -14,6 +14,7 @@ nav:
   - install.md
   - help.md
   - troubleshooting.md
+  - Pydantic AI Gateway: gateway.md
 
   - Documentation:
       - Core Concepts:
@@ -87,14 +88,14 @@ nav:
   - Integrations:
       - Debugging & Monitoring with Pydantic Logfire: logfire.md
       - Durable Execution:
-        - Overview: durable_execution/overview.md
-        - Temporal: durable_execution/temporal.md
-        - DBOS: durable_execution/dbos.md
-        - Prefect: durable_execution/prefect.md
+          - Overview: durable_execution/overview.md
+          - Temporal: durable_execution/temporal.md
+          - DBOS: durable_execution/dbos.md
+          - Prefect: durable_execution/prefect.md
       - UI Event Streams:
-        - Overview: ui/overview.md
-        - AG-UI: ui/ag-ui.md
-        - Vercel AI: ui/vercel-ai.md
+          - Overview: ui/overview.md
+          - AG-UI: ui/ag-ui.md
+          - Vercel AI: ui/vercel-ai.md
       - Agent2Agent (A2A): a2a.md
 
   - Related Packages:
@@ -233,6 +234,7 @@ theme:
     - navigation.sections
     - navigation.tracking
     - toc.follow
+    - announce.dismiss
   logo: "img/logo-white.svg"
   favicon: "favicon.ico"
 

pydantic_ai_slim/pydantic_ai/durable_exec/temporal/__init__.py

@@ -75,6 +75,8 @@ def configure_worker(self, config: WorkerConfig) -> WorkerConfig:
                     'httpx',
                     'anyio',
                     'httpcore',
+                    # Used by fastmcp via py-key-value-aio
+                    'beartype',
                     # Imported inside `logfire._internal.json_encoder` when running `logfire.info` inside an activity with attributes to serialize
                     'attrs',
                     # Imported inside `logfire._internal.json_schema` when running `logfire.info` inside an activity with attributes to serialize