"""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()