Glossary and Reference

Glossary & Reference

Spec reference: MASTER_SPEC Appendices A–C.

Glossary

Canonical vocabulary, defined once and used consistently throughout the project.

Term	Definition
Scene Compiler	The deterministic prompt compiler.
Scene Analyzer	The stage that converts natural language into Scene JSON; the only component that uses an LLM.
Scene JSON	The Intermediate Representation (IR): a structured document of semantic concepts. The compiler's stable public interface.
Raw / Validated Scene JSON	Scene JSON as produced by the Analyzer / by the Scene Validator. Used only where the stage boundary matters.
Scene Validator	The stage that validates and normalizes Scene JSON before resolution.
Concept	The smallest semantic unit in Scene JSON (e.g. female, blonde hair). Never an Illustrious tag.
Knowledge Base (KB)	The data-only single source of truth mapping concepts to Illustrious tags.
Knowledge Base Entry	A single canonical record (id, aliases, tags, category, expand, rating, deprecated, notes).
Canonical ID	The unique snake_case id of a Knowledge Base Entry.
Alias	An alternative expression that resolves directly to a Canonical ID. Aliases never chain.
Expansion	Automatic inclusion of additional Canonical IDs referenced by an entry's expand field.
Resolver	The deterministic stage that converts concepts into Illustrious tags using the Knowledge Base.
Illustrious tag	A Danbooru-format tag valid for the Illustrious model family.
Resolved Tag	A generated Illustrious tag with full traceability metadata.
Category	One of the 19 semantic groups; carried on each Knowledge Base entry and Resolved Tag for traceability (it no longer splits the output in V1.1).
Prompt	The final compiler product: the Resolved Tags joined into one flat comma-separated string, in resolution order.
Compiler Result	The uniform wrapper (data, warnings, errors, metadata) returned by every stage.

Error & warning codes

Every compiler message carries a unique code. Codes are stable across patch versions.

Code	Severity	Title	Meaning
SC0001	Warning	Unknown Concept	A concept has no Knowledge Base Entry; it is reported and ignored.
SC0002	Error	Invalid Scene JSON	Scene JSON fails schema validation.
SC0003	Error	Circular Expansion	An expansion cycle was detected.
SC0004	Fatal	Knowledge Base Load Failure	The Knowledge Base could not be loaded or failed validation.
SC0005	Error	Duplicate Canonical ID	Two Knowledge Base Entries share an id.
SC0006	Warning	Deprecated Concept	A resolved concept is marked deprecated; migration is encouraged.
SC0007	Warning	Duplicate Tag Removed	A duplicate tag was removed after expansion.
SC0008	Error	Invalid Category	A tag or entry references a category outside the defined set.
SC0009	Error	Missing Required Field	A required field is absent from an intermediate document.
SC0010	Error	Schema Version Mismatch	A document declares an unsupported schema version.
SC0011	Error	Analyzer Schema Validation Failure	The Analyzer response failed Scene JSON validation after all retries.
SC0012	Fatal	Analyzer Unavailable	The Analyzer backend (e.g. Ollama) could not be reached.
SC0013	Error	Analyzer Timeout	The Analyzer did not respond within the configured timeout.
SC0014	Fatal	Invalid Configuration	The compiler configuration is invalid.
SC0015	Warning	Unexpected Field Removed	The Scene Validator removed a field not in the schema.
SC0016	Warning	Empty Concept Removed	An empty/whitespace-only concept was removed after trimming.
SC0017	Warning	Interaction Dropped	An interaction referencing a non-existent character was dropped.
SC0018	Error	Analyzer Unexpected Response	The Analyzer backend returned an HTTP error or an unexpected response shape.
SC0019	Warning	Concept Reduced	A compound concept was reduced to its head noun to resolve. Each dropped modifier is retried as a <modifier> <head-noun> compound and, when it resolves, emitted as its own tag (V2).
SC0020	Warning	Semantic Fallback	The opt-in semantic (nearest-neighbour) fallback resolved a concept that missed deterministic lookup, above semantic.min_similarity (V2).
SC0021	Warning	List Under-Transcription	A tag-list input produced fewer concepts than it has items — the Analyzer may have omitted list entries (V2, advisory).
SC0022	Warning	Candidate Rejected	The automatic Knowledge Base builder's auto-validation rejected a generated candidate entry (V2).

Codes SC0001–SC0014 are from the specification's Appendix B; SC0015+ are extensions added during implementation. Every message contains code, severity, title, description, and optional context.

Category reference

The 19 categories

Character, Appearance, Hair, Face, Eyes, Expression, Body, Clothing, Accessories, Pose, Action, Interaction, Objects, Environment, Camera, Lighting, Style, Quality, Miscellaneous. Full descriptions are on Resolver & Prompt.

Scene section → category mapping

A concept's final category is determined by the category field of its Knowledge Base Entry, not by the Scene JSON section it appears in. The Scene section constrains placement during analysis; the Knowledge Base assigns the output category during resolution.

Scene section	Typical output category / categories
identity	Character
appearance	Hair, Face, Eyes, Body, or Appearance (per Knowledge Base Entry)
clothing	Clothing
accessories	Accessories
pose	Pose
expression	Expression
actions	Action
interactions	Interaction
objects	Objects
environment	Environment
camera	Camera
lighting	Lighting
(workflow-supplied)	Style, Quality
(fallback)	Miscellaneous

Related pages

• Data Model
• Knowledge Base
• Configuration, Errors & Logging

---

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.