mechanical-engineering-skills

Tutorial: CADSmith (text → validated CadQuery)

Skill: cadsmith-text-to-cad · Paper: J. Barkley, R. Loghmani, A. Barati Farimani, CADSmith: Multi-Agent CAD Generation with Programmatic Geometric Validation, arXiv:2603.26512

Five roles (Planner → Coder → Executor → Validator → Refiner) run in two nested loops: up to 3 repairs for execution errors and up to 5 refinements for wrong geometry. Validation combines exact OpenCASCADE kernel measurements with a three-view render judged by an independent reviewer. Results from the paper’s 100-prompt benchmark: 100% execution rate, median IoU 0.963 (zero-shot 0.809), mean Chamfer distance 0.74 (zero-shot 28.4).

Use cases

Setup

npx skills add BaratiLab/mechanical-engineering-skills --skill cadsmith-text-to-cad
pip install cadquery trimesh scipy rtree pyvista matplotlib

Walkthrough: the paper’s T3 example (flanged shaft coupling)

“A flanged shaft coupling standing along the Z axis, centered at the origin in X and Y … bottom flange 50 mm diameter, 10 mm thick (Z=0–10), hub 28 mm diameter, 40 mm long (Z=10–50), top flange 50 mm, 10 mm thick (Z=50–60). Six bolt holes 6.5 mm on a 38 mm pitch circle diameter. A 14 mm center bore the full length. A keyway 5 mm wide, 2.5 mm deep on the +X bore wall.”

1. Plan (no code yet), in plan.json: three coaxial components, target_bbox [50, 50, 60], holes Ø6.5 ×6 and Ø14 ×1, n_solids: 1.

2. Retrieve API knowledge:

python scripts/cadsmith.py kb "polarArray hole keyway bore cylinder union"

This returns KB1 entries, including the polarArray pitfall: “radius = PCD/2”.

3. Code, execute, check. A typical first attempt passes the PCD (a diameter) to polarArray:

python scripts/cadsmith.py execute part_v0_bug.py --out runs/coupling/bug
python scripts/cadsmith.py check --plan plan.json --metrics runs/coupling/bug_metrics.json
"passed": false, "issues": ["holes Ø6.5: found 0 cylindrical faces, expected ≥6"]

The bbox was a perfect 50 × 50 × 60 and the solid was valid, but the holes landed outside the flange. This is the false convergence the paper warns about, and only the hole check catches it. The refiner fixes polarArray(PCD / 2, …).

4. Re-execute, then render the three judge views (isometric, high-angle rear, front profile, as in the paper):

python scripts/cadsmith.py execute part.py --out runs/coupling/v0     # bbox 50.0 × 50.0 × 60.0, valid, 1 solid
python scripts/cadsmith.py check --plan plan.json --metrics runs/coupling/v0_metrics.json   # passed
python scripts/cadsmith.py render runs/coupling/v0.stl --out runs/coupling/v0_views.png

Three judge views

The judge counts six holes per flange, the bore with its +X keyway, and the hub between the flanges, and confirms the bbox, so the part passes. Use a separate subagent as the judge when possible; the paper used a stronger, independent model to avoid self-confirmation.

5. Benchmark against a reference (an independently built revolve):

python scripts/cadsmith.py eval runs/coupling/v0.stl runs/coupling/ref.stl

| Model | Chamfer distance | F1 @ 1 mm | IoU | Noise floor (ref vs ref) | |—|—|—|—|—| | Correct coupling | 1.100 | 0.838 | 0.996 | CD 1.096, F1 0.842 | | PCD bug | 2.125 | 0.791 | 0.946 | — |

Read metrics against the noise floor. With 10k sample points, two identical parts can’t reach CD = 0 or F1 = 1 at τ = 1 mm. The correct part sits at the floor.

Lessons the tests encode

Prompts to try