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%

release: v1.0.0 — GitHub publication (README with badges/screenshots/perf table, MIT license, version 1.0.0)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
simon-pierre boucher committed 11 days ago (Jul 31, 2026) parent cebef7e

Showing 8 changed files with +118 and −34

added LICENSE +21 −0
@@ -0,0 +1,21 @@
1 +MIT License
2 +
3 +Copyright (c) 2026 Simon-Pierre Boucher
4 +
5 +Permission is hereby granted, free of charge, to any person obtaining a copy
6 +of this software and associated documentation files (the "Software"), to deal
7 +in the Software without restriction, including without limitation the rights
8 +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 +copies of the Software, and to permit persons to whom the Software is
10 +furnished to do so, subject to the following conditions:
11 +
12 +The above copyright notice and this permission notice shall be included in all
13 +copies or substantial portions of the Software.
14 +
15 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 +SOFTWARE.
modified README.md +96 −33
@@ -6,50 +6,113 @@
6 6 Mail: contact@spboucher.ai
7 7 -->
8 8
9 +<div align="center">
10 +
11 +<img src="assets/icon/app-icon.png" width="128" alt="Zyquo MLX icon">
12 +
9 13 # Zyquo MLX
10 14
11 −**Zyquo MLX** is the foundry of the Zyquo family: a native macOS workbench for
12 −the full on-device MLX lifecycle on Apple Silicon — inference of every
13 −supported model type, LoRA/QLoRA and full fine-tuning, quantization, format
14 −conversion, dataset preparation, training runs with live metrics, evaluation,
15 −and export. Swift + SwiftUI, built without the Xcode IDE.
15 +**The local MLX foundry for your Mac — run, fine-tune, quantize, and ship models. Nothing leaves your machine.**
16 +
17 +[![Release](https://img.shields.io/github/v/release/spboucher-ai/zyquo-mlx?color=EA6A2B&label=release)](https://github.com/spboucher-ai/zyquo-mlx/releases/latest)
18 +[![macOS 14+](https://img.shields.io/badge/macOS-14%2B-334155)](https://github.com/spboucher-ai/zyquo-mlx)
19 +[![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-arm64-334155)](https://github.com/spboucher-ai/zyquo-mlx)
20 +[![Swift](https://img.shields.io/badge/Swift-SwiftUI-EA6A2B)](Package.swift)
21 +[![MLX](https://img.shields.io/badge/Apple-MLX-EA6A2B)](https://github.com/ml-explore/mlx)
22 +[![License: MIT](https://img.shields.io/badge/license-MIT-334155)](LICENSE)
23 +[![Downloads](https://img.shields.io/github/downloads/spboucher-ai/zyquo-mlx/total?color=EA6A2B)](https://github.com/spboucher-ai/zyquo-mlx/releases)
24 +[![Signed & Notarized](https://img.shields.io/badge/Signed%20%26%20Notarized-Developer%20ID-2FA36B)](docs/BUILD.md)
25 +
26 +*Where **Zyquo Local** is the chat client, **Zyquo MLX** is the foundry: the complete workbench for the on-device MLX lifecycle on Apple Silicon.*
27 +
28 +</div>
29 +
30 +---
31 +
32 +## ✨ What it does
33 +
34 +- 🧠 **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
35 +- 🔥 **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
36 +- ⚗️ **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
37 +- 📚 **Datasets, done right** — import JSONL (chat / prompt-completion / text), row-by-row validation with concrete fixes, deterministic train/valid splits, token stats
38 +- 🌐 **Model discovery** — a live-verified Featured catalog plus full mlx-community search, with RAM compatibility badges for *your* Mac and resumable downloads
39 +- 📊 **Evaluate** — base vs. fine-tuned side by side on the same prompt, with per-side stats
40 +- 🔒 **100 % local** — no API keys, no telemetry; the only network traffic is downloading models you ask for
41 +
42 +## 📸 Screenshots
43 +
44 +| Light — model library | Dark — derived forge theme |
45 +|---|---|
46 +| ![Models, light](assets/screenshots/models-light.png) | ![Models, dark](assets/screenshots/models-dark.png) |
47 +
48 +| Training run — live loss curves, console, checkpoints | Playground — streaming chat with live stats |
49 +|---|---|
50 +| ![Training run](assets/screenshots/train-run.png) | ![Playground](assets/screenshots/playground-chat.png) |
51 +
52 +## ⚡ Measured performance (M5 Max, 48 GB)
16 53
17 −## Requirements
54 +| Task | Model | Result |
55 +|---|---|---|
56 +| LLM inference | Qwen3-0.6B-4bit | **604–630 tok/s**, TTFT 0.03–0.83 s |
57 +| VLM + image | Qwen3-VL-4B-Instruct-4bit | 97 tok/s, TTFT 1.95 s |
58 +| Embeddings | Qwen3-Embedding-0.6B-DWQ | 2 texts in 0.36 s (1024-dim) |
59 +| Speech-to-text | whisper-large-v3-turbo | 7 s clip transcribed in **1.0 s** |
60 +| QLoRA training | Qwen3-0.6B-4bit | ~2,300 tok/s, peak 0.8 GB |
61 +| LoRA training | 0.6B fp16 base | ~3,300 tok/s, peak 1.6 GB |
62 +| Quantization | 0.6B fp16 → 4-bit | 1.19 GB → 335.5 MB (predicted 335.3) |
18 63
19 −- Apple Silicon Mac (arm64 only — MLX requires it), macOS 14+
20 −- Full Xcode installed **as a toolchain only** (the IDE is never opened) with
21 − the Metal toolchain component — see `docs/BUILD.md` §2:
22 − ```bash
23 − sudo xcode-select -s /Applications/Xcode.app
24 − sudo xcodebuild -license accept
25 − xcodebuild -downloadComponent metalToolchain
26 − ```
27 −- `uv` (Python-side pipelines are provisioned at first run into
28 − `~/Library/Application Support/ZyquoMLX/py/`)
29 −- For the icon pipeline: `brew install librsvg`
64 +Full matrix: [`docs/VERIFICATION.md`](docs/VERIFICATION.md).
30 65
31 −## Build
66 +## 📦 Installation
67 +
68 +**[⬇️ Download Zyquo MLX.dmg](https://github.com/spboucher-ai/zyquo-mlx/releases/latest/download/ZyquoMLX.dmg)** — signed & notarized (Developer ID)
69 +
70 +1. Open the DMG and drag **Zyquo MLX** to Applications
71 +2. Launch — grab a model from **Models › Discover** and you're forging
72 +
73 +**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`](https://docs.astral.sh/uv/): `brew install uv`; speech also uses `brew install ffmpeg`).
74 +
75 +## 🛠 Build from source
76 +
77 +Built **without the Xcode IDE** — command-line only, no `.xcodeproj`:
32 78
33 79 ```bash
34 −make app # release build + assemble "Zyquo MLX.app" (ad-hoc signed)
80 +# One-time: Xcode toolchain + Metal toolchain component (see docs/BUILD.md)
81 +sudo xcode-select -s /Applications/Xcode.app
82 +xcodebuild -downloadComponent metalToolchain
83 +
84 +git clone https://github.com/spboucher-ai/zyquo-mlx && cd zyquo-mlx
85 +make app # release build + assemble "Zyquo MLX.app"
35 86 make dev # build + launch
36 −make release # Developer ID signed + notarized (Phase 8)
37 87 ```
38 88
39 −Everything is driven by the `Makefile` — command-line `swift build` /
40 −`xcodebuild` only; no `.xcodeproj` exists or ever will.
89 +## 🏛 Architecture
90 +
91 +```
92 +Sources/ZyquoMLX/
93 +├── Engine/ # InferenceEngine actor (LLM/VLM/embeddings), MemoryAdvisor, SpeechService
94 +├── Training/ # TrainingService, RunStore, MetricsStream (live JSON protocol)
95 +├── Convert/ # ConversionService (Swift-native quant + Python fuse/convert)
96 +├── Data/ # DatasetService — JSONL validation, splits, previews
97 +├── Hub/ # HubService, resumable DownloadManager, ModelStore
98 +├── PyBridge/ # PythonRunner + pinned venv (mlx-lm 0.31.3) + JSON-lines scripts
99 +├── DesignSystem/ # ZyquoTheme — copper-on-slate tokens, light + dark
100 +└── Views/ # SwiftUI workbench: Models, Datasets, Train, Convert, Playground, Evaluate
101 +```
102 +
103 +Swift-native inference and quantization via [mlx-swift](https://github.com/ml-explore/mlx-swift) + [mlx-swift-lm](https://github.com/ml-explore/mlx-swift-lm); training and speech drive a pinned [mlx-lm](https://github.com/ml-explore/mlx-lm) through a strict JSON progress protocol. Research docs with the full ground truth live in [`docs/`](docs/) — including two upstream landmines the app works around (documented in [`docs/TRAINING-RESEARCH.md`](docs/TRAINING-RESEARCH.md)).
104 +
105 +## 🗺 Roadmap
106 +
107 +- Image generation (Swift `StableDiffusion` / FLUX pipelines)
108 +- One-click "send to Zyquo Local"
109 +- lm-evaluation-harness integration for benchmark scorecards
110 +- DWQ/AWQ/GPTQ advanced quantization recipes
41 111
42 −## Documentation
112 +## 🤝 The Zyquo family
43 113
44 −- `docs/PLAN.md` — phase-by-phase execution plan and checkpoints
45 −- `docs/MLX-RESEARCH.md` — MLX framework ground truth (verified 2026-07-30)
46 −- `docs/TRAINING-RESEARCH.md` — fine-tuning on MLX, concretely
47 −- `docs/MODELS.md` — Hub API + live-verified curated catalog
48 −- `docs/BUILD.md` — the no-Xcode-IDE build recipe (incl. Metal toolchain)
114 +**Zyquo Local** (chat client) · **Zyquo MLX** (this foundry) · Zyquo Term · Zyquo Atlas
49 115
50 −## Data locations
116 +## 📄 License
51 117
52 −- Models: `~/Library/Application Support/ZyquoMLX/Models/`
53 −- Datasets: `~/Library/Application Support/ZyquoMLX/Datasets/`
54 −- Training runs: `~/Library/Application Support/ZyquoMLX/Runs/`
55 −- Python env: `~/Library/Application Support/ZyquoMLX/py/`
118 +[MIT](LICENSE) — © 2026 Simon-Pierre Boucher · contact@spboucher.ai
modified Support/Info.plist +1 −1
@@ -22,7 +22,7 @@
22 22 <key>CFBundlePackageType</key>
23 23 <string>APPL</string>
24 24 <key>CFBundleShortVersionString</key>
25 − <string>0.1.0</string>
25 + <string>1.0.0</string>
26 26 <key>CFBundleVersion</key>
27 27 <string>1</string>
28 28 <key>CFBundleIconFile</key>
added assets/icon/app-icon.png +0 −0

Binary file not shown.

added assets/screenshots/models-dark.png +0 −0

Binary file not shown.

added assets/screenshots/models-light.png +0 −0

Binary file not shown.

added assets/screenshots/playground-chat.png +0 −0

Binary file not shown.

added assets/screenshots/train-run.png +0 −0

Binary file not shown.