Repository navigation
Requirements and Success Criteria
Spec reference: MASTER_SPEC §4–7.
| ID | Requirement | Summary |
|---|---|---|
| FR-001 | Natural Language Input | Accepts natural language as primary input; never requires manual Danbooru tags. |
| FR-002 | Scene Understanding | Extracts explicit characters, appearance, clothing, interactions, environment, objects, camera, lighting. Camera and lighting only if explicitly mentioned. |
| FR-003 | Intermediate Representation | Converts every scene into Scene JSON. Only the Analyzer may consume natural language. |
| FR-004 | Deterministic Resolution | Every concept is resolved through the Resolver using the Knowledge Base. No AI model generates tags. |
| FR-005 | Scene & Tag Validation | Scene JSON is validated before resolution; resolved tags satisfy existence, duplicate-freedom, alias resolution, and category consistency. |
| FR-006 | Category Assignment | Every resolved tag carries the category of its Knowledge Base Entry for traceability. Since V1.1 the output is one flat prompt; categories no longer split it. |
| FR-007 | Prompt Generation | The Resolver translates the resolved tags into one flat prompt string; it never modifies tags. |
| FR-008 | Error Reporting | Every detected problem is reported. Warnings never silently disappear. |
| FR-009 | Traceability | Every tag is traceable to the sentence, the Scene JSON concept, and the Resolver rule. |
| FR-010 | Repeatability | Same input, Knowledge Base, and config → identical output. |
Natural Language → Scene Compiler → Structured Prompt → EasyIllustrious → Image Generation
The user should never need to rewrite prompts manually but remains free to edit generated prompts afterwards.
| ID | Quality | Summary |
|---|---|---|
| NFR-001 | Determinism | Highest priority. No randomness inside the compiler. |
| NFR-002 | Explainability | Every decision is explainable; no unexplained output. |
| NFR-003 | Modularity | Every stage is replaceable without touching unrelated stages. |
| NFR-004 | Performance | Most time is spent in the Analyzer; the rest stays lightweight. |
| NFR-005 | Maintainability | Knowledge is never hardcoded; the codebase avoids special cases. |
| NFR-006 | Testability | Every module is independently testable (Resolver tests need no Ollama, etc.). |
| NFR-007 | Debuggability | Every intermediate representation is inspectable. |
| NFR-008 | Extensibility | Future Resolvers (Illustrious, Pony, Flux, NoobAI…) without touching the core. |
| NFR-009 | Offline Support | Operates locally; external APIs remain optional. |
| NFR-010 | Compatibility | Integrates into existing ComfyUI workflows without redesign. |
Met. Version 1 shipped as
v1.0.0/v1.1.0; every criterion below is satisfied and stays guarded by the test suite. Version 2 (v2.0.0/v2.1.0) added semantic resolution and the node/configuration consolidation without relaxing any of them — see Roadmap.
Version 1 is complete when:
- ✓ Natural language is successfully analyzed.
- ✓ Scene JSON validates successfully.
- ✓ Concepts resolve correctly.
- ✓ Illustrious tags are generated.
- ✓ Tags carry their category (traceability only; the prompt is flat).
- ✓ Prompt outputs are generated.
- ✓ All automated tests pass.
- ✓ Documentation is complete.
- ✓ Example workflows execute successfully without modification.
- ✓ No mandatory feature depends on prompt generation.
- ✓ No compiler stage performs semantic hallucination.
- Knowledge Base validates (unique canonical IDs, unique aliases, known categories, valid expansions, no cycles, valid JSON).
- Scene JSON validates against the official schema; invalid documents never continue.
- Resolver: every tag originates from a Knowledge Base Entry; nothing is hardcoded.
- Pipeline: every stage has exactly one responsibility.
- ComfyUI: all functionality is reachable through thin node wrappers.
Version 1 ships with a README, Wiki, architecture docs, Knowledge Base docs, example workflows, a contribution guide, and developer docs — plus automated tests covering the Knowledge Base, Scene Validator, Resolver, the full pipeline, and regression tests.
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.