Merge branch 'main' into update-versins

Author: medaminezghal

docs/a2a.md

@@ -27,7 +27,7 @@ The library is designed to be used with any agentic framework, and is **not excl
 
 ### Design
 
-**FastA2A** is built on top of [Starlette](https://starlette.io), which means it's fully compatible with any ASGI server.
+**FastA2A** is built on top of [Starlette](https://www.starlette.io), which means it's fully compatible with any ASGI server.
 
 Given the nature of the A2A protocol, it's important to understand the design before using it, as a developer
 you'll need to provide some components:
@@ -66,7 +66,7 @@ pip/uv-add fasta2a
 
 The only dependencies are:
 
-- [starlette](https://starlette.io): to expose the A2A server as an [ASGI application](https://asgi.readthedocs.io/en/latest/)
+- [starlette](https://www.starlette.io): to expose the A2A server as an [ASGI application](https://asgi.readthedocs.io/en/latest/)
 - [pydantic](https://pydantic.dev): to validate the request/response messages
 - [opentelemetry-api](https://opentelemetry-python.readthedocs.io/en/latest): to provide tracing capabilities
 

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/mcp/client.md

@@ -31,7 +31,7 @@ Examples of both are shown below; [mcp-run-python](run-python.md) is used as the
 !!! note
     [`MCPServerSSE`][pydantic_ai.mcp.MCPServerSSE] requires an MCP server to be running and accepting HTTP connections before calling [`agent.run_mcp_servers()`][pydantic_ai.Agent.run_mcp_servers]. Running the server is not managed by PydanticAI.
 
-The name "HTTP" is used since this implemented will be adapted in future to use the new
+The name "HTTP" is used since this implementation will be adapted in future to use the new
 [Streamable HTTP](https://github.com/modelcontextprotocol/specification/pull/206) currently in development.
 
 Before creating the SSE client, we need to run the server (docs [here](run-python.md)):
@@ -371,7 +371,7 @@ async def main():
 
 _(This example is complete, it can be run "as is" with Python 3.10+)_
 
-You can disallow sampling by settings [`allow_sampling=False`][pydantic_ai.mcp.MCPServerStdio.allow_sampling] when creating the server reference, e.g.:
+You can disallow sampling by setting [`allow_sampling=False`][pydantic_ai.mcp.MCPServerStdio.allow_sampling] when creating the server reference, e.g.:
 
 ```python {title="sampling_disallowed.py" hl_lines="6" py="3.10"}
 from pydantic_ai.mcp import MCPServerStdio

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)

examples/pydantic_ai_examples/stream_whales.py

@@ -11,7 +11,7 @@
 from typing import Annotated
 
 import logfire
-from pydantic import Field, ValidationError
+from pydantic import Field
 from rich.console import Console
 from rich.live import Live
 from rich.table import Table
@@ -51,20 +51,7 @@ async def main():
         ) as result:
             console.print('Response:', style='green')
 
-            async for message, last in result.stream_structured(debounce_by=0.01):
-                try:
-                    whales = await result.validate_structured_output(
-                        message, allow_partial=not last
-                    )
-                except ValidationError as exc:
-                    if all(
-                        e['type'] == 'missing' and e['loc'] == ('response',)
-                        for e in exc.errors()
-                    ):
-                        continue
-                    else:
-                        raise
-
+            async for whales in result.stream(debounce_by=0.01):
                 table = Table(
                     title='Species of Whale',
                     caption='Streaming Structured responses from GPT-4',

examples/pydantic_ai_examples/weather_agent.py

@@ -12,16 +12,14 @@
 from __future__ import annotations as _annotations
 
 import asyncio
-import os
-import urllib.parse
 from dataclasses import dataclass
 from typing import Any
 
 import logfire
-from devtools import debug
 from httpx import AsyncClient
+from pydantic import BaseModel
 
-from pydantic_ai import Agent, ModelRetry, RunContext
+from pydantic_ai import Agent, RunContext
 
 # 'if-token-present' means nothing will be sent (and the example will work) if you don't have logfire configured
 logfire.configure(send_to_logfire='if-token-present')
@@ -31,51 +29,38 @@
 @dataclass
 class Deps:
     client: AsyncClient
-    weather_api_key: str | None
-    geo_api_key: str | None
 
 
 weather_agent = Agent(
-    'openai:gpt-4o',
+    'openai:gpt-4.1-mini',
     # 'Be concise, reply with one sentence.' is enough for some models (like openai) to use
     # the below tools appropriately, but others like anthropic and gemini require a bit more direction.
-    instructions=(
-        'Be concise, reply with one sentence.'
-        'Use the `get_lat_lng` tool to get the latitude and longitude of the locations, '
-        'then use the `get_weather` tool to get the weather.'
-    ),
+    instructions='Be concise, reply with one sentence.',
     deps_type=Deps,
     retries=2,
 )
 
 
+class LatLng(BaseModel):
+    lat: float
+    lng: float
+
+
 @weather_agent.tool
-async def get_lat_lng(
-    ctx: RunContext[Deps], location_description: str
-) -> dict[str, float]:
+async def get_lat_lng(ctx: RunContext[Deps], location_description: str) -> LatLng:
     """Get the latitude and longitude of a location.
 
     Args:
         ctx: The context.
         location_description: A description of a location.
     """
-    if ctx.deps.geo_api_key is None:
-        # if no API key is provided, return a dummy response (London)
-        return {'lat': 51.1, 'lng': -0.1}
-
-    params = {'access_token': ctx.deps.geo_api_key}
-    loc = urllib.parse.quote(location_description)
+    # NOTE: the response here will be random, and is not related to the location description.
     r = await ctx.deps.client.get(
-        f'https://api.mapbox.com/geocoding/v5/mapbox.places/{loc}.json', params=params
+        'https://demo-endpoints.pydantic.workers.dev/latlng',
+        params={'location': location_description},
     )
     r.raise_for_status()
-    data = r.json()
-
-    if features := data['features']:
-        lat, lng = features[0]['center']
-        return {'lat': lat, 'lng': lng}
-    else:
-        raise ModelRetry('Could not find the location')
+    return LatLng.model_validate_json(r.content)
 
 
 @weather_agent.tool
@@ -87,70 +72,32 @@ async def get_weather(ctx: RunContext[Deps], lat: float, lng: float) -> dict[str
         lat: Latitude of the location.
         lng: Longitude of the location.
     """
-    if ctx.deps.weather_api_key is None:
-        # if no API key is provided, return a dummy response
-        return {'temperature': '21 °C', 'description': 'Sunny'}
-
-    params = {
-        'apikey': ctx.deps.weather_api_key,
-        'location': f'{lat},{lng}',
-        'units': 'metric',
-    }
-    with logfire.span('calling weather API', params=params) as span:
-        r = await ctx.deps.client.get(
-            'https://api.tomorrow.io/v4/weather/realtime', params=params
-        )
-        r.raise_for_status()
-        data = r.json()
-        span.set_attribute('response', data)
-
-    values = data['data']['values']
-    # https://docs.tomorrow.io/reference/data-layers-weather-codes
-    code_lookup = {
-        1000: 'Clear, Sunny',
-        1100: 'Mostly Clear',
-        1101: 'Partly Cloudy',
-        1102: 'Mostly Cloudy',
-        1001: 'Cloudy',
-        2000: 'Fog',
-        2100: 'Light Fog',
-        4000: 'Drizzle',
-        4001: 'Rain',
-        4200: 'Light Rain',
-        4201: 'Heavy Rain',
-        5000: 'Snow',
-        5001: 'Flurries',
-        5100: 'Light Snow',
-        5101: 'Heavy Snow',
-        6000: 'Freezing Drizzle',
-        6001: 'Freezing Rain',
-        6200: 'Light Freezing Rain',
-        6201: 'Heavy Freezing Rain',
-        7000: 'Ice Pellets',
-        7101: 'Heavy Ice Pellets',
-        7102: 'Light Ice Pellets',
-        8000: 'Thunderstorm',
-    }
+    # NOTE: the responses here will be random, and are not related to the lat and lng.
+    temp_response, descr_response = await asyncio.gather(
+        ctx.deps.client.get(
+            'https://demo-endpoints.pydantic.workers.dev/number',
+            params={'min': 10, 'max': 30},
+        ),
+        ctx.deps.client.get(
+            'https://demo-endpoints.pydantic.workers.dev/weather',
+            params={'lat': lat, 'lng': lng},
+        ),
+    )
+    temp_response.raise_for_status()
+    descr_response.raise_for_status()
     return {
-        'temperature': f'{values["temperatureApparent"]:0.0f}°C',
-        'description': code_lookup.get(values['weatherCode'], 'Unknown'),
+        'temperature': f'{temp_response.text} °C',
+        'description': descr_response.text,
     }
 
 
 async def main():
     async with AsyncClient() as client:
         logfire.instrument_httpx(client, capture_all=True)
-        # create a free API key at https://www.tomorrow.io/weather-api/
-        weather_api_key = os.getenv('WEATHER_API_KEY')
-        # create a free API key at https://www.mapbox.com/
-        geo_api_key = os.getenv('GEO_API_KEY')
-        deps = Deps(
-            client=client, weather_api_key=weather_api_key, geo_api_key=geo_api_key
-        )
+        deps = Deps(client=client)
         result = await weather_agent.run(
             'What is the weather like in London and in Wiltshire?', deps=deps
         )
-        debug(result)
         print('Response:', result.output)
 
 

examples/pydantic_ai_examples/weather_agent_gradio.py

@@ -1,7 +1,6 @@
 from __future__ import annotations as _annotations
 
 import json
-import os
 
 from httpx import AsyncClient
 
@@ -18,10 +17,7 @@
 TOOL_TO_DISPLAY_NAME = {'get_lat_lng': 'Geocoding API', 'get_weather': 'Weather API'}
 
 client = AsyncClient()
-weather_api_key = os.getenv('WEATHER_API_KEY')
-# create a free API key at https://geocode.maps.co/
-geo_api_key = os.getenv('GEO_API_KEY')
-deps = Deps(client=client, weather_api_key=weather_api_key, geo_api_key=geo_api_key)
+deps = Deps(client=client)
 
 
 async def stream_from_agent(prompt: str, chatbot: list[dict], past_messages: list):

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -641,7 +641,6 @@ async def process_function_tools(  # noqa C901
     run_context = build_run_context(ctx)
 
     calls_to_run: list[tuple[Tool[DepsT], _messages.ToolCallPart]] = []
-    call_index_to_event_id: dict[int, str] = {}
     for call in tool_calls:
         if (
             call.tool_name == output_tool_name
@@ -668,7 +667,6 @@ async def process_function_tools(  # noqa C901
             else:
                 event = _messages.FunctionToolCallEvent(call)
                 yield event
-                call_index_to_event_id[len(calls_to_run)] = event.call_id
                 calls_to_run.append((tool, call))
         elif mcp_tool := await _tool_from_mcp_server(call.tool_name, ctx):
             if stub_function_tools:
@@ -683,7 +681,6 @@ async def process_function_tools(  # noqa C901
             else:
                 event = _messages.FunctionToolCallEvent(call)
                 yield event
-                call_index_to_event_id[len(calls_to_run)] = event.call_id
                 calls_to_run.append((mcp_tool, call))
         elif call.tool_name in output_schema.tools:
             # if tool_name is in output_schema, it means we found a output tool but an error occurred in
@@ -700,13 +697,13 @@ async def process_function_tools(  # noqa C901
                     content=content,
                     tool_call_id=call.tool_call_id,
                 )
-                yield _messages.FunctionToolResultEvent(part, tool_call_id=call.tool_call_id)
+                yield _messages.FunctionToolResultEvent(part)
                 output_parts.append(part)
         else:
             yield _messages.FunctionToolCallEvent(call)
 
             part = _unknown_tool(call.tool_name, call.tool_call_id, ctx)
-            yield _messages.FunctionToolResultEvent(part, tool_call_id=call.tool_call_id)
+            yield _messages.FunctionToolResultEvent(part)
             output_parts.append(part)
 
     if not calls_to_run:
@@ -738,7 +735,7 @@ async def process_function_tools(  # noqa C901
             for task in done:
                 index = tasks.index(task)
                 result = task.result()
-                yield _messages.FunctionToolResultEvent(result, tool_call_id=call_index_to_event_id[index])
+                yield _messages.FunctionToolResultEvent(result)
 
                 if isinstance(result, _messages.RetryPromptPart):
                     results_by_index[index] = result