diff --git a/docs/build/examples/index.mdx b/docs/build/examples/index.mdx index bdf938ae4..8c434c44c 100644 --- a/docs/build/examples/index.mdx +++ b/docs/build/examples/index.mdx @@ -8,6 +8,18 @@ import CTAButton from "/src/components/CTAButton"; import {GithubIcon} from "/src/components/Icons"; import {MiniSpacer} from "/src/components/Spacers"; +Explore projects that use the Pieces SDK in various frameworks. + +:::info + +These projects are community-contributed and may not be maintained by the Pieces team. + +These projects may not using our latest [SDKs](/build/sdks/python). We recommend using the built-in wrapper SDKs for an improved developer experience. + +::: + +## Examples +
Python SDK for Pieces OS

-
-
-
- {'Dart - Dart SDK -
- -

Dart SDK for Pieces OS

- -
-
-
- {'Kotlin - Kotlin SDK -
- -

Kotlin SDK for Pieces OS

-
+ diff --git a/docs/build/sdks/python/assets.mdx b/docs/build/sdks/python/assets.mdx new file mode 100644 index 000000000..d0a7c3460 --- /dev/null +++ b/docs/build/sdks/python/assets.mdx @@ -0,0 +1,303 @@ +--- +title: Pieces OS Client Python SDK Assets +description: Learn how to set up and use the Pieces OS Client Python SDK to manage assets. +--- + +Use the following methods to manage your assets with the Pieces OS Client Python SDK. + +## Asset Management + +### Create a New Asset + +The `create_asset()` method requires the content of the asset and optional metadata. The method returns the ID of the created asset. + +```python +create_asset(content, metadata) +``` + +#### Parameters + +| Name | Type | Notes | +|------------- |------------ |-------------| +| **content** | **string** | [required] | +| **metadata** | **FragmentMetadata** | [optional] | + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient +from pieces_os_client import ClassificationSpecificEnum, FragmentMetadata + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Set the content and metadata for the new asset +content = "print('Hello, World!')" +metadata = FragmentMetadata(ext=ClassificationSpecificEnum.PY) # optional metadata + +# Create the new asset using the content and metadata +new_asset_id = pieces_client.create_asset(content, metadata) + +print(f"Created asset with ID: {new_asset_id}") + +# Close the client +pieces_client.close() +``` + +### Get a Specific Asset + +The `asset()` method requires the asset ID and returns the asset as a [BasicAsset](#basicasset-class) object. + +```python +asset(asset_id) +``` + +#### Parameters + +| Name | Type | Notes | +|------------- |------------ |-------------| +| **asset_id** | **string** | [required] | + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Get the asset ID +asset_id = "your_asset_id" + +# Retrieve the asset +asset = pieces_client.asset(asset_id) + +# Close the client +pieces_client.close() +``` + +### Get All Assets + +The `assets()` method returns a list of all assets with `id` and `name` properties. + +```python +assets() +``` + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Get all assets and print their names +assets = pieces_client.assets() +for asset in assets: + print(f"Asset Name: {asset.name}") + +# Close the client +pieces_client.close() +``` + +## BasicAsset Class + +The `BasicAsset` class provides a way to manage assets with various properties and methods. + +### Properties + +| Name | Type | Notes | +|--------------- |------------ |----------------------| +| **id** | **string** | The ID of the asset. | +| **asset** | [**Asset**](/build/reference/python/models/Asset) | Should **only** be used for properties not available in the `BasicAsset` class. | +| **raw_content** | **string** | The content of the asset. | +| **is_image** | **bool** | Boolean indicating if the asset is an image. | +| **classification** | [**ClassificationSpecificEnum**](/build/reference/python/models/ClassificationSpecificEnum) | The specific language classification of the asset. To get the string value, you must use `asset.classification.value` | +| **name** | **string** | The name of the asset. | +| **description** | **string** | The description of the asset. | +| **annotations** | [**Annotations**](/build/reference/python/models/Annotations) | The annotations of the asset. | + +### Methods + +#### `create()` + +Creates a new asset. + +##### Parameters + +| Name | Type | Notes | +|------------ |------------|------------------| +| **raw_content** | **string** | The raw content of the asset. | +| **metadata** | **Optional[FragmentMetadata]** | The metadata of the asset. | + +##### Returns + +| Type | Notes | +|------------- |-------------------| +| **string** | The ID of the created asset. | + +##### Example + +```python +from pieces_os_client.wrapper import PiecesClient +from pieces_os_client.wrapper.basic_identifier.asset import BasicAsset +from pieces_os_client import ClassificationSpecificEnum, FragmentMetadata + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Create a new asset +content = "print('Hello, World!')" +metadata = FragmentMetadata(ext=ClassificationSpecificEnum.PY) +new_asset_id = BasicAsset.create(content, metadata) +print(f"New Asset ID: {new_asset_id}") + +# Close the client +pieces_client.close() +``` + +#### `delete()` + +Deletes the asset. + +##### Example + +```python +# Retrieve the asset +asset = pieces_client.asset(asset_id) + +# Delete the asset +asset.delete() + +# Close the client +pieces_client.close() +``` + +#### `raw_content` + +Updates the raw content of the asset. + +##### Example + +```python +# Retrieve the asset +asset = pieces_client.asset(new_asset_id) + +# Get the asset content +content = asset.raw_content +print(f"Original Content: {content}") + +# Update the content +asset.raw_content = content + "\n# This is a comment" +print(f"Updated Content: {asset.raw_content}") + +# Close the client +pieces_client.close() +``` + +#### `classification` + +Updates the classification of the asset. + +##### Example + +```python +# Retrieve the asset +asset = pieces_client.asset(new_asset_id) + +# Get the asset classification +classification = asset.classification.value if asset.classification else "None" +print(f"Asset Classification: {classification}") + +# Update the classification +asset.classification = ClassificationSpecificEnum.SH # Reclassify to shell +print(f"New Classification: {classification}") + +# Close the client +pieces_client.close() +``` + +#### `name` + +Updates the name of the asset. + +##### Example + +```python +# Retrieve the asset +asset = pieces_client.asset(new_asset_id) + +# Get the asset name +print(f"Current Asset Name: {asset.name}") + +# Update the name +asset.name = "Updated Asset Name" +print(f"Updated Asset Name: {asset.name}") + +# Close the client +pieces_client.close() +``` + +### Full Example + +```python +from pieces_os_client.wrapper import PiecesClient +from pieces_os_client.basic_asset import BasicAsset +from pieces_os_client import ClassificationSpecificEnum + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +asset = pieces_client.assets()[0] + +# Get the asset ID +asset_id = asset.id +print(f"Asset ID: {asset_id}") + +# Get the full asset object (only for properties not available in BasicAsset) +full_asset = asset.asset +print(f"Full Asset Object: {full_asset}") + +# Check if the asset is an image +if asset.is_image: + print("The asset is an image.") +else: + print("The asset is not an image.") + +# Get and set the asset name +print(f"Current Asset Name: {asset.name}") +asset.name = "Updated Asset Name" +print(f"Updated Asset Name: {asset.name}") + +# Retrieve and modify the asset content +content = asset.raw_content +print(f"Original Content: {content}") +asset.raw_content = content + "\n# This is a comment" +print(f"Updated Content: {asset.raw_content}") + +# Get the asset classification +classification = asset.classification.value if asset.classification else "None" +print(f"Asset Classification: {classification}") + +asset.classification = ClassificationSpecificEnum.SH # Reclassify to shell +print(f"New Classification: {classification}") + +# Get the asset description +description = asset.description if asset.description else "No description available." +print(f"Asset Description: {description}") + +# Get the asset annotations +annotations = asset.annotations if asset.annotations else "No annotations available." +print(f"Asset Annotations: {annotations}") + +# Delete the asset +asset.delete() +print("Asset deleted.") + +# Create a new asset +new_asset_id = BasicAsset.create("New Asset content") +print(f"New Asset ID: {new_asset_id}") + +pieces_client.close() +``` \ No newline at end of file diff --git a/docs/build/sdks/python/copilot.mdx b/docs/build/sdks/python/copilot.mdx new file mode 100644 index 000000000..d12ce8ebe --- /dev/null +++ b/docs/build/sdks/python/copilot.mdx @@ -0,0 +1,257 @@ +--- +title: Pieces OS Client Python SDK Copilot +description: Learn how to set up and use the Pieces OS Client Python SDK to communicate Pieces Copilot. +--- + +Use the following methods to communicate with Pieces Copilot using the Pieces OS Client Python SDK. + +## Copilot Management + +### Ask a Question to Pieces Copilot + +The `stream_question()` requires a question as a parameter and will stream the response. + +#### Parameters + +| Name | Type | Notes | +|------------- |------------ |-------------| +| **question** | **string** | [required] | + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Set the question you want to ask +question = "What is Object-Oriented Programming?" + +# Ask the question and stream the response +for response in pieces_client.copilot.stream_question(question): + if response.question: + # Each answer is a chunk of the entire response to the question + answers = response.question.answers.iterable + for answer in answers: + print(answer.text,end="") + +# Close the client +pieces_client.close() +``` + +If you do not want to stream the response, you can use the `quesiton()` method instead. + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Set the question you want to ask +question = "What is Object-Oriented Programming?" + +# Ask the question and get the response +response = pieces_client.copilot.question(question) + +# Print the response message +message = response.answers.iterable[0].text +print(message) + +# Close the client +pieces_client.close() +``` + +### Get All Chats + +The `chats()` method returns a list of all chats. + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Get all chats and print their names +chats = pieces_client.copilot.chats() +for chat in chats: + print(chat.name) + +# Close the client +pieces_client.close() +``` + +{/* need section on selecting an llm */} + +## LLM Management + +### Set the Current LLM + +The `model_name` setter method allows you to set the current LLM. + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Set the current LLM +pieces_client.model_name = "your_model_name" + +# Close the client +pieces_client.close() +``` + +### Get Availiable LLMs + +The `get_models()` method returns a list of available LLMs as a dictionary. + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient +from pieces_os_client import ClassificationSpecificEnum, FragmentMetadata + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Get all models and print their names +models = pieces_client.get_models() +for model_name, model_id in models.items(): + print(model_name) + +# Close the client +pieces_client.close() +``` + +### Copilot Class + +The `Copilot` class provides a way to manage copilot functionality with various properties and methods. + +#### Properties + +| Name | Notes | +|--------------- |----------------------| +| **chat** | The chat object. | + +#### Methods + +##### Set the Current Chat + +The `chat` setter method allows you to set the current chat. + +:::info + +Changing the current chat will clear all context added to the chat. + +::: + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient +from pieces_os_client.wrapper.basic_identifier.chat import BasicChat + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Get the chat ID +chat_id = "your_chat_id" + +# Set the current chat +pieces_client.copilot.chat = BasicChat(chat_id) + +# Close the client +pieces_client.close() +``` + +## Chat Management + +### BasicChat Class + +The `BasicChat` class provides a way to manage chat with various properties and methods. + +#### Properties + +| Name | Notes | +|--------------- |----------------------| +| **id** | The ID of the chat. | +| **conversation** | The [Conversation](/build/reference/python/models/Conversation) object. Should **only** be used for properties not available in the `BasicChat` class. | +| **name** | The name of the chat. | +| **annotations** | The annotations of the chat. | + +#### Methods + +##### Get Chat Messages + +The `messages()` method returns a list of all messages in the chat. + +#### Example + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Get the chat ID +chat_id = "your_chat_id" + +# Get all messages in the chat +messages = pieces_client.copilot.chat(chat_id).messages() +for message in messages: + print(message.text) + +# Close the client +pieces_client.close() +``` + +##### Set the Chat Name + +The `name` setter method allows you to set the chat name. + +###### Example + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Get the chat ID +chat_id = "your_chat_id" + +# Set the chat name +pieces_client.copilot.chat(chat_id).name = "New Chat Name" + +# Close the client +pieces_client.close() +``` + +##### Delete a Chat + +The `delete()` method of allows you to delete a chat. + +###### Example + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Get the chat ID +chat_id = "your_chat_id" + +# Delete the chat +pieces_client.copilot.chat(chat_id).delete() + +# Close the client +pieces_client.close() +``` \ No newline at end of file diff --git a/docs/build/sdks/python/index.mdx b/docs/build/sdks/python/index.mdx new file mode 100644 index 000000000..6a43a184e --- /dev/null +++ b/docs/build/sdks/python/index.mdx @@ -0,0 +1,37 @@ +--- +title: Pieces OS Client Python SDK +description: The Pieces OS Client SDK is a powerful code engine package designed for writing applications on top of Pieces OS. +--- + +import Grid from "/src/components/Grid"; +import {CardWithoutCTA} from "/src/components/Card"; +import CTAButton from "/src/components/CTAButton"; + +The Pieces OS Client Python SDK is a powerful code engine package designed for writing applications on top of Pieces OS. + + + +## Features + + +
+

🤖 Copilot Chats

+

Communicate seamlessly with our copilot functionality.

+
+
+

📁 Asset Management

+

Save and manage assets and formats efficiently.

+
+
+

🖥 Local Server Interaction

+

Interact with a locally hosted server for various functionalities.

+
+
+

🧠 Cloud & Local LLM Support

+

Tap into your favorite cloud or local LLM with ease.

+
+ + +## Want to Contribute? + +Don't see a feature you need? We welcome contributions to the Pieces OS Client Python SDK. Check out the [GitHub repository](https://github.com/pieces-app/pieces-os-client-sdk-for-python) to get started. \ No newline at end of file diff --git a/docs/build/sdks/python/quickstart.mdx b/docs/build/sdks/python/quickstart.mdx new file mode 100644 index 000000000..40e3160ce --- /dev/null +++ b/docs/build/sdks/python/quickstart.mdx @@ -0,0 +1,130 @@ +--- +title: Pieces Wrapper Python SDK Quickstart +description: Quickly set up the Pieces Wrapper Python SDK +--- + +# Quickstart with Pieces OS Client Python SDK + +The Pieces OS Client SDK has a built-in wrapper that simplifies the process of interacting with the Pieces OS server. Here's how you can get started with the wrapper. + +## Installation + +To get started with the Pieces OS Client SDK, follow these steps: + +1. **Download Pieces OS**: Pieces OS serves as the primary backend service, providing essential functionality for the SDK. Download the appropriate version for your operating system: + - [macOS](https://docs.pieces.app/installation-getting-started/macos) + - [Windows](https://docs.pieces.app/installation-getting-started/windows) + - [Linux](https://docs.pieces.app/installation-getting-started/linux) + +2. **Install the SDK**: Use pip to install the Pieces OS Client SDK package: + ```shell + pip install pieces_os_client + ``` + +## Initialize the Pieces Client + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() +``` + +### Custom Host URL + +When we initialize the Pieces Client, it defaults to `http://localhost:1000` for macOS/Windows and `http://localhost:5323` for Linux. If you have a remote instance of Pieces OS running, you can specify the host URL when initializing the Pieces Client: + +```python +from pieces_os_client.wrapper import PiecesClient + +# Specify the host URL +host_url = "http://your-host-url:your-port" + +pieces_client = PiecesClient(host=host_url) +``` + +### Closing the Client + +After you have finished using the Pieces Client, you should always close the client to free up resources: + +```python +pieces_client.close() +``` + +## Examples + +Here are some examples of how you can use to get familiar with the Pieces OS Client SDK. + +### Create a New Asset + +To create a new asset, you can use the `create_asset` method of the Pieces Client. Here's an example of how to create a new asset: + +```python +from pieces_os_client.wrapper import PiecesClient +from pieces_os_client import FragmentMetadata + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Set the content and metadata for the new asset +content = "print('Hello, World!')" +metadata = FragmentMetadata(ext=ClassificationSpecificEnum.PY) # optional metadata + +# Create the new asset using the content and metadata +new_asset_id = pieces_client.create_asset(content, metadata) +print(f"Created asset with ID: {new_asset_id}") + +# Close the client +pieces_client.close() +``` + +### Get All Assets + +To get all your assets, you can use the `assets` method of the Pieces Client. Here's an example of how to get all your assets and print their names: + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Get all assets and print their names +assets = pieces_client.assets() +for asset in assets: + logger.info(f"Asset Name: {asset.name}") + +# Close the client +pieces_client.close() +``` + +### Ask a Question to Pieces Copilot + +To ask a question to Pieces Copilot and stream the response, you can use the `stream_question` method of the Pieces Client. Here's an example of how to ask a question and stream the response: + +```python +from pieces_os_client.wrapper import PiecesClient + +# Initialize the PiecesClient +pieces_client = PiecesClient() + +# Set the question you want to ask +question = "What is Object-Oriented Programming?" + +# Ask the question and stream the response +for response in pieces_client.copilot.stream_question(question): + if response.question: + # Each answer is a chunk of the entire response to the question + answers = response.question.answers.iterable + for answer in answers: + print(answer.text,end="") + +# Close the client +pieces_client.close() +``` + +## Next Steps + +You can explore more features and functionalities of the built-in wrapper. + +- [Assets SDK](/build/sdks/python/assets) +- [Copilot SDK](/build/sdks/python/copilot) diff --git a/sidebars.ts b/sidebars.ts index e9fc4a31c..f41d88f89 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -569,22 +569,33 @@ const sidebars: SidebarsConfig = { id: 'build/examples/index', label: '📚 Examples', }, - // { - // type: 'doc', - // id: 'build/tutorials/index', - // label: '📚 Tutorials', - // }, + { + type: 'category', + label: '🔧 SDKs', + items: [ + { + type: 'doc', + id: 'build/sdks/python/index', + label: 'Python SDK', + }, + ], + }, { type: 'category', label: '🔍 API Reference', items: allSDKs.map(sdk => ({ type: 'doc' as const, id: `build/reference/${sdk.toLowerCase()}/index`, - label: `${sdk} SDK` + label: `${sdk}` })) }, // { // type: 'doc', + // id: 'build/tutorials/index', + // label: '📚 Tutorials', + // }, + // { + // type: 'doc', // id: 'build/concepts/index', // label: '🧠 Concepts', // }, @@ -634,7 +645,7 @@ const sidebars: SidebarsConfig = { label: 'Commands', }, ], - + // Raycast Sidebar raycastSidebar: [ { @@ -664,6 +675,35 @@ const sidebars: SidebarsConfig = { } ], + // Python SDK WrapperSidebar + pythonSDKWrapperSidebar: [ + { + type: 'ref', + id: 'build/index', + label: '← Back to Build', + }, + { + type: 'doc', + id: 'build/sdks/python/index', + label: 'Overview', + }, + { + type: 'doc', + id: 'build/sdks/python/quickstart', + label: 'Quickstart', + }, + { + type: 'doc', + id: 'build/sdks/python/assets', + label: 'Assets', + }, + { + type: 'doc', + id: 'build/sdks/python/copilot', + label: 'Copilot', + }, + ], + // Generates sidebar for each active SDK ...generatedSDKSidebars, }; diff --git a/src/lib/activeSDK.ts b/src/lib/activeSDK.ts index d53c264b5..32c901844 100644 --- a/src/lib/activeSDK.ts +++ b/src/lib/activeSDK.ts @@ -9,7 +9,10 @@ const inactiveSDKs = [ 'Dart', 'Kotlin', ] -export const allSDKs = [...activeSDKs, ...inactiveSDKs]; +export const allSDKs = [ + ...activeSDKs, + // ...inactiveSDKs +]; // Template for the sidebar items for each SDK const baseSidebarItems: {