# 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:
```bash
pip install /path/to/cadquery_ocp-*.whl
```

### Step 2 — Install build123d and rendering stack

```bash
pip install build123d
pip install trimesh pyrender Pillow numpy pandas anthropic
```

### Step 3 — Set API key

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

### Step 4 — Verify

```bash
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
bash Miniforge3-MacOSX-arm64.sh
```

### Step 2 — Create FreeCAD environment

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

### Step 3 — Verify headless operation

```bash
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:
```bash
conda run -n freecad_env python step_processor.py myfile.step
```

---

## Quick Test

Once either library is installed:

```bash
# 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)

```bash
pip install cairosvg

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

Verify:
```bash
python -c "import cairosvg; print('cairosvg OK')"
```