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_runtime/embedded.py from mlx-community/clairic-4bit: direct link, hf CLI and curl.
- Browser
- Download file 5.42 kB
-
https://huggingface.co/mlx-community/clairic-4bit/resolve/main/clairic_runtime/embedded.py
- Command line
-
hf download hf://mlx-community/clairic-4bit/clairic_runtime/embedded.py
-
curl -L -o embedded.py https://huggingface.co/mlx-community/clairic-4bit/resolve/main/clairic_runtime/embedded.py
5.42 kB
| """Validation for embedded request images. | |
| Callers translate ``EmbeddedImageError`` into their own validation error type. | |
| The strict mode verifies the complete raster with Pillow; the signature mode | |
| intentionally accepts header-only images for backends that validate only magic | |
| bytes before forwarding the image to another service. | |
| """ | |
| from __future__ import annotations | |
| import base64 | |
| import binascii | |
| import io | |
| import re | |
| from collections.abc import Iterable | |
| MAX_IMAGES = 4 | |
| MAX_IMAGE_BYTES = 4 * 1024 * 1024 | |
| MAX_IMAGES_BYTES = 8 * 1024 * 1024 | |
| _STRICT_DATA_URI = re.compile( | |
| r"^data:(image/(?:png|jpe?g|webp));base64,([A-Za-z0-9+/]*={0,2})$", re.IGNORECASE | |
| ) | |
| _DATA_URL = re.compile(r"^data:([^;,]+);base64,(.*)$", re.DOTALL) | |
| _FORMATS = {"image/png": "PNG", "image/jpeg": "JPEG", "image/webp": "WEBP"} | |
| class EmbeddedImageError(ValueError): | |
| """A request-image failure, with a stable code for the serving layer.""" | |
| def __init__(self, code: str, message: str) -> None: | |
| super().__init__(message) | |
| self.code = code | |
| def normalize_embedded_image( | |
| value: object, | |
| *, | |
| strict: bool = False, | |
| max_image_bytes: int = MAX_IMAGE_BYTES, | |
| max_pixels: int = 16_000_000, | |
| ) -> dict[str, str]: | |
| """Normalize a data URL or exact ``{content_type, base64}`` object. | |
| ``strict=True`` verifies restricted data-URI syntax and complete raster data | |
| with Pillow, including the dimension limit. The default checks image | |
| signatures and accepts a more permissive data-URL syntax. | |
| """ | |
| if isinstance(value, str): | |
| matched = (_STRICT_DATA_URI if strict else _DATA_URL).fullmatch(value) | |
| if matched is None: | |
| label = "URI" if strict else "URL" | |
| raise EmbeddedImageError( | |
| "invalid_image", f"image must be an embedded base64 data {label}" | |
| ) | |
| value = {"content_type": matched.group(1), "base64": matched.group(2)} | |
| if type(value) is not dict or set(value) != {"content_type", "base64"}: | |
| raise EmbeddedImageError("invalid_image", "image object has invalid fields") | |
| content_type = value["content_type"] | |
| encoded = value["base64"] | |
| if type(content_type) is not str or type(encoded) is not str: | |
| raise EmbeddedImageError("invalid_image", "image fields must be strings") | |
| canonical_type = content_type.lower().replace("image/jpg", "image/jpeg") | |
| if canonical_type not in _FORMATS: | |
| raise EmbeddedImageError("invalid_image", "image content type is not supported") | |
| try: | |
| decoded = base64.b64decode(encoded, validate=True) | |
| except (binascii.Error, ValueError) as error: | |
| raise EmbeddedImageError( | |
| "invalid_image", "image base64 is malformed" | |
| ) from error | |
| if not decoded: | |
| raise EmbeddedImageError("invalid_image", "image payload is empty") | |
| if len(decoded) > max_image_bytes: | |
| raise EmbeddedImageError( | |
| "image_too_large", "image exceeds the decoded byte limit" | |
| ) | |
| if strict: | |
| _verify_raster(decoded, _FORMATS[canonical_type], max_pixels=max_pixels) | |
| elif not _has_image_signature(canonical_type, decoded): | |
| raise EmbeddedImageError( | |
| "invalid_image", "image payload does not match its content type" | |
| ) | |
| return { | |
| "content_type": canonical_type, | |
| "base64": base64.b64encode(decoded).decode("ascii"), | |
| } | |
| def _verify_raster(data: bytes, expected_format: str, *, max_pixels: int) -> None: | |
| from PIL import Image, UnidentifiedImageError | |
| try: | |
| with Image.open(io.BytesIO(data)) as image: | |
| if image.format != expected_format: | |
| raise EmbeddedImageError( | |
| "invalid_image", "image payload does not match its content type" | |
| ) | |
| if image.width * image.height > max_pixels: | |
| raise EmbeddedImageError( | |
| "invalid_image", "image dimensions are too large" | |
| ) | |
| image.verify() | |
| except EmbeddedImageError: | |
| raise | |
| except ( | |
| UnidentifiedImageError, | |
| OSError, | |
| ValueError, | |
| Image.DecompressionBombError, | |
| ) as error: | |
| raise EmbeddedImageError("invalid_image", "image payload is invalid") from error | |
| def _has_image_signature(content_type: str, data: bytes) -> bool: | |
| if content_type == "image/png": | |
| return data.startswith(b"\x89PNG\r\n\x1a\n") | |
| if content_type == "image/jpeg": | |
| return data.startswith(b"\xff\xd8\xff") | |
| return len(data) >= 12 and data.startswith(b"RIFF") and data[8:12] == b"WEBP" | |
| def decoded_base64_size(encoded: str) -> int: | |
| """Size of already validated, canonical base64 without decoding again.""" | |
| return len(encoded) * 3 // 4 - (len(encoded) - len(encoded.rstrip("="))) | |
| def validate_image_count(value: object, *, max_images: int = MAX_IMAGES) -> object: | |
| if not isinstance(value, (list, tuple)): | |
| raise EmbeddedImageError("invalid_image", "images must be an array") | |
| if len(value) > max_images: | |
| raise EmbeddedImageError( | |
| "too_many_images", "request exceeds the image count limit" | |
| ) | |
| return value | |
| def validate_total_image_bytes( | |
| sizes: Iterable[int], *, max_bytes: int = MAX_IMAGES_BYTES | |
| ) -> None: | |
| if sum(sizes) > max_bytes: | |
| raise EmbeddedImageError( | |
| "images_too_large", "images exceed the aggregate decoded byte limit" | |
| ) | |