pydantic-ai-slim 0.2.16__tar.gz → 0.2.18__tar.gz

{pydantic_ai_slim-0.2.16 → pydantic_ai_slim-0.2.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydantic-ai-slim
-Version: 0.2.16
+Version: 0.2.18
 Summary: Agent Framework / shim to use Pydantic with LLMs, slim package
 Author-email: Samuel Colvin <samuel@pydantic.dev>, Marcelo Trylesinski <marcelotryle@gmail.com>, David Montague <david@pydantic.dev>, Alex Hall <alex@pydantic.dev>
 License-Expression: MIT
@@ -30,11 +30,11 @@ Requires-Dist: exceptiongroup; python_version < '3.11'
 Requires-Dist: griffe>=1.3.2
 Requires-Dist: httpx>=0.27
 Requires-Dist: opentelemetry-api>=1.28.0
-Requires-Dist: pydantic-graph==0.2.16
+Requires-Dist: pydantic-graph==0.2.18
 Requires-Dist: pydantic>=2.10
 Requires-Dist: typing-inspection>=0.4.0
 Provides-Extra: a2a
-Requires-Dist: fasta2a==0.2.16; extra == 'a2a'
+Requires-Dist: fasta2a==0.2.18; extra == 'a2a'
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.52.0; extra == 'anthropic'
 Provides-Extra: bedrock
@@ -48,7 +48,7 @@ Requires-Dist: cohere>=5.13.11; (platform_system != 'Emscripten') and extra == '
 Provides-Extra: duckduckgo
 Requires-Dist: duckduckgo-search>=7.0.0; extra == 'duckduckgo'
 Provides-Extra: evals
-Requires-Dist: pydantic-evals==0.2.16; extra == 'evals'
+Requires-Dist: pydantic-evals==0.2.18; extra == 'evals'
 Provides-Extra: google
 Requires-Dist: google-genai>=1.15.0; extra == 'google'
 Provides-Extra: groq
@@ -56,7 +56,7 @@ Requires-Dist: groq>=0.15.0; extra == 'groq'
 Provides-Extra: logfire
 Requires-Dist: logfire>=3.11.0; extra == 'logfire'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.9.0; (python_version >= '3.10') and extra == 'mcp'
+Requires-Dist: mcp>=1.9.4; (python_version >= '3.10') and extra == 'mcp'
 Provides-Extra: mistral
 Requires-Dist: mistralai>=1.2.5; extra == 'mistral'
 Provides-Extra: openai

{pydantic_ai_slim-0.2.16 → pydantic_ai_slim-0.2.18}/pydantic_ai/_agent_graph.py

@@ -183,6 +183,16 @@ class UserPromptNode(AgentNode[DepsT, NodeRunEndT]):
 
         if user_prompt is not None:
             parts.append(_messages.UserPromptPart(user_prompt))
+        elif (
+            len(parts) == 0
+            and message_history
+            and (last_message := message_history[-1])
+            and isinstance(last_message, _messages.ModelRequest)
+        ):
+            # Drop last message that came from history and reuse its parts
+            messages.pop()
+            parts.extend(last_message.parts)
+
         return messages, _messages.ModelRequest(parts, instructions=instructions)
 
     async def _reevaluate_dynamic_prompts(

{pydantic_ai_slim-0.2.16 → pydantic_ai_slim-0.2.18}/pydantic_ai/mcp.py

@@ -1,27 +1,32 @@
 from __future__ import annotations
 
 import base64
+import functools
 import json
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Sequence
-from contextlib import AsyncExitStack, asynccontextmanager
+from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager
 from dataclasses import dataclass
 from pathlib import Path
 from types import TracebackType
-from typing import Any
+from typing import Any, Callable
 
 import anyio
+import httpx
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from mcp.client.streamable_http import GetSessionIdCallback, streamablehttp_client
+from mcp.shared.message import SessionMessage
 from mcp.types import (
+    AudioContent,
     BlobResourceContents,
+    Content,
     EmbeddedResource,
     ImageContent,
-    JSONRPCMessage,
     LoggingLevel,
     TextContent,
     TextResourceContents,
 )
-from typing_extensions import Self, assert_never
+from typing_extensions import Self, assert_never, deprecated
 
 from pydantic_ai.exceptions import ModelRetry
 from pydantic_ai.messages import BinaryContent
@@ -37,7 +42,7 @@ except ImportError as _import_error:
         'you can use the `mcp` optional group — `pip install "pydantic-ai-slim[mcp]"`'
     ) from _import_error
 
-__all__ = 'MCPServer', 'MCPServerStdio', 'MCPServerHTTP'
+__all__ = 'MCPServer', 'MCPServerStdio', 'MCPServerHTTP', 'MCPServerSSE', 'MCPServerStreamableHTTP'
 
 
 class MCPServer(ABC):
@@ -56,8 +61,8 @@ class MCPServer(ABC):
     """
 
     _client: ClientSession
-    _read_stream: MemoryObjectReceiveStream[JSONRPCMessage | Exception]
-    _write_stream: MemoryObjectSendStream[JSONRPCMessage]
+    _read_stream: MemoryObjectReceiveStream[SessionMessage | Exception]
+    _write_stream: MemoryObjectSendStream[SessionMessage]
     _exit_stack: AsyncExitStack
 
     @abstractmethod
@@ -66,8 +71,8 @@ class MCPServer(ABC):
         self,
     ) -> AsyncIterator[
         tuple[
-            MemoryObjectReceiveStream[JSONRPCMessage | Exception],
-            MemoryObjectSendStream[JSONRPCMessage],
+            MemoryObjectReceiveStream[SessionMessage | Exception],
+            MemoryObjectSendStream[SessionMessage],
         ]
     ]:
         """Create the streams for the MCP server."""
@@ -158,9 +163,7 @@ class MCPServer(ABC):
         await self._exit_stack.aclose()
         self.is_running = False
 
-    def _map_tool_result_part(
-        self, part: TextContent | ImageContent | EmbeddedResource
-    ) -> str | BinaryContent | dict[str, Any] | list[Any]:
+    def _map_tool_result_part(self, part: Content) -> str | BinaryContent | dict[str, Any] | list[Any]:
         # See https://github.com/jlowin/fastmcp/blob/main/docs/servers/tools.mdx#return-values
 
         if isinstance(part, TextContent):
@@ -173,6 +176,10 @@ class MCPServer(ABC):
             return text
         elif isinstance(part, ImageContent):
             return BinaryContent(data=base64.b64decode(part.data), media_type=part.mimeType)
+        elif isinstance(part, AudioContent):
+            # NOTE: The FastMCP server doesn't support audio content.
+            # See <https://github.com/modelcontextprotocol/python-sdk/issues/952> for more details.
+            return BinaryContent(data=base64.b64decode(part.data), media_type=part.mimeType)  # pragma: no cover
         elif isinstance(part, EmbeddedResource):
             resource = part.resource
             if isinstance(resource, TextResourceContents):
@@ -266,8 +273,8 @@ class MCPServerStdio(MCPServer):
         self,
     ) -> AsyncIterator[
         tuple[
-            MemoryObjectReceiveStream[JSONRPCMessage | Exception],
-            MemoryObjectSendStream[JSONRPCMessage],
+            MemoryObjectReceiveStream[SessionMessage | Exception],
+            MemoryObjectSendStream[SessionMessage],
         ]
     ]:
         server = StdioServerParameters(command=self.command, args=list(self.args), env=self.env, cwd=self.cwd)
@@ -285,47 +292,40 @@ class MCPServerStdio(MCPServer):
 
 
 @dataclass
-class MCPServerHTTP(MCPServer):
-    """An MCP server that connects over streamable HTTP connections.
+class _MCPServerHTTP(MCPServer):
+    url: str
+    """The URL of the endpoint on the MCP server."""
 
-    This class implements the SSE transport from the MCP specification.
-    See <https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse> for more information.
+    headers: dict[str, Any] | None = None
+    """Optional HTTP headers to be sent with each request to the endpoint.
 
-    The name "HTTP" is used since this implemented will be adapted in future to use the new
-    [Streamable HTTP](https://github.com/modelcontextprotocol/specification/pull/206) currently in development.
+    These headers will be passed directly to the underlying `httpx.AsyncClient`.
+    Useful for authentication, custom headers, or other HTTP-specific configurations.
 
     !!! note
-        Using this class as an async context manager will create a new pool of HTTP connections to connect
-        to a server which should already be running.
+        You can either pass `headers` or `http_client`, but not both.
 
-    Example:
-    ```python {py="3.10"}
-    from pydantic_ai import Agent
-    from pydantic_ai.mcp import MCPServerHTTP
+        See [`MCPServerHTTP.http_client`][pydantic_ai.mcp.MCPServerHTTP.http_client] for more information.
+    """
 
-    server = MCPServerHTTP('http://localhost:3001/sse')  # (1)!
-    agent = Agent('openai:gpt-4o', mcp_servers=[server])
+    http_client: httpx.AsyncClient | None = None
+    """An `httpx.AsyncClient` to use with the endpoint.
 
-    async def main():
-        async with agent.run_mcp_servers():  # (2)!
-            ...
-    ```
+    This client may be configured to use customized connection parameters like self-signed certificates.
 
-    1. E.g. you might be connecting to a server run with [`mcp-run-python`](../mcp/run-python.md).
-    2. This will connect to a server running on `localhost:3001`.
-    """
+    !!! note
+        You can either pass `headers` or `http_client`, but not both.
 
-    url: str
-    """The URL of the SSE endpoint on the MCP server.
+        If you want to use both, you can pass the headers to the `http_client` instead.
 
-    For example for a server running locally, this might be `http://localhost:3001/sse`.
-    """
+        ```python {py="3.10" test="skip"}
+        import httpx
 
-    headers: dict[str, Any] | None = None
-    """Optional HTTP headers to be sent with each request to the SSE endpoint.
+        from pydantic_ai.mcp import MCPServerSSE
 
-    These headers will be passed directly to the underlying `httpx.AsyncClient`.
-    Useful for authentication, custom headers, or other HTTP-specific configurations.
+        http_client = httpx.AsyncClient(headers={'Authorization': 'Bearer ...'})
+        server = MCPServerSSE('http://localhost:3001/sse', http_client=http_client)
+        ```
     """
 
     timeout: float = 5
@@ -342,10 +342,11 @@ class MCPServerHTTP(MCPServer):
     If no new messages are received within this time, the connection will be considered stale
     and may be closed. Defaults to 5 minutes (300 seconds).
     """
+
     log_level: LoggingLevel | None = None
     """The log level to set when connecting to the server, if any.
 
-    See <https://modelcontextprotocol.io/specification/2025-03-26/server/utilities/logging#logging> for more details.
+    See <https://modelcontextprotocol.io/introduction#logging> for more details.
 
     If `None`, no log level will be set.
     """
@@ -358,28 +359,161 @@ class MCPServerHTTP(MCPServer):
     For example, if `tool_prefix='foo'`, then a tool named `bar` will be registered as `foo_bar`
     """
 
+    @property
+    @abstractmethod
+    def _transport_client(
+        self,
+    ) -> Callable[
+        ...,
+        AbstractAsyncContextManager[
+            tuple[
+                MemoryObjectReceiveStream[SessionMessage | Exception],
+                MemoryObjectSendStream[SessionMessage],
+                GetSessionIdCallback,
+            ],
+        ]
+        | AbstractAsyncContextManager[
+            tuple[
+                MemoryObjectReceiveStream[SessionMessage | Exception],
+                MemoryObjectSendStream[SessionMessage],
+            ]
+        ],
+    ]: ...
+
     @asynccontextmanager
     async def client_streams(
         self,
     ) -> AsyncIterator[
-        tuple[
-            MemoryObjectReceiveStream[JSONRPCMessage | Exception],
-            MemoryObjectSendStream[JSONRPCMessage],
-        ]
+        tuple[MemoryObjectReceiveStream[SessionMessage | Exception], MemoryObjectSendStream[SessionMessage]]
     ]:  # pragma: no cover
-        async with sse_client(
+        if self.http_client and self.headers:
+            raise ValueError('`http_client` is mutually exclusive with `headers`.')
+
+        transport_client_partial = functools.partial(
+            self._transport_client,
             url=self.url,
-            headers=self.headers,
             timeout=self.timeout,
             sse_read_timeout=self.sse_read_timeout,
-        ) as (read_stream, write_stream):
-            yield read_stream, write_stream
+        )
+
+        if self.http_client is not None:
+
+            def httpx_client_factory(
+                headers: dict[str, str] | None = None,
+                timeout: httpx.Timeout | None = None,
+                auth: httpx.Auth | None = None,
+            ) -> httpx.AsyncClient:
+                assert self.http_client is not None
+                return self.http_client
+
+            async with transport_client_partial(httpx_client_factory=httpx_client_factory) as (
+                read_stream,
+                write_stream,
+                *_,
+            ):
+                yield read_stream, write_stream
+        else:
+            async with transport_client_partial(headers=self.headers) as (read_stream, write_stream, *_):
+                yield read_stream, write_stream
 
     def _get_log_level(self) -> LoggingLevel | None:
         return self.log_level
 
     def __repr__(self) -> str:  # pragma: no cover
-        return f'MCPServerHTTP(url={self.url!r}, tool_prefix={self.tool_prefix!r})'
+        return f'{self.__class__.__name__}(url={self.url!r}, tool_prefix={self.tool_prefix!r})'
 
     def _get_client_initialize_timeout(self) -> float:  # pragma: no cover
         return self.timeout
+
+
+@dataclass
+class MCPServerSSE(_MCPServerHTTP):
+    """An MCP server that connects over streamable HTTP connections.
+
+    This class implements the SSE transport from the MCP specification.
+    See <https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse> for more information.
+
+    !!! note
+        Using this class as an async context manager will create a new pool of HTTP connections to connect
+        to a server which should already be running.
+
+    Example:
+    ```python {py="3.10"}
+    from pydantic_ai import Agent
+    from pydantic_ai.mcp import MCPServerSSE
+
+    server = MCPServerSSE('http://localhost:3001/sse')  # (1)!
+    agent = Agent('openai:gpt-4o', mcp_servers=[server])
+
+    async def main():
+        async with agent.run_mcp_servers():  # (2)!
+            ...
+    ```
+
+    1. E.g. you might be connecting to a server run with [`mcp-run-python`](../mcp/run-python.md).
+    2. This will connect to a server running on `localhost:3001`.
+    """
+
+    @property
+    def _transport_client(self):
+        return sse_client  # pragma: no cover
+
+
+@deprecated('The `MCPServerHTTP` class is deprecated, use `MCPServerSSE` instead.')
+@dataclass
+class MCPServerHTTP(MCPServerSSE):
+    """An MCP server that connects over HTTP using the old SSE transport.
+
+    This class implements the SSE transport from the MCP specification.
+    See <https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse> for more information.
+
+    !!! note
+        Using this class as an async context manager will create a new pool of HTTP connections to connect
+        to a server which should already be running.
+
+    Example:
+    ```python {py="3.10" test="skip"}
+    from pydantic_ai import Agent
+    from pydantic_ai.mcp import MCPServerHTTP
+
+    server = MCPServerHTTP('http://localhost:3001/sse')  # (1)!
+    agent = Agent('openai:gpt-4o', mcp_servers=[server])
+
+    async def main():
+        async with agent.run_mcp_servers():  # (2)!
+            ...
+    ```
+
+    1. E.g. you might be connecting to a server run with [`mcp-run-python`](../mcp/run-python.md).
+    2. This will connect to a server running on `localhost:3001`.
+    """
+
+
+@dataclass
+class MCPServerStreamableHTTP(_MCPServerHTTP):
+    """An MCP server that connects over HTTP using the Streamable HTTP transport.
+
+    This class implements the Streamable HTTP transport from the MCP specification.
+    See <https://modelcontextprotocol.io/introduction#streamable-http> for more information.
+
+    !!! note
+        Using this class as an async context manager will create a new pool of HTTP connections to connect
+        to a server which should already be running.
+
+    Example:
+    ```python {py="3.10"}
+    from pydantic_ai import Agent
+    from pydantic_ai.mcp import MCPServerStreamableHTTP
+
+    server = MCPServerStreamableHTTP('http://localhost:8000/mcp')  # (1)!
+    agent = Agent('openai:gpt-4o', mcp_servers=[server])
+
+    async def main():
+        async with agent.run_mcp_servers():  # (2)!
+            ...
+    ```
+    """
+
+    @property
+    def _transport_client(self):
+        return streamablehttp_client  # pragma: no cover

{pydantic_ai_slim-0.2.16 → pydantic_ai_slim-0.2.18}/pydantic_ai/messages.py

@@ -2,6 +2,7 @@ from __future__ import annotations as _annotations
 
 import base64
 import uuid
+from abc import ABC, abstractmethod
 from collections.abc import Sequence
 from dataclasses import dataclass, field, replace
 from datetime import datetime
@@ -80,8 +81,35 @@ class SystemPromptPart:
 
 
 @dataclass(repr=False)
-class VideoUrl:
-    """A URL to an video."""
+class FileUrl(ABC):
+    """Abstract base class for any URL-based file."""
+
+    url: str
+    """The URL of the file."""
+
+    force_download: bool = False
+    """If the model supports it:
+
+    * If True, the file is downloaded and the data is sent to the model as bytes.
+    * If False, the URL is sent directly to the model and no download is performed.
+    """
+
+    @property
+    @abstractmethod
+    def media_type(self) -> str:
+        """Return the media type of the file, based on the url."""
+
+    @property
+    @abstractmethod
+    def format(self) -> str:
+        """The file format."""
+
+    __repr__ = _utils.dataclasses_no_defaults_repr
+
+
+@dataclass(repr=False)
+class VideoUrl(FileUrl):
+    """A URL to a video."""
 
     url: str
     """The URL of the video."""
@@ -108,9 +136,19 @@ class VideoUrl:
             return 'video/x-ms-wmv'
         elif self.url.endswith('.three_gp'):
             return 'video/3gpp'
+        # Assume that YouTube videos are mp4 because there would be no extension
+        # to infer from. This should not be a problem, as Gemini disregards media
+        # type for YouTube URLs.
+        elif self.is_youtube:
+            return 'video/mp4'
         else:
             raise ValueError(f'Unknown video file extension: {self.url}')
 
+    @property
+    def is_youtube(self) -> bool:
+        """True if the URL has a YouTube domain."""
+        return self.url.startswith(('https://youtu.be/', 'https://youtube.com/', 'https://www.youtube.com/'))
+
     @property
     def format(self) -> VideoFormat:
         """The file format of the video.
@@ -119,11 +157,9 @@ class VideoUrl:
         """
         return _video_format_lookup[self.media_type]
 
-    __repr__ = _utils.dataclasses_no_defaults_repr
-
 
 @dataclass(repr=False)
-class AudioUrl:
+class AudioUrl(FileUrl):
     """A URL to an audio file."""
 
     url: str
@@ -147,11 +183,9 @@ class AudioUrl:
         """The file format of the audio file."""
         return _audio_format_lookup[self.media_type]
 
-    __repr__ = _utils.dataclasses_no_defaults_repr
-
 
 @dataclass(repr=False)
-class ImageUrl:
+class ImageUrl(FileUrl):
     """A URL to an image."""
 
     url: str
@@ -182,11 +216,9 @@ class ImageUrl:
         """
         return _image_format_lookup[self.media_type]
 
-    __repr__ = _utils.dataclasses_no_defaults_repr
-
 
 @dataclass(repr=False)
-class DocumentUrl:
+class DocumentUrl(FileUrl):
     """The URL of the document."""
 
     url: str
@@ -215,8 +247,6 @@ class DocumentUrl:
         except KeyError as e:
             raise ValueError(f'Unknown document media type: {media_type}') from e
 
-    __repr__ = _utils.dataclasses_no_defaults_repr
-
 
 @dataclass(repr=False)
 class BinaryContent:

{pydantic_ai_slim-0.2.16 → pydantic_ai_slim-0.2.18}/pydantic_ai/models/__init__.py

@@ -6,21 +6,23 @@ specific LLM being used.
 
 from __future__ import annotations as _annotations
 
+import base64
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Iterator
 from contextlib import asynccontextmanager, contextmanager
 from dataclasses import dataclass, field, replace
 from datetime import datetime
 from functools import cache, cached_property
+from typing import Generic, TypeVar, overload
 
 import httpx
-from typing_extensions import Literal, TypeAliasType
+from typing_extensions import Literal, TypeAliasType, TypedDict
 
 from pydantic_ai.profiles import DEFAULT_PROFILE, ModelProfile, ModelProfileSpec
 
 from .._parts_manager import ModelResponsePartsManager
 from ..exceptions import UserError
-from ..messages import ModelMessage, ModelRequest, ModelResponse, ModelResponseStreamEvent
+from ..messages import FileUrl, ModelMessage, ModelRequest, ModelResponse, ModelResponseStreamEvent, VideoUrl
 from ..profiles._json_schema import JsonSchemaTransformer
 from ..settings import ModelSettings
 from ..tools import ToolDefinition
@@ -553,9 +555,9 @@ def infer_model(model: Model | KnownModelName | str) -> Model:
 
         return OpenAIModel(model_name, provider=provider)
     elif provider in ('google-gla', 'google-vertex'):
-        from .gemini import GeminiModel
+        from .google import GoogleModel
 
-        return GeminiModel(model_name, provider=provider)
+        return GoogleModel(model_name, provider=provider)
     elif provider == 'groq':
         from .groq import GroqModel
 
@@ -611,6 +613,91 @@ def _cached_async_http_transport() -> httpx.AsyncHTTPTransport:
     return httpx.AsyncHTTPTransport()
 
 
+DataT = TypeVar('DataT', str, bytes)
+
+
+class DownloadedItem(TypedDict, Generic[DataT]):
+    """The downloaded data and its type."""
+
+    data: DataT
+    """The downloaded data."""
+
+    data_type: str
+    """The type of data that was downloaded.
+
+    Extracted from header "content-type", but defaults to the media type inferred from the file URL if content-type is "application/octet-stream".
+    """
+
+
+@overload
+async def download_item(
+    item: FileUrl,
+    data_format: Literal['bytes'],
+    type_format: Literal['mime', 'extension'] = 'mime',
+) -> DownloadedItem[bytes]: ...
+
+
+@overload
+async def download_item(
+    item: FileUrl,
+    data_format: Literal['base64', 'base64_uri', 'text'],
+    type_format: Literal['mime', 'extension'] = 'mime',
+) -> DownloadedItem[str]: ...
+
+
+async def download_item(
+    item: FileUrl,
+    data_format: Literal['bytes', 'base64', 'base64_uri', 'text'] = 'bytes',
+    type_format: Literal['mime', 'extension'] = 'mime',
+) -> DownloadedItem[str] | DownloadedItem[bytes]:
+    """Download an item by URL and return the content as a bytes object or a (base64-encoded) string.
+
+    Args:
+        item: The item to download.
+        data_format: The format to return the content in:
+            - `bytes`: The raw bytes of the content.
+            - `base64`: The base64-encoded content.
+            - `base64_uri`: The base64-encoded content as a data URI.
+            - `text`: The content as a string.
+        type_format: The format to return the media type in:
+            - `mime`: The media type as a MIME type.
+            - `extension`: The media type as an extension.
+
+    Raises:
+        UserError: If the URL points to a YouTube video or its protocol is gs://.
+    """
+    if item.url.startswith('gs://'):
+        raise UserError('Downloading from protocol "gs://" is not supported.')
+    elif isinstance(item, VideoUrl) and item.is_youtube:
+        raise UserError('Downloading YouTube videos is not supported.')
+
+    client = cached_async_http_client()
+    response = await client.get(item.url, follow_redirects=True)
+    response.raise_for_status()
+
+    if content_type := response.headers.get('content-type'):
+        content_type = content_type.split(';')[0]
+        if content_type == 'application/octet-stream':
+            content_type = None
+
+    media_type = content_type or item.media_type
+
+    data_type = media_type
+    if type_format == 'extension':
+        data_type = data_type.split('/')[1]
+
+    data = response.content
+    if data_format in ('base64', 'base64_uri'):
+        data = base64.b64encode(data).decode('utf-8')
+        if data_format == 'base64_uri':
+            data = f'data:{media_type};base64,{data}'
+        return DownloadedItem[str](data=data, data_type=data_type)
+    elif data_format == 'text':
+        return DownloadedItem[str](data=data.decode('utf-8'), data_type=data_type)
+    else:
+        return DownloadedItem[bytes](data=data, data_type=data_type)
+
+
 @cache
 def get_user_agent() -> str:
     """Get the user agent string for the HTTP client."""