Setup

The corporate monoliths insist that frontier intelligence requires warehouse-scale compute, liquid nitrogen cooling, and multimillion-dollar energy bills. This is the Monolithic Delusion. We are dismantling it. S-MoE is the mechanism of liberation, returning state-of-the-art capabilities to the quiet, elegant aluminum slab sitting on your desk.

Everything you need to awaken a clean clone on any supported Apple Silicon Mac is right here. No rented servers. No cloud subscriptions. Just pure, sovereign intelligence.

---

The Prerequisites of Independence

Requirement	Minimum	Notes
Hardware	Apple Silicon Mac	M1 / M2 / M3 / M4 — Unified Memory is mandatory.
macOS	14.0 Sonoma	Requires Metal 3 API + NVMe Direct I/O support.
RAM	16 GB	16 GB runs smaller MoE vaults. For Qwen3-235B the Surface Scout alone occupies ~16 GB of UMA, so 32 GB is the practical floor and 48 GB is recommended for the frontier.
Storage	~150 GB free NVMe	A 235B vault is ~117 GB (Q4) + ~16 GB Scout. The ~470 GB HuggingFace checkpoint can live on an external drive — only the shattered artifacts need fast internal NVMe.
Xcode CLT	15.0+	xcode-select --install
Python	3.9+	Used for the shatter_moe.py sculptor — ships with macOS.
clang++	Ships with Xcode CLT	C++20 required for our zero-allocation engine.
make	Ships with Xcode CLT	GNU Make 3.81+

---

Clone & Bootstrap

Bring the resistance home.

git clone https://github.com/melasistema/s-moe.git
cd s-moe

# Forge the isolated Python sanctuary and forge dependencies
make setup

Expected resonance:

  ✓  Environment ready.  Activate with:
       source .venv/bin/activate

Sovereign Automation

No activation is needed for Make targets. Commands like make shatter and make probe elegantly summon .venv/bin/python3 directly. You only need to activate the environment if you seek a REPL or direct IDE integration.

---

Verify the Quantiser

Confirm the structural integrity of the SMOE quantiser (the smoke test exercises the Q2 code path; the same module powers Q4):

make test-quant

Expected echo:

  RMSE=0.50xxx  absmax=1.2xxxx  SNR=5.x dB
  ✓  SMOE-Q2 smoke-test passed

---

Forge the Engine

Compile the unyielding C++ core and the Metal Objective-C++ bridge. This is where your hardware learns to bypass the OS and seize direct control of intelligence.

make all

Expected forging:

  ⚡  smoe-engine → build/smoe-engine

Kernels are JIT-compiled

The Metal Shading Language kernels in src/compute/kernels.metal are compiled at engine startup via newLibraryWithSource: — no .metallib artifact is produced at build time. The first launch pays a fraction of a second of shader compilation; every launch adapts to the vault's bits field without recompiling the engine.

---

The Arsenal of Make Targets

make help                                         # list all targets
make setup                                        # create .venv + install deps
make test-quant                                   # smoke-test the SMOE quantiser
make probe MODEL=<dir>                            # topology detection dry-run
make shatter MODEL=<dir> OUT=<dir>                # shatter into .smoe vault (validation included)
make shatter MODEL=<dir> OUT=<dir> ARGS="..."     # pass extra sculptor flags, e.g. ARGS="--bits 2 --max-layers 2"
make all                                          # build the C++ engine
make rebuild                                      # clean + full rebuild
make clean                                        # remove build/
make nuke                                         # remove build/ and .venv

--validate is always passed by the shatter target — there is no need to request it. Extra sculptor flags (--bits, --max-layers, --max-experts, --measure-error, --group-size) travel through ARGS="...".