Compressore locale LLM‑ready

Compressione reversibile per testo, ottimizzata per LLM (placeholder + manifest + chunking + roundtrip verificabile)

git clone --depth 1 --branch main https://github.com/kamaludu/chunk-compress.git chunk-compress

Assicurati che questi file siano nella stessa directory:

core.py
cli.py
io_utils.py

• Python 3.8+
• Nessuna libreria esterna
• Funziona su qualsiasi shell con Python disponibile

Puoi fornire:

A) Una directory
Esempio:

/home/user/progetto/

B) Una file‑lista
Un file di testo con un percorso per riga:

src/a.py
src/b.py
docs/readme.md

python3 cli.py --input <percorso_input> --output out

Se non specifichi --output, verrà usata automaticamente:

./compressed_output/

• --L_min lunghezza minima substring (default 64)
• --N_min occorrenze minime (default 2)
• --B_min_lines righe minime per blocchi (default 5)
• --B_max_lines righe massime per blocchi (default 20)
• --verify-roundtrip verifica integrità totale

Esempio:

python3 cli.py --input ./src --output ./out --L_min 80 --verify-roundtrip

Dentro la directory out/ troverai:

1) File compressi LLM‑ready Stessa struttura dei file originali, ma con placeholder:

§§s001§§   (substring)
§§b001§§   (block)

2) mapping_subset.json Contiene solo i placeholder effettivamente usati nei file compressi.

• È generato automaticamente per tutti i file processati.
• È pensato per essere incollato in una chat LLM.
• È molto più piccolo di reverse_map.json.

Puoi controllarne la generazione con:

• --no-export-mapping → nessun mapping_subset.json
• --no-export-mapping file1,file2,... → esclude solo quei file

3) reverse_map.json Contiene il mapping completo:

• placeholder → contenuto originale
• posizioni originali
• metadati

È utile per verifiche locali, ma troppo grande per essere incollato in una chat.

4) manifest.json (solo se --export-manifest) Manifest compatto della struttura originale:

• paths
• files
• placeholder usati
• versioning

5) chunks/ (solo se --chunk-output) Contiene:

chunks/
  chunk_0001.txt
  chunk_0002.txt
  ...
  manifest.json   ← manifest dei chunk

Il chunks/manifest.json descrive:

• quali chunk compongono ogni file
• ordine dei chunk
• SHA256 atteso (se presente)

Esempio tipico dopo l’esecuzione:

out/
  src/
    a.py
    b.py
  reverse_map.json
  mapping_subset.json
  manifest.json          (solo se --export-manifest)
  chunks/                (solo se --chunk-output)
    chunk_0001.txt
    chunk_0002.txt
    ...
    manifest.json        (manifest dei chunk)

Caso A — File piccoli (senza chunking)

1. Apri out/
2. Copia i file compressi (sono molto più piccoli)
3. Incollali nella chat LLM
4. Incolla anche mapping_subset.json
   → contiene solo i placeholder effettivamente usati
5. Chiedi al modello di ricostruire i file usando mapping + file compressi

Caso B — File grandi (con chunking)

1. Apri out/chunks/
2. Copia:
   • chunks/manifest.json
   • tutti i chunk chunk_*.txt
   • mapping_subset.json
3. Incollali nella chat LLM seguendo la sequenza:
   • manifest dei chunk
   • mapping
   • chunk (uno o più per messaggio)
4. Chiedi al modello di ricostruire i file concatenando i chunk nell’ordine indicato

1. Metti i tuoi file in una directory
2. Lancia il comando
3. Ottieni file compressi
4. Incolla in chat LLM
5. Risparmi token e mantieni reversibilità totale

1. Metti i tuoi file in una directory
2. Lancia:

   python3 cli.py --input ./src --chunk-output

3. Ottieni:
   • file compressi normali
   • chunk in out/chunks/
4. In chat LLM:
   • incolla chunks/manifest.json
   • incolla mapping_subset.json
   • incolla i chunk
5. Chiedi la ricostruzione

(ordinati alfabeticamente)

Range minimo/massimo, preset consigliati e note operative.

Preset completo (aggressivo)

python3 cli.py \
  --input ../directory/file.sh \
  --output ./out \
  --L_min 30 \
  --N_min 2 \
  --B_min_lines 3 \
  --B_max_lines 10 \
  --min_total_saving 20 \
  --placeholder-sub "§§s{:03d}§§" \
  --placeholder-blk "§§b{:03d}§§" \
  --export-manifest \
  --verify-roundtrip \
  --chunk-output \
  --chunk-size 15000

Preset tipico

python3 cli.py \
  --input ../selected/directory/ \
  --L_min 32 \
  --N_min 2 \
  --B_min_lines 3 \
  --B_max_lines 10 \
  --min_total_saving 20 \
  --export-manifest \
  --verify-roundtrip

python3 cli.py --input INPUT_DIR --output OUT_DIR --export-manifest

python3 cli.py --input INPUT_DIR --output OUT_DIR --export-manifest

python3 cli.py -i ../directory/file.xx -o ./out --export-manifest

Percorso:
OUT_DIR/manifest.json

Contiene:

• paths: elenco file
• files: placeholder usati per file
• ph: metadati placeholder
• v: versione schema

Percorso:
OUT_DIR/chunks/manifest.json

Contiene:

• elenco chunk
• ordine dei chunk per ogni file
• SHA256 atteso (se presente)

• L’input può essere una directory o una file‑lista.
• I file binari/inutili vengono esclusi automaticamente (usa --include-pointless per includerli).
• mapping_subset.json è pensato per l’uso in chat LLM.
• reverse_map.json è completo ma molto grande.
• --export-manifest è idempotente.
• I chunk sono utili per file molto grandi o per chat con limiti di input.

Compressore locale LLM‑ready è distribuito sotto licenza GNU GPL v3.
Vedi LICENSE per il testo completo.

Parte del codice e della documentazione è stata redatta con l’assistenza di strumenti di IA.
L’architettura e le decisioni tecniche restano curate manualmente.

• Autore: Cristian Evangelisti
• Email: opensource​@​cevangel.​anonaddy.​me
• Repository: https://github.com/kamaludu/chunk-compress