docs: Update the missing docstrings on different modules (#911) (#1079)

Co-authored-by: Wendong-Fan <[email protected]>
Co-authored-by: Asher-hss <[email protected]>
Co-authored-by: Daniel <[email protected]>
Co-authored-by: Wendong <[email protected]>
Co-authored-by: Zeyu Zhang <[email protected]>
Co-authored-by: Guohao Li <[email protected]>
Co-authored-by: Isaac Jin <[email protected]>

Author: 7 people

camel/agents/chat_agent.py

@@ -106,6 +106,11 @@ def __str__(self) -> str:
         )
 
     def as_dict(self) -> dict[str, Any]:
+        r"""Returns the function calling record as a dictionary.
+
+        Returns:
+            dict[str, Any]: The function calling record as a dictionary.
+        """
         return self.model_dump()
 
 
@@ -221,6 +226,15 @@ def __init__(
 
     # ruff: noqa: E501
     def _generate_tool_prompt(self, tool_schema_list: List[Dict]) -> str:
+        r"""Generates a tool prompt based on the provided tool schema list.
+
+        Args:
+            tool_schema_list (List[Dict]): A list of dictionaries, each
+                containing a tool schema.
+
+        Returns:
+            str: A string representing the tool prompt.
+        """
         tool_prompts = []
 
         for tool in tool_schema_list:
@@ -241,21 +255,36 @@ def _generate_tool_prompt(self, tool_schema_list: List[Dict]) -> str:
 
     {tool_prompt_str}
 
-    If you choose to call a function ONLY reply in the following format with no prefix or suffix:
+    If you choose to call a function ONLY reply in the following format with no
+    prefix or suffix:
 
-    <function=example_function_name>{{"example_name": "example_value"}}</function>
+    <function=example_function_name>{{"example_name": "example_value"}}
+    </function>
 
     Reminder:
-    - Function calls MUST follow the specified format, start with <function= and end with </function>
+    - Function calls MUST follow the specified format, start with <function=
+      and end with </function>
     - Required parameters MUST be specified
     - Only call one function at a time
     - Put the entire function call reply on one line
-    - If there is no function call available, answer the question like normal with your current knowledge and do not tell the user about function calls
+    - If there is no function call available, answer the question like normal 
+      with your current knowledge and do not tell the user about function calls
     """
     '''
         return final_prompt
 
     def _parse_tool_response(self, response: str):
+        r"""Parses the tool response to extract the function name and
+        arguments.
+
+        Args:
+            response (str): The response from the model containing the
+                function call.
+
+        Returns:
+            Optional[Dict[str, Any]]: The parsed function name and arguments
+                if found, otherwise :obj:`None`.
+        """
         function_regex = r"<function=(\w+)>(.*?)</function>"
         match = re.search(function_regex, response)
 
@@ -270,12 +299,7 @@ def _parse_tool_response(self, response: str):
         return None
 
     def reset(self):
-        r"""Resets the :obj:`ChatAgent` to its initial state and returns the
-        stored messages.
-
-        Returns:
-            List[BaseMessage]: The stored messages.
-        """
+        r"""Resets the :obj:`ChatAgent` to its initial state."""
         self.terminated = False
         self.init_messages()
         for terminator in self.response_terminators:
@@ -292,7 +316,7 @@ def system_message(self) -> Optional[BaseMessage]:
         return self._system_message
 
     @system_message.setter
-    def system_message(self, message: BaseMessage):
+    def system_message(self, message: BaseMessage) -> None:
         r"""The setter method for the property :obj:`system_message`.
 
         Args:
@@ -827,6 +851,17 @@ def _structure_output_with_function(
     ]:
         r"""Internal function of structuring the output of the agent based on
         the given output schema.
+
+        Args:
+            response_format (Type[BaseModel]): The output schema to use for
+                structuring the output.
+
+        Returns:
+            Tuple[List[BaseMessage], List[str], Dict[str, int], str,
+                FunctionCallingRecord, int]:
+                A tuple containing the output messages, finish reasons, usage
+                dictionary, response ID, function calling record, and number of
+                tokens.
         """
         from camel.toolkits import FunctionTool
 
@@ -919,9 +954,39 @@ def _step_get_info(
         num_tokens: int,
         external_tool_request: Optional[ChatCompletionMessageToolCall] = None,
     ) -> Dict[str, Any]:
-        # Loop over responses terminators, get list of termination
-        # tuples with whether the terminator terminates the agent
-        # and termination reason
+        r"""Process the output of a chat step and gather information about the
+        step.
+
+        This method checks for termination conditions, updates the agent's
+        state, and collects information about the chat step, including tool
+        calls and termination reasons.
+
+        Args:
+            output_messages (List[BaseMessage]): The messages generated in
+                this step.
+            finish_reasons (List[str]): The reasons for finishing the
+                generation for each message.
+            usage_dict (Dict[str, int]): Dictionary containing token usage
+                information.
+            response_id (str): The ID of the response from the model.
+            tool_calls (List[FunctionCallingRecord]): Records of function calls
+                made during this step.
+            num_tokens (int): The number of tokens used in this step.
+            external_tool_request (Optional[ChatCompletionMessageToolCall]):
+                Any external tool request made during this step.
+                (default::obj:`None`)
+
+        Returns:
+            Dict[str, Any]: A dictionary containing information about the chat
+                step, including termination status, reasons, and tool call
+                information.
+
+        Note:
+            This method iterates over all response terminators and checks if
+            any of them signal termination. If a terminator signals
+            termination, the agent's state is updated accordingly, and the
+            termination reason is recorded.
+        """
         termination = [
             terminator.is_terminated(output_messages)
             for terminator in self.response_terminators
@@ -952,7 +1017,8 @@ def _step_get_info(
     def handle_batch_response(
         self, response: ChatCompletion
     ) -> Tuple[List[BaseMessage], List[str], Dict[str, int], str]:
-        r"""
+        r"""Process a batch response from the model and extract the necessary
+        information.
 
         Args:
             response (dict): Model response.
@@ -985,7 +1051,18 @@ def handle_batch_response(
             response.id,
         )
 
-    def _safe_model_dump(self, obj):
+    def _safe_model_dump(self, obj) -> dict:
+        r"""Safely dump a Pydantic model to a dictionary.
+
+        This method attempts to use the `model_dump` method if available,
+        otherwise it falls back to the `dict` method.
+
+        Args:
+            obj: The Pydantic model instance to be dumped.
+
+        Returns:
+            dict: A dictionary representation of the Pydantic model.
+        """
         # Check if the `model_dump` method exists (Pydantic v2)
         if hasattr(obj, 'model_dump'):
             return obj.model_dump()
@@ -1000,7 +1077,8 @@ def handle_stream_response(
         response: Stream[ChatCompletionChunk],
         prompt_tokens: int,
     ) -> Tuple[List[BaseMessage], List[str], Dict[str, int], str]:
-        r"""
+        r"""Process a stream response from the model and extract the necessary
+        information.
 
         Args:
             response (dict): Model response.

camel/configs/base_config.py

@@ -20,6 +20,12 @@
 
 
 class BaseConfig(ABC, BaseModel):
+    r"""Base configuration class for all models.
+
+    This class provides a common interface for all models, ensuring that all
+    models have a consistent set of attributes and methods.
+    """
+
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
         extra="forbid",
@@ -38,6 +44,12 @@ class BaseConfig(ABC, BaseModel):
     @field_validator("tools", mode="before")
     @classmethod
     def fields_type_checking(cls, tools):
+        r"""Validate the type of tools in the configuration.
+
+        This method ensures that the tools provided in the configuration are
+        instances of `FunctionTool`. If any tool is not an instance of
+        `FunctionTool`, it raises a ValueError.
+        """
         if tools is not None:
             from camel.toolkits import FunctionTool
 
@@ -50,6 +62,15 @@ def fields_type_checking(cls, tools):
         return tools
 
     def as_dict(self) -> dict[str, Any]:
+        r"""Convert the current configuration to a dictionary.
+
+        This method converts the current configuration object to a dictionary
+        representation, which can be used for serialization or other purposes.
+
+        Returns:
+            dict[str, Any]: A dictionary representation of the current
+                configuration.
+        """
         config_dict = self.model_dump()
 
         tools_schema = None

camel/configs/gemini_config.py

@@ -87,6 +87,12 @@ class GeminiConfig(BaseConfig):
     @model_validator(mode="before")
     @classmethod
     def model_type_checking(cls, data: Any):
+        r"""Validate the type of tools in the configuration.
+
+        This method ensures that the tools provided in the configuration are
+        instances of `FunctionTool`. If any tool is not an instance of
+        `FunctionTool`, it raises a ValueError.
+        """
         if isinstance(data, dict):
             response_schema = data.get("response_schema")
             safety_settings = data.get("safety_settings")
@@ -111,36 +117,38 @@ def model_type_checking(cls, data: Any):
 
         if response_schema and not isinstance(response_schema, Schema):
             raise ValueError(
-                "The response_schema should be "
-                "an instance of `google.generativeai.protos.Schema`."
+                "The response_schema should be an instance of "
+                "google.generativeai.protos.Schema."
             )
 
         if safety_settings and not isinstance(
             safety_settings, SafetySettingOptions
         ):
             raise ValueError(
-                "The response_schema should be an instance of "
-                "`google.generativeai.types.safety_types.SafetySettingOptions`."
+                "The safety_settings should be an instance of "
+                "google.generativeai.types.safety_types."
+                "SafetySettingOptions."
             )
 
         if tools is not None:
             for tool in tools:
                 if not isinstance(tool, FunctionLibraryType):
                     raise ValueError(
                         "The tool should be an instance of "
-                        "`google.generativeai.types.content_types.FunctionLibraryType`."
+                        "google.generativeai.types.content_types."
+                        "FunctionLibraryType."
                     )
         if tool_config and not isinstance(tool_config, ToolConfigType):
             raise ValueError(
-                "The response_schema should be an instance of "
-                "`google.generativeai.types.content_types.ToolConfigType`."
+                "The tool_config should be an instance of "
+                "google.generativeai.types.content_types.ToolConfigType."
             )
         if request_options and not isinstance(
             request_options, RequestOptionsType
         ):
             raise ValueError(
-                "The response_schema should be an instance of "
-                "`google.generativeai.types.helper_types.RequestOptionsType`."
+                "The request_options should be an instance of "
+                "google.generativeai.types.helper_types.RequestOptionsType."
             )
         return data