raiiaf.handlers.file_handler

RAIIAF file handler for encoding and decoding .raiiaf artifacts.

This module orchestrates packing/unpacking of latent, image, environment, and metadata chunks, builds the header, and provides a high-level API for reading and writing RAIIAF files.

Classes

raiiafFileHandler([max_file_size, ...])

High-level API for reading and writing RAIIAF files.

class raiiaf.handlers.file_handler.raiiafFileHandler(max_file_size: int | None = None, max_chunk_size: int | None = None)

Bases: object

High-level API for reading and writing RAIIAF files.

static bytes_to_png(img_bytes: bytes) → Image

Convert PNG bytes to a PIL Image.

Parameters:

img_bytes (bytes) – PNG image bytes.

Returns:

Loaded image instance.

Return type:

PIL.Image.Image

Raises:

raiiafImageError – If the bytes cannot be decoded as an image.

file_decoder(filename: str)

Decode a RAIIAF file.

Reads the header, chunk table (metadata), and iteratively decodes the latent, image, and environment chunks.

Parameters:

filename (str) – Path to the input .raiiaf file.

Returns:

A dictionary with keys:

• header (dict): Parsed header fields.

• chunks (dict): Parsed chunks: ‘latent’ (list), ‘image’ (bytes), ‘env’ (EnvChunk).

• metadata (dict): Parsed metadata manifest.

Return type:

dict

Raises:

• raiiafCorruptHeader – If the header fails validation.

• raiiafChunkError – If a chunk is truncated or corrupt.

• raiiafEnvChunkError – If the environment chunk cannot be parsed when uncompressed.

file_encoder(filename: str, latent: Dict[str, ndarray], chunk_records: list, model_name: str, model_version: str, prompt: str, tags: list, img_binary: bytes, should_compress: bool = True, convert_float16: bool = True, generation_settings: dict | None = None, hardware_info: dict | None = None, extra_image: Dict[str, Any] | None = None)

Encode a RAIIAF file.

Orchestrates packing latent, image, environment, and metadata chunks, builds the header, and writes the final file.

Parameters:

• filename (str) – Output .raiiaf filename. The .raiiaf extension is required.

• latent (Dict[str, np.ndarray]) – Mapping of latent keys to arrays.

• chunk_records (list) – Mutable list that will be appended with chunk records.

• model_name (str) – Name of the model.

• model_version (str) – Version of the model.

• prompt (str) – Prompt used for generation.

• tags (list) – Tags associated with the generation.

• img_binary (bytes) – PNG image bytes to embed.

• should_compress (bool) – Whether to compress chunks. Defaults to True.

• convert_float16 (bool) – Convert latents to float16 for storage. Defaults to True.

• generation_settings (Optional[dict]) – Generation configuration to include in metadata.

• hardware_info (Optional[dict]) – Hardware information to include in metadata.

• extra_image (Optional[Dict[str, Any]]) – Extra fields for the image chunk record.

Returns:

A dictionary containing header bytes and chunk bytes with keys:

• header (bytes)

• latent_chunks (bytes)

• metadata_chunk (bytes)

• image_chunk (Optional[bytes])

Return type:

dict

static png_to_bytes(png_path: str) → bytes

Convert a PNG image to bytes.

Preserves transparency by converting to RGBA.

Parameters:

png_path (str) – Path to the PNG image.

Returns:

PNG image data in bytes.

Return type:

bytes

Raises:

raiiafImageError – If the image cannot be read or encoded.

validate_chunk_count(count: int) → bool

Validate the number of chunks.

Parameters:

count (int) – Number of chunks.

Returns:

True if the count is within limits.

Return type:

bool

Raises:

raiiafDecodeError – If count exceeds configured limits.

validate_file_size(size: int, context: str = 'file') → bool

Validate a file or chunk size.

Parameters:

• size (int) – Size in bytes to validate.

• context (str) – Validation context; either “file” or “chunk”.

Returns:

True if the size is within limits.

Return type:

bool

Raises:

raiiafDecodeError – If size exceeds configured limits.