unique_toolkit 1.15.0__py3-none-any.whl → 1.16.1__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 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,23 @@ 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
-
-    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
-        ]
-
-    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)
+        raise NotImplementedError()
 
-    def get_tool_definitions(
-        self,
-    ) -> list[LanguageModelTool | LanguageModelToolDescription]:
-        return [tool.tool_description() for tool in self._tools]
+    @abstractmethod
+    def get_tool_choices(self) -> list[str]:
+        raise NotImplementedError()
 
-    def get_tool_prompts(self) -> list[ToolPrompts]:
-        return [tool.get_tool_prompts() for tool in self._tools]
+    @abstractmethod
+    def get_exclusive_tools(self) -> list[str]:
+        raise NotImplementedError()
 
     def does_a_tool_take_control(self, tool_calls: list[LanguageModelFunction]) -> bool:
         for tool_call in tool_calls:
@@ -233,6 +129,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 +205,269 @@ 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
+        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]}")
+
+    @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 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/chat/functions.py

@@ -1,13 +1,17 @@
 import logging
 import re
-from typing import Any
+from typing import Any, Sequence
 
 import unique_sdk
+from openai.types.chat import ChatCompletionToolChoiceOptionParam
+from openai.types.chat.chat_completion_message_param import ChatCompletionMessageParam
 from typing_extensions import deprecated
 from unique_sdk._list_object import ListObject
 
 from unique_toolkit._common import _time_utils
-from unique_toolkit.chat.constants import DEFAULT_MAX_MESSAGES
+from unique_toolkit.chat.constants import (
+    DEFAULT_MAX_MESSAGES,
+)
 from unique_toolkit.chat.schemas import (
     ChatMessage,
     ChatMessageAssessment,
@@ -30,10 +34,11 @@ from unique_toolkit.language_model.constants import (
     DEFAULT_COMPLETE_TIMEOUT,
 )
 from unique_toolkit.language_model.functions import (
-    ChatCompletionMessageParam,
     _prepare_all_completions_params_util,
 )
-from unique_toolkit.language_model.infos import LanguageModelName
+from unique_toolkit.language_model.infos import (
+    LanguageModelName,
+)
 from unique_toolkit.language_model.schemas import (
     LanguageModelMessages,
     LanguageModelStreamResponse,
@@ -761,8 +766,9 @@ def stream_complete_with_references(
     debug_info: dict | None = None,
     temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
     timeout: int = DEFAULT_COMPLETE_TIMEOUT,
-    tools: list[LanguageModelTool | LanguageModelToolDescription] | None = None,
+    tools: Sequence[LanguageModelTool | LanguageModelToolDescription] | None = None,
     start_text: str | None = None,
+    tool_choice: ChatCompletionToolChoiceOptionParam | None = None,
     other_options: dict | None = None,
 ) -> LanguageModelStreamResponse:
     """Streams a completion synchronously.
@@ -795,6 +801,7 @@ def stream_complete_with_references(
             temperature=temperature,
             tools=tools,
             other_options=other_options,
+            tool_choice=tool_choice,
             content_chunks=content_chunks or [],
         )
     )
@@ -871,7 +878,8 @@ async def stream_complete_with_references_async(
     debug_info: dict | None = None,
     temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
     timeout: int = DEFAULT_COMPLETE_TIMEOUT,
-    tools: list[LanguageModelTool | LanguageModelToolDescription] | None = None,
+    tools: Sequence[LanguageModelTool | LanguageModelToolDescription] | None = None,
+    tool_choice: ChatCompletionToolChoiceOptionParam | None = None,
     start_text: str | None = None,
     other_options: dict | None = None,
 ) -> LanguageModelStreamResponse:
@@ -889,6 +897,7 @@ async def stream_complete_with_references_async(
             model_name=model_name,
             temperature=temperature,
             tools=tools,
+            tool_choice=tool_choice,
             other_options=other_options,
             content_chunks=content_chunks or [],
         )