onnx_light.tools.mermaid#

Convert an ONNX model or graph to a Mermaid flowchart diagram.

The resulting string can be embedded directly in Markdown or in a Sphinx page using the mermaid directive:

from onnx_light.tools import to_mermaid

print(to_mermaid(model))

The converter is implemented in pure Python and only depends on the attributes of the standard ONNX message types (ModelProto, GraphProto, NodeProto, ValueInfoProto, TensorProto and TensorShapeProto). It therefore works both with messages built by onnx_light and with messages built by the upstream onnx package.

onnx_light.tools.mermaid.to_mermaid(model_or_graph: Any, *, direction: str = 'TB', include_initializers: bool = True, include_shapes: bool = True, include_attributes: bool = False, include_inplace: bool = False, include_release: bool = False) → str#

Render an ONNX ModelProto or GraphProto as a Mermaid flowchart.

Parameters:

  • model_or_graph – A ModelProto or GraphProto instance. Both onnx_light and onnx messages are accepted.

  • direction – Mermaid flowchart direction; one of "TB", "TD", "BT", "LR" or "RL". Defaults to "TB" (top-to-bottom).

  • include_initializers – When True, initializers are rendered as separate (cylinder) nodes and connected to the consumers they feed. When False, initializer tensors are not shown.

  • include_shapes – When True, tensor type/shape information available in graph inputs, outputs, value_info and initializers is appended to the corresponding node labels.

  • include_attributes – When True, node attribute names are listed inside the operator label.

  • include_inplace – When True, the in-place reuse opportunities recorded in each node’s metadata_props (under the onnx_light.inplace_reuse key) are appended to the operator label, for example inplace: out0=in1(equal).

  • include_release – When True, the post-execution release hints recorded in each node’s metadata_props (under the onnx_light.release_after key) are appended to the operator label, for example release: A, B.

Returns:

The Mermaid source as a single str (newline-separated). The returned text is not wrapped in a fenced code block so the caller can choose between "```mermaid\n...\n`”`` for Markdown and the .. mermaid:: directive for Sphinx.

Raises:

  • TypeError – If model_or_graph is neither a ModelProto nor a GraphProto.

  • ValueError – If direction is not a supported Mermaid flowchart direction.

The example below builds a small Abs chain, runs shape inference and records the in-place reuse opportunities into the graph metadata with onnx_light.onnx_optim.shape_inference.write_inplace_reuse_to_metadata(), then renders the annotated flowchart with include_inplace=True:

        flowchart TB
    t_X(["X<br/>float[3,4]"]):::onnxInput
    n_Abs_0["Abs"]:::onnxOp
    t_X -->|"float[3,4]"| n_Abs_0
    n_Abs_0 --> t_A
    n_Abs_1["Abs<br/>inplace: out0=in0(equal)"]:::onnxOp
    t_A --> n_Abs_1
    n_Abs_1 --> t_B
    n_Abs_2["Abs<br/>inplace: out0=in0(equal)"]:::onnxOp
    t_B --> n_Abs_2
    n_Abs_2 -->|"float[3,4]"| t_Y
    t_Y(["Y<br/>float[3,4]"]):::onnxOutput
    classDef onnxInput fill:#cde4ff,stroke:#3a6ea5,color:#000;
    classDef onnxOutput fill:#ffe1b3,stroke:#a35a00,color:#000;
    classDef onnxInitializer fill:#eeeeee,stroke:#888,color:#000;
    classDef onnxOp fill:#d4ecd4,stroke:#3a8c3a,color:#000;
    classDef onnxTagShape fill:#f4d6ff,stroke:#8744a2,color:#000;
    classDef onnxTagAxes fill:#ffe9a8,stroke:#9e7a00,color:#000;
    classDef onnxTagWeight fill:#e0e0e0,stroke:#666666,color:#000;
    classDef onnxTagAmbiguous fill:#ffd9d9,stroke:#a33a3a,color:#000;
onnx_light.tools.mermaid.to_mermaid_graph(graph: Any, *, direction: str = 'TB', include_initializers: bool = True, include_shapes: bool = True, include_attributes: bool = False, include_inplace: bool = False, include_release: bool = False) → str#

Render a GraphProto as a Mermaid flowchart.

See to_mermaid() for the meaning of every parameter.