# JSON to CDSL

This program converts SolidWorks export JSON into parameterized Learning IR
(`*.cdsl.json`).

Conversion responsibilities:

- normalize SolidWorks JSON into an intermediate representation;
- classify sketches into named parameterized profiles;
- reuse equivalent profiles through semantic references;
- derive deterministic geometry through the sketch solver;
- remove avoidable floating-point noise;
- report unsupported or non-self-sufficient shapes.

The converter must not hide missing geometry behind an external context file
when producing a training-ready CDSL artifact.

## Evidence v2 batch converter

`evidence_v2_to_cdsl.py` converts the newer
`solidworks.cad_evidence.v2` extraction format into semantic CDSL v1.1. It
does not modify the current rebuild engine: features without a runtime
implementation are emitted with `execution_status: "deferred"` instead.

```bash
PYTHONPATH=backend/engine python json_to_cdsl/evidence_v2_to_cdsl.py \
  json_to_cdsl/input/evidence_v2 \
  --truth-dir json_to_cdsl/input/evidence_v2/truth \
  --out json_to_cdsl/output \
  --workers 1
```

For every `*.solidworks_evidence_v2.json` input it writes:

- `<part_id>.cdsl.json`: self-contained semantic CDSL in millimetres;
- `<part_id>.diagnostic.json`: source blockers, deferred features, optional
  `inferred_from_step` selectors, semantic validation, and STEP-versus-source
  bounding-box/volume/area/topology metrics;
- `manifest.json`: batch-level counts and paths.

The optional STEP directory is used only to infer a host face when exactly one
candidate is compatible with a Hole Wizard's captured locations. Ambiguous
geometry stays in `unresolved`; the converter never invents a selector.

Source records are discovered recursively. Output remains flat and is named by
the normalized full source filename. Files that normalize to the same part ID
receive a deterministic relative-path hash suffix, so every input record maps
to a distinct output. When a matching STEP file exists, it is resolved through
the same relative subdirectory as its source record.

## Onshape API samples

`download_onshape_samples.py` downloads raw Onshape v9 feature-list responses
for a small set of public ABC Part Studios. Create a personal API key in the
Onshape developer settings, then keep the credentials out of the repository:

```bash
export ONSHAPE_ACCESS_KEY='...'
export ONSHAPE_SECRET_KEY='...'
python json_to_cdsl/download_onshape_samples.py --count 3
```

If the environment variables are absent, the program prompts without echoing
the values. Output is written under
`json_to_cdsl/input/onshape_api_samples/<abc_id>/features.json`; this input
directory is ignored by Git. Use `--url ID=URL` for another Part Studio or
`--url-file` to read ABC `objects_*.yml` mappings.

## Complete Onshape sample

`download_onshape_complete.py` saves the complete public-API representation
of one Part Studio. It is the appropriate input for building a CDSL converter:
the directory includes the feature tree, sketch definitions and constraints,
FeatureScript representation, parts, body/topology data, mass properties,
tessellations, previews, native Parasolid, STL, and an independently exported
AP242 STEP reference model.

```bash
export ONSHAPE_ACCESS_KEY='...'
export ONSHAPE_SECRET_KEY='...'
python json_to_cdsl/download_onshape_complete.py --id 00000352
```

The result is written to
`json_to_cdsl/input/onshape_complete/00000352/manifest.json`. Every successful
artifact has a byte count and SHA-256 in that manifest. Failed endpoints are
also recorded, rather than silently omitted. This is all data exposed by the
public API for the selected Part Studio; it is not an internal `.onshape`
document backup, which Onshape does not expose as a download format.