91 lines
3.8 KiB
Markdown
91 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
# 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.
|