5f2f0b7ff2
The docs had drifted badly: docs/nodes.md still documented the Category Splitter and Prompt Builder (removed in V1.1) and the Knowledge Base Loader (removed in V2.1), gave the Resolver the wrong outputs, and the consistency test actively pinned the retired RESOLVED_TAGS/CATEGORY_MAP types. - README: rewritten around the V2 philosophy shift — 'know more, ask less'. Documents the automatic Knowledge Base growth, the opt-in KB-bounded semantic fallback and the fidelity work (know more), and the configuration centralization, node consolidation (eight nodes -> five) and hidden non-user-facing options (ask less), plus what did not change: determinism. Corrects the tagline (flat prompt, not category-separated) and the node tables. - docs/nodes.md: rewritten for the five shipped nodes with their real inputs and outputs, plus a full Configuration input reference and the settings that are deliberately not exposed. - docs/definition_of_done.md: V1 record marked complete; evidence re-pointed at the code as it stands (no compiler/splitter, compiler/builder). - docs/README.md: MASTER_SPEC reframed as the original design spec (code wins); index the in-repo docs. - examples/README.md: pipeline diagram redrawn for the current graph. - tests/test_docs_consistency.py: stop requiring the retired inter-stage types and add a guard so removed nodes cannot reappear in the reference. Co-authored-by: kunail0804 <kunail0804@gmail.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
91 lines
5.3 KiB
Markdown
91 lines
5.3 KiB
Markdown
# ComfyUI node reference
|
|
|
|
The exact inputs, outputs, and data types of the shipped Scene Compiler nodes.
|
|
All nodes appear under the **Scene Compiler** category. Data flows between nodes
|
|
as typed objects; the inter-stage types are `SCENE`, `KNOWLEDGE_BASE`, and
|
|
`COMPILER_CONFIG`.
|
|
|
|
Nodes are thin adapters: all behaviour lives in the `compiler` package, which
|
|
never imports ComfyUI. Settings live on a single **Configuration** node; the stage
|
|
nodes take one optional `config` connection rather than carrying their own copies.
|
|
|
|
Every stage node also exposes a diagnostic string output — `raw` (a JSON dump of
|
|
that node's data output) for the Analyzer and Validator, and `json` (the traceable
|
|
resolved tags) for the Resolver — for inspecting the pipeline. Wire it into a
|
|
text/preview node or the Debug Viewer.
|
|
|
|
## Pipeline nodes
|
|
|
|
| Node | Inputs | Outputs |
|
|
|---|---|---|
|
|
| **Scene Analyzer** | `natural_language` (STRING), `config` (COMPILER_CONFIG, optional — supplies model/temperature/retries/timeout) | `scene` (SCENE), `warnings` (STRING), `errors` (STRING), `raw` (STRING) |
|
|
| **Scene Validator** | `scene` (SCENE), `config` (COMPILER_CONFIG, optional) | `scene` (SCENE), `warnings` (STRING), `errors` (STRING), `raw` (STRING) |
|
|
| **Resolver** | `scene` (SCENE), `knowledge_base` (KNOWLEDGE_BASE), `config` (COMPILER_CONFIG, optional) | `prompt` (STRING), `warnings` (STRING), `errors` (STRING), `json` (STRING) |
|
|
|
|
The **Resolver** is the final stage. It resolves concepts to Knowledge Base tags,
|
|
expands them, removes duplicates, and joins them into one flat `prompt` string in
|
|
resolution order. There are no per-category outputs: the separate Category Splitter
|
|
and Prompt Builder stages were removed in V1.1 and their work now happens inside the
|
|
Resolver. Categories still exist on each Knowledge Base entry and on each resolved
|
|
tag (visible in the `json` output) purely for traceability.
|
|
|
|
Without a Configuration node the Scene Analyzer falls back to built-in defaults
|
|
(llama3, temperature 0) with a 300 s timeout, which is generous on purpose: a local
|
|
Ollama model cold-loads into VRAM on the first call.
|
|
|
|
## Support nodes
|
|
|
|
| Node | Inputs | Outputs |
|
|
|---|---|---|
|
|
| **Configuration** | see the table below | `config` (COMPILER_CONFIG), `knowledge_base` (KNOWLEDGE_BASE), `warnings` (STRING), `errors` (STRING) |
|
|
| **Debug Viewer** | `scene` (SCENE, optional), `warnings` (STRING, optional), `errors` (STRING, optional) | `report` (STRING) |
|
|
|
|
- The **Configuration** node is the single source of compiler settings *and* the
|
|
Knowledge Base loader. It reads the Knowledge Base that ships inside the package
|
|
and emits it on `knowledge_base`, which you wire into the Resolver — there is no
|
|
separate Knowledge Base Loader node. The Knowledge Base path is fixed (not a
|
|
user-facing setting); bump `knowledge_base_reload` to force a fresh read. If the
|
|
Knowledge Base fails to load, `config` is still emitted (the Analyzer and Validator
|
|
do not need it) and the failure is reported on `errors`.
|
|
- The **Debug Viewer** is read-only; connect any intermediate state to inspect it.
|
|
|
|
### Configuration inputs
|
|
|
|
| Input | Type | Purpose |
|
|
|---|---|---|
|
|
| `analyzer_model` | STRING | Ollama model the Scene Analyzer uses. |
|
|
| `analyzer_temperature` | FLOAT | Sampling temperature; 0 is the most repeatable. |
|
|
| `analyzer_max_retries` | INT | Retries when the model returns malformed JSON. |
|
|
| `analyzer_timeout` | INT | Seconds to wait for the model (default 300). |
|
|
| `resolver_strict_mode` | BOOLEAN | Report unknown concepts instead of guessing. |
|
|
| `resolver_allow_aliases` | BOOLEAN | Resolve aliases to their canonical entry. |
|
|
| `resolver_expansion_enabled` | BOOLEAN | Add tags implied by an entry's expansion list. |
|
|
| `resolver_max_expansion_depth` | INT | How deep expansion may recurse. |
|
|
| `resolver_include_nsfw` | BOOLEAN | Include explicit-rated entries. Off = SFW only. |
|
|
| `validator_allow_unknown_fields` | BOOLEAN | Keep unrecognized Scene JSON fields. |
|
|
| `prompt_remove_duplicate_tags` | BOOLEAN | Drop duplicate tags after expansion (`SC0007`). |
|
|
| `debug_enabled` / `debug_level` | BOOLEAN / combo | Diagnostic logging and its verbosity. |
|
|
| `resolver_knowledge_base_version` | STRING *(optional)* | Pin a Knowledge Base dataset version. Empty = unpinned. |
|
|
| `semantic_enabled` | BOOLEAN *(optional)* | Opt-in nearest-neighbour fallback. Off by default. |
|
|
| `semantic_min_similarity` | FLOAT *(optional)* | Minimum similarity to accept a fallback match. |
|
|
| `semantic_backend` | STRING *(optional)* | Embedding backend for the fallback (offline). |
|
|
| `knowledge_base_reload` | INT *(optional)* | Bump to re-read the Knowledge Base from disk. |
|
|
|
|
Deliberately **not** exposed: the Knowledge Base path (fixed — it ships in the
|
|
package), `prompt_target` and `prompt_separator` (reserved / fixed to `,` for this
|
|
version), and any hand-written analyzer system prompt. These keep their compiler
|
|
defaults; see [Configuration, Errors & Logging](../../../wiki/Configuration-Errors-and-Logging)
|
|
for the full config document.
|
|
|
|
## Typical graph
|
|
|
|
```
|
|
Configuration ─ config ──────────► Scene Analyzer / Scene Validator / Resolver
|
|
└ knowledge_base ───► Resolver
|
|
|
|
Scene Analyzer → Scene Validator → Resolver → (image workflow)
|
|
```
|
|
|
|
A ready-to-use workflow wiring all of these is in
|
|
[`examples/workflows/scene_compiler_pipeline.json`](../examples/workflows/scene_compiler_pipeline.json).
|