Unofficial MLX port of Cloudflare's Clairic-flash (9.65B) and Clairic (27.8B) open-weight extraction models.
This repository contains the clairic_mlx inference package only. It does not re-host model weights. Weights are downloaded from Cloudflare at runtime or when you run convert, and they are not redistributed here.
Status: Text input verified (33/34). Image and PDF input is currently broken, fix in progress. Use the official PyTorch path for images and PDFs.
Clairic is built for structured extraction from text, images and PDFs: typed fields, confidence scores and character spans. Plain mlx-lm cannot load the custom head, which is why this port exists.
The measurements below are for Clairic-flash 9B. The same package can load the 27B Clairic model, which was not benched here.
This is an unofficial port. All credit for Clairic goes to Cloudflare and the Workers AI team.
The Qwen3.5 and Qwen3.8 backbones are from the Qwen team, also under Apache-2.0.
Apache License 2.0. See LICENSE and NOTICE.
The official Clairic weights, which this port downloads from Cloudflare and does not redistribute, are also Apache-2.0.
Files under third_party/cloudflare/ are copied from the Clairic release so tests can compare this port with the official PyTorch head. They remain Apache-2.0, Copyright Cloudflare, Inc.
Needs an Apple Silicon Mac and Python 3.11 or newer. An M5 Pro with 64 GB is enough for Clairic-flash in bfloat16, and for the 27B Clairic model in 4-bit.
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
Download the official snapshot yourself. Do not commit it.
pip install -U huggingface_hub
hf download Cloudflare/clairic-flash --local-dir "$HOME/models/clairic-flash"
For the 27B model, download Cloudflare/clairic instead. On 64 GB, run that model in 4-bit. Bfloat16 is about 56 GB of weights before activations.
Write a 4-bit MLX checkpoint (still local, still not uploaded). The backbone is quantized; the head stays float32:
python -m clairic_mlx.cli convert \
--model "$HOME/models/clairic-flash" \
--out "$HOME/models/clairic-flash-mlx-4bit" \
--bits 4
Extract from text with the CLI:
python -m clairic_mlx.cli extract \
--model "$HOME/models/clairic-flash-mlx-4bit" \
--state "$(cat examples/receipt.txt)" \
--fields examples/receipt_fields.json
You can also pass --quant 4 on the official snapshot to quantize the backbone while it loads, without writing a converted directory.
From Python:
from clairic_mlx import load
extractor = load("/path/to/clairic-flash", quant_bits=4)
print(extractor.extract(
"Invoice from Northwind Supply. Issued 2026-09-02. Total: $1080.00.",
{
"vendor": {"type": "text", "instructions": "The invoice vendor."},
"total": {"type": "number", "decimals": 2},
"issued": {"type": "date"},
},
))
PDFs need pip install 'clairic-mlx[pdf]'. Image and PDF input is wired in the API, but quality is currently broken (see Status above). Use Cloudflare's official PyTorch path for those inputs until the vision tower is fixed.
Without a snapshot, python -m clairic_mlx.cli demo and python examples/extract_receipt.py run a tiny random model so the pipeline can be checked. Those values are not extractions.
Independent local measurements from November 18, 2026. Speed is backbone greedy generate, 256 new tokens, thinking off, median of 3 timed runs after 1 warmup. A background inference app was paused for these runs at the owner's request.
The package in this repo is commit 5e7db582b1d442b4bcbe582fd8bb701c9773ed1d (tarball sha256 490f17dc8e3d19c6fe3308ebd268eeeebf344f7c6caccc287919736da915760c), the revision used for the pass 3 Mac mini run. mlx 0.32.4. Official Clairic-flash weights, downloaded from Cloudflare, not redistributed.
| Backend | Context | Prompt tok/s | Gen tok/s | TTFT |
|---|---|---|---|---|
| MLX BF16 | 512 | 1295 | 15.2 | 0.40 s |
| MLX BF16 | 4K | 1182 | 15.3 | 3.47 s |
| MLX BF16 | 16K | 996 | 14.5 | 16.4 s |
| MLX 4-bit | 512 | 1232 | 40.5 | 0.42 s |
| MLX 4-bit | 4K | 1090 | 38.3 | 3.76 s |
| MLX 4-bit | 16K | 1131 | 36.0 | 14.5 s |
| PyTorch BF16 (MPS) | 512 | 796 | 12.7 | 0.64 s |
| PyTorch BF16 (MPS) | 4K | 791 | 11.9 | 5.18 s |
| PyTorch BF16 (MPS) | 16K | 637 | 10.3 | 25.7 s |
Load and memory:
| Backend | Load | Memory |
|---|---|---|
| MLX BF16 | 3.1 s | 17.8 GB Metal peak |
| MLX 4-bit | 3.2 s | 7.18 GB Metal peak at load; 29.0 GB after the 16K run |
MLX 4-bit convert output (6.5 GB) |
1.1 s | 6.3 GB Metal peak |
| PyTorch BF16 (MPS) | 7.0 s | 28.8 GB peak |
Extraction, on synthetic documents with known ground truth (a receipt image, an invoice PDF and a form image):
pytest on Metal: 19/19 passed.
Cloudflare's published scores (fresh text 328/336, mixed-input 213/226, synthetic receipt fields 576/576) are lab claims. They were not reproduced here. The 34-field check is a small local suite, not that eval.
Full logs, the speed table and the raw outputs are in the benchmark dataset: pratikgx/clairic-flash-m5-pro-mac-mini-bench. The write-up is in Local AI field notes.
pip install -e ".[dev]"
pytest
The unit tests run without downloading the 9B weights. On this Mac they passed 19/19 on Metal.
Verified on a 64GB M5 Pro Mac mini, against official Clairic-flash weights:
convert --bits 4 wrote a 6.5 GB backbone that loaded and extracted from sample text with no error.Not working yet:
images= and documents=, but the outputs do not match ground truth or the official PyTorch answers. Use the official PyTorch path for those inputs.Also not claimed:
Cloudflare/clairic