Skip to content

The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.

Implement Generic Loops (Candidate III - implemented ✅) (CORE-14) (#16227)

rattus50ab50c15a31
diff --git a/comfy_api/latest/_io.py b/comfy_api/latest/_io.py
index 4c062d8aa..48fae0244 100644
--- a/comfy_api/latest/_io.py
+++ b/comfy_api/latest/_io.py
@@ -1547,7 +1547,7 @@ class HiddenHolder:
def __init__(self, unique_id: str, prompt: Any,
extra_pnginfo: Any, dynprompt: Any,
auth_token_comfy_org: str, api_key_comfy_org: str,
- comfy_usage_source: str = None, **kwargs):
+ comfy_usage_source: str = None, execution_list: Any = None, **kwargs):
self.unique_id = unique_id
"""UNIQUE_ID is the unique identifier of the node, and matches the id property of the node on the client side. It is commonly used in client-server communications (see messages)."""
self.prompt = prompt
@@ -1562,6 +1562,8 @@ class HiddenHolder:
"""API_KEY_COMFY_ORG is an API Key generated by ComfyOrg that allows skipping signing into a ComfyOrg account on frontend."""
self.comfy_usage_source = comfy_usage_source
"""COMFY_USAGE_SOURCE identifies the client that submitted the prompt (e.g. comfyui-frontend, comfy-cli, comfyui-mcp); forwarded to API nodes' upstream requests via the Comfy-Usage-Source header."""
+ self.execution_list = execution_list
+ """EXECUTION_LIST is the active graph scheduler."""
def __getattr__(self, key: str):
'''If hidden variable not found, return None.'''
@@ -1579,6 +1581,7 @@ class HiddenHolder:
auth_token_comfy_org=d.get(Hidden.auth_token_comfy_org, None),
api_key_comfy_org=d.get(Hidden.api_key_comfy_org, None),
comfy_usage_source=d.get(Hidden.comfy_usage_source, None),
+ execution_list=d.get(Hidden.execution_list, None),
)
@classmethod
@@ -1603,6 +1606,8 @@ class Hidden(str, Enum):
"""API_KEY_COMFY_ORG is an API Key generated by ComfyOrg that allows skipping signing into a ComfyOrg account on frontend."""
comfy_usage_source = "COMFY_USAGE_SOURCE"
"""COMFY_USAGE_SOURCE identifies the client that submitted the prompt (e.g. comfyui-frontend, comfy-cli, comfyui-mcp); forwarded to API nodes' upstream requests via the Comfy-Usage-Source header."""
+ execution_list = "EXECUTION_LIST"
+ """EXECUTION_LIST is the active graph scheduler."""
@dataclass
diff --git a/comfy_execution/graph.py b/comfy_execution/graph.py
index 64dec2045..e9eba9bfb 100644
--- a/comfy_execution/graph.py
+++ b/comfy_execution/graph.py
@@ -22,18 +22,27 @@ class DynamicPrompt:
def __init__(self, original_prompt):
# The original prompt provided by the user
self.original_prompt = original_prompt
+ # Runtime replacements for original nodes, without mutating the submitted prompt.
+ self.node_overrides = {}
# Any extra pieces of the graph created during execution
self.ephemeral_prompt = {}
self.ephemeral_parents = {}
self.ephemeral_display = {}
def get_node(self, node_id):
+ if node_id in self.node_overrides:
+ return self.node_overrides[node_id]
if node_id in self.ephemeral_prompt:
return self.ephemeral_prompt[node_id]
if node_id in self.original_prompt:
return self.original_prompt[node_id]
raise NodeNotFoundError(f"Node {node_id} not found")
+ def override_node(self, node_id, node_info):
+ if not self.has_node(node_id):
+ raise NodeNotFoundError(f"Node {node_id} not found")
+ self.node_overrides[node_id] = node_info
+
def has_node(self, node_id):
return node_id in self.original_prompt or node_id in self.ephemeral_prompt
@@ -110,6 +119,7 @@ class TopologicalSort:
self.blockCount = {} # Number of nodes this node is directly blocked by
self.blocking = {} # Which nodes are blocked by this node
self.externalBlocks = 0
+ self.externalBlockResults = {}
self.unblockedEvent = asyncio.Event()
def get_input_info(self, unique_id, input_name):
@@ -169,12 +179,20 @@ class TopologicalSort:
assert node_id in self.blockCount, "Can't add external block to a node that isn't pending"
self.externalBlocks += 1
self.blockCount[node_id] += 1
- def unblock():
- self.externalBlocks -= 1
- self.blockCount[node_id] -= 1
- self.unblockedEvent.set()
+ def unblock(value=None):
+ self.release_external_block(node_id, value)
return unblock
+ def release_external_block(self, node_id, value=None):
+ self.externalBlocks -= 1
+ self.blockCount[node_id] -= 1
+ if value is not None:
+ self.externalBlockResults[node_id] = value
+ self.unblockedEvent.set()
+
+ def get_external_block_result(self, node_id):
+ return self.externalBlockResults.get(node_id)
+
def is_cached(self, node_id):
return False
@@ -186,6 +204,7 @@ class TopologicalSort:
for blocked_node_id in self.blocking[unique_id]:
self.blockCount[blocked_node_id] -= 1
del self.blocking[unique_id]
+ self.externalBlockResults.pop(unique_id, None)
def is_empty(self):
return len(self.pendingNodes) == 0
@@ -239,6 +258,28 @@ class ExecutionList(TopologicalSort):
super().add_strong_link(from_node_id, from_socket, to_node_id)
self.cache_link(from_node_id, to_node_id, from_socket)
+ def inhibit_nodes(self, node_ids):
+ """Remove pending nodes selected by the currently executing control node."""
+ assert self.staged_node_id is not None, "Nodes may only be inhibited while a control node is staged"
+ node_ids = set(node_ids).intersection(self.pendingNodes)
+ assert self.staged_node_id not in node_ids, "A control node cannot inhibit itself"
+
+ for from_node_id, blocked_nodes in self.blocking.items():
+ if from_node_id not in node_ids:
+ for node_id in node_ids:
+ blocked_nodes.pop(node_id, None)
+ for node_id in node_ids:
+ for blocked_node_id in self.blocking[node_id]:
+ if blocked_node_id not in node_ids:
+ self.blockCount[blocked_node_id] -= 1
+ del self.pendingNodes[node_id]
+ del self.blockCount[node_id]
+ del self.blocking[node_id]
+ self.execution_cache.pop(node_id, None)
+ self.execution_cache_listeners.pop(node_id, None)
+ for listeners in self.execution_cache_listeners.values():
+ listeners.difference_update({listener for listener in listeners if listener[0] in node_ids})
+
async def stage_node_execution(self):
assert self.staged_node_id is None
if self.is_empty():
@@ -315,6 +356,10 @@ class ExecutionList(TopologicalSort):
assert self.staged_node_id is not None
self.staged_node_id = None
+ def is_staged_node_blocked(self):
+ assert self.staged_node_id is not None
+ return self.blockCount[self.staged_node_id] > 0
+
def complete_node_execution(self):
node_id = self.staged_node_id
self.pop_node(node_id)
diff --git a/comfy_execution/validation.py b/comfy_execution/validation.py
index ae9a2376c..6c51737b3 100644
--- a/comfy_execution/validation.py
+++ b/comfy_execution/validation.py
@@ -1,4 +1,193 @@
from comfy_api.latest import IO
+from comfy_execution.graph_utils import is_link
+
+
+class LoopValidationError(Exception):
+ def __init__(self, error_type, message, details, node_ids, output_ids):
+ super().__init__(details)
+ self.error = {
+ "type": "custom_validation_failed",
+ "message": message,
+ "details": details,
+ "extra_info": {
+ "input_name": "loop boundary",
+ "loop_error_type": error_type,
+ "node_ids": sorted(node_ids),
+ "output_ids": sorted(output_ids),
+ },
+ }
+
+
+def _walk_graph(start_ids, edges, stop_at=(), return_stops=False):
+ found = set()
+ stops = set()
+ pending = list(start_ids)
+ while pending:
+ node_id = pending.pop()
+ if node_id in found:
+ continue
+ found.add(node_id)
+ if node_id in stop_at:
+ stops.add(node_id)
+ else:
+ pending.extend(edges[node_id])
+ return stops if return_stops else found
+
+
+def _loop_validation_error(error_type, message, details, actors, children, outputs):
+ reached_outputs = _walk_graph(actors, children).intersection(outputs)
+ return LoopValidationError(error_type, message, details, actors, reached_outputs)
+
+
+def validate_loops(prompt, outputs, node_ids, start_nodes, end_nodes):
+ if not start_nodes and not end_nodes:
+ return {}
+
+ node_ids = set(node_ids)
+ all_children = {node_id: set() for node_id in prompt}
+ all_parents = {node_id: set() for node_id in prompt}
+ for node_id, node in prompt.items():
+ for value in node.get("inputs", {}).values():
+ if is_link(value) and value[0] in all_children:
+ all_children[value[0]].add(node_id)
+ all_parents[node_id].add(value[0])
+ continuation = _walk_graph(outputs, all_children, start_nodes)
+ continuation.difference_update(set(start_nodes).difference(node_ids))
+ node_ids.update(continuation)
+ node_ids.update(_walk_graph(set(end_nodes).intersection(continuation), all_parents, start_nodes))
+ parents = {
+ node_id: {
+ value[0]
+ for value in prompt[node_id].get("inputs", {}).values()
+ if is_link(value) and value[0] in node_ids
+ }
+ for node_id in node_ids
+ }
+
+ children = {node_id: set() for node_id in node_ids}
+ for node_id, node_parents in parents.items():
+ for parent_id in node_parents:
+ children[parent_id].add(node_id)
+
+ start_nodes = set(start_nodes).intersection(node_ids)
+ end_nodes = set(end_nodes).intersection(node_ids)
+ terminal_outputs = {node_id for node_id in outputs if not children[node_id]}
+
+ # Construct the Start DAG independently of Ends. Completed inner loops can
+ # lead to later Starts which are still nested under the same outer Start.
+ start_dag = {
+ start_id: _walk_graph(children[start_id], children, start_nodes, return_stops=True)
+ for start_id in start_nodes
+ }
+ start_descendants = {
+ start_id: _walk_graph(start_dag[start_id], start_dag)
+ for start_id in start_nodes
+ }
+
+ # Construct the End DAG in the reverse direction. Its leaves are the
+ # innermost Ends and are therefore paired first.
+ end_dag = {
+ end_id: _walk_graph(parents[end_id], parents, end_nodes, return_stops=True)
+ for end_id in end_nodes
+ }
+
+ pairs = {}
+ remaining_starts = set(start_nodes)
+ remaining_ends = set(end_nodes)
+ while remaining_ends:
+ end_id = next(
+ node_id
+ for node_id in sorted(remaining_ends)
+ if not end_dag[node_id].intersection(remaining_ends)
+ )
+
+ candidates = _walk_graph(parents[end_id], parents, remaining_starts, return_stops=True)
+
+ if not candidates:
+ raise _loop_validation_error(
+ "loop_end_without_start",
+ "End Loop has no Start Loop",
+ f"End Loop {end_id} has no available Start Loop",
+ {end_id},
+ children,
+ outputs,
+ )
+
+ closest = {
+ candidate
+ for candidate in candidates
+ if all(other == candidate or candidate in start_descendants[other] for other in candidates)
+ }
+ if len(closest) != 1:
+ candidate_list = ", ".join(sorted(candidates))
+ raise _loop_validation_error(
+ "ambiguous_loop_nesting",
+ "End Loop has ambiguous Start Loops",
+ f"End Loop {end_id} can close multiple unrelated Start Loops: {candidate_list}",
+ candidates.union((end_id,)),
+ children,
+ outputs,
+ )
+
+ start_id = closest.pop()
+ pairs[start_id] = end_id
+ remaining_starts.remove(start_id)
+ remaining_ends.remove(end_id)
+
+ # Validate the new pair immediately. Previously paired Ends are inner
+ # boundaries and may be crossed; an unpaired End or output is an escape.
+ escapes = _walk_graph(
+ children[start_id],
+ children,
+ remaining_ends | terminal_outputs | {end_id},
+ return_stops=True,
+ )
+ escapes.discard(end_id)
+ if escapes:
+ escape_list = ", ".join(sorted(escapes))
+ raise _loop_validation_error(
+ "loop_escape",
+ "Loop body is not closed",
+ f"Start Loop {start_id} reaches {escape_list} without passing through End Loop {end_id}",
+ escapes | {start_id, end_id},
+ children,
+ outputs,
+ )
+
+ if remaining_starts:
+ start_list = ", ".join(sorted(remaining_starts))
+ raise _loop_validation_error(
+ "loop_start_without_end",
+ "Start Loop has no End Loop",
+ f"Start Loops without End Loops: {start_list}",
+ remaining_starts,
+ children,
+ outputs,
+ )
+
+ bodies = {}
+ for start_id, end_id in pairs.items():
+ body = _walk_graph(children[start_id], children, {end_id})
+ body.remove(end_id)
+ bodies[start_id] = body
+ accumulate = prompt[end_id].get("inputs", {}).get("accumulate")
+ if is_link(accumulate) and (accumulate[0] == start_id or accumulate[0] in body):
+ source_id = accumulate[0]
+ raise _loop_validation_error(
+ "loop_accumulate_from_body",
+ "End Loop accumulate depends on its loop body",
+ f"End Loop {end_id} accumulate is driven by loop node {source_id} under Start Loop {start_id}",
+ {start_id, end_id, source_id},
+ children,
+ outputs,
+ )
+
+ for start_id, end_id in pairs.items():
+ body = bodies[start_id]
+ prompt[start_id]["_loop_body"] = sorted(body)
+ prompt[start_id]["_loop_end"] = end_id
+
+ return pairs
def validate_node_input(
diff --git a/comfy_extras/nodes_loop.py b/comfy_extras/nodes_loop.py
new file mode 100644
index 000000000..8a6242049
--- /dev/null
+++ b/comfy_extras/nodes_loop.py
@@ -0,0 +1,405 @@
+from comfy_api.latest import io
+from comfy_execution.graph_utils import GraphBuilder, is_link
+from server import PromptServer
+
+
+def _cache_enabled(value):
+ return value[0] if isinstance(value, list) else value
+
+
+def _expand_loop(dynprompt, opener_id, body, close_id, values, list_items, initial_value, reuse_cache):
+ graph = GraphBuilder()
+ loop_metadata = {}
+ close_inputs = dynprompt.get_node(close_id)["inputs"]
+ output_source = close_inputs.get("output_value")
+ next_source = close_inputs.get("next_iteration_value")
+ terminations = [value for name, value in close_inputs.items() if name.startswith("termination") and is_link(value)]
+ accumulate = bool(close_inputs.get("accumulate", False))
+ previous_carry = initial_value
+ previous_dependencies = []
+ previous_progress = None
+ result_inputs = {"close_id": close_id}
+
+ for position, value in enumerate(values):
+ item = list_items[position] if list_items is not None else None
+ iteration_inputs = {
+ "iteration_index": value,
+ "is_first": position == 0,
+ "is_last": position == len(values) - 1,
+ "list_item": item,
+ "current_iteration_value": previous_carry,
+ "reuse_cache": reuse_cache,
+ **{f"dependency{index}": dependency for index, dependency in enumerate(previous_dependencies)},
+ }
+ iteration = graph.node(
+ "LoopIteration",
+ f"iteration_{position}",
+ **iteration_inputs,
+ )
+ iteration.set_override_display_id(opener_id)
+ copies = {}
+ for node_id in body:
+ original = dynprompt.get_node(node_id)
+ copy = graph.node(original["class_type"], f"{position}_{node_id}")
+ copy.set_override_display_id(node_id)
+ copies[node_id] = copy
+
+ def copied_link(source):
+ if not is_link(source):
+ return source
+ if source[0] == opener_id:
+ return iteration.out(source[1])
+ if source[0] in copies:
+ return copies[source[0]].out(source[1])
+ return source
+
+ for node_id, copy in copies.items():
+ original = dynprompt.get_node(node_id)
+ for name, input_value in original.get("inputs", {}).items():
+ copy.set_input(name, copied_link(input_value))
+ if "_loop_end" in original:
+ loop_metadata[copy.id] = {
+ "_loop_body": [copies[body_id].id for body_id in original["_loop_body"]],
+ "_loop_end": copies[original["_loop_end"]].id,
+ }
+
+ if is_link(output_source):
+ copied_output = copied_link(output_source)
+ if accumulate:
+ result_inputs[f"output{position}"] = copied_output
+ elif position == len(values) - 1:
+ result_inputs["output0"] = copied_output
+ dependencies = [copied_output]
+ else:
+ dependencies = []
+ if is_link(next_source):
+ previous_carry = copied_link(next_source)
+ dependencies.append(previous_carry)
+ dependencies.extend(copied_link(source) for source in terminations)
+ previous_dependencies = dependencies
+ progress_inputs = {
+ "start_id": opener_id,
+ "position": position + 1,
+ "total": len(values),
+ **{f"dependency{index}": dependency for index, dependency in enumerate(dependencies)},
+ }
+ if previous_progress is not None:
+ progress_inputs["previous_progress"] = previous_progress
+ progress = graph.node(
+ "LoopProgress",
+ f"progress_{position}",
+ **progress_inputs,
+ )
+ previous_progress = progress.out(0)
+
+ if previous_progress is not None:
+ result_inputs["progress"] = previous_progress
+ result_inputs.update({f"dependency{index}": dependency for index, dependency in enumerate(previous_dependencies)})
+ graph.node("LoopResult", "result", **result_inputs)
+ expanded = graph.finalize()
+ for node_id, metadata in loop_metadata.items():
+ expanded[node_id].update(metadata)
+ return expanded
+
+
+class StartLoop(io.ComfyNode):
+ LOOP_BOUNDARY = "start"
+
+ @classmethod
+ def define_schema(cls):
+ list_item_type = io.MatchType.Template("list_item")
+ carried_type = io.MatchType.Template("carried_value")
+ return io.Schema(
+ node_id="StartLoop",
+ display_name="Start Loop",
+ category="utilities/looping",
+ is_input_list=True,
+ inputs=[
+ io.DynamicCombo.Input("mode", options=[
+ io.DynamicCombo.Option("simple", [
+ io.Int.Input(
+ "num_iterations",
+ default=4,
+ min=0,
+ tooltip="Number of times to execute the loop body.",
+ ),
+ ]),
+ io.DynamicCombo.Option("For", [
+ io.Int.Input(
+ "start_iteration_index",
+ default=0,
+ tooltip="Index of the first iteration when using For loop mode.",
+ ),
+ io.Int.Input(
+ "max_iteration",
+ default=4,
+ max=0xffffffffffffffff,
+ tooltip="The exclusive stopping value for iteration_index in For mode.",
+ ),
+ io.Int.Input(
+ "step",
+ default=1,
+ min=1,
+ tooltip="The index step size between each iteration when using For loop mode.",
+ ),
+ ]),
+ io.DynamicCombo.Option("List", [
+ io.MatchType.Input(
+ "list",
+ list_item_type,
+ tooltip="List of items the loop iterates on. The loop body executes once per item.",
+ ),
+ ]),
+ ], tooltip="The loop iteration mode."),
+ io.Boolean.Input(
+ "cache_iterations",
+ default=False,
+ advanced=True,
+ tooltip="Reuse unchanged iteration results from previous executions. Disable to execute every iteration again.",
+ ),
+ io.Int.Input(
+ "parent_iteration",
+ optional=True,
+ force_input=True,
+ tooltip="Connect iteration_index from an outer Start Loop to nest this loop.",
+ ),
+ io.MatchType.Input(
+ "initial_iteration_value",
+ carried_type,
+ optional=True,
+ tooltip="Value exposed as current_iteration_value on the first iteration.",
+ ),
+ ],
+ outputs=[
+ io.Int.Output("iteration_index", tooltip="Index of the current loop iteration."),
+ io.Boolean.Output("is_first", tooltip="True during the first iteration of the loop."),
+ io.Boolean.Output("is_last", tooltip="True during the last iteration of the loop."),
+ io.MatchType.Output(
+ list_item_type,
+ id="list_item",
+ tooltip="Current item from the list when using List mode. None in Simple and For modes.",
+ ),
+ io.MatchType.Output(
+ carried_type,
+ id="current_iteration_value",
+ tooltip="Loop-carried value for the current iteration: initial_iteration_value on the first iteration, then next_iteration_value from End Loop on each subsequent iteration.",
+ ),
+ ],
+ hidden=[io.Hidden.dynprompt, io.Hidden.execution_list, io.Hidden.unique_id],
+ enable_expand=True,
+ )
+
+ @classmethod
+ def execute(cls, mode, cache_iterations=False, parent_iteration=None, initial_iteration_value=None):
+ selected_mode = mode.get("mode", ["simple"])[0]
+ if selected_mode == "simple":
+ values = list(range(mode.get("num_iterations", [4])[0]))
+ list_items = None
+ elif selected_mode == "For":
+ step = mode.get("step", [1])[0]
+ if step == 0:
+ raise ValueError("Start Loop step must not be 0")
+ values = list(range(mode.get("start_iteration_index", [0])[0], mode.get("max_iteration", [4])[0], step))
+ list_items = None
+ else:
+ list_items = mode["list"]
+ values = list(range(len(list_items)))
+
+ dynprompt = cls.hidden.dynprompt
+ execution_list = cls.hidden.execution_list
+ unique_id = cls.hidden.unique_id
+ loop = dynprompt.get_node(unique_id)
+ body = set(loop["_loop_body"])
+ close_id = loop["_loop_end"]
+ graph = _expand_loop(
+ dynprompt,
+ unique_id,
+ body,
+ close_id,
+ values,
+ list_items,
+ initial_iteration_value[0] if initial_iteration_value else None,
+ _cache_enabled(cache_iterations),
+ )
+ close = dynprompt.get_node(close_id)
+ close_inputs = close["inputs"].copy()
+ for name in tuple(close_inputs):
+ if name in ("output_value", "next_iteration_value") or name.startswith("termination"):
+ del close_inputs[name]
+ execution_list.add_node(close_id)
+ execution_list.add_external_block(close_id)
+ execution_list.inhibit_nodes(body)
+ dynprompt.override_node(close_id, {"class_type": close["class_type"], "inputs": close_inputs})
+ PromptServer.instance.send_progress_text(f"Iteration 0 / {len(values)}", unique_id)
+ return io.NodeOutput(None, False, not values, None, None, expand=graph)
+
+ @classmethod
+ def fingerprint_inputs(cls, cache_iterations=False, **kwargs):
+ return float("NaN")
+
+
+class LoopIteration(io.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return io.Schema(
+ node_id="LoopIteration",
+ is_input_list=True,
+ inputs=[
+ io.Int.Input("iteration_index"),
+ io.Boolean.Input("is_first"),
+ io.Boolean.Input("is_last"),
+ io.AnyType.Input("list_item", optional=True),
+ io.AnyType.Input("current_iteration_value", optional=True),
+ io.Boolean.Input("reuse_cache"),
+ ],
+ outputs=[io.Int.Output(), io.Boolean.Output(), io.Boolean.Output(), io.AnyType.Output(), io.AnyType.Output()],
+ is_dev_only=True,
+ accept_all_inputs=True,
+ )
+
+ @classmethod
+ def execute(
+ cls,
+ iteration_index,
+ is_first,
+ is_last,
+ reuse_cache,
+ list_item=None,
+ current_iteration_value=None,
+ **kwargs,
+ ):
+ return io.NodeOutput(
+ iteration_index[0],
+ is_first[0],
+ is_last[0],
+ list_item[0] if list_item else None,
+ current_iteration_value[0] if current_iteration_value else None,
+ )
+
+ @classmethod
+ def fingerprint_inputs(cls, reuse_cache, **kwargs):
+ return None if _cache_enabled(reuse_cache) else float("NaN")
+
+
+class LoopProgress(io.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return io.Schema(
+ node_id="LoopProgress",
+ is_input_list=True,
+ inputs=[io.String.Input("start_id"), io.Int.Input("position"), io.Int.Input("total")],
+ outputs=[io.Int.Output()],
+ is_output_node=True,
+ is_dev_only=True,
+ accept_all_inputs=True,
+ )
+
+ @classmethod
+ def execute(cls, start_id, position, total, **kwargs):
+ PromptServer.instance.send_progress_text(f"Iteration {position[0]} / {total[0]}", start_id[0])
+ return io.NodeOutput(position[0])
+
+ @classmethod
+ def fingerprint_inputs(cls, **kwargs):
+ return float("NaN")
+
+
+class LoopResult(io.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return io.Schema(
+ node_id="LoopResult",
+ is_input_list=True,
+ inputs=[io.String.Input("close_id")],
+ outputs=[],
+ is_output_node=True,
+ is_dev_only=True,
+ accept_all_inputs=True,
+ hidden=[io.Hidden.execution_list],
+ )
+
+ @classmethod
+ def execute(cls, close_id, **kwargs):
+ outputs = []
+ while f"output{len(outputs)}" in kwargs:
+ outputs.append(kwargs[f"output{len(outputs)}"])
+ cls.hidden.execution_list.release_external_block(close_id[0], outputs)
+ return io.NodeOutput()
+
+ @classmethod
+ def fingerprint_inputs(cls, **kwargs):
+ return float("NaN")
+
+
+class EndLoop(io.ComfyNode):
+ LOOP_BOUNDARY = "end"
+
+ @classmethod
+ def define_schema(cls):
+ output_type = io.MatchType.Template("output_value")
+ carried_type = io.MatchType.Template("carried_value")
+ terminations = io.Autogrow.TemplatePrefix(
+ io.AnyType.Input(
+ "termination",
+ tooltip="Connect a preview or side-effect output that must execute on every iteration. Its value is not returned.",
+ ),
+ prefix="termination",
+ min=0,
+ max=50,
+ )
+ return io.Schema(
+ node_id="EndLoop",
+ display_name="End Loop",
+ category="utilities/looping",
+ is_input_list=True,
+ inputs=[
+ io.MatchType.Input(
+ "output_value",
+ output_type,
+ optional=True,
+ tooltip="Value returned by End Loop. It returns the final iteration or all iterations according to accumulate.",
+ ),
+ io.MatchType.Input(
+ "next_iteration_value",
+ carried_type,
+ optional=True,
+ tooltip="Value sent from End Loop back to Start Loop for the next iteration.",
+ ),
+ io.Boolean.Input(
+ "accumulate",
+ default=False,
+ tooltip="Return output_value from every iteration when enabled; otherwise return only the final iteration.",
+ ),
+ io.Autogrow.Input(
+ "terminations",
+ template=terminations,
+ optional=True,
+ tooltip="Connect outputs that must execute on every iteration. Their values are not returned.",
+ ),
+ ],
+ outputs=[
+ io.MatchType.Output(
+ output_type,
+ id="outputs",
+ is_output_list=True,
+ tooltip="The final iteration's output_value, or values accumulated across iterations when accumulate is enabled.",
+ ),
+ ],
+ hidden=[io.Hidden.execution_list, io.Hidden.unique_id],
+ )
+
+ @classmethod
+ def execute(cls, accumulate, **kwargs):
+ outputs = cls.hidden.execution_list.get_external_block_result(cls.hidden.unique_id)
+ return io.NodeOutput([value for output in outputs for value in output])
+
+
+NODE_CLASS_MAPPINGS = {
+ "StartLoop": StartLoop,
+ "EndLoop": EndLoop,
+ "LoopIteration": LoopIteration, # Dev-only; instantiated by loop expansion.
+ "LoopProgress": LoopProgress, # Dev-only; instantiated by loop expansion.
+ "LoopResult": LoopResult, # Dev-only; instantiated by loop expansion.
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {"StartLoop": "Start Loop", "EndLoop": "End Loop"}
diff --git a/comfy_extras/nodes_toolkit.py b/comfy_extras/nodes_toolkit.py
index 9f709bbe3..f43177a84 100644
--- a/comfy_extras/nodes_toolkit.py
+++ b/comfy_extras/nodes_toolkit.py
@@ -5,9 +5,8 @@ from comfy_api.latest import ComfyExtension, io
class CreateList(io.ComfyNode):
@classmethod
def define_schema(cls):
- template_matchtype = io.MatchType.Template("type")
template_autogrow = io.Autogrow.TemplatePrefix(
- input=io.MatchType.Input("input", template=template_matchtype),
+ input=io.AnyType.Input("input"),
prefix="input",
)
return io.Schema(
@@ -18,8 +17,7 @@ class CreateList(io.ComfyNode):
search_aliases=["Image Iterator", "Text Iterator", "Iterator"],
inputs=[io.Autogrow.Input("inputs", template=template_autogrow)],
outputs=[
- io.MatchType.Output(
- template=template_matchtype,
+ io.AnyType.Output(
is_output_list=True,
display_name="list",
),
@@ -34,11 +32,32 @@ class CreateList(io.ComfyNode):
return io.NodeOutput(output_list)
+class GetItemFromList(io.ComfyNode):
+ @classmethod
+ def define_schema(cls):
+ return io.Schema(
+ node_id="GetItemFromList",
+ display_name="Get Item From List",
+ category="utilities",
+ is_input_list=True,
+ inputs=[
+ io.AnyType.Input("list"),
+ io.Int.Input("index", default=0),
+ ],
+ outputs=[io.AnyType.Output()],
+ )
+
+ @classmethod
+ def execute(cls, list, index) -> io.NodeOutput:
+ return io.NodeOutput(list[index[0]])
+
+
class ToolkitExtension(ComfyExtension):
@override
async def get_node_list(self) -> list[type[io.ComfyNode]]:
return [
CreateList,
+ GetItemFromList,
]
diff --git a/execution.py b/execution.py
index 1c9e531de..adbb4cebe 100644
--- a/execution.py
+++ b/execution.py
@@ -40,7 +40,7 @@ from comfy_execution.graph import (
get_input_info,
)
from comfy_execution.graph_utils import GraphBuilder, is_link
-from comfy_execution.validation import validate_node_input
+from comfy_execution.validation import LoopValidationError, validate_loops, validate_node_input
from comfy_execution.progress import get_progress_state, reset_progress_state, add_progress_handler, WebUIProgressHandler
from comfy_execution.utils import CurrentNodeContext
from comfy_execution.asset_enrichment import register_executed_outputs, emit_cached_output
@@ -209,6 +209,8 @@ def get_input_data(inputs, class_def, unique_id, execution_list=None, dynprompt=
hidden_inputs_v3[io.Hidden.api_key_comfy_org] = extra_data.get("api_key_comfy_org", None)
if io.Hidden.comfy_usage_source.name in hidden:
hidden_inputs_v3[io.Hidden.comfy_usage_source] = extra_data.get("comfy_usage_source", None)
+ if io.Hidden.execution_list.name in hidden:
+ hidden_inputs_v3[io.Hidden.execution_list] = execution_list
else:
if "hidden" in valid_inputs:
h = valid_inputs["hidden"]
@@ -217,6 +219,8 @@ def get_input_data(inputs, class_def, unique_id, execution_list=None, dynprompt=
input_data_all[x] = [dynprompt.get_original_prompt() if dynprompt is not None else {}]
if h[x] == "DYNPROMPT":
input_data_all[x] = [dynprompt]
+ if h[x] == "EXECUTION_LIST":
+ input_data_all[x] = [execution_list]
if h[x] == "EXTRA_PNGINFO":
input_data_all[x] = [extra_data.get('extra_pnginfo', None)]
if h[x] == "UNIQUE_ID":
@@ -514,6 +518,8 @@ async def execute(server: "ExecutionServer", dynprompt, caches, current_item, ex
for i in required_inputs:
execution_list.make_input_strong_link(unique_id, i)
return (ExecutionResult.PENDING, None, None)
+ if execution_list.is_staged_node_blocked():
+ return (ExecutionResult.PENDING, None, None)
def execution_block_cb(block):
if block.message is not None:
@@ -1167,6 +1173,15 @@ async def validate_prompt(prompt_id, prompt, partial_execution_list: Union[list[
}
return (False, error, [], {})
+ start_nodes = set()
+ end_nodes = set()
+ for node_id, node in prompt.items():
+ boundary = getattr(nodes.NODE_CLASS_MAPPINGS[node["class_type"]], "LOOP_BOUNDARY", None)
+ if boundary == "start":
+ start_nodes.add(node_id)
+ elif boundary == "end":
+ end_nodes.add(node_id)
+
good_outputs = set()
errors = []
node_errors = {}
@@ -1222,6 +1237,31 @@ async def validate_prompt(prompt_id, prompt, partial_execution_list: Union[list[
node_errors[node_id]["dependent_outputs"].append(o)
logging.error("Output will be ignored")
+ has_dependency_cycle = any(
+ reason["type"] == "dependency_cycle"
+ for valid, reasons, _ in validated.values()
+ for reason in reasons
+ )
+ if not has_dependency_cycle:
+ try:
+ validate_loops(prompt, outputs, validated, start_nodes, end_nodes)
+ except LoopValidationError as ex:
+ dependent_outputs = ex.error["extra_info"]["output_ids"]
+ for node_id in ex.error["extra_info"]["node_ids"]:
+ if node_id not in node_errors:
+ node_errors[node_id] = {
+ "errors": [],
+ "dependent_outputs": [],
+ "class_type": prompt[node_id]["class_type"],
+ }
+ node_errors[node_id]["errors"].append(ex.error)
+ node_errors[node_id]["dependent_outputs"] = sorted(
+ set(node_errors[node_id]["dependent_outputs"]).union(dependent_outputs)
+ )
+ for output_id in dependent_outputs:
+ good_outputs.discard(output_id)
+ errors.append((dependent_outputs[0], [ex.error]))
+
if len(good_outputs) == 0:
errors_list = []
for o, errors in errors:
diff --git a/nodes.py b/nodes.py
index c1e6d5335..1728899fe 100644
--- a/nodes.py
+++ b/nodes.py
@@ -2539,6 +2539,7 @@ async def init_builtin_extra_nodes():
"nodes_depth_anything_3.py",
"nodes_seed.py",
"nodes_text.py",
+ "nodes_loop.py",
"nodes_sam3d_body.py",
"nodes_marigold.py",
]
diff --git a/tests-unit/comfy_extras_test/nodes_loop_test.py b/tests-unit/comfy_extras_test/nodes_loop_test.py
new file mode 100644
index 000000000..5d9d83f5e
--- /dev/null
+++ b/tests-unit/comfy_extras_test/nodes_loop_test.py
@@ -0,0 +1,67 @@
+import math
+from types import SimpleNamespace
+
+from comfy_api.latest import io
+from comfy_extras.nodes_loop import EndLoop, LoopIteration, LoopProgress, LoopResult, StartLoop
+
+
+def test_loop_schema_exposes_cache_policy_and_integrated_carry():
+ inputs = StartLoop.INPUT_TYPES()
+
+ assert inputs["required"]["cache_iterations"][1]["default"] is False
+ assert inputs["required"]["cache_iterations"][1]["advanced"] is True
+ assert list(inputs["optional"]) == ["parent_iteration", "initial_iteration_value"]
+ assert StartLoop.RETURN_NAMES[:5] == [
+ "iteration_index",
+ "is_first",
+ "is_last",
+ "list_item",
+ "current_iteration_value",
+ ]
+ assert len(StartLoop.RETURN_NAMES) == 5
+ assert "_loop_result" not in EndLoop.INPUT_TYPES().get("optional", {})
+
+
+def test_iteration_cache_policy_is_stable_or_unique():
+ assert math.isnan(StartLoop.fingerprint_inputs(False))
+ assert math.isnan(StartLoop.fingerprint_inputs([False]))
+ assert math.isnan(StartLoop.fingerprint_inputs(True))
+ assert math.isnan(StartLoop.fingerprint_inputs([True]))
+ assert math.isnan(LoopIteration.fingerprint_inputs(False))
+ assert math.isnan(LoopIteration.fingerprint_inputs([False]))
+ assert LoopIteration.fingerprint_inputs(True) is None
+ assert LoopIteration.fingerprint_inputs([True]) is None
+ assert math.isnan(LoopProgress.fingerprint_inputs())
+
+
+def test_loop_progress_reports_on_start_node(monkeypatch):
+ updates = []
+ monkeypatch.setattr(
+ "comfy_extras.nodes_loop.PromptServer",
+ SimpleNamespace(instance=SimpleNamespace(send_progress_text=lambda *args: updates.append(args))),
+ )
+
+ assert LoopProgress.execute(["start"], [2], [4]).result == (2,)
+ assert updates == [("Iteration 2 / 4", "start")]
+
+
+def test_loop_result_passes_iteration_outputs_to_end_loop():
+ unblocked = []
+ result = {}
+ def release(node_id, outputs):
+ assert node_id == "close"
+ result["close"] = outputs
+ unblocked.append(True)
+ execution_list = SimpleNamespace(
+ release_external_block=release,
+ get_external_block_result=lambda node_id: result.get(node_id),
+ )
+ result_node = LoopResult.PREPARE_CLASS_CLONE({"hidden_inputs": {io.Hidden.execution_list: execution_list}})
+ end_node = EndLoop.PREPARE_CLASS_CLONE(
+ {"hidden_inputs": {io.Hidden.execution_list: execution_list, io.Hidden.unique_id: "close"}}
+ )
+
+ result_node.execute(["close"], output0=[1, "a"], output1=[2, "b"])
+
+ assert unblocked == [True]
+ assert end_node.execute([True]).result == ([1, "a", 2, "b"],)
diff --git a/tests-unit/comfy_extras_test/nodes_toolkit_test.py b/tests-unit/comfy_extras_test/nodes_toolkit_test.py
new file mode 100644
index 000000000..8ce464f3a
--- /dev/null
+++ b/tests-unit/comfy_extras_test/nodes_toolkit_test.py
@@ -0,0 +1,20 @@
+from comfy_extras.nodes_toolkit import CreateList, GetItemFromList
+
+
+def test_create_list_accepts_heterogeneous_inputs():
+ inputs = CreateList.INPUT_TYPES()
+
+ assert inputs["required"]["inputs"][1]["template"]["input"] == {
+ "required": {"input": ("*", {})}
+ }
+ assert CreateList.RETURN_TYPES == ["*"]
+ assert CreateList.OUTPUT_IS_LIST == [True]
+ assert CreateList.execute({"input0": ["text"], "input1": [42]}).result == (["text", 42],)
+
+
+def test_get_item_from_list_uses_integer_index():
+ assert GetItemFromList.OUTPUT_IS_LIST == [False]
+ assert GetItemFromList.execute(["text", 42], [1]).result == (42,)
+ assert GetItemFromList.execute(
+ [["image 1", "image 2"], ["text 1", "text 2"]], [0]
+ ).result == (["image 1", "image 2"],)
diff --git a/tests-unit/execution_test/loop_validation_test.py b/tests-unit/execution_test/loop_validation_test.py
new file mode 100644
index 000000000..9a1e4ce4f
--- /dev/null
+++ b/tests-unit/execution_test/loop_validation_test.py
@@ -0,0 +1,454 @@
+import asyncio
+
+import pytest
+
+import nodes
+from comfy_execution.validation import LoopValidationError, validate_loops
+from comfy_extras.nodes_loop import EndLoop, StartLoop
+from execution import validate_prompt
+
+
+def node(class_type, **inputs):
+ return {"class_type": class_type, "inputs": inputs}
+
+
+def validate(prompt, *outputs):
+ starts = {node_id for node_id, value in prompt.items() if value["class_type"] == "StartLoop"}
+ ends = {node_id for node_id, value in prompt.items() if value["class_type"] == "EndLoop"}
+ return validate_loops(prompt, set(outputs) or {"output"}, prompt, starts, ends)
+
+
+def test_pairs_simple_loop():
+ prompt = {
+ "start": node("StartLoop"),
+ "body": node("Body", value=["start", 0]),
+ "end": node("EndLoop", value=["body", 0]),
+ "output": node("Output", value=["end", 0]),
+ }
+
+ assert validate(prompt) == {"start": "end"}
+
+
+def test_accepts_branched_body_when_every_branch_reaches_end():
+ prompt = {
+ "start": node("StartLoop"),
+ "left": node("Body", value=["start", 0]),
+ "right": node("Body", value=["start", 0]),
+ "end": node("EndLoop", left=["left", 0], right=["right", 0]),
+ "output": node("Output", value=["end", 0]),
+ }
+
+ assert validate(prompt) == {"start": "end"}
+
+
+def test_accepts_dependencies_entering_loop_body():
+ prompt = {
+ "source": node("Source"),
+ "start": node("StartLoop"),
+ "body": node("Body", iteration=["start", 0], value=["source", 0]),
+ "end": node("EndLoop", value=["body", 0]),
+ "output": node("Output", value=["end", 0]),
+ }
+
+ assert validate(prompt) == {"start": "end"}
+
+
+def test_accepts_accumulate_control_from_outside_loop():
+ prompt = {
+ "control": node("Source"),
+ "start": node("StartLoop"),
+ "body": node("Body", value=["start", 0]),
+ "end": node("EndLoop", value=["body", 0], accumulate=["control", 0]),
+ "output": node("Output", value=["end", 0]),
+ }
+
+ assert validate(prompt) == {"start": "end"}
+
+
+def test_pairs_nested_loops_with_outer_value_entering_inner_body():
+ prompt = {
+ "outer": node("StartLoop"),
+ "inner": node("StartLoop", parent=["outer", 0]),
+ "inner_body": node("Body", outer=["outer", 0], inner=["inner", 0]),
+ "inner_end": node("EndLoop", value=["inner_body", 0]),
+ "outer_body": node("Body", outer=["outer", 0], inner=["inner_end", 0]),
+ "outer_end": node("EndLoop", value=["outer_body", 0]),
+ "output": node("Output", value=["outer_end", 0]),
+ }
+
+ assert validate(prompt) == {"inner": "inner_end", "outer": "outer_end"}
+
+
+def test_pairs_sequential_inner_loops():
+ prompt = {
+ "outer": node("StartLoop"),
+ "first": node("StartLoop", parent=["outer", 0]),
+ "first_body": node("Body", value=["first", 0]),
+ "first_end": node("EndLoop", value=["first_body", 0]),
+ "second": node("StartLoop", value=["first_end", 0]),
+ "second_body": node("Body", outer=["outer", 0], value=["second", 0]),
+ "second_end": node("EndLoop", value=["second_body", 0]),
+ "outer_end": node("EndLoop", value=["second_end", 0]),
+ "output": node("Output", value=["outer_end", 0]),
+ }
+
+ assert validate(prompt) == {
+ "first": "first_end",
+ "second": "second_end",
+ "outer": "outer_end",
+ }
+
+
+def test_pairs_independent_loops():
+ prompt = {
+ "left": node("StartLoop"),
+ "left_end": node("EndLoop", value=["left", 0]),
+ "left_output": node("Output", value=["left_end", 0]),
+ "right": node("StartLoop"),
+ "right_end": node("EndLoop", value=["right", 0]),
+ "right_output": node("Output", value=["right_end", 0]),
+ }
+
+ assert validate(prompt, "left_output", "right_output") == {
+ "left": "left_end",
+ "right": "right_end",
+ }
+
+
+def test_ignores_boundaries_outside_selected_outputs():
+ prompt = {
+ "start": node("StartLoop"),
+ "end": node("EndLoop", value=["start", 0]),
+ "output": node("Output", value=["end", 0]),
+ "unused_start": node("StartLoop"),
+ }
+
+ assert validate_loops(
+ prompt,
+ {"output"},
+ {"start", "end", "output"},
+ {"start", "unused_start"},
+ {"end"},
+ ) == {"start": "end"}
+
+
+def test_rejects_end_without_start():
+ prompt = {
+ "source": node("Source"),
+ "end": node("EndLoop", value=["source", 0]),
+ "output": node("Output", value=["end", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt)
+
+ assert exc.value.error["type"] == "custom_validation_failed"
+ assert exc.value.error["extra_info"]["input_name"] == "loop boundary"
+ assert exc.value.error["extra_info"]["loop_error_type"] == "loop_end_without_start"
+ assert exc.value.error["extra_info"]["node_ids"] == ["end"]
+
+
+def test_rejects_start_without_end():
+ prompt = {
+ "start": node("StartLoop"),
+ "output": node("Output", value=["start", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt)
+
+ assert exc.value.error["type"] == "custom_validation_failed"
+ assert exc.value.error["extra_info"]["loop_error_type"] == "loop_start_without_end"
+ assert exc.value.error["extra_info"]["node_ids"] == ["start"]
+
+
+def test_rejects_all_unpaired_starts_together():
+ prompt = {
+ "first": node("StartLoop"),
+ "second": node("StartLoop"),
+ "output": node("Output", first=["first", 0], second=["second", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt)
+
+ assert exc.value.error["extra_info"]["loop_error_type"] == "loop_start_without_end"
+ assert exc.value.error["extra_info"]["node_ids"] == ["first", "second"]
+
+
+def test_rejects_ambiguous_unrelated_starts():
+ prompt = {
+ "left": node("StartLoop"),
+ "right": node("StartLoop"),
+ "body": node("Body", left=["left", 0], right=["right", 0]),
+ "end": node("EndLoop", value=["body", 0]),
+ "output": node("Output", value=["end", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt)
+
+ assert exc.value.error["extra_info"]["loop_error_type"] == "ambiguous_loop_nesting"
+ assert exc.value.error["extra_info"]["node_ids"] == ["end", "left", "right"]
+ assert exc.value.error["details"] == "End Loop end can close multiple unrelated Start Loops: left, right"
+
+
+def test_rejects_second_end_reached_before_pair():
+ prompt = {
+ "start": node("StartLoop"),
+ "body": node("Body", value=["start", 0]),
+ "end_a": node("EndLoop", value=["body", 0]),
+ "end_b": node("EndLoop", value=["body", 0]),
+ "output_a": node("Output", value=["end_a", 0]),
+ "output_b": node("Output", value=["end_b", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt, "output_a", "output_b")
+
+ assert exc.value.error["extra_info"]["loop_error_type"] == "loop_escape"
+ assert exc.value.error["extra_info"]["node_ids"] == ["end_a", "end_b", "start"]
+
+
+def test_rejects_output_route_around_end():
+ prompt = {
+ "start": node("StartLoop"),
+ "body": node("Body", value=["start", 0]),
+ "end": node("EndLoop", value=["body", 0]),
+ "output": node("Output", closed=["end", 0], bypass=["body", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt)
+
+ assert exc.value.error["extra_info"]["loop_error_type"] == "loop_escape"
+ assert exc.value.error["extra_info"]["node_ids"] == ["end", "output", "start"]
+
+
+def test_rejects_inner_loop_route_to_unpaired_outer_end():
+ prompt = {
+ "outer": node("StartLoop"),
+ "inner": node("StartLoop", parent=["outer", 0]),
+ "body": node("Body", value=["inner", 0]),
+ "inner_end": node("EndLoop", value=["body", 0]),
+ "outer_end": node("EndLoop", closed=["inner_end", 0], bypass=["body", 0]),
+ "output": node("Output", value=["outer_end", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt)
+
+ assert exc.value.error["extra_info"]["loop_error_type"] == "loop_escape"
+ assert exc.value.error["extra_info"]["node_ids"] == ["inner", "inner_end", "outer_end"]
+
+
+def test_rejects_end_after_start_was_already_paired():
+ prompt = {
+ "start": node("StartLoop"),
+ "first_end": node("EndLoop", value=["start", 0]),
+ "second_end": node("EndLoop", value=["first_end", 0]),
+ "output": node("Output", value=["second_end", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt)
+
+ assert exc.value.error["extra_info"]["loop_error_type"] == "loop_end_without_start"
+ assert exc.value.error["extra_info"]["node_ids"] == ["second_end"]
+
+
+def test_rejects_accumulate_control_from_loop_body():
+ prompt = {
+ "start": node("StartLoop"),
+ "body": node("Body", value=["start", 0]),
+ "control": node("Body", value=["body", 0]),
+ "end": node("EndLoop", value=["body", 0], accumulate=["control", 0]),
+ "output": node("Output", value=["end", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt)
+
+ assert exc.value.error["extra_info"]["loop_error_type"] == "loop_accumulate_from_body"
+ assert exc.value.error["extra_info"]["node_ids"] == ["control", "end", "start"]
+ assert exc.value.error["details"] == (
+ "End Loop end accumulate is driven by loop node control under Start Loop start"
+ )
+
+
+def test_rejects_accumulate_control_directly_from_start():
+ prompt = {
+ "start": node("StartLoop"),
+ "end": node("EndLoop", value=["start", 0], accumulate=["start", 1]),
+ "output": node("Output", value=["end", 0]),
+ }
+
+ with pytest.raises(LoopValidationError) as exc:
+ validate(prompt)
+
+ assert exc.value.error["extra_info"]["loop_error_type"] == "loop_accumulate_from_body"
+ assert exc.value.error["extra_info"]["node_ids"] == ["end", "start"]
+
+
+class Body:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"left": ("*",), "right": ("*",)}}
+
+ RETURN_TYPES = ("*",)
+
+
+class Output:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("*",)}}
+
+ RETURN_TYPES = ()
+ OUTPUT_NODE = True
+
+
+class InvalidOutput:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("*",), "label": ("STRING",)}}
+
+ RETURN_TYPES = ()
+ OUTPUT_NODE = True
+
+
+class Source:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {}}
+
+ RETURN_TYPES = ("*",)
+
+
+def test_prompt_validation_includes_end_after_terminated_output(monkeypatch):
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "StartLoop", StartLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "EndLoop", EndLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Body", Body)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Output", Output)
+ prompt = {
+ "start": node("StartLoop", cache_iterations=False),
+ "body": node("Body", left=["start", 0], right=["start", 0]),
+ "carry": node("Body", left=["body", 0], right=["start", 0]),
+ "output": node("Output", value=["body", 0]),
+ "end": node(
+ "EndLoop",
+ output_value=["body", 0],
+ next_iteration_value=["carry", 0],
+ termination0=["output", 0],
+ accumulate=False,
+ ),
+ }
+
+ valid, error, good_outputs, node_errors = asyncio.run(validate_prompt("prompt", prompt, None))
+
+ assert valid
+ assert error is None
+ assert good_outputs == ["output"]
+ assert node_errors == {}
+ assert prompt["start"]["_loop_end"] == "end"
+ assert "carry" in prompt["start"]["_loop_body"]
+
+
+def test_prompt_validation_reports_every_ambiguous_boundary(monkeypatch):
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "StartLoop", StartLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "EndLoop", EndLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Body", Body)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Output", Output)
+ prompt = {
+ "left": node("StartLoop", cache_iterations=False),
+ "right": node("StartLoop", cache_iterations=False),
+ "body": node("Body", left=["left", 0], right=["right", 0]),
+ "end": node("EndLoop", output_value=["body", 0], accumulate=False),
+ "output": node("Output", value=["end", 0]),
+ }
+
+ valid, error, good_outputs, node_errors = asyncio.run(validate_prompt("prompt", prompt, None))
+
+ assert not valid
+ assert error["details"] == (
+ "End Loop has ambiguous Start Loops: "
+ "End Loop end can close multiple unrelated Start Loops: left, right"
+ )
+ assert good_outputs == []
+ assert set(node_errors) == {"left", "right", "end"}
+ assert all(
+ value["errors"][0]["extra_info"]["node_ids"] == ["end", "left", "right"]
+ for value in node_errors.values()
+ )
+
+
+def test_prompt_validation_stacks_loop_and_input_errors(monkeypatch):
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "StartLoop", StartLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "EndLoop", EndLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Body", Body)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "InvalidOutput", InvalidOutput)
+ prompt = {
+ "left": node("StartLoop", cache_iterations=False),
+ "right": node("StartLoop", cache_iterations=False),
+ "body": node("Body", left=["left", 0], right=["right", 0]),
+ "end": node("EndLoop", output_value=["body", 0], accumulate=False),
+ "output": node("InvalidOutput", value=["end", 0]),
+ }
+
+ valid, error, good_outputs, node_errors = asyncio.run(validate_prompt("prompt", prompt, None))
+
+ assert not valid
+ assert good_outputs == []
+ assert {reason["type"] for reason in node_errors["output"]["errors"]} == {"required_input_missing"}
+ assert node_errors["end"]["errors"][0]["type"] == "custom_validation_failed"
+ assert node_errors["end"]["errors"][0]["extra_info"]["loop_error_type"] == "ambiguous_loop_nesting"
+ assert "Required input is missing" in error["details"]
+ assert "End Loop has ambiguous Start Loops" in error["details"]
+
+
+def test_prompt_validation_reports_loop_escape_as_recognized_node_error(monkeypatch):
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "StartLoop", StartLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "EndLoop", EndLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Body", Body)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Output", Output)
+ prompt = {
+ "start": node("StartLoop", cache_iterations=False),
+ "body": node("Body", left=["start", 0], right=["start", 0]),
+ "end": node("EndLoop", output_value=["body", 0], accumulate=False),
+ "output": node("Output", value=["end", 0], bypass=["body", 0]),
+ }
+
+ valid, error, good_outputs, node_errors = asyncio.run(validate_prompt("prompt", prompt, None))
+
+ assert not valid
+ assert good_outputs == []
+ assert error["details"].count("Loop body is not closed") == 1
+ for node_id in ("start", "end", "output"):
+ node_error = node_errors[node_id]["errors"][0]
+ assert node_error["type"] == "custom_validation_failed"
+ assert node_error["extra_info"]["input_name"] == "loop boundary"
+ assert node_error["extra_info"]["loop_error_type"] == "loop_escape"
+
+
+def test_loop_error_does_not_reject_independent_output(monkeypatch):
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "StartLoop", StartLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "EndLoop", EndLoop)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Body", Body)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Output", Output)
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "Source", Source)
+ prompt = {
+ "left": node("StartLoop", cache_iterations=False),
+ "right": node("StartLoop", cache_iterations=False),
+ "body": node("Body", left=["left", 0], right=["right", 0]),
+ "end": node("EndLoop", output_value=["body", 0], accumulate=False),
+ "loop_output": node("Output", value=["end", 0]),
+ "source": node("Source"),
+ "independent_output": node("Output", value=["source", 0]),
+ }
+
+ valid, error, good_outputs, node_errors = asyncio.run(validate_prompt("prompt", prompt, None))
+
+ assert valid
+ assert error is None
+ assert good_outputs == ["independent_output"]
+ assert set(node_errors) == {"left", "right", "end"}
+ assert all(value["dependent_outputs"] == ["loop_output"] for value in node_errors.values())
diff --git a/tests-unit/execution_test/test_execution_list.py b/tests-unit/execution_test/test_execution_list.py
new file mode 100644
index 000000000..c8ba4b3d5
--- /dev/null
+++ b/tests-unit/execution_test/test_execution_list.py
@@ -0,0 +1,106 @@
+import asyncio
+
+import pytest
+
+from comfy_execution.graph import DynamicPrompt, ExecutionList
+
+
+def test_dynamic_prompt_can_override_ephemeral_node_without_mutating_it():
+ original = {"node": {"class_type": "Original", "inputs": {"value": 1}}}
+ prompt = DynamicPrompt(original)
+ prompt.add_ephemeral_node("child", {"class_type": "Child", "inputs": {"value": 2}}, "node", "child")
+
+ prompt.override_node("child", {"class_type": "Child", "inputs": {"value": 3}})
+
+ assert prompt.get_node("child")["inputs"] == {"value": 3}
+ assert prompt.ephemeral_prompt["child"]["inputs"] == {"value": 2}
+
+
+def execution_list():
+ result = ExecutionList.__new__(ExecutionList)
+ result.staged_node_id = "start"
+ result.pendingNodes = {node_id: True for node_id in ("start", "first", "second", "end")}
+ result.blockCount = {"start": 0, "first": 1, "second": 1, "end": 2}
+ result.blocking = {
+ "start": {"first": {0: True}},
+ "first": {"second": {0: True}, "end": {0: True}},
+ "second": {"end": {0: True}},
+ "end": {},
+ }
+ result.execution_cache = {node_id: {} for node_id in result.pendingNodes}
+ result.execution_cache_listeners = {node_id: set() for node_id in result.pendingNodes}
+ result.execution_cache_listeners["start"] = {("first", 0), ("end", 0)}
+ result.externalBlocks = 0
+ result.externalBlockResults = {}
+ result.unblockedEvent = asyncio.Event()
+ return result
+
+
+def test_inhibit_nodes_removes_body_and_releases_downstream_node():
+ graph = execution_list()
+
+ graph.inhibit_nodes({"first", "second"})
+
+ assert graph.pendingNodes == {"start": True, "end": True}
+ assert graph.blockCount == {"start": 0, "end": 0}
+ assert graph.blocking == {"start": {}, "end": {}}
+ assert set(graph.execution_cache) == {"start", "end"}
+ assert set(graph.execution_cache_listeners) == {"start", "end"}
+ assert graph.execution_cache_listeners["start"] == {("end", 0)}
+
+
+def test_inhibit_nodes_ignores_nodes_which_are_not_pending():
+ graph = execution_list()
+
+ graph.inhibit_nodes({"missing"})
+
+ assert set(graph.pendingNodes) == {"start", "first", "second", "end"}
+ assert graph.blockCount["end"] == 2
+
+
+def test_inhibit_nodes_requires_staged_control_node():
+ graph = execution_list()
+ graph.staged_node_id = None
+
+ with pytest.raises(AssertionError, match="while a control node is staged"):
+ graph.inhibit_nodes({"first"})
+
+
+def test_control_node_cannot_inhibit_itself():
+ graph = execution_list()
+
+ with pytest.raises(AssertionError, match="cannot inhibit itself"):
+ graph.inhibit_nodes({"start"})
+
+
+def test_staged_node_reports_dependencies_added_during_lazy_status():
+ graph = execution_list()
+
+ assert not graph.is_staged_node_blocked()
+ graph.blockCount["start"] = 1
+
+ assert graph.is_staged_node_blocked()
+
+
+def test_external_block_carries_a_result_to_its_node():
+ graph = execution_list()
+
+ block = graph.add_external_block("end")
+ block([1, 2])
+
+ assert graph.get_external_block_result("end") == [1, 2]
+ assert graph.externalBlocks == 0
+ assert graph.blockCount["end"] == 2
+
+
+def test_multiple_external_blocks_can_be_released():
+ graph = execution_list()
+
+ first = graph.add_external_block("end")
+ second = graph.add_external_block("end")
+
+ first()
+ second()
+ assert graph.get_external_block_result("end") is None
+ assert graph.externalBlocks == 0
+ assert graph.blockCount["end"] == 2
diff --git a/tests-unit/execution_test/test_nested_loop_execution.py b/tests-unit/execution_test/test_nested_loop_execution.py
new file mode 100644
index 000000000..1fb45a817
--- /dev/null
+++ b/tests-unit/execution_test/test_nested_loop_execution.py
@@ -0,0 +1,800 @@
+import copy
+
+import pytest
+
+import nodes
+
+import comfy_extras.nodes_loop as nodes_loop
+from comfy_api.latest import io
+from comfy_execution.graph_utils import GraphBuilder
+from comfy_execution.validation import validate_loops
+from execution import PromptExecutor
+
+
+class Constant:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("INT",)}}
+
+ RETURN_TYPES = ("INT",)
+ FUNCTION = "execute"
+
+ def execute(self, value):
+ return (value,)
+
+
+class Increment:
+ calls = []
+
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("INT",)}}
+
+ RETURN_TYPES = ("INT",)
+ FUNCTION = "execute"
+
+ def execute(self, value):
+ value += 1
+ self.calls.append(value)
+ return (value,)
+
+
+class ExpandIncrement:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("INT",)}}
+
+ RETURN_TYPES = ("INT",)
+ FUNCTION = "execute"
+
+ def execute(self, value):
+ graph = GraphBuilder()
+ increment = graph.node("TestIncrement", "increment", value=value)
+ return {"result": (increment.out(0),), "expand": graph.finalize()}
+
+
+class FalseBranch:
+ calls = []
+
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("INT",)}}
+
+ RETURN_TYPES = ("INT",)
+ FUNCTION = "execute"
+
+ def execute(self, value):
+ self.calls.append(value)
+ return (value,)
+
+
+class TrueBranch(FalseBranch):
+ calls = []
+
+
+class LazySwitch:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {
+ "required": {
+ "switch": ("BOOLEAN",),
+ "on_false": ("INT", {"lazy": True}),
+ "on_true": ("INT", {"lazy": True}),
+ }
+ }
+
+ RETURN_TYPES = ("INT",)
+ FUNCTION = "execute"
+
+ def check_lazy_status(self, switch, on_false=None, on_true=None):
+ selected_name = "on_true" if switch else "on_false"
+ selected = on_true if switch else on_false
+ return [selected_name] if selected is None else []
+
+ def execute(self, switch, on_false=None, on_true=None):
+ return (on_true if switch else on_false,)
+
+
+class Capture:
+ values = []
+
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("INT",)}}
+
+ RETURN_TYPES = ()
+ FUNCTION = "execute"
+ OUTPUT_NODE = True
+
+ def execute(self, value):
+ self.values.append(value)
+ return ()
+
+
+class CapturePassthrough:
+ values = []
+
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("INT",)}}
+
+ RETURN_TYPES = ("INT",)
+ FUNCTION = "execute"
+ OUTPUT_NODE = True
+
+ def execute(self, value):
+ self.values.append(value)
+ return (value,)
+
+
+class CapturePassthroughFirst(CapturePassthrough):
+ values = []
+
+
+class CapturePassthroughSecond(io.ComfyNode):
+ values = []
+
+ @classmethod
+ def define_schema(cls):
+ return io.Schema(
+ node_id="TestCapturePassthroughSecond",
+ inputs=[io.Int.Input("value"), io.Boolean.Input("last")],
+ outputs=[io.Int.Output()],
+ hidden=[io.Hidden.dynprompt, io.Hidden.unique_id],
+ is_output_node=True,
+ )
+
+ @classmethod
+ def execute(cls, value, last):
+ cls.values.append((value, last))
+ return io.NodeOutput(value)
+
+ @classmethod
+ def fingerprint_inputs(cls, **kwargs):
+ return float("NaN")
+
+
+class Pair:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("INT",)}}
+
+ RETURN_TYPES = ("*",)
+ OUTPUT_IS_LIST = (True,)
+ FUNCTION = "execute"
+
+ def execute(self, value):
+ return ([value, str(value)],)
+
+
+class ListBackedScalar:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("INT",)}}
+
+ RETURN_TYPES = ("*",)
+ FUNCTION = "execute"
+
+ def execute(self, value):
+ return ([[value]],)
+
+
+class AppendIndex:
+ values = []
+
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {"value": ("*",), "index": ("INT",)}}
+
+ RETURN_TYPES = ("*",)
+ FUNCTION = "execute"
+
+ def execute(self, value, index):
+ value = value + [index]
+ self.values.append(value)
+ return (value,)
+
+
+class EmptyList:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {}}
+
+ RETURN_TYPES = ("*",)
+ OUTPUT_IS_LIST = (True,)
+ FUNCTION = "execute"
+
+ def execute(self):
+ return ([],)
+
+
+class IntegerList:
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {"required": {}}
+
+ RETURN_TYPES = ("INT",)
+ OUTPUT_IS_LIST = (True,)
+ FUNCTION = "execute"
+
+ def execute(self):
+ return ([10, 20],)
+
+
+class CaptureLoopState:
+ values = []
+
+ @classmethod
+ def INPUT_TYPES(cls):
+ return {
+ "required": {
+ "index": ("INT",),
+ "is_first": ("BOOLEAN",),
+ "is_last": ("BOOLEAN",),
+ "item": ("*",),
+ }
+ }
+
+ RETURN_TYPES = ("INT",)
+ FUNCTION = "execute"
+
+ def execute(self, index, is_first, is_last, item):
+ self.values.append((index, is_first, is_last, item))
+ return (index,)
+
+
+class CaptureLoopResult(nodes_loop.LoopResult):
+ output_keys = []
+
+ @classmethod
+ def execute(cls, **kwargs):
+ cls.output_keys.extend(sorted(name for name in kwargs if name.startswith("output")))
+ return super().execute(**kwargs)
+
+
+class Server:
+ client_id = None
+
+ def send_sync(self, *args, **kwargs):
+ pass
+
+
+class Progress:
+ messages = []
+ body_call_counts = []
+
+ def send_progress_text(self, text, node_id):
+ self.messages.append((text, node_id))
+ self.body_call_counts.append(len(Increment.calls))
+
+
[email protected](autouse=True)
+def register_internal_loop_nodes(monkeypatch):
+ classes = {
+ "StartLoop": nodes_loop.StartLoop,
+ "EndLoop": nodes_loop.EndLoop,
+ "LoopIteration": nodes_loop.LoopIteration,
+ "LoopProgress": nodes_loop.LoopProgress,
+ "LoopResult": nodes_loop.LoopResult,
+ "TestConstant": Constant,
+ "TestIncrement": Increment,
+ "TestExpandIncrement": ExpandIncrement,
+ "TestFalseBranch": FalseBranch,
+ "TestTrueBranch": TrueBranch,
+ "TestLazySwitch": LazySwitch,
+ "TestCapture": Capture,
+ "TestCapturePassthrough": CapturePassthrough,
+ "TestCapturePassthroughFirst": CapturePassthroughFirst,
+ "TestCapturePassthroughSecond": CapturePassthroughSecond,
+ "TestPair": Pair,
+ "TestListBackedScalar": ListBackedScalar,
+ "TestAppendIndex": AppendIndex,
+ "TestEmptyList": EmptyList,
+ "TestIntegerList": IntegerList,
+ "TestCaptureLoopState": CaptureLoopState,
+ }
+ for name, node in classes.items():
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, name, node)
+ monkeypatch.setattr(
+ nodes_loop,
+ "PromptServer",
+ type("PromptServer", (), {"instance": Progress()}),
+ )
+ execute = PromptExecutor.execute
+
+ def execute_validated(executor, prompt, prompt_id, extra_data=None, execute_outputs=None):
+ extra_data = extra_data or {}
+ execute_outputs = execute_outputs or []
+ starts = {node_id for node_id, node in prompt.items() if node["class_type"] == "StartLoop"}
+ ends = {node_id for node_id, node in prompt.items() if node["class_type"] == "EndLoop"}
+ validate_loops(prompt, set(execute_outputs), prompt, starts, ends)
+ execute(executor, prompt, prompt_id, extra_data, execute_outputs)
+
+ monkeypatch.setattr(PromptExecutor, "execute", execute_validated)
+
+
+def execute_prompt(prompt, prompt_id, outputs):
+ executor = PromptExecutor(Server(), cache_type=False, cache_args={"ram": 0, "ram_inactive": 0})
+ executor.execute(prompt, prompt_id, execute_outputs=outputs)
+ assert executor.success
+ return executor
+
+
+def test_nested_loops_execute_each_body_once_without_final_requeue():
+ Increment.calls = []
+ Capture.values = []
+
+ prompt = {
+ "constant": {
+ "class_type": "TestConstant",
+ "inputs": {"value": 0},
+ },
+ "outer": {
+ "class_type": "StartLoop",
+ "inputs": {
+ "mode": "simple",
+ "mode.num_iterations": 2,
+ "initial_iteration_value": ["constant", 0],
+ },
+ },
+ "inner": {
+ "class_type": "StartLoop",
+ "inputs": {
+ "mode": "simple",
+ "mode.num_iterations": 2,
+ "parent_iteration": ["outer", 0],
+ "initial_iteration_value": ["outer", 4],
+ },
+ },
+ "increment": {
+ "class_type": "TestIncrement",
+ "inputs": {"value": ["inner", 4]},
+ },
+ "inner_close": {
+ "class_type": "EndLoop",
+ "inputs": {
+ "output_value": ["increment", 0],
+ "next_iteration_value": ["increment", 0],
+ "accumulate": False,
+ },
+ },
+ "outer_close": {
+ "class_type": "EndLoop",
+ "inputs": {
+ "output_value": ["inner_close", 0],
+ "next_iteration_value": ["inner_close", 0],
+ "accumulate": False,
+ },
+ },
+ "capture": {
+ "class_type": "TestCapture",
+ "inputs": {"value": ["outer_close", 0]},
+ },
+ }
+ execute_prompt(prompt, "nested-loop-test", ["capture"])
+ assert Increment.calls == [1, 2, 3, 4]
+ assert Capture.values == [4]
+
+
+def test_loop_executes_termination_without_carried_or_output_value():
+ Increment.calls = []
+ CapturePassthrough.values = []
+
+ prompt = {
+ "loop": {
+ "class_type": "StartLoop",
+ "inputs": {
+ "mode": "simple",
+ "mode.num_iterations": 2,
+ },
+ },
+ "increment": {
+ "class_type": "TestIncrement",
+ "inputs": {"value": ["loop", 0]},
+ },
+ "preview": {
+ "class_type": "TestCapturePassthrough",
+ "inputs": {"value": ["increment", 0]},
+ },
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {
+ "accumulate": False,
+ "termination0": ["preview", 0],
+ },
+ },
+ }
+ execute_prompt(prompt, "termination-only-loop-test", ["preview"])
+ assert Increment.calls == [1, 2]
+ assert CapturePassthrough.values == [1, 2]
+
+
+def test_loop_executes_multiple_termination_branches_each_iteration():
+ Increment.calls = []
+ CapturePassthroughFirst.values = []
+ CapturePassthroughSecond.values = []
+ prompt = {
+ "initial": {"class_type": "TestConstant", "inputs": {"value": 0}},
+ "loop": {
+ "class_type": "StartLoop",
+ "inputs": {
+ "mode": "simple",
+ "mode.num_iterations": 2,
+ "initial_iteration_value": ["initial", 0],
+ },
+ },
+ "increment": {"class_type": "TestIncrement", "inputs": {"value": ["loop", 4]}},
+ "first": {
+ "class_type": "TestCapturePassthroughFirst",
+ "inputs": {"value": ["increment", 0]},
+ },
+ "second": {
+ "class_type": "TestCapturePassthroughSecond",
+ "inputs": {"value": ["increment", 0], "last": ["loop", 2]},
+ },
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {
+ "output_value": ["increment", 0],
+ "next_iteration_value": ["increment", 0],
+ "accumulate": False,
+ "termination0": ["first", 0],
+ "termination1": ["second", 0],
+ },
+ },
+ }
+
+ executor = execute_prompt(prompt, "multiple-termination-loop-test", ["first", "second"])
+
+ assert executor.success
+ assert Increment.calls == [1, 2]
+ assert CapturePassthroughFirst.values == [1, 2]
+ assert CapturePassthroughSecond.values == [(1, False), (2, True)]
+
+
+def test_loop_executes_final_carried_value_without_output():
+ Increment.calls = []
+ prompt = {
+ "loop": {
+ "class_type": "StartLoop",
+ "inputs": {"mode": "simple", "mode.num_iterations": 2},
+ },
+ "increment": {"class_type": "TestIncrement", "inputs": {"value": ["loop", 0]}},
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {"next_iteration_value": ["increment", 0], "accumulate": False},
+ },
+ }
+ execute_prompt(prompt, "carry-only-loop-test", ["close"])
+ assert Increment.calls == [1, 2]
+
+
+def test_loop_preserves_list_backed_carried_value():
+ AppendIndex.values = []
+ prompt = {
+ "initial": {"class_type": "TestListBackedScalar", "inputs": {"value": 7}},
+ "loop": {
+ "class_type": "StartLoop",
+ "inputs": {
+ "mode": "simple",
+ "mode.num_iterations": 2,
+ "initial_iteration_value": ["initial", 0],
+ },
+ },
+ "append": {
+ "class_type": "TestAppendIndex",
+ "inputs": {"value": ["loop", 4], "index": ["loop", 0]},
+ },
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {
+ "output_value": ["append", 0],
+ "next_iteration_value": ["append", 0],
+ "accumulate": False,
+ },
+ },
+ }
+ execute_prompt(prompt, "list-carry-loop-test", ["close"])
+ assert AppendIndex.values == [[[7], 0], [[7], 0, 1]]
+
+
+ "mode_inputs",
+ [
+ {"mode": "simple", "mode.num_iterations": 0},
+ {"mode": "List", "mode.list": ["empty_list", 0]},
+ ],
+)
+def test_empty_loop_skips_body(mode_inputs):
+ Increment.calls = []
+ CapturePassthrough.values = []
+ prompt = {
+ "empty_list": {
+ "class_type": "TestEmptyList",
+ "inputs": {},
+ },
+ "loop": {
+ "class_type": "StartLoop",
+ "inputs": mode_inputs,
+ },
+ "increment": {
+ "class_type": "TestIncrement",
+ "inputs": {"value": ["loop", 0]},
+ },
+ "preview": {
+ "class_type": "TestCapturePassthrough",
+ "inputs": {"value": ["increment", 0]},
+ },
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {
+ "accumulate": False,
+ "termination0": ["preview", 0],
+ },
+ },
+ }
+ executor = execute_prompt(prompt, "empty-loop-test", ["preview"])
+ assert Increment.calls == []
+ assert CapturePassthrough.values == []
+ assert executor.caches.outputs.get_local("close") is not None
+
+
+ ("mode_inputs", "expected"),
+ [
+ (
+ {"mode": "For", "mode.start_iteration_index": 2, "mode.max_iteration": 8, "mode.step": 3},
+ [(2, True, False, None), (5, False, True, None)],
+ ),
+ (
+ {"mode": "List", "mode.list": ["items", 0]},
+ [(0, True, False, 10), (1, False, True, 20)],
+ ),
+ ],
+)
+def test_loop_modes_expose_iteration_state(mode_inputs, expected):
+ CaptureLoopState.values = []
+ prompt = {
+ "items": {"class_type": "TestIntegerList", "inputs": {}},
+ "loop": {"class_type": "StartLoop", "inputs": mode_inputs},
+ "state": {
+ "class_type": "TestCaptureLoopState",
+ "inputs": {
+ "index": ["loop", 0],
+ "is_first": ["loop", 1],
+ "is_last": ["loop", 2],
+ "item": ["loop", 3],
+ },
+ },
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {"output_value": ["state", 0], "accumulate": True},
+ },
+ }
+ execute_prompt(prompt, "loop-mode-test", ["close"])
+ assert CaptureLoopState.values == expected
+
+
[email protected](("cache_iterations", "expected_calls"), [(False, [1, 2, 1, 2]), (True, [1, 2])])
+def test_iteration_cache_policy_and_end_cache(cache_iterations, expected_calls):
+ Increment.calls = []
+ Capture.values = []
+ Progress.messages = []
+ Progress.body_call_counts = []
+ prompt = {
+ "loop": {
+ "class_type": "StartLoop",
+ "inputs": {
+ "mode": "simple",
+ "mode.num_iterations": 2,
+ "cache_iterations": cache_iterations,
+ },
+ },
+ "increment": {"class_type": "TestIncrement", "inputs": {"value": ["loop", 0]}},
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {"output_value": ["increment", 0], "accumulate": True},
+ },
+ "capture": {"class_type": "TestCapture", "inputs": {"value": ["close", 0]}},
+ }
+ second_prompt = copy.deepcopy(prompt)
+ executor = PromptExecutor(Server(), cache_type=False, cache_args={"ram": 0, "ram_inactive": 0})
+
+ executor.execute(prompt, "loop-cache-first", execute_outputs=["capture"])
+ assert executor.success
+ assert executor.caches.outputs.get_local("close") is not None
+ executor.execute(second_prompt, "loop-cache-second", execute_outputs=["capture"])
+
+ assert executor.success
+ assert Increment.calls == expected_calls
+ assert Progress.messages == [
+ ("Iteration 0 / 2", "loop"),
+ ("Iteration 1 / 2", "loop"),
+ ("Iteration 2 / 2", "loop"),
+ ] * 2
+ assert Progress.body_call_counts == [0, 1, 2] + ([2, 2, 2] if cache_iterations else [2, 3, 4])
+ assert prompt["close"]["inputs"]["output_value"] == ["increment", 0]
+ assert second_prompt["close"]["inputs"]["output_value"] == ["increment", 0]
+
+
+def test_iteration_cache_still_expands_when_only_termination_is_requested():
+ Increment.calls = []
+ CapturePassthrough.values = []
+ prompt = {
+ "loop": {
+ "class_type": "StartLoop",
+ "inputs": {
+ "mode": "simple",
+ "mode.num_iterations": 2,
+ "cache_iterations": True,
+ },
+ },
+ "increment": {"class_type": "TestIncrement", "inputs": {"value": ["loop", 0]}},
+ "preview": {
+ "class_type": "TestCapturePassthrough",
+ "inputs": {"value": ["increment", 0]},
+ },
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {"accumulate": False, "termination0": ["preview", 0]},
+ },
+ }
+ second_prompt = copy.deepcopy(prompt)
+ executor = PromptExecutor(Server(), cache_type=False, cache_args={"ram": 0, "ram_inactive": 0})
+
+ executor.execute(prompt, "termination-cache-first", execute_outputs=["preview"])
+ assert executor.success
+ executor.execute(second_prompt, "termination-cache-second", execute_outputs=["preview"])
+
+ assert executor.success
+ assert Increment.calls == [1, 2]
+ assert CapturePassthrough.values == [1, 2]
+
+
+def test_single_loop_concatenates_list_outputs():
+ Capture.values = []
+ prompt = {
+ "loop": {
+ "class_type": "StartLoop",
+ "inputs": {"mode": "simple", "mode.num_iterations": 2},
+ },
+ "pair": {
+ "class_type": "TestPair",
+ "inputs": {"value": ["loop", 0]},
+ },
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {
+ "output_value": ["pair", 0],
+ "accumulate": True,
+ },
+ },
+ "capture": {
+ "class_type": "TestCapture",
+ "inputs": {"value": ["close", 0]},
+ },
+ }
+ execute_prompt(prompt, "single-loop-accumulation-test", ["capture"])
+ assert Capture.values == [0, "0", 1, "1"]
+
+
+def test_loop_final_output_preserves_output_list(monkeypatch):
+ Capture.values = []
+ CaptureLoopResult.output_keys.clear()
+ monkeypatch.setitem(nodes.NODE_CLASS_MAPPINGS, "LoopResult", CaptureLoopResult)
+ prompt = {
+ "loop": {"class_type": "StartLoop", "inputs": {"mode": "simple", "mode.num_iterations": 2}},
+ "pair": {"class_type": "TestPair", "inputs": {"value": ["loop", 0]}},
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {"output_value": ["pair", 0], "accumulate": False},
+ },
+ "capture": {"class_type": "TestCapture", "inputs": {"value": ["close", 0]}},
+ }
+ execute_prompt(prompt, "final-list-loop-test", ["capture"])
+ assert Capture.values == [1, "1"]
+ assert CaptureLoopResult.output_keys == ["output0"]
+
+
+def test_loop_rebuilds_lazy_branch_dependencies_each_iteration():
+ FalseBranch.calls = []
+ TrueBranch.calls = []
+ prompt = {
+ "loop": {"class_type": "StartLoop", "inputs": {"mode": "simple", "mode.num_iterations": 2}},
+ "false": {"class_type": "TestFalseBranch", "inputs": {"value": ["loop", 0]}},
+ "true": {"class_type": "TestTrueBranch", "inputs": {"value": ["loop", 0]}},
+ "switch": {
+ "class_type": "TestLazySwitch",
+ "inputs": {
+ "switch": ["loop", 1],
+ "on_false": ["false", 0],
+ "on_true": ["true", 0],
+ },
+ },
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {"output_value": ["switch", 0], "accumulate": True},
+ },
+ }
+ execute_prompt(prompt, "lazy-branch-loop-test", ["close"])
+ assert TrueBranch.calls == [0]
+ assert FalseBranch.calls == [1]
+
+
+def test_loop_repeats_runtime_expanded_descendants():
+ Increment.calls = []
+ prompt = {
+ "loop": {"class_type": "StartLoop", "inputs": {"mode": "simple", "mode.num_iterations": 3}},
+ "expand": {"class_type": "TestExpandIncrement", "inputs": {"value": ["loop", 0]}},
+ "close": {
+ "class_type": "EndLoop",
+ "inputs": {"output_value": ["expand", 0], "accumulate": True},
+ },
+ }
+ execute_prompt(prompt, "expanded-descendant-loop-test", ["close"])
+ assert Increment.calls == [1, 2, 3]
+
+
+def run_nested_accumulation(producer_name):
+ Capture.values = []
+
+ prompt = {
+ "outer": {
+ "class_type": "StartLoop",
+ "inputs": {"mode": "simple", "mode.num_iterations": 2},
+ },
+ "inner": {
+ "class_type": "StartLoop",
+ "inputs": {
+ "mode": "simple",
+ "mode.num_iterations": 2,
+ "parent_iteration": ["outer", 0],
+ },
+ },
+ "producer": {
+ "class_type": producer_name,
+ "inputs": {"value": ["inner", 0]},
+ },
+ "inner_close": {
+ "class_type": "EndLoop",
+ "inputs": {
+ "output_value": ["producer", 0],
+ "accumulate": True,
+ },
+ },
+ "outer_close": {
+ "class_type": "EndLoop",
+ "inputs": {
+ "output_value": ["inner_close", 0],
+ "accumulate": True,
+ },
+ },
+ "capture": {
+ "class_type": "TestCapture",
+ "inputs": {"value": ["outer_close", 0]},
+ },
+ }
+ execute_prompt(prompt, "nested-loop-accumulation-test", ["capture"])
+ return Capture.values
+
+
+def test_nested_loop_concatenates_lists():
+ assert run_nested_accumulation("TestPair") == [
+ 0,
+ "0",
+ 1,
+ "1",
+ 0,
+ "0",
+ 1,
+ "1",
+ ]
+
+
+def test_nested_loop_does_not_flatten_list_backed_scalars():
+ assert run_nested_accumulation("TestListBackedScalar") == [
+ [[0]],
+ [[1]],
+ [[0]],
+ [[1]],
+ ]