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.
• 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 that owns its coordinate system, datums, parameters, expressions, features, constraints, edit interface, and validation contract. See designir-2.0.md.

For an uploaded STEP, keep teacher geometry in designir-pipeline/input/ and all private evidence, DesignIR candidates, rebuilds, and acceptance reports in designir-pipeline/runs/. The reconstruction task receives evidence but no teacher STEP or imported B-Rep.

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.