Repository navigation
Scene Analyzer
Spec reference: MASTER_SPEC §12–14.
The Scene Analyzer transforms natural language into structured semantic information (Scene JSON). It is the only component permitted to use a Large Language Model. It extracts information; it never invents it. Its sole responsibility is language understanding — it knows nothing about Danbooru, Illustrious, Stable Diffusion, prompt engineering, or ComfyUI.
Must: parse natural language; identify characters, interactions, objects, environments, camera and lighting descriptions; extract explicit attributes; produce a valid Scene JSON document; preserve uncertainty.
Must not: produce Illustrious/Danbooru tags; guess or infer missing information; optimize or beautify prompts; recommend artistic choices; assign categories; or perform Knowledge Base lookup.
- Input: a single natural-language description (string).
- Output: a valid Scene JSON document conforming to the Scene schema. No Illustrious tags.
Version 1 uses Ollama. The implementation stays isolated from the compiler so replacing Ollama requires replacing only the Analyzer — no downstream component changes. The compiler must not depend on any specific language model.
-
Temperature: recommended
0.0— deterministic over creative. - Context window: the Analyzer should support long descriptions; the compiler must not assume a fixed context size.
- System prompt: the official prompt below defines behaviour.
- User prompt: forwarded without modification.
Only explicitly described information is extracted. These examples are normative:
| Input | Extracted concepts |
|---|---|
A blonde girl smiles. |
female, blonde hair, smile
|
A girl. |
female (no hair, eyes, expression, pose, or clothing) |
A beautiful girl smiles. |
female, smile (beautiful is subjective — ignored) |
A girl wearing an elegant white dress. |
female, white dress (elegant ignored) |
Subjective adjectives (beautiful, cute, elegant) and artistic language (masterpiece, best quality) are ignored. The Analyzer never infers missing information.
When ambiguity exists, the Analyzer preserves it. Given A person, the
result must not become male or female. Given Someone holds a bat, it must
not decide between animal and baseball bat; the ambiguous concept stays
visible, and the Resolver or a later stage may warn.
Each concept may optionally carry a confidence score (object form). Confidence is metadata only and must not influence deterministic compilation.
- If the Analyzer cannot confidently identify a concept, it omits it — an incorrect concept is worse than a missing one.
-
Full list transcription (V2): when the input is a list of tag-like words, the Analyzer must transcribe every item — none may be silently dropped. A deterministic post-parse check warns
SC0021(List Under-Transcription) when a tag-list input yields fewer concepts than it has items (prose with commas is excluded by a short-segment heuristic). This is part of concept fidelity (see Roadmap). -
Relations, positions, and conjunctions (V2): spatial, postural, and possessive relationships are preserved as their own concepts rather than collapsed to the bare noun — a held object also yields a
holding <object>concept (money in her hand→holding money+money, not justmoney), and body positions survive (hand on own hip,... in mouth). Every item joined by and / with / commas is a separate concept; later conjuncts are never dropped. This fidelity applies identically to explicit/NSFW input — nothing is abbreviated, softened, or omitted. The reference Knowledge Base already covers these relational tags (400+holding_*,hand on own hip,in mouth, …), so the relationship resolves end to end. - Every output must validate against the Scene schema; invalid JSON must not continue.
- Retries: a maximum of 3 is recommended; each retry reuses the original user prompt unchanged. The Analyzer must not repair JSON heuristically (surrounding prose/code fences may be unwrapped, but the JSON bytes are left intact). Because a local model is not perfectly deterministic even at temperature 0, a bad response can repeat; the retry orchestration therefore escalates the sampling temperature on retries only (the first attempt keeps the configured temperature, each retry adds a small step, capped) so a malformed attempt can self-recover — like a fresh manual re-run — without changing the prompt.
- Timeouts are configurable; failure to respond produces a compiler error.
- Errors distinguish model failure, connection failure, timeout, schema-validation failure, and unexpected response (see error codes).
The official System Prompt is part of the specification. Every compliant implementation should use it (or an equivalent).
- Core identity: "You are a Scene Analyzer… a deterministic semantic parser. Your only responsibility is extracting information explicitly present in the user's description."
- Primary objective: read → understand → extract explicit concepts → organize into Scene JSON → return valid JSON. Nothing else.
- Forbidden: never generate tags; never optimize/beautify/rewrite; never invent, guess, or assume defaults; never explain reasoning; never output anything outside the JSON document.
-
Explicit vs implicit: given
A queen, do not infer castle or crown. GivenA knight, do not invent sword, armor, or horse. - Subjective / artistic language: ignore beautiful, cute, cool, epic, masterpiece, best quality, award winning.
- Camera & lighting: extract only when explicitly present; never infer lighting from environment.
- Characters & relationships: every character is an independent object; interactions belong to the scene.
-
Output shape: the scene-level arrays (
objects,environment,camera,lighting) hold plain concept strings, exactly like the character concept arrays — never objects withid/conceptkeys. - Final objective: Understand. Extract. Structure. Never imagine, optimize, or create. Analyze.
The Scene Validator verifies and normalizes Scene JSON before resolution, guaranteeing that only structurally valid, normalized Scene JSON reaches the Resolver.
Terminology. Earlier drafts placed a "Validator" after the Resolver. That role is retired: pre-resolution validation happens here, and duplicate-tag removal happens in the Resolver.
- Input: Scene JSON (Analyzer output). Output: Validated Scene JSON.
- Must: validate against the Scene schema; normalize values; remove invalid fields; report warnings.
- Must not: create or guess concepts; generate tags; perform Knowledge Base lookup.
- Behaviour: invalid Scene JSON (malformed structure, missing required fields, wrong types) produces an error and stops. Recoverable issues (unexpected field, empty concept) produce warnings and continue. Validation order is stable.
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.