Visualization

Workflow ships three rendering helpers (since 0.9.16):

The graph IS your documentation. Let the framework render it.

to_mermaid()

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

Returns a Mermaid flowchart TD source string.

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:

```mermaid
flowchart TD
    START([START]) --> classify
    classify -->|billing| billing
    classify -->|tech| tech
    classify -.-> tech
    billing --> END([END])
    tech --> END
```

Notation:

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

Paste the output into:

• A GitHub-flavoured README.md. Mermaid renders inline 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 Mrecord shape (rounded box).
• Regular nodes use the default box shape.
• Edges carry label= for router branches; defaults are 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 / VS Code Notebooks / JupyterLab pick up the Markdown representation automatically. Just type the variable name into a cell:

>>> wf

The cell renders the Mermaid flowchart inline. No imports, no extra calls, _repr_markdown_ returns a ```mermaid fenced code block which the notebook frontend renders.

In code cells, this means:

# Cell 1 — build
wf = Workflow.route(classify, {...})
 
# Cell 2 — type wf, see the diagram
wf

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

A common pattern: keep the rendered diagram in your README in sync with code by regenerating 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) and the README’s diagram never drifts from the code.

When to use each