Skip to main content

Artifact Management

SDK Guide​

This guide covers the SDK interface to manage artifacts, including agents, models, and protocol SDKs using Python.

Setting Up the SDK Client​

To manage resources efficiently, set up a singleton pattern for the Almanak client, authenticated by your ALMANAK_API_KEY environment variable.

from almanak import Almanak
import os

# Singleton setup for the Almanak client
class AlmanakSingleton:
    _instance = None

    @classmethod
    def get_instance(cls):
        if cls._instance is None:
            cls._instance = Almanak(
                api_key=None,  # Uses os.environ["ALMANAK_API_KEY"]
                _strict_response_validation=True,
            )
        return cls._instance

# Access the client
client = AlmanakSingleton.get_instance()

Artifact Operations​

Listing Artifacts​

Retrieve a paginated list of artifacts.

artifacts_list = client.library.artifacts.list(limit=10, offset=0)
print("Artifacts list:", artifacts_list)

Retrieving an Artifact​

Fetch an artifact by name or ID.

artifact = client.library.artifacts.retrieve(artifact_name="bollinger-bands")
print("Retrieved artifact:", artifact)

Creating an Artifact​

Create a new artifact with specific metadata.

created_artifact = client.library.artifacts.create(
    artifact_name="bollinger-bands",
    description="Bollinger Bands strategy",
    type="strategy",
    metadata={"risk_level": "medium"},
    is_public=False,
)
print("Created artifact:", created_artifact)

Updating an Artifact​

Modify an artifact’s details, such as its description.

updated_artifact = client.library.artifacts.update(
    artifact_name="bollinger-bands", updates={"description": "Updated description"}
)
print("Updated artifact:", updated_artifact)

Deleting an Artifact​

Delete an artifact by name or ID.

deleted_artifact = client.library.artifacts.delete("bollinger-bands")
print("Deleted artifact:", deleted_artifact)

Artifact Version Management​

Uploading a New Version​

Upload a new version with relevant files.

new_version = client.library.artifacts.upload_new_version(
    "bollinger-bands", files=["path/to/bollinger_script.py"]
)
print("New version uploaded:", new_version)

Listing Versions​

View versions of an artifact.

versions_list = client.library.artifacts.versions.list("bollinger-bands", limit=10)
print("Versions list:", versions_list)

Downloading a Version​

Generate a download URL for a specific version.

download_url = client.library.artifacts.versions.download("bollinger-bands", "v1.0")
print("Download URL:", download_url)

Almanak CLI Guide​

This section details using the Almanak CLI to manage artifacts and strategies, with setup instructions, command usage, and options for each command.

Setup​

  1. Install Requirements
    Ensure Python and necessary packages (click, configparser, almanak) are installed.

  2. Environment Variables
    Set up your API key.

    export ALMANAK_API_KEY="<YOUR_API_KEY>"

  3. Authorize CLI Access
    Run authorize to open the Almanak profile page in your browser, retrieve your API key, and securely store it by pasting it into the CLI when prompted.

    almanak authorize

Available Commands​

Global Commands​

  • Authorize
    Opens the login page in your browser to retrieve the API key, then securely stores it.

    almanak authorize

Strategy Commands​

  • List Strategies
    Lists all available strategies with pagination.

    almanak strategy list

  • Describe a Strategy
    Retrieves details of a specific strategy by name.

    almanak strategy describe --strategy-name "example-strategy"

  • Validate a Strategy
    Validates the strategy structure, including the entry file, class definitions, and required configurations.

    almanak strategy validate \
        --working-dir "./strategies" \
        --strategy-entry-file "strategy.py" \
        --strategy-class "Strategy" \
        --ignore-file ".almanakignore"

  • Upload Strategy
    Uploads multiple files as a new version of the specified strategy, after validating its structure.

    almanak strategy upload \
        --strategy-name "example-strategy" \
        --working-dir "./strategies" \
        --strategy-entry-file "strategy.py" \
        --strategy-class "Strategy" \
        --permissions-required '{"allow": {"protocol": {"action": {"param": ["value"]}}}}' \
        --wallets-required '{"chain": {"network": {"token": 100}}}' \
        --pip "requirements.txt" \
        --ignore-file ".almanakignore"

Artifact Commands​

  • Upload Artifact
    Creates and uploads a new artifact with metadata and public/private options.

    almanak artifact upload \
        --artifact-name "new-artifact" \
        --description "Artifact description" \
        --metadata "key1=value1,key2=value2" \
        --is-public

Common Usage Examples​

  • Listing All Strategies

    almanak strategy list

  • Validating and Uploading a Strategy

    almanak strategy validate --working-dir "./strategies"
    almanak strategy upload --strategy-name "example-strategy" --working-dir "./strategies"

  • Creating a Public Artifact

    almanak artifact upload --artifact-name "public-artifact" --description "Publicly available artifact" --is-public

Notes​

  • Ensure ALMANAK_API_KEY is correctly set for CLI authentication.
  • Use .almanakignore or .gitignore files to define ignore patterns for strategy uploads, allowing only essential files to be uploaded.