Image-Text-to-Text
MLX
Safetensors
qwen3_5
clairic
cloudflare
systemone
structured-output
information-extraction
multimodal
custom-code
conversational
4-bit precision
Instructions to use mlx-community/clairic-4bit with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- MLX
How to use mlx-community/clairic-4bit with MLX:
# Make sure mlx-vlm is installed # pip install --upgrade mlx-vlm from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template from mlx_vlm.utils import load_config # Load the model model, processor = load("mlx-community/clairic-4bit") config = load_config("mlx-community/clairic-4bit") # Prepare input image = ["http://images.cocodataset.org/val2017/000000039769.jpg"] prompt = "Describe this image." # Apply chat template formatted_prompt = apply_chat_template( processor, config, prompt, num_images=1 ) # Generate output output = generate(model, processor, formatted_prompt, image) print(output) - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- LM Studio
- Pi
How to use mlx-community/clairic-4bit with Pi:
Start the MLX server
# Install MLX LM: uv tool install mlx-lm # Start a local OpenAI-compatible server: mlx_lm.server --model "mlx-community/clairic-4bit"
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": "mlx-community/clairic-4bit" } ] } } }Run Pi
# Start Pi in your project directory: pi
- Hermes Agent
How to use mlx-community/clairic-4bit 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 "mlx-community/clairic-4bit"
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 mlx-community/clairic-4bit
Run Hermes
hermes
- Atomic Chat
- OpenClaw
How to use mlx-community/clairic-4bit with OpenClaw:
Start the MLX server
# Install MLX LM: uv tool install mlx-lm # Start a local OpenAI-compatible server: mlx_lm.server --model "mlx-community/clairic-4bit"
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 "mlx-community/clairic-4bit" \ --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"
Download clairic_mlx.py from mlx-community/clairic-4bit: direct link, hf CLI and curl.
- Browser
- Download file 6.56 kB
-
https://huggingface.co/mlx-community/clairic-4bit/resolve/main/clairic_mlx.py
- Command line
-
hf download hf://mlx-community/clairic-4bit/clairic_mlx.py
-
curl -L -o clairic_mlx.py https://huggingface.co/mlx-community/clairic-4bit/resolve/main/clairic_mlx.py
6.56 kB
| """Clairic on Apple silicon: load an MLX Clairic folder and answer System One: Extract requests. | |
| from clairic_mlx import load, systemone | |
| model = load("mlx-community/clairic-flash-4bit") | |
| response = systemone(model, {"state": "...", "fields": {"total": {"type": "number", "decimals": 2}}}) | |
| Command line: | |
| python clairic_mlx.py --state "Invoice total: $1,080.00, issued 2026-09-02." \\ | |
| --fields '{"total": {"type": "number", "decimals": 2}, "issued": {"type": "date"}}' | |
| This mirrors `clairic_model.py` in the Cloudflare release (same request and response format); the request | |
| pipeline in `clairic_runtime/` is upstream's, with its PyTorch engine replaced by `clairic_runtime/mlx_engine.py`. | |
| """ | |
| from __future__ import annotations | |
| import argparse | |
| import asyncio | |
| import base64 | |
| import io | |
| import json | |
| import sys | |
| from collections.abc import Mapping | |
| from pathlib import Path | |
| from typing import Any | |
| sys.path.insert(0, str(Path(__file__).resolve().parent)) | |
| from clairic_runtime.api import PredictRequest, serialize_response # noqa: E402 | |
| from clairic_runtime.backend import ClairicFlashModel # noqa: E402 | |
| from clairic_runtime.errors import ClairRequestError # noqa: E402 | |
| from clairic_runtime.large import Clairic27BModel # noqa: E402 | |
| from clairic_runtime.settings import RuntimeSettings # noqa: E402 | |
| def _request(value: Mapping[str, Any] | PredictRequest) -> PredictRequest: | |
| """Accept PIL images, file paths and JSON-like states, as the upstream helper does.""" | |
| if isinstance(value, PredictRequest): | |
| return value | |
| from PIL import Image, ImageOps | |
| request = dict(value) | |
| if "state" in request and not isinstance(request["state"], str): | |
| request["state"] = json.dumps(request["state"], ensure_ascii=False) | |
| images = request.get("images") | |
| if isinstance(images, (list, tuple)): | |
| images = list(images) | |
| for index, image in enumerate(images): | |
| if isinstance(image, (str, Path)) and not str(image).startswith("data:") and Path(image).is_file(): | |
| image = Image.open(image) | |
| if isinstance(image, Image.Image): | |
| buffer = io.BytesIO() | |
| ImageOps.exif_transpose(image).convert("RGBA").save(buffer, format="PNG") | |
| images[index] = "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode("ascii") | |
| request["images"] = images | |
| documents = request.get("documents") | |
| if isinstance(documents, (list, tuple)): | |
| request["documents"] = [ | |
| "data:application/pdf;base64," + base64.b64encode(Path(document).read_bytes()).decode("ascii") | |
| if isinstance(document, (str, Path)) and not str(document).startswith("data:") and Path(document).is_file() | |
| else document | |
| for document in documents | |
| ] | |
| return PredictRequest.model_validate(request) | |
| class ClairicModel: | |
| """An MLX Clairic model with synchronous and async prediction.""" | |
| def __init__(self, runtime: ClairicFlashModel, public_name: str) -> None: | |
| self.runtime = runtime | |
| self.model_id = public_name | |
| names = {public_name, runtime.model_id} | |
| self._model_selectors = names | {"@cf/cloudflare/" + name for name in names} | |
| self.processor = runtime.processor | |
| self.engine = runtime.engine | |
| async def predict_async(self, request: Mapping[str, Any] | PredictRequest) -> dict[str, Any]: | |
| validated = _request(request) | |
| if validated.model is not None and validated.model not in self._model_selectors: | |
| raise ClairRequestError(f"Unsupported model '{validated.model}'. Use '{self.model_id}'.") | |
| output = await self.runtime.predict_async(validated) | |
| return serialize_response(validated, output, self.model_id) | |
| def predict(self, request: Mapping[str, Any] | PredictRequest) -> dict[str, Any]: | |
| """Return structured values and scores for a System One: Extract request.""" | |
| try: | |
| asyncio.get_running_loop() | |
| except RuntimeError: | |
| return asyncio.run(self.predict_async(request)) | |
| raise RuntimeError("Use await model.predict_async(request) inside an active event loop") | |
| def close(self) -> None: | |
| self.runtime.shutdown() | |
| def load(model_path: str | Path, max_length: int = 65_273, **engine_kwargs: Any) -> ClairicModel: | |
| """Load a local MLX Clairic folder or a Hugging Face repository.""" | |
| path = Path(model_path) | |
| if not path.is_dir(): | |
| from huggingface_hub import snapshot_download | |
| path = Path(snapshot_download(str(model_path))) | |
| large = int(json.loads((path / "clair_head_config.json").read_text())["hidden_size"]) == 5120 | |
| settings = RuntimeSettings(model_path=str(path), version="1", model_id="clairic-27b" if large else "clairic-flash", | |
| max_length=max_length, max_concurrency=1) | |
| # The exact upstream classes: parts of the pipeline switch on `type(self)`. | |
| runtime = (Clairic27BModel if large else ClairicFlashModel).load(settings, **engine_kwargs) | |
| return ClairicModel(runtime, "clairic" if large else "clairic-flash") | |
| def systemone(model: ClairicModel, request: Mapping[str, Any] | PredictRequest) -> dict[str, Any]: | |
| """Answer a System One: Extract request with typed fields and confidence.""" | |
| return model.predict(request) | |
| def main() -> None: | |
| ap = argparse.ArgumentParser(description="Clairic structured extraction with MLX") | |
| ap.add_argument("--model", default=str(Path(__file__).resolve().parent)) | |
| ap.add_argument("--state", default="") | |
| ap.add_argument("--fields", required=True, help="JSON mapping of field names to specifications") | |
| ap.add_argument("--image", action="append", default=[], help="image file (repeatable)") | |
| ap.add_argument("--document", action="append", default=[], help="PDF file (repeatable)") | |
| ap.add_argument("--reference-date", default=None) | |
| ap.add_argument("--quantiles", action="store_true") | |
| args = ap.parse_args() | |
| request: dict[str, Any] = {"state": args.state, "fields": json.loads(args.fields)} | |
| if args.image: | |
| request["images"] = args.image | |
| if args.document: | |
| request["documents"] = args.document | |
| if args.reference_date: | |
| request["reference_date"] = args.reference_date | |
| if args.quantiles: | |
| request["options"] = {"include_quantiles": True} | |
| model = load(args.model) | |
| try: | |
| print(json.dumps(systemone(model, request), indent=2, ensure_ascii=False)) | |
| finally: | |
| model.close() | |
| if __name__ == "__main__": | |
| main() | |