SamlPy — Semantic Assembly Modeling Language for Python

Deterministic, Zero-Coordinate, LLM-Native CAD Engine built on OpenCASCADE (OCCT)

SamlPy is a Python CAD library purpose-built for AI/LLM code generation. Instead of hundreds of lines of explicit coordinate math, SamlPy lets you describe assemblies declaratively — using semantic mates, anchor ports, and parametric variables — while a pure OpenCASCADE backend produces watertight B-Rep solids.

---

Why SamlPy?

General-purpose 3D CAD libraries (CadQuery, PythonOCC, build123d) are designed for human developers. When LLMs (Claude, GPT, Gemini) generate code with these libraries, common failure modes include:

Problem	Impact
High token cost	Hundreds of lines for a simple part or assembly
Syntax errors & context loss	Complex fluent-API chains cause frequent LLM mistakes
Topological instability	Face/edge addressing leads to hallucinated selectors

The Solution: Declarative, LLM-Friendly CAD

[SAML DSL (LLM Interface)]
         ↓
[SAML Compiler & IR (Constraint Solver)]
         ↓
[SamlPy OCCT Backend (Pure OpenCASCADE Core)]
    ├── B-Rep & Topology Layer (TopoDS_Shape, Faces, Edges)
    ├── Assembly Mates & Joints Engine
    └── Reverse Engineering & Import Engine (STEP/IGES)

---

Key Features

A. High-Level Assembly & Mates

Instead of placing parts with raw X, Y, Z transforms, use CAD-standard mate constraints:

from samlpy import Assembly

with Assembly("Gearbox", units="mm", material="AlSi10Mg") as asm:
    base = asm.add_box("base_plate", length=100, width=80, height=12)
    base.add_hole("mount_hole", diameter=8.5, depth=0, position=(0, 0))
    
    asm.connect(base.face("top"), "bearing:port:back_face", mate_type="FLUSH")

Result: Eliminates spatial matrix math for the LLM, reduces token usage by ~90%.

B. Built-in Standard Parts Library

Standard industrial components are called with a single line — no modeling from scratch:

from samlpy import Fastener, Bearing, Motor

bolt = Fastener.ISO4762(name="clamp_bolt", size="M8", length=35)
bearing = Bearing.SKF(name="main_bearing", code="608ZZ")
motor = Motor.NEMA17(name="drive_motor")

Result: Components that would cost 1000+ tokens are reduced to 5–10 tokens.

C. Anchor Ports & Semantic Interfaces

Parts carry their own mount points — no guessing coordinates:

asm.connect(motor.port("shaft"), wheel.port("hub"))

Result: Prevents part intersection and clash errors at the API level.

D. Cascading Parametric Variables

Entire assemblies are driven by master parameters:

with Assembly("Gearbox") as asm:
    asm.set_param("box_width", 120)
    # All child parts auto-scale to box_width

Result: Revisions require changing 1 parameter instead of rewriting the entire model (~98% token savings).

E. Reverse Engineering (STEP → Code)

Import existing industrial CAD files and convert them to SamlPy code:

from samlpy import STEPReverseEngineer

re = STEPReverseEngineer()
result = re.analyze("gearbox.step")
# → Detected faces, holes, PCD patterns, materials

F. Geometry Validation Engine

All generated geometry is validated before export:

from samlpy import ValidationEngineer

validator = ValidationEngineer()
validator.check_manifold(name, solid)     # Watertight closed solid?
clashes = validator.check_clashes(solids) # Parts intersecting?
feedback = validator.diagnose_for_llm(solids)  # NL feedback for LLM

Result: Errors return structured natural-language feedback (instead of stack traces), enabling the LLM to self-correct.

G. Multi-Format Export

Export to all major CAD and visualization formats:

from samlpy import OCCTBackend

backend = OCCTBackend()
ir = asm.to_ir()
solids = backend.compile(ir)

backend.export_step(ir, "output.step")           # STEP (ISO 10303)
backend.export_stl(ir, "output.stl")             # STL mesh
backend.export_glb(ir, "output.glb")             # glTF/GLB for web
backend.export_technical_drawing(ir, "dwg.svg")  # 2D technical drawing

H. Advanced CAD Operations

• Sketch Engine: 2D profiles with lines, arcs, circles, and constraints
• Gear Library: Spur gears, helical gears, rack & pinion
• Springs: Coil springs, coilovers with damper bodies
• Loft & Sweep: Complex aerodynamic and organic shapes
• Boolean Operations: Union, cut, intersection with adaptive fuzzy tolerance
• Fillet & Chamfer: Edge treatments on B-Rep solids
• Pattern: Linear and circular pattern arrays
• Mass Properties: Volume, center of gravity, moments of inertia

---

Installation

pip install samlpy

Note: SamlPy requires cadquery-ocp (OpenCASCADE Python bindings) as a runtime dependency. Install it via:

pip install cadquery-ocp

---

Quick Start

from samlpy import Assembly, OCCTBackend, ValidationEngineer

# 1. Define assembly declaratively
with Assembly("MyAssembly", units="mm", material="Steel") as asm:
    shaft = asm.add_cylinder("shaft", radius=10, height=100)
    plate = asm.add_box("plate", length=50, width=50, height=5)
    asm.connect(shaft.face("bottom"), plate.face("top"), mate_type="FLUSH")
    ir = asm.to_ir()

# 2. Compile to solid geometry
backend = OCCTBackend()
solids = backend.compile(ir)

# 3. Validate
validator = ValidationEngineer()
for name, solid in solids.items():
    assert validator.check_manifold(name, solid)

# 4. Export
backend.export_step(ir, "my_assembly.step")

---

Architecture

samlpy/                          # Top-level package (public API)
└── cadi_saml/                   # Core engine
    ├── core/
    │   ├── assembly.py          # Assembly builder & parametric engine
    │   ├── ports.py             # Semantic anchor ports & constraints
    │   └── sketch.py            # 2D sketch engine
    ├── backend/
    │   └── occt_backend.py      # Pure OpenCASCADE compiler & exporters
    ├── ir/
    │   ├── nodes.py             # Intermediate Representation (IR) data model
    │   └── parser.py            # SAML DSL parser
    ├── std_parts/
    │   ├── fasteners.py         # ISO 4762 bolts, screws
    │   ├── bearings.py          # SKF deep-groove bearings
    │   ├── nuts.py              # DIN 934/985 nuts
    │   ├── washers.py           # DIN 125 washers
    │   ├── profiles.py          # V-Slot aluminum extrusions
    │   ├── motors.py            # NEMA 17/23 stepper motors
    │   └── motorsport.py        # Gears, springs, coilovers
    ├── validation/
    │   └── validation_engineer.py  # Manifold check, clash detection, LLM diagnosis
    └── reverse/
        └── step_importer.py     # STEP reverse engineering

---

Use Cases

• LLM-powered CAD generation: Fine-tune or prompt LLMs to produce valid 3D models
• Parametric design automation: Drive complex assemblies from a few master parameters
• AI training data: Generate (instruction, code, STEP) triples for model training
• Rapid prototyping: Build and validate assemblies faster than traditional CAD
• Reverse engineering: Import STEP files, analyze topology, and generate editable code

---

License

MIT

---

Links

• Repository: github.com/Omerersen/Project-CAD-
• PyPI: pypi.org/project/samlpy