Vishesh 'ironeagle' Bangotra
0e49f02c4c
All checks were successful
continuous-integration/drone/push Build is passing
1 line
52 KiB
JSON
1 line
52 KiB
JSON
{"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 & 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.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 `Node` objects or a `Graph`\n defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n 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\n 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 <code>Sequence[Node]</code> or <code>Graph</code>, or contains invalid node types.</p> Notes <p>Responsibilities:</p> <pre><code>- Detects execution mode (linear or DAG) and validates node\n types and structure.\n</code></pre>"},{"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__() -> 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) -> 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.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>"},{"location":"#dagpipe.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"#dagpipe.Graph-functions","title":"Functions","text":""},{"location":"#dagpipe.Graph.__repr__","title":"__repr__","text":"<pre><code>__repr__() -> str\n</code></pre> <p>Return debug representation.</p>"},{"location":"#dagpipe.Graph.__repr__--returns","title":"Returns","text":"<p>str</p>"},{"location":"#dagpipe.Graph.add_edge","title":"add_edge","text":"<pre><code>add_edge(src: Node, dst: Node) -> 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) -> 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) -> 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() -> 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) -> 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() -> 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__() -> int\n</code></pre> <p>Return stable hash based on node ID.</p>"},{"location":"#dagpipe.Node.__hash__--returns","title":"Returns","text":"<p>int</p>"},{"location":"#dagpipe.Node.__new__","title":"__new__","text":"<pre><code>__new__() -> Node\n</code></pre> <p>Create or reuse singleton instance of the Node subclass.</p> <p>Returns:</p> Name Type Description <code>Node</code> <code>Node</code> <p>Singleton instance of the subclass.</p>"},{"location":"#dagpipe.Node.__repr__","title":"__repr__","text":"<pre><code>__repr__() -> str\n</code></pre> <p>Return debug representation.</p>"},{"location":"#dagpipe.Node.__repr__--returns","title":"Returns","text":"<p>str</p>"},{"location":"#dagpipe.Node.__str__","title":"__str__","text":"<pre><code>__str__() -> str\n</code></pre> <p>Return display representation.</p>"},{"location":"#dagpipe.Node.__str__--returns","title":"Returns","text":"<p>str</p>"},{"location":"#dagpipe.Node.clean_id_and_name","title":"clean_id_and_name <code>classmethod</code>","text":"<pre><code>clean_id_and_name() -> 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(state: State, *, payload_update=None, confidence_delta=0.0, metadata_update=None) -> 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>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\n records this node's ID in state history.\n</code></pre>"},{"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) -> 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) -> 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.\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) -> 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.as_dict","title":"as_dict","text":"<pre><code>as_dict() -> 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) -> 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) -> 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(data: Mapping[str, Any], prefix: str = '') -> 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.Payload.keys","title":"keys","text":"<pre><code>keys() -> 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]) -> 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(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 <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(payload_override: Optional[Mapping[str, Any]] = None) -> 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]</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.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) -> 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]) -> 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>"},{"location":"#dagpipe.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"#dagpipe.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\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.__repr__","title":"__repr__","text":"<pre><code>__repr__() -> 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(*, payload_update: Optional[Mapping[str, Any]] = None, confidence_delta: float = 0.0, node_id: Optional[str] = None, metadata_update: Optional[Mapping[str, Any]] = None) -> 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]</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 <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) -> 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) -> 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() -> 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-functions","title":"Functions","text":""},{"location":"#dagpipe.load_pipeline","title":"load_pipeline","text":"<pre><code>load_pipeline(path: str) -> 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(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 `Node` objects or a `Graph`\n defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n 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\n 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 <code>Sequence[Node]</code> or <code>Graph</code>, or contains invalid node types.</p> Notes <p>Responsibilities:</p> <pre><code>- Detects execution mode (linear or DAG) and validates node\n 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__() -> 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) -> 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":"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>"},{"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__() -> 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) -> 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) -> 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) -> 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() -> 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) -> 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() -> 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.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__() -> 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__() -> Node\n</code></pre> <p>Create or reuse singleton instance of the Node subclass.</p> <p>Returns:</p> Name Type Description <code>Node</code> <code>Node</code> <p>Singleton instance of the subclass.</p>"},{"location":"node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"<pre><code>__repr__() -> 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__() -> 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() -> 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) -> 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>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\n 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) -> 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) -> 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.\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) -> 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.as_dict","title":"as_dict","text":"<pre><code>as_dict() -> 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) -> 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) -> 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 = '') -> 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() -> 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]) -> 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) -> 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]) -> 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\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.__repr__","title":"__repr__","text":"<pre><code>__repr__() -> 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) -> 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]</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 <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) -> 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) -> 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() -> 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(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 <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(payload_override: Optional[Mapping[str, Any]] = None) -> 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]</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) -> 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>"}]} |