camel-ai 0.2.67__py3-none-any.whl → 0.2.80a2__py3-none-any.whl

camel/societies/workforce/task_channel.py

@@ -12,17 +12,23 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import asyncio
+from collections import defaultdict, deque
 from enum import Enum
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Set
 
+from camel.logger import get_logger
 from camel.tasks import Task
 
+logger = get_logger(__name__)
+
 
 class PacketStatus(Enum):
     r"""The status of a packet. The packet can be in one of the following
     states:
 
     - ``SENT``: The packet has been sent to a worker.
+    - ``PROCESSING``: The packet has been claimed by a worker and is being
+    processed.
     - ``RETURNED``: The packet has been returned by the worker, meaning that
       the status of the task inside has been updated.
     - ``ARCHIVED``: The packet has been archived, meaning that the content of
@@ -31,6 +37,7 @@ class PacketStatus(Enum):
     """
 
     SENT = "SENT"
+    PROCESSING = "PROCESSING"
     RETURNED = "RETURNED"
     ARCHIVED = "ARCHIVED"
 
@@ -76,38 +83,121 @@ class Packet:
 
 
 class TaskChannel:
-    r"""An internal class used by Workforce to manage tasks."""
+    r"""An internal class used by Workforce to manage tasks.
+
+    This implementation uses a hybrid data structure approach:
+    - Hash map (_task_dict) for O(1) task lookup by ID
+    - Status-based index (_task_by_status) for efficient filtering by status
+    - Assignee/publisher queues for ordered task processing
+    """
 
     def __init__(self) -> None:
         self._condition = asyncio.Condition()
         self._task_dict: Dict[str, Packet] = {}
 
+        self._task_by_status: Dict[PacketStatus, Set[str]] = defaultdict(set)
+
+        # task by assignee store which are sent to
+        self._task_by_assignee: Dict[str, deque[str]] = defaultdict(deque)
+
+        self._task_by_publisher: Dict[str, deque[str]] = defaultdict(deque)
+
+    def _update_task_status(
+        self, task_id: str, new_status: PacketStatus
+    ) -> None:
+        r"""Helper method to properly update task status in all indexes."""
+        if task_id not in self._task_dict:
+            return
+
+        packet = self._task_dict[task_id]
+        old_status = packet.status
+
+        if old_status in self._task_by_status:
+            self._task_by_status[old_status].discard(task_id)
+
+        packet.status = new_status
+
+        self._task_by_status[new_status].add(task_id)
+
+    def _cleanup_task_from_indexes(self, task_id: str) -> None:
+        r"""Helper method to remove a task from all indexes.
+
+        Args:
+            task_id (str): The ID of the task to remove from indexes.
+        """
+        if task_id not in self._task_dict:
+            return
+
+        packet = self._task_dict[task_id]
+
+        if packet.status in self._task_by_status:
+            self._task_by_status[packet.status].discard(task_id)
+
+        if packet.assignee_id and packet.assignee_id in self._task_by_assignee:
+            assignee_queue = self._task_by_assignee[packet.assignee_id]
+            self._task_by_assignee[packet.assignee_id] = deque(
+                task for task in assignee_queue if task != task_id
+            )
+
+        if packet.publisher_id in self._task_by_publisher:
+            publisher_queue = self._task_by_publisher[packet.publisher_id]
+            self._task_by_publisher[packet.publisher_id] = deque(
+                task for task in publisher_queue if task != task_id
+            )
+
     async def get_returned_task_by_publisher(self, publisher_id: str) -> Task:
         r"""Get a task from the channel that has been returned by the
         publisher.
         """
         async with self._condition:
             while True:
-                for packet in self._task_dict.values():
-                    if packet.publisher_id != publisher_id:
-                        continue
-                    if packet.status != PacketStatus.RETURNED:
-                        continue
-                    return packet.task
+                task_ids = self._task_by_publisher[publisher_id]
+
+                if task_ids:
+                    task_id = task_ids.popleft()
+
+                    if task_id in self._task_dict:
+                        packet = self._task_dict[task_id]
+
+                        if (
+                            packet.status == PacketStatus.RETURNED
+                            and packet.publisher_id == publisher_id
+                        ):
+                            # Clean up all indexes before removing
+                            self._cleanup_task_from_indexes(task_id)
+                            del self._task_dict[task_id]
+                            self._condition.notify_all()
+                            return packet.task
+
                 await self._condition.wait()
 
     async def get_assigned_task_by_assignee(self, assignee_id: str) -> Task:
-        r"""Get a task from the channel that has been assigned to the
-        assignee.
+        r"""Atomically get and claim a task from the channel that has been
+        assigned to the assignee. This prevents race conditions where multiple
+        concurrent calls might retrieve the same task.
         """
         async with self._condition:
             while True:
-                for packet in self._task_dict.values():
-                    if (
-                        packet.status == PacketStatus.SENT
-                        and packet.assignee_id == assignee_id
-                    ):
-                        return packet.task
+                task_ids = self._task_by_assignee.get(assignee_id, deque())
+
+                # Process all available tasks until we find a valid one
+                while task_ids:
+                    task_id = task_ids.popleft()
+
+                    if task_id in self._task_dict:
+                        packet = self._task_dict[task_id]
+
+                        if (
+                            packet.status == PacketStatus.SENT
+                            and packet.assignee_id == assignee_id
+                        ):
+                            # Use helper method to properly update status
+                            self._update_task_status(
+                                task_id, PacketStatus.PROCESSING
+                            )
+                            self._condition.notify_all()
+                            return packet.task
+
                 await self._condition.wait()
 
     async def post_task(
@@ -118,6 +208,8 @@ class TaskChannel:
         async with self._condition:
             packet = Packet(task, publisher_id, assignee_id)
             self._task_dict[packet.task.id] = packet
+            self._task_by_status[PacketStatus.SENT].add(packet.task.id)
+            self._task_by_assignee[assignee_id].append(packet.task.id)
             self._condition.notify_all()
 
     async def post_dependency(
@@ -130,6 +222,7 @@ class TaskChannel:
                 dependency, publisher_id, status=PacketStatus.ARCHIVED
             )
             self._task_dict[packet.task.id] = packet
+            self._task_by_status[PacketStatus.ARCHIVED].add(packet.task.id)
             self._condition.notify_all()
 
     async def return_task(self, task_id: str) -> None:
@@ -138,7 +231,12 @@ class TaskChannel:
         async with self._condition:
             if task_id in self._task_dict:
                 packet = self._task_dict[task_id]
-                packet.status = PacketStatus.RETURNED
+                # Only add to publisher queue if not already returned
+                if packet.status != PacketStatus.RETURNED:
+                    self._update_task_status(task_id, PacketStatus.RETURNED)
+                    self._task_by_publisher[packet.publisher_id].append(
+                        packet.task.id
+                    )
             self._condition.notify_all()
 
     async def archive_task(self, task_id: str) -> None:
@@ -146,7 +244,17 @@ class TaskChannel:
         async with self._condition:
             if task_id in self._task_dict:
                 packet = self._task_dict[task_id]
-                packet.status = PacketStatus.ARCHIVED
+                # Remove from assignee queue before archiving
+                if (
+                    packet.assignee_id
+                    and packet.assignee_id in self._task_by_assignee
+                ):
+                    assignee_queue = self._task_by_assignee[packet.assignee_id]
+                    self._task_by_assignee[packet.assignee_id] = deque(
+                        task for task in assignee_queue if task != task_id
+                    )
+                # Update status (keeps in status index for dependencies)
+                self._update_task_status(task_id, PacketStatus.ARCHIVED)
             self._condition.notify_all()
 
     async def remove_task(self, task_id: str) -> None:
@@ -154,17 +262,55 @@ class TaskChannel:
         async with self._condition:
             # Check if task ID exists before removing
             if task_id in self._task_dict:
+                # Clean up all indexes before removing
+                self._cleanup_task_from_indexes(task_id)
                 del self._task_dict[task_id]
             self._condition.notify_all()
 
     async def get_dependency_ids(self) -> List[str]:
         r"""Get the IDs of all dependencies in the channel."""
         async with self._condition:
-            dependency_ids = []
-            for task_id, packet in self._task_dict.items():
-                if packet.status == PacketStatus.ARCHIVED:
-                    dependency_ids.append(task_id)
-            return dependency_ids
+            return list(self._task_by_status[PacketStatus.ARCHIVED])
+
+    async def get_in_flight_tasks(self, publisher_id: str) -> List[Task]:
+        r"""Get all tasks that are currently in-flight (SENT, RETURNED
+        or PROCESSING) published by the given publisher.
+
+        Args:
+            publisher_id (str): The ID of the publisher whose
+            in-flight tasks to retrieve.
+
+        Returns:
+            List[Task]: List of tasks that are currently in-flight.
+        """
+        async with self._condition:
+            in_flight_tasks = []
+            seen_task_ids = set()  # Track seen IDs for duplicate detection
+
+            # Get tasks with SENT, RETURNED or PROCESSING
+            # status published by this publisher
+            for status in [
+                PacketStatus.SENT,
+                PacketStatus.PROCESSING,
+                PacketStatus.RETURNED,
+            ]:
+                for task_id in self._task_by_status[status]:
+                    if task_id in self._task_dict:
+                        packet = self._task_dict[task_id]
+                        if packet.publisher_id == publisher_id:
+                            # Defensive check: detect if task appears in
+                            # multiple status sets (should never happen)
+                            if task_id in seen_task_ids:
+                                logger.warning(
+                                    f"Task {task_id} found in multiple "
+                                    f"status sets. This indicates a bug in "
+                                    f"status management."
+                                )
+                                continue
+                            in_flight_tasks.append(packet.task)
+                            seen_task_ids.add(task_id)
+
+            return in_flight_tasks
 
     async def get_task_by_id(self, task_id: str) -> Task:
         r"""Get a task from the channel by its ID."""

camel/societies/workforce/utils.py

@@ -11,10 +11,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from enum import Enum
 from functools import wraps
-from typing import Callable, List
+from typing import Callable, List, Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 
 class WorkerConf(BaseModel):
@@ -37,7 +38,38 @@ class TaskResult(BaseModel):
 
     content: str = Field(description="The result of the task.")
     failed: bool = Field(
-        description="Flag indicating whether the task processing failed."
+        default=False,
+        description="Flag indicating whether the task processing failed.",
+    )
+
+
+class QualityEvaluation(BaseModel):
+    r"""Quality evaluation result for a completed task.
+
+    .. deprecated::
+        Use :class:`TaskAnalysisResult` instead. This class is kept for
+        backward compatibility.
+    """
+
+    quality_sufficient: bool = Field(
+        description="Whether the task result meets quality standards."
+    )
+    quality_score: int = Field(
+        description="Quality score from 0 to 100.", ge=0, le=100
+    )
+    issues: List[str] = Field(
+        default_factory=list,
+        description="List of quality issues found in the result.",
+    )
+    recovery_strategy: Optional[str] = Field(
+        default=None,
+        description="Recommended recovery strategy if quality is "
+        "insufficient: "
+        "'retry', 'reassign', 'replan', or 'decompose'.",
+    )
+    modified_task_content: Optional[str] = Field(
+        default=None,
+        description="Modified task content for replan strategy.",
     )
 
 
@@ -50,18 +82,145 @@ class TaskAssignment(BaseModel):
     )
     dependencies: List[str] = Field(
         default_factory=list,
-        description="List of task IDs that must complete before this task.",
+        description="List of task IDs that must complete before this task. "
+        "This is critical for the task decomposition and "
+        "execution.",
     )
 
+    # Allow LLMs to output dependencies as a comma-separated string or empty
+    # string. This validator converts such cases into a list[str] so that
+    # downstream logic does not break with validation errors.
+    @staticmethod
+    def _split_and_strip(dep_str: str) -> List[str]:
+        r"""Utility to split a comma separated string and strip
+        whitespace."""
+        return [d.strip() for d in dep_str.split(',') if d.strip()]
+
+    @field_validator("dependencies", mode="before")
+    def validate_dependencies(cls, v) -> List[str]:
+        if v is None:
+            return []
+        # Handle empty string or comma-separated string from LLM
+        if isinstance(v, str):
+            return TaskAssignment._split_and_strip(v)
+        return v
+
 
 class TaskAssignResult(BaseModel):
-    r"""The result of task assignment for both single and batch assignments."""
+    r"""The result of task assignment for both single and batch
+    assignments."""
 
     assignments: List[TaskAssignment] = Field(
         description="List of task assignments."
     )
 
 
+class RecoveryStrategy(str, Enum):
+    r"""Strategies for handling failed tasks."""
+
+    RETRY = "retry"
+    REPLAN = "replan"
+    DECOMPOSE = "decompose"
+    CREATE_WORKER = "create_worker"
+    REASSIGN = "reassign"
+
+    def __str__(self):
+        return self.value
+
+    def __repr__(self):
+        return f"RecoveryStrategy.{self.name}"
+
+
+class FailureContext(BaseModel):
+    r"""Context information about a task failure."""
+
+    task_id: str = Field(description="ID of the failed task")
+    task_content: str = Field(description="Content of the failed task")
+    failure_count: int = Field(
+        description="Number of times this task has failed"
+    )
+    error_message: str = Field(description="Detailed error message")
+    worker_id: Optional[str] = Field(
+        default=None, description="ID of the worker that failed"
+    )
+    task_depth: int = Field(
+        description="Depth of the task in the decomposition hierarchy"
+    )
+    additional_info: Optional[str] = Field(
+        default=None, description="Additional context about the task"
+    )
+
+
+class TaskAnalysisResult(BaseModel):
+    r"""Unified result for task failure analysis and quality evaluation.
+
+    This model combines both failure recovery decisions and quality evaluation
+    results into a single structure. For failure analysis, only the recovery
+    strategy and reasoning fields are populated. For quality evaluation, all
+    fields including quality_score and issues are populated.
+    """
+
+    # Common fields - always populated
+    reasoning: str = Field(
+        description="Explanation for the analysis result or recovery "
+        "decision"
+    )
+
+    recovery_strategy: Optional[RecoveryStrategy] = Field(
+        default=None,
+        description="Recommended recovery strategy: 'retry', 'replan', "
+        "'decompose', 'create_worker', or 'reassign'. None indicates no "
+        "recovery needed (quality sufficient).",
+    )
+
+    modified_task_content: Optional[str] = Field(
+        default=None,
+        description="Modified task content if strategy requires replan",
+    )
+
+    # Quality-specific fields - populated only for quality evaluation
+    quality_score: Optional[int] = Field(
+        default=None,
+        description="Quality score from 0 to 100 (only for quality "
+        "evaluation). "
+        "None indicates this is a failure analysis, "
+        "not quality evaluation.",
+        ge=0,
+        le=100,
+    )
+
+    issues: List[str] = Field(
+        default_factory=list,
+        description="List of issues found. For failures: error details. "
+        "For quality evaluation: quality issues.",
+    )
+
+    @property
+    def is_quality_evaluation(self) -> bool:
+        r"""Check if this is a quality evaluation result.
+
+        Returns:
+            bool: True if this is a quality evaluation (has quality_score),
+                False if this is a failure analysis.
+        """
+        return self.quality_score is not None
+
+    @property
+    def quality_sufficient(self) -> bool:
+        r"""For quality evaluations, check if quality meets standards.
+
+        Returns:
+            bool: True if quality is sufficient (score >= 70 and no recovery
+                strategy recommended), False otherwise. Always False for
+                failure analysis results.
+        """
+        return (
+            self.quality_score is not None
+            and self.quality_score >= 70
+            and self.recovery_strategy is None
+        )
+
+
 def check_if_running(
     running: bool,
     max_retries: int = 3,
@@ -112,7 +271,7 @@ def check_if_running(
                         if retries < max_retries:
                             logger.warning(
                                 f"{error_msg} Retrying in {retry_delay}s... "
-                                f"(Attempt {retries+1}/{max_retries})"
+                                f"(Attempt {retries + 1}/{max_retries})"
                             )
                             time.sleep(retry_delay)
                             retries += 1
@@ -134,7 +293,7 @@ def check_if_running(
                         logger.warning(
                             f"Exception in {func.__name__}: {e}. "
                             f"Retrying in {retry_delay}s... "
-                            f"(Attempt {retries+1}/{max_retries})"
+                            f"(Attempt {retries + 1}/{max_retries})"
                         )
                         time.sleep(retry_delay)
                         retries += 1
@@ -152,11 +311,19 @@ def check_if_running(
             # This should not be reached, but just in case
             if handle_exceptions:
                 logger.error(
-                    f"Unexpected failure in {func.__name__}: {last_exception}"
+                    f"Unexpected failure in {func.__name__}: "
+                    f"{last_exception}"
                 )
                 return None
             else:
-                raise last_exception
+                raise (
+                    last_exception
+                    if last_exception
+                    else RuntimeError(
+                        f"Unexpected failure in {func.__name__} "
+                        "with no exception captured."
+                    )
+                )
 
         return wrapper
 

camel/societies/workforce/worker.py

@@ -13,9 +13,10 @@
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 from __future__ import annotations
 
+import asyncio
 import logging
 from abc import ABC, abstractmethod
-from typing import List, Optional
+from typing import List, Optional, Set
 
 from colorama import Fore
 
@@ -43,6 +44,7 @@ class Worker(BaseNode, ABC):
         node_id: Optional[str] = None,
     ) -> None:
         super().__init__(description, node_id=node_id)
+        self._active_task_ids: Set[str] = set()
 
     def __repr__(self):
         return f"Worker node {self.node_id} ({self.description})"
@@ -60,7 +62,7 @@ class Worker(BaseNode, ABC):
         pass
 
     async def _get_assigned_task(self) -> Task:
-        r"""Get the task assigned to this node from the channel."""
+        r"""Get a task assigned to this node from the channel."""
         return await self._channel.get_assigned_task_by_assignee(self.node_id)
 
     @staticmethod
@@ -77,38 +79,90 @@ class Worker(BaseNode, ABC):
     def set_channel(self, channel: TaskChannel):
         self._channel = channel
 
-    @check_if_running(False)
-    async def _listen_to_channel(self):
-        """Continuously listen to the channel, process the task that are
-        assigned to this node, and update the result and status of the task.
-
-        This method should be run in an event loop, as it will run
-            indefinitely.
-        """
-        self._running = True
-        logger.info(f"{self} started.")
-
-        while True:
-            # Get the earliest task assigned to this node
-            task = await self._get_assigned_task()
+    async def _process_single_task(self, task: Task) -> None:
+        r"""Process a single task and handle its completion/failure."""
+        try:
+            self._active_task_ids.add(task.id)
             print(
                 f"{Fore.YELLOW}{self} get task {task.id}: {task.content}"
                 f"{Fore.RESET}"
             )
-            # Get the Task instance of dependencies
-            dependency_ids = await self._channel.get_dependency_ids()
-            task_dependencies = [
-                await self._channel.get_task_by_id(dep_id)
-                for dep_id in dependency_ids
-            ]
 
             # Process the task
-            task_state = await self._process_task(task, task_dependencies)
+            task_state = await self._process_task(task, task.dependencies)
 
             # Update the result and status of the task
             task.set_state(task_state)
 
             await self._channel.return_task(task.id)
+        except Exception as e:
+            logger.error(f"Error processing task {task.id}: {e}")
+            # Store error information in task result
+            task.result = f"{type(e).__name__}: {e!s}"
+            task.set_state(TaskState.FAILED)
+            await self._channel.return_task(task.id)
+        finally:
+            self._active_task_ids.discard(task.id)
+
+    @check_if_running(False)
+    async def _listen_to_channel(self):
+        r"""Continuously listen to the channel and process assigned tasks.
+
+        This method supports parallel task execution without artificial limits.
+        """
+        self._running = True
+        logger.info(f"{self} started.")
+
+        # Keep track of running task coroutines
+        running_tasks: Set[asyncio.Task] = set()
+
+        while self._running:
+            try:
+                # Clean up completed tasks
+                completed_tasks = [t for t in running_tasks if t.done()]
+                for completed_task in completed_tasks:
+                    running_tasks.remove(completed_task)
+                    # Check for exceptions in completed tasks
+                    try:
+                        await completed_task
+                    except Exception as e:
+                        logger.error(f"Task processing failed: {e}")
+
+                # Try to get a new task (with short timeout to avoid blocking)
+                try:
+                    task = await asyncio.wait_for(
+                        self._get_assigned_task(), timeout=1.0
+                    )
+
+                    # Create and start processing task
+                    task_coroutine = asyncio.create_task(
+                        self._process_single_task(task)
+                    )
+                    running_tasks.add(task_coroutine)
+
+                except asyncio.TimeoutError:
+                    # No tasks available, continue loop
+                    if not running_tasks:
+                        # No tasks running and none available, short sleep
+                        await asyncio.sleep(0.1)
+                    continue
+
+            except Exception as e:
+                logger.error(
+                    f"Error in worker {self.node_id} listen loop: {e}"
+                )
+                await asyncio.sleep(0.1)
+                continue
+
+        # Wait for all remaining tasks to complete when stopping
+        if running_tasks:
+            logger.info(
+                f"{self} stopping, waiting for {len(running_tasks)} "
+                f"tasks to complete..."
+            )
+            await asyncio.gather(*running_tasks, return_exceptions=True)
+
+        logger.info(f"{self} stopped.")
 
     @check_if_running(False)
     async def start(self):