Instructions to use Xylolabs/clairic-flash-MLX-8bit with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- MLX
How to use Xylolabs/clairic-flash-MLX-8bit with MLX:
# Make sure mlx-lm is installed # pip install --upgrade mlx-lm # Generate text with mlx-lm from mlx_lm import load, generate model, tokenizer = load("Xylolabs/clairic-flash-MLX-8bit") prompt = "Write a story about Einstein" messages = [{"role": "user", "content": prompt}] prompt = tokenizer.apply_chat_template( messages, add_generation_prompt=True ) text = generate(model, tokenizer, prompt=prompt, verbose=True) - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- LM Studio
- Pi
How to use Xylolabs/clairic-flash-MLX-8bit with Pi:
Start the MLX server
# Install MLX LM: uv tool install mlx-lm # Start a local OpenAI-compatible server: mlx_lm.server --model "Xylolabs/clairic-flash-MLX-8bit"
Configure the model in Pi
# Install Pi: npm install -g @earendil-works/pi-coding-agent # Add to ~/.pi/agent/models.json: { "providers": { "mlx-lm": { "baseUrl": "http://localhost:8080/v1", "api": "openai-completions", "apiKey": "none", "models": [ { "id": "Xylolabs/clairic-flash-MLX-8bit" } ] } } }Run Pi
# Start Pi in your project directory: pi
- MLX LM
How to use Xylolabs/clairic-flash-MLX-8bit with MLX LM:
Generate or start a chat session
# Install MLX LM uv tool install mlx-lm # Interactive chat REPL mlx_lm.chat --model "Xylolabs/clairic-flash-MLX-8bit"
Run an OpenAI-compatible server
# Install MLX LM uv tool install mlx-lm # Start the server mlx_lm.server --model "Xylolabs/clairic-flash-MLX-8bit" # Calling the OpenAI-compatible server with curl curl -X POST "http://localhost:8080/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Xylolabs/clairic-flash-MLX-8bit", "messages": [ {"role": "user", "content": "Hello"} ] }' - Hermes Agent
How to use Xylolabs/clairic-flash-MLX-8bit with Hermes Agent:
Start the MLX server
# Install MLX LM: uv tool install mlx-lm # Start a local OpenAI-compatible server: mlx_lm.server --model "Xylolabs/clairic-flash-MLX-8bit"
Configure Hermes
# Install Hermes: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash hermes setup # Point Hermes at the local server: hermes config set model.provider custom hermes config set model.base_url http://127.0.0.1:8080/v1 hermes config set model.default Xylolabs/clairic-flash-MLX-8bit
Run Hermes
hermes
- Atomic Chat
- OpenClaw
How to use Xylolabs/clairic-flash-MLX-8bit with OpenClaw:
Start the MLX server
# Install MLX LM: uv tool install mlx-lm # Start a local OpenAI-compatible server: mlx_lm.server --model "Xylolabs/clairic-flash-MLX-8bit"
Configure OpenClaw
# Install OpenClaw: npm install -g openclaw@latest # Register the local server and set it as the default model: openclaw onboard --non-interactive --mode local \ --auth-choice custom-api-key \ --custom-base-url http://127.0.0.1:8080/v1 \ --custom-model-id "Xylolabs/clairic-flash-MLX-8bit" \ --custom-provider-id mlx-lm \ --custom-compatibility openai \ --custom-text-input \ --accept-risk \ --skip-health
Run OpenClaw
openclaw agent --local --agent main --message "Hello from Hugging Face"
The language model of Cloudflare/clairic-flash (9B, Qwen3.5 architecture) converted to 8-bit MLX for mlx-lm; the vision tower and the scoring head of the original are not included.
How to run
pip install mlx-lm==0.32.2
mlx_lm.generate --model Xylolabs/clairic-flash-MLX-8bit --prompt 'Summarize the invoice: Northwind Supply, 2026-09-02, pens and paper, total $1080.00.'
mlx_lm.chat --model Xylolabs/clairic-flash-MLX-8bit
Accuracy
Mean KL divergence from BF16 (lower is better) and top-1 agreement with BF16.
| Quant | Size | WikiText-2 KL | top-1 | Chat KL | top-1 | Held-out KL | top-1 |
|---|---|---|---|---|---|---|---|
| MLX 8-bit | 9.51 GB | 0.001655 | 98.848% | 0.004075 | 98.461% | 0.000569 | 99.039% |
Which file for your hardware
Macs only (MLX runs on Apple silicon; memory options as Apple lists them for the Mac Studio, M5 Max 36, 48, 64 and 128 GB, M5 Ultra 96, 256 and 512 GB, and the 14-inch MacBook Pro M5 Max, checked 2026-11-22). The GPU may use about 75% of unified memory by default; sudo sysctl iogpu.wired_limit_mb=<MB> raises that limit (it resets at reboot). Fit rule: file + KV cache at the stated context + about 2 GB must fit in the GPU limit; sizes in GB (10^9 bytes); context is the longest that fits at the default limit, at least 32K. KV cache 33 KB per token (8 full-attention layers x 4 KV heads x 256 x 2 x 2 bytes; the other 24 layers keep a fixed 50 MB state). No MLX speed has been measured on these Macs.
| Hardware | Memory | Recommended file (ours only) | Context that fits | Notes |
|---|---|---|---|---|
| Mac Studio M5 Max (also MacBook Pro 14-inch M5 Max, 32-core GPU) | 36 GB unified | Xylolabs/clairic-flash-MLX-8bit (8-bit, 9.53 GB) |
256K (model maximum) | Fits at the default GPU limit (75% of memory). |
| Mac Studio M5 Max (also MacBook Pro 14-inch M5 Max, 40-core GPU) | 48 GB unified | Xylolabs/clairic-flash-MLX-8bit (8-bit, 9.53 GB) |
256K (model maximum) | Fits at the default GPU limit (75% of memory). |
| Mac Studio M5 Max (also MacBook Pro 14-inch M5 Max, 40-core GPU) | 64 GB unified | Xylolabs/clairic-flash-MLX-8bit (8-bit, 9.53 GB) |
256K (model maximum) | Fits at the default GPU limit (75% of memory). |
| Mac Studio M5 Ultra | 96 GB unified | Xylolabs/clairic-flash-MLX-8bit (8-bit, 9.53 GB) |
256K (model maximum) | Fits at the default GPU limit (75% of memory). |
| Mac Studio M5 Max, 40-core GPU (also MacBook Pro 14-inch) | 128 GB unified | Xylolabs/clairic-flash-MLX-8bit (8-bit, 9.53 GB) |
256K (model maximum) | Fits at the default GPU limit (75% of memory). |
| Mac Studio M5 Ultra | 256 GB unified | Xylolabs/clairic-flash-MLX-8bit (8-bit, 9.53 GB) |
256K (model maximum) | Fits at the default GPU limit (75% of memory). |
| Mac Studio M5 Ultra, 80-core GPU | 512 GB unified | Xylolabs/clairic-flash-MLX-8bit (8-bit, 9.53 GB) |
256K (model maximum) | Fits at the default GPU limit (75% of memory). |
License and notices
These files are under the Apache License 2.0, copied in LICENSE (Cloudflare's text); the original model is Cloudflare's, itself built on Qwen/Qwen3.5-9B (Apache-2.0). We quantized the language-model weights to MLX 8-bit with mlx-lm and left out the vision tower, the scoring head and the Python runtime. The source revision and what was changed are in ORIGINS.md and NOTICE. Not affiliated with or endorsed by Cloudflare.
Updates
- 2026-11-22: Added a hardware recommendation table.
- 2026-11-22: First release.
Cloudflare's original model description
Below is the model card of Cloudflare/clairic-flash (Apache-2.0), without its metadata header and unchanged.
Clairic Flash
Clairic Flash is a 9B multimodal model that turns a state and a schema of typed fields into structured answers. It supports text and image inputs, extraction, numerical estimation, and forecasting. Each field has its own value and scoring information; the response also reports input truncation and token usage.
See Clairic for the other model in the Clairic family.
Model
- Base model: Qwen3.5-9B.
- Inputs: a text or JSON state, optional images, and a mapping of field names to specifications.
- Outputs: typed values, lists, nulls, estimates, and forecast paths.
- Scoring: extraction confidence and null probabilities, plus optional quantiles for estimates.
- Runtime: PyTorch and Transformers, with local Python request helpers.
Usage
Use Python 3.11 or later and install the packages listed in requirements.txt. Inference uses PyTorch and
Transformers; xgrammar supplies schema constraints through a Transformers logits
processor.
Download the repository, load the model and processor, and call systemone with a
System One: Extract request.
import sys
from huggingface_hub import snapshot_download
path = snapshot_download("Cloudflare/clairic-flash")
sys.path.insert(0, path)
from clairic_model import load_release_model, systemone
model, processor = load_release_model(path, device="cuda")
response = systemone(
model,
processor,
{
"state": (
"Invoice from Northwind Supply. Issued 2026-09-02. "
"Items: Pens; Paper. Total: $1080.00."
),
"fields": {
"vendor": {"type": "text", "instructions": "The invoice vendor."},
"total": {"type": "number", "decimals": 2},
"issued": {"type": "date"},
"items": {
"type": "list",
"items": "text",
"instructions": "The purchased item names, in order.",
},
},
},
)
print(response["answers"])
Images
Pass PIL images alongside the state. Embedded base64 image inputs are also accepted.
from PIL import Image
response = systemone(
model,
processor,
{
"state": "Read the attached receipt.",
"images": [Image.open("receipt.png")],
"fields": {
"merchant": {"type": "text", "instructions": "The merchant name."},
"total": {"type": "number", "decimals": 2},
},
},
)
print(response["answers"])
Estimates and forecasts
Declare a range for estimated values. Forecasts also specify a horizon and interval.
Set include_quantiles to return the available quantiles.
response = systemone(
model,
processor,
{
"state": "Daily demand for the last seven days: 41, 45, 43, 47, 49, 46, 48.",
"fields": {
"next_day": {"type": "estimate", "min": 0, "max": 100},
"next_three_days": {
"type": "forecast",
"min": 0,
"max": 100,
"horizon": 3,
"interval": "day",
},
},
"options": {"include_quantiles": True},
},
)
print(response["answers"])
Input format
| Field | Description |
|---|---|
model |
Optional clairic-flash or @cf/cloudflare/clairic-flash |
state |
Source text; the Python helper serializes JSON values to text |
images |
Optional PIL images or embedded base64 images |
documents |
Optional embedded PDF data URIs or content_type / base64 objects |
fields |
Mapping of output field names to typed specifications |
reference_date |
Optional ISO date for relative date instructions |
options.include_quantiles |
Include available estimate and forecast quantiles |
options.return_state_text |
Include the retained source text in the response |
Field specifications support text, number, date, time, datetime, duration,
boolean, enum, object, list, compute, estimate, and forecast.
instructions describes what to return. Numeric fields can specify units and
rounding; lists declare their item schema; estimates and forecasts require bounds.
nullable defaults to true. source_only: true selects literal printed numbers,
dates, times, datetimes, or number/date lists. knowledge: true permits knowledge
answers for text, numbers, and supported list children. compute selects the typed
numeric head. Unsupported options and invalid combinations are rejected.
Embedded inputs are limited to 4 MiB each and 8 MiB combined. Images and rendered
PDF pages share a four-image/page limit. Image rotation accepts 0, 90, 180, or 270
clockwise degrees after EXIF orientation. Remote media URLs are not accepted.
Response
systemone returns a dictionary with model, answers, truncated, and usage.
Answers are keyed by the requested field names. Generated scalar extraction answers
retain valid, complete, full-sequence confidence, and independently scored p_null.
Uniquely matched text evidence includes character spans in state; image-only or
ambiguous evidence has null spans. Lists preserve item order and duplicates.
Estimates and forecasts include their typed values and, when requested, quantiles.
Scores are model probabilities and should be evaluated for the application's own
acceptance thresholds. Inspect truncated and any answer completeness indicators
before relying on a result.
Usage includes retries and supplemental work. The response model ID is clairic-flash.
The Python API raises validation or request errors for invalid inputs, a queue-full
error for simultaneous requests, and an inference error for failed generation.
Use await model.predict_async(request) in an async application; cancellation
drains owned work before admitting another request.
Files
| File | Purpose |
|---|---|
model*.safetensors, model.safetensors.index.json, config.json |
Model weights and configuration |
clair_head.safetensors, clair_head_config.json |
Typed output components |
clairic_model.py and supporting Python modules |
Transformers loading and request handling |
| Tokenizer and processor files | Text and image preprocessing |
requirements.txt |
Python dependencies |
LICENSE |
Apache-2.0 license |
License
Released under the Apache-2.0 license.
- Downloads last month
- 25
8-bit