Visualization

A Workflow can draw its own graph, so you can check a flow’s shape at a glance or keep a diagram in your docs that always matches the code. There are three ways to render it:

The diagram is generated from the workflow object itself, so it can’t drift out of date.

to_mermaid()

def to_mermaid(self) -> str: ...

Returns Mermaid flowchart TD source as a string, without the surrounding ```mermaid fence.

from loomflow import Workflow, START, END
 
async def classify(text): ...
async def billing(text): ...
async def tech(text): ...
 
wf = Workflow("triage")
wf.add_node("classify", classify)
wf.add_node("billing", billing)
wf.add_node("tech", tech)
 
wf.add_edge(START, "classify")
wf.add_router(
    "classify", lambda r: r.lower(),
    {"billing": "billing", "tech": "tech"},
    default="tech",
)
wf.add_edge("billing", END)
wf.add_edge("tech", END)
 
print(wf.to_mermaid())

Output:

flowchart TD
    n_classify["classify"]
    n_billing["billing"]
    n_tech["tech"]
    START([START]) --> n_classify
    n_classify -->|billing| n_billing
    n_classify -->|tech| n_tech
    n_classify -.->|default| n_tech
    n_billing --> END([END])
    n_tech --> END([END])

Rendered:

Notation:

• Solid arrows (-->) are unconditional edges.
• Labelled solid arrows (-->|key|) are router branches; the label is the routing key.
• Dotted arrows labelled default (-.->|default|) are router defaults.
• START and END render as stadium-shaped nodes (rounded ends).

Paste the output into:

• A GitHub-flavoured README.md, inside a ```mermaid fence. GitHub renders it natively.
• mermaid.live , for PNG / SVG export.
• A Notion / GitLab page that supports Mermaid.

to_dot()

def to_dot(self) -> str: ...

Same picture, emitted in Graphviz DOT for users who prefer the Graphviz toolchain:

from pathlib import Path
 
Path("graph.dot").write_text(wf.to_dot())

dot -Tpng graph.dot -o graph.png
dot -Tsvg graph.dot -o graph.svg

DOT preserves shape distinctions:

• START / END use the oval shape.
• Regular nodes use shape=box, style=rounded.
• Edges carry label= for router branches; defaults are labelled default and drawn style=dashed.

Mermaid is the recommended path since it renders without any tool install. Reach for DOT only when you already have Graphviz wired into your build.

_repr_markdown_: inline notebook rendering

Jupyter, JupyterLab and VS Code notebooks pick up the Markdown representation automatically. End a cell with the workflow variable:

# Cell 1: build
wf = Workflow.route(classify, {"billing": billing, "tech": tech})
 
# Cell 2: show the variable, see the diagram
wf

The cell renders the Mermaid flowchart inline, with no imports or extra calls: _repr_markdown_ returns the to_mermaid() text wrapped in a ```mermaid fence, and the notebook frontend renders it.

VS Code’s notebook renderer also supports Mermaid by default (via the built-in Markdown preview). JupyterLab needs the jupyterlab-mermaid extension for inline rendering; vanilla Jupyter shows the raw Markdown.

Auto-update READMEs from CI

To keep the diagram in your README in sync with the code, regenerate it on every release:

# scripts/render_workflow.py
from pathlib import Path
from app.workflows import support_flow      # your Workflow
 
readme = Path("README.md").read_text()
start = readme.index("<!-- workflow-start -->")
end   = readme.index("<!-- workflow-end -->")
 
block = (
    "<!-- workflow-start -->\n"
    f"```mermaid\n{support_flow.to_mermaid()}\n```\n"
    "<!-- workflow-end -->"
)
Path("README.md").write_text(readme[:start] + block + readme[end + len("<!-- workflow-end -->"):])

Add it to your release script (or a pre-commit hook) to keep the README’s diagram in sync with the code.

When to use each