"""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