Repository navigation
ComfyUI Nodes
Spec reference: MASTER_SPEC §20.
Version 1 is implemented entirely as a ComfyUI custom-node package. Each compiler stage is exposed as one or more nodes. Nodes are thin interfaces; all business logic lives inside the compiler package. The compiler is a toolbox, not a workflow: users can replace only the parts they need, and every node is usable independently.
Every stage node also exposes Warnings and Errors, plus a debug string. For the Scene Analyzer/Validator that debug string is Raw; the Resolver's is JSON — the traceable resolved tags, so a translation problem is inspectable.
| Node | Input | Output |
|---|---|---|
| Scene Analyzer | Natural Language; Config (COMPILER_CONFIG, optional) | Scene JSON; Warnings; Errors; Raw |
| Scene Validator | Scene JSON; Config (optional) | Validated Scene JSON; Warnings; Errors; Raw |
| Resolver | Scene JSON; Knowledge Base; Config (optional) | Prompt; Warnings; Errors; JSON |
The Resolver is the final stage: it resolves concepts to Knowledge Base tags and translates them into one flat Prompt string (in resolution order, no categories). There is no separate Category Splitter or Prompt Builder.
As of V2 the analyzer model, temperature, retries and timeout live on the
Configuration node and reach the Scene Analyzer through its optional config
input, so a setting like the model name is entered in exactly one place. Without a
Configuration node the built-in defaults apply (llama3, temperature 0) with a
generous 300 s timeout, because a local Ollama model cold-loads into VRAM on the
first call and a shorter timeout often fails on first use. Every node input carries
a plain-language tooltip.
The Configuration node is deliberately lean: the Knowledge Base path is fixed (it ships inside the package), the prompt target and separator are not exposed (fixed defaults for this version), and there is no system-prompt override — the built-in analyzer prompt is always used.
A typical wiring:
Scene Analyzer → Scene Validator → Resolver → (image workflow)
-
Debug Viewer — displays connected state: Scene JSON, Warnings, Errors. (Resolved tags are inspectable via the Resolver's
jsonoutput.) -
Configuration Node — the single place for compiler settings (Analyzer model/temperature/retries/timeout; Resolver options including the
include_nsfwtoggle and an advancedknowledge_base_versionpin; duplicate-tag removal; the opt-in semantic-fallback settings; debug). It also loads the Knowledge Base from its fixed in-package path and emits it on aknowledge_baseoutput wired into the Resolver, and exposes aknowledge_base_reloadcounter to force a fresh read. Outputs:config,knowledge_base,warnings,errors. There is no separate Knowledge Base Loader node — the Knowledge Base is loaded here, in one place.
Not a graph node. Version 2 adds an optional browser editor for curated Knowledge
Base entries, served by the ComfyUI server on the sub-route
http://127.0.0.1:8188/scene-compiler/kb (registered from the package init and
guarded so it no-ops without ComfyUI). It provides create/edit/delete with live
validation and atomic, format-safe saves, and is entirely off the compile critical
path — see Knowledge Base → Editor.
Every node should be usable independently, and users may replace any stage with a custom implementation. Core compiler behaviour is unchanged by V2.
This project — its code, tests, and documentation — is built with heavy help from AI coding assistants and maintained by a solo author. AI makes mistakes: despite testing and review, parts of this may be inaccurate, out of date, or wrong. Treat it as a good-faith best effort, not authoritative truth — if the docs and the code disagree, the code wins. Please open an issue when something looks off.