DECISION: three changes for the three obstacles of the issue, each the smallest that removes the obstacle. No new API name, no relocatable state directory, no rewrite of rule R3. 1. A run without the cache touches nothing next to the source (the crash). PROBLEM: `run_notebook(path, cache=False)` failed on a read-only source directory (`Errno 30` on Linux, `WinError 5` here): `_run` ended with `write_dependencies`, which writes `__marimo__/.../deps.json` beside the notebook, and `exclusive()` made the state directory for its lock. REPRODUCED on Windows with an ACL that denies creating entries in the directory, on the issue's own notebook: PermissionError at runner.py `write_dependencies`. After the change the same run prints `ok` and creates nothing. WHY THIS FIX: the dependency record exists for the cache (cache entries are keyed on the files it lists); a run that keeps no entries has no reason to move it, and moving it left the record and the entries out of step. The lock exists to protect pruning and that record, neither of which a run without the cache does. A run WITH the cache still writes its state and still fails loudly when it cannot: asking for persistence and silently not getting it would be worse. REJECTED: an environment variable or argument that moves the state directory (more surface, and the problem is that there should be no state, not that it is in the wrong place); swallowing the OSError (hides real cache failures). 2. The exporters take a build result (one step, no `.scadpkg` on disk). PROBLEM: STEP from a freshly built Part needed `capture(result, path)` and then the exporter on that path, and the default capture tessellates a scene nobody reads: 1.85 s against 0.26 s for the issue's 36-hole plate. WHY THIS FIX: `build_product_package` already accepts a build result or a definition and can leave the scene out; `read_product_package_translation_units`, which every exporter and translator goes through, now builds that package in memory when it is given neither a package nor bytes nor a path. So STEP, STL, OBJ, MJCF and FreeCAD all gain the one-step form with the same validation, under the existing names. A value that is no product still raises TypeError. REJECTED: `exporter.step.export_part(part_or_solid, path)` as the issue suggests: a bare Part or solid has no definition (feature graph, topology snapshot, hashes), those come from `@scad.part`; and a second family of names beside `export_product_package_to_*` (the tests pin that these live only in `scad.exporter`). 3. The skill lists the plain script as an entry for a single-script task. PROBLEM: R3 says a model is a marimo notebook; an agent given "one script, `--output part.step`" read the skill and chose another library. WHY THIS FIX: R3 keeps its force for everything a person opens or reuses; it gains one exception, a task that itself asks for a single script, and the template (which I ran in a read-only directory: STEP written, source untouched) lives in the export domain page next to the rule it relaxes. THIS IS A POLICY DECISION OF THE OWNER, made here provisionally: R3 was a deliberate rule, and the PR says so. Not done: the issue's timings were not rerun on Linux, only on this Windows machine (same direction). Checked: test_notebook_runtime and the cache tests (123 passed), test_product_exporter/packages/capture/assembly pass with the three new exporter tests, test_skill_lint passes. test_skill_build::test_files_without_directives_copied_verbatim fails on the base commit as well. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
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.
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.
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.
SG90 educational arm · 34 parts, six revolute joints solved as constraints, 3D-printable links, reserved envelopes for the electronics. sg90_arm_6dof.py
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
.scadpkgproduct 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.
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.





