From 5f2f0b7ff287c2bd5f5507e529d731c4d6e568ca Mon Sep 17 00:00:00 2001 From: Crespin Alexandre <114501859+kunail0804@users.noreply.github.com> Date: Sun, 19 Jul 2026 15:11:04 +0200 Subject: [PATCH] docs: overhaul repo documentation for V2 (#152) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Co-authored-by: Claude Opus 4.8 --- README.md | 181 +++++++++++++++++++++++---------- docs/README.md | 19 +++- docs/definition_of_done.md | 32 ++++-- docs/nodes.md | 91 ++++++++++++----- examples/README.md | 15 +-- tests/test_docs_consistency.py | 22 ++-- 6 files changed, 255 insertions(+), 105 deletions(-) diff --git a/README.md b/README.md index 026d308..620d934 100644 --- a/README.md +++ b/README.md @@ -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.** diff --git a/docs/README.md b/docs/README.md index e7b0729..3ae232f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/definition_of_done.md b/docs/definition_of_done.md index d72ff1b..1cd7ec0 100644 --- a/docs/definition_of_done.md +++ b/docs/definition_of_done.md @@ -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. diff --git a/docs/nodes.md b/docs/nodes.md index c822f43..5fc2acb 100644 --- a/docs/nodes.md +++ b/docs/nodes.md @@ -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). diff --git a/examples/README.md b/examples/README.md index d58e7de..f767f78 100644 --- a/examples/README.md +++ b/examples/README.md @@ -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. diff --git a/tests/test_docs_consistency.py b/tests/test_docs_consistency.py index 99b65b7..5cb3d5d 100644 --- a/tests/test_docs_consistency.py +++ b/tests/test_docs_consistency.py @@ -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