Ni Jingzhe d415647e96 editor: several open solids have no product until the author picks one (use_as_product), and say so
DECISION: the editor keeps letting solids exist side by side (a tool next to its body), but they are no longer
the bodies of one implicit Part. With exactly one open solid the Part is implicit as before; with several the
notebook has no product yet and the editor asks the author which solid is the part.

WHY - THE DISCUSSION (owner and assistant, 2026-11-10; full account in design-docs/part-holds-one-solid.md)
This is the editor need that started the whole multi-body Part: several solids in one notebook with no
assembly constraint (pattern a tool, then cut). The owner's judgement was that solving it inside the Part
makes assembly hard and was wrong; the agreed answer was "a Part is one solid, and the editor supports the
several solids some other way". This commit is that other way at the editor: the solids stay visible and
editable (the preview draws them, commit "runtime + preview"), and the product is chosen, never guessed. A
guess would silently leave a solid out of the exported Part; the author knows which solid is the part.

WHAT CHANGES
- editor/gui_features.py
  - snapshot(): the implicit product exists only for exactly one open solid (and its dict loses `bodies`);
    several open solids give `product: null` while `open` still lists them.
  - use_as_product(): when the notebook has no product, a part notebook and a body that is open, it writes
    the product cell `<stem> = scad.make_part_rpart(part_id=scad.notebook_id(), body=<chosen>)`. Before, it
    refused ("no product cell"), which would have left the author without a way out.
- editor-web
  - FeatureTree: a notice with one "use <solid>" button per open solid while there is no product and
    several solids are open ("N solids are open, and a Part holds exactly one solid. Choose the part:").
    The product badge reads the one product body.
  - features.ts: FeatureState.product loses `bodies`.
  - preview.ts previewSummary: nodes `node/<id>/body:<name>` are now the notebook's open solids, not the
    bodies of a part, so the header says "N open solids" (zh-CN strings added) instead of "1 part · N bodies".
- tests: test_editor / test_editor_features follow the new product dict and the required `body` argument
  of Part; a new test drives the editor flow end to end (two open solids -> no product, a headless run
  raises SeveralOpenBodiesError naming them -> use_as_product -> the Part exists and the notebook runs).

Checked: editor-web vitest (331 tests) and tsc --noEmit pass; the editor test files pass except for the
multi-body fixtures of other files, which are updated in the tests commit of the series.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 04:01:35 +08:00
2026-11-09 14:02:31 +08:00
2026-11-09 14:02:31 +08:00
2026-09-06 18:42:33 +08:00
2026-11-09 14:02:31 +08:00
2026-11-09 14:02:31 +08:00

SimpleCADAPI repository cover

SimpleCADAPI

Parametric CAD built for agents.
Efficient · Low-overhead · Agent-native

中文 · Changelog · Skill design · Paper

Start here. Paste this line to your coding agent (Claude Code, Codex, OpenCode, …):

Read physpace.dev/sca/landing.md and landing me on this sdk.

It installs the SDK, installs the skill for itself, opens a real example in the editor, and shows you how to work with it.


The idea

CAD software was made for a person with a mouse. An agent has no mouse. It has code, a context window and a token bill. SimpleCADAPI starts from that.

Efficient More first attempts come out right, and fewer tokens are spent getting there. Change one parameter and only the cells that depend on it run again.
Low-overhead One pip install: the geometry engine is native C++ on OpenCASCADE inside the wheel, with no CadQuery or OCP stack. A functional API with no hidden state, so every step is a cell that can be cached, checked and replayed. A skill an agent reads in one batch, not twenty.
Agent-native Errors say what happened, give the measured numbers and say how to fix it. Geometry is selected by what it is (ql, stable scad.ref), not by an index that moves. Every call is recorded as a replayable graph. The editor writes what you click into the notebook, so your agent reads your selection from disk.

The evidence

Against CadQuery. Same model, same prompt, same 200 real parts, one attempt each. A frozen, independent scorer compares each result with the original.

Same model and prompt on 200 parts: SimpleCADAPI delivers 3.5 times fewer badly wrong models than CadQuery

DeepSeek-V4.1-Flash, SimpleCADAPI 2.2.7b1 vs CadQuery 2.8.0, 200 open-hardware parts from 27 projects. "Badly wrong" is a delivered model whose surface F1 at 1 mm is below 99.99 %. Disclosed in the report: the SimpleCADAPI run also had a STEP-reconstruction workflow guide, the CadQuery run a general third-party CadQuery skill; the parts are mostly simple (median 19 faces).

Against a mature industrial CAD. Tokens spent per task; the industrial CAD is driven through its MCP server.

Tokens spent per task: SimpleCADAPI uses up to 6.5 times fewer than a mature industrial CAD through its MCP

What it builds

Two six-axis arms, each an assembly of part notebooks composed with scad.use. Every joint angle and link length is a named parameter: drag a slider and the model follows.

The SG90 six-axis arm in the SimpleCADAPI editor: notebook cells and joint sliders on the left, the live assembly on the right

SG90 educational arm · 34 parts, six revolute joints solved as constraints, 3D-printable links, reserved envelopes for the electronics. sg90_arm_6dof.py

The desktop six-axis arm with a gripper in the SimpleCADAPI editor

Desktop six-axis arm with gripper · 34 parts. The joint motor is a purchased part with its real mounting interface (34 × 20 × 19.6 mm body, six M2 holes on a Ø10.5 circle), and the links carry the matching pockets, screw channels and plug windows. arm6.py

The editor, sca edit, is code-first: cells on the left, the live model on the right, a slider for every parameter. Click a solid, face, edge or vertex and it writes a selection into the notebook. Your agent reads what you picked from the file, so "chamfer these two edges" needs no ids. The editor and sca run share one runtime and one per-cell cache; on the six-axis arm a joint angle already seen re-renders in 0.6 s, a new one in 2.7 s (2.2.7).

The skill

The skill is how an agent learns the SDK. It is a router and a library of small pages, written so the agent reads exactly what a step needs, in one parallel batch.

What it does — seven routes, each a complete workflow with its own checks:

Ask Route
Model one physical part single-part modeling: requirements → plan → build → verify
Build a multi-part product or mechanism assembly: connectors, constraints, kinematics, standard parts
Rebuild an editable model from a STEP file STEP reconstruction with stable entity ids and acceptance gates
Rebuild from a mesh, point cloud or photos scan reconstruction
Rebuild from a vector-PDF drawing drawing reconstruction
Produce a GB engineering drawing (DXF) engineering drawing from validated geometry
Hand the model to someone else export and translation: STEP AP242, STL, FreeCAD, MJCF

How it is organized

SKILL.md                  router: pick one route, read its batch (≤ 130 lines)
workflows/                one lifecycle per route; roles and stages load when they start
domains/                  what the SDK offers for a kind of task
discipline/               rules and invariants: core rules, feature order, verifiers, failure and repair
docs/api · stdlib · core  400+ generated signature pages; a method with no page does not exist
  • Small reading budget. The first batch of any route is at most 1,200 lines. Every page has one job, and every rule has one home. A build check fails the skill if a page breaks the contract.
  • Two modes. Every workflow runs interactive (a person can answer) or unattended (nobody will). The mode changes who decides, never what is checked.
  • One source, seven harnesses. The same pages compile for Claude Code, Codex, OpenCode, ZCode, OMP, DSH and Kimi Code.
sca skill targets            # the harnesses
sca skill install            # compile for yours and install

Plugins

Modeling is the SDK's job. Checking, simulating and translating a finished model belong in a plugin, and a plugin is a repository:

sca-addon.toml     machine-checked facts: name, version, which SDK versions, how to provision
skill/SKILL.md     everything an agent reads about it
...                its own code, binaries and docs, in any language
sca addon add owner/repo          # from GitHub; owner/repo@v1.2.0 pins a tag
sca addon add ./my-addon          # a local checkout
sca addon list                    # what is installed, and whether its runtime works
sca addon update                  # re-fetch; code is swapped, runtime state is kept
  • The agent learns it on install. The addon's skill lands beside the SDK's as sca-<name>, so the agent gets the capability and the instructions together.
  • Isolated by design. A plugin reads .scadpkg product packages across a process boundary and runs in its own environment, so plugin dependencies never touch the one that models geometry.
  • Already in use. Connector verification (bolted, pinned, press-fit, welded and other joints, checked and then run through FEM) and FEM mesh preparation (fasteners removed, their holes filled, closure proven) are plugins. The AP242 → Gmsh → CalculiX and MJCF → MuJoCo paths below run off the same package.
Bracket FEM von Mises
L-bracket static FEM
CalculiX von Mises on the Gmsh mesh of the AP242 export; faces are chosen by interface.* tags that survive model changes
Four-bar links crashing through each other in MuJoCo
Four-bar linkage, first pass
MuJoCo shows the links crossing: the assembly is wrong
Corrected four-bar assembly in MuJoCo
After the collision pass
the same crank cycle sweeps clean

Install

pip install "simplecadapi[editor]"      # the SDK and the editor
sca example u_link                       # a real workspace to open
sca edit u_link                          # the editor
sca skill install                        # the skill for your agent

Python 3.10–3.13 on Linux, macOS and Windows. uv tool install "simplecadapi[editor]" puts sca on your PATH without a virtual environment. sca run model.py runs a notebook headless; sca export writes STEP, STL and OBJ.

Research artifact

This repository is an artifact of CADIR: A Cross-Backend Editable Intermediate Representation for Agentic CAD Generation.

Apache-2.0. Validate generated models before production use.

S
Description
No description provided
Readme Apache-2.0 77 MiB
Languages
Python 58.3%
C++ 30.5%
TypeScript 11%
CMake 0.1%