---
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 directly in `input/`. Git ignores this
   directory; only deterministic ingestion and Agent B may access it.
2. Parse every new, content-unique STEP into private JSON under
   `runs/evidence/`:

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

3. Prepare a sanitized semantic batch:

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

4. Read `runs/review/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
   `runs/review/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 ../../runs/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 \
     ../../output/library.json
   ```

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

   ```bash
   python scripts/cad_experience.py query \
     ../../output/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/` and `runs/` as a local-only induction corpus. Never use them
  directly during ordinary creation, modification, or reconstruction.
- Commit only the verified runtime library in `output/`; never commit source
  STEP files, extracted evidence, review drafts, reports, or rebuilt parts.
- 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.