HammerIO Documentation

Quick Start

pip install hammerio
hammer --accept-license

# Compress anything
hammer compress data.csv
hammer compress ./dataset/ --quality fast

# Decompress
hammer decompress data.csv.zst
hammer decompress archive.tar.lz4

# Watch daemon
hammer watch --watch-root ./pipeline

# Benchmark
hammer benchmark --1gb

Installation

Standard install

pip install hammerio

GPU acceleration

pip install hammerio[gpu]

Jetson (with jtop monitoring)

pip install hammerio[jetson]

# Or clone and use the setup script
git clone https://github.com/Subzero121800/HammerIO.git
cd HammerIO && pip install -e .

Post-install setup

hammer --accept-license
hammer install-desktop     # right-click integration
hammer webui               # web dashboard

System requirements

Python 3.10, 3.11, or 3.12
CUDA 12.x for GPU features (optional — CPU fallback available)
macOS Apple Silicon for LZFSE support (M1/M2/M3/M4)
Linux (Ubuntu 20.04+, JetPack 6.x)
4GB+ RAM recommended for large file operations

CLI Reference

`hammer compress`

Compress a file or directory.

Flag	Default	Description
`FILE`	—	File or directory to compress
`--algo`	auto	Force algorithm: `lz4`, `zstd`, `gzip`, `lzfse`
`--quality`	balanced	Quality preset: `fast`, `balanced`, `max`
`--processor`	auto	Force `gpu` or `cpu`
`--output`	—	Output path
`--verify`	true	Run SHA-256 integrity check

`hammer decompress`

Decompress a file.

Flag	Default	Description
`FILE`	—	Compressed file to decompress
`--output`	—	Output path
`--verify`	true	Run SHA-256 integrity check

`hammer batch`

Compress or decompress multiple files.

Flag	Default	Description
`DIR`	—	Directory with files to process
`--mode`	compress	`compress` or `decompress`
`--recursive`	false	Process subdirectories
`--workers`	8	Number of parallel workers

`hammer watch`

Start the watch daemon for automated processing.

Flag	Default	Description
`--watch-root`	./pipeline	Root directory to watch
`--poll-interval`	2	Seconds between checks
`--daemon`	false	Run in background

`hammer benchmark`

Run performance benchmarks.

Flag	Default	Description
`--1gb`	false	Run 1GB benchmark suite
`--96mb`	false	Run 96MB benchmark suite
`--all`	false	Run all benchmarks
`--output`	—	Save results to JSON

`hammer info`

Display system info, routing decisions, and hardware profile.

Flag	Description
`--routes FILE`	Show routing decision for a specific file
`--hardware`	Show hardware profile and available engines

`hammer install-desktop`

Install right-click file manager integration.

`hammer config`

View, save, or generate the configuration file.

Flag	Description
`--show`	Print current configuration
`--save`	Save current config to file
`--generate`	Generate default config

`hammer monitor`

Real-time system monitoring during operations.

`hammer webui`

Launch the web-based dashboard.

`hammer version`

Print the installed version.

Watch Daemon

The watch daemon monitors directories and automatically processes files as they arrive.

pipeline/ compress/ ← drop files here decompress/ ← drop .lz4/.zst here compressed/ → output here decompressed/ → output here processed/ → originals archived here

# Start the watch daemon
hammer watch --watch-root ./pipeline

# Run as a background daemon
hammer watch --watch-root ./pipeline --daemon

# Custom poll interval
hammer watch --watch-root ./pipeline --poll-interval 5

Files dropped into compress/ are automatically compressed using the optimal engine. Files dropped into decompress/ are decompressed. Originals are moved to processed/ after completion.

Python API

import hammerio

# Create a router
router = hammerio.JobRouter(quality="fast")

# Route and execute
job = router.route("dataset.csv")
result = router.execute(job)

print(f"{result.compression_ratio:.1f}x in "
      f"{result.elapsed_seconds:.3f}s "
      f"via {result.processor_used}")

JobRouter options

Parameter	Values	Description
`quality`	`"fast"`, `"balanced"`, `"max"`	Compression quality preset
`processor`	`"auto"`, `"gpu"`, `"cpu"`	Force processor selection
`verify`	`True` / `False`	Enable SHA-256 verification

Result object

Attribute	Type	Description
`compression_ratio`	float	Compression ratio achieved
`elapsed_seconds`	float	Total operation time
`processor_used`	str	`"gpu"` or `"cpu"`
`method`	str	Compression method used
`input_size`	int	Input size in bytes
`output_size`	int	Output size in bytes
`integrity`	bool	SHA-256 verification result

Configuration

HammerIO reads configuration from hammerio.toml in your project root or ~/.config/hammerio/config.toml.

# hammerio.toml

[general]
default_quality = "balanced"    # fast | balanced | max
verify = true                  # SHA-256 after every op
log_level = "info"             # debug | info | warn | error

[routing]
gpu_threshold_mb = 10         # Min size for GPU routing
passthrough_extensions = [     # Skip already-compressed
  ".zip", ".gz", ".lz4",
  ".zst", ".xz", ".bz2"
]

[gpu]
device_id = 0                 # CUDA device index
chunk_size_mb = 64            # nvCOMP chunk size

[cpu]
threads = 0                    # 0 = auto (all cores)
zstd_level = 3                # Default zstd level

[watch]
poll_interval = 2             # Seconds between checks
watch_root = "./pipeline"     # Default watch directory
notifications = true           # Desktop notifications

Hardware Compatibility

Platform	Engine	Status
Jetson AGX Orin 64GB	nvCOMP GPU LZ4	Primary — fully tested
Jetson AGX Orin 32GB	nvCOMP GPU LZ4	Supported
Jetson Orin NX / Nano	nvCOMP GPU LZ4	Supported
RTX 3000 / 4000 / 5000	nvCOMP GPU LZ4	Supported
Any CUDA 12.x GPU	nvCOMP GPU LZ4	Supported
macOS Apple Silicon	Apple LZFSE	M1/M2/M3/M4
CPU-only systems	zstd / gzip / lz4	Universal fallback

Smart Routing

The JobRouter profiles every file before choosing an engine. Decision factors:

File size — files above the GPU threshold are routed to GPU
File type — datasets (CSV, Parquet, NPY) prefer GPU even at smaller sizes
Entropy — high-entropy files (already compressed, encrypted) get passthrough
Hardware — falls back to CPU if no CUDA GPU is available

Large Files  → nvCOMP LZ4 (GPU)   # Files > ~10MB
Datasets     → nvCOMP LZ4 (GPU)   # CSV, Parquet, NPY
macOS        → Apple LZFSE        # M1/M2/M3/M4
General      → zstd parallel (CPU) # Default path
Archives     → passthrough         # Already compressed

Right-Click Integration

Install file manager integration for Nautilus, Thunar, or Nemo:

hammer install-desktop

After installation, right-click any file or folder to see HammerIO options: Compress, Decompress, and Info.

Commercial Use

HammerIO is free under the Apache 2.0 license for personal, academic, and internal business use. Commercial deployment, OEM embedding, and redistribution require a commercial license.

View license details and pricing →

Contact: Joseph@resilientmindai.com