🛠️ MAC (Multi-Agent CAD): Generate printable 3D models with 1% the tokens

Tsinghua University · IEI Lab

4 agents collaborating · 116× fewer tokens · 99.3% feature pass rate — turn concise natural language directly into printable 3D models.

Same CAD generation capability, 1/116 the tokens, 1/13 the inference cost.

| | CAD Skills | MAC (ours) | Advantage | |---|---:|---:|---:| | Tokens | 103.9M | 896k | 116× ↓ | | Cost | ¥125.69 | ¥9.67 | 13× ↓ | | Pass rate | 97.9% (138/141) | 99.3% (140/141) | ↑ |

---

🎬 Web UI walkthrough

Below is a screen recording of one full pipeline run through the Web UI.

📖 Table of Contents

• 1. 📸 Real-World Gallery
• 2. 🚀 Quick Start
• 3. 💡 Introduction
• 4. ✨ Core Features
• 5. 📝 Citation

---

1. 📸 Real-World Gallery

The 10 benchmark parts (P1–P10, sharing prompts with earthtojake/text-to-cad), the 10-piece show gallery (S1–S10, original prompts), and the articulable print-in-place demo below were each generated by MAC. The 3D rotation views and prompts for the physical printed models shown above are in qwen3.7_token.md.

🤖 Articulable Print-in-Place Models

Multi-body articulable models that print pre-assembled — multiple independent solid bodies coexist in one STEP with 0.4–1 mm clearance gaps so they move freely right off the build plate, no assembly required. This is a harder scenario than single-body generation: not only must the pipeline model each body separately, it must also precisely control clearances so the kinematic pairs actually function.

| Description | Real-shot | |---|---| | Ball-in-Cage Fidget Toy<br>A print-in-place classic: a solid ball is trapped inside a cube cage, printed as one piece — the ball rattles freely but cannot escape.<br>• 40 mm cube cage with a 16 mm radius spherical hollow inside, centered at origin<br>• 15 mm radius solid ball — 1 mm clearance from cage interior on all sides<br>• Six 12 mm radius through-holes (one on each face) make the ball visible & touchable<br><br>Articulable Gyroscope Toy<br>A print-in-place rotational pair: the inner ring spins inside the outer ring via two pivot pins.<br>• Outer ring: 30 mm outer / 23 mm inner radius, 10 mm tall, centered on XY plane<br>• Two 2.4 mm radius pivot holes through the outer ring along the X axis<br>• Inner spinner: 22 mm outer / 15 mm inner radius, 10 mm tall, 8 inner notches<br>• Two pivot pins (2.0 mm radius, 6 mm long) protrude outward into outer ring holes<br>• 0.4 mm radial clearance lets the inner ring spin freely 360° around the X axis | <img src="assets/articulable.gif" width="320" alt="Articulable models real-shot"> |

🎨 Show Gallery (S1–S10)

10 demo parts showcasing MAC on creative prints — ornaments, articulable toys, and mechanical mechanisms. Unlike P1–P10 (shared prompts), these are original to this project. Detailed prompts and 3D rotation views: qwen3.7_token.md.

| S1 | S2 | S3 | S4 | S5 | |---|---|---|---|---| | Honeycomb organizer | Gyroscope ornament | Lighthouse | Smartphone stand | Ball-in-cage | | | | | | |

| S6 | S7 | S8 | S9 | S10 | |---|---|---|---|---| | Articulable gyroscope | Multi-link chain | Geneva mechanism | Plasma reactor | Brake disc | | | | | | |

📐 Benchmark Parts (P1–P10)

10 mechanical parts covering arrayed features, boolean operations, rotational patterns, helical sweeps, and multi-body assemblies. The benchmark models shown below were all generated by this project using prompts from earthtojake/text-to-cad (CAD skill). Detailed prompts and per-feature pass rates are in qwen3.7_token.md.

Benchmark model views

| P1 | P2 | P3 | P4 | P5 | |---|---|---|---|---| | Rectangular block with 4 through-holes | Circular flange | L-bracket | Stepped shaft | Open-top enclosure | | | | | | | | ¥5.53 → ¥0.31 (17.8×) | ¥8.07 → ¥0.34 (23.7×) | ¥13.07 → ¥1.08 (12.1×) | ¥6.53 → ¥0.57 (11.5×) | ¥2.88 → ¥0.36 (8.0×) |

| P6 | P7 | P8 | P9 | P10 | |---|---|---|---|---| | Aerospace clevis bracket | Radial-engine cylinder | Centrifugal impeller | Miniature spiral staircase | Planetary gear assembly | | | | | | | | ¥15.21 → ¥3.10 (4.9×) | ¥17.42 → ¥0.53 (32.9×) | ¥32.75 → ¥1.20 (27.3×) | ¥12.80 → ¥1.45 (8.8×) | ¥11.43 → ¥0.73 (15.7×) |

Per-prompt cost (CNY): CAD Skills → MAC (cost-reduction ratio). Totals: ¥125.69 → ¥9.67 (13.0×). Raw data: docs/qwen3.7_token.md.

Design your own prints! See §2 Quick Start for how to generate a model.

---

2. 🚀 Quick Start

Installation

git clone https://github.com/Pan-Chera/Multi-Agent-CAD
cd Multi-Agent-CAD
conda env create -f environment.yml
conda activate multi_agent_cad

pip users (no conda): aider-chat pins numpy==1.26.4, but build123d>=0.8 requires numpy>=2,<3 — these conflict in pure pip. Use this workaround (verified on macOS arm64 + Python 3.11):

python3.11 -m venv .venv
source .venv/bin/activate          # Windows PowerShell: .venv\Scripts\activate
pip install --upgrade pip
# Install aider first (pulls numpy 1.26.4 + transitive deps), then force-upgrade numpy.
# Verified: aider 0.82.3 imports cleanly on numpy 2.x — the pin is over-cautious upstream.
pip install "aider-chat==0.82.3"
pip install --no-deps --force-reinstall "numpy>=2,<2.3"
pip install "build123d>=0.8" "langgraph>=0.2,<0.3" "langgraph-checkpoint>=2.0,<3.0" \
            "pydantic>=2.5" "openai>=1.20.0" "anthropic>=0.30" \
            "trimesh>=4.0" "rtree>=1.1" "scipy>=1.10" "scikit-learn>=1.3" \
            "fastapi>=0.110" "uvicorn[standard]>=0.27" "ipython>=8.15" "pytest>=7.4"
# --no-deps skips re-checking the numpy pin in pyproject.toml; fastapi+uvicorn
# are already installed by the previous step, so the [web] extras resolve.
pip install --no-deps -e .

The last step registers the mac-config-reset console script and lets you run python -m multi_agent_cad.graph from any directory. See requirements.txt / pyproject.toml for the canonical dependency list.

Windows: conda env create -f environment.yml works out of the box — trimesh and rtree come from conda-forge prebuilt; OCP is pulled in transitively by build123d (via its PyPI dep cadquery-ocp-novtk). Don't use the pure-pip workaround above on Windows — native wheels for trimesh/rtree can be unreliable. Set the API key in PowerShell as $env:DASHSCOPE_API_KEY = "sk-..." (or set DASHSCOPE_API_KEY=sk-... in cmd.exe). For the Web UI under conda, pip install -e ".[web]" inside the activated env works — uvloop auto-skips on Windows. Windows isn't in CI, but the code avoids Unix-only APIs and uses UTF-8 throughout; issues welcome.

Configuration

Edit multi_agent_cad/config.py:

| Field | Purpose | |---|---| | DS_API_KEY | API key (or set DASHSCOPE_API_KEY env var — takes priority over the in-file value) | | USER_REQUEST | Default CAD generation request | | DS_BASE_URL + 4 stages' MODEL / TEMPERATURE / MAX_TOKENS / KWARGS | Provider and per-stage model params (see §4 Hybrid Routing) |

To restore defaults after editing config:

python -m multi_agent_cad._config_defaults --reset

🔌 Use any LLM provider (not locked to Alibaba Cloud)

MAC calls models through an OpenAI-compatible endpoint. The repo defaults to Alibaba Cloud DashScope (qwen3.7-max). Point two config fields at any provider and the whole pipeline follows:

The model names and endpoints below are illustrative only. Verify the exact model ID with your provider's docs (DashScope console / OpenAI models API / etc.) before use — names like qwen3.7-max may not match what's currently served.

| Provider | DS_BASE_URL | Example *_MODEL | Notes | |---|---|---|---| | OpenAI | https://api.openai.com/v1 | gpt-5.6 | DASHSCOPE_API_KEY = your OpenAI key; set *_KWARGS = {} | | DeepSeek | https://api.deepseek.com/v1 | deepseek-v4-pro | OpenAI-compatible | | Google Gemini | https://generativelanguage.googleapis.com/v1beta/openai/ | gemini-3.6-flash | OpenAI-compatible endpoint | | Local (Ollama) | http://localhost:11434/v1 | qwen3-coder:32b | no API key needed | | Anthropic Claude | via an OpenAI-compatible gateway (OpenRouter / LiteLLM proxy) | claude-sonnet-4-6 | the Aider repair stage supports Claude natively via litellm |

For OpenAI, edit config.py:

DS_BASE_URL = "https://api.openai.com/v1"
SPEC_PLANNER_MODEL = ARCHITECT_MODEL = CODER_MODEL = REPAIR_MODEL = "gpt-5.6"
# disable the Qwen-only thinking toggle:
SPEC_PLANNER_KWARGS = ARCHITECT_KWARGS = CODER_KWARGS = REPAIR_KWARGS = {}
# Aider stage (litellm-prefixed model name):
AIDER_MODEL = "openai/gpt-5.6"

then export your key (the env-var name is historical — it accepts any OpenAI-compatible key):

export DASHSCOPE_API_KEY="sk-..."              # bash / zsh
# PowerShell:  $env:DASHSCOPE_API_KEY = "sk-..."

About the model name qwen3.7-max — it is simply the model ID served on the configured endpoint, here the flagship reasoning model of Alibaba DashScope. Every *_MODEL field accepts whatever model ID your provider exposes; nothing in the code is Qwen-specific. The only Qwen-specific piece is the enable_thinking toggle inside *_KWARGS — set *_KWARGS = {} for other providers (more per-provider examples live in config.py).

Two ways to run

MAC runs the same pipeline from the terminal or from a browser UI. Same outputs, different ergonomics — pick by what you need:

| | Terminal | Web UI | |---|---|---| | Best for | Mid-run steering | Visual feedback, easier to grasp | | Mid-run inject change / halt | ✅ 10s checkpoint per QA (1 auto / 2 inject / 3 halt) | ❌ auto-iterates only | | 3D preview of result | ❌ open STEP/STL in an external viewer | ✅ in-browser <model-viewer> + one-click downloads | | Config editing | edit config.py | fill a form | | Output location | repo root (temp_*) | per-job tempdir (optional copy to a path you specify) |

See Terminal and Web UI below.

Terminal

python -m multi_agent_cad.graph          # original workflow: deterministic coder first, Aider fallback
pyth