Jerry
107 lines
4.3 KiB
Markdown
107 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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.
|