MAC (Multi-Agent CAD)
A decoupled multi-agent framework that turns concise natural language into printable 3D CAD models using roughly 1/116 of the tokens of a single-agent approach.
White-box transparency is excellent (every intermediate artifact serialized and auditable, iteration checkpoints for intervention) and source attribution is complete (MIT, baseline citations, vendored-package attribution). Deductions: generated code executes in a server-side subprocess and the Web UI binds 0.0.0.0 with only a 'trusted-network' caveat, no sandboxing evidence; config.py permits writing the API key into a file (env-var priority exists but the in-file path is encouraged); dependencies are pinned with the conflict documented but no lockfile; no destructive defaults, and rollback exists via config-reset and halt-keeps-artifacts.
Install instructions, dependency lists, and entry points are consistent across README, pyproject, requirements.txt, and CI. Deductions: the pip path is inherently fragile (requires --no-deps to bypass the numpy pin — a nameable fragility); failure-message quality (QA failures, aider drift) is essentially absent from the static evidence, so a thin score.
Audience and scenarios are clear (research, 3D printing); environment fit is excellent (conda/pip/macOS/Windows/CI all covered with caveats). Deductions: capability boundaries are only implied by benchmark scope, no explicit 'not for X' statement; trigger precision is described (10s checkpoints, cache conditions) but with a nameable known pitfall (changing the prompt without clearing the cache reuses the old model).
Information architecture, install notes, and examples are first-rate; license complete. Deductions: no CHANGELOG (only the 1.0.x table in SECURITY.md); authorship is inconsistent — pyproject says 'PUMA', LICENSE/README say Tsinghua IEI, and 2026 dates are anomalous; temp_* filenames rely on manual cleanup; the DASHSCOPE_API_KEY env-var name is self-admittedly historical.
Output usability is strong (STEP/STL/measurements JSON/3D preview/downloads); marginal value is backed by per-prompt cost and token breakdowns; cost-benefit claims are quantified and specific. As a static review these claims are not independently executed, but the internal evidence is coherent.
Fact/inference separation is well done (the 10× wall-clock figure is explicitly labeled an unmeasured order-of-magnitude estimate; model names flagged as illustrative). Deductions: the headline numbers (116×, 99.3%) are self-reported against the baseline, so cross-source corroboration is thin; claim traceability depends on docs/qwen3.7_token.md and quantified_quality.md which are not in this evidence set and could not be checked.
- Generated build123d Python executes in a server-side subprocess and the Web UI binds 0.0.0.0 by default — never expose it on an untrusted network; use an SSH tunnel.
- Do not put DASHSCOPE_API_KEY into config.py itself; prefer the environment variable and verify the file is never committed.
- Clear the two pipeline_cache/ JSON files before changing USER_REQUEST, otherwise the old model is silently returned.
- The 116× token saving, 99.3% pass rate, and 10× speed claims are self-reported and unverified; reproduce the benchmark per docs/quantified_quality.md before adoption.
- The pure-pip install path relies on --no-deps to bypass aider-chat's numpy pin — a fragile install; prefer the conda path.
- Authorship is inconsistent (pyproject 'PUMA' vs README/LICENSE 'Tsinghua IEI') and the publisher is unverified; perform your own diligence before enterprise adoption.
What does this agent do, and when should you use it?
MAC is an open-source text-to-CAD framework from Tsinghua University's IEI Lab that replaces expensive long-context single-agent reasoning with four agents wired together by a LangGraph state machine: Spec Planner, Geometric Architect, Python Coder, and an Autonomous Skill Loop with an Aider repair cycle. Stages exchange only compact structured states (CADBrief, ArchitectPlan JSON, QA reports) instead of raw conversation history, cutting total tokens from 103.9M to 896k, cost from ¥125.69 to ¥9.67, and raising the feature pass rate from 97.9% to 99.3% on a 10-prompt / 141-feature benchmark. Models are called through an OpenAI-compatible endpoint, defaulting to Alibaba DashScope's qwen3.7-max but also supporting OpenAI, DeepSeek, Gemini, local Ollama models, and Claude via a gateway. Code generation is largely token-free: the deterministic translator _plan_to_code converts ArchitectPlan directly into build123d code, emitting #TODO_AIDER placeholders only for unsupported step types. The system runs from a terminal or a FastAPI-based Web UI, serializes every intermediate artifact to disk for audit, and outputs final STEP/STL files along with generated source, white-box measurements, and diagnostics.
MAC reads a natural-language USER_REQUEST from multi_agent_cad/config.py and processes it through a four-stage pipeline: 1) Spec Planner parses the request into a CADBrief JSON containing only 3 verification targets; 2) Geometric Architect produces an ArchitectPlan JSON with sketches, steps, and selectors; 3) the Python Coder's deterministic translator _plan_to_code (multi_agent_cad/nodes.py) converts the plan into build123d code, supporting extrude, revolve, hole, boolean_union/cut, pattern_linear/circular, mirror, fillet, chamfer, and shell operations, with #TODO_AIDER placeholders for unsupported steps; 4) the Autonomous Skill Loop executes the code to produce STEP/STL, runs white-box QA using feature measurements (temp_measurements_*.) and runtime diagnostics (temp_missed_*., classified as MISSED_CUT / FILLET_FAILED / CHAMFER_FAILED), and invokes an Aider (aider-chat 0.82.3) repair loop on failure. Each QA pass opens a 10-second checkpoint to auto-iterate (1), inject change requirements (2), or halt (3). Entry points are python -m multi_agent_cad.graph (or graph_aider variant) and python -m multi_agent_cad.web (FastAPI + Uvicorn Web UI with in-browser model-viewer GLB preview and artifact downloads). pipeline_cache/ stores the first two stages' outputs so re-runs of the same prompt skip both LLM stages.
- Mechanical engineers or makers who want a one-sentence prompt to yield a printable part (flange, bracket, planetary gear assembly) while keeping API costs low.
- Users designing print-in-place articulable models: MAC handles multiple independent solid bodies in one STEP with precise 0.4–1 mm clearance gaps, e.g., a ball-in-cage fidget toy and a spinning gyroscope.
- Teams wanting per-stage model mixing: a cheap model for requirement parsing, qwen3.7-max for geometric reasoning, Claude/GPT for code repair — each stage has independent MODEL/TEMPERATURE/MAX_TOKENS/KWARGS settings.
- Researchers training specialized small models: because stages hand off only via CADBrief/ArchitectPlan structured JSON, any single stage (e.g., Architect) can be swapped without touching the rest.
- Engineering teams needing auditable workflows: all intermediate artifacts are on disk, and iteration checkpoints allow human intervention with injected change requirements.
- Local-first users with no cloud dependency: run the full pipeline against Ollama (e.g., qwen3-coder:32b) at http://localhost:11434/v1.
What are this agent's strengths and limitations?
- Token efficiency is the core differentiator: benchmarked total tokens drop from 103.9M to 896k (116×), cost from ¥125.69 to ¥9.67 (13×), API calls from 1,307 to 50, while the feature pass rate rises to 99.3%.
- A deterministic translator generates code for common CAD operations (extrude, revolve, hole, booleans, patterns, fillet, etc.) at zero token cost; the LLM is only invoked on edge cases.
- White-box and auditable: CADBrief, ArchitectPlan, generated source, feature measurements, and failure diagnostics are all serialized to disk, plus a 10-second human-intervention checkpoint after each QA loop where change requirements can be injected verbatim into the Aider repair prompt.
- Hybrid routing: all four stages pick their own model with independent temperature, max_tokens, and kwargs; any single stage can be replaced with a locally trained specialist model without touching the others.
- Dual entry points — terminal and Web UI — with the Web UI offering in-browser 3D preview and one-click downloads.
- Installation involves a real dependency conflict: aider-chat hard-pins numpy==1.26.4 against build123d's numpy>=2; the pure-pip path requires force-reinstalling numpy 2.x, and Windows users are advised to stick to conda.
- Generated Python code executes server-side; the Web UI is explicitly single-user, trusted-network only and must not be exposed to untrusted networks.
- Defaults bind to Alibaba DashScope and qwen3.7-max; switching providers requires clearing the Qwen-only enable_thinking toggle (*_KWARGS = {}), and the README warns that example model names (e.g., gpt-5.6) are illustrative — actual model IDs must be verified with each provider.
- The stage cache checks only file existence, not whether USER_REQUEST matches, so changing the prompt without clearing the cache regenerates the old model.
- The claimed ~10× wall-clock speedup is an order-of-magnitude estimate, not a formally benchmarked figure, as the authors state.
How do you install or deploy this agent?
Recommended conda flow:
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 install --no-deps "aider-chat==0.82.3"The last pip command is required: every aider-chat release on PyPI hard-pins numpy==1.26.4, which conflicts with build123d's numpy>=2 requirement, and conda's pip subprocess cannot bypass the pin, so aider is omitted from environment.yml. Pure pip users (verified on macOS arm64 + Python 3.11) should install aider-chat==0.82.3 first, then pip install --no-deps --force-reinstall "numpy>=2,<2.3", followed by build123d>=0.8, langgraph>=0.2,<0.3, pydantic>=2.5, openai>=1.20.0, trimesh>=4.0, etc., and finally pip install --no-deps -e .. On Windows, use the conda flow; avoid the pure-pip workaround. For the Web UI, additionally run pip install -e ".[web]" (installs fastapi + uvicorn). Set credentials: export DASHSCOPE_API_KEY="sk-..." (the variable name is historical — it accepts any OpenAI-compatible key), or in PowerShell $env:DASHSCOPE_API_KEY = "sk-...".
How do you use this agent?
1) Edit multi_agent_cad/config.py: set DS_API_KEY (or env var), USER_REQUEST (default generation request), DS_BASE_URL, and per-stage *_MODEL/*_TEMPERATURE/*_MAX_TOKENS/*_KWARGS. 2) Terminal: run python -m multi_agent_cad.graph (default workflow) or python -m multi_agent_cad.graph_aider (applies USER_REQUEST as modification requirements to an existing temp_design*.py). LangGraph events stream to the terminal; at each QA pass a 10-second checkpoint offers 1/2/3 for auto-iterate, inject changes, or halt. Outputs land in the repo root: temp_output_0.step/.stl, temp_design_0.py, temp_measurements_0., temp_missed_0.. 3) Web UI: pip install -e ".[web]" then python -m multi_agent_cad.web; open http://<server>:8000 in a browser, fill the form, preview the GLB, download artifacts; generated code executes server-side, so it is single-user, trusted-network only — use an SSH tunnel for remote access. 4) After changing the prompt, clear the cache: rm pipeline_cache/cad_brief. pipeline_cache/architect_plan., or set force_refresh: True. Restore default config with python -m multi_agent_cad._config_defaults --reset.
How does this agent compare with similar options?
The README quantitatively benchmarks MAC against earthtojake/text-to-cad (CAD Skills): on the same 10 benchmark prompts, CAD Skills consumed 103.9M tokens, ¥125.69, 1,307 API calls, and a 97.9% pass rate, versus MAC's 896k tokens, ¥9.67, 50 calls, and 99.3%. The 10 benchmark prompts (P1–P10) and the vendored packages/cadpy STEP/GLB runtime are derived from that project (redistributed under its original MIT license). The authors ask that MAC citations also credit that project.