Files

T

07b0f9a18b feat(knowledge-base): define KB file format, entry rules, and categories (#8 ) (#51 )

Formalize the Knowledge Base on-disk format and tighten the entry schema per
MASTER_SPEC §15.3-§15.10, §18.2.

- compiler/common/categories.py: single source of truth for the 19 canonical
  categories (lowercase identifiers of the §18.2 list) plus is_valid_category.
- knowledge_base_entry.schema.json (v1.1): category restricted to the 19; tags
  require at least one item; expand entries must be snake_case canonical ids;
  aliases uniqueItems.
- knowledge_base/README.md: by-domain file layout, the "each file is a JSON array
  of entries" format, and contributor field rules (id/alias global uniqueness,
  tag order, expansion targets, one-tag minimum).
- examples/knowledge_base.example.json: worked file demonstrating an alias and an
  expansion.

Cross-entry rules (global uniqueness, expand targets exist) are deferred to the
KB validation tooling (#9); this issue defines per-entry structure only.

Tests: 19-category constant and schema-enum consistency, entry validation
(category/tags/id/expand/unknown-field), and the worked example (array shape,
per-entry validity, alias+expansion present, expand targets resolve).

Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-07 19:23:50 +02:00

README.md

feat(knowledge-base): define KB file format, entry rules, and categories (#8 ) (#51 )

2026-07-07 19:23:50 +02:00

README.md

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 `id`s 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.