Dippin

A language and toolchain for authoring AI pipeline workflows.

Dippin is a domain-specific language that replaces Graphviz DOT as the authoring format for Tracker pipelines. It gives prompts, shell scripts, model configuration, and branching logic first-class syntax — things that DOT forces into escaped string attributes.

Why Not Just DOT?

DOT is a great graph language. Dippin doesn't replace DOT for visualization — it replaces DOT for authoring. The two coexist:

graph LR
    A["Author in Dippin"] --> B["Execute with Tracker"]
    A --> C["Export to DOT for visualization<br>(dippin export-dot)"]
    A --> D["Render with Graphviz<br>(dot -Tpng)"]
    E["Legacy DOT files"] --> F["Migrate to Dippin<br>(dippin migrate)"]
    E --> G["Verify parity<br>(dippin validate-migration)"]

What DOT does well — and Dippin preserves:

• Graph-native syntax where nodes and edges are first-class
• Graphviz rendering for instant visualization
• A familiar, widely-tooled ecosystem

What DOT does badly — and Dippin fixes:

DOT is still the visualization target. dippin export-dot generates DOT for Graphviz rendering. The migration tool (dippin migrate) converts existing DOT pipelines to Dippin with structural parity verification.

Quick Start

Prerequisites

Go 1.21+ is required.

Install

go install github.com/2389-research/dippin-lang/cmd/dippin@latest

Or build from source:

git clone https://github.com/2389-research/dippin-lang.git
cd dippin-lang
go install ./cmd/dippin/

Verify:

dippin help

Your First Workflow

Create hello.dip:

workflow Hello
  goal: "Ask the user a question and respond"
  start: Ask
  exit: Respond

  human Ask
    mode: freeform

  agent Respond
    model: claude-sonnet-4-6
    provider: anthropic
    prompt:
      The user said something. Respond helpfully.

  edges
    Ask -> Respond

Validate it:

$ dippin validate hello.dip
validation passed

$ dippin lint hello.dip
# Clean — no warnings

$ dippin export-dot hello.dip | dot -Tpng -o hello.png
# Generates a Graphviz visualization

Migrate an Existing DOT Pipeline

# Convert DOT to Dippin
dippin migrate --output pipeline.dip pipeline.dot

# Verify structural equivalence
dippin validate-migration pipeline.dot pipeline.dip

# Check the result
dippin lint pipeline.dip

Commands

Authoring

Analysis

Editor & Tooling

Exit codes: 0 = ok, 1 = errors found, 2 = usage error.

Machine-readable output: Add --format json to any command for JSON diagnostics on stderr.

CI usage: dippin fmt --check exits 1 if the file isn't canonically formatted. dippin lint exits 0 even with warnings (only errors cause exit 1).

See docs/cli.md for full command reference, and docs/analysis.md for analysis command output formats.

Language Reference

The full grammar is specified in docs/GRAMMAR.ebnf. Here's the practical reference.

Workflow Structure

Every .dip file contains one workflow:

workflow <Name>
  goal: "What this pipeline does"
  start: <EntryNodeID>
  exit: <ExitNodeID>

  defaults             # Optional graph-level defaults
    model: claude-sonnet-4-6
    provider: anthropic
    max_retries: 3
    fidelity: summary:medium

  # Node declarations (any order)
  agent <ID>
    ...
  tool <ID>
    ...
  human <ID>
    ...

  # Edge declarations
  edges
    A -> B
    B -> C when ctx.outcome == "success"

Node Types

agent — calls an LLM:

  agent Analyze
    label: "Deep Analysis"
    model: claude-opus-4-6
    provider: anthropic
    reasoning_effort: high
    fidelity: full:high
    goal_gate: true         # Pipeline fails if this node fails
    auto_status: true       # Parse STATUS: success/fail from response
    max_turns: 10
    prompt:
      Multi-line prompt. No escaping.
      Write markdown, code, anything.
      Reference context: ${ctx.last_response}

tool — runs a shell command:

  tool Build
    label: "Build and Test"
    timeout: 60s
    command:
      #!/bin/sh
      set -eu
      go build ./...
      go test ./... 2>&1
      printf 'done'

human — waits for user input:

  human Approve
    label: "Human Approval"
    mode: choice          # or "freeform"
    default: approve

parallel / fan_in — concurrent execution:

  parallel ReviewFan -> ReviewA, ReviewB, ReviewC
  fan_in ReviewJoin <- ReviewA, ReviewB, ReviewC

subgraph — embedded sub-workflow:

  subgraph Nested
    ref: other_workflow.dip

Edges and Conditions

  edges
    A -> B                                          # Unconditional
    A -> C when ctx.outcome == "fail"               # Conditional
    A -> D when ctx.outcome == "success" and ctx.retries < 3
    A -> B weight: 10                               # Priority weight
    A -> B label: "happy path"                      # Display label
    Retry -> Start restart: true                    # Loop restart

Condition operators: =, ==, !=, contains, not contains, startswith, endswith, in, and, or, not.

Context variables use dotted namespaces: ctx.outcome, ctx.last_response, graph.goal.

Multiline Blocks

Any field ending with : followed by a newline starts a raw text block. The indented content below is preserved verbatim — no tokenization, no escaping:

  agent Writer
    prompt:
      # This markdown header is prompt content, not a Dippin comment
      Write code like this:
      ```python
      print("hello -> world")  # arrows and colons are fine
      ```

  tool Runner
    command:
      #!/bin/bash
      set -euo pipefail
      if [ -f go.mod ]; then
        go test ./... 2>&1 || { echo "failed"; exit 1; }
      fi

Shell scripts with if/fi, here-docs, case/esac, process substitution, and any other construct work without modification.

Comments

  # Full-line comment
  agent Foo  # Inline comment (must be preceded by whitespace)

Comments are not stripped inside multiline blocks — a # inside a prompt or command is literal content.

All Node Fields

Diagnostics

Dippin diagnostics follow the Rust compiler convention: each has a code, severity, source location, explanation, and suggested fix.

$ dippin validate broken.dip
error[DIP003]: unknown node reference "InterpretX" in edge
  --> broken.dip:45:5
  = help: did you mean "Interpret"? (declared at line 12)

Errors (DIP001–DIP009)

Warnings (DIP101–DIP133)

Simulation

Dry-run a workflow to see the execution path without calling LLMs or running commands:

$ dippin simulate examples/ask_and_execute.dip
{"event":"pipeline_start","workflow":"AskAndExecute",...}
{"event":"node_enter","node":"Start","kind":"agent",...}
{"event":"node_exit","node":"Start","status":"success",...}
{"event":"edge_traverse","from":"Start","to":"SetupWorkspace",...}
...
{"event":"pipeline_end","status":"success","nodes_visited":12,...}

Explore failure paths:

dippin simulate workflow.dip --scenario outcome=fail

Enumerate all possible paths through the graph:

dippin simulate workflow.dip --all-paths

Editor Support

LSP Server

dippin lsp starts a Language Server Protocol server on stdio, providing:

• Real-time diagnostics (parse errors + lint warnings on every keystroke)
• Hover tooltips (node kind, model, provider, prompt preview)
• Go-to-definition (jump from edge node references to node declarations)
• Autocomplete (node IDs in edges, field names, keywords)
• Document symbols (outline of nodes and edges)

Works with any LSP-compatible editor. See docs/editor-setup.md for configuration.

VS Code Extension

A dedicated extension is available in editors/vscode/ providing:

• Syntax highlighting for .dip files
• Comment toggling (Ctrl+/)
• Indentation-based folding
• Auto-indent after :

See the extension README for installation.

Examples

The examples/ directory contains 17 workflows:

Production patterns (migrated from Tracker, with original .dot files):

Stress tests (parser and validator edge cases):

Architecture

graph LR
    DIP[".dip source"] --> Parser
    DOT_FILE[".dot file"] --> Migrator
    Parser --> IR["IR (Workflow)"]
    Migrator --> IR
    IR --> Validator["Validator<br>(DIP001–009)"]
    IR --> Linter["Linter<br>(DIP101–133)"]
    IR --> Formatter["Formatter<br>(canonical .dip)"]
    IR --> DOT["DOT Exporter<br>(visualization)"]
    IR --> Sim["Simulator<br>(dry-run)"]
    IR --> Cost["Cost / Coverage<br>/ Doctor / Optimize"]
    IR --> Diff["Diff"]
    IR --> Unused["Unused / Graph"]
    IR --> Test["Test Runner"]
    IR --> LSP["LSP Server"]

Everything flows through ir.Workflow — the canonical intermediate representation. Packages never reach into each other's internals.

| cmd/wasm/ | WebAssembly entry point for the browser playground |

Zero external dependencies for core packages. The LSP server uses go.lsp.dev libraries. The watch command uses fsnotify.

See docs/architecture.md for the full architecture guide.

Development

just setup-hooks   # install pre-commit hook (required)
just check         # full check suite: build, vet, fmt, test, complexity, examples
just complexity    # complexity checks only
just test          # run all tests
just fmt           # format all Go files

Code Quality Gates

The pre-commit hook enforces:

Test functions (_test.go) are excluded from complexity enforcement.

See QUICK_REFERENCE.md for refactoring patterns when a function exceeds the threshold.

License

MIT