refactor: add DesignIR distillation pipeline

2026-07-27 17:24:04 +08:00
parent 0adaac2b2a
commit 550b339bcc
1128 changed files with 10248 additions and 426666 deletions
@@ -0,0 +1,134 @@
+---
+name: cad-experience-builder
+description: Batch-extract STEP files into private JSON, use the active large model to semantically distill transferable CAD methods from a sanitized batch, and deterministically verify and publish a backend-neutral experience library. Use when distilling STEP/STP corpora, reviewing candidate methods, inducing feature motifs and constraints, auditing instance-data leakage, or preparing promoted experience for cad-router and CAD backends.
+---
+
+# CAD Experience Builder
+
+Induce methods, not copied answers. Keep source-part evidence outside the
+published library and require repeated support before promoting any experience.
+
+## Required workflow
+
+1. Put source `.step` or `.stp` files in
+   `workspace/teacher/inbox/`. Only deterministic ingestion and Agent B may
+   access this vault.
+2. Parse every new, content-unique STEP into visible private JSON under
+   `workspace/teacher/evidence/`:
+
+   ```bash
+   ../../scripts/cad-experience extract-folder
+   ```
+
+3. Prepare a sanitized semantic batch:
+
+   ```bash
+   ../../scripts/cad-experience prepare
+   ```
+
+4. Read `workspace/promotion/candidates/semantic-batch.json` completely. Act as the semantic
+   distiller: compare families, parameter roles, datum roles, canonical
+   reconstruction stages, feature cardinality classes, relations, prior
+   vocabulary, failure rules, and validation targets; then author
+   `workspace/promotion/candidates/experience-draft.json` using
+   `references/llm-review-contract.md`.
+
+   Propose methods, invariants, and family-level `reconstruction_grammar`
+   records, not raw co-occurrence pairs. A reconstruction grammar is a
+   canonical backend-neutral strategy inferred from repeated geometry; it is
+   not the source model's recovered feature history. Do not infer
+   manufacturing intent or failure causes that final B-Rep evidence cannot
+   support.
+
+5. Publish only after the model draft exists:
+
+   ```bash
+   ../../scripts/cad-experience publish \
+     --draft ../../workspace/promotion/candidates/experience-draft.json
+   ```
+
+   The publisher recomputes support from the private corpus, rejects numeric
+   instance answers, keeps weak proposals as candidates, and marks the library
+   router-consumable only after this verification.
+
+6. Audit the public library. Treat any failure as a hard publishing failure:
+
+   ```bash
+   python scripts/cad_experience.py audit \
+     ../../workspace/promotion/promoted/library.json
+   ```
+
+7. Query only the published library for creation, modification, or rebuilding:
+
+   ```bash
+   python scripts/cad_experience.py query \
+     ../../workspace/promotion/promoted/library.json \
+     --family flanged_hub_adapter \
+     --features base_flange,hollow_sleeve,counterbore
+   ```
+
+8. Pass the query result, never the teacher vault, unrelated private evidence,
+   or a case JSON,
+   to `$cad-router` or a backend.
+
+Direct `distill` without an LLM-authored draft is intentionally blocked. The
+active Codex model supplies semantic judgment; no separate web API key is
+required.
+
+## STEP extraction boundary
+
+- The V2 extractor reads analytic B-Rep surfaces, bounding boxes, topology
+  counts, axes, radii, and locations into a private evidence record.
+- It derives scale-independent body classes, part families, rotational and
+  prismatic motifs, passage and pattern relationships, complexity roles, and
+  normalized ratio observations before sanitization.
+- It also derives private exact cardinality evidence plus sanitized symbolic
+  parameter roles, datum roles, feature-count classes, and canonical
+  reconstruction stages. These are the evidence used to learn how to rebuild a
+  family without publishing any teacher dimensions.
+- Exact source paths, hashes, dimensions, coordinates, and face references are
+  permitted in private case JSON and forbidden in the published library.
+- Keep input/output as a human-visible staging area and induction corpus. Never
+  use it directly during creation, modification, or reconstruction.
+- A semantic candidate is not a trusted design method until repeated,
+  independently sourced cases satisfy the promotion policy.
+
+## Promotion rules
+
+- One case is evidence, not experience.
+- Publish generalized, dimension-free observations below threshold as visible
+  `candidate_experiences`, but never expose them to generation consumers.
+- Require `min_support` independent cases and conditional `min_confidence`
+  within the proposal's semantic context before promotion.
+- Promote feature compositions, semantic constraints, dimensionless
+  distributions, validation checks, and failure-repair methods.
+- Reject absolute dimensions, coordinates, face references, source paths,
+  source hashes, and full parameter dictionaries from published experience.
+- Keep generated examples out of the trusted corpus until independently
+  validated.
+- Evaluate generalization on held-out cases that were not used for induction.
+
+## Backend contract
+
+The library is backend-neutral. A consumer receives:
+
+- `feature_motif`: reusable compositions of feature types;
+- `constraint`: invariant semantic relationships;
+- `design_rule`: conditional modeling guidance;
+- `dimensionless_distribution`: multi-case ratio ranges;
+- `validation_rule`: checks independent of one part's coordinates;
+- `failure_repair`: reusable detection and repair methods.
+- `reconstruction_grammar`: symbolic parameters, datums, canonical feature
+  stages, optional/required feature roles, and validation roles for a family.
+
+build123d, SimpleCADAPI, or another backend translates the same queried
+experience into its own operations. Experience must never contain executable
+teacher geometry.
+
+## References
+
+- Read `references/case-input-contract.md` before producing batch input.
+- Read `references/experience-library-schema.md` before extending the output
+  schema or adding a consumer.
+- Read `references/llm-review-contract.md` before authoring or revising a
+  semantic proposal draft.