Skip to content

# 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

    1

    Graph()

Directed Acyclic Graph defining execution topology of `Node` objects.

Notes

Responsibilities:

    1
    2

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

Guarantees:

    1
    2

    - 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__

    1

    __repr__() -> str

Return debug representation.

###### Returns

str

###### `` add_edge

    1

    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

    1

    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

    1

    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

    1

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

Return all nodes in the graph.

Returns:

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

###### `` parents

    1

    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

    1

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

Return root nodes (nodes with no incoming edges).

Returns:

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