camel-ai 0.2.73a4__py3-none-any.whl → 0.2.80a2__py3-none-any.whl

camel/societies/workforce/structured_output_handler.py

@@ -19,8 +19,8 @@ from pydantic import BaseModel, ValidationError
 
 from camel.logger import get_logger
 from camel.societies.workforce.utils import (
-    RecoveryDecision,
     RecoveryStrategy,
+    TaskAnalysisResult,
     TaskAssignResult,
     WorkerConf,
 )
@@ -65,9 +65,9 @@ class StructuredOutputHandler:
                 r'description.*?:\s*"([^"]+)"'
             ),
         ],
-        'RecoveryDecision': [
-            r'"strategy"\s*:\s*"([^"]+)".*?"reasoning"\s*:\s*"([^"]+)"',
-            r'strategy.*?:\s*"([^"]+)".*?reasoning.*?:\s*"([^"]+)"',
+        'TaskAnalysisResult': [
+            r'"recovery_strategy"\s*:\s*"([^"]+)".*?"reasoning"\s*:\s*"([^"]+)"',
+            r'recovery_strategy.*?:\s*"([^"]+)".*?reasoning.*?:\s*"([^"]+)"',
         ],
     }
 
@@ -239,12 +239,12 @@ Ensure the JSON is valid and properly formatted.
                     except (IndexError, AttributeError):
                         continue
 
-        elif schema_name == 'RecoveryDecision':
+        elif schema_name == 'TaskAnalysisResult':
             for pattern in patterns:
                 match = re.search(pattern, text, re.DOTALL | re.IGNORECASE)
                 if match:
                     try:
-                        strategy = match.group(1)
+                        recovery_strategy = match.group(1)
                         reasoning = match.group(2)
                         # Look for modified_task_content
                         content_match = re.search(
@@ -252,14 +252,25 @@ Ensure the JSON is valid and properly formatted.
                             text,
                             re.IGNORECASE,
                         )
+                        # Look for quality_score (for quality evaluation)
+                        score_match = re.search(
+                            r'"quality_score"\s*:\s*(\d+)',
+                            text,
+                            re.IGNORECASE,
+                        )
                         return {
-                            'strategy': strategy,
+                            'recovery_strategy': recovery_strategy,
                             'reasoning': reasoning,
                             'modified_task_content': (
                                 content_match.group(1)
                                 if content_match
                                 else None
                             ),
+                            'quality_score': (
+                                int(score_match.group(1))
+                                if score_match
+                                else None
+                            ),
                         }
                     except (IndexError, AttributeError):
                         continue
@@ -370,21 +381,22 @@ Ensure the JSON is valid and properly formatted.
                         else:
                             assignment['dependencies'] = []
 
-        elif schema_name == 'RecoveryDecision':
-            # Ensure strategy is valid
-            if 'strategy' in fixed_data:
-                strategy = fixed_data['strategy'].lower()
+        elif schema_name == 'TaskAnalysisResult':
+            # Ensure recovery_strategy is valid
+            if 'recovery_strategy' in fixed_data:
+                strategy = fixed_data['recovery_strategy'].lower()
                 valid_strategies = [
                     'retry',
                     'replan',
                     'decompose',
                     'create_worker',
+                    'reassign',
                 ]
                 if strategy not in valid_strategies:
                     # Try to match partial
                     for valid in valid_strategies:
                         if valid.startswith(strategy) or strategy in valid:
-                            fixed_data['strategy'] = valid
+                            fixed_data['recovery_strategy'] = valid
                             break
 
         return fixed_data
@@ -410,10 +422,10 @@ Ensure the JSON is valid and properly formatted.
                 sys_msg="You are a helpful assistant.",
                 description="A general-purpose worker",
             )
-        elif schema_name == 'RecoveryDecision':
-            return RecoveryDecision(
-                strategy=RecoveryStrategy.RETRY,
+        elif schema_name == 'TaskAnalysisResult':
+            return TaskAnalysisResult(
                 reasoning="Unable to parse response, defaulting to retry",
+                recovery_strategy=RecoveryStrategy.RETRY,
                 modified_task_content=None,
             )
         else:
@@ -482,11 +494,11 @@ Ensure the JSON is valid and properly formatted.
                 description=f"Fallback worker for task: {task_content}...",
             )
 
-        elif schema_name == 'RecoveryDecision':
+        elif schema_name == 'TaskAnalysisResult':
             # Default to retry strategy
-            return RecoveryDecision(
-                strategy=RecoveryStrategy.RETRY,
+            return TaskAnalysisResult(
                 reasoning=f"Fallback decision due to: {error_message}",
+                recovery_strategy=RecoveryStrategy.RETRY,
                 modified_task_content=None,
             )
 

camel/societies/workforce/task_channel.py

@@ -12,11 +12,15 @@
 # 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
@@ -79,27 +83,92 @@ 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 task_id, packet in list(self._task_dict.items()):
-                    if packet.publisher_id != publisher_id:
-                        continue
-                    if packet.status != PacketStatus.RETURNED:
-                        continue
-                    # Remove the task to prevent returning it again
-                    del self._task_dict[task_id]
-                    self._condition.notify_all()
-                    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:
@@ -109,15 +178,26 @@ class TaskChannel:
         """
         async with self._condition:
             while True:
-                for packet in self._task_dict.values():
-                    if (
-                        packet.status == PacketStatus.SENT
-                        and packet.assignee_id == assignee_id
-                    ):
-                        # Atomically claim the task by changing its status
-                        packet.status = PacketStatus.PROCESSING
-                        self._condition.notify_all()
-                        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(
@@ -128,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(
@@ -140,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:
@@ -148,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:
@@ -156,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:
@@ -164,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

@@ -38,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.",
     )
 
 
@@ -52,7 +83,8 @@ class TaskAssignment(BaseModel):
     dependencies: List[str] = Field(
         default_factory=list,
         description="List of task IDs that must complete before this task. "
-        "This is critical for the task decomposition and execution.",
+        "This is critical for the task decomposition and "
+        "execution.",
     )
 
     # Allow LLMs to output dependencies as a comma-separated string or empty
@@ -60,7 +92,8 @@ class TaskAssignment(BaseModel):
     # 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."""
+        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")
@@ -74,7 +107,8 @@ class TaskAssignment(BaseModel):
 
 
 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."
@@ -88,6 +122,7 @@ class RecoveryStrategy(str, Enum):
     REPLAN = "replan"
     DECOMPOSE = "decompose"
     CREATE_WORKER = "create_worker"
+    REASSIGN = "reassign"
 
     def __str__(self):
         return self.value
@@ -116,17 +151,75 @@ class FailureContext(BaseModel):
     )
 
 
-class RecoveryDecision(BaseModel):
-    r"""Decision on how to recover from a task failure."""
+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"
+    )
 
-    strategy: RecoveryStrategy = Field(
-        description="The chosen recovery strategy"
+    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).",
     )
-    reasoning: str = Field(description="Explanation for the chosen strategy")
+
     modified_task_content: Optional[str] = Field(
-        default=None, description="Modified task content if strategy is REPLAN"
+        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,
@@ -178,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
@@ -200,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
@@ -218,7 +311,8 @@ 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: