# Visual Compiler
**Deterministic compiler for AI‑generated visual content**
*Webtoon • Manga • Visual Novel • Storyboard*
[](https://github.com/NightSky199714/visual_compiler/actions/workflows/ci.yml)
[](https://crates.io/crates/vc-cli)
[](https://docs.rs/vc-cli)
[](https://github.com/NightSky199714/visual_compiler#license)
[](https://www.rust-lang.org/)
---
## Table of Contents
- [Description](#-description)
- [Core Principles](#-core-principles)
- [Who Is This For?](#-who-is-this-for)
- [Why Visual Compiler?](#-why-visual-compiler)
- [Features](#-features)
- [Project Status](#-project-status)
- [Architecture](#-architecture-overview)
- [Workspace Crates](#-workspace-crates--dependencies)
- [Compatibility Matrix](#-compatibility-matrix)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Example Configuration](#-example-configuration)
- [Example Output](#-example-output)
- [Library Usage](#-library-usage)
- [Roadmap](#-roadmap)
- [Design Goals](#-design-goals)
- [Non‑Goals](#-non-goals)
- [FAQ](#-faq)
- [MSRV](#-msrv)
- [Versioning Policy](#-versioning-policy)
- [Documentation](#-documentation)
- [Contributing](#-contributing)
- [License](#-license)
---
## 📖 Description
**Visual Compiler** is a deterministic, modular compiler pipeline for transforming structured narrative data into **prompts** for AI image generation models (SDXL, ComfyUI, Flux, etc.).
It ensures that the **same input always produces the same output**—enabling reproducible asset generation, version control of visual assets, and seamless integration with game engines, animation pipelines, and VFX workflows.
---
## Core Principles
- **Deterministic by default** – Same input → same output, always
- **Reproducible builds** – Golden tests, content‑addressable IDs
- **Backend agnostic** – Runtime supports multiple backends via registry
- **Library first** – Use as a binary or integrate as a Rust library
- **Test driven** – Extensive unit, integration, golden, and E2E testing
- **Content addressable** – `snap_<hash>` deduplication and auditability
---
## 🎯 Who Is This For?
| **Game Developers** | Generate consistent character assets across frames |
| **Visual Novel Engines** | Maintain character appearance across scenes |
| **Asset Pipelines** | Version-controlled, reproducible image generation |
| **AI Workflow Automation** | Batch processing with deterministic outputs |
| **Research** | Reproducible experiments in AI image generation |
---
## 🧠 Why Visual Compiler?
| AI image generation is non‑deterministic | Deterministic hash‑based pipeline |
| Prompt engineering is messy | Structured semantic IR (`PromptCore`) |
| Integration with different backends is painful | Pluggable runtime backend registry |
| No versioning for generated assets | Content‑addressable IDs (`snap_<hash>`) |
| Hard to reproduce old results | Replay‑first design with golden tests |
---
## ✨ Features
| **Deterministic Pipeline** | SHA‑256 hashing, canonical JSON, Merkle root |
| **Semantic IR** | `PromptCore` – structured prompt representation, not plain text |
| **Pluggable Backends** | Dummy, SDXL, ComfyUI, Python, and extensible registry |
| **Content‑Addressable IDs** | `snap_<hash>` – deduplication and auditability built‑in |
| **Configuration‑Driven** | TOML profiles for runtime backend selection |
| **Golden Tests** | Snapshot, archive, bundle, prompt hashing regression tests |
| **CLI & Library** | Use as a binary or integrate as a Rust library |
---
## 📊 Project Status
| Public API | ✅ Frozen for `v0.1.0` |
| crates.io Readiness | ✅ Ready |
| Release Candidate | ✅ Ready |
| Documentation | ✅ Ready |
| CI/CD | ✅ Ready |
**Current version:** `v0.1.0`
---
## 🏛️ Architecture (Overview)
┌───────────────┐
│ Snapshot │ ← Structured narrative input (story, assets, characters)
│ (Core) │
└───────┬───────┘
│
▼
┌───────────────┐
│ Resolver │ ← Deterministic resolution: Snapshot → Bundle
└───────┬───────┘
│
▼
┌───────────────┐
│ Bundle │ ← Visual asset bundle (character, appearance, descriptors)
│ (Core) │
└───────┬───────┘
│
▼
┌───────────────┐
│ Prompt │ ← Semantic IR (PromptCore) – compiler boundary
│ (Core) │
└───────┬───────┘
│
▼
┌───────────────┐
│ Adapter │ ← SDXL, Flux, etc. → plain text prompt
│ (SDXL) │
└───────┬───────┘
│
▼
┌───────────────┐
│ Compiler │ ← Canonical JSON artifact (compiler_output.json)
│ Output │
└───────┬───────┘
│
▼
┌───────────────┐
│ Runtime │ ← Backend registry, BuildContext, Runner
│ (Backend) │
└───────┬───────┘
│
▼
┌───────────────┐
│ Renderer │ ← Dummy, Python, ComfyUI, etc.
│ (Image) │
└───────────────┘
---
## 📦 Workspace Crates & Dependencies
### High‑Level Dependency Path
vc-cli
│
▼
vc-runtime
│
▼
vc-output
│
▼
vc-prompt
│
▼
vc-resolver
│
▼
vc-bundle
│
▼
vc-snapshot
*Note: This is a high‑level dependency path. Additional crates like `vc-shared`, `vc-types`, and `vc-archive` are used throughout the workspace.*
### Crate Overview
| `vc-shared` | `vc-shared` | Canonical JSON, SHA‑256, Merkle root utilities |
| `vc-bundle` | `vc-bundle` | `VisualBundleCore` + deterministic hashing |
| `vc-prompt` | `vc-prompt` | `PromptCore` semantic IR + compilation |
| `vc-snapshot` | `vc-snapshot` | `SnapshotCore` + deterministic hashing |
| `vc-archive` | `vc-archive` | Archive manifest + deterministic hashing |
| `vc-resolver` | `vc-resolver` | Deterministic Snapshot → Bundle resolution |
| `vc-types` | `vc-types` | Domain types: `AdapterKind`, `CompilerVersion`, etc. |
| `vc-output` | `vc-output` | Compiler output artifact (`CompilerOutput`) |
| `vc-adapter-sdxl` | `vc-adapter-sdxl` | SDXL prompt adapter |
| `vc-runtime` | `vc-runtime` | Runtime backend registry, config, BuildContext, runner |
| `vc-cli` | `vc-cli` | Command‑line interface (binary `vc`) |
---
## 💻 Compatibility Matrix
| **Rust** | 1.75+ |
| **Edition** | 2021 |
| **Windows** | ✅ Tested |
| **Linux** | ✅ Tested |
| **macOS** | ✅ Tested |
---
## 🔧 Installation
### From crates.io (binary)
```bash
cargo install vc-cli
From source
git clone https://github.com/NightSky199714/visual_compiler.git
cd visual_compiler
cargo build --release --workspace
As a library
Add to your Cargo.toml:
[dependencies]
vc-shared = "0.1.0"
vc-prompt = "0.1.0"
vc-runtime = "0.1.0"
# ... etc.
🚀 Quick Start
1. Generate compiler output (demo)
vc demo --out build/
This creates:
build/compiler_output.json – canonical artifact
build/prompt.txt – rendered prompt text
2. Run with a backend
Create config.toml:
[global]
[profiles.default]
backend_name = "dummy"
[backends.dummy]
enabled = true
options = { kind = "dummy", options = {} }
Run:
vc run --input build/ --out run/ --config config.toml --profile default
Output:
run/runtime.json – runtime result metadata
run/image.png – generated image (placeholder for dummy backend)
📄 Example Configuration
Dummy Backend (for testing)
[backends.dummy]
enabled = true
options = { kind = "dummy", options = {} }
Python Backend
toml
[backends.python]
enabled = true
options = {
kind = "python",
options = {
script_path = "scripts/fake_renderer.py",
python_path = "python3"
}
}
ComfyUI Backend
toml
[backends.comfy]
enabled = true
options = {
kind = "comfy",
options = {
base_url = "http://127.0.0.1:8188",
timeout_secs = 30,
poll_timeout_secs = 300,
poll_interval_ms = 500,
workflow_template_path = "fixtures/comfy/workflow_base.json"
}
}
📊 Example Output
compiler_output.json (excerpt)
{
"schema_version": 1,
"prompt": {
"character": {
"descriptors": ["hero", "adventurer", "sword"]
}
},
"metadata": {
"compiler_version": "0.1.0",
"adapter": "Sdxl",
"snapshot_hash": "abc123...",
"bundle_hash": "def456...",
"prompt_hash": "789abc..."
}
}
runtime.json (excerpt)
{
"status": "Success",
"backend": "Sdxl",
"image_path": "run/image.png",
"image_hash": "hash123...",
"seed": 42,
"width": 1024,
"height": 1024,
"steps": 30,
"cfg": 7.0
}
📚 Library Usage
use vc_shared::hashing::sha256;
use vc_prompt::{PromptCore, CharacterVisual};
use vc_runtime::{load_config, run_backend, RuntimeInput};
fn main() -> anyhow::Result<()> {
// 1. Load compiler output
let input = RuntimeInput { vc_output: /* CompilerOutput */ };
// 2. Load config
let config = load_config("config.toml")?;
// 3. Run backend
let result = run_backend(&config, "default", &input, "run/")?;
// 4. Use result
println!("Image: {:?}", result.image_path);
Ok(())
}
🛣️ Roadmap
Upcoming Features
Additional Adapters – Flux, SD3, Kandinsky
Plugin API – Backend extensibility for third‑party renderers
Performance Improvements – Caching, parallelism, faster hashing
Developer Experience – Better diagnostics and error messages
See ROADMAP.md for the complete roadmap.
🎯 Design Goals
Goal Description
Deterministic Same input → same output, always
Modular Each crate has a single, clear responsibility
Backend‑Agnostic Runtime supports multiple backends via registry
Reproducible Golden tests, content‑addressable IDs
Configurable TOML profiles and runtime overrides
Observable Clear error messages, logging, and diagnostics
🚫 Non‑Goals
Not an image generation model itself (uses existing backends)
Not a UI tool (focused on CLI and library usage)
Not a real‑time renderer (batch/offline oriented)
Not a web service (though can be wrapped as one)
❓ FAQ
Q: Does this generate images?
No. It compiles prompts and delegates rendering to a backend (Dummy, Python, ComfyUI, etc.).
Q: Does it require Python?
Only if you use the Python‑based renderer. The core pipeline and Dummy/SDXL backends are pure Rust.
Q: Can I use ComfyUI?
Yes. The ComfyUI backend is fully supported with workflow templating.
Q: Is it production‑ready?
The core pipeline is stable and tested. The API is frozen for v0.1.0. Some features (like advanced backends) are still evolving.
Q: What about determinism?
The entire pipeline—from Snapshot to Runtime—is built around SHA‑256 hashing and canonical JSON. Golden tests ensure regression‑free behavior.
🔒 MSRV
The Minimum Supported Rust Version (MSRV) is 1.75.
The MSRV is guaranteed for all releases within the same minor version. Changes to the MSRV are considered a minor-version change and will be documented in the changelog.
🔒 Versioning Policy
We follow Semantic Versioning (SemVer) for all published crates.
Version Policy
v0.1.x No intentional breaking changes. Bug fixes and minor additions only.
v0.2.x Breaking changes allowed, but documented in CHANGELOG.md with migration guides.
v1.0.0 Full stability guarantee. API frozen.
See API_STABILITY.md for detailed stability guarantees.
📚 Documentation
Document Description
README.md This document
ROADMAP.md Development roadmap
CHANGELOG.md Release notes
CONTRIBUTING.md Contribution guide
CODE_OF_CONDUCT.md Code of conduct
SECURITY.md Security policy
RELEASE.md Release process
SUPPORTED_BACKENDS.md Supported backends
API_STABILITY.md API stability guarantees
ARCHITECTURE.md Architecture overview
RUNTIME.md Runtime documentation
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md for:
Development setup
Build & test commands
Commit conventions
Pull request guidelines
Quick Contribution Steps
# Clone & build
git clone https://github.com/NightSky199714/visual_compiler.git
cd visual_compiler
cargo build --workspace
# Run tests
cargo test --workspace
# Run linter
cargo clippy --workspace --all-features -- -D warnings
# Generate docs
cargo doc --workspace --no-deps
🔏 License
Licensed under either of:
MIT License
Apache License, Version 2.0
at your option.
🙏 Acknowledgements
Built with ❤️ using:
Rust
Serde
Tokio
Clap
Image
ComfyUI
Visual Compiler – Deterministic pipeline for the AI‑powered visual future. 🚀