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

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

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

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

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

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

Attributes

nodes property

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__

__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

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:

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