{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"dagpipe","text":""},{"location":"#dagpipe","title":"dagpipe","text":""},{"location":"#dagpipe--summary","title":"Summary","text":"<p>Directed acyclic graph execution framework for deterministic state propagation.</p> <p><code>dagpipe</code> executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable <code>State</code> and optionally produces derived states for downstream nodes.</p>"},{"location":"#dagpipe--installation","title":"Installation","text":"<p>Install using pip:</p> <pre><code>pip install dagpipe\n</code></pre>"},{"location":"#dagpipe--quick-start","title":"Quick Start","text":"<pre><code>from dagpipe import State, Payload, Schema, Graph, Engine\nfrom dagpipe.node import Node\n\nclass HelloNode(Node):\n    id = \"hello\"\n    def resolve(self, state):\n        yield self.fork(state, payload_update={\"msg\": \"hello\"})\n\n# Build and run\ngraph = Graph()\ngraph.add_root(HelloNode())\nengine = Engine(graph)\n\nclass MyState(State):\n    schema = Schema({})\n\nresults = engine.run(MyState(payload=Payload({})))\n</code></pre>"},{"location":"#dagpipe--public-api","title":"Public API","text":"<p>This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.</p>"},{"location":"#dagpipe--execution-core","title":"Execution Core","text":"<ul> <li><code>Engine</code>: Responsible for orchestrating node execution and state propagation.</li> <li><code>Graph</code>: Defines the execution topology and node relationships.</li> <li><code>Node</code>: Base class for defining execution logic and transformations.</li> </ul>"},{"location":"#dagpipe--state-data","title":"State &amp; Data","text":"<ul> <li><code>State</code>: Represents an immutable execution snapshot at a point in time.</li> <li><code>Payload</code>: Immutable hierarchical container for execution data.</li> <li><code>Schema</code>: Defines and validates the allowed structure of payloads.</li> <li><code>SchemaError</code>: Raised when data violates the declared schema.</li> </ul>"},{"location":"#dagpipe--declarative-pipelines","title":"Declarative Pipelines","text":"<ul> <li><code>Pipeline</code>: High-level wrapper for an engine, state type, and initial payload.</li> <li><code>load_pipeline</code>: Factory function to create a pipeline from YAML.</li> </ul>"},{"location":"#dagpipe-classes","title":"Classes","text":""},{"location":"#dagpipe.AsyncNode","title":"AsyncNode","text":"<p>               Bases: <code>Node</code></p> <p>Base class for nodes whose execution is asynchronous.</p> <p>Subclasses implement <code>resolve_async</code> (an async generator yielding derived <code>State</code> objects). The engine dispatches to <code>resolve_async</code> when running an async traversal (see <code>Engine.run_async</code>).</p> <p>Sync-only engines (and the base <code>Node.run</code>) treat an <code>AsyncNode</code> as a no-op consumer: calling <code>run</code> on an <code>AsyncNode</code> returns no states, signalling that an async engine is required.</p>"},{"location":"#dagpipe.AsyncNode-functions","title":"Functions","text":""},{"location":"#dagpipe.AsyncNode.__hash__","title":"__hash__","text":"<pre><code>__hash__() -&gt; int\n</code></pre> <p>Return stable hash based on node ID.</p> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Hash of the node ID, allowing nodes to be used as dict keys.</p>"},{"location":"#dagpipe.AsyncNode.__new__","title":"__new__","text":"<pre><code>__new__(*args: Any, **kwargs: Any) -&gt; AsyncNode\n</code></pre> <p>Create or reuse an async node instance.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Positional constructor arguments forwarded to <code>__init__</code>.</p> <code>()</code> <code>**kwargs</code> <code>Any</code> <p>Keyword constructor arguments forwarded to <code>__init__</code>.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>AsyncNode</code> <code>AsyncNode</code> <p>A fresh instance for subclasses declaring a parameterized <code>__init__</code>, or the shared singleton for stateless subclasses.</p>"},{"location":"#dagpipe.AsyncNode.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return computation identity based on node ID.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {id}&gt;</code>.</p>"},{"location":"#dagpipe.AsyncNode.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return user-facing display name.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {name}&gt;</code>.</p>"},{"location":"#dagpipe.AsyncNode.clean_id_and_name","title":"clean_id_and_name  <code>classmethod</code>","text":"<pre><code>clean_id_and_name() -&gt; None\n</code></pre> <p>Normalize and validate node ID and display name.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If ID is not a string.</p> <code>ValueError</code> <p>If ID format is invalid.</p> Notes <p>Guarantees:</p> <pre><code>- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n</code></pre>"},{"location":"#dagpipe.AsyncNode.fork","title":"fork","text":"<pre><code>fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -&gt; State\n</code></pre> <p>Create a child <code>State</code> attributed to this node.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Parent execution state.</p> required <code>payload_update</code> <code>Any</code> <p>Dot-path payload updates.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Confidence adjustment.</p> <code>0.0</code> <code>metadata_update</code> <code>Any</code> <p>Metadata updates.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>New child execution state.</p> Notes <p>Responsibilities:</p> <pre><code>- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n</code></pre>"},{"location":"#dagpipe.AsyncNode.is_async","title":"is_async","text":"<pre><code>is_async() -&gt; bool\n</code></pre> <p>Return whether this node executes asynchronously.</p> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the node is an <code>AsyncNode</code> instance.</p>"},{"location":"#dagpipe.AsyncNode.node_id_to_name","title":"node_id_to_name  <code>staticmethod</code>","text":"<pre><code>node_id_to_name(node_id: str) -&gt; str\n</code></pre> <p>Convert a dotted snake_case node ID into a human-readable name.</p> <p>Parameters:</p> Name Type Description Default <code>node_id</code> <code>str</code> <p>Unique node identifier (e.g., 'entity.resolve.numeric_merchant').</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').</p>"},{"location":"#dagpipe.AsyncNode.resolve","title":"resolve","text":"<pre><code>resolve(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute no-op resolution in sync contexts.</p> <p>Sync-only engines (and the base <code>Node.run</code>) treat an <code>AsyncNode</code> as a no-op consumer: this returns no states, signalling that an async engine is required.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Empty tuple, since async execution is handled by <code>resolve_async</code>.</p>"},{"location":"#dagpipe.AsyncNode.resolve_async","title":"resolve_async  <code>async</code>","text":"<pre><code>resolve_async(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute node logic asynchronously.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Derived execution state(s).</p> Notes <p>Guarantees:</p> <pre><code>- Subclasses implement this.\n- Must not mutate the input state.\n- Should use `fork()` to create child states.\n</code></pre>"},{"location":"#dagpipe.AsyncNode.run","title":"run","text":"<pre><code>run(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node on a <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve()</code> yields a non-<code>State</code> object.</p>"},{"location":"#dagpipe.AsyncNode.run_async","title":"run_async  <code>async</code>","text":"<pre><code>run_async(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node asynchronously on a state, validating outputs.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve_async()</code> yields a non-<code>State</code> object.</p>"},{"location":"#dagpipe.Engine","title":"Engine","text":"<pre><code>Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n</code></pre> <p>Execution engine responsible for running pipeline logic.</p> Notes <p>Responsibilities:</p> <pre><code>- 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- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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</code></pre> <p>Create an engine from a node sequence or a graph.</p> <p>Parameters:</p> Name Type Description Default <code>nodes_or_graph</code> <code>Sequence[Node] | Graph</code> <p>Either an ordered sequence of <code>Node</code> instances (linear mode) or a <code>Graph</code> defining the execution topology (graph mode).</p> required <code>on_step</code> <code>StepHook | None</code> <p>Default per-step callback <code>(step, status, message)</code> used when a step run does not supply its own hook.</p> <code>None</code> <p>Raises:</p> Type Description <code>TypeError</code> <p>If a sequence element is not a <code>Node</code>, or if <code>nodes_or_graph</code> is neither a <code>Sequence[Node]</code> nor a <code>Graph</code>.</p>"},{"location":"#dagpipe.Engine-attributes","title":"Attributes","text":""},{"location":"#dagpipe.Engine.nodes","title":"nodes  <code>property</code>","text":"<pre><code>nodes: tuple[Node, ...]\n</code></pre> <p>Return nodes managed by this engine.</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.</p>"},{"location":"#dagpipe.Engine-functions","title":"Functions","text":""},{"location":"#dagpipe.Engine.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return the canonical string representation of the object.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Representation that uniquely identifies the object and its configuration.</p>"},{"location":"#dagpipe.Engine.run","title":"run","text":"<pre><code>run(root: State) -&gt; list[State]\n</code></pre> <p>Execute the pipeline starting from a root <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states produced by the pipeline.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>root</code> is not a <code>State</code> instance.</p> <code>RuntimeError</code> <p>If the engine execution mode is invalid.</p> Notes <p>Responsibilities:</p> <pre><code>- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n</code></pre>"},{"location":"#dagpipe.Engine.run_async","title":"run_async  <code>async</code>","text":"<pre><code>run_async(root: State) -&gt; list[State]\n</code></pre> <p>Execute the pipeline starting from <code>root</code>, dispatching sync vs async nodes.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states produced by the pipeline.</p> Notes <p>Each node is executed with <code>Node.run</code> when synchronous and <code>AsyncNode.run_async</code> when asynchronous. Linear and graph topologies are both supported.</p>"},{"location":"#dagpipe.Engine.run_steps","title":"run_steps","text":"<pre><code>run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -&gt; Iterator[StepResult]\n</code></pre> <p>Execute the pipeline step-by-step, yielding one <code>StepResult</code> per step.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <code>resume_from</code> <code>int | None</code> <p>Skip steps at index &lt; <code>resume_from</code> (for resume-after-partial). Steps are 0-indexed.</p> <code>None</code> <code>on_step</code> <code>StepHook | None</code> <p>Callback <code>(step, status, message)</code> invoked per step; falls back to the engine-level hook when unset.</p> <code>None</code> <p>Yields:</p> Name Type Description <code>StepResult</code> <code>StepResult</code> <p>One per executed node/step, carrying the produced states.</p> Notes <p>This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use <code>run_steps_async</code> for async nodes.</p>"},{"location":"#dagpipe.Engine.run_steps_async","title":"run_steps_async  <code>async</code>","text":"<pre><code>run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -&gt; AsyncIterator[StepResult]\n</code></pre> <p>Async variant of <code>run_steps</code> supporting <code>AsyncNode</code> execution.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <code>resume_from</code> <code>int | None</code> <p>Skip steps at index &lt; <code>resume_from</code>.</p> <code>None</code> <code>on_step</code> <code>AsyncStepHook | None</code> <p>Async callback <code>(step, status, message)</code> invoked per step.</p> <code>None</code> <p>Yields:</p> Name Type Description <code>StepResult</code> <code>AsyncIterator[StepResult]</code> <p>One per executed node/step.</p>"},{"location":"#dagpipe.Graph","title":"Graph","text":"<pre><code>Graph()\n</code></pre> <p>Directed Acyclic Graph defining execution topology of <code>Node</code> objects.</p> Notes <p>Responsibilities:</p> <pre><code>- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n</code></pre> <p>Guarantees:</p> <pre><code>- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n</code></pre> <p>Create an empty Graph.</p> <p>Initializes node registry and edge mappings.</p>"},{"location":"#dagpipe.Graph-functions","title":"Functions","text":""},{"location":"#dagpipe.Graph.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return a compact graph description.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>A string describing the graph as <code>Graph(nodes=N, edges=M)</code> where <code>N</code> and <code>M</code> describe the current registry size.</p>"},{"location":"#dagpipe.Graph.add_edge","title":"add_edge","text":"<pre><code>add_edge(src: Node, dst: Node) -&gt; None\n</code></pre> <p>Add a directed edge from <code>src</code> to <code>dst</code>.</p> <p>Parameters:</p> Name Type Description Default <code>src</code> <code>Node</code> <p>Source node.</p> required <code>dst</code> <code>Node</code> <p>Destination node.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>src</code> or <code>dst</code> is not a <code>Node</code>.</p> <code>ValueError</code> <p>If the edge would create a cycle or if <code>src</code> and <code>dst</code> are common.</p> Notes <ul> <li>Validates node types.</li> <li>Prevents cycles.</li> <li>Registers nodes if not present.</li> <li>Updates parent and child mappings.</li> </ul>"},{"location":"#dagpipe.Graph.add_root","title":"add_root","text":"<pre><code>add_root(node: Node) -&gt; None\n</code></pre> <p>Add a root node with no parents.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to add as a root.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If node is not a Node instance.</p>"},{"location":"#dagpipe.Graph.children","title":"children","text":"<pre><code>children(node: Node) -&gt; tuple[Node, ...]\n</code></pre> <p>Return child nodes of a node.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to query.</p> required <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Outgoing neighbors.</p>"},{"location":"#dagpipe.Graph.nodes","title":"nodes","text":"<pre><code>nodes() -&gt; tuple[Node, ...]\n</code></pre> <p>Return all nodes in the graph.</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: All registered nodes.</p>"},{"location":"#dagpipe.Graph.parents","title":"parents","text":"<pre><code>parents(node: Node) -&gt; tuple[Node, ...]\n</code></pre> <p>Return parent nodes of a node.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to query.</p> required <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Incoming neighbors.</p>"},{"location":"#dagpipe.Graph.roots","title":"roots","text":"<pre><code>roots() -&gt; tuple[Node, ...]\n</code></pre> <p>Return root nodes (nodes with no incoming edges).</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Entry point nodes.</p>"},{"location":"#dagpipe.Node","title":"Node","text":"<p>               Bases: <code>ABC</code></p> <p>Base class for all dagpipe execution nodes.</p> <p>Attributes:</p> Name Type Description <code>id</code> <code>str</code> <p>Unique identifier of the node (snake_case dotted format).</p> <code>name</code> <code>str</code> <p>Human-readable display name.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre> <p>Guarantees:</p> <pre><code>- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n</code></pre>"},{"location":"#dagpipe.Node-functions","title":"Functions","text":""},{"location":"#dagpipe.Node.__hash__","title":"__hash__","text":"<pre><code>__hash__() -&gt; int\n</code></pre> <p>Return stable hash based on node ID.</p> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Hash of the node ID, allowing nodes to be used as dict keys.</p>"},{"location":"#dagpipe.Node.__new__","title":"__new__","text":"<pre><code>__new__(*args: Any, **kwargs: Any) -&gt; Node\n</code></pre> <p>Create or reuse a node instance.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Positional constructor arguments forwarded to <code>__init__</code>.</p> <code>()</code> <code>**kwargs</code> <code>Any</code> <p>Keyword constructor arguments forwarded to <code>__init__</code>.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>Node</code> <code>Node</code> <p>A fresh instance for subclasses declaring a parameterized <code>__init__</code>, or the shared singleton for stateless subclasses.</p> Notes <p>Guarantees:</p> <pre><code>- Stateless subclasses (no parameterized `__init__`) share one\n  singleton instance per class \u2014 matching the original dagpipe\n  behaviour underpinning `set_registry`-style configuration.\n- Subclasses that declare an `__init__` requiring instance-state\n  arguments get a fresh instance per construction so pipeline\n  builders can inject per-run dependencies.\n</code></pre>"},{"location":"#dagpipe.Node.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return computation identity based on node ID.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {id}&gt;</code>.</p>"},{"location":"#dagpipe.Node.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return user-facing display name.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {name}&gt;</code>.</p>"},{"location":"#dagpipe.Node.clean_id_and_name","title":"clean_id_and_name  <code>classmethod</code>","text":"<pre><code>clean_id_and_name() -&gt; None\n</code></pre> <p>Normalize and validate node ID and display name.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If ID is not a string.</p> <code>ValueError</code> <p>If ID format is invalid.</p> Notes <p>Guarantees:</p> <pre><code>- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n</code></pre>"},{"location":"#dagpipe.Node.fork","title":"fork","text":"<pre><code>fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -&gt; State\n</code></pre> <p>Create a child <code>State</code> attributed to this node.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Parent execution state.</p> required <code>payload_update</code> <code>Any</code> <p>Dot-path payload updates.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Confidence adjustment.</p> <code>0.0</code> <code>metadata_update</code> <code>Any</code> <p>Metadata updates.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>New child execution state.</p> Notes <p>Responsibilities:</p> <pre><code>- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n</code></pre>"},{"location":"#dagpipe.Node.is_async","title":"is_async","text":"<pre><code>is_async() -&gt; bool\n</code></pre> <p>Return whether this node executes asynchronously.</p> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the node is an <code>AsyncNode</code> instance.</p>"},{"location":"#dagpipe.Node.node_id_to_name","title":"node_id_to_name  <code>staticmethod</code>","text":"<pre><code>node_id_to_name(node_id: str) -&gt; str\n</code></pre> <p>Convert a dotted snake_case node ID into a human-readable name.</p> <p>Parameters:</p> Name Type Description Default <code>node_id</code> <code>str</code> <p>Unique node identifier (e.g., 'entity.resolve.numeric_merchant').</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').</p>"},{"location":"#dagpipe.Node.resolve","title":"resolve  <code>abstractmethod</code>","text":"<pre><code>resolve(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute node logic.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Derived execution state(s).</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"#dagpipe.Node.run","title":"run","text":"<pre><code>run(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node on a <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve()</code> yields a non-<code>State</code> object.</p>"},{"location":"#dagpipe.Payload","title":"Payload  <code>dataclass</code>","text":"<pre><code>Payload(_data: Mapping[str, Any])\n</code></pre> <p>Immutable hierarchical container with dot-path access.</p> <p>Attributes:</p> Name Type Description <code>_data</code> <code>Mapping[str, Any]</code> <p>Immutable hierarchical data structure.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"#dagpipe.Payload-functions","title":"Functions","text":""},{"location":"#dagpipe.Payload.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return a concise payload description.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>Payload(keys=[...])</code> listing top-level keys.</p>"},{"location":"#dagpipe.Payload.as_dict","title":"as_dict","text":"<pre><code>as_dict() -&gt; Mapping[str, Any]\n</code></pre> <p>Return underlying mapping.</p> <p>Returns:</p> Type Description <code>Mapping[str, Any]</code> <p>Mapping[str, Any]: Read-only view of the underlying data.</p>"},{"location":"#dagpipe.Payload.get","title":"get","text":"<pre><code>get(path: str, default: Any = None) -&gt; Any\n</code></pre> <p>Retrieve value using dot-path.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dot-separated path to the value.</p> required <code>default</code> <code>Any</code> <p>Default value if path doesn't exist.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>The retrieved value or default.</p>"},{"location":"#dagpipe.Payload.has","title":"has","text":"<pre><code>has(path: str) -&gt; bool\n</code></pre> <p>Return True if path exists.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dot-separated path to check.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>Existence of the path.</p>"},{"location":"#dagpipe.Payload.iter_paths","title":"iter_paths  <code>classmethod</code>","text":"<pre><code>iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -&gt; Iterable[str]\n</code></pre> <p>Recursively yield dot-paths for all leaf nodes.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>Mapping[str, Any]</code> <p>The mapping to iterate over.</p> required <code>prefix</code> <code>str</code> <p>Current path prefix.</p> <code>''</code> <p>Yields:</p> Name Type Description <code>str</code> <code>Iterable[str]</code> <p>Dot-path for each leaf node.</p>"},{"location":"#dagpipe.Payload.keys","title":"keys","text":"<pre><code>keys() -&gt; Iterable[str]\n</code></pre> <p>Return top-level keys.</p> <p>Returns:</p> Type Description <code>Iterable[str]</code> <p>Iterable[str]: Iterator over top-level keys.</p>"},{"location":"#dagpipe.Payload.update","title":"update","text":"<pre><code>update(updates: Mapping[str, Any]) -&gt; Payload\n</code></pre> <p>Create a new <code>Payload</code> with dot-path updates applied.</p> <p>Parameters:</p> Name Type Description Default <code>updates</code> <code>Mapping[str, Any]</code> <p>Dot-path to value mapping.</p> required <p>Returns:</p> Name Type Description <code>Payload</code> <code>Payload</code> <p>New immutable payload instance with updates.</p> Notes <p>Guarantees:</p> <pre><code>- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n</code></pre>"},{"location":"#dagpipe.Pipeline","title":"Pipeline  <code>dataclass</code>","text":"<pre><code>Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n</code></pre> <p>Executable pipeline created from YAML configuration.</p> <p>Attributes:</p> Name Type Description <code>engine</code> <code>Engine</code> <p>Execution engine responsible for running the pipeline.</p> <code>state_cls</code> <code>Type[State]</code> <p>Dynamically created <code>State</code> subclass with configured schema.</p> <code>initial_payload</code> <code>Payload</code> <p>Default payload used when execution begins.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"#dagpipe.Pipeline-functions","title":"Functions","text":""},{"location":"#dagpipe.Pipeline.run","title":"run","text":"<pre><code>run(\n    payload_override: Mapping[str, Any] | None = None,\n) -&gt; list[State]\n</code></pre> <p>Execute the pipeline.</p> <p>Parameters:</p> Name Type Description Default <code>payload_override</code> <code>Mapping[str, Any] | None</code> <p>Payload values overriding initial payload.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states.</p> Notes <p>Responsibilities:</p> <pre><code>- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n</code></pre>"},{"location":"#dagpipe.ProgressMessage","title":"ProgressMessage","text":"<pre><code>ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n</code></pre> <p>Lightweight progress payload emitted by engine step hooks.</p> <p>Mirrors the imperative <code>ProgressMessage</code> used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.</p> <p>Attributes:</p> Name Type Description <code>lines</code> <code>int | None</code> <p>Optional count of processed lines.</p> <code>blocks</code> <code>int | None</code> <p>Optional count of processed blocks.</p> <code>count</code> <code>int | None</code> <p>Optional generic item count.</p> <code>unit</code> <code>str | None</code> <p>Optional unit for the count (e.g., 'pages').</p> <code>raw_ocr_line</code> <code>str | None</code> <p>Optional raw OCR line payload.</p> <code>error</code> <code>str | None</code> <p>Optional error description.</p> <code>step</code> <code>str</code> <p>Identifier of the step that emitted the message.</p> <code>status</code> <code>str</code> <p>Status label associated with the step.</p> Notes <p>Guarantees:</p> <pre><code>- Immutable after construction (attributes are never reassigned).\n- Independent of pydantic; safe to construct in the engine core.\n</code></pre> <p>Create a progress message.</p> <p>Parameters:</p> Name Type Description Default <code>lines</code> <code>int | None</code> <p>Optional count of processed lines.</p> <code>None</code> <code>blocks</code> <code>int | None</code> <p>Optional count of processed blocks.</p> <code>None</code> <code>count</code> <code>int | None</code> <p>Optional generic item count.</p> <code>None</code> <code>unit</code> <code>str | None</code> <p>Optional unit for the count (e.g., 'pages').</p> <code>None</code> <code>raw_ocr_line</code> <code>str | None</code> <p>Optional raw OCR line payload.</p> <code>None</code> <code>error</code> <code>str | None</code> <p>Optional error description.</p> <code>None</code> <code>step</code> <code>str</code> <p>Identifier of the step that emitted the message.</p> <code>''</code> <code>status</code> <code>str</code> <p>Status label associated with the step.</p> <code>''</code>"},{"location":"#dagpipe.ProgressMessage-functions","title":"Functions","text":""},{"location":"#dagpipe.ProgressMessage.as_dict","title":"as_dict","text":"<pre><code>as_dict() -&gt; dict[str, Any]\n</code></pre> <p>Return the message as a plain dictionary.</p> <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>dict[str, Any]: All attribute values keyed by their attribute name.</p>"},{"location":"#dagpipe.Schema","title":"Schema  <code>dataclass</code>","text":"<pre><code>Schema(tree: Mapping[str, SchemaNode])\n</code></pre> <p>Immutable hierarchical schema defining allowed payload structure.</p> <p>Attributes:</p> Name Type Description <code>tree</code> <code>Mapping[str, SchemaNode]</code> <p>Hierarchical schema definition.</p> Notes <p>Responsibilities:</p> <pre><code>- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n</code></pre>"},{"location":"#dagpipe.Schema-functions","title":"Functions","text":""},{"location":"#dagpipe.Schema.validate_payload","title":"validate_payload","text":"<pre><code>validate_payload(payload: Payload) -&gt; None\n</code></pre> <p>Validate complete payload structure.</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>Payload</code> <p>Payload to validate.</p> required <p>Raises:</p> Type Description <code>SchemaError</code> <p>If payload violates schema.</p>"},{"location":"#dagpipe.Schema.validate_update","title":"validate_update","text":"<pre><code>validate_update(updates: Mapping[str, Any]) -&gt; None\n</code></pre> <p>Validate payload update paths.</p> <p>Parameters:</p> Name Type Description Default <code>updates</code> <code>Mapping[str, Any]</code> <p>Dot-path updates to validate.</p> required <p>Raises:</p> Type Description <code>SchemaError</code> <p>If any path is invalid according to the schema.</p>"},{"location":"#dagpipe.SchemaError","title":"SchemaError","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when payload data violates the declared schema.</p> <p>Indicates invalid structure, invalid path, or invalid type.</p>"},{"location":"#dagpipe.State","title":"State  <code>dataclass</code>","text":"<pre><code>State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n</code></pre> <p>Immutable execution state propagated through dagpipe pipeline.</p> <p>Attributes:</p> Name Type Description <code>payload</code> <code>Payload</code> <p>Execution data container.</p> <code>schema</code> <code>ClassVar[Schema]</code> <p>Payload validation schema.</p> <code>confidence</code> <code>float</code> <p>Execution confidence score.</p> <code>parent</code> <code>Optional[State]</code> <p>Parent state reference.</p> <code>depth</code> <code>int</code> <p>Execution depth.</p> <code>history</code> <code>Tuple[str, ...]</code> <p>Ordered node execution lineage.</p> <code>metadata</code> <code>Dict[str, Any]</code> <p>Execution metadata.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"#dagpipe.State-functions","title":"Functions","text":""},{"location":"#dagpipe.State.__post_init__","title":"__post_init__","text":"<pre><code>__post_init__() -&gt; None\n</code></pre> <p>Validate the payload against the declared schema.</p> <p>Raises:</p> Type Description <code>SchemaError</code> <p>If the payload violates the schema declared on the subclass.</p>"},{"location":"#dagpipe.State.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Concise debug representation.</p> <p>Avoids printing full data for large states.</p>"},{"location":"#dagpipe.State.fork","title":"fork","text":"<pre><code>fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -&gt; State\n</code></pre> <p>Create a new child <code>State</code> derived from this state.</p> <p>Parameters:</p> Name Type Description Default <code>payload_update</code> <code>Mapping[str, Any] | None</code> <p>Dot-path updates applied to the payload.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Adjustment applied to current confidence.</p> <code>0.0</code> <code>node_id</code> <code>str | None</code> <p>Identifier of the node creating this state.</p> <code>None</code> <code>metadata_update</code> <code>Mapping[str, Any] | None</code> <p>Updates merged into state metadata.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>A new immutable <code>State</code> instance.</p> Notes <p>Guarantees:</p> <pre><code>- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n</code></pre>"},{"location":"#dagpipe.State.get","title":"get","text":"<pre><code>get(key: str, default: Any = None) -&gt; Any\n</code></pre> <p>Retrieve payload value.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>Dot-path key.</p> required <code>default</code> <code>Any</code> <p>Fallback value.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>Stored value or default.</p>"},{"location":"#dagpipe.State.has","title":"has","text":"<pre><code>has(key: str) -&gt; bool\n</code></pre> <p>Check whether payload contains key.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>Dot-path key.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>Existence of the key.</p>"},{"location":"#dagpipe.State.lineage","title":"lineage","text":"<pre><code>lineage() -&gt; tuple[State, ...]\n</code></pre> <p>Return lineage from root to this State.</p> <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Ordered execution lineage (root first).</p>"},{"location":"#dagpipe.StepResult","title":"StepResult","text":"<pre><code>StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n</code></pre> <p>A single checkpointed step within an async/resumable engine run.</p> <p>Attributes:</p> Name Type Description <code>index</code> <code>int</code> <p>Ordinal index of the step.</p> <code>node_id</code> <code>str</code> <p>Identifier of the node associated with this step.</p> <code>states</code> <code>tuple[State, ...]</code> <p>States produced by running this step.</p> <code>completed</code> <code>bool</code> <p>Whether this step succeeded (vs. paused/interrupted).</p> <p>Initialise StepResult.</p> <p>Parameters:</p> Name Type Description Default <code>index</code> <code>int</code> <p>Ordinal index of the step.</p> required <code>node_id</code> <code>str</code> <p>Identifier of the node associated with this step.</p> required <code>states</code> <code>tuple[State, ...]</code> <p>States produced by running this step.</p> required <code>completed</code> <code>bool</code> <p>Whether this step succeeded (vs. paused/interrupted).</p> required"},{"location":"#dagpipe.StepResult-functions","title":"Functions","text":""},{"location":"#dagpipe-functions","title":"Functions","text":""},{"location":"#dagpipe.load_pipeline","title":"load_pipeline","text":"<pre><code>load_pipeline(path: str) -&gt; Pipeline\n</code></pre> <p>Load pipeline from YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Path to YAML configuration file.</p> required <p>Returns:</p> Name Type Description <code>Pipeline</code> <code>Pipeline</code> <p>Executable pipeline instance.</p> Notes <p>Responsibilities:</p> <pre><code>- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n</code></pre>"},{"location":"engine/","title":"Engine","text":""},{"location":"engine/#dagpipe.engine","title":"dagpipe.engine","text":""},{"location":"engine/#dagpipe.engine--summary","title":"Summary","text":"<p>Execution engine responsible for running pipelines and graphs.</p> <p>The <code>Engine</code> executes <code>Node</code> objects and propagates immutable <code>State</code> instances through either a linear sequence or a directed acyclic graph (<code>Graph</code>). It orchestrates execution order, branching, and state propagation.</p>"},{"location":"engine/#dagpipe.engine--guarantees","title":"Guarantees","text":"<ul> <li>Deterministic execution and consistent state lineage.</li> <li>Orchestrates execution without modifying <code>Graph</code>, <code>Node</code>, or <code>State</code> objects.</li> </ul>"},{"location":"engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"engine/#dagpipe.engine.Engine","title":"Engine","text":"<pre><code>Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n</code></pre> <p>Execution engine responsible for running pipeline logic.</p> Notes <p>Responsibilities:</p> <pre><code>- 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- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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</code></pre> <p>Create an engine from a node sequence or a graph.</p> <p>Parameters:</p> Name Type Description Default <code>nodes_or_graph</code> <code>Sequence[Node] | Graph</code> <p>Either an ordered sequence of <code>Node</code> instances (linear mode) or a <code>Graph</code> defining the execution topology (graph mode).</p> required <code>on_step</code> <code>StepHook | None</code> <p>Default per-step callback <code>(step, status, message)</code> used when a step run does not supply its own hook.</p> <code>None</code> <p>Raises:</p> Type Description <code>TypeError</code> <p>If a sequence element is not a <code>Node</code>, or if <code>nodes_or_graph</code> is neither a <code>Sequence[Node]</code> nor a <code>Graph</code>.</p>"},{"location":"engine/#dagpipe.engine.Engine-attributes","title":"Attributes","text":""},{"location":"engine/#dagpipe.engine.Engine.nodes","title":"nodes  <code>property</code>","text":"<pre><code>nodes: tuple[Node, ...]\n</code></pre> <p>Return nodes managed by this engine.</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.</p>"},{"location":"engine/#dagpipe.engine.Engine-functions","title":"Functions","text":""},{"location":"engine/#dagpipe.engine.Engine.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return the canonical string representation of the object.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Representation that uniquely identifies the object and its configuration.</p>"},{"location":"engine/#dagpipe.engine.Engine.run","title":"run","text":"<pre><code>run(root: State) -&gt; list[State]\n</code></pre> <p>Execute the pipeline starting from a root <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states produced by the pipeline.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>root</code> is not a <code>State</code> instance.</p> <code>RuntimeError</code> <p>If the engine execution mode is invalid.</p> Notes <p>Responsibilities:</p> <pre><code>- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n</code></pre>"},{"location":"engine/#dagpipe.engine.Engine.run_async","title":"run_async  <code>async</code>","text":"<pre><code>run_async(root: State) -&gt; list[State]\n</code></pre> <p>Execute the pipeline starting from <code>root</code>, dispatching sync vs async nodes.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states produced by the pipeline.</p> Notes <p>Each node is executed with <code>Node.run</code> when synchronous and <code>AsyncNode.run_async</code> when asynchronous. Linear and graph topologies are both supported.</p>"},{"location":"engine/#dagpipe.engine.Engine.run_steps","title":"run_steps","text":"<pre><code>run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -&gt; Iterator[StepResult]\n</code></pre> <p>Execute the pipeline step-by-step, yielding one <code>StepResult</code> per step.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <code>resume_from</code> <code>int | None</code> <p>Skip steps at index &lt; <code>resume_from</code> (for resume-after-partial). Steps are 0-indexed.</p> <code>None</code> <code>on_step</code> <code>StepHook | None</code> <p>Callback <code>(step, status, message)</code> invoked per step; falls back to the engine-level hook when unset.</p> <code>None</code> <p>Yields:</p> Name Type Description <code>StepResult</code> <code>StepResult</code> <p>One per executed node/step, carrying the produced states.</p> Notes <p>This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use <code>run_steps_async</code> for async nodes.</p>"},{"location":"engine/#dagpipe.engine.Engine.run_steps_async","title":"run_steps_async  <code>async</code>","text":"<pre><code>run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -&gt; AsyncIterator[StepResult]\n</code></pre> <p>Async variant of <code>run_steps</code> supporting <code>AsyncNode</code> execution.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <code>resume_from</code> <code>int | None</code> <p>Skip steps at index &lt; <code>resume_from</code>.</p> <code>None</code> <code>on_step</code> <code>AsyncStepHook | None</code> <p>Async callback <code>(step, status, message)</code> invoked per step.</p> <code>None</code> <p>Yields:</p> Name Type Description <code>StepResult</code> <code>AsyncIterator[StepResult]</code> <p>One per executed node/step.</p>"},{"location":"engine/#dagpipe.engine.ProgressMessage","title":"ProgressMessage","text":"<pre><code>ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n</code></pre> <p>Lightweight progress payload emitted by engine step hooks.</p> <p>Mirrors the imperative <code>ProgressMessage</code> used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.</p> <p>Attributes:</p> Name Type Description <code>lines</code> <code>int | None</code> <p>Optional count of processed lines.</p> <code>blocks</code> <code>int | None</code> <p>Optional count of processed blocks.</p> <code>count</code> <code>int | None</code> <p>Optional generic item count.</p> <code>unit</code> <code>str | None</code> <p>Optional unit for the count (e.g., 'pages').</p> <code>raw_ocr_line</code> <code>str | None</code> <p>Optional raw OCR line payload.</p> <code>error</code> <code>str | None</code> <p>Optional error description.</p> <code>step</code> <code>str</code> <p>Identifier of the step that emitted the message.</p> <code>status</code> <code>str</code> <p>Status label associated with the step.</p> Notes <p>Guarantees:</p> <pre><code>- Immutable after construction (attributes are never reassigned).\n- Independent of pydantic; safe to construct in the engine core.\n</code></pre> <p>Create a progress message.</p> <p>Parameters:</p> Name Type Description Default <code>lines</code> <code>int | None</code> <p>Optional count of processed lines.</p> <code>None</code> <code>blocks</code> <code>int | None</code> <p>Optional count of processed blocks.</p> <code>None</code> <code>count</code> <code>int | None</code> <p>Optional generic item count.</p> <code>None</code> <code>unit</code> <code>str | None</code> <p>Optional unit for the count (e.g., 'pages').</p> <code>None</code> <code>raw_ocr_line</code> <code>str | None</code> <p>Optional raw OCR line payload.</p> <code>None</code> <code>error</code> <code>str | None</code> <p>Optional error description.</p> <code>None</code> <code>step</code> <code>str</code> <p>Identifier of the step that emitted the message.</p> <code>''</code> <code>status</code> <code>str</code> <p>Status label associated with the step.</p> <code>''</code>"},{"location":"engine/#dagpipe.engine.ProgressMessage-functions","title":"Functions","text":""},{"location":"engine/#dagpipe.engine.ProgressMessage.as_dict","title":"as_dict","text":"<pre><code>as_dict() -&gt; dict[str, Any]\n</code></pre> <p>Return the message as a plain dictionary.</p> <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>dict[str, Any]: All attribute values keyed by their attribute name.</p>"},{"location":"engine/#dagpipe.engine.StepResult","title":"StepResult","text":"<pre><code>StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n</code></pre> <p>A single checkpointed step within an async/resumable engine run.</p> <p>Attributes:</p> Name Type Description <code>index</code> <code>int</code> <p>Ordinal index of the step.</p> <code>node_id</code> <code>str</code> <p>Identifier of the node associated with this step.</p> <code>states</code> <code>tuple[State, ...]</code> <p>States produced by running this step.</p> <code>completed</code> <code>bool</code> <p>Whether this step succeeded (vs. paused/interrupted).</p> <p>Initialise StepResult.</p> <p>Parameters:</p> Name Type Description Default <code>index</code> <code>int</code> <p>Ordinal index of the step.</p> required <code>node_id</code> <code>str</code> <p>Identifier of the node associated with this step.</p> required <code>states</code> <code>tuple[State, ...]</code> <p>States produced by running this step.</p> required <code>completed</code> <code>bool</code> <p>Whether this step succeeded (vs. paused/interrupted).</p> required"},{"location":"engine/#dagpipe.engine.StepResult-functions","title":"Functions","text":""},{"location":"graph/","title":"Graph","text":""},{"location":"graph/#dagpipe.graph","title":"dagpipe.graph","text":""},{"location":"graph/#dagpipe.graph--summary","title":"Summary","text":"<p>Defines DAG structure connecting nodes.</p> <p>A <code>Graph</code> describes execution topology only. It does not execute nodes or manage <code>State</code>. Execution is handled by an <code>Engine</code>.</p>"},{"location":"graph/#dagpipe.graph--responsibilities","title":"Responsibilities","text":"<ul> <li>Multiple roots, branching, and merging support.</li> <li>Deterministic traversal based on topology.</li> <li>Graph is mutable during construction but treated as immutable at runtime.</li> </ul>"},{"location":"graph/#dagpipe.graph-classes","title":"Classes","text":""},{"location":"graph/#dagpipe.graph.Graph","title":"Graph","text":"<pre><code>Graph()\n</code></pre> <p>Directed Acyclic Graph defining execution topology of <code>Node</code> objects.</p> Notes <p>Responsibilities:</p> <pre><code>- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n</code></pre> <p>Guarantees:</p> <pre><code>- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n</code></pre> <p>Create an empty Graph.</p> <p>Initializes node registry and edge mappings.</p>"},{"location":"graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return a compact graph description.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>A string describing the graph as <code>Graph(nodes=N, edges=M)</code> where <code>N</code> and <code>M</code> describe the current registry size.</p>"},{"location":"graph/#dagpipe.graph.Graph.add_edge","title":"add_edge","text":"<pre><code>add_edge(src: Node, dst: Node) -&gt; None\n</code></pre> <p>Add a directed edge from <code>src</code> to <code>dst</code>.</p> <p>Parameters:</p> Name Type Description Default <code>src</code> <code>Node</code> <p>Source node.</p> required <code>dst</code> <code>Node</code> <p>Destination node.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>src</code> or <code>dst</code> is not a <code>Node</code>.</p> <code>ValueError</code> <p>If the edge would create a cycle or if <code>src</code> and <code>dst</code> are common.</p> Notes <ul> <li>Validates node types.</li> <li>Prevents cycles.</li> <li>Registers nodes if not present.</li> <li>Updates parent and child mappings.</li> </ul>"},{"location":"graph/#dagpipe.graph.Graph.add_root","title":"add_root","text":"<pre><code>add_root(node: Node) -&gt; None\n</code></pre> <p>Add a root node with no parents.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to add as a root.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If node is not a Node instance.</p>"},{"location":"graph/#dagpipe.graph.Graph.children","title":"children","text":"<pre><code>children(node: Node) -&gt; tuple[Node, ...]\n</code></pre> <p>Return child nodes of a node.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to query.</p> required <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Outgoing neighbors.</p>"},{"location":"graph/#dagpipe.graph.Graph.nodes","title":"nodes","text":"<pre><code>nodes() -&gt; tuple[Node, ...]\n</code></pre> <p>Return all nodes in the graph.</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: All registered nodes.</p>"},{"location":"graph/#dagpipe.graph.Graph.parents","title":"parents","text":"<pre><code>parents(node: Node) -&gt; tuple[Node, ...]\n</code></pre> <p>Return parent nodes of a node.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to query.</p> required <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Incoming neighbors.</p>"},{"location":"graph/#dagpipe.graph.Graph.roots","title":"roots","text":"<pre><code>roots() -&gt; tuple[Node, ...]\n</code></pre> <p>Return root nodes (nodes with no incoming edges).</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Entry point nodes.</p>"},{"location":"node/","title":"Node","text":""},{"location":"node/#dagpipe.node","title":"dagpipe.node","text":""},{"location":"node/#dagpipe.node--summary","title":"Summary","text":"<p>Defines the <code>Node</code> abstraction used by <code>dagpipe</code>.</p> <p>A node represents a single unit of pipeline execution logic. It consumes one <code>State</code> and produces zero, one, or many new <code>State</code> objects.</p> <p>Nodes are connected using a <code>Graph</code> and executed by an <code>Engine</code>.</p>"},{"location":"node/#dagpipe.node--design-principles","title":"Design principles","text":"<ul> <li>Pure: Must not mutate input state.</li> <li>Deterministic: Same input produces same output.</li> <li>Stateless: Recommended to be stateless for reuse.</li> <li>Composable: Nodes enable branching execution graphs.</li> </ul>"},{"location":"node/#dagpipe.node-classes","title":"Classes","text":""},{"location":"node/#dagpipe.node.AsyncNode","title":"AsyncNode","text":"<p>               Bases: <code>Node</code></p> <p>Base class for nodes whose execution is asynchronous.</p> <p>Subclasses implement <code>resolve_async</code> (an async generator yielding derived <code>State</code> objects). The engine dispatches to <code>resolve_async</code> when running an async traversal (see <code>Engine.run_async</code>).</p> <p>Sync-only engines (and the base <code>Node.run</code>) treat an <code>AsyncNode</code> as a no-op consumer: calling <code>run</code> on an <code>AsyncNode</code> returns no states, signalling that an async engine is required.</p>"},{"location":"node/#dagpipe.node.AsyncNode-functions","title":"Functions","text":""},{"location":"node/#dagpipe.node.AsyncNode.__hash__","title":"__hash__","text":"<pre><code>__hash__() -&gt; int\n</code></pre> <p>Return stable hash based on node ID.</p> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Hash of the node ID, allowing nodes to be used as dict keys.</p>"},{"location":"node/#dagpipe.node.AsyncNode.__new__","title":"__new__","text":"<pre><code>__new__(*args: Any, **kwargs: Any) -&gt; AsyncNode\n</code></pre> <p>Create or reuse an async node instance.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Positional constructor arguments forwarded to <code>__init__</code>.</p> <code>()</code> <code>**kwargs</code> <code>Any</code> <p>Keyword constructor arguments forwarded to <code>__init__</code>.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>AsyncNode</code> <code>AsyncNode</code> <p>A fresh instance for subclasses declaring a parameterized <code>__init__</code>, or the shared singleton for stateless subclasses.</p>"},{"location":"node/#dagpipe.node.AsyncNode.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return computation identity based on node ID.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {id}&gt;</code>.</p>"},{"location":"node/#dagpipe.node.AsyncNode.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return user-facing display name.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {name}&gt;</code>.</p>"},{"location":"node/#dagpipe.node.AsyncNode.clean_id_and_name","title":"clean_id_and_name  <code>classmethod</code>","text":"<pre><code>clean_id_and_name() -&gt; None\n</code></pre> <p>Normalize and validate node ID and display name.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If ID is not a string.</p> <code>ValueError</code> <p>If ID format is invalid.</p> Notes <p>Guarantees:</p> <pre><code>- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n</code></pre>"},{"location":"node/#dagpipe.node.AsyncNode.fork","title":"fork","text":"<pre><code>fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -&gt; State\n</code></pre> <p>Create a child <code>State</code> attributed to this node.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Parent execution state.</p> required <code>payload_update</code> <code>Any</code> <p>Dot-path payload updates.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Confidence adjustment.</p> <code>0.0</code> <code>metadata_update</code> <code>Any</code> <p>Metadata updates.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>New child execution state.</p> Notes <p>Responsibilities:</p> <pre><code>- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n</code></pre>"},{"location":"node/#dagpipe.node.AsyncNode.is_async","title":"is_async","text":"<pre><code>is_async() -&gt; bool\n</code></pre> <p>Return whether this node executes asynchronously.</p> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the node is an <code>AsyncNode</code> instance.</p>"},{"location":"node/#dagpipe.node.AsyncNode.node_id_to_name","title":"node_id_to_name  <code>staticmethod</code>","text":"<pre><code>node_id_to_name(node_id: str) -&gt; str\n</code></pre> <p>Convert a dotted snake_case node ID into a human-readable name.</p> <p>Parameters:</p> Name Type Description Default <code>node_id</code> <code>str</code> <p>Unique node identifier (e.g., 'entity.resolve.numeric_merchant').</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').</p>"},{"location":"node/#dagpipe.node.AsyncNode.resolve","title":"resolve","text":"<pre><code>resolve(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute no-op resolution in sync contexts.</p> <p>Sync-only engines (and the base <code>Node.run</code>) treat an <code>AsyncNode</code> as a no-op consumer: this returns no states, signalling that an async engine is required.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Empty tuple, since async execution is handled by <code>resolve_async</code>.</p>"},{"location":"node/#dagpipe.node.AsyncNode.resolve_async","title":"resolve_async  <code>async</code>","text":"<pre><code>resolve_async(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute node logic asynchronously.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Derived execution state(s).</p> Notes <p>Guarantees:</p> <pre><code>- Subclasses implement this.\n- Must not mutate the input state.\n- Should use `fork()` to create child states.\n</code></pre>"},{"location":"node/#dagpipe.node.AsyncNode.run","title":"run","text":"<pre><code>run(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node on a <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve()</code> yields a non-<code>State</code> object.</p>"},{"location":"node/#dagpipe.node.AsyncNode.run_async","title":"run_async  <code>async</code>","text":"<pre><code>run_async(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node asynchronously on a state, validating outputs.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve_async()</code> yields a non-<code>State</code> object.</p>"},{"location":"node/#dagpipe.node.Node","title":"Node","text":"<p>               Bases: <code>ABC</code></p> <p>Base class for all dagpipe execution nodes.</p> <p>Attributes:</p> Name Type Description <code>id</code> <code>str</code> <p>Unique identifier of the node (snake_case dotted format).</p> <code>name</code> <code>str</code> <p>Human-readable display name.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre> <p>Guarantees:</p> <pre><code>- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n</code></pre>"},{"location":"node/#dagpipe.node.Node-functions","title":"Functions","text":""},{"location":"node/#dagpipe.node.Node.__hash__","title":"__hash__","text":"<pre><code>__hash__() -&gt; int\n</code></pre> <p>Return stable hash based on node ID.</p> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Hash of the node ID, allowing nodes to be used as dict keys.</p>"},{"location":"node/#dagpipe.node.Node.__new__","title":"__new__","text":"<pre><code>__new__(*args: Any, **kwargs: Any) -&gt; Node\n</code></pre> <p>Create or reuse a node instance.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Positional constructor arguments forwarded to <code>__init__</code>.</p> <code>()</code> <code>**kwargs</code> <code>Any</code> <p>Keyword constructor arguments forwarded to <code>__init__</code>.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>Node</code> <code>Node</code> <p>A fresh instance for subclasses declaring a parameterized <code>__init__</code>, or the shared singleton for stateless subclasses.</p> Notes <p>Guarantees:</p> <pre><code>- Stateless subclasses (no parameterized `__init__`) share one\n  singleton instance per class \u2014 matching the original dagpipe\n  behaviour underpinning `set_registry`-style configuration.\n- Subclasses that declare an `__init__` requiring instance-state\n  arguments get a fresh instance per construction so pipeline\n  builders can inject per-run dependencies.\n</code></pre>"},{"location":"node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return computation identity based on node ID.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {id}&gt;</code>.</p>"},{"location":"node/#dagpipe.node.Node.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return user-facing display name.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {name}&gt;</code>.</p>"},{"location":"node/#dagpipe.node.Node.clean_id_and_name","title":"clean_id_and_name  <code>classmethod</code>","text":"<pre><code>clean_id_and_name() -&gt; None\n</code></pre> <p>Normalize and validate node ID and display name.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If ID is not a string.</p> <code>ValueError</code> <p>If ID format is invalid.</p> Notes <p>Guarantees:</p> <pre><code>- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n</code></pre>"},{"location":"node/#dagpipe.node.Node.fork","title":"fork","text":"<pre><code>fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -&gt; State\n</code></pre> <p>Create a child <code>State</code> attributed to this node.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Parent execution state.</p> required <code>payload_update</code> <code>Any</code> <p>Dot-path payload updates.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Confidence adjustment.</p> <code>0.0</code> <code>metadata_update</code> <code>Any</code> <p>Metadata updates.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>New child execution state.</p> Notes <p>Responsibilities:</p> <pre><code>- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n</code></pre>"},{"location":"node/#dagpipe.node.Node.is_async","title":"is_async","text":"<pre><code>is_async() -&gt; bool\n</code></pre> <p>Return whether this node executes asynchronously.</p> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the node is an <code>AsyncNode</code> instance.</p>"},{"location":"node/#dagpipe.node.Node.node_id_to_name","title":"node_id_to_name  <code>staticmethod</code>","text":"<pre><code>node_id_to_name(node_id: str) -&gt; str\n</code></pre> <p>Convert a dotted snake_case node ID into a human-readable name.</p> <p>Parameters:</p> Name Type Description Default <code>node_id</code> <code>str</code> <p>Unique node identifier (e.g., 'entity.resolve.numeric_merchant').</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').</p>"},{"location":"node/#dagpipe.node.Node.resolve","title":"resolve  <code>abstractmethod</code>","text":"<pre><code>resolve(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute node logic.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Derived execution state(s).</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"node/#dagpipe.node.Node.run","title":"run","text":"<pre><code>run(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node on a <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve()</code> yields a non-<code>State</code> object.</p>"},{"location":"state/","title":"State","text":""},{"location":"state/#dagpipe.state","title":"dagpipe.state","text":""},{"location":"state/#dagpipe.state--summary","title":"Summary","text":"<p>Defines the core <code>State</code> object used by <code>dagpipe</code>.</p> <p>The <code>State</code> 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 <code>fork()</code>.</p>"},{"location":"state/#dagpipe.state--design-principles","title":"Design principles","text":"<ul> <li>Immutability: States must never be modified after creation.   All transformations must create a new state via <code>fork()</code>.</li> <li>Cheap cloning: Forking must be efficient since branching may create many states.</li> <li>Lineage tracking: Each state maintains a reference to its parent and   execution metadata for debugging and observability.</li> <li>Domain agnostic: State contains generic key-value data and does not   assume any schema.</li> <li>Engine-friendly: State contains execution metadata such as depth and history.</li> </ul>"},{"location":"state/#dagpipe.state-classes","title":"Classes","text":""},{"location":"state/#dagpipe.state.Payload","title":"Payload  <code>dataclass</code>","text":"<pre><code>Payload(_data: Mapping[str, Any])\n</code></pre> <p>Immutable hierarchical container with dot-path access.</p> <p>Attributes:</p> Name Type Description <code>_data</code> <code>Mapping[str, Any]</code> <p>Immutable hierarchical data structure.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"state/#dagpipe.state.Payload-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Payload.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return a concise payload description.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>Payload(keys=[...])</code> listing top-level keys.</p>"},{"location":"state/#dagpipe.state.Payload.as_dict","title":"as_dict","text":"<pre><code>as_dict() -&gt; Mapping[str, Any]\n</code></pre> <p>Return underlying mapping.</p> <p>Returns:</p> Type Description <code>Mapping[str, Any]</code> <p>Mapping[str, Any]: Read-only view of the underlying data.</p>"},{"location":"state/#dagpipe.state.Payload.get","title":"get","text":"<pre><code>get(path: str, default: Any = None) -&gt; Any\n</code></pre> <p>Retrieve value using dot-path.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dot-separated path to the value.</p> required <code>default</code> <code>Any</code> <p>Default value if path doesn't exist.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>The retrieved value or default.</p>"},{"location":"state/#dagpipe.state.Payload.has","title":"has","text":"<pre><code>has(path: str) -&gt; bool\n</code></pre> <p>Return True if path exists.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dot-separated path to check.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>Existence of the path.</p>"},{"location":"state/#dagpipe.state.Payload.iter_paths","title":"iter_paths  <code>classmethod</code>","text":"<pre><code>iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -&gt; Iterable[str]\n</code></pre> <p>Recursively yield dot-paths for all leaf nodes.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>Mapping[str, Any]</code> <p>The mapping to iterate over.</p> required <code>prefix</code> <code>str</code> <p>Current path prefix.</p> <code>''</code> <p>Yields:</p> Name Type Description <code>str</code> <code>Iterable[str]</code> <p>Dot-path for each leaf node.</p>"},{"location":"state/#dagpipe.state.Payload.keys","title":"keys","text":"<pre><code>keys() -&gt; Iterable[str]\n</code></pre> <p>Return top-level keys.</p> <p>Returns:</p> Type Description <code>Iterable[str]</code> <p>Iterable[str]: Iterator over top-level keys.</p>"},{"location":"state/#dagpipe.state.Payload.update","title":"update","text":"<pre><code>update(updates: Mapping[str, Any]) -&gt; Payload\n</code></pre> <p>Create a new <code>Payload</code> with dot-path updates applied.</p> <p>Parameters:</p> Name Type Description Default <code>updates</code> <code>Mapping[str, Any]</code> <p>Dot-path to value mapping.</p> required <p>Returns:</p> Name Type Description <code>Payload</code> <code>Payload</code> <p>New immutable payload instance with updates.</p> Notes <p>Guarantees:</p> <pre><code>- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n</code></pre>"},{"location":"state/#dagpipe.state.Schema","title":"Schema  <code>dataclass</code>","text":"<pre><code>Schema(tree: Mapping[str, SchemaNode])\n</code></pre> <p>Immutable hierarchical schema defining allowed payload structure.</p> <p>Attributes:</p> Name Type Description <code>tree</code> <code>Mapping[str, SchemaNode]</code> <p>Hierarchical schema definition.</p> Notes <p>Responsibilities:</p> <pre><code>- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n</code></pre>"},{"location":"state/#dagpipe.state.Schema-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Schema.validate_payload","title":"validate_payload","text":"<pre><code>validate_payload(payload: Payload) -&gt; None\n</code></pre> <p>Validate complete payload structure.</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>Payload</code> <p>Payload to validate.</p> required <p>Raises:</p> Type Description <code>SchemaError</code> <p>If payload violates schema.</p>"},{"location":"state/#dagpipe.state.Schema.validate_update","title":"validate_update","text":"<pre><code>validate_update(updates: Mapping[str, Any]) -&gt; None\n</code></pre> <p>Validate payload update paths.</p> <p>Parameters:</p> Name Type Description Default <code>updates</code> <code>Mapping[str, Any]</code> <p>Dot-path updates to validate.</p> required <p>Raises:</p> Type Description <code>SchemaError</code> <p>If any path is invalid according to the schema.</p>"},{"location":"state/#dagpipe.state.SchemaError","title":"SchemaError","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when payload data violates the declared schema.</p> <p>Indicates invalid structure, invalid path, or invalid type.</p>"},{"location":"state/#dagpipe.state.State","title":"State  <code>dataclass</code>","text":"<pre><code>State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n</code></pre> <p>Immutable execution state propagated through dagpipe pipeline.</p> <p>Attributes:</p> Name Type Description <code>payload</code> <code>Payload</code> <p>Execution data container.</p> <code>schema</code> <code>ClassVar[Schema]</code> <p>Payload validation schema.</p> <code>confidence</code> <code>float</code> <p>Execution confidence score.</p> <code>parent</code> <code>Optional[State]</code> <p>Parent state reference.</p> <code>depth</code> <code>int</code> <p>Execution depth.</p> <code>history</code> <code>Tuple[str, ...]</code> <p>Ordered node execution lineage.</p> <code>metadata</code> <code>Dict[str, Any]</code> <p>Execution metadata.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"state/#dagpipe.state.State-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.State.__post_init__","title":"__post_init__","text":"<pre><code>__post_init__() -&gt; None\n</code></pre> <p>Validate the payload against the declared schema.</p> <p>Raises:</p> Type Description <code>SchemaError</code> <p>If the payload violates the schema declared on the subclass.</p>"},{"location":"state/#dagpipe.state.State.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Concise debug representation.</p> <p>Avoids printing full data for large states.</p>"},{"location":"state/#dagpipe.state.State.fork","title":"fork","text":"<pre><code>fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -&gt; State\n</code></pre> <p>Create a new child <code>State</code> derived from this state.</p> <p>Parameters:</p> Name Type Description Default <code>payload_update</code> <code>Mapping[str, Any] | None</code> <p>Dot-path updates applied to the payload.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Adjustment applied to current confidence.</p> <code>0.0</code> <code>node_id</code> <code>str | None</code> <p>Identifier of the node creating this state.</p> <code>None</code> <code>metadata_update</code> <code>Mapping[str, Any] | None</code> <p>Updates merged into state metadata.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>A new immutable <code>State</code> instance.</p> Notes <p>Guarantees:</p> <pre><code>- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n</code></pre>"},{"location":"state/#dagpipe.state.State.get","title":"get","text":"<pre><code>get(key: str, default: Any = None) -&gt; Any\n</code></pre> <p>Retrieve payload value.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>Dot-path key.</p> required <code>default</code> <code>Any</code> <p>Fallback value.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>Stored value or default.</p>"},{"location":"state/#dagpipe.state.State.has","title":"has","text":"<pre><code>has(key: str) -&gt; bool\n</code></pre> <p>Check whether payload contains key.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>Dot-path key.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>Existence of the key.</p>"},{"location":"state/#dagpipe.state.State.lineage","title":"lineage","text":"<pre><code>lineage() -&gt; tuple[State, ...]\n</code></pre> <p>Return lineage from root to this State.</p> <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Ordered execution lineage (root first).</p>"},{"location":"yaml_loader/","title":"Yaml Loader","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader","title":"dagpipe.yaml_loader","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"<p>Loads dagpipe pipelines from YAML configuration.</p> <p>Creates fully configured pipeline objects from declarative YAML definitions, including <code>Schema</code>, <code>State</code> subclasses, <code>Node</code> instances, <code>Graph</code> topology, and initial payloads.</p>"},{"location":"yaml_loader/#dagpipe.yaml_loader-classes","title":"Classes","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline","title":"Pipeline  <code>dataclass</code>","text":"<pre><code>Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n</code></pre> <p>Executable pipeline created from YAML configuration.</p> <p>Attributes:</p> Name Type Description <code>engine</code> <code>Engine</code> <p>Execution engine responsible for running the pipeline.</p> <code>state_cls</code> <code>Type[State]</code> <p>Dynamically created <code>State</code> subclass with configured schema.</p> <code>initial_payload</code> <code>Payload</code> <p>Default payload used when execution begins.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline.run","title":"run","text":"<pre><code>run(\n    payload_override: Mapping[str, Any] | None = None,\n) -&gt; list[State]\n</code></pre> <p>Execute the pipeline.</p> <p>Parameters:</p> Name Type Description Default <code>payload_override</code> <code>Mapping[str, Any] | None</code> <p>Payload values overriding initial payload.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states.</p> Notes <p>Responsibilities:</p> <pre><code>- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n</code></pre>"},{"location":"yaml_loader/#dagpipe.yaml_loader-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.load_pipeline","title":"load_pipeline","text":"<pre><code>load_pipeline(path: str) -&gt; Pipeline\n</code></pre> <p>Load pipeline from YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Path to YAML configuration file.</p> required <p>Returns:</p> Name Type Description <code>Pipeline</code> <code>Pipeline</code> <p>Executable pipeline instance.</p> Notes <p>Responsibilities:</p> <pre><code>- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n</code></pre>"},{"location":"dagpipe/","title":"Dagpipe","text":"<ul> <li>Engine</li> <li>Graph</li> <li>Node</li> <li>State</li> <li>Yaml Loader</li> </ul>"},{"location":"dagpipe/#dagpipe","title":"dagpipe","text":""},{"location":"dagpipe/#dagpipe--summary","title":"Summary","text":"<p>Directed acyclic graph execution framework for deterministic state propagation.</p> <p><code>dagpipe</code> executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable <code>State</code> and optionally produces derived states for downstream nodes.</p>"},{"location":"dagpipe/#dagpipe--installation","title":"Installation","text":"<p>Install using pip:</p> <pre><code>pip install dagpipe\n</code></pre>"},{"location":"dagpipe/#dagpipe--quick-start","title":"Quick Start","text":"<pre><code>from dagpipe import State, Payload, Schema, Graph, Engine\nfrom dagpipe.node import Node\n\nclass HelloNode(Node):\n    id = \"hello\"\n    def resolve(self, state):\n        yield self.fork(state, payload_update={\"msg\": \"hello\"})\n\n# Build and run\ngraph = Graph()\ngraph.add_root(HelloNode())\nengine = Engine(graph)\n\nclass MyState(State):\n    schema = Schema({})\n\nresults = engine.run(MyState(payload=Payload({})))\n</code></pre>"},{"location":"dagpipe/#dagpipe--public-api","title":"Public API","text":"<p>This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.</p>"},{"location":"dagpipe/#dagpipe--execution-core","title":"Execution Core","text":"<ul> <li><code>Engine</code>: Responsible for orchestrating node execution and state propagation.</li> <li><code>Graph</code>: Defines the execution topology and node relationships.</li> <li><code>Node</code>: Base class for defining execution logic and transformations.</li> </ul>"},{"location":"dagpipe/#dagpipe--state-data","title":"State &amp; Data","text":"<ul> <li><code>State</code>: Represents an immutable execution snapshot at a point in time.</li> <li><code>Payload</code>: Immutable hierarchical container for execution data.</li> <li><code>Schema</code>: Defines and validates the allowed structure of payloads.</li> <li><code>SchemaError</code>: Raised when data violates the declared schema.</li> </ul>"},{"location":"dagpipe/#dagpipe--declarative-pipelines","title":"Declarative Pipelines","text":"<ul> <li><code>Pipeline</code>: High-level wrapper for an engine, state type, and initial payload.</li> <li><code>load_pipeline</code>: Factory function to create a pipeline from YAML.</li> </ul>"},{"location":"dagpipe/#dagpipe-classes","title":"Classes","text":""},{"location":"dagpipe/#dagpipe.AsyncNode","title":"AsyncNode","text":"<p>               Bases: <code>Node</code></p> <p>Base class for nodes whose execution is asynchronous.</p> <p>Subclasses implement <code>resolve_async</code> (an async generator yielding derived <code>State</code> objects). The engine dispatches to <code>resolve_async</code> when running an async traversal (see <code>Engine.run_async</code>).</p> <p>Sync-only engines (and the base <code>Node.run</code>) treat an <code>AsyncNode</code> as a no-op consumer: calling <code>run</code> on an <code>AsyncNode</code> returns no states, signalling that an async engine is required.</p>"},{"location":"dagpipe/#dagpipe.AsyncNode-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.AsyncNode.__hash__","title":"__hash__","text":"<pre><code>__hash__() -&gt; int\n</code></pre> <p>Return stable hash based on node ID.</p> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Hash of the node ID, allowing nodes to be used as dict keys.</p>"},{"location":"dagpipe/#dagpipe.AsyncNode.__new__","title":"__new__","text":"<pre><code>__new__(*args: Any, **kwargs: Any) -&gt; AsyncNode\n</code></pre> <p>Create or reuse an async node instance.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Positional constructor arguments forwarded to <code>__init__</code>.</p> <code>()</code> <code>**kwargs</code> <code>Any</code> <p>Keyword constructor arguments forwarded to <code>__init__</code>.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>AsyncNode</code> <code>AsyncNode</code> <p>A fresh instance for subclasses declaring a parameterized <code>__init__</code>, or the shared singleton for stateless subclasses.</p>"},{"location":"dagpipe/#dagpipe.AsyncNode.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return computation identity based on node ID.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {id}&gt;</code>.</p>"},{"location":"dagpipe/#dagpipe.AsyncNode.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return user-facing display name.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {name}&gt;</code>.</p>"},{"location":"dagpipe/#dagpipe.AsyncNode.clean_id_and_name","title":"clean_id_and_name  <code>classmethod</code>","text":"<pre><code>clean_id_and_name() -&gt; None\n</code></pre> <p>Normalize and validate node ID and display name.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If ID is not a string.</p> <code>ValueError</code> <p>If ID format is invalid.</p> Notes <p>Guarantees:</p> <pre><code>- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n</code></pre>"},{"location":"dagpipe/#dagpipe.AsyncNode.fork","title":"fork","text":"<pre><code>fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -&gt; State\n</code></pre> <p>Create a child <code>State</code> attributed to this node.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Parent execution state.</p> required <code>payload_update</code> <code>Any</code> <p>Dot-path payload updates.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Confidence adjustment.</p> <code>0.0</code> <code>metadata_update</code> <code>Any</code> <p>Metadata updates.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>New child execution state.</p> Notes <p>Responsibilities:</p> <pre><code>- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n</code></pre>"},{"location":"dagpipe/#dagpipe.AsyncNode.is_async","title":"is_async","text":"<pre><code>is_async() -&gt; bool\n</code></pre> <p>Return whether this node executes asynchronously.</p> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the node is an <code>AsyncNode</code> instance.</p>"},{"location":"dagpipe/#dagpipe.AsyncNode.node_id_to_name","title":"node_id_to_name  <code>staticmethod</code>","text":"<pre><code>node_id_to_name(node_id: str) -&gt; str\n</code></pre> <p>Convert a dotted snake_case node ID into a human-readable name.</p> <p>Parameters:</p> Name Type Description Default <code>node_id</code> <code>str</code> <p>Unique node identifier (e.g., 'entity.resolve.numeric_merchant').</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').</p>"},{"location":"dagpipe/#dagpipe.AsyncNode.resolve","title":"resolve","text":"<pre><code>resolve(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute no-op resolution in sync contexts.</p> <p>Sync-only engines (and the base <code>Node.run</code>) treat an <code>AsyncNode</code> as a no-op consumer: this returns no states, signalling that an async engine is required.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Empty tuple, since async execution is handled by <code>resolve_async</code>.</p>"},{"location":"dagpipe/#dagpipe.AsyncNode.resolve_async","title":"resolve_async  <code>async</code>","text":"<pre><code>resolve_async(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute node logic asynchronously.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Derived execution state(s).</p> Notes <p>Guarantees:</p> <pre><code>- Subclasses implement this.\n- Must not mutate the input state.\n- Should use `fork()` to create child states.\n</code></pre>"},{"location":"dagpipe/#dagpipe.AsyncNode.run","title":"run","text":"<pre><code>run(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node on a <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve()</code> yields a non-<code>State</code> object.</p>"},{"location":"dagpipe/#dagpipe.AsyncNode.run_async","title":"run_async  <code>async</code>","text":"<pre><code>run_async(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node asynchronously on a state, validating outputs.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve_async()</code> yields a non-<code>State</code> object.</p>"},{"location":"dagpipe/#dagpipe.Engine","title":"Engine","text":"<pre><code>Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n</code></pre> <p>Execution engine responsible for running pipeline logic.</p> Notes <p>Responsibilities:</p> <pre><code>- 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- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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</code></pre> <p>Create an engine from a node sequence or a graph.</p> <p>Parameters:</p> Name Type Description Default <code>nodes_or_graph</code> <code>Sequence[Node] | Graph</code> <p>Either an ordered sequence of <code>Node</code> instances (linear mode) or a <code>Graph</code> defining the execution topology (graph mode).</p> required <code>on_step</code> <code>StepHook | None</code> <p>Default per-step callback <code>(step, status, message)</code> used when a step run does not supply its own hook.</p> <code>None</code> <p>Raises:</p> Type Description <code>TypeError</code> <p>If a sequence element is not a <code>Node</code>, or if <code>nodes_or_graph</code> is neither a <code>Sequence[Node]</code> nor a <code>Graph</code>.</p>"},{"location":"dagpipe/#dagpipe.Engine-attributes","title":"Attributes","text":""},{"location":"dagpipe/#dagpipe.Engine.nodes","title":"nodes  <code>property</code>","text":"<pre><code>nodes: tuple[Node, ...]\n</code></pre> <p>Return nodes managed by this engine.</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.</p>"},{"location":"dagpipe/#dagpipe.Engine-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Engine.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return the canonical string representation of the object.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Representation that uniquely identifies the object and its configuration.</p>"},{"location":"dagpipe/#dagpipe.Engine.run","title":"run","text":"<pre><code>run(root: State) -&gt; list[State]\n</code></pre> <p>Execute the pipeline starting from a root <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states produced by the pipeline.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>root</code> is not a <code>State</code> instance.</p> <code>RuntimeError</code> <p>If the engine execution mode is invalid.</p> Notes <p>Responsibilities:</p> <pre><code>- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n</code></pre>"},{"location":"dagpipe/#dagpipe.Engine.run_async","title":"run_async  <code>async</code>","text":"<pre><code>run_async(root: State) -&gt; list[State]\n</code></pre> <p>Execute the pipeline starting from <code>root</code>, dispatching sync vs async nodes.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states produced by the pipeline.</p> Notes <p>Each node is executed with <code>Node.run</code> when synchronous and <code>AsyncNode.run_async</code> when asynchronous. Linear and graph topologies are both supported.</p>"},{"location":"dagpipe/#dagpipe.Engine.run_steps","title":"run_steps","text":"<pre><code>run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -&gt; Iterator[StepResult]\n</code></pre> <p>Execute the pipeline step-by-step, yielding one <code>StepResult</code> per step.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <code>resume_from</code> <code>int | None</code> <p>Skip steps at index &lt; <code>resume_from</code> (for resume-after-partial). Steps are 0-indexed.</p> <code>None</code> <code>on_step</code> <code>StepHook | None</code> <p>Callback <code>(step, status, message)</code> invoked per step; falls back to the engine-level hook when unset.</p> <code>None</code> <p>Yields:</p> Name Type Description <code>StepResult</code> <code>StepResult</code> <p>One per executed node/step, carrying the produced states.</p> Notes <p>This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use <code>run_steps_async</code> for async nodes.</p>"},{"location":"dagpipe/#dagpipe.Engine.run_steps_async","title":"run_steps_async  <code>async</code>","text":"<pre><code>run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -&gt; AsyncIterator[StepResult]\n</code></pre> <p>Async variant of <code>run_steps</code> supporting <code>AsyncNode</code> execution.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <code>resume_from</code> <code>int | None</code> <p>Skip steps at index &lt; <code>resume_from</code>.</p> <code>None</code> <code>on_step</code> <code>AsyncStepHook | None</code> <p>Async callback <code>(step, status, message)</code> invoked per step.</p> <code>None</code> <p>Yields:</p> Name Type Description <code>StepResult</code> <code>AsyncIterator[StepResult]</code> <p>One per executed node/step.</p>"},{"location":"dagpipe/#dagpipe.Graph","title":"Graph","text":"<pre><code>Graph()\n</code></pre> <p>Directed Acyclic Graph defining execution topology of <code>Node</code> objects.</p> Notes <p>Responsibilities:</p> <pre><code>- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n</code></pre> <p>Guarantees:</p> <pre><code>- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n</code></pre> <p>Create an empty Graph.</p> <p>Initializes node registry and edge mappings.</p>"},{"location":"dagpipe/#dagpipe.Graph-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Graph.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return a compact graph description.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>A string describing the graph as <code>Graph(nodes=N, edges=M)</code> where <code>N</code> and <code>M</code> describe the current registry size.</p>"},{"location":"dagpipe/#dagpipe.Graph.add_edge","title":"add_edge","text":"<pre><code>add_edge(src: Node, dst: Node) -&gt; None\n</code></pre> <p>Add a directed edge from <code>src</code> to <code>dst</code>.</p> <p>Parameters:</p> Name Type Description Default <code>src</code> <code>Node</code> <p>Source node.</p> required <code>dst</code> <code>Node</code> <p>Destination node.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>src</code> or <code>dst</code> is not a <code>Node</code>.</p> <code>ValueError</code> <p>If the edge would create a cycle or if <code>src</code> and <code>dst</code> are common.</p> Notes <ul> <li>Validates node types.</li> <li>Prevents cycles.</li> <li>Registers nodes if not present.</li> <li>Updates parent and child mappings.</li> </ul>"},{"location":"dagpipe/#dagpipe.Graph.add_root","title":"add_root","text":"<pre><code>add_root(node: Node) -&gt; None\n</code></pre> <p>Add a root node with no parents.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to add as a root.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If node is not a Node instance.</p>"},{"location":"dagpipe/#dagpipe.Graph.children","title":"children","text":"<pre><code>children(node: Node) -&gt; tuple[Node, ...]\n</code></pre> <p>Return child nodes of a node.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to query.</p> required <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Outgoing neighbors.</p>"},{"location":"dagpipe/#dagpipe.Graph.nodes","title":"nodes","text":"<pre><code>nodes() -&gt; tuple[Node, ...]\n</code></pre> <p>Return all nodes in the graph.</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: All registered nodes.</p>"},{"location":"dagpipe/#dagpipe.Graph.parents","title":"parents","text":"<pre><code>parents(node: Node) -&gt; tuple[Node, ...]\n</code></pre> <p>Return parent nodes of a node.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to query.</p> required <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Incoming neighbors.</p>"},{"location":"dagpipe/#dagpipe.Graph.roots","title":"roots","text":"<pre><code>roots() -&gt; tuple[Node, ...]\n</code></pre> <p>Return root nodes (nodes with no incoming edges).</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Entry point nodes.</p>"},{"location":"dagpipe/#dagpipe.Node","title":"Node","text":"<p>               Bases: <code>ABC</code></p> <p>Base class for all dagpipe execution nodes.</p> <p>Attributes:</p> Name Type Description <code>id</code> <code>str</code> <p>Unique identifier of the node (snake_case dotted format).</p> <code>name</code> <code>str</code> <p>Human-readable display name.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre> <p>Guarantees:</p> <pre><code>- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n</code></pre>"},{"location":"dagpipe/#dagpipe.Node-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Node.__hash__","title":"__hash__","text":"<pre><code>__hash__() -&gt; int\n</code></pre> <p>Return stable hash based on node ID.</p> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Hash of the node ID, allowing nodes to be used as dict keys.</p>"},{"location":"dagpipe/#dagpipe.Node.__new__","title":"__new__","text":"<pre><code>__new__(*args: Any, **kwargs: Any) -&gt; Node\n</code></pre> <p>Create or reuse a node instance.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Positional constructor arguments forwarded to <code>__init__</code>.</p> <code>()</code> <code>**kwargs</code> <code>Any</code> <p>Keyword constructor arguments forwarded to <code>__init__</code>.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>Node</code> <code>Node</code> <p>A fresh instance for subclasses declaring a parameterized <code>__init__</code>, or the shared singleton for stateless subclasses.</p> Notes <p>Guarantees:</p> <pre><code>- Stateless subclasses (no parameterized `__init__`) share one\n  singleton instance per class \u2014 matching the original dagpipe\n  behaviour underpinning `set_registry`-style configuration.\n- Subclasses that declare an `__init__` requiring instance-state\n  arguments get a fresh instance per construction so pipeline\n  builders can inject per-run dependencies.\n</code></pre>"},{"location":"dagpipe/#dagpipe.Node.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return computation identity based on node ID.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {id}&gt;</code>.</p>"},{"location":"dagpipe/#dagpipe.Node.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return user-facing display name.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {name}&gt;</code>.</p>"},{"location":"dagpipe/#dagpipe.Node.clean_id_and_name","title":"clean_id_and_name  <code>classmethod</code>","text":"<pre><code>clean_id_and_name() -&gt; None\n</code></pre> <p>Normalize and validate node ID and display name.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If ID is not a string.</p> <code>ValueError</code> <p>If ID format is invalid.</p> Notes <p>Guarantees:</p> <pre><code>- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n</code></pre>"},{"location":"dagpipe/#dagpipe.Node.fork","title":"fork","text":"<pre><code>fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -&gt; State\n</code></pre> <p>Create a child <code>State</code> attributed to this node.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Parent execution state.</p> required <code>payload_update</code> <code>Any</code> <p>Dot-path payload updates.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Confidence adjustment.</p> <code>0.0</code> <code>metadata_update</code> <code>Any</code> <p>Metadata updates.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>New child execution state.</p> Notes <p>Responsibilities:</p> <pre><code>- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n</code></pre>"},{"location":"dagpipe/#dagpipe.Node.is_async","title":"is_async","text":"<pre><code>is_async() -&gt; bool\n</code></pre> <p>Return whether this node executes asynchronously.</p> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the node is an <code>AsyncNode</code> instance.</p>"},{"location":"dagpipe/#dagpipe.Node.node_id_to_name","title":"node_id_to_name  <code>staticmethod</code>","text":"<pre><code>node_id_to_name(node_id: str) -&gt; str\n</code></pre> <p>Convert a dotted snake_case node ID into a human-readable name.</p> <p>Parameters:</p> Name Type Description Default <code>node_id</code> <code>str</code> <p>Unique node identifier (e.g., 'entity.resolve.numeric_merchant').</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').</p>"},{"location":"dagpipe/#dagpipe.Node.resolve","title":"resolve  <code>abstractmethod</code>","text":"<pre><code>resolve(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute node logic.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Derived execution state(s).</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"dagpipe/#dagpipe.Node.run","title":"run","text":"<pre><code>run(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node on a <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve()</code> yields a non-<code>State</code> object.</p>"},{"location":"dagpipe/#dagpipe.Payload","title":"Payload  <code>dataclass</code>","text":"<pre><code>Payload(_data: Mapping[str, Any])\n</code></pre> <p>Immutable hierarchical container with dot-path access.</p> <p>Attributes:</p> Name Type Description <code>_data</code> <code>Mapping[str, Any]</code> <p>Immutable hierarchical data structure.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"dagpipe/#dagpipe.Payload-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Payload.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return a concise payload description.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>Payload(keys=[...])</code> listing top-level keys.</p>"},{"location":"dagpipe/#dagpipe.Payload.as_dict","title":"as_dict","text":"<pre><code>as_dict() -&gt; Mapping[str, Any]\n</code></pre> <p>Return underlying mapping.</p> <p>Returns:</p> Type Description <code>Mapping[str, Any]</code> <p>Mapping[str, Any]: Read-only view of the underlying data.</p>"},{"location":"dagpipe/#dagpipe.Payload.get","title":"get","text":"<pre><code>get(path: str, default: Any = None) -&gt; Any\n</code></pre> <p>Retrieve value using dot-path.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dot-separated path to the value.</p> required <code>default</code> <code>Any</code> <p>Default value if path doesn't exist.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>The retrieved value or default.</p>"},{"location":"dagpipe/#dagpipe.Payload.has","title":"has","text":"<pre><code>has(path: str) -&gt; bool\n</code></pre> <p>Return True if path exists.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dot-separated path to check.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>Existence of the path.</p>"},{"location":"dagpipe/#dagpipe.Payload.iter_paths","title":"iter_paths  <code>classmethod</code>","text":"<pre><code>iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -&gt; Iterable[str]\n</code></pre> <p>Recursively yield dot-paths for all leaf nodes.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>Mapping[str, Any]</code> <p>The mapping to iterate over.</p> required <code>prefix</code> <code>str</code> <p>Current path prefix.</p> <code>''</code> <p>Yields:</p> Name Type Description <code>str</code> <code>Iterable[str]</code> <p>Dot-path for each leaf node.</p>"},{"location":"dagpipe/#dagpipe.Payload.keys","title":"keys","text":"<pre><code>keys() -&gt; Iterable[str]\n</code></pre> <p>Return top-level keys.</p> <p>Returns:</p> Type Description <code>Iterable[str]</code> <p>Iterable[str]: Iterator over top-level keys.</p>"},{"location":"dagpipe/#dagpipe.Payload.update","title":"update","text":"<pre><code>update(updates: Mapping[str, Any]) -&gt; Payload\n</code></pre> <p>Create a new <code>Payload</code> with dot-path updates applied.</p> <p>Parameters:</p> Name Type Description Default <code>updates</code> <code>Mapping[str, Any]</code> <p>Dot-path to value mapping.</p> required <p>Returns:</p> Name Type Description <code>Payload</code> <code>Payload</code> <p>New immutable payload instance with updates.</p> Notes <p>Guarantees:</p> <pre><code>- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n</code></pre>"},{"location":"dagpipe/#dagpipe.Pipeline","title":"Pipeline  <code>dataclass</code>","text":"<pre><code>Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n</code></pre> <p>Executable pipeline created from YAML configuration.</p> <p>Attributes:</p> Name Type Description <code>engine</code> <code>Engine</code> <p>Execution engine responsible for running the pipeline.</p> <code>state_cls</code> <code>Type[State]</code> <p>Dynamically created <code>State</code> subclass with configured schema.</p> <code>initial_payload</code> <code>Payload</code> <p>Default payload used when execution begins.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"dagpipe/#dagpipe.Pipeline-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Pipeline.run","title":"run","text":"<pre><code>run(\n    payload_override: Mapping[str, Any] | None = None,\n) -&gt; list[State]\n</code></pre> <p>Execute the pipeline.</p> <p>Parameters:</p> Name Type Description Default <code>payload_override</code> <code>Mapping[str, Any] | None</code> <p>Payload values overriding initial payload.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states.</p> Notes <p>Responsibilities:</p> <pre><code>- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n</code></pre>"},{"location":"dagpipe/#dagpipe.ProgressMessage","title":"ProgressMessage","text":"<pre><code>ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n</code></pre> <p>Lightweight progress payload emitted by engine step hooks.</p> <p>Mirrors the imperative <code>ProgressMessage</code> used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.</p> <p>Attributes:</p> Name Type Description <code>lines</code> <code>int | None</code> <p>Optional count of processed lines.</p> <code>blocks</code> <code>int | None</code> <p>Optional count of processed blocks.</p> <code>count</code> <code>int | None</code> <p>Optional generic item count.</p> <code>unit</code> <code>str | None</code> <p>Optional unit for the count (e.g., 'pages').</p> <code>raw_ocr_line</code> <code>str | None</code> <p>Optional raw OCR line payload.</p> <code>error</code> <code>str | None</code> <p>Optional error description.</p> <code>step</code> <code>str</code> <p>Identifier of the step that emitted the message.</p> <code>status</code> <code>str</code> <p>Status label associated with the step.</p> Notes <p>Guarantees:</p> <pre><code>- Immutable after construction (attributes are never reassigned).\n- Independent of pydantic; safe to construct in the engine core.\n</code></pre> <p>Create a progress message.</p> <p>Parameters:</p> Name Type Description Default <code>lines</code> <code>int | None</code> <p>Optional count of processed lines.</p> <code>None</code> <code>blocks</code> <code>int | None</code> <p>Optional count of processed blocks.</p> <code>None</code> <code>count</code> <code>int | None</code> <p>Optional generic item count.</p> <code>None</code> <code>unit</code> <code>str | None</code> <p>Optional unit for the count (e.g., 'pages').</p> <code>None</code> <code>raw_ocr_line</code> <code>str | None</code> <p>Optional raw OCR line payload.</p> <code>None</code> <code>error</code> <code>str | None</code> <p>Optional error description.</p> <code>None</code> <code>step</code> <code>str</code> <p>Identifier of the step that emitted the message.</p> <code>''</code> <code>status</code> <code>str</code> <p>Status label associated with the step.</p> <code>''</code>"},{"location":"dagpipe/#dagpipe.ProgressMessage-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.ProgressMessage.as_dict","title":"as_dict","text":"<pre><code>as_dict() -&gt; dict[str, Any]\n</code></pre> <p>Return the message as a plain dictionary.</p> <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>dict[str, Any]: All attribute values keyed by their attribute name.</p>"},{"location":"dagpipe/#dagpipe.Schema","title":"Schema  <code>dataclass</code>","text":"<pre><code>Schema(tree: Mapping[str, SchemaNode])\n</code></pre> <p>Immutable hierarchical schema defining allowed payload structure.</p> <p>Attributes:</p> Name Type Description <code>tree</code> <code>Mapping[str, SchemaNode]</code> <p>Hierarchical schema definition.</p> Notes <p>Responsibilities:</p> <pre><code>- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n</code></pre>"},{"location":"dagpipe/#dagpipe.Schema-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Schema.validate_payload","title":"validate_payload","text":"<pre><code>validate_payload(payload: Payload) -&gt; None\n</code></pre> <p>Validate complete payload structure.</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>Payload</code> <p>Payload to validate.</p> required <p>Raises:</p> Type Description <code>SchemaError</code> <p>If payload violates schema.</p>"},{"location":"dagpipe/#dagpipe.Schema.validate_update","title":"validate_update","text":"<pre><code>validate_update(updates: Mapping[str, Any]) -&gt; None\n</code></pre> <p>Validate payload update paths.</p> <p>Parameters:</p> Name Type Description Default <code>updates</code> <code>Mapping[str, Any]</code> <p>Dot-path updates to validate.</p> required <p>Raises:</p> Type Description <code>SchemaError</code> <p>If any path is invalid according to the schema.</p>"},{"location":"dagpipe/#dagpipe.SchemaError","title":"SchemaError","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when payload data violates the declared schema.</p> <p>Indicates invalid structure, invalid path, or invalid type.</p>"},{"location":"dagpipe/#dagpipe.State","title":"State  <code>dataclass</code>","text":"<pre><code>State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n</code></pre> <p>Immutable execution state propagated through dagpipe pipeline.</p> <p>Attributes:</p> Name Type Description <code>payload</code> <code>Payload</code> <p>Execution data container.</p> <code>schema</code> <code>ClassVar[Schema]</code> <p>Payload validation schema.</p> <code>confidence</code> <code>float</code> <p>Execution confidence score.</p> <code>parent</code> <code>Optional[State]</code> <p>Parent state reference.</p> <code>depth</code> <code>int</code> <p>Execution depth.</p> <code>history</code> <code>Tuple[str, ...]</code> <p>Ordered node execution lineage.</p> <code>metadata</code> <code>Dict[str, Any]</code> <p>Execution metadata.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"dagpipe/#dagpipe.State-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.State.__post_init__","title":"__post_init__","text":"<pre><code>__post_init__() -&gt; None\n</code></pre> <p>Validate the payload against the declared schema.</p> <p>Raises:</p> Type Description <code>SchemaError</code> <p>If the payload violates the schema declared on the subclass.</p>"},{"location":"dagpipe/#dagpipe.State.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Concise debug representation.</p> <p>Avoids printing full data for large states.</p>"},{"location":"dagpipe/#dagpipe.State.fork","title":"fork","text":"<pre><code>fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -&gt; State\n</code></pre> <p>Create a new child <code>State</code> derived from this state.</p> <p>Parameters:</p> Name Type Description Default <code>payload_update</code> <code>Mapping[str, Any] | None</code> <p>Dot-path updates applied to the payload.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Adjustment applied to current confidence.</p> <code>0.0</code> <code>node_id</code> <code>str | None</code> <p>Identifier of the node creating this state.</p> <code>None</code> <code>metadata_update</code> <code>Mapping[str, Any] | None</code> <p>Updates merged into state metadata.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>A new immutable <code>State</code> instance.</p> Notes <p>Guarantees:</p> <pre><code>- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n</code></pre>"},{"location":"dagpipe/#dagpipe.State.get","title":"get","text":"<pre><code>get(key: str, default: Any = None) -&gt; Any\n</code></pre> <p>Retrieve payload value.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>Dot-path key.</p> required <code>default</code> <code>Any</code> <p>Fallback value.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>Stored value or default.</p>"},{"location":"dagpipe/#dagpipe.State.has","title":"has","text":"<pre><code>has(key: str) -&gt; bool\n</code></pre> <p>Check whether payload contains key.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>Dot-path key.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>Existence of the key.</p>"},{"location":"dagpipe/#dagpipe.State.lineage","title":"lineage","text":"<pre><code>lineage() -&gt; tuple[State, ...]\n</code></pre> <p>Return lineage from root to this State.</p> <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Ordered execution lineage (root first).</p>"},{"location":"dagpipe/#dagpipe.StepResult","title":"StepResult","text":"<pre><code>StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n</code></pre> <p>A single checkpointed step within an async/resumable engine run.</p> <p>Attributes:</p> Name Type Description <code>index</code> <code>int</code> <p>Ordinal index of the step.</p> <code>node_id</code> <code>str</code> <p>Identifier of the node associated with this step.</p> <code>states</code> <code>tuple[State, ...]</code> <p>States produced by running this step.</p> <code>completed</code> <code>bool</code> <p>Whether this step succeeded (vs. paused/interrupted).</p> <p>Initialise StepResult.</p> <p>Parameters:</p> Name Type Description Default <code>index</code> <code>int</code> <p>Ordinal index of the step.</p> required <code>node_id</code> <code>str</code> <p>Identifier of the node associated with this step.</p> required <code>states</code> <code>tuple[State, ...]</code> <p>States produced by running this step.</p> required <code>completed</code> <code>bool</code> <p>Whether this step succeeded (vs. paused/interrupted).</p> required"},{"location":"dagpipe/#dagpipe.StepResult-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.load_pipeline","title":"load_pipeline","text":"<pre><code>load_pipeline(path: str) -&gt; Pipeline\n</code></pre> <p>Load pipeline from YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Path to YAML configuration file.</p> required <p>Returns:</p> Name Type Description <code>Pipeline</code> <code>Pipeline</code> <p>Executable pipeline instance.</p> Notes <p>Responsibilities:</p> <pre><code>- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n</code></pre>"},{"location":"dagpipe/engine/","title":"Engine","text":""},{"location":"dagpipe/engine/#dagpipe.engine","title":"dagpipe.engine","text":""},{"location":"dagpipe/engine/#dagpipe.engine--summary","title":"Summary","text":"<p>Execution engine responsible for running pipelines and graphs.</p> <p>The <code>Engine</code> executes <code>Node</code> objects and propagates immutable <code>State</code> instances through either a linear sequence or a directed acyclic graph (<code>Graph</code>). It orchestrates execution order, branching, and state propagation.</p>"},{"location":"dagpipe/engine/#dagpipe.engine--guarantees","title":"Guarantees","text":"<ul> <li>Deterministic execution and consistent state lineage.</li> <li>Orchestrates execution without modifying <code>Graph</code>, <code>Node</code>, or <code>State</code> objects.</li> </ul>"},{"location":"dagpipe/engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine","title":"Engine","text":"<pre><code>Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n</code></pre> <p>Execution engine responsible for running pipeline logic.</p> Notes <p>Responsibilities:</p> <pre><code>- 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- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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</code></pre> <p>Create an engine from a node sequence or a graph.</p> <p>Parameters:</p> Name Type Description Default <code>nodes_or_graph</code> <code>Sequence[Node] | Graph</code> <p>Either an ordered sequence of <code>Node</code> instances (linear mode) or a <code>Graph</code> defining the execution topology (graph mode).</p> required <code>on_step</code> <code>StepHook | None</code> <p>Default per-step callback <code>(step, status, message)</code> used when a step run does not supply its own hook.</p> <code>None</code> <p>Raises:</p> Type Description <code>TypeError</code> <p>If a sequence element is not a <code>Node</code>, or if <code>nodes_or_graph</code> is neither a <code>Sequence[Node]</code> nor a <code>Graph</code>.</p>"},{"location":"dagpipe/engine/#dagpipe.engine.Engine-attributes","title":"Attributes","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine.nodes","title":"nodes  <code>property</code>","text":"<pre><code>nodes: tuple[Node, ...]\n</code></pre> <p>Return nodes managed by this engine.</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.</p>"},{"location":"dagpipe/engine/#dagpipe.engine.Engine-functions","title":"Functions","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return the canonical string representation of the object.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Representation that uniquely identifies the object and its configuration.</p>"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run","title":"run","text":"<pre><code>run(root: State) -&gt; list[State]\n</code></pre> <p>Execute the pipeline starting from a root <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states produced by the pipeline.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>root</code> is not a <code>State</code> instance.</p> <code>RuntimeError</code> <p>If the engine execution mode is invalid.</p> Notes <p>Responsibilities:</p> <pre><code>- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n</code></pre>"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run_async","title":"run_async  <code>async</code>","text":"<pre><code>run_async(root: State) -&gt; list[State]\n</code></pre> <p>Execute the pipeline starting from <code>root</code>, dispatching sync vs async nodes.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states produced by the pipeline.</p> Notes <p>Each node is executed with <code>Node.run</code> when synchronous and <code>AsyncNode.run_async</code> when asynchronous. Linear and graph topologies are both supported.</p>"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run_steps","title":"run_steps","text":"<pre><code>run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -&gt; Iterator[StepResult]\n</code></pre> <p>Execute the pipeline step-by-step, yielding one <code>StepResult</code> per step.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <code>resume_from</code> <code>int | None</code> <p>Skip steps at index &lt; <code>resume_from</code> (for resume-after-partial). Steps are 0-indexed.</p> <code>None</code> <code>on_step</code> <code>StepHook | None</code> <p>Callback <code>(step, status, message)</code> invoked per step; falls back to the engine-level hook when unset.</p> <code>None</code> <p>Yields:</p> Name Type Description <code>StepResult</code> <code>StepResult</code> <p>One per executed node/step, carrying the produced states.</p> Notes <p>This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use <code>run_steps_async</code> for async nodes.</p>"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run_steps_async","title":"run_steps_async  <code>async</code>","text":"<pre><code>run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -&gt; AsyncIterator[StepResult]\n</code></pre> <p>Async variant of <code>run_steps</code> supporting <code>AsyncNode</code> execution.</p> <p>Parameters:</p> Name Type Description Default <code>root</code> <code>State</code> <p>Initial execution state.</p> required <code>resume_from</code> <code>int | None</code> <p>Skip steps at index &lt; <code>resume_from</code>.</p> <code>None</code> <code>on_step</code> <code>AsyncStepHook | None</code> <p>Async callback <code>(step, status, message)</code> invoked per step.</p> <code>None</code> <p>Yields:</p> Name Type Description <code>StepResult</code> <code>AsyncIterator[StepResult]</code> <p>One per executed node/step.</p>"},{"location":"dagpipe/engine/#dagpipe.engine.ProgressMessage","title":"ProgressMessage","text":"<pre><code>ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n</code></pre> <p>Lightweight progress payload emitted by engine step hooks.</p> <p>Mirrors the imperative <code>ProgressMessage</code> used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.</p> <p>Attributes:</p> Name Type Description <code>lines</code> <code>int | None</code> <p>Optional count of processed lines.</p> <code>blocks</code> <code>int | None</code> <p>Optional count of processed blocks.</p> <code>count</code> <code>int | None</code> <p>Optional generic item count.</p> <code>unit</code> <code>str | None</code> <p>Optional unit for the count (e.g., 'pages').</p> <code>raw_ocr_line</code> <code>str | None</code> <p>Optional raw OCR line payload.</p> <code>error</code> <code>str | None</code> <p>Optional error description.</p> <code>step</code> <code>str</code> <p>Identifier of the step that emitted the message.</p> <code>status</code> <code>str</code> <p>Status label associated with the step.</p> Notes <p>Guarantees:</p> <pre><code>- Immutable after construction (attributes are never reassigned).\n- Independent of pydantic; safe to construct in the engine core.\n</code></pre> <p>Create a progress message.</p> <p>Parameters:</p> Name Type Description Default <code>lines</code> <code>int | None</code> <p>Optional count of processed lines.</p> <code>None</code> <code>blocks</code> <code>int | None</code> <p>Optional count of processed blocks.</p> <code>None</code> <code>count</code> <code>int | None</code> <p>Optional generic item count.</p> <code>None</code> <code>unit</code> <code>str | None</code> <p>Optional unit for the count (e.g., 'pages').</p> <code>None</code> <code>raw_ocr_line</code> <code>str | None</code> <p>Optional raw OCR line payload.</p> <code>None</code> <code>error</code> <code>str | None</code> <p>Optional error description.</p> <code>None</code> <code>step</code> <code>str</code> <p>Identifier of the step that emitted the message.</p> <code>''</code> <code>status</code> <code>str</code> <p>Status label associated with the step.</p> <code>''</code>"},{"location":"dagpipe/engine/#dagpipe.engine.ProgressMessage-functions","title":"Functions","text":""},{"location":"dagpipe/engine/#dagpipe.engine.ProgressMessage.as_dict","title":"as_dict","text":"<pre><code>as_dict() -&gt; dict[str, Any]\n</code></pre> <p>Return the message as a plain dictionary.</p> <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>dict[str, Any]: All attribute values keyed by their attribute name.</p>"},{"location":"dagpipe/engine/#dagpipe.engine.StepResult","title":"StepResult","text":"<pre><code>StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n</code></pre> <p>A single checkpointed step within an async/resumable engine run.</p> <p>Attributes:</p> Name Type Description <code>index</code> <code>int</code> <p>Ordinal index of the step.</p> <code>node_id</code> <code>str</code> <p>Identifier of the node associated with this step.</p> <code>states</code> <code>tuple[State, ...]</code> <p>States produced by running this step.</p> <code>completed</code> <code>bool</code> <p>Whether this step succeeded (vs. paused/interrupted).</p> <p>Initialise StepResult.</p> <p>Parameters:</p> Name Type Description Default <code>index</code> <code>int</code> <p>Ordinal index of the step.</p> required <code>node_id</code> <code>str</code> <p>Identifier of the node associated with this step.</p> required <code>states</code> <code>tuple[State, ...]</code> <p>States produced by running this step.</p> required <code>completed</code> <code>bool</code> <p>Whether this step succeeded (vs. paused/interrupted).</p> required"},{"location":"dagpipe/engine/#dagpipe.engine.StepResult-functions","title":"Functions","text":""},{"location":"dagpipe/graph/","title":"Graph","text":""},{"location":"dagpipe/graph/#dagpipe.graph","title":"dagpipe.graph","text":""},{"location":"dagpipe/graph/#dagpipe.graph--summary","title":"Summary","text":"<p>Defines DAG structure connecting nodes.</p> <p>A <code>Graph</code> describes execution topology only. It does not execute nodes or manage <code>State</code>. Execution is handled by an <code>Engine</code>.</p>"},{"location":"dagpipe/graph/#dagpipe.graph--responsibilities","title":"Responsibilities","text":"<ul> <li>Multiple roots, branching, and merging support.</li> <li>Deterministic traversal based on topology.</li> <li>Graph is mutable during construction but treated as immutable at runtime.</li> </ul>"},{"location":"dagpipe/graph/#dagpipe.graph-classes","title":"Classes","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph","title":"Graph","text":"<pre><code>Graph()\n</code></pre> <p>Directed Acyclic Graph defining execution topology of <code>Node</code> objects.</p> Notes <p>Responsibilities:</p> <pre><code>- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n</code></pre> <p>Guarantees:</p> <pre><code>- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n</code></pre> <p>Create an empty Graph.</p> <p>Initializes node registry and edge mappings.</p>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return a compact graph description.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>A string describing the graph as <code>Graph(nodes=N, edges=M)</code> where <code>N</code> and <code>M</code> describe the current registry size.</p>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge","title":"add_edge","text":"<pre><code>add_edge(src: Node, dst: Node) -&gt; None\n</code></pre> <p>Add a directed edge from <code>src</code> to <code>dst</code>.</p> <p>Parameters:</p> Name Type Description Default <code>src</code> <code>Node</code> <p>Source node.</p> required <code>dst</code> <code>Node</code> <p>Destination node.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>src</code> or <code>dst</code> is not a <code>Node</code>.</p> <code>ValueError</code> <p>If the edge would create a cycle or if <code>src</code> and <code>dst</code> are common.</p> Notes <ul> <li>Validates node types.</li> <li>Prevents cycles.</li> <li>Registers nodes if not present.</li> <li>Updates parent and child mappings.</li> </ul>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_root","title":"add_root","text":"<pre><code>add_root(node: Node) -&gt; None\n</code></pre> <p>Add a root node with no parents.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to add as a root.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If node is not a Node instance.</p>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.children","title":"children","text":"<pre><code>children(node: Node) -&gt; tuple[Node, ...]\n</code></pre> <p>Return child nodes of a node.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to query.</p> required <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Outgoing neighbors.</p>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.nodes","title":"nodes","text":"<pre><code>nodes() -&gt; tuple[Node, ...]\n</code></pre> <p>Return all nodes in the graph.</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: All registered nodes.</p>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.parents","title":"parents","text":"<pre><code>parents(node: Node) -&gt; tuple[Node, ...]\n</code></pre> <p>Return parent nodes of a node.</p> <p>Parameters:</p> Name Type Description Default <code>node</code> <code>Node</code> <p>Node to query.</p> required <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Incoming neighbors.</p>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.roots","title":"roots","text":"<pre><code>roots() -&gt; tuple[Node, ...]\n</code></pre> <p>Return root nodes (nodes with no incoming edges).</p> <p>Returns:</p> Type Description <code>tuple[Node, ...]</code> <p>tuple[Node, ...]: Entry point nodes.</p>"},{"location":"dagpipe/node/","title":"Node","text":""},{"location":"dagpipe/node/#dagpipe.node","title":"dagpipe.node","text":""},{"location":"dagpipe/node/#dagpipe.node--summary","title":"Summary","text":"<p>Defines the <code>Node</code> abstraction used by <code>dagpipe</code>.</p> <p>A node represents a single unit of pipeline execution logic. It consumes one <code>State</code> and produces zero, one, or many new <code>State</code> objects.</p> <p>Nodes are connected using a <code>Graph</code> and executed by an <code>Engine</code>.</p>"},{"location":"dagpipe/node/#dagpipe.node--design-principles","title":"Design principles","text":"<ul> <li>Pure: Must not mutate input state.</li> <li>Deterministic: Same input produces same output.</li> <li>Stateless: Recommended to be stateless for reuse.</li> <li>Composable: Nodes enable branching execution graphs.</li> </ul>"},{"location":"dagpipe/node/#dagpipe.node-classes","title":"Classes","text":""},{"location":"dagpipe/node/#dagpipe.node.AsyncNode","title":"AsyncNode","text":"<p>               Bases: <code>Node</code></p> <p>Base class for nodes whose execution is asynchronous.</p> <p>Subclasses implement <code>resolve_async</code> (an async generator yielding derived <code>State</code> objects). The engine dispatches to <code>resolve_async</code> when running an async traversal (see <code>Engine.run_async</code>).</p> <p>Sync-only engines (and the base <code>Node.run</code>) treat an <code>AsyncNode</code> as a no-op consumer: calling <code>run</code> on an <code>AsyncNode</code> returns no states, signalling that an async engine is required.</p>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode-functions","title":"Functions","text":""},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__hash__","title":"__hash__","text":"<pre><code>__hash__() -&gt; int\n</code></pre> <p>Return stable hash based on node ID.</p> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Hash of the node ID, allowing nodes to be used as dict keys.</p>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__new__","title":"__new__","text":"<pre><code>__new__(*args: Any, **kwargs: Any) -&gt; AsyncNode\n</code></pre> <p>Create or reuse an async node instance.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Positional constructor arguments forwarded to <code>__init__</code>.</p> <code>()</code> <code>**kwargs</code> <code>Any</code> <p>Keyword constructor arguments forwarded to <code>__init__</code>.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>AsyncNode</code> <code>AsyncNode</code> <p>A fresh instance for subclasses declaring a parameterized <code>__init__</code>, or the shared singleton for stateless subclasses.</p>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return computation identity based on node ID.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {id}&gt;</code>.</p>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return user-facing display name.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {name}&gt;</code>.</p>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.clean_id_and_name","title":"clean_id_and_name  <code>classmethod</code>","text":"<pre><code>clean_id_and_name() -&gt; None\n</code></pre> <p>Normalize and validate node ID and display name.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If ID is not a string.</p> <code>ValueError</code> <p>If ID format is invalid.</p> Notes <p>Guarantees:</p> <pre><code>- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n</code></pre>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.fork","title":"fork","text":"<pre><code>fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -&gt; State\n</code></pre> <p>Create a child <code>State</code> attributed to this node.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Parent execution state.</p> required <code>payload_update</code> <code>Any</code> <p>Dot-path payload updates.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Confidence adjustment.</p> <code>0.0</code> <code>metadata_update</code> <code>Any</code> <p>Metadata updates.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>New child execution state.</p> Notes <p>Responsibilities:</p> <pre><code>- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n</code></pre>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.is_async","title":"is_async","text":"<pre><code>is_async() -&gt; bool\n</code></pre> <p>Return whether this node executes asynchronously.</p> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the node is an <code>AsyncNode</code> instance.</p>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.node_id_to_name","title":"node_id_to_name  <code>staticmethod</code>","text":"<pre><code>node_id_to_name(node_id: str) -&gt; str\n</code></pre> <p>Convert a dotted snake_case node ID into a human-readable name.</p> <p>Parameters:</p> Name Type Description Default <code>node_id</code> <code>str</code> <p>Unique node identifier (e.g., 'entity.resolve.numeric_merchant').</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').</p>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.resolve","title":"resolve","text":"<pre><code>resolve(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute no-op resolution in sync contexts.</p> <p>Sync-only engines (and the base <code>Node.run</code>) treat an <code>AsyncNode</code> as a no-op consumer: this returns no states, signalling that an async engine is required.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Empty tuple, since async execution is handled by <code>resolve_async</code>.</p>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.resolve_async","title":"resolve_async  <code>async</code>","text":"<pre><code>resolve_async(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute node logic asynchronously.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Derived execution state(s).</p> Notes <p>Guarantees:</p> <pre><code>- Subclasses implement this.\n- Must not mutate the input state.\n- Should use `fork()` to create child states.\n</code></pre>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.run","title":"run","text":"<pre><code>run(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node on a <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve()</code> yields a non-<code>State</code> object.</p>"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.run_async","title":"run_async  <code>async</code>","text":"<pre><code>run_async(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node asynchronously on a state, validating outputs.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve_async()</code> yields a non-<code>State</code> object.</p>"},{"location":"dagpipe/node/#dagpipe.node.Node","title":"Node","text":"<p>               Bases: <code>ABC</code></p> <p>Base class for all dagpipe execution nodes.</p> <p>Attributes:</p> Name Type Description <code>id</code> <code>str</code> <p>Unique identifier of the node (snake_case dotted format).</p> <code>name</code> <code>str</code> <p>Human-readable display name.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre> <p>Guarantees:</p> <pre><code>- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n</code></pre>"},{"location":"dagpipe/node/#dagpipe.node.Node-functions","title":"Functions","text":""},{"location":"dagpipe/node/#dagpipe.node.Node.__hash__","title":"__hash__","text":"<pre><code>__hash__() -&gt; int\n</code></pre> <p>Return stable hash based on node ID.</p> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>Hash of the node ID, allowing nodes to be used as dict keys.</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.__new__","title":"__new__","text":"<pre><code>__new__(*args: Any, **kwargs: Any) -&gt; Node\n</code></pre> <p>Create or reuse a node instance.</p> <p>Parameters:</p> Name Type Description Default <code>*args</code> <code>Any</code> <p>Positional constructor arguments forwarded to <code>__init__</code>.</p> <code>()</code> <code>**kwargs</code> <code>Any</code> <p>Keyword constructor arguments forwarded to <code>__init__</code>.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>Node</code> <code>Node</code> <p>A fresh instance for subclasses declaring a parameterized <code>__init__</code>, or the shared singleton for stateless subclasses.</p> Notes <p>Guarantees:</p> <pre><code>- Stateless subclasses (no parameterized `__init__`) share one\n  singleton instance per class \u2014 matching the original dagpipe\n  behaviour underpinning `set_registry`-style configuration.\n- Subclasses that declare an `__init__` requiring instance-state\n  arguments get a fresh instance per construction so pipeline\n  builders can inject per-run dependencies.\n</code></pre>"},{"location":"dagpipe/node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return computation identity based on node ID.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {id}&gt;</code>.</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return user-facing display name.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>&lt;Node {name}&gt;</code>.</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.clean_id_and_name","title":"clean_id_and_name  <code>classmethod</code>","text":"<pre><code>clean_id_and_name() -&gt; None\n</code></pre> <p>Normalize and validate node ID and display name.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If ID is not a string.</p> <code>ValueError</code> <p>If ID format is invalid.</p> Notes <p>Guarantees:</p> <pre><code>- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n</code></pre>"},{"location":"dagpipe/node/#dagpipe.node.Node.fork","title":"fork","text":"<pre><code>fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -&gt; State\n</code></pre> <p>Create a child <code>State</code> attributed to this node.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Parent execution state.</p> required <code>payload_update</code> <code>Any</code> <p>Dot-path payload updates.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Confidence adjustment.</p> <code>0.0</code> <code>metadata_update</code> <code>Any</code> <p>Metadata updates.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>New child execution state.</p> Notes <p>Responsibilities:</p> <pre><code>- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n</code></pre>"},{"location":"dagpipe/node/#dagpipe.node.Node.is_async","title":"is_async","text":"<pre><code>is_async() -&gt; bool\n</code></pre> <p>Return whether this node executes asynchronously.</p> <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>True if the node is an <code>AsyncNode</code> instance.</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.node_id_to_name","title":"node_id_to_name  <code>staticmethod</code>","text":"<pre><code>node_id_to_name(node_id: str) -&gt; str\n</code></pre> <p>Convert a dotted snake_case node ID into a human-readable name.</p> <p>Parameters:</p> Name Type Description Default <code>node_id</code> <code>str</code> <p>Unique node identifier (e.g., 'entity.resolve.numeric_merchant').</p> required <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.resolve","title":"resolve  <code>abstractmethod</code>","text":"<pre><code>resolve(state: State) -&gt; Iterable[State]\n</code></pre> <p>Execute node logic.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>Iterable[State]</code> <p>Iterable[State]: Derived execution state(s).</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"dagpipe/node/#dagpipe.node.Node.run","title":"run","text":"<pre><code>run(state: State) -&gt; tuple[State, ...]\n</code></pre> <p>Execute this node on a <code>State</code>.</p> <p>Parameters:</p> Name Type Description Default <code>state</code> <code>State</code> <p>Input execution state.</p> required <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Derived execution states.</p> <p>Raises:</p> Type Description <code>TypeError</code> <p>If <code>resolve()</code> yields a non-<code>State</code> object.</p>"},{"location":"dagpipe/state/","title":"State","text":""},{"location":"dagpipe/state/#dagpipe.state","title":"dagpipe.state","text":""},{"location":"dagpipe/state/#dagpipe.state--summary","title":"Summary","text":"<p>Defines the core <code>State</code> object used by <code>dagpipe</code>.</p> <p>The <code>State</code> 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 <code>fork()</code>.</p>"},{"location":"dagpipe/state/#dagpipe.state--design-principles","title":"Design principles","text":"<ul> <li>Immutability: States must never be modified after creation.   All transformations must create a new state via <code>fork()</code>.</li> <li>Cheap cloning: Forking must be efficient since branching may create many states.</li> <li>Lineage tracking: Each state maintains a reference to its parent and   execution metadata for debugging and observability.</li> <li>Domain agnostic: State contains generic key-value data and does not   assume any schema.</li> <li>Engine-friendly: State contains execution metadata such as depth and history.</li> </ul>"},{"location":"dagpipe/state/#dagpipe.state-classes","title":"Classes","text":""},{"location":"dagpipe/state/#dagpipe.state.Payload","title":"Payload  <code>dataclass</code>","text":"<pre><code>Payload(_data: Mapping[str, Any])\n</code></pre> <p>Immutable hierarchical container with dot-path access.</p> <p>Attributes:</p> Name Type Description <code>_data</code> <code>Mapping[str, Any]</code> <p>Immutable hierarchical data structure.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"dagpipe/state/#dagpipe.state.Payload-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.Payload.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return a concise payload description.</p> <p>Returns:</p> Name Type Description <code>str</code> <code>str</code> <p>String of the form <code>Payload(keys=[...])</code> listing top-level keys.</p>"},{"location":"dagpipe/state/#dagpipe.state.Payload.as_dict","title":"as_dict","text":"<pre><code>as_dict() -&gt; Mapping[str, Any]\n</code></pre> <p>Return underlying mapping.</p> <p>Returns:</p> Type Description <code>Mapping[str, Any]</code> <p>Mapping[str, Any]: Read-only view of the underlying data.</p>"},{"location":"dagpipe/state/#dagpipe.state.Payload.get","title":"get","text":"<pre><code>get(path: str, default: Any = None) -&gt; Any\n</code></pre> <p>Retrieve value using dot-path.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dot-separated path to the value.</p> required <code>default</code> <code>Any</code> <p>Default value if path doesn't exist.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>The retrieved value or default.</p>"},{"location":"dagpipe/state/#dagpipe.state.Payload.has","title":"has","text":"<pre><code>has(path: str) -&gt; bool\n</code></pre> <p>Return True if path exists.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Dot-separated path to check.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>Existence of the path.</p>"},{"location":"dagpipe/state/#dagpipe.state.Payload.iter_paths","title":"iter_paths  <code>classmethod</code>","text":"<pre><code>iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -&gt; Iterable[str]\n</code></pre> <p>Recursively yield dot-paths for all leaf nodes.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>Mapping[str, Any]</code> <p>The mapping to iterate over.</p> required <code>prefix</code> <code>str</code> <p>Current path prefix.</p> <code>''</code> <p>Yields:</p> Name Type Description <code>str</code> <code>Iterable[str]</code> <p>Dot-path for each leaf node.</p>"},{"location":"dagpipe/state/#dagpipe.state.Payload.keys","title":"keys","text":"<pre><code>keys() -&gt; Iterable[str]\n</code></pre> <p>Return top-level keys.</p> <p>Returns:</p> Type Description <code>Iterable[str]</code> <p>Iterable[str]: Iterator over top-level keys.</p>"},{"location":"dagpipe/state/#dagpipe.state.Payload.update","title":"update","text":"<pre><code>update(updates: Mapping[str, Any]) -&gt; Payload\n</code></pre> <p>Create a new <code>Payload</code> with dot-path updates applied.</p> <p>Parameters:</p> Name Type Description Default <code>updates</code> <code>Mapping[str, Any]</code> <p>Dot-path to value mapping.</p> required <p>Returns:</p> Name Type Description <code>Payload</code> <code>Payload</code> <p>New immutable payload instance with updates.</p> Notes <p>Guarantees:</p> <pre><code>- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n</code></pre>"},{"location":"dagpipe/state/#dagpipe.state.Schema","title":"Schema  <code>dataclass</code>","text":"<pre><code>Schema(tree: Mapping[str, SchemaNode])\n</code></pre> <p>Immutable hierarchical schema defining allowed payload structure.</p> <p>Attributes:</p> Name Type Description <code>tree</code> <code>Mapping[str, SchemaNode]</code> <p>Hierarchical schema definition.</p> Notes <p>Responsibilities:</p> <pre><code>- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n</code></pre>"},{"location":"dagpipe/state/#dagpipe.state.Schema-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.Schema.validate_payload","title":"validate_payload","text":"<pre><code>validate_payload(payload: Payload) -&gt; None\n</code></pre> <p>Validate complete payload structure.</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>Payload</code> <p>Payload to validate.</p> required <p>Raises:</p> Type Description <code>SchemaError</code> <p>If payload violates schema.</p>"},{"location":"dagpipe/state/#dagpipe.state.Schema.validate_update","title":"validate_update","text":"<pre><code>validate_update(updates: Mapping[str, Any]) -&gt; None\n</code></pre> <p>Validate payload update paths.</p> <p>Parameters:</p> Name Type Description Default <code>updates</code> <code>Mapping[str, Any]</code> <p>Dot-path updates to validate.</p> required <p>Raises:</p> Type Description <code>SchemaError</code> <p>If any path is invalid according to the schema.</p>"},{"location":"dagpipe/state/#dagpipe.state.SchemaError","title":"SchemaError","text":"<p>               Bases: <code>Exception</code></p> <p>Raised when payload data violates the declared schema.</p> <p>Indicates invalid structure, invalid path, or invalid type.</p>"},{"location":"dagpipe/state/#dagpipe.state.State","title":"State  <code>dataclass</code>","text":"<pre><code>State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n</code></pre> <p>Immutable execution state propagated through dagpipe pipeline.</p> <p>Attributes:</p> Name Type Description <code>payload</code> <code>Payload</code> <p>Execution data container.</p> <code>schema</code> <code>ClassVar[Schema]</code> <p>Payload validation schema.</p> <code>confidence</code> <code>float</code> <p>Execution confidence score.</p> <code>parent</code> <code>Optional[State]</code> <p>Parent state reference.</p> <code>depth</code> <code>int</code> <p>Execution depth.</p> <code>history</code> <code>Tuple[str, ...]</code> <p>Ordered node execution lineage.</p> <code>metadata</code> <code>Dict[str, Any]</code> <p>Execution metadata.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"dagpipe/state/#dagpipe.state.State-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.State.__post_init__","title":"__post_init__","text":"<pre><code>__post_init__() -&gt; None\n</code></pre> <p>Validate the payload against the declared schema.</p> <p>Raises:</p> Type Description <code>SchemaError</code> <p>If the payload violates the schema declared on the subclass.</p>"},{"location":"dagpipe/state/#dagpipe.state.State.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Concise debug representation.</p> <p>Avoids printing full data for large states.</p>"},{"location":"dagpipe/state/#dagpipe.state.State.fork","title":"fork","text":"<pre><code>fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -&gt; State\n</code></pre> <p>Create a new child <code>State</code> derived from this state.</p> <p>Parameters:</p> Name Type Description Default <code>payload_update</code> <code>Mapping[str, Any] | None</code> <p>Dot-path updates applied to the payload.</p> <code>None</code> <code>confidence_delta</code> <code>float</code> <p>Adjustment applied to current confidence.</p> <code>0.0</code> <code>node_id</code> <code>str | None</code> <p>Identifier of the node creating this state.</p> <code>None</code> <code>metadata_update</code> <code>Mapping[str, Any] | None</code> <p>Updates merged into state metadata.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>State</code> <code>State</code> <p>A new immutable <code>State</code> instance.</p> Notes <p>Guarantees:</p> <pre><code>- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n</code></pre>"},{"location":"dagpipe/state/#dagpipe.state.State.get","title":"get","text":"<pre><code>get(key: str, default: Any = None) -&gt; Any\n</code></pre> <p>Retrieve payload value.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>Dot-path key.</p> required <code>default</code> <code>Any</code> <p>Fallback value.</p> <code>None</code> <p>Returns:</p> Name Type Description <code>Any</code> <code>Any</code> <p>Stored value or default.</p>"},{"location":"dagpipe/state/#dagpipe.state.State.has","title":"has","text":"<pre><code>has(key: str) -&gt; bool\n</code></pre> <p>Check whether payload contains key.</p> <p>Parameters:</p> Name Type Description Default <code>key</code> <code>str</code> <p>Dot-path key.</p> required <p>Returns:</p> Name Type Description <code>bool</code> <code>bool</code> <p>Existence of the key.</p>"},{"location":"dagpipe/state/#dagpipe.state.State.lineage","title":"lineage","text":"<pre><code>lineage() -&gt; tuple[State, ...]\n</code></pre> <p>Return lineage from root to this State.</p> <p>Returns:</p> Type Description <code>tuple[State, ...]</code> <p>tuple[State, ...]: Ordered execution lineage (root first).</p>"},{"location":"dagpipe/yaml_loader/","title":"Yaml Loader","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader","title":"dagpipe.yaml_loader","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"<p>Loads dagpipe pipelines from YAML configuration.</p> <p>Creates fully configured pipeline objects from declarative YAML definitions, including <code>Schema</code>, <code>State</code> subclasses, <code>Node</code> instances, <code>Graph</code> topology, and initial payloads.</p>"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader-classes","title":"Classes","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline","title":"Pipeline  <code>dataclass</code>","text":"<pre><code>Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n</code></pre> <p>Executable pipeline created from YAML configuration.</p> <p>Attributes:</p> Name Type Description <code>engine</code> <code>Engine</code> <p>Execution engine responsible for running the pipeline.</p> <code>state_cls</code> <code>Type[State]</code> <p>Dynamically created <code>State</code> subclass with configured schema.</p> <code>initial_payload</code> <code>Payload</code> <p>Default payload used when execution begins.</p> Notes <p>Responsibilities:</p> <pre><code>- 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</code></pre>"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline-functions","title":"Functions","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline.run","title":"run","text":"<pre><code>run(\n    payload_override: Mapping[str, Any] | None = None,\n) -&gt; list[State]\n</code></pre> <p>Execute the pipeline.</p> <p>Parameters:</p> Name Type Description Default <code>payload_override</code> <code>Mapping[str, Any] | None</code> <p>Payload values overriding initial payload.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[State]</code> <p>list[State]: Terminal execution states.</p> Notes <p>Responsibilities:</p> <pre><code>- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n</code></pre>"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader-functions","title":"Functions","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.load_pipeline","title":"load_pipeline","text":"<pre><code>load_pipeline(path: str) -&gt; Pipeline\n</code></pre> <p>Load pipeline from YAML file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Path to YAML configuration file.</p> required <p>Returns:</p> Name Type Description <code>Pipeline</code> <code>Pipeline</code> <p>Executable pipeline instance.</p> Notes <p>Responsibilities:</p> <pre><code>- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n</code></pre>"}]}