docs/libs/dagpipe/site/search/search_index.json

{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"dagpipe","text":"<ul> <li>Dagpipe</li> </ul>"},{"location":"#dagpipe","title":"dagpipe","text":"<p>Directed acyclic graph execution framework for deterministic state propagation.</p>"},{"location":"#dagpipe--summary","title":"Summary","text":"<p><code>dagpipe</code> executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable state and optionally produces derived states for downstream nodes.</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> <p>Execution Core: - Engine - Graph - Node</p> <p>State &amp; Data: - State / MyState (custom base) - Payload - Schema / SchemaError</p> <p>Declarative Pipelines: - Pipeline - load_pipeline</p>"},{"location":"#dagpipe-classes","title":"Classes","text":""},{"location":"#dagpipe-functions","title":"Functions","text":""},{"location":"engine/","title":"Engine","text":""},{"location":"engine/#dagpipe.engine","title":"dagpipe.engine","text":"<p>Execution engine responsible for running pipelines and graphs.</p>"},{"location":"engine/#dagpipe.engine--summary","title":"Summary","text":"<p>The Engine executes Node objects and propagates immutable State instances through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.</p> Notes <p>Guarantees:</p> <pre><code>- Deterministic execution and consistent state lineage.\n- Orchestrates execution without modifying Graph, Node, or State objects.\n</code></pre>"},{"location":"engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"engine/#dagpipe.engine.Engine","title":"Engine","text":"<pre><code>Engine(nodes_or_graph: Union[Sequence[Node], Graph])\n</code></pre> <p>Execution engine responsible for running pipeline logic.</p> Notes <p>Responsibilities:</p> <pre><code>- Accepts either a linear sequence of Nodes or a Graph defining execution topology.\n- Propagates immutable State objects through Nodes and collects terminal States.\n</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 independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n</code></pre> <p>Initialize the execution engine.</p> <p>Parameters:</p> Name Type Description Default <code>nodes_or_graph</code> <code>Sequence[Node] | Graph</code> <p>Pipeline definition. May be a linear sequence or a DAG.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If input is not a Sequence[Node] or Graph, or contains invalid node types.</p> Notes <p>Responsibilities:</p> <pre><code>- Detects execution mode (linear or DAG) and validates node types and structure.\n</code></pre>"},{"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 State.</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 root is not a State 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 new instances for branches, and collects terminal states.\n</code></pre>"},{"location":"graph/","title":"Graph","text":""},{"location":"graph/#dagpipe.graph","title":"dagpipe.graph","text":"<p>Defines DAG structure connecting Nodes.</p>"},{"location":"graph/#dagpipe.graph--summary","title":"Summary","text":"<p>Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by Engine.</p> Notes <p>Responsibilities:</p> <pre><code>- Multiple roots, branching, and merging support.\n- Deterministic traversal based on topology.\n- Graph is mutable during construction but treated as immutable at runtime.\n</code></pre>"},{"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 Nodes.</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>"},{"location":"graph/#dagpipe.graph.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return debug representation.</p>"},{"location":"graph/#dagpipe.graph.Graph.__repr__--returns","title":"Returns","text":"<p>str</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>"},{"location":"graph/#dagpipe.graph.Graph.add_edge--add-directed-edge-from-src-to-dst","title":"Add directed edge from src to dst.","text":""},{"location":"graph/#dagpipe.graph.Graph.add_edge--parameters","title":"Parameters","text":"<p>src : Node     required: True     source node</p> Node <p>required: True destination node</p>"},{"location":"graph/#dagpipe.graph.Graph.add_edge--raises","title":"Raises","text":"<p>TypeError     if src or dst is not a Node</p> <p>ValueError     if edge would create a cycle</p> <p>ValueError     if src and dst are the same node</p>"},{"location":"graph/#dagpipe.graph.Graph.add_edge--behavior","title":"Behavior","text":"<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":"<p>Defines the Node abstraction used by dagpipe.</p>"},{"location":"node/#dagpipe.node--summary","title":"Summary","text":"<p>A Node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new States.</p> <p>Nodes are connected using Graph and executed by Engine.</p> Notes <p>Design Principles:</p> <pre><code>- **Pure:** Must not mutate input state.\n- **Deterministic:** Same input produces same output.\n- **Stateless:** Recommended to be stateless for reuse.\n- **Composable:** Nodes enable branching execution graphs.\n</code></pre>"},{"location":"node/#dagpipe.node-classes","title":"Classes","text":""},{"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. 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>"},{"location":"node/#dagpipe.node.Node.__hash__--returns","title":"Returns","text":"<p>int</p>"},{"location":"node/#dagpipe.node.Node.__new__","title":"__new__","text":"<pre><code>__new__()\n</code></pre> <p>Create or reuse singleton instance of the Node subclass.</p> <p>Returns:</p> Name Type Description <code>Node</code> <p>Singleton instance of the subclass.</p>"},{"location":"node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return debug representation.</p>"},{"location":"node/#dagpipe.node.Node.__repr__--returns","title":"Returns","text":"<p>str</p>"},{"location":"node/#dagpipe.node.Node.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return display representation.</p>"},{"location":"node/#dagpipe.node.Node.__str__--returns","title":"Returns","text":"<p>str</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(state: State, *, payload_update=None, confidence_delta=0.0, metadata_update=None) -&gt; State\n</code></pre> <p>Create a child State 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>Mapping[str, 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>Mapping[str, 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 records this node's ID in state history.\n</code></pre>"},{"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>Yields:</p> Name Type Description <code>State</code> <code>Iterable[State]</code> <p>Derived execution state(s).</p> Notes <p>Responsibilities:</p> <pre><code>- Subclasses implement specific resolution behavior. Must not mutate input state. Should use fork() to create child states. May yield zero states to terminate a branch.\n</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 State.</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 resolve() yields a non-State object.</p>"},{"location":"state/","title":"State","text":""},{"location":"state/#dagpipe.state","title":"dagpipe.state","text":"<p>Defines the core State object used by dagpipe.</p>"},{"location":"state/#dagpipe.state--summary","title":"Summary","text":"<p>The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().</p> Notes <p>Key design principles:</p> <pre><code>- **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().\n- **Cheap cloning:** Forking must be efficient since branching may create many states.\n- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.\n- **Domain agnostic:** State contains generic key\u2011value data and does not assume any schema.\n- **Engine\u2011friendly:** State contains execution metadata such as depth and history.\n</code></pre>"},{"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. 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.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(data: Mapping[str, Any], prefix: str = '') -&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>Returns:</p> Type Description <code>Iterable[str]</code> <p>Iterable[str]: Generator yielding dot-paths.</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 Payload 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. 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. Reuseable 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>"},{"location":"state/#dagpipe.state.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"state/#dagpipe.state.State","title":"State  <code>dataclass</code>","text":"<pre><code>State(payload: Payload, confidence: float = 1.0, parent: Optional[State] = None, depth: int = 0, history: Tuple[str, ...] = tuple(), metadata: Dict[str, Any] = dict())\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 pipeline traversal. 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.__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(*, payload_update: Optional[Mapping[str, Any]] = None, confidence_delta: float = 0.0, node_id: Optional[str] = None, metadata_update: Optional[Mapping[str, Any]] = None) -&gt; State\n</code></pre> <p>Create a new child State derived from this State.</p> <p>Parameters:</p> Name Type Description Default <code>payload_update</code> <code>Mapping[str, Any]</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</code> <p>Identifier of the node creating this state.</p> <code>None</code> <code>metadata_update</code> <code>Mapping[str, Any]</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 State 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, 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":"<p>Loads dagpipe pipelines from YAML configuration.</p>"},{"location":"yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"<p>Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph 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(engine: Engine, state_cls: Type[State], initial_payload: Payload)\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 State 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. 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(payload_override: Optional[Mapping[str, Any]] = None)\n</code></pre> <p>Execute pipeline.</p> <p>Parameters:</p> Name Type Description Default <code>payload_override</code> <code>Mapping[str, Any]</code> <p>Payload values overriding initial payload.</p> <code>None</code> <p>Returns:</p> Type Description <p>list[State]: Terminal execution states.</p> Notes <p>Responsibilities:</p> <pre><code>- Merges override payload with initial payload, 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, builds schema, creates State subclass, loads Node instances, 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":"<p>Directed acyclic graph execution framework for deterministic state propagation.</p>"},{"location":"dagpipe/#dagpipe--summary","title":"Summary","text":"<p><code>dagpipe</code> executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable state and optionally produces derived states for downstream nodes.</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> <p>Execution Core: - Engine - Graph - Node</p> <p>State &amp; Data: - State / MyState (custom base) - Payload - Schema / SchemaError</p> <p>Declarative Pipelines: - Pipeline - load_pipeline</p>"},{"location":"dagpipe/#dagpipe-classes","title":"Classes","text":""},{"location":"dagpipe/#dagpipe-functions","title":"Functions","text":""},{"location":"dagpipe/engine/","title":"Engine","text":""},{"location":"dagpipe/engine/#dagpipe.engine","title":"dagpipe.engine","text":"<p>Execution engine responsible for running pipelines and graphs.</p>"},{"location":"dagpipe/engine/#dagpipe.engine--summary","title":"Summary","text":"<p>The Engine executes Node objects and propagates immutable State instances through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.</p> Notes <p>Guarantees:</p> <pre><code>- Deterministic execution and consistent state lineage.\n- Orchestrates execution without modifying Graph, Node, or State objects.\n</code></pre>"},{"location":"dagpipe/engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine","title":"Engine","text":"<pre><code>Engine(nodes_or_graph: Union[Sequence[Node], Graph])\n</code></pre> <p>Execution engine responsible for running pipeline logic.</p> Notes <p>Responsibilities:</p> <pre><code>- Accepts either a linear sequence of Nodes or a Graph defining execution topology.\n- Propagates immutable State objects through Nodes and collects terminal States.\n</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 independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n</code></pre> <p>Initialize the execution engine.</p> <p>Parameters:</p> Name Type Description Default <code>nodes_or_graph</code> <code>Sequence[Node] | Graph</code> <p>Pipeline definition. May be a linear sequence or a DAG.</p> required <p>Raises:</p> Type Description <code>TypeError</code> <p>If input is not a Sequence[Node] or Graph, or contains invalid node types.</p> Notes <p>Responsibilities:</p> <pre><code>- Detects execution mode (linear or DAG) and validates node types and structure.\n</code></pre>"},{"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 State.</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 root is not a State 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 new instances for branches, and collects terminal states.\n</code></pre>"},{"location":"dagpipe/graph/","title":"Graph","text":""},{"location":"dagpipe/graph/#dagpipe.graph","title":"dagpipe.graph","text":"<p>Defines DAG structure connecting Nodes.</p>"},{"location":"dagpipe/graph/#dagpipe.graph--summary","title":"Summary","text":"<p>Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by Engine.</p> Notes <p>Responsibilities:</p> <pre><code>- Multiple roots, branching, and merging support.\n- Deterministic traversal based on topology.\n- Graph is mutable during construction but treated as immutable at runtime.\n</code></pre>"},{"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 Nodes.</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>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"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 debug representation.</p>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.__repr__--returns","title":"Returns","text":"<p>str</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>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--add-directed-edge-from-src-to-dst","title":"Add directed edge from src to dst.","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--parameters","title":"Parameters","text":"<p>src : Node     required: True     source node</p> Node <p>required: True destination node</p>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--raises","title":"Raises","text":"<p>TypeError     if src or dst is not a Node</p> <p>ValueError     if edge would create a cycle</p> <p>ValueError     if src and dst are the same node</p>"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--behavior","title":"Behavior","text":"<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":"<p>Defines the Node abstraction used by dagpipe.</p>"},{"location":"dagpipe/node/#dagpipe.node--summary","title":"Summary","text":"<p>A Node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new States.</p> <p>Nodes are connected using Graph and executed by Engine.</p> Notes <p>Design Principles:</p> <pre><code>- **Pure:** Must not mutate input state.\n- **Deterministic:** Same input produces same output.\n- **Stateless:** Recommended to be stateless for reuse.\n- **Composable:** Nodes enable branching execution graphs.\n</code></pre>"},{"location":"dagpipe/node/#dagpipe.node-classes","title":"Classes","text":""},{"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. 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>"},{"location":"dagpipe/node/#dagpipe.node.Node.__hash__--returns","title":"Returns","text":"<p>int</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.__new__","title":"__new__","text":"<pre><code>__new__()\n</code></pre> <p>Create or reuse singleton instance of the Node subclass.</p> <p>Returns:</p> Name Type Description <code>Node</code> <p>Singleton instance of the subclass.</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"<pre><code>__repr__() -&gt; str\n</code></pre> <p>Return debug representation.</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.__repr__--returns","title":"Returns","text":"<p>str</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.__str__","title":"__str__","text":"<pre><code>__str__() -&gt; str\n</code></pre> <p>Return display representation.</p>"},{"location":"dagpipe/node/#dagpipe.node.Node.__str__--returns","title":"Returns","text":"<p>str</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(state: State, *, payload_update=None, confidence_delta=0.0, metadata_update=None) -&gt; State\n</code></pre> <p>Create a child State 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>Mapping[str, 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>Mapping[str, 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 records this node's ID in state history.\n</code></pre>"},{"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>Yields:</p> Name Type Description <code>State</code> <code>Iterable[State]</code> <p>Derived execution state(s).</p> Notes <p>Responsibilities:</p> <pre><code>- Subclasses implement specific resolution behavior. Must not mutate input state. Should use fork() to create child states. May yield zero states to terminate a branch.\n</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 State.</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 resolve() yields a non-State object.</p>"},{"location":"dagpipe/state/","title":"State","text":""},{"location":"dagpipe/state/#dagpipe.state","title":"dagpipe.state","text":"<p>Defines the core State object used by dagpipe.</p>"},{"location":"dagpipe/state/#dagpipe.state--summary","title":"Summary","text":"<p>The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().</p> Notes <p>Key design principles:</p> <pre><code>- **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().\n- **Cheap cloning:** Forking must be efficient since branching may create many states.\n- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.\n- **Domain agnostic:** State contains generic key\u2011value data and does not assume any schema.\n- **Engine\u2011friendly:** State contains execution metadata such as depth and history.\n</code></pre>"},{"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. 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.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(data: Mapping[str, Any], prefix: str = '') -&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>Returns:</p> Type Description <code>Iterable[str]</code> <p>Iterable[str]: Generator yielding dot-paths.</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 Payload 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. 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. Reuseable 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>"},{"location":"dagpipe/state/#dagpipe.state.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"dagpipe/state/#dagpipe.state.State","title":"State  <code>dataclass</code>","text":"<pre><code>State(payload: Payload, confidence: float = 1.0, parent: Optional[State] = None, depth: int = 0, history: Tuple[str, ...] = tuple(), metadata: Dict[str, Any] = dict())\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 pipeline traversal. 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.__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(*, payload_update: Optional[Mapping[str, Any]] = None, confidence_delta: float = 0.0, node_id: Optional[str] = None, metadata_update: Optional[Mapping[str, Any]] = None) -&gt; State\n</code></pre> <p>Create a new child State derived from this State.</p> <p>Parameters:</p> Name Type Description Default <code>payload_update</code> <code>Mapping[str, Any]</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</code> <p>Identifier of the node creating this state.</p> <code>None</code> <code>metadata_update</code> <code>Mapping[str, Any]</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 State 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, 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":"<p>Loads dagpipe pipelines from YAML configuration.</p>"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"<p>Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph 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(engine: Engine, state_cls: Type[State], initial_payload: Payload)\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 State 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. 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(payload_override: Optional[Mapping[str, Any]] = None)\n</code></pre> <p>Execute pipeline.</p> <p>Parameters:</p> Name Type Description Default <code>payload_override</code> <code>Mapping[str, Any]</code> <p>Payload values overriding initial payload.</p> <code>None</code> <p>Returns:</p> Type Description <p>list[State]: Terminal execution states.</p> Notes <p>Responsibilities:</p> <pre><code>- Merges override payload with initial payload, 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, builds schema, creates State subclass, loads Node instances, builds Graph topology, and initializes Engine.\n</code></pre>"}]}