step-parse/skill.src/INSTALL.md

INSTALL.md — STEP Processor Setup (Apple Silicon / macOS arm64)

No Rosetta. No x64 sub-environments. Both libraries run natively.

---

1. build123d (Primary — native arm64, pip-based)

build123d depends on cadquery-ocp, which ships native arm64 wheels via GitHub Releases (not yet on PyPI, but stable).

Step 1 — Install the arm64 OCP wheel

Go to: https://github.com/CadQuery/OCP/releases

Download the wheel matching your Python version, e.g.: cadquery_ocp-7.x.x-cp311-cp311-macosx_12_0_arm64.whl

Install it:

pip install /path/to/cadquery_ocp-*.whl

Step 2 — Install build123d and rendering stack

pip install build123d
pip install trimesh pyrender Pillow numpy pandas anthropic

Step 3 — Set API key

export ANTHROPIC_API_KEY=sk-ant-...
# Add to ~/.zshrc to persist

Step 4 — Verify

python -c "import build123d; print('build123d OK')"
python -c "import trimesh; print('trimesh OK')"
python -c "import pyrender; print('pyrender OK')"

---

2. FreeCAD Headless (Fallback — native arm64 via conda-forge)

FreeCAD has been available as a native macOS-arm64 conda-forge package since late 2024. Install it in its own conda environment to avoid dependency conflicts with build123d.

Step 1 — Install Miniforge (arm64) if not already present

Download from: https://github.com/conda-forge/miniforge/releases Select: Miniforge3-MacOSX-arm64.sh

bash Miniforge3-MacOSX-arm64.sh

Step 2 — Create FreeCAD environment

conda create -n freecad_env python=3.11
conda activate freecad_env
conda install -c conda-forge freecad

Step 3 — Verify headless operation

FreeCADCmd --version
# or
python -c "import FreeCAD; import Part; print('FreeCAD headless OK')"

Important: Never import FreeCADGui in headless scripts — it will crash.

Step 4 — Make FreeCAD importable from your build123d environment

Add the FreeCAD conda env's site-packages to your PATH, or run scripts via the conda freecad_env directly:

conda run -n freecad_env python step_processor.py myfile.step

---

Quick Test

Once either library is installed:

# Test with a sample STEP file
python step_processor.py sample.step --verbose

# Test query REPL
python step_processor.py sample.step --repl

---

Dependency Summary

Package	Purpose	Required for
build123d	STEP loading + geometry	Primary path
cadquery-ocp	OCC kernel (arm64 wheel)	build123d
trimesh	Mesh handling for rendering	PNG thumbnails
pyrender	Offscreen rendering	PNG thumbnails
Pillow	PNG file writing	PNG thumbnails
numpy	Geometry math	Both paths
pandas	BOM CSV output	BOM export
anthropic	Claude API translation	Translation
FreeCAD	Fallback STEP loading	Fallback path only

---

3. cairosvg (required for PNG and PDF export from diagrams)

pip install cairosvg

# On macOS, may also need:
brew install cairo pango gdk-pixbuf libffi

Verify:

python -c "import cairosvg; print('cairosvg OK')"