fireworks-delta-compression 0.1.0

Delta compression utilities used by the Fireworks AI hot-load and incremental snapshot pipelines

fireworks-delta-compression

Delta compression utilities used by the Fireworks AI serving stack to ship incremental model weight updates (hot-loads) over the wire.

This package exposes the same compression / decompression backends that the Fireworks serving servers use internally, so you can produce or consume deltas on the customer side without copy-pasting source from the monorepo and without risk of dependency version drift.

Install

pip install fireworks-delta-compression

Quick start

import torch
from fireworks_delta_compression import (
    delta_compress,
    delta_decompress,
)

src = torch.randn(1024, 1024, dtype=torch.bfloat16)
dst = src + 1e-3 * torch.randn_like(src)

compressed_diff, checksum = delta_compress(
    src=src,
    dst=dst,
    compression_format="arc_v3",
)

restored = delta_decompress(
    src=src,
    compressed_diff=compressed_diff,
    checksum=checksum,
    compression_format="arc_v3",
)
torch.testing.assert_close(restored, dst)

Supported compression formats

Format	Backend
arc_v1	XOR diff + zlib
arc_v2	XOR diff + zstd
arc_v3	ARC v3 (typed, multi-strategy)

Higher-level helpers

• delta_compress_dicts_to_file / delta_decompress_dict_from_file — work on dict[str, torch.Tensor] and persist to safetensors with checksums in the metadata block.
• delta_compress_files_to_file — read two safetensors files and write the delta out as a third safetensors file.
• delta_compress_dirs / decompress_delta_into_source — walk a directory of safetensors shards in parallel.
• delta_decompress_inplace — mmap-based in-place decompression that rewrites the base safetensors file with the diff applied (no extra RAM copy).

Versioning

Dependencies (torch, safetensors, numpy, zstd) use loose compatible- release pins so this wheel installs cleanly alongside customer code. The upper bounds (<3, <1, <3, <2) protect against silent breakage from major-version upgrades; bump them after validating against a new server release.

License

MIT — see LICENSE.