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

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, 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. 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.

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. 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:

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

Inspect geometry facts and positioning:

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

Create visual snapshots for review:

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

Export secondary mesh formats:

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:

cad-viewer launch --file my_part.step

Summary

• Three-layer architecture: Skill definitions (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, 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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}