<!--
  README.md
  Zyquo MLX

  Author: Simon-Pierre Boucher
  Mail: contact@spboucher.ai
-->

<div align="center">

<img src="assets/icon/app-icon.png" width="128" alt="Zyquo MLX icon">

# Zyquo MLX

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

[![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)
[![macOS 14+](https://img.shields.io/badge/macOS-14%2B-334155)](https://github.com/spboucher-ai/zyquo-mlx)
[![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-arm64-334155)](https://github.com/spboucher-ai/zyquo-mlx)
[![Swift](https://img.shields.io/badge/Swift-SwiftUI-EA6A2B)](Package.swift)
[![MLX](https://img.shields.io/badge/Apple-MLX-EA6A2B)](https://github.com/ml-explore/mlx)
[![License: MIT](https://img.shields.io/badge/license-MIT-334155)](LICENSE)
[![Downloads](https://img.shields.io/github/downloads/spboucher-ai/zyquo-mlx/total?color=EA6A2B)](https://github.com/spboucher-ai/zyquo-mlx/releases)
[![Signed & Notarized](https://img.shields.io/badge/Signed%20%26%20Notarized-Developer%20ID-2FA36B)](docs/BUILD.md)

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

</div>

---

## ✨ 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](assets/screenshots/models-light.png) | ![Models, dark](assets/screenshots/models-dark.png) |

| Training run — live loss curves, console, checkpoints | Playground — streaming chat with live stats |
|---|---|
| ![Training run](assets/screenshots/train-run.png) | ![Playground](assets/screenshots/playground-chat.png) |

## ⚡ 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`](docs/VERIFICATION.md).

## 📦 Installation

**[⬇️ Download Zyquo MLX.dmg](https://github.com/spboucher-ai/zyquo-mlx/releases/latest/download/ZyquoMLX.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`](https://docs.astral.sh/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

```
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](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)).

## 🗺 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](LICENSE) — © 2026 Simon-Pierre Boucher · contact@spboucher.ai