pydantic-ai-slim 0.0.16__py3-none-any.whl → 0.0.17__py3-none-any.whl

pydantic_ai/agent.py

@@ -20,9 +20,10 @@ from . import (
     messages as _messages,
     models,
     result,
+    usage as _usage,
 )
 from .result import ResultData
-from .settings import ModelSettings, UsageLimits, merge_model_settings
+from .settings import ModelSettings, merge_model_settings
 from .tools import (
     AgentDeps,
     RunContext,
@@ -192,8 +193,8 @@ class Agent(Generic[AgentDeps, ResultData]):
         model: models.Model | models.KnownModelName | None = None,
         deps: AgentDeps = None,
         model_settings: ModelSettings | None = None,
-        usage_limits: UsageLimits | None = None,
-        usage: result.Usage | None = None,
+        usage_limits: _usage.UsageLimits | None = None,
+        usage: _usage.Usage | None = None,
         infer_name: bool = True,
     ) -> result.RunResult[ResultData]:
         """Run the agent with a user prompt in async mode.
@@ -236,7 +237,7 @@ class Agent(Generic[AgentDeps, ResultData]):
             model_name=model_used.name(),
             agent_name=self.name or 'agent',
         ) as run_span:
-            run_context = RunContext(deps, model_used, usage or result.Usage(), user_prompt)
+            run_context = RunContext(deps, model_used, usage or _usage.Usage(), user_prompt)
             messages = await self._prepare_messages(user_prompt, message_history, run_context)
             run_context.messages = messages
 
@@ -244,7 +245,7 @@ class Agent(Generic[AgentDeps, ResultData]):
                 tool.current_retry = 0
 
             model_settings = merge_model_settings(self.model_settings, model_settings)
-            usage_limits = usage_limits or UsageLimits()
+            usage_limits = usage_limits or _usage.UsageLimits()
 
             while True:
                 usage_limits.check_before_request(run_context.usage)
@@ -272,11 +273,14 @@ class Agent(Generic[AgentDeps, ResultData]):
                     # Check if we got a final result
                     if final_result is not None:
                         result_data = final_result.data
+                        result_tool_name = final_result.tool_name
                         run_span.set_attribute('all_messages', messages)
                         run_span.set_attribute('usage', run_context.usage)
                         handle_span.set_attribute('result', result_data)
                         handle_span.message = 'handle model response -> final result'
-                        return result.RunResult(messages, new_message_index, result_data, run_context.usage)
+                        return result.RunResult(
+                            messages, new_message_index, result_data, result_tool_name, run_context.usage
+                        )
                     else:
                         # continue the conversation
                         handle_span.set_attribute('tool_responses', tool_responses)
@@ -291,8 +295,8 @@ class Agent(Generic[AgentDeps, ResultData]):
         model: models.Model | models.KnownModelName | None = None,
         deps: AgentDeps = None,
         model_settings: ModelSettings | None = None,
-        usage_limits: UsageLimits | None = None,
-        usage: result.Usage | None = None,
+        usage_limits: _usage.UsageLimits | None = None,
+        usage: _usage.Usage | None = None,
         infer_name: bool = True,
     ) -> result.RunResult[ResultData]:
         """Run the agent with a user prompt synchronously.
@@ -349,8 +353,8 @@ class Agent(Generic[AgentDeps, ResultData]):
         model: models.Model | models.KnownModelName | None = None,
         deps: AgentDeps = None,
         model_settings: ModelSettings | None = None,
-        usage_limits: UsageLimits | None = None,
-        usage: result.Usage | None = None,
+        usage_limits: _usage.UsageLimits | None = None,
+        usage: _usage.Usage | None = None,
         infer_name: bool = True,
     ) -> AsyncIterator[result.StreamedRunResult[AgentDeps, ResultData]]:
         """Run the agent with a user prompt in async mode, returning a streamed response.
@@ -396,7 +400,7 @@ class Agent(Generic[AgentDeps, ResultData]):
             model_name=model_used.name(),
             agent_name=self.name or 'agent',
         ) as run_span:
-            run_context = RunContext(deps, model_used, usage or result.Usage(), user_prompt)
+            run_context = RunContext(deps, model_used, usage or _usage.Usage(), user_prompt)
             messages = await self._prepare_messages(user_prompt, message_history, run_context)
             run_context.messages = messages
 
@@ -404,7 +408,7 @@ class Agent(Generic[AgentDeps, ResultData]):
                 tool.current_retry = 0
 
             model_settings = merge_model_settings(self.model_settings, model_settings)
-            usage_limits = usage_limits or UsageLimits()
+            usage_limits = usage_limits or _usage.UsageLimits()
 
             while True:
                 run_context.run_step += 1

pydantic_ai/format_as_xml.py

@@ -0,0 +1,115 @@
+from __future__ import annotations as _annotations
+
+from collections.abc import Iterable, Iterator, Mapping
+from dataclasses import asdict, dataclass, is_dataclass
+from datetime import date
+from typing import Any
+from xml.etree import ElementTree
+
+from pydantic import BaseModel
+
+__all__ = ('format_as_xml',)
+
+
+def format_as_xml(
+    obj: Any,
+    root_tag: str = 'examples',
+    item_tag: str = 'example',
+    include_root_tag: bool = True,
+    none_str: str = 'null',
+    indent: str | None = '  ',
+) -> str:
+    """Format a Python object as XML.
+
+    This is useful since LLMs often find it easier to read semi-structured data (e.g. examples) as XML,
+    rather than JSON etc.
+
+    Supports: `str`, `bytes`, `bytearray`, `bool`, `int`, `float`, `date`, `datetime`, `Mapping`,
+    `Iterable`, `dataclass`, and `BaseModel`.
+
+    Args:
+        obj: Python Object to serialize to XML.
+        root_tag: Outer tag to wrap the XML in, use `None` to omit the outer tag.
+        item_tag: Tag to use for each item in an iterable (e.g. list), this is overridden by the class name
+            for dataclasses and Pydantic models.
+        include_root_tag: Whether to include the root tag in the output
+            (The root tag is always included if it includes a body - e.g. when the input is a simple value).
+        none_str: String to use for `None` values.
+        indent: Indentation string to use for pretty printing.
+
+    Returns: XML representation of the object.
+
+    Example:
+    ```python {title="format_as_xml_example.py" lint="skip"}
+    from pydantic_ai.format_as_xml import format_as_xml
+
+    print(format_as_xml({'name': 'John', 'height': 6, 'weight': 200}, root_tag='user'))
+    '''
+    <user>
+      <name>John</name>
+      <height>6</height>
+      <weight>200</weight>
+    </user>
+    '''
+    ```
+    """
+    el = _ToXml(item_tag=item_tag, none_str=none_str).to_xml(obj, root_tag)
+    if not include_root_tag and el.text is None:
+        join = '' if indent is None else '\n'
+        return join.join(_rootless_xml_elements(el, indent))
+    else:
+        if indent is not None:
+            ElementTree.indent(el, space=indent)
+        return ElementTree.tostring(el, encoding='unicode')
+
+
+@dataclass
+class _ToXml:
+    item_tag: str
+    none_str: str
+
+    def to_xml(self, value: Any, tag: str | None) -> ElementTree.Element:
+        element = ElementTree.Element(self.item_tag if tag is None else tag)
+        if value is None:
+            element.text = self.none_str
+        elif isinstance(value, str):
+            element.text = value
+        elif isinstance(value, (bytes, bytearray)):
+            element.text = value.decode(errors='ignore')
+        elif isinstance(value, (bool, int, float)):
+            element.text = str(value)
+        elif isinstance(value, date):
+            element.text = value.isoformat()
+        elif isinstance(value, Mapping):
+            self._mapping_to_xml(element, value)  # pyright: ignore[reportUnknownArgumentType]
+        elif is_dataclass(value) and not isinstance(value, type):
+            if tag is None:
+                element = ElementTree.Element(value.__class__.__name__)
+            dc_dict = asdict(value)
+            self._mapping_to_xml(element, dc_dict)
+        elif isinstance(value, BaseModel):
+            if tag is None:
+                element = ElementTree.Element(value.__class__.__name__)
+            self._mapping_to_xml(element, value.model_dump(mode='python'))
+        elif isinstance(value, Iterable):
+            for item in value:  # pyright: ignore[reportUnknownVariableType]
+                item_el = self.to_xml(item, None)
+                element.append(item_el)
+        else:
+            raise TypeError(f'Unsupported type for XML formatting: {type(value)}')
+        return element
+
+    def _mapping_to_xml(self, element: ElementTree.Element, mapping: Mapping[Any, Any]) -> None:
+        for key, value in mapping.items():
+            if isinstance(key, int):
+                key = str(key)
+            elif not isinstance(key, str):
+                raise TypeError(f'Unsupported key type for XML formatting: {type(key)}, only str and int are allowed')
+            element.append(self.to_xml(value, key))
+
+
+def _rootless_xml_elements(root: ElementTree.Element, indent: str | None) -> Iterator[str]:
+    for sub_element in root:
+        if indent is not None:
+            ElementTree.indent(sub_element, space=indent)
+        yield ElementTree.tostring(sub_element, encoding='unicode')

pydantic_ai/models/gemini.py

@@ -273,17 +273,26 @@ class GeminiAgentModel(AgentModel):
         contents: list[_GeminiContent] = []
         for m in messages:
             if isinstance(m, ModelRequest):
+                message_parts: list[_GeminiPartUnion] = []
+
                 for part in m.parts:
                     if isinstance(part, SystemPromptPart):
                         sys_prompt_parts.append(_GeminiTextPart(text=part.content))
                     elif isinstance(part, UserPromptPart):
-                        contents.append(_content_user_prompt(part))
+                        message_parts.append(_GeminiTextPart(text=part.content))
                     elif isinstance(part, ToolReturnPart):
-                        contents.append(_content_tool_return(part))
+                        message_parts.append(_response_part_from_response(part.tool_name, part.model_response_object()))
                     elif isinstance(part, RetryPromptPart):
-                        contents.append(_content_retry_prompt(part))
+                        if part.tool_name is None:
+                            message_parts.append(_GeminiTextPart(text=part.model_response()))
+                        else:
+                            response = {'call_error': part.model_response()}
+                            message_parts.append(_response_part_from_response(part.tool_name, response))
                     else:
                         assert_never(part)
+
+                if message_parts:
+                    contents.append(_GeminiContent(role='user', parts=message_parts))
             elif isinstance(m, ModelResponse):
                 contents.append(_content_model_response(m))
             else:
@@ -420,24 +429,6 @@ class _GeminiContent(TypedDict):
     parts: list[_GeminiPartUnion]
 
 
-def _content_user_prompt(m: UserPromptPart) -> _GeminiContent:
-    return _GeminiContent(role='user', parts=[_GeminiTextPart(text=m.content)])
-
-
-def _content_tool_return(m: ToolReturnPart) -> _GeminiContent:
-    f_response = _response_part_from_response(m.tool_name, m.model_response_object())
-    return _GeminiContent(role='user', parts=[f_response])
-
-
-def _content_retry_prompt(m: RetryPromptPart) -> _GeminiContent:
-    if m.tool_name is None:
-        part = _GeminiTextPart(text=m.model_response())
-    else:
-        response = {'call_error': m.model_response()}
-        part = _response_part_from_response(m.tool_name, response)
-    return _GeminiContent(role='user', parts=[part])
-
-
 def _content_model_response(m: ModelResponse) -> _GeminiContent:
     parts: list[_GeminiPartUnion] = []
     for item in m.parts:

pydantic_ai/models/vertexai.py

@@ -178,7 +178,7 @@ def _creds_from_file(service_account_file: str | Path) -> ServiceAccountCredenti
 # pyright: reportUnknownVariableType=false
 # pyright: reportUnknownArgumentType=false
 async def _async_google_auth() -> tuple[BaseCredentials, str | None]:
-    return await run_in_executor(google.auth.default)
+    return await run_in_executor(google.auth.default, scopes=['https://www.googleapis.com/auth/cloud-platform'])
 
 
 # default expiry is 3600 seconds

pydantic_ai/result.py

@@ -2,7 +2,7 @@ from __future__ import annotations as _annotations
 
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Awaitable, Callable
-from copy import copy
+from copy import deepcopy
 from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Generic, Union, cast
@@ -11,16 +11,10 @@ import logfire_api
 from typing_extensions import TypeVar
 
 from . import _result, _utils, exceptions, messages as _messages, models
-from .settings import UsageLimits
 from .tools import AgentDeps, RunContext
+from .usage import Usage, UsageLimits
 
-__all__ = (
-    'ResultData',
-    'ResultValidatorFunc',
-    'Usage',
-    'RunResult',
-    'StreamedRunResult',
-)
+__all__ = 'ResultData', 'ResultValidatorFunc', 'RunResult', 'StreamedRunResult'
 
 
 ResultData = TypeVar('ResultData', default=str)
@@ -44,55 +38,6 @@ Usage `ResultValidatorFunc[AgentDeps, ResultData]`.
 _logfire = logfire_api.Logfire(otel_scope='pydantic-ai')
 
 
-@dataclass
-class Usage:
-    """LLM usage associated with a request or run.
-
-    Responsibility for calculating usage is on the model; PydanticAI simply sums the usage information across requests.
-
-    You'll need to look up the documentation of the model you're using to convert usage to monetary costs.
-    """
-
-    requests: int = 0
-    """Number of requests made to the LLM API."""
-    request_tokens: int | None = None
-    """Tokens used in processing requests."""
-    response_tokens: int | None = None
-    """Tokens used in generating responses."""
-    total_tokens: int | None = None
-    """Total tokens used in the whole run, should generally be equal to `request_tokens + response_tokens`."""
-    details: dict[str, int] | None = None
-    """Any extra details returned by the model."""
-
-    def incr(self, incr_usage: Usage, *, requests: int = 0) -> None:
-        """Increment the usage in place.
-
-        Args:
-            incr_usage: The usage to increment by.
-            requests: The number of requests to increment by in addition to `incr_usage.requests`.
-        """
-        self.requests += requests
-        for f in 'requests', 'request_tokens', 'response_tokens', 'total_tokens':
-            self_value = getattr(self, f)
-            other_value = getattr(incr_usage, f)
-            if self_value is not None or other_value is not None:
-                setattr(self, f, (self_value or 0) + (other_value or 0))
-
-        if incr_usage.details:
-            self.details = self.details or {}
-            for key, value in incr_usage.details.items():
-                self.details[key] = self.details.get(key, 0) + value
-
-    def __add__(self, other: Usage) -> Usage:
-        """Add two Usages together.
-
-        This is provided so it's trivial to sum usage information from multiple requests and runs.
-        """
-        new_usage = copy(self)
-        new_usage.incr(other)
-        return new_usage
-
-
 @dataclass
 class _BaseRunResult(ABC, Generic[ResultData]):
     """Base type for results.
@@ -103,25 +48,70 @@ class _BaseRunResult(ABC, Generic[ResultData]):
     _all_messages: list[_messages.ModelMessage]
     _new_message_index: int
 
-    def all_messages(self) -> list[_messages.ModelMessage]:
-        """Return the history of _messages."""
+    def all_messages(self, *, result_tool_return_content: str | None = None) -> list[_messages.ModelMessage]:
+        """Return the history of _messages.
+
+        Args:
+            result_tool_return_content: The return content of the tool call to set in the last message.
+                This provides a convenient way to modify the content of the result tool call if you want to continue
+                the conversation and want to set the response to the result tool call. If `None`, the last message will
+                not be modified.
+
+        Returns:
+            List of messages.
+        """
         # this is a method to be consistent with the other methods
+        if result_tool_return_content is not None:
+            raise NotImplementedError('Setting result tool return content is not supported for this result type.')
         return self._all_messages
 
-    def all_messages_json(self) -> bytes:
-        """Return all messages from [`all_messages`][pydantic_ai.result._BaseRunResult.all_messages] as JSON bytes."""
-        return _messages.ModelMessagesTypeAdapter.dump_json(self.all_messages())
+    def all_messages_json(self, *, result_tool_return_content: str | None = None) -> bytes:
+        """Return all messages from [`all_messages`][pydantic_ai.result._BaseRunResult.all_messages] as JSON bytes.
+
+        Args:
+            result_tool_return_content: The return content of the tool call to set in the last message.
+                This provides a convenient way to modify the content of the result tool call if you want to continue
+                the conversation and want to set the response to the result tool call. If `None`, the last message will
+                not be modified.
+
+        Returns:
+            JSON bytes representing the messages.
+        """
+        return _messages.ModelMessagesTypeAdapter.dump_json(
+            self.all_messages(result_tool_return_content=result_tool_return_content)
+        )
 
-    def new_messages(self) -> list[_messages.ModelMessage]:
+    def new_messages(self, *, result_tool_return_content: str | None = None) -> list[_messages.ModelMessage]:
         """Return new messages associated with this run.
 
-        System prompts and any messages from older runs are excluded.
+        Messages from older runs are excluded.
+
+        Args:
+            result_tool_return_content: The return content of the tool call to set in the last message.
+                This provides a convenient way to modify the content of the result tool call if you want to continue
+                the conversation and want to set the response to the result tool call. If `None`, the last message will
+                not be modified.
+
+        Returns:
+            List of new messages.
         """
-        return self.all_messages()[self._new_message_index :]
+        return self.all_messages(result_tool_return_content=result_tool_return_content)[self._new_message_index :]
+
+    def new_messages_json(self, *, result_tool_return_content: str | None = None) -> bytes:
+        """Return new messages from [`new_messages`][pydantic_ai.result._BaseRunResult.new_messages] as JSON bytes.
 
-    def new_messages_json(self) -> bytes:
-        """Return new messages from [`new_messages`][pydantic_ai.result._BaseRunResult.new_messages] as JSON bytes."""
-        return _messages.ModelMessagesTypeAdapter.dump_json(self.new_messages())
+        Args:
+            result_tool_return_content: The return content of the tool call to set in the last message.
+                This provides a convenient way to modify the content of the result tool call if you want to continue
+                the conversation and want to set the response to the result tool call. If `None`, the last message will
+                not be modified.
+
+        Returns:
+            JSON bytes representing the new messages.
+        """
+        return _messages.ModelMessagesTypeAdapter.dump_json(
+            self.new_messages(result_tool_return_content=result_tool_return_content)
+        )
 
     @abstractmethod
     def usage(self) -> Usage:
@@ -134,12 +124,45 @@ class RunResult(_BaseRunResult[ResultData]):
 
     data: ResultData
     """Data from the final response in the run."""
+    _result_tool_name: str | None
     _usage: Usage
 
     def usage(self) -> Usage:
         """Return the usage of the whole run."""
         return self._usage
 
+    def all_messages(self, *, result_tool_return_content: str | None = None) -> list[_messages.ModelMessage]:
+        """Return the history of _messages.
+
+        Args:
+            result_tool_return_content: The return content of the tool call to set in the last message.
+                This provides a convenient way to modify the content of the result tool call if you want to continue
+                the conversation and want to set the response to the result tool call. If `None`, the last message will
+                not be modified.
+
+        Returns:
+            List of messages.
+        """
+        if result_tool_return_content is not None:
+            return self._set_result_tool_return(result_tool_return_content)
+        else:
+            return self._all_messages
+
+    def _set_result_tool_return(self, return_content: str) -> list[_messages.ModelMessage]:
+        """Set return content for the result tool.
+
+        Useful if you want to continue the conversation and want to set the response to the result tool call.
+        """
+        if not self._result_tool_name:
+            raise ValueError('Cannot set result tool return content when the return type is `str`.')
+        messages = deepcopy(self._all_messages)
+        last_message = messages[-1]
+        for part in last_message.parts:
+            if isinstance(part, _messages.ToolReturnPart) and part.tool_name == self._result_tool_name:
+                part.content = return_content
+                return messages
+        raise LookupError(f'No tool call found with tool name {self._result_tool_name!r}.')
+
 
 @dataclass
 class StreamedRunResult(_BaseRunResult[ResultData], Generic[AgentDeps, ResultData]):

pydantic_ai/settings.py

@@ -1,15 +1,12 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 from httpx import Timeout
 from typing_extensions import TypedDict
 
-from .exceptions import UsageLimitExceeded
-
 if TYPE_CHECKING:
-    from .result import Usage
+    pass
 
 
 class ModelSettings(TypedDict, total=False):
@@ -82,60 +79,3 @@ def merge_model_settings(base: ModelSettings | None, overrides: ModelSettings |
         return base | overrides
     else:
         return base or overrides
-
-
-@dataclass
-class UsageLimits:
-    """Limits on model usage.
-
-    The request count is tracked by pydantic_ai, and the request limit is checked before each request to the model.
-    Token counts are provided in responses from the model, and the token limits are checked after each response.
-
-    Each of the limits can be set to `None` to disable that limit.
-    """
-
-    request_limit: int | None = 50
-    """The maximum number of requests allowed to the model."""
-    request_tokens_limit: int | None = None
-    """The maximum number of tokens allowed in requests to the model."""
-    response_tokens_limit: int | None = None
-    """The maximum number of tokens allowed in responses from the model."""
-    total_tokens_limit: int | None = None
-    """The maximum number of tokens allowed in requests and responses combined."""
-
-    def has_token_limits(self) -> bool:
-        """Returns `True` if this instance places any limits on token counts.
-
-        If this returns `False`, the `check_tokens` method will never raise an error.
-
-        This is useful because if we have token limits, we need to check them after receiving each streamed message.
-        If there are no limits, we can skip that processing in the streaming response iterator.
-        """
-        return any(
-            limit is not None
-            for limit in (self.request_tokens_limit, self.response_tokens_limit, self.total_tokens_limit)
-        )
-
-    def check_before_request(self, usage: Usage) -> None:
-        """Raises a `UsageLimitExceeded` exception if the next request would exceed the request_limit."""
-        request_limit = self.request_limit
-        if request_limit is not None and usage.requests >= request_limit:
-            raise UsageLimitExceeded(f'The next request would exceed the request_limit of {request_limit}')
-
-    def check_tokens(self, usage: Usage) -> None:
-        """Raises a `UsageLimitExceeded` exception if the usage exceeds any of the token limits."""
-        request_tokens = usage.request_tokens or 0
-        if self.request_tokens_limit is not None and request_tokens > self.request_tokens_limit:
-            raise UsageLimitExceeded(
-                f'Exceeded the request_tokens_limit of {self.request_tokens_limit} ({request_tokens=})'
-            )
-
-        response_tokens = usage.response_tokens or 0
-        if self.response_tokens_limit is not None and response_tokens > self.response_tokens_limit:
-            raise UsageLimitExceeded(
-                f'Exceeded the response_tokens_limit of {self.response_tokens_limit} ({response_tokens=})'
-            )
-
-        total_tokens = usage.total_tokens or 0
-        if self.total_tokens_limit is not None and total_tokens > self.total_tokens_limit:
-            raise UsageLimitExceeded(f'Exceeded the total_tokens_limit of {self.total_tokens_limit} ({total_tokens=})')

pydantic_ai/tools.py

@@ -4,11 +4,11 @@ import dataclasses
 import inspect
 from collections.abc import Awaitable
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar, Union, cast
+from typing import TYPE_CHECKING, Any, Callable, Generic, Union, cast
 
 from pydantic import ValidationError
 from pydantic_core import SchemaValidator
-from typing_extensions import Concatenate, ParamSpec, TypeAlias
+from typing_extensions import Concatenate, ParamSpec, TypeAlias, TypeVar
 
 from . import _pydantic, _utils, messages as _messages, models
 from .exceptions import ModelRetry, UnexpectedModelBehavior
@@ -30,7 +30,7 @@ __all__ = (
     'ToolDefinition',
 )
 
-AgentDeps = TypeVar('AgentDeps')
+AgentDeps = TypeVar('AgentDeps', default=None)
 """Type variable for agent dependencies."""
 
 
@@ -67,7 +67,7 @@ class RunContext(Generic[AgentDeps]):
         return dataclasses.replace(self, **kwargs)
 
 
-ToolParams = ParamSpec('ToolParams')
+ToolParams = ParamSpec('ToolParams', default=...)
 """Retrieval function param spec."""
 
 SystemPromptFunc = Union[
@@ -92,7 +92,7 @@ ToolFuncPlain = Callable[ToolParams, Any]
 Usage `ToolPlainFunc[ToolParams]`.
 """
 ToolFuncEither = Union[ToolFuncContext[AgentDeps, ToolParams], ToolFuncPlain[ToolParams]]
-"""Either part_kind of tool function.
+"""Either kind of tool function.
 
 This is just a union of [`ToolFuncContext`][pydantic_ai.tools.ToolFuncContext] and
 [`ToolFuncPlain`][pydantic_ai.tools.ToolFuncPlain].
@@ -134,7 +134,7 @@ A = TypeVar('A')
 class Tool(Generic[AgentDeps]):
     """A tool function for an agent."""
 
-    function: ToolFuncEither[AgentDeps, ...]
+    function: ToolFuncEither[AgentDeps]
     takes_ctx: bool
     max_retries: int | None
     name: str
@@ -150,7 +150,7 @@ class Tool(Generic[AgentDeps]):
 
     def __init__(
         self,
-        function: ToolFuncEither[AgentDeps, ...],
+        function: ToolFuncEither[AgentDeps],
         *,
         takes_ctx: bool | None = None,
         max_retries: int | None = None,

pydantic_ai/usage.py

@@ -0,0 +1,114 @@
+from __future__ import annotations as _annotations
+
+from copy import copy
+from dataclasses import dataclass
+
+from .exceptions import UsageLimitExceeded
+
+__all__ = 'Usage', 'UsageLimits'
+
+
+@dataclass
+class Usage:
+    """LLM usage associated with a request or run.
+
+    Responsibility for calculating usage is on the model; PydanticAI simply sums the usage information across requests.
+
+    You'll need to look up the documentation of the model you're using to convert usage to monetary costs.
+    """
+
+    requests: int = 0
+    """Number of requests made to the LLM API."""
+    request_tokens: int | None = None
+    """Tokens used in processing requests."""
+    response_tokens: int | None = None
+    """Tokens used in generating responses."""
+    total_tokens: int | None = None
+    """Total tokens used in the whole run, should generally be equal to `request_tokens + response_tokens`."""
+    details: dict[str, int] | None = None
+    """Any extra details returned by the model."""
+
+    def incr(self, incr_usage: Usage, *, requests: int = 0) -> None:
+        """Increment the usage in place.
+
+        Args:
+            incr_usage: The usage to increment by.
+            requests: The number of requests to increment by in addition to `incr_usage.requests`.
+        """
+        self.requests += requests
+        for f in 'requests', 'request_tokens', 'response_tokens', 'total_tokens':
+            self_value = getattr(self, f)
+            other_value = getattr(incr_usage, f)
+            if self_value is not None or other_value is not None:
+                setattr(self, f, (self_value or 0) + (other_value or 0))
+
+        if incr_usage.details:
+            self.details = self.details or {}
+            for key, value in incr_usage.details.items():
+                self.details[key] = self.details.get(key, 0) + value
+
+    def __add__(self, other: Usage) -> Usage:
+        """Add two Usages together.
+
+        This is provided so it's trivial to sum usage information from multiple requests and runs.
+        """
+        new_usage = copy(self)
+        new_usage.incr(other)
+        return new_usage
+
+
+@dataclass
+class UsageLimits:
+    """Limits on model usage.
+
+    The request count is tracked by pydantic_ai, and the request limit is checked before each request to the model.
+    Token counts are provided in responses from the model, and the token limits are checked after each response.
+
+    Each of the limits can be set to `None` to disable that limit.
+    """
+
+    request_limit: int | None = 50
+    """The maximum number of requests allowed to the model."""
+    request_tokens_limit: int | None = None
+    """The maximum number of tokens allowed in requests to the model."""
+    response_tokens_limit: int | None = None
+    """The maximum number of tokens allowed in responses from the model."""
+    total_tokens_limit: int | None = None
+    """The maximum number of tokens allowed in requests and responses combined."""
+
+    def has_token_limits(self) -> bool:
+        """Returns `True` if this instance places any limits on token counts.
+
+        If this returns `False`, the `check_tokens` method will never raise an error.
+
+        This is useful because if we have token limits, we need to check them after receiving each streamed message.
+        If there are no limits, we can skip that processing in the streaming response iterator.
+        """
+        return any(
+            limit is not None
+            for limit in (self.request_tokens_limit, self.response_tokens_limit, self.total_tokens_limit)
+        )
+
+    def check_before_request(self, usage: Usage) -> None:
+        """Raises a `UsageLimitExceeded` exception if the next request would exceed the request_limit."""
+        request_limit = self.request_limit
+        if request_limit is not None and usage.requests >= request_limit:
+            raise UsageLimitExceeded(f'The next request would exceed the request_limit of {request_limit}')
+
+    def check_tokens(self, usage: Usage) -> None:
+        """Raises a `UsageLimitExceeded` exception if the usage exceeds any of the token limits."""
+        request_tokens = usage.request_tokens or 0
+        if self.request_tokens_limit is not None and request_tokens > self.request_tokens_limit:
+            raise UsageLimitExceeded(
+                f'Exceeded the request_tokens_limit of {self.request_tokens_limit} ({request_tokens=})'
+            )
+
+        response_tokens = usage.response_tokens or 0
+        if self.response_tokens_limit is not None and response_tokens > self.response_tokens_limit:
+            raise UsageLimitExceeded(
+                f'Exceeded the response_tokens_limit of {self.response_tokens_limit} ({response_tokens=})'
+            )
+
+        total_tokens = usage.total_tokens or 0
+        if self.total_tokens_limit is not None and total_tokens > self.total_tokens_limit:
+            raise UsageLimitExceeded(f'Exceeded the total_tokens_limit of {self.total_tokens_limit} ({total_tokens=})')

{pydantic_ai_slim-0.0.16.dist-info → pydantic_ai_slim-0.0.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydantic-ai-slim
-Version: 0.0.16
+Version: 0.0.17
 Summary: Agent Framework / shim to use Pydantic with LLMs, slim package
 Author-email: Samuel Colvin <samuel@pydantic.dev>
 License-Expression: MIT

{pydantic_ai_slim-0.0.16.dist-info → pydantic_ai_slim-0.0.17.dist-info}/RECORD

@@ -4,23 +4,25 @@ pydantic_ai/_pydantic.py,sha256=qXi5IsyiYOHeg_-qozCdxkfeqw2z0gBTjqgywBCiJWo,8125
 pydantic_ai/_result.py,sha256=cUSugZQV0n5Z4fFHiMqua-2xs_0S6m-rr-yd6QS3nFE,10317
 pydantic_ai/_system_prompt.py,sha256=MZJWksIoS5GM3Au5lznlcQnC-h7eqwtE7oI5WFgRcOg,1090
 pydantic_ai/_utils.py,sha256=skWNgm89US_x1EpxdRy5wCkghBrm1XgxFCiEh6wAkAo,8753
-pydantic_ai/agent.py,sha256=NJTcPSlqb4Fd-x9pDPuoXGCwFGF1GHcHevutoB0Busw,52333
+pydantic_ai/agent.py,sha256=8v7gyfMKB76k04SabQNV3QtUz80fSSL2BofULWwYO-o,52514
 pydantic_ai/exceptions.py,sha256=eGDKX6bGhgVxXBzu81Sk3iiAkXr0GUtgT7bD5Rxlqpg,2028
+pydantic_ai/format_as_xml.py,sha256=Gm65687GL8Z6A_lPiJWL1O_E3ovHEBn2O1DKhn1CDnA,4472
 pydantic_ai/messages.py,sha256=ImbWY8Ft3mxInUQ08EmIWywf4nJBvTiJhmsECRYDkSQ,8968
 pydantic_ai/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pydantic_ai/result.py,sha256=LbZVHZnJnQwgegSz5PtwS9r_ifrJnLRpsa9xjYnHg1g,15549
-pydantic_ai/settings.py,sha256=W8krcFsujjhE03rwckrz39F4Dz_9RwdBSeEF3izK0-Y,4918
-pydantic_ai/tools.py,sha256=mnh3Lvs0Ri0FkqpV1MUooExNN4epTCcBKw6DyZvNSQ8,11745
+pydantic_ai/result.py,sha256=-dpaaD24E1Ns7fxz5Gn7SKou-A8Cag4LjEyCBJbrHzY,17597
+pydantic_ai/settings.py,sha256=oTk8ZfYuUsNxpJMWLvSrO1OH_0ur7VKgDNTMQG0tPyM,1974
+pydantic_ai/tools.py,sha256=G4lwAb7QIowtSHk7w5cH8WQFIFqwMPn0J6Nqhgz7ubA,11757
+pydantic_ai/usage.py,sha256=60d9f6M7YEYuKMbqDGDogX4KsA73fhDtWyDXYXoIPaI,4948
 pydantic_ai/models/__init__.py,sha256=XHt02IDQAircb-lEkIbIcuabSAIh5_UKnz2V1xN0Glw,10926
 pydantic_ai/models/anthropic.py,sha256=EUZgmvT0jhMDbooBp_jfW0z2cM5jTMuAhVws1XKgaNs,13451
 pydantic_ai/models/function.py,sha256=i7qkS_31aHrTbYVh6OzQ7Cwucz44F5PjT2EJK3GMphw,10573
-pydantic_ai/models/gemini.py,sha256=Sr19D2hN8iEAcoLlzv5883pto90TgEr_xiGlV8hMOwA,28572
+pydantic_ai/models/gemini.py,sha256=jHBVJFLgp7kPLXYy1zYTs_-ush9qS2fkmC28hK8vkJ0,28417
 pydantic_ai/models/groq.py,sha256=ZoPkuWJrf78JPnTRfZhi7v0ETgxJKNN5dH8BLWagGGk,15770
 pydantic_ai/models/mistral.py,sha256=xGVI6-b8-9vnFickPPI2cRaHEWLc0jKKUM_vMjipf-U,25894
 pydantic_ai/models/ollama.py,sha256=ELqxhcNcnvQBnadd3gukS01zprUp6v8N_h1P5K-uf6c,4188
 pydantic_ai/models/openai.py,sha256=qFFInL3NbgfGcsAWigxMP5mscp76hC-jJimHc9woU6Y,16518
 pydantic_ai/models/test.py,sha256=u2pdZd9OLXQ_jI6CaVt96udXuIcv0Hfnfqd3pFGmeJM,16514
-pydantic_ai/models/vertexai.py,sha256=DBCBfpvpIhZaMG7cKvRl5rugCZqJqqEFm74uBc45weo,9259
-pydantic_ai_slim-0.0.16.dist-info/METADATA,sha256=4udd7j2erIuMC0ekYgmgQAqsKfhA5sLsKzTcD_QyOeo,2730
-pydantic_ai_slim-0.0.16.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pydantic_ai_slim-0.0.16.dist-info/RECORD,,
+pydantic_ai/models/vertexai.py,sha256=gBlEGBIOoqGHYqu6d16VLRI0rWizx5I7P2s8IuGM1CQ,9318
+pydantic_ai_slim-0.0.17.dist-info/METADATA,sha256=hhVw5I9w5RQba3Dvsi3dKP9KUuFCfMuehHeGSQhhOmQ,2730
+pydantic_ai_slim-0.0.17.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydantic_ai_slim-0.0.17.dist-info/RECORD,,