From 8044c580bc2d5c30a3d6f8def2efc6ea4f98845e Mon Sep 17 00:00:00 2001 From: chyroc Date: Thu, 26 Sep 2024 18:37:01 +0800 Subject: [PATCH] docs: update api docstring --- cozepy/bots/__init__.py | 46 +++++++++++++-- cozepy/chat/__init__.py | 55 ++++++++++++++--- cozepy/chat/message/__init__.py | 11 +++- cozepy/conversations/__init__.py | 14 +++++ cozepy/conversations/message/__init__.py | 75 ++++++++++++++++++++---- cozepy/files/__init__.py | 22 +++---- cozepy/workflows/runs/__init__.py | 27 +-------- 7 files changed, 188 insertions(+), 62 deletions(-) diff --git a/cozepy/bots/__init__.py b/cozepy/bots/__init__.py index 4e9f7e6..725e0ef 100644 --- a/cozepy/bots/__init__.py +++ b/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 = { diff --git a/cozepy/chat/__init__.py b/cozepy/chat/__init__.py index 1df4567..cdb3cd6 100644 --- a/cozepy/chat/__init__.py +++ b/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 = { diff --git a/cozepy/chat/message/__init__.py b/cozepy/chat/message/__init__.py index 8af73a4..4db2397 100644 --- a/cozepy/chat/message/__init__.py +++ b/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 = { diff --git a/cozepy/conversations/__init__.py b/cozepy/conversations/__init__.py index 9e5c236..5332c34 100644 --- a/cozepy/conversations/__init__.py +++ b/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 = { diff --git a/cozepy/conversations/message/__init__.py b/cozepy/conversations/message/__init__.py index 7b4b1e4..76c7ce3 100644 --- a/cozepy/conversations/message/__init__.py +++ b/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 diff --git a/cozepy/files/__init__.py b/cozepy/files/__init__.py index 5d357ef..ca25569 100644 --- a/cozepy/files/__init__.py +++ b/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} diff --git a/cozepy/workflows/runs/__init__.py b/cozepy/workflows/runs/__init__.py index f30fdd0..9a51416 100644 --- a/cozepy/workflows/runs/__init__.py +++ b/cozepy/workflows/runs/__init__.py @@ -162,25 +162,16 @@ def create( This API is in non-streaming response mode. For nodes that support streaming output, you should run the API Run workflow (streaming response) to obtain streaming responses. - - 执行已发布的工作流。 - 此接口为非流式响应模式，对于支持流式输出的节点，应使用接口执行工作流（流式响应）获取流式响应。 - docs en: https://www.coze.com/docs/developer_guides/workflow_run docs cn: https://www.coze.cn/docs/developer_guides/workflow_run :param workflow_id: The ID of the workflow, which should have been published. - 待执行的 Workflow ID，此工作流应已发布。 :param parameters: Input parameters and their values for the starting node of the workflow. You can view the list of parameters on the arrangement page of the specified workflow. - 工作流开始节点的输入参数及取值，你可以在指定工作流的编排页面查看参数列表。 :param bot_id: The associated Bot ID required for some workflow executions, such as workflows with database nodes, variable nodes, etc. - 需要关联的 Bot ID。 部分工作流执行时需要指定关联的 Bot，例如存在数据库节点、变量节点等节点的工作流。 :param ext: Used to specify some additional fields in the format of Map[String][String]. - 用于指定一些额外的字段，以 Map[String][String] 格式传入。 :return: The result of the workflow execution - 工作流执行结果 """ url = f"{self._base_url}/v1/workflow/run" body = {"workflow_id": workflow_id, "parameters": parameters, "bot_id": bot_id, "ext": ext} @@ -196,25 +187,17 @@ def stream( ) -> WorkflowEventIterator: """ Execute the published workflow with a streaming response method. - 执行已发布的工作流，响应方式为流式响应。 docs en: https://www.coze.com/docs/developer_guides/workflow_stream_run docs zh: https://www.coze.cn/docs/developer_guides/workflow_stream_run :param workflow_id: The ID of the workflow, which should have been published. - 待执行的 Workflow ID，此工作流应已发布。 :param parameters: Input parameters and their values for the starting node of the workflow. You can view the list of parameters on the arrangement page of the specified workflow. - 工作流开始节点的输入参数及取值，你可以在指定工作流的编排页面查看参数列表。 :param bot_id: The associated Bot ID required for some workflow executions, such as workflows with database nodes, variable nodes, etc. - 需要关联的 Bot ID。 部分工作流执行时需要指定关联的 Bot，例如存在数据库节点、变量节点等节点的工作流。 :param ext: Used to specify some additional fields in the format of Map[String][String]. - 用于指定一些额外的字段，以 Map[String][String] 格式传入。 :return: The result of the workflow execution - 工作流执行结果 - - """ url = f"{self._base_url}/v1/workflow/stream_run" body = {"workflow_id": workflow_id, "parameters": parameters, "bot_id": bot_id, "ext": ext} @@ -229,17 +212,13 @@ def resume( interrupt_type: int, ) -> WorkflowEventIterator: """ - 恢复运行已中断的工作流。 - docs zh: https://www.coze.cn/docs/developer_guides/workflow_resume :param workflow_id: The ID of the workflow, which should have been published. - 待执行的 Workflow ID，此工作流应已发布。 - :param event_id: 工作流执行中断事件 ID。 - :param resume_data:恢复执行时，用户对 Bot 指定问题的回复。回复中应包含问答节点中的必选参数，否则工作流会再次中断并提问。 - :param interrupt_type: 中断类型，你可以从执行工作流（流式响应）的响应信息中获得中断时间的中断类型。 + :param event_id: + :param resume_data: + :param interrupt_type: :return: The result of the workflow execution - 工作流执行结果 """ url = f"{self._base_url}/v1/workflow/stream_resume" body = {