Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

Auto-update documentation after merge [skip ci]

camel-docs-bot1f6de997c6e3
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.json
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.