Class NodeTemplate

masfactory/core/node_template.py:250–377

Declarative template for creating nodes inside graphs. A `NodeTemplate` is a lightweight configuration object that can be reused across graphs. It does not instantiate nodes directly; graphs materialize templates via `Graph.create_node()` so the created node is always owned by a graph.

class NodeTemplate(Generic[T]):
    """Declarative template for creating nodes inside graphs.

    A `NodeTemplate` is a lightweight configuration object that can be reused across graphs.
    It does not instantiate nodes directly; graphs materialize templates via `Graph.create_node()`
    so the created node is always owned by a graph.
    """

    def __init__(self, node_cls: Type[T], **default_kwargs):
        """Create a NodeTemplate.

        Args:
            node_cls: Node class to be materialized.
            **default_kwargs: Default constructor kwargs applied during materialization.
        """
        self.node_cls = node_cls
        self.prototype_config = default_kwargs

    def __deepcopy__(self, memo: dict[int, Any]) -> "NodeTemplate[T]":
        """Deep-copy via MASFactory clone semantics instead of Python's generic object walk.

        This ensures nested NodeTemplate declarations still respect `Shared(...)`,
        `Factory(...)`, and `__node_template_scope__` when an outer template clones
        them as part of its prototype config.
        """
        obj_id = id(self)
        if obj_id in memo:
            return memo[obj_id]

        cloned = object.__new__(type(self))
        memo[obj_id] = cloned
        cloned.node_cls = self.node_cls
        cloned.prototype_config = _safe_clone(self.prototype_config, memo)
        return cloned

    def render_config(self, **override_kwargs) -> dict[str, Any]:
        final_config = _safe_clone(self.prototype_config)
        final_config.update(_safe_clone(override_kwargs))
        return final_config

    def __call__(self, *args: Any, **override_kwargs) -> "NodeTemplate[T]":
        """
        Create a derived template with overridden defaults.

        MASFactory graphs only accept Nodes created by Graph.create_node(), so NodeTemplate intentionally does NOT
        construct a Node instance directly.
        """
        if args:
            raise TypeError(
                "NodeTemplate(...) no longer materializes a Node. "
                "Use Graph.create_node(template, name=...) or declare nodes=[(name, template)]."
            )
        if "name" in override_kwargs:
            raise TypeError(
                "NodeTemplate(...) does not accept 'name'. "
                "Use Graph.create_node(template, name=...) or declare nodes=[(name, template)]."
            )
        if not override_kwargs: