pydantic-ai-slim 0.0.11__py3-none-any.whl → 0.0.13__py3-none-any.whl

pydantic_ai/tools.py

@@ -7,9 +7,9 @@ from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar, Union, cast
 
 from pydantic import ValidationError
 from pydantic_core import SchemaValidator
-from typing_extensions import Concatenate, ParamSpec, final
+from typing_extensions import Concatenate, ParamSpec, TypeAlias
 
-from . import _pydantic, _utils, messages
+from . import _pydantic, _utils, messages as _messages
 from .exceptions import ModelRetry, UnexpectedModelBehavior
 
 if TYPE_CHECKING:
@@ -27,7 +27,10 @@ __all__ = (
     'ToolFuncPlain',
     'ToolFuncEither',
     'ToolParams',
+    'ToolPrepareFunc',
     'Tool',
+    'ObjectJsonSchema',
+    'ToolDefinition',
 )
 
 AgentDeps = TypeVar('AgentDeps')
@@ -42,6 +45,8 @@ class RunContext(Generic[AgentDeps]):
     """Dependencies for the agent."""
     retry: int
     """Number of retries so far."""
+    messages: list[_messages.ModelMessage]
+    """Messages exchanged in the conversation so far."""
     tool_name: str | None
     """Name of the tool being called."""
 
@@ -84,18 +89,44 @@ ToolFuncPlain = Callable[ToolParams, Any]
 Usage `ToolPlainFunc[ToolParams]`.
 """
 ToolFuncEither = Union[ToolFuncContext[AgentDeps, ToolParams], ToolFuncPlain[ToolParams]]
-"""Either kind of tool function.
+"""Either part_kind of tool function.
 
 This is just a union of [`ToolFuncContext`][pydantic_ai.tools.ToolFuncContext] and
 [`ToolFuncPlain`][pydantic_ai.tools.ToolFuncPlain].
 
 Usage `ToolFuncEither[AgentDeps, ToolParams]`.
 """
+ToolPrepareFunc: TypeAlias = 'Callable[[RunContext[AgentDeps], ToolDefinition], Awaitable[ToolDefinition | None]]'
+"""Definition of a function that can prepare a tool definition at call time.
+
+See [tool docs](../tools.md#tool-prepare) for more information.
+
+Example — here `only_if_42` is valid as a `ToolPrepareFunc`:
+
+```python {lint="not-imports"}
+from typing import Union
+
+from pydantic_ai import RunContext, Tool
+from pydantic_ai.tools import ToolDefinition
+
+async def only_if_42(
+    ctx: RunContext[int], tool_def: ToolDefinition
+) -> Union[ToolDefinition, None]:
+    if ctx.deps == 42:
+        return tool_def
+
+def hitchhiker(ctx: RunContext[int], answer: str) -> str:
+    return f'{ctx.deps} {answer}'
+
+hitchhiker = Tool(hitchhiker, prepare=only_if_42)
+```
+
+Usage `ToolPrepareFunc[AgentDeps]`.
+"""
 
 A = TypeVar('A')
 
 
-@final
 @dataclass(init=False)
 class Tool(Generic[AgentDeps]):
     """A tool function for an agent."""
@@ -105,86 +136,120 @@ class Tool(Generic[AgentDeps]):
     max_retries: int | None
     name: str
     description: str
+    prepare: ToolPrepareFunc[AgentDeps] | None
     _is_async: bool = field(init=False)
     _single_arg_name: str | None = field(init=False)
     _positional_fields: list[str] = field(init=False)
     _var_positional_field: str | None = field(init=False)
     _validator: SchemaValidator = field(init=False, repr=False)
-    _json_schema: _utils.ObjectJsonSchema = field(init=False)
-    _current_retry: int = field(default=0, init=False)
+    _parameters_json_schema: ObjectJsonSchema = field(init=False)
+    current_retry: int = field(default=0, init=False)
 
     def __init__(
         self,
         function: ToolFuncEither[AgentDeps, ...],
-        takes_ctx: bool,
         *,
+        takes_ctx: bool | None = None,
         max_retries: int | None = None,
         name: str | None = None,
         description: str | None = None,
+        prepare: ToolPrepareFunc[AgentDeps] | None = None,
     ):
         """Create a new tool instance.
 
         Example usage:
 
-        ```py
+        ```python {lint="not-imports"}
+        from pydantic_ai import Agent, RunContext, Tool
+
+        async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
+            return f'{ctx.deps} {x} {y}'
+
+        agent = Agent('test', tools=[Tool(my_tool)])
+        ```
+
+        or with a custom prepare method:
+
+        ```python {lint="not-imports"}
+        from typing import Union
+
         from pydantic_ai import Agent, RunContext, Tool
+        from pydantic_ai.tools import ToolDefinition
 
         async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
             return f'{ctx.deps} {x} {y}'
 
-        agent = Agent('test', tools=[Tool(my_tool, True)])
+        async def prep_my_tool(
+            ctx: RunContext[int], tool_def: ToolDefinition
+        ) -> Union[ToolDefinition, None]:
+            # only register the tool if `deps == 42`
+            if ctx.deps == 42:
+                return tool_def
+
+        agent = Agent('test', tools=[Tool(my_tool, prepare=prep_my_tool)])
         ```
 
+
         Args:
             function: The Python function to call as the tool.
-            takes_ctx: Whether the function takes a [`RunContext`][pydantic_ai.tools.RunContext] first argument.
+            takes_ctx: Whether the function takes a [`RunContext`][pydantic_ai.tools.RunContext] first argument,
+                this is inferred if unset.
             max_retries: Maximum number of retries allowed for this tool, set to the agent default if `None`.
             name: Name of the tool, inferred from the function if `None`.
             description: Description of the tool, inferred from the function if `None`.
+            prepare: custom method to prepare the tool definition for each step, return `None` to omit this
+                tool from a given step. This is useful if you want to customise a tool at call time,
+                or omit it completely from a step. See [`ToolPrepareFunc`][pydantic_ai.tools.ToolPrepareFunc].
         """
+        if takes_ctx is None:
+            takes_ctx = _pydantic.takes_ctx(function)
+
         f = _pydantic.function_schema(function, takes_ctx)
         self.function = function
         self.takes_ctx = takes_ctx
         self.max_retries = max_retries
         self.name = name or function.__name__
         self.description = description or f['description']
+        self.prepare = prepare
         self._is_async = inspect.iscoroutinefunction(self.function)
         self._single_arg_name = f['single_arg_name']
         self._positional_fields = f['positional_fields']
         self._var_positional_field = f['var_positional_field']
         self._validator = f['validator']
-        self._json_schema = f['json_schema']
+        self._parameters_json_schema = f['json_schema']
 
-    @staticmethod
-    def infer(function: ToolFuncEither[A, ...] | Tool[A]) -> Tool[A]:
-        """Create a tool from a pure function, inferring whether it takes `RunContext` as its first argument.
+    async def prepare_tool_def(self, ctx: RunContext[AgentDeps]) -> ToolDefinition | None:
+        """Get the tool definition.
 
-        Args:
-            function: The tool function to wrap; or for convenience, a `Tool` instance.
+        By default, this method creates a tool definition, then either returns it, or calls `self.prepare`
+        if it's set.
 
         Returns:
-            A new `Tool` instance.
+            return a `ToolDefinition` or `None` if the tools should not be registered for this run.
         """
-        if isinstance(function, Tool):
-            return function
+        tool_def = ToolDefinition(
+            name=self.name,
+            description=self.description,
+            parameters_json_schema=self._parameters_json_schema,
+        )
+        if self.prepare is not None:
+            return await self.prepare(ctx, tool_def)
         else:
-            return Tool(function, takes_ctx=_pydantic.takes_ctx(function))
-
-    def reset(self) -> None:
-        """Reset the current retry count."""
-        self._current_retry = 0
+            return tool_def
 
-    async def run(self, deps: AgentDeps, message: messages.ToolCall) -> messages.Message:
+    async def run(
+        self, deps: AgentDeps, message: _messages.ToolCallPart, conv_messages: list[_messages.ModelMessage]
+    ) -> _messages.ModelRequestPart:
         """Run the tool function asynchronously."""
         try:
-            if isinstance(message.args, messages.ArgsJson):
+            if isinstance(message.args, _messages.ArgsJson):
                 args_dict = self._validator.validate_json(message.args.args_json)
             else:
                 args_dict = self._validator.validate_python(message.args.args_dict)
         except ValidationError as e:
             return self._on_error(e, message)
 
-        args, kwargs = self._call_args(deps, args_dict, message)
+        args, kwargs = self._call_args(deps, args_dict, message, conv_messages)
         try:
             if self._is_async:
                 function = cast(Callable[[Any], Awaitable[str]], self.function)
@@ -195,28 +260,24 @@ class Tool(Generic[AgentDeps]):
         except ModelRetry as e:
             return self._on_error(e, message)
 
-        self._current_retry = 0
-        return messages.ToolReturn(
+        self.current_retry = 0
+        return _messages.ToolReturnPart(
             tool_name=message.tool_name,
             content=response_content,
-            tool_id=message.tool_id,
+            tool_call_id=message.tool_call_id,
         )
 
-    @property
-    def json_schema(self) -> _utils.ObjectJsonSchema:
-        return self._json_schema
-
-    @property
-    def outer_typed_dict_key(self) -> str | None:
-        return None
-
     def _call_args(
-        self, deps: AgentDeps, args_dict: dict[str, Any], message: messages.ToolCall
+        self,
+        deps: AgentDeps,
+        args_dict: dict[str, Any],
+        message: _messages.ToolCallPart,
+        conv_messages: list[_messages.ModelMessage],
     ) -> tuple[list[Any], dict[str, Any]]:
         if self._single_arg_name:
             args_dict = {self._single_arg_name: args_dict}
 
-        args = [RunContext(deps, self._current_retry, message.tool_name)] if self.takes_ctx else []
+        args = [RunContext(deps, self.current_retry, conv_messages, message.tool_name)] if self.takes_ctx else []
         for positional_field in self._positional_fields:
             args.append(args_dict.pop(positional_field))
         if self._var_positional_field:
@@ -224,17 +285,51 @@ class Tool(Generic[AgentDeps]):
 
         return args, args_dict
 
-    def _on_error(self, exc: ValidationError | ModelRetry, call_message: messages.ToolCall) -> messages.RetryPrompt:
-        self._current_retry += 1
-        if self.max_retries is None or self._current_retry > self.max_retries:
+    def _on_error(
+        self, exc: ValidationError | ModelRetry, call_message: _messages.ToolCallPart
+    ) -> _messages.RetryPromptPart:
+        self.current_retry += 1
+        if self.max_retries is None or self.current_retry > self.max_retries:
             raise UnexpectedModelBehavior(f'Tool exceeded max retries count of {self.max_retries}') from exc
         else:
             if isinstance(exc, ValidationError):
                 content = exc.errors(include_url=False)
             else:
                 content = exc.message
-            return messages.RetryPrompt(
+            return _messages.RetryPromptPart(
                 tool_name=call_message.tool_name,
                 content=content,
-                tool_id=call_message.tool_id,
+                tool_call_id=call_message.tool_call_id,
             )
+
+
+ObjectJsonSchema: TypeAlias = dict[str, Any]
+"""Type representing JSON schema of an object, e.g. where `"type": "object"`.
+
+This type is used to define tools parameters (aka arguments) in [ToolDefinition][pydantic_ai.tools.ToolDefinition].
+
+With PEP-728 this should be a TypedDict with `type: Literal['object']`, and `extra_parts=Any`
+"""
+
+
+@dataclass
+class ToolDefinition:
+    """Definition of a tool passed to a model.
+
+    This is used for both function tools result tools.
+    """
+
+    name: str
+    """The name of the tool."""
+
+    description: str
+    """The description of the tool."""
+
+    parameters_json_schema: ObjectJsonSchema
+    """The JSON schema for the tool's parameters."""
+
+    outer_typed_dict_key: str | None = None
+    """The key in the outer [TypedDict] that wraps a result tool.
+
+    This will only be set for result tools which don't have an `object` JSON schema.
+    """

{pydantic_ai_slim-0.0.11.dist-info → pydantic_ai_slim-0.0.13.dist-info}/METADATA

@@ -1,9 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: pydantic-ai-slim
-Version: 0.0.11
+Version: 0.0.13
 Summary: Agent Framework / shim to use Pydantic with LLMs, slim package
 Author-email: Samuel Colvin <samuel@pydantic.dev>
-License: MIT
+License-Expression: MIT
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Environment :: MacOS X
@@ -29,10 +29,15 @@ Requires-Dist: griffe>=1.3.2
 Requires-Dist: httpx>=0.27.2
 Requires-Dist: logfire-api>=1.2.0
 Requires-Dist: pydantic>=2.10
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
 Provides-Extra: groq
 Requires-Dist: groq>=0.12.0; extra == 'groq'
 Provides-Extra: logfire
 Requires-Dist: logfire>=2.3; extra == 'logfire'
+Provides-Extra: mistral
+Requires-Dist: json-repair>=0.30.3; extra == 'mistral'
+Requires-Dist: mistralai>=1.2.5; extra == 'mistral'
 Provides-Extra: openai
 Requires-Dist: openai>=1.54.3; extra == 'openai'
 Provides-Extra: vertexai

pydantic_ai_slim-0.0.13.dist-info/RECORD

@@ -0,0 +1,26 @@
+pydantic_ai/__init__.py,sha256=a29NqQz0JyW4BoCjcRh23fBBfwY17_n57moE4QrFWM4,324
+pydantic_ai/_griffe.py,sha256=pRjCJ6B1hhx6k46XJgl9zF6aRYxRmqEZKFok8unp4Iw,3449
+pydantic_ai/_pydantic.py,sha256=qXi5IsyiYOHeg_-qozCdxkfeqw2z0gBTjqgywBCiJWo,8125
+pydantic_ai/_result.py,sha256=LycNJR_Whc9P7sz2uD-Ce5bs9kQBU6eYqQxCUDNiNxU,10453
+pydantic_ai/_system_prompt.py,sha256=2Ui7fYAXxR_aZZLJdwMnOAecBOIbrKwx1yV4Qz523WQ,1089
+pydantic_ai/_utils.py,sha256=skWNgm89US_x1EpxdRy5wCkghBrm1XgxFCiEh6wAkAo,8753
+pydantic_ai/agent.py,sha256=sDQE20lQXyWO-SrodqSNlzzGwtaLNSkla6NgyJXPKTU,48568
+pydantic_ai/exceptions.py,sha256=ko_47M0k6Rhg9mUC9P1cj7N4LCH6cC0pEsF65A2vL-U,1561
+pydantic_ai/messages.py,sha256=Qa9H5kf9qeI1NqB-XgRjPJ-wwgVKvDZxqam7gnsLtrc,8106
+pydantic_ai/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydantic_ai/result.py,sha256=ZhaYArCiVl9JlrTllaeFIl2vU2foiIgpQYGby55G4cQ,13664
+pydantic_ai/settings.py,sha256=3sUaDMVMBX9Pku4Bh7lpv6VizX1utenHd5kVIRJvHyY,1908
+pydantic_ai/tools.py,sha256=hhhe5_ELeyYpaRoETMLjml83FAbMY7cpo5us7qwbOWg,11532
+pydantic_ai/models/__init__.py,sha256=y1tkHgWjIGLhZX95dIeOXcljSiAiRGma2T55hNi8EwA,10897
+pydantic_ai/models/anthropic.py,sha256=YBqiYjvOVqsSHPNT2Vt2aMaAAa8nMK57IMPONrtBCyc,13430
+pydantic_ai/models/function.py,sha256=i54ce97lqmy1p7Vqc162EiF_72oA3khc7z2uBGZbuWg,10731
+pydantic_ai/models/gemini.py,sha256=3oy0FVHLOP8SEOvpvoWtlUhRCJpddRj4-J_IPXaEkLE,28277
+pydantic_ai/models/groq.py,sha256=dorqZk8xbZ4ZDzZothJoWbUkoD8TWHb6lftdkNDlsu0,15821
+pydantic_ai/models/mistral.py,sha256=S0K73J5AGKwJc0UU0ifCrPmcxR2QMvVS6L1Cq19xDrk,26793
+pydantic_ai/models/ollama.py,sha256=i3mMXkXu9xL6f4c52Eyx3j4aHKfYoloFondlGHPtkS4,3971
+pydantic_ai/models/openai.py,sha256=fo3ocIOylD8YTuJMTJR1eXcRAQDGFKWFIYYrSOQS1C0,16569
+pydantic_ai/models/test.py,sha256=mBQ0vJYjEMHv01A3yyHR2porkxekpmqIUBkK-W8d-L8,15530
+pydantic_ai/models/vertexai.py,sha256=DBCBfpvpIhZaMG7cKvRl5rugCZqJqqEFm74uBc45weo,9259
+pydantic_ai_slim-0.0.13.dist-info/METADATA,sha256=57JLefiQcRnSOVvkDHcik6wQ24FZ3HOmPrfCaBUe4X8,2785
+pydantic_ai_slim-0.0.13.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydantic_ai_slim-0.0.13.dist-info/RECORD,,

{pydantic_ai_slim-0.0.11.dist-info → pydantic_ai_slim-0.0.13.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.26.3
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any

pydantic_ai_slim-0.0.11.dist-info/RECORD

@@ -1,22 +0,0 @@
-pydantic_ai/__init__.py,sha256=a29NqQz0JyW4BoCjcRh23fBBfwY17_n57moE4QrFWM4,324
-pydantic_ai/_griffe.py,sha256=pRjCJ6B1hhx6k46XJgl9zF6aRYxRmqEZKFok8unp4Iw,3449
-pydantic_ai/_pydantic.py,sha256=oFfcHDv_wuL1NQ7mCzVHvP1HBaVzyvb7xS-_Iiri_tA,8491
-pydantic_ai/_result.py,sha256=wzcfwDpr_sro1Vkn3DkyIhCXMHTReDxL_ZYm50JzdRI,9667
-pydantic_ai/_system_prompt.py,sha256=vFT0y9Wykl5veGMgLLkGRYiHQrgdW2BZ1rwMn4izjjo,1085
-pydantic_ai/_utils.py,sha256=eNb7f3-ZQC8WDEa87iUcXGQ-lyuutFQG-5yBCMD4Vvs,8227
-pydantic_ai/agent.py,sha256=5QOiDVByatRqKlxyRLba0fBUZcuaEkew3eqovFiOB5M,37311
-pydantic_ai/exceptions.py,sha256=ko_47M0k6Rhg9mUC9P1cj7N4LCH6cC0pEsF65A2vL-U,1561
-pydantic_ai/messages.py,sha256=I0_CPXDIGGSy-PXHuKq540oAXYOO9uyylpsfSsE4vLs,7032
-pydantic_ai/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pydantic_ai/result.py,sha256=UB3vFOcDAceeNLXh_f_3PKy2J0A6FIHdgDFJxPH6OJk,13651
-pydantic_ai/tools.py,sha256=rzchmsEPYtUzBBFoeeJKC1ct36iqOxFOY6kfKqItCCs,8210
-pydantic_ai/models/__init__.py,sha256=_Mz_32WGlAf4NlxXfdQ-EAaY_bDOk10gIc5HmTAO_ts,10318
-pydantic_ai/models/function.py,sha256=Mzc-zXnb2RayWAA8N9NS7KGF49do1S-VW3U9fkc661o,10045
-pydantic_ai/models/gemini.py,sha256=ruO4tnnpDDuHThg7jUOphs8I_KXBJH7gfDMluliED8E,26606
-pydantic_ai/models/groq.py,sha256=Tx2yU3ysmPLBmWGsjzES-XcumzrsoBtB7spCnJBlLiM,14947
-pydantic_ai/models/openai.py,sha256=5ihH25CrS0tnZNW-BZw4GyPe8V-IxIHWw3B9ulPVjQE,14931
-pydantic_ai/models/test.py,sha256=q1wch_E7TSb4qx9PCcP1YyBGZx567MGlAQhlAlON0S8,14463
-pydantic_ai/models/vertexai.py,sha256=5wI8y2YjeRgSE51uKy5OtevQkks65uEbxIUAs5EGBaI,9161
-pydantic_ai_slim-0.0.11.dist-info/METADATA,sha256=JPixjiAAN-dFKXFk6njU5-cf3_JqkwEBnXh2fUn2Ok4,2562
-pydantic_ai_slim-0.0.11.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-pydantic_ai_slim-0.0.11.dist-info/RECORD,,