cadSet/text-to-cad/skills/cad-router/references/backend-contract.md

Backend and artifact contract

Router input

Capture these fields when known:

• Natural-language request and normalized part family.
• Units and dimensions.
• STEP is the fixed geometry artifact format.
• New model versus modification, and existing source/artifact paths.
• Part versus assembly, standard components, mating requirements, and motion relationships.
• Required parameter controls, replay, or semantic tags.
• Geometry and visual validation targets.
• Optional schema 2.0 generalized experience library. Never pass a case DesignIR, teacher STEP, source dimensions, coordinates, or surface references to the selected backend.
• For modification, accept only an explicitly supplied original model or editable generator plus the promoted library. Never inspect the parser input/output corpus or a private case JSON.

Route decision

Record:

• selected_backend: build123d or simplecadapi.
• routing_policy.effective_execution_engine: the actual engine. It is surfaceir for an uploaded STEP even though selected_backend records the preferred semantic authoring backend for later edits.
• routing_policy.validation_engines: validators required by the chosen mode.
• Origin project and optional executable adapter.
• runner_skill: installed Skill responsible for generation.
• Ranked backend scores and human-readable reasons.
• Fallback order.
• Workflow profiles such as requirement_refinement and visual_repair.
• Any explicit override and its reason.
• operation: create or modify; for modification also record the explicit source path and whether the route uses native parameter editing, local feature rebuilding, or experience-guided semantic reconstruction.

Task manifest

Write cad-task.json beside the task artifacts with this minimum shape:

{
  "schema_version": "1.0",
  "request": "Create a 120 mm connecting rod",
  "route": {
    "selected_backend": "build123d",
    "runner_skill": "cad",
    "project": "text-to-cad",
    "fallback_order": ["simplecadapi"],
    "workflow_profiles": ["requirement_refinement", "visual_repair"]
  },
  "source": {
    "path": "connecting_rod.py",
    "format": "python",
    "backend": "build123d"
  },
  "artifacts": [
    {"path": "connecting_rod.step", "role": "primary"}
  ],
  "parameters": {},
  "experience": {
    "library": "../../../designir-pipeline/output/library.json",
    "context_kind": "generalized_cad_experience_query",
    "methods_applied": []
  },
  "assumptions": [],
  "validation": [],
  "viewer_links": []
}

Paths are relative to the task directory unless an external input must remain absolute. Do not store authoritative model parameters in cad-task.json. Every part must have a sibling *.designir.json as its editable source of truth. Authored feature models use semantic DesignIR 3.0; uploaded STEP reconstruction uses DesignIR 3.0 / SurfaceIR. See designir-3.0.md; designir-2.0.md is retained only for legacy migration.

For an uploaded STEP, use scripts/route.py --execute with an explicit source and task directory. Do not move an ordinary upload into or scan the distillation corpus. The task publishes the independent DesignIR, reconstructed STEP, validated parameter catalog, geometry report, edit report, and cad-task.json. The reconstruction subprocess receives no teacher STEP path; only extraction and acceptance may read the explicit uploaded source. The acceptance stage records both SurfaceIR geometry validation and the SimpleCADAPI B-Rep comparator. A B-Rep report may be passed, mismatch, or unavailable; only passed earns the brep_exact quality tier. Geometry equality with a topology mismatch remains usable for review but is not an exact reconstruction.

Backend adapter requirements

Any future executable adapter must:

1. Accept an explicit task directory and explicit source/output paths.
2. Never scan or generate an entire workspace implicitly.
3. Preserve a human-editable source of truth.
4. Report backend name and version.
5. Return nonzero on generation failure.
6. Emit machine-readable artifact paths and validation facts.
7. Avoid importing code from sibling Skill directories; call installed tools or self-contained runtimes.
8. Keep permanent CAD artifacts under the repository models/ root when working inside this repository.
9. Start CAD Viewer at the task directory, not the repository-wide examples directory.