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.

<p align="center"> <img src="assets/demo/v2/hero-xieyi.png" alt="Chinese Xieyi ink wash landscape" width="260"> <img src="assets/demo/v2/masters/western_oil_painting.png" alt="Western academic oil painting" width="260"> <img src="assets/demo/v2/hero-brand.png" alt="Brand design tea packaging" width="260"> </p> <p align="center"><em>Three traditions, one toolkit — Chinese ink wash / Western academic / Commercial brand design</em></p>

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

<details> <summary>Optional extras</summary>

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

</details>

---

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

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

<p align="center"> <img src="assets/demo/v2/masters/qi_baishi_shrimp.jpg" alt="Qi Baishi shrimp" height="200"> → <img src="assets/demo/v2/masters/qi_baishi_layers/ink_shrimp.png" alt="Shrimp layer" height="200"> <img src="assets/demo/v2/masters/qi_baishi_layers/ink_calligraphy.png" alt="Calligraphy layer" height="200"> <img src="assets/demo/v2/masters/qi_baishi_layers/red_seals.png" alt="Seals layer" height="200"> </p> <p align="center"><em>Qi Baishi's Shrimp → 3 layers (shrimp / calligraphy / seals)</em></p>

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

Edit — redraw layers, inpaint regions, composite

<p align="center"> <img src="assets/demo/v2/scenario1-comparison.png" alt="Before: ink wash, After: golden sunset sky — mountains untouched" width="700"> </p> <p align="center"><em>Only the sky was redrawn — mountains, pavilion, and calligraphy are pixel-identical</em></p>

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

<details> <summary>See create + evaluate workflow (GIF, 3.8 MB)</summary> <p align="center"> <img src="assets/demo/v2/vhs-create.gif" alt="Create and evaluate workflow" width="800"> </p> </details>

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, then generates each layer independently:

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:

<p align="center"> <img src="assets/demo/v2/hero-xieyi.png" alt="Original ink wash landscape" width="220"> → <img src="assets/demo/v2/display-workflow-mountains.png" alt="Extracted mountain layer" width="220"> → <img src="assets/demo/v2/workflow-brand-output.png" alt="Tea packaging using mountain reference" width="220"> </p> <p align="center"><em>Ink wash painting → extract mountain layer → tea packaging (92% brand consistency)</em></p>

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.

<details> <summary>See layer decomposition in action (GIF, 3.3 MB)</summary> <p align="center"> <img src="assets/demo/v2/vhs-layers.gif" alt="Layer decomposition demo" width="800"> </p> </details> <p align="center"> <img src="assets/demo/v2/masters/qi_baishi_shrimp.jpg" alt="Qi Baishi shrimp" height="250"> → <img src="assets/demo/v2/masters/qi_baishi_layers/ink_shrimp.png" alt="Shrimp layer" height="250"> <img src="assets/demo/v2/masters/qi_baishi_layers/ink_calligraphy.png" alt="Calligraphy layer" height="250"> <img src="assets/demo/v2/masters/qi_baishi_layers/red_seals.png" alt="Seals layer" height="250"> </p> <p align="center"><em>Qi Baishi's Shrimp → shrimp / calligraphy / seals — each on transparent canv