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
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).