Graph

junjo.Graph

Kind: Class

SDK version: 0.64.0

Documentation channel: Next source preview

Signature

Graph(source: Node | _NestableWorkflow, sinks: list[Node | _NestableWorkflow], edges: list[Edge])

View source

Represents a directed graph of nodes and edges, defining the structure and flow of a workflow.

The Graph class is a fundamental component in Junjo, responsible for encapsulating the relationships between different processing units (Nodes or Subflows) and the conditions under which transitions between them occur.

It holds references to the entry point (source) and explicit terminal nodes (sinks) of the graph, as well as a list of all edges that connect the nodes.

Graph definitions are immutable after construction. Junjo stores the source, sinks, edges, edge endpoints, edge conditions, and concurrent child membership as read-only graph-shape metadata so the cached compiled snapshot cannot silently drift away from the graph definition.

Parameters

Name	Type	Description	Default
source	Node | _NestableWorkflow	The starting node or subflow of the graph. Execution of the workflow begins here.
sinks	list[Node | _NestableWorkflow]	The explicit terminal nodes or subflows of the graph. Execution completes successfully only when one of these executables is reached.
edges	list[Edge]	A list of Edge instances that define the connections and transition logic between nodes in the graph.

Members

source

source: Node | _NestableWorkflow

View source

Return the immutable source executable for this graph definition.

sinks

sinks: tuple[Node | _NestableWorkflow, ...]

View source

Return the immutable terminal executables for this graph definition.

edges

edges: tuple[Edge, ...]

View source

Return the immutable ordered edge set for this graph definition.

compile

compile() -> CompiledGraph

View source

Compile this graph into one canonical structural snapshot.

The compiled snapshot is cached per Graph instance and becomes the structural source of truth for validation, traversal, and serialization.

Compiling a graph does not execute node logic or evaluate edge conditions. It only normalizes the graph structure into a single, immutable representation.

Returns

• CompiledGraph: The compiled structural snapshot for this graph instance.

Raises

Exception	Description
GraphCompilationError	If Junjo cannot build a consistent structural representation of the graph.

validate

validate() -> None

View source

Validate the graph’s structural shape and declared terminal nodes.

This validation pass is intentionally structural. It does not execute node logic or edge conditions. Instead, it checks the graph topology using the declared edges, source, and sinks.

Validation currently enforces:

• every declared sink is reachable from the source
• declared sinks do not have outgoing edges
• every reachable non-sink node has at least one outgoing edge
• nested subflow graphs validate recursively

Cycles are allowed as long as the graph still has a reachable sink and no reachable non-sink dead ends.

Raises

Exception	Description
GraphValidationError	If the graph shape violates Junjo’s current validation rules.

get_next_node

get_next_node(store: BaseStore, current_node: Node | _NestableWorkflow) -> Node | _NestableWorkflow

View source

Retrieve the next node or subflow in the graph for the given current executable.

This method checks the edges connected to the current executable and resolves the next executable based on the conditions defined in those edges.

Junjo uses ordered first-match traversal semantics:

• outgoing edges are considered in the order they were declared
• the first edge whose condition resolves to a next executable wins
• later edges are not evaluated once a match is found

Workflow execution checks declared sinks before calling this method. Direct callers should do the same. If this method is called for an executable with no resolving outgoing edge, including a declared sink, it raises GraphValidationError.

Parameters

Name	Type	Description	Default
store	BaseStore	The store instance to use for resolving the next executable.
current_node	Node | _NestableWorkflow	The current node or subflow in the graph.

Returns

• Node | _NestableWorkflow: The next node or subflow in the graph.

serialize_to_json_string

serialize_to_json_string() -> str

View source

Convert the graph to a neutral serialized JSON string.

The serialized representation treats RunConcurrent instances as subgraphs and includes nested subflow graphs as well.

The serialized payload includes explicit runtime and structural identities for the graph, nodes, and edges. Nested subflow nodes also include their child graph structural id plus explicit source and sink runtime and structural ids.

Returns

• str: A JSON string containing the graph structure.

Raises

Exception	Description
GraphSerializationError	If the graph payload cannot be converted into JSON.

to_mermaid

to_mermaid() -> str

View source

Render the graph as Mermaid flowchart syntax.

Mermaid rendering consumes the compiled graph snapshot directly instead of routing through serialized JSON. The returned string contains one flowchart with:

• the overview graph
• concurrent executables rendered as Mermaid subgraphs
• disconnected detail subgraphs for each subflow

Node, concurrent, and subflow identifiers are structural, which keeps Mermaid output stable across repeated fresh graph builds with the same topology.

Returns

• str: Mermaid flowchart syntax for the compiled graph.

to_dot_notation

to_dot_notation() -> str

View source

Render the Junjo graph as a main overview digraph plus one additional digraph for each subflow.

DOT rendering consumes the compiled graph snapshot directly instead of routing through serialized JSON. Rendered node and subflow identifiers are structural, which keeps DOT output stable across repeated fresh graph builds with the same topology.

export_graphviz_assets

export_graphviz_assets(out_dir: str | Path = 'graphviz_out', fmt: str = 'svg', dot_cmd: str = 'dot', open_html: bool = False, clean: bool = True) -> dict[str, Path]

View source

Render Graphviz assets for the graph and its nested subflows.

This method renders every digraph produced by to_dot_notation and builds a gallery HTML page whose headings use the human labels (for example, SampleSubflow) instead of raw digraph identifiers.

Graphviz export renders directly from the compiled graph snapshot. It does not depend on the serialized graph JSON payload, which keeps the rendering path aligned with the same canonical structure used for validation and traversal.

The output directory contains:

• one .dot file for the overview graph and each nested subflow
• one rendered image file per digraph, using the configured fmt
• index.html, a simple gallery page that references the rendered image files

Parameters

Name	Type	Description	Default
out_dir	str | Path	Directory where generated .dot files, image files, and index.html should be written. Defaults to "graphviz_out".	'graphviz_out'
fmt	str	Graphviz output format to pass to dot via -T. Defaults to "svg".	'svg'
dot_cmd	str	Graphviz command to execute. Defaults to "dot".	'dot'
open_html	bool	When True, open the generated index.html in the default browser after assets are written. Defaults to False.	False
clean	bool	When True, remove existing .dot files and files matching the selected fmt from out_dir before writing new assets. Defaults to True. index.html is overwritten on every run.	True

Returns

• dict[str, Path]: An ordered mapping of digraph name to rendered file path, in encounter order.

Raises

Exception	Description
GraphRenderError	If the Graphviz command is missing or fails while rendering an asset.