🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
Auto-update documentation after merge [skip ci]
camel-docs-bot1f6de997c6e3
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.jsonindex fad009834..c65e4102c 100644--- a/docs/mintlify/docs.json+++ b/docs/mintlify/docs.json@@ -574,7 +574,9 @@"reference/camel.toolkits.non_visual_browser_toolkit.agent","reference/camel.toolkits.non_visual_browser_toolkit.browser_non_visual_toolkit","reference/camel.toolkits.non_visual_browser_toolkit.nv_browser_session",- "reference/camel.toolkits.non_visual_browser_toolkit.snapshot"+ "reference/camel.toolkits.non_visual_browser_toolkit.snapshot",+ "reference/camel.toolkits.terminal_toolkit.terminal_toolkit",+ "reference/camel.toolkits.terminal_toolkit.utils"]},{diff --git a/docs/mintlify/reference/camel.toolkits.terminal_toolkit.terminal_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.terminal_toolkit.terminal_toolkit.mdxnew file mode 100644index 000000000..4ffb04c5b--- /dev/null+++ b/docs/mintlify/reference/camel.toolkits.terminal_toolkit.terminal_toolkit.mdx@@ -0,0 +1,303 @@+<a id="camel.toolkits.terminal_toolkit.terminal_toolkit"></a>++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit._to_plain"></a>++## _to_plain++```python+def _to_plain(text: str):+```++Convert ANSI text to plain text using rich if available.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit"></a>++## TerminalToolkit++```python+class TerminalToolkit(BaseToolkit):+```++A toolkit for LLM agents to execute and interact with terminal commands+in either a local or a sandboxed Docker environment.++**Parameters:**++- **use_docker_backend** (bool): If True, all commands are executed in a Docker container. Defaults to False.+- **docker_container_name** (Optional[str]): The name of the Docker container to use. Required if use_docker_backend is True.+- **working_dir** (str): The base directory for all operations. For the local backend, this acts as a security sandbox.+- **session_logs_dir** (Optional[str]): The directory to store session logs. Defaults to a 'terminal_logs' subfolder in the working_dir.+- **timeout** (int): The default timeout in seconds for blocking commands. Defaults to 60.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.__init__"></a>++### __init__++```python+def __init__(+ self,+ timeout: Optional[float] = 20.0,+ working_directory: Optional[str] = None,+ use_docker_backend: bool = False,+ docker_container_name: Optional[str] = None,+ session_logs_dir: Optional[str] = None,+ safe_mode: bool = True,+ allowed_commands: Optional[List[str]] = None,+ clone_current_env: bool = False+):+```++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._setup_cloned_environment"></a>++### _setup_cloned_environment++```python+def _setup_cloned_environment(self):+```++Set up a cloned Python environment.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._setup_initial_environment"></a>++### _setup_initial_environment++```python+def _setup_initial_environment(self):+```++Set up an initial environment with Python 3.10.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._adapt_command_for_environment"></a>++### _adapt_command_for_environment++```python+def _adapt_command_for_environment(self, command: str):+```++Adapt command to use virtual environment if available.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._write_to_log"></a>++### _write_to_log++```python+def _write_to_log(self, log_file: str, content: str):+```++Write content to log file with optional ANSI stripping.++**Parameters:**++- **log_file** (str): Path to the log file+- **content** (str): Content to write++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._sanitize_command"></a>++### _sanitize_command++```python+def _sanitize_command(self, command: str):+```++A comprehensive command sanitizer for both local and+Docker backends.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._start_output_reader_thread"></a>++### _start_output_reader_thread++```python+def _start_output_reader_thread(self, session_id: str):+```++Starts a thread to read stdout from a non-blocking process.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._collect_output_until_idle"></a>++### _collect_output_until_idle++```python+def _collect_output_until_idle(+ self,+ id: str,+ idle_duration: float = 0.5,+ check_interval: float = 0.1,+ max_wait: float = 5.0+):+```++Collects output from a session until it's idle or a max wait time+is reached.++**Parameters:**++- **id** (str): The session ID.+- **idle_duration** (float): How long the stream must be empty to be considered idle.(default: 0.5)+- **check_interval** (float): The time to sleep between checks. (default: 0.1)+- **max_wait** (float): The maximum total time to wait for the process to go idle. (default: 5.0)++**Returns:**++ str: The collected output. If max_wait is reached while+the process is still outputting, a warning is appended.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_exec"></a>++### shell_exec++```python+def shell_exec(+ self,+ id: str,+ command: str,+ block: bool = True+):+```++This function executes a shell command. The command can run in+blocking mode (waits for completion) or non-blocking mode+(runs in the background). A unique session ID is created for+each session.++**Parameters:**++- **command** (str): The command to execute.+- **block** (bool): If True, the command runs synchronously, waiting for it to complete or time out, and returns its full output. If False, the command runs asynchronously in the background.+- **id** (Optional[str]): A specific ID for the session. If not provided, a unique ID is generated for non-blocking sessions.++**Returns:**++ str: If block is True, returns the complete stdout and stderr.+If block is False, returns a message containing the new+session ID and the initial output from the command after+it goes idle.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_write_to_process"></a>++### shell_write_to_process++```python+def shell_write_to_process(self, id: str, command: str):+```++This function sends command to a running non-blocking+process and returns the resulting output after the process+becomes idle again. A newline \n is automatically appended+to the input command.++**Parameters:**++- **id** (str): The unique session ID of the non-blocking process.+- **command** (str): The text to write to the process's standard input.++**Returns:**++ str: The output from the process after the command is sent.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_view"></a>++### shell_view++```python+def shell_view(self, id: str):+```++This function retrieves any new output from a non-blocking session+since the last time this function was called. If the process has+terminated, it drains the output queue and appends a termination+message. If the process is still running, it simply returns any+new output.++**Parameters:**++- **id** (str): The unique session ID of the non-blocking process.++**Returns:**++ str: The new output from the process's stdout and stderr. Returns+an empty string if there is no new output.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_wait"></a>++### shell_wait++```python+def shell_wait(self, id: str, wait_seconds: float = 5.0):+```++This function waits for a specified duration for a+non-blocking process to produce more output or terminate.++**Parameters:**++- **id** (str): The unique session ID of the non-blocking process.+- **wait_seconds** (float): The maximum number of seconds to wait.++**Returns:**++ str: All output collected during the wait period.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_kill_process"></a>++### shell_kill_process++```python+def shell_kill_process(self, id: str):+```++This function forcibly terminates a running non-blocking process.++**Parameters:**++- **id** (str): The unique session ID of the process to kill.++**Returns:**++ str: A confirmation message indicating the process was terminated.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_ask_user_for_help"></a>++### shell_ask_user_for_help++```python+def shell_ask_user_for_help(self, id: str, prompt: str):+```++This function pauses execution and asks a human for help+with an interactive session.++This method can handle different scenarios:+1. If session exists: Shows session output and allows interaction+2. If session doesn't exist: Creates a temporary session for help++**Parameters:**++- **id** (str): The session ID of the interactive process needing help. Can be empty string for general help without session context.+- **prompt** (str): The question or instruction from the LLM to show the human user (e.g., "The program is asking for a filename. Please enter 'config.json'.").++**Returns:**++ str: The output from the shell session after the user's command has+been executed, or help information for general queries.++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.__del__"></a>++### __del__++```python+def __del__(self):+```++<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.get_tools"></a>++### get_tools++```python+def get_tools(self):+```++**Returns:**++ List[FunctionTool]: A list of FunctionTool objects representing the+functions in the toolkit.diff --git a/docs/mintlify/reference/camel.toolkits.terminal_toolkit.utils.mdx b/docs/mintlify/reference/camel.toolkits.terminal_toolkit.utils.mdxnew file mode 100644index 000000000..440c3c158--- /dev/null+++ b/docs/mintlify/reference/camel.toolkits.terminal_toolkit.utils.mdx@@ -0,0 +1,113 @@+<a id="camel.toolkits.terminal_toolkit.utils"></a>++<a id="camel.toolkits.terminal_toolkit.utils.contains_command_chaining"></a>++## contains_command_chaining++```python+def contains_command_chaining(command: str):+```++Check if command contains chaining operators that could be used to+bypass security.++<a id="camel.toolkits.terminal_toolkit.utils.sanitize_command"></a>++## sanitize_command++```python+def sanitize_command(+ command: str,+ use_docker_backend: bool = False,+ safe_mode: bool = True,+ working_dir: Optional[str] = None,+ allowed_commands: Optional[Set[str]] = None+):+```++A comprehensive command sanitizer for both local and Docker backends.++**Parameters:**++- **command** (str): The command to sanitize+- **use_docker_backend** (bool): Whether using Docker backend+- **safe_mode** (bool): Whether to apply security checks+- **working_dir** (Optional[str]): Working directory for path validation+- **allowed_commands** (Optional[Set[str]]): Set of allowed commands++**Returns:**++ Tuple[bool, str]: (is_safe, message_or_command)++<a id="camel.toolkits.terminal_toolkit.utils.is_uv_environment"></a>++## is_uv_environment++```python+def is_uv_environment():+```++Detect whether the current Python runtime is managed by uv.++<a id="camel.toolkits.terminal_toolkit.utils.ensure_uv_available"></a>++## ensure_uv_available++```python+def ensure_uv_available(update_callback = None):+```++Ensure uv is available, installing it if necessary.++**Parameters:**++- **update_callback**: Optional callback function to receive status updates++**Returns:**++ Tuple[bool, Optional[str]]: (success, uv_path)++<a id="camel.toolkits.terminal_toolkit.utils.setup_initial_env_with_uv"></a>++## setup_initial_env_with_uv++```python+def setup_initial_env_with_uv(+ env_path: str,+ uv_path: str,+ working_dir: str,+ update_callback = None+):+```++Set up initial environment using uv.++<a id="camel.toolkits.terminal_toolkit.utils.setup_initial_env_with_venv"></a>++## setup_initial_env_with_venv++```python+def setup_initial_env_with_venv(env_path: str, working_dir: str, update_callback = None):+```++Set up initial environment using standard venv.++<a id="camel.toolkits.terminal_toolkit.utils.clone_current_environment"></a>++## clone_current_environment++```python+def clone_current_environment(env_path: str, working_dir: str, update_callback = None):+```++Create a new Python virtual environment, optionally using uv.++<a id="camel.toolkits.terminal_toolkit.utils.check_nodejs_availability"></a>++## check_nodejs_availability++```python+def check_nodejs_availability(update_callback = None):+```++Check if Node.js is available without modifying the system.