From 0e49f02c4c333ccd12ab7f31800dff728c4a10f2 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sun, 8 Mar 2026 17:57:34 +0530 Subject: [PATCH] updated mcp --- libs/dagpipe/site/dagpipe/engine/index.html | 1218 ----- libs/dagpipe/site/dagpipe/graph/index.html | 1399 ------ libs/dagpipe/site/dagpipe/index.html | 912 ---- libs/dagpipe/site/dagpipe/node/index.html | 1602 ------ libs/dagpipe/site/dagpipe/state/index.html | 2276 --------- .../site/dagpipe/yaml_loader/index.html | 1136 ----- libs/dagpipe/site/engine/index.html | 79 +- libs/dagpipe/site/graph/index.html | 244 +- libs/dagpipe/site/index.html | 4349 ++++++++++++++++- libs/dagpipe/site/node/index.html | 87 +- libs/dagpipe/site/objects.inv | Bin 679 -> 718 bytes libs/dagpipe/site/search/search_index.json | 2 +- libs/dagpipe/site/sitemap.xml.gz | Bin 127 -> 127 bytes libs/dagpipe/site/state/index.html | 104 +- libs/dagpipe/site/yaml_loader/index.html | 40 +- libs/doc-forge/site/cli/commands/index.html | 28 +- libs/doc-forge/site/cli/index.html | 25 +- libs/doc-forge/site/cli/main/index.html | 21 +- libs/doc-forge/site/cli/mcp_utils/index.html | 34 +- .../site/cli/mkdocs_utils/index.html | 44 +- libs/doc-forge/site/index.html | 1440 +++--- .../site/loaders/griffe_loader/index.html | 50 +- libs/doc-forge/site/loaders/index.html | 43 +- libs/doc-forge/site/models/index.html | 57 +- libs/doc-forge/site/models/module/index.html | 44 +- libs/doc-forge/site/models/object/index.html | 31 +- libs/doc-forge/site/models/project/index.html | 31 +- libs/doc-forge/site/renderers/base/index.html | 24 +- libs/doc-forge/site/renderers/index.html | 31 +- .../site/renderers/mcp_renderer/index.html | 23 + .../site/renderers/mkdocs_renderer/index.html | 36 +- libs/doc-forge/site/search/search_index.json | 2 +- libs/doc-forge/site/servers/index.html | 21 +- .../site/servers/mcp_server/index.html | 23 +- libs/doc-forge/site/sitemap.xml.gz | Bin 127 -> 127 bytes .../mail-intake/site/adapters/base/index.html | 33 +- .../site/adapters/gmail/index.html | 39 +- libs/mail-intake/site/adapters/index.html | 79 +- libs/mail-intake/site/auth/base/index.html | 31 +- libs/mail-intake/site/auth/google/index.html | 43 +- libs/mail-intake/site/auth/index.html | 85 +- libs/mail-intake/site/config/index.html | 19 +- libs/mail-intake/site/credentials/index.html | 102 +- .../site/credentials/pickle/index.html | 29 +- .../site/credentials/redis/index.html | 45 +- .../site/credentials/store/index.html | 31 +- libs/mail-intake/site/exceptions/index.html | 18 +- libs/mail-intake/site/index.html | 181 +- libs/mail-intake/site/ingestion/index.html | 52 +- .../site/ingestion/reader/index.html | 45 +- .../site/mail_intake/adapters/base/index.html | 1573 ------ .../mail_intake/adapters/gmail/index.html | 1758 ------- .../site/mail_intake/adapters/index.html | 2139 -------- .../site/mail_intake/auth/base/index.html | 1396 ------ .../site/mail_intake/auth/google/index.html | 1454 ------ .../site/mail_intake/auth/index.html | 1657 ------- .../site/mail_intake/config/index.html | 1467 ------ .../site/mail_intake/credentials/index.html | 2136 -------- .../mail_intake/credentials/pickle/index.html | 1498 ------ .../mail_intake/credentials/redis/index.html | 1564 ------ .../mail_intake/credentials/store/index.html | 1495 ------ .../site/mail_intake/exceptions/index.html | 1375 ------ libs/mail-intake/site/mail_intake/index.html | 1353 ----- .../site/mail_intake/ingestion/index.html | 1561 ------ .../mail_intake/ingestion/reader/index.html | 1551 ------ .../site/mail_intake/models/index.html | 1938 -------- .../mail_intake/models/message/index.html | 1587 ------ .../site/mail_intake/models/thread/index.html | 1543 ------ .../site/mail_intake/parsers/body/index.html | 1297 ----- .../mail_intake/parsers/headers/index.html | 1428 ------ .../site/mail_intake/parsers/index.html | 1641 ------- .../mail_intake/parsers/subject/index.html | 1310 ----- libs/mail-intake/site/models/index.html | 53 +- .../site/models/message/index.html | 15 +- .../mail-intake/site/models/thread/index.html | 21 +- libs/mail-intake/site/objects.inv | Bin 1245 -> 1173 bytes libs/mail-intake/site/parsers/body/index.html | 37 +- .../site/parsers/headers/index.html | 74 +- libs/mail-intake/site/parsers/index.html | 138 +- .../site/parsers/subject/index.html | 17 +- .../mail-intake/site/search/search_index.json | 2 +- libs/mail-intake/site/sitemap.xml.gz | Bin 127 -> 127 bytes libs/omniread/site/core/content/index.html | 21 +- libs/omniread/site/core/index.html | 89 +- libs/omniread/site/core/parser/index.html | 45 +- libs/omniread/site/core/scraper/index.html | 53 +- libs/omniread/site/html/index.html | 85 +- libs/omniread/site/html/parser/index.html | 47 +- libs/omniread/site/html/scraper/index.html | 45 +- libs/omniread/site/index.html | 325 +- libs/omniread/site/objects.inv | Bin 868 -> 782 bytes .../site/omniread/core/content/index.html | 1248 ----- libs/omniread/site/omniread/core/index.html | 1810 ------- .../site/omniread/core/parser/index.html | 1156 ----- .../site/omniread/core/scraper/index.html | 1046 ---- libs/omniread/site/omniread/html/index.html | 1857 ------- .../site/omniread/html/parser/index.html | 1473 ------ .../site/omniread/html/scraper/index.html | 1195 ----- libs/omniread/site/omniread/index.html | 3113 ------------ .../site/omniread/pdf/client/index.html | 1204 ----- libs/omniread/site/omniread/pdf/index.html | 1590 ------ .../site/omniread/pdf/parser/index.html | 1144 ----- .../site/omniread/pdf/scraper/index.html | 1056 ---- libs/omniread/site/pdf/client/index.html | 31 +- libs/omniread/site/pdf/index.html | 62 +- libs/omniread/site/pdf/parser/index.html | 21 +- libs/omniread/site/pdf/scraper/index.html | 19 +- libs/omniread/site/search/search_index.json | 2 +- libs/omniread/site/sitemap.xml.gz | Bin 127 -> 127 bytes libs/openapi-first/site/app/index.html | 66 +- libs/openapi-first/site/binder/index.html | 55 +- libs/openapi-first/site/client/index.html | 27 +- libs/openapi-first/site/errors/index.html | 37 +- libs/openapi-first/site/index.html | 119 +- libs/openapi-first/site/loader/index.html | 45 +- libs/openapi-first/site/objects.inv | Bin 764 -> 415 bytes .../site/openapi_first/app/index.html | 930 ---- .../site/openapi_first/binder/index.html | 867 ---- .../site/openapi_first/cli/index.html | 856 ---- .../site/openapi_first/client/index.html | 972 ---- .../site/openapi_first/errors/index.html | 901 ---- .../site/openapi_first/index.html | 827 ---- .../site/openapi_first/loader/index.html | 895 ---- .../templates/crud_app/data/index.html | 989 ---- .../templates/crud_app/index.html | 818 ---- .../templates/crud_app/main/index.html | 711 --- .../templates/crud_app/routes/index.html | 1039 ---- .../crud_app/test_crud_app/index.html | 860 ---- .../templates/health_app/index.html | 759 --- .../templates/health_app/main/index.html | 711 --- .../templates/health_app/routes/index.html | 755 --- .../site/openapi_first/templates/index.html | 691 --- .../templates/model_app/data/index.html | 1016 ---- .../templates/model_app/index.html | 822 ---- .../templates/model_app/main/index.html | 711 --- .../templates/model_app/models/index.html | 855 ---- .../templates/model_app/routes/index.html | 1036 ---- .../model_app/test_model_app/index.html | 859 ---- .../site/search/search_index.json | 2 +- libs/openapi-first/site/sitemap.xml.gz | Bin 127 -> 127 bytes libs/py-jwt/site/app/index.html | 87 +- libs/py-jwt/site/exceptions/index.html | 48 +- libs/py-jwt/site/index.html | 211 +- libs/py-jwt/site/introspection/index.html | 8 +- libs/py-jwt/site/jwtlib/app/index.html | 1449 ------ libs/py-jwt/site/jwtlib/exceptions/index.html | 1142 ----- libs/py-jwt/site/jwtlib/index.html | 2571 ---------- .../site/jwtlib/introspection/index.html | 1221 ----- libs/py-jwt/site/jwtlib/models/app/index.html | 1510 ------ .../site/jwtlib/models/common/index.html | 1133 ----- libs/py-jwt/site/jwtlib/models/index.html | 1741 ------- .../site/jwtlib/models/mongo/index.html | 987 ---- .../site/jwtlib/models/security/index.html | 996 ---- libs/py-jwt/site/jwtlib/repository/index.html | 1428 ------ libs/py-jwt/site/jwtlib/security/index.html | 1283 ----- libs/py-jwt/site/jwtlib/utils/index.html | 1196 ----- libs/py-jwt/site/models/app/index.html | 25 +- libs/py-jwt/site/models/common/index.html | 8 +- libs/py-jwt/site/models/index.html | 104 +- libs/py-jwt/site/models/mongo/index.html | 17 +- libs/py-jwt/site/models/security/index.html | 21 +- libs/py-jwt/site/objects.inv | Bin 1067 -> 990 bytes libs/py-jwt/site/repository/index.html | 11 +- libs/py-jwt/site/search/search_index.json | 2 +- libs/py-jwt/site/security/index.html | 15 +- libs/py-jwt/site/sitemap.xml.gz | Bin 127 -> 127 bytes libs/py-jwt/site/utils/index.html | 26 +- 167 files changed, 7632 insertions(+), 98942 deletions(-) delete mode 100644 libs/dagpipe/site/dagpipe/engine/index.html delete mode 100644 libs/dagpipe/site/dagpipe/graph/index.html delete mode 100644 libs/dagpipe/site/dagpipe/index.html delete mode 100644 libs/dagpipe/site/dagpipe/node/index.html delete mode 100644 libs/dagpipe/site/dagpipe/state/index.html delete mode 100644 libs/dagpipe/site/dagpipe/yaml_loader/index.html delete mode 100644 libs/mail-intake/site/mail_intake/adapters/base/index.html delete mode 100644 libs/mail-intake/site/mail_intake/adapters/gmail/index.html delete mode 100644 libs/mail-intake/site/mail_intake/adapters/index.html delete mode 100644 libs/mail-intake/site/mail_intake/auth/base/index.html delete mode 100644 libs/mail-intake/site/mail_intake/auth/google/index.html delete mode 100644 libs/mail-intake/site/mail_intake/auth/index.html delete mode 100644 libs/mail-intake/site/mail_intake/config/index.html delete mode 100644 libs/mail-intake/site/mail_intake/credentials/index.html delete mode 100644 libs/mail-intake/site/mail_intake/credentials/pickle/index.html delete mode 100644 libs/mail-intake/site/mail_intake/credentials/redis/index.html delete mode 100644 libs/mail-intake/site/mail_intake/credentials/store/index.html delete mode 100644 libs/mail-intake/site/mail_intake/exceptions/index.html delete mode 100644 libs/mail-intake/site/mail_intake/index.html delete mode 100644 libs/mail-intake/site/mail_intake/ingestion/index.html delete mode 100644 libs/mail-intake/site/mail_intake/ingestion/reader/index.html delete mode 100644 libs/mail-intake/site/mail_intake/models/index.html delete mode 100644 libs/mail-intake/site/mail_intake/models/message/index.html delete mode 100644 libs/mail-intake/site/mail_intake/models/thread/index.html delete mode 100644 libs/mail-intake/site/mail_intake/parsers/body/index.html delete mode 100644 libs/mail-intake/site/mail_intake/parsers/headers/index.html delete mode 100644 libs/mail-intake/site/mail_intake/parsers/index.html delete mode 100644 libs/mail-intake/site/mail_intake/parsers/subject/index.html delete mode 100644 libs/omniread/site/omniread/core/content/index.html delete mode 100644 libs/omniread/site/omniread/core/index.html delete mode 100644 libs/omniread/site/omniread/core/parser/index.html delete mode 100644 libs/omniread/site/omniread/core/scraper/index.html delete mode 100644 libs/omniread/site/omniread/html/index.html delete mode 100644 libs/omniread/site/omniread/html/parser/index.html delete mode 100644 libs/omniread/site/omniread/html/scraper/index.html delete mode 100644 libs/omniread/site/omniread/index.html delete mode 100644 libs/omniread/site/omniread/pdf/client/index.html delete mode 100644 libs/omniread/site/omniread/pdf/index.html delete mode 100644 libs/omniread/site/omniread/pdf/parser/index.html delete mode 100644 libs/omniread/site/omniread/pdf/scraper/index.html delete mode 100644 libs/openapi-first/site/openapi_first/app/index.html delete mode 100644 libs/openapi-first/site/openapi_first/binder/index.html delete mode 100644 libs/openapi-first/site/openapi_first/cli/index.html delete mode 100644 libs/openapi-first/site/openapi_first/client/index.html delete mode 100644 libs/openapi-first/site/openapi_first/errors/index.html delete mode 100644 libs/openapi-first/site/openapi_first/index.html delete mode 100644 libs/openapi-first/site/openapi_first/loader/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/crud_app/data/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/crud_app/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/crud_app/main/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/crud_app/routes/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/crud_app/test_crud_app/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/health_app/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/health_app/main/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/health_app/routes/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/model_app/data/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/model_app/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/model_app/main/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/model_app/models/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/model_app/routes/index.html delete mode 100644 libs/openapi-first/site/openapi_first/templates/model_app/test_model_app/index.html delete mode 100644 libs/py-jwt/site/jwtlib/app/index.html delete mode 100644 libs/py-jwt/site/jwtlib/exceptions/index.html delete mode 100644 libs/py-jwt/site/jwtlib/index.html delete mode 100644 libs/py-jwt/site/jwtlib/introspection/index.html delete mode 100644 libs/py-jwt/site/jwtlib/models/app/index.html delete mode 100644 libs/py-jwt/site/jwtlib/models/common/index.html delete mode 100644 libs/py-jwt/site/jwtlib/models/index.html delete mode 100644 libs/py-jwt/site/jwtlib/models/mongo/index.html delete mode 100644 libs/py-jwt/site/jwtlib/models/security/index.html delete mode 100644 libs/py-jwt/site/jwtlib/repository/index.html delete mode 100644 libs/py-jwt/site/jwtlib/security/index.html delete mode 100644 libs/py-jwt/site/jwtlib/utils/index.html diff --git a/libs/dagpipe/site/dagpipe/engine/index.html b/libs/dagpipe/site/dagpipe/engine/index.html deleted file mode 100644 index bc56714..0000000 --- a/libs/dagpipe/site/dagpipe/engine/index.html +++ /dev/null @@ -1,1218 +0,0 @@ - - - - - - - - - - - - - - - - - - - Engine - dagpipe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Engine

- - -
- - - -

- dagpipe.engine - - -

- -
- -

Execution engine responsible for running pipelines and graphs.

-
-

Summary

-

The Engine executes Node objects and propagates immutable State instances -through either a linear sequence or a directed acyclic graph (Graph). -It orchestrates execution order, branching, and state propagation.

- - -
- Notes -

Guarantees:

-
1
-2
- Deterministic execution and consistent state lineage.
-- Orchestrates execution without modifying Graph, Node, or State objects.
-
-
- - -
- - - - - - -

Classes

- -
- - - -

- Engine - - -

-
1
Engine(nodes_or_graph: Union[Sequence[Node], Graph])
-
- -
- - -

Execution engine responsible for running pipeline logic.

- - -
- Notes -

Responsibilities:

-
1
-2
- Accepts either a linear sequence of Nodes or a Graph defining execution topology.
-- Propagates immutable State objects through Nodes and collects terminal States.
-
-

Guarantees:

-
1
-2
-3
-4
- Never mutates State, Node, or Graph instances.
-- State objects are never modified in place; each branch produces independent instances.
-- Execution order is deterministic and follows graph or pipeline topology.
-- Thread-safe for concurrent execution.
-
-
-

Initialize the execution engine.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
nodes_or_graph - Sequence[Node] | Graph - -
-

Pipeline definition. May be a linear sequence or a DAG.

-
- 		- required -
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- TypeError - -
-

If input is not a Sequence[Node] or Graph, or contains invalid node types.

-
-
- - -
- Notes -

Responsibilities:

-
1
- Detects execution mode (linear or DAG) and validates node types and structure.
-
-
- - - -
- - - - - -
Attributes
- -
- - - -
- nodes - - - - property - - -
-
1
nodes: tuple[Node, ...]
-
- -
- -

Return nodes managed by this engine.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- tuple[Node, ...] - -
-

tuple[Node, ...]: -Ordered sequence in linear mode or all nodes in graph mode.

-
-
-
- -
- -
Functions
- -
- - -
- __repr__ - - -
-
1
__repr__() -> str
-
- -
- -

Return the canonical string representation of the object.

- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
str - str - -
-

Representation that uniquely identifies the object and its configuration.

-
-
- -
- -
- -
- - -
- run - - -
-
1
run(root: State) -> List[State]
-
- -
- -

Execute the pipeline starting from a root State.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
root - State - -
-

Initial execution state.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- List[State] - -
-

list[State]: -Terminal execution states produced by the pipeline.

-
-
- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- TypeError - -
-

If root is not a State instance.

-
-
- RuntimeError - -
-

If the engine execution mode is invalid.

-
-
- - -
- Notes -

Responsibilities:

-
1
- Selects execution mode, propagates state through nodes, creates new instances for branches, and collects terminal states.
-
-
-
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/libs/dagpipe/site/dagpipe/graph/index.html b/libs/dagpipe/site/dagpipe/graph/index.html deleted file mode 100644 index d29c84d..0000000 --- a/libs/dagpipe/site/dagpipe/graph/index.html +++ /dev/null @@ -1,1399 +0,0 @@ - - - - - - - - - - - - - - - - - - - Graph - dagpipe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Graph

- - -
- - - -

- dagpipe.graph - - -

- -
- -

Defines DAG structure connecting Nodes.

-
-

Summary

-

Graph describes execution topology only. It does not execute nodes or manage State. -Execution is handled by Engine.

- - -
- Notes -

Responsibilities:

-
1
-2
-3
- Multiple roots, branching, and merging support.
-- Deterministic traversal based on topology.
-- Graph is mutable during construction but treated as immutable at runtime.
-
-
- - -
- - - - - - -

Classes

- -
- - - -

- Graph - - -

-
1
Graph()
-
- -
- - -

Directed Acyclic Graph defining execution topology of Nodes.

- - -
- Notes -

Responsibilities:

-
1
-2
- Stores node connectivity and validates that the topology remains acyclic.
-- Structure determines how State flows between nodes during execution.
-
-

Guarantees:

-
1
-2
- Topology is acyclic. Node relationships remain consistent.
-- Thread-safe for concurrent reads after construction.
-
-
-

Create an empty Graph.

-
Initializes node registry and edge mappings.
- - - - -
- - - - - - - -
Functions
- -
- - -
- __repr__ - - -
-
1
__repr__() -> str
-
- -
- -

Return debug representation.

-
Returns
-

str

- -
- -
- -
- - -
- add_edge - - -
-
1
add_edge(src: Node, dst: Node) -> None
-
- -
- -
Add directed edge from src to dst.
-
Parameters
-

src : Node - required: True - source node

- - -
- Node -

required: True -destination node

-
-
Raises
-

TypeError - if src or dst is not a Node

-

ValueError - if edge would create a cycle

-

ValueError - if src and dst are the same node

-
-
Behavior
-
    -
  • validates node types
    • -
  • prevents cycles
    • -
  • registers nodes if not present
    • -
  • updates parent and child mappings
    • -
-
- -
- -
- -
- - -
- add_root - - -
-
1
add_root(node: Node) -> None
-
- -
- -

Add a root node with no parents.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
node - Node - -
-

Node to add as a root.

-
- 		- required -
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- TypeError - -
-

If node is not a Node instance.

-
-
- -
- -
- -
- - -
- children - - -
-
1
children(node: Node) -> Tuple[Node, ...]
-
- -
- -

Return child nodes of a node.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
node - Node - -
-

Node to query.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Tuple[Node, ...] - -
-

Tuple[Node, ...]: -Outgoing neighbors.

-
-
- -
- -
- -
- - -
- nodes - - -
-
1
nodes() -> Tuple[Node, ...]
-
- -
- -

Return all nodes in the graph.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Tuple[Node, ...] - -
-

Tuple[Node, ...]: -All registered nodes.

-
-
- -
- -
- -
- - -
- parents - - -
-
1
parents(node: Node) -> Tuple[Node, ...]
-
- -
- -

Return parent nodes of a node.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
node - Node - -
-

Node to query.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Tuple[Node, ...] - -
-

Tuple[Node, ...]: -Incoming neighbors.

-
-
- -
- -
- -
- - -
- roots - - -
-
1
roots() -> Tuple[Node, ...]
-
- -
- -

Return root nodes (nodes with no incoming edges).

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Tuple[Node, ...] - -
-

Tuple[Node, ...]: -Entry point nodes.

-
-
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/libs/dagpipe/site/dagpipe/index.html b/libs/dagpipe/site/dagpipe/index.html deleted file mode 100644 index 7035b6b..0000000 --- a/libs/dagpipe/site/dagpipe/index.html +++ /dev/null @@ -1,912 +0,0 @@ - - - - - - - - - - - - - - - - - - - Dagpipe - dagpipe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Dagpipe

- - -
- - - -

- dagpipe - - -

- -
- -

Directed acyclic graph execution framework for deterministic state propagation.

-
-

Summary

-

dagpipe executes pipelines composed of nodes connected in a directed acyclic -graph (DAG). Each node receives an immutable state and optionally produces -derived states for downstream nodes.

-
-

Installation

-

Install using pip:

-
1
pip install dagpipe
-
-
-

Quick Start

-
 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
from dagpipe import State, Payload, Schema, Graph, Engine
-from dagpipe.node import Node
-
-class HelloNode(Node):
-    id = "hello"
-    def resolve(self, state):
-        yield self.fork(state, payload_update={"msg": "hello"})
-
-# Build and run
-graph = Graph()
-graph.add_root(HelloNode())
-engine = Engine(graph)
-
-class MyState(State):
-    schema = Schema({})
-
-results = engine.run(MyState(payload=Payload({})))
-
-
-

Public API

-

This package re-exports the core pipeline components. -Consumers should import from this namespace for standard usage.

-

Execution Core: -- Engine -- Graph -- Node

-

State & Data: -- State / MyState (custom base) -- Payload -- Schema / SchemaError

-

Declarative Pipelines: -- Pipeline -- load_pipeline

-
- - - -
- - - - - - -

Classes

-

Functions

- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/libs/dagpipe/site/dagpipe/node/index.html b/libs/dagpipe/site/dagpipe/node/index.html deleted file mode 100644 index f84cd4a..0000000 --- a/libs/dagpipe/site/dagpipe/node/index.html +++ /dev/null @@ -1,1602 +0,0 @@ - - - - - - - - - - - - - - - - - - - Node - dagpipe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Node

- - -
- - - -

- dagpipe.node - - -

- -
- -

Defines the Node abstraction used by dagpipe.

-
-

Summary

-

A Node represents a single unit of pipeline execution logic. It consumes one -State and produces zero, one, or many new States.

-

Nodes are connected using Graph and executed by Engine.

- - -
- Notes -

Design Principles:

-
1
-2
-3
-4
- **Pure:** Must not mutate input state.
-- **Deterministic:** Same input produces same output.
-- **Stateless:** Recommended to be stateless for reuse.
-- **Composable:** Nodes enable branching execution graphs.
-
-
- - -
- - - - - - -

Classes

- -
- - - -

- Node - - -

- - -
-

- Bases: ABC

- - -

Base class for all dagpipe execution nodes.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
id - str - -
-

Unique identifier of the node (snake_case dotted format).

-
-
name - str - -
-

Human-readable display name.

-
-
- - -
- Notes -

Responsibilities:

-
1
-2
-3
- Represents a deterministic unit of execution in the pipeline graph.
-- Consumes one State and produces zero, one, or many derived States.
-- Defines execution logic and enables branching, filtering, and transformation.
-
-

Guarantees:

-
1
- Nodes must never mutate the input State. Instances are singletons per subclass and reused across executions.
-
-
- - - -
- - - - - - - -
Functions
- -
- - -
- __hash__ - - -
-
1
__hash__() -> int
-
- -
- -

Return stable hash based on node ID.

-
Returns
-

int

- -
- -
- -
- - -
- __new__ - - -
-
1
__new__()
-
- -
- -

Create or reuse singleton instance of the Node subclass.

- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Node - -
-

Singleton instance of the subclass.

-
-
- -
- -
- -
- - -
- __repr__ - - -
-
1
__repr__() -> str
-
- -
- -

Return debug representation.

-
Returns
-

str

- -
- -
- -
- - -
- __str__ - - -
-
1
__str__() -> str
-
- -
- -

Return display representation.

-
Returns
-

str

- -
- -
- -
- - -
- clean_id_and_name - - - - classmethod - - -
-
1
clean_id_and_name() -> None
-
- -
- -

Normalize and validate node ID and display name.

- - -

Raises:

- - - - - - - - - - - - - - - - - -
TypeDescription
- TypeError - -
-

If ID is not a string.

-
-
- ValueError - -
-

If ID format is invalid.

-
-
- - -
- Notes -

Guarantees:

-
1
-2
-3
- Generates ID from module and class name if missing.
-- Validates ID format.
-- Generates human-readable name if missing.
-
-
-
- -
- -
- - -
- fork - - -
-
1
fork(state: State, *, payload_update=None, confidence_delta=0.0, metadata_update=None) -> State
-
- -
- -

Create a child State attributed to this node.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
state - State - -
-

Parent execution state.

-
- 		- required -
payload_update - Mapping[str, Any] - -
-

Dot-path payload updates.

-
- 		- None -
confidence_delta - float - -
-

Confidence adjustment.

-
- 		- 0.0 -
metadata_update - Mapping[str, Any] - -
-

Metadata updates.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
State - State - -
-

New child execution state.

-
-
- - -
- Notes -

Responsibilities:

-
1
- Convenience wrapper around State.fork() that automatically records this node's ID in state history.
-
-
-
- -
- -
- - -
- node_id_to_name - - - - staticmethod - - -
-
1
node_id_to_name(node_id: str) -> str
-
- -
- -

Convert a dotted snake_case node ID into a human-readable name.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
node_id - str - -
-

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
str - str - -
-

Human-readable display name (e.g., 'Entity › Resolve › Numeric Merchant').

-
-
- -
- -
- -
- - -
- resolve - - - - abstractmethod - - -
-
1
resolve(state: State) -> Iterable[State]
-
- -
- -

Execute node logic.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
state - State - -
-

Input execution state.

-
- 		- required -
- - -

Yields:

- - - - - - - - - - - - - -
Name TypeDescription
State - Iterable[State] - -
-

Derived execution state(s).

-
-
- - -
- Notes -

Responsibilities:

-
1
- Subclasses implement specific resolution behavior. Must not mutate input state. Should use fork() to create child states. May yield zero states to terminate a branch.
-
-
-
- -
- -
- - -
- run - - -
-
1
run(state: State) -> tuple[State, ...]
-
- -
- -

Execute this node on a State.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
state - State - -
-

Input execution state.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- tuple[State, ...] - -
-

tuple[State, ...]: -Derived execution states.

-
-
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- TypeError - -
-

If resolve() yields a non-State object.

-
-
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/libs/dagpipe/site/dagpipe/state/index.html b/libs/dagpipe/site/dagpipe/state/index.html deleted file mode 100644 index 91bb958..0000000 --- a/libs/dagpipe/site/dagpipe/state/index.html +++ /dev/null @@ -1,2276 +0,0 @@ - - - - - - - - - - - - - - - - - - - State - dagpipe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

State

- - -
- - - -

- dagpipe.state - - -

- -
- -

Defines the core State object used by dagpipe.

-
-

Summary

-

The State represents a single point in pipeline execution. It contains -arbitrary data and metadata and is designed to be immutable. Instead of -modifying an existing state, nodes create new child states via fork().

- - -
- Notes -

Key design principles:

-
1
-2
-3
-4
-5
- **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().
-- **Cheap cloning:** Forking must be efficient since branching may create many states.
-- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.
-- **Domain agnostic:** State contains generic key‑value data and does not assume any schema.
-- **Engine‑friendly:** State contains execution metadata such as depth and history.
-
-
- - -
- - - - - - -

Classes

- -
- - - -

- Payload - - - - dataclass - - -

-
1
Payload(_data: Mapping[str, Any])
-
- -
- - -

Immutable hierarchical container with dot-path access.

- - -

Attributes:

- - - - - - - - - - - - - - - -
NameTypeDescription
_data - Mapping[str, Any] - -
-

Immutable hierarchical data structure.

-
-
- - -
- Notes -

Responsibilities:

-
1
-2
- Stores execution data used by State. Supports efficient atomic updates without modifying existing instances.
-- Payload instances are fully thread-safe due to immutability.
-
-
- - - -
- - - - - - - -
Functions
- -
- - -
- as_dict - - -
-
1
as_dict() -> Mapping[str, Any]
-
- -
- -

Return underlying mapping.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Mapping[str, Any] - -
-

Mapping[str, Any]: -Read-only view of the underlying data.

-
-
- -
- -
- -
- - -
- get - - -
-
1
get(path: str, default: Any = None) -> Any
-
- -
- -

Retrieve value using dot-path.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Dot-separated path to the value.

-
- 		- required -
default - Any - -
-

Default value if path doesn't exist.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Any - Any - -
-

The retrieved value or default.

-
-
- -
- -
- -
- - -
- has - - -
-
1
has(path: str) -> bool
-
- -
- -

Return True if path exists.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Dot-separated path to check.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
bool - bool - -
-

Existence of the path.

-
-
- -
- -
- -
- - -
- iter_paths - - - - classmethod - - -
-
1
iter_paths(data: Mapping[str, Any], prefix: str = '') -> Iterable[str]
-
- -
- -

Recursively yield dot-paths for all leaf nodes.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
data - Mapping[str, Any] - -
-

The mapping to iterate over.

-
- 		- required -
prefix - str - -
-

Current path prefix.

-
- 		- '' -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Iterable[str] - -
-

Iterable[str]: -Generator yielding dot-paths.

-
-
- -
- -
- -
- - -
- keys - - -
-
1
keys() -> Iterable[str]
-
- -
- -

Return top-level keys.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Iterable[str] - -
-

Iterable[str]: -Iterator over top-level keys.

-
-
- -
- -
- -
- - -
- update - - -
-
1
update(updates: Mapping[str, Any]) -> Payload
-
- -
- -

Create a new Payload with dot-path updates applied.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
updates - Mapping[str, Any] - -
-

Dot-path to value mapping.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Payload - Payload - -
-

New immutable payload instance with updates.

-
-
- - -
- Notes -

Guarantees:

-
1
- Preserves existing data by copying only modified branches. Returns a new immutable payload.
-
-
-
- -
- - - -
- -
- -
- -
- - - -

- Schema - - - - dataclass - - -

-
1
Schema(tree: Mapping[str, SchemaNode])
-
- -
- - -

Immutable hierarchical schema defining allowed payload structure.

- - -

Attributes:

- - - - - - - - - - - - - - - -
NameTypeDescription
tree - Mapping[str, SchemaNode] - -
-

Hierarchical schema definition.

-
-
- - -
- Notes -

Responsibilities:

-
1
-2
- Validates State payloads and updates. Reuseable across all State instances.
-- Fully thread-safe due to immutability.
-
-
- - - -
- - - - - - - -
Functions
- -
- - -
- validate_payload - - -
-
1
validate_payload(payload: Payload) -> None
-
- -
- -

Validate complete payload structure.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
payload - Payload - -
-

Payload to validate.

-
- 		- required -
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- SchemaError - -
-

If payload violates schema.

-
-
- -
- -
- -
- - -
- validate_update - - -
-
1
validate_update(updates: Mapping[str, Any]) -> None
-
- -
- -

Validate payload update paths.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
updates - Mapping[str, Any] - -
-

Dot-path updates to validate.

-
- 		- required -
- - -

Raises:

- - - - - - - - - - - - - -
TypeDescription
- SchemaError - -
-

If any path is invalid according to the schema.

-
-
- -
- -
- - - -
- -
- -
- -
- - - -

- SchemaError - - -

- - -
-

- Bases: Exception

- - -

Raised when payload data violates the declared schema.

-
Indicates invalid structure, invalid path, or invalid type.
- - -
- -
- -
- - - -

- State - - - - dataclass - - -

-
1
State(payload: Payload, confidence: float = 1.0, parent: Optional[State] = None, depth: int = 0, history: Tuple[str, ...] = tuple(), metadata: Dict[str, Any] = dict())
-
- -
- - -

Immutable execution state propagated through dagpipe pipeline.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
payload - Payload - -
-

Execution data container.

-
-
schema - ClassVar[Schema] - -
-

Payload validation schema.

-
-
confidence - float - -
-

Execution confidence score.

-
-
parent - Optional[State] - -
-

Parent state reference.

-
-
depth - int - -
-

Execution depth.

-
-
history - Tuple[str, ...] - -
-

Ordered node execution lineage.

-
-
metadata - Dict[str, Any] - -
-

Execution metadata.

-
-
- - -
- Notes -

Responsibilities:

-
1
-2
- Represents a complete execution snapshot at a specific point in pipeline traversal. Fundamental unit of execution in dagpipe.
-- Fully thread-safe due to immutability.
-
-
- - - -
- - - - - - - -
Functions
- -
- - -
- __repr__ - - -
-
1
__repr__() -> str
-
- -
- -

Concise debug representation.

-

Avoids printing full data for large states.

- -
- -
- -
- - -
- fork - - -
-
1
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
-
- -
- -

Create a new child State derived from this State.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
payload_update - Mapping[str, Any] - -
-

Dot-path updates applied to the payload.

-
- 		- None -
confidence_delta - float - -
-

Adjustment applied to current confidence.

-
- 		- 0.0 -
node_id - str - -
-

Identifier of the node creating this state.

-
- 		- None -
metadata_update - Mapping[str, Any] - -
-

Updates merged into state metadata.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
State - State - -
-

A new immutable State instance.

-
-
- - -
- Notes -

Guarantees:

-
1
-2
- This is the only supported mechanism for modifying execution data.
-- Validates payload updates, preserves lineage, increments depth, and appends to history.
-
-
-
- -
- -
- - -
- get - - -
-
1
get(key: str, default: Any = None) -> Any
-
- -
- -

Retrieve payload value.

- - -

Parameters:

- - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
key - str - -
-

Dot-path key.

-
- 		- required -
default - Any - -
-

Fallback value.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Any - Any - -
-

Stored value or default.

-
-
- -
- -
- -
- - -
- has - - -
-
1
has(key: str) -> bool
-
- -
- -

Check whether payload contains key.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
key - str - -
-

Dot-path key.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
bool - bool - -
-

Existence of the key.

-
-
- -
- -
- -
- - -
- lineage - - -
-
1
lineage() -> Tuple[State, ...]
-
- -
- -

Return lineage from root to this State.

- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- Tuple[State, ...] - -
-

Tuple[State, ...]: -Ordered execution lineage (root first).

-
-
- -
- -
- - - -
- -
- -
- - - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/libs/dagpipe/site/dagpipe/yaml_loader/index.html b/libs/dagpipe/site/dagpipe/yaml_loader/index.html deleted file mode 100644 index fe7a1ce..0000000 --- a/libs/dagpipe/site/dagpipe/yaml_loader/index.html +++ /dev/null @@ -1,1136 +0,0 @@ - - - - - - - - - - - - - - - - - - - Yaml Loader - dagpipe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - -
- - -
- -
- - - - - - -
-
- - - -
-
-
- - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - -

Yaml Loader

- - -
- - - -

- dagpipe.yaml_loader - - -

- -
- -

Loads dagpipe pipelines from YAML configuration.

-
-

Summary

-

Creates fully configured pipeline objects from declarative YAML definitions, -including Schema, State subclasses, Node instances, Graph topology, -and initial Payloads.

- - - -
- - - - - - -

Classes

- -
- - - -

- Pipeline - - - - dataclass - - -

-
1
Pipeline(engine: Engine, state_cls: Type[State], initial_payload: Payload)
-
- -
- - -

Executable pipeline created from YAML configuration.

- - -

Attributes:

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
engine - Engine - -
-

Execution engine responsible for running the pipeline.

-
-
state_cls - Type[State] - -
-

Dynamically created State subclass with configured schema.

-
-
initial_payload - Payload - -
-

Default payload used when execution begins.

-
-
- - -
- Notes -

Responsibilities:

-
1
-2
- Encapsulates engine, state type, and initial payload. Provides a simplified interface for executing configured pipelines.
-- Safe for concurrent execution if underlying Nodes are thread-safe.
-
-
- - - -
- - - - - - - -
Functions
- -
- - -
- run - - -
-
1
run(payload_override: Optional[Mapping[str, Any]] = None)
-
- -
- -

Execute pipeline.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
payload_override - Mapping[str, Any] - -
-

Payload values overriding initial payload.

-
- 		- None -
- - -

Returns:

- - - - - - - - - - - - - -
TypeDescription
- -
-

list[State]: -Terminal execution states.

-
-
- - -
- Notes -

Responsibilities:

-
1
- Merges override payload with initial payload, creates root State, and executes engine.
-
-
-
- -
- - - -
- -
- -
-

Functions

- -
- - -

- load_pipeline - - -

-
1
load_pipeline(path: str) -> Pipeline
-
- -
- -

Load pipeline from YAML file.

- - -

Parameters:

- - - - - - - - - - - - - - - - - -
NameTypeDescriptionDefault
path - str - -
-

Path to YAML configuration file.

-
- 		- required -
- - -

Returns:

- - - - - - - - - - - - - -
Name TypeDescription
Pipeline - Pipeline - -
-

Executable pipeline instance.

-
-
- - -
- Notes -

Responsibilities:

-
1
- Loads YAML configuration, builds schema, creates State subclass, loads Node instances, builds Graph topology, and initializes Engine.
-
-
-
- -
- - - -
- -
- -
- - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - \ No newline at end of file diff --git a/libs/dagpipe/site/engine/index.html b/libs/dagpipe/site/engine/index.html index ffd74fb..94690e6 100644 --- a/libs/dagpipe/site/engine/index.html +++ b/libs/dagpipe/site/engine/index.html @@ -599,6 +599,15 @@ + + +
  • + + + Guarantees + + +
  • @@ -831,6 +840,15 @@ +
    • + +
  • + + + Guarantees + + +
  • @@ -956,23 +974,19 @@
    -

    Execution engine responsible for running pipelines and graphs.

    -
    -

    Summary

    -

    The Engine executes Node objects and propagates immutable State instances -through either a linear sequence or a directed acyclic graph (Graph). +

    Summary

    +

    Execution engine responsible for running pipelines and graphs.

    +

    The Engine executes Node objects and propagates immutable State instances +through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.

    +
    +

    Guarantees

    +
      +
    • Deterministic execution and consistent state lineage.
      • +
    • Orchestrates execution without modifying Graph, Node, or State objects.
      • +
    -
    - Notes -

    Guarantees:

    -
    1
-2
    - Deterministic execution and consistent state lineage.
-- Orchestrates execution without modifying Graph, Node, or State objects.
-
    -
    -
    @@ -1005,15 +1019,21 @@ It orchestrates execution order, branching, and state propagation.

    Notes

    Responsibilities:

    1
-2
    - Accepts either a linear sequence of Nodes or a Graph defining execution topology.
-- Propagates immutable State objects through Nodes and collects terminal States.
+2
+3
+4
    - Accepts either a linear sequence of `Node` objects or a `Graph`
+  defining execution topology.
+- Propagates immutable `State` objects through `Node` objects and
+  collects terminal states.

    Guarantees:

    1
 2
 3
-4
    - Never mutates State, Node, or Graph instances.
-- State objects are never modified in place; each branch produces independent instances.
+4
+5
    - Never mutates `State`, `Node`, or `Graph` instances.
+- `State` objects are never modified in place; each branch produces
+  independent instances.
 - Execution order is deterministic and follows graph or pipeline topology.
 - Thread-safe for concurrent execution.
    @@ -1035,7 +1055,7 @@ It orchestrates execution order, branching, and state propagation.

    nodes_or_graph - Sequence[Node] | Graph + Sequence[Node] | Graph
    @@ -1065,7 +1085,8 @@ It orchestrates execution order, branching, and state propagation.

    -

    If input is not a Sequence[Node] or Graph, or contains invalid node types.

    +

    If input is not a Sequence[Node] or Graph, or contains +invalid node types.

    @@ -1076,7 +1097,9 @@ It orchestrates execution order, branching, and state propagation.

    Notes

    Responsibilities:

    -
    @@ -1286,7 +1309,9 @@ Terminal execution states produced by the pipeline.

    Notes

    Responsibilities:

    -
    1
    - Detects execution mode (linear or DAG) and validates node types and structure.
+
    1
+2
    - Detects execution mode (linear or DAG) and validates node
+  types and structure.
 
    
 
 
@@ -1122,7 +1145,7 @@ It orchestrates execution order, branching, and state propagation.
    - tuple[Node, ...] + tuple[Node, ...]
    @@ -1194,7 +1217,7 @@ Ordered sequence in linear mode or all nodes in graph mode.

    -

    Execute the pipeline starting from a root State.

    +

    Execute the pipeline starting from a root State.

    Parameters:

    @@ -1211,7 +1234,7 @@ Ordered sequence in linear mode or all nodes in graph mode.

    root - State + State
    @@ -1237,7 +1260,7 @@ Ordered sequence in linear mode or all nodes in graph mode.
    - List[State] + List[State]
    @@ -1265,7 +1288,7 @@ Terminal execution states produced by the pipeline.
    -

    If root is not a State instance.

    +

    If root is not a State instance.

    		 
    1
    - Selects execution mode, propagates state through nodes, creates new instances for branches, and collects terminal states.
+
    1
+2
    - Selects execution mode, propagates state through nodes, creates
+  new instances for branches, and collects terminal states.
    diff --git a/libs/dagpipe/site/graph/index.html b/libs/dagpipe/site/graph/index.html index b34ce64..455189a 100644 --- a/libs/dagpipe/site/graph/index.html +++ b/libs/dagpipe/site/graph/index.html @@ -520,6 +520,15 @@ + + +
  • + + + Responsibilities + + +
  • @@ -586,42 +595,6 @@ -
    • - -
  • - - - Add directed edge from src to dst. - - - -
    • - -
  • - - - Parameters - - - -
    • - -
  • - - - Raises - - - -
    • - -
  • - - - Behavior - - -
  • @@ -906,6 +879,15 @@ +
    • + +
  • + + + Responsibilities + + +
  • @@ -972,42 +954,6 @@ -
    • - -
  • - - - Add directed edge from src to dst. - - - -
    • - -
  • - - - Parameters - - - -
    • - -
  • - - - Raises - - - -
    • - -
  • - - - Behavior - - -
  • @@ -1106,24 +1052,19 @@
    -

    Defines DAG structure connecting Nodes.

    +

    Summary

    +

    Defines DAG structure connecting nodes.

    +

    A Graph describes execution topology only. It does not execute nodes or manage +State. Execution is handled by an Engine.

    -

    Summary

    -

    Graph describes execution topology only. It does not execute nodes or manage State. -Execution is handled by Engine.

    +

    Responsibilities

    +
      +
    • Multiple roots, branching, and merging support.
      • +
    • Deterministic traversal based on topology.
      • +
    • Graph is mutable during construction but treated as immutable at runtime.
      • +
    -
    - Notes -

    Responsibilities:

    -
    1
-2
-3
    - Multiple roots, branching, and merging support.
-- Deterministic traversal based on topology.
-- Graph is mutable during construction but treated as immutable at runtime.
-
    -
    -
    @@ -1149,7 +1090,7 @@ Execution is handled by Engine.

    -

    Directed Acyclic Graph defining execution topology of Nodes.

    +

    Directed Acyclic Graph defining execution topology of Node objects.

    @@ -1157,7 +1098,7 @@ Execution is handled by Engine.

    Responsibilities:

    1
 2
    - Stores node connectivity and validates that the topology remains acyclic.
-- Structure determines how State flows between nodes during execution.
+- Structure determines how `State` flows between nodes during execution.

    Guarantees:

    1
@@ -1215,35 +1156,94 @@ Execution is handled by Engine.
    
 
     
    
 
-      
    Add directed edge from src to dst.
    
-
    Parameters
    
-
    src : Node
-    required: True
-    source node
    
+      
    Add a directed edge from src to dst.
    
 
 
-
    
-  Node
-  
    required: True
-destination node
    
-
          
    
-
    Raises
    
-
    TypeError
-    if src or dst is not a Node
    
-
    ValueError
-    if edge would create a cycle
    
-
    ValueError
-    if src and dst are the same node
    
-
    
-
    Behavior
    
-
      
-
    • validates node types
      • 
-
    • prevents cycles
      • 
-
    • registers nodes if not present
      • 
-
    • updates parent and child mappings
      • 
+
      Parameters:
      
+    
+      
+        
+          
+          
+          
+          
+        
+      
+      
+          
+            
+            
+            
+            
+          
+          
+            
+            
+            
+            
+          
+      
+    
      NameTypeDescriptionDefault
      src
+                  Node
+            
+              
      
+                
      Source node.
      
+              
      
+                  		
+                required
+            
      dst
+                  Node
+            
+              
      
+                
      Destination node.
      
+              
      
+                  		
+                required
+            
      
+
+
+
      Raises:
      
+    
+      
+        
+          
+          
+        
+      
+      
+          
+            
+            
+          
+          
+            
+            
+          
+      
+    
      TypeDescription
      
+                  TypeError
+            
+              
      
+                
      If src or dst is not a Node.
      
+              
      
+            
      
+                  ValueError
+            
+              
      
+                
      If the edge would create a cycle or if src and dst are common.
      
+              
      
+            
      
+
+
+
      
+  Notes
+  
        
+
      • Validates node types.
        • 
+
      • Prevents cycles.
        • 
+
      • Registers nodes if not present.
        • 
+
      • Updates parent and child mappings.
        • 
 
      
-
      
-
+
    @@ -1278,7 +1278,7 @@ destination node

    node - Node + Node
    @@ -1349,7 +1349,7 @@ destination node

    node - Node + Node
    @@ -1375,7 +1375,7 @@ destination node
    - Tuple[Node, ...] + Tuple[Node, ...]
    @@ -1418,7 +1418,7 @@ Outgoing neighbors.
    - Tuple[Node, ...] + Tuple[Node, ...]
    @@ -1464,7 +1464,7 @@ All registered nodes.

    node - Node + Node
    @@ -1490,7 +1490,7 @@ All registered nodes.
    - Tuple[Node, ...] + Tuple[Node, ...]
    @@ -1533,7 +1533,7 @@ Incoming neighbors.
    - Tuple[Node, ...] + Tuple[Node, ...]
    diff --git a/libs/dagpipe/site/index.html b/libs/dagpipe/site/index.html index b82bd68..2819805 100644 --- a/libs/dagpipe/site/index.html +++ b/libs/dagpipe/site/index.html @@ -316,6 +316,39 @@ + +
  • @@ -325,6 +358,603 @@ + +
  • @@ -334,6 +964,21 @@ + +
    • @@ -814,6 +1459,39 @@ + +
  • @@ -823,6 +1501,603 @@ + +
  • @@ -832,6 +2107,21 @@ + +
    • @@ -870,68 +2160,73 @@
    -

    Directed acyclic graph execution framework for deterministic state propagation.

    -
    -

    Summary

    +

    Summary

    +

    Directed acyclic graph execution framework for deterministic state propagation.

    dagpipe executes pipelines composed of nodes connected in a directed acyclic -graph (DAG). Each node receives an immutable state and optionally produces +graph (DAG). Each node receives an immutable State and optionally produces derived states for downstream nodes.

    -
    -

    Installation

    +

    Installation

    Install using pip:

    -
    1
    pip install dagpipe
-
    +
    1
    pip install dagpipe
+
    -

    Quick Start

    -
     1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
    from dagpipe import State, Payload, Schema, Graph, Engine
-from dagpipe.node import Node
-
-class HelloNode(Node):
-    id = "hello"
-    def resolve(self, state):
-        yield self.fork(state, payload_update={"msg": "hello"})
-
-# Build and run
-graph = Graph()
-graph.add_root(HelloNode())
-engine = Engine(graph)
-
-class MyState(State):
-    schema = Schema({})
-
-results = engine.run(MyState(payload=Payload({})))
-
    +

    Quick Start

    +
     1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
    from dagpipe import State, Payload, Schema, Graph, Engine
+from dagpipe.node import Node
+
+class HelloNode(Node):
+    id = "hello"
+    def resolve(self, state):
+        yield self.fork(state, payload_update={"msg": "hello"})
+
+# Build and run
+graph = Graph()
+graph.add_root(HelloNode())
+engine = Engine(graph)
+
+class MyState(State):
+    schema = Schema({})
+
+results = engine.run(MyState(payload=Payload({})))
+
    -

    Public API

    +

    Public API

    This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.

    -

    Execution Core: -- Engine -- Graph -- Node

    -

    State & Data: -- State / MyState (custom base) -- Payload -- Schema / SchemaError

    -

    Declarative Pipelines: -- Pipeline -- load_pipeline

    +

    Execution Core

    +
      +
    • Engine: Responsible for orchestrating node execution and state propagation.
      • +
    • Graph: Defines the execution topology and node relationships.
      • +
    • Node: Base class for defining execution logic and transformations.
      • +
    +

    State & Data

    +
      +
    • State: Represents an immutable execution snapshot at a point in time.
      • +
    • Payload: Immutable hierarchical container for execution data.
      • +
    • Schema: Defines and validates the allowed structure of payloads.
      • +
    • SchemaError: Raised when data violates the declared schema.
      • +
    +

    Declarative Pipelines

    +
      +
    • Pipeline: High-level wrapper for an engine, state type, and initial payload.
      • +
    • load_pipeline: Factory function to create a pipeline from YAML.
      • +
    @@ -944,7 +2239,327 @@ Consumers should import from this namespace for standard usage.

    Classes

    -

    Functions

    + +
    + + + +

    + Engine + + +

    +
    1
    Engine(nodes_or_graph: Union[Sequence[Node], Graph])
+
    + +
    + + +

    Execution engine responsible for running pipeline logic.

    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
+3
+4
    - Accepts either a linear sequence of `Node` objects or a `Graph`
+  defining execution topology.
+- Propagates immutable `State` objects through `Node` objects and
+  collects terminal states.
+
    +

    Guarantees:

    +
    1
+2
+3
+4
+5
    - Never mutates `State`, `Node`, or `Graph` instances.
+- `State` objects are never modified in place; each branch produces
+  independent instances.
+- Execution order is deterministic and follows graph or pipeline topology.
+- Thread-safe for concurrent execution.
+
    +
    +

    Initialize the execution engine.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    nodes_or_graph + Sequence[Node] | Graph + +
    +

    Pipeline definition. May be a linear sequence or a DAG.

    +
    +     		+ required +
    + + +

    Raises:

    + + + + + + + + + + + + + +
    TypeDescription
    + TypeError + +
    +

    If input is not a Sequence[Node] or Graph, or contains +invalid node types.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
    - Detects execution mode (linear or DAG) and validates node
+  types and structure.
+
    +
    + + + +
    + + + + + +
    Attributes
    + +
    + + + +
    + nodes + + + + property + + +
    +
    1
    nodes: tuple[Node, ...]
+
    + +
    + +

    Return nodes managed by this engine.

    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + tuple[Node, ...] + +
    +

    tuple[Node, ...]: +Ordered sequence in linear mode or all nodes in graph mode.

    +
    +
    +
    + +
    + +
    Functions
    + +
    + + +
    + __repr__ + + +
    +
    1
    __repr__() -> str
+
    + +
    + +

    Return the canonical string representation of the object.

    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    str + str + +
    +

    Representation that uniquely identifies the object and its configuration.

    +
    +
    + +
    + +
    + +
    + + +
    + run + + +
    +
    1
    run(root: State) -> List[State]
+
    + +
    + +

    Execute the pipeline starting from a root State.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    root + State + +
    +

    Initial execution state.

    +
    +     		+ required +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + List[State] + +
    +

    list[State]: +Terminal execution states produced by the pipeline.

    +
    +
    + + +

    Raises:

    + + + + + + + + + + + + + + + + + +
    TypeDescription
    + TypeError + +
    +

    If root is not a State instance.

    +
    +
    + RuntimeError + +
    +

    If the engine execution mode is invalid.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
    - Selects execution mode, propagates state through nodes, creates
+  new instances for branches, and collects terminal states.
+
    +
    +
    + +
    @@ -952,9 +2567,2627 @@ Consumers should import from this namespace for standard usage.

    -
    + +
    + + + +

    + Graph + + +

    +
    1
    Graph()
+
    + +
    + + +

    Directed Acyclic Graph defining execution topology of Node objects.

    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
    - Stores node connectivity and validates that the topology remains acyclic.
+- Structure determines how `State` flows between nodes during execution.
+
    +

    Guarantees:

    +
    1
+2
    - Topology is acyclic. Node relationships remain consistent.
+- Thread-safe for concurrent reads after construction.
+
    +
    +

    Create an empty Graph.

    +
    Initializes node registry and edge mappings.
    + + + + +
    + + + + + + + +
    Functions
    + +
    + + +
    + __repr__ + + +
    +
    1
    __repr__() -> str
+
    + +
    + +

    Return debug representation.

    +
    Returns
    +

    str

    + +
    + +
    + +
    + + +
    + add_edge + + +
    +
    1
    add_edge(src: Node, dst: Node) -> None
+
    + +
    + +

    Add a directed edge from src to dst.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    src + Node + +
    +

    Source node.

    +
    +     		+ required +
    dst + Node + +
    +

    Destination node.

    +
    +     		+ required +
    + + +

    Raises:

    + + + + + + + + + + + + + + + + + +
    TypeDescription
    + TypeError + +
    +

    If src or dst is not a Node.

    +
    +
    + ValueError + +
    +

    If the edge would create a cycle or if src and dst are common.

    +
    +
    + + +
    + Notes +
      +
    • Validates node types.
      • +
    • Prevents cycles.
      • +
    • Registers nodes if not present.
      • +
    • Updates parent and child mappings.
    +
    +
    + +
    + +
    + + +
    + add_root + + +
    +
    1
    add_root(node: Node) -> None
+
    + +
    + +

    Add a root node with no parents.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    node + Node + +
    +

    Node to add as a root.

    +
    +     		+ required +
    + + +

    Raises:

    + + + + + + + + + + + + + +
    TypeDescription
    + TypeError + +
    +

    If node is not a Node instance.

    +
    +
    + +
    + +
    + +
    + + +
    + children + + +
    +
    1
    children(node: Node) -> Tuple[Node, ...]
+
    + +
    + +

    Return child nodes of a node.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    node + Node + +
    +

    Node to query.

    +
    +     		+ required +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Tuple[Node, ...] + +
    +

    Tuple[Node, ...]: +Outgoing neighbors.

    +
    +
    + +
    + +
    + +
    + + +
    + nodes + + +
    +
    1
    nodes() -> Tuple[Node, ...]
+
    + +
    + +

    Return all nodes in the graph.

    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Tuple[Node, ...] + +
    +

    Tuple[Node, ...]: +All registered nodes.

    +
    +
    + +
    + +
    + +
    + + +
    + parents + + +
    +
    1
    parents(node: Node) -> Tuple[Node, ...]
+
    + +
    + +

    Return parent nodes of a node.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    node + Node + +
    +

    Node to query.

    +
    +     		+ required +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Tuple[Node, ...] + +
    +

    Tuple[Node, ...]: +Incoming neighbors.

    +
    +
    + +
    + +
    + +
    + + +
    + roots + + +
    +
    1
    roots() -> Tuple[Node, ...]
+
    + +
    + +

    Return root nodes (nodes with no incoming edges).

    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Tuple[Node, ...] + +
    +

    Tuple[Node, ...]: +Entry point nodes.

    +
    +
    + +
    + +
    + + + +
    + +
    + +
    + +
    + + + +

    + Node + + +

    + + +
    +

    + Bases: ABC

    + + +

    Base class for all dagpipe execution nodes.

    + + +

    Attributes:

    + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescription
    id + str + +
    +

    Unique identifier of the node (snake_case dotted format).

    +
    +
    name + str + +
    +

    Human-readable display name.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
+3
    - Represents a deterministic unit of execution in the pipeline graph.
+- Consumes one `State` and produces zero, one, or many derived states.
+- Defines execution logic and enables branching, filtering, and transformation.
+
    +

    Guarantees:

    +
    1
+2
    - Nodes must never mutate the input `State`.
+- Instances are singletons per subclass and reused across executions.
+
    +
    + + + +
    + + + + + + + +
    Functions
    + +
    + + +
    + __hash__ + + +
    +
    1
    __hash__() -> int
+
    + +
    + +

    Return stable hash based on node ID.

    +
    Returns
    +

    int

    + +
    + +
    + +
    + + +
    + __new__ + + +
    +
    1
    __new__() -> Node
+
    + +
    + +

    Create or reuse singleton instance of the Node subclass.

    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    Node + Node + +
    +

    Singleton instance of the subclass.

    +
    +
    + +
    + +
    + +
    + + +
    + __repr__ + + +
    +
    1
    __repr__() -> str
+
    + +
    + +

    Return debug representation.

    +
    Returns
    +

    str

    + +
    + +
    + +
    + + +
    + __str__ + + +
    +
    1
    __str__() -> str
+
    + +
    + +

    Return display representation.

    +
    Returns
    +

    str

    + +
    + +
    + +
    + + +
    + clean_id_and_name + + + + classmethod + + +
    +
    1
    clean_id_and_name() -> None
+
    + +
    + +

    Normalize and validate node ID and display name.

    + + +

    Raises:

    + + + + + + + + + + + + + + + + + +
    TypeDescription
    + TypeError + +
    +

    If ID is not a string.

    +
    +
    + ValueError + +
    +

    If ID format is invalid.

    +
    +
    + + +
    + Notes +

    Guarantees:

    +
    1
+2
+3
    - Generates ID from module and class name if missing.
+- Validates ID format.
+- Generates human-readable name if missing.
+
    +
    +
    + +
    + +
    + + +
    + fork + + +
    +
    1
    fork(state: State, *, payload_update=None, confidence_delta=0.0, metadata_update=None) -> State
+
    + +
    + +

    Create a child State attributed to this node.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    state + State + +
    +

    Parent execution state.

    +
    +     		+ required +
    payload_update + Mapping[str, Any] + +
    +

    Dot-path payload updates.

    +
    +     		+ None +
    confidence_delta + float + +
    +

    Confidence adjustment.

    +
    +     		+ 0.0 +
    metadata_update + Mapping[str, Any] + +
    +

    Metadata updates.

    +
    +     		+ None +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    State + State + +
    +

    New child execution state.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
    - Convenience wrapper around `State.fork()` that automatically
+  records this node's ID in state history.
+
    +
    +
    + +
    + +
    + + +
    + node_id_to_name + + + + staticmethod + + +
    +
    1
    node_id_to_name(node_id: str) -> str
+
    + +
    + +

    Convert a dotted snake_case node ID into a human-readable name.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    node_id + str + +
    +

    Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

    +
    +     		+ required +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    str + str + +
    +

    Human-readable display name (e.g., 'Entity › Resolve › Numeric Merchant').

    +
    +
    + +
    + +
    + +
    + + +
    + resolve + + + + abstractmethod + + +
    +
    1
    resolve(state: State) -> Iterable[State]
+
    + +
    + +

    Execute node logic.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    state + State + +
    +

    Input execution state.

    +
    +     		+ required +
    + + +

    Yields:

    + + + + + + + + + + + + + +
    Name TypeDescription
    State + Iterable[State] + +
    +

    Derived execution state(s).

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
+3
+4
    - Subclasses implement specific resolution behavior.
+- Must not mutate input state.
+- Should use `fork()` to create child states.
+- May yield zero states to terminate a branch.
+
    +
    +
    + +
    + +
    + + +
    + run + + +
    +
    1
    run(state: State) -> tuple[State, ...]
+
    + +
    + +

    Execute this node on a State.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    state + State + +
    +

    Input execution state.

    +
    +     		+ required +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + tuple[State, ...] + +
    +

    tuple[State, ...]: +Derived execution states.

    +
    +
    + + +

    Raises:

    + + + + + + + + + + + + + +
    TypeDescription
    + TypeError + +
    +

    If resolve() yields a non-State object.

    +
    +
    + +
    + +
    + + + +
    + +
    + +
    + +
    + + + +

    + Payload + + + + dataclass + + +

    +
    1
    Payload(_data: Mapping[str, Any])
+
    + +
    + + +

    Immutable hierarchical container with dot-path access.

    + + +

    Attributes:

    + + + + + + + + + + + + + + + +
    NameTypeDescription
    _data + Mapping[str, Any] + +
    +

    Immutable hierarchical data structure.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
+3
    - Stores execution data used by `State`.
+- Supports efficient atomic updates without modifying existing instances.
+- `Payload` instances are fully thread-safe due to immutability.
+
    +
    + + + +
    + + + + + + + +
    Functions
    + +
    + + +
    + as_dict + + +
    +
    1
    as_dict() -> Mapping[str, Any]
+
    + +
    + +

    Return underlying mapping.

    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Mapping[str, Any] + +
    +

    Mapping[str, Any]: +Read-only view of the underlying data.

    +
    +
    + +
    + +
    + +
    + + +
    + get + + +
    +
    1
    get(path: str, default: Any = None) -> Any
+
    + +
    + +

    Retrieve value using dot-path.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    path + str + +
    +

    Dot-separated path to the value.

    +
    +     		+ required +
    default + Any + +
    +

    Default value if path doesn't exist.

    +
    +     		+ None +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    Any + Any + +
    +

    The retrieved value or default.

    +
    +
    + +
    + +
    + +
    + + +
    + has + + +
    +
    1
    has(path: str) -> bool
+
    + +
    + +

    Return True if path exists.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    path + str + +
    +

    Dot-separated path to check.

    +
    +     		+ required +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    bool + bool + +
    +

    Existence of the path.

    +
    +
    + +
    + +
    + +
    + + +
    + iter_paths + + + + classmethod + + +
    +
    1
    iter_paths(data: Mapping[str, Any], prefix: str = '') -> Iterable[str]
+
    + +
    + +

    Recursively yield dot-paths for all leaf nodes.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    data + Mapping[str, Any] + +
    +

    The mapping to iterate over.

    +
    +     		+ required +
    prefix + str + +
    +

    Current path prefix.

    +
    +     		+ '' +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Iterable[str] + +
    +

    Iterable[str]: +Generator yielding dot-paths.

    +
    +
    + +
    + +
    + +
    + + +
    + keys + + +
    +
    1
    keys() -> Iterable[str]
+
    + +
    + +

    Return top-level keys.

    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Iterable[str] + +
    +

    Iterable[str]: +Iterator over top-level keys.

    +
    +
    + +
    + +
    + +
    + + +
    + update + + +
    +
    1
    update(updates: Mapping[str, Any]) -> Payload
+
    + +
    + +

    Create a new Payload with dot-path updates applied.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    updates + Mapping[str, Any] + +
    +

    Dot-path to value mapping.

    +
    +     		+ required +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    Payload + Payload + +
    +

    New immutable payload instance with updates.

    +
    +
    + + +
    + Notes +

    Guarantees:

    +
    1
+2
    - Preserves existing data by copying only modified branches.
+- Returns a new immutable `Payload`.
+
    +
    +
    + +
    + + + +
    + +
    + +
    + +
    + + + +

    + Pipeline + + + + dataclass + + +

    +
    1
    Pipeline(engine: Engine, state_cls: Type[State], initial_payload: Payload)
+
    + +
    + + +

    Executable pipeline created from YAML configuration.

    + + +

    Attributes:

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescription
    engine + Engine + +
    +

    Execution engine responsible for running the pipeline.

    +
    +
    state_cls + Type[State] + +
    +

    Dynamically created State subclass with configured schema.

    +
    +
    initial_payload + Payload + +
    +

    Default payload used when execution begins.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
+3
    - Encapsulates engine, state type, and initial payload.
+- Provides a simplified interface for executing configured pipelines.
+- Safe for concurrent execution if underlying nodes are thread-safe.
+
    +
    + + + +
    + + + + + + + +
    Functions
    + +
    + + +
    + run + + +
    +
    1
    run(payload_override: Optional[Mapping[str, Any]] = None) -> list[State]
+
    + +
    + +

    Execute the pipeline.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    payload_override + Mapping[str, Any] + +
    +

    Payload values overriding initial payload.

    +
    +     		+ None +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + list[State] + +
    +

    list[State]: +Terminal execution states.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
    - Merges override payload with initial payload.
+- Creates root `State` and executes engine.
+
    +
    +
    + +
    + + + +
    + +
    + +
    + +
    + + + +

    + Schema + + + + dataclass + + +

    +
    1
    Schema(tree: Mapping[str, SchemaNode])
+
    + +
    + + +

    Immutable hierarchical schema defining allowed payload structure.

    + + +

    Attributes:

    + + + + + + + + + + + + + + + +
    NameTypeDescription
    tree + Mapping[str, SchemaNode] + +
    +

    Hierarchical schema definition.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
+3
    - Validates `State` payloads and updates.
+- Reusable across all `State` instances.
+- Fully thread-safe due to immutability.
+
    +
    + + + +
    + + + + + + + +
    Functions
    + +
    + + +
    + validate_payload + + +
    +
    1
    validate_payload(payload: Payload) -> None
+
    + +
    + +

    Validate complete payload structure.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    payload + Payload + +
    +

    Payload to validate.

    +
    +     		+ required +
    + + +

    Raises:

    + + + + + + + + + + + + + +
    TypeDescription
    + SchemaError + +
    +

    If payload violates schema.

    +
    +
    + +
    + +
    + +
    + + +
    + validate_update + + +
    +
    1
    validate_update(updates: Mapping[str, Any]) -> None
+
    + +
    + +

    Validate payload update paths.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    updates + Mapping[str, Any] + +
    +

    Dot-path updates to validate.

    +
    +     		+ required +
    + + +

    Raises:

    + + + + + + + + + + + + + +
    TypeDescription
    + SchemaError + +
    +

    If any path is invalid according to the schema.

    +
    +
    + +
    + +
    + + + +
    + +
    + +
    + +
    + + + +

    + SchemaError + + +

    + + +
    +

    + Bases: Exception

    + + +

    Raised when payload data violates the declared schema.

    +
    Indicates invalid structure, invalid path, or invalid type.
    + + +
    + +
    + +
    + + + +

    + State + + + + dataclass + + +

    +
    1
    State(payload: Payload, confidence: float = 1.0, parent: Optional[State] = None, depth: int = 0, history: Tuple[str, ...] = tuple(), metadata: Dict[str, Any] = dict())
+
    + +
    + + +

    Immutable execution state propagated through dagpipe pipeline.

    + + +

    Attributes:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescription
    payload + Payload + +
    +

    Execution data container.

    +
    +
    schema + ClassVar[Schema] + +
    +

    Payload validation schema.

    +
    +
    confidence + float + +
    +

    Execution confidence score.

    +
    +
    parent + Optional[State] + +
    +

    Parent state reference.

    +
    +
    depth + int + +
    +

    Execution depth.

    +
    +
    history + Tuple[str, ...] + +
    +

    Ordered node execution lineage.

    +
    +
    metadata + Dict[str, Any] + +
    +

    Execution metadata.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
+3
+4
    - Represents a complete execution snapshot at a specific point in
+  pipeline traversal.
+- Fundamental unit of execution in `dagpipe`.
+- Fully thread-safe due to immutability.
+
    +
    + + + +
    + + + + + + + +
    Functions
    + +
    + + +
    + __repr__ + + +
    +
    1
    __repr__() -> str
+
    + +
    + +

    Concise debug representation.

    +

    Avoids printing full data for large states.

    + +
    + +
    + +
    + + +
    + fork + + +
    +
    1
    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
+
    + +
    + +

    Create a new child State derived from this state.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    payload_update + Mapping[str, Any] + +
    +

    Dot-path updates applied to the payload.

    +
    +     		+ None +
    confidence_delta + float + +
    +

    Adjustment applied to current confidence.

    +
    +     		+ 0.0 +
    node_id + str + +
    +

    Identifier of the node creating this state.

    +
    +     		+ None +
    metadata_update + Mapping[str, Any] + +
    +

    Updates merged into state metadata.

    +
    +     		+ None +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    State + State + +
    +

    A new immutable State instance.

    +
    +
    + + +
    + Notes +

    Guarantees:

    +
    1
+2
+3
    - This is the only supported mechanism for modifying execution data.
+- Validates payload updates, preserves lineage, increments depth,
+  and appends to history.
+
    +
    +
    + +
    + +
    + + +
    + get + + +
    +
    1
    get(key: str, default: Any = None) -> Any
+
    + +
    + +

    Retrieve payload value.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    key + str + +
    +

    Dot-path key.

    +
    +     		+ required +
    default + Any + +
    +

    Fallback value.

    +
    +     		+ None +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    Any + Any + +
    +

    Stored value or default.

    +
    +
    + +
    + +
    + +
    + + +
    + has + + +
    +
    1
    has(key: str) -> bool
+
    + +
    + +

    Check whether payload contains key.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    key + str + +
    +

    Dot-path key.

    +
    +     		+ required +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    bool + bool + +
    +

    Existence of the key.

    +
    +
    + +
    + +
    + +
    + + +
    + lineage + + +
    +
    1
    lineage() -> Tuple[State, ...]
+
    + +
    + +

    Return lineage from root to this State.

    + + +

    Returns:

    + + + + + + + + + + + + + +
    TypeDescription
    + Tuple[State, ...] + +
    +

    Tuple[State, ...]: +Ordered execution lineage (root first).

    +
    +
    + +
    + +
    + + + +
    + +
    + +
    +

    Functions

    + +
    + + +

    + load_pipeline + + +

    +
    1
    load_pipeline(path: str) -> Pipeline
+
    + +
    + +

    Load pipeline from YAML file.

    + + +

    Parameters:

    + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    path + str + +
    +

    Path to YAML configuration file.

    +
    +     		+ required +
    + + +

    Returns:

    + + + + + + + + + + + + + +
    Name TypeDescription
    Pipeline + Pipeline + +
    +

    Executable pipeline instance.

    +
    +
    + + +
    + Notes +

    Responsibilities:

    +
    1
+2
+3
    - Loads YAML configuration and builds schema.
+- Creates `State` subclass and loads `Node` instances.
+- Builds `Graph` topology and initializes `Engine`.
+
    +
    +
    + +
    + + + +
    + +
    + + diff --git a/libs/dagpipe/site/node/index.html b/libs/dagpipe/site/node/index.html index c44d3ad..3f69082 100644 --- a/libs/dagpipe/site/node/index.html +++ b/libs/dagpipe/site/node/index.html @@ -441,6 +441,15 @@ + + +
  • + + + Design principles + + +
  • @@ -897,6 +906,15 @@ +
    • + +
  • + + + Design principles + + +
  • @@ -1088,27 +1106,21 @@
    -

    Defines the Node abstraction used by dagpipe.

    +

    Summary

    +

    Defines the Node abstraction used by dagpipe.

    +

    A node represents a single unit of pipeline execution logic. It consumes one +State and produces zero, one, or many new State objects.

    +

    Nodes are connected using a Graph and executed by an Engine.

    -

    Summary

    -

    A Node represents a single unit of pipeline execution logic. It consumes one -State and produces zero, one, or many new States.

    -

    Nodes are connected using Graph and executed by Engine.

    +

    Design principles

    +
      +
    • Pure: Must not mutate input state.
      • +
    • Deterministic: Same input produces same output.
      • +
    • Stateless: Recommended to be stateless for reuse.
      • +
    • Composable: Nodes enable branching execution graphs.
      • +
    -
    - Notes -

    Design Principles:

    -
    1
-2
-3
-4
    - **Pure:** Must not mutate input state.
-- **Deterministic:** Same input produces same output.
-- **Stateless:** Recommended to be stateless for reuse.
-- **Composable:** Nodes enable branching execution graphs.
-
    -
    -
    @@ -1180,11 +1192,13 @@ State and produces zero, one, or many new States.

    1
 2
 3
    - Represents a deterministic unit of execution in the pipeline graph.
-- Consumes one State and produces zero, one, or many derived States.
+- Consumes one `State` and produces zero, one, or many derived states.
 - Defines execution logic and enables branching, filtering, and transformation.

    Guarantees:

    -
    1
    - Nodes must never mutate the input State. Instances are singletons per subclass and reused across executions.
+
    1
+2
    - Nodes must never mutate the input `State`.
+- Instances are singletons per subclass and reused across executions.
 
    
 
 
@@ -1229,7 +1243,7 @@ State and produces zero, one, or many new States.
    
 
 
 
-
    1
    __new__()
+
    1
    __new__() -> Node
 
    
 
     
    
@@ -1248,6 +1262,7 @@ State and produces zero, one, or many new States.
    
       
    
           
    
 Node            
+                  Node
             
             
               
    
@@ -1384,7 +1399,7 @@ State and produces zero, one, or many new States.
    
 
     
    
 
-      
    Create a child State attributed to this node.
    
+      
    Create a child State attributed to this node.
    
 
 
 
    Parameters:
    
@@ -1401,7 +1416,7 @@ State and produces zero, one, or many new States.
    
           
    
             state
             
-                  State
+                  State
             
             
               
    
@@ -1469,7 +1484,7 @@ State and produces zero, one, or many new States.
    
       
    
           
    
 State            
-                  State
+                  State
             
             
               
    
@@ -1484,7 +1499,9 @@ State and produces zero, one, or many new States.
    
 
    
   Notes
   
    Responsibilities:
    
-
    1
    - Convenience wrapper around State.fork() that automatically records this node's ID in state history.
+
    1
+2
    - Convenience wrapper around `State.fork()` that automatically
+  records this node's ID in state history.
 
    
 
     
    
@@ -1600,7 +1617,7 @@ State and produces zero, one, or many new States.
    
           
    
             state
             
-                  State
+                  State
             
             
               
    
@@ -1626,7 +1643,7 @@ State and produces zero, one, or many new States.
    
       
    
           
    
 State            
-                  Iterable[State]
+                  Iterable[State]
             
             
               
    
@@ -1641,7 +1658,13 @@ State and produces zero, one, or many new States.
    
 
    
   Notes
   
    Responsibilities:
    
-
    
diff --git a/libs/dagpipe/site/objects.inv b/libs/dagpipe/site/objects.inv
index 2b74eb4ca71e12b646233ebe3f23c50a2b2c5a01..32f2ef988c108360c4e696283026ce9d13fad344 100644
GIT binary patch
delta 607
zcmV-l0-*h;1zL|GaA~lA5Ar0UQSM*2U9&)4~OdUmre`yt8IIGU2g`MCVaV8%A3(E
z6}k7bZ9?xXfm)}{6gddN6O2DwF4AugV@Gc3x>~fOM1t1J=zrFfk>0r=lTFtT+8g;-
zY{$W4Bh1l40T}nkVt?j;NS<9>oR6-9spF4s0j>F0#L0KDfKw>pn!$ioy;fkgvT!n@
z@$USG2*taIQG+WB>doYa&jOB5=Qp?v4m5cw%X$ry(tQ&OLe;G)!sdG}!TMml8XTG)#nCCC;YeR%n8UaX}SJ{p^sadf9iT6e8f$We@rr7y?378
zNLYf;_2arT^|=JlfT#OV-@$hsqrZxnYc@+V>QJWn}2$JT&PWMZ+l%YY1!;y59O_x
zC#mZZETTmhSV+4TETVM_7S_fE1#jtsgtd24xj$`U*;C_}vP*r)b_u;^NQ%8jvT1|C
zsJVkzunB}W&;;ZaY%1XlX+Ggxq-t|GKeKQqKE1F;R`3Y=XJu!)S!+@)+F=i2Ba_4u
z}N%1*Zj&dVi&t!EWRr42JLf6p@J|
z`ryIo?r`PA=$LW_yoU~QcK$XUyFzjURu*zEN=cOoFIvxn`7O=PDo3#`rcvzI;MS2m
z%7g;wLWp96BE--iH__-`iXsCh@S~wYYgI(5n<)2+%UuhXr?3Ta(QMbfM!~e3u0wHn
zyj&s`#sm$N5`RWphNqR38b>!>VpM{n6zjt($+)kxT!w-_x?KU3Mr;1$EoT}D0J
z!_KI%+laDq*-srvgKcNYr+n;S><;ts92M*zl01D0&e2ih$c8fzq^AS~B?7JtVdF!p
zPXuPZ8P8f`9V<3U{)HkBi}wMAE1}~`MagRMIuyrUM}IzZfsxR@IjUqyyk%%~dR?$+
zubCnP=nie+liktmZJ;(pC3M)BWh0j_;JxuUop_6Lxo2nQJNpkB#2jw_7UUAC(w3l4
z>Pvz|Wb^_e@_7NxWd&_PK)fsOVWHUFlLz2~VJhrJQ$v++EoxGO*5JHZ^(}=h!@kI#
zwGO+D5xkR$;#M9mBsiG-wXDhs(&P@f^)N$LDdA$D|
G0GStCqZ|(a

diff --git a/libs/dagpipe/site/search/search_index.json b/libs/dagpipe/site/search/search_index.json
index 3c5e828..bcc2668 100644
--- a/libs/dagpipe/site/search/search_index.json
+++ b/libs/dagpipe/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"dagpipe","text":"
       
    • Dagpipe
      •  
    "},{"location":"#dagpipe","title":"dagpipe","text":"
    Directed acyclic graph execution framework for deterministic state propagation.
    "},{"location":"#dagpipe--summary","title":"Summary","text":"
    dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable state and optionally produces derived states for downstream nodes.
    "},{"location":"#dagpipe--installation","title":"Installation","text":"
    Install using pip:
     
    pip install dagpipe\n
    "},{"location":"#dagpipe--quick-start","title":"Quick Start","text":"
    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
    "},{"location":"#dagpipe--public-api","title":"Public API","text":"
    This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.
     
    Execution Core: - Engine - Graph - Node
     
    State & Data: - State / MyState (custom base) - Payload - Schema / SchemaError
     
    Declarative Pipelines: - Pipeline - load_pipeline
    "},{"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":"
    Execution engine responsible for running pipelines and graphs.
    "},{"location":"engine/#dagpipe.engine--summary","title":"Summary","text":"
    The Engine executes Node objects and propagates immutable State instances through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.
     Notes 
    Guarantees:
     
    - Deterministic execution and consistent state lineage.\n- Orchestrates execution without modifying Graph, Node, or State objects.\n
    "},{"location":"engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"engine/#dagpipe.engine.Engine","title":"Engine","text":"
    Engine(nodes_or_graph: Union[Sequence[Node], Graph])\n
     
    Execution engine responsible for running pipeline logic.
     Notes 
    Responsibilities:
     
    - Accepts either a linear sequence of Nodes or a Graph defining execution topology.\n- Propagates immutable State objects through Nodes and collects terminal States.\n
     
    Guarantees:
     
    - Never mutates State, Node, or Graph instances.\n- State objects are never modified in place; each branch produces independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
     
    Initialize the execution engine.
     
    Parameters:
     Name Type Description Default nodes_or_graph Sequence[Node] | Graph 
    Pipeline definition. May be a linear sequence or a DAG.
     required 
    Raises:
     Type Description TypeError 
    If input is not a Sequence[Node] or Graph, or contains invalid node types.
     Notes 
    Responsibilities:
     
    - Detects execution mode (linear or DAG) and validates node types and structure.\n
    "},{"location":"engine/#dagpipe.engine.Engine-attributes","title":"Attributes","text":""},{"location":"engine/#dagpipe.engine.Engine.nodes","title":"nodes  property","text":"
    nodes: tuple[Node, ...]\n
     
    Return nodes managed by this engine.
     
    Returns:
     Type Description tuple[Node, ...] 
    tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.
    "},{"location":"engine/#dagpipe.engine.Engine-functions","title":"Functions","text":""},{"location":"engine/#dagpipe.engine.Engine.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return the canonical string representation of the object.
     
    Returns:
     Name Type Description str str 
    Representation that uniquely identifies the object and its configuration.
    "},{"location":"engine/#dagpipe.engine.Engine.run","title":"run","text":"
    run(root: State) -> List[State]\n
     
    Execute the pipeline starting from a root State.
     
    Parameters:
     Name Type Description Default root State 
    Initial execution state.
     required 
    Returns:
     Type Description List[State] 
    list[State]: Terminal execution states produced by the pipeline.
     
    Raises:
     Type Description TypeError 
    If root is not a State instance.
     RuntimeError 
    If the engine execution mode is invalid.
     Notes 
    Responsibilities:
     
    - Selects execution mode, propagates state through nodes, creates new instances for branches, and collects terminal states.\n
    "},{"location":"graph/","title":"Graph","text":""},{"location":"graph/#dagpipe.graph","title":"dagpipe.graph","text":"
    Defines DAG structure connecting Nodes.
    "},{"location":"graph/#dagpipe.graph--summary","title":"Summary","text":"
    Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by Engine.
     Notes 
    Responsibilities:
     
    - Multiple roots, branching, and merging support.\n- Deterministic traversal based on topology.\n- Graph is mutable during construction but treated as immutable at runtime.\n
    "},{"location":"graph/#dagpipe.graph-classes","title":"Classes","text":""},{"location":"graph/#dagpipe.graph.Graph","title":"Graph","text":"
    Graph()\n
     
    Directed Acyclic Graph defining execution topology of Nodes.
     Notes 
    Responsibilities:
     
    - Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how State flows between nodes during execution.\n
     
    Guarantees:
     
    - Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n
     
    Create an empty Graph.
    "},{"location":"graph/#dagpipe.graph.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return debug representation.
    "},{"location":"graph/#dagpipe.graph.Graph.__repr__--returns","title":"Returns","text":"
    str
    "},{"location":"graph/#dagpipe.graph.Graph.add_edge","title":"add_edge","text":"
    add_edge(src: Node, dst: Node) -> None\n
    "},{"location":"graph/#dagpipe.graph.Graph.add_edge--add-directed-edge-from-src-to-dst","title":"Add directed edge from src to dst.","text":""},{"location":"graph/#dagpipe.graph.Graph.add_edge--parameters","title":"Parameters","text":"
    src : Node     required: True     source node
     Node 
    required: True destination node
    "},{"location":"graph/#dagpipe.graph.Graph.add_edge--raises","title":"Raises","text":"
    TypeError     if src or dst is not a Node
     
    ValueError     if edge would create a cycle
     
    ValueError     if src and dst are the same node
    "},{"location":"graph/#dagpipe.graph.Graph.add_edge--behavior","title":"Behavior","text":"
       
    • validates node types
      •  
    • prevents cycles
      •  
    • registers nodes if not present
      •  
    • updates parent and child mappings
      •  
    "},{"location":"graph/#dagpipe.graph.Graph.add_root","title":"add_root","text":"
    add_root(node: Node) -> None\n
     
    Add a root node with no parents.
     
    Parameters:
     Name Type Description Default node Node 
    Node to add as a root.
     required 
    Raises:
     Type Description TypeError 
    If node is not a Node instance.
    "},{"location":"graph/#dagpipe.graph.Graph.children","title":"children","text":"
    children(node: Node) -> Tuple[Node, ...]\n
     
    Return child nodes of a node.
     
    Parameters:
     Name Type Description Default node Node 
    Node to query.
     required 
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Outgoing neighbors.
    "},{"location":"graph/#dagpipe.graph.Graph.nodes","title":"nodes","text":"
    nodes() -> Tuple[Node, ...]\n
     
    Return all nodes in the graph.
     
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: All registered nodes.
    "},{"location":"graph/#dagpipe.graph.Graph.parents","title":"parents","text":"
    parents(node: Node) -> Tuple[Node, ...]\n
     
    Return parent nodes of a node.
     
    Parameters:
     Name Type Description Default node Node 
    Node to query.
     required 
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Incoming neighbors.
    "},{"location":"graph/#dagpipe.graph.Graph.roots","title":"roots","text":"
    roots() -> Tuple[Node, ...]\n
     
    Return root nodes (nodes with no incoming edges).
     
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Entry point nodes.
    "},{"location":"node/","title":"Node","text":""},{"location":"node/#dagpipe.node","title":"dagpipe.node","text":"
    Defines the Node abstraction used by dagpipe.
    "},{"location":"node/#dagpipe.node--summary","title":"Summary","text":"
    A Node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new States.
     
    Nodes are connected using Graph and executed by Engine.
     Notes 
    Design Principles:
     
    - **Pure:** Must not mutate input state.\n- **Deterministic:** Same input produces same output.\n- **Stateless:** Recommended to be stateless for reuse.\n- **Composable:** Nodes enable branching execution graphs.\n
    "},{"location":"node/#dagpipe.node-classes","title":"Classes","text":""},{"location":"node/#dagpipe.node.Node","title":"Node","text":"
                   Bases: ABC
     
    Base class for all dagpipe execution nodes.
     
    Attributes:
     Name Type Description id str 
    Unique identifier of the node (snake_case dotted format).
     name str 
    Human-readable display name.
     Notes 
    Responsibilities:
     
    - Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one State and produces zero, one, or many derived States.\n- Defines execution logic and enables branching, filtering, and transformation.\n
     
    Guarantees:
     
    - Nodes must never mutate the input State. Instances are singletons per subclass and reused across executions.\n
    "},{"location":"node/#dagpipe.node.Node-functions","title":"Functions","text":""},{"location":"node/#dagpipe.node.Node.__hash__","title":"__hash__","text":"
    __hash__() -> int\n
     
    Return stable hash based on node ID.
    "},{"location":"node/#dagpipe.node.Node.__hash__--returns","title":"Returns","text":"
    int
    "},{"location":"node/#dagpipe.node.Node.__new__","title":"__new__","text":"
    __new__()\n
     
    Create or reuse singleton instance of the Node subclass.
     
    Returns:
     Name Type Description Node 
    Singleton instance of the subclass.
    "},{"location":"node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return debug representation.
    "},{"location":"node/#dagpipe.node.Node.__repr__--returns","title":"Returns","text":"
    str
    "},{"location":"node/#dagpipe.node.Node.__str__","title":"__str__","text":"
    __str__() -> str\n
     
    Return display representation.
    "},{"location":"node/#dagpipe.node.Node.__str__--returns","title":"Returns","text":"
    str
    "},{"location":"node/#dagpipe.node.Node.clean_id_and_name","title":"clean_id_and_name  classmethod","text":"
    clean_id_and_name() -> None\n
     
    Normalize and validate node ID and display name.
     
    Raises:
     Type Description TypeError 
    If ID is not a string.
     ValueError 
    If ID format is invalid.
     Notes 
    Guarantees:
     
    - Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
    "},{"location":"node/#dagpipe.node.Node.fork","title":"fork","text":"
    fork(state: State, *, payload_update=None, confidence_delta=0.0, metadata_update=None) -> State\n
     
    Create a child State attributed to this node.
     
    Parameters:
     Name Type Description Default state State 
    Parent execution state.
     required payload_update Mapping[str, Any] 
    Dot-path payload updates.
     None confidence_delta float 
    Confidence adjustment.
     0.0 metadata_update Mapping[str, Any] 
    Metadata updates.
     None 
    Returns:
     Name Type Description State State 
    New child execution state.
     Notes 
    Responsibilities:
     
    - Convenience wrapper around State.fork() that automatically records this node's ID in state history.\n
    "},{"location":"node/#dagpipe.node.Node.node_id_to_name","title":"node_id_to_name  staticmethod","text":"
    node_id_to_name(node_id: str) -> str\n
     
    Convert a dotted snake_case node ID into a human-readable name.
     
    Parameters:
     Name Type Description Default node_id str 
    Unique node identifier (e.g., 'entity.resolve.numeric_merchant').
     required 
    Returns:
     Name Type Description str str 
    Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').
    "},{"location":"node/#dagpipe.node.Node.resolve","title":"resolve  abstractmethod","text":"
    resolve(state: State) -> Iterable[State]\n
     
    Execute node logic.
     
    Parameters:
     Name Type Description Default state State 
    Input execution state.
     required 
    Yields:
     Name Type Description State Iterable[State] 
    Derived execution state(s).
     Notes 
    Responsibilities:
     
    - 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
    "},{"location":"node/#dagpipe.node.Node.run","title":"run","text":"
    run(state: State) -> tuple[State, ...]\n
     
    Execute this node on a State.
     
    Parameters:
     Name Type Description Default state State 
    Input execution state.
     required 
    Returns:
     Type Description tuple[State, ...] 
    tuple[State, ...]: Derived execution states.
     
    Raises:
     Type Description TypeError 
    If resolve() yields a non-State object.
    "},{"location":"state/","title":"State","text":""},{"location":"state/#dagpipe.state","title":"dagpipe.state","text":"
    Defines the core State object used by dagpipe.
    "},{"location":"state/#dagpipe.state--summary","title":"Summary","text":"
    The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().
     Notes 
    Key design principles:
     
    - **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().\n- **Cheap cloning:** Forking must be efficient since branching may create many states.\n- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.\n- **Domain agnostic:** State contains generic key\u2011value data and does not assume any schema.\n- **Engine\u2011friendly:** State contains execution metadata such as depth and history.\n
    "},{"location":"state/#dagpipe.state-classes","title":"Classes","text":""},{"location":"state/#dagpipe.state.Payload","title":"Payload  dataclass","text":"
    Payload(_data: Mapping[str, Any])\n
     
    Immutable hierarchical container with dot-path access.
     
    Attributes:
     Name Type Description _data Mapping[str, Any] 
    Immutable hierarchical data structure.
     Notes 
    Responsibilities:
     
    - Stores execution data used by State. Supports efficient atomic updates without modifying existing instances.\n- Payload instances are fully thread-safe due to immutability.\n
    "},{"location":"state/#dagpipe.state.Payload-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Payload.as_dict","title":"as_dict","text":"
    as_dict() -> Mapping[str, Any]\n
     
    Return underlying mapping.
     
    Returns:
     Type Description Mapping[str, Any] 
    Mapping[str, Any]: Read-only view of the underlying data.
    "},{"location":"state/#dagpipe.state.Payload.get","title":"get","text":"
    get(path: str, default: Any = None) -> Any\n
     
    Retrieve value using dot-path.
     
    Parameters:
     Name Type Description Default path str 
    Dot-separated path to the value.
     required default Any 
    Default value if path doesn't exist.
     None 
    Returns:
     Name Type Description Any Any 
    The retrieved value or default.
    "},{"location":"state/#dagpipe.state.Payload.has","title":"has","text":"
    has(path: str) -> bool\n
     
    Return True if path exists.
     
    Parameters:
     Name Type Description Default path str 
    Dot-separated path to check.
     required 
    Returns:
     Name Type Description bool bool 
    Existence of the path.
    "},{"location":"state/#dagpipe.state.Payload.iter_paths","title":"iter_paths  classmethod","text":"
    iter_paths(data: Mapping[str, Any], prefix: str = '') -> Iterable[str]\n
     
    Recursively yield dot-paths for all leaf nodes.
     
    Parameters:
     Name Type Description Default data Mapping[str, Any] 
    The mapping to iterate over.
     required prefix str 
    Current path prefix.
     '' 
    Returns:
     Type Description Iterable[str] 
    Iterable[str]: Generator yielding dot-paths.
    "},{"location":"state/#dagpipe.state.Payload.keys","title":"keys","text":"
    keys() -> Iterable[str]\n
     
    Return top-level keys.
     
    Returns:
     Type Description Iterable[str] 
    Iterable[str]: Iterator over top-level keys.
    "},{"location":"state/#dagpipe.state.Payload.update","title":"update","text":"
    update(updates: Mapping[str, Any]) -> Payload\n
     
    Create a new Payload with dot-path updates applied.
     
    Parameters:
     Name Type Description Default updates Mapping[str, Any] 
    Dot-path to value mapping.
     required 
    Returns:
     Name Type Description Payload Payload 
    New immutable payload instance with updates.
     Notes 
    Guarantees:
     
    - Preserves existing data by copying only modified branches. Returns a new immutable payload.\n
    "},{"location":"state/#dagpipe.state.Schema","title":"Schema  dataclass","text":"
    Schema(tree: Mapping[str, SchemaNode])\n
     
    Immutable hierarchical schema defining allowed payload structure.
     
    Attributes:
     Name Type Description tree Mapping[str, SchemaNode] 
    Hierarchical schema definition.
     Notes 
    Responsibilities:
     
    - Validates State payloads and updates. Reuseable across all State instances.\n- Fully thread-safe due to immutability.\n
    "},{"location":"state/#dagpipe.state.Schema-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Schema.validate_payload","title":"validate_payload","text":"
    validate_payload(payload: Payload) -> None\n
     
    Validate complete payload structure.
     
    Parameters:
     Name Type Description Default payload Payload 
    Payload to validate.
     required 
    Raises:
     Type Description SchemaError 
    If payload violates schema.
    "},{"location":"state/#dagpipe.state.Schema.validate_update","title":"validate_update","text":"
    validate_update(updates: Mapping[str, Any]) -> None\n
     
    Validate payload update paths.
     
    Parameters:
     Name Type Description Default updates Mapping[str, Any] 
    Dot-path updates to validate.
     required 
    Raises:
     Type Description SchemaError 
    If any path is invalid according to the schema.
    "},{"location":"state/#dagpipe.state.SchemaError","title":"SchemaError","text":"
                   Bases: Exception
     
    Raised when payload data violates the declared schema.
    "},{"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  dataclass","text":"
    State(payload: Payload, confidence: float = 1.0, parent: Optional[State] = None, depth: int = 0, history: Tuple[str, ...] = tuple(), metadata: Dict[str, Any] = dict())\n
     
    Immutable execution state propagated through dagpipe pipeline.
     
    Attributes:
     Name Type Description payload Payload 
    Execution data container.
     schema ClassVar[Schema] 
    Payload validation schema.
     confidence float 
    Execution confidence score.
     parent Optional[State] 
    Parent state reference.
     depth int 
    Execution depth.
     history Tuple[str, ...] 
    Ordered node execution lineage.
     metadata Dict[str, Any] 
    Execution metadata.
     Notes 
    Responsibilities:
     
    - Represents a complete execution snapshot at a specific point in pipeline traversal. Fundamental unit of execution in dagpipe.\n- Fully thread-safe due to immutability.\n
    "},{"location":"state/#dagpipe.state.State-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.State.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Concise debug representation.
     
    Avoids printing full data for large states.
    "},{"location":"state/#dagpipe.state.State.fork","title":"fork","text":"
    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
     
    Create a new child State derived from this State.
     
    Parameters:
     Name Type Description Default payload_update Mapping[str, Any] 
    Dot-path updates applied to the payload.
     None confidence_delta float 
    Adjustment applied to current confidence.
     0.0 node_id str 
    Identifier of the node creating this state.
     None metadata_update Mapping[str, Any] 
    Updates merged into state metadata.
     None 
    Returns:
     Name Type Description State State 
    A new immutable State instance.
     Notes 
    Guarantees:
     
    - This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth, and appends to history.\n
    "},{"location":"state/#dagpipe.state.State.get","title":"get","text":"
    get(key: str, default: Any = None) -> Any\n
     
    Retrieve payload value.
     
    Parameters:
     Name Type Description Default key str 
    Dot-path key.
     required default Any 
    Fallback value.
     None 
    Returns:
     Name Type Description Any Any 
    Stored value or default.
    "},{"location":"state/#dagpipe.state.State.has","title":"has","text":"
    has(key: str) -> bool\n
     
    Check whether payload contains key.
     
    Parameters:
     Name Type Description Default key str 
    Dot-path key.
     required 
    Returns:
     Name Type Description bool bool 
    Existence of the key.
    "},{"location":"state/#dagpipe.state.State.lineage","title":"lineage","text":"
    lineage() -> Tuple[State, ...]\n
     
    Return lineage from root to this State.
     
    Returns:
     Type Description Tuple[State, ...] 
    Tuple[State, ...]: Ordered execution lineage (root first).
    "},{"location":"yaml_loader/","title":"Yaml Loader","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader","title":"dagpipe.yaml_loader","text":"
    Loads dagpipe pipelines from YAML configuration.
    "},{"location":"yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"
    Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial Payloads.
    "},{"location":"yaml_loader/#dagpipe.yaml_loader-classes","title":"Classes","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline","title":"Pipeline  dataclass","text":"
    Pipeline(engine: Engine, state_cls: Type[State], initial_payload: Payload)\n
     
    Executable pipeline created from YAML configuration.
     
    Attributes:
     Name Type Description engine Engine 
    Execution engine responsible for running the pipeline.
     state_cls Type[State] 
    Dynamically created State subclass with configured schema.
     initial_payload Payload 
    Default payload used when execution begins.
     Notes 
    Responsibilities:
     
    - Encapsulates engine, state type, and initial payload. Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying Nodes are thread-safe.\n
    "},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline.run","title":"run","text":"
    run(payload_override: Optional[Mapping[str, Any]] = None)\n
     
    Execute pipeline.
     
    Parameters:
     Name Type Description Default payload_override Mapping[str, Any] 
    Payload values overriding initial payload.
     None 
    Returns:
     Type Description 
    list[State]: Terminal execution states.
     Notes 
    Responsibilities:
     
    - Merges override payload with initial payload, creates root State, and executes engine.\n
    "},{"location":"yaml_loader/#dagpipe.yaml_loader-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.load_pipeline","title":"load_pipeline","text":"
    load_pipeline(path: str) -> Pipeline\n
     
    Load pipeline from YAML file.
     
    Parameters:
     Name Type Description Default path str 
    Path to YAML configuration file.
     required 
    Returns:
     Name Type Description Pipeline Pipeline 
    Executable pipeline instance.
     Notes 
    Responsibilities:
     
    - Loads YAML configuration, builds schema, creates State subclass, loads Node instances, builds Graph topology, and initializes Engine.\n
    "},{"location":"dagpipe/","title":"Dagpipe","text":"
       
    • Engine
      •  
    • Graph
      •  
    • Node
      •  
    • State
      •  
    • Yaml Loader
      •  
    "},{"location":"dagpipe/#dagpipe","title":"dagpipe","text":"
    Directed acyclic graph execution framework for deterministic state propagation.
    "},{"location":"dagpipe/#dagpipe--summary","title":"Summary","text":"
    dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable state and optionally produces derived states for downstream nodes.
    "},{"location":"dagpipe/#dagpipe--installation","title":"Installation","text":"
    Install using pip:
     
    pip install dagpipe\n
    "},{"location":"dagpipe/#dagpipe--quick-start","title":"Quick Start","text":"
    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
    "},{"location":"dagpipe/#dagpipe--public-api","title":"Public API","text":"
    This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.
     
    Execution Core: - Engine - Graph - Node
     
    State & Data: - State / MyState (custom base) - Payload - Schema / SchemaError
     
    Declarative Pipelines: - Pipeline - load_pipeline
    "},{"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":"
    Execution engine responsible for running pipelines and graphs.
    "},{"location":"dagpipe/engine/#dagpipe.engine--summary","title":"Summary","text":"
    The Engine executes Node objects and propagates immutable State instances through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.
     Notes 
    Guarantees:
     
    - Deterministic execution and consistent state lineage.\n- Orchestrates execution without modifying Graph, Node, or State objects.\n
    "},{"location":"dagpipe/engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine","title":"Engine","text":"
    Engine(nodes_or_graph: Union[Sequence[Node], Graph])\n
     
    Execution engine responsible for running pipeline logic.
     Notes 
    Responsibilities:
     
    - Accepts either a linear sequence of Nodes or a Graph defining execution topology.\n- Propagates immutable State objects through Nodes and collects terminal States.\n
     
    Guarantees:
     
    - Never mutates State, Node, or Graph instances.\n- State objects are never modified in place; each branch produces independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
     
    Initialize the execution engine.
     
    Parameters:
     Name Type Description Default nodes_or_graph Sequence[Node] | Graph 
    Pipeline definition. May be a linear sequence or a DAG.
     required 
    Raises:
     Type Description TypeError 
    If input is not a Sequence[Node] or Graph, or contains invalid node types.
     Notes 
    Responsibilities:
     
    - Detects execution mode (linear or DAG) and validates node types and structure.\n
    "},{"location":"dagpipe/engine/#dagpipe.engine.Engine-attributes","title":"Attributes","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine.nodes","title":"nodes  property","text":"
    nodes: tuple[Node, ...]\n
     
    Return nodes managed by this engine.
     
    Returns:
     Type Description tuple[Node, ...] 
    tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.
    "},{"location":"dagpipe/engine/#dagpipe.engine.Engine-functions","title":"Functions","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return the canonical string representation of the object.
     
    Returns:
     Name Type Description str str 
    Representation that uniquely identifies the object and its configuration.
    "},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run","title":"run","text":"
    run(root: State) -> List[State]\n
     
    Execute the pipeline starting from a root State.
     
    Parameters:
     Name Type Description Default root State 
    Initial execution state.
     required 
    Returns:
     Type Description List[State] 
    list[State]: Terminal execution states produced by the pipeline.
     
    Raises:
     Type Description TypeError 
    If root is not a State instance.
     RuntimeError 
    If the engine execution mode is invalid.
     Notes 
    Responsibilities:
     
    - Selects execution mode, propagates state through nodes, creates new instances for branches, and collects terminal states.\n
    "},{"location":"dagpipe/graph/","title":"Graph","text":""},{"location":"dagpipe/graph/#dagpipe.graph","title":"dagpipe.graph","text":"
    Defines DAG structure connecting Nodes.
    "},{"location":"dagpipe/graph/#dagpipe.graph--summary","title":"Summary","text":"
    Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by Engine.
     Notes 
    Responsibilities:
     
    - Multiple roots, branching, and merging support.\n- Deterministic traversal based on topology.\n- Graph is mutable during construction but treated as immutable at runtime.\n
    "},{"location":"dagpipe/graph/#dagpipe.graph-classes","title":"Classes","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph","title":"Graph","text":"
    Graph()\n
     
    Directed Acyclic Graph defining execution topology of Nodes.
     Notes 
    Responsibilities:
     
    - Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how State flows between nodes during execution.\n
     
    Guarantees:
     
    - Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n
     
    Create an empty Graph.
    "},{"location":"dagpipe/graph/#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":"
    __repr__() -> str\n
     
    Return debug representation.
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.__repr__--returns","title":"Returns","text":"
    str
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge","title":"add_edge","text":"
    add_edge(src: Node, dst: Node) -> None\n
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--add-directed-edge-from-src-to-dst","title":"Add directed edge from src to dst.","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--parameters","title":"Parameters","text":"
    src : Node     required: True     source node
     Node 
    required: True destination node
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--raises","title":"Raises","text":"
    TypeError     if src or dst is not a Node
     
    ValueError     if edge would create a cycle
     
    ValueError     if src and dst are the same node
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge--behavior","title":"Behavior","text":"
       
    • validates node types
      •  
    • prevents cycles
      •  
    • registers nodes if not present
      •  
    • updates parent and child mappings
      •  
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_root","title":"add_root","text":"
    add_root(node: Node) -> None\n
     
    Add a root node with no parents.
     
    Parameters:
     Name Type Description Default node Node 
    Node to add as a root.
     required 
    Raises:
     Type Description TypeError 
    If node is not a Node instance.
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.children","title":"children","text":"
    children(node: Node) -> Tuple[Node, ...]\n
     
    Return child nodes of a node.
     
    Parameters:
     Name Type Description Default node Node 
    Node to query.
     required 
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Outgoing neighbors.
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.nodes","title":"nodes","text":"
    nodes() -> Tuple[Node, ...]\n
     
    Return all nodes in the graph.
     
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: All registered nodes.
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.parents","title":"parents","text":"
    parents(node: Node) -> Tuple[Node, ...]\n
     
    Return parent nodes of a node.
     
    Parameters:
     Name Type Description Default node Node 
    Node to query.
     required 
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Incoming neighbors.
    "},{"location":"dagpipe/graph/#dagpipe.graph.Graph.roots","title":"roots","text":"
    roots() -> Tuple[Node, ...]\n
     
    Return root nodes (nodes with no incoming edges).
     
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Entry point nodes.
    "},{"location":"dagpipe/node/","title":"Node","text":""},{"location":"dagpipe/node/#dagpipe.node","title":"dagpipe.node","text":"
    Defines the Node abstraction used by dagpipe.
    "},{"location":"dagpipe/node/#dagpipe.node--summary","title":"Summary","text":"
    A Node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new States.
     
    Nodes are connected using Graph and executed by Engine.
     Notes 
    Design Principles:
     
    - **Pure:** Must not mutate input state.\n- **Deterministic:** Same input produces same output.\n- **Stateless:** Recommended to be stateless for reuse.\n- **Composable:** Nodes enable branching execution graphs.\n
    "},{"location":"dagpipe/node/#dagpipe.node-classes","title":"Classes","text":""},{"location":"dagpipe/node/#dagpipe.node.Node","title":"Node","text":"
                   Bases: ABC
     
    Base class for all dagpipe execution nodes.
     
    Attributes:
     Name Type Description id str 
    Unique identifier of the node (snake_case dotted format).
     name str 
    Human-readable display name.
     Notes 
    Responsibilities:
     
    - Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one State and produces zero, one, or many derived States.\n- Defines execution logic and enables branching, filtering, and transformation.\n
     
    Guarantees:
     
    - Nodes must never mutate the input State. Instances are singletons per subclass and reused across executions.\n
    "},{"location":"dagpipe/node/#dagpipe.node.Node-functions","title":"Functions","text":""},{"location":"dagpipe/node/#dagpipe.node.Node.__hash__","title":"__hash__","text":"
    __hash__() -> int\n
     
    Return stable hash based on node ID.
    "},{"location":"dagpipe/node/#dagpipe.node.Node.__hash__--returns","title":"Returns","text":"
    int
    "},{"location":"dagpipe/node/#dagpipe.node.Node.__new__","title":"__new__","text":"
    __new__()\n
     
    Create or reuse singleton instance of the Node subclass.
     
    Returns:
     Name Type Description Node 
    Singleton instance of the subclass.
    "},{"location":"dagpipe/node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return debug representation.
    "},{"location":"dagpipe/node/#dagpipe.node.Node.__repr__--returns","title":"Returns","text":"
    str
    "},{"location":"dagpipe/node/#dagpipe.node.Node.__str__","title":"__str__","text":"
    __str__() -> str\n
     
    Return display representation.
    "},{"location":"dagpipe/node/#dagpipe.node.Node.__str__--returns","title":"Returns","text":"
    str
    "},{"location":"dagpipe/node/#dagpipe.node.Node.clean_id_and_name","title":"clean_id_and_name  classmethod","text":"
    clean_id_and_name() -> None\n
     
    Normalize and validate node ID and display name.
     
    Raises:
     Type Description TypeError 
    If ID is not a string.
     ValueError 
    If ID format is invalid.
     Notes 
    Guarantees:
     
    - Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
    "},{"location":"dagpipe/node/#dagpipe.node.Node.fork","title":"fork","text":"
    fork(state: State, *, payload_update=None, confidence_delta=0.0, metadata_update=None) -> State\n
     
    Create a child State attributed to this node.
     
    Parameters:
     Name Type Description Default state State 
    Parent execution state.
     required payload_update Mapping[str, Any] 
    Dot-path payload updates.
     None confidence_delta float 
    Confidence adjustment.
     0.0 metadata_update Mapping[str, Any] 
    Metadata updates.
     None 
    Returns:
     Name Type Description State State 
    New child execution state.
     Notes 
    Responsibilities:
     
    - Convenience wrapper around State.fork() that automatically records this node's ID in state history.\n
    "},{"location":"dagpipe/node/#dagpipe.node.Node.node_id_to_name","title":"node_id_to_name  staticmethod","text":"
    node_id_to_name(node_id: str) -> str\n
     
    Convert a dotted snake_case node ID into a human-readable name.
     
    Parameters:
     Name Type Description Default node_id str 
    Unique node identifier (e.g., 'entity.resolve.numeric_merchant').
     required 
    Returns:
     Name Type Description str str 
    Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').
    "},{"location":"dagpipe/node/#dagpipe.node.Node.resolve","title":"resolve  abstractmethod","text":"
    resolve(state: State) -> Iterable[State]\n
     
    Execute node logic.
     
    Parameters:
     Name Type Description Default state State 
    Input execution state.
     required 
    Yields:
     Name Type Description State Iterable[State] 
    Derived execution state(s).
     Notes 
    Responsibilities:
     
    - 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
    "},{"location":"dagpipe/node/#dagpipe.node.Node.run","title":"run","text":"
    run(state: State) -> tuple[State, ...]\n
     
    Execute this node on a State.
     
    Parameters:
     Name Type Description Default state State 
    Input execution state.
     required 
    Returns:
     Type Description tuple[State, ...] 
    tuple[State, ...]: Derived execution states.
     
    Raises:
     Type Description TypeError 
    If resolve() yields a non-State object.
    "},{"location":"dagpipe/state/","title":"State","text":""},{"location":"dagpipe/state/#dagpipe.state","title":"dagpipe.state","text":"
    Defines the core State object used by dagpipe.
    "},{"location":"dagpipe/state/#dagpipe.state--summary","title":"Summary","text":"
    The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().
     Notes 
    Key design principles:
     
    - **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().\n- **Cheap cloning:** Forking must be efficient since branching may create many states.\n- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.\n- **Domain agnostic:** State contains generic key\u2011value data and does not assume any schema.\n- **Engine\u2011friendly:** State contains execution metadata such as depth and history.\n
    "},{"location":"dagpipe/state/#dagpipe.state-classes","title":"Classes","text":""},{"location":"dagpipe/state/#dagpipe.state.Payload","title":"Payload  dataclass","text":"
    Payload(_data: Mapping[str, Any])\n
     
    Immutable hierarchical container with dot-path access.
     
    Attributes:
     Name Type Description _data Mapping[str, Any] 
    Immutable hierarchical data structure.
     Notes 
    Responsibilities:
     
    - Stores execution data used by State. Supports efficient atomic updates without modifying existing instances.\n- Payload instances are fully thread-safe due to immutability.\n
    "},{"location":"dagpipe/state/#dagpipe.state.Payload-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.Payload.as_dict","title":"as_dict","text":"
    as_dict() -> Mapping[str, Any]\n
     
    Return underlying mapping.
     
    Returns:
     Type Description Mapping[str, Any] 
    Mapping[str, Any]: Read-only view of the underlying data.
    "},{"location":"dagpipe/state/#dagpipe.state.Payload.get","title":"get","text":"
    get(path: str, default: Any = None) -> Any\n
     
    Retrieve value using dot-path.
     
    Parameters:
     Name Type Description Default path str 
    Dot-separated path to the value.
     required default Any 
    Default value if path doesn't exist.
     None 
    Returns:
     Name Type Description Any Any 
    The retrieved value or default.
    "},{"location":"dagpipe/state/#dagpipe.state.Payload.has","title":"has","text":"
    has(path: str) -> bool\n
     
    Return True if path exists.
     
    Parameters:
     Name Type Description Default path str 
    Dot-separated path to check.
     required 
    Returns:
     Name Type Description bool bool 
    Existence of the path.
    "},{"location":"dagpipe/state/#dagpipe.state.Payload.iter_paths","title":"iter_paths  classmethod","text":"
    iter_paths(data: Mapping[str, Any], prefix: str = '') -> Iterable[str]\n
     
    Recursively yield dot-paths for all leaf nodes.
     
    Parameters:
     Name Type Description Default data Mapping[str, Any] 
    The mapping to iterate over.
     required prefix str 
    Current path prefix.
     '' 
    Returns:
     Type Description Iterable[str] 
    Iterable[str]: Generator yielding dot-paths.
    "},{"location":"dagpipe/state/#dagpipe.state.Payload.keys","title":"keys","text":"
    keys() -> Iterable[str]\n
     
    Return top-level keys.
     
    Returns:
     Type Description Iterable[str] 
    Iterable[str]: Iterator over top-level keys.
    "},{"location":"dagpipe/state/#dagpipe.state.Payload.update","title":"update","text":"
    update(updates: Mapping[str, Any]) -> Payload\n
     
    Create a new Payload with dot-path updates applied.
     
    Parameters:
     Name Type Description Default updates Mapping[str, Any] 
    Dot-path to value mapping.
     required 
    Returns:
     Name Type Description Payload Payload 
    New immutable payload instance with updates.
     Notes 
    Guarantees:
     
    - Preserves existing data by copying only modified branches. Returns a new immutable payload.\n
    "},{"location":"dagpipe/state/#dagpipe.state.Schema","title":"Schema  dataclass","text":"
    Schema(tree: Mapping[str, SchemaNode])\n
     
    Immutable hierarchical schema defining allowed payload structure.
     
    Attributes:
     Name Type Description tree Mapping[str, SchemaNode] 
    Hierarchical schema definition.
     Notes 
    Responsibilities:
     
    - Validates State payloads and updates. Reuseable across all State instances.\n- Fully thread-safe due to immutability.\n
    "},{"location":"dagpipe/state/#dagpipe.state.Schema-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.Schema.validate_payload","title":"validate_payload","text":"
    validate_payload(payload: Payload) -> None\n
     
    Validate complete payload structure.
     
    Parameters:
     Name Type Description Default payload Payload 
    Payload to validate.
     required 
    Raises:
     Type Description SchemaError 
    If payload violates schema.
    "},{"location":"dagpipe/state/#dagpipe.state.Schema.validate_update","title":"validate_update","text":"
    validate_update(updates: Mapping[str, Any]) -> None\n
     
    Validate payload update paths.
     
    Parameters:
     Name Type Description Default updates Mapping[str, Any] 
    Dot-path updates to validate.
     required 
    Raises:
     Type Description SchemaError 
    If any path is invalid according to the schema.
    "},{"location":"dagpipe/state/#dagpipe.state.SchemaError","title":"SchemaError","text":"
                   Bases: Exception
     
    Raised when payload data violates the declared schema.
    "},{"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  dataclass","text":"
    State(payload: Payload, confidence: float = 1.0, parent: Optional[State] = None, depth: int = 0, history: Tuple[str, ...] = tuple(), metadata: Dict[str, Any] = dict())\n
     
    Immutable execution state propagated through dagpipe pipeline.
     
    Attributes:
     Name Type Description payload Payload 
    Execution data container.
     schema ClassVar[Schema] 
    Payload validation schema.
     confidence float 
    Execution confidence score.
     parent Optional[State] 
    Parent state reference.
     depth int 
    Execution depth.
     history Tuple[str, ...] 
    Ordered node execution lineage.
     metadata Dict[str, Any] 
    Execution metadata.
     Notes 
    Responsibilities:
     
    - Represents a complete execution snapshot at a specific point in pipeline traversal. Fundamental unit of execution in dagpipe.\n- Fully thread-safe due to immutability.\n
    "},{"location":"dagpipe/state/#dagpipe.state.State-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.State.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Concise debug representation.
     
    Avoids printing full data for large states.
    "},{"location":"dagpipe/state/#dagpipe.state.State.fork","title":"fork","text":"
    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
     
    Create a new child State derived from this State.
     
    Parameters:
     Name Type Description Default payload_update Mapping[str, Any] 
    Dot-path updates applied to the payload.
     None confidence_delta float 
    Adjustment applied to current confidence.
     0.0 node_id str 
    Identifier of the node creating this state.
     None metadata_update Mapping[str, Any] 
    Updates merged into state metadata.
     None 
    Returns:
     Name Type Description State State 
    A new immutable State instance.
     Notes 
    Guarantees:
     
    - This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth, and appends to history.\n
    "},{"location":"dagpipe/state/#dagpipe.state.State.get","title":"get","text":"
    get(key: str, default: Any = None) -> Any\n
     
    Retrieve payload value.
     
    Parameters:
     Name Type Description Default key str 
    Dot-path key.
     required default Any 
    Fallback value.
     None 
    Returns:
     Name Type Description Any Any 
    Stored value or default.
    "},{"location":"dagpipe/state/#dagpipe.state.State.has","title":"has","text":"
    has(key: str) -> bool\n
     
    Check whether payload contains key.
     
    Parameters:
     Name Type Description Default key str 
    Dot-path key.
     required 
    Returns:
     Name Type Description bool bool 
    Existence of the key.
    "},{"location":"dagpipe/state/#dagpipe.state.State.lineage","title":"lineage","text":"
    lineage() -> Tuple[State, ...]\n
     
    Return lineage from root to this State.
     
    Returns:
     Type Description Tuple[State, ...] 
    Tuple[State, ...]: Ordered execution lineage (root first).
    "},{"location":"dagpipe/yaml_loader/","title":"Yaml Loader","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader","title":"dagpipe.yaml_loader","text":"
    Loads dagpipe pipelines from YAML configuration.
    "},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"
    Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial Payloads.
    "},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader-classes","title":"Classes","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline","title":"Pipeline  dataclass","text":"
    Pipeline(engine: Engine, state_cls: Type[State], initial_payload: Payload)\n
     
    Executable pipeline created from YAML configuration.
     
    Attributes:
     Name Type Description engine Engine 
    Execution engine responsible for running the pipeline.
     state_cls Type[State] 
    Dynamically created State subclass with configured schema.
     initial_payload Payload 
    Default payload used when execution begins.
     Notes 
    Responsibilities:
     
    - Encapsulates engine, state type, and initial payload. Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying Nodes are thread-safe.\n
    "},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline-functions","title":"Functions","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline.run","title":"run","text":"
    run(payload_override: Optional[Mapping[str, Any]] = None)\n
     
    Execute pipeline.
     
    Parameters:
     Name Type Description Default payload_override Mapping[str, Any] 
    Payload values overriding initial payload.
     None 
    Returns:
     Type Description 
    list[State]: Terminal execution states.
     Notes 
    Responsibilities:
     
    - Merges override payload with initial payload, creates root State, and executes engine.\n
    "},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader-functions","title":"Functions","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.load_pipeline","title":"load_pipeline","text":"
    load_pipeline(path: str) -> Pipeline\n
     
    Load pipeline from YAML file.
     
    Parameters:
     Name Type Description Default path str 
    Path to YAML configuration file.
     required 
    Returns:
     Name Type Description Pipeline Pipeline 
    Executable pipeline instance.
     Notes 
    Responsibilities:
     
    - Loads YAML configuration, builds schema, creates State subclass, loads Node instances, builds Graph topology, and initializes Engine.\n
    "}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"dagpipe","text":""},{"location":"#dagpipe","title":"dagpipe","text":""},{"location":"#dagpipe--summary","title":"Summary","text":"
    Directed acyclic graph execution framework for deterministic state propagation.
     
    dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable State and optionally produces derived states for downstream nodes.
    "},{"location":"#dagpipe--installation","title":"Installation","text":"
    Install using pip:
     
    pip install dagpipe\n
    "},{"location":"#dagpipe--quick-start","title":"Quick Start","text":"
    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
    "},{"location":"#dagpipe--public-api","title":"Public API","text":"
    This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.
    "},{"location":"#dagpipe--execution-core","title":"Execution Core","text":"
       
    • Engine: Responsible for orchestrating node execution and state propagation.
      •  
    • Graph: Defines the execution topology and node relationships.
      •  
    • Node: Base class for defining execution logic and transformations.
      •  
    "},{"location":"#dagpipe--state-data","title":"State & Data","text":"
       
    • State: Represents an immutable execution snapshot at a point in time.
      •  
    • Payload: Immutable hierarchical container for execution data.
      •  
    • Schema: Defines and validates the allowed structure of payloads.
      •  
    • SchemaError: Raised when data violates the declared schema.
      •  
    "},{"location":"#dagpipe--declarative-pipelines","title":"Declarative Pipelines","text":"
       
    • Pipeline: High-level wrapper for an engine, state type, and initial payload.
      •  
    • load_pipeline: Factory function to create a pipeline from YAML.
      •  
    "},{"location":"#dagpipe-classes","title":"Classes","text":""},{"location":"#dagpipe.Engine","title":"Engine","text":"
    Engine(nodes_or_graph: Union[Sequence[Node], Graph])\n
     
    Execution engine responsible for running pipeline logic.
     Notes 
    Responsibilities:
     
    - Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n
     
    Guarantees:
     
    - Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
     
    Initialize the execution engine.
     
    Parameters:
     Name Type Description Default nodes_or_graph Sequence[Node] | Graph 
    Pipeline definition. May be a linear sequence or a DAG.
     required 
    Raises:
     Type Description TypeError 
    If input is not a Sequence[Node] or Graph, or contains invalid node types.
     Notes 
    Responsibilities:
     
    - Detects execution mode (linear or DAG) and validates node\n  types and structure.\n
    "},{"location":"#dagpipe.Engine-attributes","title":"Attributes","text":""},{"location":"#dagpipe.Engine.nodes","title":"nodes  property","text":"
    nodes: tuple[Node, ...]\n
     
    Return nodes managed by this engine.
     
    Returns:
     Type Description tuple[Node, ...] 
    tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.
    "},{"location":"#dagpipe.Engine-functions","title":"Functions","text":""},{"location":"#dagpipe.Engine.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return the canonical string representation of the object.
     
    Returns:
     Name Type Description str str 
    Representation that uniquely identifies the object and its configuration.
    "},{"location":"#dagpipe.Engine.run","title":"run","text":"
    run(root: State) -> List[State]\n
     
    Execute the pipeline starting from a root State.
     
    Parameters:
     Name Type Description Default root State 
    Initial execution state.
     required 
    Returns:
     Type Description List[State] 
    list[State]: Terminal execution states produced by the pipeline.
     
    Raises:
     Type Description TypeError 
    If root is not a State instance.
     RuntimeError 
    If the engine execution mode is invalid.
     Notes 
    Responsibilities:
     
    - Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
    "},{"location":"#dagpipe.Graph","title":"Graph","text":"
    Graph()\n
     
    Directed Acyclic Graph defining execution topology of Node objects.
     Notes 
    Responsibilities:
     
    - Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n
     
    Guarantees:
     
    - Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n
     
    Create an empty Graph.
    "},{"location":"#dagpipe.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"#dagpipe.Graph-functions","title":"Functions","text":""},{"location":"#dagpipe.Graph.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return debug representation.
    "},{"location":"#dagpipe.Graph.__repr__--returns","title":"Returns","text":"
    str
    "},{"location":"#dagpipe.Graph.add_edge","title":"add_edge","text":"
    add_edge(src: Node, dst: Node) -> None\n
     
    Add a directed edge from src to dst.
     
    Parameters:
     Name Type Description Default src Node 
    Source node.
     required dst Node 
    Destination node.
     required 
    Raises:
     Type Description TypeError 
    If src or dst is not a Node.
     ValueError 
    If the edge would create a cycle or if src and dst are common.
     Notes 
       
    • Validates node types.
      •  
    • Prevents cycles.
      •  
    • Registers nodes if not present.
      •  
    • Updates parent and child mappings.
      •  
    "},{"location":"#dagpipe.Graph.add_root","title":"add_root","text":"
    add_root(node: Node) -> None\n
     
    Add a root node with no parents.
     
    Parameters:
     Name Type Description Default node Node 
    Node to add as a root.
     required 
    Raises:
     Type Description TypeError 
    If node is not a Node instance.
    "},{"location":"#dagpipe.Graph.children","title":"children","text":"
    children(node: Node) -> Tuple[Node, ...]\n
     
    Return child nodes of a node.
     
    Parameters:
     Name Type Description Default node Node 
    Node to query.
     required 
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Outgoing neighbors.
    "},{"location":"#dagpipe.Graph.nodes","title":"nodes","text":"
    nodes() -> Tuple[Node, ...]\n
     
    Return all nodes in the graph.
     
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: All registered nodes.
    "},{"location":"#dagpipe.Graph.parents","title":"parents","text":"
    parents(node: Node) -> Tuple[Node, ...]\n
     
    Return parent nodes of a node.
     
    Parameters:
     Name Type Description Default node Node 
    Node to query.
     required 
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Incoming neighbors.
    "},{"location":"#dagpipe.Graph.roots","title":"roots","text":"
    roots() -> Tuple[Node, ...]\n
     
    Return root nodes (nodes with no incoming edges).
     
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Entry point nodes.
    "},{"location":"#dagpipe.Node","title":"Node","text":"
                   Bases: ABC
     
    Base class for all dagpipe execution nodes.
     
    Attributes:
     Name Type Description id str 
    Unique identifier of the node (snake_case dotted format).
     name str 
    Human-readable display name.
     Notes 
    Responsibilities:
     
    - Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n
     
    Guarantees:
     
    - Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
    "},{"location":"#dagpipe.Node-functions","title":"Functions","text":""},{"location":"#dagpipe.Node.__hash__","title":"__hash__","text":"
    __hash__() -> int\n
     
    Return stable hash based on node ID.
    "},{"location":"#dagpipe.Node.__hash__--returns","title":"Returns","text":"
    int
    "},{"location":"#dagpipe.Node.__new__","title":"__new__","text":"
    __new__() -> Node\n
     
    Create or reuse singleton instance of the Node subclass.
     
    Returns:
     Name Type Description Node Node 
    Singleton instance of the subclass.
    "},{"location":"#dagpipe.Node.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return debug representation.
    "},{"location":"#dagpipe.Node.__repr__--returns","title":"Returns","text":"
    str
    "},{"location":"#dagpipe.Node.__str__","title":"__str__","text":"
    __str__() -> str\n
     
    Return display representation.
    "},{"location":"#dagpipe.Node.__str__--returns","title":"Returns","text":"
    str
    "},{"location":"#dagpipe.Node.clean_id_and_name","title":"clean_id_and_name  classmethod","text":"
    clean_id_and_name() -> None\n
     
    Normalize and validate node ID and display name.
     
    Raises:
     Type Description TypeError 
    If ID is not a string.
     ValueError 
    If ID format is invalid.
     Notes 
    Guarantees:
     
    - Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
    "},{"location":"#dagpipe.Node.fork","title":"fork","text":"
    fork(state: State, *, payload_update=None, confidence_delta=0.0, metadata_update=None) -> State\n
     
    Create a child State attributed to this node.
     
    Parameters:
     Name Type Description Default state State 
    Parent execution state.
     required payload_update Mapping[str, Any] 
    Dot-path payload updates.
     None confidence_delta float 
    Confidence adjustment.
     0.0 metadata_update Mapping[str, Any] 
    Metadata updates.
     None 
    Returns:
     Name Type Description State State 
    New child execution state.
     Notes 
    Responsibilities:
     
    - Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
    "},{"location":"#dagpipe.Node.node_id_to_name","title":"node_id_to_name  staticmethod","text":"
    node_id_to_name(node_id: str) -> str\n
     
    Convert a dotted snake_case node ID into a human-readable name.
     
    Parameters:
     Name Type Description Default node_id str 
    Unique node identifier (e.g., 'entity.resolve.numeric_merchant').
     required 
    Returns:
     Name Type Description str str 
    Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').
    "},{"location":"#dagpipe.Node.resolve","title":"resolve  abstractmethod","text":"
    resolve(state: State) -> Iterable[State]\n
     
    Execute node logic.
     
    Parameters:
     Name Type Description Default state State 
    Input execution state.
     required 
    Yields:
     Name Type Description State Iterable[State] 
    Derived execution state(s).
     Notes 
    Responsibilities:
     
    - 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
    "},{"location":"#dagpipe.Node.run","title":"run","text":"
    run(state: State) -> tuple[State, ...]\n
     
    Execute this node on a State.
     
    Parameters:
     Name Type Description Default state State 
    Input execution state.
     required 
    Returns:
     Type Description tuple[State, ...] 
    tuple[State, ...]: Derived execution states.
     
    Raises:
     Type Description TypeError 
    If resolve() yields a non-State object.
    "},{"location":"#dagpipe.Payload","title":"Payload  dataclass","text":"
    Payload(_data: Mapping[str, Any])\n
     
    Immutable hierarchical container with dot-path access.
     
    Attributes:
     Name Type Description _data Mapping[str, Any] 
    Immutable hierarchical data structure.
     Notes 
    Responsibilities:
     
    - Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
    "},{"location":"#dagpipe.Payload-functions","title":"Functions","text":""},{"location":"#dagpipe.Payload.as_dict","title":"as_dict","text":"
    as_dict() -> Mapping[str, Any]\n
     
    Return underlying mapping.
     
    Returns:
     Type Description Mapping[str, Any] 
    Mapping[str, Any]: Read-only view of the underlying data.
    "},{"location":"#dagpipe.Payload.get","title":"get","text":"
    get(path: str, default: Any = None) -> Any\n
     
    Retrieve value using dot-path.
     
    Parameters:
     Name Type Description Default path str 
    Dot-separated path to the value.
     required default Any 
    Default value if path doesn't exist.
     None 
    Returns:
     Name Type Description Any Any 
    The retrieved value or default.
    "},{"location":"#dagpipe.Payload.has","title":"has","text":"
    has(path: str) -> bool\n
     
    Return True if path exists.
     
    Parameters:
     Name Type Description Default path str 
    Dot-separated path to check.
     required 
    Returns:
     Name Type Description bool bool 
    Existence of the path.
    "},{"location":"#dagpipe.Payload.iter_paths","title":"iter_paths  classmethod","text":"
    iter_paths(data: Mapping[str, Any], prefix: str = '') -> Iterable[str]\n
     
    Recursively yield dot-paths for all leaf nodes.
     
    Parameters:
     Name Type Description Default data Mapping[str, Any] 
    The mapping to iterate over.
     required prefix str 
    Current path prefix.
     '' 
    Returns:
     Type Description Iterable[str] 
    Iterable[str]: Generator yielding dot-paths.
    "},{"location":"#dagpipe.Payload.keys","title":"keys","text":"
    keys() -> Iterable[str]\n
     
    Return top-level keys.
     
    Returns:
     Type Description Iterable[str] 
    Iterable[str]: Iterator over top-level keys.
    "},{"location":"#dagpipe.Payload.update","title":"update","text":"
    update(updates: Mapping[str, Any]) -> Payload\n
     
    Create a new Payload with dot-path updates applied.
     
    Parameters:
     Name Type Description Default updates Mapping[str, Any] 
    Dot-path to value mapping.
     required 
    Returns:
     Name Type Description Payload Payload 
    New immutable payload instance with updates.
     Notes 
    Guarantees:
     
    - Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
    "},{"location":"#dagpipe.Pipeline","title":"Pipeline  dataclass","text":"
    Pipeline(engine: Engine, state_cls: Type[State], initial_payload: Payload)\n
     
    Executable pipeline created from YAML configuration.
     
    Attributes:
     Name Type Description engine Engine 
    Execution engine responsible for running the pipeline.
     state_cls Type[State] 
    Dynamically created State subclass with configured schema.
     initial_payload Payload 
    Default payload used when execution begins.
     Notes 
    Responsibilities:
     
    - Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
    "},{"location":"#dagpipe.Pipeline-functions","title":"Functions","text":""},{"location":"#dagpipe.Pipeline.run","title":"run","text":"
    run(payload_override: Optional[Mapping[str, Any]] = None) -> list[State]\n
     
    Execute the pipeline.
     
    Parameters:
     Name Type Description Default payload_override Mapping[str, Any] 
    Payload values overriding initial payload.
     None 
    Returns:
     Type Description list[State] 
    list[State]: Terminal execution states.
     Notes 
    Responsibilities:
     
    - Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
    "},{"location":"#dagpipe.Schema","title":"Schema  dataclass","text":"
    Schema(tree: Mapping[str, SchemaNode])\n
     
    Immutable hierarchical schema defining allowed payload structure.
     
    Attributes:
     Name Type Description tree Mapping[str, SchemaNode] 
    Hierarchical schema definition.
     Notes 
    Responsibilities:
     
    - Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
    "},{"location":"#dagpipe.Schema-functions","title":"Functions","text":""},{"location":"#dagpipe.Schema.validate_payload","title":"validate_payload","text":"
    validate_payload(payload: Payload) -> None\n
     
    Validate complete payload structure.
     
    Parameters:
     Name Type Description Default payload Payload 
    Payload to validate.
     required 
    Raises:
     Type Description SchemaError 
    If payload violates schema.
    "},{"location":"#dagpipe.Schema.validate_update","title":"validate_update","text":"
    validate_update(updates: Mapping[str, Any]) -> None\n
     
    Validate payload update paths.
     
    Parameters:
     Name Type Description Default updates Mapping[str, Any] 
    Dot-path updates to validate.
     required 
    Raises:
     Type Description SchemaError 
    If any path is invalid according to the schema.
    "},{"location":"#dagpipe.SchemaError","title":"SchemaError","text":"
                   Bases: Exception
     
    Raised when payload data violates the declared schema.
    "},{"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  dataclass","text":"
    State(payload: Payload, confidence: float = 1.0, parent: Optional[State] = None, depth: int = 0, history: Tuple[str, ...] = tuple(), metadata: Dict[str, Any] = dict())\n
     
    Immutable execution state propagated through dagpipe pipeline.
     
    Attributes:
     Name Type Description payload Payload 
    Execution data container.
     schema ClassVar[Schema] 
    Payload validation schema.
     confidence float 
    Execution confidence score.
     parent Optional[State] 
    Parent state reference.
     depth int 
    Execution depth.
     history Tuple[str, ...] 
    Ordered node execution lineage.
     metadata Dict[str, Any] 
    Execution metadata.
     Notes 
    Responsibilities:
     
    - Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
    "},{"location":"#dagpipe.State-functions","title":"Functions","text":""},{"location":"#dagpipe.State.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Concise debug representation.
     
    Avoids printing full data for large states.
    "},{"location":"#dagpipe.State.fork","title":"fork","text":"
    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
     
    Create a new child State derived from this state.
     
    Parameters:
     Name Type Description Default payload_update Mapping[str, Any] 
    Dot-path updates applied to the payload.
     None confidence_delta float 
    Adjustment applied to current confidence.
     0.0 node_id str 
    Identifier of the node creating this state.
     None metadata_update Mapping[str, Any] 
    Updates merged into state metadata.
     None 
    Returns:
     Name Type Description State State 
    A new immutable State instance.
     Notes 
    Guarantees:
     
    - This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
    "},{"location":"#dagpipe.State.get","title":"get","text":"
    get(key: str, default: Any = None) -> Any\n
     
    Retrieve payload value.
     
    Parameters:
     Name Type Description Default key str 
    Dot-path key.
     required default Any 
    Fallback value.
     None 
    Returns:
     Name Type Description Any Any 
    Stored value or default.
    "},{"location":"#dagpipe.State.has","title":"has","text":"
    has(key: str) -> bool\n
     
    Check whether payload contains key.
     
    Parameters:
     Name Type Description Default key str 
    Dot-path key.
     required 
    Returns:
     Name Type Description bool bool 
    Existence of the key.
    "},{"location":"#dagpipe.State.lineage","title":"lineage","text":"
    lineage() -> Tuple[State, ...]\n
     
    Return lineage from root to this State.
     
    Returns:
     Type Description Tuple[State, ...] 
    Tuple[State, ...]: Ordered execution lineage (root first).
    "},{"location":"#dagpipe-functions","title":"Functions","text":""},{"location":"#dagpipe.load_pipeline","title":"load_pipeline","text":"
    load_pipeline(path: str) -> Pipeline\n
     
    Load pipeline from YAML file.
     
    Parameters:
     Name Type Description Default path str 
    Path to YAML configuration file.
     required 
    Returns:
     Name Type Description Pipeline Pipeline 
    Executable pipeline instance.
     Notes 
    Responsibilities:
     
    - Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
    "},{"location":"engine/","title":"Engine","text":""},{"location":"engine/#dagpipe.engine","title":"dagpipe.engine","text":""},{"location":"engine/#dagpipe.engine--summary","title":"Summary","text":"
    Execution engine responsible for running pipelines and graphs.
     
    The Engine executes Node objects and propagates immutable State instances through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.
    "},{"location":"engine/#dagpipe.engine--guarantees","title":"Guarantees","text":"
       
    • Deterministic execution and consistent state lineage.
      •  
    • Orchestrates execution without modifying Graph, Node, or State objects.
      •  
    "},{"location":"engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"engine/#dagpipe.engine.Engine","title":"Engine","text":"
    Engine(nodes_or_graph: Union[Sequence[Node], Graph])\n
     
    Execution engine responsible for running pipeline logic.
     Notes 
    Responsibilities:
     
    - Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n
     
    Guarantees:
     
    - Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
     
    Initialize the execution engine.
     
    Parameters:
     Name Type Description Default nodes_or_graph Sequence[Node] | Graph 
    Pipeline definition. May be a linear sequence or a DAG.
     required 
    Raises:
     Type Description TypeError 
    If input is not a Sequence[Node] or Graph, or contains invalid node types.
     Notes 
    Responsibilities:
     
    - Detects execution mode (linear or DAG) and validates node\n  types and structure.\n
    "},{"location":"engine/#dagpipe.engine.Engine-attributes","title":"Attributes","text":""},{"location":"engine/#dagpipe.engine.Engine.nodes","title":"nodes  property","text":"
    nodes: tuple[Node, ...]\n
     
    Return nodes managed by this engine.
     
    Returns:
     Type Description tuple[Node, ...] 
    tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.
    "},{"location":"engine/#dagpipe.engine.Engine-functions","title":"Functions","text":""},{"location":"engine/#dagpipe.engine.Engine.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return the canonical string representation of the object.
     
    Returns:
     Name Type Description str str 
    Representation that uniquely identifies the object and its configuration.
    "},{"location":"engine/#dagpipe.engine.Engine.run","title":"run","text":"
    run(root: State) -> List[State]\n
     
    Execute the pipeline starting from a root State.
     
    Parameters:
     Name Type Description Default root State 
    Initial execution state.
     required 
    Returns:
     Type Description List[State] 
    list[State]: Terminal execution states produced by the pipeline.
     
    Raises:
     Type Description TypeError 
    If root is not a State instance.
     RuntimeError 
    If the engine execution mode is invalid.
     Notes 
    Responsibilities:
     
    - Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
    "},{"location":"graph/","title":"Graph","text":""},{"location":"graph/#dagpipe.graph","title":"dagpipe.graph","text":""},{"location":"graph/#dagpipe.graph--summary","title":"Summary","text":"
    Defines DAG structure connecting nodes.
     
    A Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by an Engine.
    "},{"location":"graph/#dagpipe.graph--responsibilities","title":"Responsibilities","text":"
       
    • Multiple roots, branching, and merging support.
      •  
    • Deterministic traversal based on topology.
      •  
    • Graph is mutable during construction but treated as immutable at runtime.
      •  
    "},{"location":"graph/#dagpipe.graph-classes","title":"Classes","text":""},{"location":"graph/#dagpipe.graph.Graph","title":"Graph","text":"
    Graph()\n
     
    Directed Acyclic Graph defining execution topology of Node objects.
     Notes 
    Responsibilities:
     
    - Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n
     
    Guarantees:
     
    - Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n
     
    Create an empty Graph.
    "},{"location":"graph/#dagpipe.graph.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return debug representation.
    "},{"location":"graph/#dagpipe.graph.Graph.__repr__--returns","title":"Returns","text":"
    str
    "},{"location":"graph/#dagpipe.graph.Graph.add_edge","title":"add_edge","text":"
    add_edge(src: Node, dst: Node) -> None\n
     
    Add a directed edge from src to dst.
     
    Parameters:
     Name Type Description Default src Node 
    Source node.
     required dst Node 
    Destination node.
     required 
    Raises:
     Type Description TypeError 
    If src or dst is not a Node.
     ValueError 
    If the edge would create a cycle or if src and dst are common.
     Notes 
       
    • Validates node types.
      •  
    • Prevents cycles.
      •  
    • Registers nodes if not present.
      •  
    • Updates parent and child mappings.
      •  
    "},{"location":"graph/#dagpipe.graph.Graph.add_root","title":"add_root","text":"
    add_root(node: Node) -> None\n
     
    Add a root node with no parents.
     
    Parameters:
     Name Type Description Default node Node 
    Node to add as a root.
     required 
    Raises:
     Type Description TypeError 
    If node is not a Node instance.
    "},{"location":"graph/#dagpipe.graph.Graph.children","title":"children","text":"
    children(node: Node) -> Tuple[Node, ...]\n
     
    Return child nodes of a node.
     
    Parameters:
     Name Type Description Default node Node 
    Node to query.
     required 
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Outgoing neighbors.
    "},{"location":"graph/#dagpipe.graph.Graph.nodes","title":"nodes","text":"
    nodes() -> Tuple[Node, ...]\n
     
    Return all nodes in the graph.
     
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: All registered nodes.
    "},{"location":"graph/#dagpipe.graph.Graph.parents","title":"parents","text":"
    parents(node: Node) -> Tuple[Node, ...]\n
     
    Return parent nodes of a node.
     
    Parameters:
     Name Type Description Default node Node 
    Node to query.
     required 
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Incoming neighbors.
    "},{"location":"graph/#dagpipe.graph.Graph.roots","title":"roots","text":"
    roots() -> Tuple[Node, ...]\n
     
    Return root nodes (nodes with no incoming edges).
     
    Returns:
     Type Description Tuple[Node, ...] 
    Tuple[Node, ...]: Entry point nodes.
    "},{"location":"node/","title":"Node","text":""},{"location":"node/#dagpipe.node","title":"dagpipe.node","text":""},{"location":"node/#dagpipe.node--summary","title":"Summary","text":"
    Defines the Node abstraction used by dagpipe.
     
    A node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new State objects.
     
    Nodes are connected using a Graph and executed by an Engine.
    "},{"location":"node/#dagpipe.node--design-principles","title":"Design principles","text":"
       
    • Pure: Must not mutate input state.
      •  
    • Deterministic: Same input produces same output.
      •  
    • Stateless: Recommended to be stateless for reuse.
      •  
    • Composable: Nodes enable branching execution graphs.
      •  
    "},{"location":"node/#dagpipe.node-classes","title":"Classes","text":""},{"location":"node/#dagpipe.node.Node","title":"Node","text":"
                   Bases: ABC
     
    Base class for all dagpipe execution nodes.
     
    Attributes:
     Name Type Description id str 
    Unique identifier of the node (snake_case dotted format).
     name str 
    Human-readable display name.
     Notes 
    Responsibilities:
     
    - Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n
     
    Guarantees:
     
    - Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
    "},{"location":"node/#dagpipe.node.Node-functions","title":"Functions","text":""},{"location":"node/#dagpipe.node.Node.__hash__","title":"__hash__","text":"
    __hash__() -> int\n
     
    Return stable hash based on node ID.
    "},{"location":"node/#dagpipe.node.Node.__hash__--returns","title":"Returns","text":"
    int
    "},{"location":"node/#dagpipe.node.Node.__new__","title":"__new__","text":"
    __new__() -> Node\n
     
    Create or reuse singleton instance of the Node subclass.
     
    Returns:
     Name Type Description Node Node 
    Singleton instance of the subclass.
    "},{"location":"node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Return debug representation.
    "},{"location":"node/#dagpipe.node.Node.__repr__--returns","title":"Returns","text":"
    str
    "},{"location":"node/#dagpipe.node.Node.__str__","title":"__str__","text":"
    __str__() -> str\n
     
    Return display representation.
    "},{"location":"node/#dagpipe.node.Node.__str__--returns","title":"Returns","text":"
    str
    "},{"location":"node/#dagpipe.node.Node.clean_id_and_name","title":"clean_id_and_name  classmethod","text":"
    clean_id_and_name() -> None\n
     
    Normalize and validate node ID and display name.
     
    Raises:
     Type Description TypeError 
    If ID is not a string.
     ValueError 
    If ID format is invalid.
     Notes 
    Guarantees:
     
    - Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
    "},{"location":"node/#dagpipe.node.Node.fork","title":"fork","text":"
    fork(state: State, *, payload_update=None, confidence_delta=0.0, metadata_update=None) -> State\n
     
    Create a child State attributed to this node.
     
    Parameters:
     Name Type Description Default state State 
    Parent execution state.
     required payload_update Mapping[str, Any] 
    Dot-path payload updates.
     None confidence_delta float 
    Confidence adjustment.
     0.0 metadata_update Mapping[str, Any] 
    Metadata updates.
     None 
    Returns:
     Name Type Description State State 
    New child execution state.
     Notes 
    Responsibilities:
     
    - Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
    "},{"location":"node/#dagpipe.node.Node.node_id_to_name","title":"node_id_to_name  staticmethod","text":"
    node_id_to_name(node_id: str) -> str\n
     
    Convert a dotted snake_case node ID into a human-readable name.
     
    Parameters:
     Name Type Description Default node_id str 
    Unique node identifier (e.g., 'entity.resolve.numeric_merchant').
     required 
    Returns:
     Name Type Description str str 
    Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').
    "},{"location":"node/#dagpipe.node.Node.resolve","title":"resolve  abstractmethod","text":"
    resolve(state: State) -> Iterable[State]\n
     
    Execute node logic.
     
    Parameters:
     Name Type Description Default state State 
    Input execution state.
     required 
    Yields:
     Name Type Description State Iterable[State] 
    Derived execution state(s).
     Notes 
    Responsibilities:
     
    - 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
    "},{"location":"node/#dagpipe.node.Node.run","title":"run","text":"
    run(state: State) -> tuple[State, ...]\n
     
    Execute this node on a State.
     
    Parameters:
     Name Type Description Default state State 
    Input execution state.
     required 
    Returns:
     Type Description tuple[State, ...] 
    tuple[State, ...]: Derived execution states.
     
    Raises:
     Type Description TypeError 
    If resolve() yields a non-State object.
    "},{"location":"state/","title":"State","text":""},{"location":"state/#dagpipe.state","title":"dagpipe.state","text":""},{"location":"state/#dagpipe.state--summary","title":"Summary","text":"
    Defines the core State object used by dagpipe.
     
    The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().
    "},{"location":"state/#dagpipe.state--design-principles","title":"Design principles","text":"
       
    • Immutability: States must never be modified after creation.   All transformations must create a new state via fork().
      •  
    • Cheap cloning: Forking must be efficient since branching may create many states.
      •  
    • Lineage tracking: Each state maintains a reference to its parent and   execution metadata for debugging and observability.
      •  
    • Domain agnostic: State contains generic key-value data and does not   assume any schema.
      •  
    • Engine-friendly: State contains execution metadata such as depth and history.
      •  
    "},{"location":"state/#dagpipe.state-classes","title":"Classes","text":""},{"location":"state/#dagpipe.state.Payload","title":"Payload  dataclass","text":"
    Payload(_data: Mapping[str, Any])\n
     
    Immutable hierarchical container with dot-path access.
     
    Attributes:
     Name Type Description _data Mapping[str, Any] 
    Immutable hierarchical data structure.
     Notes 
    Responsibilities:
     
    - Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
    "},{"location":"state/#dagpipe.state.Payload-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Payload.as_dict","title":"as_dict","text":"
    as_dict() -> Mapping[str, Any]\n
     
    Return underlying mapping.
     
    Returns:
     Type Description Mapping[str, Any] 
    Mapping[str, Any]: Read-only view of the underlying data.
    "},{"location":"state/#dagpipe.state.Payload.get","title":"get","text":"
    get(path: str, default: Any = None) -> Any\n
     
    Retrieve value using dot-path.
     
    Parameters:
     Name Type Description Default path str 
    Dot-separated path to the value.
     required default Any 
    Default value if path doesn't exist.
     None 
    Returns:
     Name Type Description Any Any 
    The retrieved value or default.
    "},{"location":"state/#dagpipe.state.Payload.has","title":"has","text":"
    has(path: str) -> bool\n
     
    Return True if path exists.
     
    Parameters:
     Name Type Description Default path str 
    Dot-separated path to check.
     required 
    Returns:
     Name Type Description bool bool 
    Existence of the path.
    "},{"location":"state/#dagpipe.state.Payload.iter_paths","title":"iter_paths  classmethod","text":"
    iter_paths(data: Mapping[str, Any], prefix: str = '') -> Iterable[str]\n
     
    Recursively yield dot-paths for all leaf nodes.
     
    Parameters:
     Name Type Description Default data Mapping[str, Any] 
    The mapping to iterate over.
     required prefix str 
    Current path prefix.
     '' 
    Returns:
     Type Description Iterable[str] 
    Iterable[str]: Generator yielding dot-paths.
    "},{"location":"state/#dagpipe.state.Payload.keys","title":"keys","text":"
    keys() -> Iterable[str]\n
     
    Return top-level keys.
     
    Returns:
     Type Description Iterable[str] 
    Iterable[str]: Iterator over top-level keys.
    "},{"location":"state/#dagpipe.state.Payload.update","title":"update","text":"
    update(updates: Mapping[str, Any]) -> Payload\n
     
    Create a new Payload with dot-path updates applied.
     
    Parameters:
     Name Type Description Default updates Mapping[str, Any] 
    Dot-path to value mapping.
     required 
    Returns:
     Name Type Description Payload Payload 
    New immutable payload instance with updates.
     Notes 
    Guarantees:
     
    - Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
    "},{"location":"state/#dagpipe.state.Schema","title":"Schema  dataclass","text":"
    Schema(tree: Mapping[str, SchemaNode])\n
     
    Immutable hierarchical schema defining allowed payload structure.
     
    Attributes:
     Name Type Description tree Mapping[str, SchemaNode] 
    Hierarchical schema definition.
     Notes 
    Responsibilities:
     
    - Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
    "},{"location":"state/#dagpipe.state.Schema-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Schema.validate_payload","title":"validate_payload","text":"
    validate_payload(payload: Payload) -> None\n
     
    Validate complete payload structure.
     
    Parameters:
     Name Type Description Default payload Payload 
    Payload to validate.
     required 
    Raises:
     Type Description SchemaError 
    If payload violates schema.
    "},{"location":"state/#dagpipe.state.Schema.validate_update","title":"validate_update","text":"
    validate_update(updates: Mapping[str, Any]) -> None\n
     
    Validate payload update paths.
     
    Parameters:
     Name Type Description Default updates Mapping[str, Any] 
    Dot-path updates to validate.
     required 
    Raises:
     Type Description SchemaError 
    If any path is invalid according to the schema.
    "},{"location":"state/#dagpipe.state.SchemaError","title":"SchemaError","text":"
                   Bases: Exception
     
    Raised when payload data violates the declared schema.
    "},{"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  dataclass","text":"
    State(payload: Payload, confidence: float = 1.0, parent: Optional[State] = None, depth: int = 0, history: Tuple[str, ...] = tuple(), metadata: Dict[str, Any] = dict())\n
     
    Immutable execution state propagated through dagpipe pipeline.
     
    Attributes:
     Name Type Description payload Payload 
    Execution data container.
     schema ClassVar[Schema] 
    Payload validation schema.
     confidence float 
    Execution confidence score.
     parent Optional[State] 
    Parent state reference.
     depth int 
    Execution depth.
     history Tuple[str, ...] 
    Ordered node execution lineage.
     metadata Dict[str, Any] 
    Execution metadata.
     Notes 
    Responsibilities:
     
    - Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
    "},{"location":"state/#dagpipe.state.State-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.State.__repr__","title":"__repr__","text":"
    __repr__() -> str\n
     
    Concise debug representation.
     
    Avoids printing full data for large states.
    "},{"location":"state/#dagpipe.state.State.fork","title":"fork","text":"
    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
     
    Create a new child State derived from this state.
     
    Parameters:
     Name Type Description Default payload_update Mapping[str, Any] 
    Dot-path updates applied to the payload.
     None confidence_delta float 
    Adjustment applied to current confidence.
     0.0 node_id str 
    Identifier of the node creating this state.
     None metadata_update Mapping[str, Any] 
    Updates merged into state metadata.
     None 
    Returns:
     Name Type Description State State 
    A new immutable State instance.
     Notes 
    Guarantees:
     
    - This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
    "},{"location":"state/#dagpipe.state.State.get","title":"get","text":"
    get(key: str, default: Any = None) -> Any\n
     
    Retrieve payload value.
     
    Parameters:
     Name Type Description Default key str 
    Dot-path key.
     required default Any 
    Fallback value.
     None 
    Returns:
     Name Type Description Any Any 
    Stored value or default.
    "},{"location":"state/#dagpipe.state.State.has","title":"has","text":"
    has(key: str) -> bool\n
     
    Check whether payload contains key.
     
    Parameters:
     Name Type Description Default key str 
    Dot-path key.
     required 
    Returns:
     Name Type Description bool bool 
    Existence of the key.
    "},{"location":"state/#dagpipe.state.State.lineage","title":"lineage","text":"
    lineage() -> Tuple[State, ...]\n
     
    Return lineage from root to this State.
     
    Returns:
     Type Description Tuple[State, ...] 
    Tuple[State, ...]: Ordered execution lineage (root first).
    "},{"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":"
    Loads dagpipe pipelines from YAML configuration.
     
    Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial payloads.
    "},{"location":"yaml_loader/#dagpipe.yaml_loader-classes","title":"Classes","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline","title":"Pipeline  dataclass","text":"
    Pipeline(engine: Engine, state_cls: Type[State], initial_payload: Payload)\n
     
    Executable pipeline created from YAML configuration.
     
    Attributes:
     Name Type Description engine Engine 
    Execution engine responsible for running the pipeline.
     state_cls Type[State] 
    Dynamically created State subclass with configured schema.
     initial_payload Payload 
    Default payload used when execution begins.
     Notes 
    Responsibilities:
     
    - Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
    "},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline.run","title":"run","text":"
    run(payload_override: Optional[Mapping[str, Any]] = None) -> list[State]\n
     
    Execute the pipeline.
     
    Parameters:
     Name Type Description Default payload_override Mapping[str, Any] 
    Payload values overriding initial payload.
     None 
    Returns:
     Type Description list[State] 
    list[State]: Terminal execution states.
     Notes 
    Responsibilities:
     
    - Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
    "},{"location":"yaml_loader/#dagpipe.yaml_loader-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.load_pipeline","title":"load_pipeline","text":"
    load_pipeline(path: str) -> Pipeline\n
     
    Load pipeline from YAML file.
     
    Parameters:
     Name Type Description Default path str 
    Path to YAML configuration file.
     required 
    Returns:
     Name Type Description Pipeline Pipeline 
    Executable pipeline instance.
     Notes 
    Responsibilities:
     
    - Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
    "}]}
\ No newline at end of file
diff --git a/libs/dagpipe/site/sitemap.xml.gz b/libs/dagpipe/site/sitemap.xml.gz
index ef3423ec38ece858df4782cc558257c24ab3803a..d87e54deefb0f522db1ce1f7b6d2799df55bf9f4 100644
GIT binary patch
delta 13
Ucmb=gXP58h;9%IZW+Hn902}87H~;_u

delta 13
Ucmb=gXP58h;AqHNJ(0Zv03AsLWdHyG

diff --git a/libs/dagpipe/site/state/index.html b/libs/dagpipe/site/state/index.html
index 14fe1b9..f094c13 100644
--- a/libs/dagpipe/site/state/index.html
+++ b/libs/dagpipe/site/state/index.html
@@ -362,6 +362,15 @@
     
   
   
+
+        
+          
  • 
+  
+    
+      Design principles
+    
+  
+  
 
    • 
         
           
  • 
@@ -990,6 +999,15 @@
     
   
   
+
    • 
+        
+          
  • 
+  
+    
+      Design principles
+    
+  
+  
 
    • 
         
           
  • 
@@ -1274,29 +1292,25 @@
 
     
    
 
-      
    Defines the core State object used by dagpipe.
    
-
    
-
    Summary
    
-
    The State represents a single point in pipeline execution. It contains
+      
    Summary
    
+
    Defines the core State object used by dagpipe.
    
+
    The State represents a single point in pipeline execution. It contains
 arbitrary data and metadata and is designed to be immutable. Instead of
-modifying an existing state, nodes create new child states via fork().
    
+modifying an existing state, nodes create new child states via fork().
    
+
    
+
    Design principles
    
+
      
+
    • Immutability: States must never be modified after creation.
+  All transformations must create a new state via fork().
      • 
+
    • Cheap cloning: Forking must be efficient since branching may create many states.
      • 
+
    • Lineage tracking: Each state maintains a reference to its parent and
+  execution metadata for debugging and observability.
      • 
+
    • Domain agnostic: State contains generic key-value data and does not
+  assume any schema.
      • 
+
    • Engine-friendly: State contains execution metadata such as depth and history.
      • 
+
    
 
 
-
    
-  Notes
-  
    Key design principles:
    
-
    • 1
    - Subclasses implement specific resolution behavior. Must not mutate input state. Should use fork() to create child states. May yield zero states to terminate a branch.
+
    1
+2
+3
+4
    - Subclasses implement specific resolution behavior.
+- Must not mutate input state.
+- Should use `fork()` to create child states.
+- May yield zero states to terminate a branch.
 
    
 
     
    
@@ -1661,7 +1684,7 @@ State and produces zero, one, or many new States.
    
 
     
    
 
-      
    Execute this node on a State.
    
+      
    Execute this node on a State.
    
 
 
 
    Parameters:
    
@@ -1678,7 +1701,7 @@ State and produces zero, one, or many new States.
    
           
    
             state
             
-                  State
+                  State
             
             
               
    
@@ -1704,7 +1727,7 @@ State and produces zero, one, or many new States.
    
       
    
           
    
             
-                  tuple[State, ...]
+                  tuple[State, ...]
             
             
               
    
@@ -1732,7 +1755,7 @@ Derived execution states.
    
             
    		
             
               
    
-                
    If resolve() yields a non-State object.
    
+                
    If resolve() yields a non-State object.
    
               
    
                 		
           
    1
-2
-3
-4
-5
    - **Immutability:** States must never be modified after creation. All transformations must create a new state via fork().
-- **Cheap cloning:** Forking must be efficient since branching may create many states.
-- **Lineage tracking:** Each state maintains a reference to its parent and execution metadata for debugging and observability.
-- **Domain agnostic:** State contains generic key‑value data and does not assume any schema.
-- **Engine‑friendly:** State contains execution metadata such as depth and history.
-
    
-
    
-
 
   
    
 
@@ -1358,8 +1372,10 @@ modifying an existing state, nodes create new child states via fork().
    
   Notes
   
    Responsibilities:
    
 
    1
-2
    - Stores execution data used by State. Supports efficient atomic updates without modifying existing instances.
-- Payload instances are fully thread-safe due to immutability.
+2
+3
    - Stores execution data used by `State`.
+- Supports efficient atomic updates without modifying existing instances.
+- `Payload` instances are fully thread-safe due to immutability.
 
    
 
 
@@ -1720,7 +1736,7 @@ Iterator over top-level keys.
    
 
     
    
 
-      
    Create a new Payload with dot-path updates applied.
    
+      
    Create a new Payload with dot-path updates applied.
    
 
 
 
    Parameters:
    
@@ -1763,7 +1779,7 @@ Iterator over top-level keys.
    
       
    
           
    
 Payload            
-                  Payload
+                  Payload
             
             
               
    
@@ -1778,7 +1794,9 @@ Iterator over top-level keys.
    
 
    
   Notes
   
    Guarantees:
    
-
    
@@ -2303,8 +2327,10 @@ Iterator over top-level keys.
    Notes
    Guarantees:
    1
    - Preserves existing data by copying only modified branches. Returns a new immutable payload.
+
    1
+2
    - Preserves existing data by copying only modified branches.
+- Returns a new immutable `Payload`.
 
    
 
     
    
@@ -1844,7 +1862,9 @@ Iterator over top-level keys.
    
   Notes
   
    Responsibilities:
    
 
    1
-2
    - Validates State payloads and updates. Reuseable across all State instances.
+2
+3
    - Validates `State` payloads and updates.
+- Reusable across all `State` instances.
 - Fully thread-safe due to immutability.
 
    
 
@@ -1891,7 +1911,7 @@ Iterator over top-level keys.
    
           
    
             payload
             
-                  Payload
+                  Payload
             
             
               
    
@@ -1917,7 +1937,7 @@ Iterator over top-level keys.
    
       
    
           
    
             
-                  SchemaError
+                  SchemaError
             
             
               
    
@@ -1988,7 +2008,7 @@ Iterator over top-level keys.
    
       
    
           
    
             
-                  SchemaError
+                  SchemaError
             
             
               
    
@@ -2070,7 +2090,7 @@ Iterator over top-level keys.
    
           
    
             payload
             
-                  Payload
+                  Payload
             
             
               
    
@@ -2081,7 +2101,7 @@ Iterator over top-level keys.
    
           
    
             schema
             
-                  ClassVar[Schema]
+                  ClassVar[Schema]
             
             
               
    
@@ -2103,7 +2123,7 @@ Iterator over top-level keys.
    
           
    
             parent
             
-                  Optional[State]
+                  Optional[State]
             
             
               
    
@@ -2152,7 +2172,11 @@ Iterator over top-level keys.
    
   Notes
   
    Responsibilities:
    
 
    1
-2
    - Represents a complete execution snapshot at a specific point in pipeline traversal. Fundamental unit of execution in dagpipe.
+2
+3
+4
    - Represents a complete execution snapshot at a specific point in
+  pipeline traversal.
+- Fundamental unit of execution in `dagpipe`.
 - Fully thread-safe due to immutability.
 
    
 
@@ -2202,7 +2226,7 @@ Iterator over top-level keys.
    
 
     
    
 
-      
    Create a new child State derived from this State.
    
+      
    Create a new child State derived from this state.
    
 
 
 
    Parameters:
    
@@ -2287,11 +2311,11 @@ Iterator over top-level keys.
    
       
    
           
    
 State            
-                  State
+                  State
             
             
               
    
-                
    A new immutable State instance.
    
+                
    A new immutable State instance.
    
               
    
                 		
           
    
   
   
 
    1
-2
    - This is the only supported mechanism for modifying execution data.
-- Validates payload updates, preserves lineage, increments depth, and appends to history.
+2
+3
    - This is the only supported mechanism for modifying execution data.
+- Validates payload updates, preserves lineage, increments depth,
+  and appends to history.
 
    
 
    
     
    
@@ -2494,7 +2520,7 @@ Iterator over top-level keys.
    
       
    
           
    
             
-                  Tuple[State, ...]
+                  Tuple[State, ...]
             
             
               
    
diff --git a/libs/dagpipe/site/yaml_loader/index.html b/libs/dagpipe/site/yaml_loader/index.html
index 23c7973..4ee4bb4 100644
--- a/libs/dagpipe/site/yaml_loader/index.html
+++ b/libs/dagpipe/site/yaml_loader/index.html
@@ -936,12 +936,11 @@
 
     
    
 
-      
    Loads dagpipe pipelines from YAML configuration.
    
-
    
-
    Summary
    
+      
    Summary
    
+
    Loads dagpipe pipelines from YAML configuration.
    
 
    Creates fully configured pipeline objects from declarative YAML definitions,
-including Schema, State subclasses, Node instances, Graph topology,
-and initial Payloads.
    
+including Schema, State subclasses, Node instances, Graph topology,
+and initial payloads.
    
 
 
 
@@ -989,7 +988,7 @@ and initial Payloads.
    
           
    
             engine
             
-                  Engine
+                  Engine
             
             
               
    
@@ -1000,18 +999,18 @@ and initial Payloads.
    
           
    
             state_cls
             
-                  Type[State]
+                  Type[State]
             
             
               
    
-                
    Dynamically created State subclass with configured schema.
    
+                
    Dynamically created State subclass with configured schema.
    
               
    
                 		
           
    
           
    
             initial_payload
             
-                  Payload
+                  Payload
             
             
               
    
@@ -1027,8 +1026,10 @@ and initial Payloads.
    
   Notes
   
    Responsibilities:
    
 
    1
-2
    - Encapsulates engine, state type, and initial payload. Provides a simplified interface for executing configured pipelines.
-- Safe for concurrent execution if underlying Nodes are thread-safe.
+2
+3
    - Encapsulates engine, state type, and initial payload.
+- Provides a simplified interface for executing configured pipelines.
+- Safe for concurrent execution if underlying nodes are thread-safe.
 
    
 
 
@@ -1052,12 +1053,12 @@ and initial Payloads.
    
 
 
 
-
    1
    run(payload_override: Optional[Mapping[str, Any]] = None)
+
    1
    run(payload_override: Optional[Mapping[str, Any]] = None) -> list[State]
 
    
 
     
    
 
-      
    Execute pipeline.
    
+      
    Execute the pipeline.
    
 
 
 
    Parameters:
    
@@ -1100,6 +1101,7 @@ and initial Payloads.
    
       
    
           
    
             
+                  list[State]
             
             
               
    
@@ -1115,7 +1117,9 @@ Terminal execution states.
    
 
    
   Notes
   
    Responsibilities:
    
-
    1
    - Merges override payload with initial payload, creates root State, and executes engine.
+
    1
+2
    - Merges override payload with initial payload.
+- Creates root `State` and executes engine.
 
    
 
     
    
@@ -1187,7 +1191,7 @@ Terminal execution states.
    
       
    
           
    
 Pipeline            
-                  Pipeline
+                  Pipeline
             
             
               
    
@@ -1202,7 +1206,11 @@ Terminal execution states.
    
 
    
   Notes
   
    Responsibilities:
    
-
    
diff --git a/libs/doc-forge/site/cli/mkdocs_utils/index.html b/libs/doc-forge/site/cli/mkdocs_utils/index.html
index 40a6873..72a7182 100644
--- a/libs/doc-forge/site/cli/mkdocs_utils/index.html
+++ b/libs/doc-forge/site/cli/mkdocs_utils/index.html
@@ -959,6 +959,15 @@
     
@@ -1452,12 +1471,11 @@ documentation generation.
    
           
    1
    - Loads YAML configuration, builds schema, creates State subclass, loads Node instances, builds Graph topology, and initializes Engine.
+
    1
+2
+3
    - Loads YAML configuration and builds schema.
+- Creates `State` subclass and loads `Node` instances.
+- Builds `Graph` topology and initializes `Engine`.
 
    
 
     
    
diff --git a/libs/doc-forge/site/cli/commands/index.html b/libs/doc-forge/site/cli/commands/index.html
index fbf3b53..8aa73f0 100644
--- a/libs/doc-forge/site/cli/commands/index.html
+++ b/libs/doc-forge/site/cli/commands/index.html
@@ -915,6 +915,15 @@
         		
             
               
    
-                
    Treat the specified module directory as the
-project root.
    
+                
    Treat the specified module directory as the project root.
    
               
    
                 		
             
@@ -1298,8 +1319,7 @@ project root.
    
                 		
             
               
    
-                
    Directory where Markdown documentation sources
-will be generated.
    
+                
    Directory where Markdown documentation sources will be generated.
    
               
    
                 		
             
diff --git a/libs/doc-forge/site/cli/index.html b/libs/doc-forge/site/cli/index.html
index 5c81206..b1220d0 100644
--- a/libs/doc-forge/site/cli/index.html
+++ b/libs/doc-forge/site/cli/index.html
@@ -961,6 +961,15 @@
     
    
             project_name
             
-                  str | None
+                  Optional[str]
             
             
               
    
-                
    Optional override for the project name used in
-generated documentation metadata.
    
+                
    Optional override for the project name used in generated
+documentation metadata.
    
               
    
                 		
             
@@ -1217,8 +1238,8 @@ generated documentation metadata.
    
                 		
             
               
    
-                
    Directory where MCP resources (index.json, nav.json,
-and module data) will be written.
    
+                
    Directory where MCP resources (index.json, nav.json, and module data)
+will be written.
    
               
    
                 		
             
@@ -1310,8 +1331,7 @@ bundle (index.json, nav.json, and modules/).
    
                 		
             
               
    
-                
    If the MCP documentation bundle is missing
-required files or directories.
    
+                
    If the MCP documentation bundle is missing required files or directories.
    
               
    
                 		
           
    
             template
             
-                  Path | None
+                  Optional[Path]
             
             
               
    
-                
    Optional path to a custom MkDocs configuration template.
-If not provided, a built-in template will be used.
    
+                
    Optional path to a custom MkDocs configuration template. If not
+provided, a built-in template will be used.
    
               
    
                 		
             
@@ -1337,8 +1358,7 @@ If not provided, a built-in template will be used.
    
                 		
             
               
    
-                
    Destination path where the generated mkdocs.yml file
-will be written.
    
+                
    Destination path where the generated mkdocs.yml file will be written.
    
               
    
                 		
             
@@ -1378,8 +1398,7 @@ will be written.
    
                 		
             
               
    
-                
    If the navigation specification or template
-file cannot be found.
    
+                
    If the navigation specification or template file cannot be found.
    
               
    
                 		
           
    
             project_name
             
-                  str | None
+                  Optional[str]
             
             
               
    
-                
    Optional override for the project name used in
-documentation metadata.
    
+                
    Optional override for the project name used in documentation metadata.
    
               
    
                 		
             
@@ -1467,12 +1485,12 @@ documentation metadata.
    
           
    
             module_is_source
             
-                  bool | None
+                  Optional[bool]
             
             
               
    
-                
    If True, treat the specified module directory as
-the project root rather than a nested module.
    
+                
    If True, treat the specified module directory as the project root
+rather than a nested module.
    
               
    
                 		
             
diff --git a/libs/doc-forge/site/index.html b/libs/doc-forge/site/index.html
index f8c8af4..0a214a3 100644
--- a/libs/doc-forge/site/index.html
+++ b/libs/doc-forge/site/index.html
@@ -282,6 +282,15 @@
     
+  
+
+        
+          
  • 
+  
+    
+      Notes subsection grouping
+    
+  
+  
+
    • 
+        
+          
  • 
+  
+    
+      Example formatting
+    
+  
+  
+
    • 
+        
+          
  • 
+  
+    
+      Separator rules
+    
+  
+  
 
    • 
         
           
  • 
@@ -416,33 +565,6 @@
     
   
   
-
    • 
-        
-          
  • 
-  
-    
-      Notes subsection grouping
-    
-  
-  
-
    • 
-        
-          
  • 
-  
-    
-      Example formatting
-    
-  
-  
-
    • 
-        
-          
  • 
-  
-    
-      Separator rules
-    
-  
-  
 
    • 
         
           
  • 
@@ -452,11 +574,6 @@
     
   
   
-
    • 
-        
-      
-    
-  
 
         
           
  • 
@@ -1367,6 +1484,15 @@
     
+  
+
    • 
+        
+          
  • 
+  
+    
+      Notes subsection grouping
+    
+  
+  
+
    • 
+        
+          
  • 
+  
+    
+      Example formatting
+    
+  
+  
+
    • 
+        
+          
  • 
+  
+    
+      Separator rules
+    
+  
+  
 
    • 
         
           
  • 
@@ -1501,33 +1767,6 @@
     
   
   
-
    • 
-        
-          
  • 
-  
-    
-      Notes subsection grouping
-    
-  
-  
-
    • 
-        
-          
  • 
-  
-    
-      Example formatting
-    
-  
-  
-
    • 
-        
-          
  • 
-  
-    
-      Separator rules
-    
-  
-  
 
    • 
         
           
  • 
@@ -1537,11 +1776,6 @@
     
   
   
-
    • 
-        
-      
-    
-  
 
         
           
  • 
@@ -1754,64 +1988,64 @@
 
     
    
 
-      
    Renderer-agnostic Python documentation compiler that converts Python docstrings
+      
    Summary
    
+
    Renderer-agnostic Python documentation compiler that converts Python docstrings
 into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
    
 
    doc-forge statically analyzes source code, builds a semantic model of modules,
 classes, functions, and attributes, and renders that model into documentation
 outputs without executing user code.
    
 
    
-
    Installation
    
+
    Installation
    
 
    Install using pip:
    
-
    1
    pip install doc-forge
-
    
+
    1
    pip install doc-forge
+
    
 
    
-
    Quick start
    
-
    Generate a MkDocs site from a Python package:
    
-
    1
    doc-forge build --mkdocs --module my_package
-
    
-
    Generate MCP JSON documentation:
    
-
    1
    doc-forge build --mcp --module my_package
-
    
-
    Serve documentation locally:
    
-
    1
    doc-forge serve --mkdocs --module my_package
-
    
+
    CLI usage
    
+
    Generate an MkDocs site from a Python package:
    
+
    1
    doc-forge build --mkdocs --module my_package
+
    
+
    Generate MCP JSON documentation:
    
+
    1
    doc-forge build --mcp --module my_package
+
    
+
    Generate MkDocs site and MCP JSON documentation:
    
+
    1
    doc-forge build --mcp --mkdocs --module my_package
+
    
+
    Serve MkDocs locally:
    
+
    1
    doc-forge serve --mkdocs --module my_package
+
    
+
    Serve MCP locally:
    
+
    1
    doc-forge serve --mcp --module my_package
+
    
 
    
-
    Core concepts
    
-
    Loader
    
+
    Core concepts
    
+
    Loader
    
 
    Extracts symbols, signatures, and docstrings using static analysis.
    
-
    Semantic model
    
+
    Semantic model
    
 
    Structured, renderer-agnostic representation of the API.
    
-
    Renderer
    
+
    Renderer
    
 
    Converts the semantic model into output formats such as MkDocs or MCP JSON.
    
-
    Symbol
    
-
    Any documentable object:
    
-
    1
-2
-3
-4
-5
-6
    - module
-- class
-- function
-- method
-- property
-- attribute
-
    
+
    Symbol
    
+
    Any documentable object
    
+
      
+
    • module
      • 
+
    • class
      • 
+
    • function
      • 
+
    • method
      • 
+
    • property
      • 
+
    • attribute
      • 
+
    
 
    
-
    Architecture
    
+
    Architecture
    
 
    doc-forge follows a compiler architecture:
    
-
    Front-end:
    
-
    1
    Static analysis of modules, classes, functions, type hints, and docstrings.
-
    
-
    Middle-end:
    
-
    1
    Builds a semantic model describing symbols and relationships.
-
    
-
    Back-end:
    
-
    1
    Renders documentation using interchangeable renderers.
-
    
+
    Front-end:
    
+
    Static analysis of modules, classes, functions, type hints, and docstrings.
    
+
    Middle-end:
    
+
    Builds a semantic model describing symbols and relationships.
    
+
    Back-end:
    
+
    Renders documentation using interchangeable renderers.
    
 
    This architecture ensures deterministic documentation generation.
    
 
    
-
    Rendering pipeline
    
+
    Rendering pipeline
    
 
    Typical flow:
    
 
    1
 2
@@ -1822,50 +2056,21 @@ outputs without executing user code.
    
 7
 8
 9
    Python package
-    ↓
+    |
 Loader (static analysis)
-    ↓
+    |
 Semantic model
-    ↓
+    |
 Renderer
-    ↓
+    |
 MkDocs site or MCP JSON
 
    
 
    
-
    CLI usage
    
-
    Build MkDocs documentation:
    
-
    1
    doc-forge build --mkdocs --module my_package
-
    
-
    Build MCP documentation:
    
-
    1
    doc-forge build --mcp --module my_package
-
    
-
    Serve MkDocs locally:
    
-
    1
    doc-forge serve --module my_package
-
    
-
    
-
    Public API
    
-
    Loaders:
    
-
    1
-2
    GriffeLoader
-discover_module_paths
-
    
-
    Renderers:
    
-
    1
-2
    MkDocsRenderer
-MCPRenderer
-
    
-
    CLI:
    
-
    1
    main
-
    
-
    Models:
    
-
    1
    models
-
    
-
    
 
    Google-Styled Doc-Forge Convention (GSDFC)
    
 
    GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
    
 
      
 
    • Docstrings are the single source of truth.
      • 
-
    • doc-forge compiles docstrings but does not generate documentation content.
      • 
+
    • doc-forge compiles docstrings but does not generate documentation content.
      • 
 
    • Documentation follows the Python import hierarchy.
      • 
 
    • Every public symbol should have a complete and accurate docstring.
      • 
 
    
@@ -1874,17 +2079,14 @@ MCPRenderer
 
      
 
    • Use Markdown headings at package and module level.
      • 
 
    • Use Google-style structured sections at class, function, and method level.
      • 
-
    • Indent section contents using four spaces.
      • 
 
    • Use type hints in signatures instead of duplicating types in prose.
      • 
 
    • Write summaries in imperative form.
      • 
 
    • Sections are separated by ---
      • 
 
    
 
    
-
    Package docstrings
    
-
      
-
    • Package docstrings act as the documentation home page.
      • 
-
    
-
    Recommended sections:
    
+
    Notes subsection grouping
    
+
    Group related information using labeled subsections.
    
+
    Example:
    
 
     1
  2
  3
@@ -1894,16 +2096,108 @@ MCPRenderer
  7
  8
  9
-10
    ## Summary
-## Installation
-## Quick start
-## Core concepts
-## Architecture
-## Rendering pipeline
-## CLI usage
-## Public API
-## Examples
-## Notes
+10
+11
+12
+13
    Notes:
+    **Guarantees:**
+
+        - deterministic behavior
+
+    **Lifecycle:**
+
+        - created during initialization
+        - reused across executions
+
+    **Thread safety:**
+
+        - safe for concurrent reads
+
    
+
    
+
    Example formatting
    
+
      
+
    • Use indentation for examples.
      • 
+
    • Indent section contents using four spaces.
      • 
+
    • Use code blocks for example code.
      • 
+
    
+
+
+
    
+  Example
+  
    Single example:
    
+
    1
+2
+3
+4
+5
+6
    Example:
+
+    ```python
+    foo = Foo("example")
+    process(foo, multiplier=2)
+    ```
+
    
+
    Multiple examples:
    
+
     1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
    Example:
+    Create foo:
+
+        ```python
+        foo = Foo("example")
+        ```
+
+    Run engine:
+
+        ```python
+        engine = BarEngine([foo])
+        engine.run()
+        ```
+
    
+
          
    Avoid fenced code blocks inside structured sections.
    
+
    
+
    Separator rules
    
+
    Use horizontal separators only at docstring root level to separate sections:
    
+
    1
    ---
+
    
+
    Allowed locations:
    
+
      
+
    • package docstrings
      • 
+
    • module docstrings
      • 
+
    • major documentation sections
      • 
+
    
+
    Do not use separators inside code sections.
    
+
    
+
    Package docstrings
    
+
    Package docstrings act as the documentation home page.
    
+
    Recommended sections:
    
+
    1
+2
+3
+4
+5
+6
+7
+8
+9
    # Summary
+# Installation
+# Quick start
+# CLI usage
+# Core concepts
+# Architecture
+# Rendering pipeline
+# Examples
+# Notes
 
    
 
 
@@ -1939,9 +2233,9 @@ MCPRenderer
 27
 28
 29
-30
-31
-32
    • '''
+30
    '''
+# Summary
+
 Foo-bar processing framework.
 
 Provides tools for defining Foo objects and executing Bar pipelines.
@@ -1950,43 +2244,35 @@ Provides tools for defining Foo objects and executing Bar pipelines.
 
 # Installation
 
-    pip install foo-bar
+```bash
+pip install foo-bar
+```
 
 ---
 
 # Quick start
 
-    from foobar import Foo, BarEngine
+```python
+from foobar import Foo, BarEngine
 
-    foo = Foo("example")
-    engine = BarEngine([foo])
+foo = Foo("example")
+engine = BarEngine([foo])
 
-    result = engine.run()
-
----
-
-# Public API
-
-    Foo
-    Bar
-    BarEngine
+result = engine.run()
+```
 
 ---
 '''
 
    
 
          
    
-
    Module docstrings
    
-
      
-
    • Module docstrings describe a subsystem.
      • 
-
    
+
    Module docstrings
    
+
    Module docstrings describe a subsystem.
    
 
    Recommended sections:
    
 
    1
 2
-3
-4
    ## Summary
-## Examples
-## Notes
-## Public API
+3
    # Summary
+# Examples
+# Notes
 
    
 
 
@@ -2011,7 +2297,13 @@ Provides tools for defining Foo objects and executing Bar pipelines.
 16
 17
 18
-19
    '''
+19
+20
+21
+22
+23
    '''
+# Summary
+
 Foo execution subsystem.
 
 Provides utilities for executing Foo objects through Bar stages.
@@ -2020,6 +2312,7 @@ Provides utilities for executing Foo objects through Bar stages.
 
 Example:
 
+    ```python
     from foobar.engine import BarEngine
     from foobar.foo import Foo
 
@@ -2027,15 +2320,14 @@ Example:
 
     engine = BarEngine([foo])
     engine.run()
+    ```
 
 ---
 '''
 
    
 
          
    
-
    Class docstrings
    
-
      
-
    • Class docstrings define object responsibility, lifecycle, and attributes.
      • 
-
    
+
    Class docstrings
    
+
    Class docstrings define object responsibility, lifecycle, and attributes.
    
 
    Recommended sections:
    
 
    1
 2
@@ -2050,110 +2342,116 @@ Raises:
 
    
   Example
   
    Simple Foo:
    
-
     1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
    class Foo:
-    '''
-    Represents a unit of work.
-
-    Attributes:
-        name (str):
-            Identifier of the foo instance.
-
-        value (int):
-            Numeric value associated with foo.
-
-    Notes:
-        Guarantees:
-
-            - instances are immutable after creation
-
-        Lifecycle:
-
-            - create instance
-            - pass to processing engine
-
-    Example:
-        Create and inspect a Foo:
-
-            foo = Foo("example", value=42)
-            print(foo.name)
-    '''
-
    
+
     1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
    class Foo:
+    '''
+    Represents a unit of work.
+
+    Attributes:
+        name (str):
+            Identifier of the foo instance.
+
+        value (int):
+            Numeric value associated with foo.
+
+    Notes:
+        Guarantees:
+
+            - instances are immutable after creation
+
+        Lifecycle:
+
+            - create instance
+            - pass to processing engine
+
+    Example:
+        Create and inspect a Foo:
+
+            ```python
+            foo = Foo("example", value=42)
+            print(foo.name)
+            ```
+    '''
+
    
 
    Complex Bar:
    
-
     1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
    class BarEngine:
-    '''
-    Executes Foo objects through Bar stages.
-
-    Attributes:
-        foos (tuple[Foo, ...]):
-            Foo instances managed by the engine.
-
-    Notes:
-        Guarantees:
-
-            - deterministic execution order
-
-    Example:
-        Run engine:
-
-            foo1 = Foo("a")
-            foo2 = Foo("b")
-
-            engine = BarEngine([foo1, foo2])
-            engine.run()
-    '''
-
    
+
     1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
    class BarEngine:
+    '''
+    Executes Foo objects through Bar stages.
+
+    Attributes:
+        foos (tuple[Foo, ...]):
+            Foo instances managed by the engine.
+
+    Notes:
+        Guarantees:
+
+            - deterministic execution order
+
+    Example:
+        Run engine:
+
+            ```python
+            foo1 = Foo("a")
+            foo2 = Foo("b")
+
+            engine = BarEngine([foo1, foo2])
+            engine.run()
+            ```
+    '''
+
    
 
          
    
-
    Function and method docstrings
    
-
      
-
    • Function docstrings define API contracts.
      • 
-
    
+
    Function and method docstrings
    
+
    Function docstrings define API contracts.
    
 
    Recommended sections:
    
 
    1
 2
@@ -2172,132 +2470,142 @@ Example:
 
    
   Example
   
    Simple process method:
    
-
     1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
-28
-29
-30
-31
-32
    def process(foo: Foo, multiplier: int) -> int:
-    '''
-    Process a Foo instance.
-
-    Args:
-        foo (Foo):
-            Foo instance to process.
-
-        multiplier (int):
-            Value used to scale foo.
-
-    Returns:
-        int:
-            Processed result.
-
-    Raises:
-        ValueError:
-            If multiplier is negative.
-
-    Notes:
-        Guarantees:
-
-            - foo is not modified
-
-    Example:
-        Process foo:
-
-            foo = Foo("example", value=10)
-
-            result = process(foo, multiplier=2)
-            print(result)
-    '''
-
    
+
     1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
    def process(foo: Foo, multiplier: int) -> int:
+    '''
+    Process a Foo instance.
+
+    Args:
+        foo (Foo):
+            Foo instance to process.
+
+        multiplier (int):
+            Value used to scale foo.
+
+    Returns:
+        int:
+            Processed result.
+
+    Raises:
+        ValueError:
+            If multiplier is negative.
+
+    Notes:
+        Guarantees:
+
+            - foo is not modified
+
+    Example:
+        Process foo:
+
+            ```python
+            foo = Foo("example", value=10)
+
+            result = process(foo, multiplier=2)
+            print(result)
+            ```
+    '''
+
    
 
    Multiple Examples:
    
-
     1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
-28
    def combine(foo_a: Foo, foo_b: Foo) -> Foo:
-    '''
-    Combine two Foo instances.
-
-    Args:
-        foo_a (Foo):
-            First foo.
-
-        foo_b (Foo):
-            Second foo.
-
-    Returns:
-        Foo:
-            Combined foo.
-
-    Example:
-        Basic usage:
-
-            foo1 = Foo("a")
-            foo2 = Foo("b")
-
-            combined = combine(foo1, foo2)
-
-        Pipeline usage:
-
-            engine = BarEngine([foo1, foo2])
-            engine.run()
-    '''
-
    
+
     1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
    def combine(foo_a: Foo, foo_b: Foo) -> Foo:
+    '''
+    Combine two Foo instances.
+
+    Args:
+        foo_a (Foo):
+            First foo.
+
+        foo_b (Foo):
+            Second foo.
+
+    Returns:
+        Foo:
+            Combined foo.
+
+    Example:
+        Basic usage:
+
+            ```python
+            foo1 = Foo("a")
+            foo2 = Foo("b")
+
+            combined = combine(foo1, foo2)
+            ```
+
+        Pipeline usage:
+
+            ```python
+            engine = BarEngine([foo1, foo2])
+            engine.run()
+            ```
+    '''
+
    
 
          
    
-
    Property docstrings
    
-
      
-
    • Properties must document return values.
      • 
-
    
+
    Property docstrings
    
+
    Properties must document return values.
    
 
 
 
    
@@ -2316,7 +2624,12 @@ Example:
 11
 12
 13
-14
    @property
+14
+15
+16
+17
+18
    ```python
+@property
 def foos(self) -> tuple[Foo, ...]:
     '''
     Return contained Foo instances.
@@ -2326,16 +2639,17 @@ def foos(self) -> tuple[Foo, ...]:
             Stored foo objects.
 
     Example:
+        ```python
         container = FooContainer()
 
         foos = container.foos
+        ```
     '''
+```
 
    
       
    
-
    Attribute documentation
    
-
      
-
    • Document attributes in class docstrings using Attributes:.
      • 
-
    
+
    Attribute documentation
    
+
    Document attributes in class docstrings using Attributes:.
    
 
 
 
    
@@ -2350,7 +2664,10 @@ def foos(self) -> tuple[Foo, ...]:
  7
  8
  9
-10
    '''
+10
+11
+12
    ```python
+'''
 Represents a processing stage.
 
 Attributes:
@@ -2360,95 +2677,10 @@ Attributes:
     enabled (bool):
         Whether the stage is active.
 '''
+```
 
    
       
    
-
    Notes subsection grouping
    
-
      
-
    • Group related information using labeled subsections.
      • 
-
    
-
-
-
    
-  Example
-  
    Notes Example:
    
-
     1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
-10
-11
-12
-13
    Notes:
-    **Guarantees:**
-
-        - deterministic behavior
-
-    **Lifecycle:**
-
-        - created during initialization
-        - reused across executions
-
-    **Thread safety:**
-
-        - safe for concurrent reads
-
    
-
          
    
-
    Example formatting
    
-
      
-
    • Use indentation for examples.
      • 
-
    
-
-
-
    
-  Example
-  
    Single example:
    
-
    1
-2
-3
-4
    Example:
-
-    foo = Foo("example")
-    process(foo, multiplier=2)
-
    
-
    Multiple examples:
    
-
    1
-2
-3
-4
-5
-6
-7
-8
-9
    Example:
-    Create foo:
-
-        foo = Foo("example")
-
-    Run engine:
-
-        engine = BarEngine([foo])
-        engine.run()
-
    
-
          
    Avoid fenced code blocks inside structured sections.
    
-
    
-
    Separator rules
    
-
    Use horizontal separators only at docstring root level to separate sections:
    
-
    1
    ---
-
    
-
    Allowed locations:
    
-
      
-
    • package docstrings
      • 
-
    • module docstrings
      • 
-
    • major documentation sections
      • 
-
    
-
    Do not use separators inside code sections.
    
-
    
-
    Parsing guarantees
    
+
    Parsing guarantees
    
 
    GSDFC ensures doc-forge can deterministically extract: