SPB Git

spb/zyquo-mlx Public MIT

The local MLX foundry for your Mac — run, fine-tune, quantize, and ship models. Nothing leaves your machine.

macosswiftaimlxfine-tuning
Swift 93.4% Python 3.8% Makefile 2.2% Shell 0.5%
6.3 KB
View source Raw Blame History
Zyquo MLX icon

# Zyquo MLX

The local MLX foundry for your Mac — run, fine-tune, quantize, and ship models. Nothing leaves your machine.

Release macOS 14+ Apple Silicon Swift MLX License: MIT Downloads Signed & Notarized

Where Zyquo Local is the chat client, Zyquo MLX is the foundry: the complete workbench for the on-device MLX lifecycle on Apple Silicon.

# ✨ What it does

  • 🧠 Run every MLX model type — streaming LLM chat, vision-language models with images, embeddings with a live similarity inspector, and Whisper speech-to-text — with tokens/sec, time-to-first-token, and verified memory release on every run
  • 🔥 Fine-tune on your own data — LoRA, QLoRA, DoRA, and full fine-tuning with a real configurator: live loss curves, checkpoints, cancel and warm resume, and memory gating that blocks impossible configs before they run
  • ⚗️ Quantize & convert — 4/8-bit affine quantization with size previews accurate to 0.1 %, adapter fusing (with a smart de-quantize default that actually preserves your adapter), and Hugging Face → MLX conversion
  • 📚 Datasets, done right — import JSONL (chat / prompt-completion / text), row-by-row validation with concrete fixes, deterministic train/valid splits, token stats
  • 🌐 Model discovery — a live-verified Featured catalog plus full mlx-community search, with RAM compatibility badges for your Mac and resumable downloads
  • 📊 Evaluate — base vs. fine-tuned side by side on the same prompt, with per-side stats
  • 🔒 100 % local — no API keys, no telemetry; the only network traffic is downloading models you ask for

# 📸 Screenshots

Light — model library Dark — derived forge theme
Models, light Models, dark
Training run — live loss curves, console, checkpoints Playground — streaming chat with live stats
Training run Playground

# ⚡ Measured performance (M5 Max, 48 GB)

Task Model Result
LLM inference Qwen3-0.6B-4bit 604–630 tok/s, TTFT 0.03–0.83 s
VLM + image Qwen3-VL-4B-Instruct-4bit 97 tok/s, TTFT 1.95 s
Embeddings Qwen3-Embedding-0.6B-DWQ 2 texts in 0.36 s (1024-dim)
Speech-to-text whisper-large-v3-turbo 7 s clip transcribed in 1.0 s
QLoRA training Qwen3-0.6B-4bit ~2,300 tok/s, peak 0.8 GB
LoRA training 0.6B fp16 base ~3,300 tok/s, peak 1.6 GB
Quantization 0.6B fp16 → 4-bit 1.19 GB → 335.5 MB (predicted 335.3)

Full matrix: docs/VERIFICATION.md.

# 📦 Installation

⬇️ Download Zyquo MLX.dmg — signed & notarized (Developer ID)

  1. Open the DMG and drag Zyquo MLX to Applications
  2. Launch — grab a model from Models › Discover and you're forging

Requirements: Apple Silicon Mac (M1 or later), macOS 14+. For fine-tuning, conversion, and speech, the app provisions an isolated Python environment on first use (needs uv: brew install uv; speech also uses brew install ffmpeg).

# 🛠 Build from source

Built without the Xcode IDE — command-line only, no .xcodeproj:

bash
# One-time: Xcode toolchain + Metal toolchain component (see docs/BUILD.md)
sudo xcode-select -s /Applications/Xcode.app
xcodebuild -downloadComponent metalToolchain

git clone https://github.com/spboucher-ai/zyquo-mlx && cd zyquo-mlx
make app     # release build + assemble "Zyquo MLX.app"
make dev     # build + launch

# 🏛 Architecture

text
Sources/ZyquoMLX/
├── Engine/        # InferenceEngine actor (LLM/VLM/embeddings), MemoryAdvisor, SpeechService
├── Training/      # TrainingService, RunStore, MetricsStream (live JSON protocol)
├── Convert/       # ConversionService (Swift-native quant + Python fuse/convert)
├── Data/          # DatasetService — JSONL validation, splits, previews
├── Hub/           # HubService, resumable DownloadManager, ModelStore
├── PyBridge/      # PythonRunner + pinned venv (mlx-lm 0.31.3) + JSON-lines scripts
├── DesignSystem/  # ZyquoTheme — copper-on-slate tokens, light + dark
└── Views/         # SwiftUI workbench: Models, Datasets, Train, Convert, Playground, Evaluate

Swift-native inference and quantization via mlx-swift + mlx-swift-lm; training and speech drive a pinned mlx-lm through a strict JSON progress protocol. Research docs with the full ground truth live in docs/ — including two upstream landmines the app works around (documented in docs/TRAINING-RESEARCH.md).

# 🗺 Roadmap

  • Image generation (Swift StableDiffusion / FLUX pipelines)
  • One-click "send to Zyquo Local"
  • lm-evaluation-harness integration for benchmark scorecards
  • DWQ/AWQ/GPTQ advanced quantization recipes

# 🤝 The Zyquo family

Zyquo Local (chat client) · Zyquo MLX (this foundry) · Zyquo Term · Zyquo Atlas

# 📄 License

MIT — © 2026 Simon-Pierre Boucher · contact@spboucher.ai