Graph

dagpipe.graph

Defines DAG structure connecting Nodes.

---

Summary

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

Notes

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 Nodes.

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 directed edge from src to dst.

Parameters

src : Node required: True source node

Node

required: True destination node

---

Raises

TypeError if src or dst is not a Node

ValueError if edge would create a cycle

ValueError if src and dst are the same node

---

Behavior

• 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.