Headroom, il compressore di token

Cosa è Headroom?

Nel panorama dello sviluppo di applicazioni LLM mancava un tool come Headroom, ovvero uno strumento capace di comprimere i prompt da inviare ai vari servizi di intelligenza artificiale.

Ogni giorno inviamo ad Anthropic, ChatGPT e via dicendo tonnellate di prompt pieni di informazioni di dubbia utilità. Un esempio classico è l’analisi di un file di log dove, insieme alle informazioni di warning o fatal error che ci interessano, inviamo all’AI anche gigabyte di dati sugli accessi.

Headroom è uno strumento, più precisamente un context optimization layer, che filtra i prompt restituendone una versione ridotta all’osso, da inviare all’LLM.

Ma come funzoina Headroom?

Questo è l’aspetto più interessante. Esistono altri strumenti che si occupano di ottimizzare i prompt, ma si basano a loro volta su ulteriori chiamate preliminari a un LLM, andando comunque a impattare su tempi e token.

Headroom è invece uno strato intermedio basato su codice (principalmente Python) che utilizza strategie di compressione tutto sommato semplici ma efficaci. Nel dettaglio interviene su:

• JSON, riducendo all'osso la struttura e comprimendo i testi lunghi
• Codice, comprimendo la rappresentazione dei metodi (firma e struttura, non l’intera implementazione)
• Log, eliminando le informazioni ridondanti e aggregando quelle ripetitive, ad esempio calcolando il numero di occorrenze
• Testo, identificando le informazioni salienti e rimuovendo il resto (ad esempio nei testi di conferma ordine vengono eliminati i convenevoli iniziali delle email)

Tecnicamente, Headroom è una libreria che può funzionare sia come proxy che come funzione Python o TypeScript. È disponibile anche l’integrazione con diversi framework (LangChain, Agno, Strands, LiteLLM, Vercel AI SDK, MCP).

Quanti token risparmiamo con Headroom?

È lo stesso repository ufficiale a fornire dei dati. Ad oggi, grazie a circa 890 installazioni, Headroom può vantare un risparmio in token equivalente a oltre 175 mila dollari, a fronte di oltre 1 milione di richieste ottimizzate.

Nei contenuti di tipo acJSON il risparmio si attesta attorno al 70–90%; nei log tra l’80 e il 95%. Più contenuto il risparmio su risultati di ricerche da analizzare, che comunque parte da circa il 60% e può arrivare fino a un considerevole 80%. Sul codice sorgente invece la forbice è molto ampia, 40–70%, perché si tratta di basi molto eterogenee.

E se il risultato viene compromesso?

Un po’ come negli algoritmi di compressione delle immagini (JPEG), il rischio è che si perda qualità e che il risultato finale dell’LLM non sia efficace.

Headroom intercetta la richiesta di ulteriori dati da parte dell’LLM e restituisce una nuova versione, meno compressa, del prompt.

Davvero un ottimo lavoro: non è un caso che su GitHub, a giugno 2026, avesse già superato le 45 mila stelle.