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

camel/__init__.py

@@ -14,7 +14,7 @@
 
 from camel.logger import disable_logging, enable_logging, set_log_level
 
-__version__ = '0.2.52'
+__version__ = '0.2.53'
 
 __all__ = [
     '__version__',

camel/agents/__init__.py

@@ -16,6 +16,7 @@ from .chat_agent import ChatAgent
 from .critic_agent import CriticAgent
 from .embodied_agent import EmbodiedAgent
 from .knowledge_graph_agent import KnowledgeGraphAgent
+from .mcp_agent import MCPAgent
 from .repo_agent import RepoAgent
 from .role_assignment_agent import RoleAssignmentAgent
 from .search_agent import SearchAgent
@@ -42,5 +43,6 @@ __all__ = [
     'RoleAssignmentAgent',
     'SearchAgent',
     'KnowledgeGraphAgent',
+    'MCPAgent',
     'RepoAgent',
 ]

camel/agents/chat_agent.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 import json
 import logging
 import textwrap
+import threading
 import uuid
 from collections import defaultdict
 from datetime import datetime
@@ -151,6 +152,9 @@ class ChatAgent(BaseAgent):
             model calling at each step. (default: :obj:`False`)
         agent_id (str, optional): The ID of the agent. If not provided, a
             random UUID will be generated. (default: :obj:`None`)
+        stop_event (Optional[threading.Event], optional): Event to signal
+            termination of the agent's operation. When set, the agent will
+            terminate its execution. (default: :obj:`None`)
     """
 
     def __init__(
@@ -182,6 +186,7 @@ class ChatAgent(BaseAgent):
         scheduling_strategy: str = "round_robin",
         single_iteration: bool = False,
         agent_id: Optional[str] = None,
+        stop_event: Optional[threading.Event] = None,
     ) -> None:
         # Resolve model backends and set up model manager
         resolved_models = self._resolve_models(model)
@@ -252,6 +257,7 @@ class ChatAgent(BaseAgent):
         self.terminated = False
         self.response_terminators = response_terminators or []
         self.single_iteration = single_iteration
+        self.stop_event = stop_event
 
     def reset(self):
         r"""Resets the :obj:`ChatAgent` to its initial state."""
@@ -757,6 +763,13 @@ class ChatAgent(BaseAgent):
                 self._get_full_tool_schemas(),
             )
 
+            # Terminate Agent if stop_event is set
+            if self.stop_event and self.stop_event.is_set():
+                # Use the _step_token_exceed to terminate the agent with reason
+                return self._step_token_exceed(
+                    num_tokens, tool_call_records, "termination_triggered"
+                )
+
             if tool_call_requests := response.tool_call_requests:
                 # Process all tool calls
                 for tool_call_request in tool_call_requests:
@@ -849,6 +862,13 @@ class ChatAgent(BaseAgent):
                 self._get_full_tool_schemas(),
             )
 
+            # Terminate Agent if stop_event is set
+            if self.stop_event and self.stop_event.is_set():
+                # Use the _step_token_exceed to terminate the agent with reason
+                return self._step_token_exceed(
+                    num_tokens, tool_call_records, "termination_triggered"
+                )
+
             if tool_call_requests := response.tool_call_requests:
                 # Process all tool calls
                 for tool_call_request in tool_call_requests:

camel/agents/mcp_agent.py

@@ -0,0 +1,233 @@
+# ========= 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 json
+import re
+from typing import Optional
+
+from camel.agents import ChatAgent
+from camel.logger import get_logger
+from camel.messages import BaseMessage
+from camel.models import BaseModelBackend
+from camel.prompts import TextPrompt
+from camel.responses import ChatAgentResponse
+from camel.toolkits import MCPToolkit
+from camel.types import RoleType
+
+# AgentOps decorator setting
+try:
+    import os
+
+    if os.getenv("AGENTOPS_API_KEY") is not None:
+        from agentops import track_agent
+    else:
+        raise ImportError
+except (ImportError, AttributeError):
+    from camel.utils import track_agent
+
+logger = get_logger(__name__)
+
+SYS_MSG_CONTENT = """
+You are a helpful assistant, and you prefer to use tools provided by the user 
+to solve problems.
+Using a tool, you will tell the user `server_idx`, `tool_name` and 
+`tool_args` formatted in JSON as following:
+```json
+{
+    "server_idx": idx,
+    "tool_name": "tool_name",
+    "tool_args": {
+        "arg1": value1,
+        "arg2": value2,
+        ...
+    }
+}
+```
+For example:
+```json
+{
+    "server_idx": 0,
+    "tool_name": "multiply",
+    "tool_args": {"a": 5, "b": 50}
+}
+```
+Otherwise, you should respond to the user directly.
+"""
+
+
+TOOLS_PROMPT = """
+## Available Tools:
+
+{tools}
+"""
+
+FINAL_RESPONSE_PROMPT = """
+The result `{results}` is provided by tools you proposed.
+Please answer me according to the result directly.
+"""
+
+
+@track_agent(name="MCPAgent")
+class MCPAgent(ChatAgent):
+    def __init__(
+        self,
+        config_path: str,
+        model: Optional[BaseModelBackend] = None,
+        function_calling_available: bool = False,
+    ) -> None:
+        r"""A class for the MCP agent that assists using MCP tools.
+
+        Args:
+            config_path (str): Path to the MCP configuration file.
+            model (Optional[BaseModelBackend]): Model backend for the agent.
+                (default: :obj:`None`)
+            function_calling_available (bool): Flag indicating whether the
+                model is equipped with the function calling ability.
+                (default: :obj:`False`)
+        """
+        if function_calling_available:
+            sys_msg_content = "You are a helpful assistant, and you prefer "
+            "to use tools provided by the user to solve problems."
+        else:
+            sys_msg_content = SYS_MSG_CONTENT
+
+        system_message = BaseMessage(
+            role_name="MCPRouter",
+            role_type=RoleType.ASSISTANT,
+            meta_dict=None,
+            content=sys_msg_content,
+        )
+
+        super().__init__(system_message, model=model)
+
+        self._mcp_toolkit = MCPToolkit(config_path=config_path)
+        self._function_calling_available = function_calling_available
+        self._text_tools = None
+
+    async def connect(self):
+        r"""Explicitly connect to all MCP servers."""
+        await self._mcp_toolkit.connect()
+
+    async def close(self):
+        r"""Explicitly disconnect from all MCP servers."""
+        await self._mcp_toolkit.disconnect()
+
+    def add_mcp_tools(self):
+        r"""Get the MCP tools and wrap into the models"""
+
+        if not self._mcp_toolkit.is_connected():
+            raise RuntimeError("The MCP server is not connected")
+
+        prompt = TextPrompt(TOOLS_PROMPT)
+        self._text_tools = prompt.format(
+            tools=self._mcp_toolkit.get_text_tools()
+        )
+        if self._function_calling_available:
+            tools = self._mcp_toolkit.get_tools()
+            for tool in tools:
+                self.add_tool(tool)
+
+    async def run(
+        self,
+        prompt: str,
+    ) -> ChatAgentResponse:
+        r"""Run the agent to interact with the MCP tools.
+
+        Args:
+            prompt (str): The user's input prompt or query to be processed by
+                the agent.
+
+        Returns:
+            ChatAgentResponse: The agent's response after processing the
+                prompt and potentially executing MCP tool calls.
+
+        Raises:
+            RuntimeError: If the MCP server is not connected when attempting
+                to run.
+        """
+
+        if not self._mcp_toolkit.is_connected():
+            raise RuntimeError("The MCP server is not connected")
+
+        if self._function_calling_available:
+            response = await self.astep(prompt)
+            return response
+        else:
+            task = f"## Task:\n  {prompt}"
+            response = await self.astep(str(self._text_tools) + task)
+            content = response.msgs[0].content.lower()
+
+            tool_calls = []
+            while "```json" in content:
+                json_match = re.search(r'```json', content)
+                if not json_match:
+                    break
+                json_start = json_match.span()[1]
+
+                end_match = re.search(r'```', content[json_start:])
+                if not end_match:
+                    break
+                json_end = end_match.span()[0] + json_start
+
+                tool_json = content[json_start:json_end].strip('\n')
+                try:
+                    tool_calls.append(json.loads(tool_json))
+                except json.JSONDecodeError:
+                    logger.warning(f"Failed to parse JSON: {tool_json}")
+                    continue
+                content = content[json_end:]
+
+            if not tool_calls:
+                return response
+            else:
+                tools_results = []
+                for tool_call in tool_calls:
+                    server_idx = tool_call['server_idx']
+                    tool_name = tool_call['tool_name']
+                    tool_args = tool_call['tool_args']
+                    server = self._mcp_toolkit.servers[server_idx]
+                    result = await server.call_tool(tool_name, tool_args)
+                    tools_results.append({tool_name: result.content[0].text})
+                results = json.dumps(tools_results)
+                final_prompt = TextPrompt(FINAL_RESPONSE_PROMPT).format(
+                    results=results
+                )
+                response = await self.astep(final_prompt)
+                return response
+
+    @classmethod
+    async def create(
+        cls,
+        config_path: str,
+        model: Optional[BaseModelBackend] = None,
+        function_calling_available: bool = False,
+    ) -> "MCPAgent":
+        r"""Factory method to create and initialize an MCPAgent.
+
+        Args:
+            config_path (str): Path to the MCP configuration file that contains
+                server settings and other configuration parameters.
+            model (Optional[BaseModelBackend]): Model backend for the agent.
+                If None, the default model will be used. (default: :obj:`None`)
+            function_calling_available (bool): Flag indicating whether the
+                model is equipped with function calling ability. This affects
+                the system message content. (default: :obj:`False`)
+
+        Returns:
+            MCPAgent: A fully initialized MCPAgent instance ready for use.
+        """
+        agent = cls(config_path, model, function_calling_available)
+        await agent.connect()
+        agent.add_mcp_tools()
+        return agent

camel/embeddings/__init__.py

@@ -13,6 +13,7 @@
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 from .azure_embedding import AzureEmbedding
 from .base import BaseEmbedding
+from .gemini_embedding import GeminiEmbedding
 from .jina_embedding import JinaEmbedding
 from .mistral_embedding import MistralEmbedding
 from .openai_compatible_embedding import OpenAICompatibleEmbedding
@@ -31,4 +32,5 @@ __all__ = [
     "OpenAICompatibleEmbedding",
     "JinaEmbedding",
     "TogetherEmbedding",
+    "GeminiEmbedding",
 ]

camel/embeddings/gemini_embedding.py

@@ -0,0 +1,115 @@
+# ========= 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. =========
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from camel.embeddings.base import BaseEmbedding
+from camel.types import EmbeddingModelType, GeminiEmbeddingTaskType
+from camel.utils import api_keys_required
+
+
+class GeminiEmbedding(BaseEmbedding[str]):
+    r"""Provides text embedding functionalities using Google's Gemini models.
+
+    Args:
+        model_type (EmbeddingModelType, optional): The model type to be
+            used for text embeddings.
+            (default: :obj:`GEMINI_EMBEDDING_EXP`)
+        api_key (str, optional): The API key for authenticating with the
+            Gemini service. (default: :obj:`None`)
+        dimensions (int, optional): The text embedding output dimensions.
+            (default: :obj:`None`)
+        task_type (GeminiEmbeddingTaskType, optional): The task type for which
+            to optimize the embeddings. (default: :obj:`None`)
+
+    Raises:
+        RuntimeError: If an unsupported model type is specified.
+    """
+
+    @api_keys_required(
+        [
+            ("api_key", 'GEMINI_API_KEY'),
+        ]
+    )
+    def __init__(
+        self,
+        model_type: EmbeddingModelType = (
+            EmbeddingModelType.GEMINI_EMBEDDING_EXP
+        ),
+        api_key: Optional[str] = None,
+        dimensions: Optional[int] = None,
+        task_type: Optional[GeminiEmbeddingTaskType] = None,
+    ) -> None:
+        from google import genai
+
+        if not model_type.is_gemini:
+            raise ValueError("Invalid Gemini embedding model type.")
+
+        self.model_type = model_type
+        if dimensions is None:
+            self.output_dim = model_type.output_dim
+        else:
+            assert isinstance(dimensions, int)
+            self.output_dim = dimensions
+
+        self._api_key = api_key or os.environ.get("GEMINI_API_KEY")
+        self._task_type = task_type
+
+        # Initialize Gemini client
+        self._client = genai.Client(api_key=self._api_key)
+
+    def embed_list(
+        self,
+        objs: list[str],
+        **kwargs: Any,
+    ) -> list[list[float]]:
+        r"""Generates embeddings for the given texts.
+
+        Args:
+            objs (list[str]): The texts for which to generate the embeddings.
+            **kwargs (Any): Extra kwargs passed to the embedding API.
+
+        Returns:
+            list[list[float]]: A list that represents the generated embedding
+                as a list of floating-point numbers.
+        """
+        from google.genai import types
+
+        # Create embedding config if task_type is specified
+        embed_config = None
+        if self._task_type:
+            embed_config = types.EmbedContentConfig(
+                task_type=self._task_type.value
+            )
+
+        # Process each text separately since Gemini API
+        # expects single content item
+        responses = self._client.models.embed_content(
+            model=self.model_type.value,
+            contents=objs,  # type: ignore[arg-type]
+            config=embed_config,
+            **kwargs,
+        )
+
+        return [response.values for response in responses.embeddings]  # type: ignore[misc,union-attr]
+
+    def get_output_dim(self) -> int:
+        r"""Returns the output dimension of the embeddings.
+
+        Returns:
+            int: The dimensionality of the embedding for the current model.
+        """
+        return self.output_dim

camel/embeddings/openai_embedding.py

@@ -14,7 +14,7 @@
 from __future__ import annotations
 
 import os
-from typing import Any
+from typing import Any, Optional, Union
 
 from openai import OpenAI
 
@@ -27,15 +27,15 @@ class OpenAIEmbedding(BaseEmbedding[str]):
     r"""Provides text embedding functionalities using OpenAI's models.
 
     Args:
-        model_type (EmbeddingModelType, optional): The model type to be
-            used for text embeddings.
+        model_type (EmbeddingModelType): The model type to be used for text
+            embeddings.
             (default: :obj:`TEXT_EMBEDDING_3_SMALL`)
-        url (Optional[str], optional): The url to the OpenAI service.
+        url (Optional[str]): The url to the OpenAI service.
             (default: :obj:`None`)
-        api_key (str, optional): The API key for authenticating with the
-            OpenAI service. (default: :obj:`None`)
-        dimensions (int, optional): The text embedding output dimensions.
-            (default: :obj:`NOT_GIVEN`)
+        api_key (Optional[str]): The API key for authenticating with
+            the OpenAI service. (default: :obj:`None`)
+        dimensions (Union[int, NotGiven]): The text embedding output
+            dimensions. (default: :obj:`NOT_GIVEN`)
 
     Raises:
         RuntimeError: If an unsupported model type is specified.
@@ -51,9 +51,9 @@ class OpenAIEmbedding(BaseEmbedding[str]):
         model_type: EmbeddingModelType = (
             EmbeddingModelType.TEXT_EMBEDDING_3_SMALL
         ),
-        url: str | None = None,
-        api_key: str | None = None,
-        dimensions: int | NotGiven = NOT_GIVEN,
+        url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        dimensions: Union[int, NotGiven] = NOT_GIVEN,
     ) -> None:
         if not model_type.is_openai:
             raise ValueError("Invalid OpenAI embedding model type.")

camel/embeddings/together_embedding.py

@@ -27,7 +27,7 @@ class TogetherEmbedding(BaseEmbedding[str]):
     r"""Provides text embedding functionalities using Together AI's models.
 
     Args:
-        model_name (str, optional): The model name to be used for text
+        model_type (str, optional): The model name to be used for text
             embeddings.
             (default: :obj:`togethercomputer/m2-bert-80M-8k-retrieval`)
         api_key (str, optional): The API key for authenticating with the
@@ -44,17 +44,17 @@ class TogetherEmbedding(BaseEmbedding[str]):
     @api_keys_required([("api_key", 'TOGETHER_API_KEY')])
     def __init__(
         self,
-        model_name: str = "togethercomputer/m2-bert-80M-8k-retrieval",
+        model_type: str = "togethercomputer/m2-bert-80M-8k-retrieval",
         api_key: Optional[str] = None,
         dimensions: Optional[int] = None,
     ) -> None:
-        if not isinstance(model_name, str) or not model_name.strip():
+        if not isinstance(model_type, str) or not model_type.strip():
             raise ValueError("Model name must be a non-empty string")
 
         if dimensions is not None and dimensions <= 0:
             raise ValueError("Dimensions must be a positive integer")
 
-        self.model_name = model_name
+        self.model_type = model_type
         self._api_key = api_key or os.environ.get("TOGETHER_API_KEY")
         self.output_dim = dimensions
 
@@ -91,7 +91,7 @@ class TogetherEmbedding(BaseEmbedding[str]):
         try:
             response = self.client.embeddings.create(
                 input=objs,
-                model=self.model_name,
+                model=self.model_type,
                 **kwargs,
             )
 
@@ -100,7 +100,7 @@ class TogetherEmbedding(BaseEmbedding[str]):
                 self.output_dim = len(response.data[0].embedding)
                 logger.debug(
                     f"Set output dimension to {self.output_dim} for model "
-                    f"{self.model_name}"
+                    f"{self.model_type}"
                 )
 
             return [data.embedding for data in response.data]
@@ -130,7 +130,7 @@ class TogetherEmbedding(BaseEmbedding[str]):
         if self.output_dim is None:
             raise ValueError(
                 "Failed to determine embedding dimension for model: "
-                f"{self.model_name}"
+                f"{self.model_type}"
             )
 
         return self.output_dim

camel/models/model_factory.py

@@ -71,6 +71,7 @@ class ModelFactory:
         api_key: Optional[str] = None,
         url: Optional[str] = None,
         timeout: Optional[float] = None,
+        **kwargs,
     ) -> BaseModelBackend:
         r"""Creates an instance of `BaseModelBackend` of the specified type.
 
@@ -94,6 +95,10 @@ class ModelFactory:
                 (default: :obj:`None`)
             timeout (Optional[float], optional): The timeout value in seconds
                 for API calls. (default: :obj:`None`)
+            **kwargs: Additional model-specific parameters that will be passed
+                to the model constructor. For example, Azure OpenAI models may
+                require `api_version`, `azure_deployment_name`,
+                `azure_ad_token_provider`, and `azure_ad_token`.
 
         Returns:
             BaseModelBackend: The initialized backend.
@@ -202,6 +207,7 @@ class ModelFactory:
             url=url,
             token_counter=token_counter,
             timeout=timeout,
+            **kwargs,
         )
 
     @classmethod

camel/responses/agent_responses.py

@@ -39,8 +39,5 @@ class ChatAgentResponse(BaseModel):
     @property
     def msg(self):
         if len(self.msgs) != 1:
-            raise RuntimeError(
-                "Property msg is only available "
-                "for a single message in msgs."
-            )
+            return None
         return self.msgs[0]

camel/societies/role_playing.py

@@ -12,6 +12,7 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import logging
+import threading
 from typing import Dict, List, Optional, Sequence, Tuple, Union
 
 from camel.agents import (
@@ -77,6 +78,9 @@ class RolePlaying:
             task specify meta dict with. (default: :obj:`None`)
         output_language (str, optional): The language to be output by the
             agents. (default: :obj:`None`)
+        stop_event (Optional[threading.Event], optional): Event to signal
+            termination of the agent's operation. When set, the agent will
+            terminate its execution. (default: :obj:`None`)
     """
 
     def __init__(
@@ -101,6 +105,7 @@ class RolePlaying:
         extend_sys_msg_meta_dicts: Optional[List[Dict]] = None,
         extend_task_specify_meta_dict: Optional[Dict] = None,
         output_language: Optional[str] = None,
+        stop_event: Optional[threading.Event] = None,
     ) -> None:
         if model is not None:
             logger.warning(
@@ -156,6 +161,7 @@ class RolePlaying:
             assistant_agent_kwargs=assistant_agent_kwargs,
             user_agent_kwargs=user_agent_kwargs,
             output_language=output_language,
+            stop_event=stop_event,
         )
         self.critic: Optional[Union[CriticAgent, Human]] = None
         self.critic_sys_msg: Optional[BaseMessage] = None
@@ -316,6 +322,7 @@ class RolePlaying:
         assistant_agent_kwargs: Optional[Dict] = None,
         user_agent_kwargs: Optional[Dict] = None,
         output_language: Optional[str] = None,
+        stop_event: Optional[threading.Event] = None,
     ) -> None:
         r"""Initialize assistant and user agents with their system messages.
 
@@ -330,6 +337,9 @@ class RolePlaying:
                 pass to the user agent. (default: :obj:`None`)
             output_language (str, optional): The language to be output by the
                 agents. (default: :obj:`None`)
+            stop_event (Optional[threading.Event], optional): Event to signal
+                termination of the agent's operation. When set, the agent will
+                terminate its execution. (default: :obj:`None`)
         """
         if self.model is not None:
             if assistant_agent_kwargs is None:
@@ -344,6 +354,7 @@ class RolePlaying:
         self.assistant_agent = ChatAgent(
             init_assistant_sys_msg,
             output_language=output_language,
+            stop_event=stop_event,
             **(assistant_agent_kwargs or {}),
         )
         self.assistant_sys_msg = self.assistant_agent.system_message
@@ -351,6 +362,7 @@ class RolePlaying:
         self.user_agent = ChatAgent(
             init_user_sys_msg,
             output_language=output_language,
+            stop_event=stop_event,
             **(user_agent_kwargs or {}),
         )
         self.user_sys_msg = self.user_agent.system_message

camel/toolkits/__init__.py

@@ -69,6 +69,7 @@ from .openai_agent_toolkit import OpenAIAgentToolkit
 from .searxng_toolkit import SearxNGToolkit
 from .jina_reranker_toolkit import JinaRerankerToolkit
 from .klavis_toolkit import KlavisToolkit
+from .aci_toolkit import ACIToolkit
 
 
 __all__ = [
@@ -126,4 +127,5 @@ __all__ = [
     'SearxNGToolkit',
     'JinaRerankerToolkit',
     'KlavisToolkit',
+    'ACIToolkit',
 ]