vibe-cading

A parametric, AI-friendly Code-CAD library in Python.
Reusable mechanical components — plus adapters that bridge RC hardware to Lego Technic.

Built on CadQuery, every part is a Python class
whose geometry regenerates from typed parameters — change a number, get a new part.
Standard families (screws, gears, nuts) build straight from real-world size tables.
And it's designed to be driven by humans and AI agents.

Samples

HelicalGear · double_helix=True, module=1.0, teeth=30	LegoTechnicLLiftarm · 3×5 Technic L-liftarm
ServoMountBase + ServoMountClamp · SG90 → Lego, dovetail-clamped	PrintInPlaceHinge · 2 countersunk M3 holes / leaf

_{🔄 Click any sample to spin the real model in GitHub's interactive 3D viewer.}

Each part is a few lines of Python. The geometry is a function of the parameters,
so a part is never a static shape — it's a generator:

import cadquery as cq
from vibe_cading.mechanical.gears.spur import SpurGear

# Parameters drive the geometry — change teeth, get a new gear.
gear = SpurGear.from_iso(module=1.0, teeth=20, face_width=5.0)
cq.exporters.export(gear.solid, "gear.step")   # extension picks the format

Why vibe-cading

• Parametric by construction. Every part regenerates from typed constructor
  parameters; there are no frozen meshes. Standard families come from size tables —
  MetricMachineScrew.from_size("M3", length=12), SpurGear.from_iso(module=1, teeth=20, face_width=5.0) —
  so one class yields a whole catalogue of real-world parts.
• Parametric both ways. Forward is params → part. Reverse goes the other
  direction: bring an existing STEP file, let the engine's analysis tools
  measure it, and rebuild it — by hand or with an AI agent — as editable parametric
  code. boolean_diff then confirms the rebuild matches the original to within ~1%
  by volume. That's how the SG90 servo body in the samples above was built:
  measured from a reference STEP, rebuilt as a parametric class. Works best on
  simple prismatic parts.
• Print-ready fits. Real-world nominal geometry stays fixed; per-machine,
  per-material clearances live in a separate tolerance profile you calibrate once.
  The same model bores a tight hole on one printer and a loose one on another — the
  profile absorbs that, not your code.
• Built for humans and AI agents. Drive it from Python, from the live OCP CAD
  viewer, or from any MCP client. A multi-role agent workflow ships
  in-repo so models can be generated, validated, and reviewed by AI agents.
• RC ↔ Lego Technic. A library of reusable mechanical components (screws, gears,
  joints, bearings, heat-set inserts, hinges, standoffs) plus adapters that mate RC
  hardware to the 8 mm Lego Technic stud grid (motor mounts, ESC holders, axle adapters).

Featured models

Each is parametric — the call below is the whole construction.

…plus magnets, enclosures, more fastener and bearing types, the Lego Technic
primitives, and the RC adapters. See vibe_cading/ for the full library tree,
and four runnable demos under examples/.

Quick start

This project runs in a VS Code Dev Container — no local Python or CadQuery install.

1. Clone the repo, open it in VS Code, and click Reopen in Container
   (Python 3.11 + CadQuery + the OCP CAD viewer are provisioned for you).
2. Run an example — writes STEP + SVG to examples/build/:

   python3 examples/gear_from_iso.py
   

3. Preview any part live in the OCP CAD viewer (port 3939). Start a viewer
   first — view.py only pushes to one, it does not launch one. Either open
   the VS Code panel (Command Palette → OCP CAD Viewer: Open viewer), or run
   the standalone server and use a plain browser tab, which needs no VS Code:

   python3 -m ocp_vscode --host 0.0.0.0 --port 3939   # then open http://localhost:3939/viewer
   

   With a viewer running, push any part to it:

   python3 vibe_cading/tools/view.py vibe_cading.mechanical.gears.spur.SpurGear
   

   Details and troubleshooting: docs/viewer.md.
4. Before your first print, calibrate the slip fit for your printer + material:
   print the axle gauge and run python3 vibe_cading/tools/calibrate.py slip — it
   writes the measured slip.radial into your gitignored print_profiles_user.json
   so Lego pins and axles fit. (Why it matters, plus the other knobs:
   docs/print-tolerances.md.)

→ Full dev environment, the local test/lint/build loop (python build.py), and
adding your own parts: CONTRIBUTING.md.

Just want the library in your own project? It's on PyPI:

pip install vibe_cading            # the library
pip install "vibe_cading[mcp]"     # + the MCP server for AI agents

On headless Linux (cloud servers, CI runners, slim Docker images), CadQuery's
geometry kernel also needs the system OpenGL library — install it once with
apt install libgl1 (or your distro's equivalent). Desktop Linux, macOS, and
Windows already have it.

Tolerances & fit

Printed fits are printer- and material-dependent. vibe-cading keeps real-world
nominal geometry fixed and carries the per-machine clearance separately in a
tolerance profile — fdm_standard, resin_precise, and cnc ship in-repo,
selected via PRINT_PROFILE and overridable per-machine in a gitignored
print_profiles_user.json.

slip.radial (the Lego-axle slip fit) is the one knob almost everyone re-tunes;
calibrate it by printing a gauge and running python3 vibe_cading/tools/calibrate.py slip.
The free and press defaults work for most FDM printers out of the box.

→ Full fit-grade model and calibration workflow: docs/print-tolerances.md.

Learn more

License

AGPLv3. See LICENSE-FAQ.md for a plain-language guide
to what this means for your projects.

For commercial or closed-source use cases that are incompatible with AGPLv3,
dual-licensing is available. Contact [email protected] for details.