Upload folder using huggingface_hub

Browse files

Files changed (10) hide show

.gitattributes +7 -23
LICENSES.md +22 -0
README.md +181 -1
ace-step-1.5-turbo/README.md +213 -0
flux2-klein-4b-q4/README.md +130 -0
flux2-klein-4b/README.md +134 -0
shared/qwen3-4b-text-encoder-q4/README.md +130 -0
shared/qwen3-4b-text-encoder/README.md +133 -0
z-image-turbo-q4/README.md +130 -0
z-image-turbo/README.md +134 -0

.gitattributes CHANGED Viewed

@@ -1,35 +1,19 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
 *.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
 *.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
 *.gz filter=lfs diff=lfs merge=lfs -text
 *.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
 *.msgpack filter=lfs diff=lfs merge=lfs -text
 *.npy filter=lfs diff=lfs merge=lfs -text
 *.npz filter=lfs diff=lfs merge=lfs -text
 *.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
 *.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

+*.safetensors filter=lfs diff=lfs merge=lfs -text
 *.bin filter=lfs diff=lfs merge=lfs -text
 *.ckpt filter=lfs diff=lfs merge=lfs -text
 *.gz filter=lfs diff=lfs merge=lfs -text
 *.h5 filter=lfs diff=lfs merge=lfs -text
 *.msgpack filter=lfs diff=lfs merge=lfs -text
 *.npy filter=lfs diff=lfs merge=lfs -text
 *.npz filter=lfs diff=lfs merge=lfs -text
 *.onnx filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
 *.tar filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
+**/tokenizer/tokenizer.json filter=lfs diff=lfs merge=lfs -text
+**/tokenizer/vocab.json filter=lfs diff=lfs merge=lfs -text
+**/tokenizer/merges.txt filter=lfs diff=lfs merge=lfs -text
+**/lm_tokenizer/tokenizer.json filter=lfs diff=lfs merge=lfs -text
+**/lm_tokenizer/vocab.json filter=lfs diff=lfs merge=lfs -text
+**/lm_tokenizer/merges.txt filter=lfs diff=lfs merge=lfs -text

LICENSES.md ADDED Viewed

	@@ -0,0 +1,22 @@

+# Licences in this repository
+Each folder is a derivative of an upstream model and carries that model's licence.
+| folder                            | upstream                          | licence    |
+| --------------------------------- | --------------------------------- | ---------- |
+| `shared/qwen3-4b-text-encoder`    | inside the two image repos below  | Apache-2.0 |
+| `shared/qwen3-4b-text-encoder-q4` | inside the two image repos below  | Apache-2.0 |
+| `z-image-turbo`                   | Tongyi-MAI/Z-Image-Turbo          | Apache-2.0 |
+| `z-image-turbo-q4`                | Tongyi-MAI/Z-Image-Turbo          | Apache-2.0 |
+| `flux2-klein-4b`                  | black-forest-labs/FLUX.2-klein-4B | Apache-2.0 |
+| `flux2-klein-4b-q4`               | black-forest-labs/FLUX.2-klein-4B | Apache-2.0 |
+| `ace-step-1.5-turbo`              | ACE-Step/Ace-Step1.5              | MIT        |
+Apache-2.0: https://www.apache.org/licenses/LICENSE-2.0
+MIT: https://opensource.org/license/mit
+Conversion tooling and the model cards in this repository: MIT.
+The upstream cards state usage restrictions and responsible-use commitments that
+redistribution does not repeal. See in particular the out-of-scope use section of
+the FLUX.2 [klein] card: https://huggingface.co/black-forest-labs/FLUX.2-klein-4B

README.md CHANGED Viewed

@@ -1,5 +1,185 @@
 ---
 license: other
 license_name: mixed-apache-2.0-and-mit
-license_link: LICENSE
 ---

 ---
 license: other
 license_name: mixed-apache-2.0-and-mit
+license_link: https://huggingface.co/kruatech/studio-mlx/blob/main/LICENSES.md
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+- text-to-image
+- image-editing
+- text-to-music
+- quantized
 ---
+<div align="center">
+# studio-mlx
+**Image and music models converted for native MLX inference on Apple silicon**
+![MLX](https://img.shields.io/badge/MLX-0.32-1f6feb) ![platform](https://img.shields.io/badge/platform-Apple%20silicon-black) ![precision](https://img.shields.io/badge/precision-bf16%20and%204--bit-6f42c1) [![licence](https://img.shields.io/badge/licence-Apache--2.0%20and%20MIT-brightgreen)](https://huggingface.co/kruatech/studio-mlx/blob/main/LICENSES.md)
+</div>
+Three models and the text encoder the two image models share. Every folder is a self-contained bundle with its own card, so you download only what you need.
+Weights are not retrained. Tensor layouts were adapted for MLX and the 4-bit folders are quantized, so parameters are mathematically equivalent to upstream rather than byte-identical.
+## Quick start
+Pick one line. The image models need the shared encoder, the music model does not.
+```bash
+pip install "huggingface_hub[hf_xet]"
+# Z-Image-Turbo - 6.14 GiB
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "shared/qwen3-4b-text-encoder-q4/*" "z-image-turbo-q4/*"
+# FLUX.2 [klein] 4B - 4.79 GiB
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "shared/qwen3-4b-text-encoder-q4/*" "flux2-klein-4b-q4/*"
+# ACE-Step 1.5 Turbo - 9.38 GiB
+hf download kruatech/studio-mlx --local-dir bundles --include "ace-step-1.5-turbo/*"
+```
+The `-q4` folders sit at the top level rather than inside the bf16 ones, so an include pattern fetches one precision without dragging in the other.
+## What is inside
+| folder                                                               | what it does                                           | precision | size      | licence    |
+|----------------------------------------------------------------------|--------------------------------------------------------|-----------|-----------|------------|
+| [`shared/qwen3-4b-text-encoder`](shared/qwen3-4b-text-encoder)       | Shared text encoder for both image models              | `bf16`    | 7.51 GiB  | Apache-2.0 |
+| [`shared/qwen3-4b-text-encoder-q4`](shared/qwen3-4b-text-encoder-q4) | Shared text encoder for both image models              | `4-bit`   | 2.59 GiB  | Apache-2.0 |
+| [`z-image-turbo`](z-image-turbo)                                     | Text to image, 6B, 8 steps                             | `bf16`    | 11.62 GiB | Apache-2.0 |
+| [`z-image-turbo-q4`](z-image-turbo-q4)                               | Text to image, 6B, 8 steps                             | `4-bit`   | 3.55 GiB  | Apache-2.0 |
+| [`flux2-klein-4b`](flux2-klein-4b)                                   | Text to image and multi-reference editing, 4B, 4 steps | `bf16`    | 7.39 GiB  | Apache-2.0 |
+| [`flux2-klein-4b-q4`](flux2-klein-4b-q4)                             | Text to image and multi-reference editing, 4B, 4 steps | `4-bit`   | 2.20 GiB  | Apache-2.0 |
+| [`ace-step-1.5-turbo`](ace-step-1.5-turbo)                           | Text to music, 48 kHz stereo                           | `bf16`    | 9.38 GiB  | MIT        |
+## bf16 or 4-bit
+**Use the 4-bit folders.** Quantization is MLX affine: 4 bits per weight with a bf16 scale and bias for every group of 64, about 4.5 bits per weight and 28-30% of the bf16 size. Normalizations, modulations and the encoder's embedding table stay in bf16, and matrix multiplication still runs in bf16 - the gain is memory and load time, not integer arithmetic.
+|                                   | bf16      | 4-bit    |
+|-----------------------------------|-----------|----------|
+| Z-Image DiT                       | 11.46 GiB | 3.40 GiB |
+| klein DiT                         | 7.22 GiB  | 2.03 GiB |
+| shared encoder                    | 7.51 GiB  | 2.58 GiB |
+| klein 512 px, 4 steps, wall clock | 170 s     | 73 s     |
+Output quality was indistinguishable: the same prompt and seed gave two clean images that differ the way two seeds differ. The bf16 folders exist as the accuracy reference a port can be checked against.
+## Bundle layout
+```
+<folder>/
+├── manifest.json     SHA-256, byte sizes and tensor counts for every file
+├── config/           component configs copied from upstream
+├── tokenizer/        BPE plus chat_format.json, where applicable
+└── weights/          safetensors in MLX tensor layout
+```
+`manifest.json` records the quantization settings, so a loader rebuilds the exact layout without being told. Verify integrity before first use: the manifest carries SHA-256 per file, which catches corruption that size checks miss.
+`tokenizer/chat_format.json` holds the Qwen chat template already rendered into a prefix and a suffix for each pipeline, so a runtime needs no Jinja at all.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licences
+Derivatives of three upstream models under two licences. Each folder carries the licence of its upstream model.
+| folder                            | upstream                                                                                      | licence                                                   |
+|-----------------------------------|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------|
+| `shared/qwen3-4b-text-encoder`    | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
+| `shared/qwen3-4b-text-encoder-q4` | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
+| `z-image-turbo`                   | [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)                   | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
+| `z-image-turbo-q4`                | [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)                   | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
+| `flux2-klein-4b`                  | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
+| `flux2-klein-4b-q4`               | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
+| `ace-step-1.5-turbo`              | [ACE-Step/Ace-Step1.5](https://huggingface.co/ACE-Step/Ace-Step1.5)                           | [MIT](https://opensource.org/license/mit)                 |
+The shared text encoder is redistributed from inside the two image repositories, both Apache-2.0. Conversion tooling and these cards: MIT.
+The upstream cards state usage restrictions and responsible-use commitments that redistribution does not repeal. See in particular the out-of-scope use section of the FLUX.2 [klein] card.

ace-step-1.5-turbo/README.md ADDED Viewed

	@@ -0,0 +1,213 @@

+---
+license: mit
+base_model: ACE-Step/Ace-Step1.5
+tags:
+  - music-generation
+  - text-to-music
+  - mlx
+  - mlx-swift
+  - apple-silicon
+  - macos
+library_name: mlx
+pipeline_tag: text-to-audio
+---
+# ACE-Step 1.5 Turbo for native MLX inference on Apple Silicon
+Converted upstream weights for a native macOS implementation of ACE-Step 1.5.
+The inference path runs entirely through Swift and MLX — no Python, PyTorch,
+Transformers, Diffusers, subprocess or local server.
+Weights are not retrained and not quantized. Tensor layouts were adapted for
+MLX and VAE `weight_norm` was folded during conversion, so parameters are
+mathematically equivalent to upstream rather than byte-identical.
+> This folder is part of the combined `kruatech/studio-mlx` repository.
+> The status note below applies to ACE-Step only: the Swift runtime for the
+> image models in this repository is implemented, the one for ACE-Step is not.
+## Status
+The Swift runtime is not published yet and will live in a separate repository,
+so this repository currently provides the model bundle only. To try ACE-Step 1.5
+today, use the upstream repository.
+## Supported tasks
+All four turbo task types work:
+| task | what it does |
+|---|---|
+| `text2music` | generate from a text description and lyrics |
+| `repaint` | regenerate a time range, keep the rest bit-exact ¹ |
+| `cover` | follow an existing track's structure via 5 Hz FSQ codes |
+| `cover-nofsq` | same, through the full 25 Hz latent — stays closer to the source |
+¹ Outside the range the original PCM is spliced back, so it matches bit for bit
+except in the crossfade windows at the boundaries (0.025 s each by default).
+Also implemented: CFG with APG guidance, DCW wavelet correction (on by default,
+as upstream), tiled VAE encode and decode, retake variations, velocity
+stabilisation, second-order Heun sampler, LM forward pass.
+Not implemented: generating audio codes from text end to end (the LM's
+217204-entry BPE tokenizer is not ported), constrained metadata decoding,
+batches larger than one. Metadata is supplied explicitly.
+Not applicable to turbo: `use_adg` and flow-edit morphing need a base model;
+`extract`, `lego` and `complete` are base-only tasks.
+## Pipeline
+```
+prompt ──▶ Qwen3-Embedding-0.6B ──┐
+lyrics ──▶ Qwen3-Embedding-0.6B ──┼──▶ CondEncoder ──▶ encoder_hidden_states
+reference latent ─────────────────┘
+noise [1, T, 64] ──▶ DiT, 24 layers, 8 steps ──▶ latent ──▶ VAE ──▶ 48 kHz stereo
+```
+`T` is latent frames at 25 Hz: 30 s of audio is 750 frames. The VAE upsamples by
+1920 per frame.
+## Files
+Required for `text2music`, `repaint`, `cover` — 6.34 GB:
+| path | size | contents |
+|---|---|---|
+| `weights/dit.safetensors` | 4.79 GB | DiT, FSQ quantizer, detokenizer, attention pooler — 677 tensors, BF16 |
+| `weights/text_encoder.safetensors` | 1.19 GB | Qwen3-Embedding-0.6B, 310 tensors, BF16 |
+| `weights/vae.safetensors` | 337 MB | AutoencoderOobleck, 291 tensors: 146 encoder + 145 decoder |
+| `weights/silence.bin` | 3.8 MB | silence latent, F32 `[15000, 64]` in NLC |
+| `config/dit.json`, `config/text.json` | 4 KB | model configs |
+| `tokenizer/` | 14 MB | Qwen3-Embedding BPE |
+| `manifest.json` | 3 KB | SHA-256, sizes and tensor counts |
+Optional, 3.71 GB: `optional/lm.safetensors` and `optional/lm_tokenizer/` hold
+the 1.7B LM. `text2music` never loads them, and cover works without them —
+audio is encoded and tokenised directly. The LM is only needed to produce codes
+from a text description instead of a reference track.
+Verify integrity before first use: `manifest.json` carries SHA-256 for every
+file, which catches corruption that size and header checks miss.
+## Tensor layout
+MLX convolutions expect channels last, PyTorch expects channels first, so
+convolution weights are permuted during conversion:
+| kind | PyTorch | MLX |
+|---|---|---|
+| `Conv1d` | `(out, in, k)` | `(out, k, in)` |
+| `ConvTranspose1d` | `(in, out, k)` | `(out, k, in)` |
+| Snake `alpha`, `beta` | `(1, C, 1)` | `(1, 1, C)` |
+| `Linear` | `(out, in)` | unchanged |
+`weight_norm` pairs are folded into single tensors: `w = v · (g / ‖v‖)`,
+computed in F32 with an F64 accumulator and rounded once. This removes 74
+tensors from the VAE.
+## Memory
+Peak MLX active memory per stage, F32, 60 s of audio with CFG 3.0:
+| stage | peak active |
+|---|---|
+| text encoder | 2.1 GB |
+| CondEncoder | 2.8 GB |
+| DiT | 7.2 GB |
+| VAE decoder, tiled | 4.1 GB |
+Stages run sequentially and release their weights, so the figures do not add
+up. DiT sets the ceiling; with the buffer cache the working set is about 9.2 GB.
+**16 GB is the tested minimum.** An M1 Pro with 16 GB ran all four tasks
+without swap growth. 8 GB is not expected to fit.
+The VAE must be tiled — a single-pass 30 s decode drove the MLX buffer cache to
+25 GB. With tiling the cache stayed under 400 MB across all tested lengths, 10 s
+to 180 s. Overlaps of 16, 32 and 64 latent frames each produced output identical
+to a single pass.
+DiT must run in F32. BF16 halves its memory but fails accuracy at
+`rel_max 1.45e-01`.
+## Performance
+Warm cache, release build, 8 diffusion steps, batch 1, F32. RTF is generation
+time over output duration.
+**M1 Pro, 16 GB** — 10-core CPU, 16-core GPU, macOS 26.5, Swift 6.3.2:
+```
+mode                 wall      dit   s/step      vae   peak MB     RTF
+30 s, guidance 1.0    8.6s    3.65s    0.46s    3.78s     6602   0.287
+60 s, guidance 1.0   15.6s    6.81s    0.85s    7.46s     6806   0.260
+30 s, guidance 3.0   11.6s    6.91s    0.86s    3.51s     6761   0.387
+60 s, guidance 3.0   22.1s   13.38s    1.67s    7.40s     7180   0.368
+30 s, Heun sampler   16.7s   11.93s    1.49s    3.55s     6761   0.557
+```
+**M1 Max, 32 GB** — 10-core CPU, 24-core GPU, macOS 26.5, Swift 6.3.3, CFG 3.0:
+```
+30 s:  text 0.15s   cond 0.19s   dit 4.47s   vae 2.28s   ·   7.69s wall
+60 s:  dit 8.77s (1.10 s/step)                          ·   RTF 0.146
+```
+The M1 Max is about 1.5× faster per diffusion step, tracking GPU core count
+rather than memory. Peak memory is the same on both.
+CFG doubles the batch and roughly doubles diffusion time. Heun doubles model
+evaluations per step. A first run after process start is several times slower
+while 6.3 GB of weights come off disk — measure the second run.
+## Verification
+Every module was compared against the upstream reference on fixed inputs in
+F32. The metric is `rel_max = max_abs / std(reference)`, threshold `1e-03`:
+| module | rel_max | reference |
+|---|---|---|
+| tokenization | bit-exact | `transformers` |
+| text encoder, 28 layers | 3.39e-05 | `transformers` |
+| CondEncoder | 5.98e-04 | `transformers` |
+| DiT, 24 layers | 4.35e-05 | `diffusers` |
+| VAE encoder | 5.38e-04 | `diffusers` |
+| VAE decoder | cosine 1.000000 | `diffusers` |
+| FSQ | 3.40e-07 | `vector_quantize_pytorch` ¹ |
+| detokenizer | 1.15e-05 | `transformers` |
+| audio tokenizer | 1.31e-05 | `transformers` ² |
+| LM, 28 layers | 2.48e-04 | `transformers` ³ |
+| CFG / APG | 4.95e-05 | independent MLX implementation ⁴ |
+¹ Codebook matched exactly on all 64000 entries.
+² All 50 indices matched exactly.
+³ argmax matched at all 50 positions.
+⁴ APG has no PyTorch reference upstream; validated on identical noise.
+Reference versions: torch 2.13.0, transformers 5.14.1, diffusers 0.39.0,
+mlx 0.32.0.
+Verify the VAE against an F32 weight file, not the BF16 one shipped here.
+`weight_norm` folding produces new values, and storing them in BF16 quantises
+them: `rel_max 5.11e-02` against BF16 versus `4.78e-05` against F32. For
+inference BF16 is fine — median signal-to-error through encode and decode is
+49.7 dB.
+## Limitations
+Seeds are not compatible with the upstream pipeline, which uses
+`torch.Generator`. The same prompt gives comparable music, never the same file.
+Minimum length is 5.12 s. Step count is fixed at 8; this is the turbo model.
+## Licenses
+MIT, same as upstream.
+- DiT, VAE, LM: converted from
+  [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5), MIT.
+- Text encoder and tokenizer: Qwen3-Embedding-0.6B, redistributed unchanged.
+- Conversion tooling and this card: MIT.

flux2-klein-4b-q4/README.md ADDED Viewed

	@@ -0,0 +1,130 @@

+---
+license: apache-2.0
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+base_model:
+- black-forest-labs/FLUX.2-klein-4B
+---
+<div align="center">
+# FLUX.2 [klein] 4B for MLX, 4-bit
+**Text to image and multi-reference editing, 4B, 4 steps**
+![precision](https://img.shields.io/badge/precision-4--bit-6f42c1) ![size](https://img.shields.io/badge/size-2.20%20GiB-1f6feb) [![licence](https://img.shields.io/badge/licence-Apache--2.0-brightgreen)](https://www.apache.org/licenses/LICENSE-2.0) [![part of](https://img.shields.io/badge/part%20of-studio--mlx-black)](https://huggingface.co/kruatech/studio-mlx)
+</div>
+4-bit version of FLUX.2 [klein] 4B. Everything in the bf16 card applies.
+Converted from [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) for native MLX inference on Apple silicon.
+## Download
+Also download `shared/qwen3-4b-text-encoder-q4`.
+```bash
+pip install "huggingface_hub[hf_xet]"
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "shared/qwen3-4b-text-encoder-q4/*" "flux2-klein-4b-q4/*"
+```
+## Files
+| component   | class                   | precision       | tensors | size     |
+|-------------|-------------------------|-----------------|---------|----------|
+| transformer | Flux2Transformer2DModel | 4-bit, group 64 | 381     | 2.03 GiB |
+| vae         | AutoencoderKLFlux2      | keep            | 251     | 160 MiB  |
+Folder total: **2.20 GiB**. `manifest.json` carries SHA-256, byte sizes and tensor counts for every file.
+## How this model works in MLX
+- 106 linear layers quantized. The VAE is not quantized.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licence
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), the licence of the upstream model. Conversion tooling and this card: MIT. The upstream card states usage restrictions that redistribution does not repeal.

flux2-klein-4b/README.md ADDED Viewed

	@@ -0,0 +1,134 @@

+---
+license: apache-2.0
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+base_model:
+- black-forest-labs/FLUX.2-klein-4B
+---
+<div align="center">
+# FLUX.2 [klein] 4B for MLX, bf16
+**Text to image and multi-reference editing, 4B, 4 steps**
+![precision](https://img.shields.io/badge/precision-bf16-6f42c1) ![size](https://img.shields.io/badge/size-7.39%20GiB-1f6feb) [![licence](https://img.shields.io/badge/licence-Apache--2.0-brightgreen)](https://www.apache.org/licenses/LICENSE-2.0) [![part of](https://img.shields.io/badge/part%20of-studio--mlx-black)](https://huggingface.co/kruatech/studio-mlx)
+</div>
+4B rectified flow transformer, text to image and multi-reference editing, 4 steps, distilled so guidance is not applied.
+Converted from [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) for native MLX inference on Apple silicon.
+## Download
+Also download `shared/qwen3-4b-text-encoder`.
+```bash
+pip install "huggingface_hub[hf_xet]"
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "shared/qwen3-4b-text-encoder/*" "flux2-klein-4b/*"
+```
+## Files
+| component   | class                   | precision | tensors | size     |
+|-------------|-------------------------|-----------|---------|----------|
+| transformer | Flux2Transformer2DModel | keep      | 169     | 7.22 GiB |
+| vae         | AutoencoderKLFlux2      | keep      | 251     | 160 MiB  |
+Folder total: **7.39 GiB**. `manifest.json` carries SHA-256, byte sizes and tensor counts for every file.
+## How this model works in MLX
+- 5 double-stream blocks with separate text and image modulation, then 20 single-stream blocks where QKV and the MLP share one fused projection.
+- Rotary embedding over four axes, 32 each, theta 2000.
+- No `scaling_factor`: latents are patchified 2x2 into 128 channels and normalized with the VAE's BatchNorm running statistics, which are in `weights/vae.safetensors`.
+- Sigmas use the exponential dynamic shift with mu from the upstream empirical formula.
+- Reference-image editing needs no KV cache: reference tokens and their ids are appended to the sequence and the prediction is sliced back. Each 1024 px reference adds 4096 tokens, which roughly doubles the cost of a step.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licence
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), the licence of the upstream model. Conversion tooling and this card: MIT. The upstream card states usage restrictions that redistribution does not repeal.

shared/qwen3-4b-text-encoder-q4/README.md ADDED Viewed

	@@ -0,0 +1,130 @@

+---
+license: apache-2.0
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+base_model:
+- black-forest-labs/FLUX.2-klein-4B
+---
+<div align="center">
+# Qwen3-4B text encoder for MLX, 4-bit
+**Shared text encoder for both image models**
+![precision](https://img.shields.io/badge/precision-4--bit-6f42c1) ![size](https://img.shields.io/badge/size-2.59%20GiB-1f6feb) [![licence](https://img.shields.io/badge/licence-Apache--2.0-brightgreen)](https://www.apache.org/licenses/LICENSE-2.0) [![part of](https://img.shields.io/badge/part%20of-studio--mlx-black)](https://huggingface.co/kruatech/studio-mlx)
+</div>
+4-bit version of the shared text encoder. Everything in the bf16 card applies.
+Converted from [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) for native MLX inference on Apple silicon.
+## Download
+Pair it with `z-image-turbo-q4` or `flux2-klein-4b-q4`.
+```bash
+pip install "huggingface_hub[hf_xet]"
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "shared/qwen3-4b-text-encoder-q4/*"
+```
+## Files
+| component    | class            | precision       | tensors | size     |
+|--------------|------------------|-----------------|---------|----------|
+| text_encoder | Qwen3ForCausalLM | 4-bit, group 64 | 877     | 2.58 GiB |
+Folder total: **2.59 GiB**. `manifest.json` carries SHA-256, byte sizes and tensor counts for every file.
+## How this model works in MLX
+- The embedding table is left in bf16 on purpose: quantizing it moved the encoder output by 3e-01 in testing, which is not worth 0.5 GiB.
+- 245 linear layers are quantized, 4 bits with a bf16 scale and bias per group of 64.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licence
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), the licence of the upstream model. Conversion tooling and this card: MIT. The upstream card states usage restrictions that redistribution does not repeal.

shared/qwen3-4b-text-encoder/README.md ADDED Viewed

	@@ -0,0 +1,133 @@

+---
+license: apache-2.0
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+base_model:
+- black-forest-labs/FLUX.2-klein-4B
+---
+<div align="center">
+# Qwen3-4B text encoder for MLX, bf16
+**Shared text encoder for both image models**
+![precision](https://img.shields.io/badge/precision-bf16-6f42c1) ![size](https://img.shields.io/badge/size-7.51%20GiB-1f6feb) [![licence](https://img.shields.io/badge/licence-Apache--2.0-brightgreen)](https://www.apache.org/licenses/LICENSE-2.0) [![part of](https://img.shields.io/badge/part%20of-studio--mlx-black)](https://huggingface.co/kruatech/studio-mlx)
+</div>
+The text encoder both image models in this repository use. It is the Qwen3-4B encoder shipped inside the FLUX.2 [klein] and Z-Image-Turbo repositories; the two copies are identical except for the MLP of layer 35, which no pipeline reads.
+Converted from [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) for native MLX inference on Apple silicon.
+## Download
+Pair it with `z-image-turbo` or `flux2-klein-4b`. On its own it generates nothing.
+```bash
+pip install "huggingface_hub[hf_xet]"
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "shared/qwen3-4b-text-encoder/*"
+```
+## Files
+| component    | class            | precision | tensors | size     |
+|--------------|------------------|-----------|---------|----------|
+| text_encoder | Qwen3ForCausalLM | keep      | 398     | 7.51 GiB |
+Folder total: **7.51 GiB**. `manifest.json` carries SHA-256, byte sizes and tensor counts for every file.
+## How this model works in MLX
+- Z-Image consumes `hidden_states[-2]`, the output of layer n-1, so 35 of 36 layers run.
+- klein concatenates `hidden_states[9]`, `[18]` and `[27]` into 7680 features, so 27 of 36 layers run.
+- Neither pipeline touches the last layer, so a loader can skip it entirely.
+- Padding matters for klein and not for Z-Image: Z-Image drops padded positions with a mask afterwards, while klein feeds all 512 tokens to the transformer, so the attention mask has to be applied.
+- `tokenizer/chat_format.json` holds the Qwen chat template already rendered into a prefix and a suffix for each pipeline, so a runtime needs no Jinja. klein renders with thinking disabled, which still injects an empty `<think></think>` block.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licence
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), the licence of the upstream model. Conversion tooling and this card: MIT. The upstream card states usage restrictions that redistribution does not repeal.

z-image-turbo-q4/README.md ADDED Viewed

	@@ -0,0 +1,130 @@

+---
+license: apache-2.0
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+base_model:
+- Tongyi-MAI/Z-Image-Turbo
+---
+<div align="center">
+# Z-Image-Turbo for MLX, 4-bit
+**Text to image, 6B, 8 steps**
+![precision](https://img.shields.io/badge/precision-4--bit-6f42c1) ![size](https://img.shields.io/badge/size-3.55%20GiB-1f6feb) [![licence](https://img.shields.io/badge/licence-Apache--2.0-brightgreen)](https://www.apache.org/licenses/LICENSE-2.0) [![part of](https://img.shields.io/badge/part%20of-studio--mlx-black)](https://huggingface.co/kruatech/studio-mlx)
+</div>
+4-bit version of Z-Image-Turbo. Everything in the bf16 card applies.
+Converted from [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) for native MLX inference on Apple silicon.
+## Download
+Also download `shared/qwen3-4b-text-encoder-q4`.
+```bash
+pip install "huggingface_hub[hf_xet]"
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "shared/qwen3-4b-text-encoder-q4/*" "z-image-turbo-q4/*"
+```
+## Files
+| component   | class                    | precision       | tensors | size     |
+|-------------|--------------------------|-----------------|---------|----------|
+| transformer | ZImageTransformer2DModel | 4-bit, group 64 | 999     | 3.40 GiB |
+| vae         | AutoencoderKL            | keep            | 244     | 160 MiB  |
+Folder total: **3.55 GiB**. `manifest.json` carries SHA-256, byte sizes and tensor counts for every file.
+## How this model works in MLX
+- 239 linear layers quantized; normalizations, modulations and timestep MLPs stay in bf16. The VAE is not quantized - at 160 MiB there is nothing to gain.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licence
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), the licence of the upstream model. Conversion tooling and this card: MIT. The upstream card states usage restrictions that redistribution does not repeal.

z-image-turbo/README.md ADDED Viewed

	@@ -0,0 +1,134 @@

+---
+license: apache-2.0
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+base_model:
+- Tongyi-MAI/Z-Image-Turbo
+---
+<div align="center">
+# Z-Image-Turbo for MLX, bf16
+**Text to image, 6B, 8 steps**
+![precision](https://img.shields.io/badge/precision-bf16-6f42c1) ![size](https://img.shields.io/badge/size-11.62%20GiB-1f6feb) [![licence](https://img.shields.io/badge/licence-Apache--2.0-brightgreen)](https://www.apache.org/licenses/LICENSE-2.0) [![part of](https://img.shields.io/badge/part%20of-studio--mlx-black)](https://huggingface.co/kruatech/studio-mlx)
+</div>
+6B single-stream DiT (S3-DiT) plus the flux-dev VAE, text to image, 8 steps, no CFG.
+Converted from [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) for native MLX inference on Apple silicon.
+## Download
+Also download `shared/qwen3-4b-text-encoder`. This folder has no `tokenizer/`: the tokenizer lives with the encoder, and without it a prompt cannot be built.
+```bash
+pip install "huggingface_hub[hf_xet]"
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "shared/qwen3-4b-text-encoder/*" "z-image-turbo/*"
+```
+## Files
+| component   | class                    | precision | tensors | size      |
+|-------------|--------------------------|-----------|---------|-----------|
+| transformer | ZImageTransformer2DModel | bf16      | 521     | 11.46 GiB |
+| vae         | AutoencoderKL            | keep      | 244     | 160 MiB   |
+Folder total: **11.62 GiB**. `manifest.json` carries SHA-256, byte sizes and tensor counts for every file.
+## How this model works in MLX
+- 30 main layers, 2 noise-refiner and 2 context-refiner layers, dim 3840, 30 heads.
+- Rotary embedding over three axes with dims 32/48/48 and theta 256, applied to adjacent pairs rather than split halves.
+- Image and caption tokens are padded to a multiple of 32 with learned pad tokens, and the sequence is `[image, caption]`.
+- The scheduler uses the static shift of 3.0 from `scheduler_config.json`, and the prediction is negated before the Euler step.
+- Latents scale by `1/0.3611` and shift by `0.1159` before decoding.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licence
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), the licence of the upstream model. Conversion tooling and this card: MIT. The upstream card states usage restrictions that redistribution does not repeal.