{
  "module": "dagpipe.graph",
  "content": {
    "path": "dagpipe.graph",
    "docstring": "# Summary\n\nDefines DAG structure connecting nodes.\n\nA `Graph` describes execution topology only. It does not execute nodes or manage\n`State`. Execution is handled by an `Engine`.\n\n---\n\n# Responsibilities\n\n- Multiple roots, branching, and merging support.\n- Deterministic traversal based on topology.\n- Graph is mutable during construction but treated as immutable at runtime.",
    "objects": {
      "Node": {
        "name": "Node",
        "kind": "class",
        "path": "dagpipe.graph.Node",
        "signature": null,
        "docstring": "Base class for all dagpipe execution nodes.\n\nAttributes:\n    id (str):\n        Unique identifier of the node (snake_case dotted format).\n\n    name (str):\n        Human-readable display name.\n\nNotes:\n    **Responsibilities:**\n\n        - Represents a deterministic unit of execution in the pipeline graph.\n        - Consumes one `State` and produces zero, one, or many derived states.\n        - Defines execution logic and enables branching, filtering, and transformation.\n\n    **Guarantees:**\n\n        - Nodes must never mutate the input `State`.\n        - Instances are singletons per subclass and reused across executions.",
        "members": {
          "id": {
            "name": "id",
            "kind": "attribute",
            "path": "dagpipe.graph.Node.id",
            "signature": null,
            "docstring": null
          },
          "name": {
            "name": "name",
            "kind": "attribute",
            "path": "dagpipe.graph.Node.name",
            "signature": null,
            "docstring": null
          },
          "node_id_to_name": {
            "name": "node_id_to_name",
            "kind": "function",
            "path": "dagpipe.graph.Node.node_id_to_name",
            "signature": "node_id_to_name(node_id: str)",
            "docstring": "Convert a dotted snake_case node ID into a human-readable name.\n\nArgs:\n    node_id (str):\n        Unique node identifier (e.g., 'entity.resolve.numeric_merchant').\n\nReturns:\n    str:\n        Human-readable display name (e.g., 'Entity › Resolve › Numeric Merchant')."
          },
          "clean_id_and_name": {
            "name": "clean_id_and_name",
            "kind": "function",
            "path": "dagpipe.graph.Node.clean_id_and_name",
            "signature": "clean_id_and_name()",
            "docstring": "Normalize and validate node ID and display name.\n\nRaises:\n    TypeError:\n        If ID is not a string.\n    ValueError:\n        If ID format is invalid.\n\nNotes:\n    **Guarantees:**\n\n        - Generates ID from module and class name if missing.\n        - Validates ID format.\n        - Generates human-readable name if missing."
          },
          "run": {
            "name": "run",
            "kind": "function",
            "path": "dagpipe.graph.Node.run",
            "signature": "run(state: State)",
            "docstring": "Execute this node on a `State`.\n\nArgs:\n    state (State):\n        Input execution state.\n\nReturns:\n    tuple[State, ...]:\n        Derived execution states.\n\nRaises:\n    TypeError:\n        If `resolve()` yields a non-`State` object."
          },
          "fork": {
            "name": "fork",
            "kind": "function",
            "path": "dagpipe.graph.Node.fork",
            "signature": "fork(state: State, *, payload_update: Any = None, confidence_delta: float = 0.0, metadata_update: Any = None)",
            "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n    state (State):\n        Parent execution state.\n\n    payload_update (Any, optional):\n        Dot-path payload updates.\n\n    confidence_delta (float, optional):\n        Confidence adjustment.\n\n    metadata_update (Any, optional):\n        Metadata updates.\n\nReturns:\n    State:\n        New child execution state.\n\nNotes:\n    **Responsibilities:**\n\n        - Convenience wrapper around `State.fork()` that automatically\n          records this node's ID in state history."
          },
          "resolve": {
            "name": "resolve",
            "kind": "function",
            "path": "dagpipe.graph.Node.resolve",
            "signature": "resolve(state: State)",
            "docstring": "Execute node logic.\n\nArgs:\n    state (State):\n        Input execution state.\n\nReturns:\n    Iterable[State]:\n        Derived execution state(s).\n\nNotes:\n    **Responsibilities:**\n\n        - Subclasses implement specific resolution behavior.\n        - Must not mutate input state.\n        - Should use `fork()` to create child states.\n        - May yield zero states to terminate a branch."
          },
          "is_async": {
            "name": "is_async",
            "kind": "function",
            "path": "dagpipe.graph.Node.is_async",
            "signature": "is_async()",
            "docstring": "Return whether this node executes asynchronously.\n\nReturns:\n    bool:\n        True if the node is an `AsyncNode` instance."
          }
        }
      },
      "Graph": {
        "name": "Graph",
        "kind": "class",
        "path": "dagpipe.graph.Graph",
        "signature": "Graph()",
        "docstring": "Directed Acyclic Graph defining execution topology of `Node` objects.\n\nNotes:\n    **Responsibilities:**\n\n        - Stores node connectivity and validates that the topology remains acyclic.\n        - Structure determines how `State` flows between nodes during execution.\n\n    **Guarantees:**\n\n        - Topology is acyclic. Node relationships remain consistent.\n        - Thread-safe for concurrent reads after construction.",
        "members": {
          "add_edge": {
            "name": "add_edge",
            "kind": "function",
            "path": "dagpipe.graph.Graph.add_edge",
            "signature": "add_edge(src: Node, dst: Node) -> None",
            "docstring": "Add a directed edge from `src` to `dst`.\n\nArgs:\n    src (Node):\n        Source node.\n\n    dst (Node):\n        Destination node.\n\nRaises:\n    TypeError:\n        If `src` or `dst` is not a `Node`.\n\n    ValueError:\n        If the edge would create a cycle or if `src` and `dst` are common.\n\nNotes:\n    - Validates node types.\n    - Prevents cycles.\n    - Registers nodes if not present.\n    - Updates parent and child mappings."
          },
          "add_root": {
            "name": "add_root",
            "kind": "function",
            "path": "dagpipe.graph.Graph.add_root",
            "signature": "add_root(node: Node) -> None",
            "docstring": "Add a root node with no parents.\n\nArgs:\n    node (Node):\n        Node to add as a root.\n\nRaises:\n    TypeError:\n        If node is not a Node instance."
          },
          "children": {
            "name": "children",
            "kind": "function",
            "path": "dagpipe.graph.Graph.children",
            "signature": "children(node: Node) -> tuple[Node, ...]",
            "docstring": "Return child nodes of a node.\n\nArgs:\n    node (Node):\n        Node to query.\n\nReturns:\n    tuple[Node, ...]:\n        Outgoing neighbors."
          },
          "parents": {
            "name": "parents",
            "kind": "function",
            "path": "dagpipe.graph.Graph.parents",
            "signature": "parents(node: Node) -> tuple[Node, ...]",
            "docstring": "Return parent nodes of a node.\n\nArgs:\n    node (Node):\n        Node to query.\n\nReturns:\n    tuple[Node, ...]:\n        Incoming neighbors."
          },
          "roots": {
            "name": "roots",
            "kind": "function",
            "path": "dagpipe.graph.Graph.roots",
            "signature": "roots() -> tuple[Node, ...]",
            "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n    tuple[Node, ...]:\n        Entry point nodes."
          },
          "nodes": {
            "name": "nodes",
            "kind": "function",
            "path": "dagpipe.graph.Graph.nodes",
            "signature": "nodes() -> tuple[Node, ...]",
            "docstring": "Return all nodes in the graph.\n\nReturns:\n    tuple[Node, ...]:\n        All registered nodes."
          }
        }
      }
    }
  }
}