Skip to content

# Engine

## `` dagpipe.engine

### Summary

Execution engine responsible for running pipelines and graphs.

The `Engine` executes `Node` objects and propagates immutable `State` instances through either a linear sequence or a directed acyclic graph (`Graph`). It orchestrates execution order, branching, and state propagation.

### Guarantees

- Deterministic execution and consistent state lineage.
- Orchestrates execution without modifying `Graph`, `Node`, or `State` objects.

### Classes

#### `` Engine

    1

    Engine(nodes_or_graph: Union[Sequence[Node], Graph])

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

    1
    2
    3
    4

    - Accepts either a linear sequence of `Node` objects or a `Graph`
      defining execution topology.
    - Propagates immutable `State` objects through `Node` objects and
      collects terminal states.

Guarantees:

    1
    2
    3
    4
    5

    - Never mutates `State`, `Node`, or `Graph` instances.
    - `State` objects are never modified in place; each branch produces
      independent instances.
    - Execution order is deterministic and follows graph or pipeline topology.
    - Thread-safe for concurrent execution.

Initialize the execution engine.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`nodes_or_graph` | `Sequence[Node] | Graph` | Pipeline definition. May be a linear sequence or a DAG. | required

Raises:

Type | Description
--- | ---
`TypeError` | If input is not a `Sequence[Node]` or `Graph`, or contains invalid node types.

Notes

Responsibilities:

    1
    2

    - Detects execution mode (linear or DAG) and validates node
      types and structure.

##### Attributes

###### `` nodes `property`

    1

    nodes: tuple[Node, ...]

Return nodes managed by this engine.

Returns:

Type | Description
--- | ---
`tuple[Node, ...]` | tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.

##### Functions

###### `` __repr__

    1

    __repr__() -> str

Return the canonical string representation of the object.

Returns:

Name | Type | Description
--- | --- | ---
`str` | `str` | Representation that uniquely identifies the object and its configuration.

###### `` run

    1

    run(root: State) -> List[State]

Execute the pipeline starting from a root `State`.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`root` | `State` | Initial execution state. | required

Returns:

Type | Description
--- | ---
`List[State]` | list[State]: Terminal execution states produced by the pipeline.

Raises:

Type | Description
--- | ---
`TypeError` | If `root` is not a `State` instance.
`RuntimeError` | If the engine execution mode is invalid.

Notes

Responsibilities:

    1
    2

    - Selects execution mode, propagates state through nodes, creates
      new instances for branches, and collects terminal states.