vulca 0.14.1

AI-native cultural art creation organism. Multi-round img2img iteration, two-phase VLM evaluation (OBSERVE+EVALUATE), Brief-driven Studio with sketch/reference upload, local evolution flywheel, commercial extra dimensions, and 13 cultural traditions.

VULCA

AI-native creation intelligence for cultural art. Generate, evaluate, decompose, and evolve visual art across 13 cultural traditions. L1-L5 multi-dimensional scoring, structured layer generation, self-evolving weights — all from one pip install.

Three traditions, one toolkit — Chinese ink wash / Western academic / Commercial brand design

$ vulca evaluate mona_lisa.jpg -t western_academic

  Score:     100%   Tradition: western_academic   Risk: low

    L1 Visual Perception         ████████████████████ 100%  ✓
    L2 Technical Execution       ████████████████████ 100%  ✓
    L3 Cultural Context          ████████████████████ 100%  ✓
    L4 Critical Interpretation   ████████████████████ 100%  ✓
    L5 Philosophical Aesthetics  ████████████████████ 100%  ✓

Based on peer-reviewed research: VULCA Framework (EMNLP 2025 Findings) and VULCA-Bench (7,410 samples, L1-L5 definitions).

---

Install

pip install vulca                  # core SDK + CLI
export GOOGLE_API_KEY=your-key     # for Gemini generation + scoring
vulca create "Misty mountains" -t chinese_xieyi -o art.png

No API key? vulca create "..." --provider mock runs the full pipeline locally.

Optional extras

pip install vulca[mcp]             # MCP server for Claude Code / Cursor
pip install vulca[layers-full]     # rembg + SAM2 for layer extraction
pip install vulca[tools]           # OpenCV algorithmic analysis tools
pip install vulca[all]             # everything

---

What You Can Do

Generate — 13 cultural traditions, structured layers

vulca create "水墨山水，雨后春山" -t chinese_xieyi --layered    # structured layers
vulca create "Tea packaging" -t brand_design --provider gemini   # single image

Layered creation — generation-time alpha for cultural art

vulca create "远山薄雾" -t chinese_xieyi --layered -o art/

VULCA generates each layer (远山, 中景, 题款 …) on the canonical canvas of the tradition (生宣纸 for xieyi). The first layer generates serially as a style anchor — its raw RGB output becomes the visual reference for all subsequent layers, which generate in parallel. This ensures cross-layer style consistency without requiring a user-provided reference image (Defense 3, v0.14).

Per-layer alpha is extracted by tradition-specific keying (luminance for ink wash, chroma for color works), so flying-white and ink gradients become true soft alpha — no halos, no hard edges. Layers can be re-rendered individually:

vulca layers retry art/ --layer 远山          # retry one layer
vulca layers retry art/ --all-failed          # retry every failed layer
vulca layers cache clear art/                 # drop the sidecar cache

Cost: 1 serial + (N-1) parallel provider calls per artwork. The first layer is the style anchor; remaining layers generate concurrently. Iterative editing hits the per-artifact cache, so changing one layer is one provider call. Partial failures are non-blocking — the manifest records partial: true and the healthy layers remain usable. If the first layer fails, remaining layers degrade gracefully to no-reference mode (same as v0.13).

Evaluate — L1-L5 cultural scoring, three modes

$ vulca evaluate artwork.png -t chinese_xieyi --mode reference

  L2 Technical Execution  85%  (traditional)
     To push further: exploring texture strokes — axe-cut (斧劈皴)
     for sharper rocks, rain-drop (雨点皴) for rounded forms.

  L3 Cultural Context  95%  (traditional)
     To push further: adding a poem (题画诗) for poetry-calligraphy-
     painting-seal (诗书画印) harmony.

Decompose — split any image into transparent layers

→

Qi Baishi's Shrimp → 3 layers (shrimp / calligraphy / seals)

vulca layers split qi_baishi.jpg -o ./layers/ --mode regenerate

Edit — redraw layers, inpaint regions, composite

Only the sky was redrawn — mountains, pavilion, and calligraphy are pixel-identical

vulca layers redraw ./layers/ --layer sky -i "warm golden sunset"

Analyze — 5 algorithmic tools, zero API cost

vulca tools run brushstroke_analyze --image art.png -t chinese_xieyi
# Energy: 0.87 — aligns with xieyi's expressive style. Confidence: 0.90

Evolve — weights self-improve from every session

$ vulca evolution chinese_xieyi

  Dim     Original    Evolved     Change
  L1        10.0%     10.0% +    0.0%
  L2        15.0%     20.0% +    5.0%    ← Technical Execution strengthened
  L3        25.0%     35.0% +   10.0%    ← Cultural Context most evolved
  L4        20.0%     15.0%    -5.0%
  L5        30.0%     20.0%   -10.0%
  Sessions: 71

---

Create

See create + evaluate workflow (GIF, 3.8 MB)

vulca create "水墨山水，雨后春山" -t chinese_xieyi -o landscape.png
vulca create "Tea packaging, Eastern aesthetics" -t brand_design --colors "#C87F4A,#5F8A50"
vulca create "Zen garden at dawn" -t japanese_traditional --provider gemini --hitl

Structured Creation (--layered)

VULCA plans the layer structure from tradition knowledge. The first layer generates as a style anchor, then remaining layers generate in parallel using it as a visual reference:

vulca create "水墨山水，松间茅屋" -t chinese_xieyi --layered
# → 5 layers: paper, distant_mountains, mountains_pines, hut_figure, calligraphy

Works across traditions — photography produces depth layers, gongbi produces line art + wash layers, brand design produces logo + background + typography layers.

Layer-Driven Design Transfer

Extract elements from one artwork, transform into a new design while preserving cultural context:

→ →

Ink wash painting → extract mountain layer → tea packaging (92% brand consistency)

vulca layers split landscape.png -o ./layers/ --mode extract
vulca create "Premium tea packaging, mountain watermark" \
  -t brand_design --reference ./layers/distant_mountains.png

---

Evaluate — Three Modes

Dimension	What It Measures
L1 Visual Perception	Composition, color harmony, spatial arrangement
L2 Technical Execution	Rendering quality, technique fidelity, craftsmanship
L3 Cultural Context	Tradition-specific motifs, canonical conventions
L4 Critical Interpretation	Cultural sensitivity, contextual framing
L5 Philosophical Aesthetics	Artistic depth, emotional resonance, spiritual qualities

Strict Mode (Judge)

Binary cultural scoring — does the art conform to the tradition?

$ vulca evaluate artwork.png -t chinese_xieyi

  Score:     90%    Tradition: chinese_xieyi    Risk: low

    L1 Visual Perception         ██████████████████░░ 90%  ✓
    L2 Technical Execution       █████████████████░░░ 85%  ✓
    L3 Cultural Context          ██████████████████░░ 90%  ✓
    L4 Critical Interpretation   ████████████████████ 100%  ✓
    L5 Philosophical Aesthetics  ██████████████████░░ 90%  ✓

Reference Mode (Mentor)

Cultural guidance with professional terminology — not a judge, a mentor:

$ vulca evaluate artwork.png -t chinese_xieyi --mode reference

  L1 Visual Perception         ██████████████████░░ 90%  (traditional)
     To push further: varying the density of the mist (留白) more dramatically,
     using a darker, more diffused wash to suggest deeper valleys.

  L2 Technical Execution       █████████████████░░░ 85%  (traditional)
     To push further: exploring texture strokes — axe-cut (斧劈皴)
     for sharper rocks, rain-drop (雨点皴) for rounded forms.

  L3 Cultural Context          ███████████████████░ 95%  (traditional)
     To push further: adding a poem (题画诗) for poetry-calligraphy-
     painting-seal (诗书画印) harmony.

Fusion Mode (Cross-Cultural Comparison)

Evaluate the same artwork against multiple traditions simultaneously:

$ vulca evaluate artwork.png -t chinese_xieyi,japanese_traditional,western_academic --mode fusion

  Dimension                   Chinese Xieyi Japanese Tradit Western Academi
  Visual Perception                   90%             90%             10%
  Technical Execution                 90%             90%             10%
  Cultural Context                    95%             80%              0%
  Critical Interpretation            100%            100%             10%
  Philosophical Aesthetics            90%             90%             10%
  Overall Alignment                    93%             90%              8%

  Closest tradition: chinese_xieyi (93%)

---

Decompose

Split any image into semantically meaningful layers with real transparency.

See layer decomposition in action (GIF, 3.3 MB)

→

Qi Baishi's Shrimp → shrimp / calligraphy / seals — each on transparent canvas

→

Mona Lisa → face & hair / body & dress — clean semantic separation

vulca layers split qi_baishi.jpg -o ./layers/ --mode regenerate --provider gemini
vulca layers split mona_lisa.jpg -o ./layers/ --mode extract    # free, no API
vulca layers split photo.jpg -o ./layers/ --mode sam            # SAM2 segmentation

Three split modes — all produce full-canvas RGBA with real transparency:

Mode	How It Works	Cost
extract	Color-range masking from original pixels	Free
regenerate	Gemini redraws each layer (content + alpha mask)	~$0.05/layer
sam	SAM2 pixel-precise segmentation	Free (local)

---

Layer Editing Workflows

Scenario 1: Non-Destructive Editing (Artists)

"The sky doesn't feel right, but the mountains are perfect."

Only the sky layer was redrawn — mountains, pavilion, pine trees, and calligraphy are pixel-identical.

vulca layers split artwork.png -o ./layers/ --mode regenerate
vulca layers lock ./layers/ --layer calligraphy_and_seals
vulca layers redraw ./layers/ --layer background_sky \
  -i "warm golden sunset with orange and purple gradients"
vulca layers composite ./layers/ -o final.png

Scenario 2: Event Poster Design (Designers)

→

Ink wash painting → event poster with typography (92% brand consistency)

vulca layers split artwork.png -o ./layers/ --mode extract
vulca layers merge ./layers/ --layers mountains,pavilion,mist --name "poster_bg"
vulca create "Cultural festival poster, modern typography overlay" \
  -t brand_design --reference ./layers/poster_bg.png

Scenario 3: Parallax Hero Sections (Frontend Developers)

One command → depth-based layers → CSS parallax with independent scroll speeds.

6 depth layers → travel website with CSS parallax — all assets from one VULCA command

vulca create "Mountain lake at golden hour, wooden dock, canoe" \
  -t photography --layered
# → 6 layers: sky, mountains, lake, dock, canoe, reflections
vulca layers export ./output/ -o ./web-assets/ --format png

.parallax  { perspective: 1px; overflow-x: hidden; overflow-y: auto; }
.sky       { transform: translateZ(-3px) scale(4); }  /* slowest */
.mountains { transform: translateZ(-2px) scale(3); }
.dock      { transform: translateZ(0);             }  /* normal scroll */

Scenario 4: Per-Layer Cultural Evaluation (Researchers)

Which element carries the most cultural weight?

$ vulca layers evaluate ./layers/ -t chinese_xieyi

  [0] background_canvas:       92%  L3=95%
  [1] distant_mountains:       88%  L3=90%  ← L2=80%, room for texture variation
  [3] foreground_landscape:    92%  L3=95%
  [4] pavilion_and_pines:      92%  L2=90%  ← highest technical execution
  [5] calligraphy_and_seals:   89%  L3=90%

7 layer editing operations

Operation	What It Does
add	Create new transparent layer
remove	Delete layer (blocked if locked)
reorder	Move layer z-index
toggle	Show/hide in composite
lock	Prevent deletion/merge
merge	Combine selected layers
duplicate	Copy for experimentation

---

Tools — Algorithmic Analysis (No API)

5 tools that run locally with zero API cost. Feed results into VLM evaluation for hybrid scoring.

See all 5 tools in action (GIF, 1.4 MB)

$ vulca tools run brushstroke_analyze --image artwork.png -t chinese_xieyi
  Energy: 0.87 — aligns with xieyi's expressive style. Confidence: 0.90

$ vulca tools run whitespace_analyze --image artwork.png -t chinese_xieyi
  Whitespace: 32.8% — in ideal range (30%-55%). Distribution: top_heavy.

$ vulca tools run composition_analyze --image artwork.png -t chinese_xieyi
  Thirds alignment: 0.75 — asymmetric, dynamic arrangement. Confidence: 0.90

$ vulca tools run color_gamut_check --image artwork.png -t chinese_xieyi
  In-gamut: 98.2% — 1.8% pixels over-saturated. Fix mode: auto-desaturate.

$ vulca tools run color_correct --image artwork.png -t chinese_xieyi
  Suggestion: reduce saturation 5% for ink wash feel. Channel bias: R+2, G+1, B-3.

---

Inpainting — Region-Based Repaint

Pixel-level preservation outside the target region. PIL local blend, not full-image regeneration.

→

Original → sky replaced with golden sunset (mountains untouched)

vulca inpaint artwork.png --region "the sky in the upper portion" \
  --instruction "replace with dramatic stormy clouds" -t chinese_xieyi
vulca inpaint artwork.png --region "0,0,100,40" \
  --instruction "golden sunset gradient" --count 4 --select 1

---

Studio — Brief-Driven Creative Session

See studio workflow (GIF, 1.6 MB)

→

Brief: "Cyberpunk ink wash, neon pavilions" → 4 concepts → select #2 → final output (93%)

vulca studio "Cyberpunk ink wash" --provider gemini               # interactive
vulca studio "Zen garden at dawn" --provider gemini --auto         # non-interactive
vulca brief ./project -i "Cyberpunk shanshui" -m "epic-futuristic"  # step by step

---

Self-Evolution

The system learns from every session. Evolved weights, few-shot references, and cultural insights feed back into evaluation and generation prompts automatically.

$ vulca evolution chinese_xieyi

  Dim     Original    Evolved     Change
  L1        10.0%     10.0% +    0.0%
  L2        15.0%     20.0% +    5.0%    ← Technical Execution strengthened
  L3        25.0%     35.0% +   10.0%    ← Cultural Context most evolved
  L4        20.0%     15.0%    -5.0%
  L5        30.0%     20.0%   -10.0%
  Sessions: 71

Create / Evaluate ──► Session Store ──► LocalEvolver (per tradition)
       ▲                                        │
       └──────── Evolved Weights ◄──────────────┘

Evolution is automatic — every session contributes. strict mode strengthens tradition conformance, reference mode tracks exploration trends. Intentional departures are not penalized. Gating: minimum 5 sessions + 3 feedback sessions before weights shift.

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                         User Intent                          │
└──────┬───────────┬──────────────┬──────────────┬─────────────┘
       │           │              │              │
  ┌────▼──┐  ┌─────▼───┐  ┌──────▼─────┐  ┌─────▼─────┐
  │  CLI  │  │  Python  │  │    MCP     │  │  ComfyUI  │
  │       │  │   SDK    │  │  21 tools  │  │  11 nodes │
  └───┬───┘  └────┬────┘  └──────┬─────┘  └─────┬─────┘
      └───────────┴───────┬──────┴───────────────┘
                          │
                 vulca.pipeline.execute()
                          │
      ┌───────────────────┼───────────────────┐
      │                   │                   │
 ┌────▼────┐       ┌──────▼─────┐      ┌──────▼──────┐
 │ DEFAULT │       │  LAYERED   │      │  CULTURAL   │
 │ Gen→Eval│       │ Plan→Layer │      │  Tools+VLM  │
 │ →Decide │       │ →Artifact  │      │  Hybrid     │
 └────┬────┘       └──────┬─────┘      └──────┬──────┘
      └───────────────────┼───────────────────┘
                          │
              ┌───────────▼───────────┐
              │    13 Traditions      │
              │  Weights + Taboos +   │
              │  Terminology + L1-L5  │
              └───────────┬───────────┘
                          │
              ┌───────────▼───────────┐
              │   Self-Evolution      │
              │  Session → Evolver    │
              │  → Evolved Weights    │
              └───────────────────────┘

5 pipeline templates: DEFAULT (generate→evaluate→decide loop), FAST (single-round), CRITIQUE_ONLY (evaluate existing image), CULTURAL_XIEYI (hybrid algorithmic+VLM), LAYERED (structured layers).

4 image providers: Mock (local, no API), Gemini (Imagen 3), OpenAI (DALL-E), ComfyUI (local workflows).

---

13 Cultural Traditions

Cultural traditions / Design disciplines / Media types — each with its own L1-L5 weights, terminology, and taboos

chinese_xieyi chinese_gongbi japanese_traditional western_academic islamic_geometric watercolor african_traditional south_asian contemporary_art photography brand_design ui_ux_design default

Custom traditions via YAML — vulca evaluate painting.jpg --tradition ./my_style.yaml:

# my_style.yaml
name: pixel_art
display_name: { en: Pixel Art, zh: 像素艺术 }
weights: { L1: 0.25, L2: 0.30, L3: 0.15, L4: 0.15, L5: 0.15 }
terminology:
  - term: sprite
    definition: A small raster graphic used as a visual unit
    l_levels: [L1, L2]
taboos:
  - rule: Do not apply anti-aliasing judgments
    severity: high

---

Four Entry Points

CLI

vulca create "intent" -t tradition --provider gemini -o art.png
vulca create "intent" -t tradition --layered                  # structured layers
vulca evaluate art.png -t tradition --mode reference           # mentor mode
vulca layers split art.png -o ./layers/ --mode regenerate      # decompose
vulca layers redraw ./layers/ --layer sky -i "add sunset"      # edit
vulca layers composite ./layers/ -o final.png                  # composite
vulca inpaint art.png --region "sky" --instruction "storm"     # inpaint
vulca studio "concept" --provider gemini --auto                # brief session
vulca tools run brushstroke_analyze --image art.png            # algorithmic
vulca evolution tradition_name                                 # check evolution

Full CLI reference (all commands + flags)

# Create
vulca create "intent" -t tradition --provider mock|gemini|openai|comfyui
  --layered                    # structured layer generation
  --hitl                       # pause for human review
  --weights "L1=0.3,L2=0.2"   # custom dimension weights
  --reference ref.png          # reference image
  --colors "#hex1,#hex2"       # color palette constraint
  --residuals                  # attention residuals
  --sparse-eval                # evaluate only relevant dimensions
  -o output.png                # output path

# Evaluate
vulca evaluate image.png -t tradition
  --mode strict|reference|fusion
  --skills brand,audience,trend  # extra commercial scoring skills
  --sparse-eval                # auto-select relevant dimensions

# Layers (14 subcommands)
vulca layers analyze image.png
vulca layers split image.png -o dir --mode extract|regenerate|sam
vulca layers redraw dir --layer name -i "instruction"
vulca layers add dir --name name --content-type type
vulca layers toggle dir --layer name --visible true|false
vulca layers lock dir --layer name
vulca layers merge dir --layers a,b --name merged
vulca layers duplicate dir --layer name
vulca layers composite dir -o output.png
vulca layers export dir -o output.psd
vulca layers evaluate dir -t tradition
vulca layers regenerate dir --provider gemini

# Inpainting
vulca inpaint image.png --region "description or x,y,w,h"
  --instruction "what to change" -t tradition --count 4 --select 1

# Studio
vulca studio "concept" --provider gemini [--auto] [--max-rounds 3]
vulca brief ./project -i "intent" -m "mood"
vulca brief-update ./project "add more contrast"
vulca concept ./project --count 4 --provider gemini [--select 2]

# Utilities
vulca traditions                        # list all traditions
vulca tradition tradition_name          # detailed guide
vulca tradition --init my_style         # generate template YAML
vulca evolution tradition_name          # evolution status
vulca sync [--push-only|--pull-only]    # cloud sync

Python SDK

import vulca

# Evaluate
result = vulca.evaluate("artwork.png", tradition="chinese_xieyi")
print(result.score, result.suggestions, result.L3)

# Create
result = vulca.create("Tea packaging", provider="gemini", tradition="brand_design")
print(result.weighted_total, result.best_image_b64[:20])

# Structured creation
result = vulca.create("水墨山水", provider="gemini", tradition="chinese_xieyi", layered=True)

# Decompose
from vulca.layers import analyze_layers, split_extract, composite_layers
import asyncio
layers = asyncio.run(analyze_layers("artwork.png"))
results = split_extract("artwork.png", layers, output_dir="./layers")
composite_layers(results, width=1024, height=1024, output_path="composite.png")

# Self-evolution weights
weights = vulca.get_weights("chinese_xieyi")
# → {"L1": 0.10, "L2": 0.20, "L3": 0.35, "L4": 0.15, "L5": 0.20}

MCP Server (Claude Code / Cursor)

pip install vulca[mcp]
claude plugin install vulca-org/vulca-plugin    # 21 tools + 10 skills

21 tools: create_artwork, evaluate_artwork, list_traditions, get_tradition_guide, resume_artwork, get_evolution_status, studio_create_brief, studio_update_brief, studio_generate_concepts, studio_select_concept, studio_accept, inpaint_artwork, analyze_layers, layers_split, layers_redraw, layers_composite, layers_edit, layers_evaluate, layers_export, layers_regenerate, sync_data.

ComfyUI

git clone https://github.com/vulca-org/comfyui-vulca  # in custom_nodes/
pip install vulca>=0.11.0

11 nodes: Brief, Concept, Generate, Evaluate, Update, Inpaint, Layers Analyze/Composite/Export, Evolution, Traditions.

---

---

Research

VULCA builds on peer-reviewed research on culturally-aware visual understanding:

Paper	Venue	Contribution
VULCA Framework	EMNLP 2025 Findings	5-dimension evaluation framework
VULCA-Bench	arXiv	L1-L5 definitions, 7,410 samples, 9 traditions
Fire Imagery	WiNLP 2025	Cultural symbol reasoning
Art Critique	arXiv	Cross-cultural critique evaluation

Citation

@inproceedings{yu2025vulca,
  title     = {VULCA: A Framework for Culturally-Aware Visual Understanding},
  author    = {Yu, Haorui},
  booktitle = {Findings of EMNLP 2025},
  year      = {2025}
}

@article{yu2026vulcabench,
  title   = {VULCA-Bench: A Benchmark for Culturally-Aware Visual Understanding at Five Levels},
  author  = {Yu, Haorui},
  journal = {arXiv preprint arXiv:2601.07986},
  year    = {2026}
}

License

Apache 2.0

---

Issues and PRs welcome. Development happens in a private monorepo and is synced here via git subtree.