--- license: apache-2.0 library_name: transformers base_model: Qwen/Qwen3.8-27B pipeline_tag: image-text-to-text tags: - clairic - cloudflare - systemone - multimodal - structured-output - information-extraction - custom-code --- # Clairic Clairic is a 27B 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 Flash](https://huggingface.co/Cloudflare/clairic-flash) for the other model in the Clairic family. ## Model - **Base model:** [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B). - **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. ```python import sys from huggingface_hub import snapshot_download path = snapshot_download("Cloudflare/clairic") 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. ```python 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. ```python 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` or serving alias `clairic-27b`; `@cf/cloudflare/` aliases are accepted | | `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`. 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.