开源AI工作流

Install

There are two paths for end users (pick whichever fits your environment), plus a separate path for contributors who want to modify BowerBot itself.

End users, Option A: uv (recommended)

uv manages Python and isolated tool environments for you, so you do not need to install or pin Python yourself.

uv tool install bowerbot

End users, Option B: pip

If you already maintain a Python 3.12+ environment, plain pip works:

pip install bowerbot

Contributors: developer install

To modify BowerBot itself, clone the repo and let uv manage the dev environment:

git clone https://github.com/binary-core-llc/bowerbot.git
cd bowerbot
uv sync
uv run bowerbot onboard

First-time setup

bowerbot onboard

The wizard asks for your LLM API key, your asset library directory, and your projects directory, then writes ~/.bowerbot/config.json. One file, one place, no .env.

Create a project and start building

bowerbot new "Coffee Shop"
bowerbot open coffee_shop

To plug in asset providers like Sketchfab, see Skills below.

---

Scene Builder Tools

BowerBot's core tools for building USD scenes:

🚀 Quick Start

📺 Tutorials

New to BowerBot? Watch the tutorial playlist on YouTube for setup walkthroughs, scene building demos, and tips for working with USD pipelines.

---

⚙️ Configuration

All settings live in ~/.bowerbot/config.json. The skills block holds the config for any skill packages you've installed; the example below shows what it looks like once you've installed bowerbot-skill-sketchfab (see Skills). A fresh install starts with "skills": {}.

{
  "llm": {
    "model": "gpt-4.1",
    "api_key": "sk-...",
    "temperature": 0.1,
    "max_tokens": 4096,
    "context_window": null,
    "summarization_threshold": 0.75,
    "num_retries": 3,
    "request_timeout": 120.0,
    "max_tool_rounds": 25
  },
  "scene_defaults": {
    "meters_per_unit": 1.0,
    "up_axis": "Y",
    "default_room_bounds": [10.0, 3.0, 8.0]
  },
  "skills": {
    "sketchfab": {
      "enabled": true,
      "config": { "token": "your-sketchfab-token" }
    }
  },
  "assets_dir": "./assets",
  "projects_dir": "./scenes"
}

Switch models by changing one line:

{ "model": "gpt-4.1" }
{ "model": "anthropic/claude-sonnet-4-6" }
{ "model": "deepseek/deepseek-chat" }

🛠️ CLI Commands

---

Pipeline Quality Built In

BowerBot enforces ASWF USD standards at every step, not just placing assets. Fixable mismatches (non-canonical folder names, external dependencies) are auto-normalized on intake so the project copy is always self-contained. Production-required invariants are validated at intake too: assets with non-identity root transforms (Maya pivot dance, unfrozen DCC exports) are refused with a clear message and the option to bake transforms into vertex data on the project copy without touching the source. Unfixable violations (wrong root prim type, missing defaultPrim, incorrect metersPerUnit, circular references, missing dependencies) are caught at assembly time with a clear message about what's wrong and how to fix it.

"The cheapest bug to fix is the one you catch before it enters the pipeline."

---

Material Workflow

When you apply materials to an asset, BowerBot writes them into the asset folder's mtl.usda, not the scene file. The scene stays clean with only references:

You: Apply wood material to the table top
BowerBot: [searches local assets for "wood" materials]
         [discovers mesh parts: table top, legs, frame]
         [writes material definition + binding into assets/table/mtl.usda]
         Bound /table/mtl/wood_varnished to table top

The result is a production-ready asset folder:

assets/single_table/
  single_table.usda   <- root (references geo + mtl)
  geo.usda            <- geometry (untouched from source)
  mtl.usda            <- materials inline + bindings

Extension Skills

First-party skills

Maintained by Binary Core LLC alongside the BowerBot core.

Community skills

Built by external contributors, published to PyPI under each author's namespace, and listed here for discoverability. To add yours, open a PR on this README adding a row to the table below. The skill must be open source, installable via pip from public PyPI, and follow the contract in CONTRIBUTING.md.

When this list grows large enough to warrant tooling, it becomes the BowerHub skill registry.

Installing a skill

Three steps. Sketchfab as the worked example.

1. Install the skill alongside BowerBot. With uv, add it to the same tool environment:

uv tool install bowerbot --with bowerbot-skill-sketchfab

To add more skills later, rerun with every --with you want and --reinstall:

uv tool install bowerbot --with bowerbot-skill-sketchfab --with bowerbot-skill-polyhaven --reinstall

If you used plain pip to install BowerBot, install the skill in the same Python environment:

pip install bowerbot-skill-sketchfab

2. Get any credentials the skill needs. Sketchfab requires an API token from https://sketchfab.com/settings/password. Each skill's README documents what credentials (if any) it needs.

3. Add the skill's config block to ~/.bowerbot/config.json:

"skills": {
  "sketchfab": {
    "enabled": true,
    "config": { "token": "your-sketchfab-token" }
  }
}

That's it. BowerBot auto-discovers the skill via Python entry points the next time you run it. The exact shape of config is per-skill; consult the skill's README.

Verifying a skill is installed

Three commands, in increasing depth. All work on Windows, macOS, and Linux.

1. Ask BowerBot what it sees:

bowerbot skills

Lists the core scene-builder tools plus every extension skill the registry has loaded successfully. If your skill shows under "Extension skills" with its tools, you are done.

2. If it does not appear, check the package is installed:

pip show bowerbot-skill-sketchfab

If the package is installed, this prints its name, version, and location. If not, it prints Package(s) not found and exits non-zero. Install it (see Installing a skill above). Replace bowerbot-skill-sketchfab with whichever skill you are checking.

3. If the package is installed but BowerBot still does not see it, inspect the entry-point registration directly:

python -c "from importlib.metadata import entry_points; print('\n'.join(f'{ep.name} -> {ep.value}' for ep in entry_points(group='bowerbot.skills')))"

If your skill does not appear in this output despite being pip-installed, the skill's pyproject.toml is missing or broken. File an issue on the skill's repo. If the skill does appear here but bowerbot skills still does not show it, the gap is in your ~/.bowerbot/config.json: the skill's block is missing, enabled: false, or the credentials fail validate_config().

Private and in-house skills

Skills do not have to be public. Install from a private PyPI index, a git URL, or a local path:

```bash

🩹 Troubleshooting

Stuck on something? See docs/TROUBLESHOOTING.md for common issues: working alongside a DCC, skill installation, CLI rendering on Windows, and LLM tool-calling pitfalls.

---