vc-cli 0.1.0

Command-line interface for Visual Compiler
vc-cli-0.1.0 is not a library.

Visual Compiler

Deterministic compiler for AI‑generated visual content
Webtoon • Manga • Visual Novel • Storyboard

CI crates.io docs.rs License MSRV


Table of Contents


📖 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)

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. 🚀