clairic-flash-4bit / clairic_mlx.py
lucataco's picture
Clairic Flash, MLX 4-bit, with runtime, server and conversion script
ae97c5d verified
Raw History Blame Contribute Delete
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()