docs: update api docstring

cozepy/bots/__init__.py

@@ -137,6 +137,25 @@ def update(
         prompt_info: BotPromptInfo = None,
         onboarding_info: BotOnboardingInfo = None,
     ) -> None:
+        """
+        Update the configuration of a bot.
+        This API can be used to update all bots created through the Coze platform or via the API.
+        In addition to updating the bot's name and description, avatar, personality and reply logic,
+        and opening remarks, this API also supports binding a knowledge base to the bot.
+
+        docs en: https://www.coze.com/docs/developer_guides/update_bot
+        docs zh: https://www.coze.cn/docs/developer_guides/update_bot
+
+        :param bot_id: The ID of the bot that the API interacts with.
+        :param name: The name of the bot. It should be 1 to 20 characters long.
+        :param description: The description of the Bot. It can be 0 to 500 characters long. The default is empty.
+        :param icon_file_id: The file ID for the Bot's avatar. If no file ID is specified, the Douzhu platform will
+        assign a default avatar for the bot. To use a custom avatar, first upload the local file through the Upload
+        file interface and obtain the file ID from the interface response.
+        :param prompt_info: The personality and reply logic of the bot.
+        :param onboarding_info: The settings related to the bot's opening remarks.
+        :return: None
+        """
         url = f"{self._base_url}/v1/bot/update"
         body = {
             "bot_id": bot_id,
@@ -169,9 +188,15 @@ def retrieve(self, *, bot_id: str) -> Bot:
         """
         Get the configuration information of the bot, which must have been published
         to the Bot as API channel.
+        获取指定 Bot 的配置信息，此 Bot 必须已发布到 Bot as API 渠道中。
 
-        :docs: https://www.coze.com/docs/developer_guides/get_metadata
-        :calls: `GET /v1/bot/get_online_info`
+        docs en: https://www.coze.com/docs/developer_guides/get_metadata
+        docs zh: https://www.coze.cn/docs/developer_guides/get_metadata
+
+        :param bot_id: The ID of the bot that the API interacts with.
+        要查看的 Bot ID。
+        :return: bot object
+        Bot 的配置信息
         """
         url = f"{self._base_url}/v1/bot/get_online_info"
         params = {"bot_id": bot_id}
@@ -181,9 +206,20 @@ def retrieve(self, *, bot_id: str) -> Bot:
     def list(self, *, space_id: str, page_num: int = 1, page_size: int = 20) -> NumberPaged[SimpleBot]:
         """
         Get the bots published as API service.
-
-        :docs: https://www.coze.com/docs/developer_guides/published_bots_list
-        :calls: `GET /v1/space/published_bots_list`
+        查看指定空间发布到 Bot as API 渠道的 Bot 列表。
+
+        docs en: https://www.coze.com/docs/developer_guides/published_bots_list
+        docs zh: https://www.coze.cn/docs/developer_guides/published_bots_list
+
+        :param space_id: The ID of the space.
+        Bot 所在的空间的 Space ID。Space ID 是空间的唯一标识。
+        :param page_num: Pagination size. The default is 20, meaning that 20 data entries are returned per page.
+        分页大小。默认为 20，即每页返回 20 条数据。
+        :param page_size: Page number for paginated queries. The default is 1,
+        meaning that the data return starts from the first page.
+        分页查询时的页码。默认为 1，即从第一页数据开始返回。
+        :return: Specify the list of Bots published to the Bot as an API channel in space.
+        指定空间发布到 Bot as API 渠道的 Bot 列表。
         """
         url = f"{self._base_url}/v1/space/published_bots_list"
         params = {

cozepy/chat/__init__.py

@@ -285,15 +285,28 @@ def create(
         *,
         bot_id: str,
         user_id: str,
+        conversation_id: str = None,
         additional_messages: List[Message] = None,
         custom_variables: Dict[str, str] = None,
         auto_save_history: bool = True,
         meta_data: Dict[str, str] = None,
-        conversation_id: str = None,
     ) -> Chat:
         """
-        Create a conversation.
-        Conversation is an interaction between a bot and a user, including one or more messages.
+        Call the Chat API with non-streaming to send messages to a published Coze bot.
+
+        docs en: https://www.coze.com/docs/developer_guides/chat_v3
+        docs zh: https://www.coze.cn/docs/developer_guides/chat_v3
+
+        :param bot_id: The ID of the bot that the API interacts with.
+        :param user_id: The user who calls the API to chat with the bot.
+        This parameter is defined, generated, and maintained by the user within their business system.
+        :param conversation_id: Indicate which conversation the chat is taking place in.
+        :param additional_messages: Additional information for the conversation. You can pass the user's query for this
+        conversation through this field. The array length is limited to 100, meaning up to 100 messages can be input.
+        :param custom_variables: The customized variable in a key-value pair.
+        :param auto_save_history: Whether to automatically save the history of conversation records.
+        :param meta_data: Additional information, typically used to encapsulate some business-related fields.
+        :return: chat object
         """
         return self._create(
             bot_id=bot_id,
@@ -318,8 +331,21 @@ def stream(
         conversation_id: str = None,
     ) -> ChatChatIterator:
         """
-        Create a conversation.
-        Conversation is an interaction between a bot and a user, including one or more messages.
+        Call the Chat API with streaming to send messages to a published Coze bot.
+
+        docs en: https://www.coze.com/docs/developer_guides/chat_v3
+        docs zh: https://www.coze.cn/docs/developer_guides/chat_v3
+
+        :param bot_id: The ID of the bot that the API interacts with.
+        :param user_id: The user who calls the API to chat with the bot.
+        This parameter is defined, generated, and maintained by the user within their business system.
+        :param conversation_id: Indicate which conversation the chat is taking place in.
+        :param additional_messages: Additional information for the conversation. You can pass the user's query for this
+        conversation through this field. The array length is limited to 100, meaning up to 100 messages can be input.
+        :param custom_variables: The customized variable in a key-value pair.
+        :param auto_save_history: Whether to automatically save the history of conversation records.
+        :param meta_data: Additional information, typically used to encapsulate some business-related fields.
+        :return: iterator of ChatEvent
         """
         return self._create(
             bot_id=bot_id,
@@ -371,8 +397,14 @@ def retrieve(
         chat_id: str,
     ) -> Chat:
         """
-        Create a conversation.
-        Conversation is an interaction between a bot and a user, including one or more messages.
+        Get the detailed information of the chat.
+
+        docs en: https://www.coze.com/docs/developer_guides/retrieve_chat
+        docs zh: https://www.coze.cn/docs/developer_guides/retrieve_chat
+
+        :param conversation_id: The ID of the conversation.
+        :param chat_id: The ID of the chat.
+        :return: chat object
         """
         url = f"{self._base_url}/v3/chat/retrieve"
         params = {
@@ -389,6 +421,15 @@ def cancel(
     ) -> Chat:
         """
         Call this API to cancel an ongoing chat.
+
+        docs en: https://www.coze.com/docs/developer_guides/chat_cancel
+        docs zh: https://www.coze.cn/docs/developer_guides/chat_cancel
+
+        :param conversation_id: The Conversation ID can be viewed in the 'conversation_id' field of the Response when
+        initiating a conversation through the Chat API.
+        :param chat_id: The Chat ID can be viewed in the 'id' field of the Response when initiating a chat through the
+        Chat API. If it is a streaming response, check the 'id' field in the chat event of the Response.
+        :return:
         """
         url = f"{self._base_url}/v3/chat/cancel"
         params = {

cozepy/chat/message/__init__.py

@@ -18,8 +18,15 @@ def list(
         chat_id: str,
     ) -> List[Message]:
         """
-        Create a conversation.
-        Conversation is an interaction between a bot and a user, including one or more messages.
+        The information of messages in the specified conversation besides the Query, including model replies,
+        intermediate results of the Bot's execution, and other messages.
+
+        docs en: https://www.coze.com/docs/developer_guides/list_chat_messages
+        docs zh: https://www.coze.cn/docs/developer_guides/list_chat_messages
+
+        :param conversation_id: The ID of the conversation.
+        :param chat_id: The ID of the chat.
+        :return: list of Message object
         """
         url = f"{self._base_url}/v3/chat/message/list"
         params = {

cozepy/conversations/__init__.py

@@ -23,6 +23,14 @@ def create(self, *, messages: List[Message] = None, meta_data: Dict[str, str] =
         """
         Create a conversation.
         Conversation is an interaction between a bot and a user, including one or more messages.
+
+        docs en: https://www.coze.com/docs/developer_guides/create_conversation
+        docs zh: https://www.coze.cn/docs/developer_guides/create_conversation
+
+        :param messages: Messages in the conversation. For more information, see EnterMessage object.
+        :param meta_data: Additional information when creating a message, and this additional information will also be
+        returned when retrieving messages.
+        :return: Conversation object
         """
         url = f"{self._base_url}/v1/conversation/create"
         body = {
@@ -34,6 +42,12 @@ def create(self, *, messages: List[Message] = None, meta_data: Dict[str, str] =
     def retrieve(self, *, conversation_id: str) -> Conversation:
         """
         Get the information of specific conversation.
+
+        docs en: https://www.coze.com/docs/developer_guides/retrieve_conversation
+        docs cn: https://www.coze.cn/docs/developer_guides/retrieve_conversation
+
+        :param conversation_id: The ID of the conversation.
+        :return: Conversation object
         """
         url = f"{self._base_url}/v1/conversation/retrieve"
         params = {

cozepy/conversations/message/__init__.py

@@ -1,7 +1,7 @@
 from typing import Dict, List
 
-from cozepy.chat import MessageRole, MessageContentType, Message
 from cozepy.auth import Auth
+from cozepy.chat import MessageRole, MessageContentType, Message
 from cozepy.model import CozeModel, LastIDPaged
 from cozepy.request import Requester
 
@@ -25,6 +25,21 @@ def create(
         content_type: MessageContentType,
         meta_data: Dict[str, str] = None,
     ) -> Message:
+        """
+        Create a message and add it to the specified conversation.
+
+        docs en: https://www.coze.com/docs/developer_guides/create_message
+        docs cn: https://www.coze.cn/docs/developer_guides/create_message
+
+        :param conversation_id: The ID of the conversation.
+        :param role: The entity that sent this message.
+        :param content: The content of the message, supporting pure text, multimodal (mixed input of text, images,
+        files), cards, and various types of content.
+        :param content_type: The type of message content.
+        :param meta_data: Additional information when creating a message, and this additional information will also be
+        returned when retrieving messages.
+        :return:
+        """
         url = f"{self._base_url}/v1/conversation/message/create"
         params = {
             "conversation_id": conversation_id,
@@ -48,6 +63,20 @@ def list(
         after_id: str = None,
         limit: int = 50,
     ) -> LastIDPaged[Message]:
+        """
+        Get the message list of a specified conversation.
+
+        docs en: https://www.coze.com/docs/developer_guides/list_message
+        docs zh: https://www.coze.cn/docs/developer_guides/list_message
+
+        :param conversation_id: The ID of the conversation.
+        :param order: The sorting method for the message list.
+        :param chat_id: The ID of the Chat.
+        :param before_id: Get messages before the specified position.
+        :param after_id: Get messages after the specified position.
+        :param limit: The amount of data returned per query. Default is 50, with a range of 1 to 50.
+        :return: The message list of the specified conversation.
+        """
         url = f"{self._base_url}/v1/conversation/message/list"
         params = {
             "conversation_id": conversation_id,
@@ -69,6 +98,16 @@ def retrieve(
         conversation_id: str,
         message_id: str,
     ) -> Message:
+        """
+        Get the detailed information of specified message.
+
+        docs en: https://www.coze.com/docs/developer_guides/retrieve_message
+        docs zh: https://www.coze.cn/docs/developer_guides/retrieve_message
+
+        :param conversation_id: The ID of the conversation.
+        :param message_id: The ID of the message.
+        :return: The detailed information of specified message.
+        """
         url = f"{self._base_url}/v1/conversation/message/retrieve"
         params = {
             "conversation_id": conversation_id,
@@ -86,6 +125,20 @@ def update(
         content_type: MessageContentType = None,
         meta_data: Dict[str, str] = None,
     ) -> Message:
+        """
+        Modify a message, supporting the modification of message content, additional content, and message type.
+
+        docs en: https://www.coze.com/docs/developer_guides/modify_message
+        docs cn: https://www.coze.cn/docs/developer_guides/modify_message
+
+        :param conversation_id: The ID of the conversation.
+        :param message_id: The ID of the message.
+        :param content: The content of the message, supporting pure text, multimodal (mixed input of text, images,
+        files), cards, and various types of content.
+        :param content_type: The type of message content.
+        :param meta_data:
+        :return: The detailed information of specified message.
+        """
         url = f"{self._base_url}/v1/conversation/message/modify"
         params = {
             "conversation_id": conversation_id,
@@ -104,22 +157,24 @@ def delete(
         *,
         conversation_id: str,
         message_id: str,
-        content: str = None,
-        content_type: MessageContentType = None,
-        meta_data: Dict[str, str] = None,
     ) -> Message:
+        """
+        Call the API to delete a message within a specified conversation.
+
+        docs en: https://www.coze.com/docs/developer_guides/delete_message
+        docs zh: https://www.coze.cn/docs/developer_guides/delete_message
+
+        :param conversation_id:
+        :param message_id:
+        :return:
+        """
         url = f"{self._base_url}/v1/conversation/message/delete"
         params = {
             "conversation_id": conversation_id,
             "message_id": message_id,
         }
-        body = {
-            "content": content,
-            "content_type": content_type,
-            "meta_data": meta_data,
-        }
 
-        return self._requester.request("post", url, Message, params=params, body=body)
+        return self._requester.request("post", url, Message, params=params)
 
     class _PrivateListMessageResp(CozeModel):
         first_id: str

cozepy/files/__init__.py

@@ -4,20 +4,20 @@
 
 
 class File(CozeModel):
-    # The ID of the uploaded file.
     # 已上传的文件 ID。
+    # The ID of the uploaded file.
     id: str
 
-    # 文件的总字节数。
     # The total byte size of the file.
+    # 文件的总字节数。
     bytes: int
 
-    # 文件的上传时间，格式为 10 位的 Unixtime 时间戳，单位为秒（s）。
     # The upload time of the file, in the format of a 10-digit Unix timestamp in seconds (s).
+    # 文件的上传时间，格式为 10 位的 Unixtime 时间戳，单位为秒（s）。
     created_at: int
 
-    # 文件名称。
     # The name of the file.
+    # 文件名称。
     file_name: str
 
 
@@ -41,11 +41,8 @@ def upload(self, *, file: str) -> File:
         docs en: https://www.coze.com/docs/developer_guides/upload_files
         docs zh: https://www.coze.cn/docs/developer_guides/upload_files
 
-        Args:
-            file: local file path
-
-        Returns:
-            File: file info
+        :param file: local file path
+        :return: file info
         """
         url = f"{self._base_url}/v1/files/upload"
         files = {"file": open(file, "rb")}
@@ -60,11 +57,8 @@ def retrieve(self, *, file_id: str):
         docs en: https://www.coze.com/docs/developer_guides/retrieve_files
         docs cn: https://www.coze.cn/docs/developer_guides/retrieve_files
 
-        Args:
-            file_id: file id of file
-
-        Returns:
-            File: file info
+        :param file_id: file id
+        :return: file info
         """
         url = f"{self._base_url}/v1/files/retrieve"
         params = {"file_id": file_id}