Vishesh 'ironeagle' Bangotra
7aadae1736
Enables dagpipe wiki on the docs hub alongside lib and mcp, removes stale nested lib pages, and picks up regenerated GSDFC docstrings in the MCP bundle.
190 lines
12 KiB
JSON
190 lines
12 KiB
JSON
{
|
||
"module": "dagpipe.node",
|
||
"content": {
|
||
"path": "dagpipe.node",
|
||
"docstring": "# Summary\n\nDefines the `Node` abstraction used by `dagpipe`.\n\nA node represents a single unit of pipeline execution logic. It consumes one\n`State` and produces zero, one, or many new `State` objects.\n\nNodes are connected using a `Graph` and executed by an `Engine`.\n\n---\n\n# Design principles\n\n- **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.",
|
||
"objects": {
|
||
"State": {
|
||
"name": "State",
|
||
"kind": "class",
|
||
"path": "dagpipe.node.State",
|
||
"signature": "State(payload: Payload, confidence: float = 1.0, parent: State | None = None, depth: int = 0, history: tuple[str, ...] = tuple(), metadata: dict[str, Any] = dict())",
|
||
"docstring": "Immutable execution state propagated through dagpipe pipeline.\n\nAttributes:\n payload (Payload):\n Execution data container.\n\n schema (ClassVar[Schema]):\n Payload validation schema.\n\n confidence (float):\n Execution confidence score.\n\n parent (Optional[State]):\n Parent state reference.\n\n depth (int):\n Execution depth.\n\n history (Tuple[str, ...]):\n Ordered node execution lineage.\n\n metadata (Dict[str, Any]):\n Execution metadata.\n\nNotes:\n **Responsibilities:**\n\n - 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.",
|
||
"members": {
|
||
"payload": {
|
||
"name": "payload",
|
||
"kind": "attribute",
|
||
"path": "dagpipe.node.State.payload",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"schema": {
|
||
"name": "schema",
|
||
"kind": "attribute",
|
||
"path": "dagpipe.node.State.schema",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"confidence": {
|
||
"name": "confidence",
|
||
"kind": "attribute",
|
||
"path": "dagpipe.node.State.confidence",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"parent": {
|
||
"name": "parent",
|
||
"kind": "attribute",
|
||
"path": "dagpipe.node.State.parent",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"depth": {
|
||
"name": "depth",
|
||
"kind": "attribute",
|
||
"path": "dagpipe.node.State.depth",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"history": {
|
||
"name": "history",
|
||
"kind": "attribute",
|
||
"path": "dagpipe.node.State.history",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"metadata": {
|
||
"name": "metadata",
|
||
"kind": "attribute",
|
||
"path": "dagpipe.node.State.metadata",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"fork": {
|
||
"name": "fork",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.State.fork",
|
||
"signature": "fork(*, payload_update: Mapping[str, Any] | None = None, confidence_delta: float = 0.0, node_id: str | None = None, metadata_update: Mapping[str, Any] | None = None)",
|
||
"docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history."
|
||
},
|
||
"lineage": {
|
||
"name": "lineage",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.State.lineage",
|
||
"signature": "lineage()",
|
||
"docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)."
|
||
},
|
||
"get": {
|
||
"name": "get",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.State.get",
|
||
"signature": "get(key: str, default: Any = None)",
|
||
"docstring": "Retrieve payload value.\n\nArgs:\n key (str):\n Dot-path key.\n default (Any, optional):\n Fallback value.\n\nReturns:\n Any:\n Stored value or default."
|
||
},
|
||
"has": {
|
||
"name": "has",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.State.has",
|
||
"signature": "has(key: str)",
|
||
"docstring": "Check whether payload contains key.\n\nArgs:\n key (str):\n Dot-path key.\n\nReturns:\n bool:\n Existence of the key."
|
||
}
|
||
}
|
||
},
|
||
"Node": {
|
||
"name": "Node",
|
||
"kind": "class",
|
||
"path": "dagpipe.node.Node",
|
||
"signature": null,
|
||
"docstring": "Base class for all dagpipe execution nodes.\n\nAttributes:\n id (str):\n Unique identifier of the node (snake_case dotted format).\n\n name (str):\n Human-readable display name.\n\nNotes:\n **Responsibilities:**\n\n - 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\n **Guarantees:**\n\n - Nodes must never mutate the input `State`.\n - Instances are singletons per subclass and reused across executions.",
|
||
"members": {
|
||
"id": {
|
||
"name": "id",
|
||
"kind": "attribute",
|
||
"path": "dagpipe.node.Node.id",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"name": {
|
||
"name": "name",
|
||
"kind": "attribute",
|
||
"path": "dagpipe.node.Node.name",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"node_id_to_name": {
|
||
"name": "node_id_to_name",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.Node.node_id_to_name",
|
||
"signature": "node_id_to_name(node_id: str) -> str",
|
||
"docstring": "Convert a dotted snake_case node ID into a human-readable name.\n\nArgs:\n node_id (str):\n Unique node identifier (e.g., 'entity.resolve.numeric_merchant').\n\nReturns:\n str:\n Human-readable display name (e.g., 'Entity › Resolve › Numeric Merchant')."
|
||
},
|
||
"clean_id_and_name": {
|
||
"name": "clean_id_and_name",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.Node.clean_id_and_name",
|
||
"signature": "clean_id_and_name() -> None",
|
||
"docstring": "Normalize and validate node ID and display name.\n\nRaises:\n TypeError:\n If ID is not a string.\n ValueError:\n If ID format is invalid.\n\nNotes:\n **Guarantees:**\n\n - Generates ID from module and class name if missing.\n - Validates ID format.\n - Generates human-readable name if missing."
|
||
},
|
||
"run": {
|
||
"name": "run",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.Node.run",
|
||
"signature": "run(state: State) -> tuple[State, ...]",
|
||
"docstring": "Execute this node on a `State`.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n tuple[State, ...]:\n Derived execution states.\n\nRaises:\n TypeError:\n If `resolve()` yields a non-`State` object."
|
||
},
|
||
"fork": {
|
||
"name": "fork",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.Node.fork",
|
||
"signature": "fork(state: State, *, payload_update: Any = None, confidence_delta: float = 0.0, metadata_update: Any = None) -> State",
|
||
"docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history."
|
||
},
|
||
"resolve": {
|
||
"name": "resolve",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.Node.resolve",
|
||
"signature": "resolve(state: State) -> Iterable[State]",
|
||
"docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch."
|
||
},
|
||
"is_async": {
|
||
"name": "is_async",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.Node.is_async",
|
||
"signature": "is_async() -> bool",
|
||
"docstring": "Return whether this node executes asynchronously.\n\nReturns:\n bool:\n True if the node is an `AsyncNode` instance."
|
||
}
|
||
}
|
||
},
|
||
"AsyncNode": {
|
||
"name": "AsyncNode",
|
||
"kind": "class",
|
||
"path": "dagpipe.node.AsyncNode",
|
||
"signature": null,
|
||
"docstring": "Base class for nodes whose execution is asynchronous.\n\nSubclasses implement `resolve_async` (an async generator yielding derived\n`State` objects). The engine dispatches to `resolve_async` when running an\nasync traversal (see `Engine.run_async`).\n\nSync-only engines (and the base `Node.run`) treat an `AsyncNode` as a no-op\nconsumer: calling `run` on an `AsyncNode` returns no states, signalling that\nan async engine is required.",
|
||
"members": {
|
||
"resolve": {
|
||
"name": "resolve",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.AsyncNode.resolve",
|
||
"signature": "resolve(state: State) -> Iterable[State]",
|
||
"docstring": "Execute no-op resolution in sync contexts.\n\nSync-only engines (and the base `Node.run`) treat an `AsyncNode` as a\nno-op consumer: this returns no states, signalling that an async engine\nis required.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Empty tuple, since async execution is handled by\n `resolve_async`."
|
||
},
|
||
"resolve_async": {
|
||
"name": "resolve_async",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.AsyncNode.resolve_async",
|
||
"signature": "resolve_async(state: State) -> Iterable[State]",
|
||
"docstring": "Execute node logic asynchronously.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Guarantees:**\n\n - Subclasses implement this.\n - Must not mutate the input state.\n - Should use `fork()` to create child states."
|
||
},
|
||
"run_async": {
|
||
"name": "run_async",
|
||
"kind": "function",
|
||
"path": "dagpipe.node.AsyncNode.run_async",
|
||
"signature": "run_async(state: State) -> tuple[State, ...]",
|
||
"docstring": "Execute this node asynchronously on a state, validating outputs.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n tuple[State, ...]:\n Derived execution states.\n\nRaises:\n TypeError:\n If `resolve_async()` yields a non-`State` object."
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
} |