Creating Apps and Blocks via SDK

To initiate the creation of Apps and Blocks using the SDK, the first step involves instantiating the app_client and block_client.

For detailed guidance on Press Apps and Blocks, refer to the Reference Documentation and practical usage examples.

API Documentation is linked with every function in the Reference Documentation which would help in understanding the schema of the payload.

Creating Resource Dependencies with Artifacts

If we want to create a resource which is dependent on an Image (such as Block Spec) but we don’t want it to be source directly from the code repository, we can package the required files for image creation into a zip archive known as an Artifact.

More information for Artifact can be found in Artifact and Compression Document.

Providing Instance Type and Storage in Workflow Block Spec

When defining a workflow step in workflow block spec, we have the option to set the instance type and storage by including them in the resources key in the following format:

"resources": {
    "instanceTypeId": 23,
    "storage": "20GB"
}

A list of all available instances along with their corresponding instanceTypeId can be obtained using the list-instance-options function.

Adding the resources section is optional. If we don’t specify it for a particular step, the default values will be used. We can retrieve the default values by using get_default_resources function.

Providing Instance Type in Webapp Block Spec

When defining a webapp step in webapp block spec, we have the option to set the instance type by including them in the resources key in the following format:

"resources": {
    "instanceTypeId": 1,
}

Session Stickiness in Webapp Block

By default, session stickiness is disabled (false). You can activate session stickiness by setting the sessionStickiness parameter to true.

Session stickiness ensures that each user’s requests are consistently directed to a particular server. This feature is especially valuable for stateful applications like web applications that rely on server-stored session data.

Note that employing session stickiness may lead to unpredictable behavior and is not recommended if you plan to scale your application.

Providing Parameters in Blocks.

We can define parameters in the block spec and provide their values while creating the block deployment. The values for these parameters can be updated even after the deployment has been done. In block spec, we can define parameters in the following format:

"parameters": {
    "run": [
        {
            "defaultValue": "AVG",
            "description": "Select an aggregation function (e.g., AVG, SUM, COUNT)",
            "name": "agg_type",
            "required": false,
            "title": "Agg Type",
            "type": "string",
        },
        {
            "defaultValue": false,
            "description": "Enable email notifications",
            "name": "email_notifications",
            "required": false,
            "title": "Email Notifications",
            "type": "boolean",
        },
        {
            "defaultValue": 10,
            "description": "Select the number of iterations",
            "name": "num_iterations",
            "options": [
                {
                    "title": "Low",
                    "value": 10,
                },
                {
                    "title": "Medium",
                    "value": 50,
                },
                {
                    "title": "High",
                    "value": 100,
                },
            ],
            "required": false,
            "title": "Number of Iterations",
            "type": "number",
        },
        {
            "defaultValue": ["input.csv", "output.csv"],
            "description": "Specify input and output file names",
            "name": "file_names",
            "required": true,
            "title": "File Names",
            "type": "string_array",
        },
    ],
}

We can provide the values of these parameters while creating the block deployment in the following format:

"parameters": {
    "run": {
        "agg_type": "AVG",
        "email_notifications": true,
        "num_iterations": 50,
        "file_names": ["input.csv", "output.csv"],
    },
}

Providing Triggers in Workflow Block Spec

For Workflow Blocks, triggers can be one of the following: Time based, Webhook based or Manual.

// For Time Based Trigger, cron expression is required
"triggers": [
    {
        "cron": "0 0 * * *",
    },
]

// For Webhook Based Trigger, we need to provide webhook key which is a boolean and webhookPolicy which would be either "generate" (in case of creating a new webhook) or "preserve" (in case of using an existing webhook)
"triggers": [
    {
        "webhook": true,
        "webhookPolicy": "generate",
    },
]

// For Manual Trigger, we can either skip this key or provide an empty list
"triggers": []

Providing Watchers in Workflow Block Spec

For Workflow Blocks, we can set multiple watchers which can be User Based or Webhook Based.

// For User Based Watcher, user email is required. We also need to specify the events for which we want to receive notifications.
"watchers": [
    {
        "user": "someone@peak.ai",
        "events": {
            "success": false,
            "fail": true,
        },
    },
]

// For Webhook Based Watcher, we need to provide webhook details such as webhook url and payload along with the events for which we want to receive notifications.
"watchers": [
    {
        "webhook": {
            "name": "info",
            "url": "https://abc.com/post",
            "payload": "{'pingback-url':'https:/workflow/123'}",
        },
        "events": {
            "success": false,
            "fail": true,
            "runtimeExceeded": 10,
        },
    },
]

// We can also add multiple watchers of different types
"watchers": [
    {
        "user": "someone@peak.ai",
        "events": {
            "success": false,
            "fail": true,
        },
    },
    {
        "webhook": {
            "name": "info",
            "url": "https://abc.com/post",
            "payload": "{'pingback-url':'https:/workflow/123'}",
        },
        "events": {
            "success": false,
            "fail": true,
            "runtimeExceeded": 10,
        },
    },
]

Providing Image Details for Block Specs

For creating block specs, there are three ways of providing image details.

1. Using imageRef: Multiple image configurations can be included in block config and referenced in workflow steps as shown in following example.

{
    "config": {
        "images": {
            "image1": {
                "context": ".",
                "dockerfile": "Dockerfile",
                "version": "0.0.1",
                "buildArguments": {
                    "npm_token": "random_token"
                }
            },
            "image2": {
                "context": ".",
                "dockerfile": "Dockerfile",
                "version": "0.0.1",
                "buildArguments": {
                    "npm_token": "random_token"
                }
            }
        },
        "steps": {
            "step1": {
                "command": "echo hello",
                "type": "standard",
                "imageRef": "image1",
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "10GB"
                }
            },
            "step2": {
                "command": "echo world",
                "type": "standard",
                "imageRef": "image2",
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "20GB"
                }
            }
        }
    }
}

2. Using inline image: Image configuration can be directly provided within the workflow step or webapp.

{
    "config": {
        "steps": {
            "step1": {
                "command": "echo hello",
                "type": "standard",
                "image": {
                    "context": ".",
                    "dockerfile": "Dockerfile",
                    "version": "0.0.1",
                    "buildArguments": {
                        "npm_token": "random_token"
                    }
                },
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "10GB"
                }
            }
        }
    }
}

3. Using imageDetails: Existing image versions can be utilized in workflow steps and webapps. The block’s scope should be private when using existing image details.

{
    "config": {
        "steps": {
            "step1": {
                "command": "echo world",
                "type": "standard",
                "imageDetails": {
                    "id": 1,
                    "versionId": 1
                },
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "20GB"
                }
            }
        }
    }
}

Usage Examples

Block Specs

Creating a Block Spec

A block spec can be created by using Block create_spec function.

Consider the following example:

workflow_block_spec_body = {
    "version": "1",
    "kind": "workflow",
    "metadata": {
        "name": "workflow-block-shared",
        "title": "Workflow Block",
        "summary": "Creating a new workflow block spec.",
        "description": "Creating a new workflow block spec from SDK.",
        "descriptionContentType": "text/markdown",
        "imageUrl": "https://my-block-pics.com/image-0.jpg",
        "tags": [
            {
                "name": "sdk",
            },
        ],
    },
    "release": {
        "version": "1.0.0",
        "notes": "This is the original release",
    },
    "config": {
        "triggers": [],
        "steps": {
            "step-1": {
                "type": "standard",
                "image": {
                    "context": ".",
                    "dockerfile": "Dockerfile",
                    "version": "0.0.1",
                },
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "10GB",
                },
                "command": "python main.py",
            },
        },
    },
}

workflow_parameters = {
    "run": [
        {
            "defaultValue": "AVG",
            "description": "Select an aggregation function (e.g., AVG, SUM, COUNT)",
            "name": "agg_type",
            "required": False,
            "title": "Agg Type",
            "type": "string",
        },
        {
            "defaultValue": False,
            "description": "Enable email notifications",
            "name": "email_notifications",
            "required": False,
            "title": "Email Notifications",
            "type": "boolean",
        },
        {
            "defaultValue": 10,
            "description": "Select the number of iterations",
            "name": "num_iterations",
            "options": [
                {
                    "title": "Low",
                    "value": 10,
                },
                {
                    "title": "Medium",
                    "value": 50,
                },
                {
                    "title": "High",
                    "value": 100,
                },
            ],
            "required": False,
            "title": "Number of Iterations",
            "type": "number",
        },
        {
            "defaultValue": ["input.csv", "output.csv"],
            "description": "Specify input and output file names",
            "name": "file_names",
            "required": True,
            "title": "File Names",
            "type": "string_array",
        },
    ],
}

workflow_block_spec = block_client.create_spec(
    body=workflow_block_spec_body,
    artifact={"path": "../peak", "ignore_files": [".dockerignore"]},
    featured=True,
    scope="shared",
    tenants=["tenant1", "tenant2"],
    parameters=workflow_parameters,
)

The response includes the id of the newly generated spec, which is useful for creating apps or new block spec releases.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609"
}

More examples for creating the block spec can be found here.

Creating a new Block Spec Release

To modify the configuration of an existing block spec, a new block spec release needs to be generated. This can be achieved using the create_spec_release function.

body = {
    "config": {
        "triggers": [],
        "images": {
            "example-image": {
                "buildArguments": {
                    "CHUNK_SIZE": "1000",
                },
                "context": ".",
                "dockerfile": "Dockerfile",
                "secrets": ["SECRET_1"],
                "useCache": False,
                "version": "0.0.1",
            },
        },
        "steps": {
            "step-1": {
                "type": "standard",
                "imageRef": "example-image",
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "10GB",
                },
                "command": "python main.py",
            },
        },
    },
    "release": {
        "version": "2.0.0",
        "notes": "This is a revised release",
    },
}

workflow_parameters = {
    "run": [
        {
            "defaultValue": "AVG",
            "description": "Select an aggregation function (e.g., AVG, SUM, COUNT)",
            "name": "agg_type",
            "required": False,
            "title": "Agg Type",
            "type": "string",
        },
        {
            "defaultValue": False,
            "description": "Enable email notifications",
            "name": "email_notifications",
            "required": False,
            "title": "Email Notifications",
            "type": "boolean",
        },
        {
            "defaultValue": 10,
            "description": "Select the number of iterations",
            "name": "num_iterations",
            "options": [
                {
                    "title": "Low",
                    "value": 10,
                },
                {
                    "title": "Medium",
                    "value": 50,
                },
                {
                    "title": "High",
                    "value": 100,
                },
            ],
            "required": False,
            "title": "Number of Iterations",
            "type": "number",
        },
        {
            "defaultValue": ["input.csv", "output.csv"],
            "description": "Specify input and output file names",
            "name": "file_names",
            "required": True,
            "title": "File Names",
            "type": "string_array",
        },
    ],
}

new_spec_release = block_client.create_spec_release(
    spec_id="0bddb4c6-40c5-45c3-b477-fceb2c051609",
    body=body,
    artifact={"path": "../peak", "ignore_files": [".dockerignore"]},
    parameters=workflow_parameters,
)

The response provides the id and release version of the newly generated spec release.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
    "release": {
        "version": "2.0.0"
    }
}

Block Deployments

Creating a new Block Deployment

The blocks can be deployed using create_deployment function.

Consider the following example, where we are creating a new block deployment from the block spec release which we created in the previous step.

body = {
    "metadata": {
        "description": "Creating a new workflow block deployment.",
        "descriptionContentType": "text/markdown",
        "imageUrl": "https://my-block-pics.com/image-0.jpg",
        "name": "new-deployment",
        "summary": "Creating new deployment.",
        "tags": [
            {
                "name": "sdk",
            },
        ],
        "title": "New Deployment",
    },
    "parameters": {
        "run": {
            "agg_type": "AVG",
            "email_notifications": True,
            "num_iterations": 50,
            "file_names": ["input.csv", "output.csv"],
        },
    },
    "revision": {
        "notes": "This is the initial revision",
    },
    "spec": {
        "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
        "release": {
            "version": "1.0.0",
        },
    },
}

workflow_block_deployment = block_client.create_deployment(body)

It returns the id of the newly created block deployment.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609"
}

App Specs

Creating an App Spec

An app can be considered as a collection of blocks. We can create an app spec by using existing block specs or block spec releases. It can be generated using the create_spec function.

It’s worth noting that the creation of an app spec with a shared scope is possible only when all the associated blocks are also shared with those tenants.

Consider the following example, where we are creating an app spec using existing block specs.

spec_body = {
    "version": "1",
    "kind": "app",
    "metadata": {
        "name": "sdk",
        "title": "New App Spec",
        "summary": "Create new app spec",
        "description": "Creating app spec from SDK",
        "descriptionContentType": "text/markdown",
        "imageUrl": "https://my-spec-pics.com/image-1.jpg",
        "tags": [
            {
                "name": "sdk",
            },
        ],
    },
    "release": {
        "version": "1.0.0",
        "notes": "This is the original release",
    },
    "config": [
        {
            "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "release": {
                "version": "1.0.0",
            },
        },
        {
            "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "release": {
                "version": "2.0.0",
            },
        },
    ],
}


created_app_spec = app_client.create_spec(
    body=spec_body,
    featured=True,
    scope="shared",
    tenants=["tenant1", "tenant2"],
)

The response includes the id of the newly generated app spec.

{
    "id": "a3e77006-86f3-4829-8c43-f21ad462dbbd"
}

Creating a new App Spec Release

Similar to blocks, a new app spec release can be generated to modify the spec configuration. We can create a new app spec release by using create_spec_release function.

Consider the following example, where we are creating a new app spec release from the app spec which we created in the previous step.

body = {
    "config": [
        {
            "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "release": {
                "version": "1.0.0",
            },
        },
    ],
    "release": {
        "version": "2.0.0",
        "notes": "This is a revised release",
    },
}


new_spec_release = app_client.create_spec_release(
    spec_id="a3e77006-86f3-4829-8c43-f21ad462dbbd",
    body=body,
)

The response provides the id and release version of the newly generated spec release.

{
    "id": "a3e77006-86f3-4829-8c43-f21ad462dbbd",
    "release": {
        "version": "2.0.0"
    }
}

App Deployments

Creating a new App Deployment

Deploying an app spec leads to deployment of all constituent blocks. We can create a new app deployment by using create_deployment function.

deployment = app_client.create_deployment(
    body={
        "metadata": {
            "description": "Creating a new deployment.",
            "descriptionContentType": "text/markdown",
            "imageUrl": "https://my-spec-pics.com/image-1.jpg",
            "name": "new-deployment",
            "summary": "This creates a new deployment",
            "tags": [
                {
                    "name": "sdk",
                },
            ],
            "title": "New Deployment",
        },
        "parameters": {
            "block-1": {
                "run": {
                    "agg_type": "AVG",
                    "email_notifications": True,
                    "num_iterations": 50,
                    "file_names": ["input.csv", "output.csv"],
                },
            },
            "block-2": {
                "run": {
                    "agg_type": "MAX",
                    "email_notifications": False,
                    "num_iterations": 10,
                    "file_names": ["input.csv", "output.csv"],
                },
            },
        },
        "revision": {
            "notes": "This is the initial revision",
        },
        "spec": {
            "id": "a3e77006-86f3-4829-8c43-f21ad462dbbd",
            "release": {
                "version": "1.0.0",
            },
        },
    },
)

The response includes the id of the newly created app deployment.

{
    "id": "e04e308d-98dc-4443-bb02-c4ef990a3fdc"
}