step-parse/skill.src/SETUP_CHECKLIST.md

STEP Processor — macOS Setup Checklist

Apple Silicon (Mac Studio M-series) · No Rosetta Required

Work through this top to bottom. Each section has a ✅ verification command so you know it worked before moving on.

---

PHASE 1 — Prerequisites

1.1 — Confirm Python version

python3 --version

You need Python 3.10, 3.11, or 3.12. 3.13 will work but is less tested. 3.9 is too old.

If your version is wrong, install via Homebrew:

brew install python@3.11

Then use python3.11 explicitly in all commands below.

---

1.2 — Confirm Homebrew is installed

brew --version

If missing:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

---

1.3 — Create a dedicated virtual environment

Keep everything isolated from your system Python. Pick a folder — e.g. your CoWork dev directory.

python3 -m venv ~/step-processor-env
source ~/step-processor-env/bin/activate

You should see (step-processor-env) in your terminal prompt. All pip commands below assume this environment is active.

✅ Verify:

which python   # should point inside step-processor-env

---

PHASE 2 — Primary Library: build123d

2.1 — Upgrade pip first

pip install --upgrade pip

---

2.2 — Install cadquery-ocp (the OCC kernel, native arm64)

This is now on PyPI directly — no manual wheel download needed.

pip install cadquery-ocp

This is a large download (~300MB). Let it run.

✅ Verify:

python -c "import OCP; print('OCP kernel OK')"

---

2.3 — Install build123d

pip install build123d

✅ Verify:

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

---

2.4 — Install the rendering stack

pip install trimesh pyrender Pillow numpy pandas anthropic openpyxl

Note: openpyxl is required for Excel BOM output. If missing, the skill silently falls back to CSV. Install it here to get MPM-branded .xlsx output.

✅ Verify each:

python -c "import trimesh; print('trimesh OK')"
python -c "import pyrender; print('pyrender OK')"
python -c "import PIL; print('Pillow OK')"
python -c "import pandas; print('pandas OK')"
python -c "import anthropic; print('anthropic OK')"
python -c "import openpyxl; print('openpyxl OK')"

---

PHASE 3 — Diagram Export: cairosvg

Required for converting SVG diagrams to PNG and PDF.

3.1 — Install system libraries via Homebrew

brew install cairo pango gdk-pixbuf libffi

3.2 — Install cairosvg

pip install cairosvg

✅ Verify:

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

If you get a library not found error, run this and retry:

export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig"
pip install cairosvg

---

PHASE 4 — Fallback Library: FreeCAD Headless

Only needed if build123d fails on a specific file.

macOS 15 Sequoia note: The conda-forge FreeCAD package is killed silently by Gatekeeper on Sequoia due to unsigned binaries. Use the official signed FreeCAD.app instead (approach below). Conda approach will NOT work on Sequoia.

4.1 — Install official FreeCAD.app (signed & notarized)

Download the latest arm64 release from:

https://github.com/FreeCAD/FreeCAD/releases/latest

Open the .dmg and drag FreeCAD.app to /Applications as normal. Launch it once from /Applications so macOS registers the security approval.

4.2 — Verify headless via app bundle

The binary is freecadcmd (all lowercase) inside the bundle:

/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd --version
# Should print: FreeCAD 1.x.x Revision: ...

✅ Verify Python import:

/Applications/FreeCAD.app/Contents/Resources/bin/python -c \
  "import sys; sys.path.insert(0, '/Applications/FreeCAD.app/Contents/Resources/lib'); \
   import FreeCAD; print('FreeCAD', FreeCAD.Version())"

Key paths for loader.py:

• CLI binary: /Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd
• Python interpreter: /Applications/FreeCAD.app/Contents/Resources/bin/python
• Module path (add to sys.path): /Applications/FreeCAD.app/Contents/Resources/lib

The code invokes FreeCAD using the bundle's own Python — no conda env needed.

---

PHASE 5 — API Key

5.1 — Set your Anthropic API key

echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"' >> ~/.zshenv
source ~/.zshrc

Important: Add the key to both ~/.zshrc AND ~/.zshenv. ~/.zshrc is only sourced in interactive terminal sessions. ~/.zshenv is sourced for all zsh invocations including Desktop Commander's non-interactive shells — without it, translation will silently fail when running via CoWork/Desktop Commander.

✅ Verify:

echo $ANTHROPIC_API_KEY   # should print your key (or at least sk-ant-...)

---

PHASE 6 — Place the Skill Files

6.1 — Copy the step-processor folder to your working location

Recommended: somewhere in your CoWork project or a dedicated tools directory.

~/your-project/
  step-processor/
    step_processor.py
    modules/
      __init__.py
      loader.py
      bom.py
      renderer.py
      translator.py
      rewriter.py
      query_engine.py
      external_diagram.py
    schemas/
      external_diagram_schema.json
      parts_mapping_schema.json
    templates/
      datablock_template.md
    SKILL.md
    INSTALL.md

6.2 — Activate your environment before running

source ~/step-processor-env/bin/activate
cd ~/your-project/step-processor

---

PHASE 7 — Test Run (do this when you have a STEP file ready)

Work through these tests in order. Stop at the first failure and fix it before continuing.

---

TEST 1 — Confirm the skill loads without errors

python step_processor.py --help

Expected: prints the CLI help/usage block with no ImportError or traceback.

---

TEST 2 — Load a STEP file and extract BOM

Replace yourfile.step with your actual file path.

python step_processor.py /path/to/yourfile.step --no-thumbnails --verbose

Expected output:

INFO  Loading: yourfile.step
INFO  [build123d] Loaded: yourfile.step
INFO  BOM extracted: N parts
INFO  BOM XLSX → /path/to/yourfile_bom.xlsx

Open the .xlsx file to confirm part names look right. If you see Chinese characters in the Supplier Part Name column — that's expected and correct. The Part Description column will be populated with English in Test 4. If you see a CSV instead of xlsx, openpyxl is not installed — run pip install openpyxl.

---

TEST 3 — Generate thumbnails

python step_processor.py /path/to/yourfile.step --no-bom --verbose

Expected: 6 PNG files appear next to the STEP file: yourfile_front.png, yourfile_bottom.png, yourfile_left.png, yourfile_right.png, yourfile_iso_left.png, yourfile_iso_right.png

Open them in Preview to confirm they look like your enclosure from different angles.

---

TEST 4 — Translation (requires API key)

Only run this if the BOM from Test 2 has Chinese part names.

python step_processor.py /path/to/yourfile.step --no-thumbnails --translate --verbose

Expected: part_name_english column in the CSV is now populated with English names. A yourfile_EN.step should appear if Chinese labels were found in the STEP file itself.

---

TEST 5 — Geometry query REPL

python step_processor.py /path/to/yourfile.step --no-thumbnails --no-bom --repl

At the > prompt, try:

> bounding box
> list all holes
> all parts
> help
> exit

Confirm the output tables look reasonable for your file.

---

TEST 6 — External dimensional diagram

python step_processor.py /path/to/yourfile.step --diagram --verbose

Expected files next to the STEP:

• yourfile__external-diagram.svg
• yourfile__external-diagram.png
• yourfile__meta.json

Open the SVG in a browser (drag and drop into Safari or Chrome) to inspect the diagram. Open the PNG for the rasterized version. Open the JSON to confirm the metadata block populated correctly.

---

TEST 7 — Diagram with PDF output

python step_processor.py /path/to/yourfile.step --diagram --diagram-pdf --verbose

Expected: adds yourfile__external-diagram.pdf to the outputs. Open in Preview to confirm it renders cleanly.

---

Quick Reference — Re-activating After Restart

Every time you open a new terminal session:

source ~/step-processor-env/bin/activate
cd ~/your-project/step-processor
export ANTHROPIC_API_KEY="sk-ant-..."   # only if not already in ~/.zshrc

---

Troubleshooting Quick Reference

Symptom	Fix
ModuleNotFoundError: build123d	pip install build123d (check env is activated)
ModuleNotFoundError: OCP	pip install cadquery-ocp
ModuleNotFoundError: cairosvg	brew install cairo && pip install cairosvg
pyrender offscreen crash	Expected on some macOS setups — thumbnails will warn but diagram still generates
BOM shows no parts / 1 part	Normal for single-body STEP files — the STEP text parser falls back to 1-row BOM
Chinese labels not translated	Check $ANTHROPIC_API_KEY is set. If running via CoWork/Desktop Commander, add key to ~/.zshenv not just ~/.zshrc
BOM output is CSV not xlsx	openpyxl not installed — pip install openpyxl with venv active
_EN.step entity count mismatch warning	File has unusual STEP encoding — rewrite skipped, original untouched, BOM still correct
FreeCAD fallback not working	Use signed FreeCAD.app — conda-forge is Gatekeeper-blocked on Sequoia. Path: /Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd (all lowercase)
Diagram SVG opens blank	Check yourfile__meta.json warnings array for geometry errors