This document provides a technical guide for integrating with AkoFlow via its API. It covers workflow creation, including the YAML specification, encoding, and API request procedures. Future enhancements such as workflow monitoring and artifact retrieval are noted as coming soon.

---

1. Workflow Creation

To create a workflow in AkoFlow, a YAML configuration file must be generated, encoded in Base64, and transmitted to the AkoFlow API.

1.1 Workflow Specification (YAML Format)

The following YAML configuration defines a sample workflow in AkoFlow:

name: p-inference-nemo
spec:
  runtime: "sdumont"
  image: "/scratch/.../.../p-inference-nemo/sifs/p-inference-nemo.sif"
  storagePolicy:
    type: default

  webhooks:
    - name: "inference-examples"
      url: "https://myhost.com/mypath/mywebhook"

  volumes:
    - /data-akoflow/sifs/:/scratch/.../.../p-inference-nemo/sifs
    - /data-akoflow/akf-wine-singularity/:/scratch/.../.../p-inference-nemo/akf-wine-sdumont

  mountPath: "/scratch/.../.../p-inference-nemo/akf-wine-sdumont"

  activities:
    - name: inference-examples
      run: |
        echo "Running inference-examples"
        conda run -n tutorial mlflow run .  --env-manager=local
      cpuLimit: 1

YAML Specification Details:

• name: Specifies the workflow name.
• spec.runtime: Defines the execution environment.
• spec.image: Path to the container image for execution.
• storagePolicy.type: Defines the storage policy.
• webhooks: Specifies webhook event listeners.
• volumes: Defines volume mappings for the workflow execution.
• mountPath: Sets the mount point for volumes.
• activities: Defines execution activities, commands, and resource constraints.

---

2. API Integration

2.1 Sending a Workflow to AkoFlow (Python Example)

The following Python script demonstrates how to encode the YAML specification in Base64 and send it to AkoFlow’s API.

import yaml
import json
import base64
import requests

# Define workflow YAML configuration as a string
workflow_yaml = """
name: p-inference-nemo
spec:
  runtime: "sdumont"
  image: "/scratch/.../.../p-inference-nemo/sifs/p-inference-nemo.sif"
  storagePolicy:
    type: default

  webhooks:
    - name: "inference-examples"
      url: "https://myhost.com/mypath/mywebhook"

  volumes:
    - /data-akoflow/sifs/:/scratch/.../.../p-inference-nemo/sifs
    - /data-akoflow/akf-wine-singularity/:/scratch/.../.../p-inference-nemo/akf-wine-sdumont

  mountPath: "/scratch/.../.../p-inference-nemo/akf-wine-sdumont"

  activities:
    - name: inference-examples
      run: |
        echo "Running inference-examples"
        conda run -n tutorial mlflow run .  --env-manager=local
      cpuLimit: 1
"""

# Encode YAML content in Base64 format
encoded_yaml = base64.b64encode(workflow_yaml.encode("utf-8")).decode("utf-8")

API_URL = "https://api.akoflow.com/workflows"
HEADERS = {
    "Content-Type": "application/json",
}

# Prepare request payload
payload = {
    "workflow": encoded_yaml
}

# Send API request
response = requests.post(API_URL, headers=HEADERS, json=payload)

# Output response
print("Response Status Code:", response.status_code)
print("Response Body:", response.json())

---

3. Webhook Notifications

AkoFlow provides webhook notifications that are triggered when specific workflow events occur. These webhooks allow external systems to track workflow progress and activity execution status in real time.

3.1 Webhook Event Types

AkoFlow emits the following webhook events:

• WORKFLOW_DONE: Triggered when the entire workflow execution is completed.
• ACTIVITY_COMPLETED: Triggered when an individual activity within the workflow is completed.

---

3.2 Webhook Request Format

When an event occurs, AkoFlow sends a POST request to the configured webhook URL. The request body contains JSON payloads representing the state of the workflow or activity.

3.2.1 ACTIVITY_COMPLETED Webhook Payload

The ACTIVITY_COMPLETED webhook provides details about a specific activity execution, including timestamps, status, and dependencies.

Example Request:

POST /webhook-endpoint HTTP/1.1
Host: example.com
Content-Type: application/json

Payload:

{
  "type": "ACTIVITY_COMPLETED",
  "data": {
    "Id": 123,
    "WorkflowId": 456,
    "Namespace": "default",
    "Name": "inference-examples",
    "Image": "/scratch/.../.../p-inference-nemo/sifs/p-inference-nemo.sif",
    "ResourceK8sBase64": "c29tZS1lbmNvZGVkLXZhbHVl",
    "Status": 1,
    "ProcId": "abcd-efgh-1234",
    "DependOnActivity": null,
    "CreatedAt": "2025-03-09T12:00:00Z",
    "StartedAt": "2025-03-09T12:05:00Z",
    "FinishedAt": "2025-03-09T12:10:00Z"
  }
}

Field Descriptions:

Field	Type	Description
type	string	Event type (ACTIVITY_COMPLETED)
Id	int	Unique identifier for the activity
WorkflowId	int	Identifier of the associated workflow
Namespace	string	Namespace where the activity is executed
Name	string	Name of the activity
Image	string	Path to the container image used in execution
ResourceK8sBase64	string	Base64-encoded Kubernetes resource description
Status	int	Status of the activity (e.g., 1 for completed)
ProcId	string (nullable)	Process ID of the running activity
DependOnActivity	int (nullable)	ID of the dependent activity (if applicable)
CreatedAt	string (nullable)	Timestamp when the activity was created
StartedAt	string (nullable)	Timestamp when the activity execution started
FinishedAt	string (nullable)	Timestamp when the activity execution completed

---

3.2.2 WORKFLOW_DONE Webhook Payload

The WORKFLOW_DONE webhook provides details when an entire workflow execution is completed.

Example Request:

POST /webhook-endpoint HTTP/1.1
Host: example.com
Content-Type: application/json

Payload:

{
  "type": "WORKFLOW_DONE",
  "data": {
    "ID": 456,
    "Namespace": "default",
    "Runtime": "sdumont",
    "Name": "p-inference-nemo",
    "RawWorkflow": "c29tZS1lbmNvZGVkLXlhbWw=",
    "Status": 1
  }
}

Field Descriptions:

Field	Type	Description
type	string	Event type (WORKFLOW_DONE)
ID	int	Unique identifier for the workflow
Namespace	string	Namespace where the workflow is executed
Runtime	string	Execution environment for the workflow
Name	string	Workflow name
RawWorkflow	string	Base64-encoded YAML representation of the workflow
Status	int	Status of the workflow (e.g., 1 for completed)

---

3.3 Configuring Webhooks in AkoFlow

Webhooks can be configured in the workflow YAML file under the webhooks section.

Example Configuration in YAML

webhooks:
  - name: "workflow-events"
    url: "https://example.com/webhook-endpoint"

When an event occurs, AkoFlow will send a POST request to the specified URL.

4. Workflow Monitoring (Coming Soon)

Support for workflow monitoring is under development and will be available in future releases.

---

5. Artifact Retrieval (Coming Soon)

Functionality for downloading artifacts generated by workflow activities is planned for a future update.

---