camel-ai 0.2.71a2__py3-none-any.whl → 0.2.71a4__py3-none-any.whl

camel/toolkits/terminal_toolkit.py

@@ -134,7 +134,14 @@ class TerminalToolkit(BaseToolkit):
         logger.info(f"Terminal output will be redirected to: {self.log_file}")
 
         def file_update(output: str):
+            import sys
+
             try:
+                # For macOS/Linux file-based mode, also write to stdout
+                # to provide real-time feedback in the user's terminal.
+                sys.stdout.write(output)
+                sys.stdout.flush()
+
                 # Initialize file on first write
                 if not self._file_initialized:
                     with open(self.log_file, "w") as f:
@@ -147,9 +154,6 @@ class TerminalToolkit(BaseToolkit):
                 # Directly append to the end of the file
                 with open(self.log_file, "a") as f:
                     f.write(output)
-                    # If the output does not end with a newline, add one
-                    if output and not output.endswith('\n'):
-                        f.write('\n')
                 # Ensure the agent also receives the output
                 self.agent_queue.put(output)
             except Exception as e:
@@ -334,17 +338,24 @@ class TerminalToolkit(BaseToolkit):
     def file_find_in_content(
         self, file: str, regex: str, sudo: bool = False
     ) -> str:
-        r"""Search for matching text within file content.
+        r"""Search for text within a file's content using a regular expression.
+
+        This function is useful for finding specific patterns or lines of text
+        within a given file. It uses `grep` on Unix-like systems and `findstr`
+        on Windows.
 
         Args:
-            file (str): Absolute path of the file to search within.
-            regex (str): Regular expression pattern to match.
-            sudo (bool, optional): Whether to use sudo privileges. Defaults to
-                False. Note: Using sudo requires the process to have
-                appropriate permissions.
+            file (str): The absolute path of the file to search within.
+            regex (str): The regular expression pattern to match.
+            sudo (bool, optional): Whether to use sudo privileges for the
+                search. Defaults to False. Note: Using sudo requires the
+                process to have appropriate permissions.
+                (default: :obj:`False`)
 
         Returns:
-            str: Matching content found in the file.
+            str: The matching content found in the file. If no matches are
+                found, an empty string is returned. Returns an error message
+                if the file does not exist or another error occurs.
         """
 
         if not os.path.exists(file):
@@ -376,14 +387,21 @@ class TerminalToolkit(BaseToolkit):
             return f"Error: {e!s}"
 
     def file_find_by_name(self, path: str, glob: str) -> str:
-        r"""Find files by name pattern in specified directory.
+        r"""Find files by name in a specified directory using a glob pattern.
+
+        This function recursively searches for files matching a given name or
+        pattern within a directory. It uses `find` on Unix-like systems and
+        `dir` on Windows.
 
         Args:
-            path (str): Absolute path of directory to search.
-            glob (str): Filename pattern using glob syntax wildcards.
+            path (str): The absolute path of the directory to search in.
+            glob (str): The filename pattern to search for, using glob syntax
+                (e.g., "*.py", "data*").
 
         Returns:
-            str: List of files matching the pattern.
+            str: A newline-separated string containing the paths of the files
+                that match the pattern. Returns an error message if the
+                directory does not exist or another error occurs.
         """
         if not os.path.exists(path):
             return f"Directory not found: {path}"
@@ -649,18 +667,37 @@ class TerminalToolkit(BaseToolkit):
 
         return True, command
 
-    def shell_exec(self, id: str, command: str) -> str:
-        r"""Execute commands. This can be used to execute various commands,
-        such as writing code, executing code, and running commands.
+    def shell_exec(
+        self, id: str, command: str, interactive: bool = False
+    ) -> str:
+        r"""Executes a shell command in a specified session.
+
+        This function creates and manages shell sessions to execute commands,
+        simulating a real terminal. It can run commands in both non-interactive
+        (capturing output) and interactive modes. Each session is identified by
+        a unique ID. If a session with the given ID does not exist, it will be
+        created.
 
         Args:
-            id (str): Unique identifier of the target shell session.
-            command (str): Shell command to execute.
+            id (str): A unique identifier for the shell session. This is used
+                to manage multiple concurrent shell processes.
+            command (str): The shell command to be executed.
+            interactive (bool, optional): If `True`, the command runs in
+                interactive mode, connecting it to the terminal's standard
+                input. This is useful for commands that require user input,
+                like `ssh`. Defaults to `False`. Interactive mode is only
+                supported on macOS and Linux. (default: :obj:`False`)
 
         Returns:
-            str: Output of the command execution or error message.
+            str: The standard output and standard error from the command. If an
+                error occurs during execution, a descriptive error message is
+                returned.
+
+        Note:
+            When `interactive` is set to `True`, this function may block if the
+            command requires input. In safe mode, some commands that are
+            considered dangerous are restricted.
         """
-        # Command execution must be within the working directory
         error_msg = self._enforce_working_dir_for_execution(self.working_dir)
         if error_msg:
             return error_msg
@@ -673,7 +710,6 @@ class TerminalToolkit(BaseToolkit):
                 return f"Command rejected: {sanitized_command}"
             command = sanitized_command
 
-        # If the session does not exist, create a new session
         if id not in self.shell_sessions:
             self.shell_sessions[id] = {
                 "process": None,
@@ -682,7 +718,6 @@ class TerminalToolkit(BaseToolkit):
             }
 
         try:
-            # First, log the command to be executed
             self._update_terminal_output(f"\n$ {command}\n")
 
             if command.startswith('python') or command.startswith('pip'):
@@ -706,42 +741,130 @@ class TerminalToolkit(BaseToolkit):
                 elif command.startswith('pip'):
                     command = command.replace('pip', pip_path, 1)
 
-            proc = subprocess.Popen(
-                command,
-                shell=True,
-                cwd=self.working_dir,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-                stdin=subprocess.PIPE,
-                text=True,
-                bufsize=1,
-                universal_newlines=True,
-                env=os.environ.copy(),
-            )
+            if not interactive:
+                proc = subprocess.Popen(
+                    command,
+                    shell=True,
+                    cwd=self.working_dir,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    stdin=subprocess.PIPE,
+                    text=True,
+                    bufsize=1,
+                    universal_newlines=True,
+                    env=os.environ.copy(),
+                )
+
+                self.shell_sessions[id]["process"] = proc
+                self.shell_sessions[id]["running"] = True
+                stdout, stderr = proc.communicate()
+                output = stdout or ""
+                if stderr:
+                    output += f"\nStderr Output:\n{stderr}"
+                self.shell_sessions[id]["output"] = output
+                self._update_terminal_output(output + "\n")
+                return output
+
+            # Interactive mode with real-time streaming via PTY
+            if self.os_type not in ['Darwin', 'Linux']:
+                return (
+                    "Interactive mode is not supported on "
+                    f"{self.os_type} due to PTY limitations."
+                )
+
+            import pty
+            import select
+            import sys
+            import termios
+            import tty
+
+            # Fork a new process with a PTY
+            pid, master_fd = pty.fork()
+
+            if pid == 0:  # Child process
+                # Execute the command in the child process
+                try:
+                    import shlex
+
+                    parts = shlex.split(command)
+                    if not parts:
+                        logger.error("Error: Empty command")
+                        os._exit(1)
+
+                    os.chdir(self.working_dir)
+                    os.execvp(parts[0], parts)
+                except (ValueError, IndexError, OSError) as e:
+                    logger.error(f"Command execution error: {e}")
+                    os._exit(127)
+                except Exception as e:
+                    logger.error(f"Unexpected error: {e}")
+                    os._exit(1)
 
-            # Store the process and mark it as running
-            self.shell_sessions[id]["process"] = proc
+            # Parent process
+            self.shell_sessions[id]["process_id"] = pid
             self.shell_sessions[id]["running"] = True
+            output_lines: List[str] = []
+            original_settings = termios.tcgetattr(sys.stdin)
 
-            # Get output
-            stdout, stderr = proc.communicate()
+            try:
+                tty.setraw(sys.stdin.fileno())
 
-            output = stdout or ""
-            if stderr:
-                output += f"\nStderr Output:\n{stderr}"
+                while True:
+                    # Check if the child process has exited
+                    try:
+                        wait_pid, status = os.waitpid(pid, os.WNOHANG)
+                        if wait_pid == pid:
+                            self.shell_sessions[id]["running"] = False
+                            break
+                    except OSError:
+                        # Process already reaped
+                        self.shell_sessions[id]["running"] = False
+                        break
+
+                    # Use select to wait for I/O on stdin or master PTY
+                    r, _, _ = select.select(
+                        [sys.stdin, master_fd], [], [], 0.1
+                    )
 
-            # Update session information and terminal
-            self.shell_sessions[id]["output"] = output
-            self._update_terminal_output(output + "\n")
+                    if master_fd in r:
+                        try:
+                            data = os.read(master_fd, 1024)
+                            if not data:
+                                break
+                            decoded_data = data.decode(
+                                'utf-8', errors='replace'
+                            )
+                            # Echo to user's terminal and log
+                            self._update_terminal_output(decoded_data)
+                            output_lines.append(decoded_data)
+                        except OSError:
+                            break  # PTY has been closed
 
-            return output
+                    if sys.stdin in r:
+                        try:
+                            user_input = os.read(sys.stdin.fileno(), 1024)
+                            if not user_input:
+                                break
+                            os.write(master_fd, user_input)
+                        except OSError:
+                            break
+
+            finally:
+                if original_settings is not None:
+                    termios.tcsetattr(
+                        sys.stdin, termios.TCSADRAIN, original_settings
+                    )
+                if master_fd:
+                    os.close(master_fd)
+
+            final_output = "".join(output_lines)
+            self.shell_sessions[id]["output"] = final_output
+            return final_output
 
         except Exception as e:
             error_msg = f"Command execution error: {e!s}"
             logger.error(error_msg)
             self._update_terminal_output(f"\nError: {error_msg}\n")
-
-            # More detailed error information
             import traceback
 
             detailed_error = traceback.format_exc()
@@ -751,13 +874,19 @@ class TerminalToolkit(BaseToolkit):
             )
 
     def shell_view(self, id: str) -> str:
-        r"""View the content of a specified shell session.
+        r"""View the full output history of a specified shell session.
+
+        Retrieves the accumulated output (both stdout and stderr) generated by
+        commands in the specified session since its creation. This is useful
+        for checking the complete history of a session, especially after a
+        command has finished execution.
 
         Args:
-            id (str): Unique identifier of the target shell session.
+            id (str): The unique identifier of the shell session to view.
 
         Returns:
-            str: Current output content of the shell session.
+            str: The complete output history of the shell session. Returns an
+                error message if the session is not found.
         """
         if id not in self.shell_sessions:
             return f"Shell session not found: {id}"
@@ -788,16 +917,22 @@ class TerminalToolkit(BaseToolkit):
             return f"Error: {e!s}"
 
     def shell_wait(self, id: str, seconds: Optional[int] = None) -> str:
-        r"""Wait for the running process in a specified shell session to
-        return.
+        r"""Wait for a command to finish in a specified shell session.
+
+        Blocks execution and waits for the running process in a shell session
+        to complete. This is useful for ensuring a long-running command has
+        finished before proceeding.
 
         Args:
-            id (str): Unique identifier of the target shell session.
-            seconds (Optional[int], optional): Wait duration in seconds.
-                If None, wait indefinitely. Defaults to None.
+            id (str): The unique identifier of the target shell session.
+            seconds (Optional[int], optional): The maximum time to wait, in
+                seconds. If `None`, it waits indefinitely.
+                (default: :obj:`None`)
 
         Returns:
-            str: Final output content after waiting.
+            str: A message indicating that the process has completed, including
+                the final output. If the process times out, it returns a
+                timeout message.
         """
         if id not in self.shell_sessions:
             return f"Shell session not found: {id}"
@@ -857,13 +992,20 @@ class TerminalToolkit(BaseToolkit):
     ) -> str:
         r"""Write input to a running process in a specified shell session.
 
+        Sends a string of text to the standard input of a running process.
+        This is useful for interacting with commands that require input. This
+        function cannot be used with a command that was started in
+        interactive mode.
+
         Args:
-            id (str): Unique identifier of the target shell session.
-            input (str): Input content to write to the process.
-            press_enter (bool): Whether to press Enter key after input.
+            id (str): The unique identifier of the target shell session.
+            input (str): The text to write to the process's stdin.
+            press_enter (bool): If `True`, a newline character (`\n`) is
+                appended to the input, simulating pressing the Enter key.
 
         Returns:
-            str: Status message indicating whether the input was sent.
+            str: A status message indicating whether the input was sent, or an
+                error message if the operation fails.
         """
         if id not in self.shell_sessions:
             return f"Shell session not found: {id}"
@@ -899,11 +1041,17 @@ class TerminalToolkit(BaseToolkit):
     def shell_kill_process(self, id: str) -> str:
         r"""Terminate a running process in a specified shell session.
 
+        Forcibly stops a command that is currently running in a shell session.
+        This is useful for ending processes that are stuck, running too long,
+        or need to be cancelled.
+
         Args:
-            id (str): Unique identifier of the target shell session.
+            id (str): The unique identifier of the shell session containing the
+                process to be terminated.
 
         Returns:
-            str: Status message indicating whether the process was terminated.
+            str: A status message indicating that the process has been
+                terminated, or an error message if the operation fails.
         """
         if id not in self.shell_sessions:
             return f"Shell session not found: {id}"
@@ -939,22 +1087,24 @@ class TerminalToolkit(BaseToolkit):
             return f"Error killing process: {e!s}"
 
     def ask_user_for_help(self, id: str) -> str:
-        r"""Pauses agent execution to ask a human for help in the terminal.
+        r"""Pause the agent and ask a human for help with a command.
 
-        This function should be called when an agent is stuck or needs
-        assistance with a task that requires manual intervention (e.g.,
-        solving a CAPTCHA or complex debugging). The human will take over the
-        specified terminal session to execute commands and then return control
-        to the agent.
+        This function should be used when the agent is stuck and requires
+        manual intervention, such as solving a CAPTCHA or debugging a complex
+        issue. It pauses the agent's execution and allows a human to take
+        control of a specified shell session. The human can execute one
+        command to resolve the issue, and then control is returned to the
+        agent.
 
         Args:
-            id (str): Identifier of the shell session for the human to
-                interact with. If the session does not yet exist, it will be
-                created automatically.
+            id (str): The identifier of the shell session for the human to
+                interact with. If the session does not exist, it will be
+                created.
 
         Returns:
             str: A status message indicating that the human has finished,
-                including the number of commands executed.
+                including the number of commands executed. If the takeover
+                times out or fails, an error message is returned.
         """
         # Input validation
         if not id or not isinstance(id, str):

camel/types/agents/tool_calling_record.py

@@ -11,7 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
-from typing import Any, Dict
+from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel
 
@@ -24,12 +24,15 @@ class ToolCallingRecord(BaseModel):
         args (Dict[str, Any]): The dictionary of arguments passed to the tool.
         result (Any): The execution result of calling this tool.
         tool_call_id (str): The ID of the tool call, if available.
+        images (Optional[List[str]]): List of base64-encoded images returned
+            by the tool, if any.
     """
 
     tool_name: str
     args: Dict[str, Any]
     result: Any
     tool_call_id: str
+    images: Optional[List[str]] = None
 
     def __str__(self) -> str:
         r"""Overridden version of the string function.

camel/types/enums.py

@@ -388,14 +388,14 @@ class ModelType(UnifiedModelType, Enum):
     WATSONX_MISTRAL_LARGE = "mistralai/mistral-large"
 
     # Qianfan models
-    QIANFAN_ERNIE_X1_TURBO_32K = "ernie-x1-turbo-32k"
-    QIANFAN_ERNIE_X1_32K = "ernie-x1-32k"
-    QIANFAN_ERNIE_X1_32K_PREVIEW = "ernie-x1-32k-preview"
-    QIANFAN_ERNIE_4_5_TURBO_128K = "ernie-4.5-turbo-128k"
-    QIANFAN_ERNIE_4_5_TURBO_32K = "ernie-4.5-turbo-32k"
-    QIANFAN_DEEPSEEK_V3 = "deepseek-v3"
-    QIANFAN_DEEPSEEK_R1 = "deepseek-r1"
-    QIANFAN_QWEN3_235B_A22B = "qwen3-235b-a22b"
+    ERNIE_X1_TURBO_32K = "ernie-x1-turbo-32k"
+    ERNIE_X1_32K = "ernie-x1-32k"
+    ERNIE_X1_32K_PREVIEW = "ernie-x1-32k-preview"
+    ERNIE_4_5_TURBO_128K = "ernie-4.5-turbo-128k"
+    ERNIE_4_5_TURBO_32K = "ernie-4.5-turbo-32k"
+    DEEPSEEK_V3 = "deepseek-v3"
+    DEEPSEEK_R1 = "deepseek-r1"
+    QWEN3_235B_A22B = "qwen3-235b-a22b"
 
     # Crynux models
     CRYNUX_DEEPSEEK_R1_DISTILL_QWEN_1_5B = (
@@ -882,14 +882,14 @@ class ModelType(UnifiedModelType, Enum):
     @property
     def is_qianfan(self) -> bool:
         return self in {
-            ModelType.QIANFAN_ERNIE_X1_TURBO_32K,
-            ModelType.QIANFAN_ERNIE_X1_32K,
-            ModelType.QIANFAN_ERNIE_X1_32K_PREVIEW,
-            ModelType.QIANFAN_ERNIE_4_5_TURBO_128K,
-            ModelType.QIANFAN_ERNIE_4_5_TURBO_32K,
-            ModelType.QIANFAN_DEEPSEEK_V3,
-            ModelType.QIANFAN_DEEPSEEK_R1,
-            ModelType.QIANFAN_QWEN3_235B_A22B,
+            ModelType.ERNIE_X1_TURBO_32K,
+            ModelType.ERNIE_X1_32K,
+            ModelType.ERNIE_X1_32K_PREVIEW,
+            ModelType.ERNIE_4_5_TURBO_128K,
+            ModelType.ERNIE_4_5_TURBO_32K,
+            ModelType.DEEPSEEK_V3,
+            ModelType.DEEPSEEK_R1,
+            ModelType.QWEN3_235B_A22B,
         }
 
     @property
@@ -1063,11 +1063,11 @@ class ModelType(UnifiedModelType, Enum):
             ModelType.CRYNUX_QWEN_2_5_7B_INSTRUCT,
             ModelType.CRYNUX_NOUS_HERMES_3_LLAMA_3_1_8B,
             ModelType.CRYNUX_NOUS_HERMES_3_LLAMA_3_2_3B,
-            ModelType.QIANFAN_ERNIE_X1_TURBO_32K,
-            ModelType.QIANFAN_ERNIE_X1_32K,
-            ModelType.QIANFAN_ERNIE_X1_32K_PREVIEW,
-            ModelType.QIANFAN_ERNIE_4_5_TURBO_32K,
-            ModelType.QIANFAN_QWEN3_235B_A22B,
+            ModelType.ERNIE_X1_TURBO_32K,
+            ModelType.ERNIE_X1_32K,
+            ModelType.ERNIE_X1_32K_PREVIEW,
+            ModelType.ERNIE_4_5_TURBO_32K,
+            ModelType.QWEN3_235B_A22B,
         }:
             return 32_000
         elif self in {
@@ -1148,7 +1148,7 @@ class ModelType(UnifiedModelType, Enum):
             return 65_535
         elif self in {
             ModelType.NOVITA_QWEN_2_5_V1_72B,
-            ModelType.QIANFAN_DEEPSEEK_R1,
+            ModelType.DEEPSEEK_R1,
         }:
             return 96_000
         elif self in {
@@ -1203,8 +1203,8 @@ class ModelType(UnifiedModelType, Enum):
             ModelType.NETMIND_DEEPSEEK_V3,
             ModelType.NOVITA_DEEPSEEK_V3_0324,
             ModelType.MISTRAL_MEDIUM_3,
-            ModelType.QIANFAN_ERNIE_4_5_TURBO_128K,
-            ModelType.QIANFAN_DEEPSEEK_V3,
+            ModelType.ERNIE_4_5_TURBO_128K,
+            ModelType.DEEPSEEK_V3,
         }:
             return 128_000
         elif self in {

camel/utils/mcp_client.py

@@ -113,7 +113,11 @@ class ServerConfig(BaseModel):
     # Advanced options
     sse_read_timeout: float = 300.0  # 5 minutes
     terminate_on_close: bool = True
-    # For HTTP URLs, prefer SSE over StreamableHTTP
+
+    # New transport type parameter
+    type: Optional[str] = None
+
+    # Legacy parameter for backward compatibility
     prefer_sse: bool = False
 
     @model_validator(mode='after')
@@ -128,11 +132,43 @@ class ServerConfig(BaseModel):
         if self.command and self.url:
             raise ValueError("Cannot specify both 'command' and 'url'")
 
+        # Validate type if provided
+        if self.type is not None:
+            valid_types = {"stdio", "sse", "streamable_http", "websocket"}
+            if self.type not in valid_types:
+                raise ValueError(
+                    f"Invalid type: "
+                    f"'{self.type}'. "
+                    f"Valid options: {valid_types}"
+                )
+
+        # Issue deprecation warning if prefer_sse is used
+        if self.prefer_sse and self.type is None:
+            import warnings
+
+            warnings.warn(
+                "The 'prefer_sse' parameter is deprecated. "
+                "Use 'type=\"sse\"' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         return self
 
     @property
     def transport_type(self) -> TransportType:
         r"""Automatically detect transport type based on configuration."""
+        # Use explicit transport type if provided
+        if self.type is not None:
+            transport_map = {
+                "stdio": TransportType.STDIO,
+                "sse": TransportType.SSE,
+                "streamable_http": TransportType.STREAMABLE_HTTP,
+                "websocket": TransportType.WEBSOCKET,
+            }
+            return transport_map[self.type]
+
+        # If no type is provided, fall back to automatic detection
         if self.command:
             return TransportType.STDIO
         elif self.url:

camel/utils/tool_result.py

@@ -0,0 +1,44 @@
+# ========= 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 typing import List, Optional
+
+
+class ToolResult:
+    r"""Special result type for tools that can return images along with text.
+
+    This class is used by ChatAgent to detect when a tool returns visual
+    content that should be included in the conversation context.
+    """
+
+    def __init__(self, text: str, images: Optional[List[str]] = None):
+        r"""Initialize a tool result.
+
+        Args:
+            text (str): The text description or result of the tool operation.
+            images (Optional[List[str]]): List of base64-encoded images to
+                include in the conversation context. Images should be encoded
+                as "data:image/{format};base64,{data}" format.
+        """
+        self.text = text
+        self.images = images or []
+
+    def __str__(self) -> str:
+        r"""Return the text representation of the result."""
+        return self.text
+
+    def __repr__(self) -> str:
+        r"""Return a detailed representation of the result."""
+        img_count = len(self.images) if self.images else 0
+        return f"ToolResult(text='{self.text[:50]}...', images={img_count})"