🐫 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-bote0c7ac640d95
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.jsonindex f4b606cdd..6dd1059c1 100644--- a/docs/mintlify/docs.json+++ b/docs/mintlify/docs.json@@ -501,6 +501,7 @@"group": "Toolkits","pages": ["reference/camel.toolkits.aci_toolkit",+ "reference/camel.toolkits.agent_toolkit","reference/camel.toolkits.artifact_toolkit","reference/camel.toolkits.arxiv_toolkit","reference/camel.toolkits.ask_news_toolkit",@@ -555,6 +556,7 @@"reference/camel.toolkits.openai_image_toolkit","reference/camel.toolkits.openbb_toolkit","reference/camel.toolkits.origene_mcp_toolkit",+ "reference/camel.toolkits.planning_worktree_toolkit","reference/camel.toolkits.playwright_mcp_toolkit","reference/camel.toolkits.pptx_toolkit","reference/camel.toolkits.pubmed_toolkit",@@ -575,12 +577,14 @@"reference/camel.toolkits.task_planning_toolkit","reference/camel.toolkits.terminal_toolkit","reference/camel.toolkits.thinking_toolkit",+ "reference/camel.toolkits.todo_toolkit","reference/camel.toolkits.twitter_toolkit","reference/camel.toolkits.vertex_ai_veo_toolkit","reference/camel.toolkits.video_analysis_toolkit","reference/camel.toolkits.video_download_toolkit","reference/camel.toolkits.weather_toolkit","reference/camel.toolkits.web_deploy_toolkit",+ "reference/camel.toolkits.web_fetch_toolkit","reference/camel.toolkits.wechat_official_toolkit","reference/camel.toolkits.whatsapp_toolkit","reference/camel.toolkits.wolfram_alpha_toolkit",diff --git a/docs/mintlify/reference/camel.toolkits.agent_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.agent_toolkit.mdxnew file mode 100644index 000000000..61fa97db2--- /dev/null+++ b/docs/mintlify/reference/camel.toolkits.agent_toolkit.mdx@@ -0,0 +1,257 @@+<a id="camel.toolkits.agent_toolkit"></a>++<a id="camel.toolkits.agent_toolkit.AgentToolkit"></a>++## AgentToolkit++```python+class AgentToolkit(BaseToolkit, RegisteredAgentToolkit):+```++Toolkit for delegating a task to a persistent specialized sub-agent.++This toolkit exposes tools for either waiting on a delegated task directly+or starting one and checking its result later.++<a id="camel.toolkits.agent_toolkit.AgentToolkit.__init__"></a>++### __init__++```python+def __init__(self, timeout: Optional[float] = None):+```++Initialize the AgentToolkit.++**Parameters:**++- **timeout** (Optional[float]): Maximum execution time for toolkit calls. (default: :obj:`None`)++<a id="camel.toolkits.agent_toolkit.AgentToolkit._build_system_message"></a>++### _build_system_message++```python+def _build_system_message(self, subagent_type: str, description: str):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit._error_result"></a>++### _error_result++```python+def _error_result(self, error_message: str, **payload: Any):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit._require_parent_agent"></a>++### _require_parent_agent++```python+def _require_parent_agent(self):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit._resolve_child_tools"></a>++### _resolve_child_tools++```python+def _resolve_child_tools(self, parent: Optional['ChatAgent']):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit._create_subagent"></a>++### _create_subagent++```python+def _create_subagent(self, subagent_type: str, description: str):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit._run_agent_step"></a>++### _run_agent_step++```python+def _run_agent_step(self, agent: 'ChatAgent', prompt: str):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit._complete_task"></a>++### _complete_task++```python+def _complete_task(self, task_id: str):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit._submit_agent_task"></a>++### _submit_agent_task++```python+def _submit_agent_task(+ self,+ agent_id: str,+ agent: 'ChatAgent',+ prompt: str+):+```++Submit a new task. Caller MUST hold `__INLINE_CODE_0__`.++<a id="camel.toolkits.agent_toolkit.AgentToolkit._get_task"></a>++### _get_task++```python+def _get_task(self, task_id: str):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit.agent_run_subagent"></a>++### agent_run_subagent++```python+def agent_run_subagent(+ self,+ prompt: str,+ description: str = 'Specialized sub-agent task',+ subagent_type: str = 'general-purpose',+ agent_id: Optional[str] = None,+ wait: bool = True,+ timeout: Optional[float] = None+):+```++Run a specialized sub-agent, optionally waiting for completion.++Use this tool when the current task is complex enough to benefit from+a focused child agent with its own conversation state. If+:obj:`agent_id` is omitted, a new sub-agent session is created with a+fresh ChatAgent instance and its own empty conversation state. If+:obj:`agent_id` is provided, the matching sub-agent instance is reused+rather than recreated. This means the sub-agent keeps its existing+memory and any state accumulated from previous turns in that session.++Prefer :obj:`wait=True` when the parent agent needs the sub-agent+result before it can continue. Use :obj:`wait=False` only when the+parent agent intentionally wants to do other work first and check the+task later with :obj:`agent_get_task_output`.++**Parameters:**++- **prompt** (str): The task instructions to send to the sub-agent for this turn.+- **description** (str): Short description of the sub-task or role for the sub-agent. This is primarily used when creating a new session. (default: :obj:`"Specialized sub-agent task"`)+- **subagent_type** (str): Specialization label for the spawned sub-agent, such as :obj:`general-purpose`, :obj:`research`, :obj:`analysis`, :obj:`coding`, or :obj:`writing`. (default: :obj:`"general-purpose"`)+- **agent_id** (Optional[str]): Existing sub-agent session ID to resume. When provided, the stored sub-agent instance is reused, so it continues with the same memory / conversation state from earlier turns. In this case, :obj:`description` and :obj:`subagent_type` are ignored. The spawned sub-agent always uses the calling parent agent's model. (default: :obj:`None`)+- **wait** (bool): Whether to wait for the sub-agent to finish before returning. Set to :obj:`False` to start the task and check it later with :obj:`agent_get_task_output`. (default: :obj:`True`)+- **timeout** (Optional[float]): Maximum wait time in seconds for the sub-agent to finish when :obj:`wait` is True. If the timeout is reached, the task keeps running and the current status is returned.++**Returns:**++ Dict[str, Any]: Final result for completed tasks, or current task+metadata if still running.++<a id="camel.toolkits.agent_toolkit.AgentToolkit.agent_get_task_output"></a>++### agent_get_task_output++```python+def agent_get_task_output(+ self,+ task_id: str,+ block: bool = False,+ timeout: Optional[float] = None+):+```++Get the latest result of a sub-agent task started earlier.++Use this after calling :obj:`agent_run_subagent(wait=False)`. When+:obj:`block` is False, the call returns immediately with the latest+known status. When :obj:`block` is True, the tool waits up to+:obj:`timeout` seconds for completion before returning.++**Parameters:**++- **task_id** (str): Sub-agent task ID returned by :obj:`agent_run_subagent`.+- **block** (bool): Whether to wait for the task to finish before returning status and output. (default: :obj:`False`)+- **timeout** (Optional[float]): Maximum wait time in seconds when :obj:`block` is True. (default: :obj:`None`)++**Returns:**++ Dict[str, Any]: Task status, associated :obj:`agent_id`, and any+available result or error output.++<a id="camel.toolkits.agent_toolkit.AgentToolkit.agent_stop_task"></a>++### agent_stop_task++```python+def agent_stop_task(self, task_id: str):+```++Request cancellation of a running sub-agent task.++**Parameters:**++- **task_id** (str): Sub-agent task ID returned by :obj:`agent_run_subagent`.++**Returns:**++ Dict[str, Any]: Stop request status and the latest known task+state.++<a id="camel.toolkits.agent_toolkit.AgentToolkit.clone_for_new_session"></a>++### clone_for_new_session++```python+def clone_for_new_session(self, new_session_id: Optional[str] = None):+```++Create a fresh AgentToolkit without carrying over sub-agent state.++**Parameters:**++- **new_session_id** (Optional[str]): Unused compatibility parameter for ChatAgent toolkit cloning. (default: :obj:`None`)++**Returns:**++ AgentToolkit: A new toolkit instance with the same configuration+and no active sub-agent sessions.++<a id="camel.toolkits.agent_toolkit.AgentToolkit._purge_completed_tasks"></a>++### _purge_completed_tasks++```python+def _purge_completed_tasks(self):+```++Remove finished tasks to prevent unbounded memory growth.++<a id="camel.toolkits.agent_toolkit.AgentToolkit.cleanup"></a>++### cleanup++```python+def cleanup(self):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit.__del__"></a>++### __del__++```python+def __del__(self):+```++<a id="camel.toolkits.agent_toolkit.AgentToolkit.get_tools"></a>++### get_tools++```python+def get_tools(self):+```++Return the tool list for this toolkit.diff --git a/docs/mintlify/reference/camel.toolkits.file_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.file_toolkit.mdxindex 340c1dfb0..748ef3dae 100644--- a/docs/mintlify/reference/camel.toolkits.file_toolkit.mdx+++ b/docs/mintlify/reference/camel.toolkits.file_toolkit.mdx@@ -65,6 +65,34 @@ in downstream processing.Path: A fully resolved (absolute) and sanitized Path object.+<a id="camel.toolkits.file_toolkit.FileToolkit._resolve_search_path"></a>++### _resolve_search_path++```python+def _resolve_search_path(self, path: Optional[str] = None):+```++Resolve a search directory without sanitizing it.++<a id="camel.toolkits.file_toolkit.FileToolkit._resolve_existing_filepath"></a>++### _resolve_existing_filepath++```python+def _resolve_existing_filepath(self, file_path: str):+```++Resolve a file path without sanitizing the filename.++<a id="camel.toolkits.file_toolkit.FileToolkit._tool_error"></a>++### _tool_error++```python+def _tool_error(self, message: str):+```+<a id="camel.toolkits.file_toolkit.FileToolkit._sanitize_filename"></a>### _sanitize_filename@@ -86,6 +114,64 @@ underscore (_).str: The sanitized filename with disallowed characters replaced byunderscores.+<a id="camel.toolkits.file_toolkit.FileToolkit._iter_grep_candidate_files"></a>++### _iter_grep_candidate_files++```python+def _iter_grep_candidate_files(+ self,+ root: Path,+ glob_pattern: str,+ file_type: Optional[str]+):+```++<a id="camel.toolkits.file_toolkit.FileToolkit._render_grep_context_block"></a>++### _render_grep_context_block++```python+def _render_grep_context_block(+ self,+ file_path: Path,+ lines: List[str],+ match_index: int,+ context_lines: int+):+```++<a id="camel.toolkits.file_toolkit.FileToolkit._render_grep_multiline_block"></a>++### _render_grep_multiline_block++```python+def _render_grep_multiline_block(+ self,+ file_path: Path,+ lines: List[str],+ start_line: int,+ end_line: int,+ context_lines: int+):+```++<a id="camel.toolkits.file_toolkit.FileToolkit._normalize_notebook_source"></a>++### _normalize_notebook_source++```python+def _normalize_notebook_source(self, new_source: str):+```++<a id="camel.toolkits.file_toolkit.FileToolkit._build_notebook_cell"></a>++### _build_notebook_cell++```python+def _build_notebook_cell(self, new_source: str, cell_type: str):+```+<a id="camel.toolkits.file_toolkit.FileToolkit._write_text_file"></a>### _write_text_file@@ -509,6 +595,94 @@ and writes the result back.str: A success message if the edit was successful, or anerror message if the content wasn't found or an error occurred.+<a id="camel.toolkits.file_toolkit.FileToolkit.glob_files"></a>++### glob_files++```python+def glob_files(self, pattern: str, path: Optional[str] = None):+```++Find files by glob pattern and sort by modification time.++**Parameters:**++- **pattern** (str): Glob pattern to match, for example :obj:`**/*.js`.+- **path** (Optional[str]): Optional directory to search from. If not provided, the toolkit working directory is used.++**Returns:**++ Union[List[str], str]: Matching absolute file paths sorted by most+recent modification time first, or an error message.++<a id="camel.toolkits.file_toolkit.FileToolkit.grep_files"></a>++### grep_files++```python+def grep_files(+ self,+ pattern: str,+ path: str,+ glob_pattern: str = '*',+ file_type: Optional[str] = None,+ output_mode: str = 'content',+ ignore_case: bool = False,+ context_lines: int = 0,+ head_limit: int = 20,+ multiline: bool = False+):+```++Search file content with a regular expression.++**Parameters:**++- **pattern** (str): Regular expression to search for.+- **path** (str): Directory to search recursively.+- **glob_pattern** (str): Glob filter for candidate files before searching content. (default: :obj:`"*"`)+- **file_type** (Optional[str]): Optional file extension filter without requiring the leading dot. (default: :obj:`None`)+- **output_mode** (str): One of :obj:`content`, :obj:`files_with_matches`, or :obj:`count`. (default: :obj:`"content"`)+- **ignore_case** (bool): Whether to search case-insensitively. (default: :obj:`False`)+- **context_lines** (int): Number of surrounding lines to include when :obj:`output_mode` is :obj:`content`. (default: :obj:`0`)+- **head_limit** (int): Maximum number of blocks or file paths to return. (default: :obj:`20`)+- **multiline** (bool): Whether the regex may span multiple lines. (default: :obj:`False`)++**Returns:**++ Any: Matching content blocks, matching file paths, aggregate+counts, or an error string depending on :obj:`output_mode`.++<a id="camel.toolkits.file_toolkit.FileToolkit.notebook_edit_cell"></a>++### notebook_edit_cell++```python+def notebook_edit_cell(+ self,+ notebook_path: str,+ new_source: str = '',+ cell_id: Optional[str] = None,+ cell_type: Optional[str] = None,+ edit_mode: str = 'replace'+):+```++Edit, insert, or delete a cell in a Jupyter notebook.++**Parameters:**++- **notebook_path** (str): Absolute or working-directory-relative path to the notebook file.+- **new_source** (str): New source for the cell when inserting or replacing.+- **cell_id** (Optional[str]): Target cell ID. Required for replace and delete, and used as the insertion anchor when inserting.+- **cell_type** (Optional[str]): Cell type for inserted cells, or optional replacement cell type. Supported values are :obj:`code` and :obj:`markdown`.+- **edit_mode** (str): One of :obj:`replace`, :obj:`insert`, or :obj:`delete`.++**Returns:**++ str: Confirmation describing the notebook update, or an error+message.+<a id="camel.toolkits.file_toolkit.FileToolkit.search_files"></a>### search_files@@ -572,4 +746,3 @@ def get_tools(self):List[FunctionTool]: A list of FunctionTool objects representingthe available functions in this toolkit.-diff --git a/docs/mintlify/reference/camel.toolkits.function_tool.mdx b/docs/mintlify/reference/camel.toolkits.function_tool.mdxindex 1a0debb10..feaf5c02e 100644--- a/docs/mintlify/reference/camel.toolkits.function_tool.mdx+++ b/docs/mintlify/reference/camel.toolkits.function_tool.mdx@@ -1,5 +1,49 @@<a id="camel.toolkits.function_tool"></a>+<a id="camel.toolkits.function_tool._annotation_accepts"></a>++## _annotation_accepts++```python+def _annotation_accepts(annotation: Any, value: Any):+```++Quick structural check: could *annotation* plausibly apply to *value*?++Used by the Union handler to skip branches that clearly don't match+before attempting (potentially failing) coercion.++<a id="camel.toolkits.function_tool._coerce_arg"></a>++## _coerce_arg++```python+def _coerce_arg(value: Any, annotation: Any):+```++Coerce *value* so that plain dicts become Pydantic model instances+where the function signature expects them.++Handles `__INLINE_CODE_0____INLINE_CODE_1____INLINE_CODE_2____INLINE_CODE_3____INLINE_CODE_4__`,+`__INLINE_CODE_5____INLINE_CODE_6____INLINE_CODE_7__` annotations recursively.+Non-model annotations are returned unchanged.++<a id="camel.toolkits.function_tool._coerce_arguments"></a>++## _coerce_arguments++```python+def _coerce_arguments(func: Callable, args: tuple, kwargs: Dict[str, Any]):+```++Coerce positional and keyword arguments to match Pydantic model+type annotations in *func*'s signature.++This bridges the gap between the JSON dicts that the LLM produces (via+`__INLINE_CODE_0__`) and the Pydantic models that toolkit authors declare in+their function signatures. Plain values and non-model parameters are+passed through unchanged.+<a id="camel.toolkits.function_tool._remove_a_key"></a>## _remove_a_keydiff --git a/docs/mintlify/reference/camel.toolkits.planning_worktree_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.planning_worktree_toolkit.mdxnew file mode 100644index 000000000..682564567--- /dev/null+++ b/docs/mintlify/reference/camel.toolkits.planning_worktree_toolkit.mdx@@ -0,0 +1,139 @@+<a id="camel.toolkits.planning_worktree_toolkit"></a>++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit"></a>++## PlanningWorktreeToolkit++```python+class PlanningWorktreeToolkit(BaseToolkit):+```++Toolkit for plan-mode state and git worktree management.++Each toolkit instance owns an independent plan file determined by+*working_directory* and *plan_file_name*. A class-level lock registry+ensures that concurrent agents sharing the same plan file do not+corrupt each other's writes.++**Parameters:**++- **working_directory** (Optional[str]): The directory to use as the working root. Falls back to the `__INLINE_CODE_0____INLINE_CODE_1__None`)+- **timeout** (Optional[float]): The timeout for the toolkit. (default: :obj:`None`)+- **plan_file_name** (str): Name of the Markdown plan file created inside *working_directory*. (default: :obj:`".camel-plan.md"`)+- **switch_process_cwd** (bool): If :obj:`True`, `__INLINE_CODE_1____INLINE_CODE_2__False`)++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit.__init__"></a>++### __init__++```python+def __init__(+ self,+ working_directory: Optional[str] = None,+ timeout: Optional[float] = None,+ plan_file_name: str = '.camel-plan.md',+ switch_process_cwd: bool = False+):+```++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit._plan_file_path"></a>++### _plan_file_path++```python+def _plan_file_path(self):+```++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit._plan_lock"></a>++### _plan_lock++```python+def _plan_lock(self):+```++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit._error_result"></a>++### _error_result++```python+def _error_result(self, message: str, **payload: Any):+```++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit._run_git"></a>++### _run_git++```python+def _run_git(self, *args: str):+```++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit.planning_enter_plan_mode"></a>++### planning_enter_plan_mode++```python+def planning_enter_plan_mode(self):+```++**Returns:**++ Dict[str, Any]: Plan mode status and plan file location.++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit.planning_exit_plan_mode"></a>++### planning_exit_plan_mode++```python+def planning_exit_plan_mode(self, allowed_prompts: Optional[List[Dict[str, str]]] = None):+```++Exit plan mode and return the current plan for approval.++**Parameters:**++- **allowed_prompts** (Optional[List[Dict[str, str]]]): Optional list of tool/prompt pairs that are allowed after plan approval.++**Returns:**++ Dict[str, Any]: Current plan content together with the supplied+allowed prompts.++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit.worktree_enter_worktree"></a>++### worktree_enter_worktree++```python+def worktree_enter_worktree(self, name: Optional[str] = None):+```++Create and switch this toolkit to a dedicated git worktree.++**Parameters:**++- **name** (Optional[str]): Optional worktree name seed.++**Returns:**++ Dict[str, Any]: Created branch name, worktree path, and active+working directory.++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit.worktree_remove_worktree"></a>++### worktree_remove_worktree++```python+def worktree_remove_worktree(self):+```++**Returns:**++ Dict[str, Any]: Removal status and restored working directory.++<a id="camel.toolkits.planning_worktree_toolkit.PlanningWorktreeToolkit.get_tools"></a>++### get_tools++```python+def get_tools(self):+```diff --git a/docs/mintlify/reference/camel.toolkits.todo_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.todo_toolkit.mdxnew file mode 100644index 000000000..2ee17e56a--- /dev/null+++ b/docs/mintlify/reference/camel.toolkits.todo_toolkit.mdx@@ -0,0 +1,108 @@+<a id="camel.toolkits.todo_toolkit"></a>++<a id="camel.toolkits.todo_toolkit.TodoItem"></a>++## TodoItem++```python+class TodoItem(BaseModel):+```++Schema for a single todo item.++**Parameters:**++- **content**: A brief, actionable title for the task.+- **active_form**: Present-continuous label shown in a UI spinner while the task is in progress.+- **status**: Current status of the task.++<a id="camel.toolkits.todo_toolkit.TodoToolkit"></a>++## TodoToolkit++```python+class TodoToolkit(BaseToolkit):+```++A toolkit for managing a todo list persisted to local files.++The toolkit exposes a single :obj:`todo_write` tool that lets an agent+replace the current todo list with a new set of items. Each item carries+a short content string, an active-form label for UI spinners, and a+status drawn from `__INLINE_CODE_1____INLINE_CODE_2____INLINE_CODE_3____INLINE_CODE_4____INLINE_CODE_5__`.++Two files are maintained inside *working_dir*:++- `__INLINE_CODE_6__` — a clean, human-readable Markdown checklist.+- `__INLINE_CODE_7__` — structured data used to reload state across sessions.++A thread lock prevents concurrent write conflicts within the same+process.++**Parameters:**++- **working_dir** (Optional[str]): Directory where files are stored. Defaults to the current working directory.+- **timeout** (Optional[float]): The timeout for the toolkit. (default: :obj:`None`)++<a id="camel.toolkits.todo_toolkit.TodoToolkit.__init__"></a>++### __init__++```python+def __init__(+ self,+ working_dir: Optional[str] = None,+ timeout: Optional[float] = None+):+```++<a id="camel.toolkits.todo_toolkit.TodoToolkit._load"></a>++### _load++```python+def _load(self):+```++Load todos from the JSON data file, if it exists.++<a id="camel.toolkits.todo_toolkit.TodoToolkit._save"></a>++### _save++```python+def _save(self):+```++Write todos to both the JSON data file and the Markdown file.++<a id="camel.toolkits.todo_toolkit.TodoToolkit.todo_write"></a>++### todo_write++```python+def todo_write(self, todos: List[TodoItem]):+```++Replace the current todo list with a new set of items.++**Parameters:**++- **todos** (List[TodoItem]): The new todo list that will replace the current one.++**Returns:**++ str: A success message, or an error string prefixed with+`__INLINE_CODE_0__` if validation fails.++<a id="camel.toolkits.todo_toolkit.TodoToolkit.get_tools"></a>++### get_tools++```python+def get_tools(self):+```++**Returns:**++ List[FunctionTool]: A list of tools.diff --git a/docs/mintlify/reference/camel.toolkits.web_fetch_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.web_fetch_toolkit.mdxnew file mode 100644index 000000000..606bf225c--- /dev/null+++ b/docs/mintlify/reference/camel.toolkits.web_fetch_toolkit.mdx@@ -0,0 +1,89 @@+<a id="camel.toolkits.web_fetch_toolkit"></a>++<a id="camel.toolkits.web_fetch_toolkit.WebFetchToolkit"></a>++## WebFetchToolkit++```python+class WebFetchToolkit(BaseToolkit, RegisteredAgentToolkit):+```++Toolkit for fetching a web page and summarizing it for a prompt.++<a id="camel.toolkits.web_fetch_toolkit.WebFetchToolkit.__init__"></a>++### __init__++```python+def __init__(+ self,+ default_model: Optional[BaseModelBackend] = None,+ timeout: Optional[float] = None,+ request_timeout: float = 20.0+):+```++<a id="camel.toolkits.web_fetch_toolkit.WebFetchToolkit._error_message"></a>++### _error_message++```python+def _error_message(self, message: str):+```++<a id="camel.toolkits.web_fetch_toolkit.WebFetchToolkit._resolve_model"></a>++### _resolve_model++```python+def _resolve_model(self):+```++<a id="camel.toolkits.web_fetch_toolkit.WebFetchToolkit._extract_text"></a>++### _extract_text++```python+def _extract_text(self, content_type: str, body: str):+```++<a id="camel.toolkits.web_fetch_toolkit.WebFetchToolkit._get_summary_agent"></a>++### _get_summary_agent++```python+def _get_summary_agent(self):+```++<a id="camel.toolkits.web_fetch_toolkit.WebFetchToolkit.web_fetch_and_analyze"></a>++### web_fetch_and_analyze++```python+def web_fetch_and_analyze(+ self,+ url: str,+ prompt: str,+ max_chars: int = 0+):+```++Fetch a URL and answer a prompt about its content.++**Parameters:**++- **url** (str): URL to fetch.+- **prompt** (str): Instruction describing what to extract or analyze from the fetched page.+- **max_chars** (int): Maximum number of characters of page content to use. When set to 0 (default) the full page is sent to the summarizer. If the summarizer fails because the content is too long, retry with a smaller value.++**Returns:**++ str: AI-processed summary or answer derived from the page content.++<a id="camel.toolkits.web_fetch_toolkit.WebFetchToolkit.get_tools"></a>++### get_tools++```python+def get_tools(self):+```diff --git a/docs/reference/camel.toolkits.file_toolkit.md b/docs/reference/camel.toolkits.file_toolkit.mdnew file mode 100644index 000000000..340c1dfb0--- /dev/null+++ b/docs/reference/camel.toolkits.file_toolkit.md@@ -0,0 +1,575 @@+<a id="camel.toolkits.file_toolkit"></a>++<a id="camel.toolkits.file_toolkit.FileToolkit"></a>++## FileToolkit++```python+class FileToolkit(BaseToolkit):+```++A comprehensive toolkit for file operations including reading,+writing, and editing files.++This class provides cross-platform (macOS, Linux, Windows) support for:+- Reading various file formats (text, JSON, YAML, PDF, DOCX)+- Writing to multiple formats (Markdown, DOCX, PDF, plaintext, JSON,+YAML, CSV, HTML)+- Editing and modifying existing files with content replacement+- Automatic backup creation before modifications+- Custom encoding and enhanced formatting options++<a id="camel.toolkits.file_toolkit.FileToolkit.__init__"></a>++### __init__++```python+def __init__(+ self,+ working_directory: Optional[str] = None,+ timeout: Optional[float] = None,+ default_encoding: str = 'utf-8',+ backup_enabled: bool = True+):+```++Initialize the FileToolkit.++**Parameters:**++- **working_directory** (str, optional): The default directory for output files. If not provided, it will be determined by the `CAMEL_WORKDIR` environment variable (if set). If the environment variable is not set, it defaults to `camel_working_dir`.+- **timeout** (Optional[float]): The timeout for the toolkit. (default: :obj:`None`)+- **default_encoding** (str): Default character encoding for text operations. (default: :obj:`utf-8`)+- **backup_enabled** (bool): Whether to create backups of existing files before overwriting. (default: :obj:`True`)++<a id="camel.toolkits.file_toolkit.FileToolkit._resolve_filepath"></a>++### _resolve_filepath++```python+def _resolve_filepath(self, file_path: str):+```++Convert the given string path to a Path object.++If the provided path is not absolute, it is made relative to the+default output directory. The filename part is sanitized to replace+spaces and special characters with underscores, ensuring safe usage+in downstream processing.++**Parameters:**++- **file_path** (str): The file path to resolve.++**Returns:**++ Path: A fully resolved (absolute) and sanitized Path object.++<a id="camel.toolkits.file_toolkit.FileToolkit._sanitize_filename"></a>++### _sanitize_filename++```python+def _sanitize_filename(self, filename: str):+```++Sanitize a filename by replacing any character that is not+alphanumeric, a dot (.), hyphen (-), or underscore (_) with an+underscore (_).++**Parameters:**++- **filename** (str): The original filename which may contain spaces or special characters.++**Returns:**++ str: The sanitized filename with disallowed characters replaced by+underscores.++<a id="camel.toolkits.file_toolkit.FileToolkit._write_text_file"></a>++### _write_text_file++```python+def _write_text_file(+ self,+ file_path: Path,+ content: str,+ encoding: str = 'utf-8'+):+```++Write text content to a plaintext file.++**Parameters:**++- **file_path** (Path): The target file path.+- **content** (str): The text content to write.+- **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)++<a id="camel.toolkits.file_toolkit.FileToolkit._create_backup"></a>++### _create_backup++```python+def _create_backup(self, file_path: Path):+```++Create a backup of the file if it exists and backup is enabled.++**Parameters:**++- **file_path** (Path): The file path to backup.++**Returns:**++ Optional[Path]: Path to the backup file if created, None otherwise.++<a id="camel.toolkits.file_toolkit.FileToolkit._write_docx_file"></a>++### _write_docx_file++```python+def _write_docx_file(self, file_path: Path, content: str):+```++Write text content to a DOCX file with default formatting.++**Parameters:**++- **file_path** (Path): The target file path.+- **content** (str): The text content to write.++<a id="camel.toolkits.file_toolkit.FileToolkit._write_pdf_file"></a>++### _write_pdf_file++```python+def _write_pdf_file(+ self,+ file_path: Path,+ title: str,+ content: Union[str, List[List[str]]],+ use_latex: bool = False+):+```++Write text content to a PDF file with LaTeX and table support.++**Parameters:**++- **file_path** (Path): The target file path.+- **title** (str): The document title.+- **content** (Union[str, List[List[str]]]): The content to write. Can+- **be**: - String: Supports Markdown-style tables and LaTeX math expressions - List[List[str]]: Table data as list of rows for direct table rendering+- **use_latex** (bool): Whether to use LaTeX for math rendering. (default: :obj:`False`)++<a id="camel.toolkits.file_toolkit.FileToolkit._process_text_content"></a>++### _process_text_content++```python+def _process_text_content(+ self,+ story,+ content: str,+ heading_style,+ body_style+):+```++Process text content and add to story.++**Parameters:**++- **story**: The reportlab story list to append to+- **content** (str): The text content to process+- **heading_style**: Style for headings+- **body_style**: Style for body text++<a id="camel.toolkits.file_toolkit.FileToolkit._find_table_line_ranges"></a>++### _find_table_line_ranges++```python+def _find_table_line_ranges(self, lines: List[str]):+```++Find line ranges that contain markdown tables.++**Parameters:**++- **lines** (List[str]): List of lines to analyze.++**Returns:**++ List[Tuple[int, int]]: List of (start_line, end_line) tuples+for table ranges.++<a id="camel.toolkits.file_toolkit.FileToolkit._register_chinese_font"></a>++### _register_chinese_font++```python+def _register_chinese_font(self):+```++**Returns:**++ str: The font name to use for Chinese text.++<a id="camel.toolkits.file_toolkit.FileToolkit._parse_markdown_table"></a>++### _parse_markdown_table++```python+def _parse_markdown_table(self, lines: List[str]):+```++Parse markdown-style tables from a list of lines.++**Parameters:**++- **lines** (List[str]): List of text lines that may contain tables.++**Returns:**++ List[List[List[str]]]: List of tables, where each table is a list+of rows, and each row is a list of cells.++<a id="camel.toolkits.file_toolkit.FileToolkit._is_table_row"></a>++### _is_table_row++```python+def _is_table_row(self, line: str):+```++Check if a line appears to be a table row.++**Parameters:**++- **line** (str): The line to check.++**Returns:**++ bool: True if the line looks like a table row.++<a id="camel.toolkits.file_toolkit.FileToolkit._is_table_separator"></a>++### _is_table_separator++```python+def _is_table_separator(self, line: str):+```++Check if a line is a table separator (e.g., |---|---|).++**Parameters:**++- **line** (str): The line to check.++**Returns:**++ bool: True if the line is a table separator.++<a id="camel.toolkits.file_toolkit.FileToolkit._parse_table_row"></a>++### _parse_table_row++```python+def _parse_table_row(self, line: str):+```++Parse a single table row into cells.++**Parameters:**++- **line** (str): The table row line.++**Returns:**++ List[str]: List of cell contents.++<a id="camel.toolkits.file_toolkit.FileToolkit._create_pdf_table"></a>++### _create_pdf_table++```python+def _create_pdf_table(self, table_data: List[List[str]]):+```++Create a formatted table for PDF.++**Parameters:**++- **table_data** (List[List[str]]): Table data as list of rows.++**Returns:**++ Table: A formatted reportlab Table object.++<a id="camel.toolkits.file_toolkit.FileToolkit._convert_markdown_to_html"></a>++### _convert_markdown_to_html++```python+def _convert_markdown_to_html(self, text: str):+```++Convert basic markdown formatting to HTML for PDF rendering.++**Parameters:**++- **text** (str): Text with markdown formatting.++**Returns:**++ str: Text with HTML formatting.++<a id="camel.toolkits.file_toolkit.FileToolkit._ensure_html_utf8_meta"></a>++### _ensure_html_utf8_meta++```python+def _ensure_html_utf8_meta(self, content: str):+```++Ensure HTML content has UTF-8 meta tag.++**Parameters:**++- **content** (str): The HTML content.++**Returns:**++ str: HTML content with UTF-8 meta tag.++<a id="camel.toolkits.file_toolkit.FileToolkit._write_csv_file"></a>++### _write_csv_file++```python+def _write_csv_file(+ self,+ file_path: Path,+ content: Union[str, List[List]],+ encoding: str = 'utf-8-sig'+):+```++Write CSV content to a file.++**Parameters:**++- **file_path** (Path): The target file path.+- **content** (Union[str, List[List]]): The CSV content as a string or list of lists.+- **encoding** (str): Character encoding to use. (default: :obj:`utf-8-sig`)++<a id="camel.toolkits.file_toolkit.FileToolkit._write_json_file"></a>++### _write_json_file++```python+def _write_json_file(+ self,+ file_path: Path,+ content: str,+ encoding: str = 'utf-8'+):+```++Write JSON content to a file.++**Parameters:**++- **file_path** (Path): The target file path.+- **content** (str): The JSON content as a string.+- **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)++<a id="camel.toolkits.file_toolkit.FileToolkit._write_simple_text_file"></a>++### _write_simple_text_file++```python+def _write_simple_text_file(+ self,+ file_path: Path,+ content: str,+ encoding: str = 'utf-8'+):+```++Write text content to a file (used for HTML, Markdown, YAML, etc.).++**Parameters:**++- **file_path** (Path): The target file path.+- **content** (str): The content to write.+- **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)++<a id="camel.toolkits.file_toolkit.FileToolkit.write_to_file"></a>++### write_to_file++```python+def write_to_file(+ self,+ title: str,+ content: Union[str, List[List[str]]],+ filename: str,+ encoding: Optional[str] = None,+ use_latex: bool = False+):+```++Write the given content to a file.++If the file exists, it will be overwritten. Supports multiple formats:+Markdown (.md, .markdown, default), Plaintext (.txt), CSV (.csv),+DOC/DOCX (.doc, .docx), PDF (.pdf), JSON (.json), YAML (.yml, .yaml),+and HTML (.html, .htm).++**Parameters:**++- **title** (str): The title of the document.+- **content** (Union[str, List[List[str]]]): The content to write to the file. Content format varies by file type: - Text formats (txt, md, html, yaml): string - CSV: string or list of lists - JSON: string or serializable object+- **filename** (str): The name or path of the file. If a relative path is supplied, it is resolved to self.working_directory.+- **encoding** (Optional[str]): The character encoding to use. (default: :obj: `None`)+- **use_latex** (bool): Whether to use LaTeX for math rendering. (default: :obj:`False`)++**Returns:**++ str: A message indicating success or error details.++<a id="camel.toolkits.file_toolkit.FileToolkit.read_file"></a>++### read_file++```python+def read_file(self, file_paths: Union[str, List[str]]):+```++Read and return content of one or more files using MarkItDown+for better format support.++This method uses MarkItDownLoader to convert various file formats+to Markdown. It supports a wide range of formats including:+- PDF (.pdf)+- Microsoft Office: Word (.doc, .docx), Excel (.xls, .xlsx),+PowerPoint (.ppt, .pptx)+- EPUB (.epub)+- HTML (.html, .htm)+- Images (.jpg, .jpeg, .png) for OCR+- Audio (.mp3, .wav) for transcription+- Text-based formats (.csv, .json, .xml, .txt, .md)+- ZIP archives (.zip)++**Parameters:**++- **file_paths** (Union[str, List[str]]): A single file path or a list of file paths to read. Paths can be relative or absolute. If relative, they will be resolved relative to the working directory.++**Returns:**++ Union[str, Dict[str, str]]:+- If a single file path is provided: Returns the content as+a string.+- If multiple file paths are provided: Returns a dictionary+where keys are file paths and values are the corresponding+content in Markdown format.+If conversion fails, returns an error message.++<a id="camel.toolkits.file_toolkit.FileToolkit.edit_file"></a>++### edit_file++```python+def edit_file(+ self,+ file_path: str,+ old_content: str,+ new_content: str+):+```++Edit a file by replacing specified content.++This method performs simple text replacement in files. It reads+the file, replaces all occurrences of old_content with new_content,+and writes the result back.++**Parameters:**++- **file_path** (str): The path to the file to edit. Can be relative or absolute. If relative, it will be resolved relative to the working directory.+- **old_content** (str): The exact text to find and replace.+- **new_content** (str): The text to replace old_content with.++**Returns:**++ str: A success message if the edit was successful, or an+error message if the content wasn't found or an error occurred.++<a id="camel.toolkits.file_toolkit.FileToolkit.search_files"></a>++### search_files++```python+def search_files(+ self,+ pattern: str,+ file_types: Optional[List[str]] = None,+ file_pattern: Optional[str] = None,+ path: Optional[str] = None+):+```++Search for a text pattern in files with specified extensions or+file patterns.++This method searches for a text pattern (case-insensitive substring+match) in files matching either the specified file types or a file+pattern. It returns structured results showing which files contain+the pattern, along with line numbers and matching content.++**Parameters:**++- **pattern** (str): The text pattern to search for (case-insensitive string match).+- **file_types** (Optional[List[str]]): List of file extensions to search (e.g., ["md", "txt", "py"]). Do not include the dot. If not provided and file_pattern is also not provided, defaults to ["md"] (markdown files). Ignored if file_pattern is provided. (default: :obj:`None`)+- **file_pattern** (Optional[str]): Glob pattern for matching files (e.g., "*_workflow.md", "test_*.py"). If provided, this overrides file_types. (default: :obj:`None`)+- **path** (Optional[str]): Directory to search in. If not provided, uses the working_directory. Can be relative or absolute. (default: :obj:`None`)++**Returns:**++ str: JSON-formatted string containing search results with the+structure:+`\{+"pattern": "search_pattern",+"searched_path": "/absolute/path",+"file_types": ["md", "txt"],+"file_pattern": "*_workflow.md",+"matches": [+\{+"file": "relative/path/to/file.md",+"line": 42,+"content": "matching line content"+\},+...+],+"total_matches": 10,+"files_searched": 5+\}`+If an error occurs, returns a JSON string with an "error" key.++<a id="camel.toolkits.file_toolkit.FileToolkit.get_tools"></a>++### get_tools++```python+def get_tools(self):+```++**Returns:**++ List[FunctionTool]: A list of FunctionTool objects representing+the available functions in this toolkit.+