haystack-experimental 0.13.0__py3-none-any.whl → 0.14.0__py3-none-any.whl

haystack_experimental/components/agents/human_in_the_loop/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import sys
+from typing import TYPE_CHECKING
+
+from lazy_imports import LazyImporter
+
+_import_structure = {
+    "dataclasses": ["ConfirmationUIResult", "ToolExecutionDecision"],
+    "errors": ["HITLBreakpointException"],
+    "policies": ["AlwaysAskPolicy", "NeverAskPolicy", "AskOncePolicy"],
+    "strategies": ["BlockingConfirmationStrategy", "BreakpointConfirmationStrategy"],
+    "types": ["ConfirmationPolicy", "ConfirmationUI", "ConfirmationStrategy"],
+    "user_interfaces": ["RichConsoleUI", "SimpleConsoleUI"],
+}
+
+if TYPE_CHECKING:
+    from .dataclasses import ConfirmationUIResult as ConfirmationUIResult
+    from .dataclasses import ToolExecutionDecision as ToolExecutionDecision
+    from .errors import HITLBreakpointException as HITLBreakpointException
+    from .policies import AlwaysAskPolicy as AlwaysAskPolicy
+    from .policies import AskOncePolicy as AskOncePolicy
+    from .policies import NeverAskPolicy as NeverAskPolicy
+    from .strategies import BlockingConfirmationStrategy as BlockingConfirmationStrategy
+    from .strategies import BreakpointConfirmationStrategy as BreakpointConfirmationStrategy
+    from .types import ConfirmationPolicy as ConfirmationPolicy
+    from .types import ConfirmationStrategy as ConfirmationStrategy
+    from .types import ConfirmationUI as ConfirmationUI
+    from .user_interfaces import RichConsoleUI as RichConsoleUI
+    from .user_interfaces import SimpleConsoleUI as SimpleConsoleUI
+
+else:
+    sys.modules[__name__] = LazyImporter(name=__name__, module_file=__file__, import_structure=_import_structure)

haystack_experimental/components/agents/human_in_the_loop/breakpoint.py

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack.dataclasses.breakpoints import AgentSnapshot, ToolBreakpoint
+from haystack.utils import _deserialize_value_with_schema
+
+from haystack_experimental.components.agents.human_in_the_loop.strategies import _prepare_tool_args
+
+
+def get_tool_calls_and_descriptions_from_snapshot(
+    agent_snapshot: AgentSnapshot, breakpoint_tool_only: bool = True
+) -> tuple[list[dict], dict[str, str]]:
+    """
+    Extract tool calls and tool descriptions from an AgentSnapshot.
+
+    By default, only the tool call that caused the breakpoint is processed and its arguments are reconstructed.
+    This is useful for scenarios where you want to present the relevant tool call and its description
+    to a human for confirmation before execution.
+
+    :param agent_snapshot: The AgentSnapshot from which to extract tool calls and descriptions.
+    :param breakpoint_tool_only: If True, only the tool call that caused the breakpoint is returned. If False, all tool
+        calls are returned.
+    :returns:
+        A tuple containing a list of tool call dictionaries and a dictionary of tool descriptions
+    """
+    break_point = agent_snapshot.break_point.break_point
+    if not isinstance(break_point, ToolBreakpoint):
+        raise ValueError("The provided AgentSnapshot does not contain a ToolBreakpoint.")
+
+    tool_caused_break_point = break_point.tool_name
+
+    # Deserialize the tool invoker inputs from the snapshot
+    tool_invoker_inputs = _deserialize_value_with_schema(agent_snapshot.component_inputs["tool_invoker"])
+    tool_call_messages = tool_invoker_inputs["messages"]
+    state = tool_invoker_inputs["state"]
+    tool_name_to_tool = {t.name: t for t in tool_invoker_inputs["tools"]}
+
+    tool_calls = []
+    for msg in tool_call_messages:
+        if msg.tool_calls:
+            tool_calls.extend(msg.tool_calls)
+    serialized_tcs = [tc.to_dict() for tc in tool_calls]
+
+    # Reconstruct the final arguments for each tool call
+    tool_descriptions = {}
+    updated_tool_calls = []
+    for tc in serialized_tcs:
+        # Only process the tool that caused the breakpoint if breakpoint_tool_only is True
+        if breakpoint_tool_only and tc["tool_name"] != tool_caused_break_point:
+            continue
+
+        final_args = _prepare_tool_args(
+            tool=tool_name_to_tool[tc["tool_name"]],
+            tool_call_arguments=tc["arguments"],
+            state=state,
+            streaming_callback=tool_invoker_inputs.get("streaming_callback", None),
+            enable_streaming_passthrough=tool_invoker_inputs.get("enable_streaming_passthrough", False),
+        )
+        updated_tool_calls.append({**tc, "arguments": final_args})
+        tool_descriptions[tc["tool_name"]] = tool_name_to_tool[tc["tool_name"]].description
+
+    return updated_tool_calls, tool_descriptions

haystack_experimental/components/agents/human_in_the_loop/dataclasses.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from dataclasses import asdict, dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class ConfirmationUIResult:
+    """
+    Result of the confirmation UI interaction.
+
+    :param action:
+        The action taken by the user such as "confirm", "reject", or "modify".
+        This action type is not enforced to allow for custom actions to be implemented.
+    :param feedback:
+        Optional feedback message from the user. For example, if the user rejects the tool execution,
+        they might provide a reason for the rejection.
+    :param new_tool_params:
+        Optional set of new parameters for the tool. For example, if the user chooses to modify the tool parameters,
+        they can provide a new set of parameters here.
+    """
+
+    action: str  # "confirm", "reject", "modify"
+    feedback: Optional[str] = None
+    new_tool_params: Optional[dict[str, Any]] = None
+
+
+@dataclass
+class ToolExecutionDecision:
+    """
+    Decision made regarding tool execution.
+
+    :param tool_name:
+        The name of the tool to be executed.
+    :param execute:
+        A boolean indicating whether to execute the tool with the provided parameters.
+    :param tool_call_id:
+        Optional unique identifier for the tool call. This can be used to track and correlate the decision with a
+        specific tool invocation.
+    :param feedback:
+        Optional feedback message.
+        For example, if the tool execution is rejected, this can contain the reason. Or if the tool parameters were
+        modified, this can contain the modification details.
+    :param final_tool_params:
+        Optional final parameters for the tool if execution is confirmed or modified.
+    """
+
+    tool_name: str
+    execute: bool
+    tool_call_id: Optional[str] = None
+    feedback: Optional[str] = None
+    final_tool_params: Optional[dict[str, Any]] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the ToolExecutionDecision to a dictionary representation.
+
+        :return: A dictionary containing the tool execution decision details.
+        """
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ToolExecutionDecision":
+        """
+        Populate the ToolExecutionDecision from a dictionary representation.
+
+        :param data: A dictionary containing the tool execution decision details.
+        :return: An instance of ToolExecutionDecision.
+        """
+        return cls(**data)

haystack_experimental/components/agents/human_in_the_loop/errors.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Optional
+
+
+class HITLBreakpointException(Exception):
+    """
+    Exception raised when a tool execution is paused by a ConfirmationStrategy (e.g. BreakpointConfirmationStrategy).
+    """
+
+    def __init__(
+        self, message: str, tool_name: str, snapshot_file_path: str, tool_call_id: Optional[str] = None
+    ) -> None:
+        """
+        Initialize the HITLBreakpointException.
+
+        :param message: The exception message.
+        :param tool_name: The name of the tool whose execution is paused.
+        :param snapshot_file_path: The file path to the saved pipeline snapshot.
+        :param tool_call_id: Optional unique identifier for the tool call. This can be used to track and correlate
+            the decision with a specific tool invocation.
+        """
+        super().__init__(message)
+        self.tool_name = tool_name
+        self.snapshot_file_path = snapshot_file_path
+        self.tool_call_id = tool_call_id

haystack_experimental/components/agents/human_in_the_loop/policies.py

@@ -0,0 +1,78 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack_experimental.components.agents.human_in_the_loop.dataclasses import ConfirmationUIResult
+from haystack_experimental.components.agents.human_in_the_loop.types import ConfirmationPolicy
+
+
+class AlwaysAskPolicy(ConfirmationPolicy):
+    """Always ask for confirmation."""
+
+    def should_ask(self, tool_name: str, tool_description: str, tool_params: dict[str, Any]) -> bool:
+        """
+        Always ask for confirmation before executing the tool.
+
+        :param tool_name: The name of the tool to be executed.
+        :param tool_description: The description of the tool.
+        :param tool_params: The parameters to be passed to the tool.
+        :returns: Always returns True, indicating confirmation is needed.
+        """
+        return True
+
+
+class NeverAskPolicy(ConfirmationPolicy):
+    """Never ask for confirmation."""
+
+    def should_ask(self, tool_name: str, tool_description: str, tool_params: dict[str, Any]) -> bool:
+        """
+        Never ask for confirmation, always proceed with tool execution.
+
+        :param tool_name: The name of the tool to be executed.
+        :param tool_description: The description of the tool.
+        :param tool_params: The parameters to be passed to the tool.
+        :returns: Always returns False, indicating no confirmation is needed.
+        """
+        return False
+
+
+class AskOncePolicy(ConfirmationPolicy):
+    """Ask only once per tool with specific parameters."""
+
+    def __init__(self):
+        self._asked_tools = {}
+
+    def should_ask(self, tool_name: str, tool_description: str, tool_params: dict[str, Any]) -> bool:
+        """
+        Ask for confirmation only once per tool with specific parameters.
+
+        :param tool_name: The name of the tool to be executed.
+        :param tool_description: The description of the tool.
+        :param tool_params: The parameters to be passed to the tool.
+        :returns: True if confirmation is needed, False if already asked with the same parameters.
+        """
+        # Don't ask again if we've already asked for this tool with the same parameters
+        return not (tool_name in self._asked_tools and self._asked_tools[tool_name] == tool_params)
+
+    def update_after_confirmation(
+        self,
+        tool_name: str,
+        tool_description: str,
+        tool_params: dict[str, Any],
+        confirmation_result: ConfirmationUIResult,
+    ) -> None:
+        """
+        Store the tool and parameters if the action was "confirm" to avoid asking again.
+
+        This method updates the internal state to remember that the user has already confirmed the execution of the
+        tool with the given parameters.
+
+        :param tool_name: The name of the tool that was executed.
+        :param tool_description: The description of the tool.
+        :param tool_params: The parameters that were passed to the tool.
+        :param confirmation_result: The result from the confirmation UI.
+        """
+        if confirmation_result.action == "confirm":
+            self._asked_tools[tool_name] = tool_params