check_deps.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437
  1. #!/usr/bin/env python3
  2. """
  3. check_deps.py — Verify a ComfyUI workflow's dependencies (custom nodes, models,
  4. embeddings) against a running server.
  5. Improvements over v1:
  6. - Cloud-aware endpoint mapping (handles `/api/experiment/models/{folder}` and
  7. `/api/object_info` variants verified against live cloud API)
  8. - Distinguishes 200-empty (genuinely no models in folder) vs 404
  9. (folder doesn't exist) vs 403 (auth/tier issue) — no silent passes
  10. - Outputs concrete remediation commands (e.g. `comfy node install <name>`)
  11. when nodes are missing
  12. - Detects embedding references inside prompt strings as model deps
  13. - Skips check on cloud free tier `/api/object_info` (403) without false alarm
  14. - Accepts API key from CLI flag OR $COMFY_CLOUD_API_KEY env var
  15. Usage:
  16. python3 check_deps.py workflow_api.json
  17. python3 check_deps.py workflow_api.json --host 127.0.0.1 --port 8188
  18. python3 check_deps.py workflow_api.json --host https://cloud.comfy.org
  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. sys.path.insert(0, str(Path(__file__).resolve().parent))
  27. from _common import (
  28. DEFAULT_LOCAL_HOST, ENV_API_KEY,
  29. emit_json, folder_aliases_for, http_get, is_cloud_host,
  30. iter_embedding_refs, iter_model_deps, iter_nodes, parse_model_list,
  31. resolve_api_key, resolve_url, unwrap_workflow,
  32. )
  33. # Known node → custom-node-package map. When a workflow needs a node we don't
  34. # recognize, suggesting the right `comfy node install ...` makes the difference
  35. # between a working agent and a stuck one.
  36. NODE_TO_PACKAGE: dict[str, str] = {
  37. # rgthree (Reroute is JS-only and doesn't appear in /object_info)
  38. "Power Lora Loader (rgthree)": "rgthree-comfy",
  39. "Image Comparer (rgthree)": "rgthree-comfy",
  40. "Seed (rgthree)": "rgthree-comfy",
  41. "Display Any (rgthree)": "rgthree-comfy",
  42. "Display Int (rgthree)": "rgthree-comfy",
  43. # Impact pack
  44. "FaceDetailer": "comfyui-impact-pack",
  45. "DetailerForEach": "comfyui-impact-pack",
  46. "BboxDetectorSEGS": "comfyui-impact-pack",
  47. "SAMLoader": "comfyui-impact-pack",
  48. "ImpactWildcardProcessor": "comfyui-impact-pack",
  49. # Impact subpack (separate package)
  50. "UltralyticsDetectorProvider": "comfyui-impact-subpack",
  51. # Was Node Suite
  52. "Image Save": "was-node-suite-comfyui",
  53. "Number Counter": "was-node-suite-comfyui",
  54. "Text String": "was-node-suite-comfyui",
  55. # easy-use
  56. "easy fullLoader": "comfyui-easy-use",
  57. "easy positive": "comfyui-easy-use",
  58. "easy negative": "comfyui-easy-use",
  59. "easy seed": "comfyui-easy-use",
  60. "easy imageSave": "comfyui-easy-use",
  61. # Video Helper Suite
  62. "VHS_VideoCombine": "comfyui-videohelpersuite",
  63. "VHS_LoadVideo": "comfyui-videohelpersuite",
  64. "VHS_LoadAudio": "comfyui-videohelpersuite",
  65. # AnimateDiff
  66. "ADE_AnimateDiffLoaderWithContext": "comfyui-animatediff-evolved",
  67. "ADE_AnimateDiffLoaderGen1": "comfyui-animatediff-evolved",
  68. "ADE_LoadAnimateDiffModel": "comfyui-animatediff-evolved",
  69. # ControlNet aux preprocessors (full class names)
  70. "CannyEdgePreprocessor": "comfyui_controlnet_aux",
  71. "DWPreprocessor": "comfyui_controlnet_aux",
  72. "OpenposePreprocessor": "comfyui_controlnet_aux",
  73. "DepthAnythingPreprocessor": "comfyui_controlnet_aux",
  74. "Zoe_DepthAnythingPreprocessor": "comfyui_controlnet_aux",
  75. "AnimalPosePreprocessor": "comfyui_controlnet_aux",
  76. # IPAdapter Plus
  77. "IPAdapterAdvanced": "comfyui_ipadapter_plus",
  78. "IPAdapterUnifiedLoader": "comfyui_ipadapter_plus",
  79. "IPAdapterModelLoader": "comfyui_ipadapter_plus",
  80. "IPAdapterInsightFaceLoader": "comfyui_ipadapter_plus",
  81. # InstantID
  82. "InstantIDModelLoader": "comfyui_instantid",
  83. "ApplyInstantID": "comfyui_instantid",
  84. # Comfy essentials (note: registry slug uses underscore, not hyphen)
  85. "GetImageSize+": "comfyui_essentials",
  86. "ImageBatchMultiple+": "comfyui_essentials",
  87. # pysssss
  88. "ShowText|pysssss": "comfyui-custom-scripts",
  89. "PreviewImage|pysssss": "comfyui-custom-scripts",
  90. # SUPIR
  91. "SUPIR_Upscale": "comfyui-supir",
  92. "SUPIR_first_stage": "comfyui-supir",
  93. # GGUF (case-sensitive registry slug)
  94. "UNETLoaderGGUF": "ComfyUI-GGUF",
  95. "DualCLIPLoaderGGUF": "ComfyUI-GGUF",
  96. # Florence2
  97. "Florence2Run": "comfyui-florence2",
  98. # WAS
  99. "Image Filter Adjustments": "was-node-suite-comfyui",
  100. # Photomaker (case-sensitive)
  101. "PhotoMakerLoader": "ComfyUI-PhotoMaker-Plus",
  102. # Wan video (case-sensitive)
  103. "WanVideoSampler": "ComfyUI-WanVideoWrapper",
  104. "WanVideoModelLoader": "ComfyUI-WanVideoWrapper",
  105. }
  106. # Nodes whose package isn't on the comfy registry — need git-URL install via
  107. # ComfyUI-Manager. We surface a helpful hint instead of an unrunnable command.
  108. NODE_TO_GIT_URL: dict[str, str] = {
  109. "HunyuanVideoSampler": "https://github.com/kijai/ComfyUI-HunyuanVideoWrapper",
  110. "HunyuanVideoModelLoader": "https://github.com/kijai/ComfyUI-HunyuanVideoWrapper",
  111. }
  112. def fetch_object_info(url: str, headers: dict) -> tuple[set[str] | None, dict | None]:
  113. """Returns (installed_node_set, error_info). Error info is a dict if we
  114. couldn't query (e.g. cloud free tier), else None.
  115. """
  116. r = http_get(url, headers=headers, retries=2, timeout=30)
  117. if r.status == 200:
  118. try:
  119. data = r.json()
  120. if isinstance(data, dict):
  121. return set(data.keys()), None
  122. except Exception:
  123. pass
  124. return None, {"http_status": 200, "reason": "non-dict response"}
  125. if r.status == 403:
  126. try:
  127. body = r.json()
  128. except Exception:
  129. body = {"raw": r.text()[:200]}
  130. return None, {"http_status": 403, "reason": "forbidden", "body": body}
  131. if r.status == 404:
  132. return None, {"http_status": 404, "reason": "endpoint not found"}
  133. return None, {"http_status": r.status, "reason": "unexpected", "body": r.text()[:200]}
  134. def _fetch_one_folder(
  135. base: str, folder: str, headers: dict, *, is_cloud: bool,
  136. ) -> tuple[set[str] | None, dict | None]:
  137. """Single-folder fetch, no aliasing. Returns (installed_set, error_info)."""
  138. url = resolve_url(base, f"/models/{folder}", is_cloud=is_cloud)
  139. r = http_get(url, headers=headers, retries=2, timeout=30)
  140. if r.status == 200:
  141. try:
  142. return parse_model_list(r.json()), None
  143. except Exception:
  144. return set(), {"http_status": 200, "reason": "non-list response"}
  145. if r.status == 404:
  146. body_text = r.text()
  147. try:
  148. body = r.json()
  149. except Exception:
  150. body = {"raw": body_text[:200]}
  151. code = body.get("code") if isinstance(body, dict) else None
  152. if code == "folder_not_found":
  153. # Folder is genuinely empty/missing on server — not the same as
  154. # "endpoint missing". Return empty set with informational error.
  155. return set(), {"http_status": 404, "reason": "folder_empty_or_unknown", "body": body}
  156. return None, {"http_status": 404, "reason": "endpoint not found", "body": body}
  157. if r.status == 403:
  158. try:
  159. body = r.json()
  160. except Exception:
  161. body = {}
  162. return None, {"http_status": 403, "reason": "forbidden", "body": body}
  163. return None, {"http_status": r.status, "reason": "unexpected"}
  164. def fetch_models_for_folder(
  165. base: str, folder: str, headers: dict, *, is_cloud: bool,
  166. ) -> tuple[set[str] | None, dict | None]:
  167. """Fetch installed models for a folder, trying aliases.
  168. Folder renames over time (e.g. unet → diffusion_models, clip → text_encoders)
  169. mean a workflow asking for a model in `unet` may need to look in
  170. `diffusion_models`. We union models from every reachable alias.
  171. Returns (combined_set | None, last_error | None).
  172. """
  173. aliases = folder_aliases_for(folder)
  174. combined: set[str] = set()
  175. any_success = False
  176. last_err: dict | None = None
  177. for alias in aliases:
  178. models, err = _fetch_one_folder(base, alias, headers, is_cloud=is_cloud)
  179. if models is not None:
  180. combined.update(models)
  181. any_success = True
  182. last_err = None
  183. else:
  184. last_err = err
  185. if not any_success:
  186. return None, last_err
  187. return combined, None
  188. def fetch_embeddings(base: str, headers: dict, *, is_cloud: bool) -> tuple[set[str] | None, dict | None]:
  189. """Local ComfyUI exposes /embeddings; cloud uses /experiment/models/embeddings."""
  190. if is_cloud:
  191. return fetch_models_for_folder(base, "embeddings", headers, is_cloud=True)
  192. # Local: dedicated /embeddings returns a flat list of names
  193. r = http_get(resolve_url(base, "/embeddings", is_cloud=False), headers=headers, retries=2)
  194. if r.status == 200:
  195. try:
  196. data = r.json()
  197. if isinstance(data, list):
  198. # Strip extensions from the registered names since prompt syntax
  199. # usually omits them ("embedding:goodvibes" vs "goodvibes.pt")
  200. names = set()
  201. for n in data:
  202. if isinstance(n, str):
  203. names.add(n)
  204. # Also store stem for fuzzy matching
  205. names.add(Path(n).stem)
  206. return names, None
  207. except Exception:
  208. pass
  209. return None, {"http_status": r.status, "reason": "unexpected"}
  210. def normalize_for_match(name: str) -> set[str]:
  211. """Generate matching variants of a model name (with/without extension, slashes, etc.)"""
  212. s = {name}
  213. s.add(Path(name).stem)
  214. s.add(Path(name).name)
  215. # ComfyUI sometimes strips/keeps the leading folder
  216. if "/" in name or "\\" in name:
  217. flat = name.replace("\\", "/").split("/")[-1]
  218. s.add(flat)
  219. s.add(Path(flat).stem)
  220. return {x for x in s if x}
  221. def model_present(needed: str, installed: set[str]) -> bool:
  222. if not installed:
  223. return False
  224. needed_variants = normalize_for_match(needed)
  225. installed_norm: set[str] = set()
  226. for inst in installed:
  227. installed_norm.update(normalize_for_match(inst))
  228. return bool(needed_variants & installed_norm)
  229. def suggest_install_command(node_class: str) -> str | None:
  230. pkg = NODE_TO_PACKAGE.get(node_class)
  231. if pkg:
  232. return f"comfy node install {pkg}"
  233. return None
  234. def suggest_git_url(node_class: str) -> str | None:
  235. """For nodes not on the registry, return a git URL the user can hand to
  236. ComfyUI-Manager's `/manager/queue/install` endpoint."""
  237. return NODE_TO_GIT_URL.get(node_class)
  238. def check_deps(
  239. workflow: dict, host: str, *, api_key: str | None = None,
  240. ) -> dict:
  241. headers: dict[str, str] = {}
  242. if api_key:
  243. headers["X-API-Key"] = api_key
  244. is_cloud = is_cloud_host(host)
  245. base = host.rstrip("/")
  246. # ---- 1. Required nodes ----
  247. required_nodes: set[str] = set()
  248. for _, node in iter_nodes(workflow):
  249. required_nodes.add(node["class_type"])
  250. object_info_url = resolve_url(base, "/object_info", is_cloud=is_cloud)
  251. installed_nodes, obj_err = fetch_object_info(object_info_url, headers)
  252. missing_nodes: list[dict] = []
  253. node_check_skipped = False
  254. if installed_nodes is None:
  255. # Couldn't query (e.g. cloud free tier). Don't false-alarm; mark skipped.
  256. node_check_skipped = True
  257. else:
  258. for cls in sorted(required_nodes):
  259. if cls not in installed_nodes:
  260. entry = {"class_type": cls}
  261. cmd = suggest_install_command(cls)
  262. git_url = suggest_git_url(cls)
  263. if cmd:
  264. entry["fix_command"] = cmd
  265. elif git_url:
  266. entry["fix_git_url"] = git_url
  267. entry["fix_hint"] = (
  268. f"Not on registry. Install via Manager with this git URL: {git_url}"
  269. )
  270. else:
  271. entry["fix_hint"] = (
  272. "Search https://registry.comfy.org or "
  273. "use ComfyUI-Manager UI to find the package providing this node."
  274. )
  275. missing_nodes.append(entry)
  276. # ---- 2. Required models ----
  277. model_cache: dict[str, tuple[set[str] | None, dict | None]] = {}
  278. missing_models: list[dict] = []
  279. folder_errors: dict[str, dict] = {}
  280. for dep in iter_model_deps(workflow):
  281. folder = dep["folder"]
  282. if folder not in model_cache:
  283. model_cache[folder] = fetch_models_for_folder(
  284. base, folder, headers, is_cloud=is_cloud,
  285. )
  286. installed, err = model_cache[folder]
  287. if installed is None:
  288. # Couldn't enumerate this folder — record once
  289. folder_errors.setdefault(folder, err or {})
  290. # Don't flag as missing (we don't know); the folder_errors block surfaces this
  291. continue
  292. if not model_present(dep["value"], installed):
  293. entry = dict(dep)
  294. entry["fix_hint"] = (
  295. f"comfy model download --url <URL> --relative-path models/{folder} "
  296. f"--filename {dep['value']!r}"
  297. )
  298. missing_models.append(entry)
  299. # ---- 3. Embedding refs in prompts ----
  300. emb_installed, emb_err = fetch_embeddings(base, headers, is_cloud=is_cloud)
  301. missing_embeddings: list[dict] = []
  302. seen_emb: set[tuple[str, str]] = set()
  303. for nid, emb_name in iter_embedding_refs(workflow):
  304. if (nid, emb_name) in seen_emb:
  305. continue
  306. seen_emb.add((nid, emb_name))
  307. if emb_installed is None:
  308. # Couldn't enumerate — skip silently here, surface the error in the
  309. # folder_errors block
  310. continue
  311. if not model_present(emb_name, emb_installed):
  312. missing_embeddings.append({
  313. "node_id": nid,
  314. "embedding_name": emb_name,
  315. "folder": "embeddings",
  316. "fix_hint": (
  317. f"Download {emb_name}.pt or .safetensors and place in "
  318. f"models/embeddings/, or `comfy model download --url <URL> "
  319. f"--relative-path models/embeddings`"
  320. ),
  321. })
  322. if emb_err and emb_installed is None:
  323. folder_errors.setdefault("embeddings", emb_err)
  324. is_ready = (
  325. not node_check_skipped
  326. and not missing_nodes
  327. and not missing_models
  328. and not missing_embeddings
  329. )
  330. return {
  331. "is_ready": is_ready,
  332. "node_check_skipped": node_check_skipped,
  333. "node_check_skip_reason": obj_err if node_check_skipped else None,
  334. "missing_nodes": missing_nodes,
  335. "missing_models": missing_models,
  336. "missing_embeddings": missing_embeddings,
  337. "folder_errors": folder_errors,
  338. # 0 is a legitimate count (e.g. empty server). Use None only when not queried.
  339. "installed_node_count": len(installed_nodes) if installed_nodes is not None else None,
  340. "required_node_count": len(required_nodes),
  341. "required_nodes": sorted(required_nodes),
  342. "host": base,
  343. "is_cloud": is_cloud,
  344. }
  345. def main(argv: list[str] | None = None) -> int:
  346. p = argparse.ArgumentParser(description="Check ComfyUI workflow dependencies against a running server")
  347. p.add_argument("workflow", help="Path to workflow API JSON file")
  348. p.add_argument("--host", default=DEFAULT_LOCAL_HOST, help="ComfyUI server URL")
  349. p.add_argument("--port", type=int, help="Server port (overrides --host port)")
  350. p.add_argument("--api-key", help=f"API key for cloud (or set ${ENV_API_KEY} env var)")
  351. p.add_argument("--strict", action="store_true",
  352. help="Exit non-zero if node check is skipped (e.g. on cloud free tier)")
  353. args = p.parse_args(argv)
  354. host = args.host
  355. if args.port is not None:
  356. # Strip any port from host and append --port
  357. from urllib.parse import urlparse, urlunparse
  358. parsed = urlparse(host if "://" in host else f"http://{host}")
  359. new_netloc = f"{parsed.hostname}:{args.port}"
  360. host = urlunparse(parsed._replace(netloc=new_netloc))
  361. api_key = resolve_api_key(args.api_key)
  362. wf_path = Path(args.workflow).expanduser()
  363. if not wf_path.exists():
  364. emit_json({"error": f"Workflow file not found: {args.workflow}"})
  365. return 1
  366. try:
  367. with wf_path.open(encoding="utf-8-sig") as f:
  368. payload = json.load(f)
  369. workflow = unwrap_workflow(payload)
  370. except ValueError as e:
  371. emit_json({"error": str(e)})
  372. return 1
  373. except json.JSONDecodeError as e:
  374. emit_json({"error": f"Invalid JSON: {e}"})
  375. return 1
  376. try:
  377. result = check_deps(workflow, host=host, api_key=api_key)
  378. except Exception as e:
  379. emit_json({"error": f"Dep check failed: {e}", "host": host})
  380. return 1
  381. emit_json(result)
  382. if not result["is_ready"]:
  383. return 1
  384. if args.strict and result["node_check_skipped"]:
  385. return 1
  386. return 0
  387. if __name__ == "__main__":
  388. sys.exit(main())