extract_schema.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315
  1. #!/usr/bin/env python3
  2. """
  3. extract_schema.py — Analyze a ComfyUI API-format workflow and extract
  4. controllable parameters.
  5. Improvements over v1:
  6. - Catalogs live in `_common.py`, shared with `check_deps.py`
  7. - Coverage expanded for Flux / SD3 / Wan / Hunyuan / LTX / IPAdapter / rgthree
  8. - Symmetric duplicate-name resolution: ALL duplicates get a node-id suffix
  9. (instead of "first wins, second renamed"), so callers see consistent names
  10. - Negative prompt detected by tracing `KSampler.negative` connections back to
  11. the source CLIPTextEncode (more reliable than meta-title heuristic)
  12. - Embedding references in prompt text are extracted as model dependencies
  13. - Detects Primitive nodes that drive other nodes' inputs (and surfaces them
  14. as the user-facing parameter)
  15. - Reroutes are followed when tracing connections
  16. Usage:
  17. python3 extract_schema.py workflow_api.json
  18. python3 extract_schema.py workflow_api.json --output schema.json
  19. Stdlib-only. Python 3.10+.
  20. """
  21. from __future__ import annotations
  22. import argparse
  23. import json
  24. import sys
  25. from pathlib import Path
  26. from typing import Any
  27. sys.path.insert(0, str(Path(__file__).resolve().parent))
  28. from _common import (
  29. OUTPUT_NODES, PARAM_PATTERNS, PROMPT_FIELDS,
  30. is_link, iter_embedding_refs, iter_model_deps, iter_nodes, unwrap_workflow,
  31. )
  32. # Sampler nodes whose `positive` / `negative` connections we trace
  33. SAMPLER_NODE_FAMILY = {
  34. "KSampler", "KSamplerAdvanced",
  35. "SamplerCustom", "SamplerCustomAdvanced",
  36. "BasicGuider", "CFGGuider", "DualCFGGuider",
  37. }
  38. def infer_type(value: Any) -> str:
  39. if isinstance(value, bool):
  40. return "bool"
  41. if isinstance(value, int):
  42. return "int"
  43. if isinstance(value, float):
  44. return "float"
  45. if isinstance(value, str):
  46. return "string"
  47. if isinstance(value, list):
  48. return "link"
  49. if isinstance(value, dict):
  50. return "object"
  51. return "unknown"
  52. def trace_to_node(workflow: dict, link: list, *, max_hops: int = 8) -> str | None:
  53. """Follow a [node_id, slot] link, hopping through Reroute / Primitive nodes
  54. if needed, to find the *upstream* node id that holds the actual value/input.
  55. Bounded by both `max_hops` AND a visited-set to prevent infinite loops on
  56. pathological graphs.
  57. """
  58. if not is_link(link):
  59. return None
  60. nid: str | None = link[0]
  61. visited: set[str] = set()
  62. for _ in range(max_hops):
  63. if nid is None or nid in visited:
  64. return nid
  65. visited.add(nid)
  66. node = workflow.get(nid)
  67. if not isinstance(node, dict):
  68. return None
  69. cls = node.get("class_type", "")
  70. # Reroute / Primitive / passthrough wrappers
  71. if cls in {"Reroute", "PrimitiveNode", "Note", "easy showAnything"}:
  72. inputs = node.get("inputs", {}) or {}
  73. # Find first link-shaped input and follow it
  74. next_link = next((v for v in inputs.values() if is_link(v)), None)
  75. if next_link is None:
  76. return nid
  77. nid = next_link[0]
  78. continue
  79. return nid
  80. return nid
  81. def find_negative_prompt_node(workflow: dict) -> str | None:
  82. """Trace `negative` input of a sampler back to the source text encoder."""
  83. for nid, node in iter_nodes(workflow):
  84. if node["class_type"] not in SAMPLER_NODE_FAMILY:
  85. continue
  86. inputs = node.get("inputs", {}) or {}
  87. neg = inputs.get("negative")
  88. if not is_link(neg):
  89. continue
  90. src = trace_to_node(workflow, neg)
  91. if src and isinstance(workflow.get(src), dict):
  92. cls = workflow[src].get("class_type", "")
  93. if cls.startswith("CLIPTextEncode") or cls in {"smZ CLIPTextEncode", "BNK_CLIPTextEncodeAdvanced"}:
  94. return src
  95. return None
  96. def find_positive_prompt_node(workflow: dict) -> str | None:
  97. for nid, node in iter_nodes(workflow):
  98. if node["class_type"] not in SAMPLER_NODE_FAMILY:
  99. continue
  100. inputs = node.get("inputs", {}) or {}
  101. pos = inputs.get("positive")
  102. if not is_link(pos):
  103. continue
  104. src = trace_to_node(workflow, pos)
  105. if src and isinstance(workflow.get(src), dict):
  106. cls = workflow[src].get("class_type", "")
  107. if cls.startswith("CLIPTextEncode") or cls in {"smZ CLIPTextEncode", "BNK_CLIPTextEncodeAdvanced"}:
  108. return src
  109. return None
  110. def extract_schema(workflow: dict) -> dict:
  111. """Extract controllable parameters from a workflow.
  112. Returns:
  113. {
  114. "parameters": { friendly_name: {node_id, field, type, value, ...} },
  115. "output_nodes": [node_id, ...],
  116. "model_dependencies": [{node_id, class_type, field, value, folder}],
  117. "embedding_dependencies": [{node_id, embedding_name, found_in_field, value_excerpt}],
  118. "summary": {...}
  119. }
  120. """
  121. output_nodes: list[str] = []
  122. # First pass: identify positive / negative prompt nodes via connection tracing
  123. pos_node = find_positive_prompt_node(workflow)
  124. neg_node = find_negative_prompt_node(workflow)
  125. # ----- collect raw parameter candidates -----
  126. # Each candidate = (friendly_name, node_id, field, value)
  127. # We resolve duplicate friendly_names AFTER the loop so dedup is symmetric.
  128. raw_params: list[dict] = []
  129. for node_id, node in iter_nodes(workflow):
  130. cls = node["class_type"]
  131. inputs = node.get("inputs", {}) or {}
  132. if cls in OUTPUT_NODES:
  133. output_nodes.append(node_id)
  134. # Match this node against PARAM_PATTERNS
  135. for p_class, p_field, friendly in PARAM_PATTERNS:
  136. if cls != p_class:
  137. continue
  138. if p_field not in inputs:
  139. continue
  140. value = inputs[p_field]
  141. t = infer_type(value)
  142. if t == "link":
  143. continue # connections aren't directly controllable
  144. actual_name = friendly
  145. # Disambiguate prompt vs negative_prompt by connection tracing
  146. if friendly == "prompt":
  147. if node_id == neg_node and pos_node != neg_node:
  148. actual_name = "negative_prompt"
  149. elif node_id == pos_node:
  150. actual_name = "prompt"
  151. else:
  152. # Fallback: use _meta.title hints if present
  153. meta_title = (node.get("_meta") or {}).get("title", "").lower()
  154. if any(t_ in meta_title for t_ in ("negative", "neg", "-prompt", "anti")):
  155. actual_name = "negative_prompt"
  156. raw_params.append({
  157. "name_hint": actual_name,
  158. "node_id": node_id,
  159. "field": p_field,
  160. "type": t,
  161. "value": value,
  162. "class_type": cls,
  163. })
  164. # ----- symmetric duplicate-name resolution -----
  165. # Group by name_hint. If a hint appears once, keep it. If multiple, suffix
  166. # ALL with their node_id. Always-stable, always-uniquely-addressable.
  167. by_name: dict[str, list[dict]] = {}
  168. for r in raw_params:
  169. by_name.setdefault(r["name_hint"], []).append(r)
  170. parameters: dict[str, dict] = {}
  171. for name, entries in by_name.items():
  172. if len(entries) == 1:
  173. r = entries[0]
  174. parameters[name] = {
  175. "node_id": r["node_id"], "field": r["field"],
  176. "type": r["type"], "value": r["value"],
  177. "class_type": r["class_type"],
  178. }
  179. else:
  180. # Sort by node_id (string-natural) for stability
  181. entries.sort(key=lambda x: (str(x["node_id"]).zfill(8), x["field"]))
  182. for r in entries:
  183. full_name = f"{name}_{r['node_id']}"
  184. parameters[full_name] = {
  185. "node_id": r["node_id"], "field": r["field"],
  186. "type": r["type"], "value": r["value"],
  187. "class_type": r["class_type"],
  188. "alias_of": name,
  189. }
  190. # ----- model dependencies -----
  191. model_deps = list(iter_model_deps(workflow))
  192. # ----- embedding dependencies (in prompt text) -----
  193. embedding_deps: list[dict] = []
  194. seen_emb: set[tuple[str, str]] = set()
  195. for nid, emb_name in iter_embedding_refs(workflow):
  196. key = (nid, emb_name)
  197. if key in seen_emb:
  198. continue
  199. seen_emb.add(key)
  200. # Find which field had the reference, for context
  201. node = workflow.get(nid, {})
  202. inputs = node.get("inputs", {}) or {}
  203. found_field = None
  204. excerpt = None
  205. for fname, fval in inputs.items():
  206. if isinstance(fval, str) and fname in PROMPT_FIELDS and emb_name in fval:
  207. found_field = fname
  208. excerpt = fval[:120]
  209. break
  210. embedding_deps.append({
  211. "node_id": nid,
  212. "embedding_name": emb_name,
  213. "field": found_field,
  214. "value_excerpt": excerpt,
  215. "folder": "embeddings",
  216. })
  217. # ----- summary -----
  218. summary = {
  219. "parameter_count": len(parameters),
  220. "output_node_count": len(output_nodes),
  221. "model_dep_count": len(model_deps),
  222. "embedding_dep_count": len(embedding_deps),
  223. "has_negative_prompt": "negative_prompt" in parameters,
  224. "has_seed": "seed" in parameters or any(p.startswith("seed_") for p in parameters),
  225. "is_video_workflow": any(
  226. workflow.get(n, {}).get("class_type", "") in {
  227. "VHS_VideoCombine", "SaveVideo", "SaveAnimatedWEBP", "SaveAnimatedPNG",
  228. } for n in output_nodes
  229. ),
  230. }
  231. return {
  232. "parameters": parameters,
  233. "output_nodes": output_nodes,
  234. "model_dependencies": model_deps,
  235. "embedding_dependencies": embedding_deps,
  236. "summary": summary,
  237. }
  238. def main(argv: list[str] | None = None) -> int:
  239. p = argparse.ArgumentParser(description="Extract controllable parameters from a ComfyUI workflow")
  240. p.add_argument("workflow", help="Path to workflow API JSON file")
  241. p.add_argument("--output", "-o", help="Output file (default: stdout)")
  242. p.add_argument("--summary-only", action="store_true",
  243. help="Only print the summary block")
  244. args = p.parse_args(argv)
  245. wf_path = Path(args.workflow).expanduser()
  246. if not wf_path.exists():
  247. print(f"Error: {wf_path} not found", file=sys.stderr)
  248. return 1
  249. try:
  250. with wf_path.open(encoding="utf-8-sig") as f:
  251. payload = json.load(f)
  252. workflow = unwrap_workflow(payload)
  253. except ValueError as e:
  254. print(f"Error: {e}", file=sys.stderr)
  255. return 1
  256. except json.JSONDecodeError as e:
  257. print(f"Error: invalid JSON — {e}", file=sys.stderr)
  258. return 1
  259. schema = extract_schema(workflow)
  260. if args.summary_only:
  261. out = json.dumps(schema["summary"], indent=2)
  262. else:
  263. out = json.dumps(schema, indent=2, default=str)
  264. if args.output:
  265. Path(args.output).write_text(out, encoding="utf-8")
  266. print(f"Schema written to {args.output}", file=sys.stderr)
  267. else:
  268. print(out)
  269. return 0
  270. if __name__ == "__main__":
  271. sys.exit(main())