dag explain

Display the structure of a pipeline — its nodes, edges, and provider dependencies — in a human-readable or machine-readable format. Optionally append LLM-generated improvement suggestions with --suggest.

Synopsis

bash

dag explain <workflow.dag.json> [--suggest] [--format pretty|json|github-comment]

Basic Usage

Pass a .dag.json file to print a visual summary of the pipeline structure.

bash

dag explain translate-pipeline.dag.json

text

Pipeline: translate-pipeline
─────────────────────────────────────────
 input
   └─▶ llm-text-anthropic  (model: claude-3-5-haiku-20241022)
         └─▶ text-output

Nodes: 3   Edges: 2   Provider nodes: 1
─────────────────────────────────────────

Improvement Suggestions

Add --suggest to ask an LLM to review the pipeline and propose improvements. The suggestions are appended below the structure diagram.

bash

dag explain translate-pipeline.dag.json --suggest

text

Pipeline: translate-pipeline
─────────────────────────────────────────
 input
   └─▶ llm-text-anthropic  (model: claude-3-5-haiku-20241022)
         └─▶ text-output

Nodes: 3   Edges: 2   Provider nodes: 1
─────────────────────────────────────────

Suggestions (via LLM):
  1. Add a text-template node between input and llm-text-anthropic to
     inject a system prompt that enforces the target language.
  2. Consider adding an error-boundary node after text-output to catch
     provider timeouts in production use.

JSON Output

Use --format json for machine-readable output suitable for scripting or CI pipelines.

bash

dag explain translate-pipeline.dag.json --format json

json

{
  "dagId": "translate-pipeline",
  "nodes": [
    { "id": "input",               "type": "input" },
    { "id": "llm-text-anthropic",  "type": "llm-text-anthropic", "config": { "model": "claude-3-5-haiku-20241022" } },
    { "id": "text-output",         "type": "text-output" }
  ],
  "edges": [
    { "source": "input",              "target": "llm-text-anthropic" },
    { "source": "llm-text-anthropic", "target": "text-output" }
  ]
}

GitHub Comment Format

Use --format github-comment to generate Markdown output that renders correctly when posted as a pull request comment.

bash

dag explain translate-pipeline.dag.json --format github-comment --suggest \
  | gh pr comment 42 --body-file -

Flags

Flag	Description
--suggest	Append LLM-generated improvement suggestions to the output. Requires ANTHROPIC_API_KEY.
--format <mode>	Output format: pretty (default, colour terminal output), json (machine-readable), or github-comment (Markdown suitable for PR comments).