Metadata-Version: 2.4
Name: vibeinc-ai-art-team
Version: 0.2.1
Summary: AI-first Blender art-team toolkit driven by MCP: concept, 3D, art-director review, self-fix, packs, layout, camera, render
Author: VibeInc
License-Expression: MIT AND GPL-3.0-or-later
Project-URL: Homepage, https://github.com/VibeIncStudio/ai-art-team
Project-URL: Source, https://github.com/VibeIncStudio/ai-art-team
Keywords: blender,mcp,game-art,3d,ai,procedural,asset-pipeline
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSES.md
License-File: blender_addon/vibeinc_art_team/LICENSE
Dynamic: license-file

# VibeInc AI Art Team

An open-source, AI-first Blender toolkit: an "art team" of roles that agents (Claude Code, through MCP) and
people (through a Blender panel) can drive. Every action runs in headless Blender too, returns machine-readable
JSON, and measures its own output.

Made by [VibeInc](#studio-and-privacy), an AI-first game studio. The core tool is free and always will be.

![Concept to game-ready mesh](https://raw.githubusercontent.com/VibeIncStudio/ai-art-team/main/evidence/radio_eevee.png)

*GPT concept, then TRELLIS.2 on the local GPU, then Blender cleanup to 12k triangles, 35 cm tall, pivot at the base.
Rendered with `render_still`.*

## How it works

You, or Claude, ask for something in plain words. The request becomes one of 36 tools, and Blender does the work in
the background. Each tool returns what it made, along with its own checks: triangle count, scale, pivot,
clearance from walls, and whether anything is cropped. When a check fails, the agent can fix the problem before you
ever see it.

![Draft vs best quality](https://raw.githubusercontent.com/VibeIncStudio/ai-art-team/main/evidence/radio_draft_vs_hq.png)

*The same concept at TRELLIS.2 draft quality (left) and best quality (right), after Blender cleanup.*

## Why it makes the work easier

- **Idea to game-ready prop in about 5 minutes:** 45 s of concept art, about 3 min of 3D on a free 16 GB GPU, then
  seconds of cleanup.
- **The boring part is automatic:** scale, pivots, UVs, triangle budgets and GLB/FBX exports.
- **Blockouts and camera passes in seconds:** the same seed gives the same level, and walkthroughs never clip
  through walls.
- **No new subscriptions needed:** it uses your ChatGPT plan, your GPU and free Blender. Meshy is an optional
  paid engine (your own account) for higher-quality meshes, rigging and animation; TRELLIS.2 stays free.
- **Agents can run it unattended:** results are plain JSON with pass/fail checks, so Claude knows whether each step
  worked.

## What works today (v0.2.1)

| Role | Engine | Status | Tool(s) |
|---|---|---|---|
| Concept artist | GPT image generation through your ChatGPT plan (Codex app); or the OpenAI API with your key | Works (API path untested: no key here) | `concept` |
| 3D artist | TRELLIS.2 on your GPU (free), or Meshy with your own key (paid, cleared for commercial use; remeshed to budget with the detailed surface baked on), then Blender cleanup with optional LODs | Works (both tested live) | `image_to_mesh`, `cleanup_mesh`, `bake_detail` |
| Surfacing | Script-built PBR presets, bake to maps, photo to PBR | Works | `assign_material`, `photo_to_pbr`, `list_material_presets` |
| Layout | Seeded or spec-driven greybox levels | Works | `greybox` |
| Camera | Orbit, greybox flythrough, explicit paths | Works | `camera_path` |
| Render | Workbench (viewport look), EEVEE, Cycles on CPU; studio lighting; image sequences for turntables and flythroughs | Works | `render_still`, `studio_setup`, `render_frames` |
| Animator | BVH import (100STYLE, CC BY 4.0); Meshy auto-rig and Meshy's animation library with your own key (paid) | Works (Meshy rig and clips tested live). Kimodo is blocked until a Hugging Face login. | `import_motion`, `list_motion_styles`, `autorig`, `list_animations`, `animate` |
| Sound | Search your own library | Search works. **Generation is a stub.** | `sound_search`, `sound_generate` |
| Art director | GPT (your ChatGPT plan via Codex) and/or Gemini 4 Argon (your key) score a render; a saved style bible adds an on-style score | GPT tested live; Gemini tested offline | `review_asset`, `style_save`, `list_styles` |
| Self-fix | The art director's lowest score picks a fix: Meshy retexture, GPT-drawn views + Meshy multi-view rebuild, or Meshy remesh; within a credit budget | Works (needs a Meshy key) | `improve_asset` |
| One shot | Concept → mesh → cleanup → render | Works | `make_prop` |
| Asset packs | Matching concepts → meshes → renders → art-director review → regenerate or self-fix → contact sheet → `.vibepack` with LODs | Works | `make_pack` |

Plus: `status`, `list_providers`, `connect_provider`, `package_asset`, `verify_package`, `about`,
`usage_stats`, `live_blender`, `job_status`, `import_asset`, `scene_report`.

## Quick start

Requirements: Blender 4.2 or newer (tested on 5.2.2) and Python 3.10 or newer. The toolkit uses only the standard
library, so it has no dependencies.

**Install with pip** (the Blender-side files come with it):

```bash
pip install vibeinc-ai-art-team
```

Or straight from GitHub: `pip install "git+https://github.com/VibeIncStudio/ai-art-team@v0.2.1"`.

This gives you the `vibeart` command and the `vibeart-mcp` server. Machine settings go in `~/.vibeart/local.json`
(same keys as `vibeart.local.example.json`), and results go to `Documents/VibeInc/art-team-output`.

**Or work from a checkout:**

1. **Machine settings.** Copy `vibeart.local.example.json` to `vibeart.local.json` and set the paths: Blender,
   your TRELLIS.2 folder, GPU lock files to respect, and your BVH and sound libraries.
2. **Check it.**
   ```bash
   python -m vibeart.cli status '{}'
   ```
3. **Use it from Claude Code.** Copy `.mcp.example.json` to `.mcp.json` and fix the path, or add the server by hand:
   ```bash
   claude mcp add vibeinc-art-team -- python <path-to>/ai-art-team/vibeart/mcp_server.py
   ```
   After a pip install, use `claude mcp add vibeinc-art-team -- vibeart-mcp` instead.
4. **Use it in Blender.** Build the extension with `python tools/build_addon.py`, then in Blender go to
   Edit > Preferences > Get Extensions > Install from Disk and pick `vibeinc_art_team-0.2.1.zip` (from the GitHub release, or `dist/` after building).
   The panel is at View3D > Sidebar > **VibeInc**.

## For agents

- Read [AGENTS.md](https://github.com/VibeIncStudio/ai-art-team/blob/main/AGENTS.md). It covers the contract, the
  rules and the typical flows.
- **Result envelope.** Every tool returns `vibeart.result/1`. The `status` field is one of
  `ok | ok_with_failed_checks | blocked | stub | error`. The envelope also carries `outputs` (file paths),
  `metrics`, `checks` (`name, passed, value, expected`), `warnings` and `provenance`.
  `render_still`, `cleanup_mesh` and `image_to_mesh` also return the image itself through MCP, so you can look at it.
- **Scenes chain.** Scene tools take `scene` (a `.blend` path). Each step loads it and saves it back.
- **Long jobs.** `concept`, `image_to_mesh`, `make_prop`, `review_asset`, `improve_asset` and `make_pack` accept
  `background: true`, which returns a `job_id` for `job_status`.
- **Live mode.** With the add-on's "Allow live control" preference on, `live_blender` runs the same actions in the
  user's open Blender. It listens on localhost only, needs a token, and only runs whitelisted actions.

### CLI examples

```bash
python -m vibeart.cli greybox '{"scene": "runs/level/level.blend", "preset": "rooms", "seed": 3, "rooms": 5}'
```

```bash
python -m vibeart.cli camera_path '{"scene": "runs/level/level.blend", "mode": "flythrough"}'
```

```bash
python -m vibeart.cli render_still '{"scene": "runs/level/level.blend", "engine": "eevee", "camera": "auto"}'
```

```bash
python -m vibeart.cli make_prop '{"prompt": "a battered field radio", "quality": "draft", "target_height_m": 0.35}'
```

## Art director and asset packs

**`review_asset`** sends a render (and, optionally, the concept it came from) to GPT through the Codex app. The job
runs in an empty folder with the read-only sandbox, so it can look at the images but cannot change files. The answer
must match a fixed JSON schema, and the toolkit checks it again before using it:

- four scores from 1 to 10: `silhouette`, `material_read`, `matches_brief`, `game_readiness`;
- `issues`, each with a criterion, a severity (`minor`, `major` or `blocker`) and a suggested fix;
- a one-line `summary`.

The asset **passes** when every score is at or above `threshold` (default 6) and no issue is a blocker. The review is
saved as `<name>.review-<time>.json` (format `vibeart.review/1`) and recorded in `provenance.json` with the model, effort,
prompt and image hash. One review takes about 15 seconds.

**`make_pack`** builds a set of matching props from a theme and a list of items (or a `count`, and GPT plans the
items):

1. Every concept shares one style prefix, so the set looks consistent.
2. Meshes are made one at a time. The step waits up to `gpu_wait_s` for GPU locks and never runs two TRELLIS jobs at
   once.
3. Each mesh gets studio lighting and an EEVEE render. The asset `.blend` itself stays clean.
4. The art director reviews every render. A failing item is regenerated once with a new seed, and the better of the
   two attempts is kept.
5. A contact sheet PNG shows the whole pack with scores.
6. Everything is packaged as one `.vibepack` (kind `prop`) with the merged provenance. TRELLIS output stays
   `commercial_use_cleared: false`.

```bash
python -m vibeart.cli make_pack '{"theme": "weathered sci-fi field gear", "items": ["field radio", "ammo crate", "medkit"], "background": true}'
```

### Style bible

`style_save` stores the studio's art direction as `styles/<name>.json`: a summary, palette, materials, wear level,
setting, shape language, things to avoid, and up to three reference images (kept next to the file). Pass its name as
`style_bible` to `concept`, `review_asset`, `improve_asset` or `make_pack`:

- concepts get the style in the prompt, and the reference images are attached (Codex provider);
- reviews add a fifth score, `on_style`, and the reviewer sees the references;
- Meshy retextures get the style's materials, palette and wear, which always fit in Meshy's 800-character prompt.

`styles/frontier-field-gear.json` is an example.

### Self-fix loop

`improve_asset` takes a mesh that failed review and works on its weakest score:

| Weakest score | Fix | Meshy credits |
|---|---|---|
| `material_read`, `on_style` | Retexture, with the reviewer's own suggested fixes in the prompt | 10 |
| `silhouette`, `matches_brief` | GPT draws front, left and back views of the same object; Meshy rebuilds from all of them | 30 |
| `game_readiness` | Remesh to the triangle budget | 5 |

After each fix the mesh is cleaned, rendered and reviewed again, and the best version so far is kept. The loop stops
when the asset passes, after `max_rounds` (default 2), or when the next fix would exceed `budget_credits`
(default 60). Credits are reserved before each request and released only when Meshy refuses it or reports the real
charge, so the budget holds even if a request times out. If GPT or Meshy is unavailable, it stops with `blocked`.
In a pack, `self_fix: true` uses this loop instead of regenerating.

Fixes never change the licence status: anything derived from TRELLIS output stays uncleared, and so does a mesh of
unknown origin.

### Detail bake (finishing)

`bake_detail` takes a textured low-poly and a detailed mesh in the same space and bakes the detailed surface into
the low-poly's normal map, keeping its colours. `replace` uses only the baked normals; `combine` blends them with the
low-poly's own normal map. It reports how many pixels carry detail, how many look like wrong hits, and whether the
two meshes line up.

With Meshy, `image_to_mesh` does this by default (`finish: true`): Meshy remeshes to the triangle budget in the same
job (no extra credits in our runs) and also returns its detailed mesh, which is baked on in `combine` mode. If the
bake's own checks fail, the unbaked version is kept and a warning says why. On the field radio the bake took 5
seconds and gave visibly crisper bevels in close-ups.

### Gemini (optional, your own key)

Set `GEMINI_API_KEY` (Google AI Studio, paid tier) to use Google's models:

- `review_asset {judges: ["gpt", "gemini"]}`: Gemini 4 Argon reviews next to GPT. Scores are averaged, a blocker
  from either judge fails the asset, and the disagreement is reported. Set `"judges": ["gpt", "gemini"]` in
  `vibeart.local.json` to make it the default. Argon costs about $2/$10 per million input/output tokens until
  2026-11-30, then $4/$20.
- `concept {provider: "gemini"}`: concept art from Nano Banana Pro (`gemini-3-pro-image`), with style references.
- **Fallback:** when your ChatGPT usage runs out (or Codex is unavailable), concepts, GPT-drawn views and reviews
  switch to Gemini automatically and say so in `warnings`. Set `"gemini_fallback": false` to turn that off.

The key is read from the environment and only sent to Google; it is never logged or written.

### Rigging and animation (Meshy, your own key)

- `autorig {source}`: Meshy's auto-rigger on a textured humanoid GLB (front toward glTF +Z) or a Meshy task id;
  5 credits. You get a rigged GLB and FBX, Meshy's free walk and run clips, and a `rig_task_id`.
- `list_animations {query}`: browse Meshy's animation library (free), e.g. `"wave"` or `"walk"`.
- `animate {rig_task_id, actions}`: library motions by name or id, 3 credits each, capped by `max_credits`.

Rigs and library motions are Meshy "Service Assets": use them as part of your character, not on their own.
[examples/character_demo.py](https://github.com/VibeIncStudio/ai-art-team/blob/main/examples/character_demo.py)
runs the whole chain from a text prompt: GPT views, Meshy multi-view 3D, detail bake, cleanup, art-director review, rig
and clips.

### LODs

`cleanup_mesh`, `image_to_mesh`, `improve_asset` and `make_pack` take `lods`, for example `[0.5, 0.25]`. That exports
`<name>_LOD1.glb` and `<name>_LOD2.glb` at half and a quarter of the triangles. Packs ship them by default.

## Determinism and self-measurement

- **Greybox.** A seed or spec always gives the same layout. It reports `layout_signature`, connectivity, grid
  snapping and blocks on floor.
- **Mesh cleanup.** Reports triangles against the budget, UVs in 0–1, UV area (overlap), texel density, pivot at the
  base centre, transforms applied, height, open edges, export files and a thumbnail. `shape_kept` fails if
  triangle reduction shrank the model (it can drop whole regions of some meshes); loose vertices left by the
  reduction are removed so the size and pivot are measured on real geometry.
- **Camera.** Reports path length, speed, minimum clearance to geometry and whether the target stays in frame.
- **Render.** Reports exposure, clipping, subject coverage and render time.
- **Photo to PBR.** Reports seam ratio before and after, normal validity and height detail.
- **Art director.** The review format is fixed by a JSON schema and validated locally (one retry if GPT strays).
  The scores themselves come from a model and can vary between runs.
- **Generators.** TRELLIS and GPT take seeds or prompts, but their output is not bit-identical between runs.
  Every run folder keeps `provenance.json`.

## GPU courtesy

`image_to_mesh` checks the lock files listed in `gpu_lock_files` and the GPU load first. If another app owns the GPU,
it refuses with `blocked`. The exception is `quality: "draft"` with `allow_busy_gpu: true`, which runs a short job of
about 3 minutes using about 4 GB. It never kills other processes.

The toolkit also runs only one TRELLIS job at a time on the machine. The TRELLIS worker process itself holds an OS
file lock (`%TEMP%/vibeart/trellis.lock`, shared by the CLI, MCP server and Blender add-on) for exactly as long as it
runs, and the OS releases it if the worker dies. `make_pack` waits for the GPU between items when `gpu_wait_s` is set.

## Money: how VibeInc earns without charging for the tool

1. **Referral links.** Users connect their own accounts. A connector can carry a VibeInc referral link, which is shown
   only with this disclosure: *"Referral link: VibeInc may earn a referral fee if you subscribe. Your price is the
   same."* Users can switch referral links off. Referral fees never change the ordering or the defaults.
   See [docs/providers.md](https://github.com/VibeIncStudio/ai-art-team/blob/main/docs/providers.md) and
   [docs/affiliate-programmes.md](https://github.com/VibeIncStudio/ai-art-team/blob/main/docs/affiliate-programmes.md).
2. **Marketplace (designed, not launched).** `.vibepack` packages carry licence, provenance, AI disclosure and file
   hashes. See [docs/marketplace.md](https://github.com/VibeIncStudio/ai-art-team/blob/main/docs/marketplace.md).
3. **Studio funnel.** "Made with VibeInc" appears in the panel, in glTF `extras.generator` and in PNG metadata.
   A visible render badge is opt-in. The panel also links to the studio and to the opt-in community.
   Links stay hidden until URLs are set in `vibeart/data/branding.json`.

## Studio and privacy

There is no telemetry unless the user opts in (`usage_stats`). If they do, the toolkit keeps per-tool counts only, on
the user's machine, and has no upload endpoint. Opting out deletes the counts. VibeInc never sells data, never uses the
user's machine for background compute, and never trains on users' creations without explicit consent.
See [docs/privacy.md](https://github.com/VibeIncStudio/ai-art-team/blob/main/docs/privacy.md).

## Licences

See [LICENSES.md](https://github.com/VibeIncStudio/ai-art-team/blob/main/LICENSES.md).
- **Meshy output** (`provider: "meshy"`) belongs to the account holder. On Meshy's free plan it is CC BY 4.0, so credit
  Meshy. Paid plans give a private licence. Your key stays in `MESHY_API_KEY` and is never written to disk.
- **TRELLIS output is not cleared for commercial use.** Its GLB export uses NVIDIA nvdiffrast, which is licensed for
  non-commercial use only. The toolkit records this in provenance, and `package_asset` refuses paid listings for it.
- 100STYLE motion needs a credit line (CC BY 4.0).

## Tests

```bash
cd tests && python -m unittest
```

- About 100 tests cover every role plus the art director, style bible, self-fix loop, Meshy (generation,
  finishing, rigging and animation, offline), Gemini, asset packs, LODs, MCP, the add-on install, the live bridge,
  providers, the marketplace and privacy. The run takes about 6 minutes with headless Blender.
- Live engine tests are opt-in: `VIBEART_LIVE_GPT=1` and `VIBEART_LIVE_TRELLIS=1`. Results of the live runs made
  during development are in [evidence/README.md](https://github.com/VibeIncStudio/ai-art-team/blob/main/evidence/README.md).

## Layout

```
vibeart/                 host package (stdlib only): roles, tools registry, MCP server, CLI, providers,
                         marketplace, branding, telemetry, jobs, live client
blender_addon/vibeinc_art_team/   Blender extension: ops_core (all bpy actions), headless runner, panel, live bridge
tests/                   unittest suite + Blender fixture builder
tools/                   build_addon.py, try_action.py, when_gpu_free.py, showcase/ (renders + composes the demo videos)
examples/                character_demo.py (concept to rigged, animated character)
docs/                    providers, affiliate research, marketplace design, privacy
evidence/                live run outputs (GPT concept, TRELLIS mesh, renders)
```

## Inspiration

Scenario's Blender plugin (announced by @emmanuel_2m on X, 14 Oct 2026) showed eight AI roles exposed through MCP. This project
has no Scenario code and does not use Scenario's service. It follows the same idea, but with engines you run yourself
or connect with your own accounts.
