Skip to content
This repository was archived by the owner on Sep 23, 2026. It is now read-only.

Knowledge Base

Jump to bottom
kunail0804 edited this page Jul 19, 2026 · 5 revisions

Knowledge Base

Spec reference: MASTER_SPEC §15–16.

The Knowledge Base (KB) is the central source of knowledge used by the compiler. It defines how semantic concepts translate into valid Illustrious tags. It contains data only — no executable logic.

Philosophy: the single source of truth

Every Illustrious tag generated by the compiler must originate from the Knowledge Base. No module may hardcode or invent tag mappings. If a concept does not exist in the Knowledge Base, it cannot be resolved. The Knowledge Base separates semantic understanding (the Analyzer understands language) from model-specific knowledge (the Knowledge Base understands Illustrious).

Responsible for: canonical concepts, Illustrious tag mappings, aliases, category assignment, tag expansion, metadata, validation information.

Not responsible for: natural-language understanding, prompt optimization, prompt formatting, or scene analysis.

File organization

The Knowledge Base is organized into multiple JSON files by domain. The compiler loads every *.json file in the directory during initialization.

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
  gen_*.json        # generated from the Danbooru vocabulary (see below)

Two kinds of files live side by side:

  • Curated files (the named files above) — hand-authored canonical entries with aliases and expansions. These are the source of truth and always win.
  • Generated files (gen_<category>.json) — produced from a large Danbooru tag vocabulary by scripts/generate_kb_from_vocab.py (see Generated vocabulary).

Entry structure

Every entry represents exactly one canonical concept.

{
  "id": "female",
  "aliases": ["girl", "woman", "lady"],
  "tags": ["1girl"],
  "category": "character",
  "expand": [],
  "rating": "general",
  "deprecated": false,
  "notes": ""
}

Fields

  • id — unique Canonical ID, lowercase snake_case, unique across the whole KB (e.g. female, blonde_hair).
  • aliases — alternative expressions for the same concept. Aliases never generate tags directly; they resolve to the canonical entry and must be unique across the KB.
  • tags — the Illustrious tags generated by this concept. Tag order is preserved.
  • category — the primary semantic category (see category list). Unknown categories are invalid.
  • expand — optional list of additional Canonical IDs automatically added during resolution. References Canonical IDs, never raw tags.
  • rating — general (default) or explicit. Explicit-rated entries are hidden from resolution unless resolver.include_nsfw is enabled, so NSFW tags are opt-in.
  • deprecated — marks an obsolete concept. Deprecated concepts still work but emit warnings.
  • notes — optional contributor documentation; ignored during compilation.

Core concepts

Canonical concepts

Every real-world concept exists exactly once. female is one concept; girl, woman, and lady are aliases of it, not separate concepts.

Aliases

Aliases resolve deterministically and directly to a canonical concept — alias chains are forbidden:

girl → female → 1girl

Expansions

Some concepts imply additional concepts. Expansion is recursive and references Canonical IDs. Circular expansion is forbidden and must be detected during Knowledge Base loading.

school_uniform → blazer, pleated_skirt

Expansions must represent deterministic relationships only. school_uniform → blazer is valid; princess → castle is not — a princess does not necessarily imply a castle. Expansions never guess.

Validation rules

Every entry must satisfy: unique id; unique aliases; a known category; existing expansion targets; no circular expansions; at least one generated tag; and valid JSON.

Loading & reloading

The compiler loads the complete Knowledge Base during initialization; loading must fail if validation fails (partial loading is forbidden). In ComfyUI the Configuration node loads the Knowledge Base from its configured path/version and emits it for the Resolver (there is no separate loader node); bumping its knowledge_base_reload counter forces a fresh read. Automatic file watching is out of scope. The Knowledge Base is loaded once per process and reused across compilations (a V2 load-once cache; see Roadmap → Performance).

The Knowledge Base is versioned independently of the compiler — see Versioning.

Construction guide

The Knowledge Base represents meaning, not words and not prompts. Every entry should answer "What concept is being described?" rather than "What words did the user write?".

  • Choosing a Canonical ID — lowercase, English, singular where possible, readable, stable, snake_case, no spaces (looking_at_viewer, holding_hands). Avoid abbreviations and model-specific names.
  • Creating aliases — only when multiple expressions describe the same concept (lady → female, blond hair → blonde_hair). Aliases must not introduce ambiguity.
  • Creating new concepts — only when the meaning changes. cute_girl/beautiful_girl are subjective and should be avoided.
  • Composite & expansion concepts — combine ideas by expanding into simpler concepts (school_uniform → blazer, pleated_skirt), not by emitting many tags directly. Expansions must be deterministic.
  • Subjective / context-dependent / ambiguous: subjective concepts (beautiful, cute) must not exist in V1; context-dependent concepts must be made complete (holding_sword, not holding); ambiguous expressions (bat) must not resolve automatically — the compiler warns.
  • Category assignment — each concept belongs to exactly one primary category representing its semantic role (long_hair → Hair, blue_eyes → Eyes, white_dress → Clothing).
  • Granularity — prefer atomic concepts over large composites.
  • Unknown concepts & deprecation — unknown concepts are never silently ignored (warning). Entries are not deleted immediately; deprecated entries stay available and emit migration warnings.

Contributor checklist

Before adding an entry: Does the concept already exist? Could it be an alias? Should it expand into simpler concepts? Is the meaning deterministic? Is the category correct? Does it generate valid Illustrious tags? Will another contributor understand it a year from now? If any answer is uncertain, do not add the entry until clarified.

Generated vocabulary

Hand-authoring a Knowledge Base large enough to cover natural language is a never-ending task, and a tiny Knowledge Base is the main reason detail is lost (a concept with no entry is dropped). Version 1 therefore ships, alongside the curated entries, a large Knowledge Base generated from a real Danbooru tag vocabulary (~16k entries), so common concepts already resolve to valid tags.

Two scripts build it:

  • scripts/build_vocab.py — a one-time dev step that filters a Danbooru tag dump into data/danbooru_vocab.txt (dropping artist/character/copyright/attribution tags, subjective adjectives, and tags that cannot be a Canonical ID).
  • scripts/generate_kb_from_vocab.py — reads that snapshot and writes knowledge_base/gen_<category>.json, mapping each source category to one of the 19 canonical categories and marking NSFW categories rating: "explicit".

The merge is additive and curated-first: a generated tag is skipped whenever its id already exists as a curated id or alias, so canonicalization (female + aliases) and expansions (school_uniform → blazer, pleated_skirt) are always preserved.

Everything the Knowledge Base guarantees still holds: the vocabulary is a fixed set of real tags, so nothing is invented; the Analyzer proposes concepts and the Knowledge Base validates them.

Automatic builder (V2)

As of V2 the generated Knowledge Base is regenerated by a single, fully-automated pipeline with zero required human input and no approval gate (scripts/build_knowledge_base.py): generate candidates → ingest Danbooru aliases/implications (data/danbooru_aliases.txt, data/danbooru_implications.txt) → auto-validate (structural rules + confidence; SC0022 marks rejected candidates) → conflict-scan → write. Generated entries therefore now carry aliases and implications, so synonyms reach their canonical (long black stockings → thighhighs). See docs/knowledge_base_build.md.

Two standalone tools support it:

  • scripts/detect_kb_conflicts.py — a CI-gateable scan for id/alias collisions and conflicting mappings.
  • scripts/coverage_benchmark.py — a Knowledge Base coverage report.

Versioning (V2)

A Knowledge Base directory can ship a manifest.json (the new knowledge_base_manifest schema) recording the dataset's version and metadata. A project pins a specific dataset with resolver.knowledge_base_version (default null = use the shipped Knowledge Base as-is). An in-memory migration layer adapts older datasets to the current entry schema at load time — pinned files are never rewritten — and versions older than the minimum supported error clearly. The reference Knowledge Base loads with no adaptation.

Knowledge Base Editor (V2)

An optional web editor for curated entries is served by ComfyUI at http://127.0.0.1:8188/scene-compiler/kb. It offers create/edit/delete with live validation (reusing the authoritative kb_validation rules against both the candidate entry and the resulting whole-KB state, so invalid entries cannot be saved) and atomic, format-safe saves (temp + fsync + rename; only the edited entry changes, key order and trailing newline preserved). It is entirely off the compile critical path — the compiler never depends on the editor.

Related pages

A note on AI assistance

This project — its code, tests, and documentation — is built with heavy help from AI coding assistants and maintained by a solo author. AI makes mistakes: despite testing and review, parts of this may be inaccurate, out of date, or wrong. Treat it as a good-faith best effort, not authoritative truth — if the docs and the code disagree, the code wins. Please open an issue when something looks off.

Clone this wiki locally