# Dippin

> A domain-specific language and toolchain for authoring AI pipeline workflows. Replaces Graphviz DOT as the authoring format with first-class syntax for prompts, tools, conditions, parallel execution, and subgraph composition.

Dippin files use the `.dip` extension and define directed graphs of agent steps, human gates, tool calls, and control-flow constructs. The `dippin` CLI parses, validates, lints, formats, exports, simulates, and analyzes these workflows.

## Documentation

- [Analysis Tools](https://dippin.org/analysis.html): Cost estimation, health reports, edge coverage, dead branch detection, semantic diff, and optimization for AI pipelines.
- [Architecture](https://dippin.org/architecture.html): How the Dippin toolchain is organized: IR-centric design, package dependencies, and the parser-to-execution pipeline.
- [Changelog](https://dippin.org/changelog.html): Version history and release notes for dippin-lang.
- [CLI Reference](https://dippin.org/cli.html): Complete command reference for the Dippin toolchain: parse, validate, lint, format, simulate, cost, test, and 15 more commands.
- [Editor Setup](https://dippin.org/editors.html): Set up syntax highlighting, LSP diagnostics, hover docs, and go-to-definition for .dip files in VS Code, Neovim, and more.
- [Language Reference](https://dippin.org/language.html): Full syntax reference for .dip workflow files: nodes, edges, conditions, multiline prompts, parallel execution, and stylesheets.
- [Playground](https://dippin.org/playground.html): Try Dippin in your browser. Write, lint, parse, and format workflows live.
- [Scenario Testing](https://dippin.org/testing.html): Write deterministic tests for AI pipelines with .test.json files. Inject context, assert on paths, check edge coverage.
- [Validation & Linting](https://dippin.org/validation.html): 39 diagnostic checks for AI pipeline workflows. 9 structural errors and 30 semantic warnings catch bugs before runtime.

- [Conditional Edges: Routing Pipelines with when](https://dippin.org/blog/conditional-edges.html): Build branching AI pipelines that route based on LLM output. Learn Dippin's condition syntax, operators, and exhaustive detection.
- [Cost Estimation: Know Before You Run](https://dippin.org/blog/cost-estimation.html): Estimate per-run pipeline costs before spending real money on LLM calls. Use dippin cost and dippin optimize to find savings.
- [Multi-line Prompts Without Escaping](https://dippin.org/blog/multi-line-prompts.html): DOT's escaped strings are unreadable. Dippin's indentation-based blocks let you write prompts with markdown, JSON, and code blocks — no escaping required.
- [CI Integration: Lint, Test, Format](https://dippin.org/blog/ci-integration.html): Set up GitHub Actions to validate, lint, test, and format-check your Dippin workflow files on every push and pull request.
- [Editor Setup: LSP, VS Code, and Tree-sitter](https://dippin.org/blog/editor-setup.html): Set up real-time Dippin diagnostics, hover docs, and syntax highlighting in VS Code, Neovim, Helix, or any editor with LSP support.
- [Getting Started with Dippin](https://dippin.org/blog/getting-started.html): Install Dippin, write your first AI pipeline workflow, and validate it in under 10 minutes. A step-by-step guide from zero to a working .dip file.
- [Migrating from DOT to Dippin](https://dippin.org/blog/migrating-from-dot.html): Convert Graphviz DOT pipeline files to Dippin with automated migration and structural parity verification. Step-by-step with real examples.
- [Scenario Testing with .test.json](https://dippin.org/blog/scenario-testing.html): Write deterministic tests for non-deterministic AI pipelines. Inject context values, assert on execution paths, and measure edge coverage.

## Claude Code Skill

- [dippin-lang skill](https://dippin.org/skill.md): Instruction file for Claude Code to author, validate, and debug .dip workflow files. Add to CLAUDE.md: `@https://dippin.org/skill.md`

## Source

- [GitHub Repository](https://github.com/2389-research/dippin-lang)

## Quick Example

```
workflow AskAndDo
  goal: "Ask a question and act on it."
  start: Ask
  exit: Done

  defaults
    model: claude-sonnet-4-6
    provider: anthropic

  human Ask
    mode: freeform

  agent Done
    prompt:
      Complete the task based on the user's input.

  edges
    Ask -> Done
```

## Key Concepts

- **Workflow**: A directed graph of nodes and edges. One per .dip file. Has a name, goal, start node, and exit node.
- **Nodes**: Steps in the pipeline. Agent nodes call LLMs, human nodes gate on user input, tool nodes run shell commands, parallel/fan_in manage concurrency, subgraph nodes embed other workflows.
- **Edges**: Connections between nodes with optional conditions (`when ctx.outcome = success`), labels, weights, and restart flags.
- **Defaults**: Workflow-wide settings (model, provider, retry policy, fidelity) inherited by all nodes unless overridden.
- **Subgraph composition**: Embed reusable workflows via `subgraph` nodes with `ref:` pointing to another .dip file. The `flatten` package resolves refs into a single flat workflow for export.
- **Conditions**: Edge conditions use `ctx.<field> = <value>` syntax with operators: `=`, `!=`, `contains`, `not contains`. Exhaustive condition pairs (success/fail, contains/not-contains) are detected automatically.

## Installation

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

## Supported Providers

Anthropic, OpenAI, Google/Gemini, DeepSeek, xAI/Grok, Mistral, Cohere. Model names and pricing are validated against official provider documentation.