Execution engine responsible for running pipelines and graphs.
-
-
Summary
-
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.
-
-
-
- Notes
-
Guarantees:
-
1
-2
- Deterministic execution and consistent state lineage.
-- Orchestrates execution without modifying Graph, Node, or State objects.
-
Execution engine responsible for running pipeline logic.
-
-
-
- Notes
-
Responsibilities:
-
1
-2
- Accepts either a linear sequence of Nodes or a Graph defining execution topology.
-- Propagates immutable State objects through Nodes and collects terminal States.
-
-
Guarantees:
-
1
-2
-3
-4
- 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.
-
Graph describes execution topology only. It does not execute nodes or manage State.
-Execution is handled by Engine.
-
-
-
- Notes
-
Responsibilities:
-
1
-2
-3
- Multiple roots, branching, and merging support.
-- Deterministic traversal based on topology.
-- Graph is mutable during construction but treated as immutable at runtime.
-
Directed acyclic graph execution framework for deterministic state propagation.
-
-
Summary
-
dagpipe executes pipelines composed of nodes connected in a directed acyclic
-graph (DAG). Each node receives an immutable state and optionally produces
-derived states for downstream nodes.
A Node represents a single unit of pipeline execution logic. It consumes one
-State and produces zero, one, or many new States.
-
Nodes are connected using Graph and executed by Engine.
-
-
-
- Notes
-
Design Principles:
-
1
-2
-3
-4
- **Pure:** Must not mutate input state.
-- **Deterministic:** Same input produces same output.
-- **Stateless:** Recommended to be stateless for reuse.
-- **Composable:** Nodes enable branching execution graphs.
-
-
-
-
-
-
-
-
-
-
-
-
Classes
-
-
-
-
-
-
-Node
-
-
-
-
-
-
-
- Bases: ABC
-
-
-
Base class for all dagpipe execution nodes.
-
-
-
Attributes:
-
-
-
-
Name
-
Type
-
Description
-
-
-
-
-
id
-
- str
-
-
-
-
Unique identifier of the node (snake_case dotted format).
-
-
-
-
-
name
-
- str
-
-
-
-
Human-readable display name.
-
-
-
-
-
-
-
-
- Notes
-
Responsibilities:
-
1
-2
-3
- Represents a deterministic unit of execution in the pipeline graph.
-- Consumes one State and produces zero, one, or many derived States.
-- Defines execution logic and enables branching, filtering, and transformation.
-
-
Guarantees:
-
1
- Nodes must never mutate the input State. Instances are singletons per subclass and reused across executions.
-
- Subclasses implement specific resolution behavior. Must not mutate input state. Should use fork() to create child states. May yield zero states to terminate a branch.
-
The State represents a single point in pipeline execution. It contains
-arbitrary data and metadata and is designed to be immutable. Instead of
-modifying an existing state, nodes create new child states via fork().
-
-
-
- Notes
-
Key design principles:
-
1
-2
-3
-4
-5
- **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().
-- **Cheap cloning:** Forking must be efficient since branching may create many states.
-- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.
-- **Domain agnostic:** State contains generic key‑value data and does not assume any schema.
-- **Engine‑friendly:** State contains execution metadata such as depth and history.
-
Immutable hierarchical container with dot-path access.
-
-
-
Attributes:
-
-
-
-
Name
-
Type
-
Description
-
-
-
-
-
_data
-
- Mapping[str, Any]
-
-
-
-
Immutable hierarchical data structure.
-
-
-
-
-
-
-
-
- Notes
-
Responsibilities:
-
1
-2
- Stores execution data used by State. Supports efficient atomic updates without modifying existing instances.
-- Payload instances are fully thread-safe due to immutability.
-
- Represents a complete execution snapshot at a specific point in pipeline traversal. Fundamental unit of execution in dagpipe.
-- Fully thread-safe due to immutability.
-
- This is the only supported mechanism for modifying execution data.
-- Validates payload updates, preserves lineage, increments depth, and appends to history.
-
- Encapsulates engine, state type, and initial payload. Provides a simplified interface for executing configured pipelines.
-- Safe for concurrent execution if underlying Nodes are thread-safe.
-
Execution engine responsible for running pipelines and graphs.
-
-
Summary
-
The Engine executes Node objects and propagates immutable State instances
-through either a linear sequence or a directed acyclic graph (Graph).
+
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.
+
-
- Notes
-
Guarantees:
-
1
-2
- Deterministic execution and consistent state lineage.
-- Orchestrates execution without modifying Graph, Node, or State objects.
-
-
-
@@ -1005,15 +1019,21 @@ It orchestrates execution order, branching, and state propagation.
Notes
Responsibilities:
1
-2
- Accepts either a linear sequence of Nodes or a Graph defining execution topology.
-- Propagates immutable State objects through Nodes and collects terminal States.
+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:
123
-4
- Never mutates State, Node, or Graph instances.
-- State objects are never modified in place; each branch produces independent instances.
+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.
@@ -1035,7 +1055,7 @@ It orchestrates execution order, branching, and state propagation.
A Graph describes execution topology only. It does not execute nodes or manage
+State. Execution is handled by an Engine.
-
Summary
-
Graph describes execution topology only. It does not execute nodes or manage State.
-Execution is handled by Engine.
+
Responsibilities
+
+
Multiple roots, branching, and merging support.
+
Deterministic traversal based on topology.
+
Graph is mutable during construction but treated as immutable at runtime.
+
-
- Notes
-
Responsibilities:
-
1
-2
-3
- Multiple roots, branching, and merging support.
-- Deterministic traversal based on topology.
-- Graph is mutable during construction but treated as immutable at runtime.
-
-
-
@@ -1149,7 +1090,7 @@ Execution is handled by Engine.
-
Directed Acyclic Graph defining execution topology of Nodes.
+
Directed Acyclic Graph defining execution topology of Node objects.
@@ -1157,7 +1098,7 @@ Execution is handled by Engine.
Responsibilities:
12
- Stores node connectivity and validates that the topology remains acyclic.
-- Structure determines how State flows between nodes during execution.
+- Structure determines how `State` flows between nodes during execution.
Guarantees:
1
@@ -1215,35 +1156,94 @@ Execution is handled by Engine.
Directed acyclic graph execution framework for deterministic state propagation.
-
-
Summary
+
Summary
+
Directed acyclic graph execution framework for deterministic state propagation.
dagpipe executes pipelines composed of nodes connected in a directed acyclic
-graph (DAG). Each node receives an immutable state and optionally produces
+graph (DAG). Each node receives an immutable State and optionally produces
derived states for downstream nodes.
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.
+
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.
+
Unique identifier of the node (snake_case dotted format).
+
+
+
+
+
name
+
+ str
+
+
+
+
Human-readable display name.
+
+
+
+
+
+
+
+
+ Notes
+
Responsibilities:
+
1
+2
+3
- Represents a deterministic unit of execution in the pipeline graph.
+- Consumes one `State` and produces zero, one, or many derived states.
+- Defines execution logic and enables branching, filtering, and transformation.
+
+
Guarantees:
+
1
+2
- Nodes must never mutate the input `State`.
+- Instances are singletons per subclass and reused across executions.
+
- Subclasses implement specific resolution behavior.
+- Must not mutate input state.
+- Should use `fork()` to create child states.
+- May yield zero states to terminate a branch.
+
Immutable hierarchical container with dot-path access.
+
+
+
Attributes:
+
+
+
+
Name
+
Type
+
Description
+
+
+
+
+
_data
+
+ Mapping[str, Any]
+
+
+
+
Immutable hierarchical data structure.
+
+
+
+
+
+
+
+
+ Notes
+
Responsibilities:
+
1
+2
+3
- Stores execution data used by `State`.
+- Supports efficient atomic updates without modifying existing instances.
+- `Payload` instances are fully thread-safe due to immutability.
+
- Encapsulates engine, state type, and initial payload.
+- Provides a simplified interface for executing configured pipelines.
+- Safe for concurrent execution if underlying nodes are thread-safe.
+
- Represents a complete execution snapshot at a specific point in
+ pipeline traversal.
+- Fundamental unit of execution in `dagpipe`.
+- Fully thread-safe due to immutability.
+
- This is the only supported mechanism for modifying execution data.
+- Validates payload updates, preserves lineage, increments depth,
+ and appends to history.
+
- **Pure:** Must not mutate input state.
-- **Deterministic:** Same input produces same output.
-- **Stateless:** Recommended to be stateless for reuse.
-- **Composable:** Nodes enable branching execution graphs.
-
-
-
@@ -1180,11 +1192,13 @@ State and produces zero, one, or many new States.
123
- Represents a deterministic unit of execution in the pipeline graph.
-- Consumes one State and produces zero, one, or many derived States.
+- Consumes one `State` and produces zero, one, or many derived states.
- Defines execution logic and enables branching, filtering, and transformation.
Guarantees:
-
1
- Nodes must never mutate the input State. Instances are singletons per subclass and reused across executions.
+
1
+2
- Nodes must never mutate the input `State`.
+- Instances are singletons per subclass and reused across executions.
@@ -1229,7 +1243,7 @@ State and produces zero, one, or many new States.
-
@@ -1641,7 +1658,13 @@ State and produces zero, one, or many new States.
Notes
Responsibilities:
-
1
- Subclasses implement specific resolution behavior. Must not mutate input state. Should use fork() to create child states. May yield zero states to terminate a branch.
+
1
+2
+3
+4
- Subclasses implement specific resolution behavior.
+- Must not mutate input state.
+- Should use `fork()` to create child states.
+- May yield zero states to terminate a branch.
@@ -1661,7 +1684,7 @@ State and produces zero, one, or many new States.
-
Execute this node on a State.
+
Execute this node on a State.
Parameters:
@@ -1678,7 +1701,7 @@ State and produces zero, one, or many new States.
dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable state and optionally produces derived states for downstream nodes.
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.
Notes
Guarantees:
- Deterministic execution and consistent state lineage.\n- Orchestrates execution without modifying Graph, Node, or State objects.\n
Execution engine responsible for running pipeline logic.
Notes
Responsibilities:
- Accepts either a linear sequence of Nodes or a Graph defining execution topology.\n- Propagates immutable State objects through Nodes and collects terminal States.\n
Guarantees:
- Never mutates State, Node, or Graph instances.\n- State objects are never modified in place; each branch produces independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
Initialize the execution engine.
Parameters:
Name Type Description Default nodes_or_graphSequence[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.\n
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.\n- Deterministic traversal based on topology.\n- Graph is mutable during construction but treated as immutable at runtime.\n
"},{"location":"graph/#dagpipe.graph.Graph.add_edge--add-directed-edge-from-src-to-dst","title":"Add directed edge from src to dst.","text":""},{"location":"graph/#dagpipe.graph.Graph.add_edge--parameters","title":"Parameters","text":"
A Node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new States.
Nodes are connected using Graph and executed by Engine.
Notes
Design Principles:
- **Pure:** Must not mutate input state.\n- **Deterministic:** Same input produces same output.\n- **Stateless:** Recommended to be stateless for reuse.\n- **Composable:** Nodes enable branching execution graphs.\n
Unique identifier of the node (snake_case dotted format).
namestr
Human-readable display name.
Notes
Responsibilities:
- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one State and produces zero, one, or many derived States.\n- Defines execution logic and enables branching, filtering, and transformation.\n
Guarantees:
- Nodes must never mutate the input State. Instances are singletons per subclass and reused across executions.\n
- Subclasses implement specific resolution behavior. Must not mutate input state. Should use fork() to create child states. May yield zero states to terminate a branch.\n
The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().
Notes
Key design principles:
- **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().\n- **Cheap cloning:** Forking must be efficient since branching may create many states.\n- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.\n- **Domain agnostic:** State contains generic key\u2011value data and does not assume any schema.\n- **Engine\u2011friendly:** State contains execution metadata such as depth and history.\n
Immutable hierarchical container with dot-path access.
Attributes:
Name Type Description _dataMapping[str, Any]
Immutable hierarchical data structure.
Notes
Responsibilities:
- Stores execution data used by State. Supports efficient atomic updates without modifying existing instances.\n- Payload instances are fully thread-safe due to immutability.\n
Immutable execution state propagated through dagpipe pipeline.
Attributes:
Name Type Description payloadPayload
Execution data container.
schemaClassVar[Schema]
Payload validation schema.
confidencefloat
Execution confidence score.
parentOptional[State]
Parent state reference.
depthint
Execution depth.
historyTuple[str, ...]
Ordered node execution lineage.
metadataDict[str, Any]
Execution metadata.
Notes
Responsibilities:
- Represents a complete execution snapshot at a specific point in pipeline traversal. Fundamental unit of execution in dagpipe.\n- Fully thread-safe due to immutability.\n
Name Type Description Default payload_updateMapping[str, Any]
Dot-path updates applied to the payload.
Noneconfidence_deltafloat
Adjustment applied to current confidence.
0.0node_idstr
Identifier of the node creating this state.
Nonemetadata_updateMapping[str, Any]
Updates merged into state metadata.
None
Returns:
Name Type Description StateState
A new immutable State instance.
Notes
Guarantees:
- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth, and appends to history.\n
Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial Payloads.
Executable pipeline created from YAML configuration.
Attributes:
Name Type Description engineEngine
Execution engine responsible for running the pipeline.
state_clsType[State]
Dynamically created State subclass with configured schema.
initial_payloadPayload
Default payload used when execution begins.
Notes
Responsibilities:
- Encapsulates engine, state type, and initial payload. Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying Nodes are thread-safe.\n
dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable state and optionally produces derived states for downstream nodes.
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.
Notes
Guarantees:
- Deterministic execution and consistent state lineage.\n- Orchestrates execution without modifying Graph, Node, or State objects.\n
Execution engine responsible for running pipeline logic.
Notes
Responsibilities:
- Accepts either a linear sequence of Nodes or a Graph defining execution topology.\n- Propagates immutable State objects through Nodes and collects terminal States.\n
Guarantees:
- Never mutates State, Node, or Graph instances.\n- State objects are never modified in place; each branch produces independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
Initialize the execution engine.
Parameters:
Name Type Description Default nodes_or_graphSequence[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.\n
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.\n- Deterministic traversal based on topology.\n- Graph is mutable during construction but treated as immutable at runtime.\n
"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--add-directed-edge-from-src-to-dst","title":"Add directed edge from src to dst.","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--parameters","title":"Parameters","text":"
A Node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new States.
Nodes are connected using Graph and executed by Engine.
Notes
Design Principles:
- **Pure:** Must not mutate input state.\n- **Deterministic:** Same input produces same output.\n- **Stateless:** Recommended to be stateless for reuse.\n- **Composable:** Nodes enable branching execution graphs.\n
Unique identifier of the node (snake_case dotted format).
namestr
Human-readable display name.
Notes
Responsibilities:
- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one State and produces zero, one, or many derived States.\n- Defines execution logic and enables branching, filtering, and transformation.\n
Guarantees:
- Nodes must never mutate the input State. Instances are singletons per subclass and reused across executions.\n
- Subclasses implement specific resolution behavior. Must not mutate input state. Should use fork() to create child states. May yield zero states to terminate a branch.\n
The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().
Notes
Key design principles:
- **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().\n- **Cheap cloning:** Forking must be efficient since branching may create many states.\n- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.\n- **Domain agnostic:** State contains generic key\u2011value data and does not assume any schema.\n- **Engine\u2011friendly:** State contains execution metadata such as depth and history.\n
Immutable hierarchical container with dot-path access.
Attributes:
Name Type Description _dataMapping[str, Any]
Immutable hierarchical data structure.
Notes
Responsibilities:
- Stores execution data used by State. Supports efficient atomic updates without modifying existing instances.\n- Payload instances are fully thread-safe due to immutability.\n
Immutable execution state propagated through dagpipe pipeline.
Attributes:
Name Type Description payloadPayload
Execution data container.
schemaClassVar[Schema]
Payload validation schema.
confidencefloat
Execution confidence score.
parentOptional[State]
Parent state reference.
depthint
Execution depth.
historyTuple[str, ...]
Ordered node execution lineage.
metadataDict[str, Any]
Execution metadata.
Notes
Responsibilities:
- Represents a complete execution snapshot at a specific point in pipeline traversal. Fundamental unit of execution in dagpipe.\n- Fully thread-safe due to immutability.\n
Name Type Description Default payload_updateMapping[str, Any]
Dot-path updates applied to the payload.
Noneconfidence_deltafloat
Adjustment applied to current confidence.
0.0node_idstr
Identifier of the node creating this state.
Nonemetadata_updateMapping[str, Any]
Updates merged into state metadata.
None
Returns:
Name Type Description StateState
A new immutable State instance.
Notes
Guarantees:
- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth, and appends to history.\n
Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial Payloads.
Executable pipeline created from YAML configuration.
Attributes:
Name Type Description engineEngine
Execution engine responsible for running the pipeline.
state_clsType[State]
Dynamically created State subclass with configured schema.
initial_payloadPayload
Default payload used when execution begins.
Notes
Responsibilities:
- Encapsulates engine, state type, and initial payload. Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying Nodes are thread-safe.\n
- Loads YAML configuration, builds schema, creates State subclass, loads Node instances, builds Graph topology, and initializes Engine.\n
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"dagpipe","text":""},{"location":"#dagpipe","title":"dagpipe","text":""},{"location":"#dagpipe--summary","title":"Summary","text":"
Directed acyclic graph execution framework for deterministic state propagation.
dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable State and optionally produces derived states for downstream nodes.
Execution engine responsible for running pipeline logic.
Notes
Responsibilities:
- Accepts either a linear sequence of `Node` objects or a `Graph`\n defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n collects terminal states.\n
Guarantees:
- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
Initialize the execution engine.
Parameters:
Name Type Description Default nodes_or_graphSequence[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\n types and structure.\n
Directed Acyclic Graph defining execution topology of Node objects.
Notes
Responsibilities:
- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n
Guarantees:
- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n
Create an empty Graph.
"},{"location":"#dagpipe.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"#dagpipe.Graph-functions","title":"Functions","text":""},{"location":"#dagpipe.Graph.__repr__","title":"__repr__","text":"
Unique identifier of the node (snake_case dotted format).
namestr
Human-readable display name.
Notes
Responsibilities:
- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n
Guarantees:
- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
Immutable hierarchical container with dot-path access.
Attributes:
Name Type Description _dataMapping[str, Any]
Immutable hierarchical data structure.
Notes
Responsibilities:
- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
Executable pipeline created from YAML configuration.
Attributes:
Name Type Description engineEngine
Execution engine responsible for running the pipeline.
state_clsType[State]
Dynamically created State subclass with configured schema.
initial_payloadPayload
Default payload used when execution begins.
Notes
Responsibilities:
- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
Immutable execution state propagated through dagpipe pipeline.
Attributes:
Name Type Description payloadPayload
Execution data container.
schemaClassVar[Schema]
Payload validation schema.
confidencefloat
Execution confidence score.
parentOptional[State]
Parent state reference.
depthint
Execution depth.
historyTuple[str, ...]
Ordered node execution lineage.
metadataDict[str, Any]
Execution metadata.
Notes
Responsibilities:
- Represents a complete execution snapshot at a specific point in\n pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
Name Type Description Default payload_updateMapping[str, Any]
Dot-path updates applied to the payload.
Noneconfidence_deltafloat
Adjustment applied to current confidence.
0.0node_idstr
Identifier of the node creating this state.
Nonemetadata_updateMapping[str, Any]
Updates merged into state metadata.
None
Returns:
Name Type Description StateState
A new immutable State instance.
Notes
Guarantees:
- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n and appends to history.\n
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.
Execution engine responsible for running pipeline logic.
Notes
Responsibilities:
- Accepts either a linear sequence of `Node` objects or a `Graph`\n defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n collects terminal states.\n
Guarantees:
- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
Initialize the execution engine.
Parameters:
Name Type Description Default nodes_or_graphSequence[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\n types and structure.\n
Directed Acyclic Graph defining execution topology of Node objects.
Notes
Responsibilities:
- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n
Guarantees:
- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n
Create an empty Graph.
"},{"location":"graph/#dagpipe.graph.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"
Unique identifier of the node (snake_case dotted format).
namestr
Human-readable display name.
Notes
Responsibilities:
- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n
Guarantees:
- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().
Immutable hierarchical container with dot-path access.
Attributes:
Name Type Description _dataMapping[str, Any]
Immutable hierarchical data structure.
Notes
Responsibilities:
- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
Immutable execution state propagated through dagpipe pipeline.
Attributes:
Name Type Description payloadPayload
Execution data container.
schemaClassVar[Schema]
Payload validation schema.
confidencefloat
Execution confidence score.
parentOptional[State]
Parent state reference.
depthint
Execution depth.
historyTuple[str, ...]
Ordered node execution lineage.
metadataDict[str, Any]
Execution metadata.
Notes
Responsibilities:
- Represents a complete execution snapshot at a specific point in\n pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
Name Type Description Default payload_updateMapping[str, Any]
Dot-path updates applied to the payload.
Noneconfidence_deltafloat
Adjustment applied to current confidence.
0.0node_idstr
Identifier of the node creating this state.
Nonemetadata_updateMapping[str, Any]
Updates merged into state metadata.
None
Returns:
Name Type Description StateState
A new immutable State instance.
Notes
Guarantees:
- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n and appends to history.\n
Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial payloads.
Executable pipeline created from YAML configuration.
Attributes:
Name Type Description engineEngine
Execution engine responsible for running the pipeline.
state_clsType[State]
Dynamically created State subclass with configured schema.
initial_payloadPayload
Default payload used when execution begins.
Notes
Responsibilities:
- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
The State represents a single point in pipeline execution. It contains
+
Summary
+
Defines the core State object used by dagpipe.
+
The State represents a single point in pipeline execution. It contains
arbitrary data and metadata and is designed to be immutable. Instead of
-modifying an existing state, nodes create new child states via fork().
+modifying an existing state, nodes create new child states via fork().
+
+
Design principles
+
+
Immutability: States must never be modified after creation.
+ All transformations must create a new state via fork().
+
Cheap cloning: Forking must be efficient since branching may create many states.
+
Lineage tracking: Each state maintains a reference to its parent and
+ execution metadata for debugging and observability.
+
Domain agnostic: State contains generic key-value data and does not
+ assume any schema.
+
Engine-friendly: State contains execution metadata such as depth and history.
+
-
- Notes
-
Key design principles:
-
1
-2
-3
-4
-5
- **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().
-- **Cheap cloning:** Forking must be efficient since branching may create many states.
-- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.
-- **Domain agnostic:** State contains generic key‑value data and does not assume any schema.
-- **Engine‑friendly:** State contains execution metadata such as depth and history.
-
-
-
@@ -1358,8 +1372,10 @@ modifying an existing state, nodes create new child states via fork().
Notes
Responsibilities:
1
-2
- Stores execution data used by State. Supports efficient atomic updates without modifying existing instances.
-- Payload instances are fully thread-safe due to immutability.
+2
+3
- Stores execution data used by `State`.
+- Supports efficient atomic updates without modifying existing instances.
+- `Payload` instances are fully thread-safe due to immutability.
@@ -1720,7 +1736,7 @@ Iterator over top-level keys.
-
Create a new Payload with dot-path updates applied.
+
Create a new Payload with dot-path updates applied.
Parameters:
@@ -1763,7 +1779,7 @@ Iterator over top-level keys.
@@ -2152,7 +2172,11 @@ Iterator over top-level keys.
Notes
Responsibilities:
1
-2
- Represents a complete execution snapshot at a specific point in pipeline traversal. Fundamental unit of execution in dagpipe.
+2
+3
+4
- Represents a complete execution snapshot at a specific point in
+ pipeline traversal.
+- Fundamental unit of execution in `dagpipe`.
- Fully thread-safe due to immutability.
@@ -2202,7 +2226,7 @@ Iterator over top-level keys.
-
Create a new child State derived from this State.
+
Create a new child State derived from this state.
Parameters:
@@ -2287,11 +2311,11 @@ Iterator over top-level keys.
@@ -2303,8 +2327,10 @@ Iterator over top-level keys.
Notes
Guarantees:
1
-2
- This is the only supported mechanism for modifying execution data.
-- Validates payload updates, preserves lineage, increments depth, and appends to history.
+2
+3
- This is the only supported mechanism for modifying execution data.
+- Validates payload updates, preserves lineage, increments depth,
+ and appends to history.
@@ -2494,7 +2520,7 @@ Iterator over top-level keys.
@@ -1027,8 +1026,10 @@ and initial Payloads.
Notes
Responsibilities:
1
-2
- Encapsulates engine, state type, and initial payload. Provides a simplified interface for executing configured pipelines.
-- Safe for concurrent execution if underlying Nodes are thread-safe.
+2
+3
- Encapsulates engine, state type, and initial payload.
+- Provides a simplified interface for executing configured pipelines.
+- Safe for concurrent execution if underlying nodes are thread-safe.