Skip to content

vDAG spec

A vDAG (virtual Directed Acyclic Graph) is a workflow over blocks that are already running anywhere in the network, for example object detection → tracking → pose estimation. The vDAG specification lists the workflow's nodes (each mapped to a block, or to another vDAG), the graph that connects them, and the policies that pick blocks and transform data between steps.

At a glance

Submit with: POST /api/createvDAG on the Parser.
Then: deploy a vDAG controller so it can accept tasks.
Full example: services/applications/examples/vdag-pose-estimation/vdag.json in the repository.
Walkthrough: vDAG creator guide.

Top-level fields

Field Type Required Description
vdagName string Yes Name of the vDAG, used for discovery and reference.
vdagVersion object No version (for example "1.0.0") and release-tag (for example "stable"). Together with the name they form the vDAG URI, for example pose-estimator:v0.0.1-stable.
mode string No "create" (default) saves the vDAG. "dry-run" only validates the spec.
discoveryTags array No Tags for search and grouping, for example "vision", "chatbot" or "gpu".
controller object No Settings and policies for the vDAG's controller. See controller.
nodes array Yes The workflow's steps. See nodes.
graph object Yes How the steps connect. See graph.

vdagVersion

Field Type Description
version string Semantic version, for example "1.0.0".
release-tag string Release status, for example "beta", "stable" or "dev".

controller

Field Type Description
inputSources array Where the controller pulls input from, such as queue topics, stream IDs or external endpoints.
initParameters object Parameters available to the controller at start-up.
initSettings object Static settings, for example for error handling, logging or retries.
policies array Controller-level policies, such as quota, quality and health.

nodes

Each node is one step of the workflow.

Field Type Required Description
nodeLabel string Yes Unique name of the step within this vDAG. The graph refers to it.
nodeType string Yes "block" (a running block; the default) or "vdag" (another registered vDAG, used as a sub-workflow).
vdagURI string If nodeType is "vdag" URI of the nested vDAG.
manualBlockId string No Pin this step to a specific block. If set, assignmentPolicyRule is ignored.
assignmentPolicyRule object No A policy that chooses the block for this step. See Assignment policy.
preprocessingPolicyRule object No Runs before the step's computation, for example to filter, reshape or enrich the input. See Pre- and post-processing.
postprocessingPolicyRule object No Runs after the step's computation, for example to format, filter or validate the output, or to choose a route.
modelParameters object No Parameters passed to the block for this step's requests, overriding its defaults.

Note

Other node fields, such as inputProtocol, outputProtocol and IOMap, are filled in by the system or currently ignored. Don't include them.


graph

The graph describes how data flows between steps, using their nodeLabels.

Example: object detection → tracking → pose estimation

  1. object_detector finds objects in video frames.
  2. tracker follows each object from frame to frame.
  3. pose_estimator estimates each tracked object's pose.
"graph": {
  "connections": [
    {
      "nodeLabel": "tracker",
      "inputs": [
        { "nodeLabel": "object_detector" }
      ]
    },
    {
      "nodeLabel": "pose_estimator",
      "inputs": [
        { "nodeLabel": "tracker" }
      ]
    }
  ],
  "inputs": [
    {
      "nodeLabel": "object_detector"
    }
  ],
  "outputs": [
    {
      "nodeLabel": "pose_estimator"
    }
  ]
}

which runs as:

object_detector → tracker → pose_estimator
Field Type Description
connections array The edges. Each entry names a receiving step (nodeLabel) and the steps that feed it (inputs).
connections[].nodeLabel string The step receiving data.
connections[].inputs[].nodeLabel string A step sending data to it.
inputs array The entry step(s), which receive the client's input.
outputs array The exit step(s), whose output is returned to the client.

Rules

  • Every nodeLabel in the graph must exist in nodes.
  • The graph must be acyclic (no loops).
  • Steps with no incoming connections are entry points; steps with no outgoing connections are exit points.
  • A step with several inputs receives one packet from each. To combine them into a single task, use a Muxer in that block.

Assignment policy

Instead of pinning a step to a block (manualBlockId), you can let an assignment policy choose one when the vDAG is created:

  1. A filter query finds candidate blocks. See Search and filter.
  2. The candidates are passed to the assignment policy.
  3. The policy returns its choice, and that block is assigned to the step.

The policy receives clients for the global cluster and block metrics in its settings, so it can base its choice on live load.

class AIOSv1PolicyRule:
    def __init__(self, rule_id, settings, parameters):
        self.rule_id = rule_id
        self.settings = settings
        self.parameters = parameters

        # Clients for querying cluster and block metrics
        self.block_metrics_api = settings["block_metrics_api"]
        self.cluster_metrics_api = settings["cluster_metrics_api"]

    def eval(self, parameters, input_data, context):
        """
        input_data: the candidate blocks returned by the filter query
        """
        # Choose a block here, for example the least loaded one

        # Return the selection
        return []

Methods available on the metrics clients

Client Method Returns
cluster_metrics_api (GlobalClusterMetricsClient) get_cluster(cluster_id) Metrics for one cluster.
query_clusters(query_params=None) Clusters matching a filter.
block_metrics_api (GlobalBlocksMetricsClient) get_block(block_id) Metrics for one block.
query_blocks(query_params=None) Blocks matching a filter.
Client source
class GlobalClusterMetricsClient:
    """Client for accessing global cluster metrics."""

    def get_cluster(self, cluster_id):
        """Fetches metrics data for a specific cluster by its ID."""
        url = f"{self.base_url}/cluster/{cluster_id}"
        response = requests.get(url)
        return self._handle_response(response)

    def query_clusters(self, query_params=None):
        """Queries multiple clusters using optional filters."""
        url = f"{self.base_url}/cluster/query"
        response = requests.post(url, json=query_params)
        return self._handle_response(response)


class GlobalBlocksMetricsClient:
    """Client for accessing global block metrics."""

    def get_block(self, block_id):
        """Fetches metrics data for a specific block by its ID."""
        url = f"{self.base_url}/block/{block_id}"
        response = requests.get(url)
        return self._handle_response(response)

    def query_blocks(self, query_params=None):
        """Queries multiple blocks using optional filters."""
        url = f"{self.base_url}/block/query"
        response = requests.get(url, params=query_params)
        return self._handle_response(response)

Pre and post processing policies

Pre-processing and post-processing policies run custom logic around a step's main computation, inside the block's instance:

  • Pre-processing runs before the task reaches the instance's core logic, for example to validate, convert or enrich the input.
  • Post-processing runs after it, for example to reshape the output for the next step, validate it, or choose which path to take.

Policies are loaded into the instance automatically the first time it receives a task for that vDAG step. This lets one block serve several vDAGs, each with its own transformations.

Both policies have the same shape. They receive the packet and return it, possibly modified:

class AIOSv1PolicyRule:
    def __init__(self, rule_id, settings, parameters):
        self.rule_id = rule_id
        self.settings = settings
        self.parameters = parameters

        # The vDAG
        self.vdag = settings['vdag']

        # The block running this step
        self.block = settings['block']

        # This step's nodeLabel in the vDAG
        self.node_label = settings['node_label']

        # The block's ID
        self.block_id = settings['block_id']

    def eval(self, parameters, input_data, context):
        """
        input_data["packet"]: the AIOSPacket protobuf object
        """
        packet = input_data['packet']

        # Modify the packet here

        return packet

The packet is an AIOSPacket:

message AIOSPacket {
    string session_id = 1;      // Session identifier; enables stateful logic and graph routing
    uint64 seq_no = 2;          // Sequence number within the session
    string data = 4;            // JSON-encoded payload
    double ts = 5;              // Optional Unix timestamp (latency metrics, ordering)
    string output_ptr = 6;      // JSON-encoded routing to downstream blocks
    repeated FileInfo files = 7;// Optional attached files
}

message FileInfo {
    string metadata = 1;        // JSON string describing the file
    bytes file_data = 2;        // Raw file content
}

Create the vDAG

curl -X POST http://<parser-url>/api/createvDAG \
  -H "Content-Type: application/json" \
  -d @./vdag.json

Next: deploy a controller.