Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🏗️Build the DAG with Branching

Audience: Nexus adopters and integrators.

Goal: Build and validate a branching math DAG artifact that demonstrates output variants, edges, and observable execution paths.

This guide walks through the process of constructing a Directed Acyclic Graph (DAG) that demonstrates conditional logic using standard Nexus math tools. We will build the math_branching.json DAG step-by-step, then use entry groups to validate its runtime paths.

Prerequisites: complete the setup guide, then inspect each Tool FQN in your target deployment before publishing.

The Tool FQNs and schemas in this page are placeholders only. Replace every <provider-...> value with the exact output of nexus tool inspect --tool-fqn <fqn> from the target deployment, or with a provider-reviewed MetaSchema record. The illustrative port and variant labels (a, b, ok, lt, gt, eq, and result) are placeholders too. Do not infer a namespace, FQN, port, output variant, or scalar type from this algorithm or from a Tool Actions page; if exact inspection evidence is unavailable, stop before authoring or publishing the DAG.

The goal is to build a DAG that:

  1. Takes a single number a as input.

  2. Adds -3 to a.

  3. Compares the result to 0.

  4. Based on the comparison:

    • If the result is less than 0, multiply it by -3.

    • If the result is greater than 0, multiply it by 7.

    • If the result is equal to 0, add 1.

  5. Outputs the final calculated number.

DAG Overview

Before diving into the JSON, let's visualize the workflow using the phase diagrams below:

Apply defaults and compare the math input
Phase 1: Apply defaults and compare the math input. Keyed facts: User input a enters add_input_and_default; the add Tool remains the provider-reviewed <provider-add-tool-fqn> placeholder; fixed defaults are b = -3 and b = 0; the comparison Tool keeps its provider-reviewed FQN.
Route lt, gt, and eq branches to exact Tools
Phase 2: Route exact provider-reviewed math branches. Keyed facts: guards are lt (a < 0), gt (a > 0), and eq (a == 0); comparison <provider-compare-tool-fqn> and branch <provider-negative-tool-fqn>, <provider-positive-tool-fqn>, and <provider-zero-tool-fqn> placeholders; defaults are b = -3, b = 7, and b = 1; each branch returns its own final result.

This diagram shows the flow of data, starting from the user input, through the addition and comparison steps, branching based on the comparison result, and finally reaching one of the possible calculation end-points. The constant default values are shown directly connected to each step that requires them.

Core DAG Components Recap

As detailed in the DAG Construction Guide, Nexus DAGs are defined in JSON and primarily consist of:

  • vertices: Define all processing steps (Tools) within the DAG.

  • edges: Define the data flow connections between vertices, linking output ports (or better yet, output variants) to input ports.

  • default_values: Provide static or pre-configured inputs to vertices.

  • entry_groups (Optional): Define named starting configurations. If omitted, entry points are determined implicitly.

Understanding the Math Tools

This page does not claim that a particular math namespace, FQN, schema, or verifier is registered. The labels in the figure describe the intended roles only. For each placeholder, inspect the target Tool with nexus tool inspect --tool-fqn <fqn> and copy the exact MetaSchema input ports, output variants, output ports, and value types into the DAG. If the provider supplies a reviewed schema record instead, retain that record with the source revision and deployment identifier. The Tool Actions SDK reference explains inspection surfaces; it is not evidence that these example Tools exist.

Step-by-Step Construction

Let's build the math_branching.json file section by section.

The intermediate jsonc snippets are illustrative sections with comments and omitted siblings. Use the strict complete json block under Putting It All Together when saving or validating the DAG.

1. Define Vertices (vertices list)

First, we define all the nodes (steps) in our graph. Each vertex needs a unique name and specifies the tool_fqn it will execute.

  • We define five vertices, each corresponding to a step in our desired workflow.

  • add_input_and_default explicitly lists a in entry_ports. This signifies that if a isn't provided by an incoming edge or a default value, it must be provided externally when the DAG starts (making it an entry port in the default entry scenario).

2. Define Edges (edges list)

Next, we connect the vertices to define the data flow and branching logic.

  • The first edge connects the result of add_input_and_default to the a input of is_negative.

  • The next three edges implement the branching logic. They all originate from is_negative but use different output_variants (lt, gt, eq) corresponding to the comparison result. Each connects the a output of the comparison (which holds the number being compared) to the a input of the appropriate downstream math operation.

3. Set Default Values (default_values list)

We provide the constant values needed for the operations.

  • Each entry specifies the vertex and input_port to receive the value.

  • "one" declares one Nexus value, and "kind": "data" embeds the JSON data payload directly in the DAG definition.

4. Specify outputs (outputs list)

In order to access the final result of the DAG, we need to define outputs for the vertices that do not have outgoing edges. In this case, all our math operations have an output port named result, so we can define them as follows:

5. Entry Points (Implicit Default)

Since we haven't defined an entry_groups section, Nexus uses the default entry mechanism, i.e. _default_group. It identifies vertices that have entry ports specified.

In our case:

  • add_input_and_default has entry port a.

  • a is not the target of any edge.

  • a does not have a default value.

  • Therefore, add_input_and_default becomes the sole entry point, and its a port becomes the entry port. The user must provide a value for a when executing the DAG.

Putting It All Together

Combining these sections gives us the complete math_branching.json:

This is a schema-shaped template, not a deployment-ready artifact. Before saving or validating it, replace every provider FQN and every illustrative port or variant label with the exact inspected MetaSchema values. The placeholder strings are deliberately not evidence of a live Tool registration.

Complete DAG Definition

Validation and Execution with the CLI

After constructing the branching math DAG, use entry groups for nexus dag validate/publish, nexus task schedule, and nexus execution inspect examples.

The quickstart provides step-by-step instructions for:

  • Validating the DAG structure

  • Publishing the DAG to make it executable

  • Executing the DAG with different input values to test all three branches

  • Understanding the results of each execution path

Summary

This guide demonstrated how to construct a Nexus DAG (math_branching.json) involving conditional logic:

  • Defined multiple vertices using standard math tools.

  • Used edges with specific output_variants (lt, gt, eq) from the comparison tool (cmp@1) to create branching paths.

  • Utilized default_values to provide constant operands for the math operations.

  • Relied on the default entry mechanism to define the DAG's starting point and required input.

This example showcases how to combine simple tools and DAG structure definitions to create workflows with non-linear, conditional execution paths. Refer to the DAG Construction Guide for more advanced features and rules.

Up Next

Want to extend this example? Follow the next part of the guide to see how we can add another entry point to the DAG and manage this through entry groups.

Last updated