README.md

---
license: mit
---
# ZipPlus Model Card

**A pre-trained 4-layer GRU model for neural file compression. Each compressed file contains its own adapted model — no external model needed to decompress.**

This is a pre-trained ByteGRU model for [Zip+](https://github.com/CompactAIOfficial/ZipPlus).

## What is this

Zip+ compresses any file into a PNG image using a neural network (GRU + range coding). Each compressed file embeds its own adapted model:

```
file.txt → [ByteGRU + Range Coding] → file.txt.zpng.png → [embedded model] → file.txt
```

**Every PNG is self-contained** — decompress even if you lose the original model file!

## Model Details

- **Architecture**: 4-layer GRU over byte embeddings
- **Embedding dim**: 64 → Hidden dim: 512
- **Trained on**: FineWeb-Edu (10BT of educational web text) + adaptive per-file training
- **Entropy coding**: Range coding via Constriction
- **Output format**: PNG where payload + model live in RGB pixel bytes
- **Magic header**: `ZPNG` (first 4 bytes)

## Requirements

- Python 3.10+
- PyTorch (CUDA recommended)
- Constriction (`pip install constriction`)
- Pillow
- numpy
- huggingface_hub

```bash
pip install torch constriction pillow numpy huggingface_hub
```

## Quick Start

### Compress a file (with auto-adaptation)

```bash
python inference.py compress myfile.txt -o myfile.zpng.png
```

- Automatically adapts model to your file (50 steps)
- Embeds adapted model in PNG for self-contained decoding

### Decompress

```bash
python inference.py decompress myfile.zpng.png -o restored.txt
```

Loads the model embedded in the PNG — no external files needed!

### Training (optional)

```bash
python train.py --grid 128 --steps 10000
```

Auto-downloads FineWeb-Edu if no corpus specified.

## Performance

- Text files: ~5-20% of original size
- Works best on files > 10KB
- Smaller files: embedding overhead (~21MB) may exceed compression gains

## Warnings

- **Embedding adds ~21MB** to output — worth it for large files
- **GPU recommended** for training and compression
- **Lossless** — verified via SHA256 checksums

## License

MIT. I'm not liable if this eats your thesis/pixels/anything.