Auto-update documentation after merge [skip ci]

Author: camel-docs-bot

docs/mintlify/reference/camel.agents.chat_agent.mdx

@@ -897,6 +897,31 @@ response_format was provided.
 See Also:
 :meth:`asummarize`: Async version for non-blocking LLM calls.
 
+<a id="camel.agents.chat_agent.ChatAgent._build_conversation_text_from_messages"></a>
+
+### _build_conversation_text_from_messages
+
+```python
+def _build_conversation_text_from_messages(self, messages: List[Any], include_summaries: bool = False):
+```
+
+Build conversation text from messages for summarization.
+
+This is a shared helper method that converts messages to a formatted
+conversation text string, handling tool calls, tool results, and
+regular messages.
+
+**Parameters:**
+
+- **messages** (List[Any]): List of messages to convert.
+- **include_summaries** (bool): Whether to include messages starting with [CONTEXT_SUMMARY]. (default: :obj:`False`)
+
+**Returns:**
+
+  tuple[str, List[str]]: A tuple containing:
+- Formatted conversation text
+- List of user messages extracted from the conversation
+
 <a id="camel.agents.chat_agent.ChatAgent.clear_memory"></a>
 
 ### clear_memory

docs/mintlify/reference/camel.societies.workforce.utils.mdx

@@ -1,5 +1,56 @@
 <a id="camel.societies.workforce.utils"></a>
 
+<a id="camel.societies.workforce.utils.is_generic_role_name"></a>
+
+## is_generic_role_name
+
+```python
+def is_generic_role_name(role_name: str):
+```
+
+Check if a role name is generic and should trigger fallback logic.
+
+Generic role names are common, non-specific identifiers that don't
+provide meaningful information about an agent's actual purpose.
+When a role name is generic, fallback logic should be used to find
+a more specific identifier (e.g., from LLM-generated agent_title
+or description).
+
+**Parameters:**
+
+- **role_name** (str): The role name to check (will be converted to lowercase for case-insensitive comparison).
+
+**Returns:**
+
+  bool: True if the role name is generic, False otherwise.
+
+<a id="camel.societies.workforce.utils.WorkflowMetadata"></a>
+
+## WorkflowMetadata
+
+```python
+class WorkflowMetadata(BaseModel):
+```
+
+Pydantic model for workflow metadata tracking.
+
+This model defines the formal schema for workflow metadata that tracks
+versioning, timestamps, and contextual information about saved workflows.
+Used to maintain workflow history and enable proper version management.
+
+<a id="camel.societies.workforce.utils.WorkflowConfig"></a>
+
+## WorkflowConfig
+
+```python
+class WorkflowConfig(BaseModel):
+```
+
+Configuration for workflow memory management.
+
+Centralizes all workflow-related configuration options to avoid scattered
+settings across multiple files and methods.
+
 <a id="camel.societies.workforce.utils.WorkerConf"></a>
 
 ## WorkerConf

docs/mintlify/reference/camel.societies.workforce.workflow_memory_manager.mdx

@@ -37,6 +37,8 @@ workflow management concerns from the core worker task processing logic.
 - **worker** (ChatAgent): The worker agent that will use workflows.
 - **description** (str): Description of the worker's role.
 - **context_utility** (Optional[ContextUtility]): Shared context utility for workflow operations. If None, creates a new instance.
+- **role_identifier** (Optional[str]): Role identifier for organizing workflows by role. If provided, workflows will be stored in role-based folders. If None, uses default workforce context.
+- **config** (Optional[WorkflowConfig]): Configuration for workflow management. If None, uses default configuration.
 
 <a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager.__init__"></a>
 
@@ -47,7 +49,9 @@ def __init__(
     self,
     worker: ChatAgent,
     description: str,
-    context_utility: Optional[ContextUtility] = None
+    context_utility: Optional[ContextUtility] = None,
+    role_identifier: Optional[str] = None,
+    config: Optional[WorkflowConfig] = None
 ):
 ```
 
@@ -61,6 +65,132 @@ def _get_context_utility(self):
 
 Get context utility with lazy initialization.
 
+Uses role-based context if role_identifier is set, otherwise falls
+back to default workforce shared context.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._extract_existing_workflow_metadata"></a>
+
+### _extract_existing_workflow_metadata
+
+```python
+def _extract_existing_workflow_metadata(self, file_path: Path):
+```
+
+Extract metadata from an existing workflow file for versioning.
+
+This method reads the metadata section from an existing workflow
+markdown file to retrieve version number and creation timestamp,
+enabling proper version tracking when updating workflows.
+
+**Parameters:**
+
+- **file_path** (Path): Path to the existing workflow file.
+
+**Returns:**
+
+  Optional[WorkflowMetadata]: WorkflowMetadata instance if file
+exists and metadata is successfully parsed, None otherwise.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._try_role_based_loading"></a>
+
+### _try_role_based_loading
+
+```python
+def _try_role_based_loading(
+    self,
+    role_name: str,
+    pattern: Optional[str],
+    max_files_to_load: int,
+    use_smart_selection: bool
+):
+```
+
+Try loading workflows from role-based directory structure.
+
+**Parameters:**
+
+- **role_name** (str): Role name to load workflows from.
+- **pattern** (Optional[str]): Custom search pattern for workflow files.
+- **max_files_to_load** (int): Maximum number of workflow files to load.
+- **use_smart_selection** (bool): Whether to use agent-based selection.
+
+**Returns:**
+
+  bool: True if workflows were successfully loaded, False otherwise.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._try_session_based_loading"></a>
+
+### _try_session_based_loading
+
+```python
+def _try_session_based_loading(
+    self,
+    session_id: str,
+    role_name: str,
+    pattern: Optional[str],
+    max_files_to_load: int,
+    use_smart_selection: bool
+):
+```
+
+Try loading workflows from session-based directory (deprecated).
+
+**Parameters:**
+
+- **session_id** (str): Workforce session ID to load from.
+- **role_name** (str): Role name (for deprecation warning).
+- **pattern** (Optional[str]): Custom search pattern for workflow files.
+- **max_files_to_load** (int): Maximum number of workflow files to load.
+- **use_smart_selection** (bool): Whether to use agent-based selection.
+
+**Returns:**
+
+  bool: True if workflows were successfully loaded, False otherwise.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._session_based_smart_loading"></a>
+
+### _session_based_smart_loading
+
+```python
+def _session_based_smart_loading(self, session_id: str, max_files_to_load: int):
+```
+
+Load workflows from session using smart selection.
+
+**Parameters:**
+
+- **session_id** (str): Session ID to load from.
+- **max_files_to_load** (int): Maximum number of files to load.
+
+**Returns:**
+
+  bool: True if workflows were loaded, False otherwise.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._session_based_pattern_loading"></a>
+
+### _session_based_pattern_loading
+
+```python
+def _session_based_pattern_loading(
+    self,
+    pattern: Optional[str],
+    session_id: str,
+    max_files_to_load: int
+):
+```
+
+Load workflows from session using pattern matching.
+
+**Parameters:**
+
+- **pattern** (Optional[str]): Pattern for file matching.
+- **session_id** (str): Session ID to load from.
+- **max_files_to_load** (int): Maximum number of files to load.
+
+**Returns:**
+
+  bool: True if workflows were loaded, False otherwise.
+
 <a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager.load_workflows"></a>
 
 ### load_workflows
@@ -69,23 +199,54 @@ Get context utility with lazy initialization.
 def load_workflows(
     self,
     pattern: Optional[str] = None,
-    max_files_to_load: int = 3,
+    max_files_to_load: Optional[int] = None,
     session_id: Optional[str] = None,
     use_smart_selection: bool = True
 ):
 ```
 
 Load workflow memories using intelligent agent-based selection.
 
-This method uses the worker agent to intelligently select the most
-relevant workflows based on workflow information (title, description,
-tags) rather than simple filename pattern matching.
+This method first tries to load workflows from the role-based folder
+structure. If no workflows are found and session_id is provided, falls
+back to session-based loading (deprecated).
 
 **Parameters:**
 
 - **pattern** (Optional[str]): Legacy parameter for backward compatibility. When use_smart_selection=False, uses this pattern for file matching. Ignored when smart selection is enabled.
-- **max_files_to_load** (int): Maximum number of workflow files to load. (default: :obj:`3`)
-- **session_id** (Optional[str]): Specific workforce session ID to load from. If None, searches across all sessions. (default: :obj:`None`)
+- **max_files_to_load** (Optional[int]): Maximum number of workflow files to load. If None, uses config.default_max_files_to_load. (default: :obj:`None`)
+- **session_id** (Optional[str]): Deprecated. Specific workforce session ID to load from using legacy session-based organization. (default: :obj:`None`)
+- **use_smart_selection** (bool): Whether to use agent-based intelligent workflow selection. When True, uses workflow information and LLM to select most relevant workflows. When False, falls back to pattern matching. (default: :obj:`True`)
+
+**Returns:**
+
+  bool: True if workflow memories were successfully loaded, False
+otherwise. Check logs for detailed error messages.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager.load_workflows_by_role"></a>
+
+### load_workflows_by_role
+
+```python
+def load_workflows_by_role(
+    self,
+    role_name: Optional[str] = None,
+    pattern: Optional[str] = None,
+    max_files_to_load: Optional[int] = None,
+    use_smart_selection: bool = True
+):
+```
+
+Load workflow memories from role-based directory structure.
+
+This method loads workflows from the new role-based folder structure:
+workforce_workflows/\{role_name\}/*.md
+
+**Parameters:**
+
+- **role_name** (Optional[str]): Role name to load workflows from. If None, uses the worker's role_name or role_identifier.
+- **pattern** (Optional[str]): Custom search pattern for workflow files. Ignored when use_smart_selection=True.
+- **max_files_to_load** (Optional[int]): Maximum number of workflow files to load. If None, uses config.default_max_files_to_load. (default: :obj:`None`)
 - **use_smart_selection** (bool): Whether to use agent-based intelligent workflow selection. When True, uses workflow information and LLM to select most relevant workflows. When False, falls back to pattern matching. (default: :obj:`True`)
 
 **Returns:**
@@ -177,6 +338,11 @@ def _find_workflow_files(self, pattern: Optional[str], session_id: Optional[str]
 
 Find and return sorted workflow files matching the pattern.
 
+.. note::
+Session-based workflow search will be deprecated in a future
+version. Consider using :meth:`_find_workflow_files_by_role` for
+role-based organization instead.
+
 **Parameters:**
 
 - **pattern** (Optional[str]): Custom search pattern for workflow files. If None, uses worker role_name to generate pattern.
@@ -187,6 +353,33 @@ Find and return sorted workflow files matching the pattern.
   List[str]: Sorted list of workflow file paths (empty if
 validation fails).
 
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._find_workflow_files_by_role"></a>
+
+### _find_workflow_files_by_role
+
+```python
+def _find_workflow_files_by_role(
+    self,
+    role_name: Optional[str] = None,
+    pattern: Optional[str] = None
+):
+```
+
+Find workflow files in role-based directory structure.
+
+This method searches for workflows in the new role-based folder
+structure: workforce_workflows/\{role_name\}/*.md
+
+**Parameters:**
+
+- **role_name** (Optional[str]): Role name to search for. If None, uses the worker's role_name or role_identifier.
+- **pattern** (Optional[str]): Custom search pattern for workflow files. If None, searches for all workflow files in the role directory.
+
+**Returns:**
+
+  List[str]: Sorted list of workflow file paths by modification time
+(most recent first).
+
 <a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._collect_workflow_contents"></a>
 
 ### _collect_workflow_contents
@@ -287,7 +480,7 @@ def _generate_workflow_filename(self):
 **Returns:**
 
   str: Sanitized filename without timestamp and without .md
-extension. Format: \{role_name\}_workflow
+extension. Format: \{role_name\}\{workflow_filename_suffix\}
 
 <a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._prepare_workflow_prompt"></a>