From 1c27281bb759e1e7eb5727279d9daf76a2e953df Mon Sep 17 00:00:00 2001 From: choir27 Date: Sat, 17 Aug 2024 12:14:29 -0400 Subject: [PATCH] add note info to include Pieces OS for SDk. Update location to href redirec to Pieces OS docs. Change Usage to Initialize SDK. Update instructions to initialize Pieces OS. Update Features to table and content. Add parameters, return type, and example sections for the following: ask_question(), create_conversation(), prompt_conversation(), get_conversation(), update_conversation_name(), get_conversations(), get_user_profile_picture(), and Full Example using all Python SDK methods --- docs/build/copilot/python/index.mdx | 310 ++++++++++++++++++++++++++-- 1 file changed, 295 insertions(+), 15 deletions(-) diff --git a/docs/build/copilot/python/index.mdx b/docs/build/copilot/python/index.mdx index d8d0e5c96..69e447573 100644 --- a/docs/build/copilot/python/index.mdx +++ b/docs/build/copilot/python/index.mdx @@ -11,14 +11,18 @@ Follow these steps to use the Pieces Python SDK. ## Download Pieces OS -Download the appropriate version for your operating system: +:::info + +You must either have Pieces OS installed on your local machine or have access to a remote instance of Pieces OS to use this SDK. + +::: + +Download [**Pieces OS**](/installation-getting-started/pieces-os) for your operating system: - [**macOS**](/installation-getting-started/macos) - [**Windows**](/installation-getting-started/windows) - [**Linux**](/installation-getting-started/linux) -[**Pieces OS**](/installation-getting-started/pieces-os) is the primary backend service, providing essential SDK functionality. - ## Install Python SDK Use pip to install the Pieces Python SDK using the following command: @@ -27,27 +31,303 @@ Use pip to install the Pieces Python SDK using the following command: pip install pieces_os_client ``` -## Usage +## Initialize SDK -After installing the SDK, you can import the library into your project and start utilizing its features: +After installing the SDK, you must initialize the SDK with your base URL. The base URL will depend on your setup. -```sh -import pieces_os_client as pos_client +If you are using a local instance of Pieces OS: +- On macOS/Windows, use http://localhost:1000 +- On Linux, use http://localhost:5323 + +If you are using a remote instance of Pieces OS, use the URL you have set up for that. + +```python +from pieces_copilot_sdk import PiecesClient + +# Replace 'your_base_url' with your actual base URL +pieces_client = PiecesClient(config={'baseUrl': 'your_base_url'}) ``` ## Features -1. Copilot Chats - - Communicate seamlessly with the functionalities of the copilot chats. +Feature | Description +------------- | ------------- +Simplified Interaction | The Pieces Copilot SDK simplifies the interaction with the Pieces OS Client SDK by providing easy-to-use methods for various operations. +Manage Conversations | The SDK provides various methods to manage conversations such as fetching a specific conversation, updating conversation name, and more. +Get User Profile Picture | Retrieve the user's profile picture using the `get_user_profile_picture()` method. + +## ask_question() + +```python +ask_question() +``` + +Allows users to ask a question and receive a response. + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- + **question** | **string**| This is the question representing the query that will be used to generate the answer outputted by the Pieces OS Copilot. | [required] + +### Return type + +string (response body) + +### Example + +```python +from pieces_copilot_sdk import PiecesClient + +pieces_client = PiecesClient(config={'baseUrl': 'your_base_url'}) + +response = pieces_client.ask_question('What is Pieces for Developers?') + +print(response) +``` + +## create_conversation() + +```python +create_conversation(name=None, first_message=None) +``` + +Creates a new conversation. + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- +**name** | **string** | This is the name of the new conversation | [optional] +**first message** | **string** | This is the first message that will be used to generate an answer to the message |[optional] + +### Return type + +A dictionary containing many key-value pairs, including the conversation name and the answer to the first message if either are provided. + +### Example + +```python +from pieces_copilot_sdk import PiecesClient + +pieces_client = PiecesClient(config={'baseUrl': 'your_base_url'}) + +new_conversation = pieces_client.create_conversation( + props={ + 'name': 'Test Conversation', + 'firstMessage': 'Hello, how can I use the API?' + } +) + +print(new_conversation) +``` + +## prompt_conversation() + +This method prompts a conversation with a message. + +```python +prompt_conversation(question, conversation_id, regenerate_conversation_name=False) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- +**question** | **string** | This is the question that will be used to generate an answer in the message | [required] +**conversation_id** | **string** | ID of a conversation that was created | [required] +**regenerate_conversation_name** | **boolean** | Regenerate the conversation name of the provided conversation id. Default is set to `False`. | [required] + +### Return type + +A dictionary containing the text of the answer, the ID of the user query message, and the ID of the bot response message. + +If there are previous messages in the conversation, they will be used as context for the new message. If there is an error, it will return a dictionary containing only the text of the error message + +### Example + +```python +from pieces_copilot_sdk import PiecesClient + +pieces_client = PiecesClient(config={'baseUrl': 'your_base_url'}) + +answer = pieces_client.prompt_conversation( + message='Hello, world!', + conversation_id='conversationId', + regenerate_conversation_name=False, +) + +print(answer) +``` + +## get_conversation() + +This method retrieves a conversation by its ID. + +```python +get_conversation(conversation_id, include_raw_messages=False) +``` + +### Parameters + -2. Asset Management - - Save and manage assets and formats them efficiently. +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- +**conversation_id** | **string** | ID of a conversation that was created | [required] +**include_raw_messages** | **boolean** | Includes the raw messages | [optional] -3. Local Server Interaction - - Interact with a locally hosted server for various functionalities. +### Return type -4. Multi LLMs support - - Use any Pieces supported LLMs to power apps. +A dictionary representing the `Conversation` object or `None`. + +### Example + +```pieces +from pieces_copilot_sdk import PiecesClient + +pieces_client = PiecesClient(config={'baseUrl': 'your_base_url'}) + +conversation = pieces_client.get_conversation( + conversation_id='conversationId', + include_raw_messages=False +) + +print(conversation) +``` + +## update_conversation_name() + +This method generates a new name for a specific conversation based on the messages that have been sent. + +```python +update_conversation_name(conversation_id) +``` + +### Parameters + +Name | Type | Description | Notes +------------- | ------------- | ------------- | ------------- +**conversation_id** | **string** | ID of a conversation that was created | [required] + +### Return type + +It returns a string representing the updated conversation name or `None`. + +### Example + +```python +from pieces_copilot_sdk import PiecesClient + +pieces_client = PiecesClient(config={'baseUrl': 'your_base_url'}) + +updated_name = pieces_client.update_conversation_name( + conversation_id='conversationId') + +print(updated_name) +``` + +## get_conversations() + +```python +get_conversations() +``` + +This method retrieves all conversations. + +### Return type + +It returns a list of `Conversation` objects or `None`. + +### Example + +```python +from pieces_copilot_sdk import PiecesClient + +pieces_client = PiecesClient(config={'baseUrl': 'your_base_url'}) + +conversations = pieces_client.get_conversations() + +print(conversations) +``` + +## get_user_profile_picture() + +```python +get_user_profile_picture() +``` + +### Return type + +It returns a string representing the URL of the profile picture or `None`. + +### Example + +```python +from pieces_copilot_sdk import PiecesClient + +pieces_client = PiecesClient(config={'baseUrl': 'your_base_url'}) + +profile_picture_url = pieces_client.get_user_profile_picture() + +print(profile_picture_url) +``` + +## Full Example + +```python +from pieces_copilot_sdk import PiecesClient + +# Create an instance of PiecesClient +pieces_client = PiecesClient( + config={ + 'baseUrl': 'your_base_url' + } +) + +# 1. Create a new conversation +conversation_response = pieces_client.create_conversation( + props={ + "name": "Test Conversation", + "firstMessage": "Hello, how can I use the API?" + } +) + +# Check if the conversation was created successfully +if conversation_response: + print("Conversation Created:", conversation_response['conversation'].id) + print("First Message Response:", conversation_response['answer']['text']) + + # 2. Get the created conversation details + conversation_id = conversation_response['conversation'].id + conversation_details = pieces_client.get_conversation( + conversation_id=conversation_id, + include_raw_messages=True + ) + + # Access the conversation name using the key + print("Conversation Name:", conversation_details.get('name')) + + # 3. Ask a question within the created conversation + question_response = pieces_client.prompt_conversation( + message="Can you give me an example code snippet?", + conversation_id=conversation_id + ) + print("Question Response:", question_response['text']) + +# 4. Retrieve all conversations and print their names +all_conversations = pieces_client.get_conversations() +for conversation in all_conversations: + print("Conversation Name:", conversation.name) + +# 5. Get user profile picture +profile_picture = pieces_client.get_user_profile_picture() +print("User Profile Picture URL:", profile_picture) + +# 6. Ask a question +question = "What is Pieces for Developer?" +response = pieces_client.ask_question(question) +print("Question Response:", response) +``` ## Community If you have created your own SDK or any other technology specific integration and would like us to list it here under community maintained SDKs/integrations please [contact us](https://github.com/pieces-app/opensource/discussions).