Graph

dagpipe.graph

Summary

Defines DAG structure connecting nodes.

A Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by an Engine.

---

Responsibilities

• Multiple roots, branching, and merging support.
• Deterministic traversal based on topology.
• Graph is mutable during construction but treated as immutable at runtime.

Classes

Graph

Graph()

Directed Acyclic Graph defining execution topology of Node objects.

Notes

Responsibilities:

- Stores node connectivity and validates that the topology remains acyclic.
- Structure determines how `State` flows between nodes during execution.

Guarantees:

- Topology is acyclic. Node relationships remain consistent.
- Thread-safe for concurrent reads after construction.

Create an empty Graph.

Initializes node registry and edge mappings.

Functions

__repr__

__repr__() -> str

Return debug representation.

Returns

str

add_edge

add_edge(src: Node, dst: Node) -> None

Add a directed edge from src to dst.

Parameters:

Name	Type	Description	Default
src	Node	Source node.	required
dst	Node	Destination node.	required

Raises:

Type	Description
TypeError	If src or dst is not a Node.
ValueError	If the edge would create a cycle or if src and dst are common.

Notes

• Validates node types.
• Prevents cycles.
• Registers nodes if not present.
• Updates parent and child mappings.

add_root

add_root(node: Node) -> None

Add a root node with no parents.

Parameters:

Name	Type	Description	Default
node	Node	Node to add as a root.	required

Raises:

Type	Description
TypeError	If node is not a Node instance.

children

children(node: Node) -> Tuple[Node, ...]

Return child nodes of a node.

Parameters:

Name	Type	Description	Default
node	Node	Node to query.	required

Returns:

Type	Description
Tuple[Node, ...]	Tuple[Node, ...]: Outgoing neighbors.

nodes

nodes() -> Tuple[Node, ...]

Return all nodes in the graph.

Returns:

Type	Description
Tuple[Node, ...]	Tuple[Node, ...]: All registered nodes.

parents

parents(node: Node) -> Tuple[Node, ...]

Return parent nodes of a node.

Parameters:

Name	Type	Description	Default
node	Node	Node to query.	required

Returns:

Type	Description
Tuple[Node, ...]	Tuple[Node, ...]: Incoming neighbors.

roots

roots() -> Tuple[Node, ...]

Return root nodes (nodes with no incoming edges).

Returns:

Type	Description
Tuple[Node, ...]	Tuple[Node, ...]: Entry point nodes.