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
object_detectorfinds objects in video frames.trackerfollows each object from frame to frame.pose_estimatorestimates 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:
| 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
nodeLabelin the graph must exist innodes. - 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:
- A filter query finds candidate blocks. See Search and filter.
- The candidates are passed to the assignment policy.
- 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.