Nel panorama dello sviluppo di applicazioni basate su Modelli di Linguaggio (LLM), sistemi RAG (Retrieval-Augmented Generation) e Agenti AI, ci scontriamo quotidianamente con un nemico invisibile ma estremamente costoso: la "Tassa sui Token".

Alimentare un LLM con dati grezzi — come giganteschi array JSON, log di sistema infiniti, codice ridondante o codice HTML sporco — non solo fa lievitare i costi delle API, ma consuma rapidamente la finestra di contesto e degrada la qualità delle risposte del modello.

Il rilascio di Caveman v1.3.0 risponde esattamente a questa sfida. Ispirandosi all'architettura open-source headroom, questa release introduce una pipeline di compressione content-aware (consapevole del tipo di contenuto). L'idea di fondo è semplice quanto potente: ogni tipologia di dato che l'LLM deve leggere merita un algoritmo di compressione dedicato.

La nota migliore? L'aggiornamento è completamente additivo: le API esistenti restano invariate, garantendo una retrocompatibilità totale.

Il Cuore del Sistema: Routing Intelligente

Il vero punto di svolta di questa release è la centralizzazione della logica di compressione. Non è più lo sviluppatore a dover decidere come trattare il dato prima di inviarlo al prompt.

CavemanContentRouter

È l'unico punto di ingresso della pipeline. Il router analizza dinamicamente il testo in entrata, ne rileva la natura (un array JSON, un log, un git diff, del testo tabellare o del codice) e lo smista automaticamente all'algoritmo più efficiente.

Per garantire performance industriali, il router integra:

1. Skip-Set + Result Cache a due livelli: Una cache $O(1)$ con un TTL di 30 minuti ed evizione lazy per evitare di ri-elaborare contenuti identici o non comprimibili.
2. Circuit Breaker: Se il sistema rileva 3 fallimenti consecutivi, disattiva temporaneamente la compressione passando il testo in modalità passthrough per non bloccare l'applicazione.
3. Inflation Guard: Un guardiano che confronta i token di output con quelli di input; se per qualsiasi anomalia l'output dovesse superare le dimensioni dell'input, il sistema ripristina istantaneamente il testo originale.

La configurazione è immediata grazie al supporto degli enum CompressionProfile (Light, Balanced, Agent, Aggressive), che permettono un setup a riga singola:

C#

I Compressori Specializzati: Come Cambia il Dato

Vediamo nel dettaglio come i singoli moduli ottimizzano le diverse tipologie di informazione.

1. Dati Strutturati e Tabelle

1. CavemanJsonCrusher: Gestisce gli array JSON seguendo due strategie fondamentali. La via Lossless (senza perdita) converte gli array uniformi (fino a 6 chiavi e 50 righe) in tabelle Markdown o in formato CSV compatto (sfruttando l'header #schema: + righe RFC 4180), a patto che il risparmio sia almeno del 15%. La via Lossy (con perdita controllata) sfrutta l'algoritmo BM25 per eliminare le righe meno rilevanti mantenendo fisse le ancore (il primo 30% e l'ultimo 15% dei dati) e rilevando le anomalie. Le righe rimosse vengono sostituite dal marcatore <<ccr:HASH,dropped=N/TOTAL>>.
2. CavemanCcrStore: È il magazzino in-memory (thread-safe, TTL 5 minuti) che conserva le righe rimosse dal JsonCrusher, indicizzandole tramite un prefisso esadecimale a 12 caratteri dell'hash SHA-256, permettendo all'LLM di recuperarle se necessario.
3. CavemanTabularCompressor: Ottimizza file CSV e tabelle markdown eliminando le colonne vuote o costanti e campionando le righe in base alla rilevanza della query.

2. Log, Sviluppo

1. CavemanLogCompressor: Analizza i log assegnando un punteggio di gravità (ERROR, WARN, INFO, DEBUG). Rileva gli stack-frame multilingua, isola una finestra di contesto di $\pm2$ linee attorno agli errori e applica una deduzione conservativa sui warning (es. convertendo i numeri variabili in N e gli indirizzi esadecimali in ADDR).
2. CavemanSearchCompressor: Ideale per elaborare l'output di strumenti come grep o ripgrep. Raggruppa i risultati per file, calcola il punteggio dei match in base alla pertinenza con la query e mantiene i segmenti iniziali e finali di ogni file.
3. CavemanDiffCompressor: Ottimizzato per i git diff. Mantiene intatte tutte le linee di modifica (+ / -), riduce le righe di contesto statico al minimo (default 2 linee) ed elimina i blocchi di puro contesto non modificato.

3. Codice sorgente e Web

1. CavemanCodeCompressor: Un modulo multilingua (C#, Java, JS/TS, Go, Rust, Python, Ruby, SQL, Shell) che rimuove i commenti e collassa le linee vuote, garantendo un output che sia un sottoinsieme strutturale sicuro del codice sorgente originario.
2. CavemanHtmlExtractor: Un estrattore basato su espressioni regolari pure, privo di dipendenze esterne. Rimuove script e stili, converte gli elementi di blocco in nuove linee e decodifica le entità HTML per restituire un testo pulito leggibile dall'LLM.

Ottimizzazione della Performance e della KV-Cache

Oltre a ridurre il numero puro di token, Caveman v1.3.0 introduce strategie avanzate per sfruttare al massimo l'architettura hardware e software dei moderni provider di LLM.

Protezione della KV-Cache con CavemanCacheAligner

Uno dei problemi più subdoli nei sistemi conversazionali è il "busto" della KV-Cache (Key-Value Cache). Se il prompt di sistema contiene elementi volatili che cambiano a ogni singola chiamata — come UUID, timestamp ISO-8601, token JWT o hash variabili — l'infrastruttura dell'LLM è costretta a ricalcolare daccapo l'intero prompt, aumentando drasticamente la latenza (Time-To-First-Token) e i costi di calcolo.

CavemanCacheAligner individua e isola o normalizza questi token volatili nei prompt di sistema, garantendo che le parti statiche rimangano allineate e pronte nella cache del fornitore di servizi AI.

Il consiglio dell'esperto: Usate sempre il CavemanWasteAnalyzer in fase di sviluppo. Questo modulo analizza i prompt in modalità non distruttiva ed stima esattamente quanti token state sprecando a causa di spazi bianchi eccessivi, blob in base64 o JSON troppo pesanti, aiutandovi a calibrare la pipeline di compressione.

Architetture Multi-Agente e Controllo dell'Output

L'ecosistema Caveman si arricchisce anche sul fronte della gestione dei flussi conversazionali complessi:

1. CavemanSharedContext: È uno store di contesto compresso pensato per l'interazione tra più agenti. Il comando Put comprime e memorizza l'informazione; i nodi successivi possono richiamare la versione compressa tramite Get (risparmiando token a ogni lettura incrociata) o richiedere l'originale tramite Get(full:true).
2. CavemanMessageDeduplicator: Monitora la cronologia dei messaggi per identificare duplicati basati sull'hash. È in grado di distinguere un vero "re-read" (una ri-lettura a distanza di oltre 3 messaggi) dalle attività di polling ravvicinate, sostituendo i testi duplicati con un compatto [duplicate of message #N].
3. CavemanOutputShaper: Lavora sul prompt di sistema iniettando istruzioni di controllo della verbosità (come SkipCeremony, NoRestatement, ConclusionsOnly, MinimumTokens). Il sistema è idempotente, stabile a livello di byte per ogni livello prescelto e facilmente rimovibile.

Infine, l'estensione del pattern builder tramite CavemanContentRouterBuilder permette una personalizzazione granulare dei flussi, introducendo opzioni fluide come .WithProseLevel() per definire il grado di sintesi linguistica applicato ai testi descrittivi.

Conclusioni

Caveman v1.3.0 non è solo un aggiornamento tecnico, ma rappresenta un cambio di paradigma nella gestione del contesto per le applicazioni AI. Centralizzando la compressione e rendendola specializzata per tipo di dato, permette di abbattere i costi vivi di inferenza e di migliorare la reattività dei modelli, il tutto con un inserimento a zero configurazione all'interno di progetti già esistenti tramite l'interfaccia ICompressionService.CompressContentAsync.

Nuget Package

dotnet add package Caveman --version 1.3.0