Metadata-Version: 2.4
Name: samlpy
Version: 0.2.1
Summary: SamlPy: Semantic Assembly Modeling Language for Python - Deterministic, Zero-Coordinate, LLM-Native CAD Engine built on OpenCASCADE
Author: CADi Team
License: MIT
Project-URL: Homepage, https://github.com/Omerersen/Project-CAD-
Project-URL: Repository, https://github.com/Omerersen/Project-CAD-
Keywords: cad,opencascade,brep,llm,ai,parametric,assembly,3d-modeling,saml,samlpy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# 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**:
```python
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:
```python
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:
```python
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:
```python
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:
```python
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:
```python
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:
```python
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

```bash
pip install samlpy
```

> **Note**: SamlPy requires [cadquery-ocp](https://github.com/CadQuery/OCP) (OpenCASCADE Python bindings) as a runtime dependency. Install it via:
> ```bash
> pip install cadquery-ocp
> ```

---

## Quick Start

```python
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-](https://github.com/Omerersen/Project-CAD-)
- **PyPI**: [pypi.org/project/samlpy](https://pypi.org/project/samlpy/)
