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.
• Manufacturing intent: machining, printing, laser cutting, simulation, or concept.
• Required primary and secondary output formats.
• New model versus modification, and existing source/artifact paths.
• Part versus assembly, standard components, mating requirements, and motion relationships.
• Required parameter controls, replay, semantic tags, or FreeCAD interchange.
• 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, simplecadapi, or cadam.
• 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.
• Focused downstream Skills.
• 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", "cadam"],
    "workflow_profiles": ["requirement_refinement", "visual_repair"]
  },
  "source": {
    "path": "connecting_rod.py",
    "format": "python",
    "backend": "build123d"
  },
  "artifacts": [
    {"path": "connecting_rod.step", "role": "primary"},
    {"path": "connecting_rod.stl", "role": "secondary"}
  ],
  "parameters": {},
  "experience": {
    "library": "../../../cad-experience-library/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 model-spec.json that owns its parameter values, reconstruction mode, parametric modification layer, and output paths. See model-spec.md.

For an imported STEP, use exact_step_base: copy the explicitly supplied file into the task directory, record its checksum and geometry signature, and keep the imported B-Rep unchanged when the modification list is empty. This is an exact geometric base contract, not recovery of the original CAD feature tree.

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.