pieces_os_client 2.4.0

A powerful code engine package for writing applications on top of Pieces OS

Pieces OS Client SDK For Python

Introduction

The Pieces SDK is a powerful code engine package designed for writing applications on top of Pieces OS. It facilitates communication with a locally hosted server to enable features such as copilot chats, asset saving, and more.

Installation

To get started with the Pieces 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
   • Windows
   • Linux

2. Install the PyPI Package: Use pip to install the Pieces SDK package:

   pip install pieces_os_client
   

Usage

After installing the SDK, you can import the library into your project and start utilizing its features:

import pieces_os_client as pos_client

For detailed usage instructions and examples, refer to the documentation.

Features

The Pieces SDK offers the following key features:

1. Copilot Chats: Communicate seamlessly with copilot chats functionality.
2. Asset Management: Save and manage assets and formats efficiently.
3. Local Server Interaction: Interact with a locally hosted server for various functionalities.
4. Multi LLMs support: Use any Pieces supported LLMs to power apps.

Requirements

The Pieces SDK has the following system requirements:

• Pieces OS running as a backend service.
• Python environment with pip for installing the SDK package.

Getting Started

First, we will create a Python script to test the connection to the Pieces OS server. This involves creating a config.py file to store your configuration info and a wellknown.py file to test the connection.

It's important to note that the localhost port for Pieces OS is different based on the operating system.

For Linux, you should use localhost:5323.

For macOS and Windows, you should use localhost:1000.

Create a main.py file and add this code to confirm you have installed the correct package:

import pieces_os_client
import platform

# Defining the port based on the operating system. For Linux, the port is 5323, and for macOS/Windows, the port is 1000.
platform_info = platform.platform()
if 'Linux' in platform_info:
    port = 5323
else:
    port = 1000

# The `basePath` defaults to http://localhost:1000, however we need to change it to the correct port based on the operating system.
configuration = pieces_os_client.Configuration(host=f"http://localhost:{port}")

# Initialize the Pieces ApiClient
api_client = pieces_os_client.ApiClient(configuration)

# Enter a context with an instance of the ApiClient
with pieces_os_client.ApiClient(configuration) as api_client:
    # Create an instance of the WellKnownApi class
    api_instance = pieces_os_client.WellKnownApi(api_client)

    try:
        # Retrieve the (wellknown) health of the Pieces OS
        api_response = api_instance.get_well_known_health()
        print("The response of WellKnownApi().get_well_known_health:")
        print(api_response) # Response: ok
    except Exception as e:
        print("Exception when calling WellKnownApi->get_well_known_health: %s\n" % e)

Run the following command to execute the script:

python3 main.py

Examples

Here are some examples of the basic endpoint for getting up and running:

Connect

When developing and creating an application on top of Pieces OS, it is important that you authenticate with the application itself when performing requests.

To 'connect' your application (this Python project) to the server, you will need to make a POST request to the api_instance.connect() endpoint of the API and print the response.

# Enter a context with an instance of the API client
with pieces_os_client.ApiClient(configuration) as api_client:
  # Create an instance of the API class
  api_instance = pieces_os_client.ConnectorApi(api_client)
  seeded_connector_connection = pieces_os_client.SeededConnectorConnection() # SeededConnectorConnection |  (optional)

  try:
      # /connect [POST]
      api_response = api_instance.connect(seeded_connector_connection=seeded_connector_connection)
      print("The response of ConnectorApi->connect:\n")
      pprint(api_response)
  except Exception as e:
      print("Exception when calling ConnectorApi->connect: %s\n" % e) 

Create a new Asset

When integrating your application with Pieces OS, creating a new asset is a fundamental task that enables you to manage your resources effectively. This code snippet demonstrates how to accomplish this task using the Pieces OS API.

After establishing a connection with the API client and instantiating the Assets API class, you can call the assets_create_new_asset method to create the asset.You can customize the asset creation process by setting parameters such as transferables and seed.

# Enter a context with an instance of the API client
with pieces_os_client.ApiClient(configuration) as api_client:
   # Create an instance of the API class
   api_instance = Assets API(api_client)
   transferables = True # bool | This is a boolean that will decided if we are want to return the transferable data (default) or not(performance enhancement) (optional)
   seed = pieces_os_client.Seed() # Seed |  (optional)

   try:
      # /assets/create [POST] Scoped to Asset
      api_response = api_instance.assets_create_new_asset(transferables=transferables, seed=seed)
      print("The response of AssetsApi->assets_create_new_asset:\n")
      pprint(api_response)
   except Exception as e:
      print("Exception when calling AssetsApi->assets_create_new_asset: %s\n" % e)

Get your Assets Snapshot

When working with your app implementation you will often need to call the entire asset snapshot in order to get the correct snippet from your storage in Pieces OS. You can use this asset snapshot by passing the asset's ID and a boolean value indicating whether or not to return transferable data. The response from the API is then printed to the console.

 
# Enter a context with an instance of the API client
with pieces_os_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = pieces_os_client.AssetApi(api_client)
    asset = '2254f2c8-5797-40e8-ac56-41166dc0e159' # str | The id (uuid) of the asset that you are trying to access.
    transferables = True # bool | This is a boolean that will decide if we want to return the transferable data (default) or not (performance enhancement) (optional)
    seeded_accessor = pieces_os_client.SeededAccessor() # SeededAccessor |  (optional)

    try:
         # api_instance.asset_snapshot(asset, transferables=transferables, seeded_accessor=seeded_accessor) [POST] Scoped to an Asset
        api_response = api_instance.asset_snapshot_post(asset, transferables=transferables, seeded_accessor=seeded_accessor)
        print("The response of AssetApi->asset_snapshot_post:\n")
        print(api_response)
    except Exception as e:
        print("Exception when calling AssetApi->asset_snapshot_post: %s\n" % e)

A developer documentation that outlines all the ins and outs of our available endpoints can be found here.

Learn More / Support

Explore more about Pieces SDK and get help from the following resources:

• 🚀 Getting Started Tutorial
• 📜 Pieces Docs
• 💬 Discord Community

License

This repository is available under the MIT License.