camel-ai 0.2.6__py3-none-any.whl → 0.2.7__py3-none-any.whl

camel/prompts/image_craft.py

@@ -18,6 +18,14 @@ from camel.types import RoleType
 
 
 class ImageCraftPromptTemplateDict(TextPromptDict):
+    r"""A dictionary containing :obj:`TextPrompt` used in the `ImageCraft`
+    task.
+
+    Attributes:
+        ASSISTANT_PROMPT (TextPrompt): A prompt for the AI assistant to create
+            an original image based on the provided descriptive captions.
+    """
+
     ASSISTANT_PROMPT = TextPrompt(
         """You are tasked with creating an original image based on
         the provided descriptive captions. Use your imagination

camel/prompts/video_description_prompt.py

@@ -19,6 +19,14 @@ from camel.types import RoleType
 
 # flake8: noqa :E501
 class VideoDescriptionPromptTemplateDict(TextPromptDict):
+    r"""A dictionary containing :obj:`TextPrompt` used in the `VideoDescription`
+    task.
+
+    Attributes:
+        ASSISTANT_PROMPT (TextPrompt): A prompt for the AI assistant to
+            provide a shot description of the content of the current video.
+    """
+
     ASSISTANT_PROMPT = TextPrompt(
         """You are a master of video analysis. 
         Please provide a shot description of the content of the current video."""

camel/retrievers/vector_retriever.py

@@ -76,6 +76,7 @@ class VectorRetriever(BaseRetriever):
         max_characters: int = 500,
         embed_batch: int = 50,
         should_chunk: bool = True,
+        extra_info: Optional[dict] = None,
         **kwargs: Any,
     ) -> None:
         r"""Processes content from local file path, remote URL, string
@@ -93,6 +94,8 @@ class VectorRetriever(BaseRetriever):
             embed_batch (int): Size of batch for embeddings. Defaults to `50`.
             should_chunk (bool): If True, divide the content into chunks,
                 otherwise skip chunking. Defaults to True.
+            extra_info (Optional[dict]): Extra information to be added
+                to the payload. Defaults to None.
             **kwargs (Any): Additional keyword arguments for content parsing.
         """
         from unstructured.documents.elements import Element
@@ -153,12 +156,13 @@ class VectorRetriever(BaseRetriever):
                     chunk_metadata = {"metadata": chunk.metadata.to_dict()}
                     # Remove the 'orig_elements' key if it exists
                     chunk_metadata["metadata"].pop("orig_elements", "")
-
+                    extra_info = extra_info or {}
                     chunk_text = {"text": str(chunk)}
                     combined_dict = {
                         **content_path_info,
                         **chunk_metadata,
                         **chunk_text,
+                        **extra_info,
                     }
 
                     records.append(

camel/societies/role_playing.py

@@ -23,10 +23,10 @@ from camel.agents import (
 from camel.generators import SystemMessageGenerator
 from camel.human import Human
 from camel.messages import BaseMessage
-from camel.models import BaseModelBackend
+from camel.models import BaseModelBackend, ModelFactory
 from camel.prompts import TextPrompt
 from camel.responses import ChatAgentResponse
-from camel.types import RoleType, TaskType
+from camel.types import ModelPlatformType, ModelType, RoleType, TaskType
 
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.WARNING)
@@ -55,7 +55,8 @@ class RolePlaying:
             If not specified, set the criteria to improve task performance.
         model (BaseModelBackend, optional): The model backend to use for
             generating responses. If specified, it will override the model in
-            all agents. (default: :obj:`None`)
+            all agents if not specified in agent-specific kwargs. (default:
+            :obj:`OpenAIModel` with `GPT_4O_MINI`)
         task_type (TaskType, optional): The type of task to perform.
             (default: :obj:`TaskType.AI_SOCIETY`)
         assistant_agent_kwargs (Dict, optional): Additional arguments to pass
@@ -103,16 +104,21 @@ class RolePlaying:
     ) -> None:
         if model is not None:
             logger.warning(
-                "The provided model will override the model settings in "
-                "all agents, including any configurations passed "
-                "through assistant_agent_kwargs, user_agent_kwargs, and "
-                "other agent-specific kwargs."
+                "Model provided globally is set for all agents if not"
+                " already specified in agent_kwargs."
             )
 
         self.with_task_specify = with_task_specify
         self.with_task_planner = with_task_planner
         self.with_critic_in_the_loop = with_critic_in_the_loop
-        self.model = model
+        self.model: BaseModelBackend = (
+            model
+            if model is not None
+            else ModelFactory.create(
+                model_platform=ModelPlatformType.DEFAULT,
+                model_type=ModelType.DEFAULT,
+            )
+        )
         self.task_type = task_type
         self.task_prompt = task_prompt
 
@@ -204,8 +210,9 @@ class RolePlaying:
             task_specify_meta_dict.update(extend_task_specify_meta_dict or {})
             if self.model is not None:
                 if task_specify_agent_kwargs is None:
-                    task_specify_agent_kwargs = {}
-                task_specify_agent_kwargs.update(dict(model=self.model))
+                    task_specify_agent_kwargs = {'model': self.model}
+                elif 'model' not in task_specify_agent_kwargs:
+                    task_specify_agent_kwargs.update(dict(model=self.model))
             task_specify_agent = TaskSpecifyAgent(
                 task_type=self.task_type,
                 output_language=output_language,
@@ -237,8 +244,9 @@ class RolePlaying:
         if self.with_task_planner:
             if self.model is not None:
                 if task_planner_agent_kwargs is None:
-                    task_planner_agent_kwargs = {}
-                task_planner_agent_kwargs.update(dict(model=self.model))
+                    task_planner_agent_kwargs = {'model': self.model}
+                elif 'model' not in task_planner_agent_kwargs:
+                    task_planner_agent_kwargs.update(dict(model=self.model))
             task_planner_agent = TaskPlannerAgent(
                 output_language=output_language,
                 **(task_planner_agent_kwargs or {}),
@@ -332,11 +340,13 @@ class RolePlaying:
         """
         if self.model is not None:
             if assistant_agent_kwargs is None:
-                assistant_agent_kwargs = {}
-            assistant_agent_kwargs.update(dict(model=self.model))
+                assistant_agent_kwargs = {'model': self.model}
+            elif 'model' not in assistant_agent_kwargs:
+                assistant_agent_kwargs.update(dict(model=self.model))
             if user_agent_kwargs is None:
-                user_agent_kwargs = {}
-            user_agent_kwargs.update(dict(model=self.model))
+                user_agent_kwargs = {'model': self.model}
+            elif 'model' not in user_agent_kwargs:
+                user_agent_kwargs.update(dict(model=self.model))
 
         self.assistant_agent = ChatAgent(
             init_assistant_sys_msg,
@@ -394,8 +404,9 @@ class RolePlaying:
                 )
                 if self.model is not None:
                     if critic_kwargs is None:
-                        critic_kwargs = {}
-                    critic_kwargs.update(dict(model=self.model))
+                        critic_kwargs = {'model': self.model}
+                    elif 'model' not in critic_kwargs:
+                        critic_kwargs.update(dict(model=self.model))
                 self.critic = CriticAgent(
                     self.critic_sys_msg,
                     **(critic_kwargs or {}),

camel/societies/workforce/base.py

@@ -19,6 +19,12 @@ from camel.societies.workforce.utils import check_if_running
 
 
 class BaseNode(ABC):
+    r"""Base class for all nodes in the workforce.
+
+    Args:
+        description (str): Description of the node.
+    """
+
     def __init__(self, description: str) -> None:
         self.node_id = str(id(self))
         self.description = description
@@ -27,7 +33,7 @@ class BaseNode(ABC):
 
     @check_if_running(False)
     def reset(self, *args: Any, **kwargs: Any) -> Any:
-        """Resets the node to its initial state."""
+        r"""Resets the node to its initial state."""
         self._channel = TaskChannel()
         self._running = False
 

camel/societies/workforce/task_channel.py

@@ -84,6 +84,9 @@ class TaskChannel:
         self._task_dict: Dict[str, Packet] = {}
 
     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 in self._task_id_list:
@@ -96,6 +99,9 @@ class TaskChannel:
                 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.
+        """
         async with self._condition:
             while True:
                 for task_id in self._task_id_list:
@@ -147,12 +153,14 @@ class TaskChannel:
             self._condition.notify_all()
 
     async def remove_task(self, task_id: str) -> None:
+        r"""Remove a task from the channel."""
         async with self._condition:
             self._task_id_list.remove(task_id)
             self._task_dict.pop(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 in self._task_id_list:
@@ -162,11 +170,13 @@ class TaskChannel:
             return dependency_ids
 
     async def get_task_by_id(self, task_id: str) -> Task:
+        r"""Get a task from the channel by its ID."""
         async with self._condition:
             if task_id not in self._task_id_list:
                 raise ValueError(f"Task {task_id} not found.")
             return self._task_dict[task_id].task
 
     async def get_channel_debug_info(self) -> str:
+        r"""Get the debug information of the channel."""
         async with self._condition:
             return str(self._task_dict) + '\n' + str(self._task_id_list)

camel/societies/workforce/utils.py

@@ -18,6 +18,8 @@ from pydantic import BaseModel, Field
 
 
 class WorkerConf(BaseModel):
+    r"""The configuration of a worker."""
+
     role: str = Field(
         description="The role of the agent working in the work node."
     )
@@ -31,6 +33,8 @@ class WorkerConf(BaseModel):
 
 
 class TaskResult(BaseModel):
+    r"""The result of a task."""
+
     content: str = Field(description="The result of the task.")
     failed: bool = Field(
         description="Flag indicating whether the task processing failed."
@@ -38,6 +42,8 @@ class TaskResult(BaseModel):
 
 
 class TaskAssignResult(BaseModel):
+    r"""The result of task assignment."""
+
     assignee_id: str = Field(
         description="The ID of the workforce that is assigned to the task."
     )

camel/societies/workforce/worker.py

@@ -110,9 +110,11 @@ class Worker(BaseNode, ABC):
 
     @check_if_running(False)
     async def start(self):
+        r"""Start the worker."""
         await self._listen_to_channel()
 
     @check_if_running(True)
     def stop(self):
+        r"""Stop the worker."""
         self._running = False
         return

camel/storages/vectordb_storages/qdrant.py

@@ -11,8 +11,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+import logging
 from datetime import datetime
-from typing import Any, Dict, List, Optional, Tuple, Union, cast
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union, cast
+
+if TYPE_CHECKING:
+    from qdrant_client import QdrantClient
 
 from camel.storages.vectordb_storages import (
     BaseVectorStorage,
@@ -25,6 +29,7 @@ from camel.types import VectorDistance
 from camel.utils import dependencies_required
 
 _qdrant_local_client_map: Dict[str, Tuple[Any, int]] = {}
+logger = logging.getLogger(__name__)
 
 
 class QdrantStorage(BaseVectorStorage):
@@ -107,7 +112,13 @@ class QdrantStorage(BaseVectorStorage):
             hasattr(self, "delete_collection_on_del")
             and self.delete_collection_on_del
         ):
-            self._delete_collection(self.collection_name)
+            try:
+                self._delete_collection(self.collection_name)
+            except RuntimeError as e:
+                logger.error(
+                    f"Failed to delete collection"
+                    f" '{self.collection_name}': {e}"
+                )
 
     def _create_client(
         self,
@@ -244,6 +255,10 @@ class QdrantStorage(BaseVectorStorage):
             "config": collection_info.config,
         }
 
+    def close_client(self, **kwargs):
+        r"""Closes the client connection to the Qdrant storage."""
+        self._client.close(**kwargs)
+
     def add(
         self,
         records: List[VectorRecord],
@@ -273,36 +288,124 @@ class QdrantStorage(BaseVectorStorage):
                 f"{op_info}."
             )
 
-    def delete(
-        self,
-        ids: List[str],
-        **kwargs: Any,
+    def update_payload(
+        self, ids: List[str], payload: Dict[str, Any], **kwargs: Any
     ) -> None:
-        r"""Deletes a list of vectors identified by their IDs from the storage.
+        r"""Updates the payload of the vectors identified by their IDs.
 
         Args:
             ids (List[str]): List of unique identifiers for the vectors to be
-                deleted.
+                updated.
+            payload (Dict[str, Any]): List of payloads to be updated.
             **kwargs (Any): Additional keyword arguments.
 
         Raises:
-            RuntimeError: If there is an error during the deletion process.
+            RuntimeError: If there is an error during the update process.
         """
         from qdrant_client.http.models import PointIdsList, UpdateStatus
 
         points = cast(List[Union[str, int]], ids)
-        op_info = self._client.delete(
+
+        op_info = self._client.set_payload(
             collection_name=self.collection_name,
-            points_selector=PointIdsList(points=points),
-            wait=True,
+            payload=payload,
+            points=PointIdsList(points=points),
             **kwargs,
         )
         if op_info.status != UpdateStatus.COMPLETED:
             raise RuntimeError(
-                "Failed to delete vectors in Qdrant, operation info: "
+                "Failed to update payload in Qdrant, operation info: "
                 f"{op_info}"
             )
 
+    def delete_collection(self) -> None:
+        r"""Deletes the entire collection in the Qdrant storage."""
+        self._delete_collection(self.collection_name)
+
+    def delete(
+        self,
+        ids: Optional[List[str]] = None,
+        payload_filter: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        r"""Deletes points from the collection based on either IDs or payload
+        filters.
+
+        Args:
+            ids (Optional[List[str]], optional): List of unique identifiers
+                for the vectors to be deleted.
+            payload_filter (Optional[Dict[str, Any]], optional): A filter for
+                the payload to delete points matching specific conditions. If
+                `ids` is provided, `payload_filter` will be ignored unless both
+                are combined explicitly.
+            **kwargs (Any): Additional keyword arguments pass to `QdrantClient.
+                delete`.
+
+        Examples:
+            >>> # Delete points with IDs "1", "2", and "3"
+            >>> storage.delete(ids=["1", "2", "3"])
+            >>> # Delete points with payload filter
+            >>> storage.delete(payload_filter={"name": "Alice"})
+
+        Raises:
+            ValueError: If neither `ids` nor `payload_filter` is provided.
+            RuntimeError: If there is an error during the deletion process.
+
+        Notes:
+            - If `ids` is provided, the points with these IDs will be deleted
+                directly, and the `payload_filter` will be ignored.
+            - If `ids` is not provided but `payload_filter` is, then points
+                matching the `payload_filter` will be deleted.
+        """
+        from qdrant_client.http.models import (
+            Condition,
+            FieldCondition,
+            Filter,
+            MatchValue,
+            PointIdsList,
+            UpdateStatus,
+        )
+
+        if not ids and not payload_filter:
+            raise ValueError(
+                "You must provide either `ids` or `payload_filter` to delete "
+                "points."
+            )
+
+        if ids:
+            op_info = self._client.delete(
+                collection_name=self.collection_name,
+                points_selector=PointIdsList(
+                    points=cast(List[Union[int, str]], ids)
+                ),
+                **kwargs,
+            )
+            if op_info.status != UpdateStatus.COMPLETED:
+                raise RuntimeError(
+                    "Failed to delete vectors in Qdrant, operation info: "
+                    f"{op_info}"
+                )
+
+        if payload_filter:
+            filter_conditions = [
+                FieldCondition(key=key, match=MatchValue(value=value))
+                for key, value in payload_filter.items()
+            ]
+
+            op_info = self._client.delete(
+                collection_name=self.collection_name,
+                points_selector=Filter(
+                    must=cast(List[Condition], filter_conditions)
+                ),
+                **kwargs,
+            )
+
+            if op_info.status != UpdateStatus.COMPLETED:
+                raise RuntimeError(
+                    "Failed to delete vectors in Qdrant, operation info: "
+                    f"{op_info}"
+                )
+
     def status(self) -> VectorDBStatus:
         status = self._get_collection_info(self.collection_name)
         return VectorDBStatus(
@@ -313,6 +416,7 @@ class QdrantStorage(BaseVectorStorage):
     def query(
         self,
         query: VectorDBQuery,
+        filter_conditions: Optional[Dict[str, Any]] = None,
         **kwargs: Any,
     ) -> List[VectorDBQueryResult]:
         r"""Searches for similar vectors in the storage based on the provided
@@ -321,31 +425,50 @@ class QdrantStorage(BaseVectorStorage):
         Args:
             query (VectorDBQuery): The query object containing the search
                 vector and the number of top similar vectors to retrieve.
+            filter_conditions (Optional[Dict[str, Any]], optional): A
+                dictionary specifying conditions to filter the query results.
             **kwargs (Any): Additional keyword arguments.
 
         Returns:
             List[VectorDBQueryResult]: A list of vectors retrieved from the
                 storage based on similarity to the query vector.
         """
-        # TODO: filter
+        from qdrant_client.http.models import (
+            Condition,
+            FieldCondition,
+            Filter,
+            MatchValue,
+        )
+
+        # Construct filter if filter_conditions is provided
+        search_filter = None
+        if filter_conditions:
+            must_conditions = [
+                FieldCondition(key=key, match=MatchValue(value=value))
+                for key, value in filter_conditions.items()
+            ]
+            search_filter = Filter(must=cast(List[Condition], must_conditions))
+
+        # Execute the search with optional filter
         search_result = self._client.search(
             collection_name=self.collection_name,
             query_vector=query.query_vector,
             with_payload=True,
             with_vectors=True,
             limit=query.top_k,
+            query_filter=search_filter,
             **kwargs,
         )
-        query_results = []
-        for point in search_result:
-            query_results.append(
-                VectorDBQueryResult.create(
-                    similarity=point.score,
-                    id=str(point.id),
-                    payload=point.payload,
-                    vector=point.vector,  # type: ignore[arg-type]
-                )
+
+        query_results = [
+            VectorDBQueryResult.create(
+                similarity=point.score,
+                id=str(point.id),
+                payload=point.payload,
+                vector=point.vector,  # type: ignore[arg-type]
             )
+            for point in search_result
+        ]
 
         return query_results
 
@@ -363,6 +486,6 @@ class QdrantStorage(BaseVectorStorage):
         pass
 
     @property
-    def client(self) -> Any:
+    def client(self) -> "QdrantClient":
         r"""Provides access to the underlying vector database client."""
         return self._client

camel/tasks/task.py

@@ -130,6 +130,11 @@ class Task(BaseModel):
         self.set_state(TaskState.DONE)
 
     def set_id(self, id: str):
+        r"""Set the id of the task.
+
+        Args:
+            id (str): The id of the task.
+        """
         self.id = id
 
     def set_state(self, state: TaskState):
@@ -147,10 +152,20 @@ class Task(BaseModel):
             self.parent.set_state(state)
 
     def add_subtask(self, task: "Task"):
+        r"""Add a subtask to the current task.
+
+        Args:
+            task (Task): The subtask to be added.
+        """
         task.parent = self
         self.subtasks.append(task)
 
     def remove_subtask(self, id: str):
+        r"""Remove a subtask from the current task.
+
+        Args:
+            id (str): The id of the subtask to be removed.
+        """
         self.subtasks = [task for task in self.subtasks if task.id != id]
 
     def get_running_task(self) -> Optional["Task"]:

camel/terminators/base.py

@@ -18,6 +18,8 @@ from camel.messages import BaseMessage
 
 
 class BaseTerminator(ABC):
+    r"""Base class for terminators."""
+
     def __init__(self, *args, **kwargs) -> None:
         self._terminated: bool = False
         self._termination_reason: Optional[str] = None
@@ -32,6 +34,8 @@ class BaseTerminator(ABC):
 
 
 class ResponseTerminator(BaseTerminator):
+    r"""A terminator that terminates the conversation based on the response."""
+
     @abstractmethod
     def is_terminated(
         self, messages: List[BaseMessage]

camel/terminators/response_terminator.py

@@ -122,6 +122,7 @@ class ResponseWordsTerminator(ResponseTerminator):
         return self._terminated, self._termination_reason
 
     def reset(self):
+        r"""Reset the terminator."""
         self._terminated = False
         self._termination_reason = None
         self._word_count_dict = defaultdict(int)

camel/terminators/token_limit_terminator.py

@@ -53,5 +53,6 @@ class TokenLimitTerminator(BaseTerminator):
         return self._terminated, self._termination_reason
 
     def reset(self):
+        r"""Reset the terminator."""
         self._terminated = False
         self._termination_reason = None

camel/toolkits/__init__.py

@@ -17,10 +17,10 @@ from .function_tool import (
     OpenAIFunction,
     get_openai_function_schema,
     get_openai_tool_schema,
+    generate_docstring,
 )
 from .open_api_specs.security_config import openapi_security_config
 
-
 from .math_toolkit import MathToolkit, MATH_FUNCS
 from .search_toolkit import SearchToolkit, SEARCH_FUNCS
 from .weather_toolkit import WeatherToolkit, WEATHER_FUNCS
@@ -39,6 +39,7 @@ from .slack_toolkit import SlackToolkit
 from .twitter_toolkit import TwitterToolkit, TWITTER_FUNCS
 from .open_api_toolkit import OpenAPIToolkit
 from .retrieval_toolkit import RetrievalToolkit
+from .notion_toolkit import NotionToolkit
 
 __all__ = [
     'BaseToolkit',
@@ -46,6 +47,7 @@ __all__ = [
     'OpenAIFunction',
     'get_openai_function_schema',
     'get_openai_tool_schema',
+    "generate_docstring",
     'openapi_security_config',
     'GithubToolkit',
     'MathToolkit',
@@ -63,6 +65,7 @@ __all__ = [
     'AskNewsToolkit',
     'AsyncAskNewsToolkit',
     'GoogleScholarToolkit',
+    'NotionToolkit',
     'ArxivToolkit',
     'MATH_FUNCS',
     'SEARCH_FUNCS',

camel/toolkits/base.py

@@ -19,5 +19,14 @@ from camel.utils import AgentOpsMeta
 
 
 class BaseToolkit(metaclass=AgentOpsMeta):
+    r"""Base class for toolkits."""
+
     def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of FunctionTool objects representing the
+        functions in the toolkit.
+
+        Returns:
+            List[FunctionTool]: A list of FunctionTool objects
+                representing the functions in the toolkit.
+        """
         raise NotImplementedError("Subclasses must implement this method.")