lucataco's picture
Clairic Flash, MLX 4-bit, with runtime, server and conversion script
ae97c5d verified
Raw History Blame Contribute Delete
6.86 kB
"""Clairic request and response schemas."""
from __future__ import annotations
import base64
import io
from dataclasses import dataclass
from typing import Any, LiteralString, cast
from .embedded import (
MAX_IMAGE_BYTES,
MAX_IMAGES,
MAX_IMAGES_BYTES,
EmbeddedImageError,
decoded_base64_size,
normalize_embedded_image,
validate_image_count,
validate_total_image_bytes,
)
from PIL import Image, ImageOps
from pydantic import (
BaseModel,
ConfigDict,
Field,
StrictStr,
field_validator,
model_validator,
)
from pydantic_core import PydanticCustomError
from .documents import ClairDocument
MODEL_ID = "clairic"
def _image_error(error: EmbeddedImageError) -> PydanticCustomError:
# Every code and message originates from fixed literals in the shared helper.
return PydanticCustomError(
cast(LiteralString, error.code), cast(LiteralString, str(error))
)
class ClairImage(BaseModel):
"""An embedded PNG, JPEG, or WebP image validated before it reaches the processor."""
model_config = ConfigDict(extra="forbid", frozen=True)
content_type: StrictStr
base64: StrictStr
rotation: int = 0
@model_validator(mode="before")
@classmethod
def parse_image(cls, value: object) -> object:
try:
rotation = 0
explicit_rotation = isinstance(value, dict) and "rotation" in value
if explicit_rotation:
value = dict(value) # type: ignore[call-overload] # explicit_rotation guards the dict input.
rotation = value.pop("rotation") # type: ignore[attr-defined]
if type(rotation) is not int or rotation not in (0, 90, 180, 270):
raise EmbeddedImageError(
"invalid_image",
"rotation must be 0, 90, 180 or 270 clockwise degrees",
)
normalized = normalize_embedded_image(
value, strict=True, max_image_bytes=MAX_IMAGE_BYTES
)
return (
{**normalized, "rotation": rotation}
if explicit_rotation
else normalized
)
except EmbeddedImageError as error:
raise _image_error(error) from error
def to_pil(self) -> Image.Image:
from .orientation import orient_document
with Image.open(io.BytesIO(base64.b64decode(self.base64))) as image:
result = ImageOps.exif_transpose(image)
if "A" in result.getbands() or "transparency" in result.info:
# Render visible document pixels before discarding alpha. Hidden
# RGB values can otherwise erase opaque black text completely.
rgba = result if result.mode == "RGBA" else result.convert("RGBA")
result = Image.new("RGB", rgba.size, "white")
result.paste(rgba, mask=rgba.getchannel("A"))
else:
result = result.convert("RGB")
if "rotation" in self.model_fields_set:
return (
result.rotate(-self.rotation, expand=True)
if self.rotation
else result
)
return orient_document(result)
@property
def decoded_size(self) -> int:
return decoded_base64_size(self.base64)
class PredictOptions(BaseModel):
model_config = ConfigDict(extra="forbid")
include_quantiles: bool = False
return_state_text: bool = False
class PredictRequest(BaseModel):
"""A state (any text), optional images, and any number of typed fields. Field specs are checked against
the field schema when the request is encoded."""
model_config = ConfigDict(extra="forbid")
model: StrictStr | None = None
state: StrictStr = ""
images: tuple[ClairImage, ...] = Field(
default=(), json_schema_extra={"maxItems": MAX_IMAGES}
)
documents: tuple[ClairDocument, ...] = Field(default=(), max_length=MAX_IMAGES)
fields: dict[StrictStr, dict[StrictStr, Any]]
reference_date: StrictStr | None = None
options: PredictOptions = Field(default_factory=PredictOptions)
@field_validator("images", mode="before")
@classmethod
def check_image_count(cls, value: object) -> object:
try:
return validate_image_count(value, max_images=MAX_IMAGES)
except EmbeddedImageError as error:
raise _image_error(error) from error
@model_validator(mode="after")
def check_content(self) -> PredictRequest:
if not self.fields:
raise PydanticCustomError(
"empty_fields", "fields must declare at least one field"
)
if not self.state.strip() and not self.images and not self.documents:
raise PydanticCustomError(
"empty_state", "state must be non-empty when no images are sent"
)
try:
validate_total_image_bytes(
(
decoded_base64_size(item.base64)
for item in (*self.images, *self.documents)
),
max_bytes=MAX_IMAGES_BYTES, # type: ignore[attr-defined] # Both validated media types have base64.
)
except EmbeddedImageError as error:
raise _image_error(error) from error
return self
@dataclass(frozen=True, slots=True)
class PredictOutput:
answers: dict[str, dict[str, Any]]
truncated: bool
state_tokens: int
image_tokens: int
schema_tokens: int
input_tokens: int
passes: int
state_text: str | None = None
output_tokens: int = 0
def _without_quantiles(answer: dict[str, Any]) -> dict[str, Any]:
answer = {key: value for key, value in answer.items() if key != "quantiles"}
if isinstance(answer.get("steps"), list):
answer["steps"] = [_without_quantiles(step) for step in answer["steps"]]
return answer
def serialize_response(
request: PredictRequest, output: PredictOutput, model_id: str
) -> dict[str, Any]:
answers = {
name: answer
if request.options.include_quantiles
else _without_quantiles(answer)
for name, answer in output.answers.items()
}
content: dict[str, Any] = {
"model": model_id,
"answers": answers,
"truncated": output.truncated,
"usage": {
"state_tokens": output.state_tokens,
"image_tokens": output.image_tokens,
"schema_tokens": output.schema_tokens,
"input_tokens": output.input_tokens,
"output_tokens": output.output_tokens,
"passes": output.passes,
},
}
if request.options.return_state_text and output.state_text is not None:
content["state_text"] = output.state_text
return content