vulca 0.2.0__tar.gz

vulca-0.2.0/.gitignore

@@ -0,0 +1,254 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Environment variables
+.env
+.env.local
+.env.production
+.env.production.local
+.env.development.local
+.env.test.local
+.claude/settings.local.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+wenxin.db
+
+# Logs
+*.log
+logs/
+
+# Build outputs
+wenxin-moyun/dist/
+wenxin-moyun/.vite/
+
+# Uploads
+uploads/
+*.upload
+
+# Docker
+.docker/
+
+# Temporary files
+*.tmp
+~$*
+.temp/
+
+# Test coverage
+coverage/
+.nyc_output/
+
+# Redis
+dump.rdb
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# Python virtual environments
+bin/
+include/
+Scripts/
+pyvenv.cfg
+
+# Windows reserved names (cannot be used as files)
+nul
+con
+prn
+aux
+com[1-9]
+lpt[1-9]
+**/nul
+**/con
+**/prn
+**/aux
+
+# Playwright E2E Testing
+playwright-report/
+test-results/
+test-results.json
+*.trace.zip
+videos/
+screenshots/
+wenxin-moyun/playwright-report/
+wenxin-moyun/test-results/
+wenxin-moyun/test-results.json
+wenxin-moyun/tests/e2e/playwright-report/
+wenxin-moyun/tests/e2e/test-results/
+wenxin-moyun/tests/e2e/test-results.json
+ios26_figma_data.json
+
+# Playwright MCP screenshots (debug artifacts)
+.playwright-mcp/
+
+# Root-level temporary/binary files
+*.png
+*.jpg
+*.jpeg
+*.exe
+*.msi
+*.zip
+*.docx
+*.aux
+# Allow specific image assets in subdirectories
+!wenxin-moyun/public/**/*.png
+!wenxin-moyun/public/**/*.jpg
+!wenxin-moyun/public/**/*.svg
+!wenxin-moyun/src/**/*.png
+!wenxin-moyun/src/**/*.jpg
+!wenxin-moyun/marketing/**/*.png
+
+# Root-level one-off files
+*.html
+!wenxin-moyun/**/*.html
+gmail-*.md
+gmail-*.png
+
+# Build/installer artifacts
+*.whl
+cloud_sql_proxy*
+gh.zip
+gh_installer.msi
+
+# Prototype temporary outputs
+wenxin-backend/tmp/
+wenxin-backend/venv/
+wenxin-backend/vulca
+wenxin-backend/=*
+
+# Prototype runtime artifacts (images + checkpoints + data)
+wenxin-backend/app/prototype/checkpoints/
+wenxin-backend/app/prototype/data/*.jsonl
+wenxin-backend/app/prototype/data/evolved_context.json
+wenxin-backend/app/prototype/data/trajectories/
+wenxin-backend/app/prototype/data/generated/
+wenxin-backend/app/prototype/blind_eval/results/
+
+# VULCA unified package virtual environment
+.venv/
+vulca/.venv/
+
+# LaTeX artifacts
+*.aux
+*.synctex.gz
+
+# Design files
+*.pen
+
+# VULCA intro materials (binary)
+wenxin-moyun/docs/*.pdf
+wenxin-moyun/docs/*.docx
+wenxin-moyun/docs/*.zip
+Didot_exhibition_Dec/*.pdf
+network-log.txt
+wenxin-moyun/marketing/exports/
+
+# Video production scripts (personal tooling)
+add-audio.sh
+cut-demo-b.sh
+make-video.sh
+produce-demo.sh
+finalize-demo-v3.sh
+finalize-demo-v4.sh
+
+# Non-product directories
+Didot_exhibition_Dec/
+EMNLP2025-VULCA/
+ACMMM2026-AgentLoop/
+ios26_assets/
+specs/
+tasks/
+.playwright-mcp/
+wenxinmoyun/
+references/
+benchmark_results/
+huggingface-space/
+monitoring/
+vulca-pkg/
+render.yaml
+AGENTS.md
+.gcloudignore
+.claude/hooks/
+.claude/skills/prospect-manager/
+.claude/skills/northeast-review/
+.github/DEPLOYMENT_LOG.md
+
+# Internal deployment scripts
+wenxin-backend/PRODUCTION_INIT.md
+wenxin-backend/cloud_shell_import.md
+wenxin-backend/cloud_shell_upload.sh
+wenxin-backend/cloudbuild-import.yaml
+wenxin-backend/deploy_import.sh
+wenxin-backend/deploy_with_gcloud.bat
+wenxin-backend/fix_import_script.py
+wenxin-backend/run_import_on_cloud.sh
+wenxin-backend/simple_import.sql
+wenxin-backend/start_proxy.bat
+wenxin-backend/.gcloudignore
+wenxin-backend/Dockerfile.import
+wenxin-backend/cloud_sql_proxy*
+wenxin-backend/tests/smoke/test_import_chain.py
+wenxin-moyun/DEPLOYMENT.md
+wenxin-moyun/gcp-alerts.json
+wenxin-moyun/.firebase/
+wenxin-moyun/docs/
+wenxin-moyun/marketing/
+wenxin-moyun/.playwright-mcp/
+wenxin-moyun/gcp-automation.cjs
+wenxin-moyun/manual_test.spec.js
+wenxin-moyun/view_button_test.spec.js
+wenxin-moyun/PERFORMANCE_REPORT.md
+wenxin-moyun/PLAYWRIGHT_TEST_REPORT.md
+wenxin-moyun/FRONTEND_OVERVIEW.md
+wenxin-moyun/README_BROWSER_WARNINGS.md
+wenxin-moyun/nginx.cloud.conf
+wenxin-moyun/Dockerfile.cloud
+wenxin-moyun/Dockerfile.dev
+wenxin-moyun/*.png
+wenxin-moyun/*.txt
+wenxin-backend/OPENAI_BENCHMARK_SUMMARY.md
+wenxin-backend/OPTIMIZATION_SUCCESS_REPORT.md
+wenxin-moyun/tsconfig.app.tsbuildinfo
+wenxin-moyun/vulca_test_results.json

vulca-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: vulca
+Version: 0.2.0
+Summary: AI-native creation organism. Create, critique, and evolve cultural art.
+Project-URL: Homepage, https://vulcaart.art
+Project-URL: Documentation, https://github.com/vulca-org/vulca
+Project-URL: Repository, https://github.com/vulca-org/vulca
+Project-URL: Issues, https://github.com/vulca-org/vulca/issues
+Author-email: Yu Haorui <yuhaorui48@gmail.com>
+License-Expression: Apache-2.0
+Keywords: ai,art,creation,cultural,evaluation,pipeline,vlm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: litellm>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: langgraph>=0.2.0; extra == 'graph'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=3.0; extra == 'mcp'
+Provides-Extra: pipeline
+Provides-Extra: scout
+Requires-Dist: faiss-cpu>=1.7.0; extra == 'scout'
+Requires-Dist: sentence-transformers>=2.2.2; extra == 'scout'
+Description-Content-Type: text/markdown
+
+# VULCA SDK
+
+AI-native creation organism. Create, critique, and evolve cultural art.
+
+## Install
+
+```bash
+pip install -e vulca/   # From repo root
+```
+
+## Quick Start
+
+```python
+import vulca
+
+# Evaluate an artwork (mock mode — no API key needed)
+result = vulca.evaluate("painting.jpg", tradition="chinese_xieyi", mock=True)
+print(result.scores)         # {"L1": 0.85, "L2": 0.78, ...}
+print(result.weighted_total) # 0.82
+
+# Create through the full pipeline
+result = vulca.create("Misty mountains in ink wash", provider="mock")
+print(result.status)         # "completed"
+
+# Human-in-the-loop with custom weights
+result = vulca.create(
+    "水墨山水",
+    provider="mock",
+    hitl=True,
+    weights={"L1": 0.3, "L2": 0.2, "L3": 0.2, "L4": 0.15, "L5": 0.15},
+)
+# result.status == "waiting_human"
+```
+
+## CLI
+
+```bash
+vulca evaluate painting.jpg --tradition watercolor
+vulca create "Garden scene" --provider mock
+vulca create "水墨山水" --hitl --weights "L1=0.3,L2=0.2,L3=0.2,L4=0.15,L5=0.15"
+vulca traditions  # List all 9 cultural traditions
+```
+
+## MCP Server
+
+For AI agents (Claude Code, OpenClaw, etc.):
+
+```bash
+vulca-mcp  # Exposes 3 tools: create_artwork, evaluate_artwork, list_traditions
+```
+
+## Architecture
+
+```
+vulca/src/vulca/
+├── pipeline/     # Execution engine + 3 built-in nodes + 3 templates
+├── cultural/     # 9 YAML tradition configs with L1-L5 weights
+├── scoring/      # VLM model routing + L1-L5 evaluation types
+├── storage/      # Session/Feedback protocol + JSONL backend
+├── intent/       # Natural language → tradition resolution
+├── media/        # MediaType enum + creation recipe types
+├── _vlm.py       # Gemini Vision L1-L5 scoring (core)
+├── _engine.py    # Evaluation engine singleton
+├── cli.py        # CLI entry point
+└── mcp.py        # MCP server entry point
+```
+
+## Cultural Traditions
+
+9 traditions with YAML-defined weights, terminology, and taboos:
+
+| Tradition | L1 | L2 | L3 | L4 | L5 |
+|-----------|----|----|----|----|-----|
+| Chinese Xieyi | 0.10 | 0.15 | 0.25 | 0.20 | 0.30 |
+| Chinese Gongbi | 0.15 | 0.30 | 0.25 | 0.15 | 0.15 |
+| Japanese Traditional | 0.15 | 0.20 | 0.20 | 0.20 | 0.25 |
+| Western Academic | 0.20 | 0.25 | 0.15 | 0.25 | 0.15 |
+| Islamic Geometric | 0.25 | 0.30 | 0.20 | 0.15 | 0.10 |
+| Watercolor | 0.20 | 0.25 | 0.15 | 0.20 | 0.20 |
+| African Traditional | 0.15 | 0.20 | 0.30 | 0.20 | 0.15 |
+| South Asian | 0.15 | 0.20 | 0.25 | 0.15 | 0.25 |
+| Default | 0.20 | 0.20 | 0.20 | 0.20 | 0.20 |
+
+Weights evolve automatically through the self-evolution system.
+
+## Self-Evolution
+
+The system learns from every evaluation session:
+
+1. **ContextEvolver** adjusts L1-L5 weights per tradition based on scoring patterns
+2. **FewShotUpdater** selects high-scoring examples (≥0.75) as reference benchmarks
+3. **VLM prompt** receives evolved weights, few-shot calibration, and tradition insights
+4. `get_weights()` returns evolved weights when available, falling back to YAML defaults
+
+## Tests
+
+```bash
+cd vulca && .venv/bin/python -m pytest tests/ -v  # 218 tests
+```
+
+## License
+
+Apache 2.0

vulca-0.2.0/README.md

@@ -0,0 +1,103 @@
+# VULCA SDK
+
+AI-native creation organism. Create, critique, and evolve cultural art.
+
+## Install
+
+```bash
+pip install -e vulca/   # From repo root
+```
+
+## Quick Start
+
+```python
+import vulca
+
+# Evaluate an artwork (mock mode — no API key needed)
+result = vulca.evaluate("painting.jpg", tradition="chinese_xieyi", mock=True)
+print(result.scores)         # {"L1": 0.85, "L2": 0.78, ...}
+print(result.weighted_total) # 0.82
+
+# Create through the full pipeline
+result = vulca.create("Misty mountains in ink wash", provider="mock")
+print(result.status)         # "completed"
+
+# Human-in-the-loop with custom weights
+result = vulca.create(
+    "水墨山水",
+    provider="mock",
+    hitl=True,
+    weights={"L1": 0.3, "L2": 0.2, "L3": 0.2, "L4": 0.15, "L5": 0.15},
+)
+# result.status == "waiting_human"
+```
+
+## CLI
+
+```bash
+vulca evaluate painting.jpg --tradition watercolor
+vulca create "Garden scene" --provider mock
+vulca create "水墨山水" --hitl --weights "L1=0.3,L2=0.2,L3=0.2,L4=0.15,L5=0.15"
+vulca traditions  # List all 9 cultural traditions
+```
+
+## MCP Server
+
+For AI agents (Claude Code, OpenClaw, etc.):
+
+```bash
+vulca-mcp  # Exposes 3 tools: create_artwork, evaluate_artwork, list_traditions
+```
+
+## Architecture
+
+```
+vulca/src/vulca/
+├── pipeline/     # Execution engine + 3 built-in nodes + 3 templates
+├── cultural/     # 9 YAML tradition configs with L1-L5 weights
+├── scoring/      # VLM model routing + L1-L5 evaluation types
+├── storage/      # Session/Feedback protocol + JSONL backend
+├── intent/       # Natural language → tradition resolution
+├── media/        # MediaType enum + creation recipe types
+├── _vlm.py       # Gemini Vision L1-L5 scoring (core)
+├── _engine.py    # Evaluation engine singleton
+├── cli.py        # CLI entry point
+└── mcp.py        # MCP server entry point
+```
+
+## Cultural Traditions
+
+9 traditions with YAML-defined weights, terminology, and taboos:
+
+| Tradition | L1 | L2 | L3 | L4 | L5 |
+|-----------|----|----|----|----|-----|
+| Chinese Xieyi | 0.10 | 0.15 | 0.25 | 0.20 | 0.30 |
+| Chinese Gongbi | 0.15 | 0.30 | 0.25 | 0.15 | 0.15 |
+| Japanese Traditional | 0.15 | 0.20 | 0.20 | 0.20 | 0.25 |
+| Western Academic | 0.20 | 0.25 | 0.15 | 0.25 | 0.15 |
+| Islamic Geometric | 0.25 | 0.30 | 0.20 | 0.15 | 0.10 |
+| Watercolor | 0.20 | 0.25 | 0.15 | 0.20 | 0.20 |
+| African Traditional | 0.15 | 0.20 | 0.30 | 0.20 | 0.15 |
+| South Asian | 0.15 | 0.20 | 0.25 | 0.15 | 0.25 |
+| Default | 0.20 | 0.20 | 0.20 | 0.20 | 0.20 |
+
+Weights evolve automatically through the self-evolution system.
+
+## Self-Evolution
+
+The system learns from every evaluation session:
+
+1. **ContextEvolver** adjusts L1-L5 weights per tradition based on scoring patterns
+2. **FewShotUpdater** selects high-scoring examples (≥0.75) as reference benchmarks
+3. **VLM prompt** receives evolved weights, few-shot calibration, and tradition insights
+4. `get_weights()` returns evolved weights when available, falling back to YAML defaults
+
+## Tests
+
+```bash
+cd vulca && .venv/bin/python -m pytest tests/ -v  # 218 tests
+```
+
+## License
+
+Apache 2.0

vulca-0.2.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vulca"
+version = "0.2.0"
+description = "AI-native creation organism. Create, critique, and evolve cultural art."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "Yu Haorui", email = "yuhaorui48@gmail.com" },
+]
+keywords = ["ai", "art", "evaluation", "cultural", "vlm", "pipeline", "creation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+    "litellm>=1.0.0",
+    "httpx>=0.25.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+pipeline = []
+scout = [
+    "sentence-transformers>=2.2.2",
+    "faiss-cpu>=1.7.0",
+]
+graph = [
+    "langgraph>=0.2.0",
+]
+mcp = [
+    "fastmcp>=3.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://vulcaart.art"
+Documentation = "https://github.com/vulca-org/vulca"
+Repository = "https://github.com/vulca-org/vulca"
+Issues = "https://github.com/vulca-org/vulca/issues"
+
+[project.scripts]
+vulca = "vulca.cli:main"
+vulca-mcp = "vulca.mcp_server:mcp.run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vulca"]
+
+[tool.hatch.build]
+artifacts = ["src/vulca/cultural/data/**"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

vulca-0.2.0/src/vulca/__init__.py

@@ -0,0 +1,42 @@
+"""VULCA -- AI-native creation organism.
+
+Create, critique, and evolve cultural art through multi-agent AI pipelines.
+
+Usage::
+
+    import vulca
+
+    # Evaluate an artwork
+    result = vulca.evaluate("painting.jpg")
+    print(result.score)          # 0.82
+    print(result.tradition)      # "chinese_xieyi"
+    print(result.dimensions)     # {"L1": 0.75, "L2": 0.82, ...}
+
+    # With intent
+    result = vulca.evaluate("painting.jpg", intent="check ink wash style")
+
+    # With explicit tradition
+    result = vulca.evaluate("painting.jpg", tradition="chinese_xieyi")
+
+    # Async
+    result = await vulca.aevaluate("painting.jpg", intent="...")
+"""
+
+from vulca._version import __version__
+from vulca.create import acreate, create
+from vulca.evaluate import aevaluate, evaluate
+from vulca.session import asession, session
+from vulca.types import CreateResult, EvalResult, SkillResult
+
+__all__ = [
+    "__version__",
+    "evaluate",
+    "aevaluate",
+    "create",
+    "acreate",
+    "session",
+    "asession",
+    "EvalResult",
+    "CreateResult",
+    "SkillResult",
+]

vulca-0.2.0/src/vulca/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running vulca as ``python -m vulca``."""
+
+from vulca.cli import main
+
+main()

vulca-0.2.0/src/vulca/_dimensions.py

@@ -0,0 +1,82 @@
+"""L1-L5 dimension name normalization and bidirectional mapping.
+
+Provides canonical mapping between short names (L1-L5) and full descriptive names,
+plus utilities for converting between various naming formats (snake_case, camelCase, spaced).
+"""
+
+from __future__ import annotations
+
+# Canonical L1-L5 definitions
+DIMENSION_NAMES: dict[str, str] = {
+    "L1": "Visual Perception",
+    "L2": "Technical Execution",
+    "L3": "Cultural Context",
+    "L4": "Critical Interpretation",
+    "L5": "Philosophical Aesthetics",
+}
+
+# Reverse mapping: full name -> L-code
+_FULL_TO_CODE: dict[str, str] = {v.lower(): k for k, v in DIMENSION_NAMES.items()}
+
+# Snake case variants — includes both paper names and prototype names
+_SNAKE_TO_CODE: dict[str, str] = {
+    # Paper terminology (VULCA-Bench / EMNLP 2025)
+    "visual_perception": "L1",
+    "technical_execution": "L2",
+    "cultural_context": "L3",
+    "critical_interpretation": "L4",
+    "philosophical_aesthetics": "L5",
+    # Prototype terminology (wenxin-backend)
+    "technical_analysis": "L2",
+    "philosophical_aesthetic": "L5",
+}
+
+
+def to_code(name: str) -> str:
+    """Convert any dimension name format to L-code (L1-L5).
+
+    Accepts: "L1", "Visual Perception", "visual_perception", "VisualPerception"
+    Returns: "L1" (or the original string if unrecognized)
+    """
+    # Already an L-code
+    if name in DIMENSION_NAMES:
+        return name
+
+    # Full name match (case-insensitive)
+    lower = name.lower().strip()
+    if lower in _FULL_TO_CODE:
+        return _FULL_TO_CODE[lower]
+
+    # Snake case match
+    if lower in _SNAKE_TO_CODE:
+        return _SNAKE_TO_CODE[lower]
+
+    # CamelCase -> spaced -> try again
+    import re
+    spaced = re.sub(r"([a-z])([A-Z])", r"\1 \2", name).lower()
+    if spaced in _FULL_TO_CODE:
+        return _FULL_TO_CODE[spaced]
+
+    return name
+
+
+def to_full_name(code: str) -> str:
+    """Convert L-code to full descriptive name.
+
+    "L1" -> "Visual Perception"
+    """
+    return DIMENSION_NAMES.get(code, code)
+
+
+def to_snake(code: str) -> str:
+    """Convert L-code to snake_case name.
+
+    "L1" -> "visual_perception"
+    """
+    full = DIMENSION_NAMES.get(code, code)
+    return full.lower().replace(" ", "_")
+
+
+def all_codes() -> list[str]:
+    """Return all L-codes: ["L1", "L2", "L3", "L4", "L5"]."""
+    return list(DIMENSION_NAMES.keys())