kunail0804-ComfyUI-Scene-Compiler/knowledge_base

Knowledge Base

The Knowledge Base is data only — no executable code (MASTER_SPEC §15). It is the single source of truth for how semantic concepts map to Illustrious tags. The compiler loads every file here once during initialization.

File organization

Concepts are split into multiple JSON files by domain, for readability and maintenance (§15.3). The compiler loads and merges all of them:

knowledge_base/
  appearance.json   clothing.json   anatomy.json   expressions.json
  poses.json        actions.json    interactions.json  objects.json
  environments.json camera.json     lighting.json   quality.json  style.json

Domain files are a maintenance convenience; a concept's category (below), not the file it lives in, determines its behaviour.

File format

Each file is a JSON array of entries:

[
  { "id": "long_hair", "tags": ["long hair"], "category": "hair" },
  { "id": "blue_eyes", "tags": ["blue eyes"], "category": "eyes" }
]

A complete worked example (with an alias and an expansion) is in examples/knowledge_base.example.json.

Entry fields

Each entry validates against the knowledge_base_entry schema (schemas/json/knowledge_base_entry.schema.json).

Field	Required	Rule
id	yes	Canonical ID: lowercase snake_case, globally unique across the whole Knowledge Base.
tags	yes	The Illustrious tags this concept generates. At least one. Order is preserved.
category	yes	Exactly one of the 19 canonical categories (see below).
aliases	no	Alternative expressions resolving directly to this entry (no alias→alias chains). Globally unique, and must not collide with any id.
expand	no	Additional canonical ids automatically added during resolution. References canonical ids only, never raw tags; targets must exist.
deprecated	no	Marks an obsolete concept; it keeps working but the compiler emits a warning.
notes	no	Free-form documentation for contributors; ignored during compilation.

Contributor rules

• id uniqueness — every canonical id is unique across all files.
• alias uniqueness — every alias is unique across all files and never equal to any id; aliases resolve directly to their entry (no chains).
• Tag order — the order of tags is significant and preserved in output.
• Category — must be one of the 19 categories; the authoritative set is defined once in compiler/common/categories.py.
• Expansion — expand lists canonical ids only; every target must exist.
• At least one tag — every entry generates one or more tags.

Per-entry structure is enforced by the entry schema. Cross-entry rules (global uniqueness, expand targets exist, no alias chains) are enforced by the Knowledge Base validation tooling.

The 19 categories

character, appearance, hair, face, eyes, expression, body, clothing, accessories, pose, action, interaction, objects, environment, camera, lighting, style, quality, miscellaneous.

style and quality are reserved for workflow integration (not generated automatically in V1); miscellaneous is a fallback that should stay nearly empty.