Visual Compiler
Deterministic compiler for AI‑generated visual content
Webtoon • Manga • Visual Novel • Storyboard
Table of Contents
- Description
- Core Principles
- Who Is This For?
- Why Visual Compiler?
- Features
- Project Status
- Architecture
- Workspace Crates
- Compatibility Matrix
- Installation
- Quick Start
- Example Configuration
- Example Output
- Library Usage
- Roadmap
- Design Goals
- Non‑Goals
- FAQ
- MSRV
- Versioning Policy
- Documentation
- Contributing
- 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?
| Audience | Use Case |
|---|---|
| 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?
| Problem | Solution |
|---|---|
| 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
| Feature | Description |
|---|---|
| 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
| Aspect | 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
| Crate | Crates.io Name | Description |
|---|---|---|
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
| Item | Version / Support |
|---|---|
| Rust | 1.75+ |
| Edition | 2021 |
| Windows | ✅ Tested |
| Linux | ✅ Tested |
| macOS | ✅ Tested |
🔧 Installation
From crates.io (binary)
# ... etc.
)
)
)
)
{
}
)
{
}
;
;
;
)
)
)
)
)
)
)
)
) for
&
# Clone & build
# Run tests
# Run linter
# Generate docs