nodes/kunail0804-ComfyUI-Scene-Compiler
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: overhaul repo documentation for V2 (#152)

Browse Source 
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>
This commit is contained in:
Crespin Alexandre
2026-07-19 15:11:04 +02:00
committed by GitHub
co-authored by kunail0804 Claude Opus 4.8
parent 091e5b7ec7
commit 5f2f0b7ff2
6 changed files with 255 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+129 -52
View File
@@ -1,14 +1,12 @@
# ComfyUI Scene Compiler
**A deterministic prompt compiler for ComfyUI.**
Turn a plain-language scene description into structured, category-separated
Illustrious tags — without an LLM inventing anything.
Turn a plain-language scene description into a clean, valid Illustrious tag
prompt — without an LLM inventing anything.
> **Status:** Version 2 (Semantic Resolution) complete on `main`; the deterministic
> Version 1 pipeline shipped in v1.0.0 / v1.1.0. This repository is spec-driven; the
> full design is documented in [`MASTER_SPEC.md`](../MASTER_SPEC.md) and in the
> [Wiki](../../wiki). Follow the [Roadmap](../../wiki/Roadmap) and
> [issues](../../issues) for progress.
> **Status:** Version 2 released (`v2.1.0`). The deterministic Version 1 pipeline
> shipped in v1.0.0 / v1.1.0. Full documentation lives in the [Wiki](../../wiki);
> see the [Roadmap](../../wiki/Roadmap) and [issues](../../issues) for what's next.
---
@@ -33,70 +31,137 @@ deterministic and traceable.
```
Natural Language
→ Scene Analyzer → Scene JSON
→ Scene Validator → Validated Scene JSON
→ Resolver → Prompt
→ Scene Analyzer → Scene JSON
→ Scene Validator → Validated Scene JSON
→ Resolver → Prompt
```
The Resolver both resolves concepts to Knowledge Base tags and translates them
into a single flat prompt string (in resolution order). There are no categories.
Only the **Scene Analyzer** uses an LLM, and only to understand language — never
to produce tags. Every generated tag is looked up deterministically in a
data-only **Knowledge Base** (Version 1 ships a large Knowledge Base generated
from a real Danbooru tag vocabulary, so the tags are always valid and never
invented) and stays fully traceable:
to produce tags. Every generated tag is looked up in a data-only **Knowledge
Base** built from a real Danbooru tag vocabulary, so tags are always valid and
never invented. The Resolver both resolves concepts to tags and joins them into a
single flat prompt string, in resolution order. Every tag stays traceable:
```
Natural Language → Scene JSON → Knowledge Base Entry → Resolved Tag → Prompt
```
Version 2 adds an **opt-in** semantic (nearest-neighbour) fallback for concepts that
miss deterministic lookup. It is off by default, deterministic when enabled, and can
only return an entry that already exists in the Knowledge Base — so it never invents a
tag. Deterministic lookup always wins.
---
## What Version 2 changed
Version 1 proved the compiler works. Version 2 is about making it **know more and
ask less** — without giving up a single guarantee.
### Know more
The V1 compiler was honest but narrow: a concept missing from the Knowledge Base
was simply dropped, and the Knowledge Base only grew by hand.
- **The Knowledge Base grows itself.** A fully automated pipeline regenerates it
from committed Danbooru snapshots — generate candidates, ingest aliases and
implications, auto-validate, scan for conflicts, write. There is **no approval
gate**: an automation that stops to ask a human is an automation that doesn't run.
- **Near-misses are caught, not dropped.** An **opt-in** semantic (nearest-neighbour)
fallback resolves concepts that miss exact lookup. It is off by default,
deterministic when enabled, and can only return an entry that *already exists* in
the Knowledge Base — so it can never invent a tag. Deterministic lookup always wins.
- **Detail stops leaking.** The compiler used to silently discard parts of what you
wrote. Now modifiers survive (`open white shirt` → `white shirt` **and**
`open shirt`), every item of a list is transcribed, and relationships are kept
rather than flattened to a noun (`money in her hand` → `holding money`, not just
`money`). The same fidelity applies to explicit content — nothing is quietly
softened or skipped.
### Ask less
V1 exposed almost every internal as a node or a widget. That is honest, but it
pushes the compiler's internal shape onto the user.
- **Configuration lives in one place.** All settings are on the **Configuration**
node; the stage nodes take a single optional `config` connection. The analyzer
model used to be set in two disconnected places — now it's set once.
- **Fewer nodes.** Stages that carried no real decisions were folded away: the
Category Splitter and Prompt Builder collapsed into the Resolver (V1.1), and the
Knowledge Base Loader collapsed into the Configuration node (V2.1). Eight nodes
became five.
- **Don't ask what the system already knows.** The Knowledge Base ships inside the
package, so its path is no longer a question. Options that aren't ready or aren't
really user-facing (prompt target, separator, hand-written system prompts) are not
exposed — they keep working defaults instead.
- **Plain language.** Every input has a tooltip written for a user, not for a compiler
engineer.
### What did not change
Determinism. Every V2 addition is opt-in, bounded to the existing Knowledge Base,
and reproducible: the same Scene JSON, Knowledge Base, and configuration always
compile to the same prompt. Knowledge stays data, never code. Nothing is invented.
---
## Key principles
- **Determinism first** — the compiler core is deterministic: a given Scene JSON + Knowledge Base + config always produces the same output, with no random seeds. (The one non-deterministic step is the LLM understanding the language up front; everything after it is reproducible.)
- **Determinism first** — a given Scene JSON + Knowledge Base + config always produces the same output, with no random seeds. (The one non-deterministic step is the LLM understanding the language up front; everything after it is reproducible.)
- **No hallucinations** — if it isn't in the description, it isn't in the output. Unknown concepts are reported, never guessed.
- **Knowledge is data** — every concept→tag mapping lives in the Knowledge Base, never in code.
- **Fidelity** — described detail must survive to the prompt, or be reported. Silence is a bug.
- **Traceability** — every tag can be explained back to the sentence it came from.
- **Separation of concerns** — each stage does exactly one job and can be tested on its own.
- **Nodes are interfaces** — ComfyUI nodes are thin wrappers; all logic lives in the compiler package.
- **Automation without gates** — the pipeline runs end to end with zero required human input.
- **Nodes are interfaces** — ComfyUI nodes are thin wrappers; all logic lives in the compiler package, and settings live on one node.
Version 1 targets the **Illustrious** model family only. The architecture is
model-independent so future versions can add Pony, Flux, NoobAI, and others
Version 2 targets the **Illustrious** model family. The architecture is
model-independent, so future versions can add Pony, Flux, NoobAI, and others
without changing the compiler core.
---
## Nodes
Scene Compiler ships as a ComfyUI custom-node package. It is a toolbox, not a
fixed workflow — every node can be used independently.
Scene Compiler ships as a ComfyUI custom-node package of **five** nodes. It is a
toolbox, not a fixed workflow — every node can be used independently.
### Pipeline nodes
| Node | Input | Output |
| Node | Inputs | Outputs |
|---|---|---|
| **Scene Analyzer** | Natural language, 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) |
| **Scene Analyzer** | `natural_language`, `config` *(optional)* | `scene`, `warnings`, `errors`, `raw` |
| **Scene Validator** | `scene`, `config` *(optional)* | `scene`, `warnings`, `errors`, `raw` |
| **Resolver** | `scene`, `knowledge_base`, `config` *(optional)* | `prompt`, `warnings`, `errors`, `json` |
The Resolver is the final stage: it resolves concepts to Knowledge Base tags and
joins them into one flat `prompt` string. Its `json` output carries the traceable
resolved tags so a translation problem is inspectable.
### Support nodes
- **Debug Viewer** — inspect any intermediate state (Scene JSON, Resolved Tags, categories, warnings, errors).
- **Configuration Node** — the single place for compiler settings; it also loads the Knowledge Base from the configured path and emits it (as a `knowledge_base` output) for the Resolver, so there is no separate loader node.
| Node | Inputs | Outputs |
|---|---|---|
| **Configuration** | all compiler settings (see below) | `config`, `knowledge_base`, `warnings`, `errors` |
| **Debug Viewer** | `scene`, `warnings`, `errors` *(all optional)* | `report` |
- **Configuration** is the single place for compiler settings *and* the Knowledge
Base loader: it reads the Knowledge Base that ships with the package and emits it
on its `knowledge_base` output, which you wire into the Resolver. Bump its
`knowledge_base_reload` counter after editing the Knowledge Base to re-read it.
- **Debug Viewer** is read-only; connect any intermediate state to inspect it.
A typical graph:
```
Configuration ─ config ──────────► Scene Analyzer / Scene Validator / Resolver
└ knowledge_base ───► Resolver
Scene Analyzer → Scene Validator → Resolver → (your image workflow)
```
### Knowledge Base Editor (optional web tool)
Version 2 adds an optional browser editor for curated Knowledge Base entries, served
by ComfyUI at `http://127.0.0.1:8188/scene-compiler/kb`. It offers create/edit/delete
with live validation and atomic, format-safe saves. It is entirely off the compile
critical path — the compiler never depends on it.
Not a node. Version 2 adds an optional browser editor for curated Knowledge Base
entries, served by ComfyUI at `http://127.0.0.1:8188/scene-compiler/kb`. It offers
create/edit/delete with live validation and atomic, format-safe saves. It is the
*only* manual surface in the project and is entirely off the compile critical path —
the compiler never depends on it.
---
@@ -120,12 +185,17 @@ instance for language understanding; the rest of the pipeline runs fully offline
## Quick start
1. Add a **Scene Analyzer** node and type a description, e.g.
1. Add a **Configuration** node (it also loads the Knowledge Base).
2. Add a **Scene Analyzer** and type a description, e.g.
*"A blonde girl wearing a white dress hugs a young man while walking in the rain."*
2. Connect **Scene Analyzer → Scene Validator → Resolver**.
3. Wire the **Resolver**'s `prompt` output into your image-generation workflow
3. Wire **Scene Analyzer → Scene Validator → Resolver**, and connect Configuration's
`config` to each stage and its `knowledge_base` to the Resolver.
4. Send the **Resolver**'s `prompt` output into your image-generation workflow
(e.g. EasyIllustrious).
4. Use the **Debug Viewer** on any connection to inspect the intermediate state.
5. Drop a **Debug Viewer** on any connection to inspect the intermediate state.
A ready-made graph is in
[`examples/workflows/scene_compiler_pipeline.json`](examples/workflows/scene_compiler_pipeline.json).
Given the example above, the compiler extracts `female`, `blonde hair`,
`white dress`, `male`, the interaction `hug`, and environment `rain` — and
@@ -144,14 +214,20 @@ Full documentation lives in the **[Wiki](../../wiki)**:
- [Scene JSON & Schemas](../../wiki/Scene-JSON-and-Schemas)
- [Scene Analyzer](../../wiki/Scene-Analyzer)
- [Knowledge Base](../../wiki/Knowledge-Base)
- [Resolver, Categories & Prompt Builder](../../wiki/Resolver-Categories-and-Prompt-Builder)
- [Resolver & Prompt](../../wiki/Resolver-and-Prompt)
- [ComfyUI Nodes](../../wiki/ComfyUI-Nodes)
- [Configuration, Errors & Logging](../../wiki/Configuration-Errors-and-Logging)
- [Development, Testing & Contributing](../../wiki/Development-Testing-and-Contributing)
- [Roadmap](../../wiki/Roadmap)
- [Glossary & Reference](../../wiki/Glossary-and-Reference)
The complete normative specification is [`MASTER_SPEC.md`](../MASTER_SPEC.md).
In-repo notes live in [`docs/`](docs/) — see [`docs/nodes.md`](docs/nodes.md) for the
node reference and [`docs/knowledge_base_build.md`](docs/knowledge_base_build.md) for
how the Knowledge Base is regenerated.
[`MASTER_SPEC.md`](../MASTER_SPEC.md) is the original design specification. It records
the V1 design intent; where it and the shipped code disagree, the code and this
documentation win.
---
@@ -160,15 +236,15 @@ The complete normative specification is [`MASTER_SPEC.md`](../MASTER_SPEC.md).
- **Version 1 — Deterministic Compiler Foundation** *(done — v1.0.0 / v1.1.0)*: the
complete deterministic pipeline for Illustrious, plus Ollama integration, Knowledge
Base, Debug Viewer, and regression tests.
- **Version 2 — Semantic Resolution** *(done on `main`)*: opt-in semantic/embedding
fallback search, Knowledge Base editor, automatic Knowledge Base builder, Knowledge
Base versioning, concept fidelity, and performance — determinism preserved.
(Analyzer localization was dropped as unnecessary.)
- **Version 2 — Semantic Resolution** *(done — v2.0.0 / v2.1.0)*: opt-in
semantic/embedding fallback, automatic Knowledge Base builder, Knowledge Base
versioning and editor, concept fidelity, performance, and the node/configuration
consolidation — determinism preserved. (Analyzer localization was dropped as
unnecessary.)
- **Version 3 — Extensible Compiler Platform**: multi-model Resolvers, a plugin
system, multiple Analyzer backends, and a standalone Compiler SDK.
- **Version 4 — Consolidation**: tidy-up and a single unified node that runs the
whole pipeline, since most stage nodes carry little configuration. The granular
nodes stay available for debugging.
- **Version 4 — Consolidation**: a single unified node that runs the whole pipeline,
continuing the V2 consolidation. The granular nodes stay available for debugging.
See the [Roadmap](../../wiki/Roadmap) for details.
@@ -176,7 +252,8 @@ See the [Roadmap](../../wiki/Roadmap) for details.
## Contributing
Contributions are welcome — especially Knowledge Base entries. Please read the
Contributions are welcome — especially Knowledge Base entries. Please read
[CONTRIBUTING.md](CONTRIBUTING.md) and the
[Development, Testing & Contributing](../../wiki/Development-Testing-and-Contributing)
guide first. Core rule: **never hardcode knowledge, and never break determinism.**
docs/README.md
+14 -5
View File
@@ -1,13 +1,22 @@
# Documentation
Project documentation is maintained primarily in the
[GitHub Wiki](https://github.com/kunail0804/ComfyUI-Scene-Compiler/wiki), and the
authoritative specification is [`MASTER_SPEC.md`](../MASTER_SPEC.md) at the
repository root.
[GitHub Wiki](https://github.com/kunail0804/ComfyUI-Scene-Compiler/wiki).
[`MASTER_SPEC.md`](../MASTER_SPEC.md) at the repository root is the original design
specification: it records the Version 1 design intent and is kept for reference.
Where it and the shipped code disagree, **the code and this documentation win** —
V1.1 and V2 changed parts of the pipeline (see the [Roadmap](https://github.com/kunail0804/ComfyUI-Scene-Compiler/wiki/Roadmap)).
This `docs/` directory holds documentation that is **not** part of the wiki —
for example design notes, developer guides, and generated references added in
later phases.
developer guides and generated references.
## In this directory
- [`nodes.md`](nodes.md) — the ComfyUI node reference (inputs, outputs, types).
- [`knowledge_base_build.md`](knowledge_base_build.md) — how the Knowledge Base is regenerated.
- [`benchmarks.md`](benchmarks.md) — performance baselines.
- [`definition_of_done.md`](definition_of_done.md) — the Version 1 completion record.
## Where to look
docs/definition_of_done.md
+21 -11
View File
@@ -1,8 +1,15 @@
# Version 1 — Definition of Done
Status of the MASTER_SPEC §7.8 Definition of Done. Items marked **auto** are
verified by the automated test suite / CI; **manual** items require a ComfyUI
visual check before the release is tagged.
verified by the automated test suite / CI; **manual** items required a ComfyUI
visual check before the release was tagged.
> **All items are met; Version 1 shipped as `v1.0.0` / `v1.1.0`.** This page is kept
> as the V1 completion record. The *evidence* column below is updated to point at the
> code as it stands today: V1.1 removed the separate Category Splitter and Prompt
> Builder stages (their work moved into the Resolver), and V2 folded the Knowledge
> Base Loader into the Configuration node. For the current pipeline see
> [`nodes.md`](nodes.md).
| # | Definition-of-Done item | Status | Evidence |
|---|---|---|---|
@@ -10,18 +17,21 @@ visual check before the release is tagged.
| 2 | Scene JSON validates successfully | ✅ auto | Scene Validator (`compiler/validator/`) — `tests/validator/`. |
| 3 | Concepts resolve correctly | ✅ auto | Illustrious Resolver (`compiler/resolver/`) — `tests/resolver/`. |
| 4 | Illustrious tags are generated | ✅ auto | Resolver tag generation + expansion — `tests/resolver/`, golden tests. |
| 5 | Tags are categorized | ✅ auto | Category Splitter (`compiler/splitter/`) — `tests/test_category_splitter.py`. |
| 6 | Prompt outputs are generated | ✅ auto | Prompt Builder (`compiler/builder/`) — `tests/test_prompt_builder.py`, integration + golden tests. |
| 5 | Tags are categorized | ✅ auto | Every resolved tag carries the category of its Knowledge Base entry, surfaced in the Resolver's `json` output (`compiler/resolver/`) — `tests/resolver/`. Since V1.1 the category is traceability metadata and no longer splits the output. |
| 6 | Prompt outputs are generated | ✅ auto | The Resolver joins the resolved tags into one flat prompt string (`compiler/resolver/`) — `tests/resolver/`, integration + golden tests. |
| 7 | All automated tests pass | ✅ auto | `pytest` green on Python 3.11 & 3.12 in CI (unit, integration, golden, performance). |
| 8 | Documentation is complete | ✅ auto/manual | README, `docs/`, CONTRIBUTING, `knowledge_base/README.md`, wiki; `tests/test_docs_consistency.py` guards node references. |
| 9 | Example workflows execute without modification | ⏳ manual | `examples/scenes/*` compile to their documented outputs (`tests/test_examples.py`); the ComfyUI workflow (`examples/workflows/scene_compiler_pipeline.json`) needs a load-and-run check in ComfyUI. |
| 10 | No mandatory feature depends on prompt generation | ✅ auto | Reserved Negative/Scene outputs and Style/Quality categories are always empty in V1; nothing performs automatic prompt engineering. |
| 10 | No mandatory feature depends on prompt generation | ✅ auto | The Style and Quality categories are reserved for workflow integration and are not generated; nothing performs automatic prompt engineering or beautification. |
| 11 | No compiler stage performs semantic hallucination | ✅ auto | Unknown concepts are reported (SC0001) and never invented; the Analyzer prompt forbids invention; the Resolver only looks up the Knowledge Base. Golden tests pin unknown/ambiguous behaviour. |
## Remaining before tagging `v1.0.0`
## Outcome
- **ComfyUI visual verification (manual):** load the package in ComfyUI, confirm
all eight nodes appear under *Scene Compiler*, and run the example workflow
end to end (item 9).
- **Tag & release:** once the visual check passes, tag `v1.0.0` (SemVer, §28) and
publish the GitHub release. This step is intentionally deferred to a human.
Both remaining steps were completed: the package was verified visually in ComfyUI
(all nodes appear under *Scene Compiler* and the example workflow runs end to end),
and `v1.0.0` was tagged and published, followed by `v1.1.0`.
The package now ships **five** nodes — Scene Analyzer, Scene Validator, Resolver,
Configuration, and Debug Viewer — after V1.1 and V2 consolidated the pipeline. The
same manual check (load in ComfyUI, run the example workflow) is repeated before
each release.
docs/nodes.md
+67 -24
View File
@@ -2,46 +2,89 @@
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`, `RESOLVED_TAGS`,
`CATEGORY_MAP`, `KNOWLEDGE_BASE`, and `COMPILER_CONFIG`.
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.
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 **`raw`** string output — a JSON dump of that
node's data output — for inspecting the pipeline (wire it into a text/preview
node). The Knowledge Base Loader's `raw` summarizes the loaded entries. A
relative Knowledge Base `path` is resolved against the installed package, so the
default `knowledge_base/` works regardless of ComfyUI's working directory.
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) |
| **Scene Validator** | `scene` (SCENE), `config` (COMPILER_CONFIG, optional) | `scene` (SCENE), `warnings` (STRING), `errors` (STRING) |
| **Resolver** | `scene` (SCENE), `knowledge_base` (KNOWLEDGE_BASE), `config` (COMPILER_CONFIG, optional) | `resolved_tags` (RESOLVED_TAGS), `warnings` (STRING), `errors` (STRING) |
| **Category Splitter** | `resolved_tags` (RESOLVED_TAGS) | `category_map` (CATEGORY_MAP), `warnings` (STRING), `errors` (STRING) |
| **Prompt Builder** | `category_map` (CATEGORY_MAP), `config` (COMPILER_CONFIG, optional) | one STRING per category (`character`, `appearance`, `hair`, `face`, `eyes`, `expression`, `body`, `clothing`, `accessories`, `pose`, `action`, `interaction`, `objects`, `environment`, `camera`, `lighting`, `style`, `quality`, `miscellaneous`) plus reserved `negative` and `scene` (STRING) |
| **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 **Category Splitter** produces the intermediate Category Map; the per-category
prompt strings are produced by the **Prompt Builder**.
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** | the settings a user needs to touch: analyzer (model, temperature, retries, timeout), resolver (strict mode, aliases, expansion, depth, `include_nsfw`, optional `resolver_knowledge_base_version`), validator (`allow_unknown_fields`), `prompt_remove_duplicate_tags`, the opt-in semantic-fallback settings, debug, and `knowledge_base_reload`. The Knowledge Base path is fixed (not user-facing); `prompt_target`/`prompt_separator` are not exposed (fixed defaults). | `config` (COMPILER_CONFIG), `knowledge_base` (KNOWLEDGE_BASE), `warnings` (STRING), `errors` (STRING) |
| **Debug Viewer** | `scene` (SCENE, optional), `resolved_tags` (RESOLVED_TAGS, optional), `category_map` (CATEGORY_MAP, optional), `warnings` (STRING, optional), `errors` (STRING, optional) | `report` (STRING) |
| **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 place for compiler settings. Its `config`
output feeds the optional `config` input of the Scene Analyzer, Validator, and
Resolver, and it also **loads the Knowledge Base** from the configured path/version
and emits it on its `knowledge_base` output (wired into the Resolver's
`knowledge_base` input) — so the Knowledge Base directory is entered in one place.
There is no separate Knowledge Base Loader node. Bump `knowledge_base_reload` to
force a fresh read (no automatic file watching).
- 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).
examples/README.md
+9 -6
View File
@@ -8,12 +8,15 @@ Ready-to-use examples for Scene Compiler.
is a ComfyUI workflow wiring the full pipeline:
```
Configuration ─┬─▶ Scene Validator ─▶ Resolver ─▶ Category Splitter ─▶ Prompt Builder
├──────────────────────▶ (config) (config) ◀┘
Knowledge Base Loader ─────────────────▶ Resolver (knowledge_base)
Scene Analyzer ─▶ Scene Validator (scene)
Configuration ─ config ──────────► Scene Analyzer / Scene Validator / Resolver
└ knowledge_base ───► Resolver
Scene Analyzer → Scene Validator → Resolver → prompt
```
The Configuration node supplies every setting *and* loads the Knowledge Base, so it
is the only node you normally need to touch.
Load it in ComfyUI (**Load** → pick the file). The Scene Analyzer requires a local
[Ollama](https://ollama.com) instance; the rest of the pipeline runs offline.
@@ -29,8 +32,8 @@ to with the shipped Knowledge Base and default configuration:
| [`couple_interaction`](scenes/couple_interaction.scene.json) | two characters, an interaction, and an expansion (`school_uniform → blazer, pleated_skirt`) |
The `*.prompts.json` outputs are verified by `tests/test_examples.py`. To skip the
Analyzer and compile a Scene JSON directly, feed it through the Validator →
Resolver → Category Splitter → Prompt Builder nodes (or the compiler API).
Analyzer and compile a Scene JSON directly, feed it through the Scene Validator →
Resolver nodes (or the compiler API).
> **Note:** the workflow JSON is provided as a starting point; verify it loads in
> your ComfyUI and re-save if ComfyUI adjusts the layout.
tests/test_docs_consistency.py
+15 -7
View File
@@ -29,17 +29,25 @@ def test_docs_mention_every_node(doc: Path) -> None:
def test_node_reference_covers_inter_stage_types() -> None:
# The live inter-stage types. RESOLVED_TAGS and CATEGORY_MAP were retired with
# the Category Splitter and Prompt Builder in V1.1, so the reference must not be
# required to mention them.
text = (REPO_ROOT / "docs" / "nodes.md").read_text(encoding="utf-8")
for type_name in (
"SCENE",
"RESOLVED_TAGS",
"CATEGORY_MAP",
"KNOWLEDGE_BASE",
"COMPILER_CONFIG",
):
for type_name in ("SCENE", "KNOWLEDGE_BASE", "COMPILER_CONFIG"):
assert type_name in text
def test_node_reference_does_not_resurrect_removed_nodes() -> None:
"""Guard the reference against listing nodes that no longer ship.
Matches table rows only, so prose explaining that a node was removed is fine.
"""
text = (REPO_ROOT / "docs" / "nodes.md").read_text(encoding="utf-8")
for removed in ("Knowledge Base Loader", "Category Splitter", "Prompt Builder"):
row = f"| **{removed}**"
assert row not in text, f"docs/nodes.md still lists the removed {removed!r} node"
def test_contributing_links_the_knowledge_base_guide() -> None:
text = (REPO_ROOT / "CONTRIBUTING.md").read_text(encoding="utf-8")
assert "knowledge_base/README.md" in text