Headroom Token Optimizer icon

Headroom Token Optimizer

Optimize LLM token usage using local Headroom context compression

Headroom Token Optimizer

AI-generated

Summary

Compresses incoming text, a JSON message array, or an item’s chatInput through a Headroom proxy or API, using a selected tokenizer model. Returns the compressed content with token and compression details; chatInput mode also preserves the rest of the incoming item’s JSON.

Inputs

  • Mode (required) — Choose Chat Input, Messages (JSON), or Text. Chat Input reads a non-empty chatInput field from each incoming item; Messages accepts a message array or JSON array string; Text uses the required Input Text value.
  • Input Text (required) — Text to compress; shown and used in Text mode.
  • Input Messages (required) — Array of chat messages to compress, supplied as JSON or a JSON array string; shown and used in Messages mode.
  • Tokenizer Model (required) — Select a tokenizer schema for token counting. This does not select or change the workflow’s LLM. Choose Custom to provide a LiteLLM-compatible model identifier.
  • Custom Tokenizer Model (required) — Custom LiteLLM-compatible model identifier; used when Tokenizer Model is Custom.
  • Token Budget — Optional token threshold. Values above zero are passed as a budget; zero omits the budget and the node description says this means always compress.
  • Base URL (required) — Headroom proxy or API URL; defaults to http://localhost:8787.
  • API Key — Optional key for Headroom Cloud.
  • Fallback on Error — UI option for falling back to uncompressed input; execution passes fallback: false to the compression call, so this setting does not enable fallback there.
  • Compress User Messages — Whether Headroom should compress user messages; defaults to true.
  • Compress System Messages — Whether Headroom should compress system messages; defaults to false.
  • Timeout (Ms) — Request timeout in milliseconds; defaults to 30000.
  • Retries — Retry count for transient failures; defaults to 1.

Output shape

One output item per input item, each containing a JSON object.

Text mode returns compressed, tokensSaved, originalTokens, compressedTokens, compressionRatio, and transformsApplied. Messages mode returns the same fields, with compressed containing the returned message array. Chat Input mode preserves the incoming JSON, replaces chatInput with compressed content, and adds those metrics. Missing chatInput or compression errors fail the item unless Continue On Fail is enabled, in which case its output contains an error field. Despite the Fallback on Error setting, compression errors are rethrown by this operation.

Links

Discussion