Repository navigation
Data Model
Spec reference: MASTER_SPEC §9.
This page defines the internal data model manipulated by the compiler. The models are independent from JSON serialization, from ComfyUI, and from the implementation language. Their serialized form is defined in Scene JSON & Schemas.
Design constraints: every model is human-readable, JSON-serializable, versionable, immutable once produced, deterministic, and self-descriptive. Adding a documented field is allowed; removing or changing an existing field is a breaking change.
The root object; it contains every semantic element extracted from the description.
Scene
├── characters (array)
├── interactions (array)
├── objects (array)
├── environment (array of concepts)
├── camera (array of concepts)
├── lighting (array of concepts)
└── metadata (object)
One independent subject (human, creature, or identifiable subject). Each field contains semantic concepts, never Illustrious tags.
Character
├── id (integer — index within characters[])
├── identity (array of concepts) # what the character is
├── appearance (array of concepts) # permanent physical traits
├── clothing (array of concepts) # wearable items
├── accessories (array of concepts) # removable items
├── pose (array of concepts) # static body position
├── expression (array of concepts) # facial emotion
└── actions (array of concepts) # independent actions
-
id — 0-based position in
characters[]; referenced byinteractions[].participants. -
identity — what the character is (
female,male,child,cat,dragon,robot); never appearance. - appearance — permanent traits (hair, eyes, body, skin, ears, tail, horns, wings).
- clothing — wearable items (dress, shirt, pants, shoes, hat, gloves, cape, armor).
- accessories — removable items (necklace, glasses, earrings, backpack, watch, sword, shield).
- pose — static posture (standing, sitting, kneeling, lying, jumping).
- expression — facial emotion (smile, sad, angry, surprised, crying, blushing).
- actions — independent actions (reading, eating, sleeping, writing, pointing). Never interactions.
Only id is required; every other field may be an empty array. Unknown
information is omitted, never invented.
The smallest semantic unit. In Scene JSON section arrays a concept may be:
-
String form:
"female". -
Object form (optional confidence):
{ "name": "female", "confidence": 0.98 }.
Full internal model:
Concept
├── name (string — required)
├── category (string — optional until validation)
├── source (string — optional; origin sentence/field)
└── metadata (object — optional; e.g. confidence)
Concepts are resolved later by the Resolver; they are never Illustrious tags. Confidence is metadata only and must not influence deterministic compilation.
A relationship between two or more characters. Interactions belong to the scene, never to an individual character.
Interaction
├── participants (array of Character id)
└── concept (string — e.g. "holding hands")
participants must reference existing Character id values; participant order
should remain stable.
An independent scene element. Objects may optionally reference an owning character, but ownership is not required in Version 1. An object entry contains semantic concepts (and may carry attributes such as colour).
Each is an array of semantic concepts:
- Environment — location and global conditions (forest, classroom, beach; rain, sunset, spring).
- Camera — how the scene is viewed (close-up, wide shot, low angle). Only when explicitly described.
- Lighting — light conditions (sunset, moonlight, studio lighting, backlighting). Only when explicitly described.
Compiler information such as language, Analyzer version, compiler version, timestamp, schema version, and warnings. Metadata must not affect compilation.
A generated Illustrious tag. Immutable and traceable to its origin.
Resolved Tag
├── tag (string — the Illustrious tag)
├── category (string)
├── source_concept (string — the originating concept)
└── knowledge_base_entry (Canonical ID of the source entry)
The final compiler product is a single flat prompt string: the resolved tags joined in resolution order, comma-separated. It is produced by the Resolver (there is no separate Category Map or per-category Prompt Output in V1.1).
Every model carries a schema version. Breaking changes increment the major version; backward-compatible additions increment the minor version.
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.