CadCore: Autonomous Agentic CAD Engine with Closed-Loop Self-Healing

CadCore abstracts geometric modeling behind a unified backend interface. It supports two primary execution environments:

The build123d backend is the default choice for agent workflows. It runs directly in headless Python runtimes and executes with minimal overhead.

1from build123d import *
2
3# Parametric definition for an offset mounting bracket
4length, width, thickness = 75.0, 45.0, 6.0
5hole_diameter = 5.5
6
7with BuildPart() as bracket:
8    with BuildSketch():
9        RectangleRounded(length, width, radius=4.0)
10    extrude(amount=thickness)
11    
12    # Place 4 corner mounting holes using grid locations
13    with BuildSketch(bracket.faces().sort_by(Axis.Z)[-1]):
14        with GridLocations(x_spacing=length - 16, y_spacing=width - 16, x_count=2, y_count=2):
15            Circle(radius=hole_diameter / 2)
16    extrude(amount=-thickness, mode=Mode.SUBTRACT)

[!NOTE] build123d models geometry through explicit builder contexts (BuildPart, BuildSketch, BuildLine). This structure prevents state leakage between sketch operations and matches how mechanical engineers define datum planes.

Closed-Loop Execution and Self-Healing

The core problem with generative code is execution failure. If an LLM generates invalid parameters, missing imports, or impossible fillets, a traditional pipeline crashes.

CadCore implements an automated self-healing loop inside CADAgentPipeline.

How the Repair Mechanism Operates

1. Subprocess Isolation: The generated script runs in a spawned subprocess via ScriptExecutor. If the script triggers a segmentation fault or an infinite loop, the parent agent process remains protected. Execution is bounded by a strict timeout (default: 120 seconds).
2. Traceback Extraction: When execution fails, the executor captures STDOUT and STDERR.
3. Contextual Diagnostic Prompts: The error message and full source code are injected into get_repair_prompt. The prompt instructs the LLM to identify the failing line, consult library constraints, and rewrite the script without altering the mechanical dimensions.
4. Iterative Convergence: The pipeline retries execution up to max_retries (default: 3).

1# cadcore/llm/prompts.py: Diagnostic prompt structure
2def get_repair_prompt(original_code: str, error_traceback: str, user_prompt: str, backend: CADBackendType) -> str:
3    return f"""The previous {backend.value} script encountered an execution error.
4
5### USER REQUEST:
6{user_prompt}
7
8### PREVIOUS CODE:
9```python
10{original_code}

ERROR TRACEBACK:

{error_traceback}

REPAIR INSTRUCTIONS:

1. Analyze the traceback to identify the exact failing line or geometric constraint.
2. If the error is an AttributeError, verify that the class actually exists in {backend.value}.
3. Return ONLY the complete corrected Python code. """

Standalone Interactive 3D Web Viewer

The cadcore.viewer module compiles an interactive 3D WebGL viewer into a single .html file. The STL binary is base64-encoded directly into the document:

• Zero External Server: Openable locally in any modern browser (file:///...).
• Inspection Tools: OrbitControls (pan, rotate, zoom), studio environment lighting, and dimensional bounding grid.
• Heads-Up Display (HUD): Displays volume, watertight status, vertex count, and execution time directly on the viewport.

Practical Usage

1. Command-Line Interface (CLI)

CadCore includes a rich CLI powered by Typer:

1# Generate a mechanical part using default Gemini provider and build123d backend
2python -m cadcore generate "NEMA 17 motor mount plate 42x42mm, 4mm thick with central 22mm hole and 4 M3 corner holes" --output ./outputs/nema17
3
4# Generate an L-bracket and immediately launch the 3D web viewer
5python -m cadcore generate "L-bracket 60x60x30mm with 5mm wall thickness and central stiffening gusset" --output ./outputs/l_bracket --view
6
7# List active backends and verify Python dependencies
8python -m cadcore list-backends

2. Embedding in Python Pipelines

CadCore can be imported as a library to power autonomous design pipelines, agent toolsets, or automated CAD test generators:

1from pathlib import Path
2from cadcore.config import PipelineConfig, CADBackendType, LLMConfig, LLMProvider
3from cadcore.pipeline import CADAgentPipeline
4
5# Configure the agent pipeline
6config = PipelineConfig(
7    backend=CADBackendType.BUILD123D,
8    output_dir=Path("./outputs/flange"),
9    max_retries=3,
10    export_step=True,
11    export_stl=True,
12    export_svg=True,
13    generate_viewer=True,
14    llm=LLMConfig(
15        provider=LLMProvider.GEMINI,
16        model="gemini-2.5-flash",
17    ),
18)
19
20# Initialize and run
21pipeline = CADAgentPipeline(config)
22result = pipeline.run("Round pipe flange 80mm OD, 40mm ID, 10mm thickness with 6 bolt holes of 6mm diameter on 62mm PCD")
23
24if result.success:
25    print(f"Generation succeeded in {result.execution_time_seconds:.2f}s ({result.iterations} iterations)")
26    print(f"STEP File: {result.artifacts['model.step']}")
27    print(f"STL File:  {result.artifacts['model.stl']}")
28    print(f"Volume:    {result.metrics.get('volume_mm3')} mm3")
29else:
30    print(f"Generation failed: {result.error_message}")

Benchmark Evaluation

Generation latency and topological quality were measured across standard mechanical engineering benchmark parts using Gemini 2.5 Flash:

[!WARNING] While LLM agents excel at primitive combinations, fillets, and polar patterns, complex freeform organic surfaces and high-order lofting require explicit guide curves. Providing clear dimensional references in the prompt produces the most consistent B-Rep geometry.

Summary

Generative mechanical design requires more than probabilistic code output. By pairing declarative Python CAD kernels like build123d with isolated sandbox execution, topological mesh validation, and automatic error repair, CadCore establishes a reliable bridge between natural language prompts and verifiable 3D manufacturing files.

The project is fully open-source on GitHub: github.com/kXborg/CadCore.

References

• CadCore GitHub Repository
• build123d Parametric CAD Documentation
• OpenCASCADE Technology Official Portal
• FreeCAD Headless Scripting Guide
• Trimesh Geometric Analysis Library