GGUFCompressionLab

Esperimento didattico da riga di comando per misurare dimensione ed entropia dei byte di un file GGUF e confrontarne la compressione lossless con LZMA, GZIP, BZIP2 e ZLIB.

Il programma analizza il flusso binario: non interpreta tensori o metadati, non modifica la quantizzazione del modello e non sostituisce strumenti GGUF specializzati.

Cosa fa

1. richiede il percorso di un file .gguf non vuoto;
2. legge il file a blocchi da 1 MiB senza caricarlo interamente in memoria;
3. calcola la distribuzione dei byte e l'entropia di Shannon in bit per byte;
4. permette di eseguire uno o tutti i compressori disponibili;
5. salva gli output accanto all'originale e mostra dimensioni e rapporti.

Il confronto aiuta a osservare quanto un modello già quantizzato sia ulteriormente comprimibile con algoritmi generici. Non misura qualità, velocità d'inferenza o accuratezza del modello.

Requisiti e avvio

• Python 3.10 o successivo;
• dipendenze elencate in requirements.txt.

python -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements.txt
.\.venv\Scripts\python main.py

Su Linux o macOS, attivare l'ambiente con source .venv/bin/activate oppure richiamare direttamente .venv/bin/python.

Output e precauzioni

Algoritmo	Estensione
LZMA	.xz
GZIP	.gz
BZIP2	.bz2
ZLIB	.zlib

• gli output sono creati nella stessa cartella del file di origine;
• un output omonimo già esistente viene sovrascritto;
• l'opzione “Tutti” richiede spazio sufficiente per quattro copie compresse;
• modelli di grandi dimensioni possono richiedere molto tempo;
• i file .gguf e gli output generati sono esclusi da Git tramite .gitignore.

Test

I test usano esclusivamente byte sintetici temporanei e verificano entropia, gestione dei file vuoti e round-trip dei quattro compressori:

python -m unittest discover -s tests -v

Licenza e dipendenze

Il codice originale e la documentazione sono distribuiti con licenza MIT, Copyright © 2026 Fabio De Deo.

colorama, tqdm e la libreria standard Python appartengono ai rispettivi autori. Attribuzioni e collegamenti sono raccolti in THIRD_PARTY_NOTICES.md.

---

English summary

GGUFCompressionLab is a small MIT-licensed CLI experiment that streams a GGUF file, estimates byte-level Shannon entropy and compares lossless LZMA, GZIP, BZIP2 and ZLIB compression. It does not parse GGUF tensors or metadata, change model quantisation, or benchmark inference quality. See the sections above for requirements, generated files, safety notes and tests.