54b76ca75a
* fix: recover concept detail lost in resolver and harden analyzer parsing
Three shippability fixes for the v1 pipeline:
P2 (main): the Illustrious Resolver did exact-key KB lookup only, so any
compound concept the analyzer emits ("white summer dress", "black business
suit") missed and was dropped silently as SC0001. Add a deterministic
head-noun fallback (§17.2): on a miss, drop leading modifiers and look up the
longest remaining suffix ("white summer dress" -> "dress"). No tag/concept is
invented. Emits SC0019 (Concept Reduced) so the reduction is visible.
P1a: the analyzer required the entire model response to be a single JSON
document, so any surrounding prose ("Sure! Here is the scene:") failed parsing
and, with the prompt reused unchanged, every retry failed identically ->
empty output. Extract the first balanced top-level {...} object from
surrounding text (string-aware brace scan); the object bytes are unchanged and
must still validate, so this is unwrapping, not JSON repair.
P1b: the node's "raw" output was to_raw_json(result.data) -- a re-serialization
of the parsed Scene, so on failure it was empty and the model's actual text was
invisible. Capture the last raw model text in analyzer metadata and surface it
as the node's raw output.
Regenerated goldens: unknown_concepts "hologram jacket" now resolves to
"jacket" via head-noun fallback (intended).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add entry rating + resolver.include_nsfw gating
Foundations for the Danbooru-vocab KB: a per-entry `rating` (general|explicit,
default general) and a `resolver.include_nsfw` config flag (default false). The
resolver omits explicit-rated entries from lookup and expansion unless enabled,
so a gated concept is reported as unknown (SC0001). Schema, model, config, and
example config updated.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: generate KB from embedded Danbooru vocab (188 -> 16.4k tags)
Replace the coverage ceiling of the 188-entry hand KB by importing a large,
validated Danbooru tag vocabulary. This is the fix for the core "detail loss"
symptom: compound concepts the analyzer emits ("red dress", "sunflower field",
"train station platform") are now real tags that resolve instead of being
dropped.
- scripts/build_vocab.py: one-time dev step that filters the Raffle node's
categorized tag dump (drops artist/character/copyright/attribution categories
and subjective adjectives, keeps only id-pattern-valid tags) into a committed,
self-contained snapshot at data/danbooru_vocab.txt (16.4k tags).
- scripts/generate_kb_from_vocab.py: additive, non-destructive generator. Writes
knowledge_base/gen_<category>.json, mapping the Raffle categories to the 19
canonical categories and tagging NSFW categories rating=explicit. Skips any tag
already defined as a hand-curated id/alias, so the curated canonicalization
(female + aliases) and expansions (school_uniform -> blazer, pleated_skirt) are
preserved and always win.
Result: 16.4k additive entries + 188 curated. Plain natural-language concepts
now resolve broadly via curated aliases + head-noun fallback with no analyzer
prompt change; NSFW gated behind resolver.include_nsfw; golden and dataset tests
stay green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* style: ruff format build_vocab.py
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(security): drop untrusted CLI path in build_vocab (SonarCloud S8707)
The --source CLI argument fed an untrusted path to the file system (taint).
The script is a one-time dev step; hard-code the source path constant instead.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
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
iduniqueness — every canonicalidis unique across all files.aliasuniqueness — every alias is unique across all files and never equal to anyid; aliases resolve directly to their entry (no chains).- Tag order — the order of
tagsis 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 —
expandlists canonicalids 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.