unique_toolkit 1.8.1__py3-none-any.whl → 1.23.0__py3-none-any.whl

unique_toolkit/agentic/tools/tool_manager.py

@@ -1,7 +1,12 @@
 import asyncio
+from abc import ABC, abstractmethod
 from logging import Logger, getLogger
-from typing import Any
+from typing import Literal, override
 
+from openai.types.chat import (
+    ChatCompletionNamedToolChoiceParam,
+)
+from openai.types.responses import ToolParam, response_create_params
 from pydantic import BaseModel, Field
 
 from unique_toolkit.agentic.evaluation.schemas import EvaluationMetricName
@@ -9,6 +14,10 @@ from unique_toolkit.agentic.tools.a2a import A2AManager, SubAgentTool
 from unique_toolkit.agentic.tools.config import ToolBuildConfig
 from unique_toolkit.agentic.tools.factory import ToolFactory
 from unique_toolkit.agentic.tools.mcp.manager import MCPManager
+from unique_toolkit.agentic.tools.openai_builtin.base import (
+    OpenAIBuiltInTool,
+)
+from unique_toolkit.agentic.tools.openai_builtin.manager import OpenAIBuiltInToolManager
 from unique_toolkit.agentic.tools.schemas import ToolCallResponse, ToolPrompts
 from unique_toolkit.agentic.tools.tool import Tool
 from unique_toolkit.agentic.tools.tool_progress_reporter import ToolProgressReporter
@@ -19,7 +28,6 @@ from unique_toolkit.agentic.tools.utils.execution.execution import (
 from unique_toolkit.app.schemas import ChatEvent
 from unique_toolkit.language_model.schemas import (
     LanguageModelFunction,
-    LanguageModelTool,
     LanguageModelToolDescription,
 )
 
@@ -44,135 +52,41 @@ class ToolManagerConfig(BaseModel):
     )
 
 
-class ToolManager:
-    """
-    Manages the tools available to the agent and executes tool calls.
-
-    This class is responsible for:
-    - Initializing tools based on the provided configuration and runtime events.
-    - Filtering tools based on availability, exclusivity, and user-defined constraints.
-    - Managing the lifecycle of tools, including retrieval, execution, and logging.
-    - Executing tool calls in parallel when possible to optimize performance.
-    - Enforcing limits on the number of tool calls and handling duplicate requests.
-
-    Key Features:
-    - Dynamic Tool Initialization: Tools are dynamically selected and initialized
-      based on runtime events and user preferences.
-    - Parallel Execution: Supports asynchronous execution of tools for efficiency.
-    - Error Handling: Provides detailed error messages and logs for failed tool calls.
-    - Scalability: Designed to handle a large number of tools and tool calls efficiently.
-
-    Only the ToolManager is allowed to interact with the tools directly.
-    """
-
-    def __init__(
-        self,
-        logger: Logger,
-        config: ToolManagerConfig,
-        event: ChatEvent,
-        tool_progress_reporter: ToolProgressReporter,
-        mcp_manager: MCPManager,
-        a2a_manager: A2AManager,
-    ):
-        self._logger = logger
+class BaseToolManager(ABC):
+    def __init__(self, config: ToolManagerConfig):
         self._config = config
-        self._tool_progress_reporter = tool_progress_reporter
-        self._tools = []
-        self._tool_choices = event.payload.tool_choices
-        self._disabled_tools = event.payload.disabled_tools
         # this needs to be a set of strings to avoid duplicates
         self._tool_evaluation_check_list: set[EvaluationMetricName] = set()
-        self._mcp_manager = mcp_manager
-        self._a2a_manager = a2a_manager
-        self._init__tools(event)
-
-    def _init__tools(self, event: ChatEvent) -> None:
-        tool_choices = self._tool_choices
-        tool_configs = self._config.tools
-        self._logger.info("Initializing tool definitions...")
-        self._logger.info(f"Tool choices: {tool_choices}")
-        self._logger.info(f"Tool configs: {tool_configs}")
-
-        tool_configs, sub_agents = self._a2a_manager.get_all_sub_agents(
-            tool_configs, event
-        )
-
-        # Build internal tools from configurations
-        internal_tools = [
-            ToolFactory.build_tool_with_settings(
-                t.name,
-                t,
-                t.configuration,
-                event,
-                tool_progress_reporter=self._tool_progress_reporter,
-            )
-            for t in tool_configs
-        ]
-
-        # Get MCP tools (these are already properly instantiated)
-        mcp_tools = self._mcp_manager.get_all_mcp_tools()
-        # Combine both types of tools
-        self.available_tools = internal_tools + mcp_tools + sub_agents
-        self._sub_agents = sub_agents
-
-        for t in self.available_tools:
-            if not t.is_enabled():
-                continue
-            if t.name in self._disabled_tools:
-                continue
-            # if tool choices are given, only include those tools
-            if len(self._tool_choices) > 0 and t.name not in self._tool_choices:
-                continue
-            # is the tool exclusive and has been choosen by the user?
-            if t.is_exclusive() and len(tool_choices) > 0 and t.name in tool_choices:
-                self._tools = [t]  # override all other tools
-                break
-            # if the tool is exclusive but no tool choices are given, skip it
-            if t.is_exclusive():
-                continue
-
-            self._tools.append(t)
-
-    @property
-    def sub_agents(self) -> list[SubAgentTool]:
-        return self._sub_agents
-
-    def get_evaluation_check_list(self) -> list[EvaluationMetricName]:
-        return list(self._tool_evaluation_check_list)
-
-    def log_loaded_tools(self):
-        self._logger.info(f"Loaded tools: {[tool.name for tool in self._tools]}")
-
-    def get_tools(self) -> list[Tool]:
-        return self._tools  # type: ignore
 
+    @abstractmethod
     def get_tool_by_name(self, name: str) -> Tool | None:
-        for tool in self._tools:
-            if tool.name == name:
-                return tool
-        return None
+        raise NotImplementedError()
 
-    def get_forced_tools(self) -> list[dict[str, Any]]:
-        return [
-            self._convert_to_forced_tool(t.name)
-            for t in self._tools
-            if t.name in self._tool_choices
-        ]
+    @abstractmethod
+    def get_tool_choices(self) -> list[str]:
+        raise NotImplementedError()
 
-    def add_forced_tool(self, name):
-        tool = self.get_tool_by_name(name)
-        if not tool:
-            raise ValueError(f"Tool {name} not found")
-        self._tools.append(tool)
-        self._tool_choices.append(tool.name)
+    @abstractmethod
+    def get_exclusive_tools(self) -> list[str]:
+        raise NotImplementedError()
 
-    def get_tool_definitions(
+    @abstractmethod
+    def filter_tool_calls(
         self,
-    ) -> list[LanguageModelTool | LanguageModelToolDescription]:
-        return [tool.tool_description() for tool in self._tools]
+        tool_calls: list[LanguageModelFunction],
+        tool_types: list[Literal["mcp", "internal", "subagent"]],
+    ) -> list[LanguageModelFunction]:
+        """
+        Filter tool calls by their types.
 
-    def get_tool_prompts(self) -> list[ToolPrompts]:
-        return [tool.get_tool_prompts() for tool in self._tools]
+        Args:
+            tool_calls: List of tool calls to filter
+            tool_types: List of tool types to include (e.g., ["mcp", "internal", "subagent"])
+
+        Returns:
+            Filtered list of tool calls matching the specified types
+        """
+        raise NotImplementedError()
 
     def does_a_tool_take_control(self, tool_calls: list[LanguageModelFunction]) -> bool:
         for tool_call in tool_calls:
@@ -233,6 +147,14 @@ class ToolManager:
             unpacked_tool_call_result = self._create_tool_call_response(
                 result, tool_calls[i]
             )
+            if unpacked_tool_call_result.debug_info is None:
+                unpacked_tool_call_result.debug_info = {}
+            unpacked_tool_call_result.debug_info["is_exclusive"] = (
+                tool_calls[i].name in self.get_exclusive_tools()
+            )
+            unpacked_tool_call_result.debug_info["is_forced"] = (
+                tool_calls[i].name in self.get_tool_choices()
+            )
             tool_call_results_unpacked.append(unpacked_tool_call_result)
 
         return tool_call_results_unpacked
@@ -301,8 +223,301 @@ class ToolManager:
             )
         return unique_tool_calls
 
-    def _convert_to_forced_tool(self, tool_name: str) -> dict[str, Any]:
+    def get_evaluation_check_list(self) -> list[EvaluationMetricName]:
+        return list(self._tool_evaluation_check_list)
+
+
+class ToolManager(BaseToolManager):
+    """
+    Manages the tools available to the agent and executes tool calls.
+
+    This class is responsible for:
+    - Initializing tools based on the provided configuration and runtime events.
+    - Filtering tools based on availability, exclusivity, and user-defined constraints.
+    - Managing the lifecycle of tools, including retrieval, execution, and logging.
+    - Executing tool calls in parallel when possible to optimize performance.
+    - Enforcing limits on the number of tool calls and handling duplicate requests.
+
+    Key Features:
+    - Dynamic Tool Initialization: Tools are dynamically selected and initialized
+      based on runtime events and user preferences.
+    - Parallel Execution: Supports asynchronous execution of tools for efficiency.
+    - Error Handling: Provides detailed error messages and logs for failed tool calls.
+    - Scalability: Designed to handle a large number of tools and tool calls efficiently.
+
+    Only the ToolManager is allowed to interact with the tools directly.
+    """
+
+    def __init__(
+        self,
+        logger: Logger,
+        config: ToolManagerConfig,
+        event: ChatEvent,
+        tool_progress_reporter: ToolProgressReporter,
+        mcp_manager: MCPManager,
+        a2a_manager: A2AManager,
+    ):
+        super().__init__(config)
+        self._logger = logger
+        self._config = config
+        self._tool_progress_reporter = tool_progress_reporter
+        self._tools = []
+        self._tool_choices = event.payload.tool_choices
+        self._disabled_tools = event.payload.disabled_tools
+        self._exclusive_tools = [
+            tool.name for tool in self._config.tools if tool.is_exclusive
+        ]
+        # this needs to be a set of strings to avoid duplicates
+        self._tool_evaluation_check_list: set[EvaluationMetricName] = set()
+        self._mcp_manager = mcp_manager
+        self._a2a_manager = a2a_manager
+        self._init__tools(event)
+
+    def _init__tools(self, event: ChatEvent) -> None:
+        tool_choices = self._tool_choices
+        tool_configs = self._config.tools
+        self._logger.info("Initializing tool definitions...")
+        self._logger.info(f"Tool choices: {tool_choices}")
+
+        tool_configs, sub_agents = self._a2a_manager.get_all_sub_agents(
+            tool_configs, event
+        )
+
+        # Build internal tools from configurations
+        self._internal_tools = [
+            ToolFactory.build_tool_with_settings(
+                t.name,
+                t,
+                t.configuration,
+                event,
+                tool_progress_reporter=self._tool_progress_reporter,
+            )
+            for t in tool_configs
+        ]
+
+        # Get MCP tools (these are already properly instantiated)
+        self._mcp_tools = self._mcp_manager.get_all_mcp_tools()
+        # Combine both types of tools
+        self.available_tools = self._internal_tools + self._mcp_tools + sub_agents
+        self._sub_agents = sub_agents
+
+        for t in self.available_tools:
+            if not t.is_enabled():
+                continue
+            if t.name in self._disabled_tools:
+                continue
+            # if tool choices are given, only include those tools
+            if len(self._tool_choices) > 0 and t.name not in self._tool_choices:
+                continue
+            # is the tool exclusive and has been choosen by the user?
+            if t.is_exclusive() and len(tool_choices) > 0 and t.name in tool_choices:
+                self._tools = [t]  # override all other tools
+                break
+            # if the tool is exclusive but no tool choices are given, skip it
+            if t.is_exclusive():
+                continue
+
+            self._tools.append(t)
+
+    @override
+    def filter_tool_calls(
+        self,
+        tool_calls: list[LanguageModelFunction],
+        tool_types: list[Literal["mcp", "internal", "subagent"]],
+    ) -> list[LanguageModelFunction]:
+        filtered_calls = []
+
+        # Build sets for efficient lookup
+        internal_tool_names = {tool.name for tool in self._internal_tools}
+        mcp_tool_names = {tool.name for tool in self._mcp_tools}
+        sub_agent_names = {tool.name for tool in self._sub_agents}
+
+        for tool_call in tool_calls:
+            if "internal" in tool_types and tool_call.name in internal_tool_names:
+                filtered_calls.append(tool_call)
+            elif "mcp" in tool_types and tool_call.name in mcp_tool_names:
+                filtered_calls.append(tool_call)
+            elif "subagent" in tool_types and tool_call.name in sub_agent_names:
+                filtered_calls.append(tool_call)
+
+        return filtered_calls
+
+    @property
+    def sub_agents(self) -> list[SubAgentTool]:
+        return self._sub_agents
+
+    def get_evaluation_check_list(self) -> list[EvaluationMetricName]:
+        return list(self._tool_evaluation_check_list)
+
+    def log_loaded_tools(self):
+        self._logger.info(f"Loaded tools: {[tool.name for tool in self._tools]}")
+
+    @override
+    def get_tool_by_name(self, name: str) -> Tool | None:
+        for tool in self._tools:
+            if tool.name == name:
+                return tool
+        return None
+
+    @override
+    def get_tool_choices(self) -> list[str]:
+        return self._tool_choices
+
+    @override
+    def get_exclusive_tools(self) -> list[str]:
+        return self._exclusive_tools
+
+    def get_tools(self) -> list[Tool]:
+        return self._tools  # type: ignore
+
+    def get_forced_tools(
+        self,
+    ) -> list[ChatCompletionNamedToolChoiceParam]:
+        return [
+            self._convert_to_forced_tool(t.name)
+            for t in self._tools
+            if t.name in self._tool_choices
+        ]
+
+    def get_tool_definitions(
+        self,
+    ) -> list[LanguageModelToolDescription]:
+        return [tool.tool_description() for tool in self._tools]
+
+    def get_tool_prompts(self) -> list[ToolPrompts]:
+        return [tool.get_tool_prompts() for tool in self._tools]
+
+    def add_forced_tool(self, name):
+        tool = self.get_tool_by_name(name)
+        if not tool:
+            raise ValueError(f"Tool {name} not found")
+
+        if tool.name not in self._tool_choices:
+            self._tool_choices.append(tool.name)
+
+    def _convert_to_forced_tool(
+        self, tool_name: str
+    ) -> ChatCompletionNamedToolChoiceParam:
         return {
             "type": "function",
             "function": {"name": tool_name},
         }
+
+    def tool_choices(self) -> list[str]:
+        return self._tool_choices.copy()
+
+
+class ResponsesApiToolManager(BaseToolManager):
+    def __init__(
+        self,
+        logger: Logger,
+        config: ToolManagerConfig,
+        tool_manager: ToolManager,
+        builtin_tools: list[OpenAIBuiltInTool],
+    ) -> None:
+        super().__init__(config)
+        self._logger = logger
+        self._config = config
+        self._tool_manager = tool_manager
+        self._builtin_tools = builtin_tools
+        self._tools = self._tool_manager.get_tools()
+
+    @classmethod
+    async def build_manager(
+        cls,
+        logger: Logger,
+        config: ToolManagerConfig,
+        event: ChatEvent,
+        tool_progress_reporter: ToolProgressReporter,
+        mcp_manager: MCPManager,
+        a2a_manager: A2AManager,
+        builtin_tool_manager: OpenAIBuiltInToolManager,
+    ) -> "ResponsesApiToolManager":
+        (
+            tool_configs,
+            builtin_tools,
+        ) = await builtin_tool_manager.get_all_openai_builtin_tools(config.tools)
+
+        completions_tool_manager_config = ToolManagerConfig(
+            tools=tool_configs, max_tool_calls=config.max_tool_calls
+        )
+        completions_tool_manager = ToolManager(
+            logger=logger,
+            config=completions_tool_manager_config,
+            event=event,
+            tool_progress_reporter=tool_progress_reporter,
+            mcp_manager=mcp_manager,
+            a2a_manager=a2a_manager,
+        )
+
+        return cls(
+            logger=logger,
+            config=config,
+            tool_manager=completions_tool_manager,
+            builtin_tools=builtin_tools,
+        )
+
+    @override
+    def filter_tool_calls(
+        self,
+        tool_calls: list[LanguageModelFunction],
+        tool_types: list[Literal["mcp", "internal", "subagent"]],
+    ) -> list[LanguageModelFunction]:
+        """Delegate filtering to the underlying tool manager."""
+        return self._tool_manager.filter_tool_calls(tool_calls, tool_types)
+
+    @override
+    def get_tool_by_name(self, name: str) -> Tool | None:
+        return self._tool_manager.get_tool_by_name(name)
+
+    @override
+    def get_tool_choices(self) -> list[str]:
+        return self._tool_manager._tool_choices
+
+    @override
+    def get_exclusive_tools(self) -> list[str]:
+        return self._tool_manager._exclusive_tools
+
+    @property
+    def sub_agents(self) -> list[SubAgentTool]:
+        return self._tool_manager.sub_agents
+
+    def log_loaded_tools(self):
+        self._logger.info(
+            f"Loaded tools: {[tool.name for tool in self._tools + self._builtin_tools]}"
+        )
+
+    def get_tools(self) -> list[Tool]:
+        return self._tool_manager.get_tools()
+
+    def get_forced_tools(
+        self,
+    ) -> list[response_create_params.ToolChoice]:
+        """
+        Note that built-in tools cannot be forced at the moment
+        """
+        return [
+            {
+                "name": t.name,
+                "type": "function",
+            }
+            for t in self._tools
+            if t.name in self._tool_manager.tool_choices()
+        ]
+
+    def get_tool_definitions(
+        self,
+    ) -> list[LanguageModelToolDescription | ToolParam]:
+        if len(self._tool_manager.tool_choices()) > 0:
+            # We cannot send a builtin tool in this case (api error)
+            return [tool.tool_description() for tool in self._tools]
+        else:
+            return [
+                tool.tool_description() for tool in self._tools + self._builtin_tools
+            ]
+
+    def get_tool_prompts(self) -> list[ToolPrompts]:
+        return [tool.get_tool_prompts() for tool in self._tools + self._builtin_tools]
+
+    def add_forced_tool(self, name: str) -> None:
+        self._tool_manager.add_forced_tool(name)

unique_toolkit/agentic/tools/tool_progress_reporter.py

@@ -1,11 +1,12 @@
 import re
 from datetime import datetime
-from enum import Enum
+from enum import StrEnum
 from functools import wraps
-from typing import Protocol
+from typing import Protocol, TypedDict
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
+from unique_toolkit._common.pydantic_helpers import get_configuration_dict
 from unique_toolkit.chat.service import ChatService
 from unique_toolkit.content.schemas import ContentReference
 from unique_toolkit.language_model.schemas import (
@@ -17,11 +18,11 @@ ARROW = "→ "
 DUMMY_REFERENCE_PLACEHOLDER = "<sup></sup>"
 
 
-class ProgressState(Enum):
-    STARTED = "⚪"
-    RUNNING = "🟡"
-    FAILED = "🔴"
-    FINISHED = "🟢"
+class ProgressState(StrEnum):
+    STARTED = "started"
+    RUNNING = "running"
+    FAILED = "failed"
+    FINISHED = "finished"
 
 
 class ToolExecutionStatus(BaseModel):
@@ -29,15 +30,54 @@ class ToolExecutionStatus(BaseModel):
     message: str
     state: ProgressState
     references: list[ContentReference] = []
-    timestamp: datetime = datetime.now()
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+
+class StateToDisplayTemplate(TypedDict):
+    started: str
+    running: str
+    failed: str
+    finished: str
+
+
+_DEFAULT_STATE_TO_DISPLAY_TEMPLATE: StateToDisplayTemplate = {
+    "started": "{arrow}**{{tool_name}}** ⚪: {{message}}".format(arrow=ARROW),
+    "running": "{arrow}**{{tool_name}}** 🟡: {{message}}".format(arrow=ARROW),
+    "finished": "{arrow}**{{tool_name}}** 🟢: {{message}}".format(arrow=ARROW),
+    "failed": "{arrow}**{{tool_name}}** 🔴: {{message}}".format(arrow=ARROW),
+}
+
+
+state_to_display_template_description = """
+Display templates for the different progress states.
+The template is a string that will be used to display the progress status.
+It can contain the following placeholders:
+- `{tool_name}`: The name of the tool
+- `{message}`: The message to display (sent by the tool)
+""".strip()
+
+
+class ToolProgressReporterConfig(BaseModel):
+    model_config = get_configuration_dict()
+
+    state_to_display_template: StateToDisplayTemplate = Field(
+        default=_DEFAULT_STATE_TO_DISPLAY_TEMPLATE,
+        description=state_to_display_template_description,
+        title="Display Templates",
+    )
 
 
 class ToolProgressReporter:
-    def __init__(self, chat_service: ChatService):
+    def __init__(
+        self,
+        chat_service: ChatService,
+        config: ToolProgressReporterConfig | None = None,
+    ):
         self.chat_service = chat_service
         self.tool_statuses: dict[str, ToolExecutionStatus] = {}
         self._progress_start_text = ""
         self._requires_new_assistant_message = False
+        self._config = config or ToolProgressReporterConfig()
 
     @property
     def requires_new_assistant_message(self):
@@ -77,16 +117,13 @@ class ToolProgressReporter:
             references (list[ContentReference], optional): List of content references. Defaults to [].
             requires_new_assistant_message (bool, optional): Whether a new assistant message is needed when tool call is finished.
             Defaults to False. If yes, the agentic steps will remain in chat history and will be overwritten by the stream response.
-
-        Raises:
-            AssertionError: If tool_call.id is None
         """
-        assert tool_call.id is not None
         self.tool_statuses[tool_call.id] = ToolExecutionStatus(
             name=name,
             message=message,
             state=state,
             references=references,
+            timestamp=self._get_timestamp_for_tool_call(tool_call),
         )
         self.requires_new_assistant_message = (
             self.requires_new_assistant_message or requires_new_assistant_message
@@ -103,7 +140,11 @@ class ToolProgressReporter:
             references = self._correct_reference_sequence(references, start_number)
             all_references.extend(references)
 
-            messages.append(f"{ARROW}**{item.name} {item.state.value}**: {message}")
+            display_message = self._get_tool_status_display_message(
+                name=item.name, message=message, state=item.state
+            )
+            if display_message is not None:
+                messages.append(display_message)
 
         await self.chat_service.modify_assistant_message_async(
             content=self._progress_start_text + "\n\n" + "\n\n".join(messages),
@@ -130,6 +171,31 @@ class ToolProgressReporter:
             reference.sequence_number = i
         return references
 
+    def _get_timestamp_for_tool_call(
+        self, tool_call: LanguageModelFunction
+    ) -> datetime:
+        """
+        Keep the same timestamp if the tool call is already in the statuses.
+        This ensures the display order stays consistent.
+        """
+        if tool_call.id in self.tool_statuses:
+            return self.tool_statuses[tool_call.id].timestamp
+
+        return datetime.now()
+
+    def _get_tool_status_display_message(
+        self, name: str, message: str, state: ProgressState
+    ) -> str | None:
+        display_message = self._config.state_to_display_template[state.value].format(
+            tool_name=name,
+            message=message,
+        )
+        # Don't display empty messages
+        if display_message.strip() == "":
+            return None
+
+        return display_message
+
 
 class ToolWithToolProgressReporter(Protocol):
     tool_progress_reporter: ToolProgressReporter

unique_toolkit/agentic/tools/utils/__init__.py

@@ -1 +1,19 @@
 """Utilities for tools."""
+
+from unique_toolkit.agentic.tools.utils.execution.execution import (
+    Result,
+    SafeTaskExecutor,
+    failsafe,
+    failsafe_async,
+    safe_execute,
+    safe_execute_async,
+)
+
+__all__ = [
+    "failsafe",
+    "failsafe_async",
+    "safe_execute",
+    "safe_execute_async",
+    "SafeTaskExecutor",
+    "Result",
+]