🐫 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-botc8f7ca7d8e59
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.jsonindex dff288912..dd4ab0370 100644--- a/docs/mintlify/docs.json+++ b/docs/mintlify/docs.json@@ -488,6 +488,7 @@"reference/camel.toolkits.browser_toolkit","reference/camel.toolkits.browser_toolkit_commons","reference/camel.toolkits.code_execution",+ "reference/camel.toolkits.context_summarizer_toolkit","reference/camel.toolkits.craw4ai_toolkit","reference/camel.toolkits.dalle_toolkit","reference/camel.toolkits.dappier_toolkit",@@ -608,6 +609,7 @@"pages": ["reference/camel.utils.async_func","reference/camel.utils.commons",+ "reference/camel.utils.context_utils","reference/camel.utils.deduplication","reference/camel.utils.filename","reference/camel.utils.langfuse",diff --git a/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdx b/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdxindex 9da647e62..cc8452a97 100644--- a/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdx+++ b/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdx@@ -1,5 +1,19 @@<a id="camel.memories.blocks.chat_history_block"></a>+<a id="camel.memories.blocks.chat_history_block.EmptyMemoryWarning"></a>++## EmptyMemoryWarning++```python+class EmptyMemoryWarning(UserWarning):+```++Warning raised when attempting to access an empty memory.++This warning is raised when operations are performed on memory+that contains no records. It can be safely caught and suppressed+in contexts where empty memory is expected.+<a id="camel.memories.blocks.chat_history_block.ChatHistoryBlock"></a>## ChatHistoryBlock@@ -20,7 +34,7 @@ like to fetch.**Parameters:**- **storage** (BaseKeyValueStorage, optional): A storage mechanism for storing chat history. If `None`, an :obj:`InMemoryKeyValueStorage` will be used. (default: :obj:`None`)-- **keep_rate** (float, optional): In historical messages, the score of the last message is 1.0, and with each step taken backward, the score of the message is multiplied by the `keep_rate`. Higher `keep_rate` leads to high possibility to keep history messages during context creation.+- **keep_rate** (float, optional): In historical messages, the score of the last message is 1.0, and with each step taken backward, the score of the message is multiplied by the `keep_rate`. Higher `keep_rate` leads to high possibility to keep history messages during context creation. (default: :obj:`0.9`)<a id="camel.memories.blocks.chat_history_block.ChatHistoryBlock.__init__"></a>diff --git a/docs/mintlify/reference/camel.toolkits.context_summarizer_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.context_summarizer_toolkit.mdxnew file mode 100644index 000000000..63f6d62f0--- /dev/null+++ b/docs/mintlify/reference/camel.toolkits.context_summarizer_toolkit.mdx@@ -0,0 +1,333 @@+<a id="camel.toolkits.context_summarizer_toolkit"></a>++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit"></a>++## ContextSummarizerToolkit++```python+class ContextSummarizerToolkit(BaseToolkit):+```++A toolkit that provides intelligent context summarization and+management for agents.++This toolkit enables agents to compress conversation context through+intelligent summarization, save conversation history to markdown files,+and search through past conversations. It handles all context management+needs in a single toolkit.++Key features:+- Intelligent context compression with over-compression prevention+- Markdown file storage with session management+- Simple text-based search through conversation history+- Configurable summarization prompts+- Context loading and saving capabilities++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit.__init__"></a>++### __init__++```python+def __init__(+ self,+ agent: 'ChatAgent',+ working_directory: Optional[str] = None,+ timeout: Optional[float] = None,+ summary_prompt_template: Optional[str] = None+):+```++Initialize the ContextSummarizerToolkit.++**Parameters:**++- **agent** (ChatAgent): The agent that is using the toolkit. This is required to access the agent's memory.+- **working_directory** (str, optional): The directory path where notes will be stored. If not provided, a default directory will be used.+- **timeout** (Optional[float]): The timeout for the toolkit.+- **summary_prompt_template** (Optional[str]): Custom prompt template for summarization. If None, a default task-focused template is used. Users can customize this for different use cases.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._setup_storage"></a>++### _setup_storage++```python+def _setup_storage(self, working_directory: Optional[str]):+```++Initialize storage paths and create session-specific directories+using ContextUtility for file management.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._summarize_messages"></a>++### _summarize_messages++```python+def _summarize_messages(self, memory_records: List['MemoryRecord']):+```++Generate a summary of the conversation context.++**Parameters:**++- **memory_records** (`List["MemoryRecord"]`): A list of memory records to summarize.++**Returns:**++ str: The summary of the conversation context.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._save_summary"></a>++### _save_summary++```python+def _save_summary(self, summary: str):+```++Persist conversation summary to markdown file with metadata+including timestamp and session information.++**Parameters:**++- **summary** (str): The summary text to save.++**Returns:**++ str: Success message or error message.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._save_history"></a>++### _save_history++```python+def _save_history(self, memory_records: List['MemoryRecord']):+```++Export complete conversation transcript as formatted markdown+with message roles, agent IDs, and content structure preserved.++**Parameters:**++- **memory_records** (`List["MemoryRecord"]`): The list of memory records to save.++**Returns:**++ str: Success message or error message.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._compress_and_save"></a>++### _compress_and_save++```python+def _compress_and_save(self, memory_records: List['MemoryRecord']):+```++Complete compression pipeline: summarize and save both history and+summary.++**Parameters:**++- **memory_records** (`List["MemoryRecord"]`): The memory records to compress and save.++**Returns:**++ str: The generated summary text.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._load_summary"></a>++### _load_summary++```python+def _load_summary(self):+```++**Returns:**++ str: The summary content, or empty string if not found.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._load_history"></a>++### _load_history++```python+def _load_history(self):+```++**Returns:**++ str: The history content, or empty string if not found.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._format_conversation"></a>++### _format_conversation++```python+def _format_conversation(self, memory_records: List['MemoryRecord']):+```++Convert memory records into human-readable conversation format+with role names and message content for summarization processing.++**Parameters:**++- **memory_records** (`List["MemoryRecord"]`): A list of memory records to format.++**Returns:**++ str: The formatted conversation.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._create_summary_prompt"></a>++### _create_summary_prompt++```python+def _create_summary_prompt(self, conversation_text: str):+```++Construct detailed summarization prompt with instructions+for extracting key information, goals, and progress from conversation.++**Parameters:**++- **conversation_text** (str): The formatted conversation to summarize.++**Returns:**++ str: The complete prompt for summarization.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit.summarize_full_conversation_history"></a>++### summarize_full_conversation_history++```python+def summarize_full_conversation_history(self):+```++**Returns:**++ str: Success message with brief summary, or error message.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit._refresh_context_with_summary"></a>++### _refresh_context_with_summary++```python+def _refresh_context_with_summary(self, summary: str):+```++Empty the agent's memory and replace it with a summary+of the conversation history.++**Parameters:**++- **summary** (str): The summary of the conversation history.++**Returns:**++ bool: True if the context was refreshed successfully, False+otherwise.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit.get_conversation_memory_info"></a>++### get_conversation_memory_info++```python+def get_conversation_memory_info(self):+```++**Returns:**++ str: Information about current memory and saved files.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit.search_full_conversation_history"></a>++### search_full_conversation_history++```python+def search_full_conversation_history(self, keywords: List[str], top_k: int = 4):+```++Search the conversation history using keyword matching. This is+used when information is missing from the summary and the current+conversation, and can potentially be found in the full conversation+history before it was summarized.++Searches through the current session's history.md file to find the+top messages that contain the most keywords.++**Parameters:**++- **keywords** (List[str]): List of keywords to search for. The keywords must be explicitly related to the information the user is looking for, and not general terms that might be found about any topic. For example, if the user is searching for the price of the flight to "Paris" which was discussed previously, the keywords should be ["Paris", "price", "flight", "$", "costs"].+- **top_k** (int): The number of results to return (default 4).++**Returns:**++ str: The search results or error message.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit.should_compress_context"></a>++### should_compress_context++```python+def should_compress_context(self, message_limit: int = 40, token_limit: Optional[int] = None):+```++Check if context should be compressed based on limits.++**Parameters:**++- **message_limit** (int): Maximum number of messages before compression.+- **token_limit** (Optional[int]): Maximum number of tokens before compression.++**Returns:**++ bool: True if context should be compressed.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit.reset"></a>++### reset++```python+def reset(self):+```++Clear all compression state including stored summaries,+compressed message tracking, and compression counters.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit.get_current_summary"></a>++### get_current_summary++```python+def get_current_summary(self):+```++**Returns:**++ Optional[str]: The current summary, or None if no summary exists.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit.set_summary"></a>++### set_summary++```python+def set_summary(self, summary: str):+```++Override the current in-memory summary with provided content+without affecting saved files or compression tracking.++**Parameters:**++- **summary** (str): The summary to store.++<a id="camel.toolkits.context_summarizer_toolkit.ContextSummarizerToolkit.get_tools"></a>++### get_tools++```python+def get_tools(self):+```++**Returns:**++ List[FunctionTool]: The list of tools.diff --git a/docs/mintlify/reference/camel.toolkits.note_taking_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.note_taking_toolkit.mdxindex 33f5aa110..bd287f026 100644--- a/docs/mintlify/reference/camel.toolkits.note_taking_toolkit.mdx+++ b/docs/mintlify/reference/camel.toolkits.note_taking_toolkit.mdx@@ -92,25 +92,33 @@ Register a new note in the registry with thread-safe operations.### create_note```python-def create_note(self, note_name: str, content: str):+def create_note(+ self,+ note_name: str,+ content: str,+ overwrite: bool = False+):```Creates a new note with a unique name.This function will create a new file for your note.-You must provide a `note_name` that does not already exist. If you want-to add content to an existing note, use the `append_note` function-instead.+By default, you must provide a `note_name` that does not already exist.+If you want to add content to an existing note, use the `append_note`+function instead. If you want to overwrite an existing note, set+`overwrite=True`.**Parameters:**-- **note_name** (str): The name for your new note (without the .md extension). This name must be unique.+- **note_name** (str): The name for your new note (without the .md extension). This name must be unique unless overwrite is True.- **content** (str): The initial content to write in the note.+- **overwrite** (bool): Whether to overwrite an existing note. Defaults to False.**Returns:**str: A message confirming the creation of the note or an error if-the note name is not valid or already exists.+the note name is not valid or already exists+(when overwrite=False).<a id="camel.toolkits.note_taking_toolkit.NoteTakingToolkit.list_note"></a>diff --git a/docs/mintlify/reference/camel.utils.context_utils.mdx b/docs/mintlify/reference/camel.utils.context_utils.mdxnew file mode 100644index 000000000..a3973dc80--- /dev/null+++ b/docs/mintlify/reference/camel.utils.context_utils.mdx@@ -0,0 +1,295 @@+<a id="camel.utils.context_utils"></a>++<a id="camel.utils.context_utils.ContextUtility"></a>++## ContextUtility++```python+class ContextUtility:+```++Utility class for context management and file operations.++This utility provides generic functionality for managing context files,+markdown generation, and session management that can be used by+context-related features.++Key features:+- Session-based directory management+- Generic markdown file operations+- Text-based search through files+- File metadata handling+- Agent memory record retrieval++<a id="camel.utils.context_utils.ContextUtility.__init__"></a>++### __init__++```python+def __init__(self, working_directory: Optional[str] = None):+```++Initialize the ContextUtility.++**Parameters:**++- **working_directory** (str, optional): The directory path where files will be stored. If not provided, a default directory will be used.++<a id="camel.utils.context_utils.ContextUtility._setup_storage"></a>++### _setup_storage++```python+def _setup_storage(self, working_directory: Optional[str]):+```++Initialize session-specific storage paths and create directory+structure for context file management.++<a id="camel.utils.context_utils.ContextUtility._generate_session_id"></a>++### _generate_session_id++```python+def _generate_session_id(self):+```++Create timestamp-based unique identifier for isolating+current session files from other sessions.++<a id="camel.utils.context_utils.ContextUtility._create_or_update_note"></a>++### _create_or_update_note++```python+def _create_or_update_note(self, note_name: str, content: str):+```++Write content to markdown file, creating new file or+overwriting existing one with UTF-8 encoding.++**Parameters:**++- **note_name** (str): Name of the note (without .md extension).+- **content** (str): Content to write to the note.++**Returns:**++ str: Success message.++<a id="camel.utils.context_utils.ContextUtility.save_markdown_file"></a>++### save_markdown_file++```python+def save_markdown_file(+ self,+ filename: str,+ content: str,+ title: Optional[str] = None,+ metadata: Optional[Dict[str, Any]] = None+):+```++Generic method to save any markdown content to a file.++**Parameters:**++- **filename** (str): Name without .md extension.+- **content** (str): Main content to save.+- **title** (str, optional): Title for the markdown file.+- **metadata** (Dict, optional): Additional metadata to include.++**Returns:**++ str: Success message or error message.++<a id="camel.utils.context_utils.ContextUtility.load_markdown_file"></a>++### load_markdown_file++```python+def load_markdown_file(self, filename: str):+```++Generic method to load any markdown file.++**Parameters:**++- **filename** (str): Name without .md extension.++**Returns:**++ str: File content or empty string if not found.++<a id="camel.utils.context_utils.ContextUtility.file_exists"></a>++### file_exists++```python+def file_exists(self, filename: str):+```++Verify presence of markdown file in current session directory.++**Parameters:**++- **filename** (str): Name without .md extension.++**Returns:**++ bool: True if file exists, False otherwise.++<a id="camel.utils.context_utils.ContextUtility.list_markdown_files"></a>++### list_markdown_files++```python+def list_markdown_files(self):+```++**Returns:**++ List[str]: List of filenames without .md extension.++<a id="camel.utils.context_utils.ContextUtility.get_agent_memory_records"></a>++### get_agent_memory_records++```python+def get_agent_memory_records(self, agent: 'ChatAgent'):+```++Retrieve conversation history from agent's memory system.++**Parameters:**++- **agent** (ChatAgent): The agent to extract memory records from.++**Returns:**++ List[MemoryRecord]: List of memory records from the agent.++<a id="camel.utils.context_utils.ContextUtility.format_memory_as_conversation"></a>++### format_memory_as_conversation++```python+def format_memory_as_conversation(self, memory_records: List['MemoryRecord']):+```++Transform structured memory records into human-readable+conversation format with role labels and message content.++**Parameters:**++- **memory_records** (List[MemoryRecord]): Memory records to format.++**Returns:**++ str: Formatted conversation text.++<a id="camel.utils.context_utils.ContextUtility.create_session_directory"></a>++### create_session_directory++```python+def create_session_directory(+ self,+ base_dir: Optional[str] = None,+ session_id: Optional[str] = None+):+```++Create a session-specific directory.++**Parameters:**++- **base_dir** (str, optional): Base directory. If None, uses current working directory.+- **session_id** (str, optional): Custom session ID. If None, generates new one.++**Returns:**++ Path: The created session directory path.++<a id="camel.utils.context_utils.ContextUtility.get_session_metadata"></a>++### get_session_metadata++```python+def get_session_metadata(self):+```++**Returns:**++ Dict[str, Any]: Session metadata including ID, timestamp,+directory.++<a id="camel.utils.context_utils.ContextUtility.list_sessions"></a>++### list_sessions++```python+def list_sessions(self, base_dir: Optional[str] = None):+```++Discover all available session directories for browsing+historical conversations and context files.++**Parameters:**++- **base_dir** (str, optional): Base directory to search. If None, uses parent of working directory.++**Returns:**++ List[str]: List of session directory names.++<a id="camel.utils.context_utils.ContextUtility.search_in_file"></a>++### search_in_file++```python+def search_in_file(+ self,+ file_path: Path,+ keywords: List[str],+ top_k: int = 4+):+```++Perform keyword-based search through file sections,+ranking results by keyword frequency and returning top matches.++**Parameters:**++- **file_path** (Path): Path to the file to search.+- **keywords** (List[str]): Keywords to search for.+- **top_k** (int): Maximum number of results to return.++**Returns:**++ str: Formatted search results.++<a id="camel.utils.context_utils.ContextUtility.get_working_directory"></a>++### get_working_directory++```python+def get_working_directory(self):+```++**Returns:**++ Path: The working directory path.++<a id="camel.utils.context_utils.ContextUtility.get_session_id"></a>++### get_session_id++```python+def get_session_id(self):+```++**Returns:**++ str: The session ID.