text-to-cad / build123d Agent Capability Guide

This document is the required backend capability brief for CAD Agent Studio when considering the build123d route through text-to-cad. It is intentionally an Agent-facing decision document, not a geometry template.

Role

Use this route when the Agent will author backend-native build123d Python source and the server will only execute, validate, normalize to DesignIR 3.0, and publish artifacts.

text-to-cad owns orchestration, artifact contracts, DesignIR normalization, SurfaceIR reconstruction for uploaded STEP, validation, repair workflow, and Viewer handoff. For direct new model generation, build123d source is the editable source of truth.

Studio Documentation Discipline

For CAD Agent Studio backend selection, this document is sufficient. Decide from the capability boundary here: what text-to-cad/build123d is strong at, what it is weak at, and whether the primary requested object matches those strengths.

Do not read build123d API manuals, skill internals, or implementation guides during ordinary backend selection. The selection task only needs to know what the tool can generate, not the exact API signatures.

Strong Fits

Custom mechanical parts: brackets, flanges, wheel hub adapters, housings, plates, fixtures, covers, shafts, bushings, levers, cranks, connecting rods.
Feature-rich machined parts with cylinders, boxes, revolve-like stacks, holes, through cuts, counterbores, pockets, bosses, ribs, shells, chamfers, fillets, lofts, sweeps, and source-level construction logic.
Requests where words such as bolt, nut, bearing, gear, or sprocket describe holes, mounts, clearances, interfaces, or surrounding features rather than asking for those standard parts as the primary object.
Geometry where future edits should preserve readable Python parameters and explicit construction order.

Weak Fits

The requested primary object is a standard mechanical component already covered by a SimpleCADAPI standard factory, such as a gear, bearing, bolt, nut, roller-chain sprocket, rack, or reducer.
The request specifically requires SimpleCADAPI model graph replay, semantic topology lineage, unit/tolerance chains, translator workflows, or strict B-Rep comparison.

Agent Source Contract

When choosing this backend, submit raw Python source to generate_cad with:

selectedBackend = "build123d"
sourceKind = "build123d_python"
A script that accepts --step and --metadata
STEP export written exactly to the --step path
Metadata JSON written exactly to the --metadata path
stdout JSON is optional diagnostic output; file artifacts are the source of truth for execution success

If exposing editable parameters, include a top-level block:

# CAD_AGENT_PARAMETERS_START
PARAMETERS = {
    "example": 1.0
}
# CAD_AGENT_PARAMETERS_END

Each editable metadata parameter must include name, value, unit, editable, binding_kind, parameter_path, and regenerate_adapter. Use binding_kind = "python_constant" and regenerate_adapter = "build123d" for parameters bound to the PARAMETERS block.

Do not submit diagnostic, API-probing, topology-probing, radius-sweep, or smoke test scripts as nativeSource. The source must be the final model generator for the user's part and must write the requested file artifacts in one execution. If this compact reference is insufficient, report the missing reference instead of using generate_cad as an exploration tool.

Decision Rule

Choose build123d when the full requested part is a custom feature model and no SimpleCADAPI standard factory directly represents the primary object. Do not route to another backend merely because a feature name contains a standard part word. For example, bolt holes or nut clearances in a flange remain features of the flange, not a request to generate a bolt or nut.

3.8 KiB Raw Blame History