PTWM
Guides

CLI usage

Compress and decompress files with the `ptwm` command-line tool.

The ptwm command compresses and decompresses files. Compressed output uses the .ptwm suffix.

Compress a safetensors model

Tensor-by-tensor compression into a single multi-tensor .ptwm file:

ptwm compress model.safetensors
# produces model.safetensors.ptwm

Compress an arbitrary file

ptwm compress model.bin
# produces model.bin.ptwm

Compress every safetensors file in a directory

ptwm compress /path/to/model/

Each shard gets its own .ptwm file alongside.

Decompress

ptwm decompress model.safetensors.ptwm
# restores model.safetensors

Container layout

New .ptwm files use the compact container layout (\x89PTWC), which PTWM v1.2 and later read. Without --mode, a .safetensors file is written as a .ptwm.safetensors file that holds one compact frame (\x89PTWS) per tensor, which also needs v1.2. For files that v1.1 opens, write the legacy layout:

ptwm compress model.safetensors --container-layout legacy

The flag applies to every output of ptwm compress. In the .ptwm.safetensors output it makes every tensor a full \x89PTWM container.

See the release notes for the details.

Delta compression

Compress relative to a reference file. The output omits the reference — both compressor and decompressor must have access to it.

ptwm compress model_v2.safetensors --delta model_v1.safetensors
# writes model_v2.safetensors.delta.model_v1.safetensors.ptwm
ptwm decompress model_v2.safetensors.delta.model_v1.safetensors.ptwm \
    --delta model_v1.safetensors
# restores model_v2.safetensors

A .bin input keeps the pre-v1.2 name: model.bin compresses to model_delta_<reference>.ptwm.

ptwm decompress reads the input name from the compressed name. When the compressed name holds more than one .delta. or _delta_ (usually because the input or reference name holds one), it does not show where the input name stops. Then ptwm compress prints a note with the input path, and ptwm decompress needs the output file:

ptwm decompress x_delta_y.pt.delta.base.bin.ptwm --delta base.bin \
    --output x_delta_y.pt

See Delta compression for when this is worth it.

Chain promotion

Promote a chain discovered by explore_chains() into the production table:

ptwm chains promote audit-log.jsonl

This validates the chain and emits a diff for PRODUCTION_CHAINS in python/ptwm/preprocessing/_chains.py. The command stages the diff for review and writes nothing without explicit follow-up.

Help

ptwm compress --help
ptwm decompress --help
ptwm chains --help