File size: 6,559 Bytes
ae97c5d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
"""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()