camel-ai 0.2.52__py3-none-any.whl → 0.2.53__py3-none-any.whl

camel/toolkits/aci_toolkit.py

@@ -0,0 +1,456 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import os
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
+
+if TYPE_CHECKING:
+    from aci.types.app_configurations import AppConfiguration
+    from aci.types.apps import AppBasic, AppDetails
+    from aci.types.linked_accounts import LinkedAccount
+
+from camel.logger import get_logger
+from camel.toolkits import FunctionTool
+from camel.toolkits.base import BaseToolkit
+from camel.utils import api_keys_required, dependencies_required
+
+logger = get_logger(__name__)
+
+
+@api_keys_required(
+    [
+        (None, 'ACI_API_KEY'),
+    ]
+)
+class ACIToolkit(BaseToolkit):
+    r"""A toolkit for interacting with the ACI API."""
+
+    @dependencies_required('aci')
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        linked_account_owner_id: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        r"""Initialize the ACI toolkit.
+
+        Args:
+            api_key (Optional[str]): The API key for authentication.
+                (default: :obj: `None`)
+            base_url (Optional[str]): The base URL for the ACI API.
+                (default: :obj: `None`)
+            linked_account_owner_id (Optional[str]): ID of the owner of the
+                linked account, e.g., "johndoe"
+                (default: :obj: `None`)
+            timeout (Optional[float]): Request timeout.
+                (default: :obj: `None`)
+        """
+        from aci import ACI
+
+        super().__init__(timeout)
+
+        self._api_key = api_key or os.getenv("ACI_API_KEY")
+        self._base_url = base_url or os.getenv("ACI_BASE_URL")
+        self.client = ACI(api_key=self._api_key, base_url=self._base_url)
+        self.linked_account_owner_id = linked_account_owner_id
+
+    def search_tool(
+        self,
+        intent: Optional[str] = None,
+        allowed_app_only: bool = True,
+        include_functions: bool = False,
+        categories: Optional[List[str]] = None,
+        limit: Optional[int] = 10,
+        offset: Optional[int] = 0,
+    ) -> Union[List["AppBasic"], str]:
+        r"""Search for apps based on intent.
+
+        Args:
+            intent (Optional[str]): Search results will be sorted by relevance
+                to this intent.
+                (default: :obj: `None`)
+            allowed_app_only (bool): If true, only return apps that
+                are allowed by the agent/accessor, identified by the api key.
+                (default: :obj: `True`)
+            include_functions (bool): If true, include functions
+                (name and description) in the search results.
+                (default: :obj: `False`)
+            categories (Optional[List[str]]): List of categories to filter the
+                search results. Defaults to an empty list.
+                (default: :obj: `None`)
+            limit (Optional[int]): Maximum number of results to return.
+                (default: :obj: `10`)
+            offset (Optional[int]): Offset for pagination.
+                (default: :obj: `0`)
+
+        Returns:
+            Optional[List[AppBasic]]: List of matching apps if successful,
+                error message otherwise.
+        """
+        try:
+            apps = self.client.apps.search(
+                intent=intent,
+                allowed_apps_only=allowed_app_only,
+                include_functions=include_functions,
+                categories=categories,
+                limit=limit,
+                offset=offset,
+            )
+            return apps
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return str(e)
+
+    def list_configured_apps(
+        self,
+        app_names: Optional[List[str]] = None,
+        limit: Optional[int] = 10,
+        offset: Optional[int] = 0,
+    ) -> Union[List["AppConfiguration"], str]:
+        r"""List all configured apps.
+
+        Args:
+            app_names (Optional[List[str]]): List of app names to filter the
+                results. (default: :obj: `None`)
+            limit (Optional[int]): Maximum number of results to return.
+                (default: :obj: `10`)
+            offset (Optional[int]): Offset for pagination. (default: :obj: `0`)
+
+        Returns:
+            Union[List[AppConfiguration], str]: List of configured apps if
+                successful, error message otherwise.
+        """
+        try:
+            apps = self.client.app_configurations.list(
+                app_names=app_names, limit=limit, offset=offset
+            )
+            return apps
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return str(e)
+
+    def configure_app(self, app_name: str) -> Union[Dict, str]:
+        r"""Configure an app with specified authentication type.
+
+        Args:
+            app_name (str): Name of the app to configure.
+
+        Returns:
+            Union[Dict, str]: Configuration result or error message.
+        """
+        from aci.types.enums import SecurityScheme
+
+        try:
+            app_details = self.get_app_details(app_name)
+            if app_details and app_details.security_schemes[0] == "api_key":
+                security_scheme = SecurityScheme.API_KEY
+            elif app_details and app_details.security_schemes[0] == "oauth2":
+                security_scheme = SecurityScheme.OAUTH2
+            else:
+                security_scheme = SecurityScheme.NO_AUTH
+            configuration = self.client.app_configurations.create(
+                app_name=app_name, security_scheme=security_scheme
+            )
+            return configuration
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return str(e)
+
+    def get_app_configuration(
+        self, app_name: str
+    ) -> Union["AppConfiguration", str]:
+        r"""Get app configuration by app name.
+
+        Args:
+            app_name (str): Name of the app to get configuration for.
+
+        Returns:
+            Union[AppConfiguration, str]: App configuration if successful,
+                error message otherwise.
+        """
+        try:
+            app = self.client.app_configurations.get(app_name=app_name)
+            return app
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return str(e)
+
+    def delete_app(self, app_name: str) -> Optional[str]:
+        r"""Delete an app configuration.
+
+        Args:
+            app_name (str): Name of the app to delete.
+
+        Returns:
+            Optional[str]: None if successful, error message otherwise.
+        """
+        try:
+            self.client.app_configurations.delete(app_name=app_name)
+            return None
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return str(e)
+
+    def link_account(
+        self,
+        app_name: str,
+    ) -> Union["LinkedAccount", str]:
+        r"""Link an account to a configured app.
+
+        Args:
+            app_name (str): Name of the app to link the account to.
+
+        Returns:
+            Union[LinkedAccount, str]: LinkedAccount object if successful,
+                error message otherwise.
+        """
+        from aci.types.enums import SecurityScheme
+
+        try:
+            security_scheme = self.client.app_configurations.get(
+                app_name=app_name
+            ).security_scheme
+
+            if security_scheme == SecurityScheme.API_KEY:
+                return self.client.linked_accounts.link(
+                    app_name=app_name,
+                    linked_account_owner_id=self.linked_account_owner_id,
+                    security_scheme=security_scheme,
+                    api_key=self._api_key,
+                )
+            else:
+                return self.client.linked_accounts.link(
+                    app_name=app_name,
+                    linked_account_owner_id=self.linked_account_owner_id,
+                    security_scheme=security_scheme,
+                )
+        except Exception as e:
+            logger.error(f"Error linking account: {e!s}")
+            return str(e)
+
+    def get_app_details(self, app_name: str) -> "AppDetails":
+        r"""Get details of an app.
+
+        Args:
+            app_name (str): Name of the app to get details for.
+
+        Returns:
+            AppDetails: App details.
+        """
+        app = self.client.apps.get(app_name=app_name)
+        return app
+
+    def get_linked_accounts(
+        self, app_name: str
+    ) -> Union[List["LinkedAccount"], str]:
+        r"""List all linked accounts for a specific app.
+
+        Args:
+            app_name (str): Name of the app to get linked accounts for.
+
+        Returns:
+            Union[List[LinkedAccount], str]: List of linked accounts if
+                successful, error message otherwise.
+        """
+        try:
+            accounts = self.client.linked_accounts.list(app_name=app_name)
+            return accounts
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return str(e)
+
+    def enable_linked_account(
+        self, linked_account_id: str
+    ) -> Union["LinkedAccount", str]:
+        r"""Enable a linked account.
+
+        Args:
+            linked_account_id (str): ID of the linked account to enable.
+
+        Returns:
+            Union[LinkedAccount, str]: Linked account if successful, error
+                message otherwise.
+        """
+        try:
+            linked_account = self.client.linked_accounts.enable(
+                linked_account_id=linked_account_id
+            )
+            return linked_account
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return str(e)
+
+    def disable_linked_account(
+        self, linked_account_id: str
+    ) -> Union["LinkedAccount", str]:
+        r"""Disable a linked account.
+
+        Args:
+            linked_account_id (str): ID of the linked account to disable.
+
+        Returns:
+            Union[LinkedAccount, str]: The updated linked account if
+                successful, error message otherwise.
+        """
+        try:
+            linked_account = self.client.linked_accounts.disable(
+                linked_account_id=linked_account_id
+            )
+            return linked_account
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return str(e)
+
+    def delete_linked_account(self, linked_account_id: str) -> str:
+        r"""Delete a linked account.
+
+        Args:
+            linked_account_id (str): ID of the linked account to delete.
+
+        Returns:
+            str: Success message if successful, error message otherwise.
+        """
+        try:
+            self.client.linked_accounts.delete(
+                linked_account_id=linked_account_id
+            )
+            return (
+                f"linked_account_id: {linked_account_id} deleted successfully"
+            )
+        except Exception as e:
+            logger.error(f"Error: {e}")
+            return str(e)
+
+    def function_definition(self, func_name: str) -> Dict:
+        r"""Get the function definition for an app.
+
+        Args:
+            app_name (str): Name of the app to get function definition for
+
+        Returns:
+            Dict: Function definition dictionary.
+        """
+        return self.client.functions.get_definition(func_name)
+
+    def search_function(
+        self,
+        app_names: Optional[List[str]] = None,
+        intent: Optional[str] = None,
+        allowed_apps_only: bool = True,
+        limit: Optional[int] = 10,
+        offset: Optional[int] = 0,
+    ) -> List[Dict]:
+        r"""Search for functions based on intent.
+
+        Args:
+            app_names (Optional[List[str]]): List of app names to filter the
+                search results. (default: :obj: `None`)
+            intent (Optional[str]): The search query/intent.
+                (default: :obj: `None`)
+            allowed_apps_only (bool): If true, only return
+                functions from allowed apps. (default: :obj: `True`)
+            limit (Optional[int]): Maximum number of results to return.
+                (default: :obj: `10`)
+            offset (Optional[int]): Offset for pagination.
+                (default: :obj: `0`)
+
+        Returns:
+            List[Dict]: List of matching functions
+        """
+        return self.client.functions.search(
+            app_names=app_names,
+            intent=intent,
+            allowed_apps_only=allowed_apps_only,
+            limit=limit,
+            offset=offset,
+        )
+
+    def execute_function(
+        self,
+        function_name: str,
+        function_arguments: Dict,
+        linked_account_owner_id: str,
+        allowed_apps_only: bool = False,
+    ) -> Dict:
+        r"""Execute a function call.
+
+        Args:
+            function_name (str): Name of the function to execute.
+            function_arguments (Dict): Arguments to pass to the function.
+            linked_account_owner_id (str): To specify the end-user (account
+                owner) on behalf of whom you want to execute functions
+                You need to first link corresponding account with the same
+                owner id in the ACI dashboard (https://platform.aci.dev).
+            allowed_apps_only (bool): If true, only returns functions/apps
+                that are allowed to be used by the agent/accessor, identified
+                by the api key. (default: :obj: `False`)
+
+        Returns:
+            Dict: Result of the function execution
+        """
+        result = self.client.handle_function_call(
+            function_name,
+            function_arguments,
+            linked_account_owner_id,
+            allowed_apps_only,
+        )
+        return result
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Get a list of tools (functions) available in the configured apps.
+
+        Returns:
+            List[FunctionTool]: List of FunctionTool objects representing
+                available functions
+        """
+        _configure_app = [
+            app.app_name  # type: ignore[union-attr]
+            for app in self.list_configured_apps() or []
+        ]
+        _all_function = self.search_function(app_names=_configure_app)
+        tools = [
+            FunctionTool(self.search_tool),
+            FunctionTool(self.list_configured_apps),
+            FunctionTool(self.configure_app),
+            FunctionTool(self.get_app_configuration),
+            FunctionTool(self.delete_app),
+            FunctionTool(self.link_account),
+            FunctionTool(self.get_app_details),
+            FunctionTool(self.get_linked_accounts),
+            FunctionTool(self.enable_linked_account),
+            FunctionTool(self.disable_linked_account),
+            FunctionTool(self.delete_linked_account),
+            FunctionTool(self.function_definition),
+            FunctionTool(self.search_function),
+        ]
+
+        for function in _all_function:
+            schema = self.client.functions.get_definition(
+                function['function']['name']
+            )
+
+            def dummy_func(*, schema=schema, **kwargs):
+                return self.execute_function(
+                    function_name=schema['function']['name'],
+                    function_arguments=kwargs,
+                    linked_account_owner_id=self.linked_account_owner_id,
+                )
+
+            tool = FunctionTool(
+                func=dummy_func,
+                openai_tool_schema=schema,
+            )
+            tools.append(tool)
+        return tools

camel/toolkits/function_tool.py

@@ -458,9 +458,11 @@ class FunctionTool:
         for param_name in properties.keys():
             param_dict = properties[param_name]
             if "description" not in param_dict:
-                warnings.warn(f"""Parameter description is missing for 
-                            {param_dict}. This may affect the quality of tool 
-                            calling.""")
+                warnings.warn(
+                    f"Parameter description is missing "
+                    f"for {param_dict}. This may affect the "
+                    f"quality of tool calling."
+                )
 
     def get_openai_tool_schema(self) -> Dict[str, Any]:
         r"""Gets the OpenAI tool schema for this function.

camel/toolkits/mcp_toolkit.py

@@ -227,7 +227,7 @@ class MCPClient(BaseToolkit):
 
             func_params.append(param_name)
 
-        async def dynamic_function(**kwargs):
+        async def dynamic_function(**kwargs) -> str:
             r"""Auto-generated function for MCP Tool interaction.
 
             Args:
@@ -351,6 +351,39 @@ class MCPClient(BaseToolkit):
             for mcp_tool in self._mcp_tools
         ]
 
+    def get_text_tools(self) -> str:
+        r"""Returns a string containing the descriptions of the tools
+        in the toolkit.
+
+        Returns:
+            str: A string containing the descriptions of the tools
+                in the toolkit.
+        """
+        return "\n".join(
+            f"tool_name: {tool.name}\n"
+            + f"description: {tool.description or 'No description'}\n"
+            + f"input Schema: {tool.inputSchema}\n"
+            for tool in self._mcp_tools
+        )
+
+    async def call_tool(
+        self, tool_name: str, tool_args: Dict[str, Any]
+    ) -> Any:
+        r"""Calls the specified tool with the provided arguments.
+
+        Args:
+            tool_name (str): Name of the tool to call.
+            tool_args (Dict[str, Any]): Arguments to pass to the tool
+                (default: :obj:`{}`).
+
+        Returns:
+            Any: The result of the tool call.
+        """
+        if self._session is None:
+            raise RuntimeError("Session is not initialized.")
+
+        return await self._session.call_tool(tool_name, tool_args)
+
     @property
     def session(self) -> Optional["ClientSession"]:
         return self._session
@@ -548,3 +581,13 @@ class MCPToolkit(BaseToolkit):
         for server in self.servers:
             all_tools.extend(server.get_tools())
         return all_tools
+
+    def get_text_tools(self) -> str:
+        r"""Returns a string containing the descriptions of the tools
+        in the toolkit.
+
+        Returns:
+            str: A string containing the descriptions of the tools
+                in the toolkit.
+        """
+        return "\n".join(server.get_text_tools() for server in self.servers)

camel/types/__init__.py

@@ -14,6 +14,7 @@
 from .enums import (
     AudioModelType,
     EmbeddingModelType,
+    GeminiEmbeddingTaskType,
     HuggingFaceRepoType,
     ModelPlatformType,
     ModelType,
@@ -75,6 +76,7 @@ __all__ = [
     'UnifiedModelType',
     'ParsedChatCompletion',
     'HuggingFaceRepoType',
+    'GeminiEmbeddingTaskType',
     'NOT_GIVEN',
     'NotGiven',
 ]

camel/types/enums.py

@@ -1202,6 +1202,8 @@ class EmbeddingModelType(Enum):
 
     MISTRAL_EMBED = "mistral-embed"
 
+    GEMINI_EMBEDDING_EXP = "gemini-embedding-exp-03-07"
+
     @property
     def is_openai(self) -> bool:
         r"""Returns whether this type of models is an OpenAI-released model."""
@@ -1230,6 +1232,13 @@ class EmbeddingModelType(Enum):
             EmbeddingModelType.MISTRAL_EMBED,
         }
 
+    @property
+    def is_gemini(self) -> bool:
+        r"""Returns whether this type of models is an Gemini-released model."""
+        return self in {
+            EmbeddingModelType.GEMINI_EMBEDDING_EXP,
+        }
+
     @property
     def output_dim(self) -> int:
         if self in {
@@ -1253,10 +1262,29 @@ class EmbeddingModelType(Enum):
             return 3072
         elif self is EmbeddingModelType.MISTRAL_EMBED:
             return 1024
+        elif self is EmbeddingModelType.GEMINI_EMBEDDING_EXP:
+            return 3072
         else:
             raise ValueError(f"Unknown model type {self}.")
 
 
+class GeminiEmbeddingTaskType(str, Enum):
+    r"""Task types for Gemini embedding models.
+
+    For more information, please refer to:
+    https://ai.google.dev/gemini-api/docs/embeddings#task-types
+    """
+
+    SEMANTIC_SIMILARITY = "SEMANTIC_SIMILARITY"
+    CLASSIFICATION = "CLASSIFICATION"
+    CLUSTERING = "CLUSTERING"
+    RETRIEVAL_DOCUMENT = "RETRIEVAL_DOCUMENT"
+    RETRIEVAL_QUERY = "RETRIEVAL_QUERY"
+    QUESTION_ANSWERING = "QUESTION_ANSWERING"
+    FACT_VERIFICATION = "FACT_VERIFICATION"
+    CODE_RETRIEVAL_QUERY = "CODE_RETRIEVAL_QUERY"
+
+
 class TaskType(Enum):
     AI_SOCIETY = "ai_society"
     CODE = "code"

camel/utils/mcp.py

@@ -17,6 +17,42 @@ from typing import Any, Callable, Optional
 
 
 class MCPServer:
+    r"""Decorator class for registering functions of a class as tools in an MCP
+    (Model Context Protocol) server.
+
+    This class is typically used to wrap a toolkit or service class and
+    automatically register specified methods (or methods derived from
+    `BaseToolkit`) with a FastMCP server.
+
+    Args:
+        function_names (Optional[list[str]]): A list of method names to expose
+            via the MCP server. If not provided and the class is a subclass of
+            `BaseToolkit`, method names will be inferred from the tools
+            returned by `get_tools()`.
+        server_name (Optional[str]): A name for the MCP server. If not
+            provided, the class name of the decorated object is used.
+
+    Example:
+        ```
+        @MCPServer(function_names=["run", "status"])
+        class MyTool:
+            def run(self): ...
+            def status(self): ...
+        ```
+        Or, with a class inheriting from BaseToolkit (no need to specify
+        `function_names`):
+        ```
+        @MCPServer()
+        class MyToolkit(BaseToolkit):
+            ...
+        ```
+
+    Raises:
+        ValueError: If no function names are provided and the class does not
+            inherit from BaseToolkit, or if any specified method is not found
+            or not callable.
+    """
+
     def __init__(
         self,
         function_names: Optional[list[str]] = None,
@@ -26,6 +62,19 @@ class MCPServer:
         self.server_name = server_name
 
     def make_wrapper(self, func: Callable[..., Any]) -> Callable[..., Any]:
+        r"""Wraps a function (sync or async) to preserve its signature and
+        metadata.
+
+        This is used to ensure the MCP server can correctly call and introspect
+        the method.
+
+        Args:
+            func (Callable[..., Any]): The function to wrap.
+
+        Returns:
+            Callable[..., Any]: The wrapped function, with preserved signature
+            and async support.
+        """
         if inspect.iscoroutinefunction(func):
 
             @functools.wraps(func)
@@ -41,6 +90,20 @@ class MCPServer:
         return wrapper
 
     def __call__(self, cls):
+        r"""Decorates a class by injecting an MCP server instance and
+        registering specified methods.
+
+        Args:
+            cls (type): The class being decorated.
+
+        Returns:
+            type: The modified class with MCP integration.
+
+        Raises:
+            ValueError: If function names are missing and the class is not a
+                `BaseToolkit` subclass,
+                or if a specified method cannot be found or is not callable.
+        """
         from mcp.server.fastmcp import FastMCP
 
         from camel.toolkits.base import BaseToolkit