---
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 `parser/input/`.
2. Parse every new, content-unique STEP into visible private JSON under
   `parser/output/`:

   ```bash
   ../../scripts/cad-experience extract-folder
   ```

3. Prepare a sanitized semantic batch:

   ```bash
   ../../scripts/cad-experience prepare
   ```

4. Read `work/review/semantic-batch.json` completely. Act as the semantic
   distiller: compare families, features, relations, prior vocabulary, failure
   rules, and validation targets; then author
   `work/review/experience-draft.json` using
   `references/llm-review-contract.md`.

   Propose methods and invariants, not raw co-occurrence pairs. Do not infer
   operation order, 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 ../../work/review/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 \
     /path/to/cad-experience-library/library.json
   ```

7. Query only the published library for creation, modification, or rebuilding:

   ```bash
   python scripts/cad_experience.py query \
     /path/to/cad-experience-library/library.json \
     --family flanged_hub_adapter \
     --features base_flange,hollow_sleeve,counterbore
   ```

8. Pass the query result, never `parser/input`, `parser/output`, 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 extractor reads analytic B-Rep surfaces, bounding boxes, topology counts,
  axes, radii, and locations into a private evidence record.
- It derives only semantic candidates such as rotational stacks, axis
  relationships, transitions, and repeated-hole motifs.
- 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 `min_confidence` 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.

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.