vulca 0.10.0

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 cultural art creation organism. Create, evaluate, and evolve artwork across 13 cultural traditions — L1-L5 scoring, self-evolving weights, full layer editing, and 5 algorithmic analysis tools. 21 MCP tools, all from one pip install.

pip install vulca
export GOOGLE_API_KEY=your-key
vulca create "Misty mountains after rain, pine pavilion in clouds" -t chinese_xieyi -o artwork.png
# → Score: 0.915 | Tradition: chinese_xieyi | 1 round | 43s
# → Image: artwork.png

See it in action (GIF)

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

---

Architecture

graph LR
    subgraph Pipeline["Creation Pipeline"]
        S[Scout] --> G[Generate]
        G --> E[Evaluate<br/>L1-L5]
        E --> D{Decide}
        D -->|rerun| G
        D -->|accept| OUT[Output]
    end

    subgraph Evolution["Self-Evolution Loop"]
        OUT --> SE[Session Store<br/>1100+ sessions]
        SE --> LE[LocalEvolver]
        LE --> EW[Evolved Weights]
        EW --> G
        EW --> E
        EW --> D
    end

    subgraph Tools["Algorithmic Tools (no API)"]
        T1[brushstroke] --> E
        T2[whitespace] --> E
        T3[composition] --> E
        T4[color_gamut] --> E
        T5[color_correct] --> E
    end

    subgraph LayersV2["Layers V2"]
        AN[Analyze] --> SP{Split}
        SP -->|regenerate| IG[Gemini + mask alpha]
        SP -->|extract| CM[Color mask]
        SP -->|sam| SAM[SAM2 pixel mask]
        IG --> FC[Full-canvas RGBA]
        CM --> FC
        SAM --> FC
        FC --> ED[Edit / Redraw / Composite]
    end

4 entry points, 1 engine: CLI, Python SDK, MCP (21 tools), ComfyUI (11 nodes) — all share vulca.pipeline.execute().

---

Create

See create + evaluate workflow (GIF)

vulca create "Misty mountains after rain" -t chinese_xieyi -o landscape.png
vulca create "Tea packaging, Eastern aesthetics" -t brand_design --colors "#C87F4A,#5F8A50"
vulca create "Zen garden" -t japanese_traditional --provider gemini --hitl  # pause for review

Layer-Driven Design Transfer

Extract elements from artwork, transform into new designs while maintaining cultural consistency:

# 1. Extract mountain layer from ink wash painting
vulca layers split landscape.png -o ./layers/ --mode extract
# 2. Use the mountain layer as reference → create brand packaging
vulca create "Premium tea packaging, mountain silhouette as watermark" \
  -t brand_design --reference ./layers/distant_mountains.png
# → Score: 0.92

→ →

Ink wash landscape → extract mountain layer (checkerboard = transparent) → tea packaging (92%)

---

Evaluate — Three Modes

Strict Mode (Judge)

$ 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 (Advisor)

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

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

Fusion Mode (Cross-Cultural Comparison)

$ 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%)

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

---

Layers V2

Every layer is full-canvas RGBA with real transparency. Proper blend modes (normal/screen/multiply). 14 CLI subcommands.

See layer decomposition in action (GIF)

→ →

Checkerboard = transparent areas. Calligraphy layer is only 3% opaque — just the text and seals.

Scenario 1: Non-Destructive Editing (Artists)

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

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

vulca layers split artwork.png -o ./layers/ --mode regenerate --provider gemini
vulca layers lock ./layers/ --layer calligraphy_and_seals         # protect from edits
vulca layers redraw ./layers/ --layer background_sky_and_mist \
  -i "warm golden sunset with orange and purple gradients"        # redraw ONLY this layer
vulca layers composite ./layers/ -o final.png                     # other layers untouched

Scenario 2a: Event Poster Design (Graphic Designers)

Extract the full painting as background → generate poster with modern typography overlay.

→

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 2b: Parallax Hero Sections (Frontend Developers)

Any hero image → depth-based layer extraction → CSS parallax with independent scroll speeds.

# Generate or use any hero image
vulca create "Mountain lake at golden hour, wooden dock, canoe" -t photography -o hero.png
# Split into depth layers (auto-detects scene semantics)
vulca layers split hero.png -o ./parallax-layers/ --mode extract
# → 4 layers: background_landscape, wooden_dock, canoe_and_person, reflections
vulca layers export ./parallax-layers/ -o ./web-assets/
# → Each layer: full-canvas RGBA with real transparency

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

VULCA auto-detects image type — the same layers split command works for artwork (returns art layers), photography (returns depth planes), or designs (returns visual elements). No Figma or Stitch needed for the asset layer — just a photo and one command.

Scenario 3: 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%

Technical reference: 3 split modes + 7 editing operations

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

Mode	How it works	API cost
extract	Color-range masking from original image	Free
regenerate	Gemini redraws each layer (hybrid: Gemini content + extract alpha mask)	~$0.05/layer
sam	SAM2 pixel-precise segmentation (pip install vulca[sam])	Free (local)

Hybrid regenerate: Gemini can't generate real transparency, so regenerate mode combines Gemini's high-quality content with extract's color mask for the alpha channel. Result: Gemini quality + real transparency.

7 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:

See all 5 tools (GIF)

$ 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

Also: color_gamut_check (saturation profiling + fix) and color_correct (check/fix/suggest).

---

Inpainting — Region-Based Repaint

Pixel-level preservation outside the bounding box — PIL local blend, not full-image regeneration.

→

Left: original | Right: 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)

4 concepts from brief: "Cyberpunk ink wash, neon pavilions" → select → generate → 93% → accept

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. After 1100+ sessions:

$ 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

graph LR
    C[Create/Evaluate] -->|scores| S[Session Store]
    S -->|every 5 min| LE[LocalEvolver]
    LE -->|per tradition| EW[Evolved Weights]
    EW -->|read| G[GenerateNode]
    EW -->|read| E[EvaluateNode]
    EW -->|read| D[DecideNode]
    G --> C
    E --> C

Evolution is automatic — every session contributes. strict mode strengthens tradition conformance, reference mode tracks exploration trends, intentional_departure deviations are not penalized.

---

Where to Use

Claude Code / Cursor (MCP Plugin)

pip install vulca[mcp]
claude plugin install vulca-org/vulca-plugin

21 MCP tools: evaluate_artwork, create_artwork, analyze_layers, layers_split, layers_redraw, layers_edit, studio_create_brief, inpaint_artwork, 5 Tool Protocol tools, and more.

ComfyUI

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

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

Python SDK

import vulca

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

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

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

Full CLI reference

vulca evaluate painting.jpg -t chinese_xieyi                    # strict
vulca evaluate painting.jpg -t chinese_xieyi --mode reference   # advisor
vulca evaluate painting.jpg -t xieyi,japanese --mode fusion     # cross-cultural
vulca evaluate painting.jpg --sparse-eval                       # relevant dims only

vulca create "Misty mountains" -t chinese_xieyi --provider gemini -o art.png
vulca create "Tea packaging" --provider gemini --residuals      # agent attention
vulca create "Zen garden" --provider gemini --hitl              # pause for review

vulca studio "Zen garden" --provider gemini                     # interactive
vulca studio "Zen garden" --provider gemini --auto              # non-interactive

vulca layers analyze artwork.png
vulca layers split artwork.png -o ./layers --mode extract       # or regenerate / sam
vulca layers redraw ./layers --layer sky -i "add sunset"
vulca layers add ./layers --name glow --content-type effect
vulca layers toggle ./layers --layer mist --visible false
vulca layers lock ./layers --layer background
vulca layers merge ./layers --layers fg,mid --name merged
vulca layers composite ./layers -o final.png
vulca layers export ./layers -o ./assets.psd
vulca layers evaluate ./layers -t chinese_xieyi

vulca inpaint artwork.png --region "sky" --instruction "dramatic clouds"
vulca tools run brushstroke_analyze --image art.png -t chinese_xieyi
vulca evolution chinese_xieyi
vulca sessions stats
vulca resume <session-id>

---

13 Cultural Traditions

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

---

Install

pip install vulca           # core SDK + CLI
pip install vulca[mcp]      # + MCP server for Claude Code / Cursor
pip install vulca[sam]      # + SAM2 pixel-precise layer extraction

No API key required for mock mode. For real generation + scoring: export GOOGLE_API_KEY=your-key

Gemini supports 512 / 1K / 2K / 4K output with automatic size and aspect ratio mapping.

---

Citation

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

License

Apache 2.0

---

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