chore: import upstream snapshot with attribution

docs-website/reference_versioned_docs/version-2.25/haystack-api/tool_components_api.md

@@ -0,0 +1,325 @@
+---
+title: "Tool Components"
+id: tool-components-api
+description: "Components related to Tool Calling."
+slug: "/tool-components-api"
+---
+
+
+## tool_invoker
+
+### ToolInvokerError
+
+Bases: <code>Exception</code>
+
+Base exception class for ToolInvoker errors.
+
+### ToolNotFoundException
+
+Bases: <code>ToolInvokerError</code>
+
+Exception raised when a tool is not found in the list of available tools.
+
+### StringConversionError
+
+Bases: <code>ToolInvokerError</code>
+
+Exception raised when the conversion of a tool result to a string fails.
+
+### ResultConversionError
+
+Bases: <code>ToolInvokerError</code>
+
+Exception raised when the conversion of a tool output to a result fails.
+
+### ToolOutputMergeError
+
+Bases: <code>ToolInvokerError</code>
+
+Exception raised when merging tool outputs into state fails.
+
+#### from_exception
+
+```python
+from_exception(tool_name: str, error: Exception) -> ToolOutputMergeError
+```
+
+Create a ToolOutputMergeError from an exception.
+
+### ToolInvoker
+
+Invokes tools based on prepared tool calls and returns the results as a list of ChatMessage objects.
+
+Also handles reading/writing from a shared `State`.
+At initialization, the ToolInvoker component is provided with a list of available tools.
+At runtime, the component processes a list of ChatMessage object containing tool calls
+and invokes the corresponding tools.
+The results of the tool invocations are returned as a list of ChatMessage objects with tool role.
+
+Usage example:
+
+```python
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.tools import Tool
+from haystack.components.tools import ToolInvoker
+
+# Tool definition
+def dummy_weather_function(city: str):
+    return f"The weather in {city} is 20 degrees."
+
+parameters = {"type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"]}
+
+tool = Tool(name="weather_tool",
+            description="A tool to get the weather",
+            function=dummy_weather_function,
+            parameters=parameters)
+
+# Usually, the ChatMessage with tool_calls is generated by a Language Model
+# Here, we create it manually for demonstration purposes
+tool_call = ToolCall(
+    tool_name="weather_tool",
+    arguments={"city": "Berlin"}
+)
+message = ChatMessage.from_assistant(tool_calls=[tool_call])
+
+# ToolInvoker initialization and run
+invoker = ToolInvoker(tools=[tool])
+result = invoker.run(messages=[message])
+
+print(result)
+```
+
+```
+>>  {
+>>      'tool_messages': [
+>>          ChatMessage(
+>>              _role=<ChatRole.TOOL: 'tool'>,
+>>              _content=[
+>>                  ToolCallResult(
+>>                      result='"The weather in Berlin is 20 degrees."',
+>>                      origin=ToolCall(
+>>                          tool_name='weather_tool',
+>>                          arguments={'city': 'Berlin'},
+>>                          id=None
+>>                      )
+>>                  )
+>>              ],
+>>              _meta={}
+>>          )
+>>      ]
+>>  }
+```
+
+Usage example with a Toolset:
+
+````python
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.tools import Tool, Toolset
+from haystack.components.tools import ToolInvoker
+
+# Tool definition
+def dummy_weather_function(city: str):
+    return f"The weather in {city} is 20 degrees."
+
+parameters = {"type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"]}
+
+tool = Tool(name="weather_tool",
+            description="A tool to get the weather",
+            function=dummy_weather_function,
+            parameters=parameters)
+
+# Create a Toolset
+toolset = Toolset([tool])
+
+# Usually, the ChatMessage with tool_calls is generated by a Language Model
+# Here, we create it manually for demonstration purposes
+tool_call = ToolCall(
+    tool_name="weather_tool",
+    arguments={"city": "Berlin"}
+)
+message = ChatMessage.from_assistant(tool_calls=[tool_call])
+
+# ToolInvoker initialization and run with Toolset
+invoker = ToolInvoker(tools=toolset)
+result = invoker.run(messages=[message])
+
+print(result)
+
+
+
+
+
+
+
+
+
+
+
+
+#### __init__
+
+```python
+__init__(
+    tools: ToolsType,
+    raise_on_failure: bool = True,
+    convert_result_to_json_string: bool = False,
+    streaming_callback: StreamingCallbackT | None = None,
+    *,
+    enable_streaming_callback_passthrough: bool = False,
+    max_workers: int = 4
+)
+````
+
+Initialize the ToolInvoker component.
+
+**Parameters:**
+
+- **tools** (<code>ToolsType</code>) – A list of Tool and/or Toolset objects, or a Toolset instance that can resolve tools.
+- **raise_on_failure** (<code>bool</code>) – If True, the component will raise an exception in case of errors
+  (tool not found, tool invocation errors, tool result conversion errors).
+  If False, the component will return a ChatMessage object with `error=True`
+  and a description of the error in `result`.
+- **convert_result_to_json_string** (<code>bool</code>) – If True, the tool invocation result will be converted to a string using `json.dumps`.
+  If False, the tool invocation result will be converted to a string using `str`.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that will be called to emit tool results.
+  Note that the result is only emitted once it becomes available — it is not
+  streamed incrementally in real time.
+- **enable_streaming_callback_passthrough** (<code>bool</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
+  This allows tools to stream their results back to the client.
+  Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
+  If False, the `streaming_callback` will not be passed to the tool invocation.
+- **max_workers** (<code>int</code>) – The maximum number of workers to use in the thread pool executor.
+  This also decides the maximum number of concurrent tool invocations.
+
+**Raises:**
+
+- <code>ValueError</code> – If no tools are provided or if duplicate tool names are found.
+
+#### warm_up
+
+```python
+warm_up()
+```
+
+Warm up the tool invoker.
+
+This will warm up the tools registered in the tool invoker.
+This method is idempotent and will only warm up the tools once.
+
+#### run
+
+```python
+run(
+    messages: list[ChatMessage],
+    state: State | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    *,
+    enable_streaming_callback_passthrough: bool | None = None,
+    tools: ToolsType | None = None
+) -> dict[str, Any]
+```
+
+Processes ChatMessage objects containing tool calls and invokes the corresponding tools, if available.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects.
+- **state** (<code>State | None</code>) – The runtime state that should be used by the tools.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – A callback function that will be called to emit tool results.
+  Note that the result is only emitted once it becomes available — it is not
+  streamed incrementally in real time.
+- **enable_streaming_callback_passthrough** (<code>bool | None</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
+  This allows tools to stream their results back to the client.
+  Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
+  If False, the `streaming_callback` will not be passed to the tool invocation.
+  If None, the value from the constructor will be used.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role.
+  Each ChatMessage objects wraps the result of a tool invocation.
+
+**Raises:**
+
+- <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True.
+- <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True.
+- <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True.
+- <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True.
+
+#### run_async
+
+```python
+run_async(
+    messages: list[ChatMessage],
+    state: State | None = None,
+    streaming_callback: StreamingCallbackT | None = None,
+    *,
+    enable_streaming_callback_passthrough: bool | None = None,
+    tools: ToolsType | None = None
+) -> dict[str, Any]
+```
+
+Asynchronously processes ChatMessage objects containing tool calls.
+
+Multiple tool calls are performed concurrently.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects.
+- **state** (<code>State | None</code>) – The runtime state that should be used by the tools.
+- **streaming_callback** (<code>StreamingCallbackT | None</code>) – An asynchronous callback function that will be called to emit tool results.
+  Note that the result is only emitted once it becomes available — it is not
+  streamed incrementally in real time.
+- **enable_streaming_callback_passthrough** (<code>bool | None</code>) – If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it.
+  This allows tools to stream their results back to the client.
+  Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature.
+  If False, the `streaming_callback` will not be passed to the tool invocation.
+  If None, the value from the constructor will be used.
+- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
+  If set, it will override the `tools` parameter provided during initialization.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role.
+  Each ChatMessage objects wraps the result of a tool invocation.
+
+**Raises:**
+
+- <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True.
+- <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True.
+- <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True.
+- <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> ToolInvoker
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>ToolInvoker</code> – The deserialized component.