Guides

Python API

Use the Compressor and Decompressor classes directly from Python.

The public Python API lives in the top-level ptwm package. The main entry points are Compressor, Decompressor, and their config dataclasses.

Compress and decompress raw bytes

from ptwm import (
    Compressor, Decompressor,
    CompressionConfig, DecompressionConfig,
    Method, Format,
)

config = CompressionConfig(
    method=Method.AUTO,       # AUTO | HUFFMAN | MICROSCALE | ZSTD
    bytearray_dtype="bfloat16",   # hint for byte-reordering raw bytes
    threads=8,                    # encode parallelism (default: all cores)
)
compressor = Compressor(config)
compressed: bytes = compressor.compress(data, fmt=Format.BYTE)

decompressor = Decompressor(DecompressionConfig(threads=8))
restored: bytes = decompressor.decompress(compressed, fmt=Format.BYTE)

The AUTO method picks a codec by dtype: HUFFMAN for float / int weights, MICROSCALE for MXFP4 / NVFP4 paired tensors, ZSTD as a generic fallback (plain in-tree Zstd; the byte-split preprocessing op upstream supplies the SHUFFLE-style reordering).

Compress and decompress a torch tensor

import torch
from ptwm import Compressor, Decompressor, CompressionConfig, Format

config = CompressionConfig(input_format=Format.TORCH)
compressor, decompressor = Compressor(config), Decompressor()

tensor = torch.randn(1024, 1024, dtype=torch.bfloat16)
restored = decompressor.decompress(compressor.compress(tensor))
assert torch.equal(tensor, restored)

Supported input/output formats

Format	Description
`Format.BYTE`	Raw bytes in / raw bytes out. dtype hint required for byte-reordering.
`Format.TORCH`	`torch.Tensor` in / `torch.Tensor` out. dtype and shape preserved.
`Format.NUMPY`	`numpy.ndarray` equivalent.
`Format.FILE`	File-path workflow. Input path is read; output path is written.

CompressionConfig knobs

Option	Default	Description
`method`	`AUTO`	`AUTO`, `HUFFMAN`, `MICROSCALE`, or `ZSTD`
`bytearray_dtype`	`"bfloat16"`	Dtype hint for byte-reordering when input is `BYTE`
`threads`	`None` (up to 16 cores)	Maximum threads for parallel encode
`compression_threshold`	`0.95`	Skip compression if ratio exceeds this threshold
`compression_chunk`	`262144`	Chunk size in bytes (256 KB)

Full reference

See the Python API reference for every public symbol in ptwm.* with docstrings, parameters, return types, and source links.

CLI usage

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

Writing your first extension

Step-by-step walkthrough from `ptwm ext init` to a signed, installed plane codec.