Merge branch 'main' into scalar-api-refs

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
+
 <Grid cols={2}>
   <div className={'grid-card'}>
     <div style={{

docs/build/index.mdx

@@ -58,58 +58,11 @@ We're always working on improving and extending the current stack of available S
     <p>Python SDK for Pieces OS</p>
     <CTAButton
       label={'Get Started'}
-      href={'/build/reference/python'}
-      type={'secondary'}
-    />
-  </div>
-  <div className={'grid-card'}>
-    <div style={{
-      display: 'flex',
-      alignItems: 'center',
-      gap: '10px'
-    }}>
-      <img
-        src={'/assets/languages/dart_logo.png'}
-        alt={'Dart Logo'}
-        width={40}
-      />
-      <span style={{
-        fontSize: '1.5rem',
-        fontWeight: 'bold'
-      }}>Dart SDK</span>
-    </div>
-    <MiniSpacer/>
-    <p>Dart SDK for Pieces OS</p>
-    <CTAButton
-      label={'Get Started'}
-      href={'/build/reference/dart'}
-      type={'secondary'}
-    />
-  </div>
-  <div className={'grid-card'}>
-    <div style={{
-      display: 'flex',
-      alignItems: 'center',
-      gap: '10px'
-    }}>
-      <img
-        src={'/assets/languages/kotlin_logo.png'}
-        alt={'Kotlin Logo'}
-        width={40}
-      />
-      <span style={{
-        fontSize: '1.5rem',
-        fontWeight: 'bold'
-      }}>Kotlin SDK</span>
-    </div>
-    <MiniSpacer/>
-    <p>Kotlin SDK for Pieces OS</p>
-    <CTAButton
-      label={'Get Started'}
-      href={'reference/kotlin'}
+      href={'/build/sdks/python'}
       type={'secondary'}
     />
   </div>
+
 </Grid>
 
 <MiniSpacer />

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()
+```