SmartCrusher

SmartCrusher is Headroom's compressor for JSON tool outputs. This is the compressor that fires automatically when ContentRouter detects JSON arrays.

How It Works

When the lossy keep/drop path runs, SmartCrusher doesn't blindly truncate arrays -- it scores each item across five dimensions:

1. First/Last items -- Context for pagination and recency
2. Error items -- 100% preservation of error states (never dropped)
3. Anomalies -- Statistical outliers (> 2 standard deviations from the mean)
4. Relevant items -- Matches to the user's query via BM25/embeddings
5. Change points -- Significant transitions in data

On that path, the target size is max_items_after_crush (15 by default): a 1,000-item array becomes ~15 items with all the information the LLM actually needs (measured: a 1,000-item array with with_compaction=False compressed to 16 items).

What Gets Preserved

Quick Start

import { compress } from "headroom-ai";

// SmartCrusher fires automatically for JSON tool outputs
const messages = [
  { role: "system" as const, content: "You are a helpful assistant." },
  { role: "user" as const, content: "Find errors in the last 24 hours" },
  {
    role: "tool" as const,
    content: JSON.stringify({ results: new Array(1000).fill({ status: "ok" }) }),
    tool_call_id: "call_1",
  },
];

const result = await compress(messages);
console.log(`Tokens saved: ${result.tokensSaved}`);
// SmartCrusher keeps errors, anomalies, and relevant items

import json
from headroom import SmartCrusher

crusher = SmartCrusher()

# crush() takes a JSON string, not a dict
tool_output = json.dumps({"results": ["...1000 items..."]})

# Returns a CrushResult; the compressed JSON string is `.compressed`
result = crusher.crush(tool_output, query="user's question")
print(result.compressed)
print(result.strategy)  # e.g. "lossless:table(...)" or "smart_sample(1000->15)"

Configuration

import { compress } from "headroom-ai";

// Configure via the Headroom proxy or HeadroomClient
const result = await compress(messages, {
  model: "gpt-4o",
  tokenBudget: 10000, // SmartCrusher will reduce JSON to fit
});

console.log(`Transforms: ${result.transformsApplied}`);
// ["smart_crusher", "cache_aligner"]

from headroom import SmartCrusher, SmartCrusherConfig

config = SmartCrusherConfig(
    min_tokens_to_crush=200,      # Only compress if > 200 tokens
    max_items_after_crush=15,     # Keep at most 15 items (lossy path only)
    first_fraction=0.3,           # Keep first 30% of items
    last_fraction=0.15,           # Keep last 15% of items
    variance_threshold=2.0,       # Statistical variance threshold
    preserve_change_points=True,  # Keep significant transitions
)

crusher = SmartCrusher(config)
result = crusher.crush(tool_output, query="find payment failures")

Configuration Options

Example: Before and After

Consider a tool that returns 1,000 search results:

# Before compression: 45,000 tokens
{
    "results": [
        {"id": 1, "status": "ok", "message": "Success", "timestamp": "..."},
        {"id": 2, "status": "ok", "message": "Success", "timestamp": "..."},
        # ... 995 more "ok" results ...
        {"id": 998, "status": "error", "message": "Connection timeout", "timestamp": "..."},
        {"id": 999, "status": "ok", "message": "Success", "timestamp": "..."},
        {"id": 1000, "status": "ok", "message": "Success", "timestamp": "..."},
    ]
}

# After SmartCrusher's lossy keep/drop path (with_compaction=False):
# ~15-16 items kept -- first items, last items, and the error at id=998

The LLM sees the structure, the error, and a representative sample -- everything it needs to answer "find errors in the last 24 hours" without wading through 1,000 identical success responses. Note this specific shape (mostly-identical items, one error) is also exactly what the lossless table fold favors (see the callout above), so with default settings this array is more likely to be re-encoded compactly with every item still present than reduced to ~15 items -- the numbers above illustrate the scored keep/drop path, not a guarantee of which path a given array takes.