docs: Added detailed README.md

README.md

@@ -1 +1,206 @@
-# coze-py
+# coze-py
+
+## Install
+
+```shell
+pip install cozepy
+```
+
+## Usage
+
+### Auth
+
+```python
+from cozepy import Coze
+from cozepy.auth import TokenAuth, JWTAuth
+
+# use pat or oauth token as auth
+cli = Coze(auth=TokenAuth("your_token"))
+
+# use application jwt auth flow as auth
+cli = Coze(auth=JWTAuth("your_client_id", "your_private_key", "your_key_id"))
+```
+
+### Bots
+
+```python
+from cozepy import Coze
+from cozepy.auth import TokenAuth
+
+cli = Coze(auth=TokenAuth("your_token"))
+
+# retrieve bot info
+bot = cli.bots.retrieve(bot_id='bot id')
+
+# list bot list
+bots_page = cli.bots.list(space_id='space id', page_num=1)
+bots = bots_page.items
+
+# create bot
+bot = cli.bots.create(
+    space_id='space id',
+    name='bot name',
+    description='bot description',
+)
+
+# update bot info
+cli.bots.update(
+    bot_id='bot id',
+    name='bot name',
+    description='bot description',
+)
+
+# delete bot
+bot = cli.bots.publish(bot_id='bot id')
+```
+
+### Chat
+
+```python
+import time
+
+from cozepy import Coze
+from cozepy.auth import TokenAuth
+from cozepy.chat import Event, ChatStatus
+from cozepy.chat.message import Message
+
+cli = Coze(auth=TokenAuth("your_token"))
+
+# no-stream chat
+chat = cli.chat.create(
+    bot_id='bot id',
+    user_id='user id',
+    additional_messages=[
+        Message.user_text_message('how are you?'),
+        Message.assistant_text_message('I am fine, thank you.')
+    ],
+)
+start = int(time.time())
+while chat.status == ChatStatus.in_progress:
+    if int(time.time()) > 120:
+        # too long, cancel chat
+        cli.chat.cancel(conversation_id=chat.conversation_id, chat_id=chat.chat_id)
+        break
+
+    time.sleep(1)
+    chat = cli.chat.retrieve(conversation_id=chat.conversation_id, chat_id=chat.chat_id)
+
+message_list = cli.chat.message.list(conversation_id=chat.conversation_id, chat_id=chat.chat_id)
+for message in message_list:
+    print('got message:', message.content)
+
+# stream chat
+chat_iterator = cli.chat.stream(
+    bot_id='bot id',
+    user_id='user id',
+    additional_messages=[
+        Message.user_text_message('how are you?'),
+        Message.assistant_text_message('I am fine, thank you.')
+    ],
+)
+for event in chat_iterator:
+    if event.event == Event.conversation_message_delta:
+        print('got message delta:', event.message.content)
+```
+
+### Conversations
+
+```python
+from cozepy import Coze
+from cozepy.auth import TokenAuth
+from cozepy.chat import MessageContentType
+from cozepy.chat.message import Message
+from cozepy.conversations.message import MessageContentType 
+
+cli = Coze(auth=TokenAuth("your_token"))
+
+# create conversation
+conversation = cli.conversations.create(
+    messages=[
+        Message.user_text_message('how are you?'),
+        Message.assistant_text_message('I am fine, thank you.')
+    ],
+)
+
+# retrieve conversation
+conversation = cli.conversations.retrieve(conversation_id=conversation.id)
+
+# create message
+message = cli.conversations.message.create(
+    conversation_id=conversation.id,
+    content='how are you?',
+    content_type=MessageContentType.text,
+)
+
+# retrieve message
+message = cli.conversations.message.retrieve(conversation_id=conversation.id, message_id=message.id)
+
+# update message
+cli.conversations.message.update(
+    conversation_id=conversation.id,
+    message_id=message.id,
+    content='hey, how are you?',
+    content_type=MessageContentType.text,
+)
+
+# delete message
+cli.conversations.message.delete(conversation_id=conversation.id, message_id=message.id)
+
+# list messages
+message_list = cli.conversations.message.list(conversation_id=conversation.id)
+```
+
+### Files
+
+```python
+from cozepy import Coze
+from cozepy.auth import TokenAuth
+
+cli = Coze(auth=TokenAuth("your_token"))
+
+# upload file
+file = cli.files.upload('/filepath')
+
+# retrieve file info
+cli.files.retrieve(file_id=file.id)
+```
+
+### Workflows
+
+```python
+from cozepy import Coze
+from cozepy.auth import TokenAuth
+from cozepy.workflows.runs import Event,WorkflowEventIterator
+
+cli = Coze(auth=TokenAuth("your_token"))
+
+# no-stream workflow run
+result = cli.workflows.runs.create(
+    workflow_id='workflow id',
+    parameters={
+        'input_key': 'input value',
+    }
+)
+
+# stream workflow run
+def handle_workflow_iterator(iterator: WorkflowEventIterator):
+    for event in iterator:
+        if event.event == Event.message:
+            print('got message', event.message)
+        elif event.event == Event.error:
+            print('got error', event.error)
+        elif event.event == Event.interrupt:
+            handle_workflow_iterator(cli.workflows.runs.resume(
+                workflow_id='workflow id',
+                event_id=event.interrupt.interrupt_data.event_id,
+                resume_data='hey',
+                interrupt_type=event.interrupt.interrupt_data.type,
+            ))
+
+handle_workflow_iterator(cli.workflows.runs.stream(
+    workflow_id='workflow id',
+    parameters={
+        'input_key': 'input value',
+    }
+))
+```

cozepy/bots/__init__.py

@@ -136,7 +136,7 @@ def update(
         icon_file_id: str = None,
         prompt_info: BotPromptInfo = None,
         onboarding_info: BotOnboardingInfo = None,
-    ) -> Bot:
+    ) -> None:
         url = f"{self._base_url}/v1/bot/update"
         body = {
             "bot_id": bot_id,

cozepy/chat/__init__.py

@@ -281,6 +281,58 @@ def __init__(self, base_url: str, auth: Auth, requester: Requester):
         self._message = None
 
     def create(
+        self,
+        *,
+        bot_id: str,
+        user_id: str,
+        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.
+        """
+        return self._create(
+            bot_id=bot_id,
+            user_id=user_id,
+            additional_messages=additional_messages,
+            stream=False,
+            custom_variables=custom_variables,
+            auto_save_history=auto_save_history,
+            meta_data=meta_data,
+            conversation_id=conversation_id,
+        )
+
+    def stream(
+        self,
+        *,
+        bot_id: str,
+        user_id: str,
+        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,
+    ) -> ChatIterator:
+        """
+        Create a conversation.
+        Conversation is an interaction between a bot and a user, including one or more messages.
+        """
+        return self._create(
+            bot_id=bot_id,
+            user_id=user_id,
+            additional_messages=additional_messages,
+            stream=True,
+            custom_variables=custom_variables,
+            auto_save_history=auto_save_history,
+            meta_data=meta_data,
+            conversation_id=conversation_id,
+        )
+
+    def _create(
         self,
         *,
         bot_id: str,
@@ -329,16 +381,6 @@ def retrieve(
         }
         return self._requester.request("post", url, Chat, params=params)
 
-    @property
-    def message(
-        self,
-    ) -> "ChatMessageClient":
-        if self._message is None:
-            from .message import MessageClient
-
-            self._message = MessageClient(self._base_url, self._auth, self._requester)
-        return self._message
-
     def cancel(
         self,
         *,
@@ -354,3 +396,13 @@ def cancel(
             "chat_id": chat_id,
         }
         return self._requester.request("post", url, Chat, params=params)
+
+    @property
+    def message(
+        self,
+    ) -> "ChatMessageClient":
+        if self._message is None:
+            from .message import MessageClient
+
+            self._message = MessageClient(self._base_url, self._auth, self._requester)
+        return self._message

cozepy/conversations/message/__init__.py

@@ -1,6 +1,6 @@
 from typing import Dict, List
 
-from cozepy.chat.v3 import MessageRole, MessageContentType, Message
+from cozepy.chat import MessageRole, MessageContentType, Message
 from cozepy.auth import Auth
 from cozepy.model import CozeModel, LastIDPaged
 from cozepy.request import Requester

cozepy/coze.py

@@ -25,11 +25,11 @@ def __init__(
 
         # service client
         self._bots = None
-        self._workspace = None
-        self._conversation = None
+        self._workspaces = None
+        self._conversations = None
         self._chat = None
-        self._file = None
-        self._workflow = None
+        self._files = None
+        self._workflows = None
 
     @property
     def bots(self) -> "BotsClient":
@@ -41,19 +41,19 @@ def bots(self) -> "BotsClient":
 
     @property
     def workspace(self) -> "WorkspacesClient":
-        if not self._workspace:
+        if not self._workspaces:
             from .workspaces import WorkspacesClient
 
-            self._workspace = WorkspacesClient(self._base_url, self._auth, self._requester)
-        return self._workspace
+            self._workspaces = WorkspacesClient(self._base_url, self._auth, self._requester)
+        return self._workspaces
 
     @property
     def conversation(self) -> "ConversationsClient":
-        if not self._conversation:
+        if not self._conversations:
             from .conversations import ConversationsClient
 
-            self._conversation = ConversationsClient(self._base_url, self._auth, self._requester)
-        return self._conversation
+            self._conversations = ConversationsClient(self._base_url, self._auth, self._requester)
+        return self._conversations
 
     @property
     def chat(self) -> "ChatClient":
@@ -65,16 +65,16 @@ def chat(self) -> "ChatClient":
 
     @property
     def file(self) -> "FilesClient":
-        if not self._file:
+        if not self._files:
             from .files import FilesClient
 
-            self._file = FilesClient(self._base_url, self._auth, self._requester)
-        return self._file
+            self._files = FilesClient(self._base_url, self._auth, self._requester)
+        return self._files
 
     @property
-    def workflow(self) -> "WorkflowsClient":
-        if not self._workflow:
-            from .workflow import WorkflowsClient
+    def workflows(self) -> "WorkflowsClient":
+        if not self._workflows:
+            from .workflows import WorkflowsClient
 
-            self._workflow = WorkflowsClient(self._base_url, self._auth, self._requester)
-        return self._workflow
+            self._workflows = WorkflowsClient(self._base_url, self._auth, self._requester)
+        return self._workflows