Beta release: Review reconstructed geometry and generated CAD documents before using this version in production.
SimpleCADAPI 2.0.4b2 adds an Agent-oriented STEP/BREP reconstruction workflow with stable entity IDs, 17 schema-validated inspection and diagnostic tools, focused material/boundary/topology acceptance gates, and replayable interpolated B-spline profiles. See the full English update notes for implementation details, operating modes, limitations, and verification coverage.
This repository is an artifact of
CADIR: A Cross-Backend Editable Intermediate Representation for Agentic CAD Generation
SimpleCADAPI is an OCP-native Python SDK for building CAD models with clear, functional operations and replayable model graphs. It wraps OpenCascade geometry in a compact public API for creating solids, applying features, tagging semantic intent, querying topology, exporting manufacturing files, and translating recorded models into FreeCAD workflows.
Current published beta release: simplecadapi==2.0.4b1. The 2.0.4b2 notes
describe the next beta while it is under validation.
- OCP-native shape types:
Vertex,Edge,Wire,Face, andSolid. - Functional modeling operations for primitives, profiles, extrude, revolve, loft, sweep, booleans, transforms, patterns, fillets, chamfers, and shells.
- Replayable modeling with
@model,ModelResult,capture_result(...),import_model_json(...), andreplay_model_json(...). - Expression parameters with
var(...), arithmetic expressions, and serialized expression graphs. - Physical units with automatic dimension inference, canonical CAD conversion, and manufacturing tolerance-chain validation.
- QL selectors for geometry grounding, topology queries, and stable feature selections.
- Semantic tags through
apply_tag(shape=..., tag=...)andlist_tags(shape=...). - STEP/STL export and FreeCAD translation helpers for script or
.FCStdoutput. - Agent-oriented STEP/BREP reconstruction with stable entity IDs, focused local diagnostics, highlighted region renders, and measured acceptance gates.
- Replayable open and periodic interpolated B-spline Edges/Wires for freeform profiles and Loft sections.
pip install simplecadapiWith uv:
uv add simplecadapiFor local development from this repository:
uv sync --group devfrom pathlib import Path
import simplecadapi as scad
out = Path("out")
out.mkdir(exist_ok=True)
base = scad.make_box_rsolid(
width=60.0, height=36.0, depth=8.0, bottom_face_center=(0.0, 0.0, 0.0)
)
hole = scad.make_cylinder_rsolid(
radius=5.0, height=14.0, bottom_face_center=(0.0, 0.0, -3.0)
)
slot = scad.make_box_rsolid(
width=18.0, height=8.0, depth=14.0, bottom_face_center=(14.0, 0.0, -3.0)
)
part = scad.cut_rsolid(base, hole, slot)
boss = scad.make_cylinder_rsolid(
radius=8.0, height=7.0, bottom_face_center=(-18.0, 0.0, 8.0)
)
part = scad.union_rsolid(part, boss)
part = scad.apply_tag(shape=part, tag="role.demo.bracket")
print("volume", round(part.get_volume(), 3))
print("faces", len(part.get_faces()))
print("tags", scad.list_tags(shape=part))
scad.export_step(shapes=part, filename=str(out / "bracket.step"))
scad.export_stl(shapes=part, filename=str(out / "bracket.stl"))Use one @scad.model entry point when a model should be inspectable,
serializable, replayable, or translated into another CAD environment. The
decorated function owns its GraphSession and returns a ModelResult.
import simplecadapi as scad
from simplecadapi import ql as Q
@scad.model(graph_id="chamfered_block")
def build_model():
body = scad.make_box_rsolid(
width=40.0, height=24.0, depth=10.0,
bottom_face_center=(0.0, 0.0, 0.0),
)
cutter = scad.make_cylinder_rsolid(
radius=4.0, height=16.0, bottom_face_center=(0.0, 0.0, -3.0)
)
drilled = scad.cut_rsolid(body, cutter)
bottom_circle = (
Q.edges()
.where(Q.curve_type(kind="circle"))
.order_by(Q.center_axis(axis="z"))
.take(1)
.exactly(1)
)
final = scad.chamfer_rsolid(solid=drilled, edges=bottom_circle, distance=0.6)
scad.capture_result(value=final)
return final
result = build_model()
model_json = result.model_json
rebuilt = result.replay()
print("recorded_nodes", result.session.graph.node_count)
print("replayed_outputs", len(rebuilt))Pass export_dir=... to @scad.model when the invocation should also write
one self-contained <graph_id>.scene.zip. The package contains scene.json,
model/model.json, the complete project-relative Python files referenced by
operation source mappings under sources/, and the GLB/entity assets required
by the Viewer. Automatic export does not write adjacent model/session JSON,
STEP, STL, or FCStd files; those explicit export APIs remain available. The
package path is result.artifact_paths["scene"]. Without export_dir, model
execution remains in memory.
Install the optional rendering dependency when synchronized STEP views, highlighted regions, or slice overlays are needed:
pip install "simplecadapi[inspect]"Inspection lives under simplecadapi.inspect.brep. These APIs are diagnostic
tools, not modeling operations: they do not enter the graph and are rejected
inside GraphSession and @model. Export or obtain the geometry first, then
inspect it outside the modeling script.
Choose calls from the evidence required by the case instead of following a fixed reverse-engineering pipeline. Start with bounded global and local facts; add sections, component renders, boundary distance, material difference, or strict topology comparison only when those facts answer the current question.
from simplecadapi.inspect import brep
summary = brep.inspect_step_rsummary(
path="target.step",
include_parameter_groups=True,
)
face = brep.inspect_step_entity_rdescriptor(
path="target.step",
entity_id="face:0",
)
print("faces", summary["face_count"])
print("carrier", face["geometry"]["type"])Use the Reconstruction Agent test specification for controlled runs and the STEP BREP reverse-engineering guide for the inspection primitives, modeling loop, replay checks, and acceptance gates.
Declare nominal and manufacturing-tolerance units at the variable boundary. SimpleCAD evaluates lengths in millimeters and angles in degrees while preserving the declaration units in model JSON:
import simplecadapi as scad
width = scad.var(
"width",
1.0,
unit="in",
tolerance=0.1,
tolerance_unit="mm",
)
height = scad.var("height", 40.0, unit="mm", tolerance=0.2)
diagonal = scad.sqrt(width**2 + height**2)
analysis = scad.analyze_tolerance(diagonal)
check = scad.check_tolerance(diagonal, 0.3, tolerance_unit="mm")
print(analysis.dimension.name, analysis.unit.symbol)
print(analysis.nominal, analysis.lower_bound, analysis.upper_bound)
print("passes", check.passed)Addition and subtraction require matching dimensions. Multiplication, division,
integer powers, and square root derive dimensions. Trigonometric functions require
angle or dimensionless inputs as appropriate. Legacy variables without unit
remain supported, but cannot be mixed with unit-declared variables in one
expression.
- Start from design intent: reference axes, critical profiles, and the features that produce the final solid.
- Build from lower-dimensional geometry to higher-dimensional geometry: profile wires/faces first, then solid features such as extrude, revolve, loft, and sweep.
- Keep operations functional. Create new values with public functions such as
make_rectangle_rface(...),extrude_rsolid(...),cut_rsolid(...), andfillet_rsolid(...). - Use tags for semantic intent and selection anchors, for example
role.mounting.surface,anchor.datum.primary, orgroup.fasteners. - Store numeric and geometric facts in metadata or graph payloads, not in tags.
- Use QL to ground selections by geometry facts rather than relying on topology iteration order.
- When an indexed topology pick is intentional, pass the index to the plural
child-geometry getter, such as
get_edges(index),get_faces(index),get_wires(index), orget_vertices(index), so replayable graph workflows preserve the pick as a geo select node. - Use model JSON as the interchange boundary for replay, tests, and FreeCAD translation.
Recorded model JSON can be translated into a FreeCAD Python script:
script = scad.translator.freecad_translator.translate_model_json_to_freecad_script(model_json)If FreeCAD or FreeCADCmd is available, the same model JSON can be written as an
.FCStd file:
scad.translator.freecad_translator.translate_model_json_to_fcstd(model_json, "bracket.FCStd")Part/Assembly models are written as editable FreeCAD assembly structure: parts are
App::Part, assemblies are Assembly::AssemblyObject, and components are links.
Explicit compound projections remain available for geometry-only STEP export.
Run examples from the source checkout:
uv run python examples/04_dimension_tolerance_chain.py
uv run python examples/08_constrained_sketch.py
uv run python examples/09_naca0016_blade_freecad.py
uv run python examples/10_part_assembly.py
uv run python examples/16_compact_two_stage_planetary_reducer/main.py
uv run python examples/20_integrated_bldc_joint_actuator/main.py- 2.0.4b2 update notes:
docs/updates/2.0.4b2.md - Reconstruction Agent test specification:
docs/guides/reconstruction-agent-test-prompt.md - STEP BREP reverse-engineering guide:
docs/guides/step-brep-reverse-engineering.md - Public API reference:
docs/api/ - Core type and modeling notes:
docs/core/ - Serialization and replay details:
docs/core/serialization/README.md - Dimension tolerance chains:
docs/core/dimension-tolerance-chains.md - Physical units and dimension inference:
docs/core/physical-units.md - Operation graph JSON spec:
docs/core/operation_graph_json_spec.md
The repository includes a thin Agent Skill under skills/simplecadapi/. It
contains generated API and modeling references, but does not bundle the SDK
source code.
From a clean checkout, update the project version and documentation, then build and validate the release artifacts:
uv sync --group dev
uv run skill-pack --refresh-docs --archive
uv run python -m pytest test/test_skill_pack.pyThe command refreshes the generated docs, rewrites skills/simplecadapi/, and
creates skills/simplecadapi.tar.gz. Review the generated SKILL.md and
references before release:
git diff -- skills/simplecadapi docs
tar -tzf skills/simplecadapi.tar.gzCommit the generated skills/simplecadapi/ directory and refreshed docs/
with the release. The archive is intentionally ignored by Git; attach
skills/simplecadapi.tar.gz to the corresponding GitHub release or distribute
it through the target Agent Skills registry.
uv sync --group dev
uv run python -m pytest test tests
python3 -m compileall src/simplecadapiApache-2.0, see LICENSE.
The group chat currently has too many members for direct QR-code joining. Scan the QR code below to add Teacher Du Peng on WeChat, then ask him for an invitation to the CADDesigner technical community:
