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/workspace/promotion/promoted/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 the protected ingestion and acceptance workspace. The reconstruction task contains private evidence, DesignIR, backend source, and rebuilt STEP 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.