# Text-to-CAD Core Functionalities: End-to-End CAD Automation for AI Agents

> Explore Text-to-CAD core functionalities enabling AI agents to create parametric STEP models from Python code. Automate CAD generation and validation with our robust architecture.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: deep-dive
- Published: 2026-08-04

---

**Text-to-CAD core functionalities provide a deterministic, three-layer architecture—skill definitions, runtime helpers, and CLI tools—that enables AI agents to generate parametric STEP models from Python source code, validate geometry through inspection pipelines, and deliver interactive previews via the CAD Viewer.**

The `earthtojake/text-to-cad` repository is a modular library that equips AI agents with end-to-end CAD, robotics, and fabrication workflows. Understanding these Text-to-CAD core functionalities is essential for implementing reproducible, traceable solid modeling pipelines that center on STEP files as the single source of truth.

## Three-Layer Architecture

The system is deliberately split into distinct layers to separate policy from implementation.

### Skill Definitions Layer

Declarative metadata describing each capability lives in `skills/*/SKILL.md`. The primary CAD skill specification resides in [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md), which defines workflow conventions, supported exports, and non-negotiable constraints that ensure cross-agent compatibility.

### Runtime Helpers Layer

Shared, language-agnostic code implements the heavy lifting. The `packages/cadpy` directory contains Python helpers for STEP generation and assembly handling, while `packages/implicitjs` provides browser-side implicit CAD capabilities using GLSL SDF and ray-march rendering.

### CLI Tools Layer

Thin wrappers expose helpers to the agent runtime. The `scripts/step` utility handles STEP generation and secondary exports, `scripts/inspect` performs geometry validation, and `scripts/snapshot` creates visual review packets.

## Core Workflow Concepts

### STEP-First Workflow

All CAD work centers on a valid STEP/STP file as the primary output. Secondary formats like STL, 3MF, and GLB are derived from this STEP file, as documented in [`references/supported-exports.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/supported-exports.md). This rule is enforced throughout the CAD skill to maintain geometric fidelity.

### Source-Driven Generation with build123d

When creating parts from scratch, a **build123d** Python generator function `gen_step()` lives alongside the STEP file. The CLI runs `scripts/step` on the generator rather than the exported STEP, guaranteeing reproducibility and parametric editability.

### Assembly Management

Complex designs utilize `cadpy.assembly.AssemblyHelper` to define joints, datums, and explicit `Location` transforms in Python source. These relationships are baked into the final STEP assembly, with positioning conventions detailed in [`references/positioning.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/positioning.md).

### Inspection and Validation Pipeline

After STEP generation, the workflow mandates running `scripts/inspect` to extract geometry facts, planes, and positioning data. This is followed by `scripts/snapshot` to generate a PNG or GIF visual-review packet that must be returned to the user for verification.

### CAD Viewer Integration

Final artifacts are handed to the **CAD Viewer** skill (`$cad-viewer`), defined in [`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md). The viewer starts automatically when needed, providing live preview URLs that agents embed in responses for immediate visual feedback.

## Essential CLI Commands

Practical implementation of Text-to-CAD core functionalities relies on specific command-line workflows.

Generate a STEP model from build123d source:

```bash
python scripts/step my_part.py --kind part --out my_part.step

```

Inspect geometry facts and positioning:

```bash
python scripts/inspect refs my_part.step --facts --planes --positioning

```

Create visual snapshots for review:

```bash
python scripts/snapshot my_part.step --out my_part_snapshot.png

```

Export secondary mesh formats:

```bash
python scripts/step my_part.step --export stl --out my_part.stl
python scripts/step my_part.step --export 3mf --out my_part.3mf
python scripts/step my_part.step --export glb --out my_part.glb

```

Launch the CAD Viewer:

```bash
cad-viewer launch --file my_part.step

```

## Summary

- **Three-layer architecture**: Skill definitions ([`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md)), runtime helpers (`packages/cadpy`), and CLI tools (`scripts/step`, `scripts/inspect`, `scripts/snapshot`) separate policy from implementation.
- **STEP-first workflow**: STEP files serve as the single source of truth, with STL/3MF/GLB as secondary exports derived via `scripts/step`.
- **Source-driven reproducibility**: Python generators using build123d enable parametric, rebuildable models through the `gen_step()` convention.
- **Mandatory validation**: Every generation requires inspection (`scripts/inspect`) and visual snapshot (`scripts/snapshot`) before hand-off to the CAD Viewer.

## Frequently Asked Questions

### What makes Text-to-CAD deterministic compared to other CAD automation tools?

Text-to-CAD enforces a source-driven workflow where the Python generator (`gen_step()`) is the canonical definition, not the exported mesh. By requiring STEP as the primary format and running `scripts/inspect` for validation, the system eliminates ambiguity in geometric intent and ensures reproducible builds across different agents.

### How does the assembly system handle complex multi-part designs?

The `cadpy.assembly.AssemblyHelper` class manages joints and datums through explicit `Location` transforms defined in Python source. These relationships are baked into the STEP assembly structure following the conventions in [`references/positioning.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/positioning.md), allowing precise control over part positioning without relying on implicit CAD operations.

### Can Text-to-CAD export formats other than STEP?

Yes. While STEP is the required primary format, the `scripts/step` CLI supports secondary exports to STL, 3MF, and GLB. These are derived directly from the STEP solid to ensure geometric consistency, as specified in [`references/supported-exports.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/supported-exports.md).

### What is the role of the CAD Viewer skill in the workflow?

The CAD Viewer skill (`$cad-viewer`), defined in [`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md), provides interactive 3D previews of generated STEP files. It launches automatically via `cad-viewer launch` and returns URLs that agents embed in responses, creating a mandatory visual verification step before fabrication.