cadSet/text-to-cad/skills/cad-router/references/model-spec.md

Per-part model specification

Use one model-spec.json per generated or imported part. Treat it as the editable geometry contract. Keep cad-task.json separate for routing, experience use, validation results, and viewer links.

Native generator

Use native_generator when the part has editable Python source:

{
  "schema_version": "1.0",
  "model_spec_kind": "parametric_cad_model",
  "model_id": "example_part",
  "units": "mm",
  "reconstruction": {
    "mode": "native_generator",
    "generator": {
      "path": "example_part.py",
      "entrypoint": "gen_step"
    }
  },
  "parameters": {
    "width": {
      "value": 40,
      "unit": "mm",
      "role": "overall_width"
    }
  },
  "modifications": [],
  "outputs": {
    "step": "example_part.step",
    "stl": "example_part.stl"
  }
}

The generator must read its sibling model-spec.json. Do not duplicate authoritative parameter values as editable constants in both files.

Imported STEP

Convert an explicitly supplied STEP into a task-local exact-base specification:

python scripts/model_spec.py import-step input.step \
  --task-dir models/cad-router-v1/imported_part \
  --model-id imported_part

This copies the source to source.step, records its SHA-256 and geometry signature, writes model-spec.json, and exports regenerated STEP/STL files. With an empty modification list, verify requires the imported B-Rep to retain the same bounds, center, topology counts, solid count, and volume.

STEP normally contains final B-Rep geometry, not the original sketches, constraints, names, or feature history. Therefore:

• exact_step_base guarantees an unchanged imported base, not recovered native design history.
• Add later edits as named parametric modifications.
• Use semantic native reconstruction only when the feature family can be reliably recognized and validate it independently against the source.
• Never claim arbitrary STEP-to-JSON conversion recovers the author’s original parameters or construction order.

Parametric modification layer

Supported V1 operations are add_box, cut_box, add_cylinder, and cut_cylinder. Values may be literals or parameter references:

{
  "id": "central_bore",
  "operation": "cut_cylinder",
  "axis": "z",
  "center": [0, 0, 0],
  "diameter": {"parameter": "bore_diameter"},
  "length": {"parameter": "bore_length"},
  "enabled": true
}

Change a named value and rebuild:

python scripts/model_spec.py set path/to/model-spec.json bore_diameter 18
python scripts/model_spec.py build path/to/model-spec.json
python scripts/model_spec.py verify path/to/model-spec.json

Use apply_patch when adding or structurally editing parameters and features so the modification remains reviewable. After every visible rebuild, run the CAD inspection and snapshot workflow and update cad-task.json.