SimpleCADAPI Agent Capability Guide

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

Role

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

SimpleCADAPI is strongest when its standard factories or replayable model graph capabilities materially improve correctness, editability, or validation.

Strong Fits

The primary requested object is a supported standard mechanical family: spur, helical, herringbone, ring, or bevel gears; racks; cycloidal discs; ball bearings; bolts; nuts; roller-chain sprockets; planetary or cycloidal reducers; joint actuator assemblies.
The task benefits from @model, ModelResult, capture_result, model JSON, graph replay, semantic tags, topology lineage, source mapping, QL inspection, unit checking, tolerance chains, scene packages, or CAD translators.
The task needs strict STEP/B-Rep diagnostics, target/candidate comparison, multi-view diagnostics, or slice XOR diagnostics.
The model is a reusable mechanical product family whose formulas should be a deterministic SDK workflow rather than one-off source construction.

Weak Fits

The request is a custom machined part, flange, hub adapter, housing, bracket, plate, or fixture where no SimpleCADAPI standard factory directly represents the primary object.
Standard part words appear only as feature context. Examples: bolt holes, screw clearances, nut pockets, bearing seats, gear-mounting holes. These are features of another part, not requests to generate the standard part itself.
The requested shape needs freeform or multi-rail surface work outside the documented SimpleCADAPI vocabulary.
The current source of truth is an existing build123d source and the user did not request backend conversion.

Studio Documentation Discipline

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

Do not read SimpleCADAPI API manuals, SDK indexes, or per-function pages during ordinary backend selection. The selection task only needs to know what the tool can generate, not the exact API signatures.

Prefer standard-library functions only when the standard component is the primary requested object and the factory actually covers it.

Agent Source Contract

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

selectedBackend = "simplecadapi"
sourceKind = "simplecadapi_python"
A script that accepts --step, --metadata, and --model-json
STEP export written exactly to the --step path
Model JSON written exactly to the --model-json 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

The source should use one replayable @model entry point when model JSON or graph replay is part of the task. Capture explicit outputs with capture_result(...) and write the returned ModelResult.model_json.

Do not submit diagnostic, API-probing, topology-probing, radius-sweep, or smoke test scripts as nativeSource. Do not use inspect.signature(...), broad dir(...) dumps, trial loops, or intentional exceptions to discover the SDK or geometry at execution time. The source submitted to generate_cad 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.

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" for parameters bound to the PARAMETERS block, or model_graph_parameter only when the parameter is actually replayable through the model graph. Use regenerate_adapter = "simplecadapi".

Minimal Native Source Reference

Use this compact API surface for Studio generation. It is included here so the Agent can write production source without reading API indexes during backend selection.

import argparse
import json
from pathlib import Path
import simplecadapi as scad

@scad.model(graph_id="model")
def build_model():
    shape = scad.std.gear.make_spur_gear_rsolid(
        n_teeth=24,
        module=2.0,
        pressure_angle=20.0,
        gear_height=8.0,
    )
    scad.capture_result(value=shape)
    return shape

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--step", required=True)
    parser.add_argument("--metadata", required=True)
    parser.add_argument("--model-json", required=True)
    args = parser.parse_args()

    result = build_model()
    Path(args.model_json).write_text(result.model_json, encoding="utf-8")
    scad.export_step(shapes=result.value, filename=args.step)
    Path(args.metadata).write_text(json.dumps({"backend": "simplecadapi"}), encoding="utf-8")

Replace the body of build_model() with the requested standard component or workflow. Keep the CLI/output protocol unchanged.

Common standard gear factories:

scad.std.gear.make_spur_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, gear_height: float = 6.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25, backlash: float = 0.0)
scad.std.gear.make_helical_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, helix_angle: float = 30.0, gear_height: float = 8.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25, backlash: float = 0.0)
scad.std.gear.make_herringbone_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, helix_angle: float = 32.0, gear_height: float = 10.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25, backlash: float = 0.0)
scad.std.gear.make_spur_ring_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, gear_height: float = 6.0, rim_thickness: float = 3.0, backlash: float = 0.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25)
scad.std.gear.make_helical_ring_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, helix_angle: float = 25.0, gear_height: float = 8.0, rim_thickness: float = 3.0, backlash: float = 0.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25)
scad.std.gear.make_straight_bevel_gear_rsolid(n_teeth: int, module: float, pitch_angle: float = 45.0, pressure_angle: float = 20.0, face_width: float = 8.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25, backlash: float = 0.0)

Decision Rule

Choose SimpleCADAPI only when the primary requested model or required workflow matches its documented standard factories or graph/semantic capabilities. Do not select SimpleCADAPI merely because the prompt mentions a standard part word inside another feature. For example, a wheel hub adapter with bolt holes is a custom flange-like part unless the user asks to generate a bolt as the object.

7.4 KiB Raw Permalink Blame History