camel-ai 0.2.59__py3-none-any.whl → 0.2.82__py3-none-any.whl

camel/tasks/__init__.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,7 +10,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 from .task import Task, TaskManager
 from .task_prompt import TASK_DECOMPOSE_PROMPT, TASK_EVOLVE_PROMPT
 

camel/tasks/task.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,24 +10,164 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 
 import re
 from enum import Enum
-from typing import Callable, Dict, List, Literal, Optional, Union
+from types import GeneratorType
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    Generator,
+    Iterable,
+    List,
+    Literal,
+    Optional,
+    Union,
+)
+
+from PIL import Image
+from pydantic import BaseModel, ConfigDict, Field
 
-from pydantic import BaseModel
+if TYPE_CHECKING:
+    from camel.agents import ChatAgent
+    from camel.responses import ChatAgentResponse
+import uuid
 
-from camel.agents import ChatAgent
+from camel.logger import get_logger
 from camel.messages import BaseMessage
 from camel.prompts import TextPrompt
 
+# Note: validate_task_content moved here to avoid circular imports
 from .task_prompt import (
     TASK_COMPOSE_PROMPT,
     TASK_DECOMPOSE_PROMPT,
     TASK_EVOLVE_PROMPT,
 )
 
+logger = get_logger(__name__)
+
+
+class TaskValidationMode(Enum):
+    r"""Validation modes for different use cases."""
+
+    INPUT = "input"  # For validating task content before processing
+    OUTPUT = "output"  # For validating task results after completion
+
+
+def validate_task_content(
+    content: str,
+    task_id: str = "unknown",
+    min_length: int = 1,
+    mode: TaskValidationMode = TaskValidationMode.INPUT,
+    check_failure_patterns: bool = True,
+) -> bool:
+    r"""Unified validation for task content and results to avoid silent
+    failures. Performs comprehensive checks to ensure content meets quality
+    standards.
+
+    Args:
+        content (str): The task content or result to validate.
+        task_id (str): Task ID for logging purposes.
+            (default: :obj:`"unknown"`)
+        min_length (int): Minimum content length after stripping whitespace.
+            (default: :obj:`1`)
+        mode (TaskValidationMode): Validation mode - INPUT for task content,
+            OUTPUT for task results. (default: :obj:`TaskValidationMode.INPUT`)
+        check_failure_patterns (bool): Whether to check for failure indicators
+            in the content. Only effective in OUTPUT mode.
+            (default: :obj:`True`)
+
+    Returns:
+        bool: True if content passes validation, False otherwise.
+    """
+    # 1: Content must not be None
+    if content is None:
+        logger.warning(f"Task {task_id}: None content rejected")
+        return False
+
+    # 2: Content must not be empty after stripping whitespace
+    stripped_content = content.strip()
+    if not stripped_content:
+        logger.warning(
+            f"Task {task_id}: Empty or whitespace-only content rejected."
+        )
+        return False
+
+    # 3: Content must meet minimum meaningful length
+    if len(stripped_content) < min_length:
+        logger.warning(
+            f"Task {task_id}: Content too short ({len(stripped_content)} "
+            f"chars < {min_length} minimum). Content preview: "
+            f"'{stripped_content}'"
+        )
+        return False
+
+    # 4: For OUTPUT mode, check for failure patterns if enabled
+    if mode == TaskValidationMode.OUTPUT and check_failure_patterns:
+        content_lower = stripped_content.lower()
+
+        # Check for explicit failure indicators
+        failure_indicators = [
+            "i cannot complete",
+            "i cannot do",
+            "task failed",
+            "unable to complete",
+            "cannot be completed",
+            "failed to complete",
+            "i cannot",
+            "not possible",
+            "impossible to",
+            "cannot perform",
+        ]
+
+        if any(indicator in content_lower for indicator in failure_indicators):
+            logger.warning(
+                f"Task {task_id}: Failure indicator detected in result. "
+                f"Content preview: '{stripped_content}'"
+            )
+            return False
+
+        # Check for responses that are just error messages or refusals
+        if content_lower.startswith(("error", "failed", "cannot", "unable")):
+            logger.warning(
+                f"Task {task_id}: Error/refusal pattern detected at start. "
+                f"Content preview: '{stripped_content}'"
+            )
+            return False
+
+    # All validation checks passed
+    logger.debug(
+        f"Task {task_id}: {mode.value} validation passed "
+        f"({len(stripped_content)} chars)"
+    )
+    return True
+
+
+def is_task_result_insufficient(task: "Task") -> bool:
+    r"""Check if a task result is insufficient and should be treated as failed.
+
+    This is a convenience wrapper around validate_task_content for backward
+    compatibility and semantic clarity when checking task results.
+
+    Args:
+        task (Task): The task to check.
+
+    Returns:
+        bool: True if the result is insufficient, False otherwise.
+    """
+    if not hasattr(task, 'result') or task.result is None:
+        return True
+
+    return not validate_task_content(
+        content=task.result,
+        task_id=task.id,
+        mode=TaskValidationMode.OUTPUT,
+        check_failure_patterns=True,
+    )
+
 
 def parse_response(
     response: str, task_id: Optional[str] = None
@@ -48,8 +188,17 @@ def parse_response(
     tasks = []
     if task_id is None:
         task_id = "0"
-    for i, content in enumerate(tasks_content):
-        tasks.append(Task(content=content.strip(), id=f"{task_id}.{i}"))
+    for i, content in enumerate(tasks_content, 1):
+        stripped_content = content.strip()
+        # validate subtask content before creating the task
+        if validate_task_content(stripped_content, f"{task_id}.{i}"):
+            tasks.append(Task(content=stripped_content, id=f"{task_id}.{i}"))
+        else:
+            logger.warning(
+                f"Skipping invalid subtask {task_id}.{i} "
+                f"during decomposition: "
+                f"Content '{stripped_content}' failed validation"
+            )
     return tasks
 
 
@@ -69,21 +218,45 @@ class Task(BaseModel):
     r"""Task is specific assignment that can be passed to a agent.
 
     Attributes:
-        content: string content for task.
-        id: An unique string identifier for the task. This should
-        ideally be provided by the provider/model which created the task.
-        state: The state which should be OPEN, RUNNING, DONE or DELETED.
-        type: task type
-        parent: The parent task, None for root task.
-        subtasks: The childrent sub-tasks for the task.
-        result: The answer for the task.
+        content (str): string content for task.
+        id (str): An unique string identifier for the task. This should
+            ideally be provided by the provider/model which created the task.
+            (default: :obj:`uuid.uuid4()`)
+        state (TaskState): The state which should be OPEN, RUNNING, DONE or
+            DELETED. (default: :obj:`TaskState.FAILED`)
+        type (Optional[str]): task type. (default: :obj:`None`)
+        parent (Optional[Task]): The parent task, None for root task.
+            (default: :obj:`None`)
+        subtasks (List[Task]): The childrent sub-tasks for the task.
+            (default: :obj:`[]`)
+        result (Optional[str]): The answer for the task.
+            (default: :obj:`""`)
+        failure_count (int): The failure count for the task.
+            (default: :obj:`0`)
+        assigned_worker_id (Optional[str]): The ID of the worker assigned to
+            this task. (default: :obj:`None`)
+        dependencies (List[Task]): The dependencies for the task.
+            (default: :obj:`[]`)
+        additional_info (Optional[Dict[str, Any]]): Additional information for
+            the task. (default: :obj:`None`)
+        image_list (Optional[List[Union[Image.Image, str]]]): Optional list
+            of PIL Image objects or image URLs (strings) associated with the
+            task. (default: :obj:`None`)
+        image_detail (Literal["auto", "low", "high"]): Detail level of the
+            images associated with the task. (default: :obj:`auto`)
+        video_bytes (Optional[bytes]): Optional bytes of a video associated
+            with the task. (default: :obj:`None`)
+        video_detail (Literal["auto", "low", "high"]): Detail level of the
+            videos associated with the task. (default: :obj:`auto`)
     """
 
     content: str
 
-    id: str = ""
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
 
-    state: TaskState = TaskState.OPEN
+    state: TaskState = (
+        TaskState.FAILED
+    )  # TODO: Add logic for OPEN in workforce.py
 
     type: Optional[str] = None
 
@@ -95,7 +268,29 @@ class Task(BaseModel):
 
     failure_count: int = 0
 
-    additional_info: Optional[str] = None
+    assigned_worker_id: Optional[str] = None
+
+    dependencies: List["Task"] = []
+
+    additional_info: Optional[Dict[str, Any]] = None
+
+    image_list: Optional[List[Union[Image.Image, str]]] = None
+
+    image_detail: Literal["auto", "low", "high"] = "auto"
+
+    video_bytes: Optional[bytes] = None
+
+    video_detail: Literal["auto", "low", "high"] = "auto"
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def __repr__(self) -> str:
+        r"""Return a string representation of the task."""
+        content_preview = self.content
+        return (
+            f"Task(id='{self.id}', content='{content_preview}', "
+            f"state='{self.state.value}')"
+        )
 
     @classmethod
     def from_message(cls, message: BaseMessage) -> "Task":
@@ -117,7 +312,9 @@ class Task(BaseModel):
 
     def reset(self):
         r"""Reset Task to initial state."""
-        self.state = TaskState.OPEN
+        self.state = (
+            TaskState.FAILED
+        )  # TODO: Add logic for OPEN in workforce.py
         self.result = ""
 
     def update_result(self, result: str):
@@ -211,12 +408,15 @@ class Task(BaseModel):
 
     def decompose(
         self,
-        agent: ChatAgent,
+        agent: "ChatAgent",
         prompt: Optional[str] = None,
         task_parser: Callable[[str, str], List["Task"]] = parse_response,
-    ) -> List["Task"]:
-        r"""Decompose a task to a list of sub-tasks. It can be used for data
-        generation and planner of agent.
+        stream_callback: Optional[
+            Callable[["ChatAgentResponse"], None]
+        ] = None,
+    ) -> Union[List["Task"], Generator[List["Task"], None, None]]:
+        r"""Decompose a task to a list of sub-tasks. Automatically detects
+        streaming or non-streaming based on agent configuration.
 
         Args:
             agent (ChatAgent): An agent that used to decompose the task.
@@ -225,9 +425,16 @@ class Task(BaseModel):
             task_parser (Callable[[str, str], List[Task]], optional): A
                 function to extract Task from response. If not provided,
                 the default parse_response will be used.
+            stream_callback (Callable[[ChatAgentResponse], None], optional): A
+                callback function that receives each chunk (ChatAgentResponse)
+                during streaming. This allows tracking the decomposition
+                progress in real-time.
 
         Returns:
-            List[Task]: A list of tasks which are :obj:`Task` instances.
+            Union[List[Task], Generator[List[Task], None, None]]: If agent is
+                configured for streaming, returns a generator that yields lists
+                of new tasks as they are parsed. Otherwise returns a list of
+                all tasks.
         """
 
         role_name = agent.role_name
@@ -239,14 +446,136 @@ class Task(BaseModel):
             role_name=role_name, content=content
         )
         response = agent.step(msg)
+
+        # Auto-detect streaming based on response type
+        from camel.agents.chat_agent import StreamingChatAgentResponse
+
+        is_streaming = isinstance(
+            response, StreamingChatAgentResponse
+        ) or isinstance(response, GeneratorType)
+        if (
+            not is_streaming
+            and hasattr(response, "__iter__")
+            and not hasattr(response, "msg")
+        ):
+            is_streaming = True
+
+        if is_streaming:
+            return self._decompose_streaming(
+                response, task_parser, stream_callback=stream_callback
+            )
+        return self._decompose_non_streaming(response, task_parser)
+
+    def _decompose_streaming(
+        self,
+        response: Iterable,
+        task_parser: Callable[[str, str], List["Task"]],
+        stream_callback: Optional[
+            Callable[["ChatAgentResponse"], None]
+        ] = None,
+    ) -> Generator[List["Task"], None, None]:
+        r"""Handle streaming response for task decomposition.
+
+        Args:
+            response: Streaming response from agent
+            task_parser: Function to parse tasks from response
+            stream_callback (Callable[[ChatAgentResponse], None], optional): A
+                callback function that receives each chunk (ChatAgentResponse)
+                during streaming.
+
+        Yields:
+            List[Task]: New tasks as they are parsed from streaming response
+        """
+        accumulated_content = ""
+        yielded_count = 0
+
+        # Process streaming response
+        for chunk in response:
+            accumulated_content = chunk.msg.content
+            if stream_callback:
+                try:
+                    stream_callback(chunk)
+                except Exception:
+                    logger.warning(
+                        "stream_callback failed during decomposition",
+                        exc_info=True,
+                    )
+
+            # Try to parse partial tasks from accumulated content
+            try:
+                current_tasks = self._parse_partial_tasks(accumulated_content)
+
+                # Yield new tasks if we have more than previously yielded
+                if len(current_tasks) > yielded_count:
+                    new_tasks = current_tasks[yielded_count:]
+                    for task in new_tasks:
+                        task.additional_info = self.additional_info
+                        task.parent = self
+                    yield new_tasks
+                    yielded_count = len(current_tasks)
+
+            except Exception:
+                # If parsing fails, continue accumulating
+                continue
+
+        # Final complete parsing
+        final_tasks = task_parser(accumulated_content, self.id)
+        for task in final_tasks:
+            task.additional_info = self.additional_info
+            task.parent = self
+        self.subtasks = final_tasks
+
+    def _decompose_non_streaming(
+        self, response, task_parser: Callable[[str, str], List["Task"]]
+    ) -> List["Task"]:
+        r"""Handle non-streaming response for task decomposition.
+
+        Args:
+            response: Regular response from agent
+            task_parser: Function to parse tasks from response
+
+        Returns:
+            List[Task]: All parsed tasks
+        """
         tasks = task_parser(response.msg.content, self.id)
         for task in tasks:
             task.additional_info = self.additional_info
+            task.parent = self
+        self.subtasks = tasks
+        return tasks
+
+    def _parse_partial_tasks(self, response: str) -> List["Task"]:
+        r"""Parse tasks from potentially incomplete response.
+
+        Args:
+            response: Partial response content
+
+        Returns:
+            List[Task]: Tasks parsed from complete <task></task> blocks
+        """
+        pattern = r"<task>(.*?)</task>"
+        tasks_content = re.findall(pattern, response, re.DOTALL)
+
+        tasks = []
+        task_id = self.id or "0"
+
+        for i, content in enumerate(tasks_content, 1):
+            stripped_content = content.strip()
+            if validate_task_content(stripped_content, f"{task_id}.{i}"):
+                tasks.append(
+                    Task(content=stripped_content, id=f"{task_id}.{i}")
+                )
+            else:
+                logger.warning(
+                    f"Skipping invalid subtask {task_id}.{i} "
+                    f"during streaming decomposition: "
+                    f"Content '{stripped_content}' failed validation"
+                )
         return tasks
 
     def compose(
         self,
-        agent: ChatAgent,
+        agent: "ChatAgent",
         template: TextPrompt = TASK_COMPOSE_PROMPT,
         result_parser: Optional[Callable[[str], str]] = None,
     ):
@@ -270,6 +599,10 @@ class Task(BaseModel):
             role_name=role_name,
             content=self.content,
             additional_info=self.additional_info,
+            image_list=self.image_list,
+            image_detail=self.image_detail,
+            video_bytes=self.video_bytes,
+            video_detail=self.video_detail,
             other_results=sub_tasks_result,
         )
         msg = BaseMessage.make_user_message(
@@ -395,12 +728,13 @@ class TaskManager:
     def evolve(
         self,
         task: Task,
-        agent: ChatAgent,
+        agent: "ChatAgent",
         template: Optional[TextPrompt] = None,
         task_parser: Optional[Callable[[str, str], List[Task]]] = None,
     ) -> Optional[Task]:
         r"""Evolve a task to a new task.
             Evolve is only used for data generation.
+
         Args:
             task (Task): A given task.
             agent (ChatAgent): An agent that used to evolve the task.
@@ -419,7 +753,12 @@ class TaskManager:
         role_name = agent.role_name
         content = template.format(role_name=role_name, content=task.content)
         msg = BaseMessage.make_user_message(
-            role_name=role_name, content=content
+            role_name=role_name,
+            content=content,
+            image_list=task.image_list,
+            image_detail=task.image_detail,
+            video_bytes=task.video_bytes,
+            video_detail=task.video_detail,
         )
         response = agent.step(msg)
         if task_parser is None:

camel/tasks/task_prompt.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,7 +10,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 from camel.prompts import TextPrompt
 
 # ruff: noqa: E501
@@ -47,7 +47,7 @@ The related tasks result and status:
 
 {other_results}
 
-so, the final answer of the root task is: 
+so, the final answer of the root task is:
 """
 )
 

camel/terminators/__init__.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,7 +10,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 from .base import BaseTerminator
 from .response_terminator import ResponseTerminator, ResponseWordsTerminator
 from .token_limit_terminator import TokenLimitTerminator

camel/terminators/base.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,7 +10,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 from abc import ABC, abstractmethod
 from typing import List, Optional, Tuple
 

camel/terminators/response_terminator.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,7 +10,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 from collections import defaultdict
 from typing import Dict, List, Optional, Tuple
 

camel/terminators/token_limit_terminator.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,7 +10,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 from typing import Optional, Tuple
 
 from camel.terminators.base import BaseTerminator