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

camel-docs-botb48b44f24b0f
diff --git a/docs/reference/camel.environments.rlcards_env.md b/docs/reference/camel.environments.rlcards_env.md
new file mode 100644
index 000000000..103d76ac7
--- /dev/null
+++ b/docs/reference/camel.environments.rlcards_env.md
@@ -0,0 +1,495 @@
+<a id="camel.environments.rlcards_env"></a>
+
+<a id="camel.environments.rlcards_env.ActionExtractor"></a>
+
+## ActionExtractor
+
+```python
+class ActionExtractor(BaseExtractorStrategy):
+```
+
+A strategy for extracting RLCard actions from text.
+
+<a id="camel.environments.rlcards_env.ActionExtractor.__init__"></a>
+
+### __init__
+
+```python
+def __init__(self, action_pattern: str = '<Action>\\s*(.+)'):
+```
+
+Initialize the action extractor with a regex pattern.
+
+**Parameters:**
+
+- **action_pattern** (str): The regex pattern to extract actions. (default: :obj:`"<Action>\\s*(.+)"`).
+
+<a id="camel.environments.rlcards_env.RLCardsEnv"></a>
+
+## RLCardsEnv
+
+```python
+class RLCardsEnv(MultiStepEnv):
+```
+
+A base environment for RLCard games.
+
+This environment implements a wrapper around RLCard environments for
+reinforcement learning with LLMs. It handles the conversion between
+RLCard states and actions and the CAMEL environment interface.
+
+<a id="camel.environments.rlcards_env.RLCardsEnv.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ game_name: str,
+ extractor: Optional[BaseExtractor] = None,
+ max_steps: Optional[int] = None,
+ num_players: int = 2,
+ **kwargs
+):
+```
+
+Initialize the RLCard environment.
+
+**Parameters:**
+
+- **game_name** (str): The name of the RLCard game to play.
+- **extractor** (Optional[BaseExtractor]): Extractor to process LLM responses. If None, a default extractor with ActionExtractor will be used. (default: :obj:`None`)
+- **max_steps** (Optional[int]): Maximum steps per episode. (default: :obj:`None`)
+- **num_players** (int): Number of players in the game. (default: :obj:`2`) **kwargs: Additional environment parameters.
+
+<a id="camel.environments.rlcards_env.RLCardsEnv._get_initial_state"></a>
+
+### _get_initial_state
+
+```python
+def _get_initial_state(self):
+```
+
+**Returns:**
+
+ Dict[str, Any]: A dictionary containing the initial state with
+game state, player info, and game status flags.
+
+<a id="camel.environments.rlcards_env.RLCardsEnv._get_next_observation"></a>
+
+### _get_next_observation
+
+```python
+def _get_next_observation(self):
+```
+
+**Returns:**
+
+ Observation: An Observation object containing the game state
+description.
+
+<a id="camel.environments.rlcards_env.RLCardsEnv._get_terminal_observation"></a>
+
+### _get_terminal_observation
+
+```python
+def _get_terminal_observation(self):
+```
+
+**Returns:**
+
+ Observation: An Observation object containing the final game state
+description.
+
+<a id="camel.environments.rlcards_env.RLCardsEnv._is_done"></a>
+
+### _is_done
+
+```python
+def _is_done(self):
+```
+
+**Returns:**
+
+ bool: True if the game is over, False otherwise.
+
+<a id="camel.environments.rlcards_env.RLCardsEnv._convert_to_rlcard_action"></a>
+
+### _convert_to_rlcard_action
+
+```python
+def _convert_to_rlcard_action(self, action_str: str):
+```
+
+Convert a string action to the format expected by RLCard.
+
+This method must be implemented by subclasses to handle the specific
+action format of each game.
+
+**Parameters:**
+
+- **action_str** (str): The string representation of the action.
+
+**Returns:**
+
+ Any: The action in the format expected by the RLCard environment.
+
+<a id="camel.environments.rlcards_env.RLCardsEnv._format_state_for_observation"></a>
+
+### _format_state_for_observation
+
+```python
+def _format_state_for_observation(self, state: Dict[str, Any]):
+```
+
+Format the RLCard state for human-readable observation.
+
+This method must be implemented by subclasses to create a
+human-readable representation of the game state.
+
+**Parameters:**
+
+- **state** (Dict[str, Any]): The RLCard state dictionary.
+
+**Returns:**
+
+ str: A human-readable representation of the state.
+
+<a id="camel.environments.rlcards_env.RLCardsEnv._format_legal_actions"></a>
+
+### _format_legal_actions
+
+```python
+def _format_legal_actions(self, legal_actions: List[Any]):
+```
+
+Format the legal actions for human-readable observation.
+
+This method must be implemented by subclasses to create a
+human-readable representation of the legal actions.
+
+**Parameters:**
+
+- **legal_actions** (List[Any]): The list of legal actions.
+
+**Returns:**
+
+ str: A human-readable representation of the legal actions.
+
+<a id="camel.environments.rlcards_env.BlackjackEnv"></a>
+
+## BlackjackEnv
+
+```python
+class BlackjackEnv(RLCardsEnv):
+```
+
+A Blackjack environment for reinforcement learning with LLMs.
+
+This environment implements a standard Blackjack game where the LLM agent
+plays against a dealer.
+
+<a id="camel.environments.rlcards_env.BlackjackEnv.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ extractor: Optional[BaseExtractor] = None,
+ max_steps: Optional[int] = None,
+ **kwargs
+):
+```
+
+Initialize the Blackjack environment.
+
+**Parameters:**
+
+- **extractor** (Optional[BaseExtractor]): Extractor to process LLM responses. If None, a default extractor will be used. (default: :obj:`None`)
+- **max_steps** (Optional[int]): Maximum steps per episode. (default: :obj:`None`) **kwargs: Additional environment parameters.
+
+<a id="camel.environments.rlcards_env.BlackjackEnv._convert_to_rlcard_action"></a>
+
+### _convert_to_rlcard_action
+
+```python
+def _convert_to_rlcard_action(self, action_str: str):
+```
+
+Convert a string action to the format expected by RLCard Blackjack.
+
+**Parameters:**
+
+- **action_str** (str): The string representation of the action. Expected to be 'hit' or 'stand'.
+
+**Returns:**
+
+ int: 0 for 'hit', 1 for 'stand'.
+
+<a id="camel.environments.rlcards_env.BlackjackEnv._format_state_for_observation"></a>
+
+### _format_state_for_observation
+
+```python
+def _format_state_for_observation(self, state: Dict[str, Any]):
+```
+
+Format the Blackjack state for human-readable observation.
+
+**Parameters:**
+
+- **state** (Dict[str, Any]): The RLCard state dictionary.
+
+**Returns:**
+
+ str: A human-readable representation of the state.
+
+<a id="camel.environments.rlcards_env.BlackjackEnv._format_legal_actions"></a>
+
+### _format_legal_actions
+
+```python
+def _format_legal_actions(self, legal_actions: List[int]):
+```
+
+Format the legal actions for Blackjack.
+
+**Parameters:**
+
+- **legal_actions** (List[int]): The list of legal actions.
+
+**Returns:**
+
+ str: A human-readable representation of the legal actions.
+
+<a id="camel.environments.rlcards_env.BlackjackEnv._format_cards"></a>
+
+### _format_cards
+
+```python
+def _format_cards(self, cards: List[str]):
+```
+
+Format a list of cards for display.
+
+**Parameters:**
+
+- **cards** (List[str]): List of card strings.
+
+**Returns:**
+
+ str: Formatted card string.
+
+<a id="camel.environments.rlcards_env.BlackjackEnv._calculate_hand_value"></a>
+
+### _calculate_hand_value
+
+```python
+def _calculate_hand_value(self, cards: List[str]):
+```
+
+Calculate the value of a hand in Blackjack.
+
+**Parameters:**
+
+- **cards** (List[str]): List of card strings.
+
+**Returns:**
+
+ int: The value of the hand.
+
+<a id="camel.environments.rlcards_env.LeducHoldemEnv"></a>
+
+## LeducHoldemEnv
+
+```python
+class LeducHoldemEnv(RLCardsEnv):
+```
+
+A Leduc Hold'em environment for reinforcement learning with LLMs.
+
+This environment implements a Leduc Hold'em poker game where the LLM agent
+plays against one or more opponents.
+
+<a id="camel.environments.rlcards_env.LeducHoldemEnv.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ extractor: Optional[BaseExtractor] = None,
+ max_steps: Optional[int] = None,
+ num_players: int = 2,
+ **kwargs
+):
+```
+
+Initialize the Leduc Hold'em environment.
+
+**Parameters:**
+
+- **extractor** (Optional[BaseExtractor]): Extractor to process LLM responses. If None, a default extractor will be used. (default: :obj:`None`)
+- **max_steps** (Optional[int]): Maximum steps per episode. (default: :obj:`None`)
+- **num_players** (int): Number of players in the game. (default: :obj:`2`) **kwargs: Additional environment parameters.
+
+<a id="camel.environments.rlcards_env.LeducHoldemEnv._convert_to_rlcard_action"></a>
+
+### _convert_to_rlcard_action
+
+```python
+def _convert_to_rlcard_action(self, action_str: str):
+```
+
+Convert a string action to the format expected by RLCard
+Leduc Hold'em.
+
+**Parameters:**
+
+- **action_str** (str): The string representation of the action. Expected to be 'fold', 'check', 'call', or 'raise'.
+
+**Returns:**
+
+ int: 0 for 'fold', 1 for 'check/call', 2 for 'raise'.
+
+<a id="camel.environments.rlcards_env.LeducHoldemEnv._format_state_for_observation"></a>
+
+### _format_state_for_observation
+
+```python
+def _format_state_for_observation(self, state: Dict[str, Any]):
+```
+
+Format the Leduc Hold'em state for human-readable observation.
+
+**Parameters:**
+
+- **state** (Dict[str, Any]): The RLCard state dictionary.
+
+**Returns:**
+
+ str: A human-readable representation of the state.
+
+<a id="camel.environments.rlcards_env.LeducHoldemEnv._format_legal_actions"></a>
+
+### _format_legal_actions
+
+```python
+def _format_legal_actions(self, legal_actions: List[int]):
+```
+
+Format the legal actions for Leduc Hold'em.
+
+**Parameters:**
+
+- **legal_actions** (List[int]): The list of legal actions.
+
+**Returns:**
+
+ str: A human-readable representation of the legal actions.
+
+<a id="camel.environments.rlcards_env.DoudizhuEnv"></a>
+
+## DoudizhuEnv
+
+```python
+class DoudizhuEnv(RLCardsEnv):
+```
+
+A Doudizhu environment for reinforcement learning with LLMs.
+
+This environment implements a standard Doudizhu game where the LLM agent
+plays against two AI opponents.
+
+<a id="camel.environments.rlcards_env.DoudizhuEnv.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ extractor: Optional[BaseExtractor] = None,
+ max_steps: Optional[int] = None,
+ **kwargs
+):
+```
+
+Initialize the Doudizhu environment.
+
+**Parameters:**
+
+- **extractor** (Optional[BaseExtractor]): Extractor to process LLM responses. If None, a default extractor will be used. (default: :obj:`None`)
+- **max_steps** (Optional[int]): Maximum steps per episode. (default: :obj:`None`) **kwargs: Additional environment parameters.
+
+<a id="camel.environments.rlcards_env.DoudizhuEnv._convert_to_rlcard_action"></a>
+
+### _convert_to_rlcard_action
+
+```python
+def _convert_to_rlcard_action(self, action_str: str):
+```
+
+Convert a string action to the format expected by RLCard Doudizhu.
+
+**Parameters:**
+
+- **action_str** (str): The string representation of the action. Expected to be a card combination or 'pass'.
+
+**Returns:**
+
+ str: The action string in the format expected by RLCard.
+
+<a id="camel.environments.rlcards_env.DoudizhuEnv._format_state_for_observation"></a>
+
+### _format_state_for_observation
+
+```python
+def _format_state_for_observation(self, state: Dict[str, Any]):
+```
+
+Format the Doudizhu state for human-readable observation.
+
+**Parameters:**
+
+- **state** (Dict[str, Any]): The RLCard state dictionary.
+
+**Returns:**
+
+ str: A human-readable representation of the state.
+
+<a id="camel.environments.rlcards_env.DoudizhuEnv._format_legal_actions"></a>
+
+### _format_legal_actions
+
+```python
+def _format_legal_actions(self, legal_actions: List[str]):
+```
+
+Format the legal actions for Doudizhu.
+
+**Parameters:**
+
+- **legal_actions** (List[str]): The list of legal actions.
+
+**Returns:**
+
+ str: A human-readable representation of the legal actions.
+
+<a id="camel.environments.rlcards_env.DoudizhuEnv._format_cards"></a>
+
+### _format_cards
+
+```python
+def _format_cards(self, cards: List[str]):
+```
+
+Format a list of cards for display.
+
+**Parameters:**
+
+- **cards** (List[str]): List of card strings.
+
+**Returns:**
+
+ str: Formatted card string.
diff --git a/docs/reference/camel.societies.workforce.single_agent_worker.md b/docs/reference/camel.societies.workforce.single_agent_worker.md
new file mode 100644
index 000000000..1dc83058b
--- /dev/null
+++ b/docs/reference/camel.societies.workforce.single_agent_worker.md
@@ -0,0 +1,40 @@
+<a id="camel.societies.workforce.single_agent_worker"></a>
+
+<a id="camel.societies.workforce.single_agent_worker.SingleAgentWorker"></a>
+
+## SingleAgentWorker
+
+```python
+class SingleAgentWorker(Worker):
+```
+
+A worker node that consists of a single agent.
+
+**Parameters:**
+
+- **description** (str): Description of the node.
+- **worker** (ChatAgent): Worker of the node. A single agent.
+- **max_concurrent_tasks** (int): Maximum number of tasks this worker can process concurrently. (default: :obj:`10`)
+
+<a id="camel.societies.workforce.single_agent_worker.SingleAgentWorker.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ description: str,
+ worker: ChatAgent,
+ max_concurrent_tasks: int = 10
+):
+```
+
+<a id="camel.societies.workforce.single_agent_worker.SingleAgentWorker.reset"></a>
+
+### reset
+
+```python
+def reset(self):
+```
+
+Resets the worker to its initial state.
diff --git a/docs/reference/camel.societies.workforce.task_channel.md b/docs/reference/camel.societies.workforce.task_channel.md
new file mode 100644
index 000000000..9565e51e9
--- /dev/null
+++ b/docs/reference/camel.societies.workforce.task_channel.md
@@ -0,0 +1,80 @@
+<a id="camel.societies.workforce.task_channel"></a>
+
+<a id="camel.societies.workforce.task_channel.PacketStatus"></a>
+
+## PacketStatus
+
+```python
+class PacketStatus(Enum):
+```
+
+The status of a packet. The packet can be in one of the following
+states:
+
+- `__INLINE_CODE_0__`: The packet has been sent to a worker.
+- `__INLINE_CODE_1__`: The packet has been claimed by a worker and is being
+processed.
+- `__INLINE_CODE_2__`: The packet has been returned by the worker, meaning that
+the status of the task inside has been updated.
+- `__INLINE_CODE_3__`: The packet has been archived, meaning that the content of
+the task inside will not be changed. The task is considered
+as a dependency.
+
+<a id="camel.societies.workforce.task_channel.Packet"></a>
+
+## Packet
+
+```python
+class Packet:
+```
+
+The basic element inside the channel. A task is wrapped inside a
+packet. The packet will contain the task, along with the task's assignee,
+and the task's status.
+
+**Parameters:**
+
+- **task** (Task): The task that is wrapped inside the packet.
+- **publisher_id** (str): The ID of the workforce that published the task.
+- **assignee_id** (Optional[str], optional): The ID of the workforce that is assigned to the task. Would be None if the task is a dependency. Defaults to None.
+- **status** (PacketStatus): The status of the task.
+
+<a id="camel.societies.workforce.task_channel.Packet.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ task: Task,
+ publisher_id: str,
+ assignee_id: Optional[str] = None,
+ status: PacketStatus = PacketStatus.SENT
+):
+```
+
+<a id="camel.societies.workforce.task_channel.Packet.__repr__"></a>
+
+### __repr__
+
+```python
+def __repr__(self):
+```
+
+<a id="camel.societies.workforce.task_channel.TaskChannel"></a>
+
+## TaskChannel
+
+```python
+class TaskChannel:
+```
+
+An internal class used by Workforce to manage tasks.
+
+<a id="camel.societies.workforce.task_channel.TaskChannel.__init__"></a>
+
+### __init__
+
+```python
+def __init__(self):
+```
diff --git a/docs/reference/camel.societies.workforce.worker.md b/docs/reference/camel.societies.workforce.worker.md
new file mode 100644
index 000000000..1db57550e
--- /dev/null
+++ b/docs/reference/camel.societies.workforce.worker.md
@@ -0,0 +1,65 @@
+<a id="camel.societies.workforce.worker"></a>
+
+<a id="camel.societies.workforce.worker.Worker"></a>
+
+## Worker
+
+```python
+class Worker(BaseNode, ABC):
+```
+
+A worker node that works on tasks. It is the basic unit of task
+processing in the workforce system.
+
+**Parameters:**
+
+- **description** (str): Description of the node.
+- **node_id** (Optional[str]): ID of the node. If not provided, it will be generated automatically. (default: :obj:`None`)
+- **max_concurrent_tasks** (int): Maximum number of tasks this worker can process concurrently. (default: :obj:`10`)
+
+<a id="camel.societies.workforce.worker.Worker.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ description: str,
+ node_id: Optional[str] = None,
+ max_concurrent_tasks: int = 10
+):
+```
+
+<a id="camel.societies.workforce.worker.Worker.__repr__"></a>
+
+### __repr__
+
+```python
+def __repr__(self):
+```
+
+<a id="camel.societies.workforce.worker.Worker._get_dep_tasks_info"></a>
+
+### _get_dep_tasks_info
+
+```python
+def _get_dep_tasks_info(dependencies: List[Task]):
+```
+
+<a id="camel.societies.workforce.worker.Worker.set_channel"></a>
+
+### set_channel
+
+```python
+def set_channel(self, channel: TaskChannel):
+```
+
+<a id="camel.societies.workforce.worker.Worker.stop"></a>
+
+### stop
+
+```python
+def stop(self):
+```
+
+Stop the worker.
diff --git a/docs/reference/camel.societies.workforce.workforce.md b/docs/reference/camel.societies.workforce.workforce.md
new file mode 100644
index 000000000..46c0f3a6c
--- /dev/null
+++ b/docs/reference/camel.societies.workforce.workforce.md
@@ -0,0 +1,607 @@
+<a id="camel.societies.workforce.workforce"></a>
+
+<a id="camel.societies.workforce.workforce.WorkforceState"></a>
+
+## WorkforceState
+
+```python
+class WorkforceState(Enum):
+```
+
+Workforce execution state for human intervention support.
+
+<a id="camel.societies.workforce.workforce.WorkforceSnapshot"></a>
+
+## WorkforceSnapshot
+
+```python
+class WorkforceSnapshot:
+```
+
+Snapshot of workforce state for resuming execution.
+
+<a id="camel.societies.workforce.workforce.WorkforceSnapshot.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ main_task: Optional[Task] = None,
+ pending_tasks: Optional[Deque[Task]] = None,
+ completed_tasks: Optional[List[Task]] = None,
+ task_dependencies: Optional[Dict[str, List[str]]] = None,
+ assignees: Optional[Dict[str, str]] = None,
+ current_task_index: int = 0,
+ description: str = ''
+):
+```
+
+<a id="camel.societies.workforce.workforce.Workforce"></a>
+
+## Workforce
+
+```python
+class Workforce(BaseNode):
+```
+
+A system where multiple worker nodes (agents) cooperate together
+to solve tasks. It can assign tasks to worker nodes and also take
+strategies such as create new worker, decompose tasks, etc. to handle
+situations when the task fails.
+
+The workforce uses three specialized ChatAgents internally:
+- Coordinator Agent: Assigns tasks to workers based on their
+capabilities
+- Task Planner Agent: Decomposes complex tasks and composes results
+- Dynamic Workers: Created at runtime when tasks fail repeatedly
+
+**Parameters:**
+
+- **description** (str): Description of the workforce.
+- **children** (Optional[List[BaseNode]], optional): List of child nodes under this node. Each child node can be a worker node or another workforce node. (default: :obj:`None`)
+- **coordinator_agent_kwargs** (Optional[Dict], optional): Keyword arguments passed directly to the coordinator :obj:`ChatAgent` constructor. The coordinator manages task assignment and failure handling strategies. See :obj:`ChatAgent` documentation for all available parameters. (default: :obj:`None` - uses ModelPlatformType.DEFAULT, ModelType.DEFAULT)
+- **task_agent_kwargs** (Optional[Dict], optional): Keyword arguments passed directly to the task planning :obj:`ChatAgent` constructor. The task agent handles task decomposition into subtasks and result composition. See :obj:`ChatAgent` documentation for all available parameters. (default: :obj:`None` - uses ModelPlatformType.DEFAULT, ModelType.DEFAULT)
+- **new_worker_agent_kwargs** (Optional[Dict], optional): Default keyword arguments passed to :obj:`ChatAgent` constructor for workers created dynamically at runtime when existing workers cannot handle failed tasks. See :obj:`ChatAgent` documentation for all available parameters. (default: :obj:`None` - creates workers with SearchToolkit, CodeExecutionToolkit, and ThinkingToolkit)
+- **graceful_shutdown_timeout** (float, optional): The timeout in seconds for graceful shutdown when a task fails 3 times. During this period, the workforce remains active for debugging. Set to 0 for immediate shutdown. (default: :obj:`15.0`)
+- **share_memory** (bool, optional): Whether to enable shared memory across SingleAgentWorker instances in the workforce. When enabled, all SingleAgentWorker instances, coordinator agent, and task planning agent will share their complete conversation history and function-calling trajectory, providing better context for task handoffs and continuity. Note: Currently only supports SingleAgentWorker instances; RolePlayingWorker and nested Workforce instances do not participate in memory sharing. (default: :obj:`False`)
+
+<a id="camel.societies.workforce.workforce.Workforce.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ description: str,
+ children: Optional[List[BaseNode]] = None,
+ coordinator_agent_kwargs: Optional[Dict] = None,
+ task_agent_kwargs: Optional[Dict] = None,
+ new_worker_agent_kwargs: Optional[Dict] = None,
+ graceful_shutdown_timeout: float = 15.0,
+ share_memory: bool = False
+):
+```
+
+<a id="camel.societies.workforce.workforce.Workforce.__repr__"></a>
+
+### __repr__
+
+```python
+def __repr__(self):
+```
+
+<a id="camel.societies.workforce.workforce.Workforce._collect_shared_memory"></a>
+
+### _collect_shared_memory
+
+```python
+def _collect_shared_memory(self):
+```
+
+**Returns:**
+
+ Dict[str, List]: A dictionary mapping agent types to their memory
+records. Contains entries for 'coordinator', 'task_agent',
+and 'workers'.
+
+<a id="camel.societies.workforce.workforce.Workforce._share_memory_with_agents"></a>
+
+### _share_memory_with_agents
+
+```python
+def _share_memory_with_agents(self, shared_memory: Dict[str, List]):
+```
+
+Share collected memory with coordinator, task agent, and
+SingleAgentWorker instances.
+
+**Parameters:**
+
+- **shared_memory** (Dict[str, List]): Memory records collected from all agents to be shared.
+
+<a id="camel.societies.workforce.workforce.Workforce._sync_shared_memory"></a>
+
+### _sync_shared_memory
+
+```python
+def _sync_shared_memory(self):
+```
+
+Synchronize memory across all agents by collecting and sharing.
+
+<a id="camel.societies.workforce.workforce.Workforce._decompose_task"></a>
+
+### _decompose_task
+
+```python
+def _decompose_task(self, task: Task):
+```
+
+**Returns:**
+
+ List[Task]: The subtasks.
+
+<a id="camel.societies.workforce.workforce.Workforce.pause"></a>
+
+### pause
+
+```python
+def pause(self):
+```
+
+Pause the workforce execution.
+If the internal event-loop is already running we schedule the
+asynchronous pause coroutine onto it. When the loop has not yet
+been created (e.g. the caller presses the hot-key immediately after
+workforce start-up) we fall back to a synchronous state change so
+that no tasks will be scheduled until the loop is ready.
+
+<a id="camel.societies.workforce.workforce.Workforce.resume"></a>
+
+### resume
+
+```python
+def resume(self):
+```
+
+Resume execution after a manual pause.
+
+<a id="camel.societies.workforce.workforce.Workforce.stop_gracefully"></a>
+
+### stop_gracefully
+
+```python
+def stop_gracefully(self):
+```
+
+Request workforce to finish current in-flight work then halt.
+
+Works both when the internal event-loop is alive and when it has not
+yet been started. In the latter case we simply mark the stop flag so
+that the loop (when it eventually starts) will exit immediately after
+initialisation.
+
+<a id="camel.societies.workforce.workforce.Workforce.save_snapshot"></a>
+
+### save_snapshot
+
+```python
+def save_snapshot(self, description: str = ''):
+```
+
+Save current state as a snapshot.
+
+<a id="camel.societies.workforce.workforce.Workforce.list_snapshots"></a>
+
+### list_snapshots
+
+```python
+def list_snapshots(self):
+```
+
+List all available snapshots.
+
+<a id="camel.societies.workforce.workforce.Workforce.get_pending_tasks"></a>
+
+### get_pending_tasks
+
+```python
+def get_pending_tasks(self):
+```
+
+Get current pending tasks for human review.
+
+<a id="camel.societies.workforce.workforce.Workforce.get_completed_tasks"></a>
+
+### get_completed_tasks
+
+```python
+def get_completed_tasks(self):
+```
+
+Get completed tasks.
+
+<a id="camel.societies.workforce.workforce.Workforce.modify_task_content"></a>
+
+### modify_task_content
+
+```python
+def modify_task_content(self, task_id: str, new_content: str):
+```
+
+Modify the content of a pending task.
+
+<a id="camel.societies.workforce.workforce.Workforce.add_task"></a>
+
+### add_task
+
+```python
+def add_task(
+ self,
+ content: str,
+ task_id: Optional[str] = None,
+ additional_info: Optional[Dict[str, Any]] = None,
+ insert_position: int = -1
+):
+```
+
+Add a new task to the pending queue.
+
+<a id="camel.societies.workforce.workforce.Workforce.remove_task"></a>
+
+### remove_task
+
+```python
+def remove_task(self, task_id: str):
+```
+
+Remove a task from the pending queue.
+
+<a id="camel.societies.workforce.workforce.Workforce.reorder_tasks"></a>
+
+### reorder_tasks
+
+```python
+def reorder_tasks(self, task_ids: List[str]):
+```
+
+Reorder pending tasks according to the provided task IDs list.
+
+<a id="camel.societies.workforce.workforce.Workforce.resume_from_task"></a>
+
+### resume_from_task
+
+```python
+def resume_from_task(self, task_id: str):
+```
+
+Resume execution from a specific task.
+
+<a id="camel.societies.workforce.workforce.Workforce.restore_from_snapshot"></a>
+
+### restore_from_snapshot
+
+```python
+def restore_from_snapshot(self, snapshot_index: int):
+```
+
+Restore workforce state from a snapshot.
+
+<a id="camel.societies.workforce.workforce.Workforce.get_workforce_status"></a>
+
+### get_workforce_status
+
+```python
+def get_workforce_status(self):
+```
+
+Get current workforce status for human review.
+
+<a id="camel.societies.workforce.workforce.Workforce.process_task"></a>
+
+### process_task
+
+```python
+def process_task(self, task: Task):
+```
+
+Synchronous wrapper for process_task that handles async operations
+internally.
+
+**Parameters:**
+
+- **task** (Task): The task to be processed.
+
+**Returns:**
+
+ Task: The updated task.
+
+<a id="camel.societies.workforce.workforce.Workforce._process_task_with_intervention"></a>
+
+### _process_task_with_intervention
+
+```python
+def _process_task_with_intervention(self, task: Task):
+```
+
+Process task with human intervention support. This creates and
+manages its own event loop to allow for pausing/resuming functionality.
+
+**Parameters:**
+
+- **task** (Task): The task to be processed.
+
+**Returns:**
+
+ Task: The updated task.
+
+<a id="camel.societies.workforce.workforce.Workforce.continue_from_pause"></a>
+
+### continue_from_pause
+
+```python
+def continue_from_pause(self):
+```
+
+**Returns:**
+
+ Optional[Task]: The completed task if execution finishes, None if
+still running/paused.
+
+<a id="camel.societies.workforce.workforce.Workforce.add_single_agent_worker"></a>
+
+### add_single_agent_worker
+
+```python
+def add_single_agent_worker(
+ self,
+ description: str,
+ worker: ChatAgent,
+ max_concurrent_tasks: int = 10
+):
+```
+
+Add a worker node to the workforce that uses a single agent.
+
+**Parameters:**
+
+- **description** (str): Description of the worker node.
+- **worker** (ChatAgent): The agent to be added.
+- **max_concurrent_tasks** (int): Maximum number of tasks this worker can process concurrently. (default: :obj:`10`)
+
+**Returns:**
+
+ Workforce: The workforce node itself.
+
+<a id="camel.societies.workforce.workforce.Workforce.add_role_playing_worker"></a>
+
+### add_role_playing_worker
+
+```python
+def add_role_playing_worker(
+ self,
+ description: str,
+ assistant_role_name: str,
+ user_role_name: str,
+ assistant_agent_kwargs: Optional[Dict] = None,
+ user_agent_kwargs: Optional[Dict] = None,
+ summarize_agent_kwargs: Optional[Dict] = None,
+ chat_turn_limit: int = 3
+):
+```
+
+Add a worker node to the workforce that uses `RolePlaying` system.
+
+**Parameters:**
+
+- **description** (str): Description of the node.
+- **assistant_role_name** (str): The role name of the assistant agent.
+- **user_role_name** (str): The role name of the user agent.
+- **assistant_agent_kwargs** (Optional[Dict]): The keyword arguments to initialize the assistant agent in the role playing, like the model name, etc. (default: :obj:`None`)
+- **user_agent_kwargs** (Optional[Dict]): The keyword arguments to initialize the user agent in the role playing, like the model name, etc. (default: :obj:`None`)
+- **summarize_agent_kwargs** (Optional[Dict]): The keyword arguments to initialize the summarize agent, like the model name, etc. (default: :obj:`None`)
+- **chat_turn_limit** (int): The maximum number of chat turns in the role playing. (default: :obj:`3`)
+
+**Returns:**
+
+ Workforce: The workforce node itself.
+
+<a id="camel.societies.workforce.workforce.Workforce.add_workforce"></a>
+
+### add_workforce
+
+```python
+def add_workforce(self, workforce: Workforce):
+```
+
+Add a workforce node to the workforce.
+
+**Parameters:**
+
+- **workforce** (Workforce): The workforce node to be added.
+
+**Returns:**
+
+ Workforce: The workforce node itself.
+
+<a id="camel.societies.workforce.workforce.Workforce.reset"></a>
+
+### reset
+
+```python
+def reset(self):
+```
+
+Reset the workforce and all the child nodes under it. Can only
+be called when the workforce is not running.
+
+<a id="camel.societies.workforce.workforce.Workforce.set_channel"></a>
+
+### set_channel
+
+```python
+def set_channel(self, channel: TaskChannel):
+```
+
+Set the channel for the node and all the child nodes under it.
+
+<a id="camel.societies.workforce.workforce.Workforce._get_child_nodes_info"></a>
+
+### _get_child_nodes_info
+
+```python
+def _get_child_nodes_info(self):
+```
+
+Get the information of all the child nodes under this node.
+
+<a id="camel.societies.workforce.workforce.Workforce._find_assignee"></a>
+
+### _find_assignee
+
+```python
+def _find_assignee(self, tasks: List[Task]):
+```
+
+Assigns multiple tasks to worker nodes with the best capabilities.
+
+**Parameters:**
+
+- **tasks** (List[Task]): The tasks to be assigned.
+
+**Returns:**
+
+ TaskAssignResult: Assignment result containing task assignments
+with their dependencies.
+
+<a id="camel.societies.workforce.workforce.Workforce._create_worker_node_for_task"></a>
+
+### _create_worker_node_for_task
+
+```python
+def _create_worker_node_for_task(self, task: Task):
+```
+
+Creates a new worker node for a given task and add it to the
+children list of this node. This is one of the actions that
+the coordinator can take when a task has failed.
+
+**Parameters:**
+
+- **task** (Task): The task for which the worker node is created.
+
+**Returns:**
+
+ Worker: The created worker node.
+
+<a id="camel.societies.workforce.workforce.Workforce._create_new_agent"></a>
+
+### _create_new_agent
+
+```python
+def _create_new_agent(self, role: str, sys_msg: str):
+```
+
+<a id="camel.societies.workforce.workforce.Workforce.get_workforce_log_tree"></a>
+
+### get_workforce_log_tree
+
+```python
+def get_workforce_log_tree(self):
+```
+
+Returns an ASCII tree representation of the task hierarchy and
+worker status.
+
+<a id="camel.societies.workforce.workforce.Workforce.get_workforce_kpis"></a>
+
+### get_workforce_kpis
+
+```python
+def get_workforce_kpis(self):
+```
+
+Returns a dictionary of key performance indicators.
+
+<a id="camel.societies.workforce.workforce.Workforce.dump_workforce_logs"></a>
+
+### dump_workforce_logs
+
+```python
+def dump_workforce_logs(self, file_path: str):
+```
+
+Dumps all collected logs to a JSON file.
+
+**Parameters:**
+
+- **file_path** (str): The path to the JSON file.
+
+<a id="camel.societies.workforce.workforce.Workforce._submit_coro_to_loop"></a>
+
+### _submit_coro_to_loop
+
+```python
+def _submit_coro_to_loop(self, coro: 'Coroutine'):
+```
+
+Thread-safe submission of coroutine to the workforce loop.
+
+<a id="camel.societies.workforce.workforce.Workforce.stop"></a>
+
+### stop
+
+```python
+def stop(self):
+```
+
+Stop all the child nodes under it. The node itself will be stopped
+by its parent node.
+
+<a id="camel.societies.workforce.workforce.Workforce.clone"></a>
+
+### clone
+
+```python
+def clone(self, with_memory: bool = False):
+```
+
+Creates a new instance of Workforce with the same configuration.
+
+**Parameters:**
+
+- **with_memory** (bool, optional): Whether to copy the memory (conversation history) to the new instance. If True, the new instance will have the same conversation history. If False, the new instance will have a fresh memory. (default: :obj:`False`)
+
+**Returns:**
+
+ Workforce: A new instance of Workforce with the same configuration.
+
+<a id="camel.societies.workforce.workforce.Workforce.to_mcp"></a>
+
+### to_mcp
+
+```python
+def to_mcp(
+ self,
+ name: str = 'CAMEL-Workforce',
+ description: str = 'A workforce system using the CAMEL AI framework for multi-agent collaboration.',
+ dependencies: Optional[List[str]] = None,
+ host: str = 'localhost',
+ port: int = 8001
+):
+```
+
+Expose this Workforce as an MCP server.
+
+**Parameters:**
+
+- **name** (str): Name of the MCP server. (default: :obj:`CAMEL-Workforce`)
+- **description** (str): Description of the workforce. If None, a generic description is used. (default: :obj:`A workforce system using the CAMEL AI framework for multi-agent collaboration.`)
+- **dependencies** (Optional[List[str]]): Additional dependencies for the MCP server. (default: :obj:`None`)
+- **host** (str): Host to bind to for HTTP transport. (default: :obj:`localhost`)
+- **port** (int): Port to bind to for HTTP transport. (default: :obj:`8001`)
+
+**Returns:**
+
+ FastMCP: An MCP server instance that can be run.