anthropic 0.67.0__py3-none-any.whl → 0.68.0__py3-none-any.whl

anthropic/__init__.py

@@ -87,11 +87,14 @@ __all__ = [
     "DefaultAioHttpClient",
     "HUMAN_PROMPT",
     "AI_PROMPT",
+    "beta_tool",
+    "beta_async_tool",
 ]
 
 if not _t.TYPE_CHECKING:
     from ._utils._resources_proxy import resources as resources
 
+from .lib.tools import beta_tool, beta_async_tool
 from .lib.vertex import *
 from .lib.bedrock import *
 from .lib.streaming import *

anthropic/_models.py

@@ -272,7 +272,7 @@ class BaseModel(pydantic.BaseModel):
             mode: Literal["json", "python"] | str = "python",
             include: IncEx | None = None,
             exclude: IncEx | None = None,
-            by_alias: bool = False,
+            by_alias: bool | None = None,
             exclude_unset: bool = False,
             exclude_defaults: bool = False,
             exclude_none: bool = False,
@@ -280,6 +280,7 @@ class BaseModel(pydantic.BaseModel):
             warnings: bool | Literal["none", "warn", "error"] = True,
             context: dict[str, Any] | None = None,
             serialize_as_any: bool = False,
+            fallback: Callable[[Any], Any] | None = None,
         ) -> dict[str, Any]:
             """Usage docs: https://docs.pydantic.dev/2.4/concepts/serialization/#modelmodel_dump
 
@@ -311,10 +312,12 @@ class BaseModel(pydantic.BaseModel):
                 raise ValueError("context is only supported in Pydantic v2")
             if serialize_as_any != False:
                 raise ValueError("serialize_as_any is only supported in Pydantic v2")
+            if fallback is not None:
+                raise ValueError("fallback is only supported in Pydantic v2")
             dumped = super().dict(  # pyright: ignore[reportDeprecated]
                 include=include,
                 exclude=exclude,
-                by_alias=by_alias,
+                by_alias=by_alias if by_alias is not None else False,
                 exclude_unset=exclude_unset,
                 exclude_defaults=exclude_defaults,
                 exclude_none=exclude_none,
@@ -329,13 +332,14 @@ class BaseModel(pydantic.BaseModel):
             indent: int | None = None,
             include: IncEx | None = None,
             exclude: IncEx | None = None,
-            by_alias: bool = False,
+            by_alias: bool | None = None,
             exclude_unset: bool = False,
             exclude_defaults: bool = False,
             exclude_none: bool = False,
             round_trip: bool = False,
             warnings: bool | Literal["none", "warn", "error"] = True,
             context: dict[str, Any] | None = None,
+            fallback: Callable[[Any], Any] | None = None,
             serialize_as_any: bool = False,
         ) -> str:
             """Usage docs: https://docs.pydantic.dev/2.4/concepts/serialization/#modelmodel_dump_json
@@ -364,11 +368,13 @@ class BaseModel(pydantic.BaseModel):
                 raise ValueError("context is only supported in Pydantic v2")
             if serialize_as_any != False:
                 raise ValueError("serialize_as_any is only supported in Pydantic v2")
+            if fallback is not None:
+                raise ValueError("fallback is only supported in Pydantic v2")
             return super().json(  # type: ignore[reportDeprecated]
                 indent=indent,
                 include=include,
                 exclude=exclude,
-                by_alias=by_alias,
+                by_alias=by_alias if by_alias is not None else False,
                 exclude_unset=exclude_unset,
                 exclude_defaults=exclude_defaults,
                 exclude_none=exclude_none,
@@ -780,6 +786,9 @@ elif not TYPE_CHECKING:  # TODO: condition is weird
     def _create_pydantic_model(type_: _T) -> Type[RootModel[_T]]:
         return RootModel[type_]  # type: ignore
 
+    def TypeAdapter(*_args: Any, **_kwargs: Any) -> Any:
+        raise RuntimeError("attempted to use TypeAdapter in pydantic v1")
+
 
 class FinalRequestOptionsInput(TypedDict, total=False):
     method: Required[str]

anthropic/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "anthropic"
-__version__ = "0.67.0"  # x-release-please-version
+__version__ = "0.68.0"  # x-release-please-version

anthropic/lib/tools/__init__.py

@@ -0,0 +1,20 @@
+from ._beta_runner import BetaToolRunner, BetaAsyncToolRunner, BetaStreamingToolRunner, BetaAsyncStreamingToolRunner
+from ._beta_functions import (
+    BetaFunctionTool,
+    BetaAsyncFunctionTool,
+    BetaFunctionToolResultType,
+    beta_tool,
+    beta_async_tool,
+)
+
+__all__ = [
+    "beta_tool",
+    "beta_async_tool",
+    "BetaFunctionTool",
+    "BetaAsyncFunctionTool",
+    "BetaToolRunner",
+    "BetaAsyncStreamingToolRunner",
+    "BetaStreamingToolRunner",
+    "BetaAsyncToolRunner",
+    "BetaFunctionToolResultType",
+]

anthropic/lib/tools/_beta_functions.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Union, Generic, TypeVar, Callable, Iterable, Coroutine, cast, overload
+from inspect import iscoroutinefunction
+from typing_extensions import TypeAlias, override
+
+import pydantic
+import docstring_parser
+from pydantic import BaseModel
+
+from ... import _compat
+from ..._utils import is_dict
+from ..._compat import cached_property
+from ..._models import TypeAdapter
+from ..._utils._utils import CallableT
+from ...types.tool_param import ToolParam, InputSchema
+from ...types.beta.beta_tool_result_block_param import Content as BetaContent
+
+log = logging.getLogger(__name__)
+
+BetaFunctionToolResultType: TypeAlias = Union[str, Iterable[BetaContent]]
+
+Function = Callable[..., BetaFunctionToolResultType]
+FunctionT = TypeVar("FunctionT", bound=Function)
+
+AsyncFunction = Callable[..., Coroutine[Any, Any, BetaFunctionToolResultType]]
+AsyncFunctionT = TypeVar("AsyncFunctionT", bound=AsyncFunction)
+
+
+class BaseFunctionTool(Generic[CallableT]):
+    func: CallableT
+    """The function this tool is wrapping"""
+
+    name: str
+    """The name of the tool that will be sent to the API"""
+
+    description: str
+
+    input_schema: InputSchema
+
+    def __init__(
+        self,
+        func: CallableT,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        input_schema: InputSchema | type[BaseModel] | None = None,
+    ) -> None:
+        if _compat.PYDANTIC_V1:
+            raise RuntimeError("Tool functions are only supported with Pydantic v2")
+
+        self.func = func
+        self._func_with_validate = pydantic.validate_call(func)
+        self.name = name or func.__name__
+
+        self.description = description or self._get_description_from_docstring()
+
+        if input_schema is not None:
+            if isinstance(input_schema, type):
+                self.input_schema: InputSchema = input_schema.model_json_schema()
+            else:
+                self.input_schema = input_schema
+        else:
+            self.input_schema = self._create_schema_from_function()
+
+    @property
+    def __call__(self) -> CallableT:
+        return self.func
+
+    def to_dict(self) -> ToolParam:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.input_schema,
+        }
+
+    @cached_property
+    def _parsed_docstring(self) -> docstring_parser.Docstring:
+        return docstring_parser.parse(self.func.__doc__ or "")
+
+    def _get_description_from_docstring(self) -> str:
+        """Extract description from parsed docstring."""
+        if self._parsed_docstring.short_description:
+            description = self._parsed_docstring.short_description
+            if self._parsed_docstring.long_description:
+                description += f"\n\n{self._parsed_docstring.long_description}"
+            return description
+        return ""
+
+    def _create_schema_from_function(self) -> InputSchema:
+        """Create JSON schema from function signature using pydantic."""
+
+        from pydantic_core import CoreSchema
+        from pydantic.json_schema import JsonSchemaValue, GenerateJsonSchema
+        from pydantic_core.core_schema import ArgumentsParameter
+
+        class CustomGenerateJsonSchema(GenerateJsonSchema):
+            def __init__(self, *, func: Callable[..., Any], parsed_docstring: Any) -> None:
+                super().__init__()
+                self._func = func
+                self._parsed_docstring = parsed_docstring
+
+            def __call__(self, *_args: Any, **_kwds: Any) -> "CustomGenerateJsonSchema":  # noqa: ARG002
+                return self
+
+            @override
+            def kw_arguments_schema(
+                self,
+                arguments: "list[ArgumentsParameter]",
+                var_kwargs_schema: CoreSchema | None,
+            ) -> JsonSchemaValue:
+                schema = super().kw_arguments_schema(arguments, var_kwargs_schema)
+                if schema.get("type") != "object":
+                    return schema
+
+                properties = schema.get("properties")
+                if not properties or not is_dict(properties):
+                    return schema
+
+                # Add parameter descriptions from docstring
+                for param in self._parsed_docstring.params:
+                    prop_schema = properties.get(param.arg_name)
+                    if not prop_schema or not is_dict(prop_schema):
+                        continue
+
+                    if param.description and "description" not in prop_schema:
+                        prop_schema["description"] = param.description
+
+                return schema
+
+        schema_generator = CustomGenerateJsonSchema(func=self.func, parsed_docstring=self._parsed_docstring)
+        return self._adapter.json_schema(schema_generator=schema_generator)  # type: ignore
+
+    @cached_property
+    def _adapter(self) -> TypeAdapter[Any]:
+        return TypeAdapter(self._func_with_validate)
+
+
+class BetaFunctionTool(BaseFunctionTool[FunctionT]):
+    def call(self, input: object) -> BetaFunctionToolResultType:
+        if iscoroutinefunction(self.func):
+            raise RuntimeError("Cannot call a coroutine function synchronously. Use `@async_tool` instead.")
+
+        if not is_dict(input):
+            raise TypeError(f"Input must be a dictionary, got {type(input).__name__}")
+
+        try:
+            return self._func_with_validate(**cast(Any, input))
+        except pydantic.ValidationError as e:
+            raise ValueError(f"Invalid arguments for function {self.name}") from e
+
+
+class BetaAsyncFunctionTool(BaseFunctionTool[AsyncFunctionT]):
+    async def call(self, input: object) -> BetaFunctionToolResultType:
+        if not iscoroutinefunction(self.func):
+            raise RuntimeError("Cannot call a synchronous function asynchronously. Use `@tool` instead.")
+
+        if not is_dict(input):
+            raise TypeError(f"Input must be a dictionary, got {type(input).__name__}")
+
+        try:
+            return await self._func_with_validate(**cast(Any, input))
+        except pydantic.ValidationError as e:
+            raise ValueError(f"Invalid arguments for function {self.name}") from e
+
+
+@overload
+def beta_tool(func: FunctionT) -> BetaFunctionTool[FunctionT]: ...
+
+
+@overload
+def beta_tool(
+    func: FunctionT,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    input_schema: InputSchema | type[BaseModel] | None = None,
+) -> BetaFunctionTool[FunctionT]: ...
+
+
+@overload
+def beta_tool(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    input_schema: InputSchema | type[BaseModel] | None = None,
+) -> Callable[[FunctionT], BetaFunctionTool[FunctionT]]: ...
+
+
+def beta_tool(
+    func: FunctionT | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    input_schema: InputSchema | type[BaseModel] | None = None,
+) -> BetaFunctionTool[FunctionT] | Callable[[FunctionT], BetaFunctionTool[FunctionT]]:
+    """Create a FunctionTool from a function with automatic schema inference.
+
+    Can be used as a decorator with or without parentheses:
+
+    @function_tool
+    def my_func(x: int) -> str: ...
+
+    @function_tool()
+    def my_func(x: int) -> str: ...
+
+    @function_tool(name="custom_name")
+    def my_func(x: int) -> str: ...
+    """
+    if _compat.PYDANTIC_V1:
+        raise RuntimeError("Tool functions are only supported with Pydantic v2")
+
+    if func is not None:
+        # @beta_tool called without parentheses
+        return BetaFunctionTool(func=func, name=name, description=description, input_schema=input_schema)
+
+    # @beta_tool()
+    def decorator(func: FunctionT) -> BetaFunctionTool[FunctionT]:
+        return BetaFunctionTool(func=func, name=name, description=description, input_schema=input_schema)
+
+    return decorator
+
+
+@overload
+def beta_async_tool(func: AsyncFunctionT) -> BetaAsyncFunctionTool[AsyncFunctionT]: ...
+
+
+@overload
+def beta_async_tool(
+    func: AsyncFunctionT,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    input_schema: InputSchema | type[BaseModel] | None = None,
+) -> BetaAsyncFunctionTool[AsyncFunctionT]: ...
+
+
+@overload
+def beta_async_tool(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    input_schema: InputSchema | type[BaseModel] | None = None,
+) -> Callable[[AsyncFunctionT], BetaAsyncFunctionTool[AsyncFunctionT]]: ...
+
+
+def beta_async_tool(
+    func: AsyncFunctionT | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    input_schema: InputSchema | type[BaseModel] | None = None,
+) -> BetaAsyncFunctionTool[AsyncFunctionT] | Callable[[AsyncFunctionT], BetaAsyncFunctionTool[AsyncFunctionT]]:
+    """Create an AsyncFunctionTool from a function with automatic schema inference.
+
+    Can be used as a decorator with or without parentheses:
+
+    @async_tool
+    async def my_func(x: int) -> str: ...
+
+    @async_tool()
+    async def my_func(x: int) -> str: ...
+
+    @async_tool(name="custom_name")
+    async def my_func(x: int) -> str: ...
+    """
+    if _compat.PYDANTIC_V1:
+        raise RuntimeError("Tool functions are only supported with Pydantic v2")
+
+    if func is not None:
+        # @beta_async_tool called without parentheses
+        return BetaAsyncFunctionTool(
+            func=func,
+            name=name,
+            description=description,
+            input_schema=input_schema,
+        )
+
+    # @beta_async_tool()
+    def decorator(func: AsyncFunctionT) -> BetaAsyncFunctionTool[AsyncFunctionT]:
+        return BetaAsyncFunctionTool(
+            func=func,
+            name=name,
+            description=description,
+            input_schema=input_schema,
+        )
+
+    return decorator

anthropic/lib/tools/_beta_runner.py

@@ -0,0 +1,405 @@
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    List,
+    Union,
+    Generic,
+    TypeVar,
+    Callable,
+    Iterable,
+    Iterator,
+    Coroutine,
+    AsyncIterator,
+)
+from typing_extensions import TypedDict, override
+
+import httpx
+
+from ..._types import Body, Query, Headers, NotGiven
+from ..._utils import consume_sync_iterator, consume_async_iterator
+from ...types.beta import BetaMessage, BetaContentBlock, BetaMessageParam
+from ._beta_functions import BetaFunctionTool, BetaAsyncFunctionTool
+from ..streaming._beta_messages import BetaMessageStream, BetaAsyncMessageStream
+from ...types.beta.message_create_params import MessageCreateParamsBase
+from ...types.beta.beta_tool_result_block_param import BetaToolResultBlockParam
+
+if TYPE_CHECKING:
+    from ..._client import Anthropic, AsyncAnthropic
+
+
+AnyFunctionToolT = TypeVar("AnyFunctionToolT", bound=Union[BetaFunctionTool[Any], BetaAsyncFunctionTool[Any]])
+RunnerItemT = TypeVar("RunnerItemT")
+
+log = logging.getLogger(__name__)
+
+
+class RequestOptions(TypedDict, total=False):
+    extra_headers: Headers | None
+    extra_query: Query | None
+    extra_body: Body | None
+    timeout: float | httpx.Timeout | None | NotGiven
+
+
+class BaseToolRunner(Generic[AnyFunctionToolT]):
+    def __init__(
+        self,
+        *,
+        params: MessageCreateParamsBase,
+        options: RequestOptions,
+        tools: Iterable[AnyFunctionToolT],
+        max_iterations: int | None = None,
+    ) -> None:
+        self._tools_by_name = {tool.name: tool for tool in tools}
+        self._params: MessageCreateParamsBase = {
+            **params,
+            "messages": [message for message in params["messages"]],
+        }
+        self._options = options
+        self._messages_modified = False
+        self._cached_tool_call_response: BetaMessageParam | None = None
+        self._max_iterations = max_iterations
+        self._iteration_count = 0
+
+    def set_messages_params(
+        self, params: MessageCreateParamsBase | Callable[[MessageCreateParamsBase], MessageCreateParamsBase]
+    ) -> None:
+        """
+        Update the parameters for the next API call. This invalidates any cached tool responses.
+
+        Args:
+            params (MessageCreateParamsBase | Callable): Either new parameters or a function to mutate existing parameters
+        """
+        if callable(params):
+            params = params(self._params)
+        self._params = params
+
+    def append_messages(self, *messages: BetaMessageParam | BetaMessage) -> None:
+        """Add one or more messages to the conversation history.
+
+        This invalidates the cached tool response, i.e. if tools were already called, then they will
+        be called again on the next loop iteration.
+        """
+        message_params: List[BetaMessageParam] = [
+            {"role": message.role, "content": message.content} if isinstance(message, BetaMessage) else message
+            for message in messages
+        ]
+        self._messages_modified = True
+        self.set_messages_params(lambda params: {**params, "messages": [*self._params["messages"], *message_params]})
+        self._cached_tool_call_response = None
+
+    def _should_stop(self) -> bool:
+        if self._max_iterations is not None and self._iteration_count >= self._max_iterations:
+            return True
+        return False
+
+
+class BaseSyncToolRunner(BaseToolRunner[BetaFunctionTool[Any]], Generic[RunnerItemT], ABC):
+    def __init__(
+        self,
+        *,
+        params: MessageCreateParamsBase,
+        options: RequestOptions,
+        tools: Iterable[BetaFunctionTool[Any]],
+        client: Anthropic,
+        max_iterations: int | None = None,
+    ) -> None:
+        super().__init__(params=params, options=options, tools=tools, max_iterations=max_iterations)
+        self._client = client
+        self._iterator = self.__run__()
+        self._last_message: Callable[[], BetaMessage] | BetaMessage | None = None
+
+    def __next__(self) -> RunnerItemT:
+        return self._iterator.__next__()
+
+    def __iter__(self) -> Iterator[RunnerItemT]:
+        for item in self._iterator:
+            yield item
+
+    @abstractmethod
+    def __run__(self) -> Iterator[RunnerItemT]:
+        raise NotImplementedError()
+
+    def until_done(self) -> BetaMessage:
+        """
+        Consumes the tool runner stream and returns the last message if it has not been consumed yet.
+        If it has, it simply returns the last message.
+        """
+        consume_sync_iterator(self)
+        last_message = self._get_last_message()
+        assert last_message is not None
+        return last_message
+
+    def generate_tool_call_response(self) -> BetaMessageParam | None:
+        """Generate a MessageParam by calling tool functions with any tool use blocks from the last message.
+
+        Note the tool call response is cached, repeated calls to this method will return the same response.
+
+        None can be returned if no tool call was applicable.
+        """
+        if self._cached_tool_call_response is not None:
+            log.debug("Returning cached tool call response.")
+            return self._cached_tool_call_response
+        response = self._generate_tool_call_response()
+        self._cached_tool_call_response = response
+        return response
+
+
+    def _generate_tool_call_response(self) -> BetaMessageParam | None:
+        content = self._get_last_assistant_message_content()
+        if not content:
+            return None
+
+        tool_use_blocks = [block for block in content if block.type == "tool_use"]
+        if not tool_use_blocks:
+            return None
+
+        results: list[BetaToolResultBlockParam] = []
+
+        for tool_use in tool_use_blocks:
+            tool = self._tools_by_name.get(tool_use.name)
+            if tool is None:
+                results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": tool_use.id,
+                        "content": f"Error: Tool '{tool_use.name}' not found",
+                        "is_error": True,
+                    }
+                )
+                continue
+
+            try:
+                result = tool.call(tool_use.input)
+                results.append({"type": "tool_result", "tool_use_id": tool_use.id, "content": result})
+            except Exception as exc:
+                log.exception(f"Error occurred while calling tool: {tool.name}", exc_info=exc)
+                results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": tool_use.id,
+                        "content": repr(exc),
+                        "is_error": True,
+                    }
+                )
+
+        return {"role": "user", "content": results}
+
+    def _get_last_message(self) -> BetaMessage | None:
+        if callable(self._last_message):
+            return self._last_message()
+        return self._last_message
+
+    def _get_last_assistant_message_content(self) -> list[BetaContentBlock] | None:
+        last_message = self._get_last_message()
+        if last_message is None or last_message.role != "assistant" or not last_message.content:
+            return None
+
+        return last_message.content
+
+
+class BetaToolRunner(BaseSyncToolRunner[BetaMessage]):
+    @override
+    def __run__(self) -> Iterator[BetaMessage]:
+        self._last_message = message = self._client.beta.messages.create(**self._params, **self._options)
+        yield message
+        self._iteration_count += 1
+
+        while not self._should_stop():
+            response = self.generate_tool_call_response()
+            if response is None:
+                log.debug("Tool call was not requested, exiting from tool runner loop.")
+                return
+
+            if not self._messages_modified:
+                self.append_messages(message, response)
+
+            self._iteration_count += 1
+            self._messages_modified = False
+            self._cached_tool_call_response = None
+            self._last_message = message = self._client.beta.messages.create(**self._params, **self._options)
+            yield message
+
+
+class BetaStreamingToolRunner(BaseSyncToolRunner[BetaMessageStream]):
+    @override
+    def __run__(self) -> Iterator[BetaMessageStream]:
+        with self._client.beta.messages.stream(**self._params, **self._options) as stream:
+            self._last_message = stream.get_final_message
+            yield stream
+            message = stream.get_final_message()
+        self._iteration_count += 1
+
+        while not self._should_stop():
+            response = self.generate_tool_call_response()
+            if response is None:
+                log.debug("Tool call was not requested, exiting from tool runner loop.")
+                return
+
+            if not self._messages_modified:
+                self.append_messages(message, response)
+            self._iteration_count += 1
+            self._messages_modified = False
+
+            with self._client.beta.messages.stream(**self._params, **self._options) as stream:
+                self._cached_tool_call_response = None
+                self._last_message = stream.get_final_message
+                yield stream
+                message = stream.get_final_message()
+
+
+class BaseAsyncToolRunner(BaseToolRunner[BetaAsyncFunctionTool[Any]], Generic[RunnerItemT], ABC):
+    def __init__(
+        self,
+        *,
+        params: MessageCreateParamsBase,
+        options: RequestOptions,
+        tools: Iterable[BetaAsyncFunctionTool[Any]],
+        client: AsyncAnthropic,
+        max_iterations: int | None = None,
+    ) -> None:
+        super().__init__(params=params, options=options, tools=tools, max_iterations=max_iterations)
+        self._client = client
+        self._iterator = self.__run__()
+        self._last_message: Callable[[], Coroutine[None, None, BetaMessage]] | BetaMessage | None = None
+
+    async def __anext__(self) -> RunnerItemT:
+        return await self._iterator.__anext__()
+
+    async def __aiter__(self) -> AsyncIterator[RunnerItemT]:
+        async for item in self._iterator:
+            yield item
+
+    @abstractmethod
+    async def __run__(self) -> AsyncIterator[RunnerItemT]:
+        raise NotImplementedError()
+        yield  # type: ignore[unreachable]
+
+    async def until_done(self) -> BetaMessage:
+        """
+        Consumes the tool runner stream and returns the last message if it has not been consumed yet.
+        If it has, it simply returns the last message.
+        """
+        await consume_async_iterator(self)
+        last_message = await self._get_last_message()
+        assert last_message is not None
+        return last_message
+
+    async def generate_tool_call_response(self) -> BetaMessageParam | None:
+        """Generate a MessageParam by calling tool functions with any tool use blocks from the last message.
+
+        Note the tool call response is cached, repeated calls to this method will return the same response.
+
+        None can be returned if no tool call was applicable.
+        """
+        if self._cached_tool_call_response is not None:
+            log.debug("Returning cached tool call response.")
+            return self._cached_tool_call_response
+
+        response = await self._generate_tool_call_response()
+        self._cached_tool_call_response = response
+        return response
+
+    async def _get_last_message(self) -> BetaMessage | None:
+        if callable(self._last_message):
+            return await self._last_message()
+        return self._last_message
+
+    async def _get_last_assistant_message_content(self) -> list[BetaContentBlock] | None:
+        last_message = await self._get_last_message()
+        if last_message is None or last_message.role != "assistant" or not last_message.content:
+            return None
+
+        return last_message.content
+
+    async def _generate_tool_call_response(self) -> BetaMessageParam | None:
+        content = await self._get_last_assistant_message_content()
+        if not content:
+            return None
+
+        tool_use_blocks = [block for block in content if block.type == "tool_use"]
+        if not tool_use_blocks:
+            return None
+
+        results: list[BetaToolResultBlockParam] = []
+
+        for tool_use in tool_use_blocks:
+            tool = self._tools_by_name.get(tool_use.name)
+            if tool is None:
+                results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": tool_use.id,
+                        "content": f"Error: Tool '{tool_use.name}' not found",
+                        "is_error": True,
+                    }
+                )
+                continue
+
+            try:
+                result = await tool.call(tool_use.input)
+                results.append({"type": "tool_result", "tool_use_id": tool_use.id, "content": result})
+            except Exception as exc:
+                log.exception(f"Error occurred while calling tool: {tool.name}", exc_info=exc)
+                results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": tool_use.id,
+                        "content": repr(exc),
+                        "is_error": True,
+                    }
+                )
+
+        return {"role": "user", "content": results}
+
+
+class BetaAsyncToolRunner(BaseAsyncToolRunner[BetaMessage]):
+    @override
+    async def __run__(self) -> AsyncIterator[BetaMessage]:
+        self._last_message = message = await self._client.beta.messages.create(**self._params, **self._options)
+        yield message
+        self._iteration_count += 1
+
+        while not self._should_stop():
+            response = await self.generate_tool_call_response()
+            if response is None:
+                log.debug("Tool call was not requested, exiting from tool runner loop.")
+                return
+
+            if not self._messages_modified:
+                self.append_messages(message, response)
+            self._iteration_count += 1
+            self._messages_modified = False
+            self._cached_tool_call_response = None
+            self._last_message = message = await self._client.beta.messages.create(**self._params, **self._options)
+            yield message
+
+
+class BetaAsyncStreamingToolRunner(BaseAsyncToolRunner[BetaAsyncMessageStream]):
+    @override
+    async def __run__(self) -> AsyncIterator[BetaAsyncMessageStream]:
+        async with self._client.beta.messages.stream(**self._params, **self._options) as stream:
+            self._last_message = stream.get_final_message
+            yield stream
+            message = await stream.get_final_message()
+        self._iteration_count += 1
+
+        while not self._should_stop():
+            response = await self.generate_tool_call_response()
+            if response is None:
+                log.debug("Tool call was not requested, exiting from tool runner loop.")
+                return
+
+            if not self._messages_modified:
+                self.append_messages(message, response)
+            self._iteration_count += 1
+            self._messages_modified = False
+
+            async with self._client.beta.messages.stream(**self._params, **self._options) as stream:
+                self._last_message = stream.get_final_message
+                self._cached_tool_call_response = None
+                yield stream
+                message = await stream.get_final_message()

anthropic/resources/beta/messages/messages.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import warnings
-from typing import List, Union, Iterable, Optional
+from typing import TYPE_CHECKING, Any, List, Union, Iterable, Optional, cast
 from functools import partial
 from itertools import chain
 from typing_extensions import Literal, overload
@@ -24,6 +24,14 @@ from ...._utils import is_given, required_args, maybe_transform, strip_not_given
 from ...._compat import cached_property
 from ...._resource import SyncAPIResource, AsyncAPIResource
 from ...._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
+from ....lib.tools import (
+    BetaToolRunner,
+    BetaFunctionTool,
+    BetaAsyncToolRunner,
+    BetaAsyncFunctionTool,
+    BetaStreamingToolRunner,
+    BetaAsyncStreamingToolRunner,
+)
 from ...._constants import DEFAULT_TIMEOUT, MODEL_NONSTREAMING_TOKENS
 from ...._streaming import Stream, AsyncStream
 from ....types.beta import (
@@ -47,6 +55,9 @@ from ....types.beta.beta_thinking_config_param import BetaThinkingConfigParam
 from ....types.beta.beta_raw_message_stream_event import BetaRawMessageStreamEvent
 from ....types.beta.beta_request_mcp_server_url_definition_param import BetaRequestMCPServerURLDefinitionParam
 
+if TYPE_CHECKING:
+    from ...._client import Anthropic, AsyncAnthropic
+
 __all__ = ["Messages", "AsyncMessages"]
 
 
@@ -982,6 +993,185 @@ class Messages(SyncAPIResource):
             stream_cls=Stream[BetaRawMessageStreamEvent],
         )
 
+    @overload
+    def tool_runner(
+        self,
+        *,
+        max_tokens: int,
+        messages: Iterable[BetaMessageParam],
+        model: ModelParam,
+        tools: Iterable[BetaFunctionTool[Any]],
+        max_iterations: int | NotGiven = NOT_GIVEN,
+        container: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Iterable[BetaRequestMCPServerURLDefinitionParam] | NotGiven = NOT_GIVEN,
+        metadata: BetaMetadataParam | NotGiven = NOT_GIVEN,
+        service_tier: Literal["auto", "standard_only"] | NotGiven = NOT_GIVEN,
+        stop_sequences: SequenceNotStr[str] | NotGiven = NOT_GIVEN,
+        stream: Literal[False] | NotGiven = NOT_GIVEN,
+        system: Union[str, Iterable[BetaTextBlockParam]] | NotGiven = NOT_GIVEN,
+        temperature: float | NotGiven = NOT_GIVEN,
+        top_k: int | NotGiven = NOT_GIVEN,
+        top_p: float | NotGiven = NOT_GIVEN,
+        thinking: BetaThinkingConfigParam | NotGiven = NOT_GIVEN,
+        tool_choice: BetaToolChoiceParam | NotGiven = NOT_GIVEN,
+        betas: List[AnthropicBetaParam] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> BetaToolRunner: ...
+
+    @overload
+    def tool_runner(
+        self,
+        *,
+        max_tokens: int,
+        messages: Iterable[BetaMessageParam],
+        model: ModelParam,
+        tools: Iterable[BetaFunctionTool[Any]],
+        stream: Literal[True],
+        max_iterations: int | NotGiven = NOT_GIVEN,
+        container: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Iterable[BetaRequestMCPServerURLDefinitionParam] | NotGiven = NOT_GIVEN,
+        metadata: BetaMetadataParam | NotGiven = NOT_GIVEN,
+        service_tier: Literal["auto", "standard_only"] | NotGiven = NOT_GIVEN,
+        stop_sequences: SequenceNotStr[str] | NotGiven = NOT_GIVEN,
+        system: Union[str, Iterable[BetaTextBlockParam]] | NotGiven = NOT_GIVEN,
+        temperature: float | NotGiven = NOT_GIVEN,
+        top_k: int | NotGiven = NOT_GIVEN,
+        top_p: float | NotGiven = NOT_GIVEN,
+        thinking: BetaThinkingConfigParam | NotGiven = NOT_GIVEN,
+        tool_choice: BetaToolChoiceParam | NotGiven = NOT_GIVEN,
+        betas: List[AnthropicBetaParam] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> BetaStreamingToolRunner: ...
+
+    @overload
+    def tool_runner(
+        self,
+        *,
+        max_tokens: int,
+        messages: Iterable[BetaMessageParam],
+        model: ModelParam,
+        tools: Iterable[BetaFunctionTool[Any]],
+        stream: bool,
+        max_iterations: int | NotGiven = NOT_GIVEN,
+        container: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Iterable[BetaRequestMCPServerURLDefinitionParam] | NotGiven = NOT_GIVEN,
+        metadata: BetaMetadataParam | NotGiven = NOT_GIVEN,
+        service_tier: Literal["auto", "standard_only"] | NotGiven = NOT_GIVEN,
+        stop_sequences: SequenceNotStr[str] | NotGiven = NOT_GIVEN,
+        system: Union[str, Iterable[BetaTextBlockParam]] | NotGiven = NOT_GIVEN,
+        temperature: float | NotGiven = NOT_GIVEN,
+        top_k: int | NotGiven = NOT_GIVEN,
+        top_p: float | NotGiven = NOT_GIVEN,
+        thinking: BetaThinkingConfigParam | NotGiven = NOT_GIVEN,
+        tool_choice: BetaToolChoiceParam | NotGiven = NOT_GIVEN,
+        betas: List[AnthropicBetaParam] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> BetaStreamingToolRunner | BetaToolRunner: ...
+
+    def tool_runner(
+        self,
+        *,
+        max_tokens: int,
+        messages: Iterable[BetaMessageParam],
+        model: ModelParam,
+        tools: Iterable[BetaFunctionTool[Any]],
+        max_iterations: int | NotGiven = NOT_GIVEN,
+        container: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Iterable[BetaRequestMCPServerURLDefinitionParam] | NotGiven = NOT_GIVEN,
+        metadata: BetaMetadataParam | NotGiven = NOT_GIVEN,
+        service_tier: Literal["auto", "standard_only"] | NotGiven = NOT_GIVEN,
+        stop_sequences: SequenceNotStr[str] | NotGiven = NOT_GIVEN,
+        stream: bool | NotGiven = NOT_GIVEN,
+        system: Union[str, Iterable[BetaTextBlockParam]] | NotGiven = NOT_GIVEN,
+        temperature: float | NotGiven = NOT_GIVEN,
+        top_k: int | NotGiven = NOT_GIVEN,
+        top_p: float | NotGiven = NOT_GIVEN,
+        thinking: BetaThinkingConfigParam | NotGiven = NOT_GIVEN,
+        tool_choice: BetaToolChoiceParam | NotGiven = NOT_GIVEN,
+        betas: List[AnthropicBetaParam] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> BetaToolRunner | BetaStreamingToolRunner:
+        """Create a Message stream"""
+        if model in DEPRECATED_MODELS:
+            warnings.warn(
+                f"The model '{model}' is deprecated and will reach end-of-life on {DEPRECATED_MODELS[model]}.\nPlease migrate to a newer model. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+
+        extra_headers = {
+            "X-Stainless-Helper": "beta.messages.tool_runner",
+            **strip_not_given({"anthropic-beta": ",".join(str(e) for e in betas) if is_given(betas) else NOT_GIVEN}),
+            **(extra_headers or {}),
+        }
+
+        params = cast(
+            message_create_params.MessageCreateParamsNonStreaming,
+            {
+                "max_tokens": max_tokens,
+                "messages": messages,
+                "model": model,
+                "container": container,
+                "mcp_servers": mcp_servers,
+                "metadata": metadata,
+                "service_tier": service_tier,
+                "stop_sequences": stop_sequences,
+                "system": system,
+                "temperature": temperature,
+                "thinking": thinking,
+                "tool_choice": tool_choice,
+                "tools": [tool.to_dict() for tool in tools],
+                "top_k": top_k,
+                "top_p": top_p,
+            },
+        )
+
+        if stream:
+            return BetaStreamingToolRunner(
+                tools=tools,
+                params=params,
+                options={
+                    "extra_headers": extra_headers,
+                    "extra_query": extra_query,
+                    "extra_body": extra_body,
+                    "timeout": timeout,
+                },
+                client=cast("Anthropic", self._client),
+                max_iterations=max_iterations if is_given(max_iterations) else None,
+            )
+        return BetaToolRunner(
+            tools=tools,
+            params=params,
+            options={
+                "extra_headers": extra_headers,
+                "extra_query": extra_query,
+                "extra_body": extra_body,
+                "timeout": timeout,
+            },
+            client=cast("Anthropic", self._client),
+            max_iterations=max_iterations if is_given(max_iterations) else None,
+        )
+
     def stream(
         self,
         *,
@@ -2223,6 +2413,185 @@ class AsyncMessages(AsyncAPIResource):
             stream_cls=AsyncStream[BetaRawMessageStreamEvent],
         )
 
+    @overload
+    def tool_runner(
+        self,
+        *,
+        max_tokens: int,
+        messages: Iterable[BetaMessageParam],
+        model: ModelParam,
+        tools: Iterable[BetaAsyncFunctionTool[Any]],
+        max_iterations: int | NotGiven = NOT_GIVEN,
+        container: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Iterable[BetaRequestMCPServerURLDefinitionParam] | NotGiven = NOT_GIVEN,
+        metadata: BetaMetadataParam | NotGiven = NOT_GIVEN,
+        service_tier: Literal["auto", "standard_only"] | NotGiven = NOT_GIVEN,
+        stop_sequences: SequenceNotStr[str] | NotGiven = NOT_GIVEN,
+        stream: Literal[False] | NotGiven = NOT_GIVEN,
+        system: Union[str, Iterable[BetaTextBlockParam]] | NotGiven = NOT_GIVEN,
+        temperature: float | NotGiven = NOT_GIVEN,
+        top_k: int | NotGiven = NOT_GIVEN,
+        top_p: float | NotGiven = NOT_GIVEN,
+        thinking: BetaThinkingConfigParam | NotGiven = NOT_GIVEN,
+        tool_choice: BetaToolChoiceParam | NotGiven = NOT_GIVEN,
+        betas: List[AnthropicBetaParam] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> BetaAsyncToolRunner: ...
+
+    @overload
+    def tool_runner(
+        self,
+        *,
+        max_tokens: int,
+        messages: Iterable[BetaMessageParam],
+        model: ModelParam,
+        tools: Iterable[BetaAsyncFunctionTool[Any]],
+        stream: Literal[True],
+        max_iterations: int | NotGiven = NOT_GIVEN,
+        container: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Iterable[BetaRequestMCPServerURLDefinitionParam] | NotGiven = NOT_GIVEN,
+        metadata: BetaMetadataParam | NotGiven = NOT_GIVEN,
+        service_tier: Literal["auto", "standard_only"] | NotGiven = NOT_GIVEN,
+        stop_sequences: SequenceNotStr[str] | NotGiven = NOT_GIVEN,
+        system: Union[str, Iterable[BetaTextBlockParam]] | NotGiven = NOT_GIVEN,
+        temperature: float | NotGiven = NOT_GIVEN,
+        top_k: int | NotGiven = NOT_GIVEN,
+        top_p: float | NotGiven = NOT_GIVEN,
+        thinking: BetaThinkingConfigParam | NotGiven = NOT_GIVEN,
+        tool_choice: BetaToolChoiceParam | NotGiven = NOT_GIVEN,
+        betas: List[AnthropicBetaParam] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> BetaAsyncStreamingToolRunner: ...
+
+    @overload
+    def tool_runner(
+        self,
+        *,
+        max_tokens: int,
+        messages: Iterable[BetaMessageParam],
+        model: ModelParam,
+        tools: Iterable[BetaAsyncFunctionTool[Any]],
+        stream: bool,
+        max_iterations: int | NotGiven = NOT_GIVEN,
+        container: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Iterable[BetaRequestMCPServerURLDefinitionParam] | NotGiven = NOT_GIVEN,
+        metadata: BetaMetadataParam | NotGiven = NOT_GIVEN,
+        service_tier: Literal["auto", "standard_only"] | NotGiven = NOT_GIVEN,
+        stop_sequences: SequenceNotStr[str] | NotGiven = NOT_GIVEN,
+        system: Union[str, Iterable[BetaTextBlockParam]] | NotGiven = NOT_GIVEN,
+        temperature: float | NotGiven = NOT_GIVEN,
+        top_k: int | NotGiven = NOT_GIVEN,
+        top_p: float | NotGiven = NOT_GIVEN,
+        thinking: BetaThinkingConfigParam | NotGiven = NOT_GIVEN,
+        tool_choice: BetaToolChoiceParam | NotGiven = NOT_GIVEN,
+        betas: List[AnthropicBetaParam] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> BetaAsyncStreamingToolRunner | BetaAsyncToolRunner: ...
+
+    def tool_runner(
+        self,
+        *,
+        max_tokens: int,
+        messages: Iterable[BetaMessageParam],
+        model: ModelParam,
+        tools: Iterable[BetaAsyncFunctionTool[Any]],
+        max_iterations: int | NotGiven = NOT_GIVEN,
+        container: Optional[str] | NotGiven = NOT_GIVEN,
+        mcp_servers: Iterable[BetaRequestMCPServerURLDefinitionParam] | NotGiven = NOT_GIVEN,
+        metadata: BetaMetadataParam | NotGiven = NOT_GIVEN,
+        service_tier: Literal["auto", "standard_only"] | NotGiven = NOT_GIVEN,
+        stop_sequences: SequenceNotStr[str] | NotGiven = NOT_GIVEN,
+        stream: Literal[True] | Literal[False] | NotGiven = False,
+        system: Union[str, Iterable[BetaTextBlockParam]] | NotGiven = NOT_GIVEN,
+        temperature: float | NotGiven = NOT_GIVEN,
+        top_k: int | NotGiven = NOT_GIVEN,
+        top_p: float | NotGiven = NOT_GIVEN,
+        thinking: BetaThinkingConfigParam | NotGiven = NOT_GIVEN,
+        tool_choice: BetaToolChoiceParam | NotGiven = NOT_GIVEN,
+        betas: List[AnthropicBetaParam] | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> BetaAsyncToolRunner | BetaAsyncStreamingToolRunner:
+        """Create a Message stream"""
+        if model in DEPRECATED_MODELS:
+            warnings.warn(
+                f"The model '{model}' is deprecated and will reach end-of-life on {DEPRECATED_MODELS[model]}.\nPlease migrate to a newer model. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+
+        extra_headers = {
+            "X-Stainless-Helper": "beta.messages.tool_runner",
+            **strip_not_given({"anthropic-beta": ",".join(str(e) for e in betas) if is_given(betas) else NOT_GIVEN}),
+            **(extra_headers or {}),
+        }
+
+        params = cast(
+            message_create_params.MessageCreateParamsBase,
+            {
+                "max_tokens": max_tokens,
+                "messages": messages,
+                "model": model,
+                "container": container,
+                "mcp_servers": mcp_servers,
+                "metadata": metadata,
+                "service_tier": service_tier,
+                "stop_sequences": stop_sequences,
+                "system": system,
+                "temperature": temperature,
+                "thinking": thinking,
+                "tool_choice": tool_choice,
+                "tools": [tool.to_dict() for tool in tools],
+                "top_k": top_k,
+                "top_p": top_p,
+            },
+        )
+
+        if stream:
+            return BetaAsyncStreamingToolRunner(
+                tools=tools,
+                params=params,
+                options={
+                    "extra_headers": extra_headers,
+                    "extra_query": extra_query,
+                    "extra_body": extra_body,
+                    "timeout": timeout,
+                },
+                client=cast("AsyncAnthropic", self._client),
+                max_iterations=max_iterations if is_given(max_iterations) else None,
+            )
+        return BetaAsyncToolRunner(
+            tools=tools,
+            params=params,
+            options={
+                "extra_headers": extra_headers,
+                "extra_query": extra_query,
+                "extra_body": extra_body,
+                "timeout": timeout,
+            },
+            client=cast("AsyncAnthropic", self._client),
+            max_iterations=max_iterations if is_given(max_iterations) else None,
+        )
+
     def stream(
         self,
         *,

{anthropic-0.67.0.dist-info → anthropic-0.68.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: anthropic
-Version: 0.67.0
+Version: 0.68.0
 Summary: The official Python library for the anthropic API
 Project-URL: Homepage, https://github.com/anthropics/anthropic-sdk-python
 Project-URL: Repository, https://github.com/anthropics/anthropic-sdk-python
@@ -24,6 +24,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Requires-Dist: anyio<5,>=3.5.0
 Requires-Dist: distro<2,>=1.7.0
+Requires-Dist: docstring-parser<1,>=0.15
 Requires-Dist: httpx<1,>=0.25.0
 Requires-Dist: jiter<1,>=0.4.0
 Requires-Dist: pydantic<3,>=1.9.0
@@ -208,6 +209,55 @@ async for event in stream:
     print(event.type)
 ```
 
+### Tool helpers
+
+This library provides helper functions for defining and running tools as pure python functions, for example:
+
+```py
+import json
+import rich
+from typing_extensions import Literal
+from anthropic import Anthropic, beta_tool
+
+client = Anthropic()
+
+
+@beta_tool
+def get_weather(location: str) -> str:
+    """Lookup the weather for a given city in either celsius or fahrenheit
+
+    Args:
+        location: The city and state, e.g. San Francisco, CA
+    Returns:
+        A dictionary containing the location, temperature, and weather condition.
+    """
+    # Here you would typically make an API call to a weather service
+    # For demonstration, we return a mock response
+    return json.dumps(
+        {
+            "location": location,
+            "temperature": "68°F",
+            "condition": "Sunny",
+        }
+    )
+
+
+runner = client.beta.messages.tool_runner(
+    max_tokens=1024,
+    model="claude-sonnet-4-20250514",
+    tools=[get_weather],
+    messages=[
+        {"role": "user", "content": "What is the weather in SF?"},
+    ],
+)
+for message in runner:
+    rich.print(message)
+```
+
+On every iteration, an API request will be made, if Claude wants to call one of the given tools then it will be automatically called, and the result will be returned directly to the model in the next iteration.
+
+For more information see the [full docs](https://github.com/anthropics/anthropic-sdk-python/tree/main/tools.md).
+
 ### Streaming Helpers
 
 This library provides several conveniences for streaming messages, for example:

{anthropic-0.67.0.dist-info → anthropic-0.68.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-anthropic/__init__.py,sha256=_3qHjlaUTyCm_xLr3HAcWvxMuKwKJtVRR1TkwU9WEYE,2845
+anthropic/__init__.py,sha256=6JJg_MfwoX2NEIS05VHtFvK6O5obE1HllHeRfel6DB0,2935
 anthropic/_base_client.py,sha256=VdxbcECVlP8hn1oS4vFBrU87W0a1iEw0eq0NpX8Q7mI,72849
 anthropic/_client.py,sha256=kZlulmKAcSG7WdzYCUdXFFfATn5ZP1PO7gHQbqAe2Dc,22827
 anthropic/_compat.py,sha256=DQBVORjFb33zch24jzkhM14msvnzY7mmSmgDLaVFUM8,6562
@@ -6,13 +6,13 @@ anthropic/_constants.py,sha256=wADeUqY3lsseF0L6jIen-PexfQ06FOtf2dVESXDM828,885
 anthropic/_exceptions.py,sha256=bkSqVWxtRdRb31H7MIvtxfh5mo_Xf7Ib3nPTOmAOmGs,4073
 anthropic/_files.py,sha256=_Ux6v6nAsxK4e_4efdt1DiIOZ0hGmlR2ZKKcVfJIfGU,3623
 anthropic/_legacy_response.py,sha256=QsroQ_9LHI8tSoPEvbIXXB44SvLJXaXQX7khjZpnqfE,17235
-anthropic/_models.py,sha256=BDZv65jMBcFXe8SBhN2RoHGPJiNlIq3Dk89qUDcWcYM,31397
+anthropic/_models.py,sha256=wUXeougIoFGSKQr_XIcmamSHeupO6R7ZaQnFZC-hEl8,31957
 anthropic/_qs.py,sha256=AOkSz4rHtK4YI3ZU_kzea-zpwBUgEY8WniGmTPyEimc,4846
 anthropic/_resource.py,sha256=FYEOzfhB-XWTR2gyTmQuuFoecRiVXxe_SpjZlQQGytU,1080
 anthropic/_response.py,sha256=1Y7-OrGn1lOwvZ_SmMlwT9Nb2i9A1RYw2Q4-F1cwPSU,30542
 anthropic/_streaming.py,sha256=vn8K5KgfO3Bv9NE8nwHIQEjEhkQeVE6YMnGqiJlCgqE,14023
 anthropic/_types.py,sha256=PwAzwWTKp9b08FTllhWjQPX_-8CLXWh6U-9atpUYHxg,7398
-anthropic/_version.py,sha256=ZnlGfhFJ_n808nDMKeLmAYv5q8IX6Lc079zE4qSOyeA,162
+anthropic/_version.py,sha256=XBCqVoiIx9RiTN5BgCAlMHcs9_p4oh39-eXsN2hTYCw,162
 anthropic/pagination.py,sha256=hW6DOtNbwwQrNQ8wn4PJj7WB2y_37szSDQeUBnunQ40,2202
 anthropic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 anthropic/_decoders/jsonl.py,sha256=KDLw-Frjo7gRup5qDp_BWkXIZ-mFZU5vFDz0WBhEKcs,3510
@@ -46,6 +46,9 @@ anthropic/lib/streaming/_beta_messages.py,sha256=swDeDwTbhx33G_YjwTkusbij6CerLuW
 anthropic/lib/streaming/_beta_types.py,sha256=fny8XN85afEG6of84YuaScr3U8UeMCJxqyfuTePHNbM,2131
 anthropic/lib/streaming/_messages.py,sha256=OSV9sjb8MLThSywEFXQV9OchcNXAE2KxDacVpJbkNRM,16958
 anthropic/lib/streaming/_types.py,sha256=CrR4948IWgUF7L9O0ase2QwbpiQ1JeiYXrRyVi74-Bw,2086
+anthropic/lib/tools/__init__.py,sha256=ui3gBw2-vQsl_4pKjf3O5kfUYpGATjQ6H4MPLopy0h4,525
+anthropic/lib/tools/_beta_functions.py,sha256=eje6jXzDZa0azRevFF6TP_YQBo7FX3DvY4wRT5nUv7c,9738
+anthropic/lib/tools/_beta_runner.py,sha256=Lcf1bltqrLXj6niPqPaFYCaFFRWKqRHbfINtbCAqjvY,15470
 anthropic/lib/vertex/__init__.py,sha256=A8vuK1qVPtmKr1_LQgPuDRVA6I4xm_ye2aPdAa4yGsI,102
 anthropic/lib/vertex/_auth.py,sha256=Kyt_hbUc-DPlkvds4__OLR8FLPpoDas6bXhZTECxO3Y,1644
 anthropic/lib/vertex/_beta.py,sha256=8kXsUUIGstf6dZfiZtm6s9OWEueuSgra8dPvkaUacy4,3323
@@ -60,7 +63,7 @@ anthropic/resources/beta/files.py,sha256=q4V7iBnUDflYrG31oNPqY9ycXTF5oryMMBmrR7i
 anthropic/resources/beta/models.py,sha256=OsXRcsEHoNuj1VjhbFLeOYgE35DnUO8m4hTPF6zcs0Q,12594
 anthropic/resources/beta/messages/__init__.py,sha256=7ZO4hB7hPBhXQja7gMzkwLXQVDlyap4JsihpA0UKZjk,849
 anthropic/resources/beta/messages/batches.py,sha256=6sbFpFCCRC-qN37-5n7lO3BzGXKGVaXhPv9y7Daj0-0,35990
-anthropic/resources/beta/messages/messages.py,sha256=OlRVKosYcpFW-zmrrZcwDRpKNI50GuB9pnahEEBx_YU,115891
+anthropic/resources/beta/messages/messages.py,sha256=lgtY2_Pvgca5IXEYz3OhwSB7GPnnwCsv5Cbe38m_dSQ,133367
 anthropic/resources/messages/__init__.py,sha256=iOSBh4D7NTXqe7RNhw9HZCiFmJvDfIgVFnjaF7r27YU,897
 anthropic/resources/messages/batches.py,sha256=w_bNgg_NV4rFQkDeixJtRokimPIT3OVpimr8D8_7v5Y,28590
 anthropic/resources/messages/messages.py,sha256=PBhZL3iuG-A0WhNcawR3pRtgL8fR8qSmAYsx48Mksi8,109831
@@ -362,7 +365,7 @@ anthropic/types/shared/not_found_error.py,sha256=R6OsCvAmsf_SB2TwoX6E63o049qZMaA
 anthropic/types/shared/overloaded_error.py,sha256=PlyhHt3wmzcnynSfkWbfP4XkLoWsPa9B39V3CyAdgx8,282
 anthropic/types/shared/permission_error.py,sha256=nuyxtLXOiEkYEbFRXiAWjxU6XtdyjkAaXQ2NgMB3pjw,282
 anthropic/types/shared/rate_limit_error.py,sha256=eYULATjXa6KKdqeBauest7RzuN-bhGsY5BWwH9eYv4c,280
-anthropic-0.67.0.dist-info/METADATA,sha256=rgahUDxvf6Juuztdsbt6-_WOx85mKGJ-j5H_fB_THOU,27053
-anthropic-0.67.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-anthropic-0.67.0.dist-info/licenses/LICENSE,sha256=i_lphP-Lz65-SMrnalKeiiUxe6ngKr9_08xk_flWV6Y,1056
-anthropic-0.67.0.dist-info/RECORD,,
+anthropic-0.68.0.dist-info/METADATA,sha256=v27Ud_PHScKrCxi_FuUQLPA98LOh21l1vzQxP50CEgQ,28528
+anthropic-0.68.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+anthropic-0.68.0.dist-info/licenses/LICENSE,sha256=i_lphP-Lz65-SMrnalKeiiUxe6ngKr9_08xk_flWV6Y,1056
+anthropic-0.68.0.dist-info/RECORD,,