Repository navigation
Home
A deterministic prompt compiler for ComfyUI. It turns a plain-language scene description into a clean, valid Illustrious tag prompt — without an LLM inventing anything.
The language model understands the scene; the compiler generates the prompt.
Natural Language
→ Scene Analyzer → Scene JSON
→ Scene Validator → Validated Scene JSON
→ Resolver → Prompt
Only the Scene Analyzer uses an LLM, and only to understand language. Everything after it is deterministic, data-driven, and fully traceable. It targets the Illustrious model family; the architecture is built to add more without changing the core.
Status: Version 2 released (
v2.1.0); the deterministic Version 1 pipeline shipped in v1.0.0 / v1.1.0. See the Roadmap and the issue tracker for progress.
What Version 2 changed: the compiler knows more (the Knowledge Base grows itself, an opt-in Knowledge-Base-bounded semantic fallback catches near-misses, and described detail stops leaking) and asks less (settings live on one node, eight nodes became five, and it no longer asks for what it already knows). Determinism is unchanged — see Overview & Vision → How Version 2 evolved this.
| If you want to… | Read |
|---|---|
| Understand why the project exists | Overview & Vision |
| See what the compiler must deliver | Requirements & Success Criteria |
| Understand how it works | Architecture & Pipeline |
| Add concepts / tags | Knowledge Base |
| Build or contribute code | Development, Testing & Contributing |
| Look up a term or error code | Glossary & Reference |
- Overview & Vision — purpose, the problem with LLM prompt generation, how V2 evolved the philosophy, scope, non-goals, and the 15 design principles.
- Requirements & Success Criteria — functional (FR) and non-functional (NFR) requirements, and the Definition of Done.
- Architecture & Pipeline — the three-stage pipeline, invariants, immutability, the Compiler Result wrapper, and the failure policy.
- Data Model — Scene, Character, Concept, Interaction, Object, Resolved Tag, Prompt.
- Scene JSON & Schemas — the Intermediate Representation grammar and the nine JSON Schemas.
- Scene Analyzer — the only LLM stage, the official system prompt, and the Scene Validator.
- Knowledge Base — the data-only source of truth, entry format, aliases, expansions, and the construction guide.
- Resolver & Prompt — deterministic tag resolution and translation into one flat prompt.
- ComfyUI Nodes — the pipeline nodes and support nodes.
- Configuration, Errors & Logging — severity levels, message codes, debug levels, and the config file.
- Development, Testing & Contributing — repository structure, coding guidelines, testing strategy, and mandatory rules for engineering agents.
- Roadmap — the 8 development phases and the V1 → V2 → V3 long-term plan.
- Glossary & Reference — canonical vocabulary, error codes (SC0001–SC0014), and the category reference.
- Determinism first — same input → same output, always. No random seeds.
- No hallucinations — nothing appears that wasn't described. Unknown concepts are reported, never guessed.
- Knowledge is data — every mapping lives in the Knowledge Base, never in code.
-
Traceability — every tag explains itself:
Natural Language → Scene JSON → Knowledge Base Entry → Resolved Tag → Prompt. - Nodes are interfaces — all logic lives in the compiler package; nodes are thin wrappers.
The complete normative specification is MASTER_SPEC.md in the main repository.
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.