CLI usage
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