dify

dify/api/core/tools/__base/tool.py

@@ -0,0 +1,233 @@
+from abc import ABC, abstractmethod
+from collections.abc import Generator
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from models.model import File
+
+from core.tools.__base.tool_runtime import ToolRuntime
+from core.tools.entities.tool_entities import (
+    ToolEntity,
+    ToolInvokeMessage,
+    ToolParameter,
+    ToolProviderType,
+)
+
+
+class Tool(ABC):
+    """
+    The base class of a tool
+    """
+
+    def __init__(self, entity: ToolEntity, runtime: ToolRuntime):
+        self.entity = entity
+        self.runtime = runtime
+
+    def fork_tool_runtime(self, runtime: ToolRuntime) -> "Tool":
+        """
+        fork a new tool with metadata
+        :return: the new tool
+        """
+        return self.__class__(
+            entity=self.entity.model_copy(),
+            runtime=runtime,
+        )
+
+    @abstractmethod
+    def tool_provider_type(self) -> ToolProviderType:
+        """
+        get the tool provider type
+
+        :return: the tool provider type
+        """
+
+    def invoke(
+        self,
+        user_id: str,
+        tool_parameters: dict[str, Any],
+        conversation_id: str | None = None,
+        app_id: str | None = None,
+        message_id: str | None = None,
+    ) -> Generator[ToolInvokeMessage]:
+        if self.runtime and self.runtime.runtime_parameters:
+            tool_parameters.update(self.runtime.runtime_parameters)
+
+        # try parse tool parameters into the correct type
+        tool_parameters = self._transform_tool_parameters_type(tool_parameters)
+
+        result = self._invoke(
+            user_id=user_id,
+            tool_parameters=tool_parameters,
+            conversation_id=conversation_id,
+            app_id=app_id,
+            message_id=message_id,
+        )
+
+        if isinstance(result, ToolInvokeMessage):
+
+            def single_generator() -> Generator[ToolInvokeMessage, None, None]:
+                yield result
+
+            return single_generator()
+        elif isinstance(result, list):
+
+            def generator() -> Generator[ToolInvokeMessage, None, None]:
+                yield from result
+
+            return generator()
+        else:
+            return result
+
+    def _transform_tool_parameters_type(self, tool_parameters: dict[str, Any]) -> dict[str, Any]:
+        """
+        Transform tool parameters type
+        """
+        # Temp fix for the issue that the tool parameters will be converted to empty while validating the credentials
+        result = deepcopy(tool_parameters)
+        for parameter in self.entity.parameters or []:
+            if parameter.name in tool_parameters:
+                result[parameter.name] = parameter.type.cast_value(tool_parameters[parameter.name])
+
+        return result
+
+    @abstractmethod
+    def _invoke(
+        self,
+        user_id: str,
+        tool_parameters: dict[str, Any],
+        conversation_id: str | None = None,
+        app_id: str | None = None,
+        message_id: str | None = None,
+    ) -> ToolInvokeMessage | list[ToolInvokeMessage] | Generator[ToolInvokeMessage, None, None]:
+        pass
+
+    def get_runtime_parameters(
+        self,
+        conversation_id: str | None = None,
+        app_id: str | None = None,
+        message_id: str | None = None,
+    ) -> list[ToolParameter]:
+        """
+        get the runtime parameters
+
+        interface for developer to dynamic change the parameters of a tool depends on the variables pool
+
+        :return: the runtime parameters
+        """
+        return self.entity.parameters
+
+    def get_merged_runtime_parameters(
+        self,
+        conversation_id: str | None = None,
+        app_id: str | None = None,
+        message_id: str | None = None,
+    ) -> list[ToolParameter]:
+        """
+        get merged runtime parameters
+
+        :return: merged runtime parameters
+        """
+        parameters = self.entity.parameters
+        parameters = parameters.copy()
+        user_parameters = self.get_runtime_parameters() or []
+        user_parameters = user_parameters.copy()
+
+        # override parameters
+        for parameter in user_parameters:
+            # check if parameter in tool parameters
+            for tool_parameter in parameters:
+                if tool_parameter.name == parameter.name:
+                    # override parameter
+                    tool_parameter.type = parameter.type
+                    tool_parameter.form = parameter.form
+                    tool_parameter.required = parameter.required
+                    tool_parameter.default = parameter.default
+                    tool_parameter.options = parameter.options
+                    tool_parameter.llm_description = parameter.llm_description
+                    break
+            else:
+                # add new parameter
+                parameters.append(parameter)
+
+        return parameters
+
+    def create_image_message(
+        self,
+        image: str,
+    ) -> ToolInvokeMessage:
+        """
+        create an image message
+
+        :param image: the url of the image
+        :return: the image message
+        """
+        return ToolInvokeMessage(
+            type=ToolInvokeMessage.MessageType.IMAGE, message=ToolInvokeMessage.TextMessage(text=image)
+        )
+
+    def create_file_message(self, file: "File") -> ToolInvokeMessage:
+        return ToolInvokeMessage(
+            type=ToolInvokeMessage.MessageType.FILE,
+            message=ToolInvokeMessage.FileMessage(),
+            meta={"file": file},
+        )
+
+    def create_link_message(self, link: str) -> ToolInvokeMessage:
+        """
+        create a link message
+
+        :param link: the url of the link
+        :return: the link message
+        """
+        return ToolInvokeMessage(
+            type=ToolInvokeMessage.MessageType.LINK, message=ToolInvokeMessage.TextMessage(text=link)
+        )
+
+    def create_text_message(self, text: str) -> ToolInvokeMessage:
+        """
+        create a text message
+
+        :param text: the text
+        :return: the text message
+        """
+        return ToolInvokeMessage(
+            type=ToolInvokeMessage.MessageType.TEXT,
+            message=ToolInvokeMessage.TextMessage(text=text),
+        )
+
+    def create_blob_message(self, blob: bytes, meta: dict | None = None) -> ToolInvokeMessage:
+        """
+        create a blob message
+
+        :param blob: the blob
+        :param meta: the meta info of blob object
+        :return: the blob message
+        """
+        return ToolInvokeMessage(
+            type=ToolInvokeMessage.MessageType.BLOB,
+            message=ToolInvokeMessage.BlobMessage(blob=blob),
+            meta=meta,
+        )
+
+    def create_json_message(self, object: dict, suppress_output: bool = False) -> ToolInvokeMessage:
+        """
+        create a json message
+        """
+        return ToolInvokeMessage(
+            type=ToolInvokeMessage.MessageType.JSON,
+            message=ToolInvokeMessage.JsonMessage(json_object=object, suppress_output=suppress_output),
+        )
+
+    def create_variable_message(
+        self, variable_name: str, variable_value: Any, stream: bool = False
+    ) -> ToolInvokeMessage:
+        """
+        create a variable message
+        """
+        return ToolInvokeMessage(
+            type=ToolInvokeMessage.MessageType.VARIABLE,
+            message=ToolInvokeMessage.VariableMessage(
+                variable_name=variable_name, variable_value=variable_value, stream=stream
+            ),
+        )

dify/api/core/tools/__base/tool_provider.py

@@ -0,0 +1,107 @@
+from abc import ABC, abstractmethod
+from copy import deepcopy
+from typing import Any
+
+from core.entities.provider_entities import ProviderConfig
+from core.tools.__base.tool import Tool
+from core.tools.entities.tool_entities import (
+    ToolProviderEntity,
+    ToolProviderType,
+)
+from core.tools.errors import ToolProviderCredentialValidationError
+
+
+class ToolProviderController(ABC):
+    def __init__(self, entity: ToolProviderEntity):
+        self.entity = entity
+
+    def get_credentials_schema(self) -> list[ProviderConfig]:
+        """
+        returns the credentials schema of the provider
+
+        :return: the credentials schema
+        """
+        return deepcopy(self.entity.credentials_schema)
+
+    @abstractmethod
+    def get_tool(self, tool_name: str) -> Tool:
+        """
+        returns a tool that the provider can provide
+
+        :return: tool
+        """
+        pass
+
+    @property
+    def provider_type(self) -> ToolProviderType:
+        """
+        returns the type of the provider
+
+        :return: type of the provider
+        """
+        return ToolProviderType.BUILT_IN
+
+    def validate_credentials_format(self, credentials: dict[str, Any]):
+        """
+        validate the format of the credentials of the provider and set the default value if needed
+
+        :param credentials: the credentials of the tool
+        """
+        credentials_schema = dict[str, ProviderConfig]()
+        if credentials_schema is None:
+            return
+
+        for credential in self.entity.credentials_schema:
+            credentials_schema[credential.name] = credential
+
+        credentials_need_to_validate: dict[str, ProviderConfig] = {}
+        for credential_name in credentials_schema:
+            credentials_need_to_validate[credential_name] = credentials_schema[credential_name]
+
+        for credential_name in credentials:
+            if credential_name not in credentials_need_to_validate:
+                raise ToolProviderCredentialValidationError(
+                    f"credential {credential_name} not found in provider {self.entity.identity.name}"
+                )
+
+            # check type
+            credential_schema = credentials_need_to_validate[credential_name]
+            if not credential_schema.required and credentials[credential_name] is None:
+                continue
+
+            if credential_schema.type in {ProviderConfig.Type.SECRET_INPUT, ProviderConfig.Type.TEXT_INPUT}:
+                if not isinstance(credentials[credential_name], str):
+                    raise ToolProviderCredentialValidationError(f"credential {credential_name} should be string")
+
+            elif credential_schema.type == ProviderConfig.Type.SELECT:
+                if not isinstance(credentials[credential_name], str):
+                    raise ToolProviderCredentialValidationError(f"credential {credential_name} should be string")
+
+                options = credential_schema.options
+                if not isinstance(options, list):
+                    raise ToolProviderCredentialValidationError(f"credential {credential_name} options should be list")
+
+                if credentials[credential_name] not in [x.value for x in options]:
+                    raise ToolProviderCredentialValidationError(
+                        f"credential {credential_name} should be one of {options}"
+                    )
+
+            credentials_need_to_validate.pop(credential_name)
+
+        for credential_name in credentials_need_to_validate:
+            credential_schema = credentials_need_to_validate[credential_name]
+            if credential_schema.required:
+                raise ToolProviderCredentialValidationError(f"credential {credential_name} is required")
+
+            # the credential is not set currently, set the default value if needed
+            if credential_schema.default is not None:
+                default_value = credential_schema.default
+                # parse default value into the correct type
+                if credential_schema.type in {
+                    ProviderConfig.Type.SECRET_INPUT,
+                    ProviderConfig.Type.TEXT_INPUT,
+                    ProviderConfig.Type.SELECT,
+                }:
+                    default_value = str(default_value)
+
+                credentials[credential_name] = default_value

dify/api/core/tools/__base/tool_runtime.py

@@ -0,0 +1,37 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from core.app.entities.app_invoke_entities import InvokeFrom
+from core.plugin.entities.plugin_daemon import CredentialType
+from core.tools.entities.tool_entities import ToolInvokeFrom
+
+
+class ToolRuntime(BaseModel):
+    """
+    Meta data of a tool call processing
+    """
+
+    tenant_id: str
+    tool_id: str | None = None
+    invoke_from: InvokeFrom | None = None
+    tool_invoke_from: ToolInvokeFrom | None = None
+    credentials: dict[str, Any] = Field(default_factory=dict)
+    credential_type: CredentialType = Field(default=CredentialType.API_KEY)
+    runtime_parameters: dict[str, Any] = Field(default_factory=dict)
+
+
+class FakeToolRuntime(ToolRuntime):
+    """
+    Fake tool runtime for testing
+    """
+
+    def __init__(self):
+        super().__init__(
+            tenant_id="fake_tenant_id",
+            tool_id="fake_tool_id",
+            invoke_from=InvokeFrom.DEBUGGER,
+            tool_invoke_from=ToolInvokeFrom.AGENT,
+            credentials={},
+            runtime_parameters={},
+        )