.raiiaf - AI-native Context Storage

Features

• Noise latent tensor storage

• Rich AI-native metadata that includes:

  - Model name and version
  - Prompt  
  - Tags  
  - Hardware information  
  - Generation settings
  

• Environment info stored automatically as hashed canonical strings

• Issues warnings if environment drift is detected!

Storage Efficiency Benchmark (Full Latent Tensor)

We evaluate the storage overhead of different industry-standard strategies for embedding large AI metadata by comparing how the same image and the same latent tensor are stored across multiple file formats.

Experimental Setup

• Images: 5 PNG images
• Latent tensor: Shape (1, 4, 64, 64), approximately 89 KB
• Metadata: Identical semantic metadata across all formats
• raiiaf implementation: Official raiiaf API (v0.1.0), no mocks
• Metric: Relative file size overhead compared to the raw PNG baseline

Compared Storage Strategies

• Raw PNG: Image only (baseline)
• PNG + Embedded XMP: Latent tensor serialized as XMP and embedded inside the PNG
• PNG + XMP Sidecar: Latent tensor stored in a separate .xmp file alongside the PNG
• raiiaf (.raiiaf): Single-file, binary container storing both image and latent tensor

Results

The average file sizes and relative overheads are summarized below:

Interpretation

For the same image and identical latent tensor, XMP-based workflows incur approximately 5.1–5.2% storage overhead, regardless of whether the metadata is embedded or stored as a sidecar file. In contrast, raiiaf introduces only ~1.8% overhead.

This corresponds to a ~3.3% absolute reduction in file size and approximately 65% lower relative metadata overhead compared to standard XMP-based approaches, while preserving a single-file workflow.

These results indicate that a binary, AI-native container can store large latent tensors more space-efficiently than XML-based metadata strategies under identical conditions.

Why not just use EXIF/XMP/Sidecar files?

Here is an emperical comparison:

Although XMP has the ability to embed any binary payload, doing so necessitates ad hoc conventions, manual validation, and cautious handling to prevent silent data loss. By formalizing these practices into a first-class, schema-enforced representation, raiiaf lessens failure modes and implementation burden.

a comparison with sidecar files:

Installation

Just pip install the package!

pip install raiiaf

Usage

import the classes

from raiiaf.main import raiiafFileHandler

First you need to instantiate the raiiafFileHandler class.

raiiaf = raiiafFileHandler()

Encoding

!!! danger DISCLAIMER: The encoder expects NumPy arrays.
If you use PyTorch tensors, convert them with .detach().cpu().numpy().

from raiiaf.main import raiiafFileHandler

raiiaf = raiiafFileHandler()
initial_noise_tensor = torch.randn(batch_size, channels, height, width)
latent = {
    "initial_noise": initial_noise_tensor.detach().cpu().numpy() #The encoder expects numpy array not a torch tensor object
}
binary_img_data = raiiaf.png_to_bytes(r'path/to/image.png') # use the helper function to convert image to bytes

raiiaf.file_encoder(
    filename="encoded_img.raiiaf", # The .raiiaf extension is required!
    latent=latent,# initial latent noise
    chunk_records=[],
    model_name="Stable Diffusion 3",
    model_version="3", # Model Version
    prompt="A puppy smiling, cinematic",
    tags=["puppy","dog","smile"],
    img_binary=binary_img_data,
    convert_float16=False, # whether to convert input tensors to float16
    generation_settings={
        "seed": 42,
        "steps": 20,
        "sampler": "ddim",
        "cfg_scale": 7.5,
        "scheduler": "pndm",
        "eta": 0.0,
        "guidance": "classifier-free",
        "precision": "fp16",
        "deterministic": True
    },
    hardware_info={
        "machine_name": "test_machine",
        "os": "linux",
        "cpu": "Intel",
        "cpu_cores": 8, # minimum 1
        "gpu": [{"name": "RTX 3090", "memory_gb": 24, "driver": "nvidia", "cuda_version": "12.1"}],
        "ram_gb": 64.0,
        "framework": "torch",
        "compute_lib": "cuda"
    }
)

Decoding

decoded = raiiaf.file_decoder(filename)
# now to save the metadata
metadata = decoded["metadata"]["raiiaf_metadata"]

# to just get specific metadata blocks
model_info = decoded["metadata"]["raiiaf_metadata"]["model_info"]

# to save decoded metadata to a json file
with open("decoded_metadata.json", "w") as f:
    json.dump(decoded["metadata"], f, indent=2)

# to save just the image_binary as png
image_bytes = decoded["chunks"].get("image")
if image_bytes is not None:
    img = Image.open(io.BytesIO(image_bytes))
    img.save("decoded_image.png")

LICENSE

MIT

Contribution

Please refer to the CONTRIBUTING.md filein the repo

Documentation

Full docs: https://anuroopvj.github.io/raiiaf

Future improvements

• Supporting other frameworks and utilities in the EnvChunk
• Reducing File Size